/// Provides a simple API for writing object-oriented CSS classes that extend generated, functional properties. Note
/// that the property must already be emitted using `emit-properties(...)` or `emit-responsive-properties(...)`.
///
/// @param {String} $shorthand - The name of the selector series.
/// @param {String} $adjective - The name of the adjective to target.
/// @param {Map} $options - Options associated with the `$shorthand` and `$adjective` specified.
/// @param {String} $options.breakpoint - Whether to extend at a specific responsive breakpoint [default: null].
/// @param {String} $options.theme - Whether to extend with a specific theme [default: null].
/// @param {String} $options.pseudo - Whether to extend and target a specific psuedo-class or pseudo-element [default:
/// null].
/// @param {Bool} $options.important - Whether to extend with `!important`.
@mixin anthology-extend($args...)
{
  // Ensure `A(configure, ...)` has been included prior.
  @if not $_anthology-config-is-ready {
    @error '[anthology::extend] --- Before extending functional properties, call `@include A(configure...);`.';
  }

  $shorthand: nth($args, 1);

  @if type-of($shorthand) == list
  {
    @each $entry in $args
    {
      @include A(extend, $entry...);
    }
  }
  @else
  {
    $adjective: nth($args, 2);
    $options: if(length($args) > 2, nth($args, 3), ());

    // Unpack options
    $breakpoint: A(map-get, $options, 'breakpoint');
    $theme: A(map-get, $options, 'theme');
    $pseudo: A(map-get, $options, 'pseudo');
    $important: A(map-get, $options, 'important');

    $should-extend-silent: if(
      A(map-get, $options, 'breakpoint'),
      $_anthology-extend-silent-responsive,
      $_anthology-extend-silent-generic,
    );

    $raw-selector: _A(raw-selector,
      $shorthand: $shorthand,
      $adjective: $adjective,
      $breakpoint: $breakpoint,
      $theme: $theme,
      $pseudo: $pseudo,
      $important: $important,
    );

    // We need to dilute the string escapes by half.
    $raw-selector: A(str-replace, $raw-selector, '\\\\', '\\');

    $selector: if(
      $should-extend-silent,
      '%#{$raw-selector}',
      '.#{$raw-selector}',
    );

    @extend #{'#{$selector}'};
  }
}