Skip to content

docs(api): ref inputs end in Ref and match an existing role's name; API review raises every mismatch - #12699

Draft
cixzhang wants to merge 7 commits into
mainfrom
lane2/ref-naming-records
Draft

cixzhang wants to merge 7 commits into
mainfrom
lane2/ref-naming-records

Conversation

@cixzhang

@cixzhang cixzhang commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Records only. People building with Astryx get one rule for ref inputs: a prop or hook option that takes a ref ends in Ref, takes only a ref, and uses the name an existing prop already uses for the same role, such as anchorRef for the element a layer sits on. Public-API review now checks every new or changed name against the components and hooks that already serve the same role, and raises each mismatch. The native-first spec states that a ref is React-only.

Exact decision needed

None: the owner decided each point (DEC-8, DEC-9). This pull request records them. Her 13:35 decision that props live in the contracts package, with a high bar for a new prop, goes in its own records pull request with the contracts-package decision it depends on.

Existing authority searched

  • architecture:public-component-api: INV2 (names carry the same meaning; element refs a hook takes are named for the element's job), INV8 (refs), INV9, INV21a, INV22 (create… equivalents), INV24 (API delta), INV25 (routing), DEC-1 (system vocabulary).
  • spec:AST-082: FR3 (core and platform contracts; the web contract holds refs), FR4 (portable core; ReactNode and render functions are not portable), FR5, DEC-8.
  • Terms searched: Ref, anchorRef, triggerRef, handleRef, getScroller, getContainer, scrollElement, RefObject, contracts package, new prop.

Overlap checked: #12559, #11176, #10127, #10102, #6091, #6061, #12707 (the first six edit public-component-api.md or the visual-prop contract for other claims and take INV26 to INV28 and DEC-3 to DEC-5 and DEC-7, so this pull request uses INV29, INV30, DEC-8 and DEC-9; #12707 edits spec:AST-082 FR3, DEC-7 and DEC-17 for the contracts decision, while this pull request adds only an FR4 bullet there)

Decision

  • INV29 (DEC-8): a public prop, hook option, or returned ref that holds a React ref ends in Ref and has a ref type (RefObject<T | null>, Ref<T>, or RefCallback<T>). A bare ref conforms: a component's ref prop (INV8), a hook element ref with no narrower job (INV2), and a returned ref that combines several refs for one element (useTooltip, useHoverCard). It never takes a bare element or a getter. A prop or hook option for a role an existing one already names uses that name and wording (anchorRef, triggerRef, handleRef). A create… equivalent keeps the name and takes any object with a current element. INV2's element-ref sentence points to INV29.
  • INV30 (DEC-9): for each API delta row, public-API review searches for existing members with the same role, by the role's words and type, and compares the row with them, INV2, INV29, DEC-1 and the API conventions. It raises every mismatch as a finding that names the member to match, and never marks one optional. A new prop that a better default behavior can replace is also a finding.
  • spec:AST-082 FR4: a React ref is not portable; a core contract states the need neutrally and each platform's contract maps it (on React, a …Ref prop).

Rejected alternatives

  • DEC-8: an input that takes a ref or a getter; a new name for a role an existing input already names.
  • DEC-9: reviewing a new name only against its own component.

Claim scope and non-goals

  • Records only, with no code renames. The four shipped members that break INV29 (useMenuPress getScroller, useLayerDismissal getContainer, Popover's anchorRef, whose type excludes null, and useLayer's returned trigger ref) are listed as an INV29 gap and get separate follow-ups, timed by INV21a. Lab ChatVirtualizer's scrollElement must conform on promotion.
  • useHoverCard's returned positionRef keeps its name (INV21a). usePopover's anchor option is decided in its own stack, not here.
  • No lint rule. The verification row names public-API review, and the gap line names the missing lint.

Evidence and implementation relationship

An audit of the public entries of @astryxdesign/core, @astryxdesign/lab and @astryxdesign/richtext (159 entries, using the TypeScript checker) found 41 members that hold a ref, a getter or an element, or whose name ends in Ref. 38 comply and 3 do not (two shipped hook getters and one Lab element). A type check adds Popover's anchorRef, typed RefObject<HTMLElement>, and a return check adds useLayer's returned trigger ref. So the INV29 gap line lists four shipped members, and Lab's scrollElement conforms on promotion.

Writing rubric results

  • R1 narration: none. Each new invariant and FR bullet describes the system in the present tense. The owner quotes are inside the decisions, as the decision template has them.
  • R2 research in the record: none. The audit numbers stay in this description; the record names only the three violating inputs, in its gap line.
  • R3 evidence naming a change: none. The verification rows name review evidence and failure signals.
  • R4 rejected alternatives over one line or outside a decision: none. DEC-8 and DEC-9 each have one Rejected: sentence inside the decision.
  • R5 pull request or issue references remaining: none.
  • R6 ruled open questions still listing options: none touched.
  • R7 project status (build status or work order): none. The INV29 gap line states the gap without "yet".

Scope

Components: none (records: architecture:public-component-api, spec:AST-082)

  • This PR contains specification records only.
  • It records observable behavior and preserves equivalent internal implementations.
  • Any named internal mechanism is intentionally public, names its dependent caller/system, and explains why an equivalent implementation would not satisfy the contract.
  • Verification states the evidence layer and failure signal without prescribing CI job/workflow topology.
  • It records one intentional durable decision, not a rescue for a separable tagalong.
  • The canonical knowledge owner, affected current claims, and overlapping open work are named; any ownership collision is resolved or called out for human decision.
  • Adjacent API, visual, accessibility, composition, and implementation facts remain outside scope unless this exact decision depends on them.
  • Public text and artifacts contain no internal Meta context.

Validation

  • pnpm check:knowledge: templates and records aligned.
  • Prettier: clean.
  • git diff --check: clean.

@vercel

vercel Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
astryx Building Building Preview Nov 20, 2026 2:51am UTC

Request Review

@astracat-bot

astracat-bot Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

AI review status for this pull request.

Review status Updated
🔄 In progress (for maintainers only) Nov 20, 2026, 2:54 AM UTC

@meta-cla meta-cla Bot added the CLA Signed This label is managed by the Meta Open Source bot. label Nov 18, 2026
@github-actions github-actions Bot added the needs:spec-owner-review Current knowledge records await owner approval label Nov 18, 2026
@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

PR Analysis Report

Current run: The current CI run concluded skipped. Current analysis is unavailable.


Generated by PR Enrichment workflow | View current CI run

@cixzhang

Copy link
Copy Markdown
Contributor Author

/approve-spec 1dcfc28

@github-actions github-actions Bot removed the needs:spec-owner-review Current knowledge records await owner approval label Nov 18, 2026

@astracat-bot astracat-bot Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changes requested. The owner's exact-head spec approval settles the direction of INV29, INV30, DEC-8, DEC-9 and DEC-17. What remains are three text fixes in the records.

  • INV29 says that a ref name "ends in Ref", but INV2 still allows a hook element ref named ref, INV8 gives every public DOM component a ref prop, and useLayer, useTooltip, useHoverCard and useTruncation return ref: INV29 and its verification row should say that a bare ref conforms (or list these as gaps and drop INV2's ref).
  • The new AST-082 FR3 bullet puts every public prop in "the private contracts package", which no record names and which conflicts with the unchanged DEC-7 ("@astryxdesign/native stays the single cross-platform contracts package", "Core keeps the core and web contracts") and FR16 ("core never imports native"): FR3 should name the package, DEC-7 should be amended to match, and Current-state impact should name the FR3 gap.
  • Popover's anchorRef is typed React.RefObject<HTMLElement> (packages/core/src/Popover/Popover.tsx:231), which breaks INV29's type sentence: the INV29 gap line should list four shipped inputs, and the description's audit numbers should be corrected.

Two smaller points are on the lines: DEC-8 mentions a usePopover anchorRef that does not exist yet, and the gap line lists a Lab member although this record reaches Lab only through INV23.

Claims and files checked

Review mode: full; reason: no-earlier-review

  • Claim: INV29 states the Ref suffix, the ref types, no bare element or getter, the role names, and the create… rule, and INV2 points to it: present in the record (INV2, INV29); the ref conflict is a finding.
  • Claim: INV30 makes review search for same-role members and raise every mismatch, never as optional: verified in the record.
  • Claim: AST-082 FR4 says a React ref is not portable, and FR3 with DEC-17 puts props in one contracts package: present; the FR3 package conflict is a finding.
  • Claim: the owner decided DEC-8, DEC-9 and DEC-17: verified by an engineering owner's spec approval for this exact head.
  • Claim: other open pull requests hold INV26 to INV28, DEC-3 to DEC-5 and DEC-7, so INV29, INV30, DEC-8 and DEC-9 are free: verified against those pull requests' patches; DEC-17 is the next free number in AST-082.
  • Claim: records only, with no code renames: verified (two Markdown files).
  • Claim: three shipped inputs break INV29 (getScroller, getContainer, scrollElement): the three are verified, but "only three" is false (Popover anchorRef type, returned ref members).
  • Claim: INV21a keeps the two shipped hook options, and useHoverCard's positionRef keeps its name: verified.
  • Claim: usePopover's anchor is decided elsewhere: verified absent at this head; DEC-8 still mentions it (non-blocking).
  • Claim: no lint rule, so review is the verification and the gap names the missing lint: verified.
  • Claim: the audit found 41 members, 38 complying and 3 not: false, see the findings.
  • Claim: writing rubric R1 to R7 report none: verified by reading the added lines (no narration, no pull request references, no status words).
  • Claim: knowledge validation, Prettier and the whitespace check are clean: verified at this head.
  • Claim: public text holds no internal context: verified.
  • File: docs/architecture/public-component-api.md: findings (INV29 and a bare ref; the INV29 gap line), plus two non-blocking notes.
  • File: docs/specs/AST-082-native-first-surfaces/spec.md: finding (the FR3 contracts package against DEC-7 and FR16).

Automated review (maintainer link)

…ab conforms on promotion; the contracts-package bullet and DEC-17 move to their own record change
@cixzhang

Copy link
Copy Markdown
Contributor Author

/approve-spec 6287bef

@github-actions github-actions Bot removed the needs:spec-owner-review Current knowledge records await owner approval label Nov 18, 2026

@astracat-bot astracat-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changes requested: one record fix remains. An engineering owner's spec approval for this head settles the direction of INV29, INV30, DEC-8, DEC-9 and the spec:AST-082 FR4 ref bullet, and the earlier round's other points are fixed.

  • INV29 lets a returned bare ref conform only "when the element has no narrower job", but useLayer returns ref for its trigger element (a job INV2 and INV29 name triggerRef) and the gap line does not list it, while the verification row exempts only a ref "that INV8 or INV2 allows" and INV2 covers only refs a hook takes: make the row say "that INV29 allows", and either list useLayer's ref (and decide the combined ref of useTooltip and useHoverCard) in the gap line or state that these returned refs conform.

Two non-blocking notes: INV29's role sentence says "a prop" although its examples and verification row cover hook options (missed in the earlier round), and the description's overlap line predates #12707, which also edits spec:AST-082.

Claims and files checked

Review mode: full; reason: spec-record

  • Claim: records only, with no code renames: verified (two Markdown records).
  • Claim: INV29 sets the Ref suffix, the ref types, no element or getter input, the role names, the create… rule, and a bare ref where INV8 or INV2 allows it, and INV2 points to it: present; the returned-ref wording is the finding above.
  • Claim: INV30 makes review search for same-role members and raise every mismatch, never as optional: verified.
  • Claim: spec:AST-082 FR4 says a React ref is not portable: verified.
  • Claim: the owner decided DEC-8 and DEC-9: verified by an engineering owner's spec approval for this exact head.
  • Claim: the contracts-package decision goes in its own pull request: verified; it is gone from this head.
  • Claim: other open pull requests take INV26 to INV28, DEC-3 to DEC-5 and DEC-7: verified against their patches; "no open pull request edits spec:AST-082" is out of date (#12707).
  • Claim: three shipped inputs break INV29 (getScroller, getContainer, Popover's anchorRef type), and Lab scrollElement conforms on promotion: verified against the declarations.
  • Claim: useHoverCard's positionRef keeps its name, and usePopover's anchor is decided elsewhere: verified.
  • Claim: no lint rule, so the verification row names review and the gap line names the missing lint: verified.
  • Claim: the audit found 41 members, 38 complying and 3 not, plus Popover's anchorRef: the named members are verified; the totals were not reproduced, and useLayer's returned ref is unsettled under the new text (the finding).
  • Claim: writing rubric R1 to R7 report none: verified by reading the added lines.
  • Claim: knowledge validation, Prettier and the whitespace check are clean: verified at this head.
  • Claim: public text holds no internal context: verified.
  • File: docs/architecture/public-component-api.md: finding (returned bare ref), plus one non-blocking note.
  • File: docs/specs/AST-082-native-first-surfaces/spec.md: clear.

Automated review (maintainer link)

…trigger ref is a shipped gap; the same-role rule covers hook options
@github-actions github-actions Bot added the needs:spec-owner-review Current knowledge records await owner approval label Nov 18, 2026
@cixzhang

Copy link
Copy Markdown
Contributor Author

/approve-spec 5bc8a11

@github-actions github-actions Bot removed the needs:spec-owner-review Current knowledge records await owner approval label Nov 18, 2026

@astracat-bot astracat-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changes requested: two description corrections remain, and the records need no change. An engineering owner's spec approval for this exact head settles INV29, INV30, DEC-8, DEC-9 and the spec:AST-082 FR4 ref bullet, and the earlier round's record findings are fixed.

  • The overlap line says no open pull request edits spec:AST-082, but #12707 is open and edits that record's FR3, DEC-7 and DEC-17, so name it in the overlap line.
  • The audit summary ("38 comply and 3 do not", plus Popover's anchorRef) counts three shipped deviations, while the INV29 gap line and the claim-scope list name four now that useLayer's returned ref is a gap, so update the totals.

Both are description edits, so no new commit is needed and the spec approval for this head stays valid. One non-blocking suggestion: INV29 could say that a trigger props object spread onto an element, such as PopoverTriggerRenderProps, keeps ref, since spec:AST-055 FR2 requires that spread.

Claims and files checked

Review mode: full; reason: spec-record

  • Claim: records only, with no code renames: verified (two Markdown records).
  • Claim: INV29 sets the Ref suffix, the ref types, no element or getter input, the role names, the create… rule and when a bare ref conforms, and INV2 points to it: verified.
  • Claim: INV30 makes review search same-role members and raise every mismatch, never as optional, and flags a prop a better default can replace: verified.
  • Claim: spec:AST-082 FR4 says a React ref is not portable and React maps the need to a …Ref prop: verified.
  • Claim: the owner decided DEC-8 and DEC-9, so no decision is needed: verified by an engineering owner's spec approval for this exact head.
  • Claim: the contracts-package decision goes in its own records pull request: verified (#12707).
  • Claim: other open pull requests take INV26 to INV28, DEC-3 to DEC-5 and DEC-7: verified against their patches.
  • Claim: no open pull request edits spec:AST-082: false (#12707).
  • Claim: four shipped members break INV29, kept under INV21a, and Lab scrollElement conforms on promotion: verified against the declarations.
  • Claim: useHoverCard's positionRef keeps its name and usePopover's anchor is decided elsewhere: verified; nothing is renamed and usePopover has no anchor option.
  • Claim: no lint rule, so the verification row names review and the gap line names the missing lint: verified.
  • Claim: the audit found 41 members, 38 complying and 3 not, plus Popover's anchorRef: false at this head (useLayer's returned ref is a fourth shipped deviation); the totals were not reproduced.
  • Claim: writing rubric R1 to R7 report none: verified by reading the added lines.
  • Claim: knowledge validation, Prettier and the whitespace check are clean: verified at this head.
  • Claim: public text holds no internal context: verified.
  • File: docs/architecture/public-component-api.md: clear, with one non-blocking suggestion.
  • File: docs/specs/AST-082-native-first-surfaces/spec.md: clear.

Automated review (maintainer link)

Comment on lines +341 to +344
and nothing else. A bare `ref` conforms: a component's `ref` prop (INV8); a
hook's element ref, as an option or a return, when the element has no
narrower job (INV2); and a returned ref that combines several refs for one
element, as `useTooltip`'s and `useHoverCard`'s `ref` do. A function that

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Non-blocking: these allowances do not say whether a handed-back trigger props object counts. PopoverTriggerRenderProps.ref (packages/core/src/Popover/Popover.tsx:177) and the ref of DropdownMenu's, ComplexSelector's and MultiSelector's trigger props attach the trigger element, a job this invariant names triggerRef. spec:AST-055 FR2 requires such an object to spread onto one element, so its key has to stay ref. One clause saying that a props object spread onto an element keeps ref would keep the verification row from reading onto them.

@astracat-bot astracat-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved pending CI: this draft has not run CI yet, and CI runs once the pull request is marked ready for review. An engineering owner's spec approval for this exact head settles INV29, INV30, DEC-8, DEC-9 and the spec:AST-082 FR4 ref bullet, and the description now names #12707 and counts the same four shipped members as the INV29 gap line.

One non-blocking suggestion stays open on the INV29 allowances: say that a trigger props object spread onto an element, such as PopoverTriggerRenderProps, keeps ref, since spec:AST-055 FR2 requires that spread.

Claims and files checked

Review mode: same-head; reason: none

  • Claim: records only, with no code renames: verified (two Markdown records).
  • Claim: INV29 sets the Ref suffix, the ref types, no element or getter input, the role names, the create… rule and where a bare ref conforms, and INV2 points to it: verified.
  • Claim: INV30 makes review search same-role members and raise every mismatch, never as optional, and flags a prop a better default can replace: verified.
  • Claim: the native-first spec's FR4 says a React ref is not portable and React maps the need to a …Ref prop: verified.
  • Claim: the owner decided DEC-8 and DEC-9, so no decision is needed: verified by an engineering owner's spec approval for this exact head.
  • Claim: the contracts-package decision goes in its own records pull request: verified (#12707).
  • Claim: the six other overlapping pull requests take INV26 to INV28, DEC-3 to DEC-5 and DEC-7: verified against their patches.
  • Claim: #12707 edits the native-first spec's FR3, DEC-7 and DEC-17, while this pull request adds only an FR4 bullet there: verified against its patch.
  • Claim: four shipped members break INV29 and are kept under INV21a, and Lab's scrollElement conforms on promotion: verified against the declarations.
  • Claim: useHoverCard's positionRef keeps its name and usePopover's anchor is decided elsewhere: verified; nothing is renamed and usePopover has no anchor option.
  • Claim: no lint rule, so the verification row names review and the gap line names the missing lint: verified.
  • Claim: the audit's type and return checks add Popover's anchorRef and useLayer's returned ref, so the gap line lists four shipped members: verified against the gap line and the source; the audit's totals were not recounted.
  • Claim: writing rubric R1 to R7 report none: verified by reading the added lines.
  • Claim: knowledge validation, Prettier and the whitespace check are clean: verified at this head.
  • Claim: public text holds no internal context: verified.
  • File: docs/architecture/public-component-api.md: clear, with one non-blocking suggestion.
  • File: docs/specs/AST-082-native-first-surfaces/spec.md: clear.

Automated review (maintainer link)

@github-actions github-actions Bot added the needs:spec-owner-review Current knowledge records await owner approval label Nov 19, 2026
@cixzhang

Copy link
Copy Markdown
Contributor Author

/approve-spec 2838126

@github-actions github-actions Bot removed the needs:spec-owner-review Current knowledge records await owner approval label Nov 19, 2026

@astracat-bot astracat-bot Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved pending CI: required checks are still running on this head. An engineering owner's spec approval for this exact head settles INV29, INV30, DEC-8, DEC-9 and the spec:AST-082 FR4 ref bullet, and the records need no change.

test-node (5/9) fails because Lab's MediaPlayer has no swizzle sample (packages/cli/test/swizzle-proof/samples.test.mjs), a state this branch carries from main; main added the sample in #13001, so merging main again clears it, and that new head needs a fresh /approve-spec.

One non-blocking suggestion stays open on the INV29 allowances: say that a trigger props object spread onto an element, such as PopoverTriggerRenderProps, keeps ref, since spec:AST-055 FR2 requires that spread.

Claims and files checked

Review mode: same-head; reason: none

  • Records only, with no code renames: verified (two Markdown records change).
  • A ref input ends in Ref, takes only a ref, and reuses an existing role's name: verified in INV29 and DEC-8.
  • Public-API review checks each new or changed name against members with the same role and raises every mismatch: verified in INV30 and DEC-9.
  • The native-first spec says a ref is React-only: verified (the FR4 bullet).
  • Four shipped members break INV29 (getScroller, getContainer, Popover's anchorRef type, useLayer's returned ref): verified against their declarations and the gap line.
  • useHoverCard's returned positionRef keeps its name, usePopover's anchor is decided elsewhere, and Lab's scrollElement conforms on promotion: verified.
  • Overlapping work, including #12707 editing the native-first spec's FR3, DEC-7 and DEC-17 while this pull request adds only an FR4 bullet: verified.
  • INV2's element-ref sentence points to INV29: verified.
  • No lint rule, with the verification row naming public-API review and the gap line naming the missing lint: verified.
  • Each decision has one rejected-alternatives sentence, and the records carry no pull request references: verified.
  • The knowledge-record check, Prettier and git diff --check pass: verified at this head.
  • The audit totals (159 entries, 41 members): not re-derived; the members they find breaking the rule are verified.
  • The owner decided each point: verified (an engineering owner approved this exact head).
  • docs/architecture/public-component-api.md: non-blocking note (spread trigger props objects); otherwise clear.
  • docs/specs/AST-082-native-first-surfaces/spec.md: clear.

Automated review (maintainer link)

@cixzhang
cixzhang marked this pull request as ready for review November 20, 2026 02:25
@cixzhang
cixzhang marked this pull request as draft November 20, 2026 02:51
@github-actions github-actions Bot added the needs:spec-owner-review Current knowledge records await owner approval label Nov 20, 2026
@cixzhang

Copy link
Copy Markdown
Contributor Author

/approve-spec 65e21c7

@github-actions github-actions Bot removed the needs:spec-owner-review Current knowledge records await owner approval label Nov 20, 2026

This branch was successfully deployed

1 active deployment
Preview — 65e21c70 Deployed Nov 20, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

CLA Signed This label is managed by the Meta Open Source bot.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant