An open source design system that's fully customizable and agent ready
TypeScript
docs(windowing): one shared private windowing module (spec only) (#10287)
Cindy Zhangcdd64dfe4572
diff --git a/docs/architecture/list-windowing.md b/docs/architecture/list-windowing.mdnew file mode 100644index 0000000000..6ca4cb5f96--- /dev/null+++ b/docs/architecture/list-windowing.md@@ -0,0 +1,119 @@+---+schema_version: 1+template_version: 3+kind: architecture+id: architecture:list-windowing+authority: current+archive_reason: null+superseded_by: null+approved_by: cixzhang+approved_at: 2026-11-06+owners: [cixzhang]+applies_to:+ [+ packages/core/src/Selector/,+ packages/core/src/Table/,+ packages/core/src/Chat/,+ ]+verified_by: [scripts/check-knowledge.mjs]+deciding_specs: []+---++# List windowing architecture++## Contract at a glance++| Area | Contract |+| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| Governing contract | None. Each consumer's record owns what a person sees and hears in its long list; this record owns only which module computes the window. |+| System behavior | One shared internal windowing module owns long-list windowing in Core. Selector is its first consumer, then Table virtualization, then Chat. The module is not public API (INV1, INV2). |+| End-user impact | None yet: the module does not exist, and Selector renders every option. Once it ships, people opening a long list wait less, and every windowed list behaves the same way. |+| Builder impact | A Core component that windows a long list calls the one module instead of building its own. No public windowing hook exists while OQ1 is open. |+| Compatibility/readiness | Additive and internal. Spec only: the build has not started (Current-state impact). Table's approved virtualization hook keeps its public shape. |+| Review checks | Reject a second windowing implementation in Core, a public export of the module, or a change to Table's public virtualization shape made to adopt it. |+| Governing rules | DEC-1. |++This table is a review projection; the body below is authoritative.++## Purpose++Long lists in Core render only the rows a person can see. This record gives+that job one owner, so each component that windows a list shares one+implementation instead of keeping its own.++## System model++A windowed list renders the rows that cover its visible scrollport, plus a few+rows past each edge, and sizes its scroll range for the full list. The shared+windowing module computes which rows render and where the scroll range ends.+Each consumer keeps its own records for when it windows, what it renders, and+how it exposes the full list to assistive technology.++Consumers, in adoption order:++1. Selector's option list.+2. Table's row virtualization, behind `module:Table/useTableRowsVirtualization`.+3. Chat's message list.++## Boundaries and invariants++- **INV1 — One windowing module in Core.** In `@astryxdesign/core`, one shared+ internal module owns long-list windowing. A component that windows a long+ list uses it and keeps no windowing implementation of its own. Snap-paged+ pane scrollers, such as the touch calendar's `MonthScroller` shared by+ DateInput and DateTimeInput (`paneWindow` in `monthGeometry.ts`,+ `component:DateInput` PR1), keep their own pane window and are outside this+ module.+- **INV2 — The module is private.** The module is not public API: it isn't+ exported from any public entry point; another Astryx package may reach it+ only through a Core `./internal/*` subpath (`spec:AST-017` FR21). This holds+ while OQ1 is open.+- **INV3 — Consumers keep their public shapes.** Adopting the module changes+ no consumer's public API. `module:Table/useTableRowsVirtualization` keeps its+ approved public shape and uses the module internally.++## Current-state impact++- **No module exists yet.** The build has not started. Selector renders every+ option when it opens. Table's virtualization hook is specified in+ `module:Table/useTableRowsVirtualization` but not built; Chat renders every+ message.++## Change coupling++Review against this record when a change adds or alters windowing,+virtualization, or a rendered-row calculation in a Core list, or exports a+windowing symbol.++## Owning code++- `packages/core/src/Selector/` — the first consumer.+- `module:Table/useTableRowsVirtualization` — Table's public virtualization+ hook, the second consumer; it has no code yet (Current-state impact).+- `packages/core/src/Chat/` — the third consumer.++The module itself has no path yet (Current-state impact).++## Deciding specs++### DEC-1 — One shared private windowing module++**Reference:** `architecture:list-windowing/DEC-1`+**Decider:** `cixzhang`, `2026-11-06`++One shared private windowing module owns long-list windowing in Core; spec+only. Selector adopts it first, then Table virtualization and Chat. The module+stays private while OQ1 is open.++## Open questions++- **OQ1 — Is the windowing module public (a hook) or internal only?** Not+ decided. Until it is, the module stays private (INV2).++## Verification++| Invariant | Evidence | Failure signal |+| --------- | ------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------- |+| INV1 | Review of each Core list that windows (evidence gap: no module or automated check exists yet) | A Core component keeps its own windowing implementation beside the module |+| INV2 | Public export review of every package entry point (evidence gap: no module exists yet) | The module, or a type only it uses, is reachable from a public entry point |+| INV3 | The public-API report for `useTableRowsVirtualization` and each consumer (evidence gap: the hook is not built yet) | Adopting the module changes a consumer's public props, types, or exports |