staffa 0.1.0 → 0.3.0

package/src/components/main.ts

@@ -1,8 +1,11 @@
 import A from "aberdeen";
-import { type BaseOptions, type Content, type Slot, type Styling, drawSlot } from "../core.js";
+import { type Content, type Slot, type Attributes, drawSlot } from "../core.js";
+import { type MenuOptions, menuButton, drawMenu } from "./menu.js";
 
 /** Options for {@link main}. */
-export interface MainOptions extends BaseOptions {
+export interface MainOptions {
+	/** Aberdeen attr/style string applied to the outermost shell element. */
+	attrs?: Attributes;
 	/** App/page title shown in the top bar. */
 	title?: Slot;
 	/** Secondary line under the title. */
@@ -16,95 +19,252 @@ export interface MainOptions extends BaseOptions {
 	/** Footer content, pinned below the scroll area. */
 	footer?: Slot;
 	/**
-	 * Max content width. When set, the content is centered in a "sheet" with a
-	 * drop shadow and a distinct surface, against the darker page background.
-	 * e.g. `"60rem"`.
+	 * Max width for the page'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 —
+	 * it is not boxed.
 	 */
 	maxWidth?: string;
-	/** Aberdeen attr/style string applied to the content sheet. */
-	inner?: Styling;
+	/** Aberdeen attr/style string applied to the content area. */
+	contentAttrs?: Attributes;
 	/** Aberdeen attr/style string applied to the top bar. */
-	topbarInner?: Styling;
+	topbarAttrs?: Attributes;
+	/**
+	 * Navigation menu. When provided, renders a sidebar (in `"left"` / `"right"`
+	 * mode) or a button+dropdown (in `"button"` mode). The sidebar automatically
+	 * collapses to button mode when the shell is too narrow.
+	 */
+	nav?: MenuOptions;
+	/**
+	 * Where to render the nav. Defaults to `"left"`.
+	 * - `"left"` / `"right"`: sidebar next to the content area; collapses to a
+	 *   button+dropdown in the top bar when the shell width drops below 640 px.
+	 * - `"button"`: always a button+dropdown, never a sidebar.
+	 */
+	navPosition?: "left" | "right" | "button";
+	/** Aberdeen attr/style string applied to the sidebar nav panel. */
+	navAttrs?: Attributes;
 }
 
 A.insertGlobalCss({
-	".S_main": {
-		"&": "display:flex flex-direction:column min-height:100vh max-height:100vh bg:$sBg fg:$sFg",
-		"> header": "display:flex align-items:center gap:$3 padding: $2 $3; bg:$sSurfaceHi border-bottom: 1px solid $sBorder; position:sticky top:0 z-index:10",
-		"> header .S_icon": "display:flex align-items:center font-size:1.4em",
-		"> header .S_titles": "display:flex flex-direction:column min-width:0 flex:1",
-		"> header .S_title": "font-weight:700 font-size:1.1em line-height:1.2 overflow:hidden text-overflow:ellipsis white-space:nowrap",
-		"> header .S_subtitle": "fg:$sFgMuted font-size:0.85em overflow:hidden text-overflow:ellipsis white-space:nowrap",
-		"> header .S_menu": "display:flex align-items:center gap:$2",
-		"> main": "flex:1 overflow-y:auto display:flex flex-direction:column",
-		"> main > .S_content": "width:100% flex:1",
-		"> main > .S_content.S_framed": "margin: $3 auto; bg:$sSurface border: 1px solid $sBorder; r:$sRadiusLg box-shadow:$sShadow p:$4",
-		"> main > .S_content.S_plain": "p:$3",
-		"> footer": "display:flex align-items:center gap:$2 padding: $2 $3; bg:$sSurfaceHi border-top: 1px solid $sBorder; fg:$sFgMuted",
+	".s-main": {
+		// container-type so @container queries below can respond to shell width.
+		"&": "display:flex flex-direction:column min-height:100vh max-height:100vh container-type:inline-size",
+		// Header/footer stretch their background the full shell width; their inner
+		// `.s-bar` caps to maxWidth and centres, so chrome aligns with the content.
+		"> header": "border-bottom: 1px solid $s-border; position:sticky top:0 z-index:10",
+		"> footer": "border-top: 1px solid $s-border; fg:$s-fg-muted",
+		"> header > .s-bar, > footer > .s-bar": "display:flex align-items:center width:100% margin-inline:auto gap:$3 padding: $2 $3;",
+		"> header .s-header-icon": "display:flex align-items:center font-size:1.4em background: $s-gradient; -webkit-background-clip:text; background-clip:text; color:transparent;",
+		"> header .s-titles": "display:flex flex-direction:column min-width:0 flex:1",
+		"> header .s-title": "font-weight:800 font-size:1.1em line-height:1.2 overflow:hidden text-overflow:ellipsis white-space:nowrap letter-spacing:-0.01em background: $s-gradient; -webkit-background-clip:text; background-clip:text; color:transparent; width:fit-content max-width:100%",
+		"> header .s-subtitle": "fg:$s-fg-muted font-size:0.85em overflow:hidden text-overflow:ellipsis white-space:nowrap",
+		"> header .s-menu": "display:flex align-items:center gap:$2",
+		// Body holds sidebar + separator + <main> side by side (only used in sidebar
+		// nav mode). It centres `.s-body-inner`, which caps the trio to maxWidth.
+		".s-body": "flex:1 overflow:hidden display:flex flex-direction:row min-height:0 justify-content:center",
+		".s-body-inner": "flex:1 display:flex flex-direction:row min-height:0",
+		// Put the sidebar on the right (content fills the left) for right-hand navs.
+		"&.s-nav-right .s-body-inner": "flex-direction:row-reverse",
+		// A vertical hairline between sidebar and content, fading out at both ends —
+		// the vertical sibling of the menu's `hr.s-menu-sep`.
+		".s-nav-sep": "width:1px flex-shrink:0 align-self:stretch margin: 0.6rem 0; border:0 background: linear-gradient(to bottom, transparent, $s-border-strong 18%, $s-border-strong 82%, transparent);",
+		// Without a sidebar, <main> is a direct child; with one it lives in .s-body.
+		"> main, .s-body main": "flex:1 overflow-y:auto display:flex flex-direction:column",
+		// The content area fills the scroll region with comfortable padding. Without a
+		// sidebar it caps its own width to maxWidth and centres (applied inline in
+		// drawMainContent); with one, `.s-body-inner` does the capping for the trio.
+		// It is deliberately NOT a boxed "sheet" — content brings its own boxes.
+		"> main > .s-content, .s-body main > .s-content": "width:100% flex:1 p:$3",
+		// When <main> actually shows a vertical scrollbar (the `.s-scroll-y` class is
+		// toggled from JS by watchVerticalOverflow), inset it from the shell edge by
+		// $3 so the bar's right edge lines up with the header/footer content (which
+		// sits $3 inside the edge via `.s-bar` padding). The $3 gap between the content
+		// and the bar already comes from `.s-content`'s padding. Without a scrollbar
+		// there's no margin, so the content keeps its single $3 edge — not 2×$3.
+		"> main.s-scroll-y, .s-body main.s-scroll-y": "margin-right:$3",
+	},
+	// Sidebar nav panel. Items reuse the shared `.s-menu-item[-link]` /
+	// `.s-menu-sep` styles from menu.ts, so the sidebar and the floating
+	// dropdown stay visually identical.
+	// Borderless and transparent so the page's aurora shows through — an airy,
+	// floating sidebar whose only chrome is the active item's gradient pill.
+	".s-nav-panel": {
+		// Extra horizontal padding leaves room for the active pill's glow, which the
+		// vertical scroll (overflow-y:auto, which also clips overflow-x) would
+		// otherwise cut off at the panel edges.
+		"&": "display:flex flex-direction:column overflow-y:auto flex-shrink:0 max-width:228px padding:$3 gap:$1 background:transparent",
+	},
+	// In button-only mode (or always-button navPosition), hide the sidebar and
+	// show the trigger. In sidebar mode, show the panel and hide the trigger.
+	// CSS @container queries handle the responsive collapse automatically.
+	".s-main.s-nav-left .s-nav-trigger, .s-main.s-nav-right .s-nav-trigger": "display:none",
+	".s-main.s-nav-btn-only .s-nav-panel": "display:none",
+	".s-main.s-nav-btn-only .s-nav-trigger": "display:flex",
+	// Collapse sidebar → button when shell is narrow.
+	"@container (max-width: 640px)": {
+		".s-main.s-nav-left .s-nav-panel, .s-main.s-nav-right .s-nav-panel, .s-main .s-nav-sep": "display:none",
+		".s-main.s-nav-left .s-nav-trigger, .s-main.s-nav-right .s-nav-trigger": "display:flex",
+		// On phones a top-level content box becomes a full-bleed block: pull it out
+		// to negate the content padding and drop the rounded corners.
+		".s-content > .s-box": "margin-inline: calc(-1 * $3); r:0 border-inline:0",
 	},
 });
 
 /**
  * An application shell that wires up the things almost every app needs: a sticky
  * top bar (icon, title, subtitle, action menu), a scrollable content area, and a
- * footer. With {@link MainOptions.maxWidth} the content becomes a centered,
- * shadowed "sheet" — the common dashboard/document look — while staying fully
- * customisable via the various draw-function options and styling strings.
+ * footer. With {@link MainOptions.maxWidth} the content area is centred and its
+ * width capped. Add a `nav` to get a responsive sidebar (auto-collapses to a
+ * menu button below 640 px, or always a button with `navPosition: "button"`).
  *
  * @example
  * ```ts
  * S.main({
  *   icon: "✦",
  *   title: "Staffa Demo",
- *   subtitle: "Component playground",
  *   maxWidth: "56rem",
- *   menu: () => S.button({ text: "New", size: "sm" }),
+ *   nav: {
+ *     items: [
+ *       { label: "Home", icon: () => A("#🏠"), href: "/" },
+ *       { label: "Settings", href: "/settings" },
+ *     ],
+ *   },
+ *   navPosition: "left",
+ *   menu: () => S.button({ text: "New", attrs: ".small" }),
  *   content: () => drawPage(),
  *   footer: "© 2026",
  * });
  * ```
  */
 export function main(opts: MainOptions = {}): void {
-	A("div.S_main", opts.root, () => {
-		// Top bar — only rendered when there's something to show in it.
+	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}`) : "";
+
+	A(`div.s-main.s-s.base${navCls}`, opts.attrs, () => {
+		// Top bar.
 		A(() => {
-			const hasBar = opts.title != null || opts.subtitle != null || opts.icon != null || opts.menu != null;
+			const hasBar =
+				opts.title != null ||
+				opts.subtitle != null ||
+				opts.icon != null ||
+				opts.menu != null ||
+				hasNav;
 			if (!hasBar) return;
-			A("header", opts.topbarInner, () => {
-				A(() => {
-					if (opts.icon != null) A("div.S_icon", () => drawSlot(opts.icon));
-				});
-				A("div.S_titles", () => {
+			A("header.s-s.raised", opts.topbarAttrs, () => {
+				A("div.s-bar", () => {
+					// Cap the bar's content to maxWidth and centre it within the full-width header.
 					A(() => {
-						if (opts.title != null) A("div.S_title", () => drawSlot(opts.title));
+						if (opts.maxWidth != null) A("max-width:", opts.maxWidth);
 					});
+					// Nav trigger button — visible when sidebar is hidden (button mode or narrow viewport).
 					A(() => {
-						if (opts.subtitle != null) A("div.S_subtitle", () => drawSlot(opts.subtitle));
+						if (!hasNav) return;
+						// .s-nav-trigger: CSS toggles display based on sidebar visibility.
+						A("div.s-nav-trigger", () => {
+							menuButton({
+								...nav,
+								button: {
+									icon: () => A("span aria-hidden=true #☰"),
+									ariaLabel: "Open navigation",
+									attrs: ".neutral .outlined .small",
+									...nav.button,
+								},
+							});
+						});
+					});
+
+					A(() => {
+						if (opts.icon != null) A("div.s-header-icon", () => drawSlot(opts.icon));
+					});
+					A("div.s-titles", () => {
+						A(() => {
+							if (opts.title != null) A("div.s-title", () => drawSlot(opts.title));
+						});
+						A(() => {
+							if (opts.subtitle != null) A("div.s-subtitle", () => drawSlot(opts.subtitle));
+						});
+					});
+					A(() => {
+						if (opts.menu) A("div.s-menu", () => opts.menu?.());
 					});
-				});
-				A(() => {
-					if (opts.menu) A("div.S_menu", () => opts.menu?.());
 				});
 			});
 		});
 
-		// Scrollable main region with the (optionally framed) content sheet.
-		A("main", () => {
-			A("div.S_content", opts.inner, () => {
-				// Framing applied in its own scope so changing maxWidth doesn't
-				// recreate the content (which holds the whole page).
-				A(() => {
-					const max = opts.maxWidth;
-					if (max != null) A(".S_framed max-width:", max);
-					else A(".S_plain");
+		// Body — wraps sidebar + separator + main when nav is in sidebar mode. The
+		// trio together caps to maxWidth (via .s-body-inner); main fills the rest.
+		if (hasNav && navPos !== "button") {
+			A("div.s-body", () => {
+				A("div.s-body-inner", () => {
+					A(() => {
+						if (opts.maxWidth != null) A("max-width:", opts.maxWidth);
+					});
+					A(`nav.s-nav-panel.s-s.raised.s-nav-${navPos}`, opts.navAttrs, () => {
+						drawMenu(nav.items);
+					});
+					A("div.s-nav-sep aria-hidden=true");
+					drawMainContent(opts, false);
 				});
-				if (opts.content) opts.content();
 			});
-		});
+		} else {
+			drawMainContent(opts, true);
+		}
 
-		// Footer.
+		// Footer — full-width background, content centred to maxWidth via .s-bar.
 		A(() => {
-			if (opts.footer != null) A("footer", () => drawSlot(opts.footer));
+			if (opts.footer != null) {
+				A("footer", () => {
+					A("div.s-bar", () => {
+						A(() => {
+							if (opts.maxWidth != null) A("max-width:", opts.maxWidth);
+						});
+						drawSlot(opts.footer);
+					});
+				});
+			}
 		});
 	});
 }
+
+/**
+ * Draw the scrollable `<main>` + content area. When `capWidth` is true (no
+ * sidebar), the content caps its own width to maxWidth and centres; in sidebar
+ * mode the surrounding `.s-body-inner` already caps the sidebar+content trio.
+ */
+function drawMainContent(opts: MainOptions, capWidth: boolean): void {
+	const mainEl = A("main", () => {
+		A("div.s-content", opts.contentAttrs, () => {
+			if (capWidth) {
+				A(() => {
+					if (opts.maxWidth != null) A("margin-inline:auto max-width:", opts.maxWidth);
+				});
+			}
+			if (opts.content) opts.content();
+		});
+	}) as HTMLElement;
+	watchVerticalOverflow(mainEl);
+}
+
+/**
+ * Toggle the `.s-scroll-y` class on `el` whenever a vertical scrollbar is eating
+ * into its width, so CSS can inset the bar from the shell edge (see the
+ * `.s-scroll-y` rule above). We key on `offsetWidth > clientWidth` — a
+ * *space-consuming* scrollbar — rather than on content overflow, so overlay
+ * scrollbars (mobile, macOS) that take no layout width don't trigger the margin.
+ * A `ResizeObserver` watches both the viewport and its content, so the class
+ * tracks live content/layout changes; it's disconnected when the scope tears down.
+ */
+function watchVerticalOverflow(el: HTMLElement): void {
+	if (typeof ResizeObserver === "undefined") return; // No-op outside the browser.
+	const update = () => el.classList.toggle("s-scroll-y", el.offsetWidth > el.clientWidth);
+	const ro = new ResizeObserver(update);
+	ro.observe(el);
+	if (el.firstElementChild) ro.observe(el.firstElementChild);
+	update();
+	A.clean(() => ro.disconnect());
+}

package/src/components/menu.ts

@@ -0,0 +1,288 @@
+import A from "aberdeen";
+import { matchCurrent } from "aberdeen/route";
+import { type Content, type Slot, type Attributes, drawSlot } from "../core.js";
+import { button, type ButtonOptions } from "./button.js";
+
+/**
+ * A clickable item in a menu or sidebar nav.
+ *
+ * **Tip:** set `href` and call Aberdeen's `interceptLinks()` once at app
+ * startup for SPA-style navigation. When `href` is set, the item is
+ * automatically highlighted as active whenever the current URL matches it
+ * (via {@link matchCurrent}).
+ */
+export interface MenuItem {
+	/** Label text or draw function. Strings are rendered as rich text. */
+	label: Slot;
+	/** Leading icon drawn before the label. */
+	icon?: Slot;
+	/** Click handler. */
+	click?: (e: Event) => void;
+	/**
+	 * Render as a link (`<a>`) pointing here. Pairs naturally with
+	 * `interceptLinks()` — the item is highlighted automatically when the URL
+	 * matches.
+	 */
+	href?: string;
+	/** `target` for the link (`_blank`, etc.). Only meaningful with `href`. */
+	target?: string;
+	/** Disables the item. */
+	disabled?: boolean;
+	/** Aberdeen attr/style string on the item element. */
+	attrs?: Attributes;
+}
+
+/** A visual divider between groups of items. */
+export interface MenuSeparator {
+	separator: true;
+}
+
+/**
+ * An entry in a menu or sidebar nav list. Three forms:
+ * - `MenuItem` — a clickable/linkable row with label and optional icon.
+ * - `MenuSeparator` — a visual divider (`{ separator: true }`).
+ * - A draw function `() => void` — renders custom content (section header,
+ *   avatar, search box, …). Skipped by keyboard navigation.
+ */
+export type MenuEntry = MenuItem | MenuSeparator | Content;
+
+/** Options for {@link menuButton} and {@link MainOptions.nav}. */
+export interface MenuOptions {
+	/** Items shown in the dropdown or sidebar nav. */
+	items: MenuEntry[];
+	/**
+	 * Customize the trigger button rendered by {@link 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.
+	 */
+	button?: ButtonOptions;
+	/** Aberdeen attr/style string on the floating dropdown panel. */
+	dropdownAttrs?: Attributes;
+}
+
+/** Options for {@link showFloatingMenu}. */
+export interface FloatingMenuOptions {
+	/** Items to show. */
+	items: MenuEntry[];
+	/** Element to anchor the menu to (positioned just below it, flips up if needed). */
+	anchor: HTMLElement;
+	/** Aberdeen attr/style string on the floating panel. */
+	dropdownAttrs?: Attributes;
+}
+
+// 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({
+	".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 " +
+		"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]), .s-menu-item-link:hover":
+		"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]":
+		"opacity:0.45 cursor:not-allowed pointer-events:none",
+	".s-menu-icon": "fg:$s-fg-muted 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);",
+});
+
+/**
+ * Draw a list of {@link MenuEntry} items into the *current* element, with
+ * arrow-key / Home / End navigation between the focusable items. The single
+ * shared primitive behind both the floating dropdown ({@link showFloatingMenu})
+ * and the sidebar nav in `S.main()` — call it inside whatever container
+ * (`<nav>`, the floating panel, …) you've opened.
+ *
+ * Items are real `<a>`/`<button>` elements, so Enter/Space activate them and
+ * screen readers narrate them natively.
+ *
+ * @param items The entries to render.
+ * @param onActivate Optional — run when any item is activated (used by the
+ *   floating menu to close itself on selection).
+ */
+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) => {
+		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")]
+			.filter((el) => el.getAttribute("aria-disabled") !== "true");
+		if (!els.length) return;
+		const cur = els.indexOf(document.activeElement as HTMLElement);
+		const dir = e.key === "ArrowUp" ? -1 : 1;
+		const next =
+			e.key === "Home" ? 0 :
+			e.key === "End" ? els.length - 1 :
+			cur < 0 ? (dir > 0 ? 0 : els.length - 1) :
+			(cur + dir + els.length) % els.length;
+		els[next].focus();
+	});
+
+	for (const entry of items) {
+		if (typeof entry === "function") { 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, () => {
+			if (entry.href) {
+				A("href=", entry.href);
+				if (entry.target) A("target=", entry.target);
+				A(() => { if (matchCurrent(entry.href!)) A("aria-current=page"); });
+			}
+			if (entry.disabled) A("aria-disabled=true");
+			A("click=", (e: Event) => {
+				if (entry.disabled) { e.preventDefault(); return; }
+				onActivate?.();
+				entry.click?.(e);
+			});
+			if (entry.icon) A("span.s-menu-icon", () => drawSlot(entry.icon));
+			drawSlot(entry.label);
+		});
+	}
+}
+
+// ─── Floating menu ───────────────────────────────────────────────────────────
+
+// At most one floating menu is open at a time. The anchor lives in the options,
+// so it's available for positioning and focus-return without extra state.
+const $floating = A.proxy<{ opts: FloatingMenuOptions | null }>({ opts: null });
+
+function closeFloating(): void {
+	const anchor = $floating.opts?.anchor;
+	$floating.opts = null;
+	anchor?.focus();
+}
+
+function positionMenu(menuEl: HTMLElement, rect: DOMRect): void {
+	const mw = menuEl.offsetWidth, mh = menuEl.offsetHeight;
+	const vw = window.innerWidth,  vh = window.innerHeight;
+	const gap = 4;
+	let x = rect.left;
+	if (x + mw > vw - 8) x = Math.max(8, rect.right - mw);
+	let y = rect.bottom + gap;
+	if (y + mh > vh - 8 && rect.top - mh - gap >= 8) y = rect.top - mh - gap;
+	menuEl.style.left = Math.max(8, x) + "px";
+	menuEl.style.top  = Math.max(8, y) + "px";
+}
+
+A.mount(document.body, () => {
+	const f = $floating.opts;
+	if (!f) return;
+
+	const menuEl = A("div.s-menu-list.s-s.panel create=hidden destroy=hidden", f.dropdownAttrs, () => {
+		drawMenu(f.items, closeFloating);
+	}) as HTMLElement;
+
+	// Capture-phase document handlers replace an invisible backdrop element:
+	// 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();
+	};
+	const onKey = (e: KeyboardEvent) => {
+		if (e.key === "Escape" || e.key === "Tab") { e.preventDefault(); closeFloating(); }
+	};
+	document.addEventListener("click", onClick, true);
+	document.addEventListener("keydown", onKey, true);
+	A.clean(() => {
+		document.removeEventListener("click", onClick, true);
+		document.removeEventListener("keydown", onKey, true);
+	});
+
+	// 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();
+	});
+});
+
+// ─── Public API ──────────────────────────────────────────────────────────────
+
+/**
+ * Open a floating dropdown menu anchored to an element. Portals to
+ * `document.body` (never clipped), positions itself (flipping up when there's
+ * no room below), and closes on Escape, Tab, item selection, or any click
+ * outside the panel and anchor. Returns a `close()` function.
+ *
+ * @example
+ * ```ts
+ * // Custom context menu:
+ * el.addEventListener("contextmenu", (e) => {
+ *   e.preventDefault();
+ *   S.showFloatingMenu({ items, anchor: el });
+ * });
+ * ```
+ */
+export function showFloatingMenu(opts: FloatingMenuOptions): () => void {
+	$floating.opts = opts;
+	return closeFloating;
+}
+
+/**
+ * A button that opens a {@link showFloatingMenu | floating dropdown menu} on
+ * click. Keyboard navigation: Arrow Up/Down, Home, End; Escape/Tab to close;
+ * Enter/Space activate the focused item natively.
+ *
+ * **Tip:** set `href` on items and call `interceptLinks()` once at app startup
+ * for SPA navigation — active items are highlighted automatically.
+ *
+ * @example
+ * ```ts
+ * S.menuButton({
+ *   button: { text: "Actions", attrs: ".neutral .outlined" },
+ *   items: [
+ *     { label: "Edit", icon: () => A("#✎"), click: () => edit() },
+ *     { separator: true },
+ *     { label: "Delete", attrs: "fg:$s-danger", click: () => del() },
+ *   ],
+ * });
+ * ```
+ */
+export function menuButton(opts: MenuOptions): void {
+	let myEl: HTMLElement | null = null;
+	A.clean(() => { if ($floating.opts?.anchor === myEl) closeFloating(); });
+
+	button({
+		icon: () => A("span aria-hidden=true #☰"),
+		ariaLabel: "Open menu",
+		attrs: ".neutral .outlined",
+		...opts.button,
+		click: (e: Event) => {
+			myEl = e.currentTarget as HTMLElement;
+			// Toggle: a second click on the same trigger closes the menu.
+			if ($floating.opts?.anchor === myEl) { closeFloating(); return; }
+			showFloatingMenu({ items: opts.items, anchor: myEl, dropdownAttrs: opts.dropdownAttrs });
+		},
+	});
+}

package/src/components/select.ts

@@ -17,10 +17,10 @@ export interface SelectOptions extends FieldOptions {
 
 // Wrapper provides the chevron via ::after (pseudo-elements on <select> are unreliable).
 A.insertGlobalCss({
-	".S_select_wrap": {
+	".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:$sFgMuted font-size:0.85em",
+		"&::after": "content: '▾'; position:absolute right:0.7em top:50%; transform: translateY(-50%); pointer-events:none fg:$s-fg-muted font-size:0.85em",
 	},
 });
 
@@ -36,8 +36,8 @@ A.insertGlobalCss({
  */
 export function select(opts: SelectOptions): void {
 	drawField(opts, (id, isInvalid) => {
-		A("div.S_select_wrap", opts.control, () => {
-			A("select.S_input", () => {
+		A("div.s-select_wrap", opts.inputAttrs, () => {
+			A("select.s-input", () => {
 				applyControlAttrs(opts, id, isInvalid);
 
 				A("change=", (e: Event) => {