An open source design system that's fully customizable and agent ready
TypeScript
docs: define public component API architecture (#5723)
Cindy Zhang7c0009dba630
diff --git a/docs/architecture/public-component-api.md b/docs/architecture/public-component-api.mdnew file mode 100644index 0000000000..2f22fd55a8--- /dev/null+++ b/docs/architecture/public-component-api.md@@ -0,0 +1,143 @@+---+schema_version: 1+template_version: 1+kind: architecture+id: architecture:public-component-api+authority: current+archive_reason: null+superseded_by: null+approved_by: cixzhang+approved_at: 2026-08-30+owners: [cixzhang, imdreamrunner]+applies_to:+ [+ packages/core/src/,+ packages/core/package.json,+ packages/core/src/BaseProps.ts,+ packages/cli/authoring/doctypes/component/,+ internal/eslint-plugin-astryx/,+ ]+verified_by:+ [+ internal/eslint-plugin-astryx/require-base-props.js,+ internal/eslint-plugin-astryx/require-baseprops-passthrough.js,+ packages/core/src/docPropLiterals.test.ts,+ packages/core/src/docPropReferences.test.ts,+ ]+deciding_specs: [spec:AST-002/DEC-1]+---++# Public component API++This record defines the shared public API contract for stable Astryx components.++## Purpose++Consumers should be able to predict how an Astryx component is imported,+controlled, extended, and composed without learning its internal implementation.+New API should express caller-owned intent and preserve established behavior.++## System model++The installable package is the public contract. It includes:++- exported components and hooks;+- exported props and stable supporting types;+- published component subpaths;+- documented defaults; and+- behavior consumers can observe.++Consumer `.doc.mjs` files explain that contract. They do not create props or+policy that the exported code does not have.++Once this record is `current`, every current component contract lists+`architecture:public-component-api` in its `architecture` links. Draft component+contracts add that link only after this record becomes current, so candidate+relationships do not create authority early.++Component and family contracts own narrower behavior. Theme records own theme+targets, public theme properties, tokens, and generated styles. Contribution+guidance owns the process used to propose and test APIs.++## Boundaries and invariants++- **INV1 — Public exports are reachable.** A stable component, hook, prop type,+ and other promised public types are available from their published package+ entry point or component subpath.+- **INV2 — Names carry the same meaning.** Components, hooks, booleans,+ callbacks, Actions, directions, refs, and native HTML pass-throughs follow the+ shared naming grammar. Component-specific vocabulary stays local.+- **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.+- **INV4 — New props express caller-owned intent.** New public props follow+ `spec:AST-002/DEC-1`. A component keeps a decision internal when it can derive+ the correct result from state, content, layout, context, or platform behavior.+- **INV5 — Accepted consumer props are preserved.** For a DOM-owning component,+ supported DOM, data, ARIA, style, class, and event inputs reach the element that+ owns the contract. Component-owned accessibility and behavior cannot be+ accidentally overwritten.+- **INV6 — Styling inputs combine.** `xstyle`, `className`, and `style` compose in+ their documented order instead of replacing one another.+- **INV7 — Event handlers compose deliberately.** Consumer handlers and built-in+ behavior use the shared cancellation contract. A consumer can cancel built-in+ behavior only where that public API promises cancellation.+- **INV8 — Refs follow React 19.** A public DOM component accepts `ref` as a prop+ and connects it to the element promised by its contract.+- **INV9 — Released APIs change deliberately.** A released prop, type, export,+ default, or observable behavior is not removed, renamed, or retyped without an+ explicit compatibility decision and migration.+- **INV10 — Shared subcontracts are linked, not copied.** Input Actions, layer+ behavior, theming, and family-specific rules stay with their owning records.++This record applies to stable public packages. Lab components are not stable+public promises until promotion.++## Change coupling++- Adding or changing an exported prop, type, default, package entry point, ref+ target, or observable behavior triggers public-API review.+- Consumer docs and representative tests change with the API in the same pull+ request.+- A new prop includes the admission argument from `spec:AST-002/DEC-1`; it does+ not get accepted only because it solves one callsite.+- A released breaking change includes the compatibility decision and migration+ evidence required by the release process.+- Changes to a family-owned API update the family contract rather than copying+ its rule into this record or every component.++## Owning code++- Public package manifests and component barrels own reachable exports.+- Component prop/type definitions and runtime behavior own the actual API.+- `BaseProps` defines the shared DOM/styling surface for DOM-owning components.+- `.doc.mjs` files own consumer-facing prop descriptions, defaults, and examples.+- Astryx ESLint rules and API/doc tests check the shared contract.++## Deciding specs++- `spec:AST-002/DEC-1` — a new public prop requires caller-owned information the+ component cannot derive.++Transition Action sequencing and pending behavior belong to their component or+family contract. This record links that owner once it is current; it does not+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 |+| Consumer-doc projection | `docPropReferences.test.ts` and `docPropLiterals.test.ts` | Docs name a nonexistent prop or omit public literal choices |++Known verification gaps:++- 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.++These gaps are named here rather than treating partial checks as complete proof.