@astryxdesign/core 0.3.0 → 0.4.0

package/src/Indicator/indicatorRegistry.test.tsx

@@ -0,0 +1,106 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file indicatorRegistry.test.tsx
+ *
+ * Pins the seam between the indicators core ships and the ones other packages
+ * add, because that seam used to lie: `defaultIndicators` was typed as a total
+ * map over the OPEN `IndicatorName` union, so augmenting `IndicatorMap` made
+ * the compiler promise a component for a name nothing had registered, and
+ * rendering the `undefined` it actually returned threw.
+ *
+ * The augmentation below is deliberately real, not a cast — it is exactly what
+ * a downstream package writes, and it is what makes `defaultIndicators`
+ * failing to cover `'brand-star'` a compile error if anyone re-widens the map.
+ */
+
+import {describe, expect, it} from 'vitest';
+import {render} from '@testing-library/react';
+import {defineTheme} from '../theme/defineTheme';
+import {CheckboxIndicator} from './CheckboxIndicator';
+import {CheckIndicator} from './CheckIndicator';
+import {RadioIndicator} from './RadioIndicator';
+import {defaultIndicators, getIndicator} from './indicatorRegistry';
+import type {CoreIndicatorName} from './indicatorRegistry';
+import type {IndicatorName, IndicatorProps} from './types';
+
+declare module './types' {
+  interface IndicatorMap {
+    'brand-star': 'singleSelection';
+  }
+}
+
+function BrandStar({state}: IndicatorProps<'singleSelection'>) {
+  return <span aria-hidden="true" data-testid="star" data-state={state} />;
+}
+
+describe('defaultIndicators', () => {
+  it('covers exactly the core indicator names', () => {
+    // A Record over the union, not an array: adding a name to
+    // CoreIndicatorName without shipping a default fails to compile here
+    // before it can fail at runtime anywhere else.
+    const coreNames: Record<CoreIndicatorName, true> = {
+      check: true,
+      checkbox: true,
+      radio: true,
+    };
+
+    expect(Object.keys(defaultIndicators).sort()).toEqual(
+      Object.keys(coreNames).sort(),
+    );
+    expect(defaultIndicators.check).toBe(CheckIndicator);
+    expect(defaultIndicators.checkbox).toBe(CheckboxIndicator);
+    expect(defaultIndicators.radio).toBe(RadioIndicator);
+  });
+});
+
+describe('getIndicator', () => {
+  it('resolves a core name to its built-in with no theme', () => {
+    expect(getIndicator('check')).toBe(CheckIndicator);
+    expect(getIndicator('radio')).toBe(RadioIndicator);
+  });
+
+  it('prefers a theme override, by name, across every host', () => {
+    const theme = defineTheme({
+      name: 'registry-override',
+      indicators: {check: RadioIndicator},
+    });
+
+    expect(getIndicator('check', theme)).toBe(RadioIndicator);
+    // Unmapped names keep their built-in.
+    expect(getIndicator('checkbox', theme)).toBe(CheckboxIndicator);
+  });
+
+  it('returns undefined for an augmented name no theme supplies', () => {
+    // The honest answer: core ships no `brand-star`. The type says
+    // `| undefined` for exactly this reason, so a caller writes `?? BrandStar`
+    // instead of rendering undefined.
+    expect(getIndicator('brand-star')).toBeUndefined();
+  });
+
+  it('resolves an augmented name the theme does supply', () => {
+    const theme = defineTheme({
+      name: 'brand-star-theme',
+      indicators: {'brand-star': BrandStar},
+    });
+
+    const Star = getIndicator('brand-star', theme);
+    expect(Star).toBe(BrandStar);
+
+    const {container} = render(<BrandStar state="checked" />);
+    expect(container.querySelector('[data-testid="star"]')).toBeInTheDocument();
+  });
+
+  it('types a core name as always resolvable and an open name as maybe', () => {
+    // Compile-time assertions; the runtime body only keeps them referenced.
+    const core = getIndicator('check');
+    const open = getIndicator('brand-star' as IndicatorName);
+
+    // @ts-expect-error — an augmented name may have no default; callers must
+    // handle undefined rather than render it.
+    const _mustHandle: NonNullable<typeof open> = open;
+
+    expect(core).toBeDefined();
+    expect(_mustHandle ?? null).toBeDefined();
+  });
+});

