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

package/dist/composition/schema.js

@@ -0,0 +1,139 @@
+export function asSchema(value) { return value && typeof value === "object" && !Array.isArray(value) ? value : {}; }
+export function schemaProperty(schema) { return { schema, validate: value => matchesSchema(value, schema) }; }
+export function matchesSchema(value, schema) {
+    if (Array.isArray(schema.allOf) && !schema.allOf.every(s => matchesSchema(value, asSchema(s))))
+        return false;
+    if (Array.isArray(schema.anyOf) && !schema.anyOf.some(s => matchesSchema(value, asSchema(s))))
+        return false;
+    if (Object.hasOwn(schema, "const") && value !== schema.const)
+        return false;
+    if (Array.isArray(schema.enum) && !schema.enum.includes(value))
+        return false;
+    if (schema.asterType === "undefined")
+        return value === undefined;
+    if (schema.type) {
+        switch (schema.type) {
+            case "string":
+                if (typeof value !== "string")
+                    return false;
+                break;
+            case "boolean":
+                if (typeof value !== "boolean")
+                    return false;
+                break;
+            case "number":
+                if (typeof value !== "number" || !Number.isFinite(value))
+                    return false;
+                break;
+            case "integer":
+                if (typeof value !== "number" || !Number.isSafeInteger(value))
+                    return false;
+                break;
+            case "null":
+                if (value !== null)
+                    return false;
+                break;
+            case "array":
+                if (!Array.isArray(value))
+                    return false;
+                break;
+            case "object":
+                if (!value || typeof value !== "object" || Array.isArray(value))
+                    return false;
+                break;
+        }
+    }
+    if (typeof value === "number" && (typeof schema.minimum === "number" && value < schema.minimum || typeof schema.maximum === "number" && value > schema.maximum))
+        return false;
+    if (Array.isArray(value) && schema.items && !value.every(item => matchesSchema(item, asSchema(schema.items))))
+        return false;
+    if (schema.type === "object" && value && typeof value === "object") {
+        const values = value;
+        const fields = asSchema(schema.properties);
+        if (Array.isArray(schema.required) && !schema.required.every(key => typeof key === "string" && Object.hasOwn(values, key)))
+            return false;
+        for (const [key, item] of Object.entries(values)) {
+            if (Object.hasOwn(fields, key) && !matchesSchema(item, asSchema(fields[key])))
+                return false;
+            if (!Object.hasOwn(fields, key) && schema.additionalProperties === false)
+                return false;
+        }
+    }
+    return true;
+}
+/** Unknown/custom refinements are runtime checks; metadata cannot prove their assignability. */
+export function compatibility(source, target) {
+    if (Array.isArray(source.anyOf)) {
+        const results = source.anyOf.map(item => compatibility(asSchema(item), target));
+        return results.includes(false) ? false : results.every(item => item === true) ? true : undefined;
+    }
+    if (Array.isArray(target.anyOf)) {
+        const results = target.anyOf.map(item => compatibility(source, asSchema(item)));
+        return results.includes(true) ? true : results.every(item => item === false) ? false : undefined;
+    }
+    if (target.allOf || source.allOf)
+        return undefined;
+    if (target.asterType) {
+        if (!source.asterType)
+            return source.type ? false : undefined;
+        if (source.asterType !== target.asterType)
+            return Array.isArray(source.asterBases) && source.asterBases.includes(target.asterType);
+        if (target.asterType === "signal")
+            return compatibility(asSchema(source.value), asSchema(target.value));
+        return true;
+    }
+    if (target.type) {
+        if (source.asterType)
+            return false;
+        if (!source.type)
+            return undefined;
+        if (source.type !== target.type && !(source.type === "integer" && target.type === "number"))
+            return false;
+        if (Array.isArray(target.enum)) {
+            if (!Array.isArray(source.enum))
+                return undefined;
+            if (!source.enum.every(value => target.enum.includes(value)))
+                return false;
+        }
+        if (Object.hasOwn(target, "const"))
+            return Object.hasOwn(source, "const") ? source.const === target.const : undefined;
+        if (target.minimum !== undefined || target.maximum !== undefined)
+            return undefined;
+        if (target.type === "array")
+            return compatibility(asSchema(source.items), asSchema(target.items));
+        if (target.type === "object") {
+            const sourceFields = asSchema(source.properties);
+            const targetFields = asSchema(target.properties);
+            if (target.additionalProperties === false && Object.keys(sourceFields).some(key => !Object.hasOwn(targetFields, key)))
+                return false;
+            const results = Object.entries(targetFields).map(([key, field]) => {
+                if (!Object.hasOwn(sourceFields, key))
+                    return Array.isArray(target.required) && target.required.includes(key) ? false : true;
+                if (Array.isArray(target.required) && target.required.includes(key) && !(Array.isArray(source.required) && source.required.includes(key)))
+                    return false;
+                return compatibility(asSchema(sourceFields[key]), asSchema(field));
+            });
+            if (results.includes(false))
+                return false;
+            if (target.additionalProperties === false && source.additionalProperties !== false)
+                return undefined;
+            return results.every(result => result === true) ? true : undefined;
+        }
+        return true;
+    }
+    return undefined;
+}
+/** JSON cannot express instance identity, signals or undefined as literal values. */
+export function literalSchema(schema) {
+    if (schema.asterType)
+        return { not: {} };
+    const result = { ...schema };
+    if (schema.properties)
+        result.properties = Object.fromEntries(Object.entries(asSchema(schema.properties)).map(([key, field]) => [key, literalSchema(asSchema(field))]));
+    if (schema.items)
+        result.items = literalSchema(asSchema(schema.items));
+    for (const key of ["anyOf", "allOf", "oneOf"])
+        if (Array.isArray(schema[key]))
+            result[key] = schema[key].map(item => literalSchema(asSchema(item)));
+    return result;
+}

package/dist/composition/sessions.d.ts

@@ -0,0 +1,15 @@
+import { KeyedSessions, type PageScope, type SessionActivity, type SessionDescriptor } from "@getaster/data";
+import { type CompositeResolver, type CompositeSession } from "./registry.ts";
+export interface CompositeSessionsOptions {
+    readonly parentScope?: PageScope;
+    readonly activity?: SessionActivity;
+}
+export interface CompositeKeyedSession extends CompositeSession {
+    /** Stable host for placement in Tabs, renderers or ordinary DOM. */
+    readonly element: HTMLElement;
+}
+/** Keyed registered components, including compiled composites via compositeComponent.
+ * Definitions consume this through ordinary model references and renderer bindings. */
+export declare class CompositeSessions extends KeyedSessions<SessionDescriptor, CompositeKeyedSession> {
+    constructor(registry: CompositeResolver, options?: CompositeSessionsOptions);
+}

package/dist/composition/sessions.js

@@ -0,0 +1,61 @@
+import { effect } from "@preact/signals-core";
+import { KeyedSessions } from "@getaster/data";
+import { provideScope } from "../base/element.js";
+import { checkContract } from "./registry.js";
+/** Keyed registered components, including compiled composites via compositeComponent.
+ * Definitions consume this through ordinary model references and renderer bindings. */
+export class CompositeSessions extends KeyedSessions {
+    constructor(registry, options = {}) {
+        super({
+            ...options,
+            validate: descriptor => {
+                const type = registry.component(descriptor.type);
+                if (type.mutableInputs?.length && !type.apply)
+                    throw new Error(`Component '${descriptor.type}' needs apply for mutable inputs`);
+                for (const key of type.mutableInputs ?? [])
+                    if (!Object.hasOwn(type.props, key))
+                        throw new Error(`Unknown mutable input '${key}'`);
+                checkContract(descriptor.inputs ?? {}, type.props, `sessions.${descriptor.key}.inputs`);
+            },
+            checkUpdate: (previous, next) => {
+                const mutable = new Set(registry.component(next.type).mutableInputs ?? []);
+                for (const key of new Set([...Object.keys(previous.inputs ?? {}), ...Object.keys(next.inputs ?? {})])) {
+                    if (!mutable.has(key) && !Object.is(previous.inputs?.[key], next.inputs?.[key]))
+                        throw new Error(`Session '${next.key}' cannot change immutable input '${key}'`);
+                }
+                if (previous.inactive !== next.inactive)
+                    throw new Error(`Session '${next.key}' cannot change inactive policy`);
+            },
+            create: async (descriptor, mount) => {
+                const type = registry.component(descriptor.type);
+                const create = await registry.load(descriptor.type);
+                mount.lifetime.signal.throwIfAborted();
+                const session = await create({ props: descriptor.inputs ?? {}, ...mount });
+                mount.lifetime.defer(() => session.dispose?.());
+                mount.lifetime.signal.throwIfAborted();
+                const element = document.createElement("div");
+                element.className = "aster-composite-session";
+                element.dataset.session = descriptor.key;
+                provideScope(element, session.scope ?? mount.scope);
+                element.append(session.element);
+                mount.lifetime.defer(effect(() => {
+                    const active = mount.activity.active.value;
+                    if (!active && element.contains(document.activeElement)) {
+                        const target = element.parentElement?.closest('[tabindex]');
+                        target?.focus();
+                    }
+                    element.hidden = !active;
+                    element.inert = !active;
+                }));
+                return { element, ...(session.scope ? { scope: session.scope } : {}),
+                    ...(session.canClose ? { canClose: signal => session.canClose(signal) } : {}),
+                    ...(session.setActive ? { setActive: active => session.setActive(active) } : {}),
+                    dispose: () => element.remove(), };
+            },
+            update: (resource, _previous, next) => {
+                const type = registry.component(next.type);
+                type.apply?.(resource.element.firstElementChild, next.inputs ?? {});
+            },
+        });
+    }
+}

package/dist/dashboard/dashboard.d.ts

@@ -0,0 +1,26 @@
+import { AsterElement, type View } from "../base/element.ts";
+import { type DashboardConfig, type DashboardSize, type DashboardSnapshot, type DashboardWidget } from "./layout.ts";
+import { type DashboardWidgetType } from "./widget.ts";
+/** CSS-owned composition; the page owns storage, shared data and widget factories. */
+export declare class Dashboard extends AsterElement {
+    #private;
+    get label(): string;
+    set label(value: string);
+    get widgets(): readonly DashboardWidget[];
+    get maximized(): string | null;
+    get busy(): boolean;
+    connectedCallback(): void;
+    registerType(name: string, type: DashboardWidgetType): () => void;
+    add(widget: DashboardWidget): void;
+    move(id: string, index: number): void;
+    resize(id: string, width: DashboardSize, height: DashboardSize): void;
+    configure(id: string, config: DashboardConfig, title?: string): void;
+    maximize(id: string | null): void;
+    removeWidget(id: string): Promise<boolean>;
+    retry(id: string): Promise<boolean>;
+    snapshot(): DashboardSnapshot;
+    restore(snapshot: DashboardSnapshot): Promise<boolean>;
+    disconnectedCallback(): void;
+    protected render(): View;
+    protected updated(): void;
+}

package/dist/dashboard/dashboard.js

@@ -0,0 +1,296 @@
+import { PageScope } from "@getaster/data";
+import { html } from "lit-html";
+import { AsterElement, define, scopeOf } from "../base/element.js";
+import { copyLayout } from "./layout.js";
+import { DashboardPortlet } from "./widget.js";
+/** CSS-owned composition; the page owns storage, shared data and widget factories. */
+export class Dashboard extends AsterElement {
+    #label = this.prop("Dashboard");
+    #widgets = this.prop([]);
+    #maximized = this.prop(null);
+    #busy = this.prop(false);
+    #message = this.prop("");
+    #registryVersion = this.prop(0);
+    #types = new Map();
+    #cards = new Map();
+    #generation = 0;
+    #pending;
+    #focusAfter;
+    #dragEnd;
+    get label() { return this.#label.value; }
+    set label(value) { this.#label.value = value; }
+    get widgets() { return this.#widgets.value; }
+    get maximized() { return this.#maximized.value; }
+    get busy() { return this.#busy.value; }
+    connectedCallback() {
+        super.connectedCallback();
+        const report = (event) => {
+            if (event.target === this)
+                return;
+            event.stopPropagation();
+            this.emit("widgeterror", event.detail);
+        };
+        this.addEventListener("widgeterror", report);
+        this.onDisconnect(() => this.removeEventListener("widgeterror", report));
+    }
+    registerType(name, type) {
+        if (!name.trim() || this.#types.has(name) || typeof type.create !== "function")
+            throw new TypeError("Widget types require a unique name and create function");
+        this.#types.set(name, type);
+        this.#registryVersion.value++;
+        let registered = true;
+        return () => {
+            if (!registered)
+                return;
+            if (this.#widgets.peek().some(widget => widget.type === name))
+                throw new Error("Remove widgets before unregistering their type");
+            registered = false;
+            this.#types.delete(name);
+        };
+    }
+    add(widget) {
+        this.#assertIdle();
+        if (!this.#types.has(widget.type))
+            throw new Error(`Unknown widget type: ${widget.type}`);
+        this.#commit(copyLayout([...this.#widgets.peek(), widget]));
+        this.#focusAfter = widget.id;
+        this.#message.value = `${widget.title} added.`;
+    }
+    move(id, index) {
+        if (this.#busy.peek() || this.#maximized.peek())
+            return;
+        if (!Number.isInteger(index))
+            throw new TypeError("Widget position must be an integer");
+        const list = [...this.#widgets.peek()];
+        const from = this.#index(id);
+        const to = Math.max(0, Math.min(list.length - 1, index));
+        if (from === to)
+            return;
+        const [widget] = list.splice(from, 1);
+        list.splice(to, 0, widget);
+        this.#commit(list);
+        this.#message.value = `${widget.title} moved to position ${to + 1} of ${list.length}.`;
+    }
+    resize(id, width, height) {
+        if (this.#busy.peek() || this.#maximized.peek())
+            return;
+        const widget = this.#widgets.peek()[this.#index(id)];
+        const next = copyLayout(this.#widgets.peek().map(item => item.id === id ? { ...item, width, height } : item));
+        this.#commit(next);
+        this.#message.value = `${widget.title} size: ${width} columns by ${height} rows. Narrow screens may show fewer columns.`;
+    }
+    configure(id, config, title) {
+        this.#assertIdle();
+        this.#index(id);
+        this.#commit(copyLayout(this.#widgets.peek().map(widget => widget.id === id ? { ...widget, config, ...(title === undefined ? {} : { title }) } : widget)));
+    }
+    maximize(id) {
+        if (this.#busy.peek() || document.querySelector("dialog:modal"))
+            return;
+        if (id !== null)
+            this.#index(id);
+        const previous = this.#maximized.peek();
+        this.#maximized.value = id;
+        queueMicrotask(() => {
+            const card = this.#cards.get(id ?? previous ?? "");
+            card?.querySelector(".aster-widget-maximize")?.focus({ preventScroll: true });
+        });
+    }
+    removeWidget(id) {
+        const index = this.#index(id);
+        const widget = this.#widgets.peek()[index];
+        return this.#guard(`remove:${id}`, [id], () => {
+            const next = this.#widgets.peek().filter(item => item.id !== id);
+            this.#focusAfter = next[Math.min(index, next.length - 1)]?.id ?? null;
+            this.#commit(next);
+            this.#message.value = `${widget.title} removed.`;
+        });
+    }
+    retry(id) {
+        this.#index(id);
+        return this.#guard(`retry:${id}`, [id], () => {
+            const card = this.#cards.get(id);
+            const spec = this.#widgets.peek().find(widget => widget.id === id);
+            card?.dispose();
+            if (card)
+                void card.mount(this.#types.get(spec.type));
+        });
+    }
+    snapshot() { return { version: 1, widgets: copyLayout(this.#widgets.peek()) }; }
+    restore(snapshot) {
+        if (snapshot?.version !== 1)
+            throw new TypeError("Unsupported dashboard layout version");
+        const next = copyLayout(snapshot.widgets);
+        const removed = this.#widgets.peek().filter(widget => !next.some(item => item.id === widget.id && item.type === widget.type)).map(widget => widget.id);
+        return this.#guard(`layout:${JSON.stringify(next)}`, removed, () => {
+            const active = document.activeElement;
+            if (removed.some(id => this.#cards.get(id)?.contains(active)))
+                this.#focusAfter = next[0]?.id ?? null;
+            this.#commit(next);
+            this.#message.value = "Dashboard layout restored.";
+        });
+    }
+    disconnectedCallback() {
+        this.#generation++;
+        this.#pending = undefined;
+        this.#busy.value = false;
+        this.#dragEnd?.();
+        for (const card of this.#cards.values()) {
+            card.dispose();
+            card.remove();
+        }
+        this.#cards.clear();
+        super.disconnectedCallback();
+    }
+    render() {
+        this.#registryVersion.value;
+        this.#widgets.value;
+        this.#maximized.value;
+        return html `<section class="aster-dashboard" aria-label=${this.#label.value}>
+      <div class="aster-dashboard-status aster-sr-only" role="status" aria-live="polite">${this.#message.value}</div>
+      <div class="aster-dashboard-grid" role="list" aria-label=${`${this.#label.value} widgets`} tabindex="-1" aria-busy=${String(this.#busy.value)}></div>
+      ${this.#widgets.value.length ? html `` : html `<p class="aster-dashboard-empty">No widgets yet. Add a widget to build your dashboard.</p>`}
+    </section>`;
+    }
+    updated() {
+        const grid = this.querySelector(".aster-dashboard-grid");
+        const widgets = this.#widgets.peek();
+        const focused = document.activeElement;
+        for (const [id, card] of this.#cards) {
+            const spec = widgets.find(widget => widget.id === id);
+            if (!spec || card.dataset.type !== spec.type) {
+                card.dispose();
+                card.remove();
+                this.#cards.delete(id);
+            }
+        }
+        let cursor = grid.firstElementChild;
+        for (const widget of widgets) {
+            let card = this.#cards.get(widget.id);
+            if (!card) {
+                card = new DashboardPortlet();
+                card.dataset.type = widget.type;
+                card.initialize(widget, scopeOf(this)?.child() ?? new PageScope(), {
+                    move: by => this.move(widget.id, this.#index(widget.id) + by),
+                    resize: (w, h) => {
+                        const current = this.#widgets.peek()[this.#index(widget.id)];
+                        this.resize(widget.id, limit(current.width + w), limit(current.height + h));
+                    },
+                    maximize: () => this.maximize(this.#maximized.peek() === widget.id ? null : widget.id),
+                    remove: () => { void this.removeWidget(widget.id); },
+                    retry: () => { void this.retry(widget.id); },
+                    drag: event => this.#drag(widget.id, event),
+                    edges: () => ({ first: this.#index(widget.id) === 0, last: this.#index(widget.id) === this.#widgets.peek().length - 1 }),
+                });
+                this.#cards.set(widget.id, card);
+            }
+            card.update(widget, this.#maximized.peek() === widget.id, this.#busy.peek());
+            if (card !== cursor)
+                grid.insertBefore(card, cursor);
+            cursor = card.nextElementSibling;
+            void card.mount(this.#types.get(widget.type));
+        }
+        if (focused?.isConnected && grid.contains(focused) && document.activeElement !== focused)
+            focused.focus({ preventScroll: true });
+        const focus = this.#focusAfter;
+        if (focus !== undefined && !this.#busy.peek()) {
+            this.#focusAfter = undefined;
+            const generation = this.#generation;
+            requestAnimationFrame(() => {
+                if (generation !== this.#generation || !this.isConnected || document.querySelector("dialog:modal"))
+                    return;
+                if (focus === null)
+                    grid.focus({ preventScroll: true });
+                else
+                    this.#cards.get(focus)?.focusActions();
+            });
+        }
+    }
+    #guard(key, ids, apply) {
+        if (this.#pending)
+            return this.#pending.key === key ? this.#pending.task : Promise.resolve(false);
+        const generation = this.#generation;
+        this.#busy.value = true;
+        const task = Promise.resolve().then(async () => {
+            for (const id of ids) {
+                if (!(await this.#cards.get(id)?.allowRemove() ?? true))
+                    return false;
+                if (generation !== this.#generation || !this.isConnected)
+                    return false;
+            }
+            if (generation !== this.#generation || !this.isConnected)
+                return false;
+            apply();
+            return true;
+        }).catch((error) => {
+            if (generation === this.#generation) {
+                this.#message.value = "Layout change failed. Your widgets remain open.";
+                this.emit("layouterror", error);
+            }
+            return false;
+        }).finally(() => {
+            if (generation === this.#generation) {
+                this.#pending = undefined;
+                this.#busy.value = false;
+            }
+        });
+        this.#pending = { key, task };
+        return task;
+    }
+    #commit(widgets) {
+        if (!widgets.some(widget => widget.id === this.#maximized.peek()))
+            this.#maximized.value = null;
+        this.#widgets.value = Object.freeze([...widgets]);
+        this.emit("layoutchange", this.snapshot());
+    }
+    #index(id) {
+        const index = this.#widgets.peek().findIndex(widget => widget.id === id);
+        if (index < 0)
+            throw new Error(`Unknown dashboard widget: ${id}`);
+        return index;
+    }
+    #assertIdle() { if (this.#busy.peek())
+        throw new Error("A dashboard layout change is pending"); }
+    #drag(id, event) {
+        if (event.button !== 0 || this.#busy.peek() || this.#maximized.peek())
+            return;
+        const handle = event.currentTarget;
+        this.#dragEnd?.();
+        let target;
+        handle.setPointerCapture(event.pointerId);
+        event.preventDefault();
+        handle.focus({ preventScroll: true });
+        const clear = () => { if (target)
+            delete target.dataset.drop; };
+        const move = (e) => {
+            clear();
+            const hit = document.elementFromPoint(e.clientX, e.clientY)?.closest("aster-dashboard-widget");
+            target = [...this.#cards.values()].find(card => card === hit && card.dataset.widget !== id);
+            if (target)
+                target.dataset.drop = "true";
+        };
+        const finish = () => {
+            clear();
+            handle.removeEventListener("pointermove", move);
+            handle.removeEventListener("pointerup", drop);
+            handle.removeEventListener("pointercancel", cancel);
+            handle.removeEventListener("keydown", escape);
+            this.#dragEnd = undefined;
+        };
+        const drop = () => { const to = target?.dataset.widget; finish(); if (to)
+            this.move(id, this.#index(to)); };
+        const cancel = () => { finish(); };
+        const escape = (e) => { if (e.key === "Escape") {
+            e.preventDefault();
+            e.stopPropagation();
+            cancel();
+        } };
+        handle.addEventListener("pointermove", move);
+        handle.addEventListener("pointerup", drop);
+        handle.addEventListener("pointercancel", cancel);
+        handle.addEventListener("keydown", escape);
+        this.#dragEnd = cancel;
+    }
+}
+function limit(value) { return Math.max(1, Math.min(3, value)); }
+define("aster-dashboard", Dashboard);

package/dist/dashboard/layout.d.ts

@@ -0,0 +1,19 @@
+export type DashboardValue = null | boolean | number | string | readonly DashboardValue[] | {
+    readonly [key: string]: DashboardValue;
+};
+export type DashboardConfig = Readonly<Record<string, DashboardValue>>;
+export type DashboardSize = 1 | 2 | 3;
+export interface DashboardWidget {
+    readonly id: string;
+    readonly type: string;
+    readonly title: string;
+    readonly width: DashboardSize;
+    readonly height: DashboardSize;
+    readonly config?: DashboardConfig;
+}
+export interface DashboardSnapshot {
+    readonly version: 1;
+    readonly widgets: readonly DashboardWidget[];
+}
+/** Validate and copy before a layout operation acquires or releases content. */
+export declare function copyLayout(widgets: readonly DashboardWidget[]): readonly DashboardWidget[];

package/dist/dashboard/layout.js

@@ -0,0 +1,48 @@
+/** Validate and copy before a layout operation acquires or releases content. */
+export function copyLayout(widgets) {
+    if (!Array.isArray(widgets))
+        throw new TypeError("Dashboard widgets must be an array");
+    const ids = new Set();
+    return Object.freeze(Array.from(widgets, widget => {
+        if (!widget || typeof widget.id !== "string" || !widget.id.trim() || ids.has(widget.id))
+            throw new TypeError("Dashboard widget IDs must be unique and non-empty");
+        ids.add(widget.id);
+        if (typeof widget.type !== "string" || !widget.type.trim() || typeof widget.title !== "string" || !widget.title.trim())
+            throw new TypeError("Widgets require a type and title");
+        if (![1, 2, 3].includes(widget.width) || ![1, 2, 3].includes(widget.height))
+            throw new TypeError("Widget sizes must be 1, 2 or 3");
+        const config = widget.config === undefined ? {} : widget.config;
+        if (!config || Array.isArray(config) || typeof config !== "object")
+            throw new TypeError("Widget configuration must be a JSON object");
+        return Object.freeze({ id: widget.id, type: widget.type, title: widget.title, width: widget.width, height: widget.height, config: copyValue(config, new Set(), 0) });
+    }));
+}
+function copyValue(value, seen, depth) {
+    if (depth > 32)
+        throw new TypeError("Widget configuration is too deeply nested");
+    switch (typeof value) {
+        case "string":
+        case "boolean": return value;
+        case "number":
+            if (Number.isFinite(value))
+                return value;
+            break;
+        case "object": {
+            if (value === null)
+                return null;
+            if (Object.getOwnPropertySymbols(value).length)
+                throw new TypeError("Widget configuration cannot contain symbol keys");
+            if (Array.isArray(value) && Object.keys(value).length !== value.length)
+                throw new TypeError("Widget arrays cannot have holes or extra properties");
+            if (seen.has(value))
+                throw new TypeError("Widget configuration cannot contain cycles");
+            if (!Array.isArray(value) && Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null)
+                break;
+            seen.add(value);
+            const copied = Array.isArray(value) ? Array.from(value, item => copyValue(item, seen, depth + 1)) : Object.fromEntries(Object.entries(value).map(([key, item]) => [key, copyValue(item, seen, depth + 1)]));
+            seen.delete(value);
+            return Object.freeze(copied);
+        }
+    }
+    throw new TypeError("Widget configuration must contain only finite JSON values");
+}

package/dist/dashboard/widget.d.ts

@@ -0,0 +1,42 @@
+import { type ReadonlySignal } from "@preact/signals-core";
+import type { PageScope } from "@getaster/data";
+import { AsterElement, type View } from "../base/element.ts";
+import type { DashboardConfig, DashboardWidget } from "./layout.ts";
+export interface DashboardMount {
+    readonly id: string;
+    readonly scope: PageScope;
+    readonly config: ReadonlySignal<DashboardConfig>;
+    readonly signal: AbortSignal;
+}
+export interface DashboardSession {
+    render(): View;
+    dispose(): void;
+    beforeRemove?(): boolean | Promise<boolean>;
+}
+export interface DashboardWidgetType {
+    create(context: DashboardMount): DashboardSession | Promise<DashboardSession>;
+}
+interface Actions {
+    move(by: number): void;
+    resize(width: number, height: number): void;
+    maximize(): void;
+    remove(): void;
+    retry(): void;
+    drag(event: PointerEvent): void;
+    edges(): {
+        first: boolean;
+        last: boolean;
+    };
+}
+/** The dashboard owns sessions; native DOM moves only reconnect the view. */
+export declare class DashboardPortlet extends AsterElement {
+    #private;
+    initialize(widget: DashboardWidget, scope: PageScope, actions: Actions): void;
+    update(widget: DashboardWidget, maximized: boolean, busy: boolean): void;
+    mount(type: DashboardWidgetType | undefined): Promise<void>;
+    allowRemove(): Promise<boolean>;
+    dispose(): void;
+    focusActions(): void;
+    protected render(): View;
+}
+export {};