wiki-formant 0.58.0 → 0.59.0

package/README.md

@@ -287,16 +287,18 @@ The default `frame-src` is `DEFAULT_IFRAME_HOSTS`, the same list the sanitiser's
 
 `SidebarProvider` / `useSidebar` hold the rail's collapse state — remembered across loads, defaulted from the viewport only when the reader has never chosen. Pair it with `sidebarBootScript` from `wiki-formant/sidebar` (framework-free, so a server component can stamp it into `<head>`) or a remembered-closed rail paints open and animates shut on every load. `TableOfContents` is the "on this page" list, with scroll-spy, reading either headings you already know or the rendered article.
 
-The rail's breakpoint is necessarily known twice — `matchMedia` here, a media query in your stylesheet — because a media query cannot read a JS constant and a JS constant cannot read a media query. What the two can be stopped from doing is parting in silence, which is the failure that actually happens: all three wikis matched the numbers by hand, all three were right, and nothing said so. Set `--rail-floating: 1` inside the same media query that lays the rail out, and the hook checks the two agree on every breakpoint crossing, in development, naming both sides and the number to change:
+The rail's breakpoint is necessarily known twice — `matchMedia` here, a media query in a stylesheet — because a media query cannot read a JS constant and a JS constant cannot read a media query. `base.css` holds the CSS half: with `RailShell prefix="wiki-sidebar"` inside a `.wiki-layout` beside a `.wiki-layout__main`, the rail is a sticky column from 1024px and, below it, a drawer stacked above the article that the same open/closed choice shows or removes, table of contents included. 1024 is the default `breakpoint` of `SidebarProvider` and `sidebarBootScript`, so a wiki on `base.css`'s rail passes none. It is measured: an 18rem rail, a full `--measure` of prose (63ch of Inter is 636px) and the page gutters need 972px, and 1024 is the gutter tier above that. The site supplies `--rail-top` (what the sticky rail clears), `--rail-border` (the rule beside the column, which becomes the drawer's foot) and the surface, padding and gap.
+
+What the two halves can be stopped from doing is parting in silence. `base.css` sets `--rail-floating: 1` inside its media query, and the hook checks the two agree on every breakpoint crossing, in development, naming both sides and the number to change. A wiki that lays its rail out itself opts in the same way:
 
 ```css
 @media (max-width: 767px) {          /* the edge of breakpoint={768} */
   :root { --rail-floating: 1; }
-  .sidebar { position: fixed; /* … however this wiki floats its rail */ }
+  .sidebar { /* … however this wiki lays its rail out */ }
 }
 ```
 
-Declaring the property is what opts a stylesheet in; without it the check stays quiet, since a package cannot require CSS it does not ship. The mechanism is `railBreakpointMismatch` and `readRailFloating` from `wiki-formant/sidebar`, both exported, the first pure.
+Without the property the check stays quiet, since a package cannot require CSS it does not ship. The mechanism is `railBreakpointMismatch` and `readRailFloating` from `wiki-formant/sidebar`, both exported, the first pure.
 
 `useTypeahead` is the search field's state machine. Five surfaces across the three wikis had three implementations and no two agreed on what a search field does; this is their union, because each had a piece the others lacked:
 
@@ -369,7 +371,7 @@ are unit-tested without a DOM.
 
 `PageNav` is the previous/next pair at the foot of an article — the sequential read the infobox rail's lateral links do not cover. Ordering is the caller's, because it is the one part that is never portable: a wiki's sequence is its section's configured sort, a knowledge base's is a taxonomy walk. Pair it with `adjacentPages` from `wiki-formant/pagination` over a list you already hold — neither wiki needs a query for it, and the two indexed lookups the neighbours used to cost were the reason one of them dropped the control.
 
-`RailShell` stays in `wiki-formant/react`, because it calls `useSidebar` and genuinely is a client component. It renders the rail's landmark, its scroll wrapper and the three collapse states — including the `--instant` class that keeps a remembered-closed rail from animating shut on first paint, and the close-on-tap that a mobile rail needs. Compose your own rail inside it and mark the active link with `isRailLinkActive`; all three wikis do, and the pre-composed component that used to sit here had one consumer and had already lost both of those behaviours.
+`RailShell` stays in `wiki-formant/react`, because it calls `useSidebar` and genuinely is a client component. It renders the rail's landmark, its scroll wrapper and the three collapse states — including the `--instant` class that keeps a remembered-closed rail from animating shut on first paint, and the close-on-navigate that a mobile drawer needs. Only a followed link closes it: a search field or a table-of-contents entry inside the drawer leaves it open. Compose your own rail inside it and mark the active link with `isRailLinkActive`; all three wikis do, and the pre-composed component that used to sit here had one consumer and had already lost both of those behaviours.
 
 `FacetSummary` is the line under the facet bar — how much of the section is showing, and a Clear link when anything is narrowed — with the filtered-empty and empty-section states. `RelatedPages` is the see-also list: a labelled `<aside>` over a `<ul>`, its heading linked to the set `rankRelated` found in common. `InfoboxAside` is the facts panel's named landmark with its "Part of a series on" line, and `InfoboxFacts` renders `metadataRows` as a row-headed table. That table was an HTML string in two wikis, injected as a fake content block; one re-escaped a `"` before each href by hand and the other did not. As React nodes there is nothing to escape. `formatFactValue` is its default cell: a date as its day, a URL or bare domain as an outbound link, `<br>`-separated values as lines.
 
@@ -840,10 +842,8 @@ return (
 );
 ```
 
-`StatsGate` (`wiki-formant/stats`) renders `children` and a sign-out button (`PasskeySignOut`) for a signed-in reader and, for anyone else, the line saying what the prompt will do and the `PasskeyButton` that does it; `classNames` places the text, the button's box, the button and its error.
+`StatsGate` (`wiki-formant/stats`) renders `children` and a sign-out button for a signed-in reader and, for anyone else, the line saying what the prompt will do and the passkey button that does it; `classNames` places the text, the button's box, the button and its error. Those buttons are the browser half of `wiki-formant/passkey`, and they have no subpath of their own.
 
-`PasskeyButton` (`wiki-formant/passkey-button`) is the browser half and has its
-own subpath, because it imports `@simplewebauthn/browser`.
 `Stats` (`wiki-formant/stats`) renders a `digest` as one page: the
 headline figures, each with its change from the window before
 (`.stats-delta[data-better]`, a share or for the bounce rate points, for the

package/dist/base.css

@@ -65,6 +65,73 @@
 .page-with-infobox > .page-main-content { grid-area: content; min-width: 0; }
 .page-with-infobox > .infobox { grid-area: infobox; min-width: 0; }
 
+/* ---- the wiki rail (RailShell prefix="wiki-sidebar") ------------------------
+   A column beside the article from 1024px; below that, a drawer stacked above
+   it, which the same open/closed choice shows or removes. Three wikis had three
+   answers here (an overlay with no scrim at 768px, this drawer at 900px, the
+   rail moved under the article at 1024px), and an 18rem overlay on a phone hid
+   the page it was the rail of.
+
+   1024 is where the rail stops fitting, rounded up to the gutter tier: 18rem of
+   rail plus a full `--measure` of prose plus the page gutters needs 972px on
+   the widest of the three (63ch of Inter is 636px), and 1024 is the next edge
+   the gutters already step at. It is also the default `breakpoint` of
+   `SidebarProvider` and `sidebarBootScript`; pass none. `--rail-floating` below
+   is how the hook checks the two still agree.
+
+     .wiki-layout > aside.wiki-sidebar > .wiki-sidebar__scroll
+                  > .wiki-layout__main
+
+   The site sets `--rail-top` (what the sticky rail clears, a header's height),
+   `--rail-border` (the rule between rail and article, which becomes the
+   drawer's foot) and the rail's surface, padding and gap. Closed is the class
+   or `html[data-sidebar='closed']`, whichever says so first: the boot script
+   writes the attribute before React can, and React writes the class. */
+.wiki-layout { display: flex; align-items: flex-start; }
+.wiki-layout__main { flex: 1 1 0%; min-width: 0; }
+.wiki-sidebar {
+  position: sticky;
+  top: var(--rail-top, 0px);
+  flex-shrink: 0;
+  width: var(--sidebar-width, 18rem);
+  height: calc(100dvh - var(--rail-top, 0px));
+  overflow: hidden;
+  border-inline-end: var(--rail-border, none);
+  transition: width 200ms cubic-bezier(0.4, 0, 0.2, 1);
+}
+/* Closed gives the column back; the scroll box keeps its width, so nothing
+   reflows on the way out. */
+.wiki-sidebar--closed,
+html[data-sidebar='closed'] .wiki-sidebar { width: 0; }
+/* Until the hook has read storage: a rail left closed is closed on first paint
+   rather than sliding shut on every load. */
+.wiki-sidebar--instant { transition: none; }
+.wiki-sidebar__scroll {
+  display: flex;
+  flex-direction: column;
+  width: var(--sidebar-width, 18rem);
+  height: 100%;
+  overflow-y: auto;
+}
+@media (max-width: 1023px) {
+  :root { --rail-floating: 1; }
+  .wiki-layout { flex-direction: column; align-items: stretch; }
+  .wiki-sidebar {
+    position: static;
+    width: auto;
+    height: auto;
+    border-inline-end: none;
+    border-block-end: var(--rail-border, none);
+    transition: none;
+  }
+  .wiki-sidebar--closed,
+  html[data-sidebar='closed'] .wiki-sidebar { display: none; }
+  /* The cap is on the scroll box, not the rail: a percentage height inside an
+     auto-height parent is auto, so a capped rail clipped a long table of
+     contents instead of scrolling it. */
+  .wiki-sidebar__scroll { width: auto; height: auto; max-height: 70dvh; }
+}
+
 /* ---- the block views and the infobox ---------------------------------------
    The structure three or four sites had each restated around this markup;
    padding, gaps, radii and colour stay theirs. A stats block is two columns,

package/dist/react.d.ts

@@ -423,11 +423,9 @@ export declare class ErrorBoundary extends Component<{
 export interface RailShellProps {
     children: ReactNode;
     /**
-     * Class prefix the stylesheet implements: `"wiki-sidebar"` or `"sidebar"`.
-     *
-     * The one thing genuinely per-repo here. Everything else — which three states
-     * exist, what each means, and that the attribute outranks the class — is a
-     * contract both stylesheets already spell out in near-identical comments.
+     * Class prefix the stylesheet implements. `"wiki-sidebar"` is the one
+     * `wiki-formant/base.css` lays out, column and drawer both; another prefix
+     * leaves the layout to the site's own stylesheet.
      */
     prefix: string;
     /** Accessible name. A rail with none is an unlabelled landmark. */
@@ -436,7 +434,7 @@ export interface RailShellProps {
 }
 /**
  * The collapsible rail's outer shell: the landmark, its three states, and the
- * scroll container, with a tap inside it closing the rail on mobile.
+ * scroll container, with a followed link closing the rail on mobile.
  *
  * THE THREE STATES ARE NOT TWO. `--open` / `--closed` is the reader's choice;
  * `--instant` suppresses the transition until that choice has been read out of
@@ -451,9 +449,14 @@ export interface RailShellProps {
  * paint and the stylesheet lets that attribute win. The class is what keeps
  * React's view in sync afterwards.
  *
- * Closing on navigate is scoped to mobile because that is where the rail
- * OVERLAYS the article — on a desktop it is a column beside it, and collapsing
- * it on every click would be a rail that folds itself away as you use it.
+ * Closing on navigate is scoped to mobile because that is where the rail is a
+ * drawer above the article — on a desktop it is a column beside it, and
+ * collapsing it on every click would be a rail that folds itself away as you
+ * use it. Only a link closes it. Any tap used to, so a search field inside the
+ * rail shut it on focus, and a table-of-contents entry removed the drawer from
+ * above the heading it had just started scrolling to.
+ *
+ * With `prefix="wiki-sidebar"`, `wiki-formant/base.css` lays the rail out.
  */
 export declare function RailShell({ children, prefix, label, className }: RailShellProps): import("react").JSX.Element;
 /**

package/dist/react.js

@@ -809,7 +809,7 @@ export class ErrorBoundary extends Component {
 }
 /**
  * The collapsible rail's outer shell: the landmark, its three states, and the
- * scroll container, with a tap inside it closing the rail on mobile.
+ * scroll container, with a followed link closing the rail on mobile.
  *
  * THE THREE STATES ARE NOT TWO. `--open` / `--closed` is the reader's choice;
  * `--instant` suppresses the transition until that choice has been read out of
@@ -824,14 +824,19 @@ export class ErrorBoundary extends Component {
  * paint and the stylesheet lets that attribute win. The class is what keeps
  * React's view in sync afterwards.
  *
- * Closing on navigate is scoped to mobile because that is where the rail
- * OVERLAYS the article — on a desktop it is a column beside it, and collapsing
- * it on every click would be a rail that folds itself away as you use it.
+ * Closing on navigate is scoped to mobile because that is where the rail is a
+ * drawer above the article — on a desktop it is a column beside it, and
+ * collapsing it on every click would be a rail that folds itself away as you
+ * use it. Only a link closes it. Any tap used to, so a search field inside the
+ * rail shut it on focus, and a table-of-contents entry removed the drawer from
+ * above the heading it had just started scrolling to.
+ *
+ * With `prefix="wiki-sidebar"`, `wiki-formant/base.css` lays the rail out.
  */
 export function RailShell({ children, prefix, label, className }) {
     const { open, setOpen, isMobile, ready } = useSidebar();
-    const close = useCallback(() => {
-        if (isMobile)
+    const close = useCallback((e) => {
+        if (isMobile && e.target.closest('a[href]'))
             setOpen(false);
     }, [isMobile, setOpen]);
     const classes = [

package/dist/sidebar.js

@@ -22,9 +22,10 @@ export function resolveSidebarOpen({ chosen, current, stored, isMobile, }) {
 /** The attribute the boot script and the hook both write to `<html>`. */
 export const SIDEBAR_ATTRIBUTE = 'data-sidebar';
 /**
- * The custom property a consumer's stylesheet sets inside its own rail media
- * query — `1` where the rail stops being a column beside the article, `0`
- * elsewhere.
+ * The custom property set inside the rail's media query — `1` where the rail
+ * stops being a column beside the article, unset elsewhere. `base.css` sets it
+ * at the default breakpoint; a stylesheet that lays its own rail out sets it in
+ * its own query.
  *
  * The rail's breakpoint is necessarily known twice: this hook needs it in JS
  * (to close the rail on navigate, and to default a first-ever visit), and the
@@ -33,8 +34,7 @@ export const SIDEBAR_ATTRIBUTE = 'data-sidebar';
  * JS constant cannot read a media query, so the two numbers cannot be merged —
  * but they can be made unable to disagree QUIETLY, which is the actual hazard.
  *
- * All three wikis matched by hand and all three happened to be right; nothing
- * said so. Declaring this property is what opts a stylesheet into the check.
+ * Declaring this property is what opts a stylesheet into the check.
  *
  * @internal
  */

package/dist/stats-figures.d.ts

@@ -11,3 +11,17 @@ export declare function StatsFigures({ digest, first, windows }: {
     first: number;
     windows: ReactNode;
 }): import("react").JSX.Element;
+export interface PasskeyButtonProps {
+    /** The route that serves `gate.route`. */
+    endpoint: string;
+    /** The invite token from the link, when there is one. */
+    invite?: string | undefined;
+    className?: string;
+    errorClassName?: string;
+}
+export declare function PasskeyButton({ endpoint, invite, className, errorClassName }: PasskeyButtonProps): import("react").JSX.Element;
+/** Ends the session at `endpoint` (`gate.signOut` as DELETE) and reloads the page. */
+export declare function PasskeySignOut({ endpoint, className }: {
+    endpoint: string;
+    className?: string;
+}): import("react").JSX.Element;

package/dist/stats-figures.js

@@ -1,9 +1,11 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-// stats-figures.tsx — the stats page's headline figures and the chart under
-// them. Each figure is a button that charts that figure by day, week or month, so the chart
-// is not only visitors. Its own module because it holds state; `Stats` stays a
-// server component and hands it the digest, which is plain JSON.
+// stats-figures.tsx — the stats page's client half: the headline figures and
+// the chart under them, and `StatsGate`'s passkey buttons. Each figure is a
+// button that charts that figure by day, week or month, so the chart is not only
+// visitors. Its own module because it holds state; `Stats` stays a server
+// component and hands it the digest, which is plain JSON.
+import { startAuthentication, startRegistration } from '@simplewebauthn/browser';
 import { useMemo, useState } from 'react';
 import { TimeChart, stepDecimals } from './chart.js';
 const count = (n) => n.toLocaleString('en');
@@ -78,3 +80,37 @@ export function StatsFigures({ digest, first, windows }) {
     }, [byDay, first, figure]);
     return (_jsxs(_Fragment, { children: [_jsx("div", { className: "stats-figures", role: "group", "aria-label": "Chart", children: figures.map((f, i) => (_jsxs("button", { type: "button", "aria-pressed": i === chosen, onClick: () => choose(i), children: [_jsx("span", { children: f.label }), _jsxs("strong", { children: [f.value, f.delta && (_jsx("small", { className: "stats-delta", "data-better": f.delta.better, children: f.delta.text }))] })] }, f.label))) }), _jsx(TimeChart, { series: series, label: figure.label, ranges: ['all'], aggregate: figure.aggregate ?? 'sum', fromZero: true, format: figure.format, controls: windows, className: "stats-chart" })] }));
 }
+async function post(endpoint, body) {
+    const res = await fetch(endpoint, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) });
+    if (!res.ok)
+        throw new Error((await res.json().catch(() => null))?.error ?? 'Sign-in failed.');
+    return res.status === 204 ? null : res.json();
+}
+export function PasskeyButton({ endpoint, invite, className, errorClassName }) {
+    const saving = !!invite;
+    const [busy, setBusy] = useState(false);
+    const [error, setError] = useState(null);
+    async function go() {
+        setBusy(true);
+        setError(null);
+        try {
+            const optionsJSON = await post(endpoint, { invite });
+            const response = saving ? await startRegistration({ optionsJSON }) : await startAuthentication({ optionsJSON });
+            await post(endpoint, { invite, response });
+            location.replace(location.pathname + location.search.replace(/([?&])invite=[^&]*&?/, '$1').replace(/[?&]$/, ''));
+        }
+        catch (e) {
+            // A prompt the person closed throws NotAllowedError, which needs no message.
+            setError(e instanceof Error && e.name !== 'NotAllowedError' ? e.message : null);
+            setBusy(false);
+        }
+    }
+    return (_jsxs(_Fragment, { children: [_jsx("button", { type: "button", className: className, onClick: go, disabled: busy, children: saving ? 'Save a passkey' : 'Sign in with a passkey' }), error && (_jsx("p", { role: "alert", className: errorClassName, children: error }))] }));
+}
+/** Ends the session at `endpoint` (`gate.signOut` as DELETE) and reloads the page. */
+export function PasskeySignOut({ endpoint, className }) {
+    return (_jsx("button", { type: "button", className: className, onClick: async () => {
+            await fetch(endpoint, { method: 'DELETE' }).catch(() => null);
+            location.reload();
+        }, children: "Sign out" }));
+}

package/dist/stats.js

@@ -1,7 +1,6 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { STATS_FILTERS } from './analytics.js';
-import { PasskeyButton, PasskeySignOut } from './passkey-button.js';
-import { StatsFigures } from './stats-figures.js';
+import { PasskeyButton, PasskeySignOut, StatsFigures } from './stats-figures.js';
 /** The windows the stats page offers, in days; `Infinity` is all time. */
 const STATS_RANGES = [1, 7, 30, 90, 365, Infinity];
 /** A window as its `?days=` value. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wiki-formant",
-  "version": "0.58.0",
+  "version": "0.59.0",
   "description": "The portable half of a wiki: derived taxonomy and facet controls, a version-negotiating MCP transport, markdown twins, block rendering, a rich-text editor engine, conditional-GET plumbing, and the headers and CSP every origin sends.",
   "type": "module",
   "license": "MIT",
@@ -82,11 +82,6 @@
       "import": "./dist/passkey.js",
       "default": "./dist/passkey.js"
     },
-    "./passkey-button": {
-      "types": "./dist/passkey-button.d.ts",
-      "import": "./dist/passkey-button.js",
-      "default": "./dist/passkey-button.js"
-    },
     "./rola": {
       "types": "./dist/rola.d.ts",
       "import": "./dist/rola.js",

package/dist/passkey-button.d.ts

@@ -1,14 +0,0 @@
-export interface PasskeyButtonProps {
-    /** The route that serves `gate.route`. */
-    endpoint: string;
-    /** The invite token from the link, when there is one. */
-    invite?: string | undefined;
-    className?: string;
-    errorClassName?: string;
-}
-export declare function PasskeyButton({ endpoint, invite, className, errorClassName }: PasskeyButtonProps): import("react").JSX.Element;
-/** Ends the session at `endpoint` (`gate.signOut` as DELETE) and reloads the page. */
-export declare function PasskeySignOut({ endpoint, className }: {
-    endpoint: string;
-    className?: string;
-}): import("react").JSX.Element;

package/dist/passkey-button.js

@@ -1,45 +0,0 @@
-'use client';
-import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
-// passkey-button.tsx – the browser half of `wiki-formant/passkey`.
-//
-// Its own subpath because it imports `@simplewebauthn/browser`, an optional
-// peer that only an app with a passkey door installs. With an invite it saves a
-// new passkey; otherwise it signs in with a saved one. Either way, success
-// reloads the page without the invite, and the server sees the new cookie.
-// `PasskeySignOut` calls the route's DELETE (`gate.signOut`) and reloads.
-import { startAuthentication, startRegistration } from '@simplewebauthn/browser';
-import { useState } from 'react';
-async function post(endpoint, body) {
-    const res = await fetch(endpoint, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) });
-    if (!res.ok)
-        throw new Error((await res.json().catch(() => null))?.error ?? 'Sign-in failed.');
-    return res.status === 204 ? null : res.json();
-}
-export function PasskeyButton({ endpoint, invite, className, errorClassName }) {
-    const saving = !!invite;
-    const [busy, setBusy] = useState(false);
-    const [error, setError] = useState(null);
-    async function go() {
-        setBusy(true);
-        setError(null);
-        try {
-            const optionsJSON = await post(endpoint, { invite });
-            const response = saving ? await startRegistration({ optionsJSON }) : await startAuthentication({ optionsJSON });
-            await post(endpoint, { invite, response });
-            location.replace(location.pathname + location.search.replace(/([?&])invite=[^&]*&?/, '$1').replace(/[?&]$/, ''));
-        }
-        catch (e) {
-            // A prompt the person closed throws NotAllowedError, which needs no message.
-            setError(e instanceof Error && e.name !== 'NotAllowedError' ? e.message : null);
-            setBusy(false);
-        }
-    }
-    return (_jsxs(_Fragment, { children: [_jsx("button", { type: "button", className: className, onClick: go, disabled: busy, children: saving ? 'Save a passkey' : 'Sign in with a passkey' }), error && (_jsx("p", { role: "alert", className: errorClassName, children: error }))] }));
-}
-/** Ends the session at `endpoint` (`gate.signOut` as DELETE) and reloads the page. */
-export function PasskeySignOut({ endpoint, className }) {
-    return (_jsx("button", { type: "button", className: className, onClick: async () => {
-            await fetch(endpoint, { method: 'DELETE' }).catch(() => null);
-            location.reload();
-        }, children: "Sign out" }));
-}