staffa 0.2.1 → 0.3.0

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/tabs.ts

@@ -26,8 +26,6 @@ export interface TabsOptions {
 	 * its own internal selection, starting at the first tab.
 	 */
 	bind?: Bindable<string>;
-	/** Visual style of the tab strip. Defaults to `"underline"`. */
-	variant?: "underline" | "pills";
 	/** Aberdeen attr/style string applied to the active panel. */
 	contentAttrs?: Attributes;
 }
@@ -35,25 +33,17 @@ export interface TabsOptions {
 A.insertGlobalCss({
 	".s-tabs": {
 		"&": "display:flex flex-direction:column gap:$3",
-		".s-tablist": "display:flex gap:$1 align-items:stretch",
+		".s-tablist": "display:flex gap:$1 align-items:stretch overflow-x:auto scrollbar-width:none border-bottom: 1px solid $s-border;",
+		".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-bottom: 3px solid transparent; margin-bottom:-1px " +
 			"transition: color 0.15s, background 0.15s, border-color 0.15s;",
-		".s-tab:hover:not(:disabled)": "color: $s-fg;",
+		".s-tab:hover:not(:disabled), .s-tab[aria-selected=true]": "color: $s-fg;",
 		".s-tab:disabled": "opacity:0.5 cursor:not-allowed",
 		".s-tab:focus-visible": "outline:none box-shadow: 0 0 0 3px $s-focus; r: $s-radius;",
-		// Underline variant — the active marker uses the contextual brand accent.
-		"&.s-underline .s-tablist": "border-bottom: 1px solid $s-border;",
-		"&.s-underline .s-tab": "border-bottom: 2px solid transparent; margin-bottom:-1px",
-		"&.s-underline .s-tab[aria-selected=true]": "color: $s-fg; border-bottom-color: $s-accent;",
-		// Pills variant — the active pill gets the `.s-s.primary` surface (added in
-		// tabs()), so its `--s-bg`/`--s-fg` are the brand surface's; we just paint
-		// (the `.s-tab` rule's transparent background would otherwise win on it).
-		"&.s-pills .s-tab": "r: $s-radius;",
-		"&.s-pills .s-tab[aria-selected=true]": "background: $s-bg; color: $s-fg;",
-		// The panel has no enclosing box, so no default padding — its content
-		// aligns flush with the tab strip. Callers add padding/flex via `inner`.
+		".s-tab[aria-selected=true]": "border-image: $s-gradient 1;",
 		".s-tabpanel": "display:block",
 	},
 });
@@ -71,7 +61,6 @@ A.insertGlobalCss({
  * ```
  */
 export function tabs(opts: TabsOptions): void {
-	const variant = opts.variant ?? "underline";
 	const groupId = uniqueId("tabs");
 
 	// Resolve a tab's selection key (its id, or its index as a string).
@@ -85,7 +74,7 @@ export function tabs(opts: TabsOptions): void {
 		$sel.value = keyOf(tab, index);
 	};
 
-	A(`div.s-tabs.s-${variant}`, opts.attrs, () => {
+	A("div.s-tabs", opts.attrs, () => {
 		A("div.s-tablist role=tablist", () => {
 			opts.tabs.forEach((tab, index) => {
 				const key = keyOf(tab, index);
@@ -95,9 +84,6 @@ export function tabs(opts: TabsOptions): void {
 						const selected = $sel.value === key;
 						A("aria-selected=", selected ? "true" : "false");
 						A("tabindex=", selected ? "0" : "-1");
-						// The active pill is a filled brand surface; the classes flip
-						// with selection (Aberdeen removes them when this scope re-runs).
-						if (selected && variant === "pills") A(".s-s.primary");
 					});
 					if (tab.disabled) A("disabled=true");
 					A("click=", () => select(tab, index));

package/src/components/toast.ts

@@ -0,0 +1,115 @@
+import A from "aberdeen";
+import { grow, shrink } from "aberdeen/transitions";
+import { type Slot, type Attributes, drawSlot } from "../core.js";
+import type { SurfaceRole } from "../theme.js";
+
+/** Options for {@link toast}. */
+export interface ToastOptions {
+	/** Primary message. A string is rendered as rich text. */
+	message: Slot;
+	/** Optional bold title above the message. */
+	title?: Slot;
+	/**
+	 * Colour role. Defaults to `"neutral"`.
+	 * Use `"success"` / `"danger"` / `"warning"` for semantic feedback.
+	 */
+	type?: SurfaceRole;
+	/**
+	 * Auto-dismiss delay in milliseconds. Defaults to `4000`.
+	 * Pass `0` to make the toast persistent until dismissed manually.
+	 */
+	duration?: number;
+	/** Show a close button. Defaults to `true`. */
+	dismissible?: boolean;
+	/** Aberdeen attr/style string applied to the toast element. */
+	attrs?: Attributes;
+}
+
+interface ToastEntry {
+	id: number;
+	opts: ToastOptions;
+}
+
+A.insertGlobalCss({
+	".s-toasts":
+		"position:fixed bottom:$3 right:$3 z-index:400 " +
+		"display:flex flex-direction:column gap:$2 " +
+		"pointer-events:none max-width:min(90vw,24rem) w:24rem",
+	".s-toast": {
+		"&":
+			"display:flex align-items:flex-start gap:$2 " +
+			"padding: $3; border: 1px solid $s-border; r:$s-radius box-shadow:$s-shadow " +
+			"pointer-events:auto",
+		".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 " +
+			"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",
+	},
+});
+
+let toastCount = 0;
+// Keyed by stable ID so A.onEach scopes are per-toast — removing one never re-renders others.
+const toasts = A.proxy({} as Record<number, ToastEntry>);
+
+A.mount(document.body, () => {
+	A("div.s-toasts aria-live=polite aria-atomic=false", () => {
+		A.onEach(toasts, (entry) => {
+			const { opts } = entry;
+			const role = opts.type === "danger" || opts.type === "warning" ? "alert" : "status";
+			const surface = opts.type ?? "neutral";
+
+			A(`div.s-toast.s-s.${surface} role=${role}`, "create=", grow, "destroy=", shrink, opts.attrs, () => {
+				A("div.s-toast-body", () => {
+					A(() => {
+						if (opts.title != null) A("div.s-toast-title", () => drawSlot(opts.title));
+					});
+					A("div.s-toast-msg", () => drawSlot(opts.message));
+				});
+				A(() => {
+					if (opts.dismissible === false) return;
+					A("button.s-toast-close type=button aria-label=Dismiss", () => {
+						A("#×");
+						A("click=", () => dismiss(entry.id));
+					});
+				});
+			});
+		});
+	});
+});
+
+function dismiss(id: number): void {
+	delete toasts[id];
+}
+
+/**
+ * Show a toast notification. Returns a `dismiss()` function to remove it
+ * programmatically. Auto-dismisses after `duration` ms (default 4 000).
+ *
+ * @example
+ * ```ts
+ * S.toast({ message: "Saved!", type: "success" });
+ * S.toast({ title: "Error", message: "Upload failed.", type: "danger", duration: 0 });
+ * const off = S.toast({ message: "Uploading…", duration: 0, dismissible: false });
+ * // later:
+ * off();
+ * ```
+ */
+export function toast(opts: ToastOptions): () => void {
+	const id = ++toastCount;
+	toasts[id] = { id, opts };
+
+	const duration = opts.duration ?? 4000;
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	if (duration > 0) {
+		timer = setTimeout(() => dismiss(id), duration);
+	}
+
+	return () => {
+		if (timer != null) clearTimeout(timer);
+		dismiss(id);
+	};
+}

package/src/components/tooltip.ts

@@ -0,0 +1,139 @@
+import A from "aberdeen";
+import { type Slot, type Attributes, drawSlot } from "../core.js";
+
+/** Options for {@link addTooltip}. */
+export interface TooltipOptions {
+	/** The tooltip text or draw function. A string is rendered as rich text. */
+	tip: Slot;
+	/**
+	 * Which side the tooltip appears on. Defaults to `"top"`.
+	 * Automatically flips to the opposite side when there isn't enough room.
+	 */
+	placement?: "top" | "bottom" | "left" | "right";
+	/** Aberdeen attr/style string applied to the tip panel. */
+	attrs?: Attributes;
+}
+
+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",
+	},
+});
+
+// ─── Global portal state ────────────────────────────────────────────────────
+
+// At most one tooltip is visible at a time. The anchor is the element the
+// handlers were attached to (its bounding rect drives positioning).
+const $ttActive = A.proxy<{ opts: TooltipOptions; anchor: HTMLElement } | undefined>(undefined);
+let hideTimer: ReturnType<typeof setTimeout> | null = null;
+
+// Hide tooltip when the page scrolls (anchor has moved).
+if (typeof window !== "undefined") {
+	window.addEventListener("scroll", () => { $ttActive.value = undefined; }, { capture: true, passive: true });
+}
+
+function computePos(rect: DOMRect, tipW: number, tipH: number, placement: string): { x: number; y: number } {
+	const gap = 7;
+	const vw = window.innerWidth;
+	const vh = window.innerHeight;
+	let x = 0, y = 0;
+
+	if (placement === "bottom") {
+		x = rect.left + (rect.width - tipW) / 2;
+		y = rect.bottom + gap;
+		if (y + tipH > vh - 8) { y = rect.top - tipH - gap; }
+	} else if (placement === "left") {
+		x = rect.left - tipW - gap;
+		y = rect.top + (rect.height - tipH) / 2;
+		if (x < 8) { x = rect.right + gap; }
+	} else if (placement === "right") {
+		x = rect.right + gap;
+		y = rect.top + (rect.height - tipH) / 2;
+		if (x + tipW > vw - 8) { x = rect.left - tipW - gap; }
+	} else {
+		// top (default)
+		x = rect.left + (rect.width - tipW) / 2;
+		y = rect.top - tipH - gap;
+		if (y < 8) { y = rect.bottom + gap; }
+	}
+
+	return {
+		x: Math.max(8, Math.min(x, vw - tipW - 8)),
+		y: Math.max(8, Math.min(y, vh - tipH - 8)),
+	};
+}
+
+function scheduleHide(): void {
+	if (hideTimer) clearTimeout(hideTimer);
+	hideTimer = setTimeout(() => {
+		$ttActive.value = undefined;
+		hideTimer = null;
+	}, 100);
+}
+
+// ─── Portal ──────────────────────────────────────────────────────────────────
+
+A.mount(document.body, () => {
+	const active = $ttActive.value;
+	if (!active) return;
+	const { opts, anchor } = active;
+	const placement = opts.placement ?? "top";
+
+	const tipEl = A("div.s-tt-tip role=tooltip visibility:hidden", opts.attrs, () => {
+		A("mouseenter=", () => {
+			if (hideTimer) { clearTimeout(hideTimer); hideTimer = null; }
+		});
+		A("mouseleave=", scheduleHide);
+		drawSlot(opts.tip);
+	}) as HTMLElement;
+
+	requestAnimationFrame(() => {
+		if (!document.body.contains(tipEl)) return;
+		const { x, y } = computePos(anchor.getBoundingClientRect(), tipEl.offsetWidth, tipEl.offsetHeight, placement);
+		tipEl.style.left = x + "px";
+		tipEl.style.top = y + "px";
+		tipEl.style.visibility = "";
+	});
+});
+
+// ─── Public component ────────────────────────────────────────────────────────
+
+/**
+ * Attaches a tooltip to the current element: adds hover/focus handlers via
+ * {@link A} so the tip appears when the element is hovered or keyboard-focused.
+ * The tip panel is rendered into `document.body` via a portal, so it is never
+ * clipped by `overflow:hidden` ancestors. Position is computed from the
+ * element's bounding rect and automatically flips when near the viewport edge.
+ *
+ * @example
+ * ```ts
+ * A("button #Save", () => {
+ *   S.addTooltip({ tip: "Saves your work to the cloud" });
+ * });
+ *
+ * A("button #Delete", () => {
+ *   S.addTooltip({ tip: "Dangerous — cannot be undone", placement: "bottom" });
+ * });
+ * ```
+ */
+export function addTooltip(opts: TooltipOptions): void {
+	const show = (e: Event) => {
+		if (hideTimer) { clearTimeout(hideTimer); hideTimer = null; }
+		$ttActive.value = { opts, anchor: e.currentTarget as HTMLElement };
+	};
+
+	A("mouseenter=", show);
+	A("mouseleave=", scheduleHide);
+	A("focusin=", show);
+	A("focusout=", scheduleHide);
+
+	A.clean(() => {
+		if ($ttActive.value?.opts === opts) $ttActive.value = undefined;
+	});
+}

package/src/core.ts

@@ -13,7 +13,7 @@ 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` `.danger` `.success` and `.warning`
+ * - for colors: `.panel` `.raised` `.neutral` `.primary` `.secondary` `.gradient` `.danger` `.success` and `.warning`
  * - for variant: `.filled` `.tonal` and `.outlined`
  *
  * These strings are passed straight through to {@link A} as positional