Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

docs(public-component-api): interaction utilities have matching non-React equivalents; shipped APIs are grandfathered (#9973)

Cindy Zhanga1a615186efa
diff --git a/docs/architecture/public-component-api.md b/docs/architecture/public-component-api.md
index 5d6d8a501f..e53f79c6e6 100644
--- a/docs/architecture/public-component-api.md
+++ b/docs/architecture/public-component-api.md
@@ -117,7 +117,10 @@ guidance owns the process used to propose and test APIs.
`elevation`, which takes values from `Elevation`, as Card, Button, and Banner
take it. `lift` names motion under a press, such as
Switch's thumb lift, Slider's `springs.sliderLift`, and ContextMenu's
- `springs.contextMenuLift`, so it does not name a layout distance.
+ `springs.contextMenuLift`, so it does not name a layout distance. An element
+ ref a hook takes is named for the element's job, as `containerRef`,
+ `scrollRef`, `menuRef`, `triggerRef`, and `inputRef` are, or `ref` when the element has
+ no narrower job.
- **INV3 — One prop controls one independent concept.** A prop does not silently
suppress an unrelated prop. A parent does not duplicate state already owned by
a composed child. One interaction behavior is one prop, never parallel touch,
@@ -220,26 +223,29 @@ guidance owns the process used to propose and test APIs.
- **INV20 — Variants, not visual booleans.** Avoid boolean flags that only swap visuals; prefer variants. This
applies INV2's naming and INV4's caller-owned intent to visual choices; see
[Open visual vocabularies and closed axes](../contributing/api-conventions.md#open-visual-vocabularies-and-closed-axes).
-- **INV21 — One API per job.** No new
- API that shares a job with existing API, unless the existing API is being
- deprecated in favor of it. INV3 keeps one prop to one concept and INV16 keeps
- one `presentation` prop for a surface choice; INV21 applies the same rule
- across props, components, hooks, and factories. A hook that delegates
- entirely to a public factory, with no behavior of its own, and a component
- built entirely on a public factory are one API with that factory, not a
- second one (`spec:AST-107` FR6, FR8). A deprecation follows
- INV9.
-- **INV22 — Every interaction hook has a non-React path.** A public hook that
- attaches gesture, press, drag, or motion behavior to an element delegates
- entirely to a public `create…(element, options)` factory that takes the same
- options, with React content taken as a render callback (`spec:AST-107` FR8),
- and returns a handle with `destroy()` (`spec:AST-107` FR6), except a
- hook whose result only an Astryx React component or StyleX can use, such as
- `useAnimatedLayout`, `useEntryAnimation`, `useContainerReveal`,
- `useTouchTrigger`, `useTableRowExpansion`, and `useTableColumnResize`. A hook
- whose current signature cannot delegate gains a ref-taking signature beside
- it; the old signature is deprecated under INV9. A factory's announced and shown
- strings follow `architecture:internationalization` INV3a's options.
+- **INV21 — One API per job.** No new API that shares a job with existing API,
+ unless the existing API is being deprecated in favor of it. INV3 keeps one
+ prop to one concept and INV16 keeps one `presentation` prop for a surface
+ choice; INV21 applies the same rule across props, components, hooks, and
+ factories. A hook that delegates entirely to a public factory, with no
+ behavior of its own, and a component built entirely on a public factory are
+ one API with that factory, not a second one (`spec:AST-107` FR6, FR8). A
+ deprecation follows INV9. A hook whose value a component takes through one
+ slot prop is one API with that component, not a second one, as in `const value
+= useX(…); <Component x={value} />` (owner decision, 2026-11-04).
+- **INV21a — Shipped APIs change only for user value.** A breaking or
+ deprecating change to a shipped public API needs user value; conformance to a
+ system rule alone does not justify it. New APIs follow the current rules;
+ shipped APIs are grandfathered until a real need arises (owner decision,
+ 2026-11-04). Each component API change still needs its own owner approval.
+- **INV22 — Interaction utilities have non-React equivalents.** Interaction
+ utilities have non-React equivalents (`create…`) that closely match their
+ hooks (the same option names and meanings, events and return concepts). A hook
+ whose result only an Astryx component or StyleX can use (a slot hook, whose
+ output feeds one Astryx component prop, or `useAnimatedLayout`,
+ `useEntryAnimation`, `useContainerReveal`, `useTouchTrigger`,
+ `useTableRowExpansion`, `useTableColumnResize`) has none by default; the owner
+ may add one (owner decision, 2026-11-04).
- **INV23 — Each private data attribute has one owner module.** A
`data-astryx-*` attribute is private unless this invariant names it public.
Each private attribute has one internal owner module in the package that
@@ -405,8 +411,9 @@ Rejected: component-local names for shared concepts.
| INV18 | Public-API review against the component's anatomy table | A prop that selects or configures a subcomponent's prop or label, a composition that renders a slot the anatomy does not describe, or a rendered content slot that is not a part named in the anatomy |
| INV19 | Public-API review with a bundle and runtime cost note for a costly feature | A feature with a large resource cost that every caller pays with no plug-in path or named feature prop |
| INV20 | Public-API review of new boolean props | A boolean whose only effect is a visual swap where a variant fits |
-| INV21 | Public-API review against existing props, components, hooks, and factories | A new API that shares a job with an existing one that is not being deprecated in its favor |
-| INV22 | Public-API review of each public gesture, press, drag, or motion hook against its `create…` factory | A public interaction hook with no public factory taking the same options and returning `destroy()`, outside the listed exemptions |
+| INV21 | Public-API review against existing props, components, hooks, and factories | A new API that shares a job with an existing one that is not being deprecated in its favor; a hook fed to one component slot prop counted as a second API |
+| INV21a | Public-API review of each breaking or deprecating change to a shipped API | A breaking or deprecating change to a shipped public API justified only by conformance to a system rule |
+| INV22 | Public-API review of each public interaction utility hook against its `create…` equivalent | An interaction utility hook with no `create…` equivalent, outside hooks whose result only an Astryx component or StyleX can use, or an equivalent whose option names and meanings, events, or return concepts differ from its hook |
| INV23 | `@astryx/no-raw-private-attribute` lint with its baseline (test files exempt), plus public-API review of the public list | A `data-astryx-*` name or selector written outside its owner module, a test, or the public list; a `dataAttr()` call that names a private attribute; an owner module that exports its raw name or a selector; a package that imports another package's owner module; a caller that sets a property an owner style it spreads also sets; a private attribute in a public export, `.doc.mjs`, or Changeset; a baseline entry added; a public data attribute changed without INV9 evidence |
| INV24 | API report generator tests over representative entry points, plus the pull-request report's API changes | A promised export, prop, hook, type, custom property, theme target, or public attribute is missing from a report; a reachable internal-tagged member is missing; an `./internal/*` or Lab member appears; a stale committed report is not flagged, or its rows are listed as the pull request's API changes; the check fails a pull request |
| INV25 | Public-API review routing against the pull request's API changes | A row that no current record decides does not reach human review; a row a current record decides is held for a human; an undeclared row alone draws a request for changes |
@@ -435,14 +442,13 @@ Known verification gaps:
another keeps its name until a minor renames it under INV9. Outline's
`offset` is the distance below the top of its scroll root
(`component:Outline` FR4), not a gap from an anchor.
-- INV22: known gaps include `useLongPress`, `useMenuPress`,
- `usePressFeedback`, `useClickableContainer`, `useInputContainer`,
- `useOverlay`, `useCombobox`, `useMultiCombobox`, `useResizable`,
- `useTooltip`, `useHoverCard`, and `useChatStreamScroll`: each attaches
- gesture, press, drag, or motion behavior and has no `create…` factory yet;
- no full inventory exists yet. Each conforms by adding its factory and, where
- its signature cannot delegate, a ref-taking signature beside the deprecated
- one.
+- INV22: known gaps include `useLongPress`, `useMenuPress`, `usePressFeedback`,
+ `useClickableContainer`, `useInputContainer`, `useOverlay`, `useCombobox`,
+ `useMultiCombobox`, `useResizable`, `useTooltip`, `useHoverCard`, and
+ `useChatStreamScroll`: each attaches gesture, press, drag, or motion behavior
+ and has no `create…` factory yet; no full inventory exists yet. Each conforms
+ by adding its factory; a shipped hook's signature changes only when a real
+ need arises (INV21a).
- The passthrough lint is warning-only while known violations remain.
- The current source-to-doc completeness matcher still looks for old prefixed
props interfaces, so it does not yet prove full prop coverage.