An open source design system that's fully customizable and agent ready
TypeScript
docs: add contributor API conventions guide (#5725)
Cindy Zhang212c4fdad45b
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 84c8f67726..9cc3f98c46 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -4,7 +4,7 @@ For the full contribution process — what we accept, how to propose new componeKey pages:-- **[API Conventions](https://github.com/facebook/astryx/wiki/API-Conventions)** — naming, prop patterns, composition rules (read before submitting an RFC)+- **[API conventions guide](docs/contributing/api-conventions.md)** — practical naming, composition, styling, proposal, and review guidance linked to current owner records- **[Design Conventions](https://github.com/facebook/astryx/wiki/Design-Conventions)** — the design-side bar: tokens, spacing, radius, elevation, type, color, motion, and state representations- **[Specification Protocol](https://github.com/facebook/astryx/wiki/Component-Specification-Protocol)** — the 9-phase process for new components- **[Component Lifecycle](https://github.com/facebook/astryx/wiki/Component-Lifecycle)** — how components move from lab → core and templates from hidden → visiblediff --git a/docs/README.md b/docs/README.mdindex d748831a47..0d07d0fcef 100644--- a/docs/README.md+++ b/docs/README.md@@ -7,6 +7,7 @@ it governs. Consumer documentation remains in component `.doc.mjs` files and## Placement- `architecture/`: the shipped system, its boundaries, and invariants.+- `contributing/`: practical contributor workflows that project current owner records without replacing them.- `design/`: human-owned visual and interaction specifications.- `families/`: contracts shared by sibling components.- `specs/`: consequential proposed or shipped system changes and their decisions.diff --git a/docs/contributing/README.md b/docs/contributing/README.mdnew file mode 100644index 0000000000..6c4431f732--- /dev/null+++ b/docs/contributing/README.md@@ -0,0 +1,8 @@+# Contributing guides++These guides turn current Astryx owner records into practical contribution steps.+They do not create policy or replace architecture, specifications, family+contracts, or component contracts.++- [API conventions](api-conventions.md): shape, propose, implement, and review a+ public component API.diff --git a/docs/contributing/api-conventions.md b/docs/contributing/api-conventions.mdnew file mode 100644index 0000000000..069ee50bf6--- /dev/null+++ b/docs/contributing/api-conventions.md@@ -0,0 +1,258 @@+# API conventions for contributors++Use this guide to shape a public component API before review. This page is a+practical projection. It does not create policy. If it conflicts with a current+owner record, follow the owner record and fix this guide.++This repository guide is the maintained contributor reference. The public wiki+may provide an overview and rationale, but it should link here instead of keeping+a second copy of these conventions.++## Start with the owner++Use only records whose front matter says `authority: current`. Read the narrowest+owner first when one is linked or easy to find. Human contributors do not need to+understand or edit the spec system to contribute; reviewers and maintainers route+new decisions and record final rulings.++1. The component's `<Name>.spec.md`, when one exists beside its code in+ [`packages/core/src/`](../../packages/core/src/), owns component behavior.+2. A current contract under [`docs/families/`](../families/) owns behavior shared+ by sibling components.+3. Current architecture and accepted system decisions own cross-component rules.+ Start with the [public component API architecture](../architecture/public-component-api.md),+ the [knowledge contract](../architecture/knowledge-contracts.md), and+ [AST-002: public component prop admission](../specs/AST-002/spec.md).++The `owners` field names who can settle a missing decision. Component source and+its public `index.ts` own the shipped API. The component's `.doc.mjs` explains+that API to consumers.++The wiki gives broader background: [API Conventions](https://github.com/facebook/astryx/wiki/API-Conventions)+and [API Arbitration](https://github.com/facebook/astryx/wiki/API-Arbitration).+Do not copy detailed decisions from those pages into a proposal. Link the current+owner instead.++## Name one concept at a time++| Surface | Convention | Example |+| ---------------------------- | --------------------------------------- | ----------------------------- |+| Component | Unprefixed PascalCase | `Button`, `TextInput` |+| Props type | `<Component>Props` | `ButtonProps` |+| Public hook | `use<Name>` | `usePopover` |+| Boolean state | `is<Name>` | `isDisabled` |+| Boolean capability | `has<Name>` | `hasClear` |+| Uncontrolled boolean default | `defaultIs<Name>` or `defaultHas<Name>` | `defaultIsOpen` |+| Synchronous callback | `on<Verb>` | `onChange` |+| Disambiguated callback | `on<Verb><Scope>` | `onSidebarCollapsedChange` |+| Transition Action | `<verb>Action` | `changeAction`, `clickAction` |+| Logical direction | `start` or `end` | `startIcon`, `paddingEnd` |++Use callback scope only when the verb could refer to more than one part. Use an+`html` prefix only for a native attribute that passes through unchanged, such as+`htmlName`. Keep the clearer semantic name when the component owns the concept.++String values use `camelCase`. A prop should control one independent concept.+Do not combine unrelated states into one convenience mode.++## Callbacks and Actions++A callback reports an event synchronously. An Action starts transition-aware+work. The Action name never starts with `on`.++`changeAction` does not replace `onChange`. A component may support either or+both. When both are present, run the callback first. Run the Action afterward+unless the component's public event contract lets the consumer cancel it.++```tsx+interface SearchInputProps {+ value: string;+ onChange?: (+ value: string,+ event: React.ChangeEvent<HTMLInputElement>,+ ) => void;+ changeAction?: (+ value: string,+ event: React.ChangeEvent<HTMLInputElement>,+ ) => void | Promise<void>;+}++const [, startTransition] = React.useTransition();++function handleChange(event: React.ChangeEvent<HTMLInputElement>) {+ const nextValue = event.currentTarget.value;+ onChange?.(nextValue, event);++ if (changeAction && !event.defaultPrevented) {+ startTransition(() => changeAction(nextValue, event));+ }+}+```++Do not name the Action `onChangeAction`. Do not require every input callback by+category. Requiredness follows the component's usable-state, control, and+accessibility contract.++When a component and a consumer both handle the same React event, compose the+handlers deliberately. Put the consumer first only when the public contract+promises that `preventDefault()` cancels built-in behavior.++```tsx+const handleClick = composeEventHandlers(onClickProp, selectItem);+```++If cancellation is not promised, preserve the component's required behavior and+state that order in its contract and tests.++## DOM props, styling, and refs++Extend [`BaseProps`](../../packages/core/src/BaseProps.ts) only when the component+owns a stable DOM element. A component that only coordinates children or returns+multiple unrelated roots should expose the smaller contract it actually owns.++For a DOM-owning component:++- type `BaseProps` with the contract element and accept `ref` as a React 19 prop;+- remove native names that collide with component concepts by using `Omit`;+- forward neutral `data-*`, ARIA, DOM, and event props to the contract element;+- keep component-owned role, accessibility, and behavior props from being+ overwritten; and+- merge `xstyle`, `className`, and `style` instead of choosing one.++```tsx+export interface PanelProps extends BaseProps<HTMLDivElement> {+ ref?: React.Ref<HTMLDivElement>;+ children: React.ReactNode;+}++export function Panel({+ children,+ ref,+ xstyle,+ className,+ style,+ ...rest+}: PanelProps) {+ return (+ <div+ ref={ref}+ {...mergeProps(+ themeProps('panel'),+ stylex.props(styles.root, xstyle),+ className,+ style,+ )}+ {...rest}>+ {children}+ </div>+ );+}+```++Destructure styling and owned handlers before spreading `rest`. Use+`composeEventHandlers` when both sides need the same event. Set component-owned+contract props after `rest` so spread order cannot change semantics.++## Open visual vocabularies and closed axes++A theme-extensible visual vocabulary uses a public `*Map` interface in the+component subpath barrel. Derive the prop type from its keys.++```ts+// packages/core/src/Button/index.ts+export interface ButtonVariantMap {+ primary: true;+ secondary: true;+ ghost: true;+ destructive: true;+}++// packages/core/src/Button/Button.tsx+export type ButtonVariant = keyof ButtonVariantMap;+```++A theme can add a visual value through module augmentation of+`@astryxdesign/core/Button`. Keep behavioral and structural axes closed when a+theme must not invent new meanings. Examples include interaction modes,+directions, placement rules, and finite state-machine states.++Do not assume a nested `theme.components.button.variants` shape. Follow the current+[theme authoring contract](../architecture/theme-authoring-contract.md) for+component target and style-key overrides.++## Slots and composition++Prefer composition when content or child behavior has its own contract. A named+slot accepts the complete child and renders it directly.++```tsx+<AppShell+ topNav={<TopNav items={items} />}+ sideNav={<SideNav sections={sections} />}+/>+```++Do not hoist `SideNav` state or callbacks onto `AppShell`. Keep them on the child+that owns them. Use a render function only when the parent must provide item data+or context. Use a prop for a finite independent axis, not for a one-off product+recipe.++High-level compositions have a higher bar for new props than utility components.+Before adding a prop, check whether a child, slot, theme target, styling escape+hatch, parent layout, or existing context already owns the distinction.++## API proposal checklist++Before requesting review:++- **Find the owner.** Link the nearest current component, family, architecture,+ or system record when it is known. If it is not clear, explain the intended+ behavior normally; the reviewer routes the decision.+- **Prove caller ownership.** Show two otherwise identical cases that need+ different outcomes, why the caller knows the difference, and why the component+ cannot derive it. This is the admission rule in+ [AST-002](../specs/AST-002/spec.md#dec-1--public-props-require-a-non-derivable-caller-distinction).+- **Show the consumer API.** Include the default, configured or controlled,+ composed, edge, and migration cases that apply.+- **Check the shared grammar.** Cover names, optionality, callback/Action order,+ cancellation, ref target, DOM pass-through, and whether each string axis is+ open or closed.+- **Protect compatibility.** State defaults and observable behavior. Include a+ migration for a released breaking change.+- **Ship evidence together.** Update consumer docs, public exports, focused+ runtime and type tests, and representative integration coverage in the same+ pull request.++If two or three viable shapes remain after applying current conventions, use the+[API Arbitration](https://github.com/facebook/astryx/wiki/API-Arbitration)+process. Compare realistic consumer code across the relevant cases and put the+evidence in the pull request. Ask the owner to decide. A maintainer or review+agent records the final ruling in the owning spec. Keep the research procedure+out of architecture records.++## Common review smells++- A prop exposes a value the component can derive from state, content, layout,+ context, or the platform.+- A high-level component accumulates tuning props or duplicates a child's state.+- Equivalent concepts use different names, such as `onChangeAction` instead of+ `changeAction`.+- An Action suppresses its callback, or handler order accidentally removes a+ promised consumer cancellation path.+- A callback is required only because all inputs were assumed to require it.+- A theme-extensible visual value is a closed union, or a behavioral axis is+ opened to theme augmentation.+- `BaseProps` is applied to a component without one stable contract element, or+ accepted DOM props never reach that element.+- `xstyle`, `className`, `style`, a ref, or an event handler is dropped or+ clobbered by spread order.+- A parent wraps slot content or mirrors props that belong to the slotted child.+- A proposal invents a nested `theme.components.button.variants` layer instead of+ using the current component target and style-key contract.+- A green docs parser is treated as full API proof. Parsing and selected drift+ checks do not prove export reachability, runtime behavior, ref targets,+ pass-through, handler composition, compatibility, or complete doc coverage.++When a current record conflicts with another current record, stop. Do not choose+by recency or specificity. Route the conflict to the canonical owner described in+the [knowledge contract](../architecture/knowledge-contracts.md#when-current-records-disagree).