staffa 0.6.0 → 0.7.0

package/src/components/menu.ts

@@ -1,6 +1,6 @@
 import A from "aberdeen";
 import { matchCurrent } from "aberdeen/route";
-import { type Slot, type Attributes, drawSlot, mountPortal } from "../core.js";
+import { type Slot, type Attributes, drawSlot, mountPortal, focusFirst } from "../core.js";
 import { button, type ButtonOptions } from "./button.js";
 
 /**
@@ -68,54 +68,58 @@ export interface FloatingMenuOptions {
 	items: MenuEntry[];
 	/** Element to anchor the menu to (positioned just below it, flips up if needed). */
 	anchor: HTMLElement;
+	/**
+	 * Position the menu at this viewport point (e.g. a pointer location) instead
+	 * of just below the anchor. Used by {@link addContextMenu} to open at the
+	 * exact click/tap target.
+	 */
+	at?: { x: number; y: number };
+	/**
+	 * Also close the menu when the anchor itself is clicked. By default a click on
+	 * the anchor is ignored (so a trigger button can run its own toggle), but a
+	 * context menu — whose anchor has no click handler — wants the click to close.
+	 */
+	closeOnAnchorClick?: boolean;
 	/** Aberdeen attr/style string on the floating panel. */
 	dropdownAttrs?: Attributes;
 }
 
 /** Options for {@link addContextMenu} — like {@link FloatingMenuOptions}, but
  * the anchor is the element the handler is attached to. */
