Skip to content

spec(Lightbox): React Native platform record - #12849

Draft
imdreamrunner wants to merge 4 commits into
chore/knowledge-react-native-platform-recordsfrom
spec/lightbox-react-native-record
Draft

imdreamrunner wants to merge 4 commits into
chore/knowledge-react-native-platform-recordsfrom
spec/lightbox-react-native-record

Conversation

@imdreamrunner

@imdreamrunner imdreamrunner commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

Stacked on #12592; merges after it.

Merge order: this record also cites spec:AST-124 (#12562, the zoom pager) and spec:AST-132 (#12565, the video view). It merges after those too.

Exact decision needed

How React Native presents Lightbox: the form of media, the viewer's window and parts, how core's touch model runs on a phone through the zoom pager, how a video item plays, and how the viewer closes.

Existing authority searched

  • component:Lightbox (docs/specs/components/Lightbox/Lightbox.spec.md): the props, parts, touch model (FR5–FR10), index rule (FR17), video paging (FR18) and media surface (FR19) this record keeps.
  • family:overlay-dismissal: which closes the viewer allows.
  • spec:AST-124 (open draft): owns AstryxZoomPager, whose public face is Lightbox (FR8), and records Lightbox's scroll-view zoom as an FR8 gap.
  • spec:AST-132 (open draft): owns AstryxVideoView (FR7).
  • spec:AST-082 FR3, FR4, FR7 and FR11: the core and platform contracts, portable forms, base props and native-first.
  • No React Native Lightbox record exists, and no other open pull request carries one.

Decision

docs/specs/components/Lightbox/Lightbox.react-native.spec.md (component:react-native/Lightbox, platform_of: component:Lightbox):

  • React Native keeps core's props; media takes an array (an array of one is a single view), since one record or an array of them is not a portable form; caption stays content; xstyle stays web (FR1).
  • The viewer fills the screen in a modal window on the dark media surface with light status bar content, and keeps core's parts and index rule (FR2, FR3).
  • On a phone it keeps core's touch model: paging (core FR7, ORD1), the drag-down close, the tap beside the photo while the controls show, and with hasZoom only the zoom, double tap, pinch-in close and tap to hide the controls (core FR13). Every frame runs on the UI thread; the zoom pager provides that, and any equivalent that does meets the rule (FR4). The design section names the QuickLook file viewer on iOS and why it does not fit, and Android has no embeddable system viewer.
  • A video item plays in a platform video player with its own controls (the video view is that player), hasAutoPlay starts it, and a paged-away video pauses where it stopped (FR5).
  • Close, Android back, the VoiceOver escape and the gesture closes call onOpenChange(false) (FR6); paging and the closing gestures have button alternatives (Previous and Next; Close), and pinch zoom and pan keep core's double tap (AR4).
  • FRn gap lines state where the package differs: iOS zooms with a scroll view (no double tap, no paging drag), Android without the pager does not zoom, no gesture closes or tap-to-hide, video does not play, and dark status bar content in iOS light mode.

Rejected alternatives

None recorded in the record.

Claim scope and non-goals

The record covers only what React Native adds to component:Lightbox or does differently. The zoom pager and the video view stay with their owners, which the ownership lines name.

Evidence and implementation relationship

The record is a specification only and has no implementation in this pull request. It was read against the React Native package's Lightbox (the viewer, the Android zoom pager wrapper) and its generated contract. The gap lines state where the package differs from the requirements.

Writing rubric results

  • R1 narration: none; the record is in the present tense.
  • R2 research in the record: none; one-sentence reason inside FR1 only.
  • R3 evidence naming a change: none; every basis cell names records and claims.
  • R4 rejected alternatives over one line or outside a decision: none; the record keeps no Rejected: lines.
  • R5 pull request or issue references remaining: none in the record.
  • R6 ruled open questions still listing options: none; Open questions reads "None."
  • R7 project status (build status or work order): package differences are stated as FRn gap lines; "not yet released" appears only in the template's lifecycle field and readiness cell.

Scope

Components: Lightbox (React Native)

  • 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

  • node scripts/check-knowledge.mjs: knowledge templates and records are aligned; no finding in this record.
  • Prettier: --check clean on the record.
  • git diff --check: clean.

@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 8:08am UTC

Request Review

@astracat-bot

astracat-bot Bot commented Nov 19, 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, 8:13 AM UTC

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

Approval waits on an engineering owner's decision on this draft record's new requirements, and five fixes to the record stand either way.

An engineering owner approves or changes the requirements by commenting /approve-spec <full head SHA> on this pull request, and the author may do this as an engineering owner. The decision covers FR1's array-only media (it decides Lightbox's portable form, which component:Lightbox does not state), FR4's UI-thread zoom pager and FR5's platform video view (both rest on the open drafts spec:AST-124 and spec:AST-132), and the Android presentation while spec:AST-093 OQ1 is still open.

Fixes needed (blocking once that decision lands):

  • FR4 says a pan pushed far past a zoomed photo's edge turns the page, but component:Lightbox FR7 and ORD1 page only on a new drag from that edge, so state core's rule or propose the change in the core record.
  • FR4 puts the pinch-in close and the tap that hides the controls outside its hasZoom clause, while core FR9, FR10 and FR13 gate both on hasZoom (and the record's own Public concepts row agrees with core).
  • The FR4 gap line about a tap beside the photo names a close that neither FR4 nor FR6 requires, and it cites core FR8–FR10 where core states that close in ORD3 and FR16.
  • The Design relationships section names no platform viewer control it looked for and no reason none fits, which spec:AST-093 FR2 requires when a component draws its own control.
  • The description says every named internal mechanism explains why an equivalent would not satisfy the contract, but FR4 and the Native pieces table make the internal zoom pager and video view requirements without that reason.
Claims and files checked

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

  • Claim: stacked on the change that accepts React Native platform records and merges after it. Verified: the base branch is that change.
  • Claim: cites the zoom-pager and video-view drafts and merges after them. Verified: both are open drafts that define the cited pieces.
  • Claim: keeps core Lightbox's props, parts, touch model, index rule, video paging and media surface. Partly false: FR4's over-pan paging and its hasZoom gating differ from core.
  • Claim: overlay dismissal decides which closes are allowed. Verified: its platform-close rule applies.
  • Claim: the zoom-pager draft names Lightbox as its public face and records Lightbox's scroll-view zoom as a gap. Verified in its FR8.
  • Claim: the video-view draft owns the native video view. Verified in its FR7.
  • Claim: the native-first spec's core and platform contracts, portable forms, base props and native-first rule apply. Verified.
  • Claim: no React Native Lightbox record exists and no other open pull request carries one. Verified on the main branch; open pull requests were checked by search only.
  • Claim: the decision bullets (props and media form, window and parts, video, closes, gap lines) match the record. Verified, except the touch-model bullet above.
  • Claim: the gap lines state where the package differs. The record text is verified; the package's behavior is not checkable here.
  • Claim: no rejected alternatives are recorded. Verified.
  • Claim: the record covers only what React Native adds, and the zoom pager and video view stay with their owners. Verified.
  • Claim: specification only, with no implementation. Verified: one Markdown file.
  • Claim: the record was read against the React Native package and its generated contract. Not checkable: the package is not in this repository.
  • Claim: writing rubric R1–R7 results. Verified: present tense, no pull request references, no rejected lines, open questions read “None.”, and “not yet released” appears only in template fields.
  • Claim: every named internal mechanism explains why an equivalent would not satisfy the contract. False: see the last fix above.
  • Claim: the other scope checklist items. Verified.
  • Claim: the knowledge check, Prettier and the whitespace check are clean. Verified by rerunning all three.
  • File docs/specs/components/Lightbox/Lightbox.react-native.spec.md: the five fixes above, plus a non-blocking note that FR4's “On a phone” leaves tablets unspecified.

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.

Approval waits on an engineering owner's decision on this draft record's new requirements, and three fixes to the record stand either way.

An engineering owner approves or changes the requirements by commenting /approve-spec <full head SHA> on this pull request, and the author may do this as an engineering owner. The decision covers FR1's array-only media (it settles Lightbox's portable form, which component:Lightbox does not state), FR4's UI-thread rule and FR5's platform video player (both rest on the open drafts spec:AST-124 and spec:AST-132), and the Android presentation while spec:AST-093 OQ1 is still open.

Fixes needed (blocking once that decision lands):

  • Miss: ORD2 says a zoomed photo only pans and paging happens at the fitted size, but component:Lightbox ORD1 and this record's FR4 page on a new drag from a zoomed photo's edge, so restate ORD2 to match core ORD1.
  • FR4 cites spec:AST-082 FR11 for the rule that a busy JavaScript thread never stalls a gesture, but FR11 is the native-first rule and no current record states a UI-thread rule, so cite the zoom-pager draft for it and drop FR11 there.
  • Miss: AR4 and the Review checks row require a button alternative for every gesture, but pinch zoom, the double tap and a zoomed photo's pan have none and core AR1 and AR2 give them the double tap, so limit the button wording to paging and the closing gestures.
