@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/src/BottomSheet/useSheetGestures.ts

@@ -4,8 +4,7 @@
 
 /**
  * @file useSheetGestures.ts
- * @input Uses React (useCallback, useEffect, useMemo, useRef, useState) and
- *   the core useMediaQuery hook
+ * @input Uses React (useCallback, useEffect, useMemo, useRef, useState)
  * @output Exports useSheetGestures hook and its option/result types
  * @position Internal to BottomSheet; not exported from the core entry point
  *
@@ -85,7 +84,7 @@ import {
   type TouchEvent as ReactTouchEvent,
   type UIEvent as ReactUIEvent,
 } from 'react';
-import {useMediaQuery} from '../hooks';
+
 import {
   computeDetentOffsets,
   peekOffsetFor,
@@ -299,6 +298,13 @@ function visibleHeightForOffset(
 export interface UseSheetGesturesOptions {
   /** Whether the owning sheet is open. Drag state resets when it closes. */
   isOpen: boolean;
+  /**
+   * The host's controlled answer to the last close request: false once the
+   * host has taken a dismissal (its own state says closed, even while the
+   * sheet still animates out), true while it is open or has refused one.
+   * Settles whether a release's dismissal was honored. Defaults to `isOpen`.
+   */
+  isOpenRequested?: boolean;
   /**
    * Whether a downward swipe may dismiss the sheet. When false, a gesture
    * past the dismiss threshold settles at the shortest detent instead.
@@ -401,6 +407,16 @@ export interface UseSheetGesturesResult {
   isDragging: boolean;
   /** Whether the drag in progress has moved the sheet off its base detent. */
   isTraveling: boolean;
