Skip to content

spec(NavigationStack): React Native platform record - #12596

Draft
imdreamrunner wants to merge 12 commits into
mainfrom
spec/navigationstack-react-native
Draft

imdreamrunner wants to merge 12 commits into
mainfrom
spec/navigationstack-react-native

Conversation

@imdreamrunner

@imdreamrunner imdreamrunner commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Stacked on #12592; merges after it and with #12685.

The first commit is #12592's (it lets check:knowledge accept react-native platform records). This PR's own change is one file: docs/specs/components/NavigationStack/NavigationStack.react-native.spec.md.

Exact decision needed

How React Native renders NavigationStack, and where a phone screen's frame lives. The record is the React Native platform record of component:NavigationStack (component:react-native/NavigationStack, platform_of: component:NavigationStack). It states only what React Native adds or does differently; Lab's NavigationStack source and documentation stand in for the core contract.

Existing authority searched

  • Records: architecture:knowledge-contracts DEC-13 and DEC-15 (platform records beside the core record); spec:AST-082 FR3–FR5, FR7, FR11 and spec:AST-093 FR1–FR5 (core and platform contracts, native-first); spec:AST-094 (web touch release for popping a NavigationStack); spec:AST-112 as amended in spec(AST-112): React Native commands are one astryx rn group; package shape (Expo wrapper, default linking, named features) #12563 (package layer and native dependencies); the open drafts spec:AST-125 (navigation hosts), spec:AST-124 (gestures and drag), spec:AST-129 (safe area and keyboard), spec:AST-128 (presentation), and the header record component:react-native/TopNav (spec(TopNav): React Native platform record #12685).
  • Code: packages/lab/src/NavigationStack/ (NavigationStack, NavigationScreen, useNavigationStack, the back label rule and the focus rules).
  • Overlap: no other record owns NavigationStack on React Native or the screen container. The navigation hosts' record owns the native stack host, and this record is one of its callers. The header and the tab bar keep their own component records and decide their own rendering.

