@mdbase-dev/ui 0.1.0-beta.117

package/dist/brand.d.ts

@@ -0,0 +1,99 @@
+import { type JSX } from "react";
+import type { MdbaseAppId } from "./apps.js";
+export type MdbaseMarkRect = Readonly<{
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    rx: number;
+}>;
+export declare const mdbaseMarkMotions: readonly ["bootstrap", "unfold", "rebalance", "conveyor"];
+export type MdbaseMarkMotion = typeof mdbaseMarkMotions[number];
+export declare function mdbaseMarkMotionClass(motion?: MdbaseMarkMotion): string;
+export declare const MDBASE_MARK_VIEW_BOX = "18 18 84 84";
+export declare const mdbaseMarkInkRects: readonly [{
+    readonly x: 22;
+    readonly y: 22;
+    readonly width: 20;
+    readonly height: 10;
+    readonly rx: 2;
+}, {
+    readonly x: 50;
+    readonly y: 22;
+    readonly width: 20;
+    readonly height: 10;
+    readonly rx: 2;
+}, {
+    readonly x: 78;
+    readonly y: 22;
+    readonly width: 20;
+    readonly height: 10;
+    readonly rx: 2;
+}, {
+    readonly x: 22;
+    readonly y: 44;
+    readonly width: 12;
+    readonly height: 10;
+    readonly rx: 2;
+}, {
+    readonly x: 22;
+    readonly y: 66;
+    readonly width: 28;
+    readonly height: 10;
+    readonly rx: 2;
+}, {
+    readonly x: 58;
+    readonly y: 66;
+    readonly width: 40;
+    readonly height: 10;
+    readonly rx: 2;
+}, {
+    readonly x: 22;
+    readonly y: 88;
+    readonly width: 20;
+    readonly height: 10;
+    readonly rx: 2;
+}, {
+    readonly x: 50;
+    readonly y: 88;
+    readonly width: 20;
+    readonly height: 10;
+    readonly rx: 2;
+}, {
+    readonly x: 78;
+    readonly y: 88;
+    readonly width: 20;
+    readonly height: 10;
+    readonly rx: 2;
+}];
+export declare const mdbaseMarkAccentRect: {
+    readonly x: 42;
+    readonly y: 44;
+    readonly width: 56;
+    readonly height: 10;
+    readonly rx: 2;
+};
+/**
+ * The platform's Frontmatter mark. Editor and Connect's own surfaces use it; the
+ * segments and clipped conveyor exist so `motion.css` can animate the same SVG.
+ */
+export declare function MdbaseMark({ motion, className }: {
+    motion?: MdbaseMarkMotion;
+    className?: string;
+}): JSX.Element;
+/**
+ * An app's mark: the platform mark inverted, so the bars take the app's colour and
+ * the highlighted line stays ink. The plain mark stays the platform's own.
+ */
+export declare function MdbaseAppMark({ app, className }: {
+    app: MdbaseAppId;
+    className?: string;
+}): JSX.Element;
+/**
+ * `mdbase` followed by the product's quieter name. Editor carries the platform mark
+ * as the canonical app; Reader and Writer carry their app marks.
+ */
+export declare function Wordmark({ app, motion }: {
+    app: MdbaseAppId;
+    motion?: MdbaseMarkMotion;
+}): JSX.Element;

package/dist/brand.js

@@ -0,0 +1,61 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId } from "react";
+export const mdbaseMarkMotions = [
+    "bootstrap",
+    "unfold",
+    "rebalance",
+    "conveyor"
+];
+export function mdbaseMarkMotionClass(motion) {
+    return motion ? ` mdbase-motion-${motion}` : "";
+}
+export const MDBASE_MARK_VIEW_BOX = "18 18 84 84";
+export const mdbaseMarkInkRects = [
+    { x: 22, y: 22, width: 20, height: 10, rx: 2 },
+    { x: 50, y: 22, width: 20, height: 10, rx: 2 },
+    { x: 78, y: 22, width: 20, height: 10, rx: 2 },
+    { x: 22, y: 44, width: 12, height: 10, rx: 2 },
+    { x: 22, y: 66, width: 28, height: 10, rx: 2 },
+    { x: 58, y: 66, width: 40, height: 10, rx: 2 },
+    { x: 22, y: 88, width: 20, height: 10, rx: 2 },
+    { x: 50, y: 88, width: 20, height: 10, rx: 2 },
+    { x: 78, y: 88, width: 20, height: 10, rx: 2 }
+];
+export const mdbaseMarkAccentRect = {
+    x: 42,
+    y: 44,
+    width: 56,
+    height: 10,
+    rx: 2
+};
+const conveyorXs = [-6, 22, 50, 78, 106];
+function classes(...names) {
+    return names.filter(Boolean).join(" ");
+}
+function Segment({ rect, index, accent = false }) {
+    return _jsx("rect", { className: `mdbase-mark-segment mdbase-mark-segment-${index} ${accent ? "mdbase-mark-accent" : "mdbase-mark-ink"}`, pathLength: 1, ...rect });
+}
+/**
+ * The platform's Frontmatter mark. Editor and Connect's own surfaces use it; the
+ * segments and clipped conveyor exist so `motion.css` can animate the same SVG.
+ */
+export function MdbaseMark({ motion, className }) {
+    const clipId = `mdbase-fences-${useId().replaceAll(":", "")}`;
+    return _jsxs("svg", { className: classes("mdbase-mark", className) + mdbaseMarkMotionClass(motion), viewBox: MDBASE_MARK_VIEW_BOX, "aria-hidden": "true", focusable: "false", children: [_jsx("defs", { children: _jsxs("clipPath", { id: clipId, children: [_jsx("rect", { x: "22", y: "22", width: "76", height: "10", rx: "2" }), _jsx("rect", { x: "22", y: "88", width: "76", height: "10", rx: "2" })] }) }), _jsx("g", { className: "mdbase-mark-fence mdbase-mark-fence-top", children: mdbaseMarkInkRects.slice(0, 3).map((rect, index) => _jsx(Segment, { rect: rect, index: index + 1 }, `${rect.x}-${rect.y}`)) }), _jsxs("g", { className: "mdbase-mark-row mdbase-mark-row-top", children: [_jsx(Segment, { rect: mdbaseMarkInkRects[3], index: 4 }), _jsx(Segment, { rect: mdbaseMarkAccentRect, index: 5, accent: true })] }), _jsxs("g", { className: "mdbase-mark-row mdbase-mark-row-bottom", children: [_jsx(Segment, { rect: mdbaseMarkInkRects[4], index: 6 }), _jsx(Segment, { rect: mdbaseMarkInkRects[5], index: 7 })] }), _jsx("g", { className: "mdbase-mark-fence mdbase-mark-fence-bottom", children: mdbaseMarkInkRects.slice(6).map((rect, index) => _jsx(Segment, { rect: rect, index: index + 8 }, `${rect.x}-${rect.y}`)) }), _jsx("g", { clipPath: `url(#${clipId})`, children: _jsx("g", { className: "mdbase-mark-conveyor-track", children: conveyorXs.flatMap((x) => [22, 88].map((y) => _jsx("rect", { x: x, y: y, width: "20", height: "10", rx: "2" }, `${x}-${y}`))) }) })] });
+}
+/**
+ * An app's mark: the platform mark inverted, so the bars take the app's colour and
+ * the highlighted line stays ink. The plain mark stays the platform's own.
+ */
+export function MdbaseAppMark({ app, className }) {
+    return _jsxs("svg", { className: classes("mdbase-app-mark", `is-${app}`, className), viewBox: MDBASE_MARK_VIEW_BOX, "aria-hidden": "true", focusable: "false", children: [_jsx("g", { className: "mdbase-app-mark-bars", children: mdbaseMarkInkRects.map((rect) => _jsx("rect", { ...rect }, `${rect.x}-${rect.y}`)) }), _jsx("rect", { className: "mdbase-app-mark-line", ...mdbaseMarkAccentRect })] });
+}
+/**
+ * `mdbase` followed by the product's quieter name. Editor carries the platform mark
+ * as the canonical app; Reader and Writer carry their app marks.
+ */
+export function Wordmark({ app, motion }) {
+    return _jsxs("span", { className: "wordmark", children: [app === "editor"
+                ? _jsx(MdbaseMark, { motion: motion, className: "wordmark-mark" })
+                : _jsx(MdbaseAppMark, { app: app, className: "wordmark-mark" }), _jsxs("span", { className: "wordmark-label", children: [_jsx("span", { children: "mdbase" }), _jsx("strong", { children: app })] })] });
+}

