/// Susy3 API Functions
/// ===================
/// These three functions form the core of Susy's
/// layout-building grid API.
///
/// - Use `span()` and `gutter()` to return any grid-width,
///   and apply the results wherever you need them:
///   CSS `width`, `margin`, `padding`, `flex-basis`, `transform`, etc.
/// - For asymmetrical-fluid grids,
///   `slice()` can help manage your nesting context.
///
/// All three functions come with an unprefixed alias by default,
/// using the `susy` import.
/// Import the `susy-prefix` partial instead,
/// if you only only want prefixed versions of the API.
///
/// This is a thin syntax-sugar shell around
/// the "Su" core-math functions: `su-span`, `su-gutter`, and `su-slice`.
/// If you prefer the more constrained syntax of the math engine,
/// you are welcome to use those functions instead.
///
/// @group b-api
/// @see susy-span
/// @see susy-gutter
/// @see susy-slice
/// @see su-span
/// @see su-gutter
/// @see su-slice



/// ## Shorthand
///
/// All functions draw on the same shorthand syntax in two parts,
/// seperated by the word `of`.
///
/// ### Span Syntax: `<width>` [`<location>` `<spread>`]
/// The first part describes the
/// **span** width, location, and spread in any order.
/// Only the width is required:
///
/// - `span(2)` will return the width of 2 columns.
/// - `span(3 wide)` will return 3-columns, with an additional gutter.
/// - location is only needed with asymmetrical grids,
///   where `span(3 at 2)` will return the width of
///   specific columns on the grid.
///   Since these are functions, they will not handle placement for you.
///
/// ### Context Syntax: `[of <columns> <container-spread> <gutters>]`
/// The second half of Susy's shorthand
/// describes the grid-**context** –
/// available columns, container-spread, and optional gutter override –
/// in any order.
/// All of these settings have globally-defined defaults:
///
/// - `span(2 of 6)` will set the context to
///   a slice of 6 columns from the global grid.
///   More details below.
/// - `span(2 of 12 wide)` changes the container-spread
///   as well as the column-context.
/// - `span(2 of 12 set-gutters 0.5em)`
///   will override the global gutters setting
///   for this one calculation.
///
/// A single unitless number for `columns`
/// will be treated as a slice of the parent grid.
/// On a grid with `columns: susy-repeat(12, 120px)`,
/// the shorthand `of 4` will use the parent `120px` column-width.
/// You can also be more explicit,
/// and say `of susy-repeat(4, 100px)`.
/// If you are using asymmetrical grids,
/// like `columns: (1 1 2 3 5 8)`,
/// Susy can't slice it for you without knowing which columns you want.
/// The `slice` function accepts exactly the same syntax as `span`,
/// but returns a list of columns rather than a width.
/// Use it in your context like `of slice(first 3)`.
///
/// @group b-api



// Susy Span
// ---------
/// This is the primary function in Susy —
/// used to return the width of a span across one or more columns,
/// and any relevant gutters along the way.
/// With the default settings,
/// `span(3)` will return the width of 3 columns,
/// and the 2 intermediate gutters.
/// This can be used to set the `width` property of grid elements,
/// or `margin` and `padding`
/// to push, pull, and pad your elements.
///
/// - This is a thin syntax-sugar shell around
///   the core-math `su-span()` function.
/// - The un-prefixed alias `span()` is available by default.
///
/// @group b-api
/// @see su-span
/// @see $susy
///
/// @param {list} $span -
///   Shorthand expression to define the width of the span,
///   optionally containing:
///   - a count, length, or column-list span.
///   - `at $n`, `first`, or `last` location on asymmetrical grids,
///     where `at 1 == first`,
///     and `last` will calculate the proper location
///     based on columns and span.
///   - `narrow`, `wide`, or `wider` for optionally spreading
///     across adjacent gutters.
///   - `of $n <spread>` for available grid columns
///     and spread of the container.
///     Span counts like `of 6` are valid
///     in the context of symmetrical grids,
///     where Susy can safely infer a slice of the parent columns.
///   - and `set-gutters $n` to override global gutter settings.
///
/// @param {map} $config [()] -
///   Optional map of Susy grid configuration settings.
///   See `$susy` documentation for details.
///
/// @return {length} -
///   Calculated length value, using the units given,
///   or converting to `%` for fraction-based grids,
///   or a full `calc` function when units/fractions
///   are not comparable outside the browser.
///
/// @example scss - span half the grid
///   .foo {
///     // the result is a bit under 50% to account for gutters
///     width: susy-span(6 of 12);
///   }
///
/// @example scss - span a specific segment of asymmetrical grid
///   .foo {
///     width: susy-span(3 at 3 of (1 2 3 5 8));
///   }
@function susy-span(
  $span,
  $config: ()
) {
  $output: susy-compile($span, $config);

  @if map-get($output, 'span') {
    @return su-call('su-span', $output);
  }

  $actual: '[#{type-of($span)}] `#{inspect($span)}`';
  @return _susy-error(
    'Unable to determine span value from #{$actual}.',
    'susy-span');
}



