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

package/dist/menu/menu.js

@@ -0,0 +1,286 @@
+import { html, nothing } from "lit-html";
+import { AsterElement, define, uid } from "../base/element.js";
+import { openWhen, placeStyle } from "../overlay/anchor.js";
+/**
+ * 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 class Menu extends AsterElement {
+    #items = this.prop([]);
+    #label = this.prop("");
+    /** The open submenus: indexes into each level's focusable items. */
+    #path = this.prop([]);
+    #open = this.prop(false);
+    #anchor = this.prop(undefined);
+    /** Check and radio marks changed since the menu opened; items keep the state they were given. */
+    #marks = this.prop(new Map());
+    #id = uid("aster-menu");
+    #opener = null;
+    /** The item to focus once its menu has rendered and its popover is open. */
+    #focusNext;
+    #stop;
+    /** Opens at a point, such as a right-click. */
+    openAt(point, items, label, opener) {
+        this.style.setProperty("--menu-x", `${point.x}px`);
+        this.style.setProperty("--menu-y", `${point.y}px`);
+        this.#show(items, label, opener, undefined);
+    }
+    /** Opens against `anchor`, below it, flipping at the edges; focus returns to `opener`. */
+    openFrom(anchor, items, label, opener = anchor) {
+        const name = `${this.#id}-anchor`;
+        anchor.style.setProperty("anchor-name", `--${name}`);
+        this.#show(items, label, opener, name);
+    }
+    close() {
+        if (!this.#open.peek())
+            return;
+        this.#open.value = false;
+        this.#path.value = [];
+        this.#closed();
+    }
+    render() {
+        if (!this.#open.value)
+            return nothing;
+        const path = this.#path.value;
+        const levels = [{ items: this.#items.value, label: this.#label.value }];
+        for (const index of path) {
+            const parent = focusables(levels.at(-1).items)[index];
+            if (parent?.kind !== "submenu")
+                break;
+            levels.push({ items: parent.items, label: parent.label });
+        }
+        const anchored = this.#anchor.value;
+        return html `${levels.map((level, depth) => {
+            const place = depth > 0 ? placeStyle(this.#itemId(depth - 1, path[depth - 1])) : anchored ? placeStyle(anchored) : nothing;
+            return html `<div class="aster-menu" popover="manual" role="menu" aria-label=${level.label || nothing}
+        data-depth=${depth} ?data-anchored=${depth > 0 || anchored !== undefined} style=${place} ${openWhen(true)}
+        @keydown=${(e) => this.#key(e, depth)}>
+        ${this.#entries(level.items, depth, { next: 0 })}
+      </div>`;
+        })}`;
+    }
+    #entries(items, depth, counter) {
+        return items.map((item) => {
+            if (item.kind === "separator")
+                return html `<div role="separator" class="aster-menu-separator"></div>`;
+            if (item.kind === "group") {
+                const id = `${this.#id}-g${depth}-${counter.next}`;
+                return html `<div role="group" aria-labelledby=${id}>
+          <div class="aster-menu-heading" id=${id}>${item.label}</div>
+          ${this.#entries(item.items, depth, counter)}
+        </div>`;
+            }
+            const index = counter.next++;
+            const id = this.#itemId(depth, index);
+            const expanded = this.#path.value[depth] === index;
+            const enter = () => this.#hover(depth, index, item);
+            switch (item.kind) {
+                case "link":
+                    return html `<a role="menuitem" tabindex="-1" id=${id} href=${item.href} @pointerenter=${enter}
+            @click=${(event) => { this.close(); item.activate?.(event); }}><span class="aster-menu-mark" aria-hidden="true"></span>${item.label}</a>`;
+                case "check":
+                case "radio":
+                    {
+                        const checked = this.#marks.value.get(item) ?? item.checked;
+                        return html `<button type="button" role=${item.kind === "check" ? "menuitemcheckbox" : "menuitemradio"} tabindex="-1"
+              id=${id} aria-checked=${checked ? "true" : "false"} @pointerenter=${enter} @click=${() => this.#choose(item)}>
+              <span class="aster-menu-mark" aria-hidden="true">${checked ? (item.kind === "check" ? "✓" : "•") : ""}</span>${item.label}</button>`;
+                    }
+                case "submenu":
+                    return html `<button type="button" role="menuitem" tabindex="-1" id=${id} aria-haspopup="menu"
+            aria-expanded=${expanded ? "true" : "false"} style=${`anchor-name: --${id}`}
+            @pointerenter=${enter} @click=${() => this.#openSub(depth, index, true)}>
+            <span class="aster-menu-mark" aria-hidden="true"></span>${item.label}<span class="aster-menu-more" aria-hidden="true">›</span></button>`;
+                default:
+                    return html `<button type="button" role="menuitem" tabindex="-1" id=${id}
+            aria-disabled=${item.disabled ? "true" : nothing} title=${item.disabled ?? nothing}
+            @pointerenter=${enter} @click=${() => this.#choose(item)}>
+            <span class="aster-menu-mark" aria-hidden="true"></span>${item.label}</button>`;
+            }
+        });
+    }
+    #show(items, label, opener, anchor) {
+        this.#items.value = items;
+        this.#label.value = label;
+        this.#opener = opener;
+        this.#anchor.value = anchor;
+        this.#path.value = [];
+        this.#marks.value = new Map();
+        this.#open.value = true;
+        this.#focusNext = { depth: 0, index: 0 };
+        this.#watchOutside();
+    }
+    updated() {
+        const next = this.#focusNext;
+        if (!next)
+            return;
+        // After the popovers this render opened (they open in a microtask too).
+        queueMicrotask(() => {
+            const target = this.#level(next.depth)[next.index];
+            if (!target)
+                return;
+            this.#focusNext = undefined;
+            target.focus();
+        });
+    }
+    #itemId(depth, index) {
+        return `${this.#id}-${depth}-${index}`;
+    }
+    #level(depth) {
+        const menu = this.querySelector(`.aster-menu[data-depth="${depth}"]`);
+        return menu ? [...menu.querySelectorAll(':scope > [role^="menuitem"], :scope > [role="group"] > [role^="menuitem"]')] : [];
+    }
+    #choose(item) {
+        if (item.kind === "submenu" || item.kind === "link")
+            return;
+        if ((item.kind === undefined || item.kind === "action") && item.disabled)
+            return;
+        if (item.kind === "check" || item.kind === "radio") {
+            const marks = new Map(this.#marks.peek());
+            if (item.kind === "check")
+                marks.set(item, !(marks.get(item) ?? item.checked));
+            else
+                for (const other of siblings(this.#items.peek(), item) ?? [item])
+                    if (other.kind === "radio")
+                        marks.set(other, other === item);
+            this.#marks.value = marks;
+            item.run();
+            return;
+        }
+        this.close();
+        item.run();
+    }
+    #openSub(depth, index, focus) {
+        this.#path.value = [...this.#path.peek().slice(0, depth), index];
+        if (focus)
+            this.#focusNext = { depth: depth + 1, index: 0 };
+    }
+    /** Pointing at an item opens its submenu, or closes deeper ones. */
+    #hover(depth, index, item) {
+        const path = this.#path.peek();
+        if (item.kind === "submenu") {
+            if (path[depth] !== index)
+                this.#openSub(depth, index, false);
+        }
+        else if (path.length > depth) {
+            this.#path.value = path.slice(0, depth);
+        }
+        this.#level(depth)[index]?.focus();
+    }
+    #key(e, depth) {
+        e.stopPropagation();
+        const items = this.#level(depth);
+        const i = items.indexOf(document.activeElement);
+        const focus = (n) => {
+            e.preventDefault();
+            items[(n + items.length) % items.length]?.focus();
+        };
+        switch (e.key) {
+            case "ArrowDown":
+                return focus(i + 1);
+            case "ArrowUp":
+                return focus(i - 1);
+            case "Home":
+                return focus(0);
+            case "End":
+                return focus(items.length - 1);
+            case "ArrowRight":
+            case "Enter":
+            case " ": {
+                const current = items[i];
+                if (current?.getAttribute("aria-haspopup") === "menu") {
+                    e.preventDefault();
+                    this.#openSub(depth, i, true);
+                }
+                else if (e.key !== "ArrowRight") {
+                    e.preventDefault();
+                    current?.click();
+                }
+                return;
+            }
+            case "ArrowLeft":
+            case "Escape":
+                e.preventDefault();
+                if (depth === 0) {
+                    if (e.key === "Escape")
+                        this.close();
+                    return;
+                }
+                {
+                    const parent = this.#path.peek()[depth - 1];
+                    this.#path.value = this.#path.peek().slice(0, depth - 1);
+                    this.#focusNext = { depth: depth - 1, index: parent };
+                }
+                return;
+            case "Tab":
+                this.close();
+                return;
+            default: {
+                if (e.key.length !== 1 || !/\S/.test(e.key))
+                    return;
+                const k = e.key.toLowerCase();
+                for (let step = 1; step <= items.length; step++) {
+                    const n = (i + step) % items.length;
+                    if ((items[n]?.textContent ?? "").trim().toLowerCase().startsWith(k))
+                        return focus(n);
+                }
+            }
+        }
+    }
+    #watchOutside() {
+        this.#stop?.();
+        const down = (e) => {
+            if (!this.contains(e.target))
+                this.close();
+        };
+        const focus = (e) => {
+            if (!this.contains(e.target))
+                this.close();
+        };
+        document.addEventListener("pointerdown", down, true);
+        document.addEventListener("focusin", focus, true);
+        this.#stop = () => {
+            document.removeEventListener("pointerdown", down, true);
+            document.removeEventListener("focusin", focus, true);
+            this.#stop = undefined;
+        };
+    }
+    disconnectedCallback() {
+        this.#stop?.();
+        super.disconnectedCallback();
+    }
+    #closed() {
+        this.#stop?.();
+        const opener = this.#opener;
+        this.#opener = null;
+        if (opener?.isConnected && (!document.activeElement || document.activeElement === document.body || this.contains(document.activeElement))) {
+            opener.focus();
+        }
+    }
+}
+/** The list that holds `item`, searched through groups and submenus. */
+function siblings(items, item) {
+    if (items.includes(item))
+        return items;
+    for (const i of items) {
+        if (i.kind === "group" || i.kind === "submenu") {
+            const found = siblings(i.items, item);
+            if (found)
+                return found;
+        }
+    }
+    return undefined;
+}
+function focusables(items) {
+    return items.flatMap((i) => (i.kind === "separator" ? [] : i.kind === "group" ? focusables(i.items) : [i]));
+}
+define("aster-menu", Menu);

package/dist/motion.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Runs a DOM change as a view transition, so a container with a
+ * `view-transition-name` morphs to its new shape and the content fades in
+ * after it. Without support, or with reduced motion, the change just happens.
+ */
+export declare function morph(change: () => void): void;
+/** Selects the colour scheme, cross-fading the whole page. */
+export declare function setScheme(scheme: "light" | "dark", animate?: boolean): void;

package/dist/motion.js

@@ -0,0 +1,23 @@
+const reduced = () => matchMedia("(prefers-reduced-motion: reduce)").matches;
+/**
+ * Runs a DOM change as a view transition, so a container with a
+ * `view-transition-name` morphs to its new shape and the content fades in
+ * after it. Without support, or with reduced motion, the change just happens.
+ */
+export function morph(change) {
+    if (!document.startViewTransition || reduced()) {
+        change();
+        return;
+    }
+    document.startViewTransition(change);
+}
+/** Selects the colour scheme, cross-fading the whole page. */
+export function setScheme(scheme, animate = true) {
+    const apply = () => {
+        document.documentElement.dataset.scheme = scheme;
+    };
+    if (animate)
+        morph(apply);
+    else
+        apply();
+}

package/dist/overlay/anchor.d.ts

@@ -0,0 +1,18 @@
+import { nothing } from "lit-html";
+/**
+ * Overlays live in the top layer, so no scroll container or section clips
+ * them, and are placed against their anchor by CSS anchor positioning,
+ * flipping at the viewport's edges (`.aster-popover` in elements.css). JS
+ * only names the anchor and opens or closes the popover.
+ *
+ * Usage: the anchor gets `style=${anchorStyle(id)}`; the overlay gets
+ * `popover="manual" class="aster-popover" style=${placeStyle(id)} ${openWhen(open)}`.
+ */
+export declare function anchorStyle(id: string): string;
+export declare function placeStyle(id: string): string;
+/**
+ * Shows or hides the popover it's on to match `open`. A popover rendered
+ * fresh isn't in the document yet when this runs, so it syncs once it is.
+ */
+export declare function openWhen(open: boolean): import("lit-html/directive.js").DirectiveResult<typeof import("lit-html/directives/ref.js").RefDirective>;
+export { nothing };

package/dist/overlay/anchor.js

@@ -0,0 +1,41 @@
+import { nothing } from "lit-html";
+import { ref } from "lit-html/directives/ref.js";
+/**
+ * Overlays live in the top layer, so no scroll container or section clips
+ * them, and are placed against their anchor by CSS anchor positioning,
+ * flipping at the viewport's edges (`.aster-popover` in elements.css). JS
+ * only names the anchor and opens or closes the popover.
+ *
+ * Usage: the anchor gets `style=${anchorStyle(id)}`; the overlay gets
+ * `popover="manual" class="aster-popover" style=${placeStyle(id)} ${openWhen(open)}`.
+ */
+export function anchorStyle(id) {
+    return `anchor-name: --${id}`;
+}
+export function placeStyle(id) {
+    return `position-anchor: --${id}`;
+}
+/**
+ * Shows or hides the popover it's on to match `open`. A popover rendered
+ * fresh isn't in the document yet when this runs, so it syncs once it is.
+ */
+export function openWhen(open) {
+    return ref((el) => {
+        if (!(el instanceof HTMLElement))
+            return;
+        const sync = () => {
+            if (!el.isConnected)
+                return;
+            const showing = el.matches(":popover-open");
+            if (open && !showing)
+                el.showPopover();
+            else if (!open && showing)
+                el.hidePopover();
+        };
+        if (el.isConnected)
+            sync();
+        else
+            queueMicrotask(sync);
+    });
+}
+export { nothing };