package/dist/codemirror.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The popups an mdbase editor shows: completion lists, their info panels, hover cards and
+ * lint diagnostics. Reader's completion picker, in Editor's quiet treatment: a fine outline,
+ * 2px corners and no shadow. Tooltips mounted outside the editor still carry this theme.
+ *
+ * Completion `type`s map to icons: `citation` (@) and `annotation` (❝) reference sources,
+ * `source` and `text` are records, `keyword` is a command, `namespace` a folder, `type` a type.
+ */
+export declare const mdbasePopupTheme: import("@codemirror/state").Extension;

package/dist/codemirror.js

@@ -0,0 +1,98 @@
+import { EditorView } from "@codemirror/view";
+/**
+ * The popups an mdbase editor shows: completion lists, their info panels, hover cards and
+ * lint diagnostics. Reader's completion picker, in Editor's quiet treatment: a fine outline,
+ * 2px corners and no shadow. Tooltips mounted outside the editor still carry this theme.
+ *
+ * Completion `type`s map to icons: `citation` (@) and `annotation` (❝) reference sources,
+ * `source` and `text` are records, `keyword` is a command, `namespace` a folder, `type` a type.
+ */
+export const mdbasePopupTheme = EditorView.theme({
+    ".cm-tooltip": {
+        border: "1px solid var(--color-border-strong)",
+        borderRadius: "var(--control-radius, 2px)",
+        color: "var(--color-text)",
+        backgroundColor: "var(--color-surface)",
+        boxShadow: "none",
+        fontFamily: "var(--sans)"
+    },
+    ".cm-tooltip.cm-tooltip-autocomplete": { padding: "4px" },
+    ".cm-tooltip.cm-tooltip-autocomplete > ul": {
+        width: "min(440px, calc(100vw - 24px))",
+        minWidth: "0",
+        maxWidth: "none",
+        maxHeight: "min(252px, 45vh)",
+        fontFamily: "var(--sans)",
+        whiteSpace: "normal"
+    },
+    ".cm-tooltip.cm-tooltip-autocomplete > ul > li": {
+        display: "grid",
+        gridTemplateColumns: "20px minmax(0, 1fr)",
+        columnGap: "8px",
+        alignItems: "center",
+        padding: "6px 8px",
+        borderRadius: "var(--control-radius, 2px)",
+        lineHeight: "1.35"
+    },
+    ".cm-tooltip.cm-tooltip-autocomplete > ul > li[aria-selected]": {
+        color: "var(--color-text)",
+        background: "var(--color-selected)"
+    },
+    ".cm-tooltip.cm-tooltip-autocomplete > ul > li > *": {
+        minWidth: "0",
+        overflow: "hidden",
+        textOverflow: "ellipsis",
+        whiteSpace: "nowrap"
+    },
+    ".cm-completionIcon": {
+        gridRow: "1 / span 2",
+        width: "20px",
+        padding: "0",
+        color: "var(--color-text-muted)",
+        fontSize: "13px",
+        lineHeight: "20px",
+        textAlign: "center",
+        opacity: "1"
+    },
+    ".cm-completionIcon-citation::after": { content: '"@"', color: "var(--color-accent)" },
+    ".cm-completionIcon-annotation::after": { content: '"❝"', color: "var(--color-accent)" },
+    ".cm-completionIcon-source::after, .cm-completionIcon-text::after": { content: '"§"' },
+    ".cm-completionIcon-keyword::after": { content: '"/"' },
+    ".cm-completionIcon-namespace::after": { content: '"▤"' },
+    ".cm-completionIcon-type::after": { content: '"T"' },
+    ".cm-completionLabel": {
+        gridColumn: "2",
+        color: "var(--color-text)",
+        fontSize: "13px",
+        fontWeight: "700"
+    },
+    ".cm-completionMatchedText": {
+        textDecoration: "none",
+        color: "var(--color-accent)"
+    },
+    ".cm-completionDetail": {
+        gridColumn: "2",
+        marginLeft: "0",
+        color: "var(--color-text-muted)",
+        fontSize: "11px",
+        fontStyle: "normal"
+    },
+    ".cm-completionListIncompleteTop:before, .cm-completionListIncompleteBottom:after": {
+        color: "var(--color-text-faint)",
+        fontSize: "11px"
+    },
+    ".cm-tooltip.cm-completionInfo": {
+        maxWidth: "min(320px, calc(100vw - 24px))",
+        margin: "0 4px",
+        padding: "10px 12px",
+        color: "var(--color-text-soft)",
+        fontSize: "12px",
+        lineHeight: "1.5",
+        whiteSpace: "pre-line"
+    },
+    ".cm-tooltip.cm-tooltip-lint": { padding: "4px", fontSize: "12px" },
+    ".cm-diagnostic": { padding: "4px 8px", borderRadius: "var(--control-radius, 2px)", fontFamily: "var(--sans)" },
+    ".cm-diagnostic-error": { borderLeft: "3px solid var(--color-danger)" },
+    ".cm-diagnostic-warning": { borderLeft: "3px solid var(--color-warning)" },
+    ".cm-diagnostic-info, .cm-diagnostic-hint": { borderLeft: "3px solid var(--color-accent)" }
+});

package/dist/popover.d.ts

@@ -0,0 +1,50 @@
+import { type KeyboardEvent, type RefObject } from "react";
+interface Box {
+    readonly top: number;
+    readonly bottom: number;
+    readonly left: number;
+    readonly width: number;
+}
+interface Size {
+    readonly width: number;
+    readonly height: number;
+}
+/**
+ * Where a popover opens beside its trigger: below when it fits, otherwise on whichever side
+ * has more room, lined up with the trigger's start (or end) edge and kept inside the viewport.
+ */
+export declare function anchoredPlacement(trigger: Box, popover: Size, viewport: Size, { gap, margin, align }?: {
+    gap?: number;
+    margin?: number;
+    align?: "start" | "end";
+}): {
+    readonly top: number;
+    readonly left: number;
+    readonly maxHeight: number;
+};
+/**
+ * Shows a select's list in the top layer beside its trigger, focuses it, and dismisses it when
+ * the pointer lands elsewhere or the page scrolls or resizes underneath it.
+ */
+export declare function useSelectPopover(open: boolean, triggerRef: RefObject<HTMLElement | null>, listRef: RefObject<HTMLElement | null>, onDismiss: () => void): void;
+export interface MenuPopoverOptions {
+    /** Preferred width; narrow viewports shrink it. Omit it to leave the width to CSS. */
+    readonly width?: number | undefined;
+    /** Which edge of the trigger the menu lines up with. */
+    readonly align?: "start" | "end" | undefined;
+    /** Element focused when the menu opens; the menu itself when nothing matches. */
+    readonly focus?: string | undefined;
+    /** While true, outside presses, Escape and Tab leave the menu open (an action is running). */
+    readonly busy?: boolean | undefined;
+}
+/**
+ * Keeps a mounted menu in the top layer beside its trigger. It closes on an outside press,
+ * Escape (returning focus to the trigger), Tab or a resize.
+ */
+export declare function useMenuPopover(menuRef: RefObject<HTMLElement | null>, triggerRef: RefObject<HTMLElement | null>, onClose: (refocus: boolean) => void, { width, align, focus, busy }: MenuPopoverOptions): void;
+/**
+ * Arrow keys, Home and End move between a menu's enabled items. From a text field inside the
+ * menu (a filter), Home and End stay in the field and the arrows enter the list.
+ */
+export declare function moveMenuFocus(event: KeyboardEvent, menu: HTMLElement | null): void;
+export {};

