staffa 0.8.1 → 0.10.0

package/dist/components/button.js

@@ -20,6 +20,11 @@ A.insertGlobalCss({
         // button (which is already near-white) darkens toward its ink instead.
         "&.tonal:hover, &.outlined:hover": "background: color-mix(in srgb, $s-bg 24%, transparent);",
         "&.neutral:hover": "filter:none background: color-mix(in srgb, $s-text 8%, $s-bg);",
+        // The button sizes its glyph, for the same reason `.s-icon-btn` does below:
+        // a caller can't know what the button beside it passed, and only a rule
+        // here makes every icon in a row come out alike. It rides the font size,
+        // so a `.small`/`.large` button scales its icon with its text.
+        "> svg": "width:1.25em height:1.25em",
         // Subtle press feedback.
         "&:active:not(:disabled)": "transform: translateY(1px)",
         // Size: set on the button itself, or inherited from a `.small`/`.large`
@@ -27,7 +32,86 @@ A.insertGlobalCss({
         "&.small, .small > &": "padding: $m1 $m2; font-size:0.85em border-radius:$s-radius-sm",
         "&.large, .large > &": "font-size:1.4em border-radius:$s-radius-lg",
     },
+    // A bare glyph in a square hit area: no fill and no edge, just ink that lifts
+    // on hover. Deliberately *not* a `.s-s` surface — chrome that sits beside a
+    // title (a ✕, a ☰) should read as an affordance on the bar, not as
+    // another button competing with it, and a filled or outlined box around a
+    // 16px glyph is exactly what makes a top bar look busy.
+    ".s-icon-btn": {
+        "&": "display:inline-flex align-items:center justify-content:center flex-shrink:0 " +
+            "width:2rem height:2rem p:0 border:0 background:transparent cursor:pointer " +
+            "fg:$s-muted r:$s-radius-sm line-height:1 font-size:1rem text-decoration:none " +
+            "transition: color 0.12s, background 0.12s;",
+        // The container sizes the glyph, rather than trusting whatever the caller
+        // passed: a row of icon buttons only reads as a row when every glyph in it
+        // is the same size, and the caller of one of them can't know about the
+        // others. CSS beats the `width`/`height` attributes the icon set writes, so
+        // `iconButton({ icon: trash2 })` and a hand-sized glyph come out alike; an
+        // `attrs` override still wins over this, being an inline style. The same
+        // rule is on `.s-btn` above and on a floating menu's rows in menu.ts, so
+        // one `1.25em` governs the lot. (`S.main`'s nav rows are deliberately out
+        // of it — see the note there.)
+        "> svg": "width:1.25em height:1.25em",
+        // The ink resolves against whatever surface it sits on, so one treatment
+        // works on the page, in a box header, and on a coloured bar alike.
+        "&:hover:not(:disabled):not([aria-disabled=true])": "fg:$s-text background: color-mix(in srgb, $s-text 10%, transparent);",
+        "&:focus-visible": "outline: 3px solid $s-focus; outline-offset:1px",
+        // The glyph rides the font size, so it scales with the hit area.
+        "&.small, .small > &": "width:1.6rem height:1.6rem font-size:0.8rem",
+        "&.large, .large > &": "width:2.4rem height:2.4rem font-size:1.2rem",
+    },
 });
+/**
+ * A bare glyph in a square hit area — no fill, no border, just ink that lifts on
+ * hover. The quiet end of the button family, for chrome that has to sit beside
+ * something more important without competing with it: a ✕ on a box, the ☰ a
+ * routed `S.main()` puts in its top bar, the verbs in a
+ * {@link Panel.actions | page's actions}.
+ *
+ * Reach for {@link button} instead whenever the thing has a name worth reading;
+ * an icon alone is only unambiguous for a handful of universal actions.
+ *
+ * @example
+ * ```ts
+ * import { trash2, share2 } from "staffa/icons";
+ *
+ * $panel.actions = () => {
+ *   S.iconButton({ icon: share2, ariaLabel: "Share", click: share });
+ *   S.iconButton({ icon: trash2, ariaLabel: "Delete", click: del, attrs: "fg:$s-danger" });
+ * };
+ * ```
+ */
+export function iconButton(opts) {
+    const tag = opts.href != null ? "a" : "button";
+    A(`${tag}.s-icon-btn`, opts.attrs, () => {
+        applyActionBehavior(opts);
+        A("aria-label=", opts.ariaLabel);
+        drawSlot(opts.icon);
+    });
+}
+/**
+ * The link-or-button plumbing {@link button} and {@link iconButton} share:
+ * href/type, disabling, label and click. A disabled link keeps `role=button`
+ * and `aria-disabled` but loses its `href` — an anchor without one is out of
+ * the tab order and follows nothing, which is what makes it as disabled as
+ * the `<button>` form's real `disabled` attribute.
+ */
+function applyActionBehavior(o) {
+    if (o.href != null) {
+        A("role=button");
+        if (o.disabled)
+            A("aria-disabled=true");
+        else
+            A("href=", o.href);
+    }
+    else {
+        A("type=", o.type ?? "button");
+        if (o.disabled)
+            A("disabled=true");
+    }
+    if (o.click && !o.disabled)
+        A("click=", o.click);
+}
 /**
  * A button. Tonal and outlined variants show a border; filled variants rely on
  * their solid background for affordance.
@@ -60,20 +144,9 @@ export function button(opts = {}) {
     // role (`.danger`, `.neutral`, a custom `.brand`) or variant (`.outlined`); no
     // role detection needed, since the default lives in CSS, not here.
     A(`${tag}.s-btn.s-s.shadow`, o.attrs, () => {
-        if (o.href != null) {
-            A(`href=${o.href} role=button`);
-            if (o.disabled)
-                A("aria-disabled=true");
-        }
-        else {
-            A("type=", o.type ?? "button");
-            if (o.disabled)
-                A("disabled=true");
-        }
+        applyActionBehavior(o);
         if (o.ariaLabel)
             A("aria-label=", o.ariaLabel);
-        if (o.click)
-            A("click=", o.click);
         drawSlot(o.icon);
         drawSlot(o.content);
     });

package/dist/components/buttonChooser.js

@@ -35,6 +35,6 @@ export function buttonChooser(opts) {
     });
     if (opts.name) {
         // Hidden input carries the value into native form submission.
-        A(() => A(`input type=hidden name=${opts.name} value=`, opts.bind.value ?? ""));
+        A(() => A("input type=hidden name=", opts.name, "value=", opts.bind.value ?? ""));
     }
 }

package/dist/components/checkbox.js

@@ -24,11 +24,11 @@ A.insertGlobalCss({
 export function checkbox(opts = {}) {
     const id = opts.id ?? uniqueId("check");
     A("div.s-check", opts.attrs, () => {
-        A(`label for=${id}`, () => {
+        A("label for=", id, () => {
             A("input type=checkbox", opts.inputAttrs, () => {
-                A(`id=${id}`);
+                A("id=", id);
                 if (opts.name)
-                    A(`name=${opts.name}`);
+                    A("name=", opts.name);
                 // `checked` is a boolean attribute: only set it when actually true.
                 if (opts.checked && !opts.bind)
                     A("checked=true");

package/dist/components/field.js

@@ -37,7 +37,7 @@ export function drawField(opts, drawControl) {
     A("div.s-field", opts.attrs, () => {
         A(() => {
             if (opts.label != null) {
-                A(`label for=${id}`, () => {
+                A("label for=", id, () => {
                     drawSlot(opts.label);
                     if (opts.required)
                         A("span.s-req aria-hidden=true #*");
@@ -61,9 +61,9 @@ export function drawField(opts, drawControl) {
  * each get their own scope so the control element is never recreated.
  */
 export function applyControlAttrs(opts, id, isInvalid, bind) {
-    A(`id=${id}`);
+    A("id=", id);
     if (opts.name)
-        A(`name=${opts.name}`);
+        A("name=", opts.name);
     A(() => {
         if (opts.disabled)
             A("disabled=true");

package/dist/components/main.d.ts

@@ -1,27 +1,70 @@
 import { type Slot, type Attributes } from "../core.js";
 import { type MenuOptions } from "./menu.js";
-import { type RouteHandler, type RouteTable, type Routes } from "./panels.js";
+import { type PanelStack, type AncestorTable, type RouteHandler, type RouteTable, type Routes } from "./panels.js";
 /** Options for {@link main}. */
 export interface MainOptions<R = Routes> {
     /** Aberdeen attr/style string applied to the outermost shell element. */
     attrs?: Attributes;
-    /** App/page title shown in the top bar. */
+    /**
+     * The app's name, shown in the top bar in the brand's own styling, with the
+     * breadcrumb stack of open panels on the line beneath it (in routed mode).
+     * In routed mode it is a link to the app's {@link MainOptions.home}, as the
+     * {@link MainOptions.logo} is.
+     */
     title?: Slot;
-    /** Secondary line under the title. */
+    /**
+     * A tagline for the app, on the line under its name.
+     *
+     * In routed mode that line is the breadcrumb stack's, and the tagline only
+     * gets it while the stack would be saying nothing the screen doesn't
+     * already: exactly one panel open, that panel being one a nav item leads to
+     * (so the sidebar has it highlighted), and the sidebar actually on screen.
+     * Open a panel on top of it, or narrow the shell until the nav is behind the
+     * ☰, and the stack takes the line back — it is then the only thing naming
+     * the screen. Pass no subtitle and the stack simply always has it.
+     *
+     * Outside routed mode nothing competes for the line, so it always shows.
+     */
     subtitle?: Slot;
-    /** Leading icon/logo in the top bar. */
-    icon?: Slot;
-    /** Action area on the right of the top bar (buttons, menu, ...). */
+    /**
+     * The brand mark: the bar's leading slot while the nav is a sidebar.
+     *
+     * A narrow shell *displaces* it with the ☰ that opens the collapsed nav. The
+     * app never branches on which: it hands over a logo and the shell works out
+     * whether there is room for it. In routed mode it is a link to the app's
+     * {@link MainOptions.home}, as the app's name is.
+     */
+    logo?: Slot;
+    /**
+     * The app's home: where the name and the {@link MainOptions.logo} in the
+     * top bar link, as every logo on the web does. Defaults to `"/"`; set it
+     * when your home screen lives elsewhere. It's an ordinary link, so the
+     * usual rules apply: a home that is already open in the stack — its first
+     * panel, usually — is returned to, closing nothing, and one that isn't is
+     * opened the way a nav item would be. Routed mode only.
+     */
+    home?: string;
+    /**
+     * The app's own chrome, at the trailing end of the top bar: an account
+     * button, a global search box, a settings menu. It may grow into the bar's
+     * free space (so a search box is at home here); the title truncates before it
+     * gives any of it back.
+     *
+     * In routed mode a narrow shell hands this slot to the current panel's
+     * {@link Panel.actions} whenever it has any — on a phone the screen's own
+     * verbs win the space — and keeps the app's menu for the screens that
+     * declare none.
+     */
     menu?: Slot;
     /**
-     * The scrollable page content. A string is rendered as rich text.
+     * The scrollable panel content. A string is rendered as rich text.
      * Mutually exclusive with {@link MainOptions.routes}.
      */
     content?: Slot;
     /**
      * Paths mapped to the functions that draw them, which hands navigation over
      * to the shell. Each route draws one screen of your app, called a panel, and
-     * as many panels as fit are shown at a time: one at a time on a phone,
+     * as many columns as fit are shown at a time: one at a time on a phone,
      * several side by side on a wider screen. Mutually exclusive with
      * {@link MainOptions.content}.
      *
@@ -31,7 +74,7 @@ export interface MainOptions<R = Routes> {
      * string, so it has to come last and needs at least one segment to match.
      * The first key that matches wins, a segment a param refuses falls through
      * to a later route (or to {@link MainOptions.notFound}), and each handler's
-     * `$page.params` is typed from its own key.
+     * `$panel.params` is typed from its own key.
      *
      * `integer` accepts only spellings that survive a round trip back to the
      * same URL, so `/tasks/0042` is not a second path for `/tasks/42`. Ids that
@@ -39,26 +82,38 @@ export interface MainOptions<R = Routes> {
      *
      * Navigating is just links: the shell handles the clicks itself, so do *not*
      * also call Aberdeen's `interceptLinks()`. A link opens its target on top of
-     * the panel it sits in, closing anything that was above it first, unless it
-     * carries `data-panel=replace`, which replaces its own panel instead. A link
-     * to something already open goes back to it rather than opening it twice.
-     * From code, use {@link panels} (`S.panels.push()` and friends): navigating
-     * with `aberdeen/route`'s own `go()` works and still asks the panels'
-     * {@link Page.requestClose}, but builds the whole stack from the path. A
-     * navigation guard the app registered before mounting (an auth redirect,
-     * say) keeps working: the shell asks it first, and puts it back when the
-     * shell goes away.
-     *
-     * The shell draws no back arrows and no ✕ of its own: **every panel provides
-     * its own way out**, with `S.box`'s `close` option for a ✕, or
-     * {@link Page.close} behind a Cancel button. Escape and the browser's back
-     * button are the shell's contribution.
-     *
-     * Only one routed shell can be mounted at a time (a second one throws),
-     * which is what lets {@link panels} be a plain module-level object. Each
-     * handler still gets its own `$page` rather than there being one global
-     * "current page", since several panels are alive at once. It's that argument
-     * that carries the per-route typing of `params`.
+     * the panel it sits in, closing everything after that panel first. The
+     * `data-panel` attribute picks another of the three {@link PanelStack}
+     * navigations instead: `replace` puts the target in place of the link's own
+     * panel, and `open` leaves that panel behind and gives the target its own
+     * stack, the way a nav item does. A link
+     * to something already open goes back to it rather than opening it twice —
+     * a move along the stack that closes nothing: the panels right of it stay
+     * open, parked past the viewport's right edge, until a *new* panel prunes
+     * them (pinned panels excepted — see {@link Panel.pinned}).
+     * From code, use {@link pushPanel} and friends: navigating
+     * with `aberdeen/route`'s own `go()` works too — a panel with
+     * {@link Panel.unsaved} work still survives it — but builds the whole stack
+     * from the path. A navigation guard the app registered with
+     * `route.setGuard` (an auth redirect, say) keeps working: the shell
+     * registers none of its own.
+     *
+     * **A panel declares its chrome; the shell places it.** A panel says what it
+     * is called ({@link Panel.title} — unset, its first line of text stands in)
+     * and what it can do ({@link Panel.actions}); everything else in a column is
+     * the panel's own content, boxes included. The shell writes the stack of
+     * open panels as breadcrumbs in the top bar — click one to go back to it,
+     * closing nothing — and places each panel's actions where the room is: on
+     * its own column while several fit, in the bar once the shell is narrow and
+     * the current panel *is* the screen. Nothing in an app measures the
+     * viewport to lay its screens out twice.
+     *
+     * Only one routed shell can be mounted at a time (a second one throws) —
+     * the URL is global, so two of them would fight over it. Nothing else is:
+     * the {@link PanelStack} belongs to its shell, which hands it back, and
+     * each handler gets its own `$panel` rather than there being one global
+     * "current panel", since several panels are alive at once. It's that
+     * argument that carries the per-route typing of `params`.
      *
      * @example
      * ```ts
@@ -66,39 +121,78 @@ export interface MainOptions<R = Routes> {
      *   title: "Trackle",
      *   nav: { items: [{ label: "Projects", href: "/projects" }] },
      *   routes: {
-     *     "/projects": ($page) => { $page.title = "Projects"; drawProjects(); },
-     *     "/projects/[id]": ($page) => drawProject($page.params.id),  // typed string
+     *     "/projects": ($panel) => { $panel.title = "Projects"; drawProjects(); },
+     *     "/projects/[id]": ($panel) => drawProject($panel.params.id),  // typed string
      *   },
-     *   notFound: ($page) => S.box({ header: "Not found", content: $page.path }),
+     *   notFound: ($panel) => S.box({ header: "Not found", content: $panel.path }),
      * });
      * ```
      */
     routes?: R;
     /**
      * Draws the panel for a path none of the routes match. There are no params
-     * to go with it, so `$page.params` is empty; the path itself is in
-     * `$page.path`.
+     * to go with it, so `$panel.params` is empty; the path itself is in
+     * `$panel.path`.
      */
     notFound?: RouteHandler<{}>;
     /**
-     * Set `false` to show only the top panel, however wide the screen (the nav
-     * sidebar still sits beside it). Everything else behaves the same: the URL,
-     * the back button, `requestClose`, and the panels' own close buttons. This
-     * only changes how many you see. Defaults to `true`.
+     * What to open **beneath** a path that arrives cold — a shared link, a
+     * bookmark, a push notification, a nav item — with no stack of its own to
+     * restore. Keyed by path template exactly like {@link MainOptions.routes}, so
+     * each entry gets that key's params, matched and typed, rather than taking
+     * the path apart a second time.
+     *
+     * Without this, the stack is derived from the path: every prefix that has a
+     * route becomes a column, so `/projects/7/tasks/42` opens three deep. That
+     * only works for URLs that spell their own context out. A flat one —
+     * `/thread/[id]`, where a notification lands — has no prefix to walk, so it
+     * opens as a single column with nothing under it and nothing to close back
+     * to. This is where you say what that context is:
+     *
+     * ```ts
+     * S.main({
+     *   routes: {
+     *     "/mailbox/[id]": drawMailbox,
+     *     "/thread/[id=integer]": drawThread,
+     *   },
+     *   ancestors: {
+     *     "/thread/[id=integer]": ({ id }) => [`/mailbox/${mailboxOf(id)}`],  // id: number
+     *   },
+     * });
+     * ```
+     *
+     * Return the paths shallowest first; the path itself goes on top. Return
+     * nothing to leave a path to the prefix derivation, which is also what an
+     * unlisted one gets — so you only list the routes whose URL doesn't say where
+     * it belongs. Paths you have no route for are skipped, as they are there.
+     *
+     * This is asked for every origin-less navigation, so a nav item and a fresh
+     * tab still land on the same columns; a link *inside* a panel builds on that
+     * panel instead and never asks. It's consulted while the navigation is
+     * still being worked out — before any route handler runs — so it has to
+     * answer without drawing anything. From code,
+     * {@link PanelStack.openPanelStack} takes the same list directly.
+     */
+    ancestors?: AncestorTable<NoInfer<R>>;
+    /**
+     * Set `false` to show only the current panel, however wide the screen (the
+     * nav sidebar still sits beside it). Everything else behaves the same: the
+     * URL, the back button, unsaved panels, and the panels' own close buttons.
+     * This only changes how many you see. Defaults to `true`.
      */
     stacking?: boolean;
     /** Footer content, pinned below the scroll area. */
     footer?: Slot;
     /**
-     * Max width for the page's *content*, e.g. `"60rem"`. The header and footer
+     * Max width for the panel's *content*, e.g. `"60rem"`. The header and footer
      * backgrounds still span the full shell width, but their contents — and the
      * sidebar + separator + content trio (or just the content when there's no
      * sidebar) — cap to this width and centre horizontally. When unset, everything
-     * fills the available width. Either way the content shares the page surface —
+     * fills the available width. Either way the content shares the panel surface —
      * it is not boxed.
      *
      * Ignored when you pass {@link MainOptions.routes}: there the open panels
-     * decide the width (see {@link Page.layout}), and the header and footer line
+     * decide the width (see {@link Panel.maxWidth}), and the header and footer line
      * themselves up with them.
      */
     maxWidth?: string;
@@ -107,28 +201,27 @@ export interface MainOptions<R = Routes> {
     /** Aberdeen attr/style string applied to the top bar. */
     topbarAttrs?: Attributes;
     /**
-     * Navigation menu. When provided, renders a sidebar (in `"left"` / `"right"`
-     * mode) or a button+dropdown (in `"button"` mode). The sidebar automatically
-     * collapses to a button when the shell is too narrow — which there opens the
-     * nav as a full page sliding in from the left, not as a dropdown.
+     * Navigation menu, rendered as a sidebar beside the content. The sidebar
+     * collapses to a ☰ in the top bar when the shell is narrow, and there it
+     * opens the nav as a full panel sliding in from the left, not as a dropdown.
      *
      * `items` may be a reactive array: the shell reads it inside the sidebar's own
      * scope, so an item arriving or leaving redraws the sidebar and nothing else.
-     * The content beside it — in routed mode, the whole panel stack — is left
-     * alone.
+     * The content beside it — in routed mode, the whole stack — is left
+     * alone. `button` customizes the ☰; `dropdownAttrs` does nothing here, since
+     * a collapsed nav is a panel rather than a dropdown.
      */
     nav?: MenuOptions;
     /**
-     * Where to render the nav. Defaults to `"left"`.
-     * - `"left"` / `"right"`: sidebar next to the content area; collapses to a
-     *   button in the top bar when the shell width drops below 640 px.
-     * - `"button"`: always a button, never a sidebar.
-     *
-     * The button opens a dropdown on a wide shell, and — below 640 px — a
-     * full-page nav that slides in from the left, handing over to the chosen
-     * screen with a matching slide in from the right.
+     * Which side the nav sidebar sits on. Defaults to `"left"`.
+     *
+     * Either way it collapses to a ☰ in the top bar once the shell width drops to
+     * 640 px or below — the one threshold everything else keys off too, which is
+     * why there is no "always a button" mode: it would make "narrow" and "the nav
+     * is collapsed" two different things, and every rule about where a panel's
+     * chrome goes assumes they are one.
      */
-    navPosition?: "left" | "right" | "button";
+    navPosition?: "left" | "right";
     /** Aberdeen attr/style string applied to the sidebar nav panel. */
     navAttrs?: Attributes;
     /** Aberdeen attr/style string applied to the narrow-screen full-page nav. */
@@ -136,23 +229,27 @@ export interface MainOptions<R = Routes> {
 }
 /**
  * An application shell that wires up the things almost every app needs: a sticky
- * top bar (icon, title, subtitle, action menu), a scrollable content area, and a
+ * top bar (logo, title, action menu), a scrollable content area, and a
  * footer. With {@link MainOptions.maxWidth} the content area is centred and its
- * width capped. Add a `nav` to get a responsive sidebar (auto-collapses to a
- * menu button below 640 px, or always a button with `navPosition: "button"`).
- * Below 640 px that button opens the nav as a full page sliding in from the
+ * width capped. Add a `nav` to get a sidebar that collapses to a ☰ in the top bar
+ * below 640 px, which there opens the nav as a full panel sliding in from the
  * left; picking an item slides it away as the chosen screen enters from the
  * right.
  *
  * Instead of a single `content` slot, pass {@link MainOptions.routes} and the
  * shell takes over navigation: each route draws one screen, called a panel,
- * and as many panels as fit are shown at a time, side by side on a wide screen
- * and one at a time on a phone. See {@link MainOptions.routes} and {@link Page}.
+ * and as many columns as fit are shown at a time, side by side on a wide screen
+ * and one at a time on a phone. Each panel *declares* its chrome — its
+ * {@link Panel.title} and its {@link Panel.actions} — and this shell places it:
+ * the stack of titles as breadcrumbs in the bar, the actions on the panel's
+ * column while several fit and in the bar once the shell is narrow enough
+ * that the current panel is the whole screen. See {@link MainOptions.routes} and
+ * {@link Panel}.
  *
  * @example
  * ```ts
  * S.main({
- *   icon: "✦",
+ *   logo: "✦",
  *   title: "Staffa Demo",
  *   maxWidth: "56rem",
  *   nav: {
@@ -172,4 +269,30 @@ export interface MainOptions<R = Routes> {
  * }
  * ```
  */
-export declare function main<R extends RouteTable<R>>(opts?: MainOptions<R>): void;
+export declare function main<R extends RouteTable<R>>(opts: MainOptions<R> & {
+    routes: object;
+}): PanelStack;
+export declare function main(opts?: MainOptions<{}> & {
+    routes?: undefined;
+}): void;
+/**
+ * Close the navigation, if it's showing as an overlay — the full panel it becomes
+ * on a narrow shell. A sidebar isn't an overlay and has nothing to dismiss, so
+ * on a wider shell this does nothing.
+ *
+ * A navigation closes the nav by itself, links in your own custom rows included,
+ * so this is for the items that *don't* navigate — one that opens a dialog, or
+ * flips a setting, and should still get the nav out of the way.
+ *
+ * @example
+ * ```ts
+ * S.main({
+ *   nav: { items: [
+ *     { label: "Inbox", href: "/inbox" },
+ *     () => S.button({ content: "New message", click: () => { S.closeNav(); compose(); } }),
+ *   ]},
+ *   routes: { ... },
+ * });
+ * ```
+ */
+export declare function closeNav(): void;