staffa 0.8.0 → 0.9.0

package/skill/closeNav.md

@@ -0,0 +1,23 @@
+## closeNav · function
+
+Close the navigation, if it's showing as an overlay: the full page it becomes
+on a narrow shell, or the dropdown its button opens on a wider one. A sidebar
+isn't an overlay and has nothing to dismiss, so there it 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.
+
+**Signature:** `() => void`
+
+**Examples:**
+
+```ts
+S.main({
+  nav: { items: [
+    { label: "Inbox", href: "/inbox" },
+    () => S.button({ content: "New message", click: () => { S.closeNav(); compose(); } }),
+  ]},
+  routes: { ... },
+});
+```

package/skill/panels.md

@@ -7,4 +7,4 @@ 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 `Page.requestClose` first.
 
-**Value:** `{ push(path: string): void; replace(path: string): void; close(path?: string): Promise<boolean>; readonly stack: readonly string[]; }`
+**Value:** `{ push(path: string): void; replace(path: string): void; open(path: string, beneath?: readonly string[]): void; close(path?: string): Promise<boolean>; readonly stack: readonly string[]; }`

package/src/components/main.ts

@@ -1,9 +1,10 @@
 import A from "aberdeen";
+import { current as currentRoute } from "aberdeen/route";
 import { type Slot, type Attributes, drawSlot, focusFirst, NARROW_PX } from "../core.js";
 import { type MenuOptions, drawMenu, showFloatingMenu, isFloatingMenuOpen, closeFloatingMenu, menuGlyph, closeGlyph } from "./menu.js";
 import { button } from "./button.js";
 import { isDialogOpen } from "./dialog.js";
