Skip to content

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.md
index 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 hook
whose current signature cannot delegate gains a ref-taking signature beside
it; 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, such
as TopNavMegaMenuFeaturedCard's `linkLabel` and `linkHref` and
TopNavHeading'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.