@astryxdesign/core 0.6.1 → 0.6.2-canary.176dfa6

package/dist/hooks/useScrollableArea.js

@@ -4,8 +4,8 @@
 
 /**
  * @file useScrollableArea.ts
- * @input Logical scroll intent, keyboard ownership, caller-owned viewport/content props
- * @output Safe prop getters and stable per-axis effective scroll state
+ * @input Logical scroll intent, focus-time keyboard delegation, caller-owned viewport/content props
+ * @output Safe prop getters, native keyboard entry, and stable per-axis effective scroll state
  * @position Canonical behavior core for ScrollableArea and structure-owning adopters
  *
  * SYNC: When modified, update:
@@ -15,6 +15,7 @@
  */
 import { useCallback, useMemo, useRef, useState } from 'react';
 import * as stylex from '@stylexjs/stylex';
+import { attachScrollKeyboardDelegation } from "./scrollKeyboardDelegation.js";
 import { useIsomorphicLayoutEffect } from "./useIsomorphicLayoutEffect.js";
 import { mergeProps } from "../utils/mergeProps.js";
 import { mergeRefs } from "../utils/mergeRefs.js";
@@ -172,6 +173,9 @@ export function useScrollableArea({
     viewport.addEventListener('animationend', scheduleMeasure);
     content.addEventListener('transitionend', scheduleMeasure);
     content.addEventListener('animationend', scheduleMeasure);
+
+    // Geometry invalidation is independent of keyboard eligibility. The latter
+    // is inspected only on native keyboard entry, never by these observers.
     const mutationObserver = typeof MutationObserver === 'undefined' ? null : new MutationObserver(scheduleMeasure);
     mutationObserver?.observe(viewport, {
       attributes: true,
@@ -219,6 +223,13 @@ export function useScrollableArea({
     inline: axisIsRequested(axis, 'inline') ? measured.inline : INACTIVE_AXIS_STATE,
     block: axisIsRequested(axis, 'block') ? measured.block : INACTIVE_AXIS_STATE
   }), [axis, measured]);
+  const hasEffectiveAxis = state.inline.isScrollable || state.block.isScrollable;
+  useIsomorphicLayoutEffect(() => {
+    if (keyboardAccess.owner !== 'contentOrViewport' || !hasEffectiveAxis || viewport == null || content == null) {
+      return;
+    }
+    return attachScrollKeyboardDelegation(viewport, content);
+  }, [content, hasEffectiveAxis, keyboardAccess.owner, viewport]);
   const getViewportProps = useCallback((props = {}) => {
     const hasEffectiveAxis = state.inline.isScrollable || state.block.isScrollable;
     const requestedX = axisIsRequested(axis, 'inline') && mapping.inline === 'x' || axisIsRequested(axis, 'block') && mapping.block === 'x';
@@ -237,7 +248,8 @@ export function useScrollableArea({
       style: withoutOwnedOverflow(domProps.style)
     };
     const styledProps = mergeProps(callerProps, stylex.props(xstyle, styles.overflow(containsSticky ? scrollsOnX ? 'auto' : 'hidden' : 'clip', containsSticky ? scrollsOnY ? 'auto' : 'hidden' : 'clip')));
-    const keepsProgrammaticFocus = !hasEffectiveAxis && viewport != null && typeof document !== 'undefined' && document.activeElement === viewport;
+    const viewportIsKeyboardOwner = keyboardAccess.owner !== 'content';
+    const keepsProgrammaticFocus = (!viewportIsKeyboardOwner || !hasEffectiveAxis) && viewport != null && typeof document !== 'undefined' && document.activeElement === viewport;
     const behaviorStyle = {
       ...styledProps.style
     };
@@ -251,10 +263,10 @@ export function useScrollableArea({
     if (axisIsRequested(axis, 'block')) {
       behaviorStyle[blockPhysical === 'x' ? 'overscrollBehaviorX' : 'overscrollBehaviorY'] = containBlock ? 'contain' : 'auto';
     }
-    const keyboardProps = keyboardAccess.owner === 'viewport' ? {
+    const keyboardProps = keyboardAccess.owner !== 'content' ? {
       role: keyboardAccess.role ?? 'group',
       'aria-label': keyboardAccess.label,
-      tabIndex: hasEffectiveAxis ? 0 : keepsProgrammaticFocus ? -1 : undefined
+      tabIndex: viewportIsKeyboardOwner && hasEffectiveAxis ? 0 : keepsProgrammaticFocus ? -1 : undefined
     } : {};
     const result = {
       ...styledProps,

package/locales/en.json

@@ -447,6 +447,18 @@
     "defaultMessage": "Next",
     "description": "Screen-reader-only label on the right-arrow button in a Lightbox (navigates to next media item). Pairs with `lightbox.previous`."
   },
+  "@astryx.chatTypingIndicator.one": {
+    "defaultMessage": "{name} is typing…",
+    "description": "Politely announced status naming the single person currently typing in a chat. `name` is a display name supplied by the app. Present-progressive form; the trailing ellipsis is the single … character."
+  },
+  "@astryx.chatTypingIndicator.many": {
+    "defaultMessage": "{names} are typing…",
+    "description": "Politely announced status when more than one person is typing in a chat. `names` is already joined for the locale by Intl.ListFormat, so translations must not add their own conjunction — place `{names}` where the joined list belongs."
+  },
+  "@astryx.chatTypingIndicator.others": {
+    "defaultMessage": "{count, number} {count, plural, one {other} other {others}}",
+    "description": "Overflow element for the chat typing status when three or more people type: the first name is shown and the rest collapse into this phrase, which is then joined to the name by Intl.ListFormat. Renders as the last list item, e.g. \"Ana and 2 others\"."
+  },
   "@astryx.listInput.emptyTitle": {
     "defaultMessage": "No {itemName}s yet",
     "description": "EmptyState title shown inside a lab ListInput when its collection has no records. `{itemName}` is the consumer's singular noun for one record (e.g. \"guest\"); the source appends a literal \"s\" to pluralize it, which only works for regular English plurals. If your language cannot pluralize an interpolated noun this way, rephrase around `{itemName}` instead (e.g. \"No {itemName} added yet\")."
@@ -935,6 +947,10 @@
     "defaultMessage": "Loading",
     "description": "Screen-reader-only live-region announcement while a Button is in its loading state (spinner shown, action in flight). Progressive sense (\"work in progress\"), not a noun. Kept separate from `typeahead.loading` — translations may diverge."
   },
+  "@astryx.spinner.loading": {
+    "defaultMessage": "Loading",
+    "description": "Screen-reader-only default name for a standalone Spinner's role=\"status\" element, used when the consumer supplies neither `aria-label` nor a visible string label. Present-progressive form. Kept separate from `button.loading` and `typeahead.loading` — translations may diverge."
+  },
   "@astryx.chatComposerDrawer.expand": {
     "defaultMessage": "Expand {label}",
     "description": "Screen-reader-only label on the ChatComposerDrawer toggle when the drawer is collapsed. `{label}` is the drawer's visible name — example: `Expand Attachments`. Pairs with `collapse`."

package/locales/pseudo.json

@@ -335,6 +335,15 @@
   "@astryx.lightbox.next": {
     "defaultMessage": "⟦Ñéẋţ⟧"
   },
+  "@astryx.chatTypingIndicator.one": {
+    "defaultMessage": "⟦{name} íš ţýþíñĝ…⟧"
+  },
+  "@astryx.chatTypingIndicator.many": {
+    "defaultMessage": "⟦{names} àřé ţýþíñĝ…⟧"
+  },
+  "@astryx.chatTypingIndicator.others": {
+    "defaultMessage": "⟦{count, number} {count, plural, one {other} other {others}}⟧"
+  },
   "@astryx.listInput.emptyTitle": {
     "defaultMessage": "⟦Ñó {itemName}š ýéţ⟧"
   },
@@ -701,6 +710,9 @@
   "@astryx.button.loading": {
     "defaultMessage": "⟦Łóàðíñĝ⟧"
   },
+  "@astryx.spinner.loading": {
+    "defaultMessage": "⟦Łóàðíñĝ⟧"
+  },
   "@astryx.chatComposerDrawer.expand": {
     "defaultMessage": "⟦Éẋþàñð {label}⟧"
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/core",
-  "version": "0.6.1",
+  "version": "0.6.2-canary.176dfa6",
   "displayName": "Astryx Core",
   "description": "The component library. Accessible, themeable React components with built-in spacing, dark mode, and StyleX styling.",
   "author": "Meta Open Source",
@@ -672,16 +672,18 @@
     "react-dom": ">=19.0.0"
   },
   "devDependencies": {
-    "@babel/cli": "^8.0.4",
+    "@astryxdesign/a11y-spec": "0.6.2-canary.176dfa6",
+    "@astryxdesign/cli": "0.6.2-canary.176dfa6",
+    "@babel/cli": "^7.29.7",
     "@babel/core": "^7.29.7",
-    "@babel/preset-react": "^8.0.1",
+    "@babel/preset-react": "^7.29.7",
     "@babel/preset-typescript": "^7.29.7",
+    "@heroicons/react": "^2.2.0",
     "@stylexjs/babel-plugin": "^0.19.0",
     "@testing-library/dom": "^10.0.0",
     "@testing-library/jest-dom": "^6.6.0",
     "@testing-library/react": "^16.3.2",
-    "@astryxdesign/a11y-spec": "0.0.0",
-    "@astryxdesign/cli": "0.6.1"
+    "@types/babel__core": "^7.20.5"
   },
   "dependencies": {
     "intl-messageformat": "^11.2.9"

package/scripts/agent-doc-state.mjs

@@ -57,7 +57,7 @@ export const LEGACY_MARKER_END = '<!-- XDS:END -->';
  * targets are user-chosen and not enumerable here.)
  */
 export const AGENT_DOC_PATHS = [
-  AGENTS_MD, // Codex / ChatGPT / generic
+  AGENTS_MD, // Codex / ChatGPT / Muse / generic
   CLAUDE_MD, // Claude Code (root)
   CLAUDE_DIR_MD, // Claude Code (.claude/CLAUDE.md)
   CURSOR_RULES, // Cursor

package/src/BottomSheet/BottomSheet.doc.mjs

@@ -1,5 +1,12 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
+/**
+ * @file BottomSheet.doc.mjs
+ * @input BottomSheet props, sheet anatomy, and focus-time keyboard scrolling behavior
+ * @output Consumer documentation and examples for BottomSheet
+ * @position CLI and rendered component documentation
+ */
+
 /** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */
 const anatomy = [
   {
@@ -130,7 +137,7 @@ export const docs = {
       name: 'children',
       type: 'ReactNode',
       description:
-        "Sheet content, rendered below the grab handle in a scrollable area. If it includes a text-entry control that can bring up the mobile keyboard, use height='tall' and keep the sheet fully expanded while editing.",
+        "Sheet content in a scrollable area. The named body is keyboard reachable while overflowing. Forward Tab entry may move directly to the first native link or button; input controls, composite widgets, and nested scroll areas retain the body stop. Shift+Tab from a delegated first child skips the body. Fitting content adds no body stop. The internal observed content box preserves block flow and percentage heights. If it includes a text-entry control that can bring up the mobile keyboard, use height='tall' and keep the sheet fully expanded while editing.",
       required: true,
     },
     {

package/src/BottomSheet/BottomSheet.spec.md

@@ -14,6 +14,9 @@ verified_by:
   [
     packages/core/src/BottomSheet/BottomSheet.test.tsx,
     packages/core/src/BottomSheet/BottomSheetPanel.test.tsx,
+    packages/core/src/BottomSheet/BottomSheetKeyboard.test.tsx,
+    packages/core/src/BottomSheet/__tests__/BottomSheetKeyboard.a11y.browser.spec.ts,
+    apps/storybook/stories/BottomSheet.stories.tsx,
     scripts/check-knowledge.mjs,
   ]
 modules: []
@@ -22,7 +25,7 @@ design_specs: []
 architecture:
   [architecture:component-theming-surface, architecture:layer-runtime]
 contributing: []
-system_specs: []
+system_specs: [spec:AST-025]
 ---
 
 # BottomSheet component contract
@@ -30,14 +33,15 @@ system_specs: []
 ## Intent
 
 BottomSheet presents caller-provided content in a panel that rises from the
-bottom edge. This draft records current consumer anatomy and theming reachability
-without changing runtime behavior, styling, targets, or public API.
+bottom edge. This draft records current consumer anatomy, keyboard-reachable
+scrolling, and theming reachability without changing public API.
 
 ## Compatibility and migration
 
 - Released default preserved: `yes`
-- Compatibility class: additive documentation only; runtime, DOM, styling,
-  targets, and public API remain unchanged
+- Compatibility class: additive internal content box and shared scroll behavior;
+  public props, defaults, targets, and caller child ordering inside the content box
+  remain unchanged
 - Controlled/uncontrolled behavior: unchanged
 - Migration decision: none
 
@@ -48,7 +52,8 @@ Consumer migration instructions belong in consumer docs and release notes.
 **Owns**
 
 - The visual Sheet panel and its current `bottom-sheet` target.
-- The scrolling Content area and decorative Handle inside the panel.
+- The scrolling Content area, its shared viewport/content-box integration, and
+  automatic keyboard-path selection.
 - Standalone sheet presentation, including its optional native-dialog Scrim.
 
 **Does not own / non-goals**
@@ -67,10 +72,11 @@ in `BottomSheet.doc.mjs`.
 
 ## Behavioral and layout contract
 
-| ID  | Candidate invariant                                                                                                                                                | Basis                           | Draft review state                                 |
-| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------- | -------------------------------------------------- |
-| FR1 | The current presented sheet contains one Sheet panel, one scrolling Content area, and one decorative Handle; a Scrim is present only in scrim-backed presentation. | Current source, docs, and tests | Verified current behavior; no new behavior decided |
-| FR2 | The Sheet panel carries `bottom-sheet`; Content area, Handle, and Scrim carry no BottomSheet public target.                                                        | Current source, docs, and tests | Verified current behavior; no target change        |
+| ID  | Candidate invariant                                                                                                                                                                                                                         | Basis                              | Draft review state                                 |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | -------------------------------------------------- |
+| FR1 | The current presented sheet contains one Sheet panel, one scrolling Content area, and one decorative Handle; a Scrim is present only in scrim-backed presentation.                                                                          | Current source, docs, and tests    | Verified current behavior; no new behavior decided |
+| FR2 | The Sheet panel carries `bottom-sheet`; Content area, Handle, and Scrim carry no BottomSheet public target.                                                                                                                                 | Current source, docs, and tests    | Verified current behavior; no target change        |
+| FR3 | Content renders in one real observed content box. Effective overflow, containment, and keyboard access come from `useScrollableArea`; the named overflowing body delegates forward Tab entry to a safe first sequential native link/button. | `spec:AST-025`; issue #5207; tests | Focus-time prototype for owner review              |
 
 ### Allowed variation
 
@@ -96,8 +102,14 @@ in `BottomSheet.doc.mjs`.
 
 ## Accessibility contract
 
-This draft does not change or extend BottomSheet's existing dialog naming,
-focus, Handle, keyboard, or dismissal behavior.
+- **AR1 — Keyboard scroll path.** The named body is a tab stop while effectively
+  overflowing. On forward Tab entry, the shared hook may delegate to the first
+  sequential native link/button outside navigation-key-owning surfaces. It keeps
+  the body stop for excluded content and skips the body on reverse traversal
+  from the delegated first child.
+- **AR2 — Focus continuity.** Content, overflow, or eligibility changes MUST NOT
+  move focus. Pointer/programmatic body focus never delegates. A focused body
+  losing overflow remains programmatically focusable.
 
 ## Design relationships
 
@@ -143,18 +155,20 @@ a decision that they must remain unthemeable.
   mapping, and factual `none` dispositions.
 - `architecture:layer-runtime` owns the current native-dialog host distinction
   and records that sheets retain local scrim and swipe behavior.
+- `spec:AST-025` owns effective scroll measurement, overflow and containment,
+  automatic keyboard-owner selection, and focus continuity.
 - `family:overlay-dismissal` owns shared Escape and platform-close ordering and
   records BottomSheet's current local-only adoption gap. This anatomy backfill
   does not migrate that runtime behavior.
 
 ## Verification map
 
-| Contract            | Verification                                                              | Representative states                          | Mutation or failure expectation                                                                 | Audit section               |
-| ------------------- | ------------------------------------------------------------------------- | ---------------------------------------------- | ----------------------------------------------------------------------------------------------- | --------------------------- |
-| FR1                 | `BottomSheet.test.tsx` render, content, Handle, and scrim behavior suites | Modal, non-modal, and switcher presentations   | Removing a documented part fails existing content, structure, or dismissal assertions.          | `audit:BottomSheet/anatomy` |
-| FR2                 | Panel target assertion, source inspection, and theming target inventories | Sheet panel, Content area, Handle, and Scrim   | Removing the panel target or documenting an unshipped child target fails evidence or inventory. | `audit:BottomSheet/theming` |
-| Layout evidence     | `BottomSheetPanel.test.tsx`                                               | Floating Handle and scrolling Content area     | Reordering or merging the stable parts fails existing panel structure and style assertions.     | `audit:BottomSheet/anatomy` |
-| Theming anatomy map | `scripts/check-knowledge.mjs`                                             | Canonical anatomy and current target inventory | Missing, extra, prefixed, stale, or multiply assigned mappings fail repository validation.      | `audit:BottomSheet/theming` |
+| Contract            | Verification                                                                                       | Representative states                                                    | Mutation or failure expectation                                                                         | Audit section                     |
+| ------------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- | --------------------------------- |
+| FR1                 | `BottomSheet.test.tsx` render, content, Handle, and scrim behavior suites                          | Modal, non-modal, and switcher presentations                             | Removing a documented part fails existing content, structure, or dismissal assertions.                  | `audit:BottomSheet/anatomy`       |
+| FR2                 | Panel target assertion, source inspection, and theming target inventories                          | Sheet panel, Content area, Handle, and Scrim                             | Removing the panel target or documenting an unshipped child target fails evidence or inventory.         | `audit:BottomSheet/theming`       |
+| FR3, AR1–AR2        | `BottomSheetKeyboard.test.tsx`; `BottomSheetKeyboard.a11y.browser.spec.ts`; open Storybook stories | fitting/overflow, plain text, usable/unusable/dynamic descendants, focus | Missing/duplicate keyboard access, stale ownership, focus movement, or broken content-box layout fails. | `audit:BottomSheet/accessibility` |     | Layout evidence | `BottomSheetPanel.test.tsx` | Floating Handle and scrolling Content area | Reordering or merging the stable parts fails existing panel structure and style assertions. | `audit:BottomSheet/anatomy` |
+| Theming anatomy map | `scripts/check-knowledge.mjs`                                                                      | Canonical anatomy and current target inventory                           | Missing, extra, prefixed, stale, or multiply assigned mappings fail repository validation.              | `audit:BottomSheet/theming`       |
 
 Existing tests directly assert the Sheet panel target, Content area placement,
 Handle structure, and scrim behavior. Source and public target metadata confirm
@@ -162,8 +176,20 @@ that the other three parts have no public target.
 
 ## Decision log
 
-None. This draft records current facts and introduces no component-local design,
-API, theming, or layer-system decision.
+### DEC-1 — BottomSheet adopts automatic shared keyboard ownership
+
+**Reference:** `component:BottomSheet/DEC-1`
+**Decider:** cixzhang, 2026-09-13
+
+BottomSheet supplies its existing label to
+`keyboardAccess.owner="contentOrViewport"`. The shared hook keeps the overflowing
+body named and tabbable, delegating forward keyboard entry to a safe first native
+link/button. Pointer/programmatic focus and excluded content keep the body path. BottomSheet retains `stickyContainment="always"` because the
+body deliberately remains the sheet-local Sticky boundary.
+
+A real flow-root content box supplies the hook's observation seam while preserving
+representative margin, float, percentage-height, flex/grid-child, and hug-height
+behavior.
 
 ## Open questions
 

package/src/BottomSheet/BottomSheet.test.tsx

@@ -3,7 +3,7 @@
 /**
  * @file BottomSheet.test.tsx
  * @input Uses vitest, @testing-library/react, BottomSheet component
- * @output Unit tests for BottomSheet component behavior
+ * @output Unit tests for BottomSheet behavior and observed content anatomy
  * @position Core testing; validates BottomSheet.tsx implementation
  *
  * SYNC: When BottomSheet.tsx changes, update tests to match new behavior
@@ -290,7 +290,7 @@ describe('BottomSheet', () => {
     expect(onClick).toHaveBeenCalledTimes(1);
   });
 
-  it('keeps consumer content as the last scroll-body child', () => {
+  it('keeps consumer content first and last inside the observed content box', () => {
     render(
       <BottomSheet isOpen onOpenChange={() => {}} label="Filters">
         <div data-testid="consumer-content">Sheet content</div>
@@ -300,7 +300,10 @@ describe('BottomSheet', () => {
     const consumer = screen.getByTestId('consumer-content');
 
     expect(body.children).toHaveLength(1);
-    expect(body.lastElementChild).toBe(consumer);
+    const content = body.lastElementChild;
+    expect(content).toHaveAttribute('data-scroll-content');
+    expect(content?.lastElementChild).toBe(consumer);
+    expect(consumer.matches(':first-child')).toBe(true);
     expect(consumer.matches(':last-child')).toBe(true);
   });
 

package/src/BottomSheet/BottomSheet.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file BottomSheet.tsx
- * @input Uses React, StyleX, core hooks/utils, BottomSheetPanel, BottomSheetSwitcherContext
+ * @input Uses React, StyleX, core hooks/utils, named BottomSheetPanel, BottomSheetSwitcherContext
  * @output Exports BottomSheet component and BottomSheetProps
  * @position Public BottomSheet router plus private standalone/switcher hosts
  *
@@ -379,6 +379,7 @@ function StandaloneBottomSheet({
           ref={ref}
           state={panelState}
           height={height}
+          label={label}
           snapPoints={snapPoints}
           isSwipeDismissAllowed={purpose === 'info'}
           isPageScrollLocked={shouldPresent && hasScrim}
@@ -537,6 +538,7 @@ function SwitcherBottomSheetItem({
         ref={ref}
         state={panelState}
         height={height}
+        label={label}
         snapPoints={snapPoints}
         isSwipeDismissAllowed={purpose === 'info'}
         isPageScrollLocked={hasScrim}

package/src/BottomSheet/BottomSheetKeyboard.test.tsx

@@ -0,0 +1,195 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file BottomSheetKeyboard.test.tsx
+ * @input BottomSheetPanel, real shared scroll behavior, and explicit DOM geometry
+ * @output Regression coverage for viewport access, entry-time eligibility, and focus continuity
+ * @position BottomSheet integration tests; browser stories verify native key scrolling
+ */
+
+import {act, fireEvent, render, screen, waitFor} from '@testing-library/react';
+import {useState, type ReactNode} from 'react';
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
+import {BottomSheetPanel} from './BottomSheetPanel';
+
+function Fixture({children}: {children: ReactNode}) {
+  return (
+    <BottomSheetPanel
+      label="Reading details"
+      state={{kind: 'open', entering: false}}
+      height="capped"
+      onDismiss={() => {}}
+      onScrimOpacity={() => {}}>
+      {children}
+    </BottomSheetPanel>
+  );
+}
+
+function body() {
+  return screen.getByRole('group', {name: 'Reading details'});
+}
+
+async function measure(scrollHeight: number, scrollWidth = 300) {
+  const viewport = body();
+  // jsdom does not resolve the shared hook's dynamic StyleX CSS variable.
+  viewport.style.overflowY = 'auto';
+  viewport.style.overflowX = 'auto';
+  for (const [key, value] of Object.entries({
+    clientHeight: 100,
+    clientWidth: 300,
+    scrollHeight,
+    scrollWidth,
+  })) {
+    Object.defineProperty(viewport, key, {configurable: true, value});
+  }
+  fireEvent(window, new Event('resize'));
+  await waitFor(() => {
+    expect(viewport.dataset.scrollableBlock === 'true').toBe(
+      scrollHeight > 101,
+    );
+  });
+}
+
+beforeEach(() => {
+  // jsdom has no layout. Visibility-specific cases still use real computed
+  // style/hidden/inert checks; native layout is covered in Storybook.
+  vi.spyOn(HTMLElement.prototype, 'getClientRects').mockReturnValue([
+    new DOMRect(0, 0, 20, 20),
+  ] as unknown as DOMRectList);
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe('BottomSheet keyboard scrolling', () => {
+  it('adds a named body tab stop only while text-only content overflows', async () => {
+    render(<Fixture>Reading details body</Fixture>);
+    await measure(100);
+    expect(body()).not.toHaveAttribute('tabindex');
+    await measure(300);
+    expect(body()).toHaveAttribute('tabindex', '0');
+    expect(body()).toHaveStyle({overscrollBehaviorY: 'contain'});
+  });
+
+  it('preserves current body focus when overflow disappears', async () => {
+    render(<Fixture>Reading details body</Fixture>);
+    await measure(300);
+    act(() => body().focus());
+    await measure(100);
+    expect(body()).toHaveFocus();
+    expect(body()).toHaveAttribute('tabindex', '-1');
+    expect(body()).toHaveStyle({overscrollBehaviorY: 'auto'});
+  });
+
+  it('retains keyboard access to content that overflows only horizontally', async () => {
+    render(<Fixture>Wide reading content</Fixture>);
+    await measure(100, 600);
+    await waitFor(() =>
+      expect(body()).toHaveAttribute('data-scrollable-inline', 'true'),
+    );
+    expect(body()).toHaveAttribute('tabindex', '0');
+  });
+
+  it('keeps the named viewport available alongside focusable content', async () => {
+    render(
+      <Fixture>
+        <button type="button">Continue reading</button>
+      </Fixture>,
+    );
+    await measure(300);
+    expect(body()).toHaveAttribute('tabindex', '0');
+    act(() => screen.getByRole('button').focus());
+    expect(screen.getByRole('button')).toHaveFocus();
+  });
+
+  it.each([
+    <button type="button" key="disabled" disabled>
+      Unavailable
+    </button>,
+    <button type="button" key="hidden" hidden>
+      Hidden
+    </button>,
+    <button type="button" key="negative" tabIndex={-2}>
+      Programmatic only
+    </button>,
+    <button type="button" key="visibility" style={{visibility: 'hidden'}}>
+      Hidden by CSS
+    </button>,
+    <div key="inert" inert>
+      <button type="button">Inert</button>
+    </div>,
+    <fieldset key="fieldset" disabled>
+      <button type="button">Disabled by fieldset</button>
+    </fieldset>,
+  ])(
+    'ignores a descendant that cannot supply sequential keyboard access (%#)',
+    async child => {
+      render(<Fixture>{child}</Fixture>);
+      await measure(300);
+      expect(body()).toHaveAttribute('tabindex', '0');
+    },
+  );
+
+  it('does not move focus when a nested child changes', async () => {
+    let setHasControl: (value: boolean) => void = () => {};
+    function AsyncContent() {
+      const [hasControl, update] = useState(false);
+      setHasControl = update;
+      return hasControl ? (
+        <button type="button">Loaded action</button>
+      ) : (
+        <p>Loading text</p>
+      );
+    }
+    render(
+      <Fixture>
+        <AsyncContent />
+      </Fixture>,
+    );
+    await measure(300);
+    act(() => body().focus());
+    act(() => setHasControl(true));
+    expect(body()).toHaveAttribute('tabindex', '0');
+    expect(body()).toHaveFocus();
+    act(() => setHasControl(false));
+    await waitFor(() => expect(body()).toHaveAttribute('tabindex', '0'));
+  });
+
+  it('retains the viewport when an existing descendant becomes disabled', async () => {
+    render(
+      <Fixture>
+        <button type="button">Continue reading</button>
+      </Fixture>,
+    );
+    await measure(300);
+    screen.getByRole('button').setAttribute('disabled', '');
+    await waitFor(() => expect(body()).toHaveAttribute('tabindex', '0'));
+  });
+
+  it.each(['content', 'ancestor'])(
+    'retains the viewport when %s data attributes change child visibility',
+    async target => {
+      const {container} = render(
+        <Fixture>
+          <style>
+            {'[data-actions="hidden"] button { visibility: hidden; }'}
+          </style>
+          <div data-testid="conditional-content">
+            <button type="button">Conditional action</button>
+          </div>
+        </Fixture>,
+      );
+      await measure(300);
+      expect(body()).toHaveAttribute('tabindex', '0');
+      const owner =
+        target === 'content'
+          ? screen.getByTestId('conditional-content')
+          : container;
+      owner.setAttribute('data-actions', 'hidden');
+      await waitFor(() => expect(body()).toHaveAttribute('tabindex', '0'));
+      owner.removeAttribute('data-actions');
+      expect(body()).toHaveAttribute('tabindex', '0');
+    },
+  );
+});

package/src/BottomSheet/BottomSheetPanel.test.tsx

@@ -3,7 +3,7 @@
 /**
  * @file BottomSheetPanel.test.tsx
  * @input Uses vitest, Testing Library, BottomSheetPanel
- * @output Tests the shared sheet surface motion contract
+ * @output Tests the shared sheet surface motion and keyboard scroll contracts
  * @position Internal presentation tests shared by standalone and switcher modes
  */
 
@@ -50,6 +50,7 @@ function renderPanel(
 ) {
   return render(
     <BottomSheetPanel
+      label="Sheet details"
       state={state}
       height="hug"
       style={panelTransitionStyle}
@@ -92,6 +93,7 @@ describe('BottomSheetPanel', () => {
     const onMotionComplete = vi.fn();
     const {rerender} = render(
       <BottomSheetPanel
+        label="Sheet details"
         state={{kind: 'retained', motion: 'covered', alignmentOffset: 0}}
         height="hug"
         style={panelTransitionStyle}
@@ -104,6 +106,7 @@ describe('BottomSheetPanel', () => {
 
     rerender(
       <BottomSheetPanel
+        label="Sheet details"
         state={{kind: 'open', entering: true}}
         height="hug"
         style={panelTransitionStyle}
@@ -139,6 +142,7 @@ describe('BottomSheetPanel', () => {
 
     rerender(
       <BottomSheetPanel
+        label="Sheet details"
         state={{kind: 'exiting'}}
         height="hug"
         style={panelTransitionStyle}
@@ -166,6 +170,7 @@ describe('BottomSheetPanel', () => {
     const onMotionComplete = vi.fn();
     render(
       <BottomSheetPanel
+        label="Sheet details"
         state={{kind: 'open', entering: true}}
         height="hug"
         onDismiss={() => {}}
@@ -184,6 +189,7 @@ describe('BottomSheetPanel', () => {
       const onMotionComplete = vi.fn();
       render(
         <BottomSheetPanel
+          label="Sheet details"
           state={{kind: 'open', entering: true}}
           height="hug"
           style={{
@@ -211,6 +217,7 @@ describe('BottomSheetPanel', () => {
     const panelRef = vi.fn();
     const {rerender, unmount} = render(
       <BottomSheetPanel
+        label="Sheet details"
         ref={panelRef}
         state={{kind: 'open', entering: false}}
         height="hug"
@@ -223,6 +230,7 @@ describe('BottomSheetPanel', () => {
     expect(panelRef).toHaveBeenCalledTimes(1);
     rerender(
       <BottomSheetPanel
+        label="Sheet details"
         ref={panelRef}
         state={{kind: 'open', entering: false}}
         height="hug"
@@ -361,6 +369,7 @@ describe('BottomSheetPanel', () => {
 
     const {container: closing} = render(
       <BottomSheetPanel
+        label="Sheet details"
         state={{kind: 'exiting'}}
         height="hug"
         onDismiss={() => {}}
@@ -379,6 +388,7 @@ describe('BottomSheetPanel', () => {
 
     const {container: resting} = render(
       <BottomSheetPanel
+        label="Sheet details"
         state={{kind: 'open', entering: false}}
         height="hug"
         onDismiss={() => {}}