@gemboss/website-ui 0.3.0 → 0.5.0

package/docs/markup-contract.md

@@ -3,8 +3,8 @@
 The full class list, including the CSS-only helpers added while building 0.1.0 (`.gw-h1`–`.gw-h4`, `.gw-lead`,
 `.gw-note`, `.gw-actions`, `.gw-stats__source`, `.gw-plan__price`, the mobile menu parts…), is `docs/components.md`.
 
-The CSS (`css/*.css`), the script (`js/website.js`) and the templates (`templates/`) agree on exactly this. Change it
-here first, then in all three.
+The CSS (`css/*.css`), the script (`js/website.mjs`, and `js/website.js` built from it) and the templates
+(`templates/`) agree on exactly this. Change it here first, then in all three.
 
 Prefixes: kit classes `gw-`, kit CSS variables `--gw-`, state classes `is-` (set by the script), hooks `data-gw-*`.
 BEM-ish: `.gw-block`, `.gw-block__part`, `.gw-block--variant`.
@@ -21,7 +21,84 @@ BEM-ish: `.gw-block`, `.gw-block__part`, `.gw-block--variant`.
   <header class="gw-header" data-gw-header> … </header>
   <main id="main"> sections </main>
   <footer class="gw-footer"> … </footer>
-  <script src="…/website.js" defer></script>
+  <script src="…/website.js" defer></script>   <!-- or the ESM entry, see "Script" below -->
+```
+
+## Script (0.4.0)
+
+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). 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 |
+|---|---|---|
+| classic | `js/website.js` (`@gemboss/website-ui/website.js`) | `<script src="…/website.js" defer>`: wires the page on `DOMContentLoaded` by itself, then `window.gwWebsite` |
+| ESM | `js/website.mjs` (`@gemboss/website-ui/website.mjs`) | `import { init, destroy, version } from '@gemboss/website-ui/website.mjs'`: importing does nothing (safe on a server); the app calls `init()` |
+
+- **`init(root = document)`** wires the kit markup under `root`, `root` included. It is idempotent: an element is
+  wired once, so call it again after every client-side navigation or insert, and only the new elements are wired.
+  Called on a fragment, it wires that fragment and nothing else. It also lets go of elements removed from the page
+  since the last call, and moves the script's own `aria-current` mark to the new path. The listeners that belong
+  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.5.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`). 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.
+- Never wire a kit part with the site's own script (a click handler on `.gw-nav__trigger`, a class toggled by hand):
+  insert the kit's markup, then call `init` on it.
+
+### After inserting markup
+
+A Next.js app (App Router): one client component in the root layout, an effect on each route change. Effects run
+after hydration, so the server's markup is never changed before React reads it.
+
+```jsx
+// app/kit-script.jsx
+'use client';
+import { useEffect } from 'react';
+import { usePathname } from 'next/navigation';
+import { init } from '@gemboss/website-ui/website.mjs';
+
+export default function KitScript() {
+  const pathname = usePathname();
+  useEffect(() => { init(); }, [pathname]);
+  return null;
+}
+// app/layout.js: <body className="gw-page">{children}<KitScript /></body>
+```
+
+A component that mounts and unmounts kit markup on its own (a dialog, a part that streams in later):
+`useEffect(() => { const el = ref.current; init(el); return () => destroy(el); }, [])`, on a wrapper with
+`style={{ display: 'contents' }}` so it does not change the layout.
+
+A page that inserts HTML (a GemPages block rendered after load, a CMS preview), with the classic script:
+
+```js
+var slot = document.getElementById('pricing-slot');
+slot.innerHTML = html;           // kit markup: a header, a segmented control, sections
+window.gwWebsite.init(slot);     // wires what is new in it; the rest of the page is left alone
+```
+
+### Events
+
+The script tells the page's own code what changed. Every event is a `CustomEvent` that bubbles, so one listener on
+`document` hears them all; none is fired by `init`.
+
+| event | target | `detail` | fires when |
+|---|---|---|---|
+| `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: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); });
 ```
 
 ## Header
@@ -61,24 +138,71 @@ BEM-ish: `.gw-block`, `.gw-block__part`, `.gw-block--variant`.
 Script behaviour:
 - **Mega menu**: click on a trigger toggles its panel (`hidden` removed, `aria-expanded="true"`, `.is-open` on the
   `.gw-nav__item`). Hover opens on fine pointers after 80ms and closes 160ms after leaving item and panel. Only one
