@astryxdesign/core 0.5.2-canary.c9c8564 → 0.5.2-canary.e4f8e4e

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/Popover/Popover.doc.mjs

@@ -64,7 +64,7 @@ export const docs = {
         {
           name: 'width',
           type: 'number | string',
-          description: 'Width of the popover container.',
+          description: 'Width of the popover container. The layer still caps to the viewport with alignment-aware safe-area gutters before scrolling long content.',
           default: "'auto'",
         },
         {
@@ -101,7 +101,7 @@ export const docs = {
         {
           name: 'hasAutoFocus',
           type: 'boolean',
-          description: 'Whether to auto-focus the first focusable element when the popover opens. Set to false for inline showcases or documentation previews.',
+          description: 'Whether to move focus into the popover when it opens. Keyboard activation focuses the first content control; pointer activation focuses the labeled dialog container so an action does not appear preselected. Set to false for inline showcases or documentation previews.',
           default: 'true',
         },
         {
@@ -149,8 +149,8 @@ export const docs = {
       { guidance: true, description: 'Keep popover content focused on a single task or piece of information.' },
       { guidance: true, description: 'Provide a clear way to close: either by clicking outside or with an explicit close button.' },
       { guidance: false, description: 'Nest popovers inside other popovers; it creates confusing focus and navigation.' },
-      { guidance: false, description: 'Use a popover for content that requires heavy user input; use a Dialog instead.' },
-      { guidance: false, description: 'Put too much content in a popover; if it needs scrolling, use a Dialog instead.' },
+      { guidance: false, description: 'Assume input complexity alone determines the presentation; evaluate the task’s focus, space, and interaction requirements.' },
+      { guidance: false, description: 'Assume scrolling alone means Popover is the wrong component; a bounded Popover may scroll while a focused anchored interaction remains appropriate.' },
     ],
     anatomy: [
       {name: 'Header', required: true, description: 'Contains the title, optional subheader, and close button.'},
@@ -220,7 +220,7 @@ export const docsZh = {
         {
           name: 'width',
           type: 'number | string',
-          description: '弹出框容器的宽度。',
+          description: '弹出框容器的宽度。弹出层仍会限制在视口和安全区域留白内，长内容再滚动。',
           default: "'auto'",
         },
         {
@@ -294,8 +294,8 @@ export const docsZh = {
       { guidance: true, description: 'Keep popover content focused on a single task or piece of information.' },
       { guidance: true, description: 'Provide a clear way to close: either by clicking outside or with an explicit close button.' },
       { guidance: false, description: 'Nest popovers inside other popovers; it creates confusing focus and navigation.' },
-      { guidance: false, description: 'Use a popover for content that requires heavy user input; use a Dialog instead.' },
-      { guidance: false, description: 'Put too much content in a popover; if it needs scrolling, use a Dialog instead.' },
+      { guidance: false, description: 'Assume input complexity alone determines the presentation; evaluate the task’s focus, space, and interaction requirements.' },
+      { guidance: false, description: 'Assume scrolling alone means Popover is the wrong component; a bounded Popover may scroll while a focused anchored interaction remains appropriate.' },
     ],
     anatomy: [
       {name: 'Header', required: true, description: 'Contains the title, optional subheader, and close button.'},
@@ -316,8 +316,8 @@ export const docsDense = {
       { guidance: true, description: 'Keep popover content focused on a single task or piece of information.' },
       { guidance: true, description: 'Provide a clear way to close: either by clicking outside or with an explicit close button.' },
       { guidance: false, description: 'Nest popovers inside other popovers; it creates confusing focus and navigation.' },
-      { guidance: false, description: 'Use a popover for content that requires heavy user input; use a Dialog instead.' },
-      { guidance: false, description: 'Put too much content in a popover; if it needs scrolling, use a Dialog instead.' },
+      { guidance: false, description: 'Assume input complexity alone determines the presentation; evaluate the task’s focus, space, and interaction requirements.' },
+      { guidance: false, description: 'Assume scrolling alone means Popover is the wrong component; a bounded Popover may scroll while a focused anchored interaction remains appropriate.' },
     ],
     anatomy: [
       {name: 'Header', required: true, description: 'Contains the title, optional subheader, and close button.'},
@@ -340,11 +340,11 @@ export const docsDense = {
         isOpen: 'Whether popover shown in controlled mode.',
         onOpenChange: 'Callback fired when popover visibility changes.',
         isEnabled: 'When false, trigger interactions ignored.',
-        width: 'Popover container width.',
+        width: 'Popover container width; capped to alignment-aware viewport/safe-area gutters before long content scrolls.',
         label: 'Accessible label for popover dialog.',
         hasCloseButton: 'Whether to include hidden close button for accessibility.',
         closeButtonLabel: 'Label for hidden close button.',
-        hasAutoFocus: 'Auto-focus first element on open; false for showcases.',
+        hasAutoFocus: 'Move focus into the popover on open; keyboard targets the first control and pointer targets the dialog container.',
         hasLightDismiss: 'Outside click dismisses; false for explicit-dismiss surfaces (coachmarks).',
         hasEscapeDismiss: 'Escape dismisses; full effect only with hasLightDismiss=false.',
       },