@astryxdesign/core 0.4.7 → 0.5.0-canary.055e75f

package/src/hooks/useFocusTrapEscapeShim.test.tsx

@@ -0,0 +1,165 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file useFocusTrapEscapeShim.test.tsx
+ * @input Uses vitest, @testing-library/react, useFocusTrap, Dialog, Lightbox,
+ *   MobileNav, Tooltip, Popover
+ * @output Tests that hasActiveFocusTrapEscape still means what it meant in
+ *   0.4.2 — an Escape-dismissible FOCUS TRAP is active, not "a layer is open"
+ * @position Testing; guards the deprecated public shim in useFocusTrap.ts
+ *
+ * The shim is public API. Its answer must not change now that Escape moved to
+ * the shared stack: `BottomSheetSwitcher` gates its own dismissal on it, so a
+ * shim that also counts tooltips, hover cards and dialogs tells the sheet a
+ * trap is above it when none is, and the sheet stops closing.
+ *
+ * SYNC: When useFocusTrap.ts changes, update tests to match new behavior
+ */
+
+import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
+import {render} from '@testing-library/react';
+
+import {hasActiveFocusTrapEscape, useFocusTrap} from './useFocusTrap';
+import {Dialog} from '../Dialog/Dialog';
+import {Lightbox} from '../Lightbox/Lightbox';
+import {MobileNav} from '../MobileNav/MobileNav';
+import {Popover} from '../Popover/Popover';
+import {Tooltip} from '../Tooltip/Tooltip';
+import {resetLayerStackForTests} from '../Layer/layerStack';
+
+beforeEach(() => {
+  HTMLDialogElement.prototype.showModal = vi.fn(function (
+    this: HTMLDialogElement,
+  ) {
+    this.setAttribute('open', '');
+  });
+  HTMLDialogElement.prototype.close = vi.fn(function (this: HTMLDialogElement) {
+    this.removeAttribute('open');
+  });
+});
+
+afterEach(() => {
+  resetLayerStackForTests();
+});
+
+function Trap({
+  isActive = true,
+  hasEscape = true,
+  children,
+}: {
+  isActive?: boolean;
+  hasEscape?: boolean;
+  children?: React.ReactNode;
+}) {
+  const {containerRef} = useFocusTrap<HTMLDivElement>({
+    isActive,
+    onEscape: hasEscape ? () => {} : undefined,
+  });
+  return <div ref={containerRef}>{children}</div>;
+}
+
+describe('hasActiveFocusTrapEscape', () => {
+  it('is false with nothing mounted', () => {
+    expect(hasActiveFocusTrapEscape()).toBe(false);
+  });
+
+  it('is true for an active trap with an Escape handler', () => {
+    render(<Trap />);
+    expect(hasActiveFocusTrapEscape()).toBe(true);
+  });
+
+  it('is false for a trap with no Escape handler', () => {
+    render(<Trap hasEscape={false} />);
+    expect(hasActiveFocusTrapEscape()).toBe(false);
+  });
+
+  it('is false for an inactive trap', () => {
+    render(<Trap isActive={false} />);
+    expect(hasActiveFocusTrapEscape()).toBe(false);
+  });
+
+  it('is true for nested traps, and false again once both unmount', () => {
+    const {unmount} = render(
+      <Trap>
+        <Trap />
+      </Trap>,
+    );
+    expect(hasActiveFocusTrapEscape()).toBe(true);
+    unmount();
+    expect(hasActiveFocusTrapEscape()).toBe(false);
+  });
+
+  it('is true for an open Popover, which traps focus', () => {
+    render(
+      <Popover
+        isOpen={true}
+        onOpenChange={() => {}}
+        content="Popover body"
+        label="Popover">
+        <button type="button">Open</button>
+      </Popover>,
+    );
+    expect(hasActiveFocusTrapEscape()).toBe(true);
+  });
+
+  // The families below are all on the shared dismissal stack and none of them
+  // traps focus. Answering `true` for these is what broke the bottom sheet.
+  it('is false for an open Dialog', () => {
+    render(
+      <Dialog isOpen={true} onOpenChange={() => {}} aria-label="Dialog">
+        Body
+      </Dialog>,
+    );
+    expect(hasActiveFocusTrapEscape()).toBe(false);
+  });
+
+  it('is false for an open Lightbox', () => {
+    render(
+      <Lightbox
+        isOpen={true}
+        onOpenChange={() => {}}
+        media={{src: '/photo.jpg', alt: 'A photo'}}
+      />,
+    );
+    expect(hasActiveFocusTrapEscape()).toBe(false);
+  });
+
+  it('is false for an open MobileNav', () => {
+    render(
+      <MobileNav isOpen={true} onOpenChange={() => {}} label="Drawer">
+        <span>Nav</span>
+      </MobileNav>,
+    );
+    expect(hasActiveFocusTrapEscape()).toBe(false);
+  });
+
+  it('is false for a showing Tooltip', () => {
+    render(
+      <Tooltip content="Tip" isDefaultOpen={true}>
+        <button type="button">Trigger</button>
+      </Tooltip>,
+    );
+    expect(hasActiveFocusTrapEscape()).toBe(false);
+  });
+
+  it('is true for a Popover inside a Dialog, and false once the Popover closes', () => {
+    function Scene({isPopoverOpen}: {isPopoverOpen: boolean}) {
+      return (
+        <Dialog isOpen={true} onOpenChange={() => {}} aria-label="Dialog">
+          <Popover
+            isOpen={isPopoverOpen}
+            onOpenChange={() => {}}
+            content="Popover body"
+            label="Popover">
+            <button type="button">Open</button>
+          </Popover>
+        </Dialog>
+      );
+    }
+    const {rerender} = render(<Scene isPopoverOpen={true} />);
+    expect(hasActiveFocusTrapEscape()).toBe(true);
+
+    rerender(<Scene isPopoverOpen={false} />);
+    expect(hasActiveFocusTrapEscape()).toBe(false);
+  });
+});

