staffa 0.2.1 → 0.3.1

package/src/components/button.ts

@@ -11,8 +11,6 @@ export interface ButtonOptions {
 	icon?: Slot;
 	/** Click handler. */
 	click?: (event: Event) => void;
-	/** Size. Defaults to `"md"`. */
-	size?: "sm" | "md" | "lg";
 	/** Disables the button. */
 	disabled?: boolean;
 	/** Native button behaviour. Defaults to `"button"`. */
@@ -25,6 +23,10 @@ export interface ButtonOptions {
 	 * Aberdeen attr/style string applied to the button. A button is a surface, so
 	 * pass surface modifier classes here to restyle it, e.g. `".danger"`,
 	 * `".neutral .outlined"`. Defaults to a filled `.primary` surface.
+	 *
+	 * Size is set here too, with `.small` or `.large` (medium is the default and
+	 * needs no class), e.g. `".danger .small"`. A `.small`/`.large` parent (such
+	 * as a {@link buttonGroup}) also sizes its buttons, so you can set it once.
 	 */
 	attrs?: Attributes;
 }
@@ -38,16 +40,37 @@ A.insertGlobalCss({
 			"display:inline-flex align-items:center justify-content:center gap:$2 " +
 			"font-weight:600 line-height:1.2 white-space:nowrap cursor:pointer text-decoration:none " +
 			"border: 1px solid $s-border; r: $s-radius; padding: 0.5em 1em; " +
-			"transition: background 0.15s, border-color 0.15s, filter 0.15s, box-shadow 0.15s;",
+			"transition: background 0.15s, border-color 0.15s, color 0.15s, filter 0.15s, box-shadow 0.15s, transform 0.08s;",
 		"&:focus-visible": "outline:none box-shadow: 0 0 0 3px $s-focus;",
 		"&:disabled, &[aria-disabled=true]": "opacity:0.45 cursor:not-allowed pointer-events:none filter:saturate(0.6)",
-		"&:hover": "filter: brightness(1.08)",
+		// Every button lifts a little toward the cursor on hover (the transform is in
+		// the transition list above). The filled `.gradient` CTA below layers a deeper
+		// shadow on top of the same lift, so it still reads as the signature action.
+		"&:hover": "filter: brightness(1.08); transform: translateY(-1px)",
 		"&.tonal:hover, &.outlined:hover": "background: color-mix(in srgb, $s-b 26%, transparent);",
-		"&.s-sm": "padding: 0.32em 0.7em; font-size:0.85em",
-		"&.s-lg": "padding: 0.66em 1.3em; font-size:1.1em",
+		// A filled `.gradient` button (the default) is the app's signature call to
+		// action: a borderless gradient with a soft glow that lifts on hover. The
+		// gradient fill itself comes from the `.s-s.gradient` surface rule in theme.ts.
+		// No border: a filled gradient reads as one solid shape. Dropping the border
+		// (rather than making it transparent) also sidesteps a Chromium artifact where
+		// a gradient clipped to a transparent rounded border fringes the edge with the
+		// gradient's far colour.
+		"&.gradient:not(.tonal):not(.outlined)": "border:0 box-shadow: $s-glow;",
+		"&.gradient:not(.tonal):not(.outlined):hover":
+			"filter: brightness(1.06); box-shadow: 0 10px 28px color-mix(in srgb, $s-primary 42%, transparent); transform: translateY(-1px);",
+		// Subtle press feedback.
+		"&:active:not(:disabled):not([aria-disabled=true])": "transform: translateY(1px)",
+		// Size: set on the button itself, or inherited from a `.small`/`.large`
+		// parent (e.g. a buttonGroup), so a container can size all its buttons at once.
+		"&.small, .small > &": "padding: 0.32em 0.7em; font-size:0.85em",
+		"&.large, .large > &": "padding: 0.66em 1.3em; font-size:1.1em",
 	},
 });
 