-export type ContextMenuOptions = Omit<FloatingMenuOptions, "anchor">;
+export type ContextMenuOptions = Omit<FloatingMenuOptions, "anchor" | "at" | "closeOnAnchorClick">;
 
 // 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.
 A.insertGlobalCss({
+	// Border comes from the `.s-s.neutral` surface; the panel only overrides the radius
+	// (lg) and opts into elevation via `.shadow` (added on the element below).
 	".s-menu-list":
 		"position:fixed z-index:350 min-width:10rem display:flex flex-direction:column p:$1 " +
-		"border: 1px solid $s-border; r:$s-radius-lg box-shadow:$s-shadow " +
+		"r:$s-radius-lg " +
 		"overflow-y:auto max-height:min(80vh,28rem) " +
 		"transition: opacity 0.15s, transform 0.15s;",
 	".s-menu-list.hidden": "opacity:0 pointer-events:none transform:translateY(-6px)",
-	".s-menu-item, .s-menu-item-link":
-		"display:flex align-items:center gap:$2 w:100% " +
-		"padding: 0.5em 0.65em; r:$s-radius cursor:pointer text-align:left " +
-		"font-size:0.9em border:0 background:transparent fg:$s-fg text-decoration:none " +
-		"transition: background 0.12s, color 0.12s, transform 0.12s, box-shadow 0.12s;",
-	// A translucent ink tint (rather than an *opaque* mix) so the hover fades in
-	// cleanly: transitioning background from `transparent` toward an opaque colour
-	// flashes through dark mid-tones in browsers that interpolate non-premultiplied.
-	// Staying ink-hued at low alpha keeps the fade the right colour throughout.
-	".s-menu-item:hover:not([aria-disabled=true]):not([aria-current=page]), .s-menu-item-link:hover:not([aria-current=page])":
-		"background: color-mix(in srgb, $s-fg 10%, transparent);",
-	// Active (current page): a filled brand-gradient pill with a soft glow — the
-	// one place the menu shows real colour, so the current page is unmistakable.
-	".s-menu-item[aria-current=page], .s-menu-item-link[aria-current=page]":
-		"color:$s-on-accent font-weight:600 background: $s-gradient; box-shadow: 0 3px 10px color-mix(in srgb, $s-primary 38%, transparent);",
-	".s-menu-item[aria-current=page] .s-menu-icon, .s-menu-item-link[aria-current=page] .s-menu-icon":
-		"color:$s-on-accent",
-	".s-menu-item[aria-current=page]:hover, .s-menu-item-link[aria-current=page]:hover":
-		"filter:brightness(1.06)",
-	".s-menu-item:focus-visible, .s-menu-item-link:focus-visible":
-		"outline:none background: color-mix(in srgb, $s-fg 10%, transparent); box-shadow: 0 0 0 2px inset $s-focus;",
-	".s-menu-item[aria-disabled=true], .s-menu-item-link[aria-disabled=true]":
+	// One class for both the `<a>` (link) and `<button>` forms — they look
+	// identical; the element only differs where link semantics matter (see below).
+	".s-menu-item":
+		"display:flex align-items:center gap:$2 w:100% outline:0 " +
+		"padding: $m2; line-height:1.1 r:$s-radius cursor:pointer text-align:left font-weight:450 " +
+		"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)",
+	".s-menu-item[aria-disabled=true]":
 		"opacity:0.45 cursor:not-allowed pointer-events:none",
-	".s-menu-icon": "fg:$s-fg-muted flex-shrink:0",
+	".s-menu-icon": "flex-shrink:0",
 	// A soft hairline that fades out at both ends, rather than a hard full-width
 	// rule — quieter, and it reads as a grouping cue instead of a divider bar.
 	// `hr.` (not just `.`) so this wins over the global hr flow-margin rule.
 	"hr.s-menu-sep":
 		"border:0 height:1px margin: $1 0.6rem; " +
-		"background: linear-gradient(to right, transparent, $s-border-strong 18%, $s-border-strong 82%, transparent);",
+		"background: linear-gradient(to right, transparent, $s-faint 18%, $s-faint 82%, transparent);",
 });
 
 /**
@@ -135,10 +139,18 @@ A.insertGlobalCss({
 export function drawMenu(items: MenuEntry[], onActivate?: () => void): void {
 	// Roving focus via the DOM: query the live item elements on each keypress.
 	A("keydown=", (e: KeyboardEvent) => {
+		// Link items navigate through interceptLinks' own Enter handler, which
+		// preventDefault()s the activation — so no synthetic `click` fires, and the
+		// click-bound `onActivate` (which closes a floating menu) never runs. Close it
+		// ourselves, deferred so this keydown finishes dispatching (and navigates) first.
+		if (e.key === "Enter" && (e.target as HTMLElement).tagName === "A") {
+			queueMicrotask(() => onActivate?.());
+			return;
+		}
 		if (e.key !== "ArrowDown" && e.key !== "ArrowUp" && e.key !== "Home" && e.key !== "End") return;
 		e.preventDefault();
 		const container = e.currentTarget as HTMLElement;
-		const els = [...container.querySelectorAll<HTMLElement>(".s-menu-item, .s-menu-item-link")]
+		const els = [...container.querySelectorAll<HTMLElement>(".s-menu-item")]
 			.filter((el) => el.getAttribute("aria-disabled") !== "true");
 		if (!els.length) return;
 		const cur = els.indexOf(document.activeElement as HTMLElement);
@@ -155,7 +167,7 @@ export function drawMenu(items: MenuEntry[], onActivate?: () => void): void {
 		if (typeof entry === "string" || typeof entry === "function") { drawSlot(entry); continue; }
 		if ("separator" in entry) { A("hr.s-menu-sep"); continue; }
 
-		A(entry.href ? "a.s-menu-item-link" : "button.s-menu-item type=button", entry.attrs, () => {
+		A(entry.href ? "a.s-menu-item" : "button.s-menu-item type=button", entry.attrs, () => {
 			if (entry.href) {
 				A("href=", entry.href);
 				if (entry.target) A("target=", entry.target);
@@ -185,7 +197,16 @@ function closeFloating(): void {
 	anchor?.focus();
 }
 
-function positionMenu(menuEl: HTMLElement, rect: DOMRect): void {
+/**
+ * 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.
+ */
+export function isFloatingMenuOpen(): boolean {
+	return $floating.opts != null;
+}
+
+function positionMenu(menuEl: HTMLElement, rect: { left: number; right: number; top: number; bottom: number }): void {
 	const mw = menuEl.offsetWidth, mh = menuEl.offsetHeight;
 	const vw = window.innerWidth,  vh = window.innerHeight;
 	const gap = 4;
@@ -201,7 +222,7 @@ mountPortal(() => {
 	const f = $floating.opts;
 	if (!f) return;
 
-	const menuEl = A("div.s-menu-list.s-s.panel create=hidden destroy=hidden", f.dropdownAttrs, () => {
+	const menuEl = A("div.s-menu-list.s-s.neutral.shadow create=hidden destroy=hidden", f.dropdownAttrs, () => {
 		drawMenu(f.items, closeFloating);
 	}) as HTMLElement;
 
@@ -209,7 +230,7 @@ mountPortal(() => {
 	// any click outside the panel + anchor closes; Escape/Tab close.
 	const onClick = (e: MouseEvent) => {
 		const t = e.target as Node;
-		if (!menuEl.contains(t) && !f.anchor.contains(t)) closeFloating();
+		if (!menuEl.contains(t) && (f.closeOnAnchorClick || !f.anchor.contains(t))) closeFloating();
 	};
 	const onKey = (e: KeyboardEvent) => {
 		if (e.key === "Escape" || e.key === "Tab") { e.preventDefault(); closeFloating(); }
@@ -224,10 +245,14 @@ mountPortal(() => {
 	// Position after layout, then focus the first enabled item.
 	requestAnimationFrame(() => {
 		if (!document.body.contains(menuEl)) return;
-		positionMenu(menuEl, f.anchor.getBoundingClientRect());
-		menuEl.querySelector<HTMLElement>(
-			".s-menu-item:not([aria-disabled=true]), .s-menu-item-link:not([aria-disabled=true])",
-		)?.focus();
+		// Position at the supplied point (a zero-size rect) when given — e.g. the
+		// pointer location for a context menu — otherwise below the anchor.
+		const rect = f.at ? { left: f.at.x, right: f.at.x, top: f.at.y, bottom: f.at.y } : f.anchor.getBoundingClientRect();
+		positionMenu(menuEl, rect);
+		// Focus the active (current-page) item if there is one — so opening lands
+		// where you are — else the first focusable element (covers custom slot
+		// content, like a settings dropdown, not just `.s-menu-item`s).
+		focusFirst(menuEl, ".s-menu-item[aria-current=page]");
 	});
 });
 
@@ -288,10 +313,18 @@ export function addContextMenu(opts: ContextMenuOptions): void {
 	let myEl: HTMLElement | null = null;
 	A.clean(() => { if ($floating.opts?.anchor === myEl) closeFloating(); });
 
-	A("contextmenu=", (e: Event) => {
+	A("contextmenu=", (e: MouseEvent) => {
 		e.preventDefault();
 		myEl = e.currentTarget as HTMLElement;
-		showFloatingMenu({ items: opts.items, anchor: myEl, dropdownAttrs: opts.dropdownAttrs });
+		// Anchor at the exact click/tap point, and close on a plain click of the
+		// element (it has no toggle handler of its own).
+		showFloatingMenu({
+			items: opts.items,
+			anchor: myEl,
+			at: { x: e.clientX, y: e.clientY },
+			closeOnAnchorClick: true,
+			dropdownAttrs: opts.dropdownAttrs,
+		});
 	});
 }
 
@@ -306,7 +339,7 @@ export function addContextMenu(opts: ContextMenuOptions): void {
  * @example
  * ```ts
  * S.menuButton({
- *   button: { content: "Actions", attrs: ".neutral .outlined" },
+ *   button: { content: "Actions", attrs: ".neutral" },
  *   items: [
  *     { label: "Edit", icon: () => A("#✎"), click: () => edit() },
  *     { separator: true },
@@ -324,7 +357,7 @@ export function menuButton(opts: MenuOptions): void {
 		// 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),
-		attrs: ".neutral .outlined",
+		attrs: ".neutral",
 		...opts.button,
 		click: (e: Event) => {
 			myEl = e.currentTarget as HTMLElement;

package/src/components/select.ts

@@ -20,7 +20,7 @@ A.insertGlobalCss({
 	".s-select_wrap": {
 		"&": "position:relative display:block",
 		"select": "w:100% cursor:pointer padding-right:2.2em; appearance:none",
-		"&::after": "content: '▾'; position:absolute right:0.7em top:50%; transform: translateY(-50%); pointer-events:none fg:$s-fg-muted font-size:0.85em",
+		"&::after": "content: '▾'; position:absolute right:0.7em top:50%; transform: translateY(-50%); pointer-events:none fg:$s-muted font-size:0.85em",
 	},
 });
 

package/src/components/tabs.ts

@@ -33,14 +33,14 @@ export interface TabsOptions {
 A.insertGlobalCss({
 	".s-tabs": {
 		"&": "display:flex flex-direction:column gap:$3",
-		".s-tablist": "display:flex gap:$1 align-items:stretch overflow-x:auto scrollbar-width:none border-bottom: 1px solid $s-border;",
+		".s-tablist": "display:flex gap:$1 align-items:stretch overflow-x:auto scrollbar-width:none border-bottom: 1px solid $s-faint;",
 		".s-tablist::-webkit-scrollbar": "display:none",
 		".s-tab":
 			"display:inline-flex align-items:center gap:$2 cursor:pointer background:transparent " +
-			"border:0 color: $s-fg-muted; font-weight:600 padding: 0.6em 0.9em; " +
+			"border:0 color: $s-muted; font-weight:600 padding: 0.6em 0.9em; " +
 			"border-bottom: 3px solid transparent; margin-bottom:-1px " +
 			"transition: color 0.15s, background 0.15s, border-color 0.15s;",
-		".s-tab:hover:not(:disabled), .s-tab[aria-selected=true]": "color: $s-fg;",
+		".s-tab:hover:not(:disabled), .s-tab[aria-selected=true]": "color: $s-text;",
 ".s-tab:focus-visible": "outline:none box-shadow: 0 0 0 3px $s-focus; r: $s-radius;",
 		".s-tab[aria-selected=true]": "border-image: $s-gradient 1;",
 		".s-tabpanel": "display:block",

package/src/components/toast.ts

@@ -36,16 +36,15 @@ A.insertGlobalCss({
 	".s-toast": {
 		"&":
 			"display:flex align-items:flex-start gap:$2 " +
-			"padding: $3; border: 1px solid $s-border; r:$s-radius box-shadow:$s-shadow " +
+			"padding: $3; " +
 			"pointer-events:auto position:relative overflow:hidden",
 		".s-toast-body": "display:flex flex-direction:column gap:$1 flex:1 min-width:0",
 		".s-toast-title": "font-weight:700 line-height:1.3",
-		".s-toast-msg": "font-size:0.9em fg:$s-fg-muted line-height:1.4",
 		".s-toast-close":
-			"cursor:pointer border:0 background:transparent fg:$s-fg-muted font-size:1.1em line-height:1 " +
+			"cursor:pointer border:0 background:transparent fg:$s-muted font-size:1.1em line-height:1 " +
 			"padding: 0 0.15em; r:4px flex-shrink:0 align-self:flex-start",
-		".s-toast-close:hover": "fg:$s-fg",
-		".s-toast-close:focus-visible": "outline:none box-shadow: 0 0 0 3px $s-focus; fg:$s-fg",
+		".s-toast-close:hover": "fg:$s-text",
+		".s-toast-close:focus-visible": "outline:none box-shadow: 0 0 0 3px $s-focus; fg:$s-text",
 		".s-toast-progress": "position:absolute bottom:0 left:0 right:0 height:2px background:$s-accent width:100%",
 	},
 });
@@ -58,11 +57,12 @@ mountPortal(() => {
 	// In initial peek is here to NOT subscribe to changes once `toasts` first becomes non empty,
 	// leaving the container in the DOM forever after. (So as not to cut of hide animations.)
 	if (A.peek(() => A.isEmpty(toasts)) && A.isEmpty(toasts)) return;
-	A("div.s-toasts aria-live=polite aria-atomic=false", () => {
+	A("div.s-toasts", () => {
 		A.onEach(toasts, (entry) => {
 			const { opts, id } = entry;
 			const role = opts.type === "danger" || opts.type === "warning" ? "alert" : "status";
-			const surface = opts.type ?? "neutral";
+			// "neutral" (the default) is a neutral surface; the rest are accent surfaces.
+			const surface = opts.type == null || opts.type === "neutral" ? "neutral" : opts.type;
 			const duration = opts.duration ?? 6000;
 
 			let timer: ReturnType<typeof setTimeout> | undefined;
@@ -91,7 +91,7 @@ mountPortal(() => {
 
 			A.clean(() => clearTimeout(timer));
 
-			A(`div.s-toast.s-s.${surface} role=${role}`, "create=", grow, "destroy=", shrink, opts.attrs, () => {
+			A(`div.s-toast.s-s.${surface}.extra-shadow aria-live=polite role=${role}`, "create=", grow, "destroy=", shrink, opts.attrs, () => {
 				if (duration > 0) {
 					A("mouseenter=", stopCountdown);
 					A("mouseleave=", startCountdown);

package/src/components/tooltip.ts

@@ -14,13 +14,14 @@ export interface TooltipOptions {
 	attrs?: Attributes;
 }
 
+// The tip is a `.s-s.neutral.shadow` surface (it portals to <body>, so it renders at
+// the page's next neutral shade), which provides its background, ink, border,
+// radius and elevation.
 A.insertGlobalCss({
 	".s-tt-tip": {
 		"&":
 			"position:fixed z-index:500 " +
 			"max-width:20rem w:max-content " +
-			"bg:$s-raised fg:$s-fg border: 1px solid $s-border-strong; " +
-			"r:$s-radius box-shadow:$s-shadow " +
 			"padding: 0.3em 0.65em; font-size:0.85em line-height:1.4 " +
 			"pointer-events:none",
 	},
@@ -85,7 +86,7 @@ mountPortal(() => {
 	const { opts, anchor } = active;
 	const placement = opts.placement ?? "top";
 
-	const tipEl = A("div.s-tt-tip role=tooltip visibility:hidden", opts.attrs, () => {
+	const tipEl = A("div.s-tt-tip.s-s.neutral.shadow role=tooltip visibility:hidden", opts.attrs, () => {
 		A("mouseenter=", () => {
 			if (hideTimer) { clearTimeout(hideTimer); hideTimer = null; }
 		});

package/src/core.ts

@@ -13,8 +13,9 @@ import A from "aberdeen";
  * An Aberdeen attribute/style/class string, e.g. `"display:flex gap:$3 .my-class"`.
  * 
  * Common values are our surface modifier classes:
- * - for colors: `.panel` `.raised` `.neutral` `.primary` `.secondary` `.gradient` `.danger` `.success` and `.warning`
- * - for variant: `.filled` `.tonal` and `.outlined`
+ * - neutral surface: `.neutral` (shade steps with nesting depth)
+ * - accent surface: `.primary` `.danger` `.success` `.warning` and `.link`
+ * - accent variant: `.filled` `.tonal` and `.outlined`
  *
  * These strings are passed straight through to {@link A} as positional
  * arguments, so they accept the full Aberdeen shorthand syntax: CSS shortcuts
@@ -70,6 +71,33 @@ export function drawSlot<Args extends unknown[] = []>(slot: Slot<Args> | undefin
 	else A("rich=", slot);
 }
 
+/** Selector matching the natively focusable elements we care about. */
+const FOCUSABLE_SELECTOR = "a[href], button, input, select, textarea, [tabindex]";
+
+/**
+ * Move keyboard focus to the first focusable element inside `container`, skipping
+ * disabled, `aria-disabled`, `tabindex=-1` and hidden ones. When `prefer` (a
+ * selector) matches a focusable element it wins — e.g. a menu's current item — so
+ * opening lands where the user already is. Returns whether anything was focused.
+ *
+ * Shared by overlays (the floating menu, dialogs) so "open → focus the right
+ * thing" behaves identically everywhere. Call it after the element is in the DOM
+ * and laid out (typically inside a `requestAnimationFrame`).
+ */
+export function focusFirst(container: HTMLElement, prefer?: string): boolean {
+	const ok = (el: Element): el is HTMLElement =>
+		el instanceof HTMLElement &&
+		!el.hasAttribute("disabled") &&
+		el.getAttribute("aria-disabled") !== "true" &&
+		el.tabIndex >= 0 &&
+		el.getClientRects().length > 0;
+	const target =
+		(prefer ? [...container.querySelectorAll(prefer)].find(ok) : undefined) ??
+		[...container.querySelectorAll(FOCUSABLE_SELECTOR)].find(ok);
+	target?.focus();
+	return target != null;
+}
+
 /**
  * Mount a portal (tooltip, toast, menu, dialog, …) directly into `<body>`.
  * Must be called at module top level, where Aberdeen's root scope (whose