Skip to content

refactor(NavigationStack): push takes sourceRef, not source - #12793

Draft
cixzhang wants to merge 2 commits into
mainfrom
lab/navstack-source-ref
Draft

cixzhang wants to merge 2 commits into
mainfrom
lab/navstack-source-ref

Conversation

@cixzhang

@cixzhang cixzhang commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

What changes

NavigationStack's push option source (an element) becomes sourceRef (a ref object): useNavigationStack().push(entry, {sourceRef: openerRef}). push reads sourceRef.current, and that control gets focus back when the screen pops. Focus behavior is otherwise unchanged.

Why

Scope

  • packages/lab/src/NavigationStack/NavigationStack.tsx: the option's type (RefObject<Element | null>), its JSDoc, and the one read in push.
  • NavigationStack.test.tsx: a new case, "returns focus to the control push names in sourceRef", which passes the ref and fails before the change.
  • There are no other callers: the stories, the sandbox and the doc file call push(entry) without options.
  • @astryxdesign/lab is private, so there is no deprecation alias and no changeset.

Testing

  • vitest --project ui packages/lab/src/NavigationStack: 42 passed. The new case fails at main.
  • tsc --noEmit for Lab: clean. ESLint on the changed files: clean.

Overlap checked: #12737, #12004, #12002 (#12004 platform history back and #12737 the WebKit start clock change other lines of NavigationStack.tsx, and this merges after #12004 so its pending owner check keeps its head; #12002 is a draft-record preview that rewrites the same push signature and keeps source, so whichever lands second takes the other's name; only this one renames the option, as the ref naming rule asks)

A ref-valued input ends in Ref. Lab is private, so there is no alias. A
test covers focus returning to the control push names in sourceRef.
@vercel

vercel Bot commented Nov 19, 2026 •

Copy link
Copy Markdown

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

Project Deployment Actions Updated
astryx Ready Ready Preview Nov 19, 2026 12:22pm UTC

Request Review

@meta-cla meta-cla Bot added the CLA Signed This label is managed by the Meta Open Source bot. label Nov 19, 2026
@astracat-bot

astracat-bot Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

AI review status for this pull request.

Review status Updated
🟢 Reviewed (for maintainers only) Nov 19, 2026, 12:29 PM UTC

@cixzhang

Copy link
Copy Markdown
Contributor Author

/approve-spec 89bc771

@github-actions

github-actions Bot commented Nov 19, 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

@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 renamed option's type does not match its new name.

  • sourceRef in packages/lab/src/NavigationStack/NavigationStack.tsx:129 is typed Element | null, so a caller who passes the ref the name asks for gets a type error, or loses focus return in untyped code; type it RefObject<Element | null> and read .current in push (with the test passing the ref), or keep an element-valued name without Ref.
  • The overlap note says #12002 changes other lines of the NavigationStack files, but #12002 rewrites the same push signature and keeps source; please correct the note.

The React Native draft the description cites now also takes a ref object for sourceRef, so taking a ref keeps both platforms on one name and one value. The new test fails before the rename, and the NavigationStack tests, the Lab typecheck and lint pass at this head.

Claims and files checked

Review mode: same-head; reason: none

Claims:

  • The option is renamed with the same value, and focus behavior is unchanged: verified (NavigationStack.tsx:129, :1594-1595; 42 tests pass).
  • A ref-valued input ends in Ref under the cited naming rule: false; the option takes an element, and that rule says a name ending in Ref holds only a ref (NavigationStack.tsx:129).
  • The React Native record already names the option sourceRef, keeping one name: verified for the name; that draft now takes a ref object, so the values differ.
  • Only the option's type, its JSDoc and the one read in push change: verified (the diff).
  • The new case fails before the rename: verified (it fails at the base on NavigationStack.test.tsx:451).
  • No other caller passes options; the stories, the sandbox and the docs call push(entry): verified.
  • Lab is private, so there is no alias and no changeset: verified (packages/lab/package.json).
  • The NavigationStack tests pass (42): verified.
  • Lab's tsc --noEmit is clean: verified.
  • ESLint is clean on the changed files: verified.
  • The three overlapping pull requests change other lines, and none renames the option: false for #12002, which rewrites the same push signature; the rest holds.

Files:

  • packages/lab/src/NavigationStack/NavigationStack.tsx: finding (the sourceRef type).
  • packages/lab/src/NavigationStack/NavigationStack.test.tsx: clear.

Automated review (maintainer link)

push reads options.sourceRef.current, so a caller passes the ref its name
asks for, as on React Native. The test passes the ref.
@cixzhang

Copy link
Copy Markdown
Contributor Author

/approve-spec ef6f467

@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: CI has not run on this head yet, because the pull request is a draft, and it runs once the pull request is marked ready for review.

Both points from the last review are fixed: sourceRef now takes a ref object that push reads, the test passes the ref, and the overlap note now describes #12002 correctly. One thing to weigh, not blocking: push reads the ref once, when it runs, while the React Native draft reads it at the pop, so a control that remounts while its screen is covered gets focus back on React Native but not on web.

Claims and files checked

Review mode: incremental; reason: none

Changed rules (0): none

Claims:

  • The push option source (an element) becomes sourceRef (a ref object): verified (NavigationStack.tsx:130).
  • push reads sourceRef.current, and that control gets focus back when its screen pops: verified (NavigationStack.tsx:1596; the new test).
  • Focus behavior is otherwise unchanged: verified (only that read changed; the other 41 tests pass).
  • A ref-valued input ends in Ref under the cited naming rule: verified against that draft rule (the name ends in Ref and the type is RefObject<Element | null>).
  • The React Native record names the option sourceRef and takes a ref object, so both platforms share one name and one value: verified; that draft reads the ref at the pop, this change at the push.
  • The change is the option's type, its JSDoc and the one read in push: verified (plus the type import).
  • The new test passes the ref: verified (NavigationStack.test.tsx:414).
  • The new test fails before the change: verified (it fails at the base on NavigationStack.test.tsx:451).
  • No other caller passes options; the stories, the sandbox and the docs call push(entry): verified.
  • Lab is private, so there is no alias and no changeset: verified (packages/lab/package.json).
  • The NavigationStack tests pass (42): verified.
  • Lab's typecheck is clean: verified.
  • ESLint is clean on the changed files: verified.
  • The platform history-back and WebKit start-clock pull requests change other lines of NavigationStack.tsx: verified.
  • This merges after the platform history-back pull request: a merge-order plan, still possible (that pull request is open).
  • The draft-record preview rewrites the same push signature and keeps source, and only this change renames the option: verified.

Files:

  • packages/lab/src/NavigationStack/NavigationStack.tsx: clear.
  • packages/lab/src/NavigationStack/NavigationStack.test.tsx: clear.

Automated review (maintainer link)

This branch was successfully deployed

1 active deployment
Preview — ef6f467b Deployed Nov 19, 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