@cahyo-dimas/freeday 1.53.0 → 1.54.0

package/CHANGELOG.md

@@ -3,6 +3,48 @@
 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

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.
 
@@ -135,8 +137,21 @@ off-canvas drawer and backdrop are built in.
 - **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.
+  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.53.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.53.0)
+[![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.53.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.53.0)
+[![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');
+}

package/adapters/react/components/FdyAppShell.tsx

@@ -0,0 +1,159 @@
+import type { JSX, ReactNode } from 'react';
+import { useCallback, useEffect, useRef, useState } from 'react';
+import {
+  NAV_QUERY,
+  applyShellState,
+  focusPanel,
+  restoreFocus,
+  trapTab,
+} from '../../core/app-shell.js';
+
+// A React wrapper over freeday's `.fdy-app` shell (src/components/app-shell.css). React port of
+// adapters/vue/components/FdyAppShell.vue, sharing adapters/core/app-shell.js so the two cannot
+// drift into two different focus traps.
+//
+// ONE model: `navOpen` means "the nav is visible to the reader". Above the nav breakpoint a hidden
+// nav is `--nav-collapsed`, below it a visible nav is `--nav-open` — the kit owns that mapping so an
+// app never reasons about the viewport to answer a question about its own UI.
+//
+// Omit `navOpen` and the component keeps its own, defaulting BY VIEWPORT: a column on a wide screen,
+// hidden on a narrow one. That default is why the prop is optional — a parent cannot express it as a
+// single initial value before it knows the viewport.
+
+export interface FdyAppShellProps {
+  navOpen?: boolean;
+  onNavOpenChange?: (open: boolean) => void;
+  title?: ReactNode;
+  toggleLabel?: string;
+  toggleIcon?: ReactNode;
+  skip?: ReactNode;
+  brand?: ReactNode;
+  nav?: ReactNode;
+  topbar?: ReactNode;
+  children?: ReactNode;
+}
+
+export function FdyAppShell(props: FdyAppShellProps): JSX.Element {
+  const rootRef = useRef<HTMLDivElement>(null);
+  const restoreToRef = useRef<Element | null>(null);
+  /* Set while a viewport change is driving the state, so the effect below reconciles `inert` and
+     the classes but leaves FOCUS alone: a resize is not a reader asking to go somewhere. */
+  const fromResizeRef = useRef<boolean>(false);
+  const [overlay, setOverlay] = useState<boolean>(false);
+  const [uncontrolled, setUncontrolled] = useState<boolean>(true);
+
+  const controlled: boolean = props.navOpen !== undefined;
+  const navVisible: boolean = controlled ? props.navOpen === true : uncontrolled;
+
+  const setVisible = useCallback((next: boolean): void => {
+    if (!controlled) setUncontrolled(next);
+    if (props.onNavOpenChange !== undefined) props.onNavOpenChange(next);
+  }, [controlled, props.onNavOpenChange]);
+
+  /* The media listener reads these through refs and subscribes ONCE. Depending on navVisible would
+     resubscribe on every toggle and re-run the handler, and its "narrowing with the nav visible
+     hides it" rule would then fire on an ordinary open — closing the panel in the same tick the
+     reader opened it. */
+  const navVisibleRef = useRef<boolean>(navVisible);
+  navVisibleRef.current = navVisible;
+  const setVisibleRef = useRef<(next: boolean) => void>(setVisible);
+  setVisibleRef.current = setVisible;
+
+  // The media query owns `overlay`, and the two directions are not symmetrical. Narrowing with the
+  // nav visible would drop an overlay panel over a page nobody asked to leave, so it is hidden;
+  // widening is harmless, since a visible nav simply becomes the column again.
+  useEffect((): (() => void) => {
+    const media: MediaQueryList = window.matchMedia(NAV_QUERY);
+    const onChange = (): void => {
+      const nowOverlay: boolean = !media.matches;
+      setOverlay((was: boolean): boolean => {
+        if (was !== nowOverlay) fromResizeRef.current = true;
+        return nowOverlay;
+      });
+      if (nowOverlay && navVisibleRef.current) setVisibleRef.current(false);
+    };
+    // Mount: adopt the viewport without the hide-on-narrow side effect — nothing is open yet.
+    setOverlay(!media.matches);
+    if (!controlled) setUncontrolled(media.matches);
+    media.addEventListener('change', onChange);
+    return (): void => media.removeEventListener('change', onChange);
+  }, [controlled]);
+
+  // Focus moves only after the class change has been painted, or the panel is still off-canvas and
+  // the browser refuses to focus what it cannot lay out.
+  useEffect((): void => {
+    const el: HTMLDivElement | null = rootRef.current;
+    if (el === null) return;
+    applyShellState(el, { navVisible, overlay });
+    if (fromResizeRef.current) {
+      fromResizeRef.current = false;
+      return;
+    }
+    if (!overlay) return;
+    if (navVisible) restoreToRef.current = focusPanel(el);
+    else restoreFocus(el, restoreToRef.current);
+  }, [navVisible, overlay]);
+
+  useEffect((): (() => void) => {
+    const onKeydown = (e: KeyboardEvent): void => {
+      const el: HTMLDivElement | null = rootRef.current;
+      if (el === null || !overlay || !navVisible) return;
+      if (e.key === 'Escape') {
+        e.preventDefault();
+        setVisible(false);
+        return;
+      }
+      trapTab(el, e);
+    };
+    document.addEventListener('keydown', onKeydown);
+    return (): void => document.removeEventListener('keydown', onKeydown);
+  }, [overlay, navVisible, setVisible]);
+
+  const shellClass: string = overlay
+    ? (navVisible ? 'fdy-app fdy-app--nav-open' : 'fdy-app')
+    : (navVisible ? 'fdy-app' : 'fdy-app fdy-app--nav-collapsed');
+
+  return (
+    <div ref={rootRef} className={shellClass}>
+      {props.skip}
+
+      <aside
+        className="fdy-app__sidebar"
+        onClick={(e): void => {
+          // Following a link in an overlay nav means "take me there" — the panel must not stay over
+          // the page it was just asked for. On a wide viewport the nav is a column: nothing to close.
+          if (!overlay || !navVisible) return;
+          const target: HTMLElement | null = e.target as HTMLElement | null;
+          if (target !== null && target.closest('.fdy-nav__item') !== null) setVisible(false);
+        }}
+      >
+        {props.brand}
+        {props.nav}
+      </aside>
+
+      <div className="fdy-app__content">
+        <header className="fdy-app__topbar">
+          <button
+            className="fdy-app__navtoggle"
+            type="button"
+            aria-label={props.toggleLabel ?? 'Toggle navigation'}
+            onClick={(): void => setVisible(!navVisible)}
+          >{props.toggleIcon ?? '☰'}</button>
+
+          <h1 className="fdy-app__title">{props.title}</h1>
+
+          {props.topbar}
+        </header>
+
+        <main className="fdy-app__main">{props.children}</main>
+      </div>
+
+      <div
+        className="fdy-app__backdrop"
+        onClick={(): void => {
+          if (overlay && navVisible) setVisible(false);
+        }}
+      />
+    </div>
+  );
+}

package/adapters/react/index.d.ts

@@ -41,6 +41,7 @@ export { FdyTable, type FdyTableProps } from './components/FdyTable';
 export { FdyTableFooter, type FdyTableFooterProps } from './components/FdyTableFooter';
 export { FdyModal, type FdyModalProps } from './components/FdyModal';
 export { FdyDrawer, type FdyDrawerProps } from './components/FdyDrawer';
+export { FdyAppShell, type FdyAppShellProps } from './components/FdyAppShell';
 
 /** Controlled data-table types (shared, framework-agnostic core). */
 export type {

package/adapters/react/index.js

@@ -11,3 +11,4 @@ export { FdyTable } from './components/FdyTable.tsx';
 export { FdyTableFooter } from './components/FdyTableFooter.tsx';
 export { FdyModal } from './components/FdyModal.tsx';
 export { FdyDrawer } from './components/FdyDrawer.tsx';
+export { FdyAppShell } from './components/FdyAppShell.tsx';

package/adapters/vue/components/FdyAppShell.vue

@@ -0,0 +1,160 @@
+<script setup lang="ts">
+import { computed, onBeforeUnmount, onMounted, ref, watch, type ComputedRef, type Ref } from 'vue';
+import {
+  NAV_QUERY,
+  applyShellState,
+  focusPanel,
+  restoreFocus,
+  trapTab,
+} from '../../core/app-shell.js';
+
+// A Vue wrapper over freeday's `.fdy-app` shell (src/components/app-shell.css) that ships the
+// behaviour the CSS cannot: Escape, backdrop, focus into the panel and back, `inert`, and a Tab
+// trap. The DOM work lives in adapters/core/app-shell.js so this component, its React twin and the
+// Blazor bridge cannot drift into three different focus traps.
+//
+// ONE model: `navOpen` means "the nav is visible to the reader". The two state classes are the
+// kit's business — above the nav breakpoint a hidden nav is `--nav-collapsed`, below it a visible
+// nav is `--nav-open` — so an app never reasons about the viewport to answer a question about its
+// own UI.
+//
+// Leave `navOpen` unbound and the component keeps its own: visible on a wide viewport, hidden on a
+// narrow one, which is the right default and one an app cannot express in a single initial value.
+// Bind it (`v-model:navOpen`) when the app wants to drive it — a menu item, a persisted preference.
+
+const props = withDefaults(defineProps<{
+  navOpen?: boolean;
+  title?: string;
+  toggleLabel?: string;
+}>(), { navOpen: undefined, title: '', toggleLabel: 'Toggle navigation' });
+
+const emit = defineEmits<{
+  'update:navOpen': [boolean];
+}>();
+
+const root: Ref<HTMLElement | null> = ref(null);
+const overlay: Ref<boolean> = ref(false);
+const uncontrolled: Ref<boolean> = ref(true);
+const restoreTo: Ref<Element | null> = ref(null);
+let media: MediaQueryList | null = null;
+/* Set while a viewport change is driving the state, so the watcher below reconciles `inert` and the
+   classes but leaves FOCUS alone: a resize is not a reader asking to go somewhere. */
+let fromResize: boolean = false;
+
+const navVisible: ComputedRef<boolean> = computed((): boolean =>
+  props.navOpen === undefined ? uncontrolled.value : props.navOpen,
+);
+
+const shellClass: ComputedRef<string> = computed((): string => {
+  if (overlay.value) return navVisible.value ? 'fdy-app fdy-app--nav-open' : 'fdy-app';
+  return navVisible.value ? 'fdy-app' : 'fdy-app fdy-app--nav-collapsed';
+});
+
+function setVisible(next: boolean): void {
+  uncontrolled.value = next;
+  emit('update:navOpen', next);
+}
+
+/* Focus is moved AFTER the class change has been rendered, or the panel is still off-canvas and
+   the browser refuses to focus what it cannot lay out. */
+watch([navVisible, overlay], ([visible, isOverlay]: [boolean, boolean]): void => {
+  const el: HTMLElement | null = root.value;
+  if (el === null) return;
+  applyShellState(el, { navVisible: visible, overlay: isOverlay });
+  if (fromResize) {
+    fromResize = false;
+    return;
+  }
+  if (!isOverlay) return;
+  if (visible) restoreTo.value = focusPanel(el);
+  else restoreFocus(el, restoreTo.value);
+}, { flush: 'post' });
+
+function onToggle(): void {
+  setVisible(!navVisible.value);
+}
+
+function onBackdrop(): void {
+  if (overlay.value && navVisible.value) setVisible(false);
+}
+
+/* Following a link in an overlay nav means "take me there" — the panel must not stay over the page
+   it was just asked for. On a wide viewport the nav is a column and clicking it changes nothing. */
+function onSidebarClick(e: MouseEvent): void {
+  if (!overlay.value || !navVisible.value) return;
+  const target: HTMLElement | null = e.target as HTMLElement | null;
+  if (target !== null && target.closest('.fdy-nav__item') !== null) setVisible(false);
+}
+
+function onKeydown(e: KeyboardEvent): void {
+  const el: HTMLElement | null = root.value;
+  if (el === null || !overlay.value || !navVisible.value) return;
+  if (e.key === 'Escape') {
+    e.preventDefault();
+    setVisible(false);
+    return;
+  }
+  trapTab(el, e);
+}
+
+/* Both directions matter, and they are not symmetrical.
+   Narrowing with the nav visible would drop an overlay panel over a page nobody asked to leave, so
+   the nav is hidden. Widening is harmless — a visible nav simply becomes the column again — and the
+   watcher clears the `inert` the overlay had put on the content. */
+function onMediaChange(): void {
+  const nowOverlay: boolean = media !== null && !media.matches;
+  if (nowOverlay === overlay.value) return;
+  fromResize = true;
+  overlay.value = nowOverlay;
+  if (nowOverlay && navVisible.value) setVisible(false);
+}
+
+onMounted((): void => {
+  media = window.matchMedia(NAV_QUERY);
+  overlay.value = !media.matches;
+  uncontrolled.value = media.matches;
+  media.addEventListener('change', onMediaChange);
+  document.addEventListener('keydown', onKeydown);
+  const el: HTMLElement | null = root.value;
+  if (el !== null) applyShellState(el, { navVisible: navVisible.value, overlay: overlay.value });
+});
+
+onBeforeUnmount((): void => {
+  if (media !== null) media.removeEventListener('change', onMediaChange);
+  document.removeEventListener('keydown', onKeydown);
+});
+</script>
+
+<template>
+  <div ref="root" :class="shellClass">
+    <slot name="skip" />
+
+    <aside class="fdy-app__sidebar" @click="onSidebarClick">
+      <slot name="brand" />
+      <slot name="nav" />
+    </aside>
+
+    <div class="fdy-app__content">
+      <header class="fdy-app__topbar">
+        <button
+          class="fdy-app__navtoggle"
+          type="button"
+          :aria-label="toggleLabel"
+          @click="onToggle"
+        ><slot name="toggle-icon">&#9776;</slot></button>
+
+        <h1 class="fdy-app__title">
+          <slot name="title">{{ title }}</slot>
+        </h1>
+
+        <slot name="topbar" />
+      </header>
+
+      <main class="fdy-app__main">
+        <slot />
+      </main>
+    </div>
+
+    <div class="fdy-app__backdrop" @click="onBackdrop" />
+  </div>
+</template>

package/adapters/vue/index.d.ts

@@ -40,6 +40,7 @@ export { default as FdyTable } from './components/FdyTable.vue';
 export { default as FdyTableFooter } from './components/FdyTableFooter.vue';
 export { default as FdyModal } from './components/FdyModal.vue';
 export { default as FdyDrawer } from './components/FdyDrawer.vue';
+export { default as FdyAppShell } from './components/FdyAppShell.vue';
 
 /** Controlled data-table types (shared, framework-agnostic core). */
 export type {

package/adapters/vue/index.js

@@ -11,3 +11,4 @@ export { default as FdyTable } from './components/FdyTable.vue';
 export { default as FdyTableFooter } from './components/FdyTableFooter.vue';
 export { default as FdyModal } from './components/FdyModal.vue';
 export { default as FdyDrawer } from './components/FdyDrawer.vue';
+export { default as FdyAppShell } from './components/FdyAppShell.vue';

package/dist/freeday-app-shell.js

@@ -14,7 +14,12 @@
  *   - `__content` is inert only while the nav is an OPEN OVERLAY, so Tab cannot wander behind the
  *     backdrop.
  *
- * Emits nothing; the classes are the state. FreedayAppShell.init(root) for late-mounted markup.
+ * Emits a bubbling `fdy-app-nav` CustomEvent (detail {visible}) whenever the nav's visibility
+ * changes, and takes `FreedayAppShell.setVisible(root, visible)` from outside. Those two exist for
+ * the same reason the other enhancers have them: a host that keeps its own state — the Blazor
+ * wrapper binding @bind-NavOpen, an app persisting the collapsed preference — has to be able to
+ * hear the change and to drive it, without owning the behaviour twice.
+ * FreedayAppShell.init(root) for late-mounted markup.
  */
 (function () {
   'use strict';
@@ -51,6 +56,7 @@
 
     var mqWide = window.matchMedia(WIDE);
     var restoreTo = null;
+    var lastVisible = null;
 
     function isOverlayOpen() { return app.classList.contains('fdy-app--nav-open'); }
     function isCollapsed() { return app.classList.contains('fdy-app--nav-collapsed'); }
@@ -63,6 +69,12 @@
       toggle.setAttribute('aria-expanded', String(visible));
       setInert(sidebar, !visible);
       setInert(content, !mqWide.matches && visible);
+      /* Announce only real changes. The first sync() runs at init to describe the state the markup
+         arrived in, which is not something a host asked for and must not look like one. */
+      if (lastVisible !== null && visible !== lastVisible) {
+        app.dispatchEvent(new CustomEvent('fdy-app-nav', { bubbles: true, detail: { visible: visible } }));
+      }
+      lastVisible = visible;
     }
 
     function open() {
@@ -147,6 +159,23 @@
     });
 
     sync();
+
+    /* The same handle the other enhancers expose (`_fdyCombo` and friends): a host that binds its
+       own state needs to drive this without reaching for the class names the kit reserves. */
+    app._fdyAppShell = {
+      isVisible: navVisible,
+      setVisible: function (visible) {
+        if (visible === navVisible()) return;
+        if (mqWide.matches) {
+          app.classList.toggle('fdy-app--nav-collapsed', !visible);
+          sync();
+        } else if (visible) {
+          open();
+        } else {
+          close();
+        }
+      },
+    };
   }
 
   function initShells(context) {
@@ -163,5 +192,16 @@
     initShells();
   }
 
-  window.FreedayAppShell = { init: initShells, initAll: initShells };
+  window.FreedayAppShell = {
+    init: initShells,
+    initAll: initShells,
+    /* Both take the shell root. A missing or un-initialised root is a no-op rather than a throw:
+       a host may race the enhancer on first render, and a crash there is worse than a late sync. */
+    setVisible: function (root, visible) {
+      if (root && root._fdyAppShell) root._fdyAppShell.setVisible(visible === true);
+    },
+    isVisible: function (root) {
+      return !!(root && root._fdyAppShell && root._fdyAppShell.isVisible());
+    },
+  };
 })();

package/dist/freeday.js

@@ -16,7 +16,12 @@
  *   - `__content` is inert only while the nav is an OPEN OVERLAY, so Tab cannot wander behind the
  *     backdrop.
  *
- * Emits nothing; the classes are the state. FreedayAppShell.init(root) for late-mounted markup.
+ * Emits a bubbling `fdy-app-nav` CustomEvent (detail {visible}) whenever the nav's visibility
+ * changes, and takes `FreedayAppShell.setVisible(root, visible)` from outside. Those two exist for
+ * the same reason the other enhancers have them: a host that keeps its own state — the Blazor
+ * wrapper binding @bind-NavOpen, an app persisting the collapsed preference — has to be able to
+ * hear the change and to drive it, without owning the behaviour twice.
+ * FreedayAppShell.init(root) for late-mounted markup.
  */
 (function () {
   'use strict';
@@ -53,6 +58,7 @@
 
     var mqWide = window.matchMedia(WIDE);
     var restoreTo = null;
+    var lastVisible = null;
 
     function isOverlayOpen() { return app.classList.contains('fdy-app--nav-open'); }
     function isCollapsed() { return app.classList.contains('fdy-app--nav-collapsed'); }
@@ -65,6 +71,12 @@
       toggle.setAttribute('aria-expanded', String(visible));
       setInert(sidebar, !visible);
       setInert(content, !mqWide.matches && visible);
+      /* Announce only real changes. The first sync() runs at init to describe the state the markup
+         arrived in, which is not something a host asked for and must not look like one. */
+      if (lastVisible !== null && visible !== lastVisible) {
+        app.dispatchEvent(new CustomEvent('fdy-app-nav', { bubbles: true, detail: { visible: visible } }));
+      }
+      lastVisible = visible;
     }
 
     function open() {
@@ -149,6 +161,23 @@
     });
 
     sync();
+
+    /* The same handle the other enhancers expose (`_fdyCombo` and friends): a host that binds its
+       own state needs to drive this without reaching for the class names the kit reserves. */
+    app._fdyAppShell = {
+      isVisible: navVisible,
+      setVisible: function (visible) {
+        if (visible === navVisible()) return;
+        if (mqWide.matches) {
+          app.classList.toggle('fdy-app--nav-collapsed', !visible);
+          sync();
+        } else if (visible) {
+          open();
+        } else {
+          close();
+        }
+      },
+    };
   }
 
   function initShells(context) {
@@ -165,7 +194,18 @@
     initShells();
   }
 
-  window.FreedayAppShell = { init: initShells, initAll: initShells };
+  window.FreedayAppShell = {
+    init: initShells,
+    initAll: initShells,
+    /* Both take the shell root. A missing or un-initialised root is a no-op rather than a throw:
+       a host may race the enhancer on first render, and a crash there is worse than a late sync. */
+    setVisible: function (root, visible) {
+      if (root && root._fdyAppShell) root._fdyAppShell.setVisible(visible === true);
+    },
+    isVisible: function (root) {
+      return !!(root && root._fdyAppShell && root._fdyAppShell.isVisible());
+    },
+  };
 })();
 
 /* Freeday — autocomplete enhancer (optional, zero-dependency).

package/docs/agent-onboarding.md

@@ -46,7 +46,7 @@ upload, tree, tabs, menu, rating, slider, form validation, carousel, timepicker)
 wrapper — use the raw markup and hydrate it:
 
 - **Vue / React** — `useFreeday(rootRef)` from the same import path, plus `import '@cahyo-dimas/freeday'`
-  once at app entry to register the enhancers. (The ten typed components do **not** need this: they
+  once at app entry to register the enhancers. (The eleven typed components do **not** need this: they
   are native Vue/React implementations of the same markup, not wrappers over the enhancer.)
 - **Blazor** — `FreedayBlazor.initAll` interop. (Here the typed components *are* thin wrappers over
   the enhancers, so the enhancer script is always required.)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cahyo-dimas/freeday",
-  "version": "1.53.0",
+  "version": "1.54.0",
   "description": "Freeday — token-driven, framework-agnostic UI KIT (design source-of-truth).",
   "type": "module",
   "license": "MIT",
@@ -92,7 +92,7 @@
   "scripts": {
     "build": "node tokens/build.mjs",
     "test": "node --test",
-    "test:browser": "node --test browser/vanilla.mjs browser/adapter.mjs browser/layout.mjs browser/theme.mjs browser/state.mjs browser/root-init.mjs browser/upload-states.mjs browser/number.mjs browser/card-stretch.mjs browser/text-override.mjs browser/control-heights.mjs browser/cfl-multi.mjs browser/crowding.mjs browser/over-dialog.mjs browser/chart-scale.mjs browser/overlay-stack.mjs browser/chart-a11y.mjs browser/app-shell.mjs",
+    "test:browser": "node --test --test-concurrency=3 browser/vanilla.mjs browser/adapter.mjs browser/layout.mjs browser/theme.mjs browser/state.mjs browser/root-init.mjs browser/upload-states.mjs browser/number.mjs browser/card-stretch.mjs browser/text-override.mjs browser/control-heights.mjs browser/cfl-multi.mjs browser/crowding.mjs browser/over-dialog.mjs browser/chart-scale.mjs browser/overlay-stack.mjs browser/chart-a11y.mjs browser/app-shell.mjs",
     "prepack": "node tokens/build.mjs",
     "version": "node tokens/build.mjs && git add dist",
     "typecheck:react": "tsc -p adapters/react/tsconfig.json --noEmit"