Claims and files checked

Review mode: full; reason: spec-record

  • Claim: stacked on the change that accepts React Native platform records and merges after it. Verified: the base branch is that open change.
  • Claim: cites the zoom-pager and video-view drafts and merges after them. Verified: both are open drafts that define the cited pieces.
  • Claim: keeps core Lightbox's props, parts, touch model, index rule, video paging and media surface. Partly false: ORD2 limits paging to the fitted size, unlike core's zoom-before-paging rule.
  • Claim: overlay dismissal decides which closes are allowed. Verified: its platform-close rule applies.
  • Claim: the zoom-pager draft names Lightbox as its public face and records Lightbox's scroll-view zoom as a gap. Verified in its FR8.
  • Claim: the video-view draft owns the native video view. Verified in its FR7.
  • Claim: the native-first spec's core and platform contracts, portable forms, base props and native-first rule apply. Verified; the record also cites the native-first rule for the UI-thread rule, which it does not state (second fix).
  • Claim: no React Native Lightbox record exists and no other open pull request carries one. Verified on the main branch and by a repository search.
  • Claim: React Native keeps core's props, takes media as an array, keeps the caption as content and leaves xstyle on the web. Verified in FR1.
  • Claim: a full-screen modal on the dark media surface with light status bar content, keeping core's parts and index rule. Verified in FR2 and FR3.
  • Claim: on a phone, core's paging, the drag-down close, the tap beside the photo while the controls show, and with hasZoom only the zoom gestures, pinch-in close and tap to hide; frames on the UI thread through the zoom pager or any equivalent. Verified in FR4; ORD2 disagrees on paging (first fix).
  • Claim: the design section names the iOS file viewer and why it does not fit, and Android has no embeddable viewer. Verified.
  • Claim: a video plays in a platform player with its own controls, autoplay starts it, and a paged-away video pauses where it stopped. Verified in FR5.
  • Claim: Close, Android back, the screen-reader escape and the gesture closes call onOpenChange(false). Verified in FR6.
  • Claim: every gesture keeps its button alternative. False: pinch zoom, the double tap and a zoomed pan have none (third fix).
  • Claim: the gap lines state where the package differs. The record text is verified; the package's behavior is not checkable here.
  • Claim: no rejected alternatives are recorded. Verified.
  • Claim: the record covers only what React Native adds, and the zoom pager and video view stay with their owners. Verified.
  • Claim: specification only, with no implementation. Verified: one Markdown file.
  • Claim: the record was read against the React Native package and its generated contract. Not checkable: the package is not in this repository.
  • Claim: writing rubric R1–R7 results. Verified: present tense, no pull request references, no rejected lines, open questions read "None.", and "not yet released" appears only in template fields.
  • Claim: every named internal mechanism is public on purpose or replaceable by an equivalent. Verified for FR4 and FR5; PR1 still names the zoom pager (non-blocking note below).
  • Claim: the other scope checklist items. Verified.
  • Claim: the knowledge check, Prettier and the whitespace check are clean. Verified by rerunning all three.
  • File docs/specs/components/Lightbox/Lightbox.react-native.spec.md: the three fixes above, plus non-blocking notes: PR1 still says paging, zoom and pan run in the zoom pager although FR4 accepts any equivalent (Miss), FR3 cites core FR1 for the gallery ends where core states them in AV2, and "On a phone" leaves tablets unspecified.

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.

Approval waits on an engineering owner's decision on this draft record's new requirements, and one fix to the description stands either way.

An engineering owner approves or changes the requirements by commenting /approve-spec <full head SHA> on this pull request, and the author may do this as an engineering owner. The decision covers FR1's array-only media (it settles Lightbox's portable form, which component:Lightbox does not state), FR2's window and status bar, FR4's UI-thread rule and FR5's platform video player (both rest on the open drafts spec:AST-124 and spec:AST-132), and the Android presentation while spec:AST-093 OQ1 is still open.

Fix needed, blocking once that decision lands:

  • The description says "every gesture keeps its button alternative (AR4)", but AR4 now gives buttons only to paging and the closing gestures and keeps core's double tap for pinch zoom and pan, so change that line to match AR4.
Claims and files checked

