staffa 0.2.1 → 0.3.0

package/dist/components/main.d.ts

@@ -1,4 +1,5 @@
 import { type Content, type Slot, type Attributes } from "../core.js";
+import { type MenuOptions } from "./menu.js";
 /** Options for {@link main}. */
 export interface MainOptions {
     /** Aberdeen attr/style string applied to the outermost shell element. */
@@ -16,31 +17,55 @@ 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;
 }
 /**
  * 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",
  * });

package/dist/components/main.js

@@ -1,91 +1,229 @@
 import A from "aberdeen";
 import { drawSlot } from "../core.js";
+import { menuButton, drawMenu } from "./menu.js";
 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 = {}) {
-    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();
             });
-        });
-        // Footer.
+        }
+        else {
+            drawMainContent(opts, true);
+        }
+        // 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, capWidth) {
+    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();
         });
     });
+    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) {
+    if (typeof ResizeObserver === "undefined")
+        return; // No-op outside the browser.
+    const update = () => el.classList.toggle("s-scroll-y", el.offsetWidth > el.clientWidth);
+    const ro = new ResizeObserver(update);
+    ro.observe(el);
+    if (el.firstElementChild)
+        ro.observe(el.firstElementChild);
+    update();
+    A.clean(() => ro.disconnect());
 }

package/dist/components/menu.d.ts

@@ -0,0 +1,118 @@
+import { type Content, type Slot, type Attributes } from "../core.js";
+import { 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;
+}
+/**
+ * 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 declare function drawMenu(items: MenuEntry[], onActivate?: () => void): void;
+/**
+ * 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 declare function showFloatingMenu(opts: FloatingMenuOptions): () => void;
+/**
+ * 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 declare function menuButton(opts: MenuOptions): void;