@getaster/elements 0.0.0-stage → 0.1.0-preview.1

package/dist/dashboard/widget.js

@@ -0,0 +1,165 @@
+import { signal } from "@preact/signals-core";
+import { html, nothing } from "lit-html";
+import { AsterElement, define, provideScope, uid } from "../base/element.js";
+import { windowBar } from "../window/chrome.js";
+import { openWhen } from "../overlay/anchor.js";
+import { Menu } from "../menu/menu.js";
+/** The dashboard owns sessions; native DOM moves only reconnect the view. */
+export class DashboardPortlet extends AsterElement {
+    #widget = this.prop(undefined);
+    #maximized = this.prop(false);
+    #busy = this.prop(false);
+    #status = this.prop("unavailable");
+    #config = signal({});
+    #id = uid("aster-widget");
+    #scope;
+    #actions;
+    #session;
+    #abort;
+    #generation = 0;
+    #started = false;
+    initialize(widget, scope, actions) {
+        this.#scope = scope;
+        this.#actions = actions;
+        provideScope(this, scope);
+        this.setAttribute("role", "listitem");
+        this.update(widget, false, false);
+    }
+    update(widget, maximized, busy) {
+        this.#widget.value = widget;
+        this.#maximized.value = maximized;
+        this.#busy.value = busy;
+        if (JSON.stringify(widget.config ?? {}) !== JSON.stringify(this.#config.peek()))
+            this.#config.value = widget.config ?? {};
+        this.dataset.widget = widget.id;
+        this.dataset.width = String(widget.width);
+        this.dataset.height = String(widget.height);
+    }
+    async mount(type) {
+        if (!type || this.#started)
+            return;
+        this.#started = true;
+        const generation = ++this.#generation;
+        const abort = new AbortController();
+        this.#abort = abort;
+        this.#status.value = "loading";
+        try {
+            const session = await type.create({ id: this.#widget.peek().id, config: this.#config, scope: this.#scope, signal: abort.signal });
+            if (generation !== this.#generation || abort.signal.aborted) {
+                session.dispose();
+                return;
+            }
+            this.#session = session;
+            this.#status.value = "ready";
+        }
+        catch (error) {
+            if (generation === this.#generation)
+                this.#fail(error);
+        }
+    }
+    async allowRemove() { return await this.#session?.beforeRemove?.() ?? true; }
+    dispose() {
+        this.#generation++;
+        this.#abort?.abort();
+        this.#abort = undefined;
+        const session = this.#session;
+        this.#session = undefined;
+        this.#started = false;
+        try {
+            session?.dispose();
+        }
+        catch (error) {
+            this.#report(error);
+        }
+        this.#status.value = "unavailable";
+    }
+    focusActions() { this.querySelector(".aster-widget-actions")?.focus(); }
+    render() {
+        const widget = this.#widget.value;
+        if (!widget)
+            return nothing;
+        const max = this.#maximized.value;
+        const busy = this.#busy.value;
+        return html `<section class="aster-portlet" data-maximized=${String(max)} role=${max ? "dialog" : "region"}
+      aria-modal=${max ? "false" : nothing} aria-labelledby=${this.#id} popover=${max ? "manual" : nothing}
+      ${openWhen(max)} @keydown=${(event) => {
+            if (max && event.key === "Escape" && !event.defaultPrevented) {
+                event.preventDefault();
+                event.stopPropagation();
+                this.#actions.maximize();
+            }
+        }}>
+      ${windowBar(this.#id, widget.title, html `
+        <button type="button" aria-label=${`Move ${widget.title}`} ?disabled=${busy || max}
+          aria-describedby=${`${this.#id}-move`} @pointerdown=${(event) => this.#actions.drag(event)}
+          @keydown=${(event) => this.#key(event, false)}>
+          <svg viewBox="0 0 16 16" aria-hidden="true"><path d="M8 2v12M2 8h12M8 2 6 4m2-2 2 2M2 8l2-2m-2 2 2 2M14 8l-2-2m2 2-2 2M8 14l-2-2m2 2 2-2"/></svg>
+        </button>
+        <span id=${`${this.#id}-move`} hidden>Drag onto another widget, or use arrow keys to move earlier or later. The actions menu offers the same controls.</span>
+        <button type="button" aria-label=${`Resize ${widget.title}`} ?disabled=${busy || max}
+          aria-describedby=${`${this.#id}-resize`} @keydown=${(event) => this.#key(event, true)}>
+          <svg viewBox="0 0 16 16" aria-hidden="true"><path d="M3 13 13 3M7 3h6v6M3 7v6h6"/></svg>
+        </button>
+        <span id=${`${this.#id}-resize`} hidden>Left and right change width; up and down change height. The actions menu offers the same controls.</span>
+        <button type="button" class="aster-widget-actions" aria-label=${`Actions for ${widget.title}`} aria-haspopup="menu" ?disabled=${busy}
+          @click=${(event) => this.#menu(event.currentTarget)}>
+          <svg viewBox="0 0 16 16" aria-hidden="true"><path d="M3 8h.1M8 8h.1M13 8h.1" stroke-width="3"/></svg>
+        </button>
+        <button type="button" class="aster-widget-maximize" aria-label=${`${max ? "Restore" : "Maximize"} ${widget.title}`} ?disabled=${busy}
+          @click=${() => this.#actions.maximize()}><svg viewBox="0 0 16 16" aria-hidden="true"><path d="M3 3h10v10H3zM3 6h10"/></svg></button>
+        <button type="button" aria-label=${`Remove ${widget.title}`} ?disabled=${busy} @click=${() => this.#actions.remove()}>
+          <svg viewBox="0 0 16 16" aria-hidden="true"><path d="m4 4 8 8m0-8-8 8"/></svg></button>`)}
+      <div class="aster-portlet-body" aria-busy=${String(this.#status.value === "loading")}>${this.#body()}</div>
+      <aster-menu></aster-menu>
+    </section>`;
+    }
+    #body() {
+        switch (this.#status.value) {
+            case "ready":
+                try {
+                    return this.#session.render();
+                }
+                catch (error) {
+                    const generation = this.#generation;
+                    queueMicrotask(() => { if (generation === this.#generation && this.#status.peek() !== "error")
+                        this.#fail(error); });
+                    return html `<p role="status">Widget content unavailable.</p>`;
+                }
+            case "loading": return html `<p role="status">Loading widget…</p>`;
+            case "error": return html `<p role="status">Widget content unavailable. <button type="button" class="aster-button" @click=${() => this.#actions.retry()}>Retry widget</button></p>`;
+            default: return html `<p role="status">This widget type is unavailable. Its saved configuration is retained.</p>`;
+        }
+    }
+    #fail(error) { this.#status.value = "error"; this.#report(error); }
+    #report(error) { this.emit("widgeterror", { id: this.#widget.peek().id, error }); }
+    #key(event, resize) {
+        if (this.#busy.peek() || this.#maximized.peek())
+            return;
+        const changes = { ArrowLeft: [-1, 0], ArrowRight: [1, 0], ArrowUp: [0, -1], ArrowDown: [0, 1] };
+        const by = changes[event.key];
+        if (!by)
+            return;
+        event.preventDefault();
+        if (resize)
+            this.#actions.resize(by[0], by[1]);
+        else
+            this.#actions.move(by[0] || by[1]);
+    }
+    #menu(anchor) {
+        const widget = this.#widget.peek();
+        const edges = this.#actions.edges();
+        const disabled = this.#maximized.peek() ? "Restore this widget before changing its layout." : undefined;
+        const action = (label, reason, run) => ({ label, ...(reason ? { disabled: reason } : {}), run });
+        const items = [
+            action("Move earlier", disabled ?? (edges.first ? "Already first." : undefined), () => this.#actions.move(-1)),
+            action("Move later", disabled ?? (edges.last ? "Already last." : undefined), () => this.#actions.move(1)),
+            { kind: "separator" },
+            action("Narrower", disabled ?? (widget.width === 1 ? "Already narrowest." : undefined), () => this.#actions.resize(-1, 0)),
+            action("Wider", disabled ?? (widget.width === 3 ? "Already widest." : undefined), () => this.#actions.resize(1, 0)),
+            action("Shorter", disabled ?? (widget.height === 1 ? "Already shortest." : undefined), () => this.#actions.resize(0, -1)),
+            action("Taller", disabled ?? (widget.height === 3 ? "Already tallest." : undefined), () => this.#actions.resize(0, 1)),
+        ];
+        this.querySelector("aster-menu").openFrom(anchor, items, `Layout for ${widget.title}`);
+    }
+}
+define("aster-dashboard-widget", DashboardPortlet);

package/dist/date/calendar.d.ts

@@ -0,0 +1,34 @@
+import { nothing, type TemplateResult } from "lit-html";
+/** Whether the calendar is open, and the day that has focus in it. */
+export declare class CalendarState {
+    readonly open: import("@preact/signals-core").Signal<boolean>;
+    readonly focused: import("@preact/signals-core").Signal<string>;
+    /** Set on opening: the focused day takes focus once rendered. */
+    focusPending: boolean;
+    show(value: string | undefined, today: string): void;
+}
+/** Closes the calendar on a press outside `root`, until it closes. */
+export declare function closeOutside(state: CalendarState, root: Element): void;
+export interface CalendarProps {
+    readonly id: string;
+    /** The anchor's `anchor-name`, without the dashes. */
+    readonly anchor: string;
+    readonly value: string | undefined;
+    readonly today: string;
+    readonly label: string;
+    readonly choose: (date: string) => void;
+    /** Closed without a choice: Escape, or a press outside. */
+    readonly dismiss: (refocus: boolean) => void;
+}
+/**
+ * The APG date-picker dialog: a month grid in a top-layer popover.
+ *
+ * Keyboard in the grid: arrows by day and week, Page Up/Down by month (with
+ * Shift, by year), Home/End to the week's start and end, Enter or Space
+ * choose. Tab cycles through the dialog's buttons and the grid; Escape
+ * closes. The focused day is the grid's one tab stop, and moving it to
+ * another month turns the page.
+ */
+export declare function calendarView(state: CalendarState, p: CalendarProps): TemplateResult | typeof nothing;
+/** Where a key moves the focused day, or undefined if it doesn't. */
+export declare function gridKey(e: Pick<KeyboardEvent, "key" | "shiftKey">, from: string): string | undefined;

package/dist/date/calendar.js

@@ -0,0 +1,137 @@
+import { signal } from "@preact/signals-core";
+import { html, nothing } from "lit-html";
+import { ref } from "lit-html/directives/ref.js";
+import { openWhen, placeStyle } from "../overlay/anchor.js";
+import { monthWeeks, shift, weekBounds } from "./dates.js";
+const MONTH = new Intl.DateTimeFormat("en-GB", { month: "long", year: "numeric", timeZone: "UTC" });
+const DAY = new Intl.DateTimeFormat("en-GB", { weekday: "long", day: "numeric", month: "long", year: "numeric", timeZone: "UTC" });
+const WEEKDAYS = [
+    ["Mo", "Monday"],
+    ["Tu", "Tuesday"],
+    ["We", "Wednesday"],
+    ["Th", "Thursday"],
+    ["Fr", "Friday"],
+    ["Sa", "Saturday"],
+    ["Su", "Sunday"],
+];
+/** Whether the calendar is open, and the day that has focus in it. */
+export class CalendarState {
+    open = signal(false);
+    focused = signal("");
+    /** Set on opening: the focused day takes focus once rendered. */
+    focusPending = false;
+    show(value, today) {
+        this.focused.value = value && /^\d{4}-\d{2}-\d{2}$/.test(value) ? value : today;
+        this.focusPending = true;
+        this.open.value = true;
+    }
+}
+/** Closes the calendar on a press outside `root`, until it closes. */
+export function closeOutside(state, root) {
+    const outside = (e) => {
+        if (!root.contains(e.target))
+            state.open.value = false;
+    };
+    document.addEventListener("pointerdown", outside, { capture: true });
+    const stop = state.open.subscribe((open) => {
+        if (open)
+            return;
+        document.removeEventListener("pointerdown", outside, { capture: true });
+        queueMicrotask(() => stop());
+    });
+}
+/**
+ * The APG date-picker dialog: a month grid in a top-layer popover.
+ *
+ * Keyboard in the grid: arrows by day and week, Page Up/Down by month (with
+ * Shift, by year), Home/End to the week's start and end, Enter or Space
+ * choose. Tab cycles through the dialog's buttons and the grid; Escape
+ * closes. The focused day is the grid's one tab stop, and moving it to
+ * another month turns the page.
+ */
+export function calendarView(state, p) {
+    if (!state.open.value)
+        return nothing;
+    const focused = state.focused.value;
+    const headingId = `${p.id}-month`;
+    const move = (to) => {
+        state.focused.value = to;
+        queueMicrotask(() => document.getElementById(`${p.id}-${to}`)?.focus());
+    };
+    const page = (by) => (state.focused.value = shift(focused, by));
+    const grid = (e) => {
+        const to = gridKey(e, focused);
+        if (to) {
+            e.preventDefault();
+            move(to);
+        }
+        else if (e.key === "Enter" || e.key === " ") {
+            e.preventDefault();
+            p.choose(focused);
+        }
+    };
+    const dialog = (e) => {
+        e.stopPropagation();
+        if (e.key === "Escape") {
+            e.preventDefault();
+            p.dismiss(true);
+        }
+        else if (e.key === "Tab") {
+            const stops = [...e.currentTarget.querySelectorAll("button, [tabindex='0']")];
+            const at = stops.indexOf(document.activeElement);
+            e.preventDefault();
+            stops[(at + (e.shiftKey ? -1 : 1) + stops.length) % stops.length]?.focus();
+        }
+    };
+    const month = focused.slice(0, 7);
+    return html `<div class="aster-calendar aster-popover" popover="manual" role="dialog" aria-modal="true" aria-label=${p.label}
+    id=${p.id} style=${placeStyle(p.anchor)} ${openWhen(true)} @keydown=${dialog}
+    ${ref(() => {
+        if (!state.focusPending)
+            return;
+        state.focusPending = false;
+        requestAnimationFrame(() => document.getElementById(`${p.id}-${state.focused.peek()}`)?.focus());
+    })}>
+    <div class="aster-calendar-head">
+      <button type="button" aria-label="Previous year" @click=${() => page({ years: -1 })}>«</button>
+      <button type="button" aria-label="Previous month" @click=${() => page({ months: -1 })}>‹</button>
+      <h2 id=${headingId} aria-live="polite">${MONTH.format(Date.parse(`${month}-15T12:00:00Z`))}</h2>
+      <button type="button" aria-label="Next month" @click=${() => page({ months: 1 })}>›</button>
+      <button type="button" aria-label="Next year" @click=${() => page({ years: 1 })}>»</button>
+    </div>
+    <table role="grid" aria-labelledby=${headingId} @keydown=${grid}>
+      <thead><tr>${WEEKDAYS.map(([short, long]) => html `<th scope="col" abbr=${long}>${short}</th>`)}</tr></thead>
+      <tbody>
+        ${monthWeeks(focused).map((week) => html `<tr>${week.map((day) => day.slice(0, 7) !== month
+        ? html `<td></td>`
+        : html `<td role="gridcell" id=${`${p.id}-${day}`} tabindex=${day === focused ? "0" : "-1"}
+                  aria-selected=${day === p.value ? "true" : nothing} aria-current=${day === p.today ? "date" : nothing}
+                  aria-label=${DAY.format(Date.parse(`${day}T12:00:00Z`))}
+                  @click=${() => p.choose(day)}>${Number(day.slice(8))}</td>`)}</tr>`)}
+      </tbody>
+    </table>
+  </div>`;
+}
+/** Where a key moves the focused day, or undefined if it doesn't. */
+export function gridKey(e, from) {
+    switch (e.key) {
+        case "ArrowLeft":
+            return shift(from, { days: -1 });
+        case "ArrowRight":
+            return shift(from, { days: 1 });
+        case "ArrowUp":
+            return shift(from, { days: -7 });
+        case "ArrowDown":
+            return shift(from, { days: 7 });
+        case "PageUp":
+            return shift(from, e.shiftKey ? { years: -1 } : { months: -1 });
+        case "PageDown":
+            return shift(from, e.shiftKey ? { years: 1 } : { months: 1 });
+        case "Home":
+            return weekBounds(from)[0];
+        case "End":
+            return weekBounds(from)[1];
+        default:
+            return undefined;
+    }
+}

package/dist/date/date-field.d.ts

@@ -0,0 +1,18 @@
+import { type View } from "../base/element.ts";
+import { BoundField, type ControlContext } from "../field/bound-field.ts";
+/**
+ * A date field: typed dates in the forms people write them ("7 Oct",
+ * "7/10/2026", "2026-10-07"), shown as "7 Oct 2026", with a calendar
+ * button that opens the APG date-picker dialog. What's typed is kept as
+ * typed while the input has focus; text that isn't a date stays text, and
+ * validation says so.
+ *
+ * The calendar button takes focus on press in every engine (macOS engines
+ * don't focus buttons on click), so focus never falls to the body between
+ * the input and the calendar: a grid row being edited would end its edit.
+ */
+export declare class DateField extends BoundField {
+    #private;
+    focus(options?: FocusOptions): void;
+    protected control(c: ControlContext): View;
+}

package/dist/date/date-field.js

@@ -0,0 +1,81 @@
+import { html, nothing } from "lit-html";
+import { live } from "lit-html/directives/live.js";
+import { define } from "../base/element.js";
+import { BoundField } from "../field/bound-field.js";
+import { anchorStyle } from "../overlay/anchor.js";
+import { CalendarState, calendarView, closeOutside } from "./calendar.js";
+import { formatDate, parseDate, today } from "./dates.js";
+/**
+ * A date field: typed dates in the forms people write them ("7 Oct",
+ * "7/10/2026", "2026-10-07"), shown as "7 Oct 2026", with a calendar
+ * button that opens the APG date-picker dialog. What's typed is kept as
+ * typed while the input has focus; text that isn't a date stays text, and
+ * validation says so.
+ *
+ * The calendar button takes focus on press in every engine (macOS engines
+ * don't focus buttons on click), so focus never falls to the body between
+ * the input and the calendar: a grid row being edited would end its edit.
+ */
+export class DateField extends BoundField {
+    #calendar = new CalendarState();
+    /** What's being typed, while the input has focus. */
+    #draft = this.prop(undefined);
+    focus(options) {
+        this.querySelector("input")?.focus(options);
+    }
+    control(c) {
+        const value = typeof c.value === "string" ? c.value : undefined;
+        const readOnly = c.state.readOnly;
+        const open = this.#calendar.open.value;
+        const text = this.#draft.value ?? (value === undefined ? "" : formatDate(value));
+        const button = `${c.id}-calendar`;
+        const close = (refocus) => {
+            this.#calendar.open.value = false;
+            if (refocus)
+                this.querySelector(`#${CSS.escape(button)}`)?.focus();
+        };
+        return html `<div class="aster-field aster-date" data-ring-owner style=${anchorStyle(c.id)}>
+        <input id=${c.id} .value=${live(text)}
+          aria-label=${this.labelled ? nothing : c.label}
+          placeholder=${c.meta?.nullable ? "None" : "A date, like 7 Oct"}
+          ?readonly=${readOnly}
+          aria-required=${c.state.required ? "true" : nothing}
+          aria-invalid=${c.invalid ? "true" : nothing}
+          aria-describedby=${c.describedBy ?? nothing}
+          autocomplete="off" spellcheck="false"
+          @input=${(e) => {
+            const t = e.target.value;
+            this.#draft.value = t;
+            this.write(t.trim() === "" ? null : parseDate(t, Number(today().slice(0, 4))) ?? t);
+        }}
+          @blur=${() => (this.#draft.value = undefined)}>
+        ${readOnly
+            ? nothing
+            : html `<button type="button" class="aster-date-button" id=${button} aria-label=${`Choose ${c.label}`}
+              aria-haspopup="dialog" aria-expanded=${open ? "true" : "false"} aria-controls=${`${c.id}-dialog`}
+              @pointerdown=${(e) => e.currentTarget.focus()}
+              @mousedown=${(e) => e.preventDefault()}
+              @click=${() => (open ? close(false) : this.#open(value))}>
+              <svg viewBox="0 0 16 16" aria-hidden="true"><rect x="2.5" y="3.5" width="11" height="10" rx="1.5"/><path d="M2.5 6.5h11M5.5 2v3M10.5 2v3"/></svg>
+            </button>`}
+      </div>
+      ${calendarView(this.#calendar, {
+            id: `${c.id}-dialog`,
+            anchor: c.id,
+            value,
+            today: today(),
+            label: `Choose ${c.label}`,
+            choose: (date) => {
+                this.write(date);
+                close(false);
+                this.querySelector("input")?.focus();
+            },
+            dismiss: close,
+        })}`;
+    }
+    #open(value) {
+        this.#calendar.show(value, today());
+        closeOutside(this.#calendar, this);
+    }
+}
+define("aster-date", DateField);

package/dist/date/dates.d.ts

@@ -0,0 +1,22 @@
+export declare function iso(year: number, month: number, day: number): string | undefined;
+/** "7 Oct 2026" for `2026-10-07`; other text unchanged. Month names are ours, the same in every engine. */
+export declare function formatDate(value: string): string;
+/**
+ * A typed date: `2026-10-07`, `7/10/2026` (day first), `7 Oct 2026`,
+ * `Oct 7 2026`, or `7 Oct` (this year). `undefined` when it isn't one.
+ */
+export declare function parseDate(text: string, thisYear: number): string | undefined;
+/** Adds days, months (clamped to the month's end) or years. */
+export declare function shift(value: string, by: {
+    days?: number;
+    months?: number;
+    years?: number;
+}): string;
+/** Monday of `value`'s week, and Sunday. */
+export declare function weekBounds(value: string): [string, string];
+/** The weeks of `value`'s month, Monday to Sunday, padded with the days of the months either side (the calendar leaves those blank). */
+export declare function monthWeeks(value: string): string[][];
+/** Sets where "today" comes from: an app with its own clock (frozen in tests) passes it here. */
+export declare function setClock(clock: () => number): void;
+/** Today as `YYYY-MM-DD`, in UTC like the dates themselves. */
+export declare function today(): string;

package/dist/date/dates.js

@@ -0,0 +1,80 @@
+// Calendar dates as `YYYY-MM-DD`, with no time zone: what Edm.Date holds.
+const MONTHS = ["jan", "feb", "mar", "apr", "may", "jun", "jul", "aug", "sep", "oct", "nov", "dec"];
+const SHORT = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+export function iso(year, month, day) {
+    const d = new Date(Date.UTC(year, month - 1, day));
+    if (d.getUTCFullYear() !== year || d.getUTCMonth() !== month - 1 || d.getUTCDate() !== day)
+        return undefined;
+    return d.toISOString().slice(0, 10);
+}
+/** "7 Oct 2026" for `2026-10-07`; other text unchanged. Month names are ours, the same in every engine. */
+export function formatDate(value) {
+    const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(value);
+    return m ? `${Number(m[3])} ${SHORT[Number(m[2]) - 1]} ${m[1]}` : value;
+}
+/**
+ * A typed date: `2026-10-07`, `7/10/2026` (day first), `7 Oct 2026`,
+ * `Oct 7 2026`, or `7 Oct` (this year). `undefined` when it isn't one.
+ */
+export function parseDate(text, thisYear) {
+    const t = text.trim().toLowerCase().replace(/,/g, " ").replace(/\s+/g, " ");
+    let m = /^(\d{4})-(\d{1,2})-(\d{1,2})$/.exec(t);
+    if (m)
+        return iso(Number(m[1]), Number(m[2]), Number(m[3]));
+    m = /^(\d{1,2})[/.-](\d{1,2})[/.-](\d{2}|\d{4})$/.exec(t);
+    if (m)
+        return iso(year(m[3]), Number(m[2]), Number(m[1]));
+    m = /^(\d{1,2}) ([a-z]+)\.?(?: (\d{2}|\d{4}))?$/.exec(t);
+    if (m)
+        return byName(m[2], Number(m[1]), m[3] ? year(m[3]) : thisYear);
+    m = /^([a-z]+)\.? (\d{1,2})(?: (\d{2}|\d{4}))?$/.exec(t);
+    if (m)
+        return byName(m[1], Number(m[2]), m[3] ? year(m[3]) : thisYear);
+    return undefined;
+}
+function year(text) {
+    return text.length === 2 ? 2000 + Number(text) : Number(text);
+}
+function byName(name, day, y) {
+    const month = MONTHS.indexOf(name.slice(0, 3));
+    return month < 0 ? undefined : iso(y, month + 1, day);
+}
+/** Adds days, months (clamped to the month's end) or years. */
+export function shift(value, by) {
+    const [y, m, d] = value.split("-").map(Number);
+    if (by.days)
+        return new Date(Date.UTC(y, m - 1, d + by.days)).toISOString().slice(0, 10);
+    const months = (by.months ?? 0) + (by.years ?? 0) * 12;
+    const first = new Date(Date.UTC(y, m - 1 + months, 1));
+    const last = new Date(Date.UTC(first.getUTCFullYear(), first.getUTCMonth() + 1, 0)).getUTCDate();
+    return iso(first.getUTCFullYear(), first.getUTCMonth() + 1, Math.min(d, last));
+}
+/** Monday of `value`'s week, and Sunday. */
+export function weekBounds(value) {
+    const day = (new Date(`${value}T12:00:00Z`).getUTCDay() + 6) % 7;
+    return [shift(value, { days: -day }), shift(value, { days: 6 - day })];
+}
+/** The weeks of `value`'s month, Monday to Sunday, padded with the days of the months either side (the calendar leaves those blank). */
+export function monthWeeks(value) {
+    const first = `${value.slice(0, 7)}-01`;
+    let day = weekBounds(first)[0];
+    const weeks = [];
+    do {
+        const week = [];
+        for (let i = 0; i < 7; i++) {
+            week.push(day);
+            day = shift(day, { days: 1 });
+        }
+        weeks.push(week);
+    } while (day.slice(0, 7) === value.slice(0, 7));
+    return weeks;
+}
+let now = () => Date.now();
+/** Sets where "today" comes from: an app with its own clock (frozen in tests) passes it here. */
+export function setClock(clock) {
+    now = clock;
+}
+/** Today as `YYYY-MM-DD`, in UTC like the dates themselves. */
+export function today() {
+    return new Date(now()).toISOString().slice(0, 10);
+}

package/dist/dialog/dialog.d.ts

@@ -0,0 +1,23 @@
+import { AsterElement, type View } from "../base/element.ts";
+/**
+ * A modal dialog over a native `<dialog>`: the rest of the page is inert,
+ * focus goes in on open and returns to the opener on close, and Escape or
+ * a click on the backdrop closes it. One dialog morphs between views
+ * (`showView`) rather than stacking modals.
+ */
+export declare class Dialog extends AsterElement {
+    #private;
+    /** The dialog's contents; usually a template reading the current view. */
+    get content(): View;
+    set content(v: View);
+    /** The id of the element that names the dialog. */
+    get labelledBy(): string | undefined;
+    set labelledBy(v: string | undefined);
+    get open(): boolean;
+    /** Opens modally. `focus` is the element to focus inside; otherwise the first focusable. */
+    show(opener?: HTMLElement | null, focus?: () => HTMLElement | null): void;
+    close(): void;
+    /** Changes view in place: the panel morphs, then the new content inks in. */
+    showView(change: () => void): void;
+    protected render(): View;
+}

package/dist/dialog/dialog.js

@@ -0,0 +1,70 @@
+import { html, nothing } from "lit-html";
+import { AsterElement, define } from "../base/element.js";
+import { morph } from "../motion.js";
+/**
+ * A modal dialog over a native `<dialog>`: the rest of the page is inert,
+ * focus goes in on open and returns to the opener on close, and Escape or
+ * a click on the backdrop closes it. One dialog morphs between views
+ * (`showView`) rather than stacking modals.
+ */
+export class Dialog extends AsterElement {
+    #content = this.prop(nothing);
+    #label = this.prop(undefined);
+    #opener = null;
+    /** The dialog's contents; usually a template reading the current view. */
+    get content() {
+        return this.#content.value;
+    }
+    set content(v) {
+        this.#content.value = v;
+    }
+    /** The id of the element that names the dialog. */
+    get labelledBy() {
+        return this.#label.value;
+    }
+    set labelledBy(v) {
+        this.#label.value = v;
+    }
+    get open() {
+        return this.#dialog()?.open ?? false;
+    }
+    /** Opens modally. `focus` is the element to focus inside; otherwise the first focusable. */
+    show(opener = document.activeElement, focus) {
+        const dialog = this.#dialog();
+        if (!dialog || dialog.open)
+            return;
+        this.#opener = opener;
+        dialog.showModal();
+        const target = focus?.();
+        if (target)
+            target.focus();
+    }
+    close() {
+        const dialog = this.#dialog();
+        if (!dialog?.open)
+            return;
+        dialog.close();
+    }
+    /** Changes view in place: the panel morphs, then the new content inks in. */
+    showView(change) {
+        morph(change);
+    }
+    render() {
+        return html `<dialog class="aster-dialog" aria-labelledby=${this.#label.value ?? nothing}
+      @close=${() => this.#closed()}
+      @click=${(e) => e.target === e.currentTarget && this.close()}>
+      <div class="aster-dialog-panel">${this.#content.value}</div>
+    </dialog>`;
+    }
+    #closed() {
+        const opener = this.#opener;
+        this.#opener = null;
+        if (opener?.isConnected)
+            opener.focus();
+        this.emit("close");
+    }
+    #dialog() {
+        return this.querySelector("dialog");
+    }
+}
+define("aster-dialog", Dialog);