@astryxdesign/core 0.3.0 → 0.4.0

package/src/Selector/hooks.ts

@@ -4,15 +4,36 @@
 
 /**
  * @file hooks.ts
+ * @input Uses untransformed DOM layout geometry from the Selector's outer
+ *   anchor, listbox, and selected option
  * @output Hooks for Selector
  * @position Internal hooks; used by Selector.tsx
  */
 
-import {useCallback, useRef, useState} from 'react';
+import {useCallback, useState} from 'react';
 import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
 import type {RefObject} from 'react';
 import type {SelectorOptionData} from './types';
 
+// The selected row renders one optical pixel below the closed trigger label at
+// the same mathematical center, so compensate before viewport clamping.
+const SELECTED_ITEM_OPTICAL_OFFSET = 1;
+
+/**
+ * Return an element's document-relative layout top without CSS transforms.
+ * getBoundingClientRect includes the popover's entry scale, which would make
+ * the measured error grow with each option's distance from the menu top.
+ */
+function getLayoutTop(element: HTMLElement): number {
+  let top = 0;
+  let current: HTMLElement | null = element;
+  while (current) {
+    top += current.offsetTop;
+    current = current.offsetParent as HTMLElement | null;
+  }
+  return top;
+}
+
 // =============================================================================
 // useSelectedItemOffset - Position dropdown to center selected item over trigger
 // =============================================================================
