staffa 0.3.1 → 0.4.0

package/README.md

@@ -4,7 +4,7 @@ A small, opinionated TypeScript component library for the [Aberdeen](https://abe
 
 ```ts
 import A from "aberdeen";
-import S from "staffa";
+import * as S from "staffa";
 
 const $user = A.proxy({ name: "", email: "" });
 
@@ -213,7 +213,7 @@ Two-way binding uses Aberdeen proxies: pass `bind: A.ref($obj, "key")` to form f
 </script>
 <script type="module">
   import A from "aberdeen";
-  import S from "staffa/all.js";
+  import * as S from "staffa/all.js";
   // ...
 </script>
 ```
@@ -265,4 +265,19 @@ npm run build      # compile TypeScript to dist/
 npm run typecheck  # check types
 npm run smoke      # render every component in jsdom
 npx http-server    # allows demo to be viewed at http://localhost:8080/demo
+npx shotest test   # visual tests: click through the demo, screenshotting every step
+npx shotest review # review/accept the visual changes against the baseline
 ```
+
+The visual tests (`tests/*.spec.ts`) need a build first (`npm run build`); they serve the repo root themselves and click through every demo page. Accepted baselines live in `test-accepted/`.
+
+## AI skill
+
+If you use Claude Code, GitHub Copilot or another AI agents that supports Skills, Staffa includes a `skill/` directory that provides specialized knowledge to the AI about how to use the library effectively.
+
+To use this, it is recommended to symlink the skill into your project's `.claude/skills` directory:
+
+```sh
+mkdir -p .claude/skills
+ln -s ../../node_modules/staffa/skill .claude/skills/staffa
+```

package/dist/components/box.d.ts

@@ -1,4 +1,4 @@
-import { type Content, type ContentOptions, type Slot, type Attributes } from "../core.js";
+import { type ContentOptions, type Slot, type Attributes } from "../core.js";
 /** Options for {@link box}. */
 export interface BoxOptions extends ContentOptions {
     /** Header content, drawn in a styled bar above the body. */
@@ -30,4 +30,4 @@ export interface BoxOptions extends ContentOptions {
  * S.box(() => A("p#Just some content"));   // shorthand
  * ```
  */
-export declare function box(opts?: BoxOptions | Content): void;
+export declare function box(opts?: BoxOptions | Slot): void;

package/dist/components/box.js

@@ -9,7 +9,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",
     },
 });
@@ -32,7 +32,7 @@ A.insertGlobalCss({
  * ```
  */
 export function box(opts = {}) {
-    const o = typeof opts === "function" ? { content: opts } : opts;
+    const o = 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
         // the body (which may hold focused inputs / lots of content).
@@ -41,8 +41,7 @@ export function box(opts = {}) {
                 A("header.s-s.raised", o.headerAttrs, () => drawSlot(o.header));
         });
         A("div", o.contentAttrs, () => {
-            if (o.content)
-                o.content();
+            drawSlot(o.content);
         });
         A(() => {
             if (o.footer != null)

package/dist/components/button.d.ts

@@ -1,10 +1,8 @@
-import { type Content, type Slot, type Attributes } from "../core.js";
+import { type Slot, type Attributes } 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. */
@@ -39,15 +37,15 @@ export interface ButtonOptions {
  * 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 declare function button(opts?: ButtonOptions | string | Content): void;
+export declare function button(opts?: ButtonOptions | Slot): void;

package/dist/components/button.js

@@ -17,14 +17,15 @@ 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;",
-        "&.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);",
+        // 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.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`
@@ -47,19 +48,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 = {}) {
-    const o = typeof opts === "string" ? { text: opts } : typeof opts === "function" ? { content: opts } : opts;
+    const o = typeof opts === "string" || typeof opts === "function" ? { content: opts } : opts;
     const tag = o.href != null ? "a" : "button";
     // 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`,
@@ -82,9 +83,6 @@ export function button(opts = {}) {
         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/dist/components/buttonChooser.d.ts

@@ -10,13 +10,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. */
@@ -24,14 +24,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,

package/dist/components/buttonChooser.js

@@ -2,14 +2,14 @@ import A from "aberdeen";
 import { buttonGroup } from "./buttonGroup.js";
 /**
  * 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,
@@ -22,11 +22,13 @@ export function buttonChooser(opts) {
         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/dist/components/buttonGroup.js

@@ -1,4 +1,5 @@
 import A from "aberdeen";
+import { drawSlot } from "../core.js";
 import { button } from "./button.js";
 A.insertGlobalCss({
     ".s-bgroup": {
@@ -37,7 +38,6 @@ export function buttonGroup(opts = {}) {
         if (opts.buttons)
             for (const b of opts.buttons)
                 button(b);
-        if (opts.content)
-            opts.content();
+        drawSlot(opts.content);
     });
 }

package/dist/components/dialog.d.ts

@@ -52,8 +52,8 @@ export interface DialogOptions {
  *   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 });
  *   },
  * });
  * ```

package/dist/components/dialog.js

@@ -1,5 +1,5 @@
 import A from "aberdeen";
-import { drawSlot } from "../core.js";
+import { drawSlot, mountPortal } from "../core.js";
 import { button } from "./button.js";
 import { buttonGroup } from "./buttonGroup.js";
 import { textline } from "./textline.js";
@@ -17,7 +17,7 @@ A.insertGlobalCss({
             "transition: opacity 0.2s ease-out, transform 0.2s ease-out;",
         "> header": "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; " +
+        "> footer": "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",
@@ -30,7 +30,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]; };
         A.clean(() => {
@@ -78,8 +78,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 });
  *   },
  * });
  * ```
@@ -126,7 +126,7 @@ export function alert(message, opts = {}) {
         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,
@@ -150,8 +150,8 @@ export function confirm(message, opts = {}) {
             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,
@@ -189,8 +189,8 @@ export function prompt(message, defaultValue = "", opts = {}) {
                     });
                     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/dist/components/form.d.ts

@@ -1,4 +1,4 @@
-import { type Content, type ContentOptions, type Attributes } from "../core.js";
+import { type ContentOptions, type Attributes, type Slot } from "../core.js";
 /** Options for {@link form}. */
 export interface FormOptions extends ContentOptions {
     /**
@@ -16,7 +16,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;
 }
 /**
  * An opinionated `<form>` wrapper that lays its fields out consistently — a clean
@@ -35,8 +35,8 @@ export interface FormOptions extends ContentOptions {
  *     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 declare function form(opts?: FormOptions | Content): void;
+export declare function form(opts?: FormOptions | Slot): void;

package/dist/components/form.js

@@ -1,10 +1,11 @@
 import A from "aberdeen";
+import { drawSlot } from "../core.js";
 A.insertGlobalCss({
     ".s-form": {
         "&": "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",
     },
 });
 /**
@@ -24,12 +25,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 = {}) {
-    const o = typeof opts === "function" ? { content: opts } : opts;
+    const o = 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
         // the fields (which would lose focus / input state).
@@ -48,12 +49,11 @@ export function form(opts = {}) {
                 o.submit(data, event);
             }
         });
-        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?.());
+                A("footer", o.actionsAttrs, () => drawSlot(o.actions));
         });
     });
 }

package/dist/components/main.d.ts

@@ -1,4 +1,4 @@
-import { type Content, type Slot, type Attributes } from "../core.js";
+import { type Slot, type Attributes } from "../core.js";
 import { type MenuOptions } from "./menu.js";
 /** Options for {@link main}. */
 export interface MainOptions {
@@ -11,9 +11,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;
     /**
@@ -65,7 +65,7 @@ export interface MainOptions {
  *     ],
  *   },
  *   navPosition: "left",
- *   menu: () => S.button({ text: "New", attrs: ".small" }),
+ *   menu: () => S.button({ content: "New", attrs: ".small" }),
  *   content: () => drawPage(),
  *   footer: "© 2026",
  * });

package/dist/components/main.js

@@ -15,8 +15,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.
@@ -24,20 +25,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
@@ -63,6 +63,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",
     },
 });
 /**
@@ -85,7 +88,7 @@ A.insertGlobalCss({
  *     ],
  *   },
  *   navPosition: "left",
- *   menu: () => S.button({ text: "New", attrs: ".small" }),
+ *   menu: () => S.button({ content: "New", attrs: ".small" }),
  *   content: () => drawPage(),
  *   footer: "© 2026",
  * });
@@ -146,31 +149,28 @@ export function main(opts = {}) {
                     });
                     A(() => {
                         if (opts.menu)
-                            A("div.s-menu", () => 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(() => {
             if (opts.footer != null) {
@@ -187,22 +187,10 @@ export function main(opts = {}) {
         });
     });
 }
-/**
- * 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, capWidth) {
+function drawMainContent(opts) {
     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);
         });
     });
     watchVerticalOverflow(mainEl);

package/dist/components/menu.d.ts

@@ -1,4 +1,4 @@
-import { type Content, type Slot, type Attributes } from "../core.js";
+import { type Slot, type Attributes } from "../core.js";
 import { type ButtonOptions } from "./button.js";
 /**
  * A clickable item in a menu or sidebar nav.
@@ -36,10 +36,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 {
     /** Items shown in the dropdown or sidebar nav. */

package/dist/components/menu.js

@@ -1,6 +1,6 @@
 import A from "aberdeen";
 import { matchCurrent } from "aberdeen/route";
-import { drawSlot } from "../core.js";
+import { drawSlot, mountPortal } from "../core.js";
 import { button } from "./button.js";
 // 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
@@ -68,8 +68,8 @@ export function drawMenu(items, onActivate) {
         els[next].focus();
     });
     for (const entry of items) {
-        if (typeof entry === "function") {
-            entry();
+        if (typeof entry === "string" || typeof entry === "function") {
+            drawSlot(entry);
             continue;
         }
         if ("separator" in entry) {
@@ -122,7 +122,7 @@ function positionMenu(menuEl, rect) {
     menuEl.style.left = Math.max(8, x) + "px";
     menuEl.style.top = Math.max(8, y) + "px";
 }
-A.mount(document.body, () => {
+mountPortal(() => {
     const f = $floating.opts;
     if (!f)
         return;
@@ -202,7 +202,9 @@ export function menuButton(opts) {
         closeFloating(); });
     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) => {