An open source design system that's fully customizable and agent ready
TypeScript
spec(public-component-api): each private data attribute has one owner module (INV23) (#9182)
Cindy Zhangd18fdaa66c1a
diff --git a/docs/architecture/public-component-api.md b/docs/architecture/public-component-api.mdindex f90096f904..584b8fc2b1 100644--- a/docs/architecture/public-component-api.md+++ b/docs/architecture/public-component-api.md@@ -14,6 +14,8 @@ applies_to:packages/core/src/,packages/core/package.json,packages/core/src/BaseProps.ts,+ packages/lab/src/,+ packages/richtext/src/,packages/cli/authoring/doctypes/component/,internal/eslint-plugin-astryx/,]@@ -211,9 +213,43 @@ guidance owns the process used to propose and test APIs.`useTouchTrigger`, `useTableRowExpansion`, and `useTableColumnResize`. A hookwhose current signature cannot delegate gains a ref-taking signature besideit; the old signature is deprecated under INV9.+- **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+ writes it, `packages/<package>/src/privateAttributes/<name>.stylex.ts`, that+ holds its name and values and writes each selector on it once, as a literal in+ its own `stylex.create` call; StyleX resolves a selector only where it is+ written. The owner exports only ready-made styles that read the attribute, the+ props or writer that set it, and the runtime readers its package needs, such+ as a `closest` or `matches` helper or a getter; it never exports the raw name+ or a selector. Every other file in that package spreads those exports and+ never writes the attribute or its selector, and no package imports another+ package's owner module through an internal path. StyleX merges styles one+ whole property at a time, so an owner style carries every condition of each+ property it sets, its rest state and pointer states included, and a caller+ does not set those properties again on the same element. Outside the owner+ modules and test files, a hand-typed `data-astryx-` string, template, or JSX+ attribute name, or a `dataAttr()` call that names a private attribute, fails+ the `@astryx/no-raw-private-attribute` lint rule; sites that predate the rule+ sit in its baseline, which only shrinks. Tests may name a private attribute,+ because they assert the DOM a component renders. A private attribute appears+ in no public export, `.doc.mjs`, or Changeset, carries no compatibility+ promise, and may change in any release. The public data attributes are+ `data-astryx-theme`, the theme scope (`spec:AST-066` FR6);+ `data-astryx-media`, the media-surface scope that theme compilation emits;+ `data-astryx-aspect-ratio-override` (`component:AspectRatio` FR3);+ `data-astryx-token` and `data-astryx-token-value`+ (`component:ChatComposerTokenElement` FR1); `data-astryx-menu-press`, the+ menu-root marker (`module:DropdownMenu/useMenuPress`);+ `data-astryx-pressable`, the press marker (`component:SegmentedControlItem`+ FR7); and `data-astryx-edge-comp`, exported as `EDGE_COMP_ATTR` (INV12). They+ change only under INV9. The code that owns them writes them at its own sites,+ among them Theme, MediaTheme, `reset.css`, `generateThemeRules.ts`, the CLI+ theme build, AspectRatio, the Chat composer, the press and menu-press hooks,+ and the edge-compensation styles, and the lint rule allows their names.-This record applies to stable public packages. Lab components are not stable-public promises until promotion.+This record applies to stable public packages, and INV23 also applies to Lab+source. Lab components are not stable public promises until promotion.## Change coupling@@ -284,25 +320,26 @@ copy the component matrix.## Verification-| Invariant | Evidence | Failure signal |-| ----------------------- | --------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| INV1, INV8 | Export, public-subpath, prop, and ref checks | A promised component/type cannot be imported or its ref cannot reach the contract element |-| INV2 | Naming and logical-direction lint/tests | Equivalent concepts use conflicting names or physical direction leaks into public API |-| INV3, INV4 | Historical API review benchmark and `spec:AST-002` evidence | A prop combines unrelated axes or exposes a derivable implementation choice |-| INV5, INV6, INV7 | BaseProps/passthrough lint and representative runtime tests | Consumer ARIA/data/style/events are dropped, clobber component semantics, or fail to compose |-| INV9 | Published-surface, Changeset, migration, and public-type checks | A released API changes without explicit compatibility evidence |-| INV11 | Public-API admission review plus owning theming/component tests | A public semantic custom property exposes derivable or unsupported implementation detail |-| INV12, INV13 | Generated declaration/export/behavior inventory plus canonical-owner mapping | A reachable supporting type or behavior outside `./internal/*` is called internal, or mechanical evidence is treated as permission to accept it |-| INV14 | `AppShell.test.tsx` | A component hardcodes a divergent point or treats equality as below |-| INV15 | Public-API review of the generated declaration inventory | A part or StyleX-typed styling prop ships without class-name and inline-style counterparts on the same element |-| INV16 | Public-API review of touch presentations plus coarse- and fine-pointer runtime tests | A stable component that presents a different surface or switches an open surface's input mode under a coarse pointer and has no `presentation` value that keeps its fine-pointer surface and mode; such a touch mode callers cannot reach; a default that overrides an explicit caller choice |-| INV17 | Resolver tests at the compact edges plus public-API review | A component that chooses a presentation by screen size with its own numbers, or disagrees with the theme compact definition at width 768 or height 500 |-| 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 |-| Consumer-doc projection | `docPropReferences.test.ts` and `docPropLiterals.test.ts` | Docs name a nonexistent prop or omit public literal choices |+| Invariant | Evidence | Failure signal |+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| INV1, INV8 | Export, public-subpath, prop, and ref checks | A promised component/type cannot be imported or its ref cannot reach the contract element |+| INV2 | Naming and logical-direction lint/tests | Equivalent concepts use conflicting names or physical direction leaks into public API |+| INV3, INV4 | Historical API review benchmark and `spec:AST-002` evidence | A prop combines unrelated axes or exposes a derivable implementation choice |+| INV5, INV6, INV7 | BaseProps/passthrough lint and representative runtime tests | Consumer ARIA/data/style/events are dropped, clobber component semantics, or fail to compose |+| INV9 | Published-surface, Changeset, migration, and public-type checks | A released API changes without explicit compatibility evidence |+| INV11 | Public-API admission review plus owning theming/component tests | A public semantic custom property exposes derivable or unsupported implementation detail |+| INV12, INV13 | Generated declaration/export/behavior inventory plus canonical-owner mapping | A reachable supporting type or behavior outside `./internal/*` is called internal, or mechanical evidence is treated as permission to accept it |+| INV14 | `AppShell.test.tsx` | A component hardcodes a divergent point or treats equality as below |+| INV15 | Public-API review of the generated declaration inventory | A part or StyleX-typed styling prop ships without class-name and inline-style counterparts on the same element |+| INV16 | Public-API review of touch presentations plus coarse- and fine-pointer runtime tests | A stable component that presents a different surface or switches an open surface's input mode under a coarse pointer and has no `presentation` value that keeps its fine-pointer surface and mode; such a touch mode callers cannot reach; a default that overrides an explicit caller choice |+| INV17 | Resolver tests at the compact edges plus public-API review | A component that chooses a presentation by screen size with its own numbers, or disagrees with the theme compact definition at width 768 or height 500 |+| 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 |+| 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 |+| Consumer-doc projection | `docPropReferences.test.ts` and `docPropLiterals.test.ts` | Docs name a nonexistent prop or omit public literal choices |Known verification gaps:@@ -329,5 +366,20 @@ Known verification gaps:- INV18: shipped props that configure a subcomponent's label or target, suchas TopNavMegaMenuFeaturedCard's `linkLabel` and `linkHref` andTopNavHeading's `logoLabel`, conform only through replacement under INV9.+- INV23: the `@astryx/no-raw-private-attribute` rule and its baseline do not+ exist yet, and no owner module exists yet; public-API review is the check+ until they do. The `data-astryx-press` selector is copied in 14 Core files.+ Other private attributes still written at their sites include+ `data-astryx-popover-fallback-close` and DropdownMenu's+ `data-astryx-submenu-regions`, which Popover and DropdownMenuSubMenu also read+ at runtime; `data-astryx-table-pinned` and `data-astryx-cell-gliding`, each+ named in two files; `data-astryx-scrolling`, read but never written;+ DropdownMenu's `data-astryx-submenu-host`; the Chat composer's+ `data-astryx-dictation-interim`; and RichText's+ `data-astryx-richtext-code-syntax`. No full inventory exists yet. Each+ conforms by moving into an owner module in its own package, with a runtime+ reader from that module where its package reads the attribute in code. Lab's+ Schedule reads Core's `data-astryx-popover-fallback-close`, and conforms+ through Core's public API or an attribute Lab owns.These gaps are named here rather than treating partial checks as complete proof.