staffa 0.13.0 → 0.15.0

package/dist/components/panels.d.ts

@@ -4,20 +4,24 @@ import { type Slot } from "../core.js";
  * Routed, multi-column panel navigation for {@link main}.
  *
  * Each route draws one screen of the app, called a *panel*. The open panels
- * form a **stack**, and one of them is the **current** panel: the one the URL
+ * form a **stack**, whose last panel is the **current** one: the panel the URL
  * names, and the rightmost column on screen. As many panels as fit are shown,
  * ending at the current one — on a phone that is one at a time, on a wider
  * screen the panels that would have covered each other sit side by side
  * instead. The app's own code is the same either way.
  *
- * Going to a panel that is already open — a breadcrumb, or any link to it —
- * just moves the current-panel cursor along the stack: panels right of it stay
- * open, parked past the right edge of the viewport, and nothing closes.
- * Opening a *new* panel is what prunes: everything after the panel it came
- * from closes, except panels the user pinned — which ride along beneath the
- * new panel — and panels holding unsaved work, which no navigation ever tears
- * down. Escape steps one panel left, closing the panel it leaves only when
- * that panel is the stack's discardable end.
+ * Whatever a navigation lands on becomes the top of that stack, and the same
+ * path is never in it twice. Opening a new panel closes everything after the
+ * panel it came from; a plain link to a panel that is already open — a
+ * breadcrumb, a nav item for the section you are in — returns to its own
+ * place, closing whatever was stacked on top, while a `replace` or `open`
+ * applies its usual shape, the open panel moving into it alive.
+ * Two kinds of panel survive that: the ones the user pinned, which ride along,
+ * and the ones holding unsaved work, which no navigation ever tears down.
+ * Those wait parked out of sight past the rightmost column, which is the only
+ * way a panel ever sits *after* the current one. Escape closes the current
+ * panel — or just steps left, when it holds unsaved work or panels sit parked
+ * beyond it.
  *
  * Navigation runs through `aberdeen/route`: the URL holds the current panel,
  * and the rest of the arrangement — the panels before it, the ones parked
@@ -83,6 +87,14 @@ export type AncestorsHandler<P = any> = (params: P, path: string) => readonly st
 export type AncestorTable<R> = {
     [K in keyof R & string]?: (params: Prettify<PathParams<K>>, path: string) => readonly string[] | undefined | void;
 };
+/**
+ * How wide a panel asks to be — a ceiling the shell never exceeds; see
+ * {@link Panel.maxWidth}. `"small"` is the column the content area is divided
+ * into; `"medium"` and `"large"` are two and three of those, and `"none"` is
+ * the whole area. Each is capped at the content area, so on a narrow window
+ * they all come to the same thing.
+ */
+export type PanelSize = "small" | "medium" | "large" | "none";
 /**
  * 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
@@ -153,35 +165,39 @@ export interface Panel<P = Record<string, string | number | string[]>> {
      */
     readonly visible: boolean;
     /**
-     * The widest this panel can usefully be. Every panel must work at 360–540px,
-     * because that is what it gets when two columns fit; this says how much
-     * *more* it can take.
-     *
-     * - `"half"` — nothing more. Half the content area (360px up to half of
-     *   {@link MainOptions.fullWidth}), so a second column fits beside it. For
-     *   lists and detail forms.
-     * - `"full"` (the default) — the whole content area, which is exactly
-     *   {@link MainOptions.fullWidth}: 1080px unless the app says otherwise.
-     * - `"screen"` — the whole window, unbounded: boards, wide tables, dense
-     *   dashboards. While one is open the columns stretch to the screen edges
-     *   instead of stopping at the standard page; the top bar and footer hold
-     *   the standard width throughout.
-     *
-     * Below the width two columns need, everything takes the content area
-     * whatever it asked for. Widths depend only on the window, never on what
-     * else is open, so opening or closing a panel never resizes another.
-     *
-     * This is a *layout regime*, not a width guarantee: handle whatever width
-     * the bucket yields, and ask only for what your content can actually use —
-     * a screen that would cap its own content narrower than its ask is holding
-     * room that would have let another column fit beside it.
+     * The widest this panel can usefully be — a ceiling the shell never
+     * exceeds, so the draw function never has to look right past it. It is
+     * counted in the shell's *columns*: the content area divides into the
+     * narrowest whole number of columns of at least 360px each (three columns
+     * of 360 in a 1080px area, four of 380 in 1520px), and a column is never
+     * wider than 540 — where the area holds just one, a small centres in it
+     * rather than stretching. So an ask never exceeds its column count × 540:
+     *
+     * - `"small"` — one column, never above 540px: lists, detail forms.
+     * - `"medium"` (the default) — two columns, never above 1080px.
+     * - `"large"` — three columns, never above 1620px: wide tables.
+     * - `"none"` — the whole content area, unbounded: boards, dashboards.
+     *   Bound it with the shell's own `maxWidth` where that matters.
+     *
+     * Every size is capped at the content area, so on a phone they all come to
+     * the same thing: one screen at a time. And a width depends only on the
+     * window, never on what else is open, so opening or closing a panel never
+     * resizes another — the run of columns just recentres in the area.
+     *
+     * The ask is a ceiling only; there is no matching floor, since the window can
+     * be any width. Aim your layout at 360px — about the narrowest phone still in
+     * common use — and let it degrade gracefully below that.
+     *
+     * Ask only for what your content can actually use: a panel that would cap
+     * its own content narrower than its ask is holding room that would have
+     * let another column fit beside it.
      *
      * Set it at the top of your handler and the panel is already that wide when
      * you draw (see {@link Panel.width}); set it later — when your data tells you
      * — and the panel reflows without being redrawn, keeping its state, while
      * the columns beside it move over.
      */
-    maxWidth?: "half" | "full" | "screen";
+    maxWidth?: PanelSize;
     /**
      * 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
@@ -192,10 +208,10 @@ export interface Panel<P = Record<string, string | number | string[]>> {
     loading?: boolean;
     /**
      * Keeps this panel from being closed by navigation happening *elsewhere*.
-     * Opening a new panel normally closes everything after the panel it came
-     * from; a pinned panel survives that, staying in the stack — parked past the
-     * right edge of the viewport — slotted in beneath the new panel, one crumb
-     * click away. The user toggles it from the crumb's context menu
+     * A navigation normally closes everything after the panel it came from (or
+     * returned to); a pinned panel survives that, staying in the stack — slotted
+     * in beneath the new panel, or parked out of sight when the new panel was
+     * already beneath it. Either way it is one crumb click away. The user toggles it from the crumb's context menu
      * (right-click or long-press), which is also where the pin shows; setting
      * it from code does the same thing.
      *
@@ -207,12 +223,11 @@ export interface Panel<P = Record<string, string | number | string[]>> {
     /**
      * Set this while the panel holds work that must not be lost — a dirty form,
      * an upload in flight. An unsaved panel cannot be closed, by anything:
-     * navigation that would prune it parks it instead, past the viewport's
-     * right edge, wearing a ● in its crumb — even the browser's back button
-     * only parks it. {@link Panel.close} and the crumb menu's Close refuse,
+     * navigation that would prune it parks it out of sight instead, wearing a
+     * ● in its crumb — even the browser's back button only parks it. {@link Panel.close} and the crumb menu's Close refuse,
      * Escape on it steps left along the stack rather than closing, and closing
-     * the browser tab runs into the browser's own are-you-sure (after which the
-     * shell brings the unsaved panel back on screen).
+     * the browser tab runs into the browser's own are-you-sure, the unsaved
+     * panel brought on screen as the question is raised.
      *
      * Only the app clears it; the user has no toggle. A Save or Discard button
      * clears it and then closes:
@@ -277,6 +292,7 @@ export interface Panel<P = Record<string, string | number | string[]>> {
      */
     open(href: string, how?: "push" | "replace" | "open"): Promise<boolean>;
 }