Review mode: full; reason: spec-record

  • Claim: stacked on the change that accepts React Native platform records and merges after it. Verified: the base branch is that open change.
  • Claim: cites the zoom-pager and video-view drafts and merges after them. Verified: both are open drafts that define the cited pieces.
  • Claim: keeps core Lightbox's props, parts, touch model, index rule, video paging and media surface. Verified in FR1 to FR5 and ORD2.
  • Claim: overlay dismissal decides which closes are allowed. Verified: its platform-close rule applies.
  • Claim: the zoom-pager draft names Lightbox as its public face and records Lightbox's scroll-view zoom as a gap. Verified in its FR8.
  • Claim: the video-view draft owns the native video view. Verified in its FR7.
  • Claim: the native-first spec's core and platform contracts, portable forms, base props and native-first rule apply. Verified.
  • Claim: no React Native Lightbox record exists and no other open pull request carries one. Verified on the main branch and by a repository search.
  • Claim: React Native keeps core's props, takes media as an array, keeps the caption as content and leaves xstyle on the web. Verified in FR1.
  • Claim: a full-screen modal on the dark media surface with light status bar content, keeping core's parts and index rule. Verified in FR2 and FR3.
  • Claim: on a phone, core's paging, the drag-down close, the tap beside the photo while the controls show, and with hasZoom only the zoom gestures, pinch-in close and tap to hide; frames on the UI thread through the zoom pager or any equivalent. Verified in FR4 and ORD2.
  • Claim: the design section names the iOS file viewer and why it does not fit, and Android has no embeddable viewer. Verified.
  • Claim: a video plays in a platform player with its own controls, autoplay starts it, and a paged-away video pauses where it stopped. Verified in FR5.
  • Claim: Close, Android back, the screen-reader escape and the gesture closes call onOpenChange(false). Verified in FR6.
  • Claim: every gesture keeps its button alternative. False: AR4 keeps the double tap for pinch zoom and pan (the fix above).
  • Claim: the gap lines state where the package differs. The record text is verified; the package's behavior is not checkable here.
  • Claim: no rejected alternatives are recorded. Verified.
  • Claim: the record covers only what React Native adds, and the zoom pager and video view stay with their owners. Verified.
  • Claim: specification only, with no implementation. Verified: one Markdown file.
  • Claim: the record was read against the React Native package and its generated contract. Not checkable: the package is not in this repository.
  • Claim: writing rubric R1 to R7 results. Verified: present tense, no pull request references, no rejected lines, open questions read "None.", and "not yet released" appears only in template fields.
  • Claim: every named internal mechanism is public on purpose or replaceable by an equivalent. Verified: FR4 and FR5 accept any equivalent, and PR1 now names only the UI thread.
  • Claim: the other scope checklist items. Verified.
  • Claim: the knowledge check, Prettier and the whitespace check are clean. Verified by rerunning all three.
  • File docs/specs/components/Lightbox/Lightbox.react-native.spec.md: the earlier ORD2, FR11-citation and AR4 fixes are in; non-blocking notes: FR2 credits core FR19 with an opaque backdrop that FR19 does not state (Miss), FR3 cites core FR1 for the gallery ends where core states them in AV2, and "On a phone" leaves tablets unspecified.

Automated review (maintainer link)

| ID | Candidate invariant | Basis | Draft review state |
| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | ------------------ |
| FR1 | React Native MUST export the component as `Lightbox`, its name on every platform, and keep core's props, meanings and defaults (`spec:AST-082` FR3). `media` takes an array of items, and an array of one is a single view: a value that is either one record or an array of records is not one of the portable forms (`spec:AST-082` FR4), so core's single-object form stays web. Each item is `src`, `alt`, an optional `caption`, which is content as on the web since React Native runs React (`spec:AST-082` FR4), and an optional `type`. `xstyle` stays web. | `component:Lightbox`; `spec:AST-082` FR3, FR4 | settled |
| FR2 | The open viewer MUST fill the screen in a modal window over the app, under the system bars, with Android back as its close request. It is a media surface: its controls and caption take the theme's dark media surface values over an opaque dark backdrop (core FR19), and the status bar shows light content over it. | `component:Lightbox` FR19; `spec:AST-093` FR3 | 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: "an opaque dark backdrop (core FR19)" credits core with more than it says. component:Lightbox FR19 states only that the viewer renders inside MediaTheme (dark), so its controls and caption take the theme's dark surface tokens. Cite the claim that states an opaque backdrop, or leave it to the owner's ruling on FR2.

This branch was successfully deployed

1 active deployment
Preview — d2b064ec 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