@astryxdesign/core 0.5.1 → 0.5.2-canary.00477a5

package/src/MultiSelector/MultiSelector.tsx

@@ -28,7 +28,6 @@ import React, {
   type ReactNode,
 } from 'react';
 import * as stylex from '@stylexjs/stylex';
-import {usePopoverInternal} from '../Popover/usePopover';
 import {useTooltip} from '../Tooltip';
 import {Icon, renderIconSlot, type IconType} from '../Icon';
 import type {IconName} from '../Icon';
@@ -57,7 +56,6 @@ import {
   typographyVars,
   fontWeightVars,
   typeScaleVars,
-  borderVars,
 } from '../theme/tokens.stylex';
 import type {
   MultiSelectorOptionType,
@@ -86,6 +84,10 @@ import {groupStyles} from '../InputGroup/groupStyles';
 import {useInputGroup} from '../InputGroup/InputGroupContext';
 import {VisuallyHidden} from '../VisuallyHidden';
 import {useTranslator} from '../i18n';
+import type {AdaptivePresentation} from '../hooks/useAdaptivePresentation';
+import {SelectorBottomSheet} from '../Selector/SelectorBottomSheet';
+import {useSelectorPresentation} from '../Selector/useSelectorPresentation';
+import {selectorPresentationStyles} from '../Selector/selectorPresentation.stylex';
 
 // Sentinel value for the select-all item in keyboard navigation
 const SELECT_ALL_VALUE = '__xds_select_all__';
@@ -245,6 +247,9 @@ const styles = stylex.create({
     overflowY: 'auto',
     padding: spacingVars['--spacing-1'],
   },
+  listbox: {
+    outline: 'none',
+  },
 
   // Popover container (for anchor positioning)
   popover: {
@@ -415,6 +420,8 @@ export type MultiSelectorSize = 'sm' | 'md' | 'lg';
 
 export type MultiSelectorVariant = 'input' | 'ghost';
 
+export type MultiSelectorPresentation = AdaptivePresentation;
+
 export type MultiSelectorStatusType = 'warning' | 'error' | 'success';
 
 export type {MultiSelectorStatus};
@@ -658,6 +665,15 @@ export interface MultiSelectorProps<
    */
   indicatorPosition?: IndicatorPosition;
 
+  /**
+   * How the option list is presented.
+   * - 'popover': anchored to the trigger
+   * - 'bottom-sheet': modal sheet suited to compact touch screens
+   * - 'adaptive': bottom sheet on compact coarse-pointer screens, otherwise popover
+   * @default 'popover'
+   */
+  presentation?: MultiSelectorPresentation;
+
   /**
    * Whether the dropdown starts open on mount.
    * Useful for showcases and previews.
@@ -747,6 +763,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
   maxBadges = 3,
   renderOption,
   indicatorPosition = 'start',
+  presentation = 'popover',
   isDefaultOpen = false,
   'data-testid': testId,
   htmlName,
@@ -754,6 +771,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
   xstyle,
   className,
   style,
+  onFocus,
 }: MultiSelectorProps<T>) {
   const t = useTranslator();
   const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
@@ -780,6 +798,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
   const searchId = useId();
   const triggerRef = useRef<HTMLButtonElement>(null);
   const searchRef = useRef<HTMLInputElement>(null);
+  const listboxRef = useRef<HTMLDivElement>(null);
   const inputGroup = useInputGroup();
 
   const [searchQuery, setSearchQuery] = useState('');
@@ -935,27 +954,31 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
     // Clear any lingering result count when the popover closes so stale status
     // text does not linger in the a11y tree.
     announce('');
-    triggerRef.current?.focus();
   }, [announce]);
 
-  const popover = usePopoverInternal({
-    hasLightDismiss: true,
+  const surface = useSelectorPresentation({
+    presentation,
     onHide: handleLayerHide,
-    hasCloseButton: false,
-    hasAutoFocus: false,
-    // The popup's own role="listbox" is the exposed semantics; the trigger
-    // keeps DOM focus, so wrapping it in a modal dialog would misrepresent it.
-    role: 'none',
-    // The theme target belongs on the SURFACE that paints the popup, which
-    // `usePopover` owns — not on the scrolling list inside it.
-    surfaceTarget: 'multi-selector-popup',
+    triggerRef,
+    popoverOptions: {
+      hasLightDismiss: true,
+      hasCloseButton: false,
+      hasAutoFocus: false,
+      // The popup's own role="listbox" is the exposed semantics; the trigger
+      // keeps DOM focus, so wrapping it in a modal dialog would misrepresent it.
+      role: 'none',
+      // The theme target belongs on the SURFACE that paints the popup, which
+      // `usePopover` owns — not on the scrolling list inside it.
+      surfaceTarget: 'multi-selector-popup',
+    },
   });
+  const {popover} = surface;
   const keepOpenProps = useKeepLayerOpenProps(popover.id, popover.isOpen);
 
   // Open dropdown on mount when isDefaultOpen is true
   useEffect(() => {
     if (isDefaultOpen) {
-      popover.show();
+      surface.show();
     }
     // eslint-disable-next-line @eslint-react/exhaustive-deps -- mount-only: isDefaultOpen is not reactive
   }, []);
@@ -999,7 +1022,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
   const announcedEmptyRef = useRef<string | null>(null);
   useEffect(() => {
     const isPanelEmpty =
-      popover.isOpen &&
+      surface.isOpen &&
       !isLoading &&
       searchQuery === '' &&
       selectableItems.length === 0;
@@ -1013,7 +1036,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
     announcedEmptyRef.current = emptyAnnouncement;
     announce(emptyAnnouncement);
   }, [
-    popover.isOpen,
+    surface.isOpen,
     isLoading,
     searchQuery,
     selectableItems.length,
@@ -1158,24 +1181,24 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
     onKeyDown,
     onItemMouseEnter,
   } = useMultiCombobox({
-    wasJustDismissed: popover.wasJustDismissed,
+    wasJustDismissed: surface.wasJustDismissed,
     selectableItems: sortedItems,
     isDisabled,
-    isOpen: popover.isOpen,
+    isOpen: surface.isOpen,
     hasSearch,
     onOpen: useCallback(() => {
       // Snapshot which items are selected at open time — sort is frozen until close
       setSelectedAtOpen(new Set(optimisticValue));
 
-      popover.show();
+      surface.show();
       if (hasSearch) {
         // Focus search after popover opens
         requestAnimationFrame(() => {
           searchRef.current?.focus();
         });
       }
-    }, [popover, hasSearch, optimisticValue]),
-    onClose: popover.hide,
+    }, [surface, hasSearch, optimisticValue]),
+    onClose: surface.hide,
     onToggle: handleNavigableToggle,
     onClear: hasClear ? clearValues : undefined,
     hasValue,
@@ -1187,13 +1210,13 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
   // cursor walks off-screen once navigation passes the visible window. Mirrors
   // CommandPaletteItem's scrollIntoView({block: 'nearest'}) behavior.
   useEffect(() => {
-    if (!popover.isOpen || highlightedIndex < 0) {
+    if (!surface.isOpen || highlightedIndex < 0) {
       return;
     }
     document
       .getElementById(getItemId(highlightedIndex))
       ?.scrollIntoView?.({block: 'nearest'});
-  }, [popover.isOpen, highlightedIndex, getItemId]);
+  }, [surface.isOpen, highlightedIndex, getItemId]);
 
   // Build trigger display content
   const selectedItems = useMemo(() => {
@@ -1288,11 +1311,11 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
         // not the trigger — must be the combobox reporting the highlighted
         // option via aria-activedescendant (comboboxes-4).
         role="combobox"
-        aria-expanded={popover.isOpen}
+        aria-expanded={surface.isOpen}
         aria-controls={listboxId}
         aria-autocomplete="list"
         aria-activedescendant={
-          popover.isOpen && highlightedIndex >= 0
+          surface.isOpen && highlightedIndex >= 0
             ? getItemId(highlightedIndex)
             : undefined
         }
@@ -1355,7 +1378,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
     searchPlaceholder,
     handleSearchChange,
     onKeyDown,
-    popover.isOpen,
+    surface.isOpen,
     highlightedIndex,
     getItemId,
     t,
@@ -1608,6 +1631,64 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
   const showStatusTooltip =
     status != null && effectiveStatusVariant === 'tooltip' && !!status.message;
 
+  const panelContent = hasSearch ? (
+    <div>
+      {renderSearch()}
+      <Divider />
+      <div {...stylex.props(styles.dropdown)}>
+        <div
+          ref={listboxRef}
+          id={listboxId}
+          role="listbox"
+          aria-multiselectable="true"
+          aria-labelledby={triggerId}
+          {...stylex.props(styles.listbox)}>
+          {renderOptions()}
+        </div>
+      </div>
+    </div>
+  ) : (
+    <div {...stylex.props(styles.dropdown)}>
+      <div
+        ref={listboxRef}
+        id={listboxId}
+        role="listbox"
+        aria-multiselectable="true"
+        aria-labelledby={triggerId}
+        aria-activedescendant={
+          surface.isOpen && highlightedIndex >= 0
+            ? getItemId(highlightedIndex)
+            : undefined
+        }
+        tabIndex={surface.activePresentation === 'bottom-sheet' ? 0 : undefined}
+        onKeyDown={
+          surface.activePresentation === 'bottom-sheet' ? onKeyDown : undefined
+        }
+        {...stylex.props(styles.listbox)}>
+        {renderOptions()}
+      </div>
+    </div>
+  );
+
+  const selectionSurface =
+    surface.activePresentation === 'bottom-sheet' ? (
+      <SelectorBottomSheet
+        isOpen={surface.isSheetOpen}
+        onOpenChange={surface.onSheetOpenChange}
+        finalFocusRef={triggerRef}
+        initialFocusRef={hasSearch ? searchRef : listboxRef}
+        label={label}>
+        {panelContent}
+      </SelectorBottomSheet>
+    ) : (
+      popover.render(panelContent, {
+        placement: 'below',
+        alignment: 'start',
+        offset: spacingVars['--spacing-1'],
+        xstyle: styles.popover,
+      })
+    );
+
   const multiSelectorContent = (
     <>
       <div
@@ -1634,6 +1715,8 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
             variant === 'ghost' && styles.triggerGhost,
             variant === 'ghost' && interactionOverlayStyles.backgroundImage,
             variant === 'ghost' && focusOutlineStyles.focusWithin,
+            surface.isTriggerFocusRingSuppressed &&
+              selectorPresentationStyles.pointerRestoredFocus,
             isDisabled && inputWrapperStyles.disabled,
             variant === 'ghost' && isDisabled && styles.triggerGhostDisabled,
             optimisticValue.length === 0 && styles.triggerPlaceholder,
@@ -1663,11 +1746,13 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
           // focus + aria-activedescendant, comboboxes-4), so the trigger is a
           // plain button that opens the listbox — not a second combobox.
           role={hasSearch ? undefined : 'combobox'}
-          aria-haspopup="listbox"
-          aria-expanded={popover.isOpen}
+          aria-haspopup={
+            surface.activePresentation === 'bottom-sheet' ? 'dialog' : 'listbox'
+          }
+          aria-expanded={surface.isOpen}
           aria-controls={listboxId}
           aria-activedescendant={
-            !hasSearch && popover.isOpen && highlightedIndex >= 0
+            !hasSearch && surface.isOpen && highlightedIndex >= 0
               ? getItemId(highlightedIndex)
               : undefined
           }
@@ -1682,6 +1767,10 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
           disabled={isDisabled && !showsDisabledMessage}
           aria-disabled={showsDisabledMessage ? 'true' : undefined}
           onKeyDown={onKeyDown}
+          onFocus={event => {
+            onFocus?.(event);
+            surface.onTriggerFocus(event);
+          }}
           tabIndex={isDisabled && !showsDisabledMessage ? -1 : 0}
           {...stylex.props(styles.trigger)}>
           <span {...stylex.props(styles.triggerContent)}>
@@ -1754,7 +1843,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
             xstyle={[
               styles.triggerIcon,
               styles.triggerIconRotation,
-              popover.isOpen && styles.triggerIconOpen,
+              surface.isOpen && styles.triggerIconOpen,
             ]}
             // Stable theme target on the chevron glyph itself, so a theme can
             // restyle just this icon (color, size, hover) — and its
@@ -1762,54 +1851,13 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
             // @layer astryx-theme win over the icon's own base color/size,
             // which a button-level target could not reach.
             {...themeProps('multi-selector-indicator-icon', {
-              state: popover.isOpen ? 'expanded' : 'collapsed',
+              state: surface.isOpen ? 'expanded' : 'collapsed',
             })}
           />
         )}
       </div>
 
-      {popover.render(
-        hasSearch ? (
-          // With a search row the panel splits: the header stays put while the
-          // options scroll under it, so the field does not slide out of reach
-          // in a long list. Without one the panel is a single scroll container,
-          // exactly as before.
-          <div>
-            {renderSearch()}
-            {/*
-              Separates the header from the options and spans the panel: the
-              search row and the option list each hold their own inline
-              padding, the line does not, so it reads as the panel's own edge.
-            */}
-            <Divider />
-            <div {...stylex.props(styles.dropdown)}>
-              <div
-                id={listboxId}
-                role="listbox"
-                aria-multiselectable="true"
-                aria-labelledby={triggerId}>
-                {renderOptions()}
-              </div>
-            </div>
-          </div>
-        ) : (
-          <div {...stylex.props(styles.dropdown)}>
-            <div
-              id={listboxId}
-              role="listbox"
-              aria-multiselectable="true"
-              aria-labelledby={triggerId}>
-              {renderOptions()}
-            </div>
-          </div>
-        ),
-        {
-          placement: 'below',
-          alignment: 'start',
-          offset: spacingVars['--spacing-1'],
-          xstyle: styles.popover,
-        },
-      )}
+      {selectionSurface}
 
       {showStatusTooltip && statusTooltip.renderTooltip(status?.message ?? '')}
 