@@ -22,7 +43,7 @@ interface UseSelectedItemOffsetOptions {
   selectedItemIndex: number;
   listboxId: string;
   listboxRef: RefObject<HTMLDivElement | null>;
-  triggerRef: RefObject<HTMLButtonElement | null>;
+  anchorRef: RefObject<HTMLElement | null>;
 }
 
 interface UseSelectedItemOffsetResult {
@@ -32,9 +53,9 @@ interface UseSelectedItemOffsetResult {
 
 /**
  * Calculates the offset needed to position the dropdown so that the selected
- * item appears centered over the trigger button (macOS-style selector).
+ * item appears centered over the outer selector control (macOS-style selector).
  *
- * The desired dropdown top is calculated directly from the trigger center and
+ * The desired dropdown top is calculated directly from the anchor center and
  * selected-item center, then clamped to the viewport. This preserves the
  * default "selected item over trigger" behavior while letting the menu slide
  * upward near the bottom edge or downward near the top edge instead of being
@@ -45,7 +66,7 @@ export function useSelectedItemOffset({
   selectedItemIndex,
   listboxId,
   listboxRef,
-  triggerRef,
+  anchorRef,
 }: UseSelectedItemOffsetOptions): UseSelectedItemOffsetResult {
   const [offset, setOffset] = useState(0);
   const [isPositioned, setIsPositioned] = useState(false);
@@ -67,7 +88,7 @@ export function useSelectedItemOffset({
       return;
     }
 
-    if (!listboxRef.current || !triggerRef.current) {
+    if (!listboxRef.current || !anchorRef.current) {
       commitPosition(0, true);
       return;
     }
@@ -83,34 +104,37 @@ export function useSelectedItemOffset({
       return;
     }
 
-    // Get positions. JSDOM returns zero rects by default, but browsers provide
-    // real dimensions before paint via layout effect.
-    const listboxRect = listboxRef.current.getBoundingClientRect();
-    const itemRect = targetItem.getBoundingClientRect();
-    const triggerRect = triggerRef.current.getBoundingClientRect();
+    const listbox = listboxRef.current;
+    const anchorRect = anchorRef.current.getBoundingClientRect();
 
-    const listboxHeight = listboxRect.height;
+    // offset* metrics intentionally exclude the popover's entry transform.
+    const listboxHeight = listbox.offsetHeight;
     if (listboxHeight <= 0) {
       commitPosition(0, true);
       return;
     }
 
     // Item center relative to listbox top. This remains stable even as the
-    // popover's top changes between measurements.
+    // popover animates between scale values. scrollTop keeps the calculation
+    // correct when a previously scrolled listbox is reopened.
     const itemCenterInListbox =
-      itemRect.top - listboxRect.top + itemRect.height / 2;
-    const triggerCenter = triggerRect.top + triggerRect.height / 2;
-
-    // Desired top aligns the selected item's center with trigger center.
-    const desiredTop = triggerCenter - itemCenterInListbox;
+      getLayoutTop(targetItem) -
+      getLayoutTop(listbox) -
+      listbox.scrollTop +
+      targetItem.offsetHeight / 2;
+    const anchorCenter = anchorRect.top + anchorRect.height / 2;
+
+    // Desired top aligns the selected item's center with the anchor center.
+    const desiredTop =
+      anchorCenter - itemCenterInListbox - SELECTED_ITEM_OPTICAL_OFFSET;
     const viewportHeight = window.innerHeight;
     const maxTop = Math.max(0, viewportHeight - listboxHeight);
     const clampedTop = Math.min(Math.max(desiredTop, 0), maxTop);
 
-    // useLayer positions the popover below the trigger. Apply a negative
+    // useLayer positions the popover below the outer anchor. Apply a negative
     // block-start margin to the layer container so the listbox top moves from
-    // triggerRect.bottom to clampedTop.
-    const clampedOffset = Math.max(0, triggerRect.bottom - clampedTop);
+    // anchorRect.bottom to clampedTop.
+    const clampedOffset = Math.max(0, anchorRect.bottom - clampedTop);
 
     commitPosition(clampedOffset, true);
   }, [
@@ -118,7 +142,7 @@ export function useSelectedItemOffset({
     selectedItemIndex,
     listboxId,
     listboxRef,
-    triggerRef,
+    anchorRef,
     commitPosition,
   ]);
 
@@ -126,7 +150,7 @@ export function useSelectedItemOffset({
 }
 
 // =============================================================================
-// useCombobox - Keyboard navigation, typeahead, and selection
+// useCombobox - Keyboard navigation and selection
 // =============================================================================
 
 interface UseComboboxOptions {
@@ -145,6 +169,13 @@ interface UseComboboxOptions {
    * navigation owns those keys there) or when there is no value.
    */
   onClear?: () => void;
+  /**
+   * With `hasSearch`, printable characters typed on the trigger are appended to
+   * the search query (opening the popup if needed), so type-to-find works
+   * without a separate open step. Characters keep arriving here until focus
+   * lands in the search input, which then owns its own typing.
+   */
+  onSearchSeed?: (char: string) => void;
   listboxId: string;
 }
 
@@ -159,7 +190,12 @@ interface UseComboboxResult {
 }
 
 /**
- * Handles keyboard navigation, typeahead search, and selection for combobox/listbox patterns.
+ * Handles keyboard navigation and selection for combobox/listbox patterns.
+ *
+ * Type-to-select is not handled here: callers that want it compose the shared
+ * `useTypeahead` hook and run it ahead of this handler (see Selector). That
+ * keeps matching consistent with the other collections and leaves consumers
+ * whose own input already filters the items (CommandPalette) untouched.
  */
 export function useCombobox({
   selectableItems,
@@ -171,13 +207,10 @@ export function useCombobox({
   onClose,
   onSelect,
   onClear,
+  onSearchSeed,
   listboxId,
 }: UseComboboxOptions): UseComboboxResult {
   const [highlightedIndex, setHighlightedIndex] = useState<number>(-1);
-  const [typeahead, setTypeahead] = useState('');
-  const typeaheadTimeoutRef = useRef<ReturnType<typeof setTimeout> | undefined>(
-    undefined,
-  );
 
   const getItemId = useCallback(
     (index: number) => `${listboxId}-item-${index}`,
@@ -274,6 +307,8 @@ export function useCombobox({
           if (hasSearch) {
             break;
           }
+        // A space mid-typeahead extends the query instead of activating; the
+        // caller's useTypeahead claims it before this handler ever runs.
         // falls through
         case 'Enter':
           e.preventDefault();
@@ -349,28 +384,20 @@ export function useCombobox({
           break;
 
         default:
-          if (!hasSearch && e.key.length === 1 && !e.ctrlKey && !e.metaKey) {
-            const newTypeahead = typeahead + e.key.toLowerCase();
-            setTypeahead(newTypeahead);
-
-            if (typeaheadTimeoutRef.current) {
-              clearTimeout(typeaheadTimeoutRef.current);
-            }
-            typeaheadTimeoutRef.current = setTimeout(() => {
-              setTypeahead('');
-            }, 500);
-
-            const matchIndex = selectableItems.findIndex(
-              item =>
-                !item.disabled &&
-                item.label?.toLowerCase().startsWith(newTypeahead),
-            );
-            if (matchIndex >= 0) {
-              if (!isOpen) {
-                onOpen();
-              }
-              setHighlightedIndex(matchIndex);
+          // Keys land here only while the trigger holds focus — once the search
+          // input takes over it handles its own typing — so they belong in the
+          // query, including the ones racing the open.
+          if (
+            hasSearch &&
+            onSearchSeed &&
+            e.key.length === 1 &&
+            !e.ctrlKey &&
+            !e.metaKey
+          ) {
+            if (!isOpen) {
+              onOpen();
             }
+            onSearchSeed(e.key);
           }
           break;
       }
@@ -385,9 +412,9 @@ export function useCombobox({
       selectItem,
       findSelectedIndex,
       getEnabledIndices,
-      typeahead,
       hasSearch,
       onClear,
+      onSearchSeed,
       value,
     ],
   );

package/src/SideNav/SideNav.test.tsx

@@ -183,6 +183,27 @@ describe('SideNav', () => {
     expect(nav.children).toHaveLength(1);
   });
 
+  it('centers footer content when collapsed, matching children alignment', () => {
+    render(
+      <SideNav
+        data-testid="nav"
+        collapsible={{isCollapsed: true, hasButton: false}}
+        footer={<span data-testid="footer-content">F</span>}>
+        <span data-testid="children-content">C</span>
+      </SideNav>,
+    );
+
+    // scrollableCollapsed (wraps children) and stickyBottomCollapsed (wraps
+    // footer) are structurally parallel collapsed-rail containers; both
+    // must center their content the same way, or full-width footer content
+    // stretches to the collapsed rail's width instead of centering.
+    const childrenContainer =
+      screen.getByTestId('children-content').parentElement;
+    const footerContainer = screen.getByTestId('footer-content').parentElement;
+    expect(getComputedStyle(childrenContainer!).alignItems).toBe('center');
+    expect(getComputedStyle(footerContainer!).alignItems).toBe('center');
+  });
+
   it('fires a consumer onClick on the collapse button in addition to toggling', async () => {
     const user = userEvent.setup();
     const onClick = vi.fn();
@@ -592,6 +613,31 @@ describe('SideNavHeading collapsed', () => {
       expect(menu!.contains(button)).toBe(false);
     }
   });
+
+  it('anchors the collapsed icon-only trigger so the popover positions against it', () => {
+    render(
+      <CollapsedWrapper>
+        <SideNavHeading
+          heading="My App"
+          icon={<span data-testid="app-icon">🏠</span>}
+          menu={<div role="menuitem">Alpha</div>}
+        />
+      </CollapsedWrapper>,
+    );
+    const trigger = screen.getByRole('button', {name: 'My App'});
+    // The same element also carries the collapsed-item Tooltip's own
+    // anchor-name (via anchorRef={collapsedItemRef}), so a plain
+    // non-empty check would pass even when the menu popover itself isn't
+    // anchored. Assert the popover's own position-anchor id specifically
+    // appears in the trigger's (possibly multi-value) anchor-name list.
+    const popoverEl = document.querySelector('[popover]') as HTMLElement;
+    const anchorId = popoverEl.style.positionAnchor;
+    expect(anchorId).not.toBe('');
+    const triggerAnchorNames = trigger.style.anchorName
+      .split(',')
+      .map(s => s.trim());
+    expect(triggerAnchorNames).toContain(anchorId);
+  });
 });
 
 // =============================================================================

package/src/SideNav/SideNav.tsx

@@ -143,6 +143,7 @@ const styles = stylex.create({
   },
   stickyBottomCollapsed: {
     paddingBlockStart: 0,
+    alignItems: 'center',
   },
   // Drawer footer — pushed to bottom of the scrollable content area
   drawerFooter: {

package/src/SideNav/SideNavCollapseButton.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file SideNavCollapseButton.tsx
- * @input Uses React, StyleX, SideNavCollapseContext, getIcon
+ * @input Uses React, StyleX, SideNavCollapseContext, Icon
  * @output Exports SideNavCollapseButton component
  * @position Composable toggle button for sidenav collapse
  *
@@ -20,7 +20,7 @@
 import React, {type ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {durationVars, easeVars} from '../theme/tokens.stylex';
-import {useIcon} from '../Icon';
+import {Icon} from '../Icon';
 import {Button} from '../Button';
 import type {BaseProps} from '../BaseProps';
 import {composeEventHandlers, rtlStyles} from '../utils';
@@ -107,7 +107,6 @@ export function SideNavCollapseButton({
   ...props
 }: SideNavCollapseButtonProps) {
   const t = useTranslator();
-  const chevronLeftIcon = useIcon('chevronLeft');
   const {isCollapsed, toggle, isCollapsible} =
     useSideNavCollapseState(handleRef);
   const {isMobile} = useAppShellMobile();
@@ -132,14 +131,20 @@ export function SideNavCollapseButton({
       onClick={composeEventHandlers(onClickProp, toggle)}
       icon={
         children ?? (
+          // The RTL mirror stays on its own element, wrapping (not merged
+          // into) the state rotation: both are `transform`, so on a single
+          // element one would overwrite the other and the chevron would stop
+          // mirroring under RTL. See utils/rtlStyles.ts.
           <span {...stylex.props(rtlStyles.mirror)}>
-            <span
-              {...stylex.props(
-                styles.chevron,
-                isCollapsed && styles.chevronCollapsed,
-              )}>
-              {chevronLeftIcon}
-            </span>
+            {/* `sm` (1rem) matches what this glyph already renders at: Button's
+                icon slot pins its wrapper to 16px, and the registry SVG is
+                1em, so the chevron is 16px today. */}
+            <Icon
+              icon="chevronLeft"
+              size="sm"
+              color="inherit"
+              xstyle={[styles.chevron, isCollapsed && styles.chevronCollapsed]}
+            />
           </span>
         )
       }

package/src/SideNav/SideNavHeading.tsx

@@ -33,7 +33,7 @@ import {
 // of lazy loading layer resources.
 import {usePopover} from '../Popover/usePopover';
 import {Link} from '../Link';
-import {useIcon} from '../Icon';
+import {Icon} from '../Icon';
 import {Tooltip} from '../Tooltip';
 import {navItemStyles} from '../NavItem/navItemStyles.stylex';
 import {useSideNavCollapse} from './SideNavCollapseContext';
@@ -172,6 +172,11 @@ const styles = stylex.create({
     minWidth: spacingVars['--spacing-7'],
     minHeight: spacingVars['--spacing-7'],
     color: colorVars['--color-icon-secondary'],
+    // 28px is the hit/alignment box, not the glyph. Icon sizes its own span
+    // with a matching font-size (the registry chevron is a 1em SVG), so pin
+    // font-size back to inherit to keep the glyph at the 14px it renders at
+    // today. The 28px min box still wins over Icon's width/height.
+    fontSize: 'inherit',
   },
   headerEndContent: {
     flexShrink: 0,
@@ -217,8 +222,15 @@ const styles = stylex.create({
     minWidth: spacingVars['--spacing-7'],
     minHeight: spacingVars['--spacing-7'],
     color: colorVars['--color-icon-secondary'],
+    // See `chevron` — keep the glyph on the inherited font-size.
+    fontSize: 'inherit',
     transform: 'rotate(180deg)',
   },
+  // Glyph inside a chevron *trigger* (the button already carries the 28px box
+  // and the color, so the Icon only has to avoid resizing itself).
+  chevronGlyph: {
+    fontSize: 'inherit',
+  },
   popover: {
     minWidth: 'anchor-size(width)',
     marginBlockStart: spacingVars['--spacing-1'],
@@ -344,7 +356,6 @@ export function SideNavHeading({
   ...props
 }: SideNavHeadingProps) {
   const t = useTranslator();
-  const chevronDownIcon = useIcon('chevronDown');
   const LinkComponent = useLinkComponent(as);
   const {isCollapsed} = useSideNavCollapse();
   const rootRef = useRef<HTMLDivElement>(null);
@@ -387,7 +398,11 @@ export function SideNavHeading({
   if (isCollapsed && icon) {
     const collapsedIcon = <span {...stylex.props(styles.icon)}>{icon}</span>;
 
-    const collapsedSetRef = mergeRefs<HTMLElement>(collapsedItemRef, ref);
+    const collapsedSetRef = mergeRefs<HTMLElement>(
+      collapsedItemRef,
+      ref,
+      menu ? popover.triggerRef : undefined,
+    );
 
     let collapsedElement: ReactNode;
 
@@ -454,9 +469,12 @@ export function SideNavHeading({
                       )}>
                       {heading}
                     </span>
-                    <span {...stylex.props(styles.popoverChevron)}>
-                      {chevronDownIcon}
-                    </span>
+                    <Icon
+                      icon="chevronDown"
+                      size="sm"
+                      color="secondary"
+                      xstyle={styles.popoverChevron}
+                    />
                   </span>
                   {subheading && (
                     <span {...stylex.props(styles.subheading)}>
@@ -551,7 +569,12 @@ export function SideNavHeading({
   );
 
   const chevronElement = showChevron && (
-    <span {...stylex.props(styles.chevron)}>{chevronDownIcon}</span>
+    <Icon
+      icon="chevronDown"
+      size="sm"
+      color="secondary"
+      xstyle={styles.chevron}
+    />
   );
 
   const headerEndContentElement = headerEndContent && (
@@ -567,7 +590,12 @@ export function SideNavHeading({
       onClick={triggerProps.onClick}>
       {icon && <span {...stylex.props(styles.icon)}>{icon}</span>}
       {renderTextContent(
-        <span {...stylex.props(styles.popoverChevron)}>{chevronDownIcon}</span>,
+        <Icon
+          icon="chevronDown"
+          size="sm"
+          color="secondary"
+          xstyle={styles.popoverChevron}
+        />,
       )}
     </button>
   );
@@ -619,7 +647,12 @@ export function SideNavHeading({
               }}
               {...popover.triggerProps}
               {...stylex.props(styles.chevron, styles.interactive)}>
-              {chevronDownIcon}
+              <Icon
+                icon="chevronDown"
+                size="sm"
+                color="inherit"
+                xstyle={styles.chevronGlyph}
+              />
             </button>,
           )}
           {headerEndContentElement}
@@ -685,7 +718,12 @@ export function SideNavHeading({
                 }}
                 {...popover.triggerProps}
                 {...stylex.props(styles.chevron, styles.interactive)}>
-                {chevronDownIcon}
+                <Icon
+                  icon="chevronDown"
+                  size="sm"
+                  color="inherit"
+                  xstyle={styles.chevronGlyph}
+                />
               </button>
             ) : undefined,
           )}

package/src/SideNav/SideNavItem.tsx

@@ -38,7 +38,7 @@ import {
   borderVars,
   radiusVars,
 } from '../theme/tokens.stylex';
-import {renderIconSlot, useIcon, type IconType} from '../Icon';
+import {Icon, renderIconSlot, type IconType} from '../Icon';
 import {useLinkComponent} from '../Link/useLinkComponent';
 import type {LinkComponentType} from '../Link/types';
 import {usePopover} from '../Popover/usePopover';
@@ -108,6 +108,11 @@ const styles = stylex.create({
     justifyContent: 'center',
     width: spacingVars['--spacing-6'],
     height: spacingVars['--spacing-6'],
+    // Icon's `lg` would also set font-size: 1.5rem, and the registry chevron
+    // is a 1em SVG — that would blow the glyph up from the 14px it inherits
+    // from the row to the full 24px box. The 24px box is the touch/alignment
+    // target, not the glyph size, so keep the glyph on the inherited size.
+    fontSize: 'inherit',
     transitionProperty: 'transform',
     transitionDuration: durationVars['--duration-fast'],
     transitionTimingFunction: easeVars['--ease-standard'],
@@ -358,7 +363,6 @@ export function SideNavItem({
   xstyle,
 }: SideNavItemProps) {
   const t = useTranslator();
-  const chevronDownIcon = useIcon('chevronDown');
   const {isCollapsed} = useSideNavCollapse();
   const renderMode = useSideNavRenderMode();
   const {closeMobileNav} = useAppShellMobile();
@@ -574,13 +578,15 @@ export function SideNavItem({
         <span {...stylex.props(styles.endContent)}>{endContent}</span>
       )}
       {!isCollapsed && isItemCollapsible && !hasIndependentToggle && (
-        <span
-          {...stylex.props(
+        <Icon
+          icon="chevronDown"
+          size="lg"
+          color="inherit"
+          xstyle={[
             styles.expandChevron,
             !isItemCollapsed && styles.expandChevronExpanded,
-          )}>
-          {chevronDownIcon}
-        </span>
+          ]}
+        />
       )}
     </>
   );
@@ -637,13 +643,15 @@ export function SideNavItem({
           aria-expanded={!isItemCollapsed}
           aria-controls={`${id}-children`}
           {...stylex.props(styles.expandToggle)}>
-          <span
-            {...stylex.props(
+          <Icon
+            icon="chevronDown"
+            size="lg"
+            color="inherit"
+            xstyle={[
               styles.expandChevron,
               !isItemCollapsed && styles.expandChevronExpanded,
-            )}>
-            {chevronDownIcon}
-          </span>
+            ]}
+          />
         </button>
       </div>
     );