package/dist/popover.js

@@ -0,0 +1,162 @@
+import { useEffect, useEffectEvent, useLayoutEffect } from "react";
+/**
+ * Where a popover opens beside its trigger: below when it fits, otherwise on whichever side
+ * has more room, lined up with the trigger's start (or end) edge and kept inside the viewport.
+ */
+export function anchoredPlacement(trigger, popover, viewport, { gap = 4, margin = 8, align = "start" } = {}) {
+    const below = viewport.height - trigger.bottom - gap - margin;
+    const above = trigger.top - gap - margin;
+    const opensUp = popover.height > below && above > below;
+    const room = Math.max(120, opensUp ? above : below);
+    const height = Math.min(popover.height, room);
+    const width = Math.max(popover.width, trigger.width);
+    const start = align === "end" ? trigger.left + trigger.width - width : trigger.left;
+    return {
+        top: opensUp ? trigger.top - gap - height : trigger.bottom + gap,
+        left: Math.max(margin, Math.min(start, viewport.width - width - margin)),
+        maxHeight: room
+    };
+}
+function place(trigger, popover, options) {
+    const box = trigger.getBoundingClientRect();
+    if (options.matchWidth)
+        popover.style.minWidth = `${box.width}px`;
+    popover.style.maxHeight = "";
+    const placement = anchoredPlacement(box, { width: popover.offsetWidth, height: popover.scrollHeight }, { width: window.innerWidth, height: window.innerHeight }, options);
+    popover.style.top = `${placement.top}px`;
+    popover.style.left = `${placement.left}px`;
+    popover.style.maxHeight = `${placement.maxHeight}px`;
+}
+// Browsers without the Popover API (and jsdom) keep the element in place instead.
+function showInTopLayer(element) {
+    if (typeof element.showPopover === "function")
+        element.showPopover();
+}
+function hideFromTopLayer(element) {
+    if (typeof element.hidePopover === "function" && element.matches(":popover-open"))
+        element.hidePopover();
+}
+function onScreen(element) {
+    const box = element.getBoundingClientRect();
+    return box.width > 0 && box.bottom > 0 && box.top < window.innerHeight
+        && box.right > 0 && box.left < window.innerWidth;
+}
+/**
+ * Shows a select's list in the top layer beside its trigger, focuses it, and dismisses it when
+ * the pointer lands elsewhere or the page scrolls or resizes underneath it.
+ */
+export function useSelectPopover(open, triggerRef, listRef, onDismiss) {
+    const dismiss = useEffectEvent(onDismiss);
+    useLayoutEffect(() => {
+        const list = listRef.current;
+        const trigger = triggerRef.current;
+        if (!open || !list || !trigger)
+            return undefined;
+        showInTopLayer(list);
+        place(trigger, list, { matchWidth: true });
+        list.focus({ preventScroll: true });
+        return () => {
+            hideFromTopLayer(list);
+        };
+    }, [open, triggerRef, listRef]);
+    useEffect(() => {
+        const list = listRef.current;
+        const trigger = triggerRef.current;
+        if (!open || !list || !trigger)
+            return undefined;
+        const outside = (event) => {
+            const target = event.target;
+            if (target && !list.contains(target) && !trigger.contains(target))
+                dismiss();
+        };
+        // Content under the list can move (a panel scrolls, a list re-renders): the list follows
+        // its trigger, and closes only once the trigger has left the screen.
+        const follow = (event) => {
+            if (list.contains(event.target))
+                return;
+            if (onScreen(trigger))
+                place(trigger, list, { matchWidth: true });
+            else
+                dismiss();
+        };
+        const onResize = () => dismiss();
+        document.addEventListener("pointerdown", outside, true);
+        document.addEventListener("scroll", follow, true);
+        window.addEventListener("resize", onResize);
+        return () => {
+            document.removeEventListener("pointerdown", outside, true);
+            document.removeEventListener("scroll", follow, true);
+            window.removeEventListener("resize", onResize);
+        };
+    }, [open, triggerRef, listRef]);
+}
+/**
+ * Keeps a mounted menu in the top layer beside its trigger. It closes on an outside press,
+ * Escape (returning focus to the trigger), Tab or a resize.
+ */
+export function useMenuPopover(menuRef, triggerRef, onClose, { width, align = "start", focus = '[aria-checked="true"], [role^="menuitem"]', busy = false }) {
+    const close = useEffectEvent(onClose);
+    const locked = useEffectEvent(() => busy);
+    useLayoutEffect(() => {
+        const menu = menuRef.current;
+        const trigger = triggerRef.current;
+        if (!menu || !trigger)
+            return undefined;
+        showInTopLayer(menu);
+        if (width !== undefined)
+            menu.style.width = `${Math.min(width, window.innerWidth - 16)}px`;
+        place(trigger, menu, { gap: 6, align, matchWidth: false });
+        (menu.querySelector(focus) ?? menu).focus({ preventScroll: true });
+        return () => {
+            hideFromTopLayer(menu);
+        };
+    }, [menuRef, triggerRef, width, align, focus]);
+    useEffect(() => {
+        const onPointerDown = (event) => {
+            const target = event.target;
+            if (target && !locked() && !menuRef.current?.contains(target) && !triggerRef.current?.contains(target)) {
+                close(false);
+            }
+        };
+        const onKeyDown = (event) => {
+            if ((event.key === "Escape" || event.key === "Tab") && !locked()) {
+                if (event.key === "Escape") {
+                    event.preventDefault();
+                    event.stopPropagation();
+                }
+                close(event.key === "Escape");
+            }
+        };
+        const onResize = () => close(false);
+        document.addEventListener("pointerdown", onPointerDown, true);
+        document.addEventListener("keydown", onKeyDown, true);
+        window.addEventListener("resize", onResize);
+        return () => {
+            document.removeEventListener("pointerdown", onPointerDown, true);
+            document.removeEventListener("keydown", onKeyDown, true);
+            window.removeEventListener("resize", onResize);
+        };
+    }, [menuRef, triggerRef]);
+}
+/**
+ * Arrow keys, Home and End move between a menu's enabled items. From a text field inside the
+ * menu (a filter), Home and End stay in the field and the arrows enter the list.
+ */
+export function moveMenuFocus(event, menu) {
+    if (!menu || !["ArrowDown", "ArrowUp", "Home", "End"].includes(event.key))
+        return;
+    const items = [...menu.querySelectorAll('[role^="menuitem"]:not(:disabled)')];
+    const inField = document.activeElement instanceof HTMLInputElement && menu.contains(document.activeElement);
+    if (inField && (event.key === "Home" || event.key === "End"))
+        return;
+    event.preventDefault();
+    const current = items.indexOf(document.activeElement);
+    const next = event.key === "Home"
+        ? 0
+        : event.key === "End"
+            ? items.length - 1
+            : inField
+                ? 0
+                : (current + (event.key === "ArrowDown" ? 1 : -1) + items.length) % items.length;
+    items[next]?.focus({ preventScroll: true });
+}