-import { PanelController, type Page, type RouteHandler, type RouteTable, type Routes } from "./panels.js";
+import { PanelController, type AncestorsHandler, type AncestorTable, type Page, type RouteHandler, type RouteTable, type Routes } from "./panels.js";
 
 /** Options for {@link main}. */
 export interface MainOptions<R = Routes> {
@@ -84,6 +85,48 @@ export interface MainOptions<R = Routes> {
 	 * `$page.path`.
 	 */
 	notFound?: RouteHandler<{}>;
+	/**
+	 * 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 has to answer without drawing anything,
+	 * since the panels being replaced are asked their {@link Page.requestClose}
+	 * before the navigation is applied — before any handler could run. From code,
+	 * {@link panels}.`open()` takes the same list directly.
+	 */
+	// `NoInfer`, because `R` is inferred from `routes` alone: a second inference
+	// site for it would make TypeScript reconcile the two, and every handler's
+	// `$page` would quietly degrade to `any` (see the note on `main` below).
+	ancestors?: AncestorTable<NoInfer<R>>;
 	/**
 	 * 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,
@@ -115,6 +158,11 @@ export interface MainOptions<R = Routes> {
 	 * 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.
+	 *
+	 * `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.
 	 */
 	nav?: MenuOptions;
 	/**
@@ -303,10 +351,14 @@ A.insertGlobalCss({
 // silently degrades to `any`. Callers that pass no `routes` are unaffected —
 // `MainOptions`'s own default kicks in there.
 export function main<R extends RouteTable<R>>(opts: MainOptions<R> = {}): void {
+	// Whether there is a nav to show is deliberately NOT worked out here: `items`
+	// may well be a reactive array, and reading it in the shell's own scope would
+	// subscribe *the whole shell* to it — an item arriving later would redraw the
+	// lot, and in routed mode that means tearing the panel stack down and building
+	// it again from the URL. So every use below reads `nav.items` inside its own
+	// scope, and only that scope redraws.
 	const nav = opts.nav;
 	const navPos = opts.navPosition ?? "left";
-	const hasNav = nav != null && nav.items.length > 0;
-	const navCls = hasNav ? (navPos === "button" ? ".s-nav-btn-only" : `.s-nav-${navPos}`) : "";
 	// Whether the narrow-screen full-page nav is showing. Per shell, so nested or
 	// sibling `main()`s can't fight over it.
 	const $nav = A.proxy({ open: false });
@@ -317,13 +369,32 @@ export function main<R extends RouteTable<R>>(opts: MainOptions<R> = {}): void {
 	}
 	// The panel stack owns the routing, so it starts observing (and building its
 	// stack from) the URL before any of the shell is drawn — the top bar's back
-	// button already needs to know how deep we are.
-	const ctl = routes ? new PanelController({ ...opts, routes, title: opts.title }) : null;
+	// button already needs to know how deep we are. Its options are listed one by
+	// one rather than spread from `opts`: a spread reads every key, which on a
+	// proxied options object subscribes this scope to all of them.
+	const ctl = routes
+		? new PanelController({
+			routes,
+			notFound: opts.notFound,
+			ancestors: opts.ancestors,
+			stacking: opts.stacking,
+			title: opts.title,
+		})
+		: null;
 	// Routed mode caps the shell to the ensemble width the layout engine publishes,
 	// rather than to `maxWidth`.
 	const capWidth = ctl ? null : opts.maxWidth;
 
-	const root = A(`div.s-main${navCls}${ctl ? ".s-routed" : ""}`, opts.attrs, () => {
+	const root = A(`div.s-main${ctl ? ".s-routed" : ""}`, opts.attrs, () => {
+		// Which nav mode the shell is in — sidebar or button — as a class on the
+		// shell, for the CSS below to hang the responsive collapse off. Its own
+		// scope (see `nav` above), so a nav appearing or emptying out only retags
+		// the shell rather than redrawing it.
+		A(() => {
+			if (nav == null || !nav.items.length) return;
+			A(navPos === "button" ? ".s-nav-btn-only" : `.s-nav-${navPos}`);
+		});
+
 		// Top bar.
 		A(() => {
 			const hasBar =
@@ -331,7 +402,7 @@ export function main<R extends RouteTable<R>>(opts: MainOptions<R> = {}): void {
 				opts.subtitle != null ||
 				opts.icon != null ||
 				opts.menu != null ||
-				hasNav;
+				(nav != null && nav.items.length > 0);
 			if (!hasBar) return;
 			A("header.s-s.neutral", opts.topbarAttrs, () => {
 				A("div.s-bar", () => {
@@ -341,7 +412,7 @@ export function main<R extends RouteTable<R>>(opts: MainOptions<R> = {}): void {
 					});
 					// Nav trigger button — visible when sidebar is hidden (button mode or narrow viewport).
 					A(() => {
-						if (!hasNav) return;
+						if (nav == null || !nav.items.length) return;
 						// .s-nav-trigger: CSS toggles display based on sidebar visibility.
 						A("div.s-nav-trigger", () => drawNavTrigger(nav, $nav));
 					});
@@ -371,17 +442,20 @@ export function main<R extends RouteTable<R>>(opts: MainOptions<R> = {}): void {
 				A(() => {
 					if (capWidth != null) A("max-width:", capWidth);
 				});
-				if (hasNav && navPos !== "button") {
+				// The sidebar, in its own scope so a changing item list redraws just
+				// it — never the content area beside it (see `nav` above).
+				A(() => {
+					if (nav == null || !nav.items.length || navPos === "button") return;
 					A(`nav.s-nav-panel.s-nav-${navPos}`, opts.navAttrs, () => {
 						drawMenu(nav.items);
 					});
 					A("div.s-nav-sep aria-hidden=true");
-				}
+				});
 				drawMainContent(opts, ctl);
 			});
 			// The narrow-screen nav page, laid over the body it slides across.
 			A(() => {
-				if (hasNav && $nav.open) drawNavPage(nav, opts.navPageAttrs, $nav);
+				if (nav != null && nav.items.length && $nav.open) drawNavPage(nav, opts.navPageAttrs, $nav);
 			});
 		});
 
@@ -406,7 +480,7 @@ export function main<R extends RouteTable<R>>(opts: MainOptions<R> = {}): void {
 	// shell width calls for), which focuses its current item. Listens on
 	// `document` so it works wherever focus is, but bows out while another overlay
 	// (a dialog, or an already-open menu) is up — those handle Escape themselves.
-	if (hasNav || ctl) {
+	if (nav != null || ctl) {
 		const onKey = (e: KeyboardEvent) => {
 			if (e.key !== "Escape" || e.defaultPrevented) return;
 			// An open dialog or menu owns Escape itself — don't also jump to the nav.
@@ -427,7 +501,9 @@ export function main<R extends RouteTable<R>>(opts: MainOptions<R> = {}): void {
 				void ctl.closeTop();
 				return;
 			}
-			if (!hasNav) return;
+			// Whether there is a nav at all is asked of the DOM, not of `nav.items`:
+			// a subscription here would be one on the shell's own scope again, and
+			// an empty nav simply has neither of the two elements below.
 			// `offsetParent` is null when the sidebar is hidden (display:none).
 			const panel = root.querySelector<HTMLElement>(".s-nav-panel");
 			if (panel?.offsetParent != null) {
@@ -444,6 +520,37 @@ export function main<R extends RouteTable<R>>(opts: MainOptions<R> = {}): void {
 	}
 }
 
+/**
+ * Dismisses whichever collapsed nav is showing, if either is: at most one shell
+ * has its nav up as an overlay at a time, so this needs nothing passed in. Set
+ * by the two things that open one (see {@link closeNav}).
+ */
+let openNav: (() => void) | null = null;
+
+/**
+ * Close the navigation, if it's showing as an overlay: the full page it becomes
+ * on a narrow shell, or the dropdown its button opens on a wider one. A sidebar
+ * isn't an overlay and has nothing to dismiss, so there it 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 function closeNav(): void {
+	openNav?.();
+}
+
 /**
  * The hamburger in the top bar, shown whenever the sidebar isn't. What it opens
  * depends on how much room the shell has: a dropdown when there's plenty, and —
@@ -453,6 +560,10 @@ export function main<R extends RouteTable<R>>(opts: MainOptions<R> = {}): void {
 function drawNavTrigger(nav: MenuOptions, $nav: { open: boolean }): void {
 	let myEl: HTMLElement | null = null;
 	A.clean(() => { if (myEl) closeFloatingMenu(myEl); });
+	// The dropdown form of the same overlay, for `closeNav()` (see `openNav`).
+	// The floating menu bows out on a navigation by itself, so this is only ever
+	// asked to dismiss one that isn't going anywhere.
+	const dismiss = () => { if (myEl) closeFloatingMenu(myEl); };
 
 	button({
 		// The glyph doubles as the state: ☰ to open the page, ✕ to dismiss it. Its
@@ -471,7 +582,10 @@ function drawNavTrigger(nav: MenuOptions, $nav: { open: boolean }): void {
 			// Wide shell: the classic dropdown. A click on the trigger never reaches
 			// the menu's own outside-click handler, so toggle it here.
 			if (isFloatingMenuOpen(myEl)) closeFloatingMenu(myEl);
-			else showFloatingMenu({ items: nav.items, anchor: myEl, dropdownAttrs: nav.dropdownAttrs });
+			else {
+				openNav = dismiss;
+				showFloatingMenu({ items: nav.items, anchor: myEl, dropdownAttrs: nav.dropdownAttrs });
+			}
 		},
 	});
 }
@@ -486,13 +600,25 @@ function drawNavPage(nav: MenuOptions, attrs: Attributes | undefined, $nav: { op
 	// Whether this close is a *navigation* — the only kind that hands over to an
 	// incoming screen. Dismissing the page just uncovers the content again.
 	let navigated = false;
+	const dismiss = () => { navigated = true; $nav.open = false; };
 
 	const pageEl = A(
 		"nav.s-nav-page.s-s.neutral aria-label=Navigation create=s-nav-page-off destroy=s-nav-page-off",
 		attrs,
-		() => drawMenu(nav.items, () => { navigated = true; $nav.open = false; }),
+		() => drawMenu(nav.items, dismiss),
 	) as HTMLElement;
 
+	// This is the shell's one nav overlay, so `closeNav()` knows where to aim.
+	openNav = dismiss;
+	A.clean(() => { if (openNav === dismiss) openNav = null; });
+
+	// Whatever the page navigated to, it hands over to: the items do that
+	// themselves (`dismiss` above), but custom slot content — a link in a row the
+	// shell knows nothing about — doesn't, and neither does a navigation from
+	// anywhere else. Its own scope, so it can't redraw the page it closes.
+	const openedAt = A.peek(currentRoute, "path");
+	A(() => { if (currentRoute.path !== openedAt) dismiss(); });
+
 	const shell = pageEl.closest<HTMLElement>(".s-main");
 	const behind = pageEl.parentElement?.querySelector<HTMLElement>(":scope > .s-body-inner");
 	// Content mode's incoming half of the hand-off. In routed mode there is no

package/src/components/menu.ts

@@ -1,5 +1,5 @@
 import A from "aberdeen";
-import { matchCurrent } from "aberdeen/route";
+import { matchCurrent, current as currentRoute } from "aberdeen/route";
 import { type Slot, type Attributes, drawSlot, mountPortal, focusFirst } from "../core.js";
 import { mk } from "../icons-helpers.js";
 import { button, type ButtonOptions } from "./button.js";
@@ -263,6 +263,12 @@ mountPortal(() => {
 	const onKey = (e: KeyboardEvent) => {
 		if (e.key === "Escape" || e.key === "Tab") { e.preventDefault(); closeFloating(); }
 	};
+	// A menu is a transient overlay: whatever navigation it started, it hands over
+	// to. Items do that themselves (`closeFloating` is `drawMenu`'s `onActivate`
+	// above), but custom slot content — a link in a row the menu knows nothing
+	// about — doesn't, and neither does a navigation from anywhere else.
+	const openedAt = A.peek(currentRoute, "path");
+	A(() => { if (currentRoute.path !== openedAt) closeFloating(); });
 	document.addEventListener("click", onClick, true);
 	document.addEventListener("keydown", onKey, true);
 	A.clean(() => {