staffa 0.14.0 → 0.16.0

package/src/components/dialog.ts

@@ -3,6 +3,7 @@ import { type Slot, type Attributes, drawSlot, mountPortal, focusFirst } from ".
 import { button } from "./button.js";
 import { buttonGroup } from "./buttonGroup.js";
 import { textline } from "./textline.js";
+import { bindKey, claimKeyboard, keyboardOwner } from "../keys.js";
 
 /** Options for {@link dialog}. */
 export interface DialogOptions {
@@ -25,10 +26,17 @@ export interface DialogOptions {
 	 */
 	allowCancel?: boolean;
 	/**
-	 * When set to `true` (default) the model will be destroyed when the `dialog()`-calling
-	 * scope is destroyed.
+	 * When `true` (default), the dialog is destroyed when the scope that called
+	 * `dialog()` is destroyed.
 	 */
 	cancelWithScope?: boolean;
+	/**
+	 * Leave the keyboard shortcuts behind this dialog working, instead of owning
+	 * the keyboard the way a modal does. For overlays that inform rather than
+	 * interrupt — the `?` shortcut overview is one. Esc still closes it first,
+	 * whatever it meant before.
+	 */
+	keyboardTransparent?: boolean;
 	/**
 	 * Dialog body. A {@link Slot} whose draw-function receives a `close()` function
 	 * — call it to dismiss the dialog programmatically. (A plain string renders as
@@ -48,16 +56,14 @@ A.insertGlobalCss({
 		"&": "position:fixed inset:0 z-index:200 display:block background: rgba(0,0,0,0.55); transition: opacity 0.4s ease-in-out;",
 		"&.hidden": "opacity:0 pointer-events:none",
 	},
-	// The dialog panel is a `.s-s.neutral.extra-shadow` surface: border, radius (lg)
-	// and the deep floating shadow come from the surface itself (see theme.ts).
+	// Border, radius and the deep floating shadow come from the panel's
+	// `.s-s.neutral.extra-shadow` surface (see theme.ts).
 	".s-dialog": {
 		"&":
 			"position:fixed z-index:200 top:50% left:50% " +
 			"display:flex flex-direction:column " +
 			"transform:translate(-50%,-50%) " +
-			// vw/vh divided by --s-zoom: viewport units shrink with the page-fitting
-			// zoom (see `watchScale` in main.ts), and these caps mean the window.
-			"min-width:20rem max-width:min(calc(90vw/var(--s-zoom,1)),44rem) max-height:min(calc(88vh/var(--s-zoom,1)),800px) " +
+			"min-width:min(20rem,90vw) max-width:min(90vw,44rem) max-height:min(88vh,800px) " +
 			"r: $s-radius-lg; overflow:hidden " +
 			"transition: opacity 0.2s ease-out, transform 0.2s ease-out;",
 		"> header":
@@ -71,7 +77,7 @@ A.insertGlobalCss({
 	},
 });
 
-const dialogs = A.proxy({} as Record<number,{resolve: (value: void | PromiseLike<void>) => void, opts: DialogOptions}>);
+const dialogs = A.proxy({} as Record<string,{resolve: (value: void | PromiseLike<void>) => void, opts: DialogOptions}>);
 let dialogCount = 0;
 
 const topDialogId = A.derive(() => {
@@ -89,20 +95,40 @@ mountPortal(() => {
 		const close = () => { delete dialogs[dialogId]; };
 
 		A.clean(() => {
-			// Fires when this render is torn down — either because $closed became
-			// true (normal close) or because the parent reactive scope was cleaned up.
+			// Fires on a normal close and on parent-scope teardown alike.
 			opts.onClose?.();
 			resolve();
 		});
 
+		// Return focus to where it was when this dialog opened, so a keyboard
+		// user doesn't lose their place.
+		const prevFocus = document.activeElement;
+		A.clean(() => {
+			if (prevFocus instanceof HTMLElement && document.contains(prevFocus)) prevFocus.focus();
+		});
+
 		// Backdrop - hide when not the top dialog
 		const overlaid = A.derive(() => topDialogId.value != dialogId);
 		A("div.s-backdrop create=hidden destroy=hidden .hidden=", overlaid, "click=", () => {
 			if (opts.allowCancel !== false) close();
 		});
 
-		// Dialog itself
 		const dialogEl = A("div.s-dialog.neutral.s-s.extra-shadow create=hidden destroy=hidden", opts.attrs, () => {
+			// A modal owns the keyboard: claiming makes the shortcuts drawn inside
+			// (the content below included) register here and silences the rest. The
+			// `?` overview passes `keyboardTransparent` to leave them all working.
+			if (!opts.keyboardTransparent) A.clean(claimKeyboard());
+			// Esc closes the dialog — or, while `allowCancel` forbids it, is
+			// swallowed by the no-op press, so nothing below acts on it either.
+			// Anchored at whoever owned the keyboard as this dialog opened —
+			// itself, or with `keyboardTransparent` the modal beneath (or the page)
+			// — so it shadows whatever Esc meant so far, restored on close.
+			const escAt = keyboardOwner();
+			A(() => {
+				const can = opts.allowCancel !== false;
+				bindKey("esc", can ? "Close this dialog" : undefined, can ? close : () => {}, escAt);
+			});
+
 			A(() => {
 				if (opts.header != null) {
 					A("header.s-s.neutral", opts.headerAttrs, () => drawSlot(opts.header));
@@ -120,8 +146,8 @@ mountPortal(() => {
 			});
 		}) as HTMLElement;
 
-		// Once laid out, move focus into the dialog (first focusable element) so it's
-		// keyboard-ready and focus doesn't linger on whatever opened it.
+		// Once laid out, move focus into the dialog so it's keyboard-ready and focus
+		// doesn't linger on whatever opened it.
 		requestAnimationFrame(() => { if (document.body.contains(dialogEl)) focusFirst(dialogEl); });
 	});
 })
@@ -148,30 +174,6 @@ mountPortal(() => {
  * ```
  */
 export function dialog(opts: DialogOptions): Promise<void> {
-	if (!dialogCount) {
-		// Install Esc handler the first time we create a dialog
-		document.addEventListener("keydown", (e: KeyboardEvent) => {
-			// A layer above us that consumed Escape (an open floating menu's capture
-			// handler, or a widget inside the dialog like an open autocomplete list)
-			// marks it with preventDefault — the dialog must not also act on it.
-			if (e.key !== "Escape" || e.defaultPrevented) return;
-			const ds = A.unproxy(dialogs);
-			// Search for top-most dialog
-			for(let i=dialogCount; i>0; i--) {
-				if (ds[i]) {
-					// A dialog owns Escape, closable or not — handlers beneath it
-					// must not also act (main()'s nav jump and cooperative page
-					// handlers check defaultPrevented, or S.isDialogOpen()).
-					e.preventDefault();
-					if (ds[i].opts.allowCancel !== false) {
-						// The clean handler should call resolve and onClose
-						delete dialogs[i];
-					}
-					break;
-				}
-			}
-		});
-	}
 	const dialogId = ++dialogCount;
 	if (opts.cancelWithScope !== false) A.clean(() => { delete dialogs[dialogId]; });
 	return new Promise<void>((resolve) => {

package/src/components/field.ts

@@ -3,11 +3,9 @@ import { type Bindable, type Slot, type Attributes, drawSlot, uniqueId } from ".
 
 /**
  * Options shared by all *form field* components (textline, textarea, checkbox,
- * autocomplete, ...).
- *
- * Fields share a consistent vertical layout: an optional label, the control
- * itself, and optional help/error text below it. {@link form} relies on this
- * shared structure to align groups of fields.
+ * autocomplete, ...). Every field lays out the same way — optional label,
+ * control, optional help/error below — which is what lets {@link form} align
+ * groups of them.
  */
 export interface FieldOptions {
 	/** Aberdeen attr/style string applied to the field's wrapper element. */
@@ -42,9 +40,8 @@ A.insertGlobalCss({
 	".s-help": "font-size:0.82em fg:$s-muted",
 	".s-error": "font-size:0.82em fg:$s-danger",
 	".s-input": {
-		// A light inset field, derived from the surrounding surface: the surface
-		// background nudged slightly toward its ink, with the ink as text. Adapts to
-		// whatever surface (and mode) holds the field, no fixed input colour needed.
+		// Derived from the surrounding surface — its background nudged toward its ink —
+		// so the field adapts to any surface and mode, with no fixed input colour.
 		"&": "w:100% background: color-mix(in oklab, $s-bg, $s-text 4%); color:$s-text border: 1px solid $s-faint; r:$s-radius padding: 0.55em 0.7em; transition: border-color 0.15s, box-shadow 0.15s;",
 		"&:hover:not(:disabled)": "border-color: color-mix(in oklab, $s-text, $s-bg 55%);",
 		"&:focus-visible": "border-color:$s-accent box-shadow: 0 0 0 3px $s-focus; outline:none",
@@ -56,9 +53,8 @@ A.insertGlobalCss({
  * Render the standard field chrome (label + control + help/error) around a
  * caller-supplied control.
  *
- * Each piece is read inside its own small reactive scope, so e.g. flipping
- * `error` on a proxied options object only re-renders the error line — not the
- * control.
+ * Each piece gets its own reactive scope, so flipping `error` on a proxied
+ * options object re-renders just the error line, not the control.
  *
  * @param opts The field options.
  * @param drawControl Receives the resolved `id` and the live "invalid" getter,

package/src/components/form.ts

@@ -31,13 +31,11 @@ A.insertGlobalCss({
 });
 
 /**
- * An opinionated `<form>` wrapper that lays its fields out consistently — a clean
- * single column by default, or a responsive grid — and provides a standard
- * action bar.
- *
- * Field components ({@link import("./textline").textline} et al.) drop straight
- * in as {@link ContentOptions.content}. Submission is wired so the browser's
- * native validation runs, but the page never reloads.
+ * An opinionated `<form>` wrapper: fields in a single column by default, or a
+ * responsive grid, plus a standard action bar. Field components
+ * ({@link import("./textline").textline} et al.) drop straight in as
+ * {@link ContentOptions.content}; the browser's native validation runs on submit,
+ * but the page never reloads.
  *
  * @example
  * ```ts
@@ -56,8 +54,7 @@ export function form(opts: FormOptions | Slot = {}): void {
 	const o: FormOptions = typeof opts === "string" || typeof opts === "function" ? { content: opts } : opts;
 
 	A(`form.s-form`, o.attrs, () => {
-		// Toggle grid class in its own scope so changing layout doesn't recreate
-		// the fields (which would lose focus / input state).
+		// Own scope, so a layout change doesn't recreate the fields (losing focus/input state).
 		A(() => {
 			A(".grid=", o.layout === 'grid');
 		});

package/src/components/keyhelp.ts

@@ -0,0 +1,96 @@
+import A from "aberdeen";
+import { drawSlot } from "../core.js";
+import { bindKey, formatKey, getActiveKeyBindings } from "../keys.js";
+import { dialog } from "./dialog.js";
+
+A.insertGlobalCss({
+	".s-keyhelp": {
+		"&": "display:flex flex-direction:column gap:$1 min-width:14rem",
+		"> div": "display:flex align-items:baseline justify-content:space-between gap:$4",
+		"kbd": "font-family:inherit font-size:0.85em fg:$s-muted white-space:nowrap border: 1px solid $s-faint; r:$s-radius-sm padding: 0 0.4em;",
+	},
+});
+
+/** Non-null while the overview is up; calling it closes the dialog. */
+let closeHelp: (() => void) | null = null;
+
+/**
+ * The shortcut overview: a dialog listing what a keypress could do *right now*
+ * — every described binding the keyboard focus and any open modal leave in
+ * effect: buttons under their label, menu items under theirs, {@link bindKey}
+ * bindings under the description they were given.
+ *
+ * It's a cheat-sheet, not a modal: the shortcuts it lists keep working, and any
+ * keypress closes it *and* still lands — so the key you just looked up can be
+ * pressed right there. That is also what keeps the listing honest: focus cannot
+ * move while it is up (a click lands on the backdrop, a key closes it), so what
+ * was true when it opened stays true. Bound to `?` (and `mod+?`, which also
+ * works while typing in a field) by default — see {@link setKeyHelp}. Calling
+ * this while the overview is already up closes it, which is what lets that `?`
+ * toggle.
+ */
+export function showKeyHelp(): void {
+	if (closeHelp) {
+		closeHelp();
+		return;
+	}
+	// What a keypress could do at the moment of asking, snapshotted before the
+	// overview's own dialog (whose Esc shadows the Esc row shown here) exists.
+	// Focus cannot move while the overview is up, so the listing stays true —
+	// except for Esc itself, which dismisses the overview first.
+	const entries = getActiveKeyBindings(document.activeElement);
+	void dialog({
+		header: "Keyboard shortcuts",
+		// Usually pressed into being from the global `?` handler, where there is
+		// no scope to tie the dialog's life to.
+		cancelWithScope: false,
+		// The whole point: the keys it lists stay pressable while it is up.
+		keyboardTransparent: true,
+		onClose: () => { closeHelp = null; },
+		content: (close) => {
+			closeHelp = close;
+
+			// Any keypress closes the overview, in the capture phase so the key
+			// then travels on to whoever handles it. Except: bare modifiers (the
+			// combination they start still needs reading), Esc (the dialog's own
+			// close, handled there) and `?` (the toggle binding's).
+			const closer = (e: KeyboardEvent) => {
+				if (e.repeat || ["Control", "Shift", "Alt", "Meta", "Escape", "?"].includes(e.key)) return;
+				close();
+			};
+			document.addEventListener("keydown", closer, true);
+			A.clean(() => document.removeEventListener("keydown", closer, true));
+
+			A("div.s-keyhelp", () => {
+				for (const [keyStr, binding] of entries) {
+					if (binding.description === undefined) continue;
+					A("div", () => {
+						A("span", () => drawSlot(binding.description));
+						A("kbd text=", formatKey(keyStr));
+					});
+				}
+			});
+		},
+	});
+}
+
+/** Whether the default `?` / `mod+?` bindings are on. */
+const $enabled = A.proxy(true);
+
+/**
+ * Turn the default overview shortcuts off (or back on): `?` — free, like any
+ * unmodified key, whenever nothing is being typed into — and `mod+?`, which
+ * reaches the overview even from inside a text field. On by default.
+ */
+export function setKeyHelp(enabled: boolean): void {
+	$enabled.value = enabled;
+}
+
+// Global bindings, so they keep working while a dialog is up — the overview
+// should answer anywhere. It lists itself under the `mod+?` spelling, the one
+// that is true everywhere, a text field included; the bare `?` stays quiet.
+A(() => {
+	if (!$enabled.value) return;
+	bindKey("?", undefined, showKeyHelp, "global");
+	bindKey("mod+?", "This overview", showKeyHelp, "global");
+});