+  /**
+   * Whether the sheet's current dismissal was started by the release of a
+   * touch drag (a finger's swipe or fling past the dismiss line). True from
+   * the release until the sheet is open again; false for a dismissal from a
+   * control, Escape, the scrim or code, and for a mouse or pen drag. Under
+   * reduced motion a transition a touch drag's release starts cross-fades on
+   * every pointer (`design:reduced-motion` DR2), so the exit's motion needs
+   * to know.
+   */
+  isDismissedByTouchDrag: boolean;
   /**
    * The sheet's offset right now, in px: the settled detent at rest, the live
    * position during a drag. Written per input sample without a render; read
@@ -458,6 +474,7 @@ function prefersReducedMotion(): boolean {
  */
 export function useSheetGestures({
   isOpen,
+  isOpenRequested = isOpen,
   canDismiss = true,
   offscreenBlockEndInset = 0,
   onDismiss,
@@ -468,6 +485,35 @@ export function useSheetGestures({
   const [dragOffset, setDragOffset] = useState(0);
   const [settledOffset, setSettledOffset] = useState(0);
   const [isDragging, setIsDragging] = useState(false);
+  // Scoped to the one close the release requested. The release calls
+  // onDismiss() and sets `pending`; the host answers in the same update, so
+  // the first render afterwards says whether it took the close (its
+  // controlled state now says closed: the exit under way is the drag's) or
+  // refused it (a guarded onOpenChange left it open: the sheet snaps back and
+  // the request is spent). Either way the flag is settled during render, the
+  // prev-prop pattern, and derived back to false once the sheet is open
+  // again — so a later close from a control, Escape or code is never
+  // mistaken for a drag.
+  const [touchDragDismissal, setTouchDragDismissal] = useState<{
+    isTouch: boolean;
+    pending: boolean;
+  } | null>(null);
+  if (touchDragDismissal != null) {
+    if (touchDragDismissal.pending) {
+      setTouchDragDismissal(
+        isOpenRequested
+          ? null
+          : {isTouch: touchDragDismissal.isTouch, pending: false},
+      );
+    } else if (isOpenRequested) {
+      setTouchDragDismissal(null);
+    }
+  }
+  const isDismissedByTouchDrag =
+    touchDragDismissal != null &&
+    !touchDragDismissal.pending &&
+    touchDragDismissal.isTouch &&
+    !isOpenRequested;
   // Whether the drag in flight has moved the sheet off its base detent. One
   // state change per drag, for hosts that react to travel beginning.
   const [isTraveling, setIsTraveling] = useState(false);
@@ -597,6 +643,8 @@ export function useSheetGestures({
     // capture and takes its events from `touchmove`, so every real-pointer
     // handler has to leave it alone.
     syntheticTouch: boolean;
+    /** The pointer's kind: a finger, a pen, or a mouse. */
+    pointerType: string;
     pointerId: number;
     startCoord: number;
     lastCoord: number;
@@ -930,6 +978,10 @@ export function useSheetGestures({
   );
 
   useEffect(() => {
+    // Only an open sheet can be dragged; a closed one listens to nothing.
+    if (!isOpen) {
+      return;
+    }
     const handleWindowBlur = () => cancelDrag();
     const handleVisibilityChange = () => {
       if (document.visibilityState === 'hidden') {
@@ -942,7 +994,7 @@ export function useSheetGestures({
       window.removeEventListener('blur', handleWindowBlur);
       document.removeEventListener('visibilitychange', handleVisibilityChange);
     };
-  }, [cancelDrag]);
+  }, [cancelDrag, isOpen]);
 
   const settleFromDrag = useCallback(
     (
@@ -956,6 +1008,7 @@ export function useSheetGestures({
       renderedOffset: number,
       layoutOffset: number,
       naturalEndGap: number,
+      isTouch: boolean,
     ) => {
       const {offsets, peekOffset} = resolveDetents(height);
       const maxOffset = offsets[offsets.length - 1];
@@ -1014,6 +1067,7 @@ export function useSheetGestures({
             naturalEndGap,
             false,
           );
+          setTouchDragDismissal({isTouch, pending: true});
           onDismissRef.current();
         } else {
           settleAt(maxOffset);
@@ -1056,6 +1110,7 @@ export function useSheetGestures({
       const baseLayoutOffset = settledLayoutOffsetRef.current;
       dragStateRef.current = {
         syntheticTouch,
+        pointerType: syntheticTouch ? 'touch' : event.pointerType,
         pointerId: event.pointerId,
         startCoord: start,
         lastCoord: event.clientY,
@@ -1254,6 +1309,7 @@ export function useSheetGestures({
         state.renderedOffset,
         state.layoutOffset,
         state.naturalEndGap,
+        state.pointerType === 'touch',
       );
     },
     [settleFromDrag],
@@ -1578,11 +1634,6 @@ export function useSheetGestures({
     }
   }, []);
 
-  // Subscribed, not memoized: the preference can change while a sheet is open,
-  // and this branch decides whether the settle runs as a transition at all.
-  // The imperative gesture paths read prefersReducedMotion() directly.
-  const reducedMotion = useMediaQuery('(prefers-reduced-motion: reduce)');
-
   const reconcileScrollPreservationInset = useCallback(
     (body: HTMLElement) => {
       if (scrollPreservationInsetRef.current <= 0) {
@@ -1674,9 +1725,13 @@ export function useSheetGestures({
         // Gated on the sheet being up: suppression must not outlive the sheet
         // it was suppressing for. The host swaps the panel to its closing
         // state in whatever frame the dismissal lands, and a stale `none`
-        // would apply to that transform too, cutting the exit.
+        // would apply to that transform too, cutting the exit. Reduced motion
+        // is the panel's own stylesheet's to honor (its transform transition
+        // collapses under the preference), not an inline `none` here: the
+        // shorthand would also silence the panel's opacity transition, the
+        // cross-fade `design:reduced-motion` DR2 asks for on a coarse pointer.
         transition:
-          isOpen && (isDragging || isScrollAreaReconciling || reducedMotion)
+          isOpen && (isDragging || isScrollAreaReconciling)
             ? 'none'
             : undefined,
         // One-finger drags are the sheet's; a pinch stays the browser's.
@@ -1684,7 +1739,7 @@ export function useSheetGestures({
         overscrollBehavior: 'contain',
       },
     }),
-    [activeOffset, isDragging, isOpen, isScrollAreaReconciling, reducedMotion],
+    [activeOffset, isDragging, isOpen, isScrollAreaReconciling],
   );
 
   const handleProps = useMemo<SheetHandleProps>(
@@ -1742,6 +1797,7 @@ export function useSheetGestures({
     settledOffset,
     isDragging,
     isTraveling,
+    isDismissedByTouchDrag,
     activeOffsetRef,
     sheetHeight,
     scrollPreservationInset,

package/src/Breadcrumbs/BreadcrumbItem.spec.md

@@ -1,25 +1,32 @@
 ---
 schema_version: 3
-template_version: 4
+template_version: 7
 kind: component
 id: component:BreadcrumbItem
-authority: draft
+authority: current
 archive_reason: null
 superseded_by: null
-approved_by: null
-approved_at: null
+approved_by: cixzhang
+approved_at: 2026-10-27
 owners: [cixzhang]
 review_triggers: [public-api, behavior, layout, theming, accessibility]
 verified_by:
   [
     packages/core/src/Breadcrumbs/Breadcrumbs.test.tsx,
+    packages/core/src/Breadcrumbs/__tests__/Breadcrumbs.a11y.test.tsx,
+    packages/core/src/Breadcrumbs/__tests__/Breadcrumbs.a11y.chromium.spec.ts,
     apps/storybook/stories/BreadcrumbItem.stories.tsx,
     packages/core/src/theme/themingTargets.test.ts,
     scripts/check-knowledge.mjs,
   ]
 modules: []
-families: [family:navigation-destinations, family:overlay-dismissal]
-design_specs: []
+families:
+  [
+    family:navigation-destinations,
+    family:overlay-dismissal,
+    family:action-groups,
+  ]
+design_specs: [design:bidirectionality]
 architecture:
   [
     architecture:component-style-authoring,
@@ -31,28 +38,52 @@ architecture:
     architecture:react-component-runtime,
   ]
 contributing: [contributing:api-conventions]
-system_specs: [spec:AST-002, spec:AST-005, spec:AST-029]
+system_specs: [spec:AST-002, spec:AST-005]
 ---
 
 # BreadcrumbItem component contract
 
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                                                                                           |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | `BreadcrumbItem` with `children`, `href`, `as`, `onClick`, `isCurrent`, `startIcon`, `menu`, and `menuSize`; targets `breadcrumb-item`, `breadcrumb-item-menu-trigger`, and `breadcrumb-menu`.                                                     |
+| Behavior                | One crumb: a link, a link-styled button, plain text, the current page, or a sibling-menu trigger, chosen by ORD1. It renders its own decorative separator, hidden on the first crumb. The last crumb becomes current when no crumb says otherwise. |
+| End-user impact         | Users move up the hierarchy, open sibling destinations from a crumb's menu, and hear which crumb is the current page.                                                                                                                              |
+| Builder impact          | None.                                                                                                                                                                                                                                              |
+| Compatibility/readiness | Records shipped behavior; no public change. Two implementation gaps: automatic current-page state is applied after render, and can land on the list item (see Current-state impact).                                                               |
+| Review checks           | Reject a current item without `aria-current="page"` on its content owner (apart from the recorded `<li>` fallback), an exposed separator, a menu without its name, state, and control link, or menu closing that steals valid outside focus.       |
+| Governing rules         | `component:Breadcrumbs`; `family:navigation-destinations`; `family:overlay-dismissal`; `component:Popover`; `design:bidirectionality` DR4; `architecture:react-component-runtime` INV1.                                                            |
+
+This table is a review projection; the body below is authoritative.
+
 ## Intent
 
-BreadcrumbItem presents one destination, action, current location, or sibling-menu
-trigger inside a Breadcrumbs trail. This observational draft records verified
-released behavior and current shared obligations without changing public API,
-defaults, or the component's visual design.
+BreadcrumbItem presents one destination, action, current location, or
+sibling-menu trigger inside a Breadcrumbs trail. Consumer usage lives in
+`BreadcrumbItem.doc.mjs`.
 
 ## Compatibility and migration
 
 - Released default preserved: `yes`
-- Compatibility class: additive observational documentation plus bug fixes that
-  preserve the released public surface
+- Compatibility class: records shipped behavior; no public change
 - Controlled/uncontrolled behavior: not applicable
 - Migration decision: none
 
 Consumer migration instructions belong in consumer docs and release notes.
 
+## Current-state impact
+
+- **Automatic current state is repaired after render.** When no crumb sets
+  `isCurrent`, the last crumb first renders without `aria-current` and an
+  Effect then inspects the sibling list in the DOM and adds `aria-current="page"`.
+  `architecture:react-component-runtime` INV1 requires rendered output to start
+  from a valid state rather than be repaired in a follow-up Effect.
+- **Auto-current can land on the list item.** When the last crumb renders
+  through a custom `as` or `LinkProvider` link that does not forward its ref,
+  the auto-current repair sets `aria-current="page"` on the `<li>` and none on
+  the link, so the link is not announced as the current page (FR3, AR2).
+
 ## Ownership boundary
 
 **Owns**
@@ -81,33 +112,31 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 ## Public concepts
 
-| Concept       | Closed values or states                            | Meaning                                                                                                                         | Availability by variant/orientation/state | Default                                         | Owner                                          | Stability                                       | Invalid-value behavior                                                                     |
-| ------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | ----------------------------------------------- | ---------------------------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------ |
-| Item content  | required `ReactNode`                               | Supplies the visible item label and may contain caller-owned content.                                                           | Every item branch                         | Required                                        | `component:BreadcrumbItem`                     | Released                                        | React renders the supplied node.                                                           |
-| Destination   | supplied or absent `href`                          | Selects the shared link path when the item is not explicitly current and has no menu.                                           | Default and supporting variants           | Absent                                          | `family:navigation-destinations`               | Released                                        | Shared link handling decides accepted destinations.                                        |
-| Action        | supplied or absent `onClick`                       | Selects a native link-styled button when no destination or menu is supplied, or augments the link path when `href` is supplied. | Non-current items                         | Absent                                          | `component:BreadcrumbItem`                     | Released                                        | `menu` currently suppresses this input and warns in development.                           |
-| Current page  | `true`, `false`, or omitted                        | `true` explicitly marks the item current; `false` opts it out; omission makes the item an auto-current candidate.               | Every branch, including a menu trigger    | Omitted                                         | `component:BreadcrumbItem`                     | Released observation; intent review pending     | When no item is explicitly current, the omitted final item receives `aria-current="page"`. |
-| Link renderer | per-item `as`, provider renderer, or native anchor | Selects the component that receives an accepted destination.                                                                    | Non-current link path                     | Provider renderer, then native anchor           | `family:navigation-destinations`               | Released                                        | Explicitly current and menu paths do not use it.                                           |
-| Start content | supplied or absent `startIcon`                     | Renders caller content before the item label.                                                                                   | Every item branch                         | Absent                                          | Caller                                         | Released                                        | Caller content remains caller-owned.                                                       |
-| Sibling menu  | data array, composed menu content, or absent       | Replaces the link/action content branch with a menu button and menu surface.                                                    | Current or non-current item               | Absent                                          | `component:BreadcrumbItem`; menu rows delegate | Released observation; precedence review pending | Currently suppresses `href` or `onClick` and warns in development.                         |
-| Menu size     | `sm`, `md`, or `lg`                                | Selects the delegated menu-row size.                                                                                            | Menu branch                               | `sm` for supporting Breadcrumbs; otherwise `md` | `component:BreadcrumbItem`                     | Released                                        | TypeScript rejects unsupported values.                                                     |
+| Concept       | Closed values or states                            | Meaning                                                                                                                         | Availability by variant/orientation/state | Default                                         | Owner                                          | Stability | Invalid-value behavior                                                                                    |
+| ------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | ----------------------------------------------- | ---------------------------------------------- | --------- | --------------------------------------------------------------------------------------------------------- |
+| Item content  | required `ReactNode`                               | Supplies the visible item label and may contain caller-owned content.                                                           | Every item branch                         | Required                                        | `component:BreadcrumbItem`                     | Released  | React renders the supplied node.                                                                          |
+| Destination   | supplied or absent `href`                          | Selects the shared link path when the item is not explicitly current and has no menu.                                           | Default and supporting variants           | Absent                                          | `family:navigation-destinations`               | Released  | Shared link handling decides accepted destinations.                                                       |
+| Action        | supplied or absent `onClick`                       | Selects a native link-styled button when no destination or menu is supplied, or augments the link path when `href` is supplied. | Non-current items                         | Absent                                          | `component:BreadcrumbItem`                     | Released  | `menu` currently suppresses this input and warns in development.                                          |
+| Current page  | `true`, `false`, or omitted                        | `true` explicitly marks the item current; `false` opts it out; omission makes the item an auto-current candidate.               | Every branch, including a menu trigger    | Omitted                                         | `component:BreadcrumbItem`                     | Released  | When no item is explicitly current, the last crumb receives `aria-current="page"` when it omits the prop. |
+| Link renderer | per-item `as`, provider renderer, or native anchor | Selects the component that receives an accepted destination.                                                                    | Non-current link path                     | Provider renderer, then native anchor           | `family:navigation-destinations`               | Released  | Explicitly current and menu paths do not use it.                                                          |
+| Start content | supplied or absent `startIcon`                     | Renders caller content before the item label.                                                                                   | Every item branch                         | Absent                                          | Caller                                         | Released  | Caller content remains caller-owned.                                                                      |
+| Sibling menu  | data array, composed menu content, or absent       | Replaces the link/action content branch with a menu button and menu surface.                                                    | Current or non-current item               | Absent                                          | `component:BreadcrumbItem`; menu rows delegate | Released  | Currently suppresses `href` or `onClick` and warns in development.                                        |
+| Menu size     | `sm`, `md`, or `lg`                                | Selects the delegated menu-row size.                                                                                            | Menu branch                               | `sm` for supporting Breadcrumbs; otherwise `md` | `component:BreadcrumbItem`                     | Released  | TypeScript rejects unsupported values.                                                                    |
 
 ## Behavioral and layout contract
 
-Draft requirements identify their basis so observed code is not mistaken for an
-intentional decision.
-
-| ID  | Candidate invariant                                                                                                                                                                                                                   | Basis                                                                                  | Draft review state                                                                                          |
-| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
-| FR1 | The item root MUST remain one `<li>` carrying the public ref, item theme target, variant reflection, styling escape hatches, and neutral DOM pass-throughs.                                                                           | Released types, source, docs, and tests; `architecture:public-component-api`           | Verified current behavior; no API change proposed                                                           |
-| FR2 | A non-current item with `href` and no menu MUST use the shared link renderer; an item with only `onClick` MUST use a native button; an item with neither MUST render text content.                                                    | Released source, docs, and tests                                                       | Verified current behavior                                                                                   |
-| FR3 | Explicit `isCurrent=true` MUST expose `aria-current="page"`; explicit `false` MUST opt out; when every item omits the prop, the final item MUST receive the same current-page state.                                                  | Released source, docs, and tests                                                       | Verified current behavior; whether auto-detection remains the intended long-term default needs owner review |
-| FR4 | Every item MUST render one decorative separator container; the first item hides it. The built-in slash mirrors exactly once in RTL, while caller-provided separators remain caller-owned.                                             | Source, focused tests, and objective bidi behavior                                     | Verified current behavior                                                                                   |
-| FR5 | A menu item MUST expose one named menu button, current expanded state, control relationship, and one named `role="menu"` surface. Click, Enter, Space, and ArrowDown open it and focus its first item; Escape and selection close it. | APG Menu Button pattern, current Popover contract, source, tests, and browser evidence | Settled objective behavior                                                                                  |
-| FR6 | Closing the menu MUST preserve a newly focused outside control. Focus returns to the trigger only when the closing surface would otherwise strand focus.                                                                              | `component:Popover/AR4` and browser focus behavior                                     | Settled objective behavior                                                                                  |
-| FR7 | The menu branch MUST delegate item rendering, selection, typeahead, row focus, and submenu content to the shared DropdownMenu pipeline.                                                                                               | Released source and focused tests                                                      | Verified current behavior; DropdownMenu's draft contract remains context only                               |
-| FR8 | Omitted `menuSize` MUST resolve from the parent variant before entering DropdownMenu context.                                                                                                                                         | Released source and consumer docs                                                      | Verified current behavior                                                                                   |
-| FR9 | The current local targets MUST remain `breadcrumb-item`, `breadcrumb-item-menu-trigger`, and `breadcrumb-menu`, each on its current visible style owner with `variant` reflected where applicable.                                    | Released docs, source, and theming tests                                               | Verified current inventory; no target change proposed                                                       |
+| ID   | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Basis                                                                             |
+| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| FR1  | The item root is one `<li>` carrying the public ref, the `breadcrumb-item` target with the trail's variant, `data-testid`, styling escape hatches, and other DOM props.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Released types, source, docs, and tests; `architecture:public-component-api`      |
+| FR2  | A non-current item with `href` and no menu uses the shared link renderer, with `onClick` on the link; an item with only `onClick` uses a native button styled as a link; an item with neither renders text content.                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Released source, docs, and tests                                                  |
+| FR3  | Explicit `isCurrent=true` renders the content as text (or the menu trigger) carrying `aria-current="page"` and ignores `href` and `onClick`; explicit `false` opts out; when no item in the list carries `aria-current="page"`, the list's last child, if it omits the prop, receives it on its content owner (Current-state impact records the fallback to the `<li>`); a trail whose last child sets `isCurrent={false}` has no current crumb.                                                                                                                                                                                                                            | Released source, docs, and tests                                                  |
+| FR4  | Every item renders one `aria-hidden` separator container before its content, hidden on the first item. The built-in `/` mirrors exactly once in RTL; caller-provided separators render as given.                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Source, focused tests, and `design:bidirectionality` DR4                          |
+| FR5  | A menu item exposes one menu button with `aria-haspopup="menu"`, its expanded state, and `aria-controls`, and one `role="menu"` surface labelled by the trigger, including non-string trigger content. Click, Enter, Space, and ArrowDown open it and focus its first item; Escape, Tab, and selection close it; arrows move between items without wrapping, and typeahead jumps to a matching item.                                                                                                                                                                                                                                                                        | APG Menu Button pattern, `component:Popover`, source, tests, and browser evidence |
+| FR6  | Closing the menu preserves a newly focused outside control. Focus returns to the trigger only when the closing surface would otherwise strand focus.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `component:Popover` and browser focus behavior                                    |
+| FR7  | The menu branch delegates item rendering, selection, row focus, and submenu content to the shared DropdownMenu item pipeline, from a data array or composed children. With `menu`, `href` and `onClick` are ignored and a development warning is logged.                                                                                                                                                                                                                                                                                                                                                                                                                    | Released source and focused tests                                                 |
+| FR8  | Omitted `menuSize` resolves to `sm` under the `supporting` variant and `md` otherwise before entering the menu pipeline.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Released source and consumer docs                                                 |
+| FR9  | The local targets are `breadcrumb-item` on the `<li>`, `breadcrumb-item-menu-trigger` on the menu button, and `breadcrumb-menu` on the menu surface; the first two reflect the trail's variant. Link, button, and menu trigger paint the shared focus outline.                                                                                                                                                                                                                                                                                                                                                                                                              | Released docs, source, and theming tests                                          |
+| FR10 | In the open menu, a press (finger, pen or mouse) that lands on an enabled item and slides across the items acts on the one it lifts on, once, through that item's own activation, with the highlight following the pointer; a lift outside acts on nothing, and a mouse released outside closes the menu. The menu adopts `module:DropdownMenu/useMenuPress` for this (`family:action-groups` FR1–FR5; `module:DropdownMenu/useMenuPress` DEC-7). A press on caller content that is not an item, and a Ctrl-, Cmd- or Shift-click or a middle click on a link item, stays that content's or the browser's own, and keyboard and assistive-technology behavior is unchanged. | Current source and tests                                                          |
 
 ### Allowed variation
 
@@ -122,15 +151,15 @@ intentional decision.
 
 ### Representative states
 
-| State            | Required invariant                                                                                            | Allowed variation                                             |
-| ---------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
-| Destination link | Shared link path, visible keyboard focus, and accepted destination behavior remain available.                 | Native or custom router renderer; optional start content.     |
-| Action button    | Native button semantics and supplied click handling remain available.                                         | Default or supporting typography.                             |
-| Explicit current | Current-page state is exposed on the rendered content owner.                                                  | Plain content or menu trigger.                                |
-| Auto-current     | The final omitted item receives current-page state only when no explicit current item exists.                 | Link or text content remains in its released branch.          |
-| Closed menu      | Trigger exposes `aria-haspopup="menu"`, controls the menu, and reports collapsed state.                       | Data-driven or composed rows; current or non-current trigger. |
-| Open menu        | Named menu is top-layer reachable and focus enters its first eligible row.                                    | Row kinds, submenu content, and explicit menu size.           |
-| Dismissed menu   | One dismissal closes the surface; valid outside focus is preserved and stranded focus returns to the trigger. | Escape, selection, Tab, or native light dismiss.              |
+| State            | Required invariant                                                                                             | Allowed variation                                             |
+| ---------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
+| Destination link | Shared link path, visible keyboard focus, and accepted destination behavior remain available.                  | Native or custom router renderer; optional start content.     |
+| Action button    | Native button semantics and supplied click handling remain available.                                          | Default or supporting typography.                             |
+| Explicit current | Current-page state is exposed on the rendered content owner.                                                   | Plain content or menu trigger.                                |
+| Auto-current     | The last crumb, when it omits the prop, receives current-page state only when no explicit current item exists. | Link or text content remains in its released branch.          |
+| Closed menu      | Trigger exposes `aria-haspopup="menu"`, controls the menu, and reports collapsed state.                        | Data-driven or composed rows; current or non-current trigger. |
+| Open menu        | Named menu is top-layer reachable and focus enters its first eligible row.                                     | Row kinds, submenu content, and explicit menu size.           |
+| Dismissed menu   | One dismissal closes the surface; valid outside focus is preserved and stranded focus returns to the trigger.  | Escape, selection, Tab, or native light dismiss.              |
 
 ### Transformation and precedence order
 
@@ -148,10 +177,10 @@ intentional decision.
 - **PR1 — Delegated layer resources.** BreadcrumbItem creates no independent global
   listeners or observers; menu lifecycle and focus resources remain delegated to
   Popover and shared menu hooks.
-- **PR2 — Auto-current reconciliation.** Current source reconciles omitted current
-  state by inspecting the rendered sibling list after render. This is a known
-  runtime-authority gap under `architecture:react-component-runtime`, not an
-  approved implementation requirement.
+- **PR2 — Auto-current reconciliation.** Current source resolves omitted current
+  state by inspecting the rendered sibling list after render. This is the gap
+  recorded under Current-state impact, not an approved implementation
+  requirement.
 
 ## Accessibility contract
 
@@ -159,6 +188,8 @@ intentional decision.
   aggregate breadcrumb semantics; each item remains one list item.
 - **AR2 — Current state.** The content owner for a current item exposes
   `aria-current="page"`; the list-item wrapper does not duplicate it.
+  Implementation gap: auto-current falls back to the `<li>` when a custom link
+  does not forward its ref (Current-state impact).
 - **AR3 — Native interaction.** Links use link semantics, action-only items use a
   native button, and menu items use the APG Menu Button relationship.
 - **AR4 — Menu name.** The menu surface is labelled by its trigger, including when
@@ -182,6 +213,8 @@ intentional decision.
 
 ## Family and system relationships
 
+- `component:Breadcrumbs` supplies the separator and variant.
+- `design:bidirectionality` DR4 governs the built-in separator's mirroring.
 - `family:navigation-destinations` owns destination inspection and handoff for
   native and custom link paths. BreadcrumbItem composes the shared link owner.
 - `family:overlay-dismissal` owns topmost Escape/platform-close routing.
@@ -195,19 +228,30 @@ intentional decision.
 
 ## Verification map
 
-| Contract         | Verification                                                               | Representative states                                                                      | Mutation or failure expectation                                                                     | Audit section                                 |
-| ---------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------- | --------------------------------------------- |
-| FR1–FR3, AR1–AR3 | `Breadcrumbs.test.tsx` branch, ref, pass-through, and current-state suites | Link, action, explicit current, omitted final, explicit false                              | A branch changes semantic element, loses current state, or moves the public root contract.          | `audit:BreadcrumbItem/api-behavior`           |
-| FR4, AR6         | `Breadcrumbs.test.tsx`, `BreadcrumbItem.stories.tsx`, and RTL audit        | Built-in slash, bidi-mirrored glyph, explicit icon mirror, LTR and RTL                     | A contextual separator fails to mirror exactly once or becomes exposed to AT.                       | `audit:BreadcrumbItem/rtl`                    |
-| FR5–FR8, AR3–AR5 | `Breadcrumbs.test.tsx` plus real-browser story evidence                    | String and ReactNode labels, click/keyboard open, rows, selection, Escape, outside dismiss | A menu loses its name/state, focus enters the wrong owner, or dismissal steals valid outside focus. | `audit:BreadcrumbItem/accessibility-behavior` |
-| FR9              | `themingTargets.test.ts`, source inspection, and rendered theme evidence   | Item, menu trigger, menu surface; default/supporting                                       | A target disappears, moves to non-painting plumbing, or loses variant reflection.                   | `audit:BreadcrumbItem/theming`                |
-| Draft structure  | `scripts/check-knowledge.mjs`                                              | Required schema and current relationship links                                             | Missing sections, stale links, or accidental current authority fail validation.                     | `audit:BreadcrumbItem/knowledge`              |
+| Contract         | Verification                                                                     | Representative states                                                                      | Mutation or failure expectation                                                                     | Audit section                                 |
+| ---------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------- | --------------------------------------------- |
+| FR1–FR3, AR1–AR3 | `Breadcrumbs.test.tsx` branch, test-id, and current-state suites                 | Link, action, explicit current, omitted last crumb                                         | A branch changes semantic element, loses current state, or moves the public root contract.          | `audit:BreadcrumbItem/api-behavior`           |
+| FR4, AR6         | `Breadcrumbs.test.tsx` separator, mirror-style class, and custom-separator tests | Built-in slash, custom separator                                                           | A contextual separator fails to mirror exactly once or becomes exposed to AT.                       | `audit:BreadcrumbItem/rtl`                    |
+| FR5–FR8, AR3–AR5 | `Breadcrumbs.test.tsx` menu suites                                               | String and ReactNode labels, click/keyboard open, rows, selection, Escape, outside dismiss | A menu loses its name/state, focus enters the wrong owner, or dismissal steals valid outside focus. | `audit:BreadcrumbItem/accessibility-behavior` |
+| FR9              | `Breadcrumbs.test.tsx` theme-target tests; `themingTargets.test.ts`              | Item, menu trigger, menu surface; default/supporting                                       | A target disappears, moves to non-painting plumbing, or loses variant reflection.                   | `audit:BreadcrumbItem/theming`                |
+| AR1–AR2          | `Breadcrumbs.a11y.test.tsx` and `Breadcrumbs.a11y.chromium.spec.ts`              | Trail, explicit current, auto current, opt-out                                             | A role, name, state, or focus expectation regresses.                                                | `audit:BreadcrumbItem/accessibility-behavior` |
+| FR10             | `Breadcrumbs.test.tsx` menu-crumb suite (touch and mouse slides)                 | Touch and mouse slides across items                                                        | Removing the adoption fails the slide tests.                                                        | —                                             |
+
+Read from source, with no focused test yet:
+
+- FR1: the item `ref` and other DOM props on the `<li>`.
+- FR3: a last crumb with `isCurrent={false}` leaving the trail with no current
+  crumb.
+- FR4: the built-in slash mirroring exactly once in a right-to-left layout.
+- FR5: Enter and Space opening the menu, a click focusing the first row, Tab
+  closing the menu, arrows stopping at the ends without wrapping, and typeahead.
+- FR7: `onClick` being ignored beside `menu`.
+- FR8.
+- FR9: the shared focus outline on the link, button, and menu trigger.
 
 ## Decision log
 
-None. This draft records observed released behavior and objective shared
-requirements; it makes no component-local API, default, compatibility, ownership,
-or visual-design decision.
+No component-local decision is recorded.
 
 ## Open questions
 

package/src/Breadcrumbs/BreadcrumbItem.tsx

@@ -51,6 +51,10 @@ import {focusOutlineProps} from '../utils/focusOutline.stylex';
 import {Icon} from '../Icon';
 import {usePopover} from '../Popover/usePopover';
 import {useListFocus} from '../hooks/useListFocus';
+import {useMenuPress} from '../hooks/useMenuPress';
+import {pressOnItemsOnly} from '../hooks/menuPressOnItems';
+import {menuTouchActionStyles} from '../DropdownMenu/menuTouchAction.stylex';
+import {useMenuOverflow} from '../DropdownMenu/useMenuOverflow';
 import {useTypeahead} from '../hooks/useTypeahead';
 import {layerAnimations} from '../Layer/layerAnimations.stylex';
 import {renderDropdownItems} from '../DropdownMenu/renderDropdownItems';
@@ -68,6 +72,7 @@ import {
 import type {DropdownMenuOption} from '../DropdownMenu/DropdownMenu';
 
 import {useMergedRefs} from '../hooks/useMergedRefs';
+import {useInteractionModalityTracking} from '../utils/interactionModality';
 // =============================================================================
 // Props
 // =============================================================================
@@ -519,6 +524,10 @@ function BreadcrumbMenuTrigger({
   const triggerId = useId();
   const buttonRef = useRef<HTMLButtonElement>(null);
   const isSupporting = variant === 'supporting';
+  // The menu's rows move focus with the last input
+  // (`architecture:interaction-modality` INV1); this menu has no press model
+  // to activate the tracking they read, so it activates it itself.
+  useInteractionModalityTracking();
 
   const popover = usePopover({
     hasLightDismiss: true,
@@ -547,6 +556,15 @@ function BreadcrumbMenuTrigger({
     onEscape: closeMenu,
   });
 
+  // A press that slides across the menu's items acts on the item it lifts on,
+  // the highlight following the pointer, as DropdownMenu's does
+  // (`family:action-groups` FR1-FR3, FR5); a mouse released outside closes it.
+  const menuPress = useMenuPress({
+    menuRef: listRef,
+    itemSelector: MENU_ITEM_SELECTOR,
+    onDismiss: closeMenu,
+  });
+
   const typeahead = useTypeahead({
     getItemLabels: () => getMenuItems().map(el => el.textContent),
     onMatch: focusItem,
@@ -620,6 +638,7 @@ function BreadcrumbMenuTrigger({
   );
 
   const menuContent = Array.isArray(menu) ? renderDropdownItems(menu) : menu;
+  const hasOverflow = useMenuOverflow(listRef, menuContent, popover.isOpen);
 
   return (
     <>
@@ -668,10 +687,20 @@ function BreadcrumbMenuTrigger({
           id={menuId}
           role="menu"
           aria-labelledby={triggerId}
+          {...menuPress.menuProps}
+          onPointerDown={pressOnItemsOnly(
+            menuPress.menuProps.onPointerDown,
+            MENU_ITEM_SELECTOR,
+          )}
           onKeyDown={listKeyDown}
           {...mergeProps(
             themeProps('breadcrumb-menu'),
-            stylex.props(menuStyles.menu),
+            stylex.props(
+              menuStyles.menu,
+              hasOverflow
+                ? menuTouchActionStyles.scrolls
+                : menuTouchActionStyles.fits,
+            ),
           )}>
           <DropdownMenuContext value={contextValue}>
             <DropdownMenuRootOpenContext value={popover.isOpen}>