package/src/MultiSelector/index.ts

@@ -11,6 +11,7 @@
 export {
   MultiSelector,
   type MultiSelectorProps,
+  type MultiSelectorPresentation,
   type MultiSelectorSize,
   type MultiSelectorStatusType,
   type MultiSelectorSelectedItem,

package/src/NavIcon/NavIcon.doc.mjs

@@ -1,5 +1,19 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
+/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */
+const anatomy = [
+  {
+    name: 'Container',
+    required: true,
+    description: 'Circular painted container for the supplied icon.',
+  },
+  {
+    name: 'Icon',
+    required: true,
+    description: 'Caller-supplied visual content rendered inside the container.',
+  },
+];
+
 /** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
@@ -29,6 +43,7 @@ export const docs = {
     ],
   },
   usage: {
+    anatomy,
     description:
       'NavIcon is a circular icon container with an accent-colored background. Use it in navigation headers such as TopNavHeading and PageNavHeader to visually identify a section or application.',
     bestPractices: [
@@ -61,6 +76,7 @@ export const docsZh = {
     ],
   },
   usage: {
+    anatomy,
     description:
       'NavIcon is a circular icon container with an accent-colored background. Use it in navigation headers such as TopNavHeading and PageNavHeader to visually identify a section or application.',
     bestPractices: [
@@ -76,6 +92,7 @@ export const docsDense = {
   description:
     'Circular icon container w/ accent background for navigation headers.',
   usage: {
+    anatomy,
     description:
       'NavIcon is a circular icon container with an accent-colored background. Use it in navigation headers such as TopNavHeading and PageNavHeader to visually identify a section or application.',
     bestPractices: [

package/src/NavIcon/NavIcon.spec.md

@@ -0,0 +1,133 @@
+---
+schema_version: 1
+template_version: 3
+kind: component
+id: component:NavIcon
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+owners: [cixzhang]
+review_triggers: [theming]
+verified_by:
+  [packages/core/src/NavIcon/NavIcon.test.tsx, scripts/check-knowledge.mjs]
+families: []
+design_specs: []
+architecture:
+  [architecture:component-theming-surface, architecture:public-component-api]
+contributing: []
+system_specs: []
+---
+
+# NavIcon component contract
+
+## Intent
+
+NavIcon renders caller-supplied icon content inside a circular navigation
+container. This draft records the current consumer anatomy and theming ownership
+without changing runtime behavior or target compatibility.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`
+- Compatibility class: additive documentation only; runtime, DOM, styling,
+  targets, aliases, and public API remain unchanged
+- Controlled/uncontrolled behavior: not applicable
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- The circular container and its current `nav-icon` theming target.
+
+**Does not own / non-goals**
+
+- The artwork or component supplied through `icon` — owned by the caller.
+- Interaction semantics — NavIcon remains a display-only container.
+
+## Public concepts
+
+No new public concept is introduced. Consumer props and usage remain documented
+in `NavIcon.doc.mjs`.
+
+## Behavioral and layout contract
+
+| ID  | Candidate invariant                                                                              | Basis                           | Draft review state                                 |
+| --- | ------------------------------------------------------------------------------------------------ | ------------------------------- | -------------------------------------------------- |
+| FR1 | The current render contains a circular container and the caller-supplied icon content.           | Current source, docs, and tests | Verified current behavior; no new behavior decided |
+| FR2 | The container carries `nav-icon`; the deprecated `navicon` alias remains compatibility metadata. | Current source, docs, and tests | Verified current behavior; no target change        |
+
+### Allowed variation
+
+- Caller-supplied icon artwork and implementation may vary without becoming
+  NavIcon-owned anatomy.
+
+### Representative states
+
+- The documented anatomy is the same for every caller-supplied icon.
+
+### Transformation and precedence order
+
+- No new ordering rule is introduced.
+
+### Performance and resources
+
+- No new performance or resource rule is introduced.
+
+## Accessibility contract
+
+This draft does not change or extend NavIcon's existing accessibility behavior.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                             | Representation authority       | Hierarchy role    | Component contract |
+| ---------------- | ---------------------------------------------- | ------------------------------ | ----------------- | ------------------ |
+| Container        | Presents the current circular painted surface. | Current source and public docs | Supporting        | FR1, FR2           |
+| Icon             | Presents caller-supplied visual content.       | Caller-supplied content        | Context-dependent | FR1                |
+
+The deprecated `navicon` alias is compatibility metadata, not a separate anatomy
+part or current target.
+
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+  "Container": {"target": "nav-icon"},
+  "Icon": {"inherits": "nav-icon"}
+}
+```
+
+## Family and system relationships
+
+This draft references the current shared owners without restating their rules:
+`architecture:component-theming-surface` and
+`architecture:public-component-api`. The deprecated `navicon` alias remains
+compatibility metadata rather than separate anatomy.
+
+## Verification map
+
+| Contract            | Verification                         | Representative states                 | Mutation or failure expectation                                                       | Audit section           |
+| ------------------- | ------------------------------------ | ------------------------------------- | ------------------------------------------------------------------------------------- | ----------------------- |
+| FR1                 | `NavIcon.test.tsx` content suite     | Caller-supplied icon                  | Removing the container or supplied content fails existing render and ref assertions.  | `audit:NavIcon/anatomy` |
+| FR2                 | `NavIcon.test.tsx` target-name suite | Current and deprecated target classes | Removing either emitted compatibility class fails the existing target assertion.      | `audit:NavIcon/theming` |
+| Theming anatomy map | `scripts/check-knowledge.mjs`        | Canonical anatomy and current target  | Missing, extra, prefixed, stale, or alias-backed mappings fail repository validation. | `audit:NavIcon/theming` |
+
+## Decision log
+
+None. This draft records current facts and introduces no component-local design
+decision.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables, examples, implementation
+steps, or system rules. It links to their owners.