package/dist/screens.d.ts

@@ -0,0 +1,29 @@
+import type { JSX, ReactNode } from "react";
+import type { MdbaseAppId } from "./apps.js";
+/**
+ * What an app shows while it opens a collection: its wordmark, held still, and a quiet line
+ * saying what it is waiting for. A failure keeps the same place and offers a retry.
+ */
+export declare function OpeningScreen({ app, title, detail, error, onRetry }: {
+    readonly app: MdbaseAppId;
+    readonly title: string;
+    readonly detail?: string | undefined;
+    readonly error?: string | null | undefined;
+    readonly onRetry?: (() => void) | undefined;
+}): JSX.Element;
+/**
+ * The screen before a collection is open: the app's wordmark, a headline, what the app will
+ * do, what went wrong if anything, and then the actions (children) for connecting. A status
+ * and an error that say the same thing are said once; technical detail waits behind a
+ * disclosure.
+ */
+export declare function ConnectLayout({ app, title, lead, status, error, detail, footnote, children }: {
+    readonly app: MdbaseAppId;
+    readonly title: ReactNode;
+    readonly lead?: ReactNode | undefined;
+    readonly status?: string | null | undefined;
+    readonly error?: string | null | undefined;
+    readonly detail?: string | null | undefined;
+    readonly footnote?: ReactNode | undefined;
+    readonly children?: ReactNode | undefined;
+}): JSX.Element;

