@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/dist/Selector/hooks.js

@@ -7,7 +7,8 @@
  * @input Uses untransformed DOM layout geometry from the Selector's outer
  *   anchor, listbox, and selected option
  * @output Hooks for Selector: useSelectedItemOffset, and useCombobox (public,
- *   exported from the Selector entry point; also used by CommandPalette)
+ *   exported from the Selector entry point; also used by CommandPalette, and
+ *   by products for a combobox over a text field they render, spec:AST-075)
  * @position Selector hooks; used by Selector.tsx and CommandPalette
  *
  * SYNC: When useCombobox's options or return change, update:
@@ -16,6 +17,7 @@
 import { useCallback, useState } from 'react';
 import { useHighlightedOptionScroll } from "../hooks/useHighlightedOptionScroll.js";
 import { useIsomorphicLayoutEffect } from "../hooks/useIsomorphicLayoutEffect.js";
+import { isImeKeyEvent } from "../utils/ime.js";
 // 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;
@@ -122,6 +124,25 @@ export function useSelectedItemOffset({
 // useCombobox - Keyboard navigation and selection
 // =============================================================================
 
+/**
+ * What useCombobox reads from an option: its value, and whether it can be
+ * picked. Any option type that carries these works; Selector's
+ * `SelectorOptionData` is the default.
+ */
+
+/** Spread onto the caller's field. */
+
+/** Spread onto the caller's listbox, which the caller names. */
+
+/** Spread onto the caller's option at one index. */
+
+/** The caller's own handlers for its field, run after the hook's. */
+
+/** Whether a key is chorded with a modifier, such as Shift+Enter. */
+function hasModifier(e) {
+  return e.altKey || e.ctrlKey || e.metaKey || e.shiftKey;
+}
+
 /**
  * Handles keyboard navigation and selection for combobox/listbox patterns.
  *
@@ -129,6 +150,12 @@ export function useSelectedItemOffset({
  * `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.
+ *
+ * For a single-line text field the caller renders (spec:AST-075), `getFieldProps`,
+ * `getListboxProps` and `getOptionProps` carry the combobox semantics, the
+ * field's keys and the pointer model, while the caller keeps the field, the
+ * rows and where the list renders. The caller announces each new result count
+ * through useAnnounce (spec:AST-075 DEC-2), with the words the field shows.
  */
 export function useCombobox({
   selectableItems,
@@ -305,6 +332,119 @@ export function useCombobox({
         break;
     }
   }, [isDisabled, isOpen, onOpen, closeAndReset, selectableItems, highlightedIndex, selectItem, findSelectedIndex, getEnabledIndices, hasSearch, onClear, onSearchSeed, value]);
+
+  // ---------------------------------------------------------------------------
+  // A field the caller renders (spec:AST-075). Focus never leaves it: the
+  // active option is named through aria-activedescendant, and the field keeps
+  // every key the list does not need.
+  // ---------------------------------------------------------------------------
+
+  // The listbox renders only while it has options; an open list with none
+  // shows the caller's empty state instead, which is not a listbox.
+  const isListboxShown = isOpen && selectableItems.length > 0;
+  const activeDescendant = isListboxShown && highlightedIndex >= 0 && highlightedIndex < selectableItems.length ? getItemId(highlightedIndex) : undefined;
+  const onFieldKeyDown = useCallback(e => {
+    // A chord is the field's own command, such as Shift+Enter, except
+    // Escape: whatever modifier is held, it hides a shown list first, so an
+    // enclosing layer never closes on the same press. An input method
+    // composing text owns every key, Escape included, until it commits or
+    // cancels.
+    if (isDisabled || isImeKeyEvent(e.nativeEvent) || hasModifier(e) && e.key !== 'Escape') {
+      return;
+    }
+    const enabledIndices = getEnabledIndices();
+    if (!isOpen) {
+      // A single-line field has no caret work for ArrowDown, so it shows the
+      // hidden list.
+      if (e.key === 'ArrowDown' && selectableItems.length > 0 && onOpen() !== false) {
+        e.preventDefault();
+        setHighlightedIndex(enabledIndices[0] ?? -1);
+      }
+      return;
+    }
+    switch (e.key) {
+      case 'ArrowDown':
+      case 'ArrowUp':
+        {
+          // The list keeps the arrows even with nothing to move to, so they
+          // never move the caret under an open list.
+          e.preventDefault();
+          if (enabledIndices.length === 0) {
+            break;
+          }
+          // Wraps at either end, as the typeahead input does; with nothing
+          // active, ArrowDown starts at the first option and ArrowUp at the
+          // last.
+          const count = enabledIndices.length;
+          const position = enabledIndices.indexOf(highlightedIndex);
+          const next = e.key === 'ArrowDown' ? (position + 1) % count : position < 0 ? count - 1 : (position - 1 + count) % count;
+          setHighlightedIndex(enabledIndices[next]);
+          break;
+        }
+      case 'Enter':
+        {
+          // Only a pick stops the field's own Enter (a send, a newline).
+          const item = highlightedIndex >= 0 ? selectableItems[highlightedIndex] : null;
+          if (item != null && !item.disabled) {
+            e.preventDefault();
+            selectItem(item);
+          }
+          break;
+        }
+      case 'Escape':
+        // Claimed, so an enclosing layer stays open on this press.
+        e.preventDefault();
+        closeAndReset();
+        break;
+      default:
+        // Every other key reaches the field unchanged. Home and End stay
+        // with the caret until their behavior is decided (AST-075 OQ2).
+        break;
+    }
+  }, [isDisabled, getEnabledIndices, isOpen, selectableItems, onOpen, highlightedIndex, selectItem, closeAndReset]);
+  const getFieldProps = useCallback((props = {}) => {
+    return {
+      role: 'combobox',
+      'aria-expanded': isListboxShown,
+      'aria-autocomplete': 'list',
+      'aria-controls': isListboxShown ? listboxId : undefined,
+      'aria-activedescendant': activeDescendant,
+      onKeyDown: event => {
+        onFieldKeyDown(event);
+        if (!event.defaultPrevented) {
+          props.onKeyDown?.(event);
+        }
+      }
+    };
+  }, [isListboxShown, listboxId, activeDescendant, onFieldKeyDown]);
+  const getListboxProps = useCallback(() => ({
+    id: listboxId,
+    role: 'listbox',
+    // A press anywhere in the list keeps focus in the field (FR6).
+    onMouseDown: event => event.preventDefault()
+  }), [listboxId]);
+  const getOptionProps = useCallback(index => {
+    const item = selectableItems[index];
+    const isOptionDisabled = item?.disabled === true;
+    return {
+      id: getItemId(index),
+      role: 'option',
+      'aria-selected': index === highlightedIndex,
+      ...(isOptionDisabled ? {
+        'aria-disabled': true
+      } : {}),
+      onMouseMove: () => {
+        if (item != null && !isOptionDisabled && index !== highlightedIndex) {
+          highlightOnHover(index);
+        }
+      },
+      onClick: () => {
+        if (item != null) {
+          selectItem(item);
+        }
+      }
+    };
+  }, [selectableItems, getItemId, highlightedIndex, highlightOnHover, selectItem]);
   return {
     highlightedIndex,
     setHighlightedIndex,
@@ -312,6 +452,9 @@ export function useCombobox({
     onTriggerClick,
     onKeyDown,
     onItemSelect: selectItem,
-    onItemMouseEnter
+    onItemMouseEnter,
+    getFieldProps,
+    getListboxProps,
+    getOptionProps
   };
 }

package/dist/SideNav/SideNav.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SideNav.d.ts","sourceRoot":"","sources":["../../src/SideNav/SideNav.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAKL,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AACf,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAE5C,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,kBAAkB,CAAC;AAGnD,OAAO,EAGL,KAAK,wBAAwB,EAC7B,KAAK,+BAA+B,EACrC,MAAM,0BAA0B,CAAC;AAKlC,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,2BAA2B,CAAC;AAsP/D,MAAM,WAAW,YAAa,SAAQ,SAAS,CAAC,WAAW,CAAC;IAC1D,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IAE7B;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,+BAA+B,CAAC,CAAC;IAEvD;;OAEG;IACH,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB;;OAEG;IACH,UAAU,CAAC,EAAE,SAAS,CAAC;IACvB;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAC;IACpB;;OAEG;IACH,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB;;OAEG;IACH,WAAW,CAAC,EAAE,SAAS,CAAC;IACxB;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,KAAK,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC;IAC5B;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,SAAS,CAAC,EAAE,OAAO,GAAG,eAAe,CAAC;IAEtC;;;;;;;;;;;;;OAaG;IACH,WAAW,CAAC,EAAE,OAAO,GAAG,wBAAwB,CAAC;CAClD;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,OAAO,CAAC,EACtB,MAAM,EACN,UAAU,EACV,QAAQ,EACR,MAAM,EACN,WAAW,EACX,WAAmB,EACnB,SAAiB,EACjB,MAAM,EACN,SAAS,EACT,KAAK,EACL,aAAa,EAAE,MAAM,EACrB,GAAG,EACH,SAAS,EACT,GAAG,KAAK,EACT,EAAE,YAAY,+BAmRd;yBAlSe,OAAO"}
+{"version":3,"file":"SideNav.d.ts","sourceRoot":"","sources":["../../src/SideNav/SideNav.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAQL,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AACf,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAE5C,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,kBAAkB,CAAC;AAGnD,OAAO,EAGL,KAAK,wBAAwB,EAC7B,KAAK,+BAA+B,EACrC,MAAM,0BAA0B,CAAC;AAKlC,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,2BAA2B,CAAC;AA+P/D,MAAM,WAAW,YAAa,SAAQ,SAAS,CAAC,WAAW,CAAC;IAC1D,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IAE7B;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,+BAA+B,CAAC,CAAC;IAEvD;;OAEG;IACH,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB;;OAEG;IACH,UAAU,CAAC,EAAE,SAAS,CAAC;IACvB;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAC;IACpB;;OAEG;IACH,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB;;OAEG;IACH,WAAW,CAAC,EAAE,SAAS,CAAC;IACxB;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,KAAK,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC;IAC5B;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,SAAS,CAAC,EAAE,OAAO,GAAG,eAAe,CAAC;IAEtC;;;;;;;;;;;;;OAaG;IACH,WAAW,CAAC,EAAE,OAAO,GAAG,wBAAwB,CAAC;CAClD;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,OAAO,CAAC,EACtB,MAAM,EACN,UAAU,EACV,QAAQ,EACR,MAAM,EACN,WAAW,EACX,WAAmB,EACnB,SAAiB,EACjB,MAAM,EACN,SAAS,EACT,KAAK,EACL,aAAa,EAAE,MAAM,EACrB,GAAG,EACH,SAAS,EACT,GAAG,KAAK,EACT,EAAE,YAAY,+BA2Vd;yBA1We,OAAO"}

package/dist/SideNav/SideNav.js

@@ -21,7 +21,7 @@
  * - /apps/storybook/stories/SideNav.stories.tsx
  * - /packages/cli/assets/templates/blocks/components/SideNav/ (showcase blocks)
  */
-import { useCallback, useId, useImperativeHandle, useRef } from 'react';
+import { use, useCallback, useId, useImperativeHandle, useLayoutEffect, useMemo, useRef } from 'react';
 import * as stylex from '@stylexjs/stylex';
 import "../theme/tokens.stylex.js";
 import { focusVars, spacingVars } from "../theme/tokens.stylex.js";
@@ -37,6 +37,8 @@ import { SizeProvider } from "../SizeContext/SizeContext.js";
 import { useDevWarning } from "../hooks/useDevWarning.js";
 import { useTranslator } from "../i18n/index.js";
 import { useMergedRefs } from "../hooks/useMergedRefs.js";
+import { LayoutChangeSnapshot } from "../motion/LayoutChangeSnapshot.js";
+import { createRailLayout, playRail, snapshotRail, SideNavShellContext } from "./railMotion.js";
 // =============================================================================
 // Constants
 // =============================================================================
@@ -209,6 +211,52 @@ export function SideNav({
     onCollapseChange: onCollapsedChange
   });
   const collapsed = resizableHook.isCollapsed;
+
+  // Every collapse or expand, whatever caused it, plays the rail's motion
+  // (`component:SideNav` FR6): measured in the commit before the DOM changes,
+  // played after it before paint. Inside AppShell the content area moves with
+  // it through AppShell's own handle (`component:AppShell` FR17); outside,
+  // SideNav holds its own over its parent.
+  const shell = use(SideNavShellContext);
+  const ownLayout = useMemo(() => createRailLayout(() => navRef.current), []);
+  const railSnapshotRef = useRef(null);
+  const motionRef = useRef(null);
+  const measureRail = useCallback(wasCollapsed => {
+    // A change during a running motion starts from what the rail shows.
+    const running = motionRef.current;
+    const shown = running?.rail.shown() ?? null;
+    running?.rail.end();
+    running?.endContent();
+    motionRef.current = null;
+    railSnapshotRef.current = snapshotRail(shell?.rail() ?? navRef.current, shell?.animatedLayout ?? ownLayout, shown, wasCollapsed);
+    // A collapse covers the old rail with its copy; when the rail cannot
+    // be copied, the page lands at once with it, on one clock, a running
+    // glide included.
+    const snapshot = railSnapshotRef.current;
+    if (snapshot != null && snapshot.swap == null && !wasCollapsed) {
+      shell?.landContent();
+      return;
+    }
+    shell?.beforeRailChange();
+  }, [shell, ownLayout]);
+  useLayoutEffect(() => {
+    const snapshot = railSnapshotRef.current;
+    railSnapshotRef.current = null;
+    if (snapshot == null) {
+      return;
+    }
+    // The content moves first: its glide starts before the rail rides it.
+    const endContent = shell?.afterRailChange() ?? (() => {});
+    motionRef.current = {
+      rail: playRail(snapshot, shell?.rail() ?? navRef.current, shell?.animatedLayout ?? ownLayout, shell?.column() ?? null),
+      endContent
+    };
+  }, [collapsed, shell, ownLayout]);
+  // An unmount mid-motion removes the copy at once.
+  useLayoutEffect(() => () => {
+    motionRef.current?.rail.end();
+    motionRef.current?.endContent();
+  }, []);
   const toggle = useCallback(() => {
     const next = !collapsed;
 
@@ -410,7 +458,7 @@ export function SideNav({
   // Overlay drag handle inside the nav when resizable.
   // Uses ResizeHandle in overlay mode so the handle sits inside
   // the panel's overflow: clip bounds.
-  const content = showResizeHandle ? /*#__PURE__*/_jsxs("div", {
+  const rail = showResizeHandle ? /*#__PURE__*/_jsxs("div", {
     ...{
       className: "x1n2onr6 x78zum5 x2lah0s x5yr21d x7giv3"
     },
@@ -426,6 +474,14 @@ export function SideNav({
       "aria-controls": navId
     })]
   }) : navElement;
+  // The snapshot stays mounted outside the resize wrapper, which comes and
+  // goes with the collapse it measures.
+  const content = /*#__PURE__*/_jsxs(_Fragment, {
+    children: [/*#__PURE__*/_jsx(LayoutChangeSnapshot, {
+      value: collapsed,
+      onBeforeChange: measureRail
+    }), rail]
+  });
   if (isCollapsible) {
     return /*#__PURE__*/_jsx(SideNavCollapseContext, {
       value: collapseContext,

package/dist/SideNav/SideNavHeading.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SideNavHeading.d.ts","sourceRoot":"","sources":["../../src/SideNav/SideNavHeading.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAkB,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAsBtD,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,eAAe,CAAC;AAGrD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AA2N5C,MAAM,WAAW,mBAAoB,SAAQ,SAAS,CAAC,cAAc,CAAC;IACpE,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC;;OAEG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB;;;;OAIG;IACH,EAAE,CAAC,EAAE,iBAAiB,CAAC;IACvB;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;OAEG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;OAEG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,SAAS,CAAC;IAC7B;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC;CAClB;AAQD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,cAAc,CAAC,EAC7B,EAAE,EACF,IAAI,EACJ,OAAO,EACP,WAAW,EACX,YAAY,EACZ,gBAAgB,EAChB,UAAU,EACV,cAAc,EACd,gBAAgB,EAChB,IAAI,EACJ,MAAM,EACN,SAAS,EACT,KAAK,EACL,aAAa,EAAE,MAAM,EACrB,GAAG,EACH,GAAG,KAAK,EACT,EAAE,mBAAmB,sCAkgBrB;yBAnhBe,cAAc"}
+{"version":3,"file":"SideNavHeading.d.ts","sourceRoot":"","sources":["../../src/SideNav/SideNavHeading.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAkB,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAsBtD,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,eAAe,CAAC;AAGrD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAiP5C,MAAM,WAAW,mBAAoB,SAAQ,SAAS,CAAC,cAAc,CAAC;IACpE,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC;;OAEG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB;;;;OAIG;IACH,EAAE,CAAC,EAAE,iBAAiB,CAAC;IACvB;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;OAEG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;OAEG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,SAAS,CAAC;IAC7B;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC;CAClB;AAQD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,cAAc,CAAC,EAC7B,EAAE,EACF,IAAI,EACJ,OAAO,EACP,WAAW,EACX,YAAY,EACZ,gBAAgB,EAChB,UAAU,EACV,cAAc,EACd,gBAAgB,EAChB,IAAI,EACJ,MAAM,EACN,SAAS,EACT,KAAK,EACL,aAAa,EAAE,MAAM,EACrB,GAAG,EACH,GAAG,KAAK,EACT,EAAE,mBAAmB,sCA4kBrB;yBA7lBe,cAAc"}

package/dist/SideNav/SideNavHeading.js

@@ -39,14 +39,21 @@ import { useLinkComponent } from "../Link/useLinkComponent.js";
 import { mergeProps } from "../utils/index.js";
 import { useMergedRefs } from "../hooks/useMergedRefs.js";
 import { useMenuHover } from "../hooks/useMenuHover.js";
-import { NavHeadingCloseContext } from "../NavMenu/NavMenuContext.js";
+import { useMenuPress } from "../hooks/useMenuPress.js";
+import { pressOnItemsOnly } from "../hooks/menuPressOnItems.js";
+import { menuTouchActionStyles } from "../DropdownMenu/menuTouchAction.stylex.js";
+import { useMenuOverflow } from "../DropdownMenu/useMenuOverflow.js";
+import { NavHeadingCloseContext, NavHeadingDismissContext } from "../NavMenu/NavMenuContext.js";
 import { themeProps } from "../utils/themeProps.js";
 import { useTranslator } from "../i18n/index.js";
 
 // =============================================================================
 // Styles
 // =============================================================================
+
+/** The rows a press can act on in the heading's menu. */
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+const HEADING_MENU_ITEM_SELECTOR = '[role="menuitem"]:not([aria-disabled="true"])';
 const styles = {
   root: {
     k1xSpc: "x78zum5",
@@ -129,6 +136,17 @@ const styles = {
     kGuDYH: "x1qlqyl8",
     $$css: true
   },
+  linkBesideEndContent: {
+    k1xSpc: "x78zum5",
+    kGNEyG: "x6s0dn4",
+    kSGwAc: "xkh2ocl",
+    kOIVth: "x1txdalj",
+    kzQI83: "x1iyjqo2",
+    k7Eaqz: "xeuugli",
+    kybGjl: "x1hl2dhg",
+    kMwMTN: "x1heor9g",
+    $$css: true
+  },
   popoverHeading: {
     k1xSpc: "x78zum5",
     kGNEyG: "x6s0dn4",
@@ -273,6 +291,23 @@ export function SideNavHeading({
     // default-prevented: it holds the heading's own links.
     popoverId: isCollapsed ? popover.id : undefined
   });
+
+  // A press that slides across the menu's items acts on the item it lifts on,
+  // the highlight following the pointer (`family:action-groups` FR1-FR3,
+  // FR5); a mouse released outside closes it. Only the role="menu" region is
+  // tracked, not the heading button above it.
+  const headingMenuRef = useRef(null);
+  const headingMenuPress = useMenuPress({
+    menuRef: headingMenuRef,
+    itemSelector: HEADING_MENU_ITEM_SELECTOR,
+    onDismiss: closeMenu,
+    isEnabled: !!menu
+  });
+  const headingMenuPointerDown = pressOnItemsOnly(headingMenuPress.menuProps.onPointerDown, HEADING_MENU_ITEM_SELECTOR);
+  const dismissCtx = useMemo(() => ({
+    dismiss: closeMenu
+  }), [closeMenu]);
+  const headingMenuTouch = stylex.props(useMenuOverflow(headingMenuRef, menu, popover.isOpen) ? menuTouchActionStyles.scrolls : menuTouchActionStyles.fits);
   const closeMenuCtx = useMemo(() => ({
     closeMenu
   }), [closeMenu]);
@@ -372,8 +407,12 @@ export function SideNavHeading({
               })]
             })]
           }), /*#__PURE__*/_jsx("div", {
+            ref: headingMenuRef,
             role: "menu",
             "aria-label": heading,
+            ...headingMenuPress.menuProps,
+            onPointerDown: headingMenuPointerDown,
+            ...headingMenuTouch,
             children: /*#__PURE__*/_jsx(NavHeadingCloseContext, {
               value: closeMenuCtx,
               children: menu
@@ -484,6 +523,29 @@ export function SideNavHeading({
     }))]
   });
 
+  // Whole heading is a link (no menu, single headingHref). End content may
+  // be a control, which must not sit inside the link (no interactive content
+  // in an <a>), so with end content the row is a div holding the link and the
+  // end content side by side, as the mixed mode does.
+  if (isWholeHeadingLink && headingHref && headerEndContentElement) {
+    return /*#__PURE__*/_jsxs("div", {
+      ref: ref,
+      "data-testid": testId,
+      ...mergeProps(themeProps('side-nav-heading'), stylex.props(styles.root, xstyle), className, style),
+      children: [/*#__PURE__*/_jsxs(LinkComponent, {
+        href: headingHref,
+        ...focusOutlineProps.focusVisible(styles.linkBesideEndContent, styles.menuTrigger),
+        ...props,
+        children: [icon && /*#__PURE__*/_jsx("span", {
+          ...{
+            className: "x2lah0s x78zum5 x6s0dn4 xl56j7k"
+          },
+          children: icon
+        }), renderTextContent()]
+      }), headerEndContentElement]
+    });
+  }
+
   // Whole heading is a link (no menu, single headingHref)
   if (isWholeHeadingLink && headingHref) {
     return /*#__PURE__*/_jsxs(LinkComponent, {
@@ -538,9 +600,16 @@ export function SideNavHeading({
         },
         ...contentProps,
         children: [popoverHeadingContent, /*#__PURE__*/_jsx("div", {
+          ref: headingMenuRef,
           role: "menu",
           "aria-label": heading,
-          children: menu
+          ...headingMenuPress.menuProps,
+          onPointerDown: headingMenuPointerDown,
+          ...headingMenuTouch,
+          children: /*#__PURE__*/_jsx(NavHeadingDismissContext, {
+            value: dismissCtx,
+            children: menu
+          })
         })]
       }), {
         placement: 'below',
@@ -594,9 +663,16 @@ export function SideNavHeading({
         },
         ...contentProps,
         children: [popoverHeadingContent, /*#__PURE__*/_jsx("div", {
+          ref: headingMenuRef,
           role: "menu",
           "aria-label": heading,
-          children: menu
+          ...headingMenuPress.menuProps,
+          onPointerDown: headingMenuPointerDown,
+          ...headingMenuTouch,
+          children: /*#__PURE__*/_jsx(NavHeadingDismissContext, {
+            value: dismissCtx,
+            children: menu
+          })
         })]
       }), {
         placement: 'below',

package/dist/SideNav/SideNavItem.d.ts

@@ -6,7 +6,11 @@
  *
  * Navigation item with icon, selected state, row-level actions, and nesting.
  * Collapsed icon-only controls use a meaningful consumer `aria-label` when
- * provided and fall back to `label` when it is missing or blank.
+ * provided and fall back to `label` when it is missing or blank. Their label
+ * tooltip binds to the interactive control through a callback ref, so hover,
+ * keyboard focus, and `aria-describedby` follow the control from the first
+ * collapsed render. A disabled control takes neither pointer nor focus, so its
+ * row is the tooltip's trigger instead.
  *
  * Collapsed items with children open their submenu flyout through
  * `useMenuHover`, the shared hover-intent hook (same one `SideNavHeading` and

package/dist/SideNav/SideNavItem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SideNavItem.d.ts","sourceRoot":"","sources":["../../src/SideNav/SideNavItem.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAQL,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAYf,OAAO,EAAuB,KAAK,QAAQ,EAAC,MAAM,SAAS,CAAC;AAE5D,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,eAAe,CAAC;AAIrD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAE5C,OAAO,EAAgB,KAAK,WAAW,EAAC,MAAM,iCAAiC,CAAC;AA4ShF,MAAM,WAAW,gBAAiB,SAAQ,SAAS,CAAC,WAAW,CAAC;IAC9D,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IAC7B;;;;OAIG;IACH,EAAE,CAAC,EAAE,iBAAiB,CAAC;IACvB;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;OAEG;IACH,IAAI,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC;IAC5B;;OAEG;IACH,YAAY,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC;IACpC;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;OAEG;IACH,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;IACxC;;;;OAIG;IACH,UAAU,CAAC,EAAE,SAAS,CAAC;IACvB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,EAAE,SAAS,CAAC;IACpB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB;;;;;;;;;;OAUG;IACH,WAAW,CAAC,EACR,OAAO,GACP;QACE,kBAAkB,CAAC,EAAE,OAAO,CAAC;QAC7B,WAAW,CAAC,EAAE,OAAO,CAAC;QACtB,iBAAiB,CAAC,EAAE,CAAC,WAAW,EAAE,OAAO,KAAK,IAAI,CAAC;KACpD,CAAC;IACN;;;OAGG;IACH,IAAI,CAAC,EAAE,WAAW,CAAC;CACpB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,WAAW,CAAC,EAC1B,EAAE,EACF,KAAK,EACL,IAAI,EACJ,YAAY,EACZ,UAAkB,EAClB,UAAkB,EAClB,IAAI,EACJ,OAAO,EACP,UAAU,EACV,OAAO,EACP,QAAQ,EACR,WAAW,EAAE,eAAe,EAC5B,IAAW,EACX,aAAa,EAAE,MAAM,EACrB,GAAG,EACH,MAAM,EACN,GAAG,IAAI,EACR,EAAE,gBAAgB,sCAqalB;yBAvbe,WAAW"}
+{"version":3,"file":"SideNavItem.d.ts","sourceRoot":"","sources":["../../src/SideNav/SideNavItem.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAOL,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAYf,OAAO,EAAuB,KAAK,QAAQ,EAAC,MAAM,SAAS,CAAC;AAE5D,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,eAAe,CAAC;AAIrD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAE5C,OAAO,EAAgB,KAAK,WAAW,EAAC,MAAM,iCAAiC,CAAC;AAkThF,MAAM,WAAW,gBAAiB,SAAQ,SAAS,CAAC,WAAW,CAAC;IAC9D,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IAC7B;;;;OAIG;IACH,EAAE,CAAC,EAAE,iBAAiB,CAAC;IACvB;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;OAEG;IACH,IAAI,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC;IAC5B;;OAEG;IACH,YAAY,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC;IACpC;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;OAEG;IACH,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;IACxC;;;;OAIG;IACH,UAAU,CAAC,EAAE,SAAS,CAAC;IACvB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,EAAE,SAAS,CAAC;IACpB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB;;;;;;;;;;OAUG;IACH,WAAW,CAAC,EACR,OAAO,GACP;QACE,kBAAkB,CAAC,EAAE,OAAO,CAAC;QAC7B,WAAW,CAAC,EAAE,OAAO,CAAC;QACtB,iBAAiB,CAAC,EAAE,CAAC,WAAW,EAAE,OAAO,KAAK,IAAI,CAAC;KACpD,CAAC;IACN;;;OAGG;IACH,IAAI,CAAC,EAAE,WAAW,CAAC;CACpB;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,WAAW,CAAC,EAC1B,EAAE,EACF,KAAK,EACL,IAAI,EACJ,YAAY,EACZ,UAAkB,EAClB,UAAkB,EAClB,IAAI,EACJ,OAAO,EACP,UAAU,EACV,OAAO,EACP,QAAQ,EACR,WAAW,EAAE,eAAe,EAC5B,IAAW,EACX,aAAa,EAAE,MAAM,EACrB,GAAG,EACH,MAAM,EACN,GAAG,IAAI,EACR,EAAE,gBAAgB,sCA2blB;yBA7ce,WAAW"}

package/dist/SideNav/SideNavItem.js

@@ -10,7 +10,11 @@
  *
  * Navigation item with icon, selected state, row-level actions, and nesting.
  * Collapsed icon-only controls use a meaningful consumer `aria-label` when
- * provided and fall back to `label` when it is missing or blank.
+ * provided and fall back to `label` when it is missing or blank. Their label
+ * tooltip binds to the interactive control through a callback ref, so hover,
+ * keyboard focus, and `aria-describedby` follow the control from the first
+ * collapsed render. A disabled control takes neither pointer nor focus, so its
+ * row is the tooltip's trigger instead.
  *
  * Collapsed items with children open their submenu flyout through
  * `useMenuHover`, the shared hover-intent hook (same one `SideNavHeading` and
@@ -29,7 +33,7 @@
  * - /apps/storybook/stories/SideNav.stories.tsx
  * - /packages/cli/assets/templates/blocks/components/SideNav/ (showcase blocks)
  */
-import { createContext, use, useCallback, useId, useMemo, useRef, useState } from 'react';
+import { createContext, use, useCallback, useId, useMemo, useState } from 'react';
 import * as stylex from '@stylexjs/stylex';
 import "../theme/tokens.stylex.js";
 import { colorVars, spacingVars, sizeVars, fontWeightVars, typeScaleVars, durationVars, easeVars, radiusVars } from "../theme/tokens.stylex.js";
@@ -38,7 +42,7 @@ import { useLinkComponent } from "../Link/useLinkComponent.js";
 import { usePopover } from "../Popover/usePopover.js";
 import { useMenuHover } from "../hooks/useMenuHover.js";
 import { mergeProps } from "../utils/index.js";
-import { Tooltip } from "../Tooltip/index.js";
+import { useTooltip } from "../Tooltip/index.js";
 import { navItemStyles } from "../NavItem/navItemStyles.stylex.js";
 import { SizeProvider } from "../SizeContext/SizeContext.js";
 import { focusOutlineProps } from "../utils/focusOutline.stylex.js";
@@ -233,6 +237,12 @@ function NavItemElement({
   });
 }
 
+/** Joins the non-empty ids into one `aria-describedby` value. */
+function joinIds(...ids) {
+  const joined = ids.filter(Boolean).join(' ');
+  return joined === '' ? undefined : joined;
+}
+
 // =============================================================================
 // Types
 // =============================================================================
@@ -304,7 +314,6 @@ export function SideNavItem({
   const isInDrawer = renderMode === 'drawer' || renderMode === 'drawer-content';
   const id = useId();
   const hasChildren = !!children;
-  const itemRef = useRef(null);
   const depth = use(SideNavItemDepthContext);
 
   // Popover for collapsed items with children
@@ -318,6 +327,19 @@ export function SideNavItem({
   });
   const mergedTriggerRef = useMergedRefs(ref, popover.triggerRef);
 
+  // Label tooltip for a collapsed leaf. It binds through a callback ref and
+  // its id renders as an `aria-describedby` prop, so both follow the element
+  // they describe across re-renders. The hook outlives the collapsed branch,
+  // so it is held shut whenever the item is not a collapsed leaf: a tooltip
+  // open when the rail expands must not come back on the next collapse.
+  const isRailLeaf = isCollapsed && !hasChildren;
+  const railTooltip = useTooltip({
+    placement: 'end',
+    isEnabled: isRailLeaf,
+    isOpen: isRailLeaf ? undefined : false
+  });
+  const railLeafRef = useMergedRefs(ref, railTooltip.ref);
+
   // Collapse state for items with children
   const itemCollapsibleConfig = useMemo(() => typeof itemCollapsible === 'object' ? itemCollapsible : {}, [itemCollapsible]);
   const isItemCollapsible = hasChildren && itemCollapsible !== false;
@@ -453,15 +475,20 @@ export function SideNavItem({
       });
     }
 
-    // Items without children: icon-only link/button with tooltip
+    // Items without children: icon-only link or button, its label in a
+    // tooltip. The control is the trigger, so the element that takes focus is
+    // the one described. A disabled control takes neither pointer
+    // (`navItemStyles.disabled`) nor focus, so its row is the trigger instead.
+    const isRowTrigger = isDisabled;
     const collapsedAriaProps = {
       'aria-current': isSelected ? 'page' : undefined,
+      'aria-describedby': isRowTrigger ? rest['aria-describedby'] : joinIds(rest['aria-describedby'], railTooltip.describedBy),
       'aria-disabled': isDisabled || undefined,
       'aria-label': collapsedAccessibleLabel,
       'data-testid': testId
     };
     const collapsedElement = /*#__PURE__*/_jsx(NavItemElement, {
-      ref: ref,
+      ref: isRowTrigger ? ref : railLeafRef,
       href: href,
       as: as,
       isDisabled: isDisabled,
@@ -472,13 +499,10 @@ export function SideNavItem({
       children: collapsedIcon
     });
     return /*#__PURE__*/_jsxs("div", {
-      ref: itemRef,
+      ref: isRowTrigger ? railTooltip.ref : undefined,
+      "aria-describedby": isRowTrigger ? railTooltip.describedBy : undefined,
       ...stylex.props(styles.root, xstyle),
-      children: [collapsedElement, /*#__PURE__*/_jsx(Tooltip, {
-        content: label,
-        placement: "end",
-        anchorRef: itemRef
-      })]
+      children: [collapsedElement, railTooltip.renderTooltip(label)]
     });
   }
   const itemContent = /*#__PURE__*/_jsxs(_Fragment, {
@@ -628,7 +652,6 @@ export function SideNavItem({
     });
   }
   const item = /*#__PURE__*/_jsxs("div", {
-    ref: itemRef,
     ...stylex.props(styles.root, xstyle),
     children: [itemElement, hasChildren && !isCollapsed && /*#__PURE__*/_jsx("div", {
       id: `${id}-children`,

package/dist/SideNav/railMotion.d.ts

@@ -0,0 +1,54 @@
+import { type AnimatedLayout, type LayoutSwap } from '../motion/animatedLayout.js';
+/** What AppShell lends its SideNav; outside AppShell, nothing. */
+export interface SideNavShell {
+    /** AppShell's own handle, whose area holds the rail and the content. */
+    readonly animatedLayout: AnimatedLayout;
+    /** The rail's outer element, which paints its background. */
+    rail(): HTMLElement | null;
+    /** The content column beside the rail, which glides. */
+    column(): HTMLElement | null;
+    /** In the commit, before the DOM changes: the content measures itself. */
+    beforeRailChange(): void;
+    /** After it, before paint: the content moves; returns what ends it. */
+    afterRailChange(): () => void;
+    /** The content lands where it is laid out, ending any running glide. */
+    landContent(): void;
+}
+export declare const SideNavShellContext: import("react").Context<SideNavShell | null>;
+/** A SideNav outside AppShell holds its own handle over its parent. */
+export declare function createRailLayout(rail: () => HTMLElement | null): AnimatedLayout;
+/** What a rail shows: at rest, or partway through a motion. */
+export interface RailShown {
+    readonly width: number;
+    /** The labels' opacity. */
+    readonly labels: number;
+    /** The collapsed rail's opacity (its icons). */
+    readonly collapsed: number;
+}
+export interface RailSnapshot {
+    readonly rail: HTMLElement;
+    readonly railRect: DOMRect;
+    /** What the rail shows when the change lands. */
+    readonly shown: RailShown;
+    /** The old rail, held by the swap. */
+    readonly swap: LayoutSwap | null;
+}
+/** A playing rail motion. */
+export interface RailMotion {
+    /** Ends it at once (a new change, an unmount). */
+    end(): void;
+    /** What the rail shows now, or null once it has settled. */
+    shown(): RailShown | null;
+}
+/**
+ * Before the change commits: the old rail, where it was, and what it shows,
+ * from a running motion or at rest.
+ */
+export declare function snapshotRail(rail: HTMLElement | null, handle: AnimatedLayout, running: RailShown | null, isCollapsed: boolean): RailSnapshot | null;
+/**
+ * After the change commits, before paint: play the rail's motion from the
+ * snapshot, on the module's motion. With a `column` (in AppShell), the rail's
+ * edge rides its glide.
+ */
+export declare function playRail(snapshot: RailSnapshot, current: HTMLElement | null, handle: AnimatedLayout, column?: HTMLElement | null): RailMotion;
+//# sourceMappingURL=railMotion.d.ts.map

package/dist/SideNav/railMotion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"railMotion.d.ts","sourceRoot":"","sources":["../../src/SideNav/railMotion.ts"],"names":[],"mappings":"AA4CA,OAAO,EAML,KAAK,cAAc,EACnB,KAAK,UAAU,EAChB,MAAM,0BAA0B,CAAC;AAElC,kEAAkE;AAClE,MAAM,WAAW,YAAY;IAC3B,wEAAwE;IACxE,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;IACxC,6DAA6D;IAC7D,IAAI,IAAI,WAAW,GAAG,IAAI,CAAC;IAC3B,wDAAwD;IACxD,MAAM,IAAI,WAAW,GAAG,IAAI,CAAC;IAC7B,0EAA0E;IAC1E,gBAAgB,IAAI,IAAI,CAAC;IACzB,uEAAuE;IACvE,eAAe,IAAI,MAAM,IAAI,CAAC;IAC9B,wEAAwE;IACxE,WAAW,IAAI,IAAI,CAAC;CACrB;AAED,eAAO,MAAM,mBAAmB,8CAA2C,CAAC;AAG5E,uEAAuE;AACvE,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,WAAW,GAAG,IAAI,GAC7B,cAAc,CAEhB;AAED,+DAA+D;AAC/D,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,2BAA2B;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,gDAAgD;IAChD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,iDAAiD;IACjD,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,sCAAsC;IACtC,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,CAAC;CAClC;AAED,6BAA6B;AAC7B,MAAM,WAAW,UAAU;IACzB,kDAAkD;IAClD,GAAG,IAAI,IAAI,CAAC;IACZ,4DAA4D;IAC5D,KAAK,IAAI,SAAS,GAAG,IAAI,CAAC;CAC3B;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,WAAW,GAAG,IAAI,EACxB,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,SAAS,GAAG,IAAI,EACzB,WAAW,EAAE,OAAO,GACnB,YAAY,GAAG,IAAI,CAerB;AAwBD;;;;GAIG;AACH,wBAAgB,QAAQ,CACtB,QAAQ,EAAE,YAAY,EACtB,OAAO,EAAE,WAAW,GAAG,IAAI,EAC3B,MAAM,EAAE,cAAc,EACtB,MAAM,GAAE,WAAW,GAAG,IAAW,GAChC,UAAU,CAsJZ"}