// Susy Gutter
// -----------
/// The gutter function returns
/// the width of a single gutter on your grid,
/// to be applied where you see fit –
/// on `margins`, `padding`, `transform`, or element `width`.
///
/// - This is a thin syntax-sugar shell around
///   the core-math `su-gutter()` function.
/// - The un-prefixed alias `gutter()` is available by default.
///
/// @group b-api
/// @see su-gutter
/// @see $susy
///
/// @param {list | number} $context [null] -
///   Optional context for nested gutters,
///   including shorthand for
///   `columns`, `gutters`, and `container-spread`
///   (additional shorthand will be ignored)
///
/// @param {map} $config [()] -
///   Optional map of Susy grid configuration settings.
///   See `$susy` documentation for details.
///
/// @return {length} -
///   Width of a gutter as `%` of current context,
///   or in the units defined by `column-width` when available
///
/// @example scss - add gutters before or after an element
///   .floats {
///     float: left;
///     width: span(3 of 6);
///     margin-left: gutter(of 6);
///   }
///
/// @example scss - add gutters to padding
///   .flexbox {
///     flex: 1 1 span(3 wide of 6 wide);
///     padding: gutter(of 6) / 2;
///   }
///
@function susy-gutter(
  $context: susy-get('columns'),
  $config: ()
) {
  $context: susy-compile($context, $config, 'context-only');

  @return su-call('su-gutter', $context);
}



// Susy Slice
// ----------
/// Working with asymmetrical grids (un-equal column widths)
/// can be challenging – 
/// expecially when they involve fluid/fractional elements.
/// Describing a context `of (15em 6em 6em 6em 15em)` is a lot
/// to put inside the span or gutter function shorthand.
/// This slice function returns a sub-slice of asymmetrical columns to use
/// for a nested context.
/// `slice(3 at 2)` will give you a subset of the global grid,
/// spanning 3 columns, starting with the second.
///
/// - This is a thin syntax-sugar shell around
///   the core-math `su-slice()` function.
/// - The un-prefixed alias `slice()` is available by default.
///
/// @group b-api
/// @see su-slice
/// @see $susy
///
/// @param {list} $span -
///   Shorthand expression to define the subset span, optionally containing:
///   - `at $n`, `first`, or `last` location on asymmetrical grids;
///   - `of $n <spread>` for available grid columns
///     and spread of the container
///     - Span-counts like `of 6` are only valid
///       in the context of symmetrical grids
///     - Valid spreads include `narrow`, `wide`, or `wider`
///
/// @param {map} $config [()] -
///   Optional map of Susy grid configuration settings.
///   See `$susy` documentation for details.
///
/// @return {list} -
///   Subset list of columns for use for a nested context
///
/// @example scss - Return a nested segment of asymmetrical grid
///   $context: susy-slice(3 at 3 of (1 2 3 5 8));
///   /* $context: #{$context}; */
@function susy-slice(
  $span,
  $config: ()
) {
  $span: susy-compile($span, $config);

  @return su-call('su-slice', $span);
}



/// ## Building Grids
/// The web has come a long way
/// since the days of double-margin-hacks
/// and inconsistent subpixel rounding.
/// In addition to floats and tables,
/// we can now use much more powerful tools,
/// like flexbox and CSS grid,
/// to build more interesting and responsive layouts.
///
/// With Susy3, we hope you'll start moving in that direction.
/// You can still build classic 12-column Grid Systems,
/// and we'll help you get there,
/// but Susy3 is primarily designed for a grid-math-on-demand
/// approach to layout:
/// applying our functions only where you really need grid math.
/// Read the [intro article by OddBird][welcome] for more details.
///
/// [welcome]: http://oddbird.net/2017/06/28/susy3/
///
/// @group b-api
/// @link http://oddbird.net/2017/06/28/susy3/ Article: Welcome to Susy3
///
/// @example scss - floats
///   .float {
///     width: span(3);
///     margin-right: gutter();
///   }
///
/// @example scss - flexbox
///   .flexbox {
///     flex: 1 1 span(3);
///     // half a gutter on either side…
///     padding: 0 gutter() / 2;
///   }
///
/// @example scss - pushing and pulling
///   .push-3 {
///     margin-left: span(3 wide);
///   }
///
///   .pull-3 {
///     margin-left: 0 - span(3 wide);
///   }
///
/// @example scss - building an attribute system
///   // markup example: <div data-span="last 3"></div>
///   [data-span] {
///     float: left;
///
///     &:not([data-span*='last']) {
///       margin-right: gutter();
///     }
///   }
///
///   @for $span from 1 through length(susy-get('columns')) {
///     [data-span*='#{$span}'] {
///       width: span($span);
///     }
///   }