@cahyo-dimas/freeday 1.52.0 → 1.53.0

package/CHANGELOG.md

@@ -3,6 +3,96 @@
 Semua perubahan penting dicatat di sini. Format longgar mengikuti
 [Keep a Changelog](https://keepachangelog.com/); tiap versi = git tag.
 
+## [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
+  no transient activation — "from a timer, or after an `await` that outlived the click" — has its
+  close watcher grouped with the dialog below, so one Escape closes both. A consumer audited three
+  call sites of exactly that shape and could not reproduce it. They were right, and the reason is
+  that the line is **sticky** activation, not transient: grouping needs a page that has received no
+  user input *at all*. Six seconds after a single click — transient activation long expired,
+  `navigator.userActivation.isActive === false` — two stacked overlays are still independent. So the
+  grouping is reachable in a test harness and nowhere else, which is exactly where the kit met it.
+- **What the advice was protecting was real, but it is a different failure.** Open either overlay
+  from script and the second one's `cancel` event arrives **non-cancelable**: Escape still closes
+  only the topmost, but `preventDefault()` on it is ignored, so an "unsaved changes, stay open" guard
+  on that dialog silently stops working. Only when both overlays are opened by a real gesture is that
+  veto available. The Modal entry now says this instead.
+- The note also proposed documenting that the typed wrappers' `@cancel.prevent` makes them immune to
+  the grouping. **Measured, they are not** — in a page with no activation the `cancel` event is not
+  cancelable at all, so preventing it does nothing and both dialogs close regardless. That claim is
+  not in the docs, and this is why.
+### Added — guards
+- `browser/overlay-stack.mjs` gains the whole matrix as one assertion — four ways to open two
+  overlays × what one Escape leaves open × whether it could be refused — so a row changing is
+  reported as news about the browser rather than a regression in the kit. Verified identical on
+  Chromium 133 (the suite's engine) and Chrome 151.
+- 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

@@ -122,8 +122,21 @@ 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.
+- 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.
 
 **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
@@ -1061,10 +1074,19 @@ that. Escape closes the topmost first, so cancelling returns to the still-open d
 Escape then closes the drawer. Closing them out of order is fine too: closing the drawer while the
 modal is up leaves the modal open, painted and dismissible.
 
-One caveat, and it is the browser's rather than the kit's: **open each overlay from the gesture
-that asked for it.** A `showModal()` that runs with no user activation — from a timer, or after an
-`await` that outlived the click — has its close watcher grouped with the dialog below it, and then
-a single Escape closes both at once instead of the topmost only.
+One caveat, and it is the browser's rather than the kit's: **the second overlay's Escape can only
+be refused if both were opened by a real gesture.** A `showModal()` that runs from script — a timer,
+or after an `await` that outlived the click — still closes only the topmost, but its `cancel` event
+arrives **non-cancelable**, so `preventDefault()` on it is ignored and an "unsaved changes, stay
+open" guard silently stops working. Routing Escape through app state instead, which is what the
+typed wrappers do, is unaffected: the dialog closes and your state follows it.
+
+*Correction to 1.51.1, which said such a dialog has its close watcher grouped with the one below so
+that a single Escape closes both.* That happens only on a page that has received **no user input at
+all** — a test harness, never an app; six seconds after one click the overlays are still
+independent. Open overlays with real clicks in a test, or a stacking assertion fails for a reason
+that is not the kit. Both rules measured on Chromium 133 and 151, and pinned as a matrix in
+`browser/overlay-stack.mjs`.
 
 ## Drawer — `.fdy-drawer`
 > **Typed wrapper: `<FdyDrawer>`** — Vue (`:open` + `@close`) · React (`open` + `onClose`) · Blazor (`@bind-Open`). In those stacks use the wrapper; the markup below is for stacks without an adapter (and is what the wrapper renders).

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.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.52.0)
+[![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)
 
 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`.

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.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.52.0)
+[![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)
 
 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`.

package/dist/freeday-app-shell.js

@@ -0,0 +1,167 @@
+/* Freeday — app shell enhancer (optional, zero-dependency).
+ * Opt in with <div class="fdy-app" data-fdy-app>; the markup is otherwise unchanged.
+ *
+ * The shell has always shipped the state classes and no behaviour, which left every consumer to
+ * assemble the toggle, Escape, focus trap, focus restore and `inert` themselves — and the two
+ * hand-rolled copies in this repo's own docs already disagreed about which of those exist. Below
+ * 721px the sidebar is an OVERLAY (app-shell.css: position:fixed + translateX(-100%)), so it needs
+ * the same treatment a modal drawer gets; at or above 721px it is a column that merely collapses.
+ *
+ * One rule covers both a hidden nav and a hidden page:
+ *   - `__sidebar` is inert whenever the nav is NOT visible. Off-canvas and collapsed panels stay in
+ *     the tab order otherwise — translateX(-100%) and width:0 hide a thing from the eye, not from
+ *     the keyboard, which is how a nav nobody can see still swallows Tab.
+ *   - `__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.
+ */
+(function () {
+  'use strict';
+
+  /* Must match app-shell.css, which switches at (min-width:721px) / (max-width:720px). */
+  var WIDE = '(min-width: 721px)';
+
+  var FOCUSABLE = 'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]),'
+    + ' textarea:not([disabled]), [tabindex]:not([tabindex="-1"])';
+
+  /* getClientRects(), not offsetParent: an overlay sidebar is position:fixed, and a fixed element
+     reports no offsetParent at all — filtering on it would call every nav item invisible. */
+  function focusables(root) {
+    return Array.prototype.filter.call(root.querySelectorAll(FOCUSABLE), function (el) {
+      return el.getClientRects().length > 0;
+    });
+  }
+
+  function setInert(el, on) {
+    if (!el) return;
+    if (on) el.setAttribute('inert', '');
+    else el.removeAttribute('inert');
+  }
+
+  function initShell(app) {
+    if (app.dataset.fdyAppShellReady === '1') return;
+    app.dataset.fdyAppShellReady = '1';
+
+    var toggle = app.querySelector('.fdy-app__navtoggle');
+    var sidebar = app.querySelector('.fdy-app__sidebar');
+    if (!toggle || !sidebar) return;
+    var content = app.querySelector('.fdy-app__content');
+    var backdrop = app.querySelector('.fdy-app__backdrop');
+
+    var mqWide = window.matchMedia(WIDE);
+    var restoreTo = null;
+
+    function isOverlayOpen() { return app.classList.contains('fdy-app--nav-open'); }
+    function isCollapsed() { return app.classList.contains('fdy-app--nav-collapsed'); }
+    function navVisible() { return mqWide.matches ? !isCollapsed() : isOverlayOpen(); }
+
+    /* aria-expanded answers "is the nav showing?" in BOTH modes — the two state classes are the
+       kit's business, not the reader's. */
+    function sync() {
+      var visible = navVisible();
+      toggle.setAttribute('aria-expanded', String(visible));
+      setInert(sidebar, !visible);
+      setInert(content, !mqWide.matches && visible);
+    }
+
+    function open() {
+      if (isOverlayOpen()) return;
+      restoreTo = document.activeElement;
+      app.classList.add('fdy-app--nav-open');
+      sync();
+      var first = focusables(sidebar)[0];
+      if (first) {
+        first.focus();
+      } else {
+        sidebar.setAttribute('tabindex', '-1');
+        sidebar.focus();
+      }
+    }
+
+    /* restoreFocus is false when the viewport closed it rather than the user — a resize must not
+       yank focus out from under whatever the reader was doing. */
+    function close(restoreFocus) {
+      if (!isOverlayOpen()) return;
+      app.classList.remove('fdy-app--nav-open');
+      sync();
+      if (restoreFocus === false) return;
+      /* Back to the control that opened it. document.body is where a keyboard user gets stranded,
+         so anything that is gone, detached or the body itself falls back to the toggle. */
+      var target = (restoreTo && restoreTo !== document.body && document.contains(restoreTo))
+        ? restoreTo : toggle;
+      if (typeof target.focus === 'function') target.focus();
+    }
+
+    toggle.addEventListener('click', function () {
+      if (mqWide.matches) {
+        app.classList.toggle('fdy-app--nav-collapsed');
+        sync();
+      } else if (isOverlayOpen()) {
+        close();
+      } else {
+        open();
+      }
+    });
+
+    if (backdrop) backdrop.addEventListener('click', function () { close(); });
+
+    /* Following a link inside an overlay nav means "take me there" — leaving the panel open over
+       the page you just asked for is the one thing every hand-rolled copy in this repo disagreed on. */
+    sidebar.addEventListener('click', function (e) {
+      if (!isOverlayOpen()) return;
+      if (e.target.closest && e.target.closest('.fdy-nav__item')) close();
+    });
+
+    document.addEventListener('keydown', function (e) {
+      if (!isOverlayOpen()) return;
+      if (e.key === 'Escape') {
+        e.preventDefault();
+        close();
+        return;
+      }
+      if (e.key !== 'Tab') return;
+      /* The trap. `inert` on the content stops Tab reaching the page, but without this the focus
+         would walk out of the document into the browser's own chrome instead of cycling. */
+      var items = focusables(sidebar);
+      if (items.length === 0) {
+        e.preventDefault();
+        return;
+      }
+      var first = items[0], last = items[items.length - 1];
+      if (e.shiftKey && document.activeElement === first) {
+        e.preventDefault();
+        last.focus();
+      } else if (!e.shiftKey && document.activeElement === last) {
+        e.preventDefault();
+        first.focus();
+      }
+    });
+
+    /* Crossing the breakpoint with the overlay open would otherwise leave --nav-open set and the
+       content inert forever: the panel becomes a static column again, and the page it is covering
+       can no longer be clicked or read. */
+    mqWide.addEventListener('change', function () {
+      if (mqWide.matches && isOverlayOpen()) close(false);
+      else sync();
+    });
+
+    sync();
+  }
+
+  function initShells(context) {
+    var ctx = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON
+       the widget. */
+    if (ctx.matches && ctx.matches('[data-fdy-app]')) initShell(ctx);
+    Array.prototype.forEach.call(ctx.querySelectorAll('[data-fdy-app]'), initShell);
+  }
+
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', function () { initShells(); });
+  } else {
+    initShells();
+  }
+
+  window.FreedayAppShell = { init: initShells, initAll: initShells };
+})();

package/dist/freeday.js

@@ -1,5 +1,173 @@
 /* Freeday enhancers — GENERATED by tokens/build.mjs. Do not edit by hand.
  * Concatenation of every src/*.js enhancer (each a self-contained IIFE). */
+/* Freeday — app shell enhancer (optional, zero-dependency).
+ * Opt in with <div class="fdy-app" data-fdy-app>; the markup is otherwise unchanged.
+ *
+ * The shell has always shipped the state classes and no behaviour, which left every consumer to
+ * assemble the toggle, Escape, focus trap, focus restore and `inert` themselves — and the two
+ * hand-rolled copies in this repo's own docs already disagreed about which of those exist. Below
+ * 721px the sidebar is an OVERLAY (app-shell.css: position:fixed + translateX(-100%)), so it needs
+ * the same treatment a modal drawer gets; at or above 721px it is a column that merely collapses.
+ *
+ * One rule covers both a hidden nav and a hidden page:
+ *   - `__sidebar` is inert whenever the nav is NOT visible. Off-canvas and collapsed panels stay in
+ *     the tab order otherwise — translateX(-100%) and width:0 hide a thing from the eye, not from
+ *     the keyboard, which is how a nav nobody can see still swallows Tab.
+ *   - `__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.
+ */
+(function () {
+  'use strict';
+
+  /* Must match app-shell.css, which switches at (min-width:721px) / (max-width:720px). */
+  var WIDE = '(min-width: 721px)';
+
+  var FOCUSABLE = 'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]),'
+    + ' textarea:not([disabled]), [tabindex]:not([tabindex="-1"])';
+
+  /* getClientRects(), not offsetParent: an overlay sidebar is position:fixed, and a fixed element
+     reports no offsetParent at all — filtering on it would call every nav item invisible. */
+  function focusables(root) {
+    return Array.prototype.filter.call(root.querySelectorAll(FOCUSABLE), function (el) {
+      return el.getClientRects().length > 0;
+    });
+  }
+
+  function setInert(el, on) {
+    if (!el) return;
+    if (on) el.setAttribute('inert', '');
+    else el.removeAttribute('inert');
+  }
+
+  function initShell(app) {
+    if (app.dataset.fdyAppShellReady === '1') return;
+    app.dataset.fdyAppShellReady = '1';
+
+    var toggle = app.querySelector('.fdy-app__navtoggle');
+    var sidebar = app.querySelector('.fdy-app__sidebar');
+    if (!toggle || !sidebar) return;
+    var content = app.querySelector('.fdy-app__content');
+    var backdrop = app.querySelector('.fdy-app__backdrop');
+
+    var mqWide = window.matchMedia(WIDE);
+    var restoreTo = null;
+
+    function isOverlayOpen() { return app.classList.contains('fdy-app--nav-open'); }
+    function isCollapsed() { return app.classList.contains('fdy-app--nav-collapsed'); }
+    function navVisible() { return mqWide.matches ? !isCollapsed() : isOverlayOpen(); }
+
+    /* aria-expanded answers "is the nav showing?" in BOTH modes — the two state classes are the
+       kit's business, not the reader's. */
+    function sync() {
+      var visible = navVisible();
+      toggle.setAttribute('aria-expanded', String(visible));
+      setInert(sidebar, !visible);
+      setInert(content, !mqWide.matches && visible);
+    }
+
+    function open() {
+      if (isOverlayOpen()) return;
+      restoreTo = document.activeElement;
+      app.classList.add('fdy-app--nav-open');
+      sync();
+      var first = focusables(sidebar)[0];
+      if (first) {
+        first.focus();
+      } else {
+        sidebar.setAttribute('tabindex', '-1');
+        sidebar.focus();
+      }
+    }
+
+    /* restoreFocus is false when the viewport closed it rather than the user — a resize must not
+       yank focus out from under whatever the reader was doing. */
+    function close(restoreFocus) {
+      if (!isOverlayOpen()) return;
+      app.classList.remove('fdy-app--nav-open');
+      sync();
+      if (restoreFocus === false) return;
+      /* Back to the control that opened it. document.body is where a keyboard user gets stranded,
+         so anything that is gone, detached or the body itself falls back to the toggle. */
+      var target = (restoreTo && restoreTo !== document.body && document.contains(restoreTo))
+        ? restoreTo : toggle;
+      if (typeof target.focus === 'function') target.focus();
+    }
+
+    toggle.addEventListener('click', function () {
+      if (mqWide.matches) {
+        app.classList.toggle('fdy-app--nav-collapsed');
+        sync();
+      } else if (isOverlayOpen()) {
+        close();
+      } else {
+        open();
+      }
+    });
+
+    if (backdrop) backdrop.addEventListener('click', function () { close(); });
+
+    /* Following a link inside an overlay nav means "take me there" — leaving the panel open over
+       the page you just asked for is the one thing every hand-rolled copy in this repo disagreed on. */
+    sidebar.addEventListener('click', function (e) {
+      if (!isOverlayOpen()) return;
+      if (e.target.closest && e.target.closest('.fdy-nav__item')) close();
+    });
+
+    document.addEventListener('keydown', function (e) {
+      if (!isOverlayOpen()) return;
+      if (e.key === 'Escape') {
+        e.preventDefault();
+        close();
+        return;
+      }
+      if (e.key !== 'Tab') return;
+      /* The trap. `inert` on the content stops Tab reaching the page, but without this the focus
+         would walk out of the document into the browser's own chrome instead of cycling. */
+      var items = focusables(sidebar);
+      if (items.length === 0) {
+        e.preventDefault();
+        return;
+      }
+      var first = items[0], last = items[items.length - 1];
+      if (e.shiftKey && document.activeElement === first) {
+        e.preventDefault();
+        last.focus();
+      } else if (!e.shiftKey && document.activeElement === last) {
+        e.preventDefault();
+        first.focus();
+      }
+    });
+
+    /* Crossing the breakpoint with the overlay open would otherwise leave --nav-open set and the
+       content inert forever: the panel becomes a static column again, and the page it is covering
+       can no longer be clicked or read. */
+    mqWide.addEventListener('change', function () {
+      if (mqWide.matches && isOverlayOpen()) close(false);
+      else sync();
+    });
+
+    sync();
+  }
+
+  function initShells(context) {
+    var ctx = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON
+       the widget. */
+    if (ctx.matches && ctx.matches('[data-fdy-app]')) initShell(ctx);
+    Array.prototype.forEach.call(ctx.querySelectorAll('[data-fdy-app]'), initShell);
+  }
+
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', function () { initShells(); });
+  } else {
+    initShells();
+  }
+
+  window.FreedayAppShell = { init: initShells, initAll: initShells };
+})();
+
 /* Freeday — autocomplete enhancer (optional, zero-dependency).
  * Editable combobox (WAI-ARIA APG): a text input filters a role="listbox" of role="option"
  * items as you type; select fills the input. Auto-inits [data-fdy-autocomplete]. Options are

package/docs/reference-screen.html

@@ -33,7 +33,7 @@
      Doctrine behind the choices: USAGE.md.
      ══════════════════════════════════════════════════════════════════════════════════════════ -->
 
-<div class="fdy-app" id="app">
+<div class="fdy-app" id="app" data-fdy-app>
   <a class="fdy-skip" href="#main">Skip to main content</a>
 
   <!-- Sidebar comes FIRST: .fdy-app is a flex row of [sidebar | content]. The brand lives in the
@@ -407,6 +407,7 @@
 </dialog>
 
 <!-- Enhancers: only the ones this screen actually uses. Zero dependencies, load order free. -->
+<script src="../dist/freeday-app-shell.js"></script>
 <script src="../dist/freeday-popover.js"></script>
 <script src="../dist/freeday-select.js"></script>
 <script src="../dist/freeday-datepicker.js"></script>
@@ -417,21 +418,9 @@
 <script src="../dist/freeday-toast.js"></script>
 
 <script>
-  // The shell's only wiring: the nav toggle. Two state classes, no library.
-  // Above 720px the sidebar collapses to zero width (--nav-collapsed); at or below it slides in as
-  // an off-canvas drawer (--nav-open). 720px is where app-shell.css switches — keep them in step.
-  const app = document.getElementById('app');
-  const toggle = app.querySelector('.fdy-app__navtoggle');
-  const wide = () => window.matchMedia('(min-width: 721px)').matches;
-  toggle.addEventListener('click', () => {
-    const cls = wide() ? 'fdy-app--nav-collapsed' : 'fdy-app--nav-open';
-    const open = app.classList.toggle(cls);
-    toggle.setAttribute('aria-expanded', String(wide() ? !open : open));
-  });
-  app.querySelector('.fdy-app__backdrop').addEventListener('click', () => {
-    app.classList.remove('fdy-app--nav-open');
-    toggle.setAttribute('aria-expanded', 'false');
-  });
+  // The nav toggle is the kit's now: `data-fdy-app` on the shell is the whole wiring. What used to
+  // live here handled the two state classes and nothing else — no Escape, no focus trap, no inert
+  // background, no focus restore — which is exactly why the behaviour moved into the kit.
 
   // Theme + density live on <html>, set once — never per component.
   const root = document.documentElement;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cahyo-dimas/freeday",
-  "version": "1.52.0",
+  "version": "1.53.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",
+    "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",
     "prepack": "node tokens/build.mjs",
     "version": "node tokens/build.mjs && git add dist",
     "typecheck:react": "tsc -p adapters/react/tsconfig.json --noEmit"