Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
9.2 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

/**
 * @file focusOutline.stylex.ts
 * @input Uses StyleX and theme color tokens
 * @output Exports shared focus-outline prop builders
 * @position Internal utility for consistent keyboard focus outlines across core components
 */

// Every ring in core and lab comes from here, except Switch's: its condition
// is a component-scoped ancestor marker, which cannot be shared without
// leaking focus state. A component may override only the offset. The values
// come from the `--focus-outline-*` tokens, so a theme restyles every ring at
// once. The `:focus-visible` condition is not themeable, so a theme cannot
// show the ring to pointer users.

import * as stylex from '@stylexjs/stylex';
import {focusVars} from '../theme/tokens.stylex';

const FOCUS_OUTLINE_WIDTH = focusVars['--focus-outline-width'];
const FOCUS_OUTLINE_STYLE = focusVars['--focus-outline-style'];
const FOCUS_OUTLINE_COLOR = focusVars['--focus-outline-color'];

const FOCUS_OUTLINE_OFFSET = focusVars['--focus-outline-offset'];

/**
 * The ring as a single `outline` value, for reading it at runtime — an
 * assertion, or an element styled imperatively.
 *
 * NOT usable inside another file's `stylex.create`: StyleX resolves imported
 * `defineVars` and nothing else, so a component whose condition
 * {@link focusOutlineStyles} cannot express (Switch, whose ring keys off a
 * component-scoped ancestor marker) has to compose the `focusVars` tokens
 * itself.
 */
export const FOCUS_OUTLINE = `${FOCUS_OUTLINE_WIDTH} ${FOCUS_OUTLINE_STYLE} ${FOCUS_OUTLINE_COLOR}`;

/**
 * Written as longhands rather than the `outline` shorthand.
 *
 * A shorthand resets every longhand it covers, so `outline: 2px solid accent`
 * would clobber a later `outlineColor` no matter the order — which is how
 * destructive buttons silently lost their red ring. With longhands, a variant
 * can re-color the ring and inherit width, style and offset.
 */
const focusOutlineLonghands = {
  outlineWidth: FOCUS_OUTLINE_WIDTH,
  outlineStyle: FOCUS_OUTLINE_STYLE,
  outlineColor: FOCUS_OUTLINE_COLOR,
} as const;

/**
 * The standard focus ring as plain CSS values, for the one case that has to
 * apply it imperatively: a control whose focusable input is visually hidden and
 * whose ring must land on a *themeable indicator* beside it (see
 * `useIndicatorFocusRing`). Everything else should use the styles above.
 *
 * Longhands, not the `outline` shorthand, for the same reason the styles are:
 * a shorthand resets every longhand it covers, so a caller could not re-color
 * the ring without restating its width and style. Split, each part is
 * independently overridable — and every part stays a var, so a theme's
 * `--focus-outline-*` overrides still flow through.
 *
 * NOT usable inside another file's `stylex.create`, for the same reason as
 * {@link FOCUS_OUTLINE}: StyleX compiles each member there to a CSS variable
 * nothing defines. Compose the `focusVars` tokens instead.
 *
 * Keys are camelCase to match `HTMLElement.style`, so this spreads straight
 * onto an element:
 *
 * ```ts
 * Object.assign(el.style, FOCUS_OUTLINE_PARTS);        // draw
 * Object.assign(el.style, FOCUS_OUTLINE_PARTS_NONE);   // clear
 * ```
 */
export const FOCUS_OUTLINE_PARTS = {
  outlineWidth: FOCUS_OUTLINE_WIDTH,
  outlineStyle: FOCUS_OUTLINE_STYLE,
  outlineColor: FOCUS_OUTLINE_COLOR,
  outlineOffset: FOCUS_OUTLINE_OFFSET,
} as const;

/** Clears {@link FOCUS_OUTLINE_PARTS}, one key per part so nothing lingers. */
export const FOCUS_OUTLINE_PARTS_NONE = {
  outlineWidth: '',
  outlineStyle: '',
  outlineColor: '',
  outlineOffset: '',
} as const;

