Repository navigation
docs(spec): AppShell region plugins and Focus Mode - #8410
humbertovirtudes wants to merge 1 commit into
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
AI review status for this pull request.
|
meta-cla
Bot
added
the
CLA Signed
![astracat-bot[bot]](https://avatars.githubusercontent.com/in/4796231?s=60&v=4){kind=small}
There was a problem hiding this comment.
This draft spec can't be approved yet. No current spec covers its new AppShell plugins API and Focus Mode (FR1–FR14), so an engineering owner needs to decide OQ1–OQ4, including whether region descriptors should be able to replace children and padding alongside the existing slot props, or carry only isHidden. An engineering owner records that decision by commenting /approve-spec <full head SHA> on this pull request; as an engineering owner, you can do so yourself. Whatever the decision, these points conflict with current records and need fixing:
- FR7 moves focus to main when the drawer closes, but the current MobileNav contract (FR6) returns focus to an opener that is still connected. Either name that amendment in Current-state impact or make FR7 conform.
- Under reduced motion the record settles changes immediately, but the current reduced-motion design (DR2) requires an opacity-only cross-fade of 200 ms or less on touch screens.
- FR9's
--ease-standardand the animation of the space navigation releases predate the current theme-motion spec (AST-108) and AppShell's FR17. Please reconcile them when you rebase.
[Automated review]
| MobileNav's native dialog closes and releases page inertness before its | ||
| Activity boundary suspends cleanup. Its ordinary restoration to the opener | ||
| does not target navigation that is becoming hidden: the cooperating drawer | ||
| completes native close, suppresses that obsolete restoration, and hands focus |
There was a problem hiding this comment.
The current MobileNav contract (FR6) returns focus to the recorded opener whenever it is still connected, and an opener inside a region Activity hides stays connected. Suppressing that restoration changes MobileNav's contract, so please name FR6 (and AR2) in Current-state impact as claims this record amends, or make this requirement conform.
| this contract does not raise their floor. | ||
| - The React support floor remains the Core package's peer dependency. Activity | ||
| capability and effect-lifecycle compatibility are separate from CSS support. | ||
| - Reduced motion and an unsupported transition enhancement settle immediately |
There was a problem hiding this comment.
Under a coarse primary pointer, the current reduced-motion design (DR2) requires an opacity-only cross-fade of 200 ms or less, not an immediate change. Consider stating that visibility transitions follow reduced-motion DR1–DR3 and DR2a, as AppShell's FR17 and MobileNav's FR7 do.
| entry animation or a flash of the opposite state. Only subsequent visibility | ||
| changes animate. A post-hydration breakpoint correction alone does not count | ||
| as a Focus Mode action. `spec:AST-013` FR9 and FR13 remain applicable. | ||
| - **FR9 — Motion remains token-based.** Shell motion uses `--duration-medium` |
There was a problem hiding this comment.
In the current theme-motion spec (AST-108 FR2), --ease-standard is the exits' curve and stays the same at every character; entrances and moves read --ease-entrance and --ease-move. AppShell's FR17 also says the content area never animates its width. Please say which motion each part of the transition uses and how it relates to FR17.
Exact decision needed
Refs #4255. This is a specification-only draft for AppShell's region-transform plugin API and its first Focus Mode plugin. It does not implement or close the feature.
The caller knows whether otherwise identical page content is part of ordinary navigation or a focused task. Removing navigation slots loses state; styling alone cannot coordinate generated drawers, native modal close, and focus. The candidate keeps that task intent at the shell boundary.
Owner decisions remain explicit in OQ1-OQ4: region descriptor and ordering admission, the single preset, effect lifecycle without React Activity on the supported React floor, and restoration of requested drawer state.
Existing authority searched
component:AppShell,family:layout-regions,family:overlay-dismissal,spec:AST-002,spec:AST-013, and the React runtime and component-theming architecture.AppShellPlugin,useFocusMode, region transforms, Focus Mode and overlapping public work. No active duplicate implements this feature. fix(AppShell): animate nav surface enter/exit (#4174) #4194 is closed and unmerged in favour of AppShell: region-transform plugin system + Focus Mode (first built-in plugin) #4255.The distinct system boundary is coordination between AppShell visibility, a cooperating MobileNav's native modal lifecycle, and focus handoff to page content. AppShell remains the aggregate API owner; Focus Mode's independent contract belongs to its module. The current canonical owners must receive the approved projections before build.
Decision
Candidate contract:
focusModefirst, then custom own-entry order; region writes compose forward and the last write wins. The first context wrapper is outermost, matching Table.focuspreset hides top/side/mobile navigation and preserves banner, content, padding and independent SideNav state.No owner decision is recorded by this draft.
Rejected alternatives
A dedicated focus-mode prop or independent hide props creates a second mechanism instead of the selected plugin direction. Child-component props cannot represent arbitrary existing node slots. Conditional removal loses navigation state; a fragment-only visibility fallback leaves navigation interactive. More presets, augmentation, motion tuning and shortcuts need separate caller-need evidence.
Claim scope and non-goals
Specification records only. No runtime implementation, exports, stories, changesets, theme targets, consumer-doc changes, SideNav collapse/resize changes, or unrelated shell repairs. Main content and its skip target remain available.
Evidence and implementation relationship
The record is grounded in current source and existing canonical contracts. Its verification matrix describes required future evidence, not completed feature tests. An independent critique informed the native-modal focus sequence, custom-drawer cooperation boundary, effective context state, absent/disabled slot cases and Table-compatible context order.
Implementation remains held until exact-text owner decisions are recorded as current authority.
Writing rubric results
Scope
Validation
node scripts/check-knowledge.mjs(thepnpm check:knowledgescript): passed; all knowledge templates and records are aligned.git diff --check: passed.419bbed8628d2fc5b3bd6b6d83128d639c441cab.37c057574712701eaeb6259cf8f0c8c0df971f70.