+// Surface-role classes a caller may pass in `attrs`. When one is present we skip
+// the default `.gradient` base so the two roles don't stack on one element.
+const ROLE_CLASS = /\.(gradient|primary|secondary|neutral|danger|success|warning|base|panel|raised)(\.|\s|$)/;
+
 /**
  * A button. Always carries at least a visible border so its affordance is
  * obvious at a glance.
@@ -55,6 +78,13 @@ A.insertGlobalCss({
  * Shortcut: pass a string to use it as the label, or a function for custom
  * content.
  *
+ * **Tip:** pair `href` with Aberdeen's `interceptLinks()` (called once at app
+ * startup) for SPA-style navigation without manual click handlers:
+ * ```ts
+ * interceptLinks(); // once at root
+ * S.button({ href: "/dashboard", text: "Dashboard" }); // navigates via router
+ * ```
+ *
  * @example
  * ```ts
  * S.button({ text: "Save", click: save });
@@ -67,11 +97,13 @@ export function button(opts: ButtonOptions | string | Content = {}): void {
 	const o: ButtonOptions = typeof opts === "string" ? { text: opts } : typeof opts === "function" ? { content: opts } : opts;
 
 	const tag = o.href != null ? "a" : "button";
-	const sizeCls = o.size != null ? `.s-${o.size}` : "";
 
-	// A filled `.primary` surface by default; `attrs` (applied after) can override
-	// the role/variant with e.g. `.danger`, `.neutral .outlined`.
-	A(`${tag}.s-btn.s-s.primary${sizeCls}`, o.attrs, () => {
+	// A filled `.gradient` surface by default — the signature CTA. If the caller's
+	// `attrs` already names a surface role we omit the default, so `.danger`,
+	// `.neutral .outlined`, etc. fully take over (rather than stacking two roles).
+	// A bare variant/size (`.outlined`, `.small`) keeps the gradient base.
+	const role = o.attrs && ROLE_CLASS.test(o.attrs) ? "" : ".gradient";
+	A(`${tag}.s-btn.s-s${role}`, o.attrs, () => {
 		if (o.href != null) {
 			A(`href=${o.href} role=button`);
 			if (o.disabled) A("aria-disabled=true");

package/src/components/buttonChooser.ts

@@ -1,5 +1,5 @@
 import A from "aberdeen";
-import { type Bindable, type Attributes } from "../core.js";
+import { type Bindable, type Attributes, type Slot } from "../core.js";
 import { buttonGroup } from "./buttonGroup.js";
 
 /** Options for {@link buttonChooser}. */
@@ -8,9 +8,10 @@ export interface ButtonChooserOptions {
 	attrs?: Attributes;
 	/**
 	 * The options to display, as a plain object mapping id → display label.
-	 * Buttons appear in insertion order.
+	 * Buttons appear in insertion order. A label may be a plain (rich-text)
+	 * string, or a draw-function for custom content such as an icon.
 	 */
-	options: Record<string, string>;
+	options: Record<string, Slot>;
 	/**
 	 * Two-way binding for the selected id, or `null` when nothing is selected.
 	 * Use an `A.proxy` or `A.ref`.
@@ -21,8 +22,6 @@ export interface ButtonChooserOptions {
 	 * `bind.value` to `null`. Useful for "none / auto" states.
 	 */
 	allowDeselect?: boolean;
-	/** Button size. Defaults to `"md"`. */
-	size?: "sm" | "md" | "lg";
 	/** Name attribute for the hidden `<input>`, enabling form submission. */
 	name?: string;
 }
@@ -49,8 +48,8 @@ export function buttonChooser(opts: ButtonChooserOptions): void {
 		buttonGroup({
 			attrs: opts.attrs,
 			buttons: Object.entries(opts.options).map(([id, label]) => ({
-				text: label,
-				size: opts.size,
+				text: typeof label === "string" ? label : undefined,
+				content: typeof label === "function" ? label : undefined,
 				attrs: selected === id ? ".primary" : ".neutral .outlined",
 				click: () => {
 					opts.bind.value = (opts.allowDeselect && selected === id) ? null : id;

package/src/components/buttonGroup.ts

@@ -24,8 +24,6 @@ A.insertGlobalCss({
 		"&.s-spaced": "gap:$2 flex-wrap:wrap",
 		"&.s-vertical": "flex-direction:column",
 		"&.s-attached": "gap:0",
-		// When attached, collapse the shared border and square off the touching
-		// corners, keeping only the outer ends of the group rounded.
 		"&.s-attached:not(.s-vertical) > .s-btn:not(:first-child)": "margin-left:-1px",
 		"&.s-attached:not(.s-vertical) > .s-btn:not(:first-child):not(:last-child)": "r:0",
 		"&.s-attached:not(.s-vertical) > .s-btn:first-child:not(:last-child)": "border-top-right-radius:0 border-bottom-right-radius:0",
@@ -34,7 +32,6 @@ A.insertGlobalCss({
 		"&.s-attached.s-vertical > .s-btn:not(:first-child):not(:last-child)": "r:0",
 		"&.s-attached.s-vertical > .s-btn:first-child:not(:last-child)": "border-bottom-left-radius:0 border-bottom-right-radius:0",
 		"&.s-attached.s-vertical > .s-btn:last-child:not(:first-child)": "border-top-left-radius:0 border-top-right-radius:0",
-		// Keep the hovered/focused button's border above its neighbours.
 		"&.s-attached > .s-btn:hover, &.s-attached > .s-btn:focus-visible": "z-index:1",
 	},
 });

package/src/components/field.ts

@@ -38,12 +38,9 @@ A.insertGlobalCss({
 		"&": "display:flex flex-direction:column gap:$1",
 		"> label": "font-weight:600 font-size:0.9em fg:$s-fg user-select:none",
 	},
-	// Shared, reusable bits (also used by checkbox & autocomplete).
 	".s-req": "fg:$s-danger margin-left:2px",
 	".s-help": "font-size:0.82em fg:$s-fg-muted",
 	".s-error": "font-size:0.82em fg:$s-danger",
-	// Shared look for text-like controls: a panel fill with a contextual border,
-	// the brand accent for focus, and the semantic danger ink when invalid.
 	".s-input": {
 		"&": "w:100% bg:$s-panel fg:$s-ink border: 1px solid $s-border; r:$s-radius padding: 0.55em 0.7em; transition: border-color 0.15s, box-shadow 0.15s;",
 		"&:hover:not(:disabled)": "border-color:$s-border-strong",

package/src/components/main.ts

@@ -1,5 +1,6 @@
 import A from "aberdeen";
 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 {
@@ -18,97 +19,252 @@ export interface MainOptions {
 	/** 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. */
+	/** Aberdeen attr/style string applied to the content area. */
 	contentAttrs?: Attributes;
 	/** Aberdeen attr/style string applied to the top bar. */
 	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": {
-		// Colours come from the surface classes added in main(): the shell is a
-		// filled base, the bars are raised, the framed sheet is a panel.
-		"&": "display:flex flex-direction:column min-height:100vh max-height:100vh",
-		"> header": "display:flex align-items:center gap:$3 padding: $2 $3; border-bottom: 1px solid $s-border; position:sticky top:0 z-index:10",
-		"> header .s-icon": "display:flex align-items:center font-size:1.4em",
+		// 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:700 font-size:1.1em line-height:1.2 overflow:hidden text-overflow:ellipsis white-space:nowrap",
+		"> 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",
-		"> 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; border: 1px solid $s-border; r:$s-radius-lg box-shadow:$s-shadow p:$4",
-		"> main > .s-content.s-plain": "p:$3",
-		"> footer": "display:flex align-items:center gap:$2 padding: $2 $3; border-top: 1px solid $s-border; fg:$s-fg-muted",
+		// 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.s-s.base", opts.attrs, () => {
-		// 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.s-s.raised", opts.topbarAttrs, () => {
-				A(() => {
-					if (opts.icon != null) A("div.s-icon", () => drawSlot(opts.icon));
-				});
-				A("div.s-titles", () => {
+				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.contentAttrs, () => {
-				// 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.s-s.panel 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());
+}