staffa 0.9.0 → 0.10.0

package/skill/MainOptions.md

@@ -14,31 +14,68 @@ Aberdeen attr/style string applied to the outermost shell element.
 
 ### mainOptions.title · member
 
-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 `MainOptions.home`, as the
+`MainOptions.logo` is.
 
 **Type:** `Slot`
 
 ### mainOptions.subtitle · member
 
-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.
 
 **Type:** `Slot`
 
-### mainOptions.icon · member
+### mainOptions.logo · member
 
-Leading icon/logo in the top bar.
+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
+`MainOptions.home`, as the app's name is.
 
 **Type:** `Slot`
 
+### mainOptions.home · member
+
+The app's home: where the name and the `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.
+
+**Type:** `string`
+
 ### mainOptions.menu · member
 
-Action area on the right of the top bar (buttons, menu, ...).
+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
+`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.
 
 **Type:** `Slot`
 
 ### mainOptions.content · member
 
-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 `MainOptions.routes`.
 
 **Type:** `Slot`
@@ -47,7 +84,7 @@ Mutually exclusive with `MainOptions.routes`.
 
 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
 `MainOptions.content`.
 
@@ -57,7 +94,7 @@ a string, `[name=integer]` matches one segment as a number, and a trailing
 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 `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
@@ -65,26 +102,38 @@ aren't safe integers, such as snowflakes, want a plain `[id]`.
 
 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 `panels` (`S.panels.push()` and friends): navigating
-with `aberdeen/route`'s own `go()` works and still asks the panels'
-`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
-`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 `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 `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 `Panel.pinned`).
+From code, use `pushPanel` and friends: navigating
+with `aberdeen/route`'s own `go()` works too — a panel with
+`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 (`Panel.title` — unset, its first line of text stands in)
+and what it can do (`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 `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`.
 
 **Type:** `R`
 
@@ -95,18 +144,18 @@ S.main({
   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 }),
 });
 ```
 
 ### mainOptions.notFound · member
 
 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`.
 
 **Type:** `RouteHandler<{}>`
 
@@ -144,19 +193,19 @@ 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 has to answer without drawing anything,
-since the panels being replaced are asked their `Page.requestClose`
-before the navigation is applied — before any handler could run. From code,
-`panels`.`open()` takes the same list directly.
+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,
+`PanelStack.openPanelStack` takes the same list directly.
 
 **Type:** `AncestorTable<NoInfer<R>>`
 
 ### mainOptions.stacking · member
 
-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`.
+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`.
 
 **Type:** `boolean`
 
@@ -168,15 +217,15 @@ Footer content, pinned below the scroll area.
 
 ### mainOptions.maxWidth · member
 
-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 `MainOptions.routes`: there the open panels
-decide the width (see `Page.layout`), and the header and footer line
+decide the width (see `Panel.maxWidth`), and the header and footer line
 themselves up with them.
 
 **Type:** `string`
@@ -195,30 +244,29 @@ Aberdeen attr/style string applied to the top bar.
 
 ### mainOptions.nav · member
 
-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.
 
 **Type:** `MenuOptions`
 
 ### mainOptions.navPosition · member
 
-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.
+Which side the nav sidebar sits on. Defaults to `"left"`.
 
-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.
+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.
 
-**Type:** `"button" | "left" | "right"`
+**Type:** `"left" | "right"`
 
 ### mainOptions.navAttrs · member
 

package/skill/MenuItem.md

@@ -29,7 +29,7 @@ Click handler.
 
 Render as a link (`<a>`) pointing here. Pairs naturally with
 `interceptLinks()` — the item is highlighted automatically when the URL
-matches.
+matches, and scrolled into view if its list had scrolled it out.
 
 **Type:** `string`
 
@@ -50,3 +50,18 @@ Disables the item.
 Aberdeen attr/style string on the item element.
 
 **Type:** `string`
+
+### menuItem.items · member
+
+Child entries, which turn the item into a collapsible **branch** of a
+tree. Only the branch holding the current page is expanded; navigate away
+and it folds back up. Clicking a branch *selects* rather than toggles: it
+follows the item's own `href`, or failing that the first linked leaf
+below it — which is what expands it. A branch with no link anywhere below
+it falls back to plain open/close toggling.
+
+Expanding is not selecting: a branch click never counts as picking an
+item (see `onLeafSelect` on `menu`), so on a phone the nav stays up
+while a section unfolds.
+
+**Type:** `MenuEntry[]`

package/skill/MenuListOptions.md

@@ -0,0 +1,24 @@
+## MenuListOptions · interface
+
+Options for `menu`.
+
+### menuListOptions.items · member
+
+The entries: items, separators, custom slots — and collapsible branches,
+via `MenuItem.items`.
+
+**Type:** `MenuEntry[]`
+
+### menuListOptions.onLeafSelect · member
+
+Run when a **leaf** item is activated. A branch expanding is not a
+selection, so it doesn't run this — which is what lets a menu that
+dismisses itself on selection stay up while a section unfolds.
+
+**Type:** `() => void`
+
+### menuListOptions.attrs · member
+
+Aberdeen attr/style string on the list element.
+
+**Type:** `string`

package/skill/MenuOptions.md

@@ -13,8 +13,9 @@ Items shown in the dropdown or sidebar nav.
 Customize the trigger button rendered by `menuButton`. Defaults to a
 `☰` icon button. The `click` handler is managed internally.
 
-When used as a `nav` in `S.main()`, this also customizes the hamburger
-button shown when the sidebar collapses.
+When used as a `nav` in `S.main()`, this also customizes the ☰ the sidebar
+collapses into — which is an `iconButton`, so only `icon`,
+`ariaLabel` and `attrs` apply there.
 
 **Type:** `ButtonOptions`
 

package/skill/Panel.md

@@ -0,0 +1,190 @@
+## Panel · interface
+
+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 current panel only. Any other
+panel keeps just its path, so anything a panel needs in order to redraw
+itself has to live in that path. (A panel browsed away from does get its
+search and hash back when a crumb makes it current again.)
+
+**Type Parameters:**
+
+- `P = Record<string, string | number | string[]>`
+
+### panel.params · member
+
+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.
+
+**Type:** `P`
+
+### panel.stack · member
+
+The stack this panel is in — the very object `S.main()` hands back. It is
+here as well because a route handler runs *while* that call is still
+going, so its return value isn't available to it yet; this always is.
+
+**Type:** `PanelStack`
+
+### panel.path · member
+
+This panel's path, e.g. `"/projects/7"`. Read-only.
+
+**Type:** `string`
+
+### panel.title · member
+
+Names this screen, in the top bar's breadcrumb stack and in
+`document.title` while the panel is current. A panel that doesn't set one
+borrows the first line of text in its own body, so the stack never shows a
+blank — but a borrowed paragraph makes a poor name, so say it yourself.
+
+It does **not** conjure a heading: naming a screen and heading its content
+are different jobs, and a screen that wants its name in its own body
+writes it there, where it owns the typography.
+
+**Type:** `string`
+
+### panel.actions · member
+
+This screen's own actions: a couple of buttons, a menu. The shell draws
+them — never the panel — and *where* depends on facts only the shell has:
+a quiet strip at the top of this panel's column while several columns are
+up, and the top bar (where they take the app's own `menu` slot) once the
+shell is narrow and this panel is the screen.
+
+They are drawn in exactly one of those places at a time, so crossing the
+threshold redraws them; anything stateful inside (the focus in a search
+box) is lost. Buttons and menus are fine.
+
+**Type:** `Slot`
+
+### panel.width · member
+
+How wide this panel's column actually is, in pixels — what
+`Panel.maxWidth` asked for, resolved against the window. Reactive and
+read-only, and correct *before* your handler draws, so content that sizes
+itself can read it instead of measuring.
+
+You rarely need it: the shell places the chrome for you. It's for content
+that genuinely differs by width, such as a table that becomes a list.
+
+**Type:** `number`
+
+### panel.visible · member
+
+Whether this panel is on screen right now: not crowded out from under the
+visible run, not parked past its right end, and not on its way out.
+Reactive and read-only.
+
+The one to hang per-panel floating UI on (a FAB, a "3 selected" bar), for
+which "am I the current panel?" is the wrong question — two columns can be
+visible at once, and both of them are really there.
+
+**Type:** `boolean`
+
+### panel.maxWidth · member
+
+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 (360–540px), so a second
+  column fits beside it. For lists and detail forms.
+- `"full"` (the default) — the whole content area, up to ~1100px.
+- `"screen"` — the whole window, unbounded: boards, wide tables, dense
+  dashboards. While one is open the shell itself stretches to the screen
+  edges instead of stopping at the standard 1280px page.
+
+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.
+
+Set it at the top of your handler and the panel is already that wide when
+you draw (see `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.
+
+**Type:** `"half" | "full" | "screen"`
+
+### panel.loading · member
+
+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 and the URL never wait for it.
+
+**Type:** `boolean`
+
+### panel.pinned · member
+
+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
+(right-click or long-press), which is also where the pin shows; setting
+it from code does the same thing.
+
+A pin never blocks an *explicit* close: Escape at the stack's end,
+`Panel.close`, the crumb menu's Close and `data-panel=replace` all
+still close the panel.
+
+**Type:** `boolean`
+
+### panel.unsaved · member
+
+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. `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).
+
+Only the app clears it; the user has no toggle. A Save or Discard button
+clears it and then closes:
+
+```ts
+A(() => { $panel.unsaved = $form.dirty || undefined; });
+S.button({ content: "Discard", attrs: ".neutral", click: () => {
+  $panel.unsaved = false;   // explicitly — see below
+  void $panel.close();
+}});
+```
+
+The explicit `unsaved = false` before `close()` matters when the flag is
+kept by a reactive scope, as above: resetting the form marks that scope
+dirty, but it reruns *after* the running handler — after `close()` has
+already been refused.
+
+**Type:** `boolean`
+
+### panel.close · member
+
+Closes **this** panel, wherever it sits in the stack. Closing the current
+panel hands the focus to the panel on its left; closing any other panel
+takes just it away, leaving the columns around it where they are, with
+their state. Either way it becomes a history entry, so the browser's
+back button brings the panel back.
+
+Resolves `false` if the panel didn't close: it holds
+`Panel.unsaved` work, it was the only panel on the stack (so
+there's nothing to show instead), or another navigation got there first.
+The shell's breadcrumbs already travel back, so reach for this when a
+screen wants a more explicit way out: a Cancel button, or a Save that
+closes.
+
+**Type:** `() => Promise<boolean>`
+
+**Examples:**
+
+```ts
+S.button({ content: "Cancel", attrs: ".neutral", click: () => void $panel.close() });
+```

package/skill/PanelStack.md

@@ -0,0 +1,106 @@
+## PanelStack · interface
+
+The panel stack behind a routed `S.main()`, and what that call hands back:
+the open `Panel`s, which of them is current, and the four ways to
+change that. Everything on it is scoped to its own shell.
+
+Every navigation settles asynchronously (closes travel through the
+browser's history), so the methods resolve once it has: `true` when it
+landed, `false` when it didn't — an unsaved panel refused to close, an
+app-registered route guard said no, or another navigation superseded it.
+Ignore the promise unless you care.
+
+**Examples:**
+
+```ts
+const shell = S.main({ title: "Trackle", routes: { ... } });
+
+S.button({ content: "New task", click: async () => {
+  const task = await createTask();
+  shell.pushPanel(`/tasks/${task.id}`);
+}});
+```
+
+### panelStack.panels · member
+
+The open panels, oldest first — the stack itself, as live objects rather
+than a copy of it. Writing through one is how you pin a panel, or rename
+it, from outside its own handler. Reactive on the stack's shape; don't
+hold a `Panel` across a navigation, since a closed one is dropped
+here while its element plays out its exit.
+
+**Type:** `readonly Panel<Record<string, string | number | string[]>>[]`
+
+### panelStack.currentPanelIndex · member
+
+Index into `PanelStack.panels` of the current panel. Reactive.
+
+**Type:** `number`
+
+### panelStack.currentPanel · member
+
+The current panel — shorthand for `panels[currentPanelIndex]`, and
+`undefined` only while the stack is still empty. Reactive on *which*
+panel is current; the fields you then read (`title`, `actions`, …) are
+reactive in their own right.
+
+**Type:** `Panel<Record<string, string | number | string[]>>`
+
+### panelStack.pushPanel · member
+
+Opens `path` in a new panel on top of the current one, closing the
+unpinned panels that were after it (pinned ones stay, sliding in beneath
+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 `Panel.unsaved` work is
+never closed, only parked. That's what a plain link does, and what
+`data-panel=push` says outright.
+
+**Type:** `(path: string) => Promise<boolean>`
+
+### panelStack.replacePanel · member
+
+Opens `path` in place of the current panel, which closes. The panels
+beneath it stay as they are. That's what a `data-panel=replace` link does.
+
+**Type:** `(path: string) => Promise<boolean>`
+
+### panelStack.openPanelStack · member
+
+Opens `path` as a whole stack rather than on top of what's there: the same
+thing a nav item or a fresh tab does. Without `beneath`, the stack under it
+is worked out the way a cold link's is (see `MainOptions.ancestors`);
+with it, the paths you give are opened underneath, shallowest first.
+
+That's the one for a screen whose URL doesn't say where it belongs — the
+thread a notification opens — and for seeding a stack from code in general.
+Panels the new stack also holds stay as they are; ones it drops close,
+except panels with `Panel.unsaved` work, which stay, parked.
+
+A `data-panel=open` link does the same thing (without a `beneath`): it
+leaves the panel it sits in behind rather than stacking on it, which is
+what a link to somewhere else in the app wants — a search hit, a mention.
+
+**Type:** `(path: string, beneath?: readonly string[]) => Promise<boolean>`
+
+**Examples:**
+
+```ts
+shell.openPanelStack(`/thread/${id}`, [`/mailbox/${mailboxId}`]);
+```
+
+### panelStack.closePanel · member
+
+Closes the current panel, or, given a `path`, whichever panel is open at
+it. Closing the current panel hands the focus to the panel on its left;
+closing any other panel takes just it away, leaving the columns around it
+exactly as they are, with their state. Either way it becomes a history
+entry, so the browser's back button brings the panel back.
+
+Resolves `false` if the panel didn't close: it holds `Panel.unsaved`
+work, `path` isn't open, it was the stack's only panel, or another
+navigation got there first.
+
+**Type:** `(path?: string) => Promise<boolean>`