Decision

  • React Native takes web's NavigationStack, NavigationScreen and useNavigationStack() props, names, types and defaults. The one change is push's source: on React Native it is sourceRef, a ref object (a RefObject of the native View that pushed), because React Native has no DOM Element and every ref-valued input ends in Ref (spec:AST-116 DEC-1; FR1, DEC-6).
  • The stack renders on the native stack host. path stays the one source of truth: a pop the system completes (back control, back menu, back swipe, predictive back, system back, a screen-reader back) reaches the app as one onPathChange (FR2–FR5, FR10).
  • Back gestures and transitions are the platform's. On iOS there is an edge swipe and a content swipe, with drag ownership against controls (spec:AST-124 FR3). On Android there is system back and predictive back, with no content swipe (FR8, FR9, FR11).
  • NavigationScreen's title, backTitle, titleDisplayMode and endContent reach the screen's header. The header component decides how it renders (FR6, FR7).
  • Screen is the frame every screen's content sits in on a phone. It has scroll and fill modes, insets from the first frame, keeps fields above the keyboard, hosts pull to refresh, and holds the one scroll target. useScreenScrollProps() hands that scroll target to a component's or an app's own scroller (FR12–FR16, DEC-2).
  • Astryx's router supports Astryx's header, tab bar and sheets. An app may use another router instead, such as Expo Router: Astryx components work inside its screens, and that router's navigation is not covered (FR17, DEC-3).
  • The stack needs no third-party native library. The common navigation, gesture, animation and safe-area libraries can be linked beside it (FR18).
  • In the Astryx router, a stack screen's options may be ({route, navigation, theme}) => options. The returned options are app API: NavigationScreen's four values, the whole set. The header's visuals come from the native theme, and component:react-native/TopNav's flat options record is the wire format between TopNav parts and the native host. An option set is a function, so extending one is a call (FR19, DEC-4).
  • While web's NavigationStack is a Lab component, the React Native stack, Screen and useScreenScrollProps() are exported from the package's lab space under ./unstable/* (spec:AST-112 FR23). They move to @astryxdesign/react-native's ./navigation entry when web's NavigationStack leaves Lab (FR1, DEC-5).
  • Accessibility: a push moves focus to the new title, and a pop returns focus to the control that pushed. The back control is named by its destination. Titles are headings and scale with text size. Reduce Motion cross-fades the screens, and covered screens are hidden from screen readers (AR1–AR6).

Rejected alternatives

None recorded.

Claim scope and non-goals

The claims are FR1–FR19, AR1–AR6, ORD1–ORD2, PR1–PR2 and DEC-1–DEC-6. The record's "Does not own" list names the owner of each adjacent responsibility.

Open questions:

  • OQ1 (human-api): what isInteractivePopEnabled={false} does on Android.
  • OQ2 (checkable): whether the system's own focus move already meets AR1 and AR2.

Evidence and implementation relationship

No React Native implementation exists in this repository. The record states the target behavior. Its verification map names the evidence for each requirement: unit tests through the package's testing doubles, Simulator and emulator checks, and VoiceOver and TalkBack checks.

Writing rubric results

  • R1 narration: none; every requirement is in the present tense about the system.
  • R2 research in the record: none; the record keeps only the conclusions inside DEC-1 to DEC-6.
  • R3 evidence naming a change: none; basis cells cite records, clauses and platform guidance.
  • R4 rejected alternatives over one line or outside a decision: none; the record has no rejected alternatives.
  • R5 pull request or issue references remaining: none.
  • R6 ruled open questions still listing options: none; routing and the default chrome are settled, so they are not open questions. Routing is in FR17 and DEC-3. Chrome belongs to the header and tab bar components. OQ1 is unanswered and keeps its two options.
  • R7 project status (build status or work order): none.

Scope

Components: NavigationStack

  • 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: passes on this branch. The record is discovered and validated: a wrong id is reported as id must match "^component:react-native/NavigationStack$".
  • 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 Ready Ready Preview Nov 19, 2026 3:00am UTC

Request Review

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

astracat-bot Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

AI review status for this pull request.

Review status Updated
❓ Needs maintainer input (for maintainers only) Nov 19, 2026, 3:07 AM UTC

@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

@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.

Outcome: waiting on an owner's spec decision, with two fixes to make.

This pull request proposes new requirements: the draft React Native NavigationStack record (FR1–FR18, AR1–AR6, ORD1–ORD2, PR1–PR2 and DEC-1–DEC-3, including the new Screen and useScreenScrollProps() API and the router direction in DEC-3) and the knowledge-contracts sentence that names swift and react-native as the platform-record languages. Approval waits on an engineering owner recording that decision by commenting /approve-spec <full head SHA> on this pull request, and the author may do so as an engineering owner. That decision should also settle the merge order, since FR2–FR9, FR11, FR13 and FR15 rest on records that exist only in the open drafts #12554, #12562 and #12552.

Blocking findings:

  • The description says the verification map names the evidence for each requirement, but the map has no row or state for ORD1 and FR9's back precedence, PR2, or PR1's large-title collapse (record lines 130, 166–178 and 261–274), so add those states or narrow the sentence.
  • FR2 (record line 123) requires the internal AstryxStackHost and AstryxStackScreen, which the knowledge-contracts rule against prescribing internal mechanisms (INV18) does not allow, so state FR2 by its outcome and leave the host names to the Native pieces table.
Claims and files checked

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

Claims:

  • The first commit is the stacked pull request's and this pull request adds one file of its own: verified in the commit history.
  • The record has a language-qualified id and names the core component it implements: verified (record lines 5–6).
  • The record states only what React Native adds or does differently, with Lab's source standing in for the core contract: verified against Lab's NavigationStack source and docs.
  • Each decision bullet points at the requirements it cites (FR1–FR18, AR1–AR6, DEC-1–DEC-3) and the two open questions: verified.
  • No React Native implementation exists in the repository: verified from the package list.
  • The verification map names the evidence for each requirement: false for ORD1, PR2 and PR1's large-title collapse.
  • Every named internal mechanism says why an equivalent implementation would not satisfy the contract: false for FR2's host.
  • The writing rubric results (no narration, research, change references, pull request references or project status in the record): verified.
  • pnpm check:knowledge passes and reports a wrong id with the quoted message: verified at the head and on a scratch copy.
  • Prettier and git diff --check are clean: verified.

Files:

  • .github/scripts/change-scope.test.mjs: clear.
  • .github/scripts/knowledge-paths.cjs: clear.
  • .github/scripts/knowledge-paths.test.mjs: clear.
  • docs/architecture/knowledge-contracts.md: waits on the owner decision.
  • docs/specs/components/NavigationStack/NavigationStack.react-native.spec.md: waits on the owner decision, with the two findings above.
  • scripts/check-knowledge.test.mjs: clear.
  • scripts/specs-for-file.test.mjs: clear.

Automated review (maintainer link)

@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.

Outcome: waiting on an engineering owner's spec decision; no other fixes needed.

Both earlier findings are fixed: FR2 now states its outcome, and the verification map covers ORD1, PR1 and PR2. Approval waits on an engineering owner approving the proposed requirements, the draft React Native NavigationStack record (FR1–FR18, AR1–AR6, ORD1–ORD2, PR1–PR2 and DEC-1–DEC-3, including the new Screen and useScreenScrollProps() API and the router direction in DEC-3) and the knowledge-contracts sentence that names swift and react-native as the platform-record languages, by commenting /approve-spec <full head SHA> on this pull request; the author may do so as an engineering owner. That decision should also settle the merge order, since FR2–FR9, FR11, FR13, FR15 and PR1 rest on records that exist only in the open drafts #12554, #12562 and #12552.

Claims and files checked

Review mode: full; reason: spec-record

Claims:

  • The pull request contains the knowledge-tooling pull request's commit and merges after it: verified, its first commit is that pull request's head.
  • Its own change is the one record file: verified, the two later commits touch only that file.
  • The record is NavigationStack's React Native platform record with a language-qualified id and platform_of: verified, record lines 5–6.
  • React Native keeps web's props, names, types and defaults, with push's source a native view: verified against Lab's web types (FR1).
  • Stack rendering, system pops as one onPathChange, back gestures, transitions, header mapping, Screen and its hook, router direction, native dependencies and accessibility are as the description lists: verified in FR2–FR18 and AR1–AR6.
  • The non-goals name an owner for each excluded concern: verified in Ownership boundary.
  • Two open questions remain, on Android's disabled back swipe and on system focus: verified, OQ1 and OQ2.
  • No React Native implementation exists in the repository: verified, no React Native package under packages/.
  • The verification map names evidence for each requirement: verified at this head, with ORD2 proved through the frame and scroll-target row.
  • Rubric results (present tense, one one-line rejected alternative in DEC-1, no pull request references, no project status): verified; the record's only status line is its readiness row.
  • check:knowledge passes and an id without its language gets the language-qualified message: verified by runs at this head.
  • Prettier and the whitespace check are clean: verified.
  • The listed records and drafts exist with the stated authority: verified on main and in the open draft pull requests.

Files:

  • .github/scripts/knowledge-paths.cjs: clear.
  • .github/scripts/knowledge-paths.test.mjs, .github/scripts/change-scope.test.mjs, scripts/check-knowledge.test.mjs, scripts/specs-for-file.test.mjs: clear; the new cases fail on the base code and pass at this head.
  • docs/architecture/knowledge-contracts.md: waits on owner approval of the language sentence.
  • docs/specs/components/NavigationStack/NavigationStack.react-native.spec.md: waits on owner approval; the Governing rules row leaves out two bases (non-blocking).

Automated review (maintainer link)

@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.

Outcome: waiting on an engineering owner's spec decision, with two fixes to make.

Approval waits on an engineering owner approving the proposed requirements, the draft React Native NavigationStack record (FR1–FR19, AR1–AR6, ORD1–ORD2, PR1–PR2 and DEC-1–DEC-4, including Screen, useScreenScrollProps(), the router direction in DEC-3 and the screen options in FR19) and the knowledge-contracts sentence that names swift and react-native as the platform-record languages, by commenting /approve-spec <full head SHA> on this pull request; the author may do so as an engineering owner. That decision should also settle the merge order, since FR2–FR9, FR11, FR13, FR15 and PR1 rest on records that exist only in the open drafts #12554, #12562 and #12552.

Fixes, needed whatever the decision:

  • FR19 (record line 122) sets the shape of "a stack screen's options" as ({route, navigation, theme}) => options, but no API in this record or in web's NavigationStack takes options or defines route and navigation, so name the API that takes the function and define its arguments and option set, or move FR19 and DEC-4 to the router's stack-options record.
  • The non-goals list now reads "None." (record line 85) while the record gives the header, the stack host, drag ownership and the safe area to other owners, and routing state, tabs, sheets, Stage and Preview are no longer disowned anywhere, so restore the owner-tagged non-goals list.

The earlier note on the Governing rules row is fixed.

Claims and files checked

Review mode: full; reason: spec-record

Claims:

  • The pull request carries the knowledge-tooling pull request's commit and merges after it: verified, its first commit is that pull request's head, which is still open.
  • Its own change is the one record file: verified, the three later commits touch only that file.
  • The record is NavigationStack's React Native platform record with a language-qualified id and platform_of: verified, record lines 5–6.
  • React Native keeps web's props, names, types and defaults, with push's source a native view: verified against Lab's web types (FR1).
  • Native stack rendering, system pops as one onPathChange, back gestures and transitions, header mapping, Screen and its hook, router direction, native dependencies, screen options and accessibility are as the description lists: verified in FR1–FR19 and AR1–AR6.
  • The listed records and open drafts exist with the stated authority: verified; every cited draft is still open.
  • No other record owns NavigationStack on React Native or the screen container: verified.
  • The header and the tab bar keep their own records: no longer stated in the record, whose non-goals read "None." (fix above).
  • No rejected alternatives are recorded and the record lists no non-goals: verified; the second is the fix above.
  • Two open questions remain, on Android's disabled back swipe and on system focus: verified, OQ1 and OQ2.
  • No React Native implementation exists in the repository: verified, no React Native package.
  • The verification map names evidence for each requirement: verified, FR19 included.
  • Writing rubric results (present tense, no research, no change or pull request references, no project status): verified; the only status line is the template's release field.
  • Scope checklist: specification records only holds for this pull request's own commits; adjacent API staying out of scope, one decision, and ownership collisions being called out are false for FR19 (fix above).
  • check:knowledge passes and an id without its language gets the quoted message: verified by runs at this head.
  • Prettier and the whitespace check are clean: verified.

Files:

  • .github/scripts/knowledge-paths.cjs: clear.
  • .github/scripts/knowledge-paths.test.mjs, .github/scripts/change-scope.test.mjs, scripts/check-knowledge.test.mjs, scripts/specs-for-file.test.mjs: clear; the new cases fail on the base code and pass at this head.
  • docs/architecture/knowledge-contracts.md: waits on owner approval of the language sentence.
  • docs/specs/components/NavigationStack/NavigationStack.react-native.spec.md: waits on owner approval; FR19 and the non-goals list need fixes.

Automated review (maintainer link)

@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.

Outcome: waiting on an engineering owner's spec decision, with one fix to make.

Approval waits on an engineering owner approving the proposed requirements, the draft React Native NavigationStack record (FR1–FR19, AR1–AR6, ORD1–ORD2, PR1–PR2 and DEC-1–DEC-4, including Screen, useScreenScrollProps(), the router direction in DEC-3 and the router screen options in FR19) and the knowledge-contracts sentence that names swift and react-native as the platform-record languages, by commenting /approve-spec <full head SHA> on this pull request; the author may do so as an engineering owner. That decision should also settle which stack-options shape stands, since the open navigation-hosts draft (#12554) declares stack options through composed Header parts, and the merge order, since FR2–FR9, FR11, FR13, FR15 and PR1 rest on records that exist only in the open drafts #12554, #12562 and #12552.

Fix, needed whatever the decision:

  • The non-goals (record lines 89–91), line 250 and FR19 (line 135) give the header and half of FR19's option set to component:react-native/TopNav, which no record or open pull request defines while the drafts this record rests on call the header Header, so name the header record the drafts use (or add that record and align the drafts), and until it exists list FR19's option set here or state the header as an uncontracted gap.

The earlier non-goals finding is fixed, and FR19 now names the router and defines route and navigation.

Claims and files checked

Review mode: full; reason: spec-record

Claims:

  • The pull request carries the knowledge-tooling pull request's commit and merges after it: verified, its first commit is that pull request's head, which is still open.
  • Its own change is the one record file: verified, the five later commits touch only that file.
  • The record is NavigationStack's React Native platform record with a language-qualified id and platform_of: verified, record lines 5–6.
  • React Native keeps web's props, names, types and defaults, with push's source a native view: verified against Lab's web types (FR1).
  • Native stack rendering, system pops as one onPathChange, back gestures and transitions, header mapping, Screen and its hook, router direction, native dependencies, screen options and accessibility are as the description lists: present in FR1–FR19 and AR1–AR6, proposed and unapproved.
  • The listed records and open drafts exist with the stated authority: verified; every cited draft is still open.
  • No other record owns NavigationStack on React Native or the screen container: verified.
  • The header and the tab bar keep their own component records: false for the header, whose named record does not exist (fix above); the tab bar goes to the navigation-hosts draft.
  • The non-goals name the owner of each adjacent responsibility: holds except the header owner (fix above).
  • No rejected alternatives are recorded: verified.
  • Two open questions remain, on Android's disabled back swipe and on system focus: verified, OQ1 and OQ2.
  • No React Native implementation exists in the repository: verified, no React Native package.
  • The verification map names evidence for each requirement: verified, FR19 included.
  • Writing rubric results (present tense, no research, no change or pull request references, no project status): verified; the only status line is the template's release field.
  • Scope checklist: specification records only holds for this pull request's own commits; ownership collisions being called out is false for the header owner and the stack-options shape.
  • check:knowledge passes and a wrong id gets the quoted message: verified by runs at this head and the new validation test.
  • Prettier and the whitespace check are clean: verified.

Files:

  • .github/scripts/knowledge-paths.cjs: clear.
  • .github/scripts/knowledge-paths.test.mjs, .github/scripts/change-scope.test.mjs, scripts/check-knowledge.test.mjs, scripts/specs-for-file.test.mjs: clear; the new cases fail on the base code and pass at this head.
  • docs/architecture/knowledge-contracts.md: waits on owner approval of the language sentence.
  • docs/specs/components/NavigationStack/NavigationStack.react-native.spec.md: waits on owner approval; the header owner needs the fix above.

Automated review (maintainer link)

@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.

Outcome: waiting on an engineering owner's spec decision, with one fix to make.

Approval waits on an engineering owner approving the proposed requirements, the draft React Native NavigationStack record (FR1–FR19, AR1–AR6, ORD1–ORD2, PR1–PR2 and DEC-1–DEC-4, including Screen, useScreenScrollProps(), the router direction in DEC-3 and the screen options in FR19) and the knowledge-contracts sentence that names swift and react-native as platform-record languages, by commenting /approve-spec <full head SHA> on this pull request; the author may do so as an engineering owner. That decision should also settle whether options returned from FR19's function are app API, since the open header draft (#12685) calls the header record wire format and not app API, and the merge order, since FR2–FR9, FR11, FR13, FR15 and PR1 rest on records that exist only in the open drafts #12554, #12562 and #12552, and the header owner only in #12685.

Fix, needed whatever the decision:

  • The record now calls TopNav's React Native form Header (record lines 91–92, FR19 on line 136, lines 251–255), but the current native-first record keeps a component's name the same on every platform (AST-082 FR3), so refer to the header by its record, component:react-native/TopNav, and to "the header's parts", or land an approved amendment of AST-082 FR3 first.

Also worth a look:

  • Miss (non-blocking): the Design relationships (line 219) and FR11's basis cite AST-093 FR3 for Material 3 guidance, but AST-093 FR3 covers only iOS and macOS and leaves Android guidelines to its OQ1, so cite the Android guidance as this record's own basis, as FR9 does.

The earlier header-owner finding is fixed: component:react-native/TopNav now exists as an open draft, and the drafts agree on it.

Claims and files checked

Review mode: full; reason: spec-record

Claims:

  • The pull request carries the knowledge-tooling pull request's commit and merges after it: verified, its first commit is that pull request's head, which is still open.
  • Its own change is the one record file: verified, the six later commits touch only that file.
  • The record is NavigationStack's React Native platform record with a language-qualified id and platform_of: verified, record lines 5–6.
  • The listed records and open drafts exist with the stated authority: verified; every cited draft is still an open pull request.
  • No other record owns NavigationStack on React Native or the screen container: verified.
  • The header and the tab bar keep their own component records: verified, both are open drafts.
  • React Native keeps web's props, names, types and defaults, with push's source a native view: verified against Lab's web types (FR1).
  • Native stack rendering, system pops as one onPathChange, back gestures and transitions, header mapping, Screen and its hook, router direction, no third-party native library, screen options and accessibility are as the description lists: present in FR1–FR19 and AR1–AR6, proposed and unapproved.
  • No rejected alternatives are recorded: verified.
  • The claims are FR1–FR19, AR1–AR6, ORD1–ORD2, PR1–PR2 and DEC-1–DEC-4, and the non-goals name each adjacent owner: verified.
  • Two open questions remain, on Android's disabled back swipe and on system focus: verified, OQ1 and OQ2.
  • No React Native implementation exists in the repository: verified, no React Native package.
  • The verification map names evidence for each requirement: verified; ORD2 is covered by the frame and scroll-target row's states.
  • Writing rubric results (present tense, no research, no change or pull request references, no project status): verified; the only status lines are the template's release field and readiness cell.
  • Scope checklist: specification records only holds for this pull request's own commits; affected current claims being named is false for the core-contract name rule (fix above).
  • check:knowledge passes and a wrong id gets the quoted message: verified by a run at this head and the new validation test.
  • Prettier and the whitespace check are clean: verified.

Files:

  • .github/scripts/knowledge-paths.cjs: clear.
  • .github/scripts/knowledge-paths.test.mjs, .github/scripts/change-scope.test.mjs, scripts/check-knowledge.test.mjs, scripts/specs-for-file.test.mjs: clear; the new or extended cases fail on the merge-base code and pass at this head.
  • docs/architecture/knowledge-contracts.md: waits on owner approval of the language sentence.
  • docs/specs/components/NavigationStack/NavigationStack.react-native.spec.md: waits on owner approval; the Header name needs the fix above; one non-blocking citation note.

Automated review (maintainer link)

… API; cite Android guidance as this record's basis

@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.

Outcome: waiting on an engineering owner's spec decision; no blocking fix remains.

Approval waits on an engineering owner approving the proposed requirements — the draft React Native NavigationStack record (FR1–FR19, AR1–AR6, ORD1–ORD2, PR1–PR2 and DEC-1–DEC-4, including Screen, useScreenScrollProps(), the router direction in DEC-3 and the screen options in FR19) and the knowledge-contracts sentence that names swift and react-native as platform-record languages — by commenting /approve-spec <full head SHA> on this pull request; the author may do so as an engineering owner. That decision should also settle what a screen's router options carry, since FR19 now returns only NavigationScreen's four values while the open header draft (#12685, FR15–FR16) has a screen set the header's tint, colours and material through the same options, and the merge order, since FR2–FR9, FR11, FR13, FR15 and PR1 rest on records that exist only in the open drafts #12554, #12562 and #12552.

Also worth a look (non-blocking):

  • FR19's rule for theme-derived option values (line 135) and its verification state "a theme-derived value under a nested theme" (line 271) apply to none of the four values FR19 now returns; once the option set is ruled, either name the header settings a screen may return there or drop that sentence and state.

The earlier findings are fixed: the header keeps its core name TopNav, as the native-first record requires, and the Android transition and predictive-back guidance is now the record's own basis.

Claims and files checked

Review mode: full; reason: spec-record

Claims:

  • The pull request carries the knowledge-tooling pull request's commit and merges after it, and with the header record's pull request: verified, its first commit is that tooling pull request's head, and both are open drafts.
  • Its own change is the one record file: verified, every later commit touches only that file.
  • The record is NavigationStack's React Native platform record with a language-qualified id and platform_of: verified, record lines 5–6.
  • The listed records and open drafts exist with the stated authority: verified; the native-first, native-guideline and touch records are current, and every cited draft is an open pull request.
  • No other record owns NavigationStack on React Native or the screen container: verified.
  • The header and the tab bar keep their own component records: verified, both are open drafts.
  • React Native keeps web's props, names, types and defaults, with push's source a native view: verified against Lab's web types (FR1).
  • Native stack rendering, system pops as one onPathChange, back gestures and transitions, header mapping, Screen and its hook, router direction, no third-party native library and accessibility are as the description lists: present in FR1–FR18 and AR1–AR6, proposed and unapproved.
  • Screen options are a function of route, navigation and theme, with theme-derived values resolved in the screen's scope: present in FR19 and DEC-4; the theme rule has no value to apply to (note above).
  • No rejected alternatives are recorded: verified.
  • The claims are FR1–FR19, AR1–AR6, ORD1–ORD2, PR1–PR2 and DEC-1–DEC-4, and the non-goals name each adjacent owner: verified, record lines 83–98.
  • Two open questions remain, on Android's disabled back swipe and on system focus: verified, OQ1 and OQ2.
  • No React Native implementation exists in the repository: verified, no React Native package.
  • The verification map names evidence for each requirement: verified.
  • Writing rubric results (present tense, no research, no change or pull request references, no project status): verified; the only status lines are the template's release field and readiness cell.
  • Scope checklist (specification records only, owners and overlapping work named): holds for this pull request's own commits; the option-set overlap with the header draft is the owner reading above.
  • check:knowledge passes and a wrong id gets the quoted message: verified by a run at this head and the new validation test.
  • Prettier and the whitespace check are clean: verified.

Files:

  • .github/scripts/knowledge-paths.cjs: clear.
  • .github/scripts/knowledge-paths.test.mjs, .github/scripts/change-scope.test.mjs, scripts/check-knowledge.test.mjs, scripts/specs-for-file.test.mjs: clear; they pass at this head, and the new React Native cases fail on the merge-base tooling.
  • docs/architecture/knowledge-contracts.md: waits on owner approval of the language sentence.
  • docs/specs/components/NavigationStack/NavigationStack.react-native.spec.md: waits on owner approval; one non-blocking note on FR19.

Automated review (maintainer link)

…-5); FR19's four values are the whole option set

@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.

Outcome: waiting on an engineering owner's spec decision, with one fix to make.

Approval waits on an engineering owner approving the proposed requirements — the draft React Native NavigationStack record (FR1–FR19, AR1–AR6, ORD1–ORD2, PR1–PR2 and DEC-1–DEC-6) and the knowledge-contracts sentence that names swift and react-native as platform-record languages — by commenting /approve-spec <full head SHA> on this pull request; the author may do so as an engineering owner. That decision should also confirm who decided DEC-5 and DEC-6, which entry the stack moves to when web's NavigationStack leaves Lab (this record and #12563's DEC-20 say the main entry, #12563's FR23 says ./navigation), and whether this record merges only after #12563, #12554, #12562 and #12552, which its requirements rest on.

Blocking:

  • push's React Native option is named sourceRef but takes the pushing view itself (FR1 and DEC-6), while every …Ref input in the system takes a ref (for example BottomSheet's finalFocusRef) and the "every ref-valued input ends in Ref" rule DEC-6 cites is said of anchorRef, a ref, so either keep web's source typed as the native view or make sourceRef a ref object, and align AR2, the Builder impact cell and the FR1 verification row with it.

The earlier note on FR19 is fixed: its theme rule and verification state are gone now that its four values hold no theme-derived option.

Claims and files checked

Review mode: full; reason: spec-record

Claims:

  • The pull request carries the knowledge-tooling pull request's commit and merges after it, and with the header record's pull request: verified; its first commit is that pull request's head, and both are open drafts.
  • Its own change is the one record file: verified; every later commit touches only that file.
  • The record is NavigationStack's React Native platform record with a language-qualified id and platform_of: verified, record lines 5–6.
  • The listed records and drafts exist with the stated authority: verified; the native-first, native-guideline and touch records are current, the React Native foundation record is draft on the default branch, and every cited draft is an open pull request.
  • No other record owns NavigationStack on React Native or the screen container: verified.
  • React Native keeps web's props, names, types and defaults, with one change, push's sourceRef, because a ref-valued input ends in Ref: the props match Lab's web types; the stated reason is false as applied (blocking finding).
  • Native stack rendering, system pops as one onPathChange, back gestures and transitions, header mapping, Screen and its hook, router direction, no third-party native library, the screen options and accessibility are as the description lists: present in FR2–FR19 and AR1–AR6, proposed and unapproved.
  • The stack starts in the lab space under ./unstable/* and moves to the main entry when web's NavigationStack leaves Lab: present in FR1 and DEC-5; the foundation requirement it cites exists only in an open draft whose requirement says ./navigation (owner reading).
  • No rejected alternatives are recorded: verified.
  • The claims are FR1–FR19, AR1–AR6, ORD1–ORD2, PR1–PR2 and DEC-1–DEC-6, and the non-goals name each adjacent owner: verified.
  • Two open questions remain, on Android's disabled back swipe and on system focus: verified, OQ1 and OQ2.
  • No React Native implementation exists in the repository: verified, no React Native package.
  • The verification map names evidence for each requirement: verified; ORD2 is covered by the frame and scroll-target row.
  • Writing rubric results (present tense, no research, no pull request references, no project status): verified; the only status text is the template's release field and readiness cell.
  • Scope checklist (specification records only, owners and overlapping work named): holds; who decided DEC-5 and DEC-6 is the owner reading above.
  • check:knowledge passes and a wrong id gets the quoted message: verified by a run at this head and the new validation test.
  • Prettier and the whitespace check are clean: verified.

Files:

  • .github/scripts/knowledge-paths.cjs: clear.
  • .github/scripts/knowledge-paths.test.mjs, .github/scripts/change-scope.test.mjs, scripts/check-knowledge.test.mjs, scripts/specs-for-file.test.mjs: clear; they pass at this head.
  • docs/architecture/knowledge-contracts.md: waits on owner approval of the language sentence.
  • docs/specs/components/NavigationStack/NavigationStack.react-native.spec.md: waits on owner approval; one blocking fix (sourceRef).

Automated review (maintainer link)

@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.

Outcome: waiting on an engineering owner's spec decision; no blocking fix remains.

Approval waits on an engineering owner approving the proposed requirements — the draft React Native NavigationStack record (FR1–FR19, AR1–AR6, ORD1–ORD2, PR1–PR2 and DEC-1–DEC-6) and the knowledge-contracts sentence that names swift and react-native as platform-record languages — by commenting /approve-spec <full head SHA> on this pull request; the author may do so as an engineering owner. That decision should also confirm who decided DEC-5 and DEC-6, and whether this record merges only after #12563, #12554, #12562 and #12552, which its requirements rest on. The earlier sourceRef finding is fixed: it now takes a ref object, and the graduation entry matches #12563.

  • Non-blocking: the FR1 verification row adds "a sourceRef whose view unmounted before the pop", but AR2 gives no result for it; core moves focus to the revealed screen's title when the pushing control is gone, and AR2 could say the same.
  • Non-blocking: FR18's basis cites the draft React Native foundation record, while the current native-first record's dependency requirement already says no other third-party library is required; citing it anchors FR18 to current authority.
Claims and files checked

Review mode: full; reason: spec-record

Claims:

  • The pull request carries the knowledge-tooling pull request's commit and merges after it, and with the header record's pull request: verified; its first commit is that pull request's head, and both are open drafts.
  • Its own change is the one record file: verified; every later commit touches only that file.
  • The record is NavigationStack's React Native platform record with a language-qualified id and platform_of: verified, record lines 5–6.
  • The listed records and drafts exist with the stated authority: verified; the native-first, native-guideline, touch and popover-anchoring records are current, the React Native foundation record is draft on the default branch, and every cited draft is an open pull request.
  • No other record owns NavigationStack on React Native or the screen container: verified.
  • React Native keeps web's props, names, types and defaults, with one change, push's sourceRef, a ref object, because every ref-valued input ends in Ref: verified; the props match Lab's web types, and the name and type follow the system's ref naming.
  • Native stack rendering, system pops as one onPathChange, back gestures and transitions, header mapping, Screen and its hook, router direction, no third-party native library, the screen options and accessibility are as the description lists: present in FR2–FR19 and AR1–AR6, proposed and unapproved.
  • The stack starts in the lab space under ./unstable/* and moves to ./navigation when web's NavigationStack leaves Lab: present in FR1, the Compatibility cell and DEC-5; the foundation requirement it cites exists only in an open draft, which now says the same.
  • No rejected alternatives are recorded: verified.
  • The claims are FR1–FR19, AR1–AR6, ORD1–ORD2, PR1–PR2 and DEC-1–DEC-6, and the non-goals name each adjacent owner: verified.
  • Two open questions remain, on Android's disabled back swipe and on system focus: verified, OQ1 and OQ2.
  • No React Native implementation exists in the repository: verified, no React Native package.
  • The verification map names evidence for each requirement: verified; the FR1 row's unmounted-view state has no failure signal (non-blocking above).
  • Writing rubric results (present tense, no research, no pull request references, no project status): verified; the only status text is the template's release field and readiness cell.
  • Scope checklist (specification records only, owners and overlapping work named): holds; who decided DEC-5 and DEC-6 is part of the owner decision.
  • check:knowledge passes and a wrong id gets the quoted message: verified by a run at this head and the new validation test.
  • Prettier and the whitespace check are clean: verified.

Files:

  • .github/scripts/knowledge-paths.cjs: clear.
  • .github/scripts/knowledge-paths.test.mjs, .github/scripts/change-scope.test.mjs, scripts/check-knowledge.test.mjs, scripts/specs-for-file.test.mjs: clear; they pass at this head.
  • docs/architecture/knowledge-contracts.md: waits on owner approval of the language sentence.
  • docs/specs/components/NavigationStack/NavigationStack.react-native.spec.md: waits on owner approval; two non-blocking suggestions.

Automated review (maintainer link)

title is its accessibility title: VoiceOver announces the screen change, and
on Android the screen's pane title is its `title`, so TalkBack announces it.
- **AR2 — Pop returns focus.** After a pop, VoiceOver and TalkBack focus MUST
return to the control that pushed the screen: the view `push`'s `sourceRef` points to when given,

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: the FR1 verification row (line 258) now tests "a sourceRef whose view unmounted before the pop", but AR2 gives no result for it, and DEC-6 reads the ref at the pop, so sourceRef.current is null there. Core's focus rule, which AR1 follows, moves focus to the revealed screen's title when the pushing control is gone or cannot take focus (Lab NavigationStack.tsx, the pop branch of its focus move). Suggest ending AR2 with "When that view is gone or cannot take focus, focus moves to the revealed screen's title, as core's does", and naming that case in the FR1 row's failure column.

| FR15 | `Screen` MUST apply the screen's insets from its first frame (`spec:AST-125` FR10; `spec:AST-129`), so no edge is padded twice and no content sits under the bar, the home indicator or a display cutout. It MUST keep a focused text field above the keyboard: in `scroll` mode by scrolling the field into view, in `fill` mode by ending its content above the keyboard. Content in a keyboard dock rides on the keyboard (`spec:AST-129`). | `spec:AST-125` FR10; `spec:AST-129` | verify |
| FR16 | `onRefresh` MUST add the platform's pull to refresh to a `scroll` mode screen's scroll target: the system refresh control on iOS and the Material swipe-refresh indicator on Android. `isRefreshing` shows the indicator; the screen calls `onRefresh` when the person pulls past the system's threshold. A screen has one refresh home: a scroll target that brings its own refresh (a `List` with its own scroller) takes precedence and is the screen's refresh. | DEC-2 | verify |
| FR17 | NavigationStack MUST be the stack of Astryx's router, which supports Astryx's header, tab bar and sheets: a stack the router declares behaves as this record states. An app MAY navigate with another router, such as Expo Router, instead. Astryx's components, `Screen` included, MUST then work inside that router's screens, and that router's navigation (its stack, transitions, back handling and header) is not covered by Astryx. There `Screen` takes its insets from the safe area (`spec:AST-129`) and adds no bar of its own. | DEC-3 | settled |
| FR18 | NavigationStack and `Screen` MUST need no third-party native library: their native pieces are Astryx's own (FR2; `spec:AST-112` FR2). An app MAY link react-native-screens, react-native-gesture-handler, Reanimated and react-native-safe-area-context beside them. With any of them linked, the stack's pushes, pops, back gestures and insets MUST behave as this record states, and those libraries' own views MUST keep their behaviour inside a `Screen`. | `spec:AST-112` FR2; DEC-3 | verify |

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: FR18's basis cites spec:AST-112 FR2, which is draft on main, while current spec:AST-082 FR13 already says any other third-party library "is never required to use Astryx on any platform". Citing AST-082 FR13 in this basis cell anchors FR18 to current authority.

@imdreamrunner imdreamrunner changed the title spec(NavigationStack): React Native platform record (draft) spec(NavigationStack): React Native platform record Nov 19, 2026

This branch was successfully deployed

1 active deployment
Preview — 5bd64d40 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. needs:spec-owner-review Current knowledge records await owner approval

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant