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

package/dist/list-edit/list-edit.d.ts

@@ -0,0 +1,42 @@
+import type { Collection, ListEdit, ListRow } from "@getaster/data";
+import type { PickerOptions } from "../picker/options.ts";
+import { AsterElement, type View } from "../base/element.ts";
+export interface ListColumn {
+    readonly field: string;
+    /** A CSS track size; `1fr` by default. */
+    readonly width?: string;
+    /** Makes a foreign key a picker over these records. */
+    readonly options?: Collection | PickerOptions;
+    /** Shows an option's text instead of the key, for read-only rows. */
+    readonly display?: (row: ListRow) => string;
+}
+/**
+ * The rows of a list edit as a grid of fields. A new row shows as pending
+ * in full. Removing an existing row marks it for deletion: it shows struck
+ * through and read-only, with Undo, until the list is saved. Removing a new
+ * row discards it. A changed row offers Revert. While `readOnly`, rows show
+ * as text, with `readOnlyReason` above them, and nothing can be added.
+ *
+ * A list with a position field can be reordered: by dragging a row's handle
+ * (a touch or pen holds it still first), or with Alt+↑ and Alt+↓ on it, the
+ * new place announced.
+ */
+export declare class ListEditor extends AsterElement {
+    #private;
+    get list(): ListEdit | undefined;
+    set list(v: ListEdit | undefined);
+    get columns(): readonly ListColumn[];
+    set columns(v: readonly ListColumn[]);
+    get label(): string;
+    set label(v: string);
+    get addLabel(): string;
+    set addLabel(v: string);
+    /** Why the rows can't be edited now; set, even to an empty string, it makes the list read-only. */
+    get readOnlyReason(): string | undefined;
+    set readOnlyReason(v: string | undefined);
+    /** Shown when there are no rows. */
+    get empty(): View;
+    set empty(v: View);
+    protected render(): View;
+    protected updated(): void;
+}

package/dist/list-edit/list-edit.js

@@ -0,0 +1,220 @@
+import { html, nothing } from "lit-html";
+import { styleMap } from "lit-html/directives/style-map.js";
+import { AsterElement, define, each } from "../base/element.js";
+import { holds, pressDrag } from "../base/drag.js";
+import { controlFor } from "../form/controls.js";
+import { formatValue } from "../field/values.js";
+/**
+ * The rows of a list edit as a grid of fields. A new row shows as pending
+ * in full. Removing an existing row marks it for deletion: it shows struck
+ * through and read-only, with Undo, until the list is saved. Removing a new
+ * row discards it. A changed row offers Revert. While `readOnly`, rows show
+ * as text, with `readOnlyReason` above them, and nothing can be added.
+ *
+ * A list with a position field can be reordered: by dragging a row's handle
+ * (a touch or pen holds it still first), or with Alt+↑ and Alt+↓ on it, the
+ * new place announced.
+ */
+export class ListEditor extends AsterElement {
+    #list = this.prop(undefined);
+    #columns = this.prop([]);
+    #label = this.prop("");
+    #addLabel = this.prop("Add");
+    #empty = this.prop(nothing);
+    #readOnly = this.prop(undefined);
+    /** A row just added or moved, focused once it has rendered (a moved row on its handle). */
+    #focus;
+    #focusHandle = false;
+    #said = this.prop("");
+    /** A row being dragged: where its drop line is, whether a touch lifted it, and whether that touch is outside the list. */
+    #drag = this.prop(undefined);
+    get list() {
+        return this.#list.value;
+    }
+    set list(v) {
+        this.#list.value = v;
+    }
+    get columns() {
+        return this.#columns.value;
+    }
+    set columns(v) {
+        this.#columns.value = v;
+    }
+    get label() {
+        return this.#label.value;
+    }
+    set label(v) {
+        this.#label.value = v;
+    }
+    get addLabel() {
+        return this.#addLabel.value;
+    }
+    set addLabel(v) {
+        this.#addLabel.value = v;
+    }
+    /** Why the rows can't be edited now; set, even to an empty string, it makes the list read-only. */
+    get readOnlyReason() {
+        return this.#readOnly.value;
+    }
+    set readOnlyReason(v) {
+        this.#readOnly.value = v;
+    }
+    /** Shown when there are no rows. */
+    get empty() {
+        return this.#empty.value;
+    }
+    set empty(v) {
+        this.#empty.value = v;
+    }
+    render() {
+        const list = this.#list.value;
+        if (!list)
+            return nothing;
+        const columns = this.#columns.value;
+        const type = list.type;
+        const rows = list.rows.value;
+        const reason = this.#readOnly.value;
+        const readOnly = reason !== undefined;
+        const ordered = list.ordered && !readOnly;
+        const tracks = styleMap({ "--list-columns": `${ordered ? "24px " : ""}${columns.map((c) => c.width ?? "1fr").join(" ")} auto` });
+        const drag = this.#drag.value;
+        return html `${reason ? html `<p class="aster-hint">${reason}</p>` : nothing}
+      <div class="aster-list-edit" role="table" aria-label=${this.#label.value} style=${tracks}>
+        <div class="aster-list-edit-row aster-list-edit-head" role="row">
+          ${ordered ? html `<span role="columnheader"><span class="aster-sr-only">Order</span></span>` : nothing}
+          ${columns.map((c) => html `<span role="columnheader">${type.field(c.field)?.title ?? c.field}</span>`)}
+          <span role="columnheader"><span class="aster-sr-only">Actions</span></span>
+        </div>
+        ${each(rows, (r) => r.id, (r) => this.#row(r, columns, readOnly, ordered))}
+        ${drag && !drag.outside ? html `<div class="aster-list-edit-drop" aria-hidden="true" style=${`--at:${drag.to}`}></div>` : nothing}
+      </div>
+      <span class="aster-sr-only" aria-live="polite">${this.#said.value}</span>
+      ${rows.length === 0 ? html `<p class="aster-list-edit-empty">${this.#empty.value}</p>` : nothing}
+      ${readOnly
+            ? nothing
+            : html `<button type="button" class="aster-list-edit-add" @click=${() => this.#add(list)}>
+            <svg viewBox="0 0 14 14" aria-hidden="true"><path d="M7 2.5v9M2.5 7h9"/></svg>${this.#addLabel.value}
+          </button>`}`;
+    }
+    #row(row, columns, readOnly, ordered) {
+        const list = this.#list.peek();
+        const { edit } = row;
+        const first = String(edit.values.value[columns[0]?.field ?? ""] ?? "") || "new row";
+        // Struck through or marked new is drawn; the first cell also says it.
+        const said = row.removing ? "To be removed: " : row.isNew ? "New: " : "";
+        const lead = (i) => (i === 0 && said ? html `<span class="aster-sr-only">${said}</span>` : nothing);
+        const cells = row.removing || readOnly
+            ? columns.map((c, i) => html `<span role="cell" class="aster-list-edit-static" ?data-pending=${!row.removing && edit.pending(c.field).value}>${lead(i)}${c.display?.(row) ?? formatValue(edit.type.field(c.field), edit.values.value[c.field])}</span>`)
+            : columns.map((c, i) => {
+                // A field this row can't change (a key once set) reads as text, its reason on hover, not repeated on every row.
+                const state = edit.state(c.field).value;
+                return state.readOnly && !row.isNew
+                    ? html `<span role="cell" class="aster-list-edit-static" title=${state.reasons.readOnly ?? ""}>${lead(i)}${c.display?.(row) ?? formatValue(edit.type.field(c.field), edit.values.value[c.field])}</span>`
+                    : html `<span role="cell">${lead(i)}${controlFor(edit, c.field, { options: c.options, labelled: false })}</span>`;
+            });
+        const action = readOnly
+            ? nothing
+            : row.removing
+                ? html `<button type="button" class="aster-list-edit-action" @click=${() => list.restore(row.id)}
+          aria-label=${`Undo removing ${first}`}>Undo</button>`
+                : html `${edit.dirty.value && !row.isNew
+                    ? html `<button type="button" class="aster-list-edit-action" @click=${() => edit.revert()}
+                aria-label=${`Revert ${first}`}>Revert</button>`
+                    : nothing}
+          <button type="button" class="aster-list-edit-action" @click=${() => list.remove(row.id)}
+            aria-label=${`Remove ${first}`}>Remove</button>`;
+        const handle = !ordered
+            ? nothing
+            : row.removing
+                ? html `<span role="cell"></span>`
+                : html `<span role="cell"><button type="button" class="aster-list-edit-handle" aria-label=${`Move ${first}`}
+          aria-keyshortcuts="Alt+ArrowUp Alt+ArrowDown" title="Drag, or Alt+↑ and Alt+↓"
+          @keydown=${(e) => this.#moveKey(e, row, first)}
+          @pointerdown=${(e) => this.#dragStart(e, row, first)}>
+          <svg viewBox="0 0 14 14" aria-hidden="true"><path d="M5 3.5h.01M9 3.5h.01M5 7h.01M9 7h.01M5 10.5h.01M9 10.5h.01"/></svg>
+        </button></span>`;
+        return html `<div class="aster-list-edit-row" role="row" data-id=${row.id} ?data-new=${row.isNew} ?data-removing=${row.removing}
+        ?data-pending=${row.isNew || edit.dirty.value} ?data-dragging=${this.#drag.value?.id === row.id}
+        ?data-lifted=${this.#drag.value?.id === row.id && this.#drag.value.lifted}>
+      ${handle}${cells}
+      <span role="cell" class="aster-list-edit-actions">${action}</span>
+      ${row.removeError ? html `<p class="aster-error aster-list-edit-error" role="alert">${row.removeError}</p>` : nothing}
+    </div>`;
+    }
+    /** Where `row` is among the rows not being removed, and how many there are. */
+    #place(row) {
+        const live = this.#list.peek().rows.peek().filter((r) => !r.removing);
+        return [live.findIndex((r) => r.id === row.id), live.length];
+    }
+    #moveTo(row, index, name) {
+        const [from, count] = this.#place(row);
+        const to = Math.max(0, Math.min(count - 1, index));
+        if (to === from)
+            return;
+        this.#list.peek().move(row.id, to);
+        this.#said.value = `${name}, moved to ${to + 1} of ${count}`;
+        this.#focus = row.id;
+        this.#focusHandle = true;
+    }
+    #moveKey(e, row, name) {
+        if (!e.altKey || (e.key !== "ArrowUp" && e.key !== "ArrowDown"))
+            return;
+        e.preventDefault();
+        this.#moveTo(row, this.#place(row)[0] + (e.key === "ArrowUp" ? -1 : 1), name);
+    }
+    /**
+     * Dragging by the handle: a mouse lifts the row past a few pixels, a touch
+     * or pen by holding still (`pressDrag`), the row then drawn lifted. The
+     * drop line follows the pointer between rows; letting go moves the row
+     * there. Escape or an interrupted pointer doesn't, and nor does a touch
+     * let go outside the list.
+     */
+    #dragStart(e, row, name) {
+        if (e.button !== 0)
+            return;
+        const handle = e.currentTarget;
+        const touch = holds(e);
+        const table = this.querySelector(".aster-list-edit");
+        const rows = () => [...this.querySelectorAll(".aster-list-edit-row[data-id]:not([data-removing])")];
+        const others = () => rows().filter((el) => el.dataset.id !== row.id);
+        const indexAt = (y) => others().filter((el) => {
+            const r = el.getBoundingClientRect();
+            return r.top + r.height / 2 < y;
+        }).length;
+        const [from, count] = this.#place(row);
+        let target;
+        let outside = false;
+        pressDrag(e, { distance: 4, vertical: true, capture: handle, escape: true }, {
+            lift: () => (this.#said.value = `Picked up ${name}, ${from + 1} of ${count}`),
+            move: (x, y) => {
+                target = indexAt(y);
+                const el = others()[target - 1];
+                const box = table.getBoundingClientRect();
+                const line = el ? el.getBoundingClientRect().bottom - box.top : (rows()[0]?.offsetTop ?? 0);
+                outside = touch && (x < box.left || x > box.right || y < box.top - 24 || y > box.bottom + 24);
+                this.#drag.value = { id: row.id, to: Math.round(line), lifted: touch, outside };
+            },
+            end: (drop) => {
+                this.#drag.value = undefined;
+                if (drop && !outside && target !== undefined && target !== from)
+                    this.#moveTo(row, target, name);
+                else
+                    this.#said.value = `${name} not moved`;
+            },
+        });
+    }
+    updated() {
+        if (this.#focus === undefined)
+            return;
+        const target = this.querySelector(`[data-id="${CSS.escape(this.#focus)}"] ${this.#focusHandle ? ".aster-list-edit-handle" : ":is(input, select)"}`);
+        if (!target)
+            return;
+        this.#focus = undefined;
+        this.#focusHandle = false;
+        target.focus();
+    }
+    #add(list) {
+        this.#focus = list.add().id;
+    }
+}
+define("aster-list-editor", ListEditor);

package/dist/listbox/listbox.d.ts

@@ -0,0 +1,45 @@
+import { type Collection, type Entity, type KeyText, type Selection } from "@getaster/data";
+import { AsterElement, type View } from "../base/element.ts";
+import "../caret/caret-group.ts";
+export type RowRenderer = (entity: Entity, key: KeyText) => View;
+export interface RowMenuDetail {
+    readonly key: KeyText;
+    /** Where to open a menu: the pointer, or the row's start for the keyboard. */
+    readonly x: number;
+    readonly y: number;
+    readonly opener: HTMLElement;
+}
+/**
+ * A single-select listbox over a selection's collection. The selection is
+ * data the owner provides, so other views can follow it; with `publish`, the
+ * listbox also publishes it to its page scope under that key. Focus stays on
+ * the listbox and the active row is its `aria-activedescendant`.
+ *
+ * Fires `row-menu` (context menu, Shift+F10 or the Menu key) and `row-open`
+ * (Enter, double-click). Keys typed into an editor inside a row are left alone.
+ */
+export declare class Listbox extends AsterElement {
+    #private;
+    get collection(): Collection | undefined;
+    set collection(v: Collection | undefined);
+    get selection(): Selection | undefined;
+    set selection(v: Selection | undefined);
+    /** The page-scope key to publish the selection under. */
+    get publish(): string;
+    set publish(v: string);
+    connectedCallback(): void;
+    get renderRow(): RowRenderer;
+    set renderRow(v: RowRenderer);
+    /** Shown when the collection is loaded and has no rows. */
+    get empty(): View;
+    set empty(v: View);
+    get label(): string;
+    set label(v: string);
+    /** The row element for a key, if it's rendered. */
+    rowFor(key: KeyText): HTMLElement | undefined;
+    /** Draws the eye to a row once, after it appears or is revealed. */
+    flash(key: KeyText): void;
+    focus(options?: FocusOptions): void;
+    protected render(): View;
+    select(key: KeyText): void;
+}

package/dist/listbox/listbox.js

@@ -0,0 +1,187 @@
+import { effect } from "@preact/signals-core";
+import { selectionPublication } from "@getaster/data";
+import { html, nothing } from "lit-html";
+import { AsterElement, define, each, scopeOf, uid } from "../base/element.js";
+import "../caret/caret-group.js";
+/**
+ * A single-select listbox over a selection's collection. The selection is
+ * data the owner provides, so other views can follow it; with `publish`, the
+ * listbox also publishes it to its page scope under that key. Focus stays on
+ * the listbox and the active row is its `aria-activedescendant`.
+ *
+ * Fires `row-menu` (context menu, Shift+F10 or the Menu key) and `row-open`
+ * (Enter, double-click). Keys typed into an editor inside a row are left alone.
+ */
+export class Listbox extends AsterElement {
+    #collection = this.prop(undefined);
+    #selection = this.prop(undefined);
+    #publish = this.prop("");
+    #row = this.prop(() => nothing);
+    #empty = this.prop(nothing);
+    #label = this.prop("");
+    #prefix = uid("aster-row") + "-";
+    get collection() {
+        return this.#collection.value;
+    }
+    set collection(v) {
+        this.#collection.value = v;
+    }
+    get selection() {
+        return this.#selection.value;
+    }
+    set selection(v) {
+        this.#selection.value = v;
+    }
+    /** The page-scope key to publish the selection under. */
+    get publish() {
+        return this.#publish.value;
+    }
+    set publish(v) {
+        this.#publish.value = v;
+    }
+    connectedCallback() {
+        super.connectedCallback();
+        this.onDisconnect(effect(() => {
+            const key = this.#publish.value;
+            const selection = this.#selection.value;
+            const scope = scopeOf(this);
+            if (key && selection && scope)
+                return scope.publish(key, selectionPublication(selection));
+            return undefined;
+        }));
+    }
+    get renderRow() {
+        return this.#row.value;
+    }
+    set renderRow(v) {
+        this.#row.value = v;
+    }
+    /** Shown when the collection is loaded and has no rows. */
+    get empty() {
+        return this.#empty.value;
+    }
+    set empty(v) {
+        this.#empty.value = v;
+    }
+    get label() {
+        return this.#label.value;
+    }
+    set label(v) {
+        this.#label.value = v;
+    }
+    /** The row element for a key, if it's rendered. */
+    rowFor(key) {
+        return this.querySelector(`#${CSS.escape(this.#id(key))}`) ?? undefined;
+    }
+    /** Draws the eye to a row once, after it appears or is revealed. */
+    flash(key) {
+        requestAnimationFrame(() => {
+            const row = this.rowFor(key);
+            if (!row)
+                return;
+            row.classList.remove("aster-flash");
+            void row.offsetWidth;
+            row.classList.add("aster-flash");
+        });
+    }
+    focus(options) {
+        this.querySelector('[role="listbox"]')?.focus(options);
+    }
+    render() {
+        const collection = this.#collection.value ?? this.#selection.value?.collection;
+        if (!collection)
+            return nothing;
+        const all = collection.keys.value;
+        const items = collection.items.value;
+        const selected = this.#selection.value?.key.value;
+        const row = this.#row.value;
+        const rows = all.flatMap((k, i) => (k === undefined ? [] : [{ key: k, entity: items[i] }]));
+        const keys = rows.map((r) => r.key);
+        const empty = collection.count.value === 0;
+        const active = selected !== undefined && keys.includes(selected) ? this.#id(selected) : undefined;
+        return html `<aster-caret-group class="aster-listbox" role="listbox" aria-label=${this.#label.value} aria-busy=${collection.status.value === "loading" ? "true" : "false"}
+      tabindex=${empty ? -1 : 0} aria-activedescendant=${active ?? nothing}
+      @keydown=${(e) => this.#key(e, keys)}
+      @click=${(e) => this.#click(e)}
+      @dblclick=${(e) => this.#open(e)}
+      @contextmenu=${(e) => this.#menu(e)}>
+      ${each(rows, (r) => r.key, ({ key, entity }) => html `<div class="aster-option" role="option" id=${this.#id(key)} data-key=${key}
+          aria-selected=${key === selected ? "true" : "false"}>${entity ? row(entity, key) : nothing}</div>`)}
+      ${empty ? html `<div class="aster-listbox-empty" role="presentation">${this.#empty.value}</div>` : nothing}
+    </aster-caret-group>`;
+    }
+    select(key) {
+        const selection = this.#selection.peek();
+        if (!selection)
+            return;
+        selection.select(key);
+        requestAnimationFrame(() => this.rowFor(key)?.scrollIntoView({ block: "nearest" }));
+    }
+    #id(key) {
+        return this.#prefix + key.replace(/[^\w-]/g, (c) => `_${c.charCodeAt(0).toString(16)}`);
+    }
+    #rowOf(e) {
+        return e.target.closest('[role="option"]') ?? undefined;
+    }
+    #click(e) {
+        const row = this.#rowOf(e);
+        if (!row)
+            return;
+        // Dragging across a name to copy it doesn't change the selection.
+        const text = getSelection();
+        if (text && !text.isCollapsed && row.contains(text.anchorNode))
+            return;
+        this.select(row.dataset.key);
+    }
+    #open(e) {
+        if (editing(e))
+            return;
+        const row = this.#rowOf(e);
+        if (row)
+            this.emit("row-open", { key: row.dataset.key });
+    }
+    #menu(e) {
+        const row = this.#rowOf(e);
+        if (!row)
+            return;
+        e.preventDefault();
+        this.select(row.dataset.key);
+        this.emit("row-menu", { key: row.dataset.key, x: e.clientX, y: e.clientY, opener: this.#list() });
+    }
+    #key(e, keys) {
+        if (editing(e))
+            return;
+        const current = this.#selection.peek()?.key.peek();
+        if ((e.key === "F10" && e.shiftKey) || e.key === "ContextMenu") {
+            if (current === undefined)
+                return;
+            e.preventDefault();
+            const rect = this.rowFor(current)?.getBoundingClientRect();
+            this.emit("row-menu", { key: current, x: rect?.left ?? 0, y: rect?.bottom ?? 0, opener: this.#list() });
+            return;
+        }
+        if (e.key === "Enter" && current !== undefined) {
+            e.preventDefault();
+            this.emit("row-open", { key: current });
+            return;
+        }
+        const i = current === undefined ? -1 : keys.indexOf(current);
+        const n = e.key === "Home" ? 0
+            : e.key === "End" ? keys.length - 1
+                : e.key === "ArrowDown" ? Math.min(keys.length - 1, i + 1)
+                    : e.key === "ArrowUp" ? Math.max(0, i - 1)
+                        : undefined;
+        if (n === undefined || keys[n] === undefined)
+            return;
+        e.preventDefault();
+        this.select(keys[n]);
+    }
+    #list() {
+        return this.querySelector('[role="listbox"]') ?? this;
+    }
+}
+/** The event comes from an editor inside a row, which keeps its own keys. */
+function editing(e) {
+    return e.target.closest("input, textarea, select, [contenteditable]") !== null;
+}
+define("aster-listbox", Listbox);

package/dist/menu/menu.d.ts

@@ -0,0 +1,55 @@
+import { AsterElement, type View } from "../base/element.ts";
+/** An entry of a menu. Without a `kind` it's an action. */
+export type MenuItem = {
+    readonly kind?: "action";
+    readonly label: string;
+    readonly run: () => void;
+    readonly disabled?: string;
+} | {
+    readonly kind: "link";
+    readonly label: string;
+    readonly href: string;
+    readonly activate?: (event: MouseEvent) => void;
+} | {
+    readonly kind: "check" | "radio";
+    readonly label: string;
+    readonly checked: boolean;
+    readonly run: () => void;
+} | {
+    readonly kind: "submenu";
+    readonly label: string;
+    readonly items: readonly MenuItem[];
+} | {
+    readonly kind: "group";
+    readonly label: string;
+    readonly items: readonly MenuItem[];
+} | {
+    readonly kind: "separator";
+};
+/**
+ * A menu in the top layer (Popover API), following the APG menu pattern: it
+ * opens at a point (a context menu) or against an element, focuses its
+ * first item, and moves with the arrows, Home, End and type-ahead. → opens a
+ * submenu and ← closes it; check and radio items toggle in place. Escape
+ * closes one level, a press outside or focus leaving closes all, and focus
+ * returns to the opener. Disabled items stay focusable and say why.
+ *
+ * The popovers are manual because an auto popover opened from `contextmenu`
+ * is dismissed by the same click's pointer-up in some engines. A menu opened
+ * at a point writes only the point; one opened against an element, and every
+ * submenu, is placed by CSS anchor positioning and flips at the edges.
+ */
+export declare class Menu extends AsterElement {
+    #private;
+    /** Opens at a point, such as a right-click. */
+    openAt(point: {
+        x: number;
+        y: number;
+    }, items: readonly MenuItem[], label: string, opener: HTMLElement | null): void;
+    /** Opens against `anchor`, below it, flipping at the edges; focus returns to `opener`. */
+    openFrom(anchor: HTMLElement, items: readonly MenuItem[], label: string, opener?: HTMLElement): void;
+    close(): void;
+    protected render(): View;
+    protected updated(): void;
+    disconnectedCallback(): void;
+}