@cahyo-dimas/freeday 1.52.1 → 1.54.0

package/CHANGELOG.md

@@ -3,6 +3,88 @@
 Semua perubahan penting dicatat di sini. Format longgar mengikuti
 [Keep a Changelog](https://keepachangelog.com/); tiap versi = git tag.
 
+## [1.54.0] — 2026-08-25
+### Added
+- **`<FdyAppShell>` — the shell becomes the eleventh typed component**, in Vue, React and Blazor
+  (`NEXT-UP.md` #8, stage 2). One model: `navOpen` means *the nav is visible to the reader*, and the
+  kit owns the mapping — above the nav breakpoint a hidden nav is `--nav-collapsed`, below it a
+  visible nav is `--nav-open`. An app never reasons about the viewport to answer a question about
+  its own UI. Vue `v-model:navOpen` · React `navOpen`/`onNavOpenChange` · Blazor `@bind-NavOpen`.
+- **The prop is optional in all three, and that is the design.** Unbound, the shell starts from the
+  viewport: a column on a wide screen, hidden on a narrow one. A caller cannot express that as a
+  single initial value before it knows the viewport, so `undefined` (Vue/React) and `null` (Blazor)
+  mean "you decide". Bound, the caller wins and is pushed down on mount.
+- **`adapters/core/app-shell.js`** (+ `.d.ts`) — the Tab trap, `inert` bookkeeping and focus restore
+  shared by the Vue and React wrappers, following `adapters/core/table-model.js`. `NAV_QUERY` is
+  built from `tokens/breakpoints.mjs` rather than repeating `721`, so the JS and `app-shell.css`
+  cannot drift. Blazor does not use it: `freeday-blazor.js` says the enhancers stay the source of
+  truth, so the Blazor shell renders `data-fdy-app` and BINDS to `freeday-app-shell.js`. Two
+  implementations, not four, and a guard holds them to one contract.
+- **`fdy-app-nav`** — the enhancer now emits a bubbling CustomEvent (`detail {visible}`) on every
+  real change, and takes `FreedayAppShell.setVisible(root, visible)` / `isVisible(root)` from
+  outside. That is what the Blazor binding rides on, and what any vanilla app persisting a collapsed
+  preference needed. The event fires for viewport-driven changes too — narrowing hides a nav that
+  was a visible column, and a bound value that stayed `true` would describe a panel nobody can see.
+  Setting what is already set announces nothing, so a bound host cannot loop on its own echo.
+### Docs
+- `COMPONENTS.md` §App shell carries the typed-wrapper line and the `navOpen` contract; `USAGE.md`
+  now tells you to take the behaviour, not just the frame. The parity claim moves from 10/10 to
+  11/11 in `README.md`, `README.id.md`, `CLAUDE.md`, `docs/agent-onboarding.md` and `NEXT-UP.md`.
+- `NEXT-UP.md` #8 is struck through rather than deleted, and its number kept: the CHANGELOG, the
+  design spec and two guard headers already say "NEXT-UP #8", so renumbering the rows under it would
+  quietly break references that are already written down.
+### Added — guards
+- `browser/adapter.mjs` runs one description of the shell contract against BOTH typed stacks —
+  viewport default, focus into the panel, the Tab cycle, Escape returning focus, `inert`, and a nav
+  link closing the overlay. Verified by sabotage: with `applyShellState` and the focus calls stubbed
+  out, React fails three of three and Vue two of three, the third being the sidebar click path the
+  sabotage did not touch.
+- `browser/app-shell.mjs` gains the host-binding pair (`fdy-app-nav` ordering, `setVisible` doing the
+  whole job and staying silent on a no-op) and the path only Blazor takes: a shell that does not
+  exist at `DOMContentLoaded`, hydrated afterwards by handing `initAll` the component's own root —
+  which is the element itself, not a descendant of it.
+- `dotnet build` on the Blazor RCL is clean (0 warnings, 0 errors).
+
+## [1.53.0] — 2026-08-24
+### Added
+- **`freeday-app-shell.js` — the shell finally ships its own behaviour** (`NEXT-UP.md` #8, reported
+  twice). `.fdy-app` shipped `__navtoggle`, `__backdrop` and the `--nav-open` / `--nav-collapsed`
+  classes with **zero JS**, and `COMPONENTS.md` told every consumer to wire it in two sentences that
+  never mentioned Escape, focus, `inert` or focus restore. Follow that exactly and you get an
+  off-canvas overlay that cannot be closed from the keyboard and lets Tab wander behind the
+  backdrop. Opt in with `data-fdy-app`; the markup is otherwise untouched, so an existing shell
+  gains the behaviour by adding one attribute and deleting its own copy.
+  Owned now: the toggle in both modes, Escape, backdrop click, closing when a `.fdy-nav__item` is
+  followed, focus into the panel and back to `__navtoggle` on close, `inert` on `__content` while
+  the overlay is open, and a Tab trap inside the panel.
+### Fixed
+- **A hidden nav was still a tabbable nav**, in both modes and from the beginning. Collapsed at
+  ≥721px is `width:0;overflow:hidden`; off-canvas at ≤720px is `translateX(-100%)`. Both hide the
+  panel from the eye and neither hides it from the keyboard, so a nav nobody could see still
+  swallowed every Tab on the way into the page. `__sidebar` is now `inert` whenever the nav is not
+  visible — one rule for both modes rather than two patches.
+- **Crossing the breakpoint with the overlay open stranded the page.** Widening the window left
+  `--nav-open` set and `__content` `inert`, so the page underneath could never be clicked or read
+  again — the same failure that produced `breakpoints.nav` in v1.20.0. The enhancer clears the
+  overlay state on the media-query change, and deliberately does *not* move focus while doing it: a
+  resize is not a user asking to go somewhere.
+### Changed
+- **`docs/index.html` and `docs/reference-screen.html` stopped hand-rolling it**, which is the
+  proof rather than a tidy-up. The two copies had drifted: `index.html` handled Escape and
+  close-on-nav-click, `reference-screen.html` handled neither, and *neither* trapped focus, marked
+  the content `inert`, or restored focus. Two versions in one repository disagreeing is the whole
+  argument for the kit owning this.
+### Added — guards
+- `browser/app-shell.mjs` (5 tests), each verified to fail with the enhancer switched off: collapse
+  and its `inert` at ≥721px, the overlay and its `inert` at ≤720px, focus entering the panel and
+  cycling inside it under **trusted** Tab presses, Escape returning focus to the toggle, backdrop
+  and nav-item dismissal, and the breakpoint crossing. One of the five originally passed against a
+  shell with no behaviour at all — the nav never opened, so "it is closed" was true and meaningless
+  — and now asserts it opened first.
+- `setViewport()` in the browser harness (`Emulation.setDeviceMetricsOverride`). A responsive
+  contract cannot be tested at a fixed window size, and the moment a layout *crosses* a breakpoint
+  is exactly where its state gets stranded.
+
 ## [1.52.1] — 2026-08-24
 ### Docs
 - **1.51.1's close-watcher caveat named the wrong condition** (#048). It said a `showModal()` with
@@ -30,6 +112,29 @@ Semua perubahan penting dicatat di sini. Format longgar mengikuti
 - The fixture records each `cancel` event's `cancelable` flag; nothing prevents it, so the older
   tests measure what they always did.
 
+### Fixed — the kit's own suite
+- **The browser guards did not run where the releases are made.** CI ran the 59 unit tests and
+  published; the 58 browser tests across 18 specs — pixel paint order for stacked overlays, chart
+  accessible subtrees, the user-activation matrix above — ran only when someone remembered to run
+  them locally. Automating the release through OIDC in 1.52.0 removed the someone. `ci.yml` now runs
+  both suites on every push and is *called* by `publish.yml` (`needs: test`), so the step list that
+  guards a release cannot drift from the one that runs during development, and a tag with red guards
+  never reaches npm.
+- **A job that merely ran the command would have been green while running nothing.** Every browser
+  spec skips itself when no Chrome is found, and a skipped suite still exits 0. So the job checks
+  the binary before it starts and then parses its own summary, failing on any skip — "the job was
+  green" and "the guards ran" were separate facts, and only one of them was enforceable. Both
+  demonstrated on real runs: the assertion green at 58/0, and a deliberately broken `CHROME_BIN`
+  red.
+- **The harness can now drive any installed Chrome.** `chrome-headless-shell` is headless by
+  construction; an ordinary Chrome binary is not and, on a machine with no display, looks for one
+  and dies. It now gets `--headless=new` (and `--no-sandbox` only under `CI`), which is what lets
+  `CHROME_BIN=<some other Chrome>` compare engines — the manoeuvre that settled #048. CI runs the
+  runner's Chrome stable, local runs Chromium 133, so both engines `COMPONENTS.md` names are
+  genuinely exercised.
+- Spec: `docs/superpowers/specs/2026-08-24-browser-guards-in-ci-design.md`. No shipped file changed —
+  `browser/` and `.github/` are not in the published tarball, so there is no release for this.
+
 ## [1.52.0] — 2026-08-24
 ### Fixed
 - **A chart's legend, bar values and donut centre were exposed to assistive tech after all** (#047).

package/COMPONENTS.md

@@ -114,6 +114,8 @@ is a no-op.
 # Shell & composition
 
 ## App shell — `.fdy-app`
+> **Typed wrapper: `<FdyAppShell>`** — Vue (`v-model:navOpen`) · React (`navOpen`/`onNavOpenChange`) · Blazor (`@bind-NavOpen`). In those stacks use the wrapper; the markup below is for stacks without an adapter (and is what the wrapper renders).
+
 The frame every application lives in. Do not hand-roll one from flexbox: the responsive sidebar,
 off-canvas drawer and backdrop are built in.
 
@@ -122,8 +124,34 @@ off-canvas drawer and backdrop are built in.
 - Modifiers: `--nav-open` (mobile drawer open, ≤720px) · `--nav-collapsed` (collapse to zero width,
   ≥721px) · `--static` (embed the shell in a page instead of filling the viewport)
 - Also: `.fdy-skip` — the skip-to-content link, first child of the shell.
-- JS: none. Toggle `--nav-collapsed` (≥721px) or `--nav-open` (≤720px) on the root from
-  `__navtoggle`'s click; clear `--nav-open` when `__backdrop` is clicked.
+- **Behaviour: `freeday-app-shell.js`.** Opt in with `data-fdy-app` on the root — the markup below
+  is unchanged. It owns the toggle in both modes plus everything an overlay needs that hand-rolling
+  reliably forgets: Escape, backdrop click, closing when a `.fdy-nav__item` is followed, focus moved
+  into the panel on open and returned to `__navtoggle` on close, `inert` on `__content` while the
+  overlay is up, and a Tab trap inside the panel. `aria-expanded` on `__navtoggle` answers "is the
+  nav showing?" in both modes, so you never read the state classes yourself.
+- **A hidden nav is not a tabbable nav.** `__sidebar` is `inert` whenever the nav is not visible —
+  collapsed at ≥721px (`width:0`) or off-canvas at ≤720px (`translateX(-100%)`). Both hide it from
+  the eye; neither hides it from the keyboard, so without this a nav nobody can see still swallows
+  Tab on the way to the page.
+- **Crossing the breakpoint is part of the contract**: open the overlay, then widen the window, and
+  `--nav-open` is dropped and `inert` removed. Leaving them set is how a page becomes permanently
+  unreachable.
+- **`navOpen` is one idea, in both modes.** The typed wrappers expose "is the nav visible?" and the
+  kit maps it: above the breakpoint a hidden nav is `--nav-collapsed`, below it a visible nav is
+  `--nav-open`. Leave the prop unbound (`undefined` in Vue/React, `null` in Blazor) and the shell
+  starts from the viewport — a column on a wide screen, hidden on a narrow one. That default is why
+  the prop is optional: a caller cannot express it as a single initial value before it knows the
+  viewport.
+- **Binding your own state to the vanilla shell:** it emits a bubbling `fdy-app-nav` CustomEvent
+  (`detail {visible}`) on every real change — including the ones a viewport change causes, since a
+  bound value that stayed `true` while the nav went off-canvas would be describing a panel nobody
+  can see. Drive it with `FreedayAppShell.setVisible(root, visible)` rather than the class names;
+  setting what is already set announces nothing, so a bound host cannot loop on its own echo.
+  `FreedayAppShell.isVisible(root)` reads it back.
+- Skip the enhancer and nothing breaks: the classes still mean what they always meant and the
+  behaviour is yours to write. `FreedayAppShell.init(root)` for markup mounted later — hand it the
+  shell root itself, which is what the Blazor bridge does after its first render.
 
 **The nesting is fixed, not free-form:** `.fdy-app` is a flex **row** of `[__sidebar | __content]`,
 and `__content` is the column holding `__topbar` + `__main` — it exists to give the sticky topbar a

package/README.id.md

@@ -5,7 +5,7 @@
 > **Lebih banyak _free day_ buat dev — UI kit-nya sudah siap pakai.**
 
 [![Live docs](https://img.shields.io/badge/docs-live-2050d8?style=flat-square)](https://cahyo-dimas.github.io/freeday-ui-kit/)
-[![Release](https://img.shields.io/badge/release-v1.52.1-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.52.1)
+[![Release](https://img.shields.io/badge/release-v1.54.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.54.0)
 
 UI KIT yang token-driven & framework-agnostic — satu sumber kebenaran untuk warna, tipografi,
 spasi, dan komponen. Blueprint: `docs/superpowers/specs/2026-07-21-freeday-ui-kit-design.md`.
@@ -178,7 +178,7 @@ const root = useRef<HTMLDivElement>(null);
 useFreeday(root);                     // event fdy-* bubbling → listen di root
 ```
 ```razor
-@* Blazor — RCL Freeday.Blazor (net8.0): komponen native typed <FdyX> dengan @bind, 10/10 parity *@
+@* Blazor — RCL Freeday.Blazor (net8.0): komponen native typed <FdyX> dengan @bind, 11/11 parity *@
 @using Freeday.Blazor
 <FdyCombo TValue="string" @bind-Value="_status" Options="_statusOptions" AriaLabelledby="lbl" />
 <FdyTable TRow="Invoice" Columns="_cols" Rows="_rows" RowKey="@(i => i.Code)" PageSize="10" />

package/README.md

@@ -5,7 +5,7 @@
 > **More free days for devs — the UI kit is ready to use.**
 
 [![Live docs](https://img.shields.io/badge/docs-live-2050d8?style=flat-square)](https://cahyo-dimas.github.io/freeday-ui-kit/)
-[![Release](https://img.shields.io/badge/release-v1.52.1-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.52.1)
+[![Release](https://img.shields.io/badge/release-v1.54.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.54.0)
 
 A token-driven, framework-agnostic UI kit — one source of truth for color, typography,
 spacing, and components. Blueprint: `docs/superpowers/specs/2026-07-21-freeday-ui-kit-design.md`.
@@ -177,7 +177,7 @@ const root = useRef<HTMLDivElement>(null);
 useFreeday(root);                     // fdy-* events bubble → listen at the root
 ```
 ```razor
-@* Blazor — Freeday.Blazor RCL (net8.0): native typed <FdyX> with @bind, 10/10 parity *@
+@* Blazor — Freeday.Blazor RCL (net8.0): native typed <FdyX> with @bind, 11/11 parity *@
 @using Freeday.Blazor
 <FdyCombo TValue="string" @bind-Value="_status" Options="_statusOptions" AriaLabelledby="lbl" />
 <FdyTable TRow="Invoice" Columns="_cols" Rows="_rows" RowKey="@(i => i.Code)" PageSize="10" />

package/USAGE.md

@@ -162,8 +162,12 @@ buttons with exactly one `aria-pressed="true"` **is** the segmented control; don
 
 1. **Shell:** every application starts inside **`.fdy-app`** — a flex row of `__sidebar` (with
    `__brand` + `.fdy-nav`) and `__content` (which holds `__topbar` + `__main`, plus `__navtoggle`
-   and `__backdrop`). The nesting is fixed; don't hand-roll a shell from flexbox — the toggle and
-   backdrop plumbing are already there. Skeleton: `COMPONENTS.md` §App shell; a working screen:
+   and `__backdrop`). The nesting is fixed; don't hand-roll a shell from flexbox. **Take the
+   behaviour too** — `<FdyAppShell>` in Vue/React/Blazor, or `data-fdy-app` plus
+   `freeday-app-shell.js` in plain markup. Until 1.53.0 the kit shipped the classes and left every
+   consumer to write the toggle, Escape, focus trap, focus restore and `inert` themselves, and the
+   two copies in this repo's own docs had already drifted apart; a nav panel you cannot escape from
+   with the keyboard is the usual result. Skeleton: `COMPONENTS.md` §App shell; a working screen:
    `docs/reference-screen.html`.
 2. **Page:** wrap the screen body in **`.fdy-page`** (vertical section rhythm), opening with a
    **`.fdy-page__header`** (eyebrow + `.fdy-title-page` + `.fdy-page__desc` on the left, the one

package/adapters/blazor/FdyAppShell.razor

@@ -0,0 +1,50 @@
+@namespace Freeday.Blazor
+@inherits FreedayComponentBase<FdyAppShell>
+
+@* Blazor wrapper over freeday's .fdy-app shell. Unlike FdyModal and FdyDrawer, which drive a native
+   <dialog> through the bridge, this one hands the whole behaviour to freeday-app-shell.js via
+   `data-fdy-app` and binds to it: the enhancer announces changes as a bubbling `fdy-app-nav` event
+   and accepts them through FreedayAppShell.setVisible. That is the bridge's own doctrine — the
+   enhancers stay the source of truth — and it keeps the focus trap from existing a third time. *@
+<div @ref="Root" class="fdy-app" data-fdy-app>
+    @SkipContent
+
+    <aside class="fdy-app__sidebar">
+        @BrandContent
+        @NavContent
+    </aside>
+
+    <div class="fdy-app__content">
+        <header class="fdy-app__topbar">
+            <button class="fdy-app__navtoggle" type="button" aria-label="@ToggleLabel">
+                @if (ToggleIcon is not null)
+                {
+                    @ToggleIcon
+                }
+                else
+                {
+                    <text>&#9776;</text>
+                }
+            </button>
+
+            <h1 class="fdy-app__title">
+                @if (TitleContent is not null)
+                {
+                    @TitleContent
+                }
+                else
+                {
+                    @Title
+                }
+            </h1>
+
+            @TopbarContent
+        </header>
+
+        <main class="fdy-app__main">
+            @ChildContent
+        </main>
+    </div>
+
+    <div class="fdy-app__backdrop"></div>
+</div>

package/adapters/blazor/FdyAppShell.razor.cs

@@ -0,0 +1,114 @@
+using Microsoft.AspNetCore.Components;
+using Microsoft.JSInterop;
+
+namespace Freeday.Blazor;
+
+public partial class FdyAppShell
+{
+    /// <summary>
+    /// Whether the nav is visible to the reader — one idea, in both modes: above the nav breakpoint
+    /// a hidden nav is a collapsed column, below it a visible nav is an overlay. The kit owns that
+    /// mapping so an app never reasons about the viewport to answer a question about its own UI.
+    /// <para>
+    /// Leave it <c>null</c> (the default) and the shell keeps its own, starting from the viewport:
+    /// a column on a wide screen, hidden on a narrow one. That default is why this is nullable —
+    /// a caller cannot express it as a single initial value before it knows the viewport. Bind it
+    /// (<c>@bind-NavOpen</c>) when the app wants to drive it from a menu or a saved preference.
+    /// </para>
+    /// </summary>
+    [Parameter] public bool? NavOpen { get; set; }
+    [Parameter] public EventCallback<bool?> NavOpenChanged { get; set; }
+
+    /// <summary>Plain-text page title; ignored when <see cref="TitleContent"/> is supplied.</summary>
+    [Parameter] public string Title { get; set; } = string.Empty;
+    [Parameter] public RenderFragment? TitleContent { get; set; }
+
+    /// <summary>The brand block at the top of the sidebar.</summary>
+    [Parameter] public RenderFragment? BrandContent { get; set; }
+
+    /// <summary>The navigation itself — normally a <c>.fdy-nav</c> list.</summary>
+    [Parameter] public RenderFragment? NavContent { get; set; }
+
+    /// <summary>Topbar actions, rendered after the title.</summary>
+    [Parameter] public RenderFragment? TopbarContent { get; set; }
+
+    /// <summary>The skip link, if the app ships one. Rendered as the shell's first child.</summary>
+    [Parameter] public RenderFragment? SkipContent { get; set; }
+
+    /// <summary>The page itself.</summary>
+    [Parameter] public RenderFragment? ChildContent { get; set; }
+
+    /// <summary>Custom glyph for the nav toggle; a hamburger is used when null.</summary>
+    [Parameter] public RenderFragment? ToggleIcon { get; set; }
+
+    [Parameter] public string ToggleLabel { get; set; } = "Toggle navigation";
+
+    private int _navToken;
+    private bool? _lastNavOpen;
+
+    protected override async ValueTask HydrateAsync()
+    {
+        await JS.InvokeVoidAsync("FreedayBlazor.initAll", Root);
+        _navToken = await JS.InvokeAsync<int>(
+            "FreedayBlazor.on", Root, "fdy-app-nav", Self, nameof(OnNavChanged));
+
+        if (NavOpen is bool wanted)
+        {
+            // A caller that bound a value is authoritative — push it down.
+            await JS.InvokeVoidAsync("FreedayAppShell.setVisible", Root, wanted);
+            _lastNavOpen = wanted;
+        }
+        else
+        {
+            // Nobody bound one, so adopt what the shell decided from the viewport. Without this the
+            // bound value would claim `false` next to a nav that is plainly a visible column.
+            bool visible = await JS.InvokeAsync<bool>("FreedayAppShell.isVisible", Root);
+            _lastNavOpen = visible;
+            await SetNavOpenAsync(visible);
+        }
+    }
+
+    protected override async Task OnParametersSetAsync()
+    {
+        // Only reconcile once the shell is wired, and only when the caller actually changed it —
+        // echoing our own event back down would fight the enhancer for the same state.
+        if (_navToken != 0 && NavOpen is bool wanted && wanted != _lastNavOpen)
+        {
+            _lastNavOpen = wanted;
+            await JS.InvokeVoidAsync("FreedayAppShell.setVisible", Root, wanted);
+        }
+    }
+
+    /// <summary>Invoked by the bridge when the shell's nav visibility changes for any reason —
+    /// the toggle, Esc, the backdrop, following a nav link, or the viewport crossing the
+    /// breakpoint.</summary>
+    [JSInvokable]
+    public async Task OnNavChanged(NavDetail detail)
+    {
+        _lastNavOpen = detail.Visible;
+        await SetNavOpenAsync(detail.Visible);
+    }
+
+    private async Task SetNavOpenAsync(bool visible)
+    {
+        if (NavOpenChanged.HasDelegate)
+        {
+            await NavOpenChanged.InvokeAsync(visible);
+        }
+        else
+        {
+            NavOpen = visible;
+            StateHasChanged();
+        }
+    }
+
+    protected override async ValueTask CleanupAsync()
+    {
+        if (_navToken != 0)
+        {
+            await JS.InvokeVoidAsync("FreedayBlazor.off", _navToken);
+        }
+    }
+
+    public sealed record NavDetail(bool Visible);
+}

package/adapters/core/app-shell.d.ts

@@ -0,0 +1,30 @@
+// Types for the framework-agnostic app-shell behaviour (adapters/core/app-shell.js).
+// Shared by FdyAppShell in the Vue, React and Blazor adapters.
+
+/** The parts the shell's behaviour touches. Any of them may be absent from a partial shell. */
+export interface FdyShellParts {
+  sidebar: HTMLElement | null;
+  content: HTMLElement | null;
+  toggle: HTMLElement | null;
+  backdrop: HTMLElement | null;
+}
+
+/**
+ * What the DOM should reflect right now.
+ * `navVisible` is the single idea the app owns — is the nav showing? `overlay` is whether the
+ * viewport is currently below the nav breakpoint, where a visible nav covers the page.
+ */
+export interface FdyShellState {
+  navVisible: boolean;
+  overlay: boolean;
+}
+
+/** The media query the shell switches at, built from tokens/breakpoints.mjs (`nav`). */
+export declare const NAV_QUERY: string;
+
+export declare function shellParts(root: HTMLElement): FdyShellParts;
+export declare function focusablesIn(el: HTMLElement): HTMLElement[];
+export declare function applyShellState(root: HTMLElement, state: FdyShellState): void;
+export declare function focusPanel(root: HTMLElement): Element | null;
+export declare function restoreFocus(root: HTMLElement, previous: Element | null): void;
+export declare function trapTab(root: HTMLElement, event: KeyboardEvent): boolean;

package/adapters/core/app-shell.js

@@ -0,0 +1,134 @@
+// Freeday — framework-agnostic app-shell behaviour (DOM helpers, zero dependencies).
+//
+// The focus trap, `inert` bookkeeping and focus restore shared by FdyAppShell in the Vue, React and
+// Blazor adapters. Kept here — plain ESM with a .d.ts sidecar — for the same reason as
+// table-model.js: three copies of a focus trap is three chances to write it differently, and the
+// one that gets it wrong strands a keyboard user with no way out of a nav panel.
+//
+// The vanilla enhancer (src/freeday-app-shell.js) deliberately does NOT import this: dist/freeday.js
+// is a plain IIFE concatenation with no module system. That leaves exactly two implementations, and
+// browser/adapter.mjs holds them to the same observable behaviour.
+//
+// State stays with the caller. These functions read and write the DOM and nothing else, so a
+// controlled wrapper can own `navOpen` as a prop and still get the parts that are easy to forget.
+
+import { breakpoints } from '../../tokens/breakpoints.mjs';
+
+/** The media query the shell switches at — the same 721px app-shell.css uses. */
+export const NAV_QUERY = `(min-width: ${breakpoints.nav}px)`;
+
+const FOCUSABLE = 'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]),'
+  + ' textarea:not([disabled]), [tabindex]:not([tabindex="-1"])';
+
+/**
+ * The shell's parts, or nulls. Callers pass the root element they rendered.
+ * @param {HTMLElement} root
+ */
+export function shellParts(root) {
+  return {
+    sidebar: root.querySelector('.fdy-app__sidebar'),
+    content: root.querySelector('.fdy-app__content'),
+    toggle: root.querySelector('.fdy-app__navtoggle'),
+    backdrop: root.querySelector('.fdy-app__backdrop'),
+  };
+}
+
+/**
+ * Focusable descendants, in tab order, that are actually rendered.
+ * getClientRects() rather than offsetParent: an overlay sidebar is position:fixed, and a fixed
+ * element reports no offsetParent at all — filtering on that calls every nav item invisible.
+ * @param {HTMLElement} el
+ * @returns {HTMLElement[]}
+ */
+export function focusablesIn(el) {
+  return Array.prototype.filter.call(el.querySelectorAll(FOCUSABLE), (node) => node.getClientRects().length > 0);
+}
+
+/**
+ * Reconcile the parts of the shell that are not classes: `inert` and `aria-expanded`.
+ *
+ * One rule, both modes — the sidebar is inert whenever the nav is not visible. `width:0` (collapsed)
+ * and `translateX(-100%)` (off-canvas) hide a panel from the eye and neither hides it from the
+ * keyboard, so without this a nav nobody can see still swallows Tab on the way into the page.
+ * The content is inert only while the nav is an open overlay.
+ *
+ * @param {HTMLElement} root
+ * @param {{navVisible: boolean, overlay: boolean}} state
+ */
+export function applyShellState(root, state) {
+  const { sidebar, content, toggle } = shellParts(root);
+  if (toggle) toggle.setAttribute('aria-expanded', String(state.navVisible));
+  setInert(sidebar, !state.navVisible);
+  setInert(content, state.overlay && state.navVisible);
+}
+
+/**
+ * Move focus into the panel, and hand back whatever had it — the caller keeps that until close.
+ * @param {HTMLElement} root
+ * @returns {Element|null} the element that was focused before
+ */
+export function focusPanel(root) {
+  const previous = document.activeElement;
+  const { sidebar } = shellParts(root);
+  if (sidebar === null) return previous;
+  const first = focusablesIn(sidebar)[0];
+  if (first !== undefined) {
+    first.focus();
+  } else {
+    sidebar.setAttribute('tabindex', '-1');
+    sidebar.focus();
+  }
+  return previous;
+}
+
+/**
+ * Put focus back where it came from. Anything gone, detached, or the body itself falls back to the
+ * toggle: document.body is where a keyboard user gets stranded with nothing to press.
+ * @param {HTMLElement} root
+ * @param {Element|null} previous
+ */
+export function restoreFocus(root, previous) {
+  const { toggle } = shellParts(root);
+  const usable = previous !== null && previous !== document.body && document.contains(previous)
+    && typeof previous.focus === 'function';
+  const target = usable ? previous : toggle;
+  if (target !== null && typeof target.focus === 'function') target.focus();
+}
+
+/**
+ * Cycle Tab inside the panel. Call from a keydown handler while the overlay is open.
+ * `inert` on the content stops Tab reaching the page; without this the focus would still walk out
+ * of the document into the browser's own chrome.
+ * @param {HTMLElement} root
+ * @param {KeyboardEvent} event
+ * @returns {boolean} true when focus was moved
+ */
+export function trapTab(root, event) {
+  if (event.key !== 'Tab') return false;
+  const { sidebar } = shellParts(root);
+  if (sidebar === null) return false;
+  const items = focusablesIn(sidebar);
+  if (items.length === 0) {
+    event.preventDefault();
+    return false;
+  }
+  const first = items[0];
+  const last = items[items.length - 1];
+  if (event.shiftKey && document.activeElement === first) {
+    event.preventDefault();
+    last.focus();
+    return true;
+  }
+  if (!event.shiftKey && document.activeElement === last) {
+    event.preventDefault();
+    first.focus();
+    return true;
+  }
+  return false;
+}
+
+function setInert(el, on) {
+  if (el === null) return;
+  if (on) el.setAttribute('inert', '');
+  else el.removeAttribute('inert');
+}