-  open at a time. `Escape` closes and returns focus to the trigger. A click outside closes. Arrow keys are not required.
+  open at a time on the page, across every header `init` wired. `Escape` closes and returns focus to the trigger. A
+  click outside closes. Arrow keys are not required. Each change fires `gw:mega`.
 - **Mobile menu** (below 1080px the `.gw-nav` and sign-in hide, `.gw-menu-toggle` shows): the toggle flips `hidden`
-  on `#gw-mobile-menu`, `aria-expanded`, `.is-menu-open` on `<html>` (the CSS locks scroll), and its `aria-label`
-  (Open menu / Close menu). `Escape` closes. Resizing above 1080px closes it.
+  on the menu its `aria-controls` names (`#gw-mobile-menu`), `aria-expanded`, `.is-menu-open` on `<html>` (the CSS
+  locks scroll), and its `aria-label` (Open menu / Close menu). `Escape` closes. Resizing above 1080px closes it.
 - **Labels in other languages**: the script never writes English over a translated page. Give the toggles their
   words with `data-gw-label-open` / `data-gw-label-close` (menu toggle) and `data-gw-label-dark` /
   `data-gw-label-light` (theme toggle); without them it keeps the markup's own `aria-label`, then falls back to English.
 - **Theme toggle**: cycles light ↔ dark by setting `data-theme` on `<html>`, stores the choice in `localStorage`
-  (`gw-theme`, every access in try/catch), updates `aria-label`. On load, a stored choice is applied before paint by a
-  one-line inline script in `<head>` that the template carries (`templates/page.html`).
-- **Reveal**: elements with `.gw-reveal` get `.is-in` when 15% visible (IntersectionObserver, once). Failsafe: after
-  2.5s, or if IntersectionObserver is missing, all get `.is-in`. Under `prefers-reduced-motion` the CSS shows them
-  without motion.
+  (`gw-theme`, every access in try/catch), updates `aria-label` on every toggle, fires `gw:theme`. On load, a stored
+  choice is applied before paint by a one-line inline script in `<head>` that the template carries
+  (`templates/page.html`).
+- **Reveal**: elements with `.gw-reveal` get `.is-in` when 15% visible (IntersectionObserver, once). Failsafe: 2.5s
+  after the `init` that found them, or at once if IntersectionObserver is missing, they get `.is-in`. Under
+  `prefers-reduced-motion` the CSS shows them without motion.
 - **Header**: `.is-scrolled` on `[data-gw-header]` once the page scrolled more than 8px (the CSS may use it for the
   hairline only; the bar does not change height or colour). The floating header needs nothing more from the script:
   it is the same element with one more class.
