An open source design system that's fully customizable and agent ready
TypeScript
docs(spec): admit BottomSheet as a container publisher (#6882)
Xinzi Zhouf4984589e75e
diff --git a/docs/architecture/container-padding.md b/docs/architecture/container-padding.mdindex 32ed88f2ad..71cdcbfd72 100644--- a/docs/architecture/container-padding.md+++ b/docs/architecture/container-padding.md@@ -6,8 +6,8 @@ id: architecture:container-paddingauthority: currentarchive_reason: nullsuperseded_by: null-approved_by: cixzhang-approved_at: 2026-09-22+approved_by: imdreamrunner+approved_at: 2026-10-04owners: [cixzhang, imdreamrunner]applies_to:[@@ -37,6 +37,7 @@ verified_by:packages/core/src/Layout/Layout.test.tsx,packages/core/src/Layout/LayoutSlots.test.tsx,packages/core/src/Layout/overlayPaddingReset.test.tsx,+ packages/core/src/BottomSheet/BottomSheetPanel.test.tsx,packages/core/src/Layout/__tests__/edgeCompensation.test.tsx,packages/core/src/List/List.test.tsx,packages/core/src/TabList/TabList.test.tsx,@@ -77,9 +78,10 @@ The protocol has four layers:public spacing scale. Theme component overrides may set supported paddingproperties. `architecture:theme-authoring-contract` and`architecture:component-theming-surface` own those public surfaces.-2. **Container lowering.** `container()` resolves Card, Section, and Dialog- padding into internal logical-edge variables. An explicit component padding- prop may publish the same geometry through the maps in `padding.stylex.ts`.+2. **Container lowering.** `container()` resolves Card, Section, Dialog, and+ BottomSheet padding into internal logical-edge variables. An explicit+ component padding prop may publish the same geometry through the maps in+ `padding.stylex.ts`.3. **Descendant geometry.** Four inherited `--container-padding-*` variablescarry the inset that bleed descendants subtract. Container publishers andexplicit region-padding paths couple those variables to their padding.@@ -96,7 +98,7 @@ The protocol has four layers:| Role | Participants | Contract responsibility || -------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |-| Container publisher | Card, Section, Dialog, ScrollableArea | Resolve component padding or publish explicit content-box padding as logical-edge and Layout inset variables |+| Container publisher | Card, Section, Dialog, BottomSheet, ScrollableArea | Resolve component padding or publish explicit content-box padding as logical-edge and Layout inset variables || Region publisher | LayoutHeader, LayoutContent, LayoutFooter, LayoutPanel | Publish baseline or explicit-padding geometry; automatic outer-edge publication has the conformance gap below || Bleed consumer | Section, ScrollableArea, Layout, Divider, Table | Subtract inherited inset on the edges each component is designed to escape; ScrollableArea does so only with `isFullBleed` || Edge-compensation consumer | TabList; List/ListItem rows (admitted) | Move visible content toward the container content line while retaining component-owned interaction padding; exact alignment depends on each component's bounded geometry |@@ -111,6 +113,14 @@ compensation geometry, List is the admitted next consumer, and Toolbar consumesalignment geometry. Participation here does not by itself make any of thosecomponents a member of `family:layout-regions`.+BottomSheet publishes the way Dialog does. Its Sheet panel is the overlay+boundary owner, and its scrolling Content area is a container publisher that+pads caller content and publishes the applied inset. The inset resolves from the+`padding` prop on the public spacing scale, then the theme's `padding` properties+on the `bottom-sheet` component. With neither, the Content area keeps its+released default: no inset, and descendants see the boundary's reset values.+This prop and theme property are BottomSheet's projection of container lowering.+Edge compensation is a two-sided geometry contract, not a token contract:1. **Host side.** An eligible container or region state publishes the padding@@ -283,12 +293,12 @@ evidence, not part of this documentation stack.alias through its approved compatibility window, moves maintained examples tothe canonical name, and tests both paths before removal.- Changing `container()` or the public-to-private padding lowering reviews Card,- Section, Dialog, Layout regions, and overlay behavior together.+ Section, Dialog, BottomSheet, Layout regions, and overlay behavior together.- Changing overlay hosting or adding an overlay root verifies that stale pagegeometry stops at the new boundary without suppressing public theme values.-- A component that wants a new public full-bleed mode or padding prop follows- its component/family API review; this architecture does not authorize that- API. `component:List` owns List's first new projection, and+- A component other than BottomSheet that wants a new public full-bleed mode or+ padding prop follows its component/family API review; this architecture does+ not authorize that API. `component:List` owns List's first new projection, and`component:TabList` owns its existing behavior and migration. This record doesnot authorize another component projection.@@ -300,8 +310,8 @@ evidence, not part of this documentation stack.logical-edge setters, Section propagation, and the overlay reset.- `packages/core/src/Layout/edgeCompensation.stylex.ts` — owns the container-sidealignment adjustment for marked edge content.-- Card, Section, Dialog, ScrollableArea, and Layout region implementations —- publish their current geometry.+- Card, Section, Dialog, BottomSheet, ScrollableArea, and Layout region+ implementations — publish their current geometry.- Section, ScrollableArea, Layout, Divider, Table, TabList, and Toolbarimplementations — consume the current geometry for bleed or alignment.- TabList currently lowers its component-owned projection; List owns its admitted@@ -329,6 +339,7 @@ evidence, not part of this documentation stack.| INV2, INV5 | `Section.test.tsx` per-edge and nested-propagation tests | A per-edge prop leaves a stale geometry variable, or nested Sections lose the shipped propagation order || INV2, INV3, INV8 | `ScrollableArea.test.tsx` padding and full-bleed tests | The content box publishes inset different from its applied padding, or the viewport escapes inherited padding without explicit full bleed || INV4 | Layout source review plus `Layout.test.tsx` and `LayoutSlots.test.tsx` | Slot presence stops selecting the shipped applied outer/inner edge styles; exact republished geometry remains limited by the named conformance gap |+| INV2 | `BottomSheetPanel.test.tsx` padding tests | The Content area publishes an inset that differs from its applied padding, or the `padding` prop or theme `padding` does not reach it || INV6 | `overlayPaddingReset.test.tsx` | An overlay inherits page inset, loses its theme's Section padding, or lets ancestor Section propagation cross the boundary || INV3, INV7 | `Layout/__tests__/edgeCompensation.test.tsx` plus component tests | An unmarked child is compensated, or marked edge content loses direct-child discoverability || INV9, INV10 | `List.test.tsx` plus real-browser geometry evidence | The header moves; a row reads the wrong logical edge, diverges from themed/density padding, applies the wrong bounded movement, or loses paint inset |diff --git a/packages/core/src/BottomSheet/BottomSheet.spec.md b/packages/core/src/BottomSheet/BottomSheet.spec.mdindex fa0f0dbd44..782be64cb0 100644--- a/packages/core/src/BottomSheet/BottomSheet.spec.md+++ b/packages/core/src/BottomSheet/BottomSheet.spec.md@@ -9,7 +9,7 @@ superseded_by: nullapproved_by: nullapproved_at: nullowners: [cixzhang]-review_triggers: [theming]+review_triggers: [theming, layout, public-api]verified_by:[packages/core/src/BottomSheet/BottomSheet.test.tsx,@@ -23,7 +23,11 @@ modules: []families: [family:overlay-dismissal]design_specs: []architecture:- [architecture:component-theming-surface, architecture:layer-runtime]+ [+ architecture:component-theming-surface,+ architecture:container-padding,+ architecture:layer-runtime,+ ]contributing: []system_specs: [spec:AST-025]---@@ -34,14 +38,14 @@ system_specs: [spec:AST-025]BottomSheet presents caller-provided content in a panel that rises from thebottom edge. This draft records current consumer anatomy, keyboard-reachable-scrolling, and theming reachability without changing public API.+scrolling, theming reachability, and the Content area's container padding.## Compatibility and migration-- Released default preserved: `yes`-- Compatibility class: additive internal content box and shared scroll behavior;- public props, defaults, targets, and caller child ordering inside the content box- remain unchanged+- Released default preserved: `yes` — with no `padding` prop and no theme+ padding, the Content area has no inset+- Compatibility class: additive `padding` prop. A theme's `padding` on+ `bottom-sheet` now insets the Content area instead of the Sheet panel- Controlled/uncontrolled behavior: unchanged- Migration decision: none@@ -54,6 +58,8 @@ Consumer migration instructions belong in consumer docs and release notes.- The visual Sheet panel and its current `bottom-sheet` target.- The scrolling Content area, its shared viewport/content-box integration, andautomatic keyboard-path selection.+- The Content area's container padding, published per+ `architecture:container-padding`.- Standalone sheet presentation, including its optional native-dialog Scrim.**Does not own / non-goals**@@ -77,6 +83,7 @@ in `BottomSheet.doc.mjs`.| 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 |+| FR4 | The Content area pads caller content by the sheet's container inset, none by default, and publishes the applied inset to descendants as a container publisher. | `architecture:container-padding` | Admitted; implementation pending |### Allowed variation@@ -94,7 +101,9 @@ in `BottomSheet.doc.mjs`.### Transformation and precedence order-- No new height, gesture, motion, or styling precedence rule is introduced.+- Content area inset: the `padding` prop, then the theme's `padding` properties+ on `bottom-sheet`, then no inset.+- No new height, gesture, or motion precedence rule is introduced.### Performance and resources@@ -116,7 +125,7 @@ in `BottomSheet.doc.mjs`.| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract || ---------------- | ------------------------------------------------------------------------------------- | ------------------------------ | -------------- | ------------------ || Sheet panel | Presents the painted bottom-edge surface and owns panel geometry and motion. | Current source and public docs | Prominent | FR1, FR2 |-| Content area | Provides the scrolling area for caller-provided sheet content. | Current source and tests | Prominent | FR1, FR2 |+| Content area | Provides the scrolling, inset area for caller-provided sheet content. | Current source and tests | Prominent | FR1, FR2, FR4 || Handle | Presents the decorative grab affordance and owns the panel's drag interaction region. | Current source and tests | Supporting | FR1, FR2 || Scrim | Dims and blocks the page in a scrim-backed host. | Current source and public docs | Supporting | FR1, FR2 |@@ -153,6 +162,8 @@ a decision that they must remain unthemeable.- `architecture:component-theming-surface` owns anatomy qualification, targetmapping, and factual `none` dispositions.+- `architecture:container-padding` owns the shared container inset protocol and+ admits the Content area as a container publisher.- `architecture:layer-runtime` owns the current native-dialog host distinctionand records that sheets retain local scrim and swipe behavior.- `spec:AST-025` owns effective scroll measurement, overflow and containment,@@ -168,6 +179,7 @@ a decision that they must remain unthemeable.| 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` |+| FR4 | `BottomSheetPanel.test.tsx` container padding tests; `derivedVarRegistry.test.ts` | default, `padding` prop, theme `padding`, lone padded Section child | The published inset differs from the applied padding, or the default sheet changes geometry. | `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,