staffa 0.3.0 → 0.4.0

package/dist/theme.js

@@ -38,7 +38,9 @@ import A from "aberdeen";
  * | `--s-fg-faint`   | placeholders, disabled                    |
  * | `--s-border` / `--s-border-strong` | borders                 |
  * | `--s-accent`     | brand "pop" colour (active indicators, etc.) |
- * | `--s-gradient`   | primary→secondary brand sweep (mark, primary buttons, active nav) |
+ * | `--s-gradient`   | full primary→secondary brand sweep (mark, active nav) |
+ * | `--s-gradient-surface` | compressed sweep for filled gradient surfaces (buttons) |
+ * | `--s-tint`       | brand mid colour; the hue the neutral greys lean toward |
  * | `--s-glow`       | soft coloured shadow for lit brand elements |
  * | `--s-link` / `--s-focus` | link & focus-ring colours         |
  * | `--s-radius` / `--s-radius-lg` / `--s-shadow` | shape tokens      |
@@ -134,12 +136,22 @@ export function getDarkMode(allowAuto = false) {
 // names (--s-primary/-danger/-success/-warning) double as semantic *ink*
 // colours, legible as text/borders on neutral surfaces.
 // ---------------------------------------------------------------------------
+// The neutral fills/inks aren't hard-coded greys: each one mixes a small dose
+// of `--s-tint` (the brand's mid colour, defined in the static block below)
+// into a true-grey base. Re-skin the brand and every "grey" — page, panels,
+// ink, the neutral fill — drifts subtly toward the new brand hue, light and
+// dark alike. The percentages are deliberately small: a tint you'd only spot
+// in a side-by-side, never a colour cast.
 A(() => {
     if (getDarkMode()) {
         A.insertGlobalCss({
             ":root": "--s-primary:#8b7bff --s-secondary:#ef7fd0 --s-danger:#ff6b6b --s-success:#46d39a --s-warning:#fbbf24 " +
-                "--s-neutral:#3c4352 --s-page:#0e1015 --s-panel:#181b22 --s-raised:#222632 " +
-                "--s-ink:#e8eaf0 --s-on-accent:#0c0a14 --s-focus:rgba(139,123,255,0.45) " +
+                "--s-neutral: color-mix(in oklab, #3d4047, $s-tint 14%); " +
+                "--s-page: color-mix(in oklab, #0e0f12, $s-tint 5%); " +
+                "--s-panel: color-mix(in oklab, #17181c, $s-tint 6%); " +
+                "--s-raised: color-mix(in oklab, #212327, $s-tint 8%); " +
+                "--s-ink: color-mix(in oklab, #e9eaec, $s-tint 8%); " +
+                "--s-on-accent:#0c0a14 --s-focus: color-mix(in srgb, $s-primary 45%, transparent); " +
                 "--s-radius:12px --s-radius-lg:18px --s-shadow: 0 10px 34px rgba(0,0,0,0.5);",
             // Contextual link, restored across the neutral group (see static block).
             ":root, .s-s.base, .s-s.panel, .s-s.raised, .s-s.neutral": "--s-link:#6db3ff",
@@ -148,8 +160,12 @@ A(() => {
     else {
         A.insertGlobalCss({
             ":root": "--s-primary:#6c5ce7 --s-secondary:#d6459e --s-danger:#e23b3b --s-success:#1f9d6b --s-warning:#d97706 " +
-                "--s-neutral:#c7ccda --s-page:#f3f4f8 --s-panel:#ffffff --s-raised:#eceef4 " +
-                "--s-ink:#1b1e27 --s-on-accent:#0c0a14 --s-focus:rgba(108,92,231,0.35) " +
+                "--s-neutral: color-mix(in oklab, #c9cbd0, $s-tint 14%); " +
+                "--s-page: color-mix(in oklab, #f3f4f6, $s-tint 5%); " +
+                "--s-panel: color-mix(in oklab, #ffffff, $s-tint 2%); " +
+                "--s-raised: color-mix(in oklab, #edeef0, $s-tint 7%); " +
+                "--s-ink: color-mix(in oklab, #1d1f24, $s-tint 7%); " +
+                "--s-on-accent:#0c0a14 --s-focus: color-mix(in srgb, $s-primary 35%, transparent); " +
                 "--s-radius:12px --s-radius-lg:18px --s-shadow: 0 10px 30px rgba(20,24,40,0.13);",
             ":root, .s-s.base, .s-s.panel, .s-s.raised, .s-s.neutral": "--s-link:#2563eb",
         });
@@ -174,12 +190,18 @@ A.setSpacingCssVars();
 A.insertGlobalCss({
     // Derived brand tokens. These only reference the per-mode palette colours, so
     // they're defined once here and track the active mode (and any re-skin):
-    // `--s-gradient` is the primary→secondary brand sweep used for the headline
-    // mark, primary buttons and the active nav pill; `--s-glow` is a soft coloured
-    // shadow that makes those same elements feel lit; `--s-page-bg` is a faint
+    // `--s-tint` is the brand's mid colour, the hue the neutral greys above lean
+    // toward; `--s-gradient` is the full primary→secondary sweep used where the
+    // brand should *show* (the headline mark, the active nav pill, tab edges);
+    // `--s-gradient-surface` is a compressed, near-vertical cut of that same sweep
+    // for *filled* gradient surfaces (buttons): it reads as one rich colour with
+    // depth rather than a two-colour banner; `--s-glow` is a soft coloured shadow
+    // that makes lit brand elements feel raised; `--s-page-bg` is a faint
     // twin-corner aurora wash painted on the page surface.
-    ":root": "--s-gradient: linear-gradient(135deg, $s-primary, $s-secondary); " +
-        "--s-glow: 0 8px 24px color-mix(in srgb, $s-primary 32%, transparent); " +
+    ":root": "--s-tint: color-mix(in oklab, $s-primary, $s-secondary); " +
+        "--s-gradient: linear-gradient(135deg, $s-primary, $s-secondary); " +
+        "--s-gradient-surface: linear-gradient(170deg, color-mix(in oklab, $s-primary 85%, $s-secondary), color-mix(in oklab, $s-primary 30%, $s-secondary)); " +
+        "--s-glow: 0 5px 16px color-mix(in srgb, $s-primary 26%, transparent); " +
         "--s-page-bg: radial-gradient(120% 80% at 100% 0%, color-mix(in oklab, $s-secondary, transparent 86%), transparent 56%), radial-gradient(120% 80% at 0% 0%, color-mix(in oklab, $s-primary, transparent 87%), transparent 56%), $s-page;",
     // Level/role modifier → anchors. Levels (neutral elevations) use the shared
     // ink; accent roles use the on-accent ink over their named fill. The page
@@ -231,10 +253,11 @@ A.insertGlobalCss({
     // overrides a component's default `.tonal`/`.outlined` (resetting both the
     // anchors and the painted background).
     ".s-s.filled": "--s-fg:$s-a --s-bg:$s-b background:$s-bg;",
-    // Paint the brand sweep for a filled `.gradient` surface. Sits after the
-    // variant rules and is keyed on `:not(.tonal):not(.outlined)`, so those
-    // variants keep their solid-primary tint/edge.
-    ".s-s.gradient:not(.tonal):not(.outlined)": "background: $s-gradient;",
+    // Paint the brand sweep for a filled `.gradient` surface — the compressed
+    // surface cut, not the full banner sweep. Sits after the variant rules and is
+    // keyed on `:not(.tonal):not(.outlined)`, so those variants keep their
+    // solid-primary tint/edge.
+    ".s-s.gradient:not(.tonal):not(.outlined)": "background: $s-gradient-surface;",
     // Contextual accent: the brand pop colour on neutral surfaces. Declared on the
     // whole neutral group so re-entering a neutral surface under a coloured one
     // restores it. (--s-link gets the same treatment in the reactive block, where

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "staffa",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "An opinionated component library for the Aberdeen reactive UI library.",
   "license": "ISC",
   "author": "",
@@ -25,9 +25,11 @@
   "scripts": {
     "build:icons": "node scripts/generate-icons.mjs",
     "build": "npm run build:icons && tsc && tsc -p demo && esbuild src/index.ts --bundle --external:aberdeen --minify --format=esm --outfile=dist/staffa.esm.js",
+    "build:skill": "rm -rf skill ; mkdir skill && readme-tsdoc --create src/index.ts --file skill/REFERENCE.md --split && awk '/^@@include /{while((getline line < $2)>0) print line; close($2); next} 1' skill-template.md > skill/SKILL.md && rm skill/REFERENCE.md",
     "typecheck": "tsc --noEmit && tsc -p demo --noEmit",
     "smoke": "tsc && node smoke.mjs",
-    "prepublish": "npm run build"
+    "prepublish": "npm run build && shotest test && npm run build:skill",
+    "test": "shotest test"
   },
   "peerDependencies": {
     "aberdeen": "^1.17.1"
@@ -35,8 +37,13 @@
   "devDependencies": {
     "aberdeen": "^1.17.1",
     "esbuild": "^0.28.0",
+    "http-server": "^14.1.1",
     "jsdom": "^29.1.1",
     "lucide-static": "^1.17.0",
+    "readme-tsdoc": "^1.2.1",
     "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "shotest": "^1.6.1"
   }
 }

package/src/components/box.ts

@@ -1,5 +1,5 @@
 import A from "aberdeen";
-import { type Content, type ContentOptions, type Slot, type Attributes, drawSlot } from "../core.js";
+import { type ContentOptions, type Slot, type Attributes, drawSlot } from "../core.js";
 
 /** Options for {@link box}. */
 export interface BoxOptions extends ContentOptions {
@@ -24,7 +24,7 @@ A.insertGlobalCss({
 		"&": "display:flex flex-direction:column border: 1px solid $s-border; r: $s-radius-lg; overflow:hidden box-shadow: $s-shadow;",
 		"&:not(:first-child)": "margin-top: $3",
 		"> header": "display:flex align-items:center gap:$2 padding: $2 $3; border-bottom: 1px solid $s-border; font-weight:600",
-		"> footer": "display:flex align-items:center gap:$2 padding: $2 $3; border-top: 1px solid $s-border;",
+		"> footer": "display:flex align-items:center justify-content:flex-end gap:$2 padding: $2 $3; border-top: 1px solid $s-border;",
 		"> div": "p:$3 gap:$3",
 	},
 });
@@ -47,8 +47,8 @@ A.insertGlobalCss({
  * S.box(() => A("p#Just some content"));   // shorthand
  * ```
  */
-export function box(opts: BoxOptions | Content = {}): void {
-	const o: BoxOptions = typeof opts === "function" ? { content: opts } : opts;
+export function box(opts: BoxOptions | Slot = {}): void {
+	const o: BoxOptions = typeof opts === "string" || typeof opts === "function" ? { content: opts } : opts;
 
 	A("section.s-box.s-s.panel", o.attrs, () => {
 		// Header and footer get their own scopes so toggling them doesn't recreate
@@ -58,7 +58,7 @@ export function box(opts: BoxOptions | Content = {}): void {
 		});
 
 		A("div", o.contentAttrs, () => {
-			if (o.content) o.content();
+			drawSlot(o.content);
 		});
 
 		A(() => {

package/src/components/button.ts

@@ -1,12 +1,10 @@
 import A from "aberdeen";
-import { type Content, type Slot, type Attributes, drawSlot } from "../core.js";
+import { type Slot, type Attributes, drawSlot } from "../core.js";
 
 /** Options for {@link button}. */
 export interface ButtonOptions {
-	/** Button label text. */
-	text?: string;
-	/** Custom content (overrides {@link ButtonOptions.text | text}). */
-	content?: Content;
+	/** Button content: a string for plain text, or a function for custom markup. */
+	content?: Slot;
 	/** Leading icon/adornment, drawn before the label. */
 	icon?: Slot;
 	/** Click handler. */
@@ -49,15 +47,17 @@ A.insertGlobalCss({
 		"&:hover": "filter: brightness(1.08); transform: translateY(-1px)",
 		"&.tonal:hover, &.outlined:hover": "background: color-mix(in srgb, $s-b 26%, transparent);",
 		// 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;",
+		// action: a borderless gradient with a hairline top highlight (a hint of
+		// top-lighting that sells the fill as a lit, rounded shape) over a soft glow.
+		// 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: inset 0 1px 0 color-mix(in srgb, white 25%, transparent), $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);",
+			"filter: brightness(1.05); box-shadow: inset 0 1px 0 color-mix(in srgb, white 25%, transparent), 0 7px 18px color-mix(in srgb, $s-primary 34%, 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`
@@ -82,19 +82,19 @@ const ROLE_CLASS = /\.(gradient|primary|secondary|neutral|danger|success|warning
  * startup) for SPA-style navigation without manual click handlers:
  * ```ts
  * interceptLinks(); // once at root
- * S.button({ href: "/dashboard", text: "Dashboard" }); // navigates via router
+ * S.button({ href: "/dashboard", content: "Dashboard" }); // navigates via router
  * ```
  *
  * @example
  * ```ts
- * S.button({ text: "Save", click: save });
- * S.button({ text: "Delete", attrs: ".danger .outlined", click: del });
- * S.button("Cancel");                        // shorthand for { text: "Cancel" }
- * S.button({ href: "/docs", text: "Docs" }); // renders an <a role=button>
+ * S.button({ content: "Save", click: save });
+ * S.button({ content: "Delete", attrs: ".danger .outlined", click: del });
+ * S.button("Cancel");                        // shorthand for { content: "Cancel" }
+ * S.button({ href: "/docs", content: "Docs" }); // renders an <a role=button>
  * ```
  */
-export function button(opts: ButtonOptions | string | Content = {}): void {
-	const o: ButtonOptions = typeof opts === "string" ? { text: opts } : typeof opts === "function" ? { content: opts } : opts;
+export function button(opts: ButtonOptions | Slot = {}): void {
+	const o: ButtonOptions = typeof opts === "string" || typeof opts === "function" ? { content: opts } : opts;
 
 	const tag = o.href != null ? "a" : "button";
 
@@ -115,7 +115,6 @@ export function button(opts: ButtonOptions | string | Content = {}): void {
 		if (o.click) A("click=", o.click);
 
 		drawSlot(o.icon);
-		if (o.content) o.content();
-		else if (o.text != null) A("#", o.text);
+		drawSlot(o.content);
 	});
 }

package/src/components/buttonChooser.ts

@@ -13,13 +13,13 @@ export interface ButtonChooserOptions {
 	 */
 	options: Record<string, Slot>;
 	/**
-	 * Two-way binding for the selected id, or `null` when nothing is selected.
+	 * Two-way binding for the selected id, or `undefined` when nothing is selected.
 	 * Use an `A.proxy` or `A.ref`.
 	 */
-	bind: Bindable<string | null>;
+	bind: Bindable<string | undefined>;
 	/**
 	 * When `true`, clicking the already-selected button deselects it, setting
-	 * `bind.value` to `null`. Useful for "none / auto" states.
+	 * `bind.value` to `undefined`. Useful for "none / auto" states.
 	 */
 	allowDeselect?: boolean;
 	/** Name attribute for the hidden `<input>`, enabling form submission. */
@@ -28,14 +28,14 @@ export interface ButtonChooserOptions {
 
 /**
  * A single-selection segmented control: an attached button group where exactly
- * one button is active at a time. Optionally allows deselecting back to `null`.
+ * one button is active at a time. Optionally allows deselecting back to `undefined`.
  *
  * Renders a hidden `<input>` alongside (when `name` is set) so the selected
  * value is included in native form submission.
  *
  * @example
  * ```ts
- * const $view = A.proxy({ value: "day" as string | null });
+ * const $view = A.proxy({ value: "day" as string | undefined });
  * S.buttonChooser({
  *   options: { day: "Day", week: "Week", month: "Month" },
  *   bind: $view,
@@ -48,11 +48,13 @@ export function buttonChooser(opts: ButtonChooserOptions): void {
 		buttonGroup({
 			attrs: opts.attrs,
 			buttons: Object.entries(opts.options).map(([id, label]) => ({
-				text: typeof label === "string" ? label : undefined,
-				content: typeof label === "function" ? label : undefined,
+				content: label,
+				// Icon-only options (draw-function labels) get the id as their
+				// accessible name; plain-text labels speak for themselves.
+				ariaLabel: typeof label === "function" ? id : undefined,
 				attrs: selected === id ? ".primary" : ".neutral .outlined",
 				click: () => {
-					opts.bind.value = (opts.allowDeselect && selected === id) ? null : id;
+					opts.bind.value = (opts.allowDeselect && selected === id) ? undefined : id;
 				},
 			})),
 		});

package/src/components/buttonGroup.ts

@@ -1,5 +1,6 @@
 import A from "aberdeen";
 import type { ContentOptions } from "../core.js";
+import { drawSlot } from "../core.js";
 import { type ButtonOptions, button } from "./button.js";
 
 /** Options for {@link buttonGroup}. */
@@ -55,6 +56,6 @@ export function buttonGroup(opts: ButtonGroupOptions = {}): void {
 
 	A(`div.s-bgroup${cls} role=group`, opts.attrs, () => {
 		if (opts.buttons) for (const b of opts.buttons) button(b);
-		if (opts.content) opts.content();
+		drawSlot(opts.content);
 	});
 }

package/src/components/dialog.ts

@@ -1,5 +1,5 @@
 import A from "aberdeen";
-import { type Slot, type Attributes, drawSlot } from "../core.js";
+import { type Slot, type Attributes, drawSlot, mountPortal } from "../core.js";
 import { button } from "./button.js";
 import { buttonGroup } from "./buttonGroup.js";
 import { textline } from "./textline.js";
@@ -60,7 +60,7 @@ A.insertGlobalCss({
 			"display:flex align-items:center gap:$2 padding: $2 $3; " +
 			"border-bottom: 1px solid $s-border; font-weight:600 flex-shrink:0",
 		"> footer":
-			"display:flex align-items:center gap:$2 padding: $2 $3; " +
+			"display:flex align-items:center justify-content:flex-end gap:$2 padding: $2 $3; " +
 			"border-top: 1px solid $s-border; flex-shrink:0",
 		"> div": "p:$3 gap:$3 display:flex flex-direction:column overflow-y:auto flex:1 min-height:0",
 		"&.hidden": "opacity:0 pointer-events:none transform: translate(-50%, calc(-50% + 20px)); pointer-events:none",
@@ -75,7 +75,7 @@ const topDialogId = A.derive(() => {
 	if (keys.length) return keys[keys.length-1];
 });
 
-A.mount(document.body, () => {
+mountPortal(() => {
 	A.onEach(dialogs, ({resolve, opts}, dialogId) => {
 		const close = () => { delete dialogs[dialogId]; };
 
@@ -128,8 +128,8 @@ A.mount(document.body, () => {
  *   header: "Confirm",
  *   content: (close) => {
  *     A("p #Are you sure?");
- *     S.button({ text: "Yes", click: () => { doIt(); close(); } });
- *     S.button({ text: "Cancel", attrs: ".neutral .outlined", click: close });
+ *     S.button({ content: "Yes", click: () => { doIt(); close(); } });
+ *     S.button({ content: "Cancel", attrs: ".neutral .outlined", click: close });
  *   },
  * });
  * ```
@@ -176,7 +176,7 @@ export function alert(message: string, opts: Partial<DialogOptions> = {}): Promi
 		content: (close) => {
 			A("p", () => { A("#", message); });
 			buttonGroup({ layout: "spaced", attrs: "align-self:flex-end", content: () => {
-				button({ text: "OK", click: close });
+				button({ content: "OK", click: close });
 			}});
 		},
 		...opts,
@@ -201,8 +201,8 @@ export function confirm(message: string, opts: Partial<DialogOptions> = {}): Pro
 			content: (close) => {
 				A("p", () => { A("#", message); });
 				buttonGroup({ layout: "spaced", attrs: "align-self:flex-end", content: () => {
-					button({ text: "Cancel", attrs: ".neutral .outlined", click: close });
-					button({ text: "OK", click: () => { confirmed = true; close(); } });
+					button({ content: "Cancel", attrs: ".neutral .outlined", click: close });
+					button({ content: "OK", click: () => { confirmed = true; close(); } });
 				}});
 			},
 			...opts,
@@ -241,8 +241,8 @@ export function prompt(message: string, defaultValue = "", opts: Partial<DialogO
 					});
 					textline({ bind: A.ref($v, "value") });
 					buttonGroup({ layout: "spaced", attrs: "align-self:flex-end", content: () => {
-						button({ text: "Cancel", attrs: ".neutral .outlined", type: "button", click: close });
-						button({ text: "OK", type: "submit" });
+						button({ content: "Cancel", attrs: ".neutral .outlined", type: "button", click: close });
+						button({ content: "OK", type: "submit" });
 					}});
 				});
 			},

package/src/components/form.ts

@@ -1,5 +1,5 @@
 import A from "aberdeen";
-import { type Content, type ContentOptions, type Attributes } from "../core.js";
+import { type ContentOptions, type Attributes, type Slot, drawSlot } from "../core.js";
 
 /** Options for {@link form}. */
 export interface FormOptions extends ContentOptions {
@@ -18,7 +18,7 @@ export interface FormOptions extends ContentOptions {
 	/** Aberdeen attr/style string for the action bar. */
 	actionsAttrs?: Attributes;
 	/** Footer actions (typically a {@link import("./buttonGroup").buttonGroup} or buttons). */
-	actions?: Content;
+	actions?: Slot;
 }
 
 A.insertGlobalCss({
@@ -26,7 +26,7 @@ A.insertGlobalCss({
 		"&": "display:flex flex-direction:column gap:$3",
 		"&.grid": "display:grid grid-template-columns: repeat(auto-fit, minmax(16rem, 1fr)); gap:$3",
 		"&.grid > .s-wide, &.grid > footer": "grid-column: 1 / -1;",
-		"> footer": "display:flex align-items:center gap:$2 flex-wrap:wrap margin-top:$1",
+		"> footer": "display:flex align-items:center justify-content:flex-end gap:$2 flex-wrap:wrap margin-top:$1",
 	},
 });
 
@@ -47,12 +47,12 @@ A.insertGlobalCss({
  *     S.textline({ label: "Name", required: true, bind: A.ref($u, "name") });
  *     S.textline({ label: "Email", type: "email", bind: A.ref($u, "email") });
  *   },
- *   actions: () => S.button({ text: "Save", type: "submit" }),
+ *   actions: () => S.button({ content: "Save", type: "submit" }),
  * });
  * ```
  */
-export function form(opts: FormOptions | Content = {}): void {
-	const o: FormOptions = typeof opts === "function" ? { content: opts } : opts;
+export function form(opts: FormOptions | Slot = {}): void {
+	const o: FormOptions = typeof opts === "string" || typeof opts === "function" ? { content: opts } : opts;
 
 	A(`form.s-form`, o.attrs, () => {
 		// Toggle grid class in its own scope so changing layout doesn't recreate
@@ -74,11 +74,11 @@ export function form(opts: FormOptions | Content = {}): void {
 			}
 		});
 
-		if (o.content) o.content();
+		drawSlot(o.content);
 
 		// Own scope so toggling actions doesn't recreate the fields above.
 		A(() => {
-			if (o.actions) A("footer", o.actionsAttrs, () => o.actions?.());
+			if (o.actions) A("footer", o.actionsAttrs, () => drawSlot(o.actions));
 		});
 	});
 }

package/src/components/main.ts

@@ -1,5 +1,5 @@
 import A from "aberdeen";
-import { type Content, type Slot, type Attributes, drawSlot } from "../core.js";
+import { type Slot, type Attributes, drawSlot } from "../core.js";
 import { type MenuOptions, menuButton, drawMenu } from "./menu.js";
 
 /** Options for {@link main}. */
@@ -13,9 +13,9 @@ export interface MainOptions {
 	/** Leading icon/logo in the top bar. */
 	icon?: Slot;
 	/** Action area on the right of the top bar (buttons, menu, ...). */
-	menu?: Content;
-	/** The scrollable page content. */
-	content?: Content;
+	menu?: Slot;
+	/** The scrollable page content. A string is rendered as rich text. */
+	content?: Slot;
 	/** Footer content, pinned below the scroll area. */
 	footer?: Slot;
 	/**
@@ -62,8 +62,9 @@ A.insertGlobalCss({
 		"> 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.
+		// Body always wraps <main> (with or without a sidebar) so max-width centering
+		// and scrollbar alignment work identically in both cases.
+		// .s-body centres .s-body-inner; .s-body-inner caps the content 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.
@@ -71,20 +72,19 @@ A.insertGlobalCss({
 		// 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.
+		// min-height:0 overrides the flex default of min-height:auto so <main> can
+		// shrink to fit the bounded container and show its own scrollbar.
+		".s-body main": "flex:1 min-height:0 overflow-y:auto display:flex flex-direction:column",
+		// The content area fills the scroll region with comfortable padding.
 		// 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",
+		".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",
+		".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
@@ -110,6 +110,9 @@ A.insertGlobalCss({
 		// 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",
+		// At narrow widths, content boxes are full-bleed so there's no inset to
+		// align the scrollbar with — cancel the right margin.
+		".s-main .s-body main.s-scroll-y": "margin-right:0",
 	},
 });
 
@@ -133,7 +136,7 @@ A.insertGlobalCss({
  *     ],
  *   },
  *   navPosition: "left",
- *   menu: () => S.button({ text: "New", attrs: ".small" }),
+ *   menu: () => S.button({ content: "New", attrs: ".small" }),
  *   content: () => drawPage(),
  *   footer: "© 2026",
  * });
@@ -190,30 +193,28 @@ export function main(opts: MainOptions = {}): void {
 						});
 					});
 					A(() => {
-						if (opts.menu) A("div.s-menu", () => opts.menu?.());
+						if (opts.menu) A("div.s-menu", () => drawSlot(opts.menu));
 					});
 				});
 			});
 		});
 
-		// 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);
-					});
+		// Body always wraps <main> so max-width centering and scrollbar alignment
+		// are identical with and without a sidebar nav.
+		A("div.s-body", () => {
+			A("div.s-body-inner", () => {
+				A(() => {
+					if (opts.maxWidth != null) A("max-width:", opts.maxWidth);
+				});
+				if (hasNav && navPos !== "button") {
 					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);
-				});
+				}
+				drawMainContent(opts);
 			});
-		} else {
-			drawMainContent(opts, true);
-		}
+		});
 
 		// Footer — full-width background, content centred to maxWidth via .s-bar.
 		A(() => {
@@ -231,20 +232,10 @@ export function main(opts: MainOptions = {}): void {
 	});
 }
 
-/**
- * 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 {
+function drawMainContent(opts: MainOptions): 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();
+			drawSlot(opts.content);
 		});
 	}) as HTMLElement;
 	watchVerticalOverflow(mainEl);

package/src/components/menu.ts

@@ -1,6 +1,6 @@
 import A from "aberdeen";
 import { matchCurrent } from "aberdeen/route";
-import { type Content, type Slot, type Attributes, drawSlot } from "../core.js";
+import { type Slot, type Attributes, drawSlot, mountPortal } from "../core.js";
 import { button, type ButtonOptions } from "./button.js";
 
 /**
@@ -41,10 +41,10 @@ export interface MenuSeparator {
  * 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,
+ * - A slot (string or draw function) — renders custom content (section header,
  *   avatar, search box, …). Skipped by keyboard navigation.
  */
-export type MenuEntry = MenuItem | MenuSeparator | Content;
+export type MenuEntry = MenuItem | MenuSeparator | Slot;
 
 /** Options for {@link menuButton} and {@link MainOptions.nav}. */
 export interface MenuOptions {
@@ -91,7 +91,7 @@ A.insertGlobalCss({
 	// 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":
+	".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.
@@ -148,7 +148,7 @@ export function drawMenu(items: MenuEntry[], onActivate?: () => void): void {
 	});
 
 	for (const entry of items) {
-		if (typeof entry === "function") { entry(); continue; }
+		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, () => {
@@ -193,7 +193,7 @@ function positionMenu(menuEl: HTMLElement, rect: DOMRect): void {
 	menuEl.style.top  = Math.max(8, y) + "px";
 }
 
-A.mount(document.body, () => {
+mountPortal(() => {
 	const f = $floating.opts;
 	if (!f) return;
 
@@ -275,7 +275,9 @@ export function menuButton(opts: MenuOptions): void {
 
 	button({
 		icon: () => A("span aria-hidden=true #☰"),
-		ariaLabel: "Open menu",
+		// 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",
 		...opts.button,
 		click: (e: Event) => {