@astryxdesign/core 0.4.6 → 0.4.7-canary.019ae5a

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

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