package/dist/picker/options.d.ts

@@ -0,0 +1,59 @@
+import { type ReadonlySignal } from "@preact/signals-core";
+import { type Collection, type Criteria, type DataContext, type Entity, type EntityType, type Query, type SortKey, type Value } from "@getaster/data";
+export interface OptionsSpec {
+    readonly set: string;
+    /** Limits the options. A signal follows the page scope: the project's people, the country's regions. */
+    readonly filter?: Criteria | ReadonlySignal<Criteria | undefined>;
+    /** By default the display field (after `groupBy`). */
+    readonly orderBy?: readonly SortKey[];
+    /** The field an option shows as its name; by default the type's title field. */
+    readonly display?: string;
+    /** Fields typing searches, case-insensitively; by default the display field. */
+    readonly searchFields?: readonly string[];
+    /** More fields shown as columns beside the name, with a header that sorts by them. */
+    readonly columns?: readonly string[];
+    /** Column widths as CSS track sizes, by field (the name's too); shared space otherwise. */
+    readonly widths?: Readonly<Record<string, string>>;
+    /** Options under a heading per value of this field. */
+    readonly groupBy?: string;
+    readonly pageSize?: number;
+    /** Offers "Create …": a small form with these fields, the typed text in the display field. */
+    readonly create?: readonly string[];
+    /** Said under the field when its value is outside the options: "isn't on this project's team". */
+    readonly outside?: string;
+}
+/**
+ * Where a picker's options come from: a query over an entity set, shared by
+ * every picker that uses it (a column of a grid, a list of tasks). With
+ * more options than one page, typing searches on the server through a
+ * collection of its own; with fewer, it filters what's loaded.
+ */
+export declare class PickerOptions {
+    #private;
+    readonly ctx: DataContext;
+    readonly spec: OptionsSpec;
+    readonly type: EntityType;
+    readonly key: string;
+    readonly display: string;
+    readonly pageSize: number;
+    /** The options with no search typed. */
+    readonly all: Collection;
+    /** The sort a person chose from the columns' header; the spec's order until then. */
+    readonly sort: import("@preact/signals-core").Signal<readonly SortKey[] | undefined>;
+    constructor(ctx: DataContext, spec: OptionsSpec);
+    /** Sorts by a column, or reverses the sort when it's already by that column. */
+    sortBy(field: string): void;
+    /** The grid tracks for the name and the columns, after a check column when several can be chosen. */
+    tracks(multiple: boolean): string;
+    /** Every option is loaded or loads in one page, so typing filters them here. */
+    get small(): boolean;
+    query(base: Criteria | undefined, search?: string): Query;
+    /** A collection over the options matching `search`; `release` it when done. */
+    search(search: ReadonlySignal<string>): Collection;
+    release(collection: Collection): void;
+    /** The record a value names, fetched if it isn't loaded. */
+    record(value: Value | undefined): ReadonlySignal<Entity | undefined> | undefined;
+    /** Whether a record is among the options now; undefined if that can't be told here. */
+    fits(entity: Entity): boolean | undefined;
+    text(entity: Entity, field?: string): string;
+}

package/dist/picker/options.js

@@ -0,0 +1,97 @@
+import { computed, signal } from "@preact/signals-core";
+import { keyText, matches, } from "@getaster/data";
+/**
+ * Where a picker's options come from: a query over an entity set, shared by
+ * every picker that uses it (a column of a grid, a list of tasks). With
+ * more options than one page, typing searches on the server through a
+ * collection of its own; with fewer, it filters what's loaded.
+ */
+export class PickerOptions {
+    ctx;
+    spec;
+    type;
+    key;
+    display;
+    pageSize;
+    /** The options with no search typed. */
+    all;
+    #filter;
+    /** The sort a person chose from the columns' header; the spec's order until then. */
+    sort = signal(undefined);
+    constructor(ctx, spec) {
+        this.ctx = ctx;
+        this.spec = spec;
+        this.type = ctx.schema.set(spec.set).type;
+        this.key = this.type.key[0];
+        this.display = spec.display ?? this.type.titleField ?? this.key;
+        this.pageSize = spec.pageSize ?? 50;
+        const filter = spec.filter;
+        this.#filter = filter === undefined ? computed(() => undefined) : "value" in filter && "peek" in filter ? filter : computed(() => filter);
+        this.all = ctx.collection(computed(() => this.query(this.#filter.value)), { pageSize: this.pageSize });
+    }
+    /** Sorts by a column, or reverses the sort when it's already by that column. */
+    sortBy(field) {
+        const current = this.sort.peek()?.[0];
+        this.sort.value = [{ field, ...(current?.field === field && !current.descending ? { descending: true } : {}) }];
+    }
+    /** The grid tracks for the name and the columns, after a check column when several can be chosen. */
+    tracks(multiple) {
+        const widths = this.spec.widths ?? {};
+        const fields = [this.display, ...(this.spec.columns ?? [])];
+        return [...(multiple ? ["12px"] : []), ...fields.map((f, i) => widths[f] ?? (i === 0 ? "minmax(0, 1.4fr)" : "minmax(0, 1fr)"))].join(" ");
+    }
+    /** Every option is loaded or loads in one page, so typing filters them here. */
+    get small() {
+        const n = this.all.count.value;
+        return n !== undefined && n <= this.pageSize;
+    }
+    query(base, search) {
+        const fields = this.spec.searchFields ?? [this.display];
+        const text = search?.trim();
+        const searching = text
+            ? fields.length === 1
+                ? { op: "contains", field: fields[0], value: text, caseInsensitive: true }
+                : { op: "or", args: fields.map((field) => ({ op: "contains", field, value: text, caseInsensitive: true })) }
+            : undefined;
+        const parts = [base, searching].filter((c) => c !== undefined);
+        const orderBy = [
+            ...(this.spec.groupBy ? [{ field: this.spec.groupBy }] : []),
+            ...(this.sort.value ?? this.spec.orderBy ?? [{ field: this.display }]),
+        ];
+        return {
+            set: this.spec.set,
+            ...(parts.length === 0 ? {} : { filter: parts.length === 1 ? parts[0] : { op: "and", args: parts } }),
+            orderBy,
+        };
+    }
+    /** A collection over the options matching `search`; `release` it when done. */
+    search(search) {
+        return this.ctx.collection(computed(() => this.query(this.#filter.value, search.value)), { pageSize: this.pageSize });
+    }
+    release(collection) {
+        this.ctx.release(collection);
+    }
+    /** The record a value names, fetched if it isn't loaded. */
+    record(value) {
+        return value === null || value === undefined ? undefined : this.ctx.lookup(this.spec.set, keyText([value]));
+    }
+    /** Whether a record is among the options now; undefined if that can't be told here. */
+    fits(entity) {
+        const filter = this.#filter.value;
+        if (!filter)
+            return true;
+        try {
+            return matches(filter, entity, this.type);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    text(entity, field = this.display) {
+        const v = entity[field];
+        if (v === null || v === undefined)
+            return "";
+        const allowed = this.type.field(field)?.allowedValues?.find((a) => a.value === v);
+        return allowed?.label ?? String(v);
+    }
+}

package/dist/picker/picker.d.ts

@@ -0,0 +1,46 @@
+import { type Collection, type Field as FieldMeta, type Value } from "@getaster/data";
+import { type View } from "../base/element.ts";
+import { BoundField, type ControlContext } from "../field/bound-field.ts";
+import "../field/field.ts";
+import "../select/select.ts";
+import { PickerOptions } from "./options.ts";
+/**
+ * A combobox over related records (APG editable combobox with list
+ * autocomplete). It shows the record's display field and offers the
+ * options, filtered as you type: on the server when there are more than a
+ * page of them, with the match count announced.
+ *
+ * With `PickerOptions` it also has columns with a header, headings by a
+ * group field, options that follow the page scope (a value they no longer
+ * include stays, and the field says so), and "Create …", a small form that
+ * selects what it created. `multiple` holds several values as chips and
+ * reports them by `change`; it isn't bound to a model.
+ *
+ * Keyboard: ↓/↑ open and move, Page Down/Up move further, Home/End go to
+ * the first and last option, Enter chooses, Escape closes and restores the
+ * text, Tab leaves without choosing; with chips, Backspace in the empty
+ * input removes the last. The active option is the input's
+ * `aria-activedescendant`, so focus stays in the input.
+ */
+export declare class Picker extends BoundField {
+    #private;
+    get options(): Collection | PickerOptions | undefined;
+    set options(v: Collection | PickerOptions | undefined);
+    /** The field of an option shown as its text (with a plain collection). */
+    get display(): string;
+    set display(v: string);
+    get valueField(): string;
+    set valueField(v: string);
+    get multiple(): boolean;
+    set multiple(v: boolean);
+    /** The chosen values when `multiple`. */
+    get values(): readonly Value[];
+    set values(v: readonly Value[]);
+    get placeholder(): string;
+    set placeholder(v: string);
+    protected describe(_meta: FieldMeta | undefined, value: Value | undefined): string;
+    focus(options?: FocusOptions): void;
+    disconnectedCallback(): void;
+    protected control(c: ControlContext): View;
+}
+export { PickerOptions, type OptionsSpec } from "./options.ts";