package/src/hooks/useHotkeys.ts

@@ -18,7 +18,8 @@
  * unless a hotkey opts in via `allowInInputs`.
  *
  * Platform-aware: `mod` maps to metaKey (⌘) on Apple platforms and
- * ctrlKey elsewhere — mirrors the detection used by Kbd.
+ * ctrlKey elsewhere, through the same isApplePlatform util Kbd reads, so
+ * displayed and handled shortcuts cannot disagree.
  *
  * SYNC: When modified, update:
  * - /packages/core/src/hooks/index.ts
@@ -26,6 +27,7 @@
  */
 
 import {useEffect, useRef} from 'react';
+import {isApplePlatform} from '../utils/isApplePlatform';
 
 /**
  * A single keyboard shortcut registration.
@@ -71,23 +73,6 @@ const KEY_ALIASES: Record<string, string> = {
   plus: '+',
 };
 
-/**
- * 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).
- * Mirrors the detection used by Kbd so displayed and handled shortcuts agree.
- */
-function isApplePlatform(): boolean {
-  if (typeof navigator === 'undefined') {
-    return false;
-  }
-  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 ?? '');
-  }
-  return /Mac|iPhone|iPad|iPod/.test(navigator.platform ?? '');
-}
-
 /**
  * Whether the event target is a typing surface where global shortcuts
  * should stay silent by default.

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/raw-import.d.ts

@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Ambient module declaration for Vite's `?raw` imports.
+ *
+ * numberParser.docblock.test.ts reads its own subject's source as text, to
+ * check the prose in it against the parser's behaviour. Vite serves that with
+ * the `?raw` query; without this declaration TypeScript fails with TS2307.
+ */
+
+declare module '*?raw' {
+  const content: string;
+  export default content;
+}

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',
   },
 };

package/src/theme/derivedVarRegistry.test.ts

