@astryxdesign/core 0.1.9 → 0.2.0-canary.0b7a99e

package/src/MultiSelector/MultiSelector.tsx

@@ -13,7 +13,7 @@
  * - /packages/core/src/MultiSelector/MultiSelector.test.tsx
  * - /packages/core/src/MultiSelector/index.ts
  * - /apps/storybook/stories/InputGroup.stories.tsx
- * - /packages/cli/templates/blocks/components/MultiSelector/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/MultiSelector/ (showcase blocks)
  */
 
 import React, {
@@ -37,6 +37,7 @@ import {
   inputStatusBorderStyles,
   inputStatusHoverShadowStyles,
   inputWrapperStyles,
+  type FieldStatusVariant,
 } from '../Field';
 import {Divider} from '../Divider';
 import {Spinner} from '../Spinner';
@@ -118,11 +119,12 @@ const styles = stylex.create({
     lineHeight: 'inherit',
     color: 'inherit',
     cursor: 'pointer',
-    outline: {
-      default: 'none',
-      ':focus-visible': `${borderVars['--border-width']} solid ${colorVars['--color-accent']}`,
-    },
-    outlineOffset: '0',
+    // The wrapper (inputWrapperStyles.base) renders the focus ring via
+    // :focus-within when this button is focused, matching
+    // TextInput/NumberInput/Selector. The button must not draw its own
+    // :focus-visible outline or the two stack into a doubled ring over the
+    // trigger.
+    outline: 'none',
     borderRadius: radiusVars['--radius-element'],
   },
   triggerPlaceholder: {
@@ -479,6 +481,13 @@ export interface MultiSelectorProps<
    * Status indicator for the selector.
    */
   status?: MultiSelectorStatus;
+  /**
+   * How the status message is placed relative to the input.
+   * - 'attached': message overlaps directly below the input (bordered treatment)
+   * - 'detached': message floats below as a separate element with spacing
+   * @default 'attached'
+   */
+  statusVariant?: FieldStatusVariant;
 
   /**
    * Width of the field. Numbers are treated as pixels, strings are used as-is
@@ -562,6 +571,21 @@ export interface MultiSelectorProps<
   'data-testid'?: string;
 }
 
+// Case-insensitive substring match for a single option. The one predicate used
+// by both the flat filter (count + keyboard nav) and the grouped renderer, so
+// what is shown while searching stays in lockstep with the announced count.
+function optionMatchesQuery(
+  option: MultiSelectorOptionData,
+  query: string,
+): boolean {
+  if (!query) {
+    return true;
+  }
+  return (option.label ?? option.value)
+    .toLowerCase()
+    .includes(query.toLowerCase());
+}
+
 // Case-insensitive substring filter over the selectable options. Shared by the
 // `filteredItems` memo (rendering) and the search-change handler, which needs
 // the count for the *next* query synchronously to announce it exactly once per
@@ -573,10 +597,7 @@ function filterOptionsByQuery(
   if (!query) {
     return items;
   }
-  const q = query.toLowerCase();
-  return items.filter(item =>
-    (item.label ?? item.value).toLowerCase().includes(q),
-  );
+  return items.filter(item => optionMatchesQuery(item, query));
 }
 
 /**
@@ -610,6 +631,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
   placeholder: placeholderFromProps,
   size: sizeProp,
   status,
+  statusVariant = 'attached',
   labelTooltip,
   startIcon,
   hasClear = false,
@@ -716,35 +738,25 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
 
   // Single source of truth for item order. Both the hook (keyboard navigation)
   // and renderOptions (DOM rendering) consume this list — no independent sorting.
-  // Selected-at-open items are placed first within each group/section.
+  // Selected-at-open items are placed first within each group/section, and the
+  // same walk applies while searching so group structure survives filtering
+  // (only matching items are kept; the query is empty in non-search mode).
   const sortedItems = useMemo(() => {
     const selectedSet = selectedAtOpen ?? new Set<string>();
-    if (searchQuery) {
-      const selected = filteredItems.filter(item =>
-        selectedSet.has(item.value),
-      );
-      const unselected = filteredItems.filter(
-        item => !selectedSet.has(item.value),
-      );
-      const items = [...selected, ...unselected];
-      if (hasSelectAll) {
-        return [{value: SELECT_ALL_VALUE, label: selectAllLabel}, ...items];
-      }
-      return items;
-    }
-    // For non-search mode, flatten options in the same order as renderOptions
     const result: MultiSelectorOptionData[] = [];
     let pendingFlat: MultiSelectorOptionData[] = [];
 
+    const orderSelectedFirst = (items: MultiSelectorOptionData[]) => {
+      const selected = items.filter(item => selectedSet.has(item.value));
+      const unselected = items.filter(item => !selectedSet.has(item.value));
+      return [...selected, ...unselected];
+    };
+
     const flushFlat = () => {
       if (pendingFlat.length === 0) {
         return;
       }
-      const selected = pendingFlat.filter(item => selectedSet.has(item.value));
-      const unselected = pendingFlat.filter(
-        item => !selectedSet.has(item.value),
-      );
-      result.push(...selected, ...unselected);
+      result.push(...orderSelectedFirst(pendingFlat));
       pendingFlat = [];
     };
 
@@ -753,16 +765,15 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
         flushFlat();
       } else if (isSection(option)) {
         flushFlat();
-        const sectionOptions = option.options.map(opt => normalizeOption(opt));
-        const selected = sectionOptions.filter(item =>
-          selectedSet.has(item.value),
-        );
-        const unselected = sectionOptions.filter(
-          item => !selectedSet.has(item.value),
-        );
-        result.push(...selected, ...unselected);
+        const sectionOptions = option.options
+          .map(opt => normalizeOption(opt))
+          .filter(opt => optionMatchesQuery(opt, searchQuery));
+        result.push(...orderSelectedFirst(sectionOptions));
       } else if (isOptionData(option)) {
-        pendingFlat.push(normalizeOption(option));
+        const normalized = normalizeOption(option);
+        if (optionMatchesQuery(normalized, searchQuery)) {
+          pendingFlat.push(normalized);
+        }
       }
     }
     flushFlat();
@@ -771,14 +782,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
       return [{value: SELECT_ALL_VALUE, label: selectAllLabel}, ...result];
     }
     return result;
-  }, [
-    filteredItems,
-    searchQuery,
-    options,
-    selectedAtOpen,
-    hasSelectAll,
-    selectAllLabel,
-  ]);
+  }, [searchQuery, options, selectedAtOpen, hasSelectAll, selectAllLabel]);
 
   // Layer for dropdown positioning
   const handleLayerHide = useCallback(() => {
@@ -1126,6 +1130,11 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
         ? allEnabledSelected
         : optimisticValue.includes(item.value);
       const checkboxValue = isSelectAll ? selectAllState : isSelected;
+      // aria-selected="mixed" is invalid on role="option", and the tri-state
+      // checkbox is inert/decorative, so the indeterminate state must be
+      // conveyed through the option's accessible name (WCAG 4.1.2).
+      const isPartiallySelected =
+        isSelectAll && selectAllState === 'indeterminate';
 
       return (
         <div
@@ -1133,6 +1142,13 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
           id={getItemId(flatIndex)}
           role="option"
           aria-selected={isSelected}
+          aria-label={
+            isPartiallySelected
+              ? t('@astryx.multiSelector.selectAllPartiallySelected', {
+                  label: selectAllLabel,
+                })
+              : undefined
+          }
           aria-disabled={item.disabled}
           onClick={() => {
             if (!item.disabled) {
@@ -1177,10 +1193,12 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
       optimisticValue,
       allEnabledSelected,
       selectAllState,
+      selectAllLabel,
       getItemId,
       handleNavigableToggle,
       onItemMouseEnter,
       size,
+      t,
     ],
   );
 
@@ -1208,25 +1226,28 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
       cursor = 1;
     }
 
-    // Empty state — no real items to show
+    // Empty state — no real items to show. role="presentation" keeps the
+    // message out of the listbox's accessibility tree (role="listbox" only
+    // permits option/group children); the no-results outcome is announced
+    // via the result-count live region instead.
     if (realItemCount === 0) {
       elements.push(
-        <div key="empty" {...stylex.props(styles.emptyState)}>
+        <div
+          key="empty"
+          role="presentation"
+          {...stylex.props(styles.emptyState)}>
           No results found
         </div>,
       );
       return elements;
     }
 
-    if (searchQuery) {
-      for (let i = cursor; i < sortedItems.length; i++) {
-        elements.push(renderItem(sortedItems[i], i));
-      }
-      return elements;
-    }
-
-    // Non-search: consume items from sortedItems in order, interleaving
-    // structural elements (dividers, section headers) from the options prop.
+    // Consume items from sortedItems in order, interleaving structural elements
+    // (dividers, section headers) from the options prop. While searching, only
+    // matching items are present in sortedItems, so a section consumes just its
+    // matches and is skipped entirely when none match — no header left standing
+    // over nothing, and the cursor stays aligned with the combobox indices.
+    const isSearching = Boolean(searchQuery);
     let pendingCount = 0;
 
     const flushPending = () => {
@@ -1242,12 +1263,25 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
 
       if (isDivider(option)) {
         flushPending();
-        elements.push(<Divider key={`divider-${i}`} xstyle={styles.divider} />);
+        // A standalone divider between groups would orphan itself once its
+        // neighbors are filtered out, so skip it while searching.
+        if (!isSearching) {
+          elements.push(
+            <Divider key={`divider-${i}`} xstyle={styles.divider} />,
+          );
+        }
       } else if (isSection(option)) {
         flushPending();
-        const count = option.options.length;
+        const matchCount = isSearching
+          ? option.options.filter(opt =>
+              optionMatchesQuery(normalizeOption(opt), searchQuery),
+            ).length
+          : option.options.length;
+        if (matchCount === 0) {
+          continue;
+        }
         const sectionItems: ReactNode[] = [];
-        for (let j = 0; j < count; j++) {
+        for (let j = 0; j < matchCount; j++) {
           sectionItems.push(renderItem(sortedItems[cursor], cursor));
           cursor++;
         }
@@ -1266,7 +1300,12 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
           </div>,
         );
       } else if (isOptionData(option)) {
-        pendingCount++;
+        if (
+          !isSearching ||
+          optionMatchesQuery(normalizeOption(option), searchQuery)
+        ) {
+          pendingCount++;
+        }
       }
     }
     flushPending();
@@ -1274,6 +1313,10 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
     return elements;
   }, [options, renderItem, sortedItems, searchQuery, hasSelectAll]);
 
+  // The detached message box renders its own leading status icon, so the
+  // on-field icon would duplicate it — keep the chevron indicator instead.
+  const showStatusIcon = status != null && statusVariant !== 'detached';
+
   const multiSelectorContent = (
     <>
       <div
@@ -1295,7 +1338,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
             isDisabled && inputWrapperStyles.disabled,
             optimisticValue.length === 0 && styles.triggerPlaceholder,
             status && inputStatusBorderStyles[status.type],
-            status && inputStatusHoverShadowStyles[status.type],
+            status && !isDisabled && inputStatusHoverShadowStyles[status.type],
             inputGroup && groupStyles.inGroup,
             xstyle,
           ),
@@ -1359,23 +1402,45 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
             onClick={handleClear}
             aria-label={t('@astryx.multiSelector.clearAll', {label})}
             {...stylex.props(styles.clearButton)}>
-            <Icon icon="close" size="sm" color="secondary" />
+            <Icon
+              icon="close"
+              size="sm"
+              color="secondary"
+              // Stable theme target on the clear glyph itself, so a theme can
+              // restyle just this icon (color, size, hover) via `defineTheme`.
+              // Same-element rules in @layer astryx-theme win over the icon's
+              // own base color/size, which a button-level target could not
+              // reach.
+              {...themeProps('multi-selector-clear-icon')}
+            />
           </button>
         )}
         <span
           {...stylex.props(
             styles.triggerIcon,
-            !status && popover.isOpen && styles.triggerIconOpen,
-            status && styles.triggerIconStatus,
+            !showStatusIcon && popover.isOpen && styles.triggerIconOpen,
+            showStatusIcon && styles.triggerIconStatus,
           )}>
-          {status ? (
+          {showStatusIcon ? (
             <Icon
               icon={STATUS_ICON_MAP[status.type]}
               size="sm"
               color={STATUS_ICON_COLOR_MAP[status.type]}
             />
           ) : (
-            <Icon icon="chevronDown" size="sm" color="inherit" />
+            <Icon
+              icon="chevronDown"
+              size="sm"
+              color="inherit"
+              // Stable theme target on the chevron glyph itself, so a theme can
+              // restyle just this icon (color, size, hover) — and its
+              // open/closed state — via `defineTheme`. Same-element rules in
+              // @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',
+              })}
+            />
           )}
         </span>
       </div>
@@ -1426,6 +1491,7 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
             }
           : undefined
       }
+      statusVariant={statusVariant}
       labelTooltip={labelTooltip}
       width={width}>
       {multiSelectorContent}

package/src/NavIcon/NavIcon.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'NavIcon',
@@ -36,7 +36,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docsZh = {
   name: 'NavIcon',
   displayName: 'Nav Icon',
@@ -65,7 +65,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description:
     'Circular icon container w/ accent background for navigation headers.',

package/src/NavIcon/NavIcon.tsx

@@ -11,7 +11,7 @@
  * - /packages/core/src/NavIcon/NavIcon.test.tsx
  * - /packages/core/src/NavIcon/index.ts
  * - /apps/storybook/stories/TopNav.stories.tsx
- * - /packages/cli/templates/blocks/components/NavIcon/NavIconShowcase.tsx
+ * - /packages/cli/assets/templates/blocks/components/NavIcon/NavIconShowcase.tsx
  */
 
 import type {ReactNode} from 'react';

package/src/NavMenu/NavHeadingMenuItem.tsx

@@ -49,7 +49,7 @@ const styles = stylex.create({
     },
     border: 'none',
     cursor: 'pointer',
-    textAlign: 'left',
+    textAlign: 'start',
     outline: 'none',
     textDecoration: 'none',
   },

package/src/NavMenu/NavMenu.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'NavHeadingMenu',
@@ -40,7 +40,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description: 'Accessible menu container + items for nav heading popovers. NavHeadingMenu = role="menu" w/ keyboard nav; NavHeadingMenuItem renders selectable items.',
   usage: {

package/src/NumberInput/NumberInput.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'NumberInput',
@@ -94,6 +94,13 @@ export const docs = {
       type: "{type: 'error' | 'warning' | 'success', message?: string}",
       description: 'Validation status with optional message.',
     },
+    {
+      name: 'statusVariant',
+      type: "'attached' | 'detached' | 'tooltip'",
+      description:
+        'How the status message is placed relative to the input. attached overlaps directly below the input (bordered treatment); detached floats below as a separate element with spacing; tooltip hides the message box and surfaces it in a tooltip on the status icon.',
+      default: "'attached'",
+    },
     {
       name: 'min',
       type: 'number | null',
@@ -138,6 +145,12 @@ export const docs = {
       type: 'string',
       description: 'HTML autocomplete attribute.',
     },
+    {
+      name: 'width',
+      type: 'SizeValue',
+      description:
+        'Width of the field (number = pixels, string used as-is, e.g. "100%"). Sizes the whole field (label, control, and status) so they stay aligned.',
+    },
     {
       name: 'hasAutoFocus',
       type: 'boolean',
@@ -184,7 +197,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docsZh = {
   name: 'NumberInput',
   displayName: 'Number Input',
@@ -275,6 +288,13 @@ export const docsZh = {
       type: "{type: 'error' | 'warning' | 'success', message?: string}",
       description: '带可选消息的验证状态。',
     },
+    {
+      name: 'statusVariant',
+      type: "'attached' | 'detached' | 'tooltip'",
+      description:
+        '状态消息相对于输入框的放置方式。attached 直接叠加在输入框下方（带边框处理）；detached 作为独立元素浮于下方并留有间距；tooltip 隐藏消息框，并在状态图标上以提示气泡形式显示。',
+      default: "'attached'",
+    },
     {
       name: 'min',
       type: 'number | null',
@@ -364,7 +384,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description: 'Number input component for collecting numeric user input w/ validation.',
   usage: {
@@ -402,6 +422,7 @@ export const docsDense = {
     startIcon: 'Icon at input start.',
     labelIcon: 'Icon before label text.',
     status: 'Validation status w/ optional message.',
+    statusVariant: 'How status message is placed: attached overlaps below input; detached floats below w/ spacing; tooltip hides the box and shows it on the status icon.',
     min: 'Minimum value allowed.',
     max: 'Maximum value allowed.',
     step: 'Step increment.',

package/src/NumberInput/NumberInput.test.tsx

@@ -13,6 +13,7 @@ import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
 import {render, screen, fireEvent, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {TestIcon} from '../__tests__/TestIcon';
+import {InputGroup} from '../InputGroup';
 import {NumberInput} from './NumberInput';
 import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
 
@@ -336,6 +337,33 @@ describe('NumberInput', () => {
       expect(screen.queryByText('%')).not.toBeInTheDocument();
       expect(screen.queryByText('GB')).not.toBeInTheDocument();
     });
+
+    it('includes the units text in the accessible description (WCAG 1.3.1)', () => {
+      render(
+        <NumberInput
+          label="Storage"
+          value={50}
+          onChange={() => {}}
+          units="GB"
+        />,
+      );
+      expect(screen.getByRole('spinbutton')).toHaveAccessibleDescription(/GB/);
+    });
+
+    it('combines units with the description in the accessible description', () => {
+      render(
+        <NumberInput
+          label="Discount"
+          value={10}
+          onChange={() => {}}
+          description="Applied at checkout"
+          units="%"
+        />,
+      );
+      const input = screen.getByRole('spinbutton');
+      expect(input).toHaveAccessibleDescription(/Applied at checkout/);
+      expect(input).toHaveAccessibleDescription(/%/);
+    });
   });
 
   describe('event callbacks', () => {
@@ -463,6 +491,26 @@ describe('NumberInput', () => {
       expect(screen.getByText('Value must be positive')).toBeInTheDocument();
     });
 
+    it('has no dangling aria-describedby ids inside InputGroup (WCAG 1.3.1)', () => {
+      // Inside an InputGroup no Field renders, so the status message element
+      // does not exist; aria-describedby must not reference its id.
+      render(
+        <InputGroup label="Price">
+          <NumberInput
+            label="Amount"
+            value={null}
+            onChange={() => {}}
+            status={{type: 'error', message: 'Value must be positive'}}
+          />
+        </InputGroup>,
+      );
+      const input = screen.getByRole('spinbutton');
+      const describedBy = input.getAttribute('aria-describedby') ?? '';
+      for (const idToken of describedBy.split(/\s+/).filter(Boolean)) {
+        expect(document.getElementById(idToken)).not.toBeNull();
+      }
+    });
+
     it('does not render status message when not provided', () => {
       render(
         <NumberInput
@@ -916,3 +964,26 @@ describe('keyboard clearing with hasClear (#3599)', () => {
     expect((input as HTMLInputElement).value).toBe('42');
   });
 });
+
+
+describe('NumberInput statusVariant forwarding', () => {
+  it('defaults to attached (status renders with data-variant="attached")', () => {
+    const {container} = render(
+      <NumberInput label="Amount" value={null} onChange={() => {}} status={{type: 'error', message: 'Must be positive'}} />,
+    );
+    expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
+      'data-variant',
+      'attached',
+    );
+  });
+
+  it('forwards statusVariant="detached" to the underlying Field status', () => {
+    const {container} = render(
+      <NumberInput label="Amount" value={null} onChange={() => {}} status={{type: 'error', message: 'Must be positive'}} statusVariant="detached" />,
+    );
+    expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
+      'data-variant',
+      'detached',
+    );
+  });
+});