@gemboss/website-ui 0.7.0 → 0.8.0

package/docs/markup-contract.md

@@ -28,7 +28,8 @@ BEM-ish: `.gw-block`, `.gw-block__part`, `.gw-block--variant`.
 
 One script wires every part below: the mega menu, the mobile menu, the theme toggle, reveal, the header's scroll
 state, the current page, the segmented control, the busy button, an article's contents list and the scroll box of its
-prose tables (0.5.0), and the footer's folds (0.7.0). It comes in two entries built from one source
+prose tables (0.5.0), the footer's folds (0.7.0), and the mobile menu's drill-down and the language switcher (0.8.0).
+It comes in two entries built from one source
 (`js/website.mjs`; `scripts/build.mjs` writes `js/website.js` from it and `--check` fails when they differ):
 
 | entry | file | how it starts |
@@ -43,9 +44,9 @@ prose tables (0.5.0), and the footer's folds (0.7.0). It comes in two entries bu
   to the page (Escape, the outside click, the busy-button guard, the system theme, the scroll) are installed once.
 - **`destroy(root = document)`** takes back what `init` wired under `root`: its listeners and its marks. An open
   mega menu or mobile menu is closed first, so an unmounted menu cannot leave the page locked.
-- **`version`**: `'0.7.0'`. The classic script exposes the three as `window.gwWebsite`.
-- **`data-gw-ready`**: on each wired element, the parts wired on it (`mega`, `menu`, `theme`, `reveal`, `header`,
-  `segmented`, `toc`, `table`, `fold`). It is a mark for people and tests, not a switch: markup copied from a live page, attribute and all,
+- **`version`**: `'0.8.0'`. The classic script exposes the three as `window.gwWebsite`.
+- **`data-gw-ready`**: on each wired element, the parts wired on it (`mega`, `menu`, `lang`, `theme`, `reveal`,
+  `header`, `segmented`, `toc`, `table`, `fold`). A drill-down menu is wired with its toggle (`menu`). It is a mark for people and tests, not a switch: markup copied from a live page, attribute and all,
   is still wired.
 - **One copy per page.** The first copy that runs owns the page (`window.gwWebsite`); another one (the classic
   script next to a bundle, two bundles) hands its calls to it, so nothing is wired twice.
@@ -94,11 +95,13 @@ The script tells the page's own code what changed. Every event is a `CustomEvent
 | `gw:mega` | the trigger (`[data-gw-mega]`) | `{ id, open }`: the panel's `id`, `true` when it opened | a panel opens or closes: click, hover, Escape, a click outside, focus leaving, a link inside, `destroy` of an open one. Moving to another menu fires a close, then an open |
 | `gw:theme` | `<html>` | `{ theme: 'light' \| 'dark' }`: the theme the page now shows | a press on a theme toggle; also a change of the system's scheme while the page follows it (no `data-theme`) |
 | `gw:segmented` | the group (`[data-gw-segmented]`) | `{ name, value }`: the group's name, the chosen option's `value` | the reader chooses an option (click, arrows, Home, End) |
+| `gw:menu` | the mobile menu (`.gw-mobile-menu`) | `{ open, level }`: `true` while it is open; `level` is the title of the drill-down level in view, `''` for the top level (and for a 0.7.0 menu) | the menu opens or closes (the toggle, Escape, a link inside, resizing past 1080px, `destroy` of an open one), and a drill-down menu moves to a level or back to the top. Closing from a level fires only the close (0.8.0) |
 | `gw:toc` | the contents (`[data-gw-toc]`) | `{ id }`: the id of the heading whose section is now marked, `''` above the first one | the section in view changes: scrolling, a contents link, a jump. Also once after load when the page opens inside a section (a link to `#id`): the observer reports after `init`, never during it |
 
 ```js
 document.addEventListener('gw:theme', function (e) { chart.setTheme(e.detail.theme); });
 document.addEventListener('gw:toc', function (e) { analytics.track('section', e.detail.id); });
+document.addEventListener('gw:menu', function (e) { if (e.detail.level) analytics.track('menu', e.detail.level); });
 ```
 
 ## Header