package/src/Indicator/indicatorRegistry.ts

@@ -0,0 +1,120 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file indicatorRegistry.ts
+ * @input Theme source and indicator name
+ * @output Exports the default indicator map and getIndicator resolution
+ * @position Server-safe indicator resolver; no 'use client' so it is
+ *           importable from RSC
+ *
+ * Two name spaces meet here, and keeping them apart is the whole design:
+ *
+ *   - {@link CoreIndicatorName} — the indicators Astryx itself ships. Closed,
+ *     and every one of them has a default, so resolving one always yields a
+ *     component.
+ *   - {@link IndicatorName} — every indicator name that exists, including the
+ *     ones other packages add by augmenting `IndicatorMap`. Open, and core has
+ *     no default for a name it has never heard of.
+ *
+ * `getIndicator` is overloaded along that seam: a core name resolves to a
+ * component, an augmented name resolves to a component *or* `undefined`, and
+ * the caller has to say what to do about it. Typing the map as total over the
+ * open union instead — which is what shipped in #4712 — made the compiler
+ * promise a component for `getIndicator('brand-star')` and hand back
+ * `undefined` at runtime.
+ */
+
+import type {DefinedTheme} from '../theme/defineTheme';
+import {getRegisteredTheme} from '../theme/themeRegistry';
+import {CheckboxIndicator} from './CheckboxIndicator';
+import {CheckIndicator} from './CheckIndicator';
+import {RadioIndicator} from './RadioIndicator';
+import type {
+  IndicatorComponent,
+  IndicatorMap,
+  IndicatorName,
+  IndicatorRegistry,
+} from './types';
+
+/**
+ * The indicator names Astryx ships a default for.
+ *
+ * Written out rather than derived from {@link IndicatorMap}, because that
+ * interface is open to augmentation and this set is not: it is exactly what is
+ * in {@link defaultIndicators} below. `indicatorRegistry.test.tsx` pins the two
+ * together in both directions.
+ */
+export type CoreIndicatorName = 'check' | 'checkbox' | 'radio';
+
+/**
+ * The indicators Astryx ships. A theme's `indicators` entries override these
+ * by name.
+ *
+ * Typed per family (rather than as one widened component type) so a default
+ * declared here has to accept the states its family passes — the same rule
+ * {@link IndicatorRegistry} holds replacements to.
+ */
+export const defaultIndicators: {
+  [N in CoreIndicatorName]: IndicatorComponent<IndicatorMap[N]>;
+} = {
+  check: CheckIndicator,
+  checkbox: CheckboxIndicator,
+  radio: RadioIndicator,
+};
+
+export type IndicatorRegistrySource = DefinedTheme | string | null | undefined;
+
+function getTheme(source: IndicatorRegistrySource): DefinedTheme | null {
+  if (source == null) {
+    return null;
+  }
+  return typeof source === 'string' ? getRegisteredTheme(source) : source;
+}
+
+function getThemeIndicators(
+  source: IndicatorRegistrySource,
+): IndicatorRegistry | null {
+  return getTheme(source)?.indicators ?? null;
+}
+
+/**
+ * Resolve an indicator component by name, preferring the theme's override and
+ * falling back to the built-in indicator.
+ *
+ * Works in both server and client environments. Client components should use
+ * the {@link useIndicator} hook, which resolves against the nearest `<Theme>`.
+ *
+ * @example
+ * ```
+ * const Radio = getIndicator('radio', themeName);
+ * <Radio state="checked" />
+ * ```
+ *
+ * For a name contributed by augmentation there is no built-in to fall back to,
+ * so the result is `undefined` unless a theme supplies one — the package that
+ * added the name owns its default:
+ *
+ * @example
+ * ```
+ * const Star = getIndicator('brand-star', themeName) ?? BrandStar;
+ * ```
+ */
+export function getIndicator<N extends CoreIndicatorName>(
+  name: N,
+  source?: IndicatorRegistrySource,
+): IndicatorComponent<IndicatorMap[N]>;
+export function getIndicator<N extends IndicatorName>(
+  name: N,
+  source?: IndicatorRegistrySource,
+): IndicatorComponent<IndicatorMap[N]> | undefined;
+export function getIndicator(
+  name: IndicatorName,
+  source?: IndicatorRegistrySource,
+): IndicatorComponent | undefined {
+  const override = getThemeIndicators(source)?.[name];
+  return (override ??
+    // `name` may be an augmented one, which this map has no entry for — hence
+    // the `| undefined` the overloads expose to those callers.
+    (defaultIndicators as Partial<Record<IndicatorName, unknown>>)[name]) as
+    IndicatorComponent | undefined;
+}

package/src/Indicator/types.ts

@@ -0,0 +1,186 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file types.ts
+ * @input None (pure type definitions)
+ * @output The indicator contract: families, states, props, names, registry
+ * @position Type foundation for stateful control visuals
+ *
+ * An **indicator** is a decorative visual that expresses a piece of component
+ * state: the box a checkbox draws, the circle a radio draws, the mark on a
+ * chosen list option. The owning component keeps the input, role, accessible
+ * name, focus, and keyboard behavior; the indicator turns state into a picture.
+ *
+ * Componentizing them buys three things a theme could not otherwise have:
+ *
+ *   1. **Theme it** — an indicator renders stable `astryx-*` class targets, so
+ *      `defineTheme({components})` restyles it like any other component, in one
+ *      place rather than per host component.
+ *   2. **Swizzle it** — `astryx swizzle <Name>` copies the source to own.
+ *   3. **Replace it** — `defineTheme({indicators})` swaps in another component
+ *      by name, and every component that renders that indicator follows. A
+ *      product that wants radio visuals for single selection replaces `check`.
+ *
+ * Indicators come in **families**, and a family fixes the state space. That is
+ * what lets one mechanism serve semantics as different as "is this option
+ * chosen" and "are several of these chosen" without either pretending to be
+ * the other, and without a shared enum that would typecheck `indeterminate` on
+ * a radio.
+ *
+ * Each family's vocabulary is the one the accessibility layer already uses, so
+ * a component passing state down says the same word its ARIA attribute says.
+ * Sharing one enum across families was measured and rejected (#4831): it
+ * produced call sites reading `aria-expanded={isOpen}` beside
+ * `state={isOpen ? 'on' : 'off'}`.
+ */
+
+import type {ComponentType, ReactNode, Ref} from 'react';
+import type {BaseProps} from '../BaseProps';
+
+/**
+ * The indicator families, each mapped to the states it can express.
+ *
+ * Single and multi selection are separate families because their state spaces
+ * genuinely differ: `aria-checked` is `true|false` for a radio and
+ * `true|false|mixed` for a checkbox. Keeping them apart is what makes a
+ * replacement type-checkable — a checkbox visual cannot stand in where only
+ * two states are ever passed, and a radio cannot be asked to draw a partial
+ * state it has no picture for.
+ *
+ * Adding a family is additive: declare it here, then declare indicators of
+ * that family in {@link IndicatorMap}. Packages outside core can contribute
+ * families through module augmentation.
+ */
+export interface IndicatorFamilyMap {
+  /** Is this one thing chosen? Radios, and the mark on a selected option. */
+  singleSelection: 'unchecked' | 'checked';
+  /** Which of these are chosen? Checkboxes, including the partial state. */
+  multiSelection: 'unchecked' | 'checked' | 'indeterminate';
+}
+
+export type IndicatorFamily = keyof IndicatorFamilyMap & string;
+
+/** The states an indicator of family `F` can be asked to draw. */
+export type IndicatorState<F extends IndicatorFamily = IndicatorFamily> =
+  IndicatorFamilyMap[F];
+
+/** Indicator size scale — matches the control sizes of the owning inputs. */
+export type IndicatorSize = 'sm' | 'md';
+
+/**
+ * Props every indicator accepts.
+ *
+ * Indicators are **decorative**: they render `aria-hidden` visuals and own no
+ * role, focus, keyboard handling, or state. The component that renders one
+ * (CheckboxInput, RadioListItem, a listbox option) keeps all of that. An
+ * indicator's only job is to turn `state` into a picture.
+ *
+ * The a11y props are omitted from this interface rather than left to
+ * convention: un-hiding an indicator has it announced next to the control that
+ * owns the accessible name — the same thing said twice (#4918). A replacement
+ * that genuinely needs announcing is not an indicator; name the owning control.
+ *
+ * `tabIndex` is omitted for the same reason, one step on: the element is
+ * unconditionally `aria-hidden`, so a tab stop on it is a focusable node inside
+ * a hidden subtree. Measured with axe in real Chromium: 0 `aria-hidden-focus`
+ * violations becomes 1 the moment it is forwarded.
+ *
+ * The omission is only half enforceable, and it is worth knowing which half.
+ * TypeScript exempts JSX attribute names that are not valid JS identifiers from
+ * excess-property checking, so a LITERAL `role=` is a compile error while
+ * `aria-hidden` and `aria-label` are not — and a spread (`{...props}`, the
+ * ordinary host idiom) bypasses the check for every member, `role` included.
+ * Measured, not assumed. So the components also emit their own `aria-hidden`
+ * AFTER `{...rest}` and drop a forwarded `tabIndex`: that ordering, not the
+ * type, is what enforces the contract. Nothing else is stripped — a forwarded
+ * `aria-label` still reaches the DOM, inert inside an `aria-hidden` subtree.
+ *
+ * Interaction state is deliberately *not* a prop. Hover and focus reach an
+ * indicator through the CSS ancestor marker ({@link indicatorScope}) applied
+ * by its owner, so a row hover tints the control without anyone threading a
+ * boolean through React — and an owner that should not tint its indicator
+ * simply does not apply the marker.
+ */
+export interface IndicatorProps<
+  F extends IndicatorFamily = IndicatorFamily,
+> extends Omit<
+  BaseProps<HTMLSpanElement>,
+  'aria-hidden' | 'role' | 'aria-label' | 'aria-labelledby' | 'tabIndex'
+> {
+  /** Ref forwarded to the indicator's root element. */
+  ref?: Ref<HTMLSpanElement>;
+  /** Which state to draw. The state space is fixed by the family. */
+  state: IndicatorState<F>;
+  /**
+   * Control size.
+   * @default 'md'
+   */
+  size?: IndicatorSize;
+  /**
+   * Whether the owning control is disabled. Purely visual — the owner still
+   * owns the actual disabled semantics.
+   * @default false
+   */
+  isDisabled?: boolean;
+  /**
+   * Content rendered inside the indicator chrome *instead of* the state mark.
+   * CheckboxInput uses this to show a loading Spinner inside the box while a
+   * change action is pending.
+   */
+  children?: ReactNode;
+}
+
+/** An indicator is any component accepting {@link IndicatorProps} of its family. */
+export type IndicatorComponent<F extends IndicatorFamily = IndicatorFamily> =
+  ComponentType<IndicatorProps<F>>;
+
+/**
+ * The named indicators a theme can replace, each mapped to its family.
+ *
+ * The name is what a theme addresses, and what every component renders
+ * through — so replacing `check` reaches every single-selection mark at once,
+ * which is the point.
+ *
+ * Packages outside core can contribute their own through module augmentation.
+ * Core ships no default for a name it does not know, so the package that adds
+ * the name owns its default — `getIndicator`/`useIndicator` return
+ * `| undefined` for it, and the call site supplies the fallback:
+ *
+ * ```ts
+ * declare module '@astryxdesign/core/Indicator' {
+ *   interface IndicatorMap {
+ *     'brand-star': 'singleSelection';
+ *   }
+ * }
+ *
+ * const Star = useIndicator('brand-star') ?? BrandStar;
+ * ```
+ */
+export interface IndicatorMap {
+  /** The mark on a chosen option — a checkmark by default. */
+  check: 'singleSelection';
+  /** The filled circle of a radio control. */
+  radio: 'singleSelection';
+  /** The box of a checkbox control, including its partial state. */
+  checkbox: 'multiSelection';
+}
+
+export type IndicatorName = keyof IndicatorMap & string;
+
+/** The indicator names belonging to family `F`. */
+export type IndicatorNameOfFamily<F extends IndicatorFamily> = {
+  [N in IndicatorName]: IndicatorMap[N] extends F ? N : never;
+}[IndicatorName];
+
+/**
+ * Theme-provided indicator overrides, keyed by indicator name.
+ *
+ * Family-checked: each entry must accept the state space of that indicator's
+ * family, so a replacement cannot be written against the wrong states. A
+ * `check` replacement that only handles `collapsed`/`expanded`, or a `radio`
+ * replacement expecting `indeterminate`, is a type error rather than a
+ * runtime surprise.
+ */
+export type IndicatorRegistry = {
+  [N in IndicatorName]?: IndicatorComponent<IndicatorMap[N]>;
+};

package/src/Indicator/useIndicator.ts

@@ -0,0 +1,39 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useIndicator.ts
+ * @input Indicator name
+ * @output Exports useIndicator hook for theme-aware indicator components
+ * @position Client hook used by controls that render a selection visual
+ */
+
+import {useThemeName} from '../theme/useTheme';
+import {getIndicator, type CoreIndicatorName} from './indicatorRegistry';
+import type {IndicatorComponent, IndicatorMap, IndicatorName} from './types';
+
+/**
+ * Resolve an indicator component from the nearest `<Theme>`.
+ *
+ * A core indicator always resolves. A name contributed by augmentation
+ * resolves only if a theme supplies it, so that overload returns
+ * `| undefined` — see {@link getIndicator}.
+ *
+ * @example
+ * ```
+ * const Checkbox = useIndicator('checkbox');
+ * return <Checkbox state={isChecked ? 'checked' : 'unchecked'} size={size} />;
+ * ```
+ */
+export function useIndicator<N extends CoreIndicatorName>(
+  name: N,
+): IndicatorComponent<IndicatorMap[N]>;
+export function useIndicator<N extends IndicatorName>(
+  name: N,
+): IndicatorComponent<IndicatorMap[N]> | undefined;
+export function useIndicator(
+  name: IndicatorName,
+): IndicatorComponent | undefined {
+  return getIndicator(name, useThemeName());
+}

package/src/Item/Item.doc.mjs

@@ -37,7 +37,7 @@ export const docs = {
         {name: 'labelLines', type: 'number', description: 'Max lines before label truncates with ellipsis.'},
         {name: 'descriptionLines', type: 'number', description: 'Max lines before description truncates with ellipsis.'},
         {name: 'onClick', type: '(event: MouseEvent) => void', description: 'Click handler. Makes the item clickable with button semantics.'},
-        {name: 'interactiveRef', type: 'RefObject<HTMLElement | null>', description: 'Ref to a nested control (e.g. a checkbox in startContent) that owns the item\'s keyboard access and action. The row becomes an enlarged click/tap target that delegates surface clicks to it (useClickableContainer) and renders no invisible button/anchor, so the row adds no second tab stop (WCAG 4.1.2). Mutually exclusive with onClick/href — those are ignored when set.'},
+        {name: 'interactiveRef', type: 'RefObject<HTMLElement | null>', description: 'Ref to a nested control (e.g. a checkbox in startContent) that owns the item\'s keyboard access and action. The row becomes an enlarged click/tap target that delegates surface clicks to it (useClickableContainer) and renders no invisible button/anchor, so the row adds no second tab stop (WCAG 4.1.2). Mutually exclusive with onClick/href; those are ignored when set.'},
         {name: 'href', type: 'string', description: 'Link URL. Makes the item a link via an invisible anchor element.'},
         {name: 'target', type: "'_blank' | '_self'", description: 'Link target. Only used with href. target="_blank" automatically adds noopener noreferrer.'},
         {name: 'rel', type: 'string', description: 'Link relationship tokens. noopener noreferrer are merged automatically for target="_blank".'},

package/src/Item/Item.tsx

@@ -33,6 +33,7 @@ import {useLinkComponent} from '../Link/useLinkComponent';
 import {useClickableContainer} from '../hooks/useClickableContainer';
 import {useDevWarning} from '../hooks/useDevWarning';
 import {themeProps} from '../utils/themeProps';
+import {focusOutlineProps} from '../utils/focusOutline.stylex';
 
 // =============================================================================
 // Types
@@ -218,16 +219,6 @@ const styles = stylex.create({
       ':active': colorVars['--color-overlay-pressed'],
     },
   },
-  focusVisibleOutline: {
-    outline: {
-      default: 'none',
-      ':has(:focus-visible)': `2px solid ${colorVars['--color-accent']}`,
-    },
-    outlineOffset: {
-      default: '0',
-      ':has(:focus-visible)': '2px',
-    },
-  },
   highlighted: {
     backgroundColor: colorVars['--color-overlay-hover'],
   },
@@ -274,7 +265,9 @@ const styles = stylex.create({
     textAlign: 'start',
   },
   label: {
-    color: colorVars['--color-text-primary'],
+    // Falls back to the primary text token; a parent (e.g. a destructive menu
+    // item) can recolor the label by setting --_item-label-color.
+    color: `var(--_item-label-color, ${colorVars['--color-text-primary']})`,
     fontSize: typeScaleVars['--text-body-size'],
     lineHeight: typeScaleVars['--text-body-leading'],
   },
@@ -289,7 +282,8 @@ const styles = stylex.create({
     WebkitBoxOrient: 'vertical' as const,
   },
   description: {
-    color: colorVars['--color-text-secondary'],
+    // Companion to --_item-label-color for the secondary line.
+    color: `var(--_item-description-color, ${colorVars['--color-text-secondary']})`,
     fontSize: typeScaleVars['--text-supporting-size'],
     lineHeight: typeScaleVars['--text-supporting-leading'],
   },
@@ -555,12 +549,11 @@ export function Item({
       aria-disabled={isDisabled || undefined}
       {...mergeProps(
         themeProps('item', {density, align}),
-        stylex.props(
+        focusOutlineProps.focusWithin(
           styles.root,
           densityStyles[density],
           align === 'start' && styles.alignStart,
           isInteractive && styles.interactive,
-          isInteractive && styles.focusVisibleOutline,
           isHighlighted && styles.highlighted,
           isSelected && styles.selected,
           isDisabled && !hasParentRole && styles.disabled,

package/src/Layer/useLayer.doc.mjs

@@ -79,7 +79,7 @@ export const docs = {
       name: 'render',
       type: '(children: ReactNode, props: ContextRenderProps | FixedRenderProps) => ReactNode',
       description:
-        'Render function for the popover element. Pass placement/alignment in context mode or x/y in fixed mode. Placement/alignment are logical: they map to the self-* position-area keyword family, which resolves against the popover\'s own inherited direction, so RTL contexts mirror automatically in pure CSS. Pass `positioning: "custom"` in context mode to author position styles yourself via `style` (e.g. explicit anchor() insets or an anchor-size() cover): the hook keeps the popover behavior and position-anchor wiring but derives no position styles, including the automatic RTL mirroring, which becomes your responsibility. In context mode, pass `as: "span"` to render an inline-safe layer (e.g. inside a paragraph). The layer renders inline in the React tree; the Popover API promotes it to the top layer when shown, so it escapes ancestor clipping and stacking without a portal. When the layer would overflow the viewport, position-try fallbacks flip it to the opposite side; centered layers additionally slide along the alignment axis (span fallbacks) so they stay on-screen near viewport edges.',
+        'Render function for the popover element. Pass placement/alignment in context mode or x/y in fixed mode. Placement/alignment are logical: they map to the self-* position-area keyword family, which resolves against the popover\'s own inherited direction, so RTL contexts mirror automatically in pure CSS. Pass `positioning: "custom"` in context mode to author position styles yourself via `style` (e.g. explicit anchor() insets or an anchor-size() cover): the hook keeps the popover behavior and position-anchor wiring but derives no position styles, including the automatic RTL mirroring, which becomes your responsibility. Pass `offset` (a CSS length; a number is px) in context mode for clearance from the anchor: it applies to both edges of the placement axis, so the gap survives a flip. Layers are flush by default. In context mode, pass `as: "span"` to render an inline-safe layer (e.g. inside a paragraph). The layer renders inline in the React tree; the Popover API promotes it to the top layer when shown, so it escapes ancestor clipping and stacking without a portal. When the layer would overflow the viewport, position-try fallbacks flip it to the opposite side; centered layers additionally slide along the alignment axis (span fallbacks) so they stay on-screen near viewport edges.',
     },
   ],
   usage: {
@@ -131,7 +131,7 @@ export const docsDense = {
     hide: 'hide layer.',
     isOpen: 'whether layer is open.',
     id: 'unique ARIA id.',
-    render: 'renders popover element; pass placement/alignment or x/y. Placement/alignment logical: mapped to self-* position-area keywords resolved against the popover\'s inherited direction (RTL mirrors in pure CSS). `positioning: "custom"` (context mode) = author position styles yourself via `style`; keeps popover behavior + position-anchor wiring, derives nothing (incl. RTL mirroring, which becomes yours). Context mode accepts `as: "span"` for inline-safe layers. Renders inline; the Popover API top layer escapes clipping/stacking without a portal. Viewport overflow: flips to opposite side; centered layers also slide along the alignment axis (span fallbacks).',
+    render: 'renders popover element; pass placement/alignment or x/y. Placement/alignment logical: mapped to self-* position-area keywords resolved against the popover\'s inherited direction (RTL mirrors in pure CSS). `positioning: "custom"` (context mode) = author position styles yourself via `style`; keeps popover behavior + position-anchor wiring, derives nothing (incl. RTL mirroring, which becomes yours). `offset` (context mode) = clearance from the anchor as a CSS length (number = px), applied to both edges of the placement axis so it survives a flip; layers are flush by default. Context mode accepts `as: "span"` for inline-safe layers. Renders inline; the Popover API top layer escapes clipping/stacking without a portal. Viewport overflow: flips to opposite side; centered layers also slide along the alignment axis (span fallbacks).',
   },
   usage: {
     description:

package/src/Layer/useLayer.test.tsx

@@ -440,6 +440,91 @@ describe('useLayer context positioning', () => {
     });
   });
 
+  describe('offset', () => {
+    function OffsetHarness({
+      placement,
+      offset,
+      positioning,
+    }: {
+      placement?: LayerPlacement;
+      offset?: number | string;
+      positioning?: 'anchor' | 'custom';
+    }) {
+      const layer = useLayer({mode: 'context'});
+      return (
+        <>
+          <button type="button" ref={layer.ref} onClick={layer.show}>
+            trigger
+          </button>
+          {layer.render(<span>content</span>, {
+            placement,
+            offset,
+            positioning,
+          })}
+        </>
+      );
+    }
+
+    // Debug-mode StyleX variable names for the dynamic offset style, as in
+    // Grid.test.tsx. jsdom resolves neither the var indirection nor logical
+    // margin properties, so the declarations themselves are the assertion.
+    async function openAndGetOffsets(ui: React.ReactElement) {
+      const user = userEvent.setup();
+      const {container, getByRole} = render(ui);
+      await user.click(getByRole('button', {name: 'trigger'}));
+      const el = container.querySelector('[popover]') as HTMLElement;
+      const read = (prop: string) => el.style.getPropertyValue(`--x-${prop}`);
+      return {
+        blockStart: read('marginBlockStart'),
+        blockEnd: read('marginBlockEnd'),
+        inlineStart: read('marginInlineStart'),
+        inlineEnd: read('marginInlineEnd'),
+      };
+    }
+
+    const NONE = {blockStart: '', blockEnd: '', inlineStart: '', inlineEnd: ''};
+
+    it('is flush by default', async () => {
+      expect(await openAndGetOffsets(<OffsetHarness placement="below" />)).toEqual(
+        NONE,
+      );
+    });
+
+    // Both edges of the axis, so the gap survives a position-try-fallbacks
+    // flip to the opposite side (#4803).
+    it('clears both block edges for a block placement', async () => {
+      expect(
+        await openAndGetOffsets(<OffsetHarness placement="above" offset={8} />),
+      ).toEqual({...NONE, blockStart: '8px', blockEnd: '8px'});
+    });
+
+    it('clears both inline edges for an inline placement', async () => {
+      expect(
+        await openAndGetOffsets(<OffsetHarness placement="end" offset={8} />),
+      ).toEqual({...NONE, inlineStart: '8px', inlineEnd: '8px'});
+    });
+
+    it('takes a CSS length string', async () => {
+      expect(
+        await openAndGetOffsets(
+          <OffsetHarness placement="below" offset="var(--spacing-1)" />,
+        ),
+      ).toEqual({
+        ...NONE,
+        blockStart: 'var(--spacing-1)',
+        blockEnd: 'var(--spacing-1)',
+      });
+    });
+
+    it('is ignored under custom positioning, which owns its own insets', async () => {
+      expect(
+        await openAndGetOffsets(
+          <OffsetHarness placement="below" offset={8} positioning="custom" />,
+        ),
+      ).toEqual(NONE);
+    });
+  });
+
   it('fixed mode emits no anchor-positioning styles', async () => {
     function FixedHarness() {
       const layer = useLayer({mode: 'fixed'});