export const focusOutlineStyles = stylex.create({
  focusVisible: {
    outlineWidth: {
      default: '0',
      ':focus-visible': focusOutlineLonghands.outlineWidth,
    },
    outlineStyle: {
      default: 'none',
      ':focus-visible': focusOutlineLonghands.outlineStyle,
    },
    outlineColor: {
      default: null,
      ':focus-visible': focusOutlineLonghands.outlineColor,
    },
    outlineOffset: {default: '0', ':focus-visible': FOCUS_OUTLINE_OFFSET},
  },
  focusWithin: {
    outlineWidth: {
      default: '0',
      ':has(:focus-visible)': focusOutlineLonghands.outlineWidth,
    },
    outlineStyle: {
      default: 'none',
      ':has(:focus-visible)': focusOutlineLonghands.outlineStyle,
    },
    outlineColor: {
      default: null,
      ':has(:focus-visible)': focusOutlineLonghands.outlineColor,
    },
    outlineOffset: {default: '0', ':has(:focus-visible)': FOCUS_OUTLINE_OFFSET},
  },
  /**
   * Like {@link focusOutlineStyles.focusWithin}, but only for the element's
   * FIRST child — for a wrapper that paints the ring on behalf of one primary
   * control while its siblings ring themselves.
   *
   * `focusWithin` matches any descendant, so a row holding more than one tab
   * stop lights the whole row *on top of* the focused control's own ring: two
   * outlines for one tab stop. Scoping to `> :first-child` keeps the ring the
   * primary's, and leaves every sibling control ringing itself.
   *
   * The wrapper owns the coupling: the primary has to be its first child, and
   * the wrapper must not be a tab stop (its own `:focus-visible` would never
   * match). Pair it with {@link focusOutlineStyles.suppressed} on the primary.
   */
  focusWithinFirstChild: {
    outlineWidth: {
      default: '0',
      ':has(> :first-child:focus-visible)': focusOutlineLonghands.outlineWidth,
    },
    outlineStyle: {
      default: 'none',
      ':has(> :first-child:focus-visible)': focusOutlineLonghands.outlineStyle,
    },
    outlineColor: {
      default: null,
      ':has(> :first-child:focus-visible)': focusOutlineLonghands.outlineColor,
    },
    outlineOffset: {
      default: '0',
      ':has(> :first-child:focus-visible)': FOCUS_OUTLINE_OFFSET,
    },
  },
  /**
   * Like {@link focusOutlineStyles.focusWithin}, but only for a direct child
   * with `role="combobox"`: for a control box that paints the ring for its
   * combobox trigger while sibling controls inside it (a status info-tip, a
   * clear button) ring themselves. One focus move shows one ring.
   */
  focusWithinCombobox: {
    outlineWidth: {
      default: '0',
      ':has(> [role="combobox"]:focus-visible)':
        focusOutlineLonghands.outlineWidth,
    },
    outlineStyle: {
      default: 'none',
      ':has(> [role="combobox"]:focus-visible)':
        focusOutlineLonghands.outlineStyle,
    },
    outlineColor: {
      default: null,
      ':has(> [role="combobox"]:focus-visible)':
        focusOutlineLonghands.outlineColor,
    },
    outlineOffset: {
      default: '0',
      ':has(> [role="combobox"]:focus-visible)': FOCUS_OUTLINE_OFFSET,
    },
  },
  /**
   * Draws no ring, and keeps the UA's own off — for an element whose ring an
   * ancestor paints.
   *
   * The reset is not optional. Every other style here suppresses the browser
   * default through its `default` branch, so dropping the ring from a control
   * drops that suppression with it, and a bare `<a>` or `<button>` goes back
   * to the UA focus ring — painted *inside* the ancestor's.
   */
  suppressed: {
    outlineWidth: '0',
    outlineStyle: 'none',
    outlineOffset: '0',
  },
  publishFocusVisibleVars: {
    '--_focus-outline': {
      default: 'none',
      ':focus-visible': FOCUS_OUTLINE,
    },
    '--_focus-outline-offset': {
      default: '0',
      ':focus-visible': FOCUS_OUTLINE_OFFSET,
    },
  },
  focusWithinOrPublished: {
    outline: {
      default: 'var(--_focus-outline, none)',
      ':has(:focus-visible)': FOCUS_OUTLINE,
    },
    outlineOffset: {
      default: 'var(--_focus-outline-offset, 0)',
      ':has(:focus-visible)': FOCUS_OUTLINE_OFFSET,
    },
  },
});

// StyleX does not expose a stable public input type for stylex.props();
// keep this helper permissive so it mirrors stylex.props() itself.
type StyleXPropsArg = unknown;

function makeFocusOutlineProps(style: StyleXPropsArg) {
  return (...styles: StyleXPropsArg[]) =>
    // Caller styles LAST, so a component can deliberately re-color its ring —
    // destructive buttons ring in error red, not accent. StyleX is last-wins,
    // and reversing this to protect the ring silently ate that override.
    //
    // The hazard in this direction is the opposite one: a caller whose base
    // style carries `outline: 'none'` wipes the ring out entirely (TreeList
    // did, and shipped a focusable row with no visible focus). Two things
    // guard it — this file states the rule, and the ring is written as
    // LONGHANDS, so an override has to name `outlineStyle`/`outlineWidth`
    // explicitly rather than erasing them through the `outline` shorthand.
    stylex.props(style as never, ...(styles as never[]));
}

export const focusOutlineProps = {
  focusVisible: makeFocusOutlineProps(focusOutlineStyles.focusVisible),
  focusWithin: makeFocusOutlineProps(focusOutlineStyles.focusWithin),
  focusWithinFirstChild: makeFocusOutlineProps(
    focusOutlineStyles.focusWithinFirstChild,
  ),
  suppressed: makeFocusOutlineProps(focusOutlineStyles.suppressed),
  publishFocusVisibleVars: makeFocusOutlineProps(
    focusOutlineStyles.publishFocusVisibleVars,
  ),
  focusWithinOrPublished: makeFocusOutlineProps(
    focusOutlineStyles.focusWithinOrPublished,
  ),
} as const;