Carets

.caret {
  white-space: nowrap;
  @include caret();
}
.caret-before {
  white-space: nowrap;
  @include caret($position: before);
}
.caret-up::after,
.caret-up::before {
  transform: rotate(180deg);
}
.caret-start::after,
.caret-start::before {
  transform: rotate(var(--logical-angle-90, 90deg));
}
.caret-end::after,
.caret-end::before {
  transform: rotate(var(--logical-angle-270, 270deg));
}

// In case --caret-* is not set.
// $caret-icon:               "<svg xmlns='http://www.w3.org/2000/svg' width='24' height='24' fill='currentcolor' viewBox='0 0 24 24'><path d='m11.121 16.648-5-5a1.264 1.264 0 0 1-.273-1.367A1.28 1.28 0 0 1 7.02 9.5h10c.508 0 .937.313 1.133.781a1.263 1.263 0 0 1-.274 1.367l-5 5a1.205 1.205 0 0 1-1.758 0Z'/></svg>";
$caret-icon:                "<svg xmlns='http://www.w3.org/2000/svg' width='24' height='24' fill='currentcolor' viewBox='0 0 24 24'><path d='m11.121 16.629-7.5-7.5a1.205 1.205 0 0 1 0-1.758 1.205 1.205 0 0 1 1.758 0l6.64 6.602 6.602-6.602a1.205 1.205 0 0 1 1.758 0c.508.469.508 1.29 0 1.758l-7.5 7.5a1.205 1.205 0 0 1-1.758 0Z'/></svg>";
$caret-size:                1.25em;
$caret-spacing:             (after: .5em 0, before: 0 .5em);
$caret-color:               var(--fg-color);
$caret-transition:          transform .2s ease-in-out;
$caret-vertical-align:      $icon-vertical-align;

/// Render a directional caret icon using a CSS mask on a pseudo-element.
///
/// Each parameter falls back to a CSS custom property (e.g. `--caret-size`),
/// which in turn falls back to the corresponding Sass variable. Override the
/// custom property on the parent to restyle without re-including the mixin.
///
/// The caret is always drawn on `::after` by default, regardless of direction.
/// Pass `$position: before` for a leading caret (e.g. a `start` back-button).
///
/// @param {String} $direction [down] - Caret direction: `down`, `up`, `end`, or `start`
/// @param {String} $icon [null] - Mask image override; falls back to `var(--caret-icon, svg-icon($caret-icon))`
/// @param {Number|String} $size [null] - Size override; falls back to `var(--caret-size, $caret-size)`
/// @param {Color|String} $color [null] - Color override; falls back to `var(--caret-color, $caret-color)`
/// @param {Number|String} $spacing [null] - `margin-inline` override; falls back to `var(--caret-spacing, …)`
/// @param {String} $position [after] - Pseudo-element to draw on: `after` (default) or `before`
/// @throw If `$direction` is not one of `down`, `up`, `start`, or `end`
/// @throw If `$position` is not `after` or `before`
/// @example scss - Trailing caret (default)
///   .dropdown-toggle {
///     @include caret();
///   }
/// @example scss - Leading caret (start direction, drawn on `::before`)
///   .back-button {
///     @include caret(start, $position: before);
///   }
/// @example scss - Custom icon at compile time
///   .custom-toggle {
///     @include caret($icon: svg-icon($my-custom-icon));
///   }
@mixin caret(
  $direction: down,
  $icon: null,
  $size: null,
  $color: null,
  $spacing: null,
  $position: after
) {
  @if $direction != down and $direction != up and $direction != start and $direction != end {
    @error "caret(): $direction must be `down`, `up`, `start`, or `end`, got `#{$direction}`.";
  }

  @if $position != after and $position != before {
    @error "caret(): $position must be `after` or `before`, got `#{$position}`.";
  }

  $-size:     if(sass($size != null):     $size;      else: var(--caret-size, #{$caret-size}));
  $-icon:     if(sass($icon != null):     $icon;      else: var(--caret-icon, #{svg-icon($caret-icon)}));
  $-color:    if(sass($color != null):    $color;     else: var(--caret-color, #{$caret-color}));
  $-spacing:  if(sass($spacing != null):  $spacing;   else: var(--caret-spacing, #{map.get($caret-spacing, $position)}));
  $-angles:  (
    down:   0deg,
    up:     180deg,
    start:  var(--logical-angle-90, 90deg),
    end:    var(--logical-angle-270, 270deg),
  );

  &::#{$position} {
    display: inline-block;
    flex-shrink: 0;
    width: $-size;
    height: $-size;
    margin-block: auto;
    margin-inline: $-spacing;
    vertical-align: var(--caret-vertical-align, #{$caret-vertical-align});
    content: "";
    background-color: $-color;
    mask-image: $-icon;
    mask-repeat: no-repeat;
    mask-position: center;
    mask-size: $-size;
    transform: rotate(map.get($-angles, $direction));
  }
}

// Always draws the directional caret, independent of $enable-caret. This is
// the opt-in surface behind the `.form-caret` helper, so the helper stays
// usable even when the automatic caret on selects/comboboxes is disabled.
// $enable-caret only gates the *automatic* @extend on `select.form-input` and
// `.combobox` (see _form-input.scss and _combobox.scss).
%form-caret {
  // Adjust padding to accommodate the caret and potential validation icons.
  padding-inline-end: calc(var(--padding-x) * 2 + var(--caret-size));
  background-image: var(--form-caret), var(--feedback-icon, none);
  background-repeat: no-repeat;
  background-position: $form-select-caret-position;
  background-size: var(--caret-size);

  // Disabled state uses a separate root-level icon baked with the disabled caret color.
  &[disabled],
  &.disabled,
  &:disabled,
  &:has(> :not(option, optgroup):is(.disabled, :disabled)) {
    background-image: var(--form-caret-disabled), var(--feedback-icon, none);
  }
}

// Feedback-only background layer for selects/comboboxes when the caret is
// disabled via `$enable-caret: false`. Draws no caret and reserves no caret
// padding, but still composites the validation feedback icon — selects and
// comboboxes paint it through this background layer. The matching feedback
// layout for this case lives in _validation.scss under the same gate.
%form-feedback-bg {
  background-image: var(--feedback-icon, none);
  background-repeat: no-repeat;
}