@astryxdesign/core 0.7.6-canary.fdabeba → 0.7.6

package/src/ScrollableArea/modules/useScrollableArea.spec.md

@@ -1,149 +0,0 @@
----
-schema_version: 3
-template_version: 1
-kind: module
-id: module:ScrollableArea/useScrollableArea
-authority: current
-archive_reason: null
-superseded_by: null
-approved_by: cixzhang
-approved_at: 2026-09-11
-owners: [cixzhang]
-review_triggers: [public-api, behavior, accessibility]
-verified_by:
-  [
-    packages/core/src/hooks/useScrollableArea.test.tsx,
-    packages/core/src/hooks/scrollKeyboardDelegation.test.ts,
-    packages/core/src/BottomSheet/__tests__/BottomSheetKeyboard.a11y.browser.spec.ts,
-  ]
-parent_component: component:ScrollableArea
-references: [architecture:public-component-api, spec:AST-025/DEC-1]
----
-
-# useScrollableArea module contract
-
-## Intent
-
-useScrollableArea is the canonical reusable behavior core for components that
-already own a viewport and content root. It provides safe prop/ref composition,
-logical-axis measurement, live owner registration, edge state, keyboard access,
-and scroll chaining without inserting structure.
-
-## Compatibility and migration
-
-- Released default preserved: not yet released
-- Compatibility class: additive public hook and types
-- Migration decision: `spec:AST-025/DEC-1`
-
-## Ownership boundary
-
-**Owns**
-
-- Effective-axis measurement and stable logical-edge state.
-- Observation, invalidation, DOM owner registration, conditional viewport access,
-  and effective-axis chaining.
-- Safe composition of caller viewport/content props and refs.
-
-**Does not own / non-goals**
-
-- Viewport layout, paint, overflow declarations, scrollbar presentation, or
-  insertion of a content wrapper.
-- Sticky positioning and public owner lookup.
-
-## Public API and concepts
-
-| Concept        | Closed values or states                                | Meaning                                 | Default                   | Owner                                     | Stability |
-| -------------- | ------------------------------------------------------ | --------------------------------------- | ------------------------- | ----------------------------------------- | --------- |
-| axis           | `inline`, `block`, `both`                              | requested logical scroll intent         | required                  | `spec:AST-025`                            | stable    |
-| keyboard owner | `content`, named `viewport`, named `contentOrViewport` | fixed or automatic keyboard scroll path | required                  | `spec:AST-025`                            | stable    |
-| overscroll     | `allow`, `contain`                                     | edge propagation on effective axes      | `allow`                   | `spec:AST-025`                            | stable    |
-| axis state     | `isScrollable`, `atStart`, `atEnd`                     | effective ownership and logical edges   | inactive, both edges true | `module:ScrollableArea/useScrollableArea` | stable    |
-
-## Behavioral contract
-
-| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                        | Basis                       | Acceptance and implementation state     |
-| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | --------------------------------------- |
-| FR1 | An axis MUST be effective only when requested, computed overflow is scroll-capable, and geometry exceeds 1px.                                                                                                                                                                                                                                                                    | `spec:AST-025` FR1–FR4      | implemented                             |
-| FR2 | Viewport and content geometry MUST be observed; invalidations MUST coalesce and preserve the last valid state while unmeasurable.                                                                                                                                                                                                                                                | `spec:AST-025` FR5–FR9      | implemented                             |
-| FR3 | Logical edges and behavior-owned physical overflow MUST map through direction and horizontal, vertical, or sideways writing modes without requiring adopters to recreate the mapping.                                                                                                                                                                                            | `spec:AST-025` FR1, FR3–FR4 | implemented                             |
-| FR4 | The nearest registered effective owner MUST win independently by axis.                                                                                                                                                                                                                                                                                                           | `spec:AST-025` FR10, FR18   | implemented privately for future Sticky |
-| FR5 | Viewport keyboard props and overscroll containment MUST appear only while applicable requested axes are effective.                                                                                                                                                                                                                                                               | `spec:AST-025` FR12–FR14    | implemented                             |
-| FR6 | Prop getters MUST compose refs and preserve caller handlers/classes/styles/ARIA while behavior-owned accessibility and non-cancellable behavior win conflicts.                                                                                                                                                                                                                   | `spec:AST-025` IR4          | implemented                             |
-| FR7 | The viewport prop getter MUST consume caller `xstyle` and internally compose geometry-driven `clip`/`auto`/`hidden` overflow plus explicit fitting Sticky containment.                                                                                                                                                                                                           | `spec:AST-025` FR21         | implemented                             |
-| FR8 | `contentOrViewport` MUST retain the named overflowing viewport, inspect the first sequential descendant on forward Tab entry, and delegate only to a native link/button outside navigation-key-owning surfaces. Reverse traversal from the delegated first child skips the viewport. Pointer/programmatic focus never delegates; eligibility is checked again on the next entry. | `spec:AST-025` FR12–FR13    | implemented                             |
-
-### Transformation and precedence order
-
-- **ORD1 — Effective state.** requested logical axis → computed physical axis →
-  scroll-capable overflow → geometry tolerance → normalized logical edge.
-- **ORD2 — Prop composition.** caller props and `xstyle` → behavior-owned
-  fitting/active overflow style → stable composed ref → behavior-owned keyboard,
-  state, and chaining outputs.
-
-### Performance and resources
-
-- **PR1 — Stable publication.** Equal effective/edge state reuses the prior object.
-- **PR2 — Shared observation.** Both element boxes use the shared ResizeObserver;
-  all secondary invalidation signals coalesce through one animation frame.
-
-## Accessibility contract
-
-- **AR1 — Named viewport owner.** Fixed viewport and automatic access require a
-  label and retain `tabIndex=0` while effectively scrollable. Automatic access
-  delegates only on forward keyboard entry; the descendant retains its own name
-  inside the named viewport group/region.
-- **AR2 — Focus continuity.** Content, eligibility, and geometry changes never
-  move or blur focus. A viewport losing overflow while focused remains
-  programmatically focusable. Reverse traversal from the delegated first child
-  skips the viewport, including after visiting later descendants.
-- **AR3 — Conservative eligibility.** Inspect the first sequential target; do not
-  search past an excluded one for a link/button. Composite roles, editable
-  surfaces, native or registered nested scroll owners, positive tab ordering,
-  popup triggers, and unproven interactive roles retain the viewport path.
-- **AR4 — Native scrolling.** Delegation MUST preserve Arrow/Page access to both
-  scroll edges without implementing JavaScript scrolling.
-
-## Design relationships
-
-No visual representation is owned by this hook.
-
-## Parent and system relationships
-
-- `component:ScrollableArea` owns the reference viewport/content composition.
-- `spec:AST-025` owns the shared behavior and adoption boundary.
-
-## Verification map
-
-| Contract         | Verification                                                                                                     | Representative states                                                                                                                                  | Mutation or failure expectation                                                                                                                 |
-| ---------------- | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| FR1–FR8, AR1–AR4 | `useScrollableArea.test.tsx`, `scrollKeyboardDelegation.test.ts`, and `BottomSheetKeyboard.a11y.browser.spec.ts` | horizontal/vertical/sideways, LTR/RTL, fit/overflow/edge, fixed/automatic keyboard owners, dynamic descendant eligibility, nested owners, focused loss | style-only or geometry-only ownership, physical-edge leakage, duplicate/missing keyboard path, stale state, ref loss, or dead containment fails |
-
-## Decision log
-
-### DEC-1 — Prop getters are the public composition seam
-
-**Reference:** `module:ScrollableArea/useScrollableArea/DEC-1`
-**Decider:** cixzhang, 2026-09-11
-
-One returned prop object per owned element keeps refs, accessibility, handlers,
-and behavior together without making consumer spread order part of correctness.
-
-### DEC-2 — Automatic ownership is shared behavior
-
-**Reference:** `module:ScrollableArea/useScrollableArea/DEC-2`
-**Decider:** cixzhang, 2026-09-13
-
-`contentOrViewport` retains the named overflowing viewport and delegates only on
-forward Tab entry to a safe first sequential native link/button. This replaces
-continuous keyboard-eligibility observation. Geometry observation is unchanged;
-keyboard eligibility adds no subtree or ancestor observers and is inspected anew
-at each entry. BottomSheet is a proving composition of this shared behavior.
-
-## Open questions
-
-None.
-
-## Content boundary
-
-This file does not duplicate consumer signatures/examples, ScrollableArea's
-structure/presentation, or Sticky's future API and positioning mechanism.

package/src/Section/Section.spec.md

@@ -1,197 +0,0 @@
----
-schema_version: 3
-template_version: 7
-kind: component
-id: component:Section
-authority: current
-archive_reason: null
-superseded_by: null
-approved_by: cixzhang
-approved_at: 2026-10-28
-owners: [cixzhang]
-review_triggers: [public-api, layout, theming, accessibility]
-verified_by:
-  [
-    packages/core/src/Layout/overlayPaddingReset.test.tsx,
-    .github/visual-baseline/manifest.json,
-    packages/core/src/serverSafeComponents.test.ts,
-    packages/core/src/Section/Section.test.tsx,
-    apps/storybook/stories/Section.stories.tsx,
-    packages/core/src/theme/themingTargets.test.ts,
-    scripts/check-knowledge.mjs,
-  ]
-modules: []
-families: [family:layout-regions]
-design_specs: []
-architecture:
-  [
-    architecture:component-theming-surface,
-    architecture:container-padding,
-    architecture:public-component-api,
-  ]
-contributing: []
-system_specs: []
----
-
-# Section component contract
-
-## Contract at a glance
-
-| Area                    | Contract                                                                                                                                                    |
-| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract         | A generic page region with `variant`, selected `dividers`, `padding` with axis and edge overrides, and box sizing.                                          |
-| Behavior                | An outer wrapper takes sizing and caller inputs and escapes a parent's inset; an inner container paints the variant and dividers and publishes its padding. |
-| End-user impact         | Readers see related content grouped in a region whose edges and spacing line up with the surrounding layout.                                                |
-| Builder impact          | None; the record describes shipped behavior.                                                                                                                |
-| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes. One implementation gap is listed under Current-state impact.                     |
-| Review checks           | Reject physical left/right dividers or padding, edge padding that does not move its matching container variable, or a nested Section that loses its escape. |
-| Governing rules         | `family:layout-regions/FR2,FR4,FR5,FR7–FR9`; `architecture:container-padding`; `architecture:public-component-api/INV5,INV6,INV8`.                          |
-
-This table is a review projection; the body below is authoritative.
-
-## Intent
-
-Section is the generic painted region of the layout-regions family. It owns
-its variant, selected divider edges, component padding, and how a nested
-Section escapes its parent's inset.
-
-## Compatibility and migration
-
-- Released default preserved: `yes`
-- Compatibility class: records shipped behavior; no public prop, default, DOM,
-  styling, or target changes
-- Controlled/uncontrolled behavior: not applicable
-- Migration decision: none
-
-Consumer migration instructions belong in consumer docs and release notes.
-
-## Current-state impact
-
-- **Painted region shorter than its minimum height (FR1).** With `minHeight`
-  and no `height`, the wrapper reaches the minimum but the inner container,
-  which carries the background, dividers, and padding, stays at its content
-  height. A `muted` or `section` region then paints only its top part, and
-  its bottom divider sits above the wrapper's bottom edge.
-
-## Ownership boundary
-
-**Owns**
-
-- The outer wrapper and the inner painted container with its `section` target.
-- Variant paint, selected divider edges, component padding and its publication,
-  and the nested escape.
-
-**Does not own / non-goals**
-
-- Caller content inside the section.
-- Slot arrangement — owned by `component:Layout` and its regions.
-- Landmark semantics, scrolling, and responsive substitution — not provided by
-  Section (`family:layout-regions` FR7–FR9).
-
-## Public concepts
-
-| Concept  | Closed values or states                              | Meaning                                  | Availability by variant/orientation/state | Default          | Owner               | Stability | Invalid-value behavior                                                                                  |
-| -------- | ---------------------------------------------------- | ---------------------------------------- | ----------------------------------------- | ---------------- | ------------------- | --------- | ------------------------------------------------------------------------------------------------------- |
-| Variant  | `section`, `transparent`, `muted`; theme additions   | Region background.                       | Always                                    | `section`        | `component:Section` | Stable    | A theme-added value with no matching theme rule renders no Section background and keeps `data-variant`. |
-| Dividers | any of `top`, `bottom`, `start`, `end`               | Which edges draw a 1px border.           | Always                                    | none             | `component:Section` | Stable    | TypeScript rejects other values.                                                                        |
-| Padding  | Spacing steps uniform, per axis, or per logical edge | Inner padding, published to descendants. | Always                                    | resolved per FR3 | `component:Section` | Stable    | TypeScript rejects other values.                                                                        |
-| Sizing   | `width`, `height`, `maxWidth`, `minHeight`           | The wrapper's box size.                  | Always                                    | unset            | `component:Section` | Stable    | Strings pass through as CSS.                                                                            |
-
-## Behavioral and layout contract
-
-| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Basis                                    |
-| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
-| FR1 | Section renders an outer `div` wrapper holding an inner `div` that carries the `section` target, reflects `variant`, and holds the children. The inner container fills the wrapper's height. Implementation gap: it fills only a set `height`; under `minHeight` alone the painted container stays at its content height inside a taller wrapper (Current-state impact).                                                                                                                                                                                                                                                                          | Current source and tests                 |
-| FR2 | `section` paints `--color-background-surface`, `transparent` paints nothing, and `muted` paints `--color-background-muted`; a theme-added variant with no matching theme rule paints no background and still reflects `data-variant` (`architecture:component-theming-surface` INV14). Each selected divider draws a 1px solid `--color-border` border on that edge; `start` and `end` are logical inline edges.                                                                                                                                                                                                                                  | Current source and tests                 |
-| FR3 | An omitted `padding` resolves per edge from the theme's per-edge and per-axis section padding, then the nearest ancestor Section's explicit `padding`, then the theme's single section padding, then spacing step 4. A step sets uniform padding and publishes it as the container-padding variables for descendants, and nested Sections without `padding` inherit it, except across an overlay boundary, where the inherited value stops (`architecture:container-padding` INV5). `paddingInline` and `paddingBlock` override one axis, and an edge prop overrides its edge alone; each override moves the matching container-padding variable. | Current source, tests, and family record |
-| FR4 | The wrapper escapes its parent's published container padding: always on both inline edges, and on the block-start edge only as a first child and the block-end edge only as a last child. The inner container resets the inherited padding variables before publishing its own.                                                                                                                                                                                                                                                                                                                                                                   | Current source and family record         |
-| FR5 | `ref`, `className`, `style`, `xstyle`, sizing, and DOM, data, ARIA, and event props reach the outer wrapper; numbers in sizing props are pixels. The inner painted container takes none of them; Toolbar relies on the wrapper routing.                                                                                                                                                                                                                                                                                                                                                                                                           | Current source and tests                 |
-
-### Allowed variation
-
-- **AV1 — Theme paint.** A theme may restyle `section` per `variant` and set
-  the section padding.
-- **AV2 — Content.** Any caller content fills the region.
-
-### Representative states
-
-| State         | Required invariant                                                          | Allowed variation |
-| ------------- | --------------------------------------------------------------------------- | ----------------- |
-| Default       | Surface paint; theme section padding; no dividers.                          | Content.          |
-| Divided       | 1px borders on selected logical edges.                                      | Edges.            |
-| Edge override | Only the named edge changes, with its container variable.                   | Step.             |
-| Nested        | Inner Section escapes the outer inset inline and at first/last block edges. | Variant.          |
-
-### Transformation and precedence order
-
-- **ORD1 — Padding per edge.** Edge prop → axis prop → `padding` → theme
-  per-edge and per-axis section padding → nearest ancestor Section's explicit
-  `padding`, not across an overlay boundary → theme single section padding → spacing step 4.
-
-### Performance and resources
-
-- **PR1 — Static render.** Section holds no state and uses no hooks.
-
-## Accessibility contract
-
-- **AR1 — No semantics added.** Section adds no role, name, landmark, or tab
-  stop (`family:layout-regions` FR8); callers supply a role and label when the
-  context needs one.
-
-## Design relationships
-
-| Anatomy or state  | Design requirement                                     | Representation authority | Hierarchy role    | Component contract |
-| ----------------- | ------------------------------------------------------ | ------------------------ | ----------------- | ------------------ |
-| Section container | The painted region with optional dividers and padding. | Current source and docs  | Supporting        | FR1–FR4            |
-| Consumer content  | Caller content inside the region.                      | Caller-supplied content  | Context-dependent | AR1                |
-
-### Theming anatomy
-
-<!-- anatomy-theming:v1 -->
-
-```json
-{
-  "Section container": {"target": "section"},
-  "Consumer content": {
-    "none": {
-      "reason": "intentional: caller content keeps its own theming ownership; Section applies no content target."
-    }
-  }
-}
-```
-
-The outer wrapper is implementation structure and carries no target.
-
-## Family and system relationships
-
-- `family:layout-regions` names Section the generic region and a container
-  publisher; FR2–FR4 apply its logical direction, padding, and boundary rules.
-- `architecture:container-padding` owns the inset protocol Section publishes
-  and escapes.
-- `architecture:public-component-api` owns caller-input routing; FR5 names
-  the outer wrapper as the element that receives caller inputs and `ref`
-  under INV5 and INV8.
-
-## Verification map
-
-| Contract            | Verification                                                                                                                                     | Representative states               | Mutation or failure expectation                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Audit section           |
-| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
-| FR1, FR2            | `Section.test.tsx` structure and variant tests; stable visual baseline `core-section--default`                                                   | Variants; default section           | A lost two-div structure, a lost `section` target on the inner `div`, or a lost variant reflection fails; a changed default surface comes back changed for review. Gap: the divider test asserts only that content renders, so divider borders and the `transparent` and `muted` paint have no automated check, and no check asserts the inner container fills the wrapper's height, including the `minHeight` gap. A theme-added variant with no matching rule also has no focused test. | `audit:Section/anatomy` |
-| FR3, ORD1           | `Section.test.tsx` padding, propagation, and edge-override tests; `overlayPaddingReset.test.tsx`; `Section.stories.tsx` NestedPaddingInheritance | Uniform, axis, edge, nested         | Axis-as-two-edges drift, edge over axis on the end edges, a lost propagated value for nested Sections, an ancestor Section's padding that crosses an overlay boundary, or a container variable (inline or block) that does not move with an edge override fails. Gap: edge over axis on the start edges, axis over uniform, the theme per-edge and per-axis padding ahead of the inherited value, and a variable that stops moving on both the axis and edge paths have no check.         | `audit:Section/layout`  |
-| FR4                 | `Section.stories.tsx` nested fixtures in a browser                                                                                               | Nested sections                     | Gap: no unit test asserts the escape margins; a lost escape is visible in the rendered fixture.                                                                                                                                                                                                                                                                                                                                                                                           | `audit:Section/layout`  |
-| FR5                 | `Section.test.tsx` ref, className, style, and passthrough tests                                                                                  | Caller inputs                       | A `className` or `style` that misses the outer wrapper, or a dropped `data-testid`, fails. Gap: the ref test accepts either `div`, the passthrough test finds `data-testid` anywhere in the tree so the routing of DOM, data, ARIA, and event props has no check, and the sizing and `xstyle` tests assert only that content renders.                                                                                                                                                     | `audit:Section/api`     |
-| AR1, PR1            | `serverSafeComponents.test.ts`; source review                                                                                                    | Every state                         | A client API (state, a hook) added without a client directive fails `serverSafeComponents.test.ts`. Gap: a client API added together with a client directive passes, and no automated check fails if Section adds a role, name, landmark, or tab stop.                                                                                                                                                                                                                                    | `audit:Section/a11y`    |
-| Theming anatomy map | `scripts/check-knowledge.mjs`                                                                                                                    | Consumer anatomy and current target | Missing, extra, or stale mappings fail repository validation.                                                                                                                                                                                                                                                                                                                                                                                                                             | `audit:Section/theming` |
-
-## Decision log
-
-None recorded. The record describes shipped behavior.
-
-## Open questions
-
-None.
-
-## Content boundary
-
-This file does not duplicate consumer prop tables/examples, current audit
-results, implementation steps, or family/system rules. It links to their owners.