staffa 0.7.4 → 0.8.1

package/dist/components/menu.js

@@ -1,7 +1,17 @@
 import A from "aberdeen";
 import { matchCurrent } from "aberdeen/route";
 import { drawSlot, mountPortal, focusFirst } from "../core.js";
+import { mk } from "../icons-helpers.js";
 import { button } from "./button.js";
+// The two glyphs the shell draws for itself. As inline SVG (built with the icon
+// set's own helper, so no icon data is pulled in) rather than the `☰`/`✕`
+// characters: a text glyph is at the mercy of the system font, and next to a real
+// icon it lands thin and undersized. These match Lucide's `menu` and `x` exactly,
+// so a nav trigger sits beside app icons as an equal.
+/** `☰` — opens a menu or the nav. */
+export const menuGlyph = mk('<path d="M4 6h16"/><path d="M4 12h16"/><path d="M4 18h16"/>');
+/** `✕` — dismisses what the {@link menuGlyph} opened. */
+export const closeGlyph = mk('<path d="M18 6 6 18"/><path d="m6 6 12 12"/>');
 // Styles shared by the floating dropdown and the sidebar nav, so both look
 // identical. The item styles aren't scoped to a container, so `drawMenu` can
 // render its items into either one.
@@ -20,7 +30,12 @@ A.insertGlobalCss({
         "font-size:0.9em border:0 background:transparent fg:$s-text text-decoration:none " +
         "transition: color 0.12s, transform 0.12s, text-shadow 0.12s;",
     ".s-menu-item:focus-visible:not([aria-current=page]), .s-menu-item:hover:not([aria-disabled=true]):not([aria-current=page])": "filter:none color: color-mix(in lab, $s-primary 33%, $s-text);",
-    ".s-menu-item[aria-current=page]": "text-shadow: 0 0 2px $s-primary; color: color-mix(in lab, $s-primary 50%, $s-text); filter:brightness(1.15)",
+    // The active row is simply drawn in the surface's accent — the brand colour on a
+    // neutral surface, the ink on an accent one. No glow and no brightening: those
+    // pushed it off the brand colour, so it read as a lit-up variant of it rather
+    // than as the colour itself. `filter:none` keeps the global `a:hover` brighten
+    // off it too, since the hover rule above deliberately skips the active row.
+    ".s-menu-item[aria-current=page]": "color:$s-accent filter:none",
     ".s-menu-item[aria-disabled=true]": "opacity:0.45 cursor:not-allowed pointer-events:none",
     ".s-menu-icon": "flex-shrink:0",
     // A soft hairline that fades out at both ends, rather than a hard full-width
@@ -116,9 +131,22 @@ function closeFloating() {
  * Whether a floating menu is currently open. Reflects live state (cleared the
  * instant it closes), unlike the DOM — the panel lingers briefly while its
  * `destroy=` transition plays out.
+ *
+ * @param anchor When given, only reports `true` for a menu opened from *this*
+ *   anchor — so a component can ask about its own menu rather than any menu.
+ */
+export function isFloatingMenuOpen(anchor) {
+    const opts = $floating.opts;
+    return opts != null && (anchor == null || opts.anchor === anchor);
+}
+/**
+ * Close the open floating menu (if any), returning focus to its anchor. With an
+ * `anchor`, only closes when the open menu belongs to it, so dismissing your own
+ * menu can't steal someone else's.
  */
-export function isFloatingMenuOpen() {
-    return $floating.opts != null;
+export function closeFloatingMenu(anchor) {
+    if (isFloatingMenuOpen(anchor))
+        closeFloating();
 }
 function positionMenu(menuEl, rect) {
     const mw = menuEl.offsetWidth, mh = menuEl.offsetHeight;
@@ -267,7 +295,7 @@ export function menuButton(opts) {
     A.clean(() => { if ($floating.opts?.anchor === myEl)
         closeFloating(); });
     button({
-        icon: () => A("span aria-hidden=true #☰"),
+        icon: () => menuGlyph({ size: "1.4em" }),
         // Only label the trigger "Open menu" when it has no visible text of its
         // own — an aria-label would otherwise *hide* that text from AT.
         ...(opts.button?.content == null ? { ariaLabel: "Open menu" } : null),

package/dist/components/panels.d.ts

@@ -0,0 +1,392 @@
+/**
+ * Routed, multi-column panel navigation for {@link main}.
+ *
+ * Each route draws one screen of the app, called a panel, and as many panels as
+ * fit are shown at a time. On a phone that is one, so a link opens a new panel
+ * on top and closing it brings the previous one back. On a wider screen the
+ * panels that would have covered each other sit side by side instead, oldest on
+ * the left. The app's own code is the same either way.
+ *
+ * Navigation runs through `aberdeen/route`: the URL holds the top panel, and
+ * the ones beneath it are stored beside it in the history entry. So back and
+ * forward step through whole arrangements of columns, and a reload (or a shared
+ * link) brings the same columns back.
+ */
+/** Flattens an intersection into a single object type, so hovers read nicely. */
+type Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+/**
+ * What a `[name=matcher]` matcher name yields. An unrecognised name resolves to
+ * `never`, which shows up as an unusable param at the handler rather than
+ * quietly typing as `string` (the route key itself throws at mount time).
+ */
+export type MatcherType<M extends string> = M extends "integer" ? number : never;
+/**
+ * The params contributed by a single path-template segment: `[x]` a string,
+ * `[x=integer]` a number, `[...x]` the rest of the path as one raw string.
+ */
+export type SegParams<S extends string> = S extends `[...${infer Name}]` ? {
+    [K in Name]: string;
+} : S extends `[${infer Name}=${infer Matcher}]` ? {
+    [K in Name]: MatcherType<Matcher>;
+} : S extends `[${infer Name}]` ? {
+    [K in Name]: string;
+} : {};
+/**
+ * The params object described by a path template, e.g.
+ * `PathParams<"/projects/[id]/tasks/[taskId=integer]">` is
+ * `{ id: string; taskId: number }`.
+ */
+export type PathParams<P extends string> = P extends `${infer Head}/${infer Rest}` ? SegParams<Head> & PathParams<Rest> : SegParams<P>;
+/** A panel draw function: it receives the panel's {@link Page} and draws into the current scope. */
+export type RouteHandler<P = any> = (page: Page<P>) => void;
+/**
+ * A route table: path templates mapped to panel draw functions. Used as the
+ * loose (non-inferred) type; `S.main()` infers a more precise type from the
+ * literal you pass, so each handler's `$page.params` is typed per its key.
+ */
+export type Routes = Record<string, RouteHandler>;
+/**
+ * The shape `S.main()`'s `routes` option is checked against: every key types its
+ * own handler's `params`. Used as a self-referential generic constraint, which
+ * is what makes `$page.params` infer from the route key.
+ */
+export type RouteTable<R> = {
+    [K in keyof R & string]: (page: Page<Prettify<PathParams<K>>>) => void;
+};
+/**
+ * What a route handler gets: the params from its route, plus everything the
+ * shell needs to know about the panel it is drawing. It's an Aberdeen proxy, so
+ * you can set things later, such as a `title` that arrives with your data or
+ * `loading` going back to `false`, and the shell keeps up.
+ *
+ * Search params and the `#hash` belong to the top panel only. A panel with
+ * another one on top of it keeps just its path, so anything a panel needs in
+ * order to redraw itself has to live in that path.
+ */
+export interface Page<P = Record<string, string | number | string[]>> {
+    /**
+     * The params matched from this panel's path, typed per its route key:
+     * `[x]` is a `string`, `[x=integer]` a `number`, `[...x]` a `string`.
+     * Read-only.
+     */
+    readonly params: P;
+    /** This panel's path, e.g. `"/projects/7"`. Read-only. */
+    readonly path: string;
+    /** Shown in `document.title` while this panel is top-most. */
+    title?: string;
+    /**
+     * How much room this panel takes. The content area is the page, at most
+     * 1280px wide, minus the nav sidebar; the widths below assume a sidebar of
+     * around 170px, so without one add that back.
+     *
+     * - `"small"` is 360 to 540px once two panels fit side by side, which is
+     *   what makes it right for lists, detail forms, and anything else that
+     *   reads well at phone width. Below that it takes the whole content area
+     *   (so up to ~730px), like a medium does. A lone small leaves its other
+     *   half empty, and that is exactly where the next small lands, without
+     *   anything on screen moving.
+     * - `"medium"` (the default) takes the whole content area: up to ~1100px,
+     *   and the screen width on a phone. The safe default for ordinary screens.
+     *   Nothing fits beside a medium on a standard 1280px page, though on a wide
+     *   enough window a small still can.
+     * - `"large"` takes the whole window, with no upper limit (~1750px on a
+     *   1920px screen): for boards, wide tables and dense dashboards. While it's
+     *   open the whole shell (top bar, content and footer) stretches to the
+     *   screen edges rather than stopping at 1280px.
+     *
+     * When more columns fit than the standard page holds (three smalls, or a
+     * medium and a small) the page itself grows, staying centred, to hold them.
+     *
+     * A panel's width depends only on the size of the window, never on what else
+     * is open, so opening or closing a panel never resizes the ones already on
+     * screen.
+     *
+     * The panel is sized from this **before** your handler runs, so anything that
+     * measures its own box has a real one from the first frame. What it is sized
+     * at is whatever this says at that moment, which for a brand-new panel is the
+     * default: a handler that *assigns* `layout` is drawn at the medium width and
+     * reflowed immediately after — in time for the frame, but not for a
+     * measurement taken in the same breath.
+     *
+     * Assigning it later works just as well. When your data arrives and you find
+     * you want the wide one, the panel reflows to its new width without being
+     * redrawn — so nothing in it is rebuilt or loses its state — and the columns
+     * beside it move over.
+     */
+    layout?: "small" | "medium" | "large";
+    /**
+     * Set this while you're fetching what the panel needs, and back to `false`
+     * when you're done. A new panel waits a moment before sliding in, so it can
+     * arrive with real content instead of empty; if the wait drags on it slides
+     * in anyway and shows a loading indicator until the flag clears. It only
+     * affects the animation; the stack, the URL and `requestClose` never wait
+     * for it.
+     */
+    loading?: boolean;
+    /**
+     * Your chance to say no. Everything that would close this panel waits for
+     * it: Escape, the panel's own ✕ or Cancel button ({@link Page.close}, or a
+     * box with `close: true`), the browser's back button, a link that would
+     * close it, and {@link panels}.`close()`. Return `false` to keep the panel
+     * open, usually after a dirty check and a {@link confirm}.
+     */
+    requestClose?: () => boolean | Promise<boolean>;
+    /**
+     * Closes **this** panel, wherever it sits in the stack. The top panel goes
+     * back to whatever was underneath it; any other panel is taken out on its
+     * own, leaving the columns to its right where they are, with their state,
+     * and the URL alone, since the top panel didn't move. Either way it
+     * becomes a history entry, so the browser's back button brings it back.
+     *
+     * Resolves `false` if the panel didn't close: {@link Page.requestClose} said
+     * no, it was the only panel on the stack (so there's nothing to go back to),
+     * or another navigation got there first. The shell draws no back arrows or
+     * ✕ of its own, so this (or `S.box`'s `close` option) is how a panel gives
+     * the user a way out.
+     *
+     * @example
+     * ```ts
+     * S.button({ content: "Cancel", attrs: ".neutral", click: () => void $page.close() });
+     * ```
+     */
+    close(): Promise<boolean>;
+}
+/** Options the panel stack needs from its shell. */
+export interface PanelStackOptions {
+    routes: Routes;
+    notFound?: RouteHandler<{}>;
+    /** Set `false` to show only the top panel, however much room there is. */
+    stacking?: boolean;
+    /** The shell's own title, used as the suffix of `document.title`. */
+    title?: unknown;
+}
+export declare class PanelController {
+    private compiled;
+    private opts;
+    /** The live stack, shallow-to-deep. Closing panels are no longer part of it. */
+    private live;
+    private byId;
+    private nextId;
+    /** Drives rendering: panel id → its `order` (used only as the sort key). */
+    $ids: Record<string, number>;
+    /**
+     * The live stack's paths and its top panel, for reactive readers: the
+     * `document.title` watcher, `main()`'s Escape handling and `S.panels.stack`.
+     */
+    $state: {
+        paths: string[];
+        topId: number;
+    };
+    private containerEl?;
+    /** The shell's measurements, shared by everything drawn since they were taken. */
+    private geom?;
+    /** The body width at the last layout; a change means a window resize → snap. */
+    private lastBodyW;
+    private layoutQueued;
+    private timers;
+    constructor(opts: PanelStackOptions);
+    /** Resolve a path to its route handler + params, falling back to `notFound`. */
+    private resolve;
+    private matches;
+    /**
+     * The one derivation rule for origin-less navigation (§2.8): probe every
+     * prefix of the path against the route table; the matching prefixes become
+     * the stack. Prefixes without a route are simply skipped, so an app that
+     * doesn't want one screen stacked under another just doesn't route that
+     * prefix. The path itself is always the top panel, matched or not.
+     */
+    deriveStack(path: string): string[];
+    /** The stack a route implies: its snapshot topped by its path, or — without a snapshot — derived. */
+    private targetFor;
+    /** The stack the current history entry asks for. Subscribes to path + snapshot. */
+    private computeTarget;
+    /**
+     * The route guard (see `route.setGuard` in the constructor): asked before any
+     * route change lands, wherever it came from. Runs the {@link Page.requestClose}
+     * guard of every panel the new route's stack would remove — a set defined by
+     * the target (the commit reconciles by path), so a derived stack that shares
+     * nothing with the live one still asks exactly the panels that are closing.
+     */
+    private checkChange;
+    private paths;
+    /** The live panels a target stack drops — by path, so a splice removes only its own column. */
+    private removedBy;
+    /**
+     * Adopt a stack proposed by the URL. Close guards have already been run (and
+     * have passed) by the time a route change is visible here — `checkChange` is
+     * consulted by the router itself, before anything is applied.
+     */
+    private propose;
+    /**
+     * Apply a target stack: unmount what's gone, mount what's new, animate the
+     * difference.
+     *
+     * Reconciliation is BY PATH (a stack can't hold the same path twice, so that's
+     * well-defined): a panel present in both stacks stays mounted *even if its
+     * index shifted*, which is what lets a panel be spliced out of the middle
+     * (§7) without disturbing the columns above it. A common-prefix diff would
+     * remount every one of them, throwing away exactly the scroll and form state
+     * rule 5 promises to keep.
+     */
+    private commit;
+    private createEntry;
+    /**
+     * Take a panel out of the shell. The *scope* goes now: its cleaners run this
+     * tick, so whatever the panel registered with `A.clean` — subscriptions,
+     * timers, an open portal — is torn down when the panel closes, not when its
+     * animation is over. Only the element lingers, to play that animation, which
+     * is what the `destroy=` hook in `drawPanel` is for: Aberdeen hands the
+     * element to {@link playExit} instead of removing it.
+     */
+    private beginClose;
+    /**
+     * A closed panel's send-off, run by Aberdeen once the panel's scope is gone (so
+     * the content it shows is frozen, which is exactly what a departing column
+     * should be): it fades where it stands, inert, and leaves the DOM when the fade
+     * itself ends. Removing it on a fixed timer instead would race the transition —
+     * pull the element a frame early and the panel appears to fade half-way and
+     * then vanish. The timeout is just a fallback for when no `transitionend` is
+     * coming at all (transitions off, or an element that never got placed).
+     */
+    private playExit;
+    /**
+     * Navigate back to a stack that is a truncation of the current one — the shared
+     * implementation of Escape, a page closing itself, return-links and
+     * `S.panels.close()`. `route.back()` prefers the history entry where that
+     * panel was on top (with its scroll state intact); when there is no such entry
+     * it replaces the current one, carrying the snapshot passed as the fallback.
+     * Either way the route guard asks the closing panels first, and the returned
+     * promise reports its verdict.
+     */
+    private goBackTo;
+    /** Close every panel above `index` (guarded). Resolves `false` when vetoed. */
+    closeDownTo(index: number): Promise<boolean>;
+    /** Guarded close of the top panel. */
+    closeTop(): Promise<boolean>;
+    /**
+     * Guarded close of the panel at `index`, top of the stack or not — what a
+     * page's own close affordances ({@link Page.close}, a box's ✕) come down to.
+     *
+     * The top panel pops back to the snapshot beneath it. Any other panel is
+     * *spliced* out: its guard runs, the columns above it keep their place and
+     * state (the commit reconciles by path), and the URL doesn't change, since the
+     * top panel didn't. That still gets its own history entry, so the browser's
+     * back button restores the closed column like any other snapshot — which is
+     * why it goes through `route.go` here rather than through `navigate()`, whose
+     * "link to the panel we're already on" check would see a no-op.
+     */
+    closePanelAt(index: number): Promise<boolean>;
+    /** Guarded close of whichever panel `path` is open as. False when it isn't open. */
+    closeByPath(path: string): Promise<boolean>;
+    /** Guarded close of the panel whose `.s-panel` element this is. */
+    closePanelEl(el: HTMLElement): Promise<boolean>;
+    /**
+     * Navigate to `href`. `originIndex` is the depth of the panel the link lives
+     * in (−1 when it has none — a nav item or a programmatic call, which derives
+     * the whole stack instead). `replace` swaps the originating panel rather than
+     * stacking on top of it.
+     */
+    navigate(href: string, originIndex: number, replace?: boolean): void;
+    /** Programmatic push/replace, with the top panel as the implied origin. */
+    pushPath(path: string, replace: boolean): void;
+    /**
+     * Link handling through `route.interceptLinks()`, whose handler hook hands us
+     * the anchor so we can decide what the click *means*: the originating
+     * `.s-panel` (which decides what the click truncates), `data-panel=replace`,
+     * and return-to-an-open-panel semantics. The exclusion rules (targets,
+     * downloads, modified clicks, external URLs) live in Aberdeen; the close
+     * guards run in `checkChange` when our navigation reaches the router.
+     */
+    private interceptLinks;
+    /** `"<page title> · <app title>"`, kept in sync with the top panel. */
+    private watchTitle;
+    /**
+     * Draw the panel viewport into the current element. Called by `main()`.
+     *
+     * There is deliberately no close chrome here — no back rail, no ←: pages
+     * provide their own way out (see {@link Page.close} and `S.box`'s `close`
+     * option). The shell contributes Escape and the browser's own back button.
+     */
+    drawStack(): void;
+    private drawPanel;
+    scheduleLayout(): void;
+    /**
+     * Measure the shell, and with it the width the window gives a panel of each
+     * layout. Measured on the *shell*, not on the panel region: the region's width
+     * is the layout engine's own output, so reading it back would nail the layout
+     * to whatever it happened to be a frame ago. Fractional widths throughout — a
+     * rounded column edge would drift a pixel away from the chrome above it.
+     *
+     * `undefined` while the shell has no width to speak of (it isn't in a document
+     * yet, or it's `display:none`); the next pass tries again.
+     */
+    private measure;
+    /**
+     * The measurements this pass runs on. Taken once per layout pass and per
+     * commit, and shared with the panels drawn in between — they all size
+     * themselves against the same shell, and a `getBoundingClientRect()` each
+     * would be a forced reflow each, in the middle of building their DOM.
+     */
+    private geometry;
+    /** How wide a panel of this layout is, right now; 0 while the shell can't be measured. */
+    private roomFor;
+    /**
+     * Size and position every panel, and publish the width of the whole ensemble
+     * (sidebar + separator + columns) for the shell to centre itself on.
+     *
+     * This is everything CSS can't work out for itself: which panels exist, which
+     * of them are visible, how wide each one is and where it sits. All the motion
+     * between two of these arrangements is CSS's job.
+     */
+    private layout;
+    /** Let a `loading` panel's enter animation wait — but not indefinitely. */
+    private holdEnter;
+}
+/**
+ * Navigating the routed `S.main()` shell from code, for the times it isn't a
+ * link click, such as opening the screen for a record you just created.
+ *
+ * The same rules as a link click apply: pushing a path that is already open
+ * goes back to it rather than opening it twice, and anything that would close a
+ * panel asks its {@link Page.requestClose} first.
+ *
+ * @example
+ * ```ts
+ * S.button({ content: "New task", click: async () => {
+ *   const task = await createTask();
+ *   S.panels.push(`/tasks/${task.id}`);
+ * }});
+ * ```
+ */
+export declare const panels: {
+    /** Opens `path` in a new panel on top of the top one. */
+    push(path: string): void;
+    /**
+     * Opens `path` in place of the top panel, which closes (asking its
+     * {@link Page.requestClose} first). The panels beneath it stay as they are.
+     */
+    replace(path: string): void;
+    /**
+     * Closes the top panel, or, given a `path`, whichever panel is open at it,
+     * asking {@link Page.requestClose} first. A panel that isn't on top is taken
+     * out on its own, leaving the columns to its right exactly as they are.
+     *
+     * Resolves `false` if the panel didn't close: `requestClose` said no, `path`
+     * isn't open, or another navigation got there first.
+     */
+    close(path?: string): Promise<boolean>;
+    /** The paths of the open panels, oldest first. Reactive: safe to read in a scope. */
+    readonly stack: readonly string[];
+};
+/**
+ * Closes the panel `el` sits in, working out which one that is from the DOM.
+ * That is what lets a close button work without being handed a `$page`, from
+ * any column, whether or not it is on top. Used by `S.box`'s `close: true`.
+ *
+ * Outside a routed shell (or outside any panel, such as a box in a dialog) there is
+ * nothing to close: it warns and resolves `false`.
+ */
+export declare function closeContainingPanel(el: Element | null | undefined): Promise<boolean>;
+export {};