Repository navigation
docs(api): ref inputs end in Ref and match an existing role's name; API review raises every mismatch - #12699
docs(api): ref inputs end in Ref and match an existing role's name; API review raises every mismatch#12699cixzhang wants to merge 7 commits into
Conversation
… the system; props live in the contracts package
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
AI review status for this pull request.
|
PR Analysis Report
Generated by PR Enrichment workflow | View current CI run |
|
/approve-spec 1dcfc28 |
There was a problem hiding this comment.
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 namedref, INV8 gives every public DOM component arefprop, anduseLayer,useTooltip,useHoverCardanduseTruncationreturnref: INV29 and its verification row should say that a barerefconforms (or list these as gaps and drop INV2'sref). - 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/nativestays 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
anchorRefis typedReact.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
Refsuffix, the ref types, no bare element or getter, the role names, and thecreate…rule, and INV2 points to it: present in the record (INV2, INV29); therefconflict 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 (PopoveranchorReftype, returnedrefmembers). - Claim: INV21a keeps the two shipped hook options, and
useHoverCard'spositionRefkeeps 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 bareref; 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).
…ab conforms on promotion; the contracts-package bullet and DEC-17 move to their own record change
|
/approve-spec 6287bef |
There was a problem hiding this comment.
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
refconform only "when the element has no narrower job", butuseLayerreturnsreffor its trigger element (a job INV2 and INV29 nametriggerRef) and the gap line does not list it, while the verification row exempts only aref"that INV8 or INV2 allows" and INV2 covers only refs a hook takes: make the row say "that INV29 allows", and either listuseLayer'sref(and decide the combinedrefofuseTooltipanduseHoverCard) 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
Refsuffix, the ref types, no element or getter input, the role names, thecreate…rule, and a barerefwhere INV8 or INV2 allows it, and INV2 points to it: present; the returned-refwording is the finding above. - Claim: INV30 makes review search for same-role members and raise every mismatch, never as optional: verified.
- Claim:
spec:AST-082FR4 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'sanchorReftype), and LabscrollElementconforms on promotion: verified against the declarations. - Claim:
useHoverCard'spositionRefkeeps its name, andusePopover'sanchoris 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, anduseLayer's returnedrefis 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 bareref), plus one non-blocking note. - File:
docs/specs/AST-082-native-first-surfaces/spec.md: clear.
…trigger ref is a shipped gap; the same-role rule covers hook options
|
/approve-spec 5bc8a11 |
There was a problem hiding this comment.
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 thatuseLayer's returnedrefis 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
Refsuffix, the ref types, no element or getter input, the role names, thecreate…rule and when a barerefconforms, 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-082FR4 says a React ref is not portable and React maps the need to a…Refprop: 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
scrollElementconforms on promotion: verified against the declarations. - Claim:
useHoverCard'spositionRefkeeps its name andusePopover'sanchoris decided elsewhere: verified; nothing is renamed andusePopoverhas 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 returnedrefis 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.
| 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 |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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
Refsuffix, the ref types, no element or getter input, the role names, thecreate…rule and where a barerefconforms, 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
…Refprop: 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
scrollElementconforms on promotion: verified against the declarations. - Claim:
useHoverCard'spositionRefkeeps its name andusePopover'sanchoris decided elsewhere: verified; nothing is renamed andusePopoverhas 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
anchorRefanduseLayer's returnedref, 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.
|
/approve-spec 2838126 |
There was a problem hiding this comment.
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'sanchorReftype,useLayer's returnedref): verified against their declarations and the gap line. useHoverCard's returnedpositionRefkeeps its name,usePopover's anchor is decided elsewhere, and Lab'sscrollElementconforms 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 --checkpass: 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.
|
/approve-spec 65e21c7 |
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 asanchorReffor 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;ReactNodeand render functions are not portable), FR5, DEC-8.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.mdor 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 editsspec:AST-082FR3, DEC-7 and DEC-17 for the contracts decision, while this pull request adds only an FR4 bullet there)Decision
Refand has a ref type (RefObject<T | null>,Ref<T>, orRefCallback<T>). A barerefconforms: a component'srefprop (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). Acreate…equivalent keeps the name and takes any object with acurrentelement. INV2's element-ref sentence points to INV29.spec:AST-082FR4: a React ref is not portable; a core contract states the need neutrally and each platform's contract maps it (on React, a…Refprop).Rejected alternatives
Claim scope and non-goals
useMenuPressgetScroller,useLayerDismissalgetContainer, Popover'sanchorRef, whose type excludesnull, anduseLayer's returned triggerref) are listed as an INV29 gap and get separate follow-ups, timed by INV21a. Lab ChatVirtualizer'sscrollElementmust conform on promotion.useHoverCard's returnedpositionRefkeeps its name (INV21a).usePopover'sanchoroption is decided in its own stack, not here.Evidence and implementation relationship
An audit of the public entries of
@astryxdesign/core,@astryxdesign/laband@astryxdesign/richtext(159 entries, using the TypeScript checker) found 41 members that hold a ref, a getter or an element, or whose name ends inRef. 38 comply and 3 do not (two shipped hook getters and one Lab element). A type check adds Popover'sanchorRef, typedRefObject<HTMLElement>, and a return check addsuseLayer's returned triggerref. So the INV29 gap line lists four shipped members, and Lab'sscrollElementconforms on promotion.Writing rubric results
Rejected:sentence inside the decision.Scope
Components: none (records:
architecture:public-component-api,spec:AST-082)Validation
pnpm check:knowledge: templates and records aligned.git diff --check: clean.