package/dist/screens.js

@@ -0,0 +1,18 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Wordmark } from "./brand.js";
+/**
+ * What an app shows while it opens a collection: its wordmark, held still, and a quiet line
+ * saying what it is waiting for. A failure keeps the same place and offers a retry.
+ */
+export function OpeningScreen({ app, title, detail, error, onRetry }) {
+    return _jsx("main", { className: "mdbase-opening", "data-loading-state": error ? "failed" : "opening", "aria-label": title, "aria-busy": !error, children: _jsxs("div", { className: "mdbase-opening-message", role: error ? "alert" : "status", children: [_jsx(Wordmark, { app: app }), _jsxs("div", { children: [_jsx("p", { children: error ?? title }), !error && detail && _jsx("small", { children: detail })] }), error && onRetry && _jsx("button", { type: "button", className: "mdbase-button", onClick: onRetry, children: "Try again" })] }) });
+}
+/**
+ * The screen before a collection is open: the app's wordmark, a headline, what the app will
+ * do, what went wrong if anything, and then the actions (children) for connecting. A status
+ * and an error that say the same thing are said once; technical detail waits behind a
+ * disclosure.
+ */
+export function ConnectLayout({ app, title, lead, status, error, detail, footnote, children }) {
+    return _jsx("main", { className: "mdbase-connect-screen", children: _jsxs("section", { children: [_jsx(Wordmark, { app: app }), _jsx("h1", { children: title }), lead && _jsx("p", { className: "mdbase-connect-lead", children: lead }), status && status !== error && _jsx("p", { className: "mdbase-connect-status", role: "status", children: status }), error && _jsx("p", { className: "mdbase-connect-error", role: "alert", children: error }), detail && _jsxs("details", { className: "mdbase-connect-detail", children: [_jsx("summary", { children: "Details" }), _jsx("code", { children: detail })] }), children, footnote && _jsx("p", { className: "mdbase-connect-footnote", children: footnote })] }) });
+}

package/dist/select-model.d.ts

@@ -0,0 +1,34 @@
+export interface SelectOption<Value extends string = string> {
+    readonly value: Value;
+    readonly label: string;
+    readonly disabled?: boolean | undefined;
+}
+export interface SelectOptionGroup<Value extends string = string> {
+    readonly label: string;
+    readonly options: readonly SelectOption<Value>[];
+}
+export type SelectItems<Value extends string = string> = readonly (SelectOption<Value> | SelectOptionGroup<Value>)[];
+export interface FlatSelectOption<Value extends string = string> extends SelectOption<Value> {
+    /** The group heading this option sits under, if any. */
+    readonly group?: string | undefined;
+}
+export declare function isOptionGroup<Value extends string>(item: SelectOption<Value> | SelectOptionGroup<Value>): item is SelectOptionGroup<Value>;
+/** Options in display order, each remembering its group. */
+export declare function flattenOptions<Value extends string>(items: SelectItems<Value>): readonly FlatSelectOption<Value>[];
+/** The next enabled option from `from` in `direction`, stopping at the ends like a native list. */
+export declare function stepOption(options: readonly SelectOption[], from: number, direction: 1 | -1): number;
+/** The first (or last) enabled option, or -1 when every option is disabled. */
+export declare function edgeOption(options: readonly SelectOption[], edge: "first" | "last"): number;
+/**
+ * Type-to-select: the next enabled option whose label starts with what was typed. Typing one
+ * letter repeatedly cycles through the options that start with it, as a native select does.
+ */
+export declare function typeaheadOption(options: readonly SelectOption[], typed: string, from: number): number;
+/** Where each item's options start in the flattened list, so groups can render in place. */
+export declare function itemOffsets<Value extends string>(items: SelectItems<Value>): readonly number[];
+export interface TypeaheadBuffer {
+    readonly text: string;
+    readonly at: number;
+}
+/** Appends a typed key, starting over after a pause, as native selects do. */
+export declare function extendTypeahead(buffer: TypeaheadBuffer, key: string, at: number): TypeaheadBuffer;