+export declare const SMALL_MAX_PX = 540;
 /** Options the stack needs from its shell. */
 export interface PanelStackOptions {
     routes: Routes;
@@ -287,8 +303,6 @@ export interface PanelStackOptions {
     columns?: "auto" | "single";
     /** What a bare link does. See {@link MainOptions.linkNavigation}. */
     linkNavigation?: "push" | "replace" | "open";
-    /** How wide a `"full"` panel gets, in px. See {@link MainOptions.fullWidth}. */
-    fullWidth: number;
     /** The shell's own title, used as the suffix of `document.title`. */
     title?: unknown;
     /**
@@ -346,10 +360,10 @@ export interface PanelStack {
      * the new panel).
      *
      * The same rules as a link click apply: pushing a path that is already open
-     * goes back to it — a focus move along the stack, closing nothing — rather
-     * than opening it twice, and a panel holding {@link Panel.unsaved} work is
-     * never closed, only parked. That's what a plain link does, and what
-     * `data-panel=push` says outright.
+     * returns to it — closing whatever was stacked on top — rather than opening
+     * it twice, and a panel holding {@link Panel.unsaved} work is never closed,
+     * only parked. That's what a plain link does, and what `data-panel=push`
+     * says outright.
      *
      * Note that a link builds on the panel it is *drawn in*, which is the
      * current panel only while no column beside it has the focus. Code
@@ -584,19 +598,21 @@ export declare class PanelStackController implements PanelStack {
     private issue;
     private start;
     /**
-     * Make the stack's `index`th panel current: the URL and the visible run move
-     * to it, while the panels right of it stay open, parked past the right edge
-     * of the viewport. Nothing closes; it is a history entry, so the browser's
-     * back button returns the focus to where it was. What a click on a
-     * breadcrumb — any link to an open panel — comes down to.
+     * Make the stack's `index`th panel current without closing anything, leaving
+     * the panels right of it parked out of sight.
+     *
+     * Only ever a step around a panel that refuses to close — nothing else is
+     * left sitting after the current one — so this is Escape's way past an
+     * unsaved panel, and the way back to one. It is a history entry, so the
+     * browser's back button returns the focus to where it was.
      */
     private focusAt;
     /**
      * One step back along the stack — what Escape does (`main()` calls this;
-     * it is not {@link PanelStack} API). At the stack's end this closes the
-     * current panel; mid-stack — with panels parked to the right — or when the
-     * panel holds {@link Panel.unsaved} work, the panel stays open and the
-     * focus just moves to the panel on its left, parking the one it leaves.
+     * it is not {@link PanelStack} API). Normally that closes the current panel,
+     * which is the stack's end. When it holds {@link Panel.unsaved} work — or
+     * panels sit parked beyond it — it stays open instead, and the focus
+     * simply moves to the panel on its left.
      * Resolves `false` at the stack's start, where there is no left to go.
      */
     back(): Promise<boolean>;
@@ -632,11 +648,14 @@ export declare class PanelStackController implements PanelStack {
      * that know it.
      *
      * `how` is the link's `data-panel` attribute (or the caller's word for
-     * it): absent — like a link without the attribute — it is the shell's
-     * `linkNavigation` default, an unrecognised value is a push on top of
-     * `from`, `"replace"` swaps `from` out rather than stacking on it, and
-     * `"open"` drops `from` altogether so the target arrives with its own
-     * stack, the way a nav item's link does.
+     * it), picking how much of `from`'s context the target keeps: a push (the
+     * default, and what unrecognised values fall back to) keeps `from` and
+     * builds on it, `"replace"` keeps only what is beneath `from`, and
+     * `"open"` keeps nothing — the target arrives with its own stack, the way
+     * a nav item's link does. Absent, it is the shell's `linkNavigation`
+     * default, like a link without the attribute. A target that is already
+     * open is returned to by a push, and *moved* — alive, state intact — by
+     * the other two: the stack never holds a path twice.
      *
      * Resolves the way every {@link PanelStack} method does: `true` once the
      * navigation lands, `false` when it doesn't (already there counts as
@@ -669,21 +688,15 @@ export declare class PanelStackController implements PanelStack {
     setColumns(columns: "auto" | "single" | undefined): void;
     /** Adopt a changed `linkNavigation` default; the next click reads it. */
     setLinkNavigation(mode: "push" | "replace" | "open" | undefined): void;
-    /**
-     * Adopt a changed `fullWidth`: one layout pass, nothing redrawn. A changed
-     * `navWidth` needs no counterpart — resizing the sidebar resizes the column
-     * region, which the layout engine is already observing.
-     */
-    setFullWidth(px: number): void;
     /**
      * The breadcrumb stack, drawn by `main()` into the top bar: every open
      * panel, oldest first, the ones on screen right now in bold, pinned ones
      * wearing their pin. Every crumb but the current panel's is a plain link to
-     * that panel, and a link to an open panel is a focus move (see `navigate`) —
-     * so clicking along the stack closes nothing, in either direction, and the
-     * panels right of the current one wait just past the viewport's edge.
-     * Right-click (or long-press) offers pinning, and closing just that one
-     * panel — the close that splices it out of the middle when it isn't last.
+     * that panel, and a link to an open panel returns to it (see `navigate`) —
+     * so clicking a crumb goes back to that panel and closes what was stacked on
+     * top of it, pinned and unsaved panels excepted. Right-click (or long-press)
+     * offers pinning, and closing just that one panel — the close that splices
+     * it out of the middle when it isn't last.
      */
     drawCrumbs(): void;
     private drawCrumb;
@@ -702,9 +715,9 @@ export declare class PanelStackController implements PanelStack {
     private watchTitle;
     /**
      * While any open panel holds unsaved work, closing the tab — or navigating
-     * the whole browser away — runs into the browser's own are-you-sure. When
-     * the user stays, the unsaved panel is brought back on screen if it wasn't,
-     * so what held the tab is in front of them rather than parked out of sight.
+     * the whole browser away — runs into the browser's own are-you-sure, with
+     * the unsaved panel brought on screen as the question is raised, so what is
+     * holding the tab is in front of the user rather than parked out of sight.
      */
     private guardTabClose;
     /**
@@ -726,11 +739,31 @@ export declare class PanelStackController implements PanelStack {
     private drawActions;
     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 column 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.
+     * Run the pending layout pass now, rather than on the frame it is waiting
+     * for. For the callers that have to *read* what only the pass knows —
+     * `$panel.visible`, `$panel.width` — at a moment when waiting isn't an
+     * option. Does nothing when no pass is owed.
+     */
+    private flushLayout;
+    /**
+     * Measure the content area, and with it the width a panel of each size gets.
+     *
+     * The column region *is* the content area: it takes whatever the shell has
+     * left beside the sidebar, capped by the shell's own `maxWidth` — all of it
+     * CSS's doing, so there is nothing to add up here and nothing that could
+     * drift from the width the bars above and below line up with. Fractional
+     * widths throughout: a rounded column edge would drift a pixel away from that
+     * chrome.
+     *
+     * The area divides into the narrowest whole number of columns that keeps each
+     * at least {@link SMALL_MIN_PX} wide — the `"small"` unit every other size is
+     * a multiple of, capped at the area itself. So 1080px is three columns of 360
+     * and 1520px four of 380. An area too narrow for two is a single column,
+     * itself capped at {@link SMALL_MAX_PX}: a small centres there instead of
+     * stretching toward 720, so its ceiling holds, while the larger sizes still
+     * take the whole area. A width is thus a pure function of the window: a panel
+     * NEVER resizes because a neighbour came or went, and only a window resize
+     * (the snap pass in `layout`) changes one.
      *
      * `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.
@@ -746,8 +779,7 @@ export declare class PanelStackController implements PanelStack {
     /** How wide a panel asking for this 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.
+     * Size and position every panel.
      *
      * 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