@@ -213,6 +213,7 @@ function discoverComponents(): ComponentInfo[] {
 // ---------------------------------------------------------------------------
 
 const DIR_TO_REGISTRY_KEY: Record<string, string> = {
+  Avatar: 'avatar',
   Banner: 'banner',
   Button: 'button',
   Card: 'card',
@@ -221,13 +222,13 @@ const DIR_TO_REGISTRY_KEY: Record<string, string> = {
   Dialog: 'dialog',
   DropdownMenu: 'dropdown-menu',
   Field: 'field',
-  HoverCard: 'hovercard',
+  HoverCard: 'hover-card',
   NumberInput: 'number-input',
   Popover: 'popover',
-  ProgressBar: 'progressbar-mark',
+  ProgressBar: 'progress-bar-mark',
   Section: 'section',
   SegmentedControl: 'segmented-control',
-  TextArea: 'textarea',
+  TextArea: 'text-area',
 };
 
 /**
@@ -418,6 +419,21 @@ describe('getDerivedVars', () => {
     expect(getDerivedVars('unknown', 'borderRadius')).toEqual([]);
   });
 
+  it('resolves a deprecated key to the entries of the key that replaced it', () => {
+    // A theme written against the old spelling still selects the element (the
+    // component emits both classes), so its derived vars must still expand —
+    // otherwise the rule lands and the var half of it silently does nothing.
+    expect(getDerivedVars('hovercard', 'borderRadius')).toEqual(
+      getDerivedVars('hover-card', 'borderRadius'),
+    );
+    expect(getDerivedVars('textarea', 'paddingInline')).toEqual(
+      getDerivedVars('text-area', 'paddingInline'),
+    );
+    expect(getDerivedVars('progressbar-mark', 'width')).toEqual(
+      getDerivedVars('progress-bar-mark', 'width'),
+    );
+  });
+
   it('returns empty for unregistered property', () => {
     expect(getDerivedVars('card', 'color')).toEqual([]);
   });

package/src/theme/derivedVarRegistry.ts

@@ -43,6 +43,7 @@ export interface DerivedVarEntry {
  * entries share the same property.
  */
 export const derivedVarRegistry: Record<string, DerivedVarEntry[]> = {
+  avatar: [{property: 'borderRadius', vars: ['--_avatar-radius']}],
   banner: [{property: 'borderRadius', vars: ['--_banner-radius']}],
   button: [{property: 'borderRadius', vars: ['--_button-radius']}],
   card: [
@@ -66,13 +67,13 @@ export const derivedVarRegistry: Record<string, DerivedVarEntry[]> = {
     {property: 'padding', vars: ['--_dropdown-menu-padding']},
   ],
   field: [{property: 'borderRadius', vars: ['--_field-radius']}],
-  hovercard: [{property: 'borderRadius', vars: ['--_hovercard-radius']}],
+  'hover-card': [{property: 'borderRadius', vars: ['--_hovercard-radius']}],
   'number-input': [
     {property: 'padding', expand: 'container'},
     {property: 'borderRadius', vars: ['--_field-radius']},
   ],
   popover: [{property: 'borderRadius', vars: ['--_popover-radius']}],
-  'progressbar-mark': [
+  'progress-bar-mark': [
     {property: 'width', vars: ['--_progressbar-mark-width'], replaces: true},
     {property: 'height', vars: ['--_progressbar-mark-height'], replaces: true},
   ],
@@ -81,7 +82,7 @@ export const derivedVarRegistry: Record<string, DerivedVarEntry[]> = {
     {property: 'borderRadius', vars: ['--_segmented-control-radius']},
     {property: 'padding', vars: ['--_segmented-control-padding']},
   ],
-  textarea: [
+  'text-area': [
     {
       property: 'paddingInline',
       vars: ['--_textarea-inline-padding'],
@@ -90,6 +91,21 @@ export const derivedVarRegistry: Record<string, DerivedVarEntry[]> = {
   ],
 };
 
+/**
+ * Deprecated component keys → the key that superseded them.
+ *
+ * A renamed target keeps emitting its old class, so a theme written against
+ * the old key still selects the element. Without this the rule would land but
+ * its derived vars would not expand, and the half that travels through a var
+ * (a hover card's radius, a text area's inline padding) would silently do
+ * nothing. Drop these with the classes, in the next major.
+ */
+const DEPRECATED_REGISTRY_KEYS: Record<string, string> = {
+  hovercard: 'hover-card',
+  'progressbar-mark': 'progress-bar-mark',
+  textarea: 'text-area',
+};
+
 /**
  * Look up derived var entries for a component + CSS property.
  * Returns matching entries in priority order, or empty array if none.
@@ -98,7 +114,10 @@ export function getDerivedVars(
   component: string,
   property: string,
 ): DerivedVarEntry[] {
-  const entries = derivedVarRegistry[component];
+  const renamedTo = DEPRECATED_REGISTRY_KEYS[component];
+  const entries =
+    derivedVarRegistry[component] ??
+    (renamedTo ? derivedVarRegistry[renamedTo] : undefined);
   if (!entries) {
     return [];
   }

package/src/theme/generateThemeRules.test.ts

@@ -702,3 +702,40 @@ describe('physical padding longhands', () => {
     expect(rule).not.toContain('--_dropdown-menu-padding');
   });
 });
+
+describe('renamed theme targets', () => {
+  // The renamed targets emit both classes, so a rule written against either
+  // key selects the element. What is easy to miss is the derived-var half: a
+  // key the registry does not know still emits a rule, minus every var the
+  // component actually reads — the same silent nothing a misspelled key gives.
+  it('expands derived vars for a renamed key and its deprecated spelling', () => {
+    const rules = (component: string, styles: Record<string, string>) =>
+      generateThemeRules(
+        defineTheme({
+          name: `test-renamed-${component}`,
+          components: {[component]: {base: styles}},
+        }),
+      ).join('\n');
+
+    const hoverCard = rules('hover-card', {borderRadius: '9px'});
+    expect(hoverCard).toContain('.astryx-hover-card');
+    expect(hoverCard).toContain('--_hovercard-radius: 9px');
+    expect(rules('hovercard', {borderRadius: '9px'})).toContain(
+      '--_hovercard-radius: 9px',
+    );
+
+    const textArea = rules('text-area', {paddingInline: '11px'});
+    expect(textArea).toContain('.astryx-text-area');
+    expect(textArea).toContain('--_textarea-inline-padding: 11px');
+    expect(rules('textarea', {paddingInline: '11px'})).toContain(
+      '--_textarea-inline-padding: 11px',
+    );
+
+    const mark = rules('progress-bar-mark', {width: '3px'});
+    expect(mark).toContain('.astryx-progress-bar-mark');
+    expect(mark).toContain('--_progressbar-mark-width: 3px');
+    expect(rules('progressbar-mark', {width: '3px'})).toContain(
+      '--_progressbar-mark-width: 3px',
+    );
+  });
+});

package/src/theme/syntax/tokens.ts

@@ -44,8 +44,11 @@ export const syntaxTokenDefaults = {
   '--color-syntax-attribute': 'var(--color-text-teal)',
   // property -> cyan text (object properties)
   '--color-syntax-property': 'var(--color-text-cyan)',
-  // punctuation -> disabled text (brackets, semicolons)
-  '--color-syntax-punctuation': 'var(--color-text-disabled)',
+  // punctuation -> secondary text (brackets, semicolons). Not disabled text:
+  // disabled grey is calibrated to fail AA on purpose (WCAG exempts inactive
+  // controls), and punctuation in a code sample is normal, always-active
+  // text — see #5386.
+  '--color-syntax-punctuation': 'var(--color-text-secondary)',
   // background -> muted surface
   '--color-syntax-background': 'var(--color-background-muted)',
 } as const;

package/src/utils/groupItems.ts

@@ -19,6 +19,11 @@ export interface ItemGroup<T extends SearchableItem = SearchableItem> {
   items: T[];
 }
 
+export interface GroupItemsOptions {
+  /** Place ungrouped items before named groups instead of after them. */
+  ungroupedFirst?: boolean;
+}
+
 /**
  * Extract the group string from an item's auxiliaryData.
  */
@@ -52,6 +57,7 @@ export function getItemGroup(item: SearchableItem): string | undefined {
  */
 export function groupItems<T extends SearchableItem>(
   items: T[],
+  {ungroupedFirst = false}: GroupItemsOptions = {},
 ): ItemGroup<T>[] {
   const hasGroups = items.some(item => getItemGroup(item) != null);
 
@@ -76,14 +82,14 @@ export function groupItems<T extends SearchableItem>(
     }
   }
 
-  const result: ItemGroup<T>[] = groupOrder.map(heading => ({
+  const namedGroups: ItemGroup<T>[] = groupOrder.map(heading => ({
     heading,
     items: groups.get(heading) ?? [],
   }));
+  const ungroupedGroup: ItemGroup<T>[] =
+    ungrouped.length > 0 ? [{heading: null, items: ungrouped}] : [];
 
-  if (ungrouped.length > 0) {
-    result.push({heading: null, items: ungrouped});
-  }
-
-  return result;
+  return ungroupedFirst
+    ? [...ungroupedGroup, ...namedGroups]
+    : [...namedGroups, ...ungroupedGroup];
 }

package/src/utils/index.ts

@@ -86,7 +86,7 @@ export type {
   ThemeProps,
 } from './themeProps';
 export {groupItems, getItemGroup} from './groupItems';
-export type {ItemGroup} from './groupItems';
+export type {ItemGroup, GroupItemsOptions} from './groupItems';
 export {observeResize, unobserveResize} from './sharedResizeObserver';
 export {isRenderable} from './isRenderable';
 export {getInputARIA} from './inputAria';