package/dist/select-model.js

@@ -0,0 +1,53 @@
+export function isOptionGroup(item) {
+    return "options" in item;
+}
+/** Options in display order, each remembering its group. */
+export function flattenOptions(items) {
+    return items.flatMap((item) => isOptionGroup(item) ? item.options.map((option) => ({ ...option, group: item.label })) : [item]);
+}
+/** The next enabled option from `from` in `direction`, stopping at the ends like a native list. */
+export function stepOption(options, from, direction) {
+    for (let index = from + direction; index >= 0 && index < options.length; index += direction) {
+        if (!options[index]?.disabled) {
+            return index;
+        }
+    }
+    return from;
+}
+/** The first (or last) enabled option, or -1 when every option is disabled. */
+export function edgeOption(options, edge) {
+    const start = edge === "first" ? -1 : options.length;
+    const found = stepOption(options, start, edge === "first" ? 1 : -1);
+    return found === start ? -1 : found;
+}
+/**
+ * Type-to-select: the next enabled option whose label starts with what was typed. Typing one
+ * letter repeatedly cycles through the options that start with it, as a native select does.
+ */
+export function typeaheadOption(options, typed, from) {
+    const query = typed.toLocaleLowerCase();
+    const prefix = /^(.)\1+$/su.test(query) ? query.slice(0, 1) : query;
+    const offset = prefix.length === 1 ? 1 : 0;
+    for (let step = 0; step < options.length; step += 1) {
+        const index = (from + offset + step + options.length) % options.length;
+        const option = options[index];
+        if (option && !option.disabled && option.label.toLocaleLowerCase().startsWith(prefix)) {
+            return index;
+        }
+    }
+    return -1;
+}
+/** Where each item's options start in the flattened list, so groups can render in place. */
+export function itemOffsets(items) {
+    const offsets = [];
+    let next = 0;
+    for (const item of items) {
+        offsets.push(next);
+        next += isOptionGroup(item) ? item.options.length : 1;
+    }
+    return offsets;
+}
+/** Appends a typed key, starting over after a pause, as native selects do. */
+export function extendTypeahead(buffer, key, at) {
+    return { text: at - buffer.at > 600 ? key : buffer.text + key, at };
+}

package/dist/theme.d.ts

@@ -0,0 +1,18 @@
+/** Every mdbase surface stores an explicit System, Light or Dark choice under this key. */
+export declare const THEME_STORAGE_KEY = "mdbase:theme";
+export declare const themePreferences: readonly ["system", "light", "dark"];
+export type ThemePreference = (typeof themePreferences)[number];
+/** Browser chrome colours matching the light and dark canvas tokens. */
+export declare const themeColors: {
+    readonly light: "#fcfcfd";
+    readonly dark: "#1b1d23";
+};
+export type ThemeStorage = Pick<Storage, "getItem" | "setItem">;
+export type ThemeRoot = Pick<HTMLElement, "dataset" | "removeAttribute">;
+export declare function normalizeThemePreference(value: unknown): ThemePreference;
+/** Storage may be absent (server rendering, extension pages) or blocked; both mean System. */
+export declare function loadThemePreference(storage?: ThemeStorage): ThemePreference;
+export declare function resolveDarkTheme(root?: Pick<HTMLElement, "dataset">): boolean;
+export declare function observeTheme(listener: () => void, root?: HTMLElement): () => void;
+export declare function applyThemePreference(preference: ThemePreference, root?: ThemeRoot): void;
+export declare function saveThemePreference(preference: ThemePreference, storage?: ThemeStorage, root?: ThemeRoot): void;