-- **Current page**: the script marks `aria-current="page"` on `.gw-nav__link` / `.gw-mega__link` whose `href`
-  pathname equals `location.pathname` (when the markup did not already).
+- **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.
+
+## Article: contents and prose tables (0.5.0)
+
+```html
+<article class="gw-wrap gw-article">
+  <header class="gw-article__head"> .gw-breadcrumbs, <h1>, .gw-article-meta </header>
+  <figure class="gw-article__hero"><img …></figure>                 <!-- optional -->
+  <nav class="gw-toc" aria-label="On this page" data-gw-toc>
+    <details>                                                       <!-- no open: the script opens it from 1080px -->
+      <summary>On this page</summary>
+      <ol><li><a href="#section-id">The section's heading</a><ol>…h3s…</ol></li> …</ol>
+    </details>
+  </nav>
+  <div class="gw-prose"> <h2 id="section-id">…</h2> … <table><caption>…</caption>…</table> … </div>
+</article>
+```
+
+- **Contents** (`[data-gw-toc]`, a `.gw-toc`): the script reads its links whose `href` is `#id` of an element on the
+  page (percent-encoded ids are decoded; links to other pages and to no id are ignored). With none, the list is not
+  wired yet and a later `init` tries again.
+  - The section in view is the one whose heading is the last above the line 30% down the window. Its link gets
+    `aria-current="true"`; the previous link loses it. Above the first heading no link is marked. Each change fires
+    `gw:toc` on the nav.
+  - One `IntersectionObserver` per list, observing the linked headings, with
+    `rootMargin: '100000px 0px -70% 0px'`: its root runs from far above the window down to the line, so a heading
+    is "intersecting" exactly while it is above the line, and a jump across many sections is seen as well as a
+    scroll. Each report measures every heading again. Without `IntersectionObserver` nothing is marked; the links
+    still work.
+  - The `<details>` inside: from 1080px (`matchMedia('(min-width: 1080px)')`, the kit's desktop width, where the CSS makes it sticky) the
+    script sets `open`; below it, the markup's own state (folded unless the markup says `open`), again on every
+    change of width. Below 1080px a click on a link folds it, in the click, before the browser moves to the section.
+  - `destroy`: the observer disconnects, the mark goes, the `<details>` takes the markup's state back.
+- **Prose tables**: every `<table>` that is a child of a `.gw-prose` (not one inside the author's own `.gw-table`, a
+  figure or another element) is moved into `<div class="gw-prose__table" role="region" tabindex="0" aria-label="…">`
+  at its place, and gets `.is-wrapped`.
+  - The name is the text of the table's `<caption>`, else of its first `<th>`, else of its first `<td>`, spaces
+    collapsed. A table with no text there is left as it is.
+  - The CSS keeps a wrapped table `display: table` (some Safari versions stop announcing a table whose display
+    changed) and gives the box the scroll, the hairline and the radius. A table without `.is-wrapped` (no script,
+    or before it runs) scrolls by itself with `display: block`, as in 0.2.0. Both look the same.
+  - Once per table: a second `init` finds it inside its box and leaves it. `destroy` puts the table back in the
+    prose, removes the box, and removes `.is-wrapped` unless the markup had it.
+  - A framework that renders the prose's table itself (JSX, not HTML from the CMS) should call `destroy(prose)`
+    before it re-renders that part, as for every element the script changed.
 
 ## Brand profiles (0.3.0)
 
@@ -131,12 +255,19 @@ Script behaviour:
 | `.gw-segmented` (+ `--block`) | one choice out of two to four (script above) |
 | `.gw-badge` (+ `--accent`, `--success`, `--warning`) | small status, pill |
 | `.gw-card` (+ `--soft`, `--link`) | white box, 1px hairline, the card radius; `--link` makes the whole card an `<a>` |
+| `.gw-card__media` (+ `--wide`, `--square`) | the card's picture, first child, edge to edge on top; 16:9, 1.91:1 or 1:1 (0.5.0) |
+| `.gw-callout` (+ `--note`, `--tip`, `--warning`, `__label`) | a note, a tip or a warning in an article, `role="note"`, its kind in words (0.5.0) |
+| `.gw-breadcrumbs` | `<nav aria-label>` + `<ol>`, the last item `aria-current="page"`; separators drawn by the CSS (0.5.0) |
+| `.gw-article-meta` (+ `__avatar`) | author, category, `<time datetime>`, read time (0.5.0) |
+| `.gw-article` (`__head`, `__hero`), `.gw-toc` | the article page and its contents (script above, 0.5.0) |
+| `.gw-post-list` (+ `--compact`), `.gw-post` (`__title`) | post cards; the title's link covers the card (0.5.0) |
+| `.gw-pagination` (`__status`) | previous / next links, `rel="prev"` / `rel="next"`, markup only (0.5.0) |
 | `.gw-window` (+ `__bar`, `__body`, `__caption`) | a framed screenshot/mock-up, like a browser or app window; `__caption` (last child) says what its numbers are: "Illustrative data." or their source |
 | `.gw-icon` | 20px inline stroke SVG wrapper |
 | `.gw-list--check` | list with check marks |
 | `.gw-table` (+ `--compare`) | data / comparison table; scrolls inside its box on phones |
 | `.gw-faq` (`<details class="gw-faq__item"><summary>`) | FAQ accordion with no script |
-| `.gw-prose` (+ `--sm`) | long-form reading: an article's own HTML, no classes inside |
+| `.gw-prose` (+ `--sm`) | long-form reading: an article's own HTML, no classes inside; its bare tables get a `.gw-prose__table` box from the script (0.5.0) |
 | `.gw-tabs` (`role="tablist"`) | NOT in the kit yet (a reported gap would add it) |
 
 ## Sections