@astryxdesign/core 0.4.6 → 0.4.7-canary.29be96d

package/src/TextInput/TextInput.doc.mjs

@@ -71,6 +71,16 @@ export const docs = {
         'Displays a "Required" indicator next to the label and sets aria-required. Mutually exclusive with isOptional.',
       default: 'false',
     },
+    {
+      name: 'onEnter',
+      type: '() => void',
+      description: 'Callback fired when the user presses the Enter key.',
+    },
+    {
+      name: 'onKeyDown',
+      type: '(e: KeyboardEvent<HTMLInputElement>) => void',
+      description: 'Callback fired on keydown events on the input.',
+    },
     {
       name: 'isDisabled',
       type: 'boolean',

package/src/Toast/Toast.doc.mjs

@@ -60,6 +60,12 @@ export const docs = {
       type: '(reason: "auto" | "manual") => void',
       description: 'Callback fired when the toast is removed.',
     },
+    {
+      name: 'onDismiss',
+      type: '(reason: "auto" | "manual") => void',
+      description: 'Callback fired when the toast is dismissed.',
+      required: true,
+    },
   ],  theming: {
     targets: [
       {className: 'astryx-toast', visualProps: ['type']},

package/src/Tokenizer/Tokenizer.doc.mjs

@@ -201,6 +201,16 @@ export const docs = {
       description:
         'Width of the field (number = pixels, string used as-is, e.g. "100%"). Sizes the whole field (label, control, and status) so they stay aligned.',
     },
+    {
+      name: 'onFocus',
+      type: '(e: FocusEvent<HTMLInputElement>) => void',
+      description: 'Fires when focus enters the tokenizer input.',
+    },
+    {
+      name: 'onBlur',
+      type: '(e: FocusEvent<HTMLInputElement>) => void',
+      description: 'Fires when focus leaves the tokenizer input.',
+    },
     {
       name: 'xstyle',
       type: 'StyleXStyles',

package/src/Toolbar/Toolbar.doc.mjs

@@ -133,6 +133,11 @@ export const docs = {
           description: 'Visual variant passed to Section.',
           default: "'transparent'",
         },
+        {
+          name: 'dividers',
+          type: "Array<'top' | 'bottom' | 'start' | 'end'>",
+          description: 'Borders/dividers rendered around the toolbar.',
+        },
         {
           name: 'xstyle',
           type: 'StyleXStyles',

package/src/__tests__/apiContractDrift.test.tsx

@@ -0,0 +1,80 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect} from 'vitest';
+
+import {docs as ButtonDocs} from '../Button/Button.doc.mjs';
+import {docs as ContextMenuDocs} from '../ContextMenu/ContextMenu.doc.mjs';
+import {docs as DialogDocs} from '../Dialog/Dialog.doc.mjs';
+import {docs as LinkDocs} from '../Link/Link.doc.mjs';
+import {docs as MoreMenuDocs} from '../MoreMenu/MoreMenu.doc.mjs';
+import {docs as NumberInputDocs} from '../NumberInput/NumberInput.doc.mjs';
+import {docs as PowerSearchDocs} from '../PowerSearch/PowerSearch.doc.mjs';
+import {docs as SelectorDocs} from '../Selector/Selector.doc.mjs';
+import {docs as TextInputDocs} from '../TextInput/TextInput.doc.mjs';
+import {docs as ToastDocs} from '../Toast/Toast.doc.mjs';
+import {docs as TokenizerDocs} from '../Tokenizer/Tokenizer.doc.mjs';
+
+// `docs` is the ComponentDoc union (single vs multi component); narrow it
+// for structural access to either the top-level props or the first
+// sub-component's props.
+function getProps(docs: unknown): {name: string}[] {
+  const doc = docs as {
+    props?: {name: string}[];
+    components?: {props?: {name: string}[]}[];
+  };
+  return doc.props || doc.components?.[0]?.props || [];
+}
+
+describe('API Contract Drift Audit (#4163)', () => {
+  it('documents Button link mode props', () => {
+    const props = getProps(ButtonDocs).map(p => p.name);
+    expect(props).toContain('href');
+    expect(props).toContain('as');
+    expect(props).toContain('target');
+    expect(props).toContain('rel');
+  });
+
+  it('documents Toast onDismiss callback', () => {
+    const props = getProps(ToastDocs).map(p => p.name);
+    expect(props).toContain('onDismiss');
+  });
+
+  it('documents ContextMenu and MoreMenu onOpenChange callback', () => {
+    const contextProps = getProps(ContextMenuDocs).map(p => p.name);
+    const moreProps = getProps(MoreMenuDocs).map(p => p.name);
+    expect(contextProps).toContain('onOpenChange');
+    expect(moreProps).toContain('onOpenChange');
+  });
+
+  it('documents Selector startIcon and isLoading props', () => {
+    const props = getProps(SelectorDocs).map(p => p.name);
+    expect(props).toContain('startIcon');
+    expect(props).toContain('isLoading');
+  });
+
+  it('documents TextInput and NumberInput onEnter / onKeyDown callbacks', () => {
+    const textProps = getProps(TextInputDocs).map(p => p.name);
+    const numProps = getProps(NumberInputDocs).map(p => p.name);
+    expect(textProps).toContain('onEnter');
+    expect(textProps).toContain('onKeyDown');
+    expect(numProps).toContain('onEnter');
+    expect(numProps).toContain('onKeyDown');
+  });
+
+  it('documents PowerSearch and Tokenizer onFocus / onBlur callbacks', () => {
+    const powerProps = getProps(PowerSearchDocs).map(p => p.name);
+    const tokProps = getProps(TokenizerDocs).map(p => p.name);
+    expect(powerProps).toContain('onFocus');
+    expect(powerProps).toContain('onBlur');
+    expect(tokProps).toContain('onFocus');
+    expect(tokProps).toContain('onBlur');
+  });
+
+  it('documents Link download / referrerPolicy and Dialog padding props', () => {
+    const linkProps = getProps(LinkDocs).map(p => p.name);
+    const dialogProps = getProps(DialogDocs).map(p => p.name);
+    expect(linkProps).toContain('download');
+    expect(linkProps).toContain('referrerPolicy');
+    expect(dialogProps).toContain('padding');
+  });
+});

package/src/__tests__/fieldContract.test.tsx

@@ -0,0 +1,24 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect} from 'vitest';
+
+import {docs as FieldDocs} from '../Field/Field.doc.mjs';
+
+// `docs` is the ComponentDoc union (single vs multi component); narrow it
+// for structural access to either the top-level props or the first
+// sub-component's props.
+function getProps(docs: unknown): {name: string}[] {
+  const doc = docs as {
+    props?: {name: string}[];
+    components?: {props?: {name: string}[]}[];
+  };
+  return doc.props || doc.components?.[0]?.props || [];
+}
+
+describe('Field Component API Contract Drift (#4163)', () => {
+  it('documents Field labelID and isGroupLabel props', () => {
+    const props = getProps(FieldDocs).map(p => p.name);
+    expect(props).toContain('labelID');
+    expect(props).toContain('isGroupLabel');
+  });
+});

package/src/__tests__/structuralComponentContract.test.tsx

@@ -0,0 +1,39 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect} from 'vitest';
+
+import {docs as CodeBlockDocs} from '../CodeBlock/CodeBlock.doc.mjs';
+import {docs as StackDocs} from '../Stack/Stack.doc.mjs';
+import {docs as ToolbarDocs} from '../Toolbar/Toolbar.doc.mjs';
+
+// `docs` is the ComponentDoc union (single vs multi component); narrow it
+// for structural access to either the top-level props or the first
+// sub-component's props.
+function getProps(docs: unknown): {name: string}[] {
+  const doc = docs as {
+    props?: {name: string}[];
+    components?: {props?: {name: string}[]}[];
+  };
+  return doc.props || doc.components?.[0]?.props || [];
+}
+
+describe('Structural Component API Contract Drift (#4163)', () => {
+  it('documents CodeBlock highlightMode prop', () => {
+    const props = getProps(CodeBlockDocs).map(p => p.name);
+    expect(props).toContain('highlightMode');
+  });
+
+  it('documents Toolbar dividers prop', () => {
+    const props = getProps(ToolbarDocs).map(p => p.name);
+    expect(props).toContain('dividers');
+  });
+
+  it('documents Stack direction and base props', () => {
+    const props = getProps(StackDocs).map(p => p.name);
+    expect(props).toContain('direction');
+    expect(props).toContain('gap');
+    expect(props).toContain('padding');
+    expect(props).toContain('width');
+    expect(props).toContain('height');
+  });
+});

package/src/hooks/index.ts

@@ -56,6 +56,8 @@ export type {UseTypeaheadOptions, UseTypeaheadReturn} from './useTypeahead';
 
 export {useMediaQuery} from './useMediaQuery';
 
+export {useMergedRefs} from './useMergedRefs';
+
 export {useOverflow} from './useOverflow';
 export type {UseOverflowOptions, UseOverflowReturn} from './useOverflow';
 

package/src/hooks/useHotkeys.test.ts

@@ -67,6 +67,24 @@ describe('useHotkeys', () => {
     expect(onPress).toHaveBeenCalledTimes(1);
   });
 
+  it('reads a blank userAgentData.platform as unknown, not as non-Apple', () => {
+    // Builds that rewrite their client-hints identity expose the key with an
+    // empty value; navigator.platform is the only surface left that answers.
+    vi.stubGlobal('navigator', {
+      userAgentData: {platform: ''},
+      platform: 'MacIntel',
+    });
+    const onPress = vi.fn();
+    renderHook(() => useHotkeys([{keys: 'mod+k', onPress}]));
+
+    press('k', {ctrlKey: true});
+    expect(onPress).not.toHaveBeenCalled();
+
+    const event = press('k', {metaKey: true});
+    expect(onPress).toHaveBeenCalledTimes(1);
+    expect(onPress).toHaveBeenCalledWith(event);
+  });
+
   it('does not fire a bare key when modifiers are held', () => {
     stubApplePlatform();
     const onPress = vi.fn();

package/src/hooks/useHotkeys.ts

@@ -73,8 +73,9 @@ const KEY_ALIASES: Record<string, string> = {
 
 /**
  * Detects whether the current platform is macOS/iOS.
- * Prefers the User-Agent Client Hints API when available (modern Chrome/Edge),
- * falls back to navigator.platform (deprecated but universally supported).
+ * Prefers the User-Agent Client Hints API when it names a platform (modern
+ * Chrome/Edge), falls back to navigator.platform (deprecated but universally
+ * supported) when it is absent or blank.
  * Mirrors the detection used by Kbd so displayed and handled shortcuts agree.
  */
 function isApplePlatform(): boolean {
@@ -83,7 +84,13 @@ function isApplePlatform(): boolean {
   }
   const uaData = 'userAgentData' in navigator ? navigator.userAgentData : null;
   if (uaData && typeof uaData === 'object' && 'platform' in uaData) {
-    return /mac/i.test((uaData as {platform: string}).platform ?? '');
+    const uaPlatform = (uaData as {platform?: unknown}).platform;
+    // A blank platform is no answer, not a negative one. Builds that rewrite
+    // their client-hints identity ship '', so fall through rather than
+    // reading it as "not Apple".
+    if (typeof uaPlatform === 'string' && uaPlatform.trim() !== '') {
+      return /mac/i.test(uaPlatform);
+    }
   }
   return /Mac|iPhone|iPad|iPod/.test(navigator.platform ?? '');
 }

package/src/hooks/useListFocus.doc.mjs

@@ -36,7 +36,7 @@ export const docs = {
     {
       name: 'options.onEscape',
       type: '() => void',
-      description: 'Callback when Escape key is pressed (e.g., close menu).',
+      description: 'Callback when Escape key is pressed (e.g., close menu). Supplying it also consumes the key (preventDefault); without it Escape passes through to the surrounding layer.',
       required: false,
     },
     {
@@ -144,7 +144,7 @@ export const docsDense = {
     'options.itemSelector': 'selector for focusable items in list.',
     'options.boundarySelector': "boundary selector for lists that contain nested lists (e.g. submenu flyouts); scopes items + key handling to this level.",
     'options.wrap': 'whether arrow navigation wraps around at ends.',
-    'options.onEscape': 'callback when Escape key pressed (e.g. close menu).',
+    'options.onEscape': 'callback when Escape key pressed (e.g. close menu). Also consumes the key; without it Escape passes through to the surrounding layer.',
     'options.orientation': "navigation orientation. 'horizontal' uses ArrowLeft/ArrowRight, 'vertical' uses ArrowUp/ArrowDown, 'both' accepts all four arrows.",
     'options.hasHomeEnd': 'whether Home/End jump to first/last enabled item.',
     'options.isRtl': 'ArrowLeft/ArrowRight swap for horizontal nav (RTL). default: auto-detect from container computed direction; explicit boolean wins.',

package/src/hooks/useListFocus.test.tsx

@@ -3,14 +3,14 @@
 /**
  * @file useListFocus.test.tsx
  * @input Uses vitest, @testing-library/react, useListFocus hook
- * @output Unit tests for useListFocus disabled-item skipping, navigation, and
- *   RTL auto-detection
+ * @output Unit tests for useListFocus disabled-item skipping, navigation,
+ *   Escape consumption, and RTL auto-detection
  * @position Testing; validates useListFocus.ts keyboard navigation
  *
  * SYNC: When useListFocus.ts changes, update tests to match new behavior
  */
 
-import {describe, it, expect} from 'vitest';
+import {describe, it, expect, vi} from 'vitest';
 import type {KeyboardEvent as ReactKeyboardEvent} from 'react';
 import {render, screen, fireEvent} from '@testing-library/react';
 import {useListFocus} from './useListFocus';
@@ -525,3 +525,65 @@ describe('useListFocus boundarySelector (nested lists)', () => {
     expect(innerProbe).toHaveAttribute('data-owns', 'false');
   });
 });
+
+// A list inside a host that dismisses on Escape. The host's guard mirrors
+// `useFocusTrap`: it acts only on a key no inner handler has consumed.
+function EscapeHost({
+  onEscape,
+  onHostEscape,
+}: {
+  onEscape?: () => void;
+  onHostEscape: () => void;
+}) {
+  const {listRef, handleKeyDown} = useListFocus<HTMLDivElement>({onEscape});
+  return (
+    <div
+      data-testid="host"
+      onKeyDown={e => {
+        if (e.key === 'Escape' && !e.defaultPrevented) {
+          onHostEscape();
+        }
+      }}>
+      <div ref={listRef} role="menu" onKeyDown={handleKeyDown}>
+        <div role="menuitem" tabIndex={-1} data-testid="One">
+          One
+        </div>
+        <div role="menuitem" tabIndex={-1} data-testid="Two">
+          Two
+        </div>
+      </div>
+    </div>
+  );
+}
+
+describe('useListFocus Escape', () => {
+  it('leaves Escape to the host when no onEscape is supplied', () => {
+    const onHostEscape = vi.fn();
+    render(<EscapeHost onHostEscape={onHostEscape} />);
+
+    fireEvent.keyDown(screen.getByRole('menu'), {key: 'Escape'});
+    expect(onHostEscape).toHaveBeenCalledTimes(1);
+  });
+
+  it('consumes Escape and runs onEscape when one is supplied', () => {
+    const onEscape = vi.fn();
+    const onHostEscape = vi.fn();
+    render(<EscapeHost onEscape={onEscape} onHostEscape={onHostEscape} />);
+
+    fireEvent.keyDown(screen.getByRole('menu'), {key: 'Escape'});
+    expect(onEscape).toHaveBeenCalledTimes(1);
+    expect(onHostEscape).not.toHaveBeenCalled();
+  });
+
+  it('still consumes arrow keys with no onEscape (page-scroll suppression)', () => {
+    render(<EscapeHost onHostEscape={() => {}} />);
+    screen.getByTestId('One').focus();
+
+    // fireEvent returns false when a handler cancelled the event.
+    const wasCancelled = !fireEvent.keyDown(screen.getByRole('menu'), {
+      key: 'ArrowDown',
+    });
+    expect(wasCancelled).toBe(true);
+    expect(screen.getByTestId('Two')).toHaveFocus();
+  });
+});

package/src/hooks/useListFocus.ts

@@ -14,6 +14,8 @@
  *
  * SYNC: When modified, update:
  * - /packages/core/src/hooks/index.ts
+ * - /packages/core/src/hooks/useListFocus.doc.mjs
+ * - /packages/core/src/hooks/useListFocus.test.tsx
  */
 
 import {useCallback, useRef} from 'react';
@@ -64,7 +66,9 @@ export interface UseListFocusOptions {
   wrap?: boolean;
 
   /**
-   * Callback when Escape key is pressed.
+   * Callback when Escape key is pressed. Supplying it also makes the list
+   * consume the key (`preventDefault`); without it Escape passes through to
+   * the surrounding layer.
    */
   onEscape?: () => void;
 
@@ -277,7 +281,8 @@ function shouldDeferToCaret(target: EventTarget | null, key: string): boolean {
  * - ArrowUp/ArrowLeft: Move to previous item (wraps to last)
  * - Home: Move to first item
  * - End: Move to last item
- * - Escape: Custom callback (e.g., close menu)
+ * - Escape: runs `onEscape` and consumes the key. With no `onEscape` the key
+ *   is left alone, so a surrounding layer can still dismiss on it.
  *
  * By default the hook only *moves* focus and leaves `tabindex` management to
  * the caller. Opt into {@link UseListFocusOptions.hasRovingTabIndex} for a hook
@@ -557,12 +562,15 @@ export function useListFocus<T extends HTMLElement = HTMLElement>(
         return;
       }
 
-      // Escape is handled regardless of orientation. Preserve the historical
-      // behavior of always consuming Escape here (preventDefault) so consumers
-      // that relied on it are unaffected.
+      // Escape is handled regardless of orientation, but only *consumed* when
+      // a handler asked for it: a list with no dismissal to perform must leave
+      // the key to whatever host layer does have one, and those defer to
+      // `defaultPrevented` (see `useFocusTrap`) or to the native popover.
       if (e.key === 'Escape') {
-        e.preventDefault();
-        onEscape?.();
+        if (onEscape) {
+          e.preventDefault();
+          onEscape();
+        }
         return;
       }
 

package/src/hooks/useMergedRefs.doc.mjs

@@ -0,0 +1,79 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
+export const docs = {
+  name: 'useMergedRefs',
+  displayName: 'useMergedRefs',
+  keywords: [
+    'ref',
+    'refs',
+    'merge',
+    'forwardRef',
+    'callback ref',
+    'stable ref',
+  ],
+  params: [
+    {
+      name: 'refs',
+      type: 'Array<Ref<T> | undefined>',
+      description: 'Up to six refs that should all receive the same element.',
+      required: true,
+    },
+  ],
+  returns: [
+    {
+      name: 'ref',
+      type: 'RefCallback<T>',
+      description:
+        'A merged callback ref that remains stable until an input ref changes.',
+    },
+  ],
+  usage: {
+    description:
+      'Combines multiple object or callback refs into one stable callback ref. Use it when a component must forward a consumer ref while also attaching internal refs. Unlike calling mergeRefs during render, the callback identity stays stable across unrelated rerenders, so React does not detach and reattach the element.',
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          'Use useMergedRefs when one element must receive both a forwarded ref and one or more internal refs.',
+      },
+      {
+        guidance: false,
+        description:
+          'Call mergeRefs directly in a JSX ref prop; that creates a new callback on every render and forces unnecessary detach and attach work.',
+      },
+    ],
+  },
+  relatedComponents: [],
+  relatedHooks: [],
+  importPath: '@astryxdesign/core/hooks',
+  category: 'utility',
+};
+
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
+export const docsDense = {
+  description:
+    'Combines object/callback refs into one stable callback ref. Identity changes only when an input ref changes, avoiding detach/attach churn from inline mergeRefs calls.',
+  paramDescriptions: {
+    refs: 'refs that should all receive the same element.',
+  },
+  returnDescriptions: {
+    ref: 'stable merged callback ref; changes only when an input ref changes.',
+  },
+  usage: {
+    description:
+      'Use when one element needs a forwarded consumer ref plus internal refs. Keeps the callback stable across unrelated rerenders.',
+    bestPractices: [
+      {
+        guidance: true,
+        description:
+          'Use for a forwarded ref plus internal measurement, focus, or anchor refs.',
+      },
+      {
+        guidance: false,
+        description:
+          'Call mergeRefs inline in JSX; it forces ref detach/attach on every render.',
+      },
+    ],
+  },
+};

package/src/hooks/useMergedRefs.test.tsx

@@ -0,0 +1,62 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file useMergedRefs.test.tsx
+ * @input Uses vitest, @testing-library/react, useMergedRefs hook
+ * @output Unit tests for stable merged ref behavior
+ * @position Testing; validates useMergedRefs.ts
+ *
+ * SYNC: When useMergedRefs.ts changes, update tests to match new behavior
+ */
+
+import {renderHook} from '@testing-library/react';
+import {createRef} from 'react';
+import {describe, expect, it, vi} from 'vitest';
+import {useMergedRefs} from './useMergedRefs';
+
+describe('useMergedRefs', () => {
+  it('forwards values to callback and object refs', () => {
+    const callbackRef = vi.fn();
+    const objectRef = createRef<HTMLDivElement>();
+    const {result} = renderHook(() =>
+      useMergedRefs<HTMLDivElement>(callbackRef, objectRef),
+    );
+    const element = document.createElement('div');
+
+    const cleanup = result.current(element);
+
+    expect(callbackRef).toHaveBeenCalledWith(element);
+    expect(objectRef.current).toBe(element);
+
+    cleanup?.();
+    expect(callbackRef).toHaveBeenLastCalledWith(null);
+    expect(objectRef.current).toBeNull();
+  });
+
+  it('keeps the merged callback stable when input refs are unchanged', () => {
+    const callbackRef = vi.fn();
+    const objectRef = createRef<HTMLDivElement>();
+    const {result, rerender} = renderHook(() =>
+      useMergedRefs<HTMLDivElement>(callbackRef, objectRef),
+    );
+    const first = result.current;
+
+    rerender();
+
+    expect(result.current).toBe(first);
+  });
+
+  it('updates the merged callback when an input ref changes', () => {
+    const firstRef = vi.fn();
+    const secondRef = vi.fn();
+    const {result, rerender} = renderHook(
+      ({ref}) => useMergedRefs<HTMLDivElement>(ref),
+      {initialProps: {ref: firstRef}},
+    );
+    const first = result.current;
+
+    rerender({ref: secondRef});
+
+    expect(result.current).not.toBe(first);
+  });
+});

package/src/hooks/useMergedRefs.ts

@@ -0,0 +1,36 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useMergedRefs.ts
+ * @input React refs to combine into one stable callback ref
+ * @output Exports useMergedRefs
+ * @position Core hook; use when one element must receive multiple refs
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/hooks/index.ts
+ * - /packages/core/src/hooks/useMergedRefs.doc.mjs
+ * - /packages/core/src/hooks/useMergedRefs.test.tsx
+ */
+
+import {useMemo, type Ref, type RefCallback} from 'react';
+import {mergeRefs} from '../utils/mergeRefs';
+
+/**
+ * Combine up to six refs into a callback ref whose identity changes only when
+ * one of the input refs changes.
+ */
+export function useMergedRefs<T>(
+  refA?: Ref<T>,
+  refB?: Ref<T>,
+  refC?: Ref<T>,
+  refD?: Ref<T>,
+  refE?: Ref<T>,
+  refF?: Ref<T>,
+): RefCallback<T> {
+  return useMemo(
+    () => mergeRefs(refA, refB, refC, refD, refE, refF),
+    [refA, refB, refC, refD, refE, refF],
+  );
+}

package/src/index.ts

@@ -55,6 +55,7 @@ export * from './NavIcon';
 export * from './NavMenu';
 export * from './Slider';
 export * from './Stack';
+export * from './Stepper';
 export * from './Switch';
 export * from './DateInput';
 export * from './DateTimeInput';

package/src/theme/MediaTheme.doc.mjs

@@ -68,7 +68,7 @@ export const docs = {
       {
         guidance: true,
         description:
-          'Prefer mode="auto" when the surface color comes from a theme token. A token named "inverted" is not guaranteed to be inverted, and auto measures what was actually painted instead of trusting the name — including deciding that a surface needs no media context at all.',
+          'Prefer mode="auto" when the surface color comes from a theme token. A token named "inverted" is not guaranteed to be inverted, and auto measures what was actually painted instead of trusting the name. It can even decide that a surface needs no media context at all.',
       },
       {
         guidance: true,
@@ -93,14 +93,14 @@ export const docs = {
       type: "'dark' | 'light' | 'auto' | 'off'",
       required: true,
       description:
-        'Surface luminance context: dark for content over dark backgrounds (light text, white-tinted interactions), light for content over light backgrounds (dark text, black-tinted interactions), auto to decide from the painted surface — no media context when the ambient text already reads on the surface (3:1), otherwise the side that reads better — and off to turn it off explicitly. The element renders either way, so a surface can switch contexts without remounting children.',
+        'Surface luminance context: dark for content over dark backgrounds (light text, white-tinted interactions), light for content over light backgrounds (dark text, black-tinted interactions), auto to decide from the painted surface (no media context when the ambient text already reads on the surface at 3:1, otherwise the side that reads better), and off to turn it off explicitly. The element renders either way, so a surface can switch contexts without remounting children.',
     },
     {
       name: 'fallback',
       type: "'dark' | 'light'",
       default: "'dark'",
       description:
-        'Which side auto uses when the surface cannot be measured: during SSR, on the first client frame, and whenever the backdrop is not knowable from CSS — most often a background-image, whose pixels need sampling (useImageMode) rather than a computed style. Ignored unless mode is auto.',
+        'Which side auto uses when the surface cannot be measured: during SSR, on the first client frame, and whenever the backdrop is not knowable from CSS, most often a background-image, whose pixels need sampling (useImageMode) rather than a computed style. Ignored unless mode is auto.',
     },
     {
       name: 'children',
@@ -126,7 +126,7 @@ export const docsDense = {
       {
         guidance: true,
         description:
-          'Prefer mode="auto" when surface color comes from a theme token — a token named "inverted" is not guaranteed to be; auto measures what was painted.',
+          'Prefer mode="auto" when surface color comes from a theme token; a token named "inverted" is not guaranteed to be; auto measures what was painted.',
       },
       {
         guidance: true,
@@ -148,6 +148,6 @@ export const docsDense = {
   propDescriptions: {
     mode: 'surface luminance context: dark for content over dark backgrounds (light text, white-tinted interactions), light for content over light backgrounds (dark text, black-tinted interactions), auto to decide from painted surface (none if ambient text already reads at 3:1, else better-reading side), off to turn off explicitly (element still renders, so children never remount)',
     fallback:
-      'side auto uses when surface is unmeasurable (SSR, first frame, background-image — those need useImageMode sampling); ignored unless mode is auto',
+      'side auto uses when surface is unmeasurable (SSR, first frame, background-image, which needs useImageMode sampling); ignored unless mode is auto',
   },
 };