/// Specifies the number of columns an element should span. If the selector is nested the number of columns of its parent element should be passed as an argument as well.
///
/// @param {List} $span
///   A list containing `$columns`, the unitless number of columns the element spans (required), and `$container-columns`, the number of columns the parent element spans (optional).
///
///   If only one value is passed, it is assumed that it's `$columns` and that that `$container-columns` is equal to `$grid-columns`, the total number of columns in the grid.
///
///   The values can be separated with any string such as `of`, `/`, etc.
///
/// @param {String} $display (block)
///   Sets the display property of the element. By default it sets the display propert of the element to `block`.
///
///   If passed `block-collapse`, it also removes the margin gutter by adding it to the element width.
///
///   If passed `table`, it sets the display property to `table-cell` and calculates the width of the element without taking gutters into consideration. The result does not align with the block-based grid.
///
/// @example scss - Usage
///   .element {
///     @include span-columns(6);
///
///    .nested-element {
///      @include span-columns(2 of 6);
///    }
///  }
///
/// @example css - CSS Output
///   .element {
///     display: block;
///     float: left;
///     margin-right: 2.35765%;
///     width: 48.82117%;
///   }
///
///   .element:last-child {
///     margin-right: 0;
///   }
///
///   .element .nested-element {
///     display: block;
///     float: left;
///     margin-right: 4.82916%;
///     width: 30.11389%;
///   }
///
///   .element .nested-element:last-child {
///     margin-right: 0;
///   }

@mixin span-columns($span: $columns of $container-columns, $display: block) {
  $columns: nth($span, 1);
  $container-columns: container-span($span);

  $parent-columns: get-parent-columns($container-columns) !global;

  $direction: get-direction($layout-direction, $default-layout-direction);
  $opposite-direction: get-opposite-direction($direction);

  $display-table: is-display-table($container-display-table, $display);

  @if $display-table  {
    display: table-cell;
    width: percentage($columns / $container-columns);
  } @else {
    float: #{$opposite-direction};

    @if $display != no-display {
      display: block;
    }

    @if $display == collapse {
      @include -neat-warn("The 'collapse' argument will be deprecated. Use 'block-collapse' instead.");
    }

    @if $display == collapse or $display == block-collapse {
      width: flex-grid($columns, $container-columns) + flex-gutter($container-columns);

      &:last-child {
        width: flex-grid($columns, $container-columns);
      }

    } @else {
      margin-#{$direction}: flex-gutter($container-columns);
      width: flex-grid($columns, $container-columns);

      &:last-child {
        margin-#{$direction}: 0;
      }
    }
  }
}