@astryxdesign/core 0.6.0 → 0.6.1

package/src/RadioList/__tests__/RadioGroup.a11y.test.tsx

@@ -0,0 +1,217 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+/** @vitest-environment jsdom */
+
+/**
+ * @file RadioGroup.a11y.test.tsx
+ * @input Uses the shared radio-group contract and complete binding inventory
+ * @output DOM-layer binding evidence for direct and menu radio-group parts
+ * @position Fast migration lane; browser-owned outcomes remain explicitly unrun.
+ */
+
+import {cleanup, render, screen} from '@testing-library/react';
+import {describe, expect, it} from 'vitest';
+import {
+  RADIO_GROUP_PATTERN,
+  checkAccessibilitySpec,
+  createJsdomHarness,
+  expectAccessibilitySpec,
+  summarize,
+  unmatchedKnownFailures,
+  type BindingResult,
+} from '@astryxdesign/a11y-spec';
+import {RADIO_GROUP_KNOWN_FAILURES} from './RadioGroup.a11y.known-failures';
+import {RADIO_GROUP_STATE_RENDERS} from './RadioGroup.a11y.renders';
+import {
+  RADIO_GROUP_BINDING_STATES,
+  RADIO_GROUP_EXCLUSIONS,
+  type RadioGroupBindingRow,
+} from './RadioGroup.a11y.states';
+
+function subjectFor(state: RadioGroupBindingRow): Element {
+  return screen.getByRole(state.facts.role, {
+    name: state.subjectName,
+    hidden: true,
+  });
+}
+
+async function expectState(state: RadioGroupBindingRow): Promise<void> {
+  await expectAccessibilitySpec({
+    spec: RADIO_GROUP_PATTERN,
+    binding: state.binding,
+    state: state.id,
+    facts: state.facts,
+    knownFailures: RADIO_GROUP_KNOWN_FAILURES,
+    render: () => {
+      render(RADIO_GROUP_STATE_RENDERS[state.id]());
+    },
+    subject: () => subjectFor(state),
+    cleanup,
+  });
+}
+
+async function checkState(state: RadioGroupBindingRow): Promise<BindingResult> {
+  return checkAccessibilitySpec({
+    spec: RADIO_GROUP_PATTERN,
+    binding: state.binding,
+    state: state.id,
+    facts: state.facts,
+    knownFailures: RADIO_GROUP_KNOWN_FAILURES,
+    mount: async () => {
+      render(RADIO_GROUP_STATE_RENDERS[state.id]());
+      return createJsdomHarness({subject: subjectFor(state)});
+    },
+    unmount: cleanup,
+  });
+}
+
+describe('the shared radio-group pattern, jsdom lane', () => {
+  it.each(
+    RADIO_GROUP_BINDING_STATES.map(
+      state =>
+        [`${state.binding} [${state.id}]`, state.summary, state] as const,
+    ),
+  )('%s — %s', async (_id, _summary, state) => {
+    await expectState(state);
+  });
+
+  it('runs the DOM layer and reports higher layers as unrun', async () => {
+    const results: BindingResult[] = [];
+    for (const state of RADIO_GROUP_BINDING_STATES) {
+      results.push(await checkState(state));
+    }
+    const report = summarize(RADIO_GROUP_PATTERN, results);
+    expect(report.counts.pass).toBeGreaterThan(0);
+    expect(report.unrunLayers).toEqual(['accessibility-tree', 'real-browser']);
+    expect(report.counts.unexpectedPass).toBe(0);
+    expect(unmatchedKnownFailures(RADIO_GROUP_KNOWN_FAILURES, results)).toEqual(
+      [],
+    );
+  });
+});
+
+describe('the radio-group binding inventory', () => {
+  it('names a distinct checked-in story for every state', () => {
+    const ids = RADIO_GROUP_BINDING_STATES.map(state => state.storyId);
+    expect(new Set(ids).size).toBe(ids.length);
+  });
+
+  it('binds every current direct and menu radio-group part', () => {
+    const bound = new Set(
+      RADIO_GROUP_BINDING_STATES.map(state => state.binding),
+    );
+    expect([...bound].sort()).toEqual([
+      'DropdownMenuRadioGroup',
+      'DropdownMenuRadioItem',
+      'RadioList',
+      'RadioListItem',
+      'SegmentedControl',
+      'SegmentedControlItem',
+    ]);
+  });
+
+  it('records role-conditional and delegated surfaces explicitly', () => {
+    expect(
+      RADIO_GROUP_EXCLUSIONS.map(({owner, classification}) => ({
+        owner,
+        classification,
+      })),
+    ).toEqual([
+      {
+        owner: 'SelectableCard in independent or multi-select composition',
+        classification: 'preserved',
+      },
+      {
+        owner: 'SelectableCard in caller-managed single-select composition',
+        classification: 'needs-human',
+      },
+      {
+        owner: 'DropdownMenu and ContextMenu radio-item movement',
+        classification: 'out-of-scope',
+      },
+      {
+        owner: 'TabMenu overflow choices',
+        classification: 'out-of-scope',
+      },
+      {
+        owner: 'Pagination dots',
+        classification: 'out-of-scope',
+      },
+      {
+        owner: 'Home and End keyboard shortcuts',
+        classification: 'out-of-scope',
+      },
+    ]);
+    expect(RADIO_GROUP_EXCLUSIONS.every(row => row.reason.length > 0)).toBe(
+      true,
+    );
+  });
+
+  it('locks interaction ownership instead of letting bindings opt out', () => {
+    const wrong: string[] = [];
+    for (const state of RADIO_GROUP_BINDING_STATES) {
+      const facts = state.facts;
+      if (facts.part === 'group' && facts.role === 'radiogroup') {
+        for (const fact of [
+          'spaceSelection',
+          'pointerSelection',
+          'arrowSelection',
+        ] as const) {
+          if (facts[fact] !== facts.operable) {
+            wrong.push(
+              `${state.id}: direct-group ${fact}=${facts[fact]} but operable=${facts.operable}`,
+            );
+          }
+        }
+        if (facts.arrowSelection && facts.movement === 'none') {
+          wrong.push(`${state.id}: owns arrows without a movement model`);
+        }
+      } else if (facts.part === 'group') {
+        if (
+          facts.spaceSelection ||
+          facts.arrowSelection ||
+          facts.movement !== 'none'
+        ) {
+          wrong.push(`${state.id}: menu-owned keyboard behavior leaked in`);
+        }
+        if (facts.pointerSelection !== facts.operable) {
+          wrong.push(
+            `${state.id}: menu pointerSelection=${facts.pointerSelection} but operable=${facts.operable}`,
+          );
+        }
+      } else {
+        if (
+          facts.spaceSelection ||
+          facts.pointerSelection ||
+          facts.arrowSelection
+        ) {
+          wrong.push(`${state.id}: option row claims group-level interaction`);
+        }
+        if (facts.pointerCancellation !== facts.operable) {
+          wrong.push(
+            `${state.id}: pointerCancellation=${facts.pointerCancellation} but operable=${facts.operable}`,
+          );
+        }
+      }
+    }
+    expect(wrong).toEqual([]);
+  });
+
+  it('locks which bindings expose a visible label for the bound subject', () => {
+    const wrong = RADIO_GROUP_BINDING_STATES.filter(state => {
+      const expected =
+        state.binding !== 'SegmentedControl' &&
+        state.binding !== 'DropdownMenuRadioGroup' &&
+        state.id !== 'segmented-option-selected-hidden-label';
+      return state.facts.visibleLabel !== expected;
+    }).map(state => state.id);
+    expect(wrong).toEqual([]);
+  });
+
+  it('renders exactly one named subject for every state', () => {
+    for (const state of RADIO_GROUP_BINDING_STATES) {
+      render(RADIO_GROUP_STATE_RENDERS[state.id]());
+      expect(subjectFor(state), state.id).toBeTruthy();
+      cleanup();
+    }
+  });
+});

package/src/ScrollableArea/ScrollableArea.doc.mjs

@@ -0,0 +1,100 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
+export const docs = {
+  name: 'ScrollableArea',
+  displayName: 'Scrollable Area',
+  category: 'Layout',
+  keywords: ['scroll', 'overflow', 'viewport', 'logical axis', 'keyboard', 'overscroll', 'sticky', 'scrollbar', 'padding', 'full bleed'],
+  usage: {
+    description: 'Provides a native scroll viewport and a real observed content box. The viewport enters the tab order only while a requested logical axis is effectively scrollable, and containment applies only to effective axes.',
+    bestPractices: [
+      {guidance: true, description: 'Give every area a concise label that identifies the content keyboard users will scroll.'},
+      {guidance: true, description: 'Choose `inline`, `block`, or `both` from content intent; the component maps the logical axes through writing mode and direction.'},
+      {guidance: true, description: 'Keep the default `overscroll="allow"` for nested areas unless the interaction deliberately needs containment.'},
+      {guidance: true, description: 'Use `useScrollableArea` instead when a component already owns both a viewport and a suitable content box, or when children must remain direct flex/grid items or retain a definite percentage block-size basis.'},
+      {guidance: true, description: 'ScrollableArea owns one normal block content box with a 100% minimum size. Inline and both-axis modes use max-content inline sizing, so intrinsic inline layout is intentionally wider than the viewport.'},
+      {guidance: true, description: 'Use logical padding props on the content box so nested full-bleed components receive the same inset geometry.'},
+      {guidance: true, description: 'Set `isFullBleed` only when the viewport itself should reach an ancestor container edge; it is off by default.'},
+      {guidance: true, description: 'Set `stickyContainment="always"` only when a fitting viewport should intentionally remain a Sticky boundary.'},
+      {guidance: false, description: 'Hide the native scrollbar without another visible and operable overflow affordance.'},
+      {guidance: false, description: 'Add another overflow wrapper around ScrollableArea; one native viewport should own scrolling.'},
+    ],
+    anatomy: [
+      {name: 'Viewport', required: true, description: 'The root native scroll container, accessible name owner, focus target while effective, and `astryx-scrollable-area` theme target.'},
+      {name: 'Content box', required: true, description: 'A real inner layout box observed together with the viewport. For inline scrolling it uses max-content inline sizing with a 100% minimum.'},
+    ],
+  },
+  props: [
+    {name: 'axis', type: "'inline' | 'block' | 'both'", description: 'Logical axis or axes where native scrolling is allowed.', default: "'block'"},
+    {name: 'label', type: 'string', description: 'Accessible name for the viewport when it becomes keyboard scrollable.', required: true},
+    {name: 'role', type: "'group' | 'region'", description: 'Semantics for the named viewport.', default: "'group'"},
+    {name: 'overscroll', type: "'allow' | 'contain'", description: 'Whether effective axes continue scrolling an ancestor at their edge.', default: "'allow'"},
+    {name: 'width', type: 'SizeValue', description: 'Width of the viewport; a number is interpreted as pixels, a string is used as-is.'},
+    {name: 'height', type: 'SizeValue', description: 'Height of the viewport; a number is interpreted as pixels, a string is used as-is.'},
+    {name: 'maxWidth', type: 'SizeValue', description: 'Maximum width of the viewport.'},
+    {name: 'minHeight', type: 'SizeValue', description: 'Minimum height of the viewport.'},
+    {name: 'stickyContainment', type: "'whenScrollable' | 'always'", description: 'Whether fitting content passes Sticky ownership to an outer container or deliberately keeps this viewport as the CSS Sticky boundary.', default: "'whenScrollable'"},
+    {name: 'padding', type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10', description: 'Content padding on every logical edge; publishes matching inset geometry.', default: '0'},
+    {name: 'paddingInline', type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10', description: 'Logical inline-axis content padding; overrides `padding` on that axis.'},
+    {name: 'paddingInlineStart', type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10', description: 'Logical inline-start content padding; overrides broader padding values.'},
+    {name: 'paddingInlineEnd', type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10', description: 'Logical inline-end content padding; overrides broader padding values.'},
+    {name: 'paddingBlock', type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10', description: 'Logical block-axis content padding; overrides `padding` on that axis.'},
+    {name: 'paddingBlockStart', type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10', description: 'Logical block-start content padding; overrides broader padding values.'},
+    {name: 'paddingBlockEnd', type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10', description: 'Logical block-end content padding; overrides broader padding values.'},
+    {name: 'isFullBleed', type: 'boolean', description: 'Lets the viewport escape inherited container padding without changing content padding.', default: 'false'},
+    {name: 'children', type: 'ReactNode', description: 'Content rendered inside the observed content box.'},
+    {name: 'xstyle', type: 'StyleXStyles', description: 'StyleX sizing and native scrollbar presentation overrides for the viewport.'},
+  ],
+  playground: {
+    defaults: {
+      axis: 'block',
+      label: 'Scrollable example',
+      children: 'Add enough content to exceed a constrained viewport.',
+    },
+  },
+  theming: {
+    targets: [
+      {className: 'astryx-scrollable-area', visualProps: ['axis']},
+    ],
+  },
+};
+
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
+export const docsDense = {
+  description: 'native logical-axis scroll viewport with conditional keyboard access, live edge state, and observed content geometry',
+  usage: {
+    description: 'Use for a complete viewport/content composition; use useScrollableArea for existing structure.',
+    bestPractices: [
+      {guidance: true, description: 'Always provide a concise label.'},
+      {guidance: true, description: 'Prefer overscroll allow; contain only deliberate nested interactions.'},
+      {guidance: true, description: 'Use content padding props to publish inset; use isFullBleed only for viewport escape.'},
+      {guidance: false, description: 'Nest another overflow wrapper around it.'},
+    ],
+    anatomy: [
+      {name: 'Viewport', required: true, description: 'native scrolling, conditional tab stop, and theme target'},
+      {name: 'Content box', required: true, description: 'real observed layout box'},
+    ],
+  },
+  propDescriptions: {
+    axis: "logical scroll intent: 'inline' | 'block' (default) | 'both'",
+    label: 'required accessible viewport name',
+    role: "named viewport semantics: 'group' (default) | 'region'",
+    overscroll: "edge behavior: 'allow' (default) | 'contain' on effective axes only",
+    width: 'viewport width',
+    height: 'viewport height',
+    maxWidth: 'viewport maximum width',
+    minHeight: 'viewport minimum height',
+    stickyContainment: "fitting Sticky ownership: 'whenScrollable' (default) | 'always'",
+    padding: 'content inset on every edge; defaults to 0 and publishes geometry',
+    paddingInline: 'logical inline-axis content inset',
+    paddingInlineStart: 'logical inline-start content inset',
+    paddingInlineEnd: 'logical inline-end content inset',
+    paddingBlock: 'logical block-axis content inset',
+    paddingBlockStart: 'logical block-start content inset',
+    paddingBlockEnd: 'logical block-end content inset',
+    isFullBleed: 'opt-in viewport escape from inherited container padding',
+    children: 'content inside the observed box',
+    xstyle: 'viewport sizing and native scrollbar presentation overrides',
+  },
+};

package/src/ScrollableArea/ScrollableArea.spec.md

@@ -0,0 +1,189 @@
+---
+schema_version: 3
+template_version: 4
+kind: component
+id: component:ScrollableArea
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-09-11
+owners: [cixzhang]
+review_triggers: [public-api, behavior, layout, theming, accessibility]
+verified_by:
+  [
+    packages/core/src/ScrollableArea/ScrollableArea.test.tsx,
+    packages/core/src/hooks/useScrollableArea.test.tsx,
+    apps/storybook/stories/ScrollableArea.stories.tsx,
+  ]
+modules: [module:ScrollableArea/useScrollableArea]
+families: []
+design_specs: []
+architecture:
+  [architecture:container-padding, architecture:public-component-api]
+contributing: []
+system_specs: [spec:AST-025/DEC-1]
+---
+
+# ScrollableArea component contract
+
+## Intent
+
+ScrollableArea gives builders a complete native scroll viewport and observable
+content box without making them coordinate keyboard access, chaining, edge state,
+and native scrollbar presentation. It is the reference composition over the
+shared behavior hook, not the exclusive owner of that behavior.
+
+## Compatibility and migration
+
+- Released default preserved: not yet released
+- Compatibility class: additive component and package exports
+- Controlled/uncontrolled behavior: not applicable
+- Migration decision: `spec:AST-025/DEC-1`
+
+## Ownership boundary
+
+**Owns**
+
+- One root native viewport and one real observed inner content box.
+- Conditional viewport keyboard access, accessible naming, logical-axis intent,
+  overscroll policy, and native scrollbar defaults supplied by the shared hook.
+- Optional logical content padding that publishes matching container inset, plus
+  opt-in viewport bleed against inherited container padding.
+
+**Does not own / non-goals**
+
+- JavaScript-driven scrolling or custom scrollbar DOM.
+- A general Sticky public API or fallback positioning algorithm.
+- Existing component-owned viewport migrations such as Layout and Table.
+
+## Public concepts
+
+| Concept            | Closed values or states                    | Meaning                                     | Availability by variant/orientation/state | Default          | Owner                            | Stability | Invalid-value behavior |
+| ------------------ | ------------------------------------------ | ------------------------------------------- | ----------------------------------------- | ---------------- | -------------------------------- | --------- | ---------------------- |
+| logical axis       | `inline`, `block`, `both`                  | axes where native scrolling is allowed      | all                                       | `block`          | `spec:AST-025`                   | stable    | type error             |
+| overscroll         | `allow`, `contain`                         | whether effective axes propagate at an edge | all                                       | `allow`          | `spec:AST-025`                   | stable    | type error             |
+| viewport sizing    | `width`, `height`, `maxWidth`, `minHeight` | standard container geometry on the viewport | all                                       | auto             | `component:ScrollableArea`       | stable    | type error             |
+| content padding    | shared logical spacing-step ladder         | content-box inset and published geometry    | all                                       | `0`              | `architecture:container-padding` | stable    | type error             |
+| full bleed         | `false`, `true`                            | whether viewport escapes inherited inset    | all                                       | `false`          | `architecture:container-padding` | stable    | type error             |
+| Sticky containment | `whenScrollable`, `always`                 | whether fitting content captures Sticky     | all                                       | `whenScrollable` | `spec:AST-025`                   | stable    | type error             |
+| viewport semantics | `group`, `region` plus required label      | names a conditional keyboard scroll target  | all                                       | `group`          | `component:ScrollableArea`       | stable    | type error             |
+
+## Behavioral and layout contract
+
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                      | Basis                            | Acceptance and implementation state |
+| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | ----------------------------------- |
+| FR1 | The root MUST remain the one native viewport and receive the public ref, standard container sizing props, and styling inputs through StyleX.                                                                                                                                                                                                                                                                                                   | `spec:AST-025` IR3–IR4           | implemented                         |
+| FR2 | The inner content wrapper MUST be a real normal-flow block box observed with the viewport, use a 100% minimum size, and use max-content inline sizing only when inline scrolling is requested. Children participate in that box rather than the viewport's flex/grid formatting context, and the minimum block size does not create a definite percentage-height basis; structures that must preserve those semantics adopt the hook directly. | `spec:AST-025` FR5–FR6           | implemented                         |
+| FR3 | Native scrollbar behavior MUST remain authoritative; the default thumb uses `--color-neutral`, the track is transparent, and forced colors restore platform presentation.                                                                                                                                                                                                                                                                      | `spec:AST-025` FR15              | implemented                         |
+| FR4 | Scroll-state container queries MAY enhance descendant stuck/edge presentation, but hook state MUST remain the cross-browser source of truth.                                                                                                                                                                                                                                                                                                   | `spec:AST-025` platform support  | implemented progressively           |
+| FR5 | The content box MUST apply and publish logical padding with edge-over-axis-over-uniform precedence, defaulting every published edge to zero. `isFullBleed` MUST let only the viewport consume inherited inset; nested content continues to read the content box's published values.                                                                                                                                                            | `architecture:container-padding` | implemented                         |
+| FR6 | A fitting viewport MUST use `clip` on both physical axes so it prevents paint overflow without capturing native Sticky. Excess requested-axis geometry MUST activate the writing-mode-resolved `auto`/`hidden` pair. `stickyContainment="always"` MUST explicitly retain that pair while fitting.                                                                                                                                              | `spec:AST-025` FR21              | implemented                         |
+
+### Allowed variation
+
+- **AV1 — Sizing and presentation.** Consumer `xstyle`, `className`, and `style`
+  may size the viewport and adjust standards-based native scrollbar properties.
+- **AV2 — Content.** Any flow content may render in the observed box; builders
+  remain responsible for content semantics.
+
+### Representative states
+
+| State                          | Required invariant                                                                                      | Allowed variation          |
+| ------------------------------ | ------------------------------------------------------------------------------------------------------- | -------------------------- |
+| fitting                        | `clip` on both axes; no tab stop; Sticky passes outward unless containment is `always`; both edges true | viewport size and content  |
+| overflowing                    | named tab stop; per-axis logical edge state                                                             | one or both requested axes |
+| overflow removed while focused | remove future tab stop without moving focus                                                             | current focus remains      |
+| forced colors                  | native platform scrollbar presentation                                                                  | platform rendering         |
+
+### Transformation and precedence order
+
+- **ORD1 — Props.** Consumer DOM and styling props compose first; behavior-owned
+  ref, accessibility, and active-axis chaining win documented conflicts.
+
+### Performance and resources
+
+- **PR1 — Shared, coalesced observation.** Viewport and content resize signals use
+  the shared observer, and repeated invalidations publish at most once per frame.
+
+## Accessibility contract
+
+- **AR1 — Conditional access.** The viewport enters sequential navigation only
+  while at least one requested axis is effective, with the supplied label and role.
+- **AR2 — Focus continuity.** Losing overflow MUST NOT blur or move focus.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                                                | Representation authority | Hierarchy role | Component contract |
+| ---------------- | ----------------------------------------------------------------- | ------------------------ | -------------- | ------------------ |
+| Viewport         | platform scrollbar with token-colored thumb and transparent track | `spec:AST-025`           | supporting     | FR1, FR3           |
+| Content box      | no independent paint by default                                   | caller content           | structural     | FR2                |
+
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+  "Viewport": {"target": "scrollable-area"},
+  "Content box": {
+    "none": {
+      "reason": "intentional: The content box is structural and paints no component-owned appearance."
+    }
+  }
+}
+```
+
+## Family and system relationships
+
+- `module:ScrollableArea/useScrollableArea` owns reusable measurement,
+  overflow-boundary, Sticky-containment, accessibility, and registration behavior.
+- `architecture:container-padding` owns optional content inset publication and
+  opt-in viewport bleed.
+- `spec:AST-025` owns shared effective-axis, observation, accessibility, overscroll,
+  ownership, edge, and native presentation rules.
+
+## Verification map
+
+| Contract         | Verification                                     | Representative states                                                                                                                              | Mutation or failure expectation                                                                                                     | Audit section                   |
+| ---------------- | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
+| FR1–FR6, AR1–AR2 | component/hook tests and Storybook browser probe | fit, overflow, focused loss, LTR/RTL/vertical, nested allow/contain, fitting Sticky passthrough/containment, native scrollbar, padding, full bleed | duplicate viewport, stale state, dead nested scroll zone, implicit Sticky containment, unconditional tab stop, or stale inset fails | `audit:ScrollableArea/behavior` |
+
+## Decision log
+
+### DEC-1 — The convenience component owns one explicit content box
+
+**Reference:** `component:ScrollableArea/DEC-1`
+**Decider:** cixzhang, 2026-09-11
+
+A stable viewport/content structure gives the reference component dependable live
+measurement while leaving structure-owning components free to adopt the hook directly.
+
+### DEC-2 — ScrollableArea participates in the container-padding system
+
+**Reference:** `component:ScrollableArea/DEC-2`
+**Decider:** cixzhang, 2026-09-11
+
+The content box publishes its actual logical padding, zero by default, so nested
+bleed consumers never inherit stale inset. The viewport consumes ancestor inset
+only when `isFullBleed` is explicit; scrolling alone does not silently escape its
+parent container.
+
+### DEC-3 — Fitting content passes Sticky ownership outward by default
+
+**Reference:** `component:ScrollableArea/DEC-3`
+**Decider:** cixzhang, 2026-09-12
+
+A fitting viewport uses `clip` on both axes to prevent a pre-measure paint flash
+without becoming a CSS scroll container. Excess requested-axis geometry activates
+the writing-mode-resolved scroll boundary. `stickyContainment="always"` is the
+explicit opt-in for retaining that boundary while fitting.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer examples, the shared hook algorithm, Sticky's
+future public API, or migration plans for existing component-owned viewports.