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

package/dist/composition/composite.js

@@ -0,0 +1,409 @@
+import { planCommands } from "./commands.js";
+import { computed, effect, signal, untracked } from "@preact/signals-core";
+import { render, nothing } from "lit-html";
+import { Command, Lifetime, PageScope, SessionActivity, command } from "@getaster/data";
+import { provideScope } from "../base/element.js";
+import { CompositeError, defineComposite, deriveComposite, located, record } from "./definition.js";
+import { checkContract } from "./registry.js";
+function isSignal(value) {
+    return !!value && typeof value === "object" && "peek" in value && "subscribe" in value;
+}
+/** A logical owner with a stable scope and independently activated named views. */
+export class Composite {
+    registry;
+    element = document.createElement("div");
+    lifetime = new Lifetime();
+    scope;
+    activity;
+    commands;
+    children;
+    model;
+    definition;
+    #refs = new Map();
+    #sources;
+    constructor(definition, registry, ...args) {
+        this.registry = registry;
+        const options = args[0] ?? {};
+        this.#sources = options.sources ?? {};
+        this.activity = this.lifetime.own(new SessionActivity(options.activity ? { parent: options.activity, inactive: "continue" } : {}));
+        this.scope = new PageScope(options.parentScope, options.ctx ? { ctx: options.ctx } : {});
+        this.element.className = "aster-composite";
+        this.element.tabIndex = -1;
+        provideScope(this.element, this.scope);
+        try {
+            if (registry.inputs)
+                checkContract(options.inputs ?? {}, registry.inputs, "inputs");
+            this.definition = options.overrides ? deriveComposite(definition, options.overrides) : defineComposite(definition);
+            definition = this.definition;
+            this.element.dataset.composite = definition.name;
+            for (const [key, value] of Object.entries(options.inputs ?? {}))
+                this.#refs.set(`inputs.${key}`, value);
+            // Validate registration names before constructing the model or starting data work.
+            for (const [key, child] of Object.entries(definition.children))
+                this.#component(child.type, `definition.children.${key}.type`);
+            let type;
+            try {
+                type = registry.model(definition.model.type);
+            }
+            catch (error) {
+                throw new CompositeError("definition.model.type", String(error));
+            }
+            const inputs = this.#values(definition.model.inputs ?? {}, "definition.model.inputs");
+            checkContract(inputs, type.inputs, "definition.model.inputs");
+            const model = untracked(() => type.create(inputs, this.lifetime, this.activity));
+            checkContract(model.values, type.exports, "definition.model.exports");
+            this.model = model.values;
+            for (const [key, value] of Object.entries(model.values))
+                this.#refs.set(`model.${key}`, value);
+            for (const [key, value] of Object.entries(model.publications ?? {}))
+                this.#refs.set(`model.publications.${key}`, value);
+            for (const [key, value] of Object.entries(model.commands ?? {}))
+                this.#refs.set(`model.commands.${key}`, value);
+            for (const [key, spec] of Object.entries(definition.publish ?? {})) {
+                const path = `definition.publish.${key}`;
+                const publication = this.#ref(spec.ref, path);
+                if (!publication || !publication.values || !Object.values(publication.values).every(isSignal))
+                    throw new CompositeError(path, "expected a publication");
+                this.lifetime.defer(this.scope.publish(key, publication));
+            }
+            const commands = Object.create(null);
+            const plan = planCommands(definition.commands ?? {}, reference => this.#refs.get(reference) instanceof Command);
+            if (plan.errors[0])
+                throw new CompositeError(plan.errors[0].path, plan.errors[0].message);
+            for (const key of plan.order) {
+                const spec = definition.commands[key];
+                const path = `definition.commands.${key}`;
+                const base = this.#ref(spec.use, `${path}.use`);
+                if (!(base instanceof Command))
+                    throw new CompositeError(path, "expected an exported Command");
+                const rule = spec.enabledWhen;
+                if (rule) {
+                    const errors = this.scope.checkRule(rule);
+                    if (errors.length)
+                        throw new CompositeError(`${path}.enabledWhen`, errors.join("; "));
+                }
+                const state = rule ? this.scope.state(`commands.${key}`, { enabled: { when: rule, ...(spec.reason ? { reason: spec.reason } : {}) } }, { availability: true }) : undefined;
+                const allowed = computed(() => state?.value.enabled ?? true);
+                const action = this.lifetime.own(command({
+                    label: base.label,
+                    enabled: () => base.enabled.value && allowed.value,
+                    reason: () => base.reason.value ?? spec.reason ?? "The page rule is not satisfied.",
+                    run: () => base.execute(),
+                }));
+                commands[key] = action;
+                this.#refs.set(`commands.${key}`, action);
+            }
+            this.commands = Object.freeze(Object.fromEntries(Object.keys(definition.commands ?? {}).map(key => [key, commands[key]])));
+            const children = Object.create(null);
+            // Resolve every public binding before starting lazy imports.
+            for (const [key, spec] of Object.entries(definition.children)) {
+                const path = `definition.children.${key}`;
+                const entry = this.#component(spec.type, `${path}.type`);
+                const props = this.#props(spec.props ?? {}, `${path}.props`);
+                if (spec.enabled !== false)
+                    checkContract(this.#readProps(props), entry.props, `${path}.props`);
+                children[key] = new Child(key, spec, entry, props, this);
+            }
+            this.children = children;
+            const activations = [];
+            this.#activation(definition.layout, children, () => true, "definition.layout", activations);
+            if (options.placement) {
+                const placed = new Set();
+                const template = options.placement(key => {
+                    if (key === undefined) {
+                        for (const name of Object.keys(children)) {
+                            if (placed.has(name))
+                                throw new CompositeError("placement", `duplicate placement '${name}'`);
+                            placed.add(name);
+                        }
+                        return this.#layout(definition.layout, children);
+                    }
+                    if (!Object.hasOwn(children, key))
+                        throw new CompositeError("placement", `unknown child '${key}'`);
+                    if (placed.has(key))
+                        throw new CompositeError("placement", `duplicate placement '${key}'`);
+                    placed.add(key);
+                    return children[key].element;
+                });
+                render(template, this.element);
+                this.lifetime.defer(() => render(nothing, this.element));
+                for (const key of Object.keys(children))
+                    if (!placed.has(key) || !this.element.contains(children[key].element))
+                        throw new CompositeError("placement", `child '${key}' has no placement`);
+            }
+            else
+                this.element.append(this.#layout(definition.layout, children));
+            for (const activate of activations)
+                activate();
+        }
+        catch (error) {
+            this.lifetime.dispose();
+            throw located(error, this.#sources);
+        }
+    }
+    mount(target) {
+        if (this.lifetime.disposed)
+            throw new Error("Composite is disposed");
+        target.append(this.element);
+        return this;
+    }
+    /** The caller performs close/draft guards before unconditional teardown. */
+    dispose() { try {
+        this.lifetime.dispose();
+    }
+    finally {
+        this.element.remove();
+    } }
+    #component(type, path) {
+        try {
+            return this.registry.component(type);
+        }
+        catch (error) {
+            throw new CompositeError(path, String(error));
+        }
+    }
+    #ref(path, at) {
+        if (!this.#refs.has(path))
+            throw new CompositeError(at, `unknown public reference '${path}'`);
+        return this.#refs.get(path);
+    }
+    #value(value, path, property = "") {
+        if (value === null || typeof value !== "object")
+            return value;
+        if (Array.isArray(value))
+            return value.map((item, i) => this.#value(item, `${path}.${i}`, property));
+        const obj = record(value, path);
+        for (const kind of ["ref", "bind", "renderer"])
+            if (Object.hasOwn(obj, kind)) {
+                if (Object.keys(obj).length !== 1 || typeof obj[kind] !== "string")
+                    throw new CompositeError(path, `invalid ${kind} node`);
+                if (kind === "renderer") {
+                    let renderer;
+                    try {
+                        renderer = this.registry.renderer(obj[kind]);
+                    }
+                    catch (error) {
+                        throw new CompositeError(path, String(error));
+                    }
+                    if (!renderer.accepts(property))
+                        throw new CompositeError(path, `renderer is not registered for '${property}'`);
+                    return renderer.render;
+                }
+                const result = this.#ref(obj[kind], path);
+                if (kind === "bind") {
+                    if (!isSignal(result))
+                        throw new CompositeError(path, "bind requires a signal");
+                    return result.value;
+                }
+                return result;
+            }
+        return Object.fromEntries(Object.entries(obj).map(([key, item]) => [key, this.#value(item, `${path}.${key}`, property)]));
+    }
+    #values(values, path) {
+        return Object.fromEntries(Object.entries(values).map(([key, value]) => [key, this.#value(value, `${path}.${key}`, key)]));
+    }
+    #props(values, path) {
+        return computed(() => this.#values(values, path));
+    }
+    #readProps(props) { return props.value; }
+    #activation(spec, children, active, path, activations) {
+        if ("child" in spec) {
+            const child = children[spec.child];
+            activations.push(() => this.lifetime.defer(effect(() => {
+                const show = active();
+                untracked(() => child.activate(show));
+            })));
+            return;
+        }
+        switch (spec.type) {
+            case "stack":
+                spec.items.forEach((item, i) => this.#activation(item, children, active, `${path}.items.${i}`, activations));
+                break;
+            case "deck": {
+                const current = computed(() => this.#value(spec.active, `${path}.active`));
+                for (const [key, item] of Object.entries(spec.items))
+                    this.#activation(item, children, () => active() && current.value === key, `${path}.items.${key}`, activations);
+                break;
+            }
+            case "outlet": {
+                const current = computed(() => this.#value(spec.active, `${path}.active`));
+                this.#activation(spec.content, children, () => active() && current.value === true, `${path}.content`, activations);
+                break;
+            }
+        }
+    }
+    #layout(spec, children) {
+        if ("child" in spec)
+            return children[spec.child].element;
+        const node = document.createElement("div");
+        node.className = `aster-composite-${spec.type}`;
+        switch (spec.type) {
+            case "stack":
+                spec.items.forEach(item => node.append(this.#layout(item, children)));
+                break;
+            case "deck":
+                Object.values(spec.items).forEach(item => node.append(this.#layout(item, children)));
+                break;
+            case "outlet":
+                node.append(this.#layout(spec.content, children));
+                break;
+        }
+        return node;
+    }
+    report(error) { return located(error, this.#sources); }
+}
+/** Use either a compiled YAML definition or a JS definition as a registered child. */
+export function compositeComponent(definition, registry, inputs, sources) {
+    return {
+        props: inputs,
+        create: ({ props, scope, activity }) => {
+            const instance = new Composite(definition, registry, { inputs: props, parentScope: scope, ...(activity ? { activity } : {}), ...(sources ? { sources } : {}) });
+            return { element: instance.element, scope: instance.scope, setActive: active => instance.activity.setActive(active), dispose: () => instance.dispose() };
+        },
+    };
+}
+class Child {
+    key;
+    spec;
+    type;
+    props;
+    owner;
+    element = document.createElement("div");
+    #status = signal("idle");
+    #error = signal(undefined);
+    status = this.#status;
+    error = this.#error;
+    #lifetime;
+    #pending;
+    #session;
+    #generation = 0;
+    #activity;
+    constructor(key, spec, type, props, owner) {
+        this.key = key;
+        this.spec = spec;
+        this.type = type;
+        this.props = props;
+        this.owner = owner;
+        this.#activity = owner.lifetime.own(new SessionActivity({ parent: owner.activity, active: false }));
+        this.element.className = "aster-composite-child";
+        this.element.dataset.child = key;
+        this.element.hidden = true;
+        if (spec.enabled === false)
+            this.#status.value = "suppressed";
+        owner.lifetime.defer(() => { this.#reset(); this.#status.value = "disposed"; });
+    }
+    activate(active) {
+        if (this.spec.enabled === false)
+            return;
+        this.#activity.setActive(active);
+        this.#session?.setActive?.(active);
+        if (!active && this.element.contains(document.activeElement))
+            this.owner.element.focus();
+        this.element.hidden = !active;
+        this.element.inert = !active;
+        if (!active && this.spec.retain === false) {
+            this.#reset();
+            return;
+        }
+        if (active || this.spec.create !== "on-demand") {
+            if (this.#status.peek() === "idle")
+                void this.ensure().catch(() => { });
+        }
+    }
+    ensure() {
+        if (this.owner.lifetime.disposed)
+            return Promise.reject(new Error("Composite is disposed"));
+        if (this.spec.enabled === false)
+            return Promise.reject(new Error(`Child '${this.key}' is suppressed`));
+        if (this.#pending)
+            return this.#pending;
+        if (this.#session)
+            return Promise.resolve(this.#session.element);
+        const lifetime = this.#lifetime = new Lifetime();
+        const generation = ++this.#generation;
+        this.#status.value = "loading";
+        this.#error.value = undefined;
+        this.element.setAttribute("aria-busy", "true");
+        const status = document.createElement("p");
+        status.setAttribute("role", "status");
+        status.textContent = `Loading ${this.key}…`;
+        this.element.replaceChildren(status);
+        const pending = this.owner.registry.load(this.spec.type).then(async (create) => {
+            lifetime.signal.throwIfAborted();
+            const session = await create({ props: this.props.peek(), lifetime, scope: this.owner.scope, activity: this.#activity });
+            lifetime.defer(() => { try {
+                session.dispose?.();
+            }
+            finally {
+                session.element.remove();
+            } });
+            lifetime.signal.throwIfAborted();
+            if (generation !== this.#generation)
+                throw new Error("Stale child creation");
+            this.#session = session;
+            session.setActive?.(this.#activity.active.peek());
+            provideScope(session.element, session.scope ?? this.owner.scope);
+            if (this.type.apply) {
+                let initial = true;
+                lifetime.defer(effect(() => {
+                    try {
+                        const props = this.props.value;
+                        checkContract(props, this.type.props, `definition.children.${this.key}.props`);
+                        untracked(() => this.type.apply(session.element, props));
+                    }
+                    catch (error) {
+                        if (initial)
+                            throw error;
+                        queueMicrotask(() => this.#fail(error, generation, lifetime));
+                    }
+                }));
+                initial = false;
+            }
+            this.element.replaceChildren(session.element);
+            this.element.removeAttribute("aria-busy");
+            this.#status.value = "ready";
+            return session.element;
+        }).catch((error) => {
+            this.#fail(error, generation, lifetime);
+            throw error;
+        }).finally(() => { if (generation === this.#generation)
+            this.#pending = undefined; });
+        this.#pending = pending;
+        return pending;
+    }
+    #fail(error, generation, lifetime) {
+        if (generation !== this.#generation || this.owner.lifetime.disposed)
+            return;
+        try {
+            lifetime.dispose();
+        }
+        catch (cleanup) {
+            error = new AggregateError([error, cleanup], "Child failed and cleanup reported an error");
+        }
+        this.#session = undefined;
+        this.#status.value = "error";
+        const failure = this.owner.report(error instanceof CompositeError ? error : new CompositeError(`definition.children.${this.key}`, error instanceof Error ? error.message : String(error)));
+        this.#error.value = failure;
+        this.element.removeAttribute("aria-busy");
+        const message = document.createElement("p");
+        message.setAttribute("role", "status");
+        message.textContent = `Could not load ${this.key}. ${failure.message}`;
+        const retry = document.createElement("button");
+        retry.type = "button";
+        retry.className = "aster-button";
+        retry.textContent = `Retry ${this.key}`;
+        retry.addEventListener("click", () => void this.ensure().catch(() => { }), { signal: this.owner.lifetime.signal });
+        this.element.replaceChildren(message, retry);
+    }
+    #reset() {
+        ++this.#generation;
+        this.#lifetime?.dispose();
+        this.#lifetime = undefined;
+        this.#pending = undefined;
+        this.#session = undefined;
+        this.#status.value = "idle";
+        this.#error.value = undefined;
+        this.element.replaceChildren();
+        this.element.removeAttribute("aria-busy");
+    }
+}

package/dist/composition/contracts.d.ts

@@ -0,0 +1,63 @@
+import type { SessionActivity } from "@getaster/data";
+import type { ReadonlySignal } from "@preact/signals-core";
+import type { Lifetime, Publication } from "@getaster/data";
+import { type CompositeContract, type CompositeModel, type CompositeModelType, type CompositeProperty, type CompositeValues } from "./registry.ts";
+export interface CompositeType<T> extends CompositeProperty {
+    readonly validate: (value: unknown) => value is T;
+}
+export type CompositeTypes = Readonly<Record<string, CompositeType<unknown>>>;
+type TypeValue<T> = T extends CompositeType<infer V> ? V : unknown;
+export type CompositeContractValues<C extends CompositeContract> = {
+    readonly [K in keyof C as C[K] extends {
+        readonly optional: true;
+    } ? never : K]: TypeValue<C[K]>;
+} & {
+    readonly [K in keyof C as C[K] extends {
+        readonly optional: true;
+    } ? K : never]?: Exclude<TypeValue<C[K]>, undefined>;
+};
+declare function type<T>(description: string, validate: (value: unknown) => value is T, schema?: Readonly<Record<string, unknown>>): CompositeType<T>;
+/** Reusable runtime checks, inferred TS values and discoverable contract metadata. */
+export declare const compositeTypes: Readonly<{
+    string: CompositeType<string>;
+    boolean: CompositeType<boolean>;
+    number: CompositeType<number>;
+    positiveInteger: CompositeType<number>;
+    custom: typeof type;
+    refine<const C extends CompositeType<unknown>>(inner: C, description: string, accepts: (value: TypeValue<C>) => boolean, schema: Readonly<Record<string, unknown>>): C;
+    instance<T>(ctor: abstract new (...args: never[]) => T): CompositeType<T>;
+    optional<const C extends CompositeType<unknown>>(inner: C): Omit<C, "validate"> & CompositeType<TypeValue<C> | undefined> & {
+        readonly optional: true;
+    };
+    array<const C extends CompositeType<unknown>>(inner: C): CompositeType<readonly TypeValue<C>[]> & {
+        readonly item: C;
+    };
+    signal<const C extends CompositeType<unknown>>(inner: C): CompositeType<ReadonlySignal<TypeValue<C>>> & {
+        readonly signalValue: C;
+    };
+    publication<const C extends CompositeTypes>(fields: C): CompositeType<Publication>;
+    object<const C extends CompositeTypes>(fields: C): CompositeType<CompositeContractValues<C>> & {
+        readonly fields: C;
+    };
+}>;
+export interface TypedCompositeModel<I extends CompositeTypes, E extends CompositeTypes, C extends CompositeTypes = {}, P extends CompositeTypes = {}> extends CompositeModelType {
+    readonly inputs: I;
+    readonly exports: E;
+    readonly commands: C;
+    readonly publications: P;
+    /** Validate and narrow public exports without an application-side cast. */
+    read(values: CompositeValues): CompositeContractValues<E>;
+}
+/** One contract drives runtime validation and contextual typing of model code. */
+export declare function defineCompositeModel<const I extends CompositeTypes, const E extends CompositeTypes, const C extends CompositeTypes = {}, const P extends CompositeTypes = {}>(spec: {
+    readonly inputs: I;
+    readonly exports: E;
+    readonly commands?: C;
+    readonly publications?: P;
+    readonly create: (inputs: CompositeContractValues<I>, lifetime: Lifetime, activity?: SessionActivity) => Omit<CompositeModel, "values"> & {
+        readonly values: CompositeContractValues<E>;
+    };
+}): TypedCompositeModel<I, E, C, P>;
+/** JSON-compatible metadata; identity and signal checks still require the runtime. */
+export declare function describeCompositeContract(contract: CompositeContract): Readonly<Record<string, unknown>>;
+export {};

package/dist/composition/contracts.js

@@ -0,0 +1,97 @@
+import { Command } from "@getaster/data";
+import { checkContract, snapshotContract } from "./registry.js";
+function type(description, validate, schema = {}) {
+    const metadata = structuredClone(schema);
+    function freeze(value) {
+        if (!value || typeof value !== "object")
+            return;
+        Object.values(value).forEach(freeze);
+        Object.freeze(value);
+    }
+    freeze(metadata);
+    return Object.freeze({ description, validate, schema: metadata });
+}
+/** Reusable runtime checks, inferred TS values and discoverable contract metadata. */
+export const compositeTypes = Object.freeze({
+    string: type("string", (value) => typeof value === "string", { type: "string" }),
+    boolean: type("boolean", (value) => typeof value === "boolean", { type: "boolean" }),
+    number: type("finite number", (value) => typeof value === "number" && Number.isFinite(value), { type: "number" }),
+    positiveInteger: type("positive safe integer", (value) => typeof value === "number" && Number.isSafeInteger(value) && value > 0, { type: "integer", minimum: 1, maximum: Number.MAX_SAFE_INTEGER }),
+    custom: type,
+    refine(inner, description, accepts, schema) {
+        const validate = inner.validate;
+        return Object.freeze({ ...inner, ...type(description, (value) => validate(value) && accepts(value), { allOf: [inner.schema ?? {}, schema] }) });
+    },
+    instance(ctor) {
+        const name = Object.is(ctor, Command) ? "Command" : ctor.name;
+        const bases = [];
+        for (let base = Object.getPrototypeOf(ctor); base && base !== Function.prototype; base = Object.getPrototypeOf(base)) {
+            if (base.name)
+                bases.push(Object.is(base, Command) ? "Command" : base.name);
+        }
+        return type(name, (value) => value instanceof ctor, { asterType: name, asterBases: bases });
+    },
+    optional(inner) {
+        return Object.freeze({ ...inner, schema: Object.freeze({ anyOf: Object.freeze([inner.schema ?? {}, Object.freeze({ asterType: "undefined" })]) }), optional: true, validate: (value) => value === undefined || inner.validate(value) });
+    },
+    array(inner) {
+        return Object.freeze({ ...type(`array of ${inner.description}`, (value) => Array.isArray(value) && value.every(item => inner.validate(item)), { type: "array", items: inner.schema ?? {} }), item: inner });
+    },
+    signal(inner) {
+        return Object.freeze({ ...type(`signal of ${inner.description}`, (value) => {
+                if (!value || typeof value !== "object" || !("peek" in value) || typeof value.peek !== "function" || !("subscribe" in value) || typeof value.subscribe !== "function")
+                    return false;
+                return inner.validate(value.peek());
+            }, { asterType: "signal", value: inner.schema ?? {} }), signalValue: inner });
+    },
+    publication(fields) {
+        const members = snapshotContract(fields);
+        return type("publication", (value) => {
+            if (!value || typeof value !== "object" || !("values" in value) || !value.values || typeof value.values !== "object")
+                return false;
+            const values = value.values;
+            return Object.entries(members).every(([key, spec]) => compositeTypes.signal(spec).validate(values[key]));
+        }, { asterType: "publication", properties: Object.fromEntries(Object.entries(members).map(([key, spec]) => [key, spec.schema ?? {}])) });
+    },
+    object(fields) {
+        const members = Object.freeze(Object.fromEntries(Object.entries(fields).map(([key, spec]) => [key, Object.freeze({ ...spec })])));
+        const required = Object.keys(members).filter(key => !members[key].optional);
+        return Object.freeze({ ...type("object", (value) => {
+                if (!value || typeof value !== "object" || Array.isArray(value) || ![null, Object.prototype].includes(Object.getPrototypeOf(value)))
+                    return false;
+                const values = value;
+                return Object.keys(values).every(key => Object.hasOwn(members, key)) && Object.entries(members).every(([key, spec]) => spec.validate(values[key]));
+            }, { type: "object", properties: Object.fromEntries(Object.entries(members).map(([key, spec]) => [key, spec.schema ?? {}])), required, additionalProperties: false }), fields: members });
+    },
+});
+/** One contract drives runtime validation and contextual typing of model code. */
+export function defineCompositeModel(spec) {
+    const inputsContract = snapshotContract(spec.inputs);
+    const exports = snapshotContract(spec.exports);
+    const commands = snapshotContract(spec.commands ?? {});
+    const publications = snapshotContract(spec.publications ?? {});
+    const create = spec.create;
+    return {
+        inputs: inputsContract,
+        exports,
+        commands,
+        publications,
+        create: (inputs, lifetime, activity) => {
+            checkContract(inputs, inputsContract, "model.inputs");
+            const model = create(inputs, lifetime, activity);
+            if (spec.commands)
+                checkContract(model.commands ?? {}, commands, "model.commands");
+            if (spec.publications)
+                checkContract(model.publications ?? {}, publications, "model.publications");
+            return model;
+        },
+        read: values => {
+            checkContract(values, exports, "model.exports");
+            return values;
+        },
+    };
+}
+/** JSON-compatible metadata; identity and signal checks still require the runtime. */
+export function describeCompositeContract(contract) {
+    return Object.fromEntries(Object.entries(contract).map(([key, spec]) => [key, { description: spec.description ?? "Custom validator", optional: spec.optional ?? false, schema: spec.schema ?? {} }]));
+}

package/dist/composition/definition.d.ts

@@ -0,0 +1,94 @@
+import type { Condition } from "@getaster/data";
+export type CompositeValue = null | boolean | number | string | readonly CompositeValue[] | {
+    readonly [key: string]: CompositeValue;
+};
+export interface CompositeChild {
+    readonly type: string;
+    readonly props?: Readonly<Record<string, CompositeValue>>;
+    readonly create?: "eager" | "on-demand";
+    readonly retain?: boolean;
+    /** Static suppression; does not construct or load this child. */
+    readonly enabled?: boolean;
+}
+export interface CompositeChildCustomization {
+    readonly props?: readonly string[];
+    readonly replace?: readonly string[];
+    readonly optional?: boolean;
+    readonly lifecycle?: boolean;
+}
+export interface CompositeCustomization {
+    readonly children?: Readonly<Record<string, CompositeChildCustomization>>;
+    readonly modelInputs?: readonly string[];
+    readonly layout?: boolean;
+}
+export type CompositeLayout = {
+    readonly child: string;
+} | {
+    readonly type: "stack";
+    readonly items: readonly CompositeLayout[];
+} | {
+    readonly type: "deck";
+    readonly active: CompositeValue;
+    readonly items: Readonly<Record<string, CompositeLayout>>;
+} | {
+    readonly type: "outlet";
+    readonly active: CompositeValue;
+    readonly content: CompositeLayout;
+};
+export interface CompositeDefinition {
+    readonly version: 1;
+    readonly name: string;
+    readonly model: {
+        readonly type: string;
+        readonly inputs?: Readonly<Record<string, CompositeValue>>;
+    };
+    readonly publish?: Readonly<Record<string, {
+        readonly ref: string;
+    }>>;
+    readonly commands?: Readonly<Record<string, {
+        readonly use: string;
+        readonly enabledWhen?: Condition;
+        readonly reason?: string;
+    }>>;
+    readonly children: Readonly<Record<string, CompositeChild>>;
+    readonly layout: CompositeLayout;
+    readonly customize?: CompositeCustomization;
+}
+export type CompositeOverrides<D extends CompositeDefinition = CompositeDefinition> = {
+    readonly name?: string;
+    readonly modelInputs?: Readonly<Partial<Record<keyof NonNullable<D["model"]["inputs"]>, CompositeValue>>>;
+    readonly children?: {
+        readonly [K in keyof D["children"]]?: {
+            readonly type?: string;
+            readonly props?: Readonly<Partial<Record<keyof NonNullable<D["children"][K]["props"]>, CompositeValue>>>;
+            readonly enabled?: boolean;
+            readonly create?: "eager" | "on-demand";
+            readonly retain?: boolean;
+        };
+    };
+    readonly layout?: CompositeLayout;
+};
+export type CompositeVariant<D extends CompositeDefinition> = Omit<CompositeDefinition, "children"> & {
+    readonly children: {
+        readonly [K in keyof D["children"]]: CompositeChild;
+    };
+};
+export interface CompositeLocation {
+    readonly file: string;
+    readonly line: number;
+    readonly column: number;
+}
+export type CompositeSources = Readonly<Record<string, CompositeLocation>>;
+export declare class CompositeError extends Error {
+    readonly path: string;
+    constructor(path: string, message: string);
+}
+export declare function located(error: unknown, sources?: CompositeSources): Error;
+export declare function record(value: unknown, path: string): Record<string, unknown>;
+export declare function keys(value: Record<string, unknown>, allowed: readonly string[], path: string): void;
+export declare function name(value: unknown, path: string): asserts value is string;
+/** Validate the JSON-compatible subset shared by YAML and JavaScript definitions. */
+export declare function defineComposite<const D extends CompositeDefinition>(value: D): D;
+export declare function defineComposite(value: unknown): CompositeDefinition;
+/** Immutable public customization: base → derived definition → instance overrides. */
+export declare function deriveComposite<D extends CompositeDefinition>(base: D, overrides: CompositeOverrides<NoInfer<D>>): CompositeVariant<D>;