@astryxdesign/core 0.2.0 → 0.3.0-canary.041a0ef

package/src/TreeList/TreeListItem.tsx

@@ -11,7 +11,7 @@
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/TreeList/TreeList.doc.mjs
  * - /packages/core/src/TreeList/TreeList.tsx
- * - /packages/cli/templates/blocks/components/TreeList/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/TreeList/ (showcase blocks)
  */
 
 import {useId, useMemo, type ReactNode} from 'react';
@@ -24,8 +24,9 @@ import {
   easeVars,
   typeScaleVars,
 } from '../theme/tokens.stylex';
-import {getIcon} from '../Icon/globalIconRegistry';
-import {mergeProps, rtlStyles} from '../utils';
+import {focusOutlineProps} from '../utils/focusOutline.stylex';
+import {Icon} from '../Icon';
+import {mergeProps} from '../utils';
 import {useLinkComponent} from '../Link/useLinkComponent';
 import {TreeListBranches} from './TreeListBranches';
 import type {TreeListDensity, TreeListVariant} from './TreeListTypes';
@@ -51,14 +52,6 @@ const styles = stylex.create({
     // redeclares these vars (default: 'none' / '0'), so a descendant row's
     // default shadows an ancestor's active value — the ring can never leak
     // past the nearest containing treeitem, however deep the tree nests.
-    '--_tree-focus-outline': {
-      default: 'none',
-      ':focus-visible': `2px solid ${colorVars['--color-accent']}`,
-    },
-    '--_tree-focus-outline-offset': {
-      default: '0',
-      ':focus-visible': '2px',
-    },
   },
   childGroup: {
     margin: 0,
@@ -70,6 +63,17 @@ const styles = stylex.create({
   },
   rowWrapper: {
     position: 'relative',
+    // Inter-row gap. Half the public `--tree-list-row-gap` lever sits above and
+    // half below the row box; because this is PADDING (not margin) it cannot
+    // collapse, so adjacent rows end up a full gap apart — and it rides the
+    // `rowWrapper`, which carries no theme target, so the paintable
+    // `tree-list-item` stays a pure paint seam (layout lives off it). The <li>s
+    // stay contiguous — the gap is padding INSIDE each <li>, not space between
+    // them — so the per-<li> connector guide can still span it and read as a
+    // continuous line (see TreeListBranches). The lever's default is a subtle
+    // `--spacing-0-5` (2px, set on the tree-list root); a theme widens or closes
+    // it via the `tree-list` target.
+    paddingBlock: 'calc(var(--tree-list-row-gap, 0px) / 2)',
   },
   contentWrapper: {
     borderRadius: radiusVars['--radius-element'],
@@ -77,7 +81,8 @@ const styles = stylex.create({
     alignItems: 'center',
     gap: spacingVars['--spacing-2'],
     paddingInline: spacingVars['--spacing-2'],
-    outline: 'none',
+    // No `outline: 'none'` here: this element receives the shared focus ring,
+    // which already defaults to none, and the shorthand would erase it.
     overflow: 'hidden',
     position: 'relative',
     boxSizing: 'border-box',
@@ -102,19 +107,6 @@ const styles = stylex.create({
       ':active': `linear-gradient(${colorVars['--color-overlay-pressed']}, ${colorVars['--color-overlay-pressed']})`,
     },
   },
-  focusVisibleOutline: {
-    outline: {
-      // Reads the row's own --_tree-focus-outline (published on the <li> in
-      // `wrapper`), which resolves to the nearest containing treeitem only.
-      default: 'var(--_tree-focus-outline, none)',
-      // Also support inner focusable actions.
-      ':has(:focus-visible)': `2px solid ${colorVars['--color-accent']}`,
-    },
-    outlineOffset: {
-      default: 'var(--_tree-focus-outline-offset, 0)',
-      ':has(:focus-visible)': '2px',
-    },
-  },
   disabled: {
     cursor: 'not-allowed',
     opacity: 0.5,
@@ -207,15 +199,34 @@ const styles = stylex.create({
   },
   chevronSvg: {
     display: 'flex',
+    // The chevron column is sized in spacing tokens by the button/container
+    // around it (--spacing-4 = 16px), not on Icon's rem scale, so the glyph's
+    // box is pinned to that same token. Icon's `sm` (1rem) only coincides with
+    // 16px at a 16px root font-size; drifting off the token would knock the
+    // glyph out of its 16px column.
+    width: spacingVars['--spacing-4'],
+    height: spacingVars['--spacing-4'],
+    fontSize: spacingVars['--spacing-4'],
     transitionProperty: 'transform',
     transitionDuration: durationVars['--duration-fast'],
     transitionTimingFunction: easeVars['--ease-standard'],
   },
+  // The RTL mirror is folded into each state's transform rather than living on
+  // a parent span. Both are `transform`, so on one element the later value
+  // would win — spelling out `scaleX(-1) rotate(...)` per state composes them
+  // exactly as the nested elements did, while leaving a single element to
+  // carry the glyph's theme target.
   chevronExpanded: {
-    transform: 'rotate(90deg)',
+    transform: {
+      default: 'rotate(90deg)',
+      ':is([dir="rtl"] *)': 'scaleX(-1) rotate(90deg)',
+    },
   },
   chevronCollapsed: {
-    transform: 'rotate(0deg)',
+    transform: {
+      default: 'rotate(0deg)',
+      ':is([dir="rtl"] *)': 'scaleX(-1) rotate(0deg)',
+    },
   },
 });
 
@@ -273,6 +284,16 @@ export interface TreeListItemInternalProps {
   isDisabled?: boolean;
   isSelected?: boolean;
   hasChildren: boolean;
+  /**
+   * Whether the tree contains at least one expandable item anywhere (i.e. a
+   * caret exists somewhere to align labels under). A leaf reserves the chevron
+   * column — the extra offset that lines its label up past an expandable
+   * ancestor/sibling's caret — whenever this is true, so it stays indented
+   * beyond its parent's label. Only a fully flat tree (no expandable items at
+   * all) has no caret to align under, so its rows sit flush (no chevron-column
+   * offset). Computed once for the whole tree by TreeList.
+   */
+  hasExpandableItems: boolean;
   nestedLevel: number;
   isLast: boolean;
   ancestorsIsLast: ReadonlyArray<boolean>;
@@ -315,6 +336,7 @@ export function TreeListItem({
   isDisabled = false,
   isSelected = false,
   hasChildren,
+  hasExpandableItems,
   nestedLevel,
   isLast,
   ancestorsIsLast,
@@ -366,15 +388,19 @@ export function TreeListItem({
 
   // Per-level indent distance. The per-level step is the public, themeable
   // `--tree-list-indent` lever (default `--spacing-4`, set on the tree-list
-  // root). Leaves add a fixed chevron-column offset (chevron width + gap) so
-  // their labels line up with sibling parents' labels; that offset is tied to
+  // root). A leaf adds a fixed chevron-column offset (chevron width + gap) so
+  // its label lines up past an expandable ancestor/sibling's caret — but ONLY
+  // when the tree actually contains an expandable item somewhere. In a fully
+  // flat tree there is no caret to align under, so the offset is pointless and
+  // every row sits flush, like a parent at that level. That offset is tied to
   // the chevron's own dimensions, not the indent step, so it does not scale
   // with the lever. Published as the private `--_tree-indent` and consumed by
   // `contentWrapper`'s stylesheet `margin-inline-start` (kept out of the inline
   // style so the theme layer can override it — see #4308).
-  const indentDistance = hasChildren
-    ? `calc(${nestedLevel} * var(--tree-list-indent))`
-    : `calc(${nestedLevel} * var(--tree-list-indent) + ${spacingVars['--spacing-4']} + ${spacingVars['--spacing-2']})`;
+  const reservesChevronColumn = !hasChildren && hasExpandableItems;
+  const indentDistance = reservesChevronColumn
+    ? `calc(${nestedLevel} * var(--tree-list-indent) + ${spacingVars['--spacing-4']} + ${spacingVars['--spacing-2']})`
+    : `calc(${nestedLevel} * var(--tree-list-indent))`;
   const indentStyle: IndentStyle = {'--_tree-indent': indentDistance};
 
   const labelAndDescription = (
@@ -405,16 +431,24 @@ export function TreeListItem({
     </>
   );
 
+  // <Icon> renders the glyph's span itself — carrying the pre-existing
+  // astryx-icon target — so the rotation rides on that same element instead of
+  // an extra wrapper: a theme can still restyle the mark and its open/closed
+  // transform through one selector.
   const chevronIcon = (
-    <span {...stylex.props(rtlStyles.mirror)}>
-      <span
-        {...stylex.props(
-          styles.chevronSvg,
-          isExpanded ? styles.chevronExpanded : styles.chevronCollapsed,
-        )}>
-        {getIcon('chevronRight')}
-      </span>
-    </span>
+    <Icon
+      icon="chevronRight"
+      // Nearest size to the 16px chevron column; `chevronSvg` re-pins the exact
+      // box because the column is spacing-token-sized, not rem-sized.
+      size="sm"
+      // The button/container owns the chevron color (--color-icon-secondary);
+      // inheriting keeps that as the single source.
+      color="inherit"
+      xstyle={[
+        styles.chevronSvg,
+        isExpanded ? styles.chevronExpanded : styles.chevronCollapsed,
+      ]}
+    />
   );
 
   const chevron = hasChildren ? (
@@ -520,7 +554,7 @@ export function TreeListItem({
       data-tree-id={id}
       data-tree-level={nestedLevel + 1}
       data-tree-disabled={isDisabled || undefined}
-      {...stylex.props(styles.wrapper)}>
+      {...focusOutlineProps.publishFocusVisibleVars(styles.wrapper)}>
       {variant !== 'noGuides' && (
         <div {...stylex.props(styles.treeBranches)}>
           <TreeListBranches
@@ -538,16 +572,20 @@ export function TreeListItem({
               selected: isSelected ? 'selected' : null,
               disabled: isDisabled ? 'disabled' : null,
             }),
-            stylex.props(
-              styles.contentWrapper,
-              densityStyles[density],
-              (isInteractive || (hasChildren && onClick == null)) &&
-                styles.interactive,
-              (isInteractive || (hasChildren && onClick == null)) &&
-                styles.focusVisibleOutline,
-              isDisabled && styles.disabled,
-              isSelected && styles.selected,
-            ),
+            isInteractive || (hasChildren && onClick == null)
+              ? focusOutlineProps.focusWithinOrPublished(
+                  styles.contentWrapper,
+                  densityStyles[density],
+                  styles.interactive,
+                  isDisabled && styles.disabled,
+                  isSelected && styles.selected,
+                )
+              : stylex.props(
+                  styles.contentWrapper,
+                  densityStyles[density],
+                  isDisabled && styles.disabled,
+                  isSelected && styles.selected,
+                ),
           )}
           style={indentStyle}
           onClick={handleClick}>

package/src/TreeList/TreeListTypes.ts

@@ -12,28 +12,11 @@
  */
 
 import type {ReactNode} from 'react';
+import type {TreeListVariantMap} from './index';
 
 /** Spacing density for tree list items. */
 export type TreeListDensity = 'compact' | 'balanced' | 'spacious';
 
-/**
- * Extensible variant map for TreeList.
- *
- * Theme packages can add custom variants via TypeScript module augmentation:
- * @example
- * ```
- * declare module '@astryxdesign/core/TreeList' {
- *   interface TreeListVariantMap {
- *     'dotted': true;
- *   }
- * }
- * ```
- */
-export interface TreeListVariantMap {
-  lineGuides: true;
-  noGuides: true;
-}
-
 /**
  * Visual treatment of the hierarchy guide (connector) lines. Extensible via
  * module augmentation of TreeListVariantMap.

package/src/TreeList/index.ts

@@ -11,6 +11,24 @@
  * SYNC: When modified, update /packages/core/src/TreeList/TreeList.doc.mjs
  */
 
+/**
+ * Extensible variant map for TreeList.
+ *
+ * Theme packages can add custom variants via TypeScript module augmentation:
+ * @example
+ * ```
+ * declare module '@astryxdesign/core/TreeList' {
+ *   interface TreeListVariantMap {
+ *     'dotted': true;
+ *   }
+ * }
+ * ```
+ */
+export interface TreeListVariantMap {
+  lineGuides: true;
+  noGuides: true;
+}
+
 export {TreeList} from './TreeList';
 export type {TreeListProps, TreeListDensity, TreeListVariant} from './TreeList';
-export type {TreeListItemData, TreeListVariantMap} from './TreeListTypes';
+export type {TreeListItemData} from './TreeListTypes';

package/src/Typeahead/BaseTypeahead.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: 'BaseTypeahead',

package/src/Typeahead/BaseTypeahead.tsx

@@ -14,7 +14,7 @@
  *
  * SYNC: When modified, update:
  * - /packages/core/src/Typeahead/index.ts
- * - /packages/cli/templates/blocks/components/Typeahead/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Typeahead/ (showcase blocks)
  */
 
 import React, {
@@ -30,6 +30,7 @@ import * as stylex from '@stylexjs/stylex';
 import type {StyleXStyles} from '@stylexjs/stylex';
 import {usePopover} from '../Popover/usePopover';
 import {useAnnounce} from '../hooks/useAnnounce';
+import {isImeKeyEvent} from '../hooks/useFocusTrap';
 import {TypeaheadItem} from './TypeaheadItem';
 import {Icon} from '../Icon';
 import {
@@ -157,6 +158,16 @@ export interface BaseTypeaheadProps<T extends SearchableItem> extends Omit<
    */
   inputXStyle?: StyleXStyles;
 
+  /**
+   * Tab-order override for the input element. Typeahead passes `-1` while
+   * its selected-value token is shown: the input is visually collapsed
+   * (width 0 / opacity 0) but must stay programmatically focusable for
+   * token edit/clear interactions, so removing it from the Tab order is
+   * what prevents an invisible tab stop (WCAG 2.4.3 / 2.4.7). The input
+   * remains focusable via `.focus()` regardless of this value.
+   */
+  inputTabIndex?: number;
+
   /**
    * Ref to the anchor element for dropdown positioning.
    * The dropdown will be positioned relative to this element.
@@ -316,6 +327,7 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
   ariaDescribedBy,
   ariaLabelledBy,
   inputXStyle,
+  inputTabIndex,
   anchorRef,
   onKeyDown: externalOnKeyDown,
   debounceMs = 150,
@@ -622,6 +634,17 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
         return;
       }
 
+      // An IME candidate window uses Enter to commit the composition and
+      // Escape/ArrowUp/ArrowDown/Home/End to navigate its own candidates.
+      // Without this guard, a composing Enter both fires handleSelect AND
+      // clears the input via handleSelect's setQuery(''), so the IME's
+      // subsequent compositionend then writes the still-pending syllable
+      // into the freshly-cleared field -- producing a second, spurious
+      // selection on the next real Enter.
+      if (isImeKeyEvent(e.nativeEvent)) {
+        return;
+      }
+
       if (!popover.isOpen) {
         if (e.key === 'ArrowDown' && (hasEntriesOnFocus || query.length > 0)) {
           e.preventDefault();
@@ -748,6 +771,7 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
         aria-describedby={ariaDescribedBy}
         aria-labelledby={ariaLabelledBy}
         aria-disabled={isFocusableDisabled ? 'true' : undefined}
+        tabIndex={inputTabIndex}
         value={query}
         onChange={handleInputChange}
         onPointerDown={() => {
@@ -797,7 +821,11 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
             stylex.props(styles.dropdown),
           )}>
           {results.length === 0 && hasSearched ? (
-            <div {...stylex.props(styles.emptyState)}>
+            <div
+              {...mergeProps(
+                themeProps('typeahead-empty-state'),
+                stylex.props(styles.emptyState),
+              )}>
               {emptySearchResultsText}
             </div>
           ) : (

package/src/Typeahead/Typeahead.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: 'Typeahead',
@@ -183,6 +183,7 @@ export const docs = {
     targets: [
       {className: 'astryx-typeahead', visualProps: ['status', 'size']},
       {className: 'astryx-typeahead-dropdown'},
+      {className: 'astryx-typeahead-empty-state'},
       {className: 'astryx-typeahead-item'},
     ],
   },
@@ -233,7 +234,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsZh = {
   usage: {
     description:
@@ -277,7 +278,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description:
     'Searchable dropdown for single-item selection w/ keyboard navigation. Supports async+sync search via searchSource interface.',

package/src/Typeahead/Typeahead.test.tsx

@@ -171,6 +171,28 @@ describe('BaseTypeahead', () => {
     });
   });
 
+  it('exposes the empty state as a themeable target', async () => {
+    const {container} = render(
+      <BaseTypeahead
+        searchSource={fruitSource}
+        value={null}
+        onChange={() => {}}
+        debounceMs={0}
+        emptySearchResultsText="No results found"
+      />,
+    );
+    const input = screen.getByRole('combobox');
+    fireEvent.change(input, {target: {value: 'zzzzz'}});
+
+    await waitFor(() => {
+      const emptyState = container.querySelector(
+        '.astryx-typeahead-empty-state',
+      );
+      expect(emptyState).not.toBeNull();
+      expect(emptyState).toHaveTextContent('No results found');
+    });
+  });
+
   describe('empty results active descendant (#4059)', () => {
     it('does not set aria-activedescendant when search has 0 results', async () => {
       render(
@@ -198,6 +220,45 @@ describe('BaseTypeahead', () => {
     });
   });
 
+  describe('IME composition guard (#4828)', () => {
+    it('does not select the highlighted result on a composing Enter', async () => {
+      const onChange = vi.fn();
+      render(
+        <BaseTypeahead
+          searchSource={fruitSource}
+          value={null}
+          onChange={onChange}
+          debounceMs={0}
+        />,
+      );
+      const input = screen.getByRole('combobox');
+      fireEvent.change(input, {target: {value: 'App'}});
+      await waitFor(() => {
+        expect(input).toHaveAttribute('aria-expanded', 'true');
+      });
+
+      // The browser fires this composing keydown for the Enter that commits
+      // an IME candidate (isComposing: true, or legacy keyCode 229) before
+      // compositionend writes the pending syllable into the input. Without
+      // the guard this both selects the highlighted result AND clears the
+      // input via handleSelect, so the syllable that compositionend then
+      // writes lands in an emptied field instead of being part of the word.
+      fireEvent.keyDown(input, {key: 'Enter', isComposing: true});
+      expect(onChange).not.toHaveBeenCalled();
+      expect(input).toHaveValue('App');
+
+      fireEvent.keyDown(input, {key: 'Enter', keyCode: 229});
+      expect(onChange).not.toHaveBeenCalled();
+      expect(input).toHaveValue('App');
+
+      // A real, non-composing Enter still selects normally.
+      fireEvent.keyDown(input, {key: 'Enter'});
+      expect(onChange).toHaveBeenCalledWith(
+        expect.objectContaining({label: 'Apple'}),
+      );
+    });
+  });
+
   it('disables input when isDisabled', () => {
     render(
       <BaseTypeahead
@@ -737,6 +798,68 @@ describe('Typeahead edit mode', () => {
   });
 });
 
+describe('Typeahead collapsed input tab order', () => {
+  it('removes the invisible input from the Tab order while a token is shown', () => {
+    render(
+      <Typeahead
+        label="Fruit"
+        searchSource={fruitSource}
+        value={fruits[0]}
+        onChange={() => {}}
+      />,
+    );
+    // While the token is shown the input is collapsed (width 0 / opacity 0);
+    // it must stay programmatically focusable for token interactions but must
+    // not be an invisible Tab stop (WCAG 2.4.3 / 2.4.7).
+    expect(screen.getByRole('combobox')).toHaveAttribute('tabindex', '-1');
+  });
+
+  it('Tab from the token skips the invisible input', async () => {
+    const user = userEvent.setup();
+    render(
+      <Typeahead
+        label="Fruit"
+        searchSource={fruitSource}
+        value={fruits[0]}
+        onChange={() => {}}
+      />,
+    );
+    // Focus the token's internal button, then Tab away — focus must not land
+    // on the visually hidden combobox input.
+    const tokenButton = screen.getByRole('button', {name: fruits[0].label});
+    tokenButton.focus();
+    await user.tab();
+    expect(screen.getByRole('combobox')).not.toHaveFocus();
+  });
+
+  it('keeps the input in the Tab order when no token is shown', () => {
+    render(
+      <Typeahead
+        label="Fruit"
+        searchSource={fruitSource}
+        value={null}
+        onChange={() => {}}
+      />,
+    );
+    expect(screen.getByRole('combobox')).not.toHaveAttribute('tabindex');
+  });
+
+  it('restores the input to the Tab order in edit mode', () => {
+    render(
+      <Typeahead
+        label="Fruit"
+        searchSource={fruitSource}
+        value={fruits[0]}
+        onChange={() => {}}
+      />,
+    );
+    // Entering edit mode removes the token and uncollapses the input
+    const tokenText = screen.getByText(fruits[0].label);
+    fireEvent.click(tokenText.closest('div')!);
+    expect(screen.getByRole('combobox')).not.toHaveAttribute('tabindex');
+  });
+});
+
 describe('BaseTypeahead paste behavior', () => {
   it('pasting text triggers search results like typing', async () => {
     const user = userEvent.setup();
@@ -976,11 +1099,16 @@ describe('Typeahead disabledMessage', () => {
   });
 });
 
-
 describe('Typeahead statusVariant forwarding', () => {
   it('defaults to attached (status renders with data-variant="attached")', () => {
     const {container} = render(
-      <Typeahead label="Fruit" searchSource={fruitSource} value={null} onChange={() => {}} status={{type: 'error', message: 'Required'}} />,
+      <Typeahead
+        label="Fruit"
+        searchSource={fruitSource}
+        value={null}
+        onChange={() => {}}
+        status={{type: 'error', message: 'Required'}}
+      />,
     );
     expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
       'data-variant',
@@ -990,7 +1118,14 @@ describe('Typeahead statusVariant forwarding', () => {
 
   it('forwards statusVariant="detached" to the underlying Field status', () => {
     const {container} = render(
-      <Typeahead label="Fruit" searchSource={fruitSource} value={null} onChange={() => {}} status={{type: 'error', message: 'Required'}} statusVariant="detached" />,
+      <Typeahead
+        label="Fruit"
+        searchSource={fruitSource}
+        value={null}
+        onChange={() => {}}
+        status={{type: 'error', message: 'Required'}}
+        statusVariant="detached"
+      />,
     );
     expect(container.querySelector('.astryx-field-status')).toHaveAttribute(
       'data-variant',

package/src/Typeahead/Typeahead.tsx

@@ -15,7 +15,7 @@
  * SYNC: When modified, update:
  * - /packages/core/src/Typeahead/index.ts
  * - /apps/storybook/stories/Typeahead.stories.tsx
- * - /packages/cli/templates/blocks/components/Typeahead/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Typeahead/ (showcase blocks)
  */
 
 import React, {
@@ -467,6 +467,12 @@ export function Typeahead<T extends SearchableItem>({
           anchorRef={wrapperRef}
           onKeyDown={handleKeyDown}
           inputXStyle={showToken ? styles.inputHidden : undefined}
+          // While the token is shown the input is collapsed (width 0 /
+          // opacity 0) — take it out of the Tab order so keyboard users
+          // don't hit an invisible stop (WCAG 2.4.3 / 2.4.7). It stays
+          // programmatically focusable: entering edit mode and clearing
+          // both refocus it after it uncollapses.
+          inputTabIndex={showToken ? -1 : undefined}
           size={size}
         />
         {hasClear && value && !isDisabled && (

package/src/Typeahead/TypeaheadItem.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: 'TypeaheadItem',

package/src/Typeahead/TypeaheadItem.tsx

@@ -8,7 +8,7 @@
  *
  * SYNC: When modified, update:
  * - /packages/core/src/Typeahead/index.ts
- * - /packages/cli/templates/blocks/components/Typeahead/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Typeahead/ (showcase blocks)
  */
 
 import React, {type ReactNode} from 'react';

package/src/VStack/VStack.tsx

@@ -9,7 +9,7 @@
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/Stack/Stack.doc.mjs
  * - /packages/core/src/VStack/VStack.test.tsx
- * - /packages/cli/templates/blocks/components/VStack/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/VStack/ (showcase blocks)
  */
 
 import {Stack, type StackProps} from '../Stack/Stack';