@@ -125,13 +128,14 @@ document.addEventListener('gw:toc', function (e) { analytics.track('section', e.
     </nav>
     <div class="gw-header__actions">
       <button class="gw-theme-toggle" type="button" data-gw-theme-toggle aria-label="Switch to dark theme">svg</button>
+      <div class="gw-lang" data-gw-lang hidden> … </div>   <!-- optional: the language switcher (0.8.0, below) -->
       <a class="gw-nav__link gw-header__signin" href="…">Sign in</a>
       <a class="gw-btn gw-btn--secondary gw-btn--sm" href="…">Book a demo</a>
       <a class="gw-btn gw-btn--sm" href="…">Start free</a>
       <button class="gw-menu-toggle" type="button" aria-expanded="false" aria-controls="gw-mobile-menu" data-gw-menu-toggle aria-label="Open menu">svg</button>
     </div>
   </div>
-  <div class="gw-mobile-menu" id="gw-mobile-menu" hidden> …the same links as lists, and the actions… </div>
+  <div class="gw-mobile-menu" id="gw-mobile-menu" data-gw-menu?="drill" hidden> …the same links as lists, and the actions… </div>
 </header>
 ```
 
@@ -159,6 +163,99 @@ Script behaviour:
 - **Current page**: the script marks `aria-current="page"` on `.gw-nav__link` / `.gw-mega__link` and the mobile
   menu's links whose `href` pathname equals `location.pathname` (when the markup did not already). Each `init` takes
   its own marks back first, so after a client-side navigation they follow the new path; a mark in the markup stays.
+- **`gw:menu`** (0.8.0): opening and closing a mobile menu fire `gw:menu` on it (`{ open, level: '' }`; Events above).
+
+### Drill-down mobile menu (0.8.0)
+
+Opt-in on the sheet, `data-gw-menu="drill"`; the markup is the 0.7.0 menu plus a head in each group. The groups, the
+top-level links and the actions are children of the sheet's `<nav>`.
+
+```html
+<div class="gw-mobile-menu" id="gw-mobile-menu" data-gw-menu="drill" hidden>
+  <nav class="gw-wrap" aria-label="Main, mobile">
+    <details class="gw-mobile-menu__group">
+      <summary>Product</summary>
+      <div class="gw-mobile-menu__head"><button class="gw-mobile-menu__back" type="button">Back</button><h2 class="gw-mobile-menu__title" tabindex="-1">Product</h2></div>
+      <p class="gw-mobile-menu__heading">Build</p>                                             <!-- optional -->
+      <ul class="gw-mobile-menu__list">
+        <li><a class="gw-mobile-menu__link" href="/funnel"><span class="gw-mobile-menu__icon" aria-hidden="true">svg</span><span><b>Funnel builder</b><i>Angles, advertorials, offers</i></span></a></li>
+        <li><a class="gw-mobile-menu__link" href="/data">Analytics &amp; data</a></li>        <!-- the icon and the line are optional -->
+      </ul>
+      <a class="gw-mobile-menu__all" href="/product">All of Product</a>                         <!-- optional -->
+    </details>
+    <a class="gw-mobile-menu__top" href="/pricing">Pricing</a>
+    <div class="gw-mobile-menu__actions">                                                       <!-- the bar at the bottom -->
+      <div class="gw-lang" data-gw-lang hidden> … </div>                                        <!-- optional: first line, left -->
+      <a class="gw-btn gw-btn--lg gw-btn--block" href="…">Start free</a>
+      <a class="gw-btn gw-btn--secondary gw-btn--lg gw-btn--block" href="…">Book a demo</a>
+      <a class="gw-mobile-menu__link" href="…">Sign in</a>                                       <!-- first line, right -->
+    </div>
+  </nav>
+</div>
+```
+
+- **CSS, from the attribute** (works before and without the script): the sheet is a column with no bottom padding,
+  clipped sideways; top-level rows of 64px with 24px words; a level's links 56px with a hairline, their `<b>` and
+  `<i>`, the 32px `__icon` tile, the muted `__heading`; the actions are a bar that stays at the bottom of the sheet
+  (`position: sticky`): what is not a `.gw-btn` on the first line (two things at most), the last of those on the right,
+  the buttons side by side on the second line. Without the script the groups are `<details>` that open in place (the 0.7.0 menu), their
+  chevron pointing down, and the heads are not drawn.
+- **Script** (`.is-drill` on the sheet once wired, with the toggle's `menu` record). Each group that has a `<summary>`
+  and a `.gw-mobile-menu__title` is a level; the script closes them all (and gives the markup's `open` back on
+  `destroy`). A press on a summary (click, tap, Enter, Space; its default is cancelled) opens that group alone, puts
+  `.is-drilled` on the sheet (the CSS then draws only that level and its head, and hides its summary), scrolls the
+  sheet to its top, moves the focus to the title and fires `gw:menu` (`{ open: true, level: <the title's words> }`).
+  A press on `.gw-mobile-menu__back` shows the top level (`.is-back` on the sheet, for the slide back), puts the focus
+  on the summary it came from and fires `gw:menu` (`level: ''`). Closing the sheet (the toggle, Escape from anywhere in
+  it, a link, resizing past 1080px, `destroy`) shows the top level again without an event of its own.
+- **While it is open**: Tab on the sheet's last shown stop goes to the toggle, Shift+Tab on the toggle to that stop, and
+  a focus found outside comes back in (the trap; a 0.7.0 menu has none). The page is locked as in 0.7.0
+  (`html.is-menu-open`). As it opens, the script sets `--gw-menu-top` on the sheet to where the header ends, and the
+  header stays `sticky` (not `fixed`), so the sheet starts under the header and an announcement bar above it stays.
+- **Motion**: a level slides in from the right, the sections back from the left (`transform` and `opacity`, 0.24s, the
+  kit's ease), only under `prefers-reduced-motion: no-preference`.
+- `check` reports a group of a drill menu that is not a `<details>`, has no `<summary>`, no back button, no title or a
+  title without `tabindex="-1"`, and `data-gw-menu` with another value (`menu-markup`).
+
+### Language switcher (0.8.0)
+
+```html
+<head>
+  <link rel="alternate" hreflang="en" href="https://example.com/pricing">
+  <link rel="alternate" hreflang="vi" href="https://example.com/vi/pricing">
+  <link rel="alternate" hreflang="x-default" href="https://example.com/pricing">
+</head>
+…
+<div class="gw-lang" data-gw-lang hidden>
+  <button class="gw-lang__btn" type="button" aria-expanded="false" aria-controls="gw-lang-menu" data-gw-label-language="Language"><svg aria-hidden="true">globe</svg><span class="gw-lang__short"></span></button>
+  <ul class="gw-lang__menu" id="gw-lang-menu" hidden></ul>
+</div>
+```
+
+- **Where**: in `.gw-header__actions`, before Sign in (drawn from 1080px), and a second one, with its own list `id`, in
+  the mobile menu's `.gw-mobile-menu__actions` (its list opens upward there). Both are filled the same way.
+- **The languages are the head's** `<link rel="alternate" hreflang href>`, not `x-default`, the first link of each
+  `hreflang`: the links search engines read. The current language is the one whose `hreflang` is `<html lang>`, else the
+  first with the same base language (`<html lang="zh">` is `zh-Hans`). The script writes each other language into the
+  list as `<li><a class="gw-lang__link" href hreflang lang>Name</a></li>`, the name in its own language: the `<link>`'s
+  `title`, else the kit's (`en` English, `vi` Tiếng Việt, `zh` and `zh-Hans` 中文), else the browser's
+  (`Intl.DisplayNames`, first letter capitalised), else the code. A link whose host is the host of
+  `<link rel="canonical">` (else this page's host) keeps only its path, search and hash, so a preview deployment stays
+  on itself. The button's `.gw-lang__short` gets the current language's short code (`EN`, `VI`, `中`, else its base code
+  in capitals) and its `lang`.
+- **Hidden** while the list is empty: a page with no other language (no alternates, or only its own) keeps `hidden`;
+  the script takes it away when there is one. Every `init` reads the links again, so a route change that brings other
+  alternates updates both switchers.
+- **Words**: `data-gw-label-language` on the button (else its `aria-label`, else "Language"): the button is named
+  "Language: English" (the word, then the current language's name), the list "Language". `destroy` gives back the
+  button's own label, empties the list and hides the switcher.
+- **Keys and pointer**: the button opens and closes the list (`aria-expanded`); ArrowDown and ArrowUp on it open the
+  list on its first or last link; in the list ArrowDown and ArrowUp move (wrapping), Home and End go to the ends;
+  Escape closes it, gives the focus back to the button and stops there (an open mobile menu around it stays open); the
+  focus leaving it, or a click outside, closes it. Closing the mobile menu closes the list inside it. No event.
+- `check` reports a `.gw-lang` that is not `hidden`, has no `data-gw-lang`, no `.gw-lang__btn`, a button whose
+  `aria-controls` names no list inside it or without `aria-expanded`, links typed into the list, and, on a page with a
+  switcher, a `<link rel="alternate">` without `type` that lacks `hreflang` or `href` (`lang-markup`).
 
 ## Footer (0.7.0)
 

package/docs/theming.md

@@ -15,8 +15,9 @@ widths. That is what makes the sites look like one family, and why a site built
 still looks careful. `npx gemboss-website check` reports anything outside this set.
 
 Working examples: `demo/theme-example.html` (the accent only), `demo/brand-profiles.html` (a GemPages-style brand:
-the accent, all three profiles and the floating header) and `demo/footer.html` (the footer, with a switch to the same
-footer for a GemPages-style brand).
+the accent, all three profiles and the floating header), `demo/footer.html` (the footer, with a switch to the same
+footer for a GemPages-style brand) and `demo/header.html` (the header with the drill-down phone menu and the language
+switcher, with the same switch: the bar's buttons and the language list follow the radius and action profiles).
 
 ## 1 to 3. Accent, wash, logo
 

package/js/website.js

@@ -1,9 +1,9 @@
-/*! @gemboss/website-ui 0.7.0 website.js | GENERATED by scripts/build.mjs from js/website.mjs (the source, with its comments): edit that file | spec: docs/markup-contract.md | load with defer */
+/*! @gemboss/website-ui 0.8.0 website.js | GENERATED by scripts/build.mjs from js/website.mjs (the source, with its comments): edit that file | spec: docs/markup-contract.md | load with defer */
 (function () {
 'use strict';
 if (window.gwWebsite) return;
 
-var version = '0.7.0';
+var version = '0.8.0';
 var api = { version: version, init: init, destroy: destroy };
 var doc, root, mine, fine, sys, wide, mid, live = [], megaOpen = null, megaTimer = 0, queued = false;
 var READY = 'data-gw-ready';
@@ -93,24 +93,136 @@ function mobile(ctx) {
     var menu = doc.getElementById(attr(btn, 'aria-controls', 'gw-mobile-menu'));
     if (!menu) return;
     var label = [attr(btn, 'data-gw-label-open', attr(btn, 'aria-label', 'Open menu')), attr(btn, 'data-gw-label-close', 'Close menu')];
+    var groups = attr(menu, 'data-gw-menu', '') !== 'drill' ? [] : all('.gw-mobile-menu__group', menu).filter(function (g) { return g.querySelector('summary') && head(g); });
+    var own = groups.map(function (g) { return g.open; }), cur = null;
+    function head(g) { return g.querySelector('.gw-mobile-menu__title'); }
     var r = {
       open: function () { return !menu.hidden; },
       set: function (o, focus) {
+        if (o && groups.length) menu.style.setProperty('--gw-menu-top', Math.round((btn.closest('[data-gw-header]') || menu.parentNode).getBoundingClientRect().bottom) + 'px');
         menu.hidden = !o;
         btn.setAttribute('aria-expanded', String(o));
         btn.setAttribute('aria-label', label[+o]);
         root.classList.toggle('is-menu-open', o);
+        if (!o) {
+          r.go(null);
+          records('lang', function (l) { if (menu.contains(l.el)) l.set(false); });
+        }
         if (focus) btn.focus();
+        emit(menu, 'gw:menu', { open: o, level: '' });
       },
-      stop: function () { if (r.open()) r.set(false); }
+      go: function (g, focus) {
+        var from = cur;
+        if (g === cur) return;
+        cur = g;
+        groups.forEach(function (x) { x.open = x === g; });
+        menu.classList.toggle('is-drilled', !!g);
+        menu.classList.toggle('is-back', !g && r.open());
+        menu.scrollTop = 0;
+        if (focus) (g ? head(g) : from.querySelector('summary')).focus();
+        if (r.open()) emit(menu, 'gw:menu', { open: true, level: g ? words(head(g)) : '' });
+      },
+      trap: function (e) {
+        var stops = [btn].concat(all('a[href], button, summary, input, select, textarea, [tabindex="0"]', menu).filter(function (el) { return !el.disabled && el.getClientRects().length; }));
+        var a = doc.activeElement, last = stops[stops.length - 1];
+        if ((a !== btn && !menu.contains(a)) || a === (e.shiftKey ? btn : last)) { e.preventDefault(); (e.shiftKey ? last : btn).focus(); }
+      },
+      stop: function () {
+        if (r.open()) r.set(false);
+        if (!groups.length) return;
+        menu.classList.remove('is-drill');
+        menu.style.removeProperty('--gw-menu-top');
+        groups.forEach(function (g, i) { g.open = own[i]; });
+      }
     };
     on(btn, 'click', function () { r.set(!r.open()); });
     on(menu, 'click', function (e) { if (link(e)) r.set(false); });
+    groups.forEach(function (g) {
+      var back = g.querySelector('.gw-mobile-menu__back');
+      on(g.querySelector('summary'), 'click', function (e) { e.preventDefault(); r.go(g, true); });
+      if (back) on(back, 'click', function () { r.go(null, true); });
+      g.open = false;
+    });
+    if (groups.length) menu.classList.add('is-drill'); else r.trap = null;
     return r;
   });
 }
 function closeMenus(focus) { records('menu', function (r) { if (r.open()) r.set(false, focus); }); }
 
+var LANGS = { en: ['English', 'EN'], vi: ['Ti\u1ebfng Vi\u1ec7t', 'VI'], zh: ['\u4e2d\u6587', '\u4e2d'], 'zh-hans': ['\u4e2d\u6587', '\u4e2d'] };
+function base(code) { return code.toLowerCase().split(/[-_]/)[0]; }
+function speak(x) {
+  var k = LANGS[x.code.toLowerCase()], n = x.title || (k && k[0]);
+  try { n = n || new Intl.DisplayNames([x.code], { type: 'language' }).of(x.code); } catch (e) { /* an old browser, a bad code */ }
+  n = n || x.code;
+  return n.charAt(0).toUpperCase() + n.slice(1);
+}
+function alternates() {
+  var here = attr(root, 'lang', '').toLowerCase(), c = doc.querySelector('link[rel="canonical"][href]'), host = location.host, seen = {}, list = [];
+  try { if (c) host = new URL(attr(c, 'href', ''), location.href).host; } catch (e) { /* this host */ }
+  all('link[rel="alternate"][hreflang][href]').forEach(function (l) {
+    var code = attr(l, 'hreflang', ''), k = code.toLowerCase(), u;
+    try { u = new URL(attr(l, 'href', ''), location.href); } catch (e) { return; }
+    if (k === 'x-default' || seen[k]) return;
+    seen[k] = 1;
+    list.push({ code: code, title: attr(l, 'title', ''), here: k === here, href: u.host === host ? u.pathname + u.search + u.hash : u.href });
+  });
+  if (!list.some(function (x) { return x.here; })) list.some(function (x) { return (x.here = base(x.code) === base(here)); });
+  return list;
+}
+function lang(ctx) {
+  each(ctx, '[data-gw-lang]', 'lang', function (box, on) {
+    var btn = box.querySelector('.gw-lang__btn'), list = btn && doc.getElementById(attr(btn, 'aria-controls', ''));
+    if (!list) return;
+    var short = box.querySelector('.gw-lang__short'), name = attr(btn, 'aria-label', null), word = attr(btn, 'data-gw-label-language', name || 'Language');
+    function links() { return all('a[href]', list); }
+    var r = {
+      open: function () { return !list.hidden; },
+      set: function (o, focus) { list.hidden = !o; btn.setAttribute('aria-expanded', String(o)); if (focus) btn.focus(); },
+      fill: function () {
+        var alts = alternates(), cur = alts.filter(function (x) { return x.here; })[0] || { code: attr(root, 'lang', '') }, k = LANGS[cur.code.toLowerCase()];
+        list.textContent = '';
+        alts.forEach(function (x) {
+          if (x === cur) return;
+          var li = doc.createElement('li'), a = doc.createElement('a');
+          a.className = 'gw-lang__link';
+          a.setAttribute('href', x.href);
+          a.setAttribute('hreflang', x.code);
+          a.setAttribute('lang', x.code);
+          a.textContent = speak(x);
+          li.appendChild(a);
+          list.appendChild(li);
+        });
+        box.hidden = !links().length;
+        if (box.hidden) r.set(false);
+        if (short) { short.textContent = k ? k[1] : base(cur.code).toUpperCase(); short.setAttribute('lang', cur.code); }
+        btn.setAttribute('aria-label', word + ': ' + speak(cur));
+        list.setAttribute('aria-label', word);
+      },
+      stop: function () {
+        r.set(false);
+        list.textContent = '';
+        box.hidden = true;
+        if (short) { short.textContent = ''; short.removeAttribute('lang'); }
+        if (name === null) btn.removeAttribute('aria-label'); else btn.setAttribute('aria-label', name);
+      }
+    };
+    on(btn, 'click', function () { r.set(!r.open()); });
+    on(box, 'keydown', function (e) {
+      if (esc(e)) { if (r.open()) { e.stopPropagation(); r.set(false, true); } return; }
+      var l = links(), n = l.length, i = l.indexOf(doc.activeElement);
+      var k = { ArrowDown: i + 1, ArrowUp: (i < 0 ? 0 : i) - 1 + n, Home: 0, End: n - 1 }[e.key];
+      if (k === undefined || !n || (i < 0 && (e.target !== btn || /^(Home|End)$/.test(e.key))) || e.altKey || e.ctrlKey || e.metaKey) return;
+      e.preventDefault();
+      r.set(true);
+      l[k % n].focus();
+    });
+    on(box, 'focusout', function (e) { if (e.relatedTarget && !box.contains(e.relatedTarget)) r.set(false); });
+    return r;
+  });
+  records('lang', function (r) { r.fill(); });
+}
+
 function dark() { var t = root.getAttribute('data-theme'); return t ? t === 'dark' : sys.matches; }
 function relabel() { records('theme', function (r) { r.el.setAttribute('aria-label', r.labels[+dark()]); }); }
 function theme(ctx) {
@@ -274,6 +386,8 @@ function install() {
   on(doc, 'click', function (e) { if (megaOpen && !inside(megaOpen, e.target)) hideMega(); });
   on(doc, 'keydown', function (e) { if (megaOpen && esc(e)) hideMega(inside(megaOpen, doc.activeElement) || megaOpen.mode === 'click'); });
   on(doc, 'keydown', function (e) { if (esc(e)) closeMenus(true); });
+  on(doc, 'keydown', function (e) { if (e.key === 'Tab') records('menu', function (r) { if (r.trap && r.open()) r.trap(e); }); });
+  on(doc, 'click', function (e) { records('lang', function (r) { if (r.open() && !r.el.contains(e.target)) r.set(false); }); });
   watch(wide, function () { if (wide.matches) closeMenus(); records('toc', function (r) { r.fit(); }); });
   watch(mid, function () { records('fold', function (r) { r.fit(); }); });
   on(window, 'pageshow', function (e) { if (e.persisted) closeMenus(); });
@@ -300,7 +414,7 @@ function init(ctx) {
   window.gwWebsite = api;
   if (!doc) run([install]);
   live.slice().forEach(function (r) { if (r.el.isConnected === false) drop(r); });
-  run([mega, mobile, theme, reveal, header, current, segmented, toc, tables, folds], ctx && ctx.querySelectorAll ? ctx : doc);
+  run([mega, mobile, lang, theme, reveal, header, current, segmented, toc, tables, folds], ctx && ctx.querySelectorAll ? ctx : doc);
 }
 
 /** Takes back what init() wired under root (default: the whole document): listeners and data-gw-ready marks. */

package/js/website.mjs

@@ -6,7 +6,7 @@
 // the export line and the // comments, plus auto-init): edit this file, then run the build. Keep comments on lines of
 // their own, so the build can leave them out.
 
-var version = '0.7.0';
+var version = '0.8.0';
 var api = { version: version, init: init, destroy: destroy };
 // Page state. Set up by the first init(), never at import: a server can import this file.
 var doc, root, mine, fine, sys, wide, mid, live = [], megaOpen = null, megaTimer = 0, queued = false;
@@ -101,30 +101,168 @@ function mega(ctx) {
 }
 
 // Mobile menu. Labels: data-gw-label-open/-close, else the markup's aria-label, else English. A link inside closes it
-// (same-page anchors do not reload). Taken back while open, it closes first: it must not keep the page locked.
+// (same-page anchors do not reload). Taken back while open, it closes first: it must not keep the page locked. Opening
+// and closing fire gw:menu on the menu ({ open, level: '' }); closing also closes a language list inside it.
+//
+// Drill-down (0.8.0, gap #41): a menu with data-gw-menu="drill". Each group in it (a <details class="gw-mobile-menu__group">
+// with its <summary> and a .gw-mobile-menu__title) is a level. A press on the summary shows that level alone
+// (.is-drilled on the menu, the group open, the menu scrolled to its top) and puts the focus on the level's title; its
+// .gw-mobile-menu__back shows the top level again (.is-back, for the CSS's slide) and puts the focus back on the summary.
+// Each move fires gw:menu ({ open: true, level }: the title's words, '' for the top level); closing the menu goes back
+// to the top level without a word of its own. While it is open, Tab and Shift+Tab go round the toggle and the menu (the
+// focus trap), and the menu starts where the header ends (--gw-menu-top, measured as it opens), so an announcement bar
+// above the header stays where it is. .is-drill on the menu says it is wired: without the script (or before init) the
+// groups are the 0.7.0 <details> that open in place. destroy gives back the groups' own open state.
 function mobile(ctx) {
   each(ctx, '[data-gw-menu-toggle]', 'menu', function (btn, on) {
     var menu = doc.getElementById(attr(btn, 'aria-controls', 'gw-mobile-menu'));
     if (!menu) return;
     var label = [attr(btn, 'data-gw-label-open', attr(btn, 'aria-label', 'Open menu')), attr(btn, 'data-gw-label-close', 'Close menu')];
+    var groups = attr(menu, 'data-gw-menu', '') !== 'drill' ? [] : all('.gw-mobile-menu__group', menu).filter(function (g) { return g.querySelector('summary') && head(g); });
+    var own = groups.map(function (g) { return g.open; }), cur = null;
+    function head(g) { return g.querySelector('.gw-mobile-menu__title'); }
     var r = {
       open: function () { return !menu.hidden; },
       set: function (o, focus) {
+        if (o && groups.length) menu.style.setProperty('--gw-menu-top', Math.round((btn.closest('[data-gw-header]') || menu.parentNode).getBoundingClientRect().bottom) + 'px');
         menu.hidden = !o;
         btn.setAttribute('aria-expanded', String(o));
         btn.setAttribute('aria-label', label[+o]);
         root.classList.toggle('is-menu-open', o);
+        if (!o) {
+          r.go(null);
+          records('lang', function (l) { if (menu.contains(l.el)) l.set(false); });
+        }
         if (focus) btn.focus();
+        emit(menu, 'gw:menu', { open: o, level: '' });
+      },
+      // the level in view: a group, or null for the top level
+      go: function (g, focus) {
+        var from = cur;
+        if (g === cur) return;
+        cur = g;
+        groups.forEach(function (x) { x.open = x === g; });
+        menu.classList.toggle('is-drilled', !!g);
+        menu.classList.toggle('is-back', !g && r.open());
+        menu.scrollTop = 0;
+        if (focus) (g ? head(g) : from.querySelector('summary')).focus();
+        if (r.open()) emit(menu, 'gw:menu', { open: true, level: g ? words(head(g)) : '' });
       },
-      stop: function () { if (r.open()) r.set(false); }
+      // Tab on the last stop goes to the toggle, Shift+Tab on the toggle to the last stop; focus found outside comes in
+      trap: function (e) {
+        var stops = [btn].concat(all('a[href], button, summary, input, select, textarea, [tabindex="0"]', menu).filter(function (el) { return !el.disabled && el.getClientRects().length; }));
+        var a = doc.activeElement, last = stops[stops.length - 1];
+        if ((a !== btn && !menu.contains(a)) || a === (e.shiftKey ? btn : last)) { e.preventDefault(); (e.shiftKey ? last : btn).focus(); }
+      },
+      stop: function () {
+        if (r.open()) r.set(false);
+        if (!groups.length) return;
+        menu.classList.remove('is-drill');
+        menu.style.removeProperty('--gw-menu-top');
+        groups.forEach(function (g, i) { g.open = own[i]; });
+      }
     };
     on(btn, 'click', function () { r.set(!r.open()); });
     on(menu, 'click', function (e) { if (link(e)) r.set(false); });
+    groups.forEach(function (g) {
+      var back = g.querySelector('.gw-mobile-menu__back');
+      on(g.querySelector('summary'), 'click', function (e) { e.preventDefault(); r.go(g, true); });
+      if (back) on(back, 'click', function () { r.go(null, true); });
+      g.open = false;
+    });
+    if (groups.length) menu.classList.add('is-drill'); else r.trap = null;
     return r;
   });
 }
 function closeMenus(focus) { records('menu', function (r) { if (r.open()) r.set(false, focus); }); }
 
+// Language switcher (0.8.0, gap #29): a .gw-lang with data-gw-lang, its button .gw-lang__btn and the list its
+// aria-controls names. The languages are the page's own <link rel="alternate" hreflang href> (not x-default): the links
+// search engines read, so the switcher offers exactly the translations they are told about. The one whose hreflang is
+// <html lang> (else the first with the same base language: zh for zh-Hans) is the current one: the button shows its
+// short code. Each other one is a link in the list (href, hreflang, lang), named in its own language: the <link>'s
+// title, else the kit's name (en, vi, zh), else the browser's (Intl.DisplayNames), else its code. A link to the host of
+// <link rel="canonical"> (else to this host) keeps only its path, so a preview deployment stays on itself. With no other
+// language the switcher keeps `hidden`. Every init reads the links again: a route change brings the new page's.
+// The button opens and closes the list. ArrowDown / ArrowUp on it open the list on its first / last link; in the list
+// they move, wrapping, and Home / End go to the ends. Escape closes it and gives the focus back to the button (and goes
+// no further: an open mobile menu around it stays open); the focus leaving it, or a click outside, closes it.
+// Labels: data-gw-label-language on the button, else its aria-label, else "Language": the button is named
+// "<label>: <the current language>", the list "<label>". destroy empties the list and hides the switcher again.
+var LANGS = { en: ['English', 'EN'], vi: ['Ti\u1ebfng Vi\u1ec7t', 'VI'], zh: ['\u4e2d\u6587', '\u4e2d'], 'zh-hans': ['\u4e2d\u6587', '\u4e2d'] };
+function base(code) { return code.toLowerCase().split(/[-_]/)[0]; }
+function speak(x) {
+  var k = LANGS[x.code.toLowerCase()], n = x.title || (k && k[0]);
+  try { n = n || new Intl.DisplayNames([x.code], { type: 'language' }).of(x.code); } catch (e) { /* an old browser, a bad code */ }
+  n = n || x.code;
+  return n.charAt(0).toUpperCase() + n.slice(1);
+}
+function alternates() {
+  var here = attr(root, 'lang', '').toLowerCase(), c = doc.querySelector('link[rel="canonical"][href]'), host = location.host, seen = {}, list = [];
+  try { if (c) host = new URL(attr(c, 'href', ''), location.href).host; } catch (e) { /* this host */ }
+  all('link[rel="alternate"][hreflang][href]').forEach(function (l) {
+    var code = attr(l, 'hreflang', ''), k = code.toLowerCase(), u;
+    try { u = new URL(attr(l, 'href', ''), location.href); } catch (e) { return; }
+    if (k === 'x-default' || seen[k]) return;
+    seen[k] = 1;
+    list.push({ code: code, title: attr(l, 'title', ''), here: k === here, href: u.host === host ? u.pathname + u.search + u.hash : u.href });
+  });
+  if (!list.some(function (x) { return x.here; })) list.some(function (x) { return (x.here = base(x.code) === base(here)); });
+  return list;
+}
+function lang(ctx) {
+  each(ctx, '[data-gw-lang]', 'lang', function (box, on) {
+    var btn = box.querySelector('.gw-lang__btn'), list = btn && doc.getElementById(attr(btn, 'aria-controls', ''));
+    if (!list) return;
+    var short = box.querySelector('.gw-lang__short'), name = attr(btn, 'aria-label', null), word = attr(btn, 'data-gw-label-language', name || 'Language');
+    function links() { return all('a[href]', list); }
+    var r = {
+      open: function () { return !list.hidden; },
+      set: function (o, focus) { list.hidden = !o; btn.setAttribute('aria-expanded', String(o)); if (focus) btn.focus(); },
+      fill: function () {
+        var alts = alternates(), cur = alts.filter(function (x) { return x.here; })[0] || { code: attr(root, 'lang', '') }, k = LANGS[cur.code.toLowerCase()];
+        list.textContent = '';
+        alts.forEach(function (x) {
+          if (x === cur) return;
+          var li = doc.createElement('li'), a = doc.createElement('a');
+          a.className = 'gw-lang__link';
+          a.setAttribute('href', x.href);
+          a.setAttribute('hreflang', x.code);
+          a.setAttribute('lang', x.code);
+          a.textContent = speak(x);
+          li.appendChild(a);
+          list.appendChild(li);
+        });
+        box.hidden = !links().length;
+        if (box.hidden) r.set(false);
+        if (short) { short.textContent = k ? k[1] : base(cur.code).toUpperCase(); short.setAttribute('lang', cur.code); }
+        btn.setAttribute('aria-label', word + ': ' + speak(cur));
+        list.setAttribute('aria-label', word);
+      },
+      stop: function () {
+        r.set(false);
+        list.textContent = '';
+        box.hidden = true;
+        if (short) { short.textContent = ''; short.removeAttribute('lang'); }
+        if (name === null) btn.removeAttribute('aria-label'); else btn.setAttribute('aria-label', name);
+      }
+    };
+    on(btn, 'click', function () { r.set(!r.open()); });
+    on(box, 'keydown', function (e) {
+      if (esc(e)) { if (r.open()) { e.stopPropagation(); r.set(false, true); } return; }
+      var l = links(), n = l.length, i = l.indexOf(doc.activeElement);
+      var k = { ArrowDown: i + 1, ArrowUp: (i < 0 ? 0 : i) - 1 + n, Home: 0, End: n - 1 }[e.key];
+      if (k === undefined || !n || (i < 0 && (e.target !== btn || /^(Home|End)$/.test(e.key))) || e.altKey || e.ctrlKey || e.metaKey) return;
+      e.preventDefault();
+      r.set(true);
+      l[k % n].focus();
+    });
+    on(box, 'focusout', function (e) { if (e.relatedTarget && !box.contains(e.relatedTarget)) r.set(false); });
+    return r;
+  });
+  records('lang', function (r) { r.fill(); });
+}
+
 // Theme toggle. Labels: data-gw-label-dark/-light, else the markup's aria-label, else English. A press fires gw:theme
 // on <html>; so does a change of the system's scheme while the page follows it.
 function dark() { var t = root.getAttribute('data-theme'); return t ? t === 'dark' : sys.matches; }
@@ -319,6 +457,9 @@ function install() {
   on(doc, 'click', function (e) { if (megaOpen && !inside(megaOpen, e.target)) hideMega(); });
   on(doc, 'keydown', function (e) { if (megaOpen && esc(e)) hideMega(inside(megaOpen, doc.activeElement) || megaOpen.mode === 'click'); });
   on(doc, 'keydown', function (e) { if (esc(e)) closeMenus(true); });
+  // a drill-down menu that is open keeps the focus (its trap); a click outside a language list closes it
+  on(doc, 'keydown', function (e) { if (e.key === 'Tab') records('menu', function (r) { if (r.trap && r.open()) r.trap(e); }); });
+  on(doc, 'click', function (e) { records('lang', function (r) { if (r.open() && !r.el.contains(e.target)) r.set(false); }); });
   watch(wide, function () { if (wide.matches) closeMenus(); records('toc', function (r) { r.fit(); }); });
   watch(mid, function () { records('fold', function (r) { r.fit(); }); });
   on(window, 'pageshow', function (e) { if (e.persisted) closeMenus(); });
@@ -351,7 +492,7 @@ function init(ctx) {
   if (!doc) run([install]);
   // an element removed from the page since the last init is let go
   live.slice().forEach(function (r) { if (r.el.isConnected === false) drop(r); });
-  run([mega, mobile, theme, reveal, header, current, segmented, toc, tables, folds], ctx && ctx.querySelectorAll ? ctx : doc);
+  run([mega, mobile, lang, theme, reveal, header, current, segmented, toc, tables, folds], ctx && ctx.querySelectorAll ? ctx : doc);
 }
 
 /** Takes back what init() wired under root (default: the whole document): listeners and data-gw-ready marks. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gemboss/website-ui",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "The GemBoss website kit: tokens, header, footer, sections and the rules (AGENTS.md) that GemCommerce public websites share, plus a CLI that checks a site, reports kit gaps and upgrades.",
   "license": "UNLICENSED",
   "type": "module",

package/skill/SKILL.md

@@ -28,6 +28,10 @@ the kit and its rules are how the page ends up looking designed. Compose from th
    - The footer is `KIT/templates/footer.html` (the footer of gemboss.ai), filled once in the site's shared partial:
      fill its rows (columns, family rows, words), delete the optional parts you do not use (Ask AI, newsletter, family
      rows, theme toggle, wordmark), never invent a footer part. Columns fold on phones by themselves (`<details>`).
+   - The header is `KIT/templates/header.html`, filled once in the site's shared partial. A site with deep sections
+     uses its drill-down mobile menu (`data-gw-menu="drill"`, a head with Back and the title in each group); a site in
+     more than one language keeps its language switcher (`.gw-lang`, `hidden`, empty) and gives every page its
+     `<link rel="alternate" hreflang>`: the switcher lists those, and stays hidden on a page in one language.
    - Changed page: keep its kit classes; change words, order and choice of sections.
    - Site CSS only for what the kit cannot know (an illustration, a product mock-up), with the kit's tokens and
      scales, classes in the site's own prefix. Never style a `.gw-*` class, never edit `node_modules`.