@threadlabs/looma 0.30.2 → 0.30.3

package/vue/props.d.ts

@@ -0,0 +1,272 @@
+type TypeNode = {
+    readonly kind: "terminal";
+    readonly name: string;
+} | {
+    readonly kind: "separated-list";
+    readonly item: TypeNode;
+    readonly separator: "space" | "comma";
+} | {
+    readonly kind: "keyword";
+    readonly value: string;
+} | {
+    readonly kind: "union";
+    readonly members: readonly TypeNode[];
+} | {
+    readonly kind: "constrained";
+    readonly base: TypeNode;
+    readonly values?: readonly (string | number | boolean)[];
+    readonly min?: number | string;
+    readonly max?: number | string;
+    readonly minLength?: number;
+    readonly maxLength?: number;
+    readonly pattern?: string;
+} | {
+    readonly kind: "list";
+    readonly item: TypeNode;
+} | {
+    readonly kind: "record";
+    readonly value: TypeNode;
+} | {
+    readonly kind: "object";
+    readonly fields: readonly {
+        readonly name: string;
+        readonly type: TypeNode;
+        readonly optional: boolean;
+    }[];
+    readonly open: boolean;
+};
+type Parsed = {
+    readonly ok: true;
+    readonly value: unknown;
+} | {
+    readonly ok: false;
+    readonly issues: readonly string[];
+};
+declare function parse(value: unknown, node: TypeNode, path: string): Parsed;
+/** Return the actual selected destination, without a validation fallback. */
+export declare function selectedBindingNode(selector: unknown, options: readonly {
+    readonly value: string | number | boolean;
+    readonly type: TypeNode;
+}[]): TypeNode | null;
+export declare function selectedPropNode(selector: unknown, options: readonly {
+    readonly value: string | number | boolean;
+    readonly type: TypeNode;
+}[]): TypeNode;
+export declare function checkedProp<T>(value: unknown, type: TypeNode, required: true, name: string, accepted?: Record<string, unknown>, inputAccepted?: Record<string, boolean>, htmlBoolean?: boolean): T;
+export declare function checkedProp<T>(value: unknown, type: TypeNode, required: false, name: string, accepted?: Record<string, unknown>, inputAccepted?: Record<string, boolean>, htmlBoolean?: boolean): T | null;
+export declare function checkPropInput(value: unknown, type: TypeNode, htmlBoolean?: boolean, optional?: boolean): Parsed;
+type ValidityReason = "valueMissing" | "typeMismatch" | "patternMismatch" | "tooLong" | "tooShort" | "rangeUnderflow" | "rangeOverflow" | "stepMismatch" | "badInput" | "customError" | "schemaMismatch" | "untrustedValue";
+type ValidityError = {
+    readonly reason: ValidityReason;
+    readonly message: string;
+    readonly path?: string;
+};
+type ValidatedProp = {
+    readonly type: TypeNode | {
+        readonly kind: "selected";
+        readonly from: string;
+        readonly options: readonly {
+            readonly value: string | number | boolean;
+            readonly type: TypeNode;
+        }[];
+    };
+    readonly required: boolean;
+    readonly values?: readonly (string | number | boolean)[];
+    readonly select?: {
+        readonly from: string;
+        readonly options: readonly {
+            readonly value: string | number | boolean;
+            readonly type: TypeNode;
+        }[];
+    };
+    readonly min?: number | string;
+    readonly max?: number | string;
+    readonly minLength?: number;
+    readonly maxLength?: number;
+    readonly pattern?: string;
+};
+type PropValidityBinding = {
+    readonly contract: {
+        readonly props: Readonly<Record<string, ValidatedProp>>;
+    };
+    readonly values: Readonly<Record<string, unknown>>;
+};
+export declare function propValidityState(binding: PropValidityBinding, name: string): Readonly<{
+    errors: readonly ValidityError[];
+    valid: boolean;
+}>;
+export declare const vPropValidity: {
+    mounted(el: Element, binding: {
+        value: PropValidityBinding;
+    }): void;
+    updated(el: Element, binding: {
+        value: PropValidityBinding;
+    }): void;
+    unmounted(el: Element): void;
+};
+/** Framework-neutral lifecycle entry points for a converted component root. */
+export declare function mountPropValidity(el: Element, value: PropValidityBinding): () => void;
+export declare function updatePropValidity(el: Element, value: PropValidityBinding): void;
+/** Controller writes use immediate destination checks, including declared nested paths. */
+export declare function acceptsControllerWrite(value: unknown, type: TypeNode | undefined, keys: readonly string[]): boolean;
+/** The public failure a template may read; stacks and producer capabilities stay with their owner. */
+export interface InputFailure {
+    readonly name: string;
+    readonly message: string;
+}
+/** Availability is independent of the declared value's type, truthiness and input ownership. */
+export interface InputStatus {
+    readonly ready: boolean;
+    readonly pending: boolean;
+    readonly error: InputFailure | null;
+    readonly stale: boolean;
+}
+export declare const READY_INPUT: InputStatus;
+export declare const UNRESOLVED_INPUT: InputStatus;
+/** A draft owns its records/lists; native and opaque objects retain their platform identity. */
+export declare function copyStateSeed<T>(value: T, seen?: WeakMap<object, object>): T;
+/** Public error identity is its name/message, not the producer's object allocation. */
+export declare function sameInputStatus(left: InputStatus | undefined, right: InputStatus | undefined): boolean;
+/** Only synchronous reads made by this evaluation contribute prerequisites. */
+export declare function observingInputs(): boolean;
+/** Validation can examine reference paths without declaring them evaluated prerequisites. */
+export declare function withoutInputObservation<T>(run: () => T): T;
+export declare function observeInputStatus(status: InputStatus): void;
+/** Compiler adapters wrap declaration reads; ordinary application values keep their types. */
+export declare function inputRead<T>(value: T, status: InputStatus): T;
+/** Native expression evaluation and framework computeds share status composition, not reactivity. */
+export declare function evaluateInput<T>(compute: () => T, previous?: InputStatus, invalid?: unknown): {
+    readonly value: T;
+    readonly status: InputStatus;
+};
+/** A fallback handles absence; only the branch supplying the result contributes availability. */
+export declare function inputDefault<T, F>(read: () => T, fallback: () => F, absent?: unknown): T | F;
+/** The adapter supplies its own memo/computed primitive; acceptance runs only for available data. */
+export declare function inputComputed<T>(compute: () => T, make: <V>(read: () => V) => {
+    get(): V;
+}, accept?: (value: T) => T, initialStatus?: InputStatus): {
+    get(): T | null;
+    readonly value: T | null;
+    status(): InputStatus;
+};
+/** Project only the status a template may observe, retaining no mutable producer-owned object. */
+export declare function publicInputStatus(status: InputStatus): InputStatus;
+/** An await group consumes a status, never a Promise or an instruction to start a producer. */
+export declare function readInputStatus(scope: {
+    get(name: string): unknown;
+    inputStatus?(name: string): InputStatus;
+}, name: string, handlesError: boolean): InputStatus;
+export declare function requireInputStatus(status: InputStatus, handlesError: boolean): InputStatus;
+/** A source proposes a value and availability; the renderer retains typed-value acceptance. */
+export interface InputSnapshot<T = unknown> {
+    readonly value?: T;
+    readonly status: InputStatus;
+}
+/** A synchronous read and the availability of the declarations it actually evaluated. */
+export type InputEvaluation<T> = {
+    readonly status: InputStatus;
+} & ({
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly error: unknown;
+});
+export interface InputSource<T = unknown> {
+    /** The accepted component value, which can differ from a refused source result. */
+    current(): InputSnapshot<T>;
+    /** False when a caller owns this input, the source ended, or normal type acceptance refused it. */
+    publish(snapshot: InputSnapshot<T>): boolean;
+    /** Ends this source's write capability; deactivation alone need not release a retained source. */
+    dispose(): void;
+}
+export interface ComponentInputs {
+    readonly names: readonly string[];
+    /** Props plus declared state, computed values and context aliases; only props accept sources. */
+    readonly readNames: readonly string[];
+    read(name: string): unknown;
+    status(name: string): InputStatus;
+    supplied(name: string): boolean;
+    /** Opaque, nonreactive revision for validating retained producer data; undefined means uncacheable. */
+    revision(name: string): number | undefined;
+    /** Runs in the renderer's observation scope, including when a driver is bundled separately. */
+    capture<T>(read: () => T): InputEvaluation<T>;
+    source<T = unknown>(name: string): InputSource<T>;
+    /** A source owner stops this subscription when its preparation or activation ends. */
+    watch(run: () => void | (() => void)): () => void;
+}
+export interface InputPortAdapter {
+    readonly names: readonly string[];
+    readonly readNames?: readonly string[];
+    read(name: string): unknown;
+    status(name: string): InputStatus;
+    supplied(name: string): boolean;
+    /** Enable/read accepted-input commit tracking only when a driver asks for it. */
+    revision?(name: string): number;
+    /** Validate against the whole accepted candidate, then commit value and status together. */
+    publish(name: string, snapshot: InputSnapshot): boolean;
+    /** Publishing is write bookkeeping; it must not subscribe a producer to its own output. */
+    untracked<T>(run: () => T): T;
+    watch(run: () => void | (() => void)): () => void;
+}
+/** Shared SDK protocol; no source configuration or server/browser execution policy lives here. */
+export declare const INPUT_PORT: unique symbol;
+export declare function componentInputs(host: object): ComponentInputs;
+/**
+ * One source capability per prop. The adapter owns accepted storage and type checks; this port
+ * owns neither a second value store nor a second reactive engine. It also enforces caller precedence
+ * before the adapter sees any source proposal, including proposals that arrive after disposal.
+ */
+export declare function createInputPort(adapter: InputPortAdapter): ComponentInputs;
+/** Renderer-neutral input bookkeeping. Accepted values remain in the renderer's existing store. */
+export declare const BINDING_INPUTS_PROP = "\0htmlNextInputStatus";
+export type InputBindings = Readonly<Record<string, () => InputSnapshot>>;
+export type InputAcceptance = {
+    readonly ok: true;
+    readonly value: unknown;
+} | {
+    readonly ok: false;
+};
+export interface PropInputOptions {
+    readonly names: readonly string[];
+    readonly values: Record<string, unknown>;
+    readonly defaults: Readonly<Record<string, unknown>>;
+    readonly check: (name: string, value: unknown, source: boolean, values: Readonly<Record<string, unknown>>) => InputAcceptance;
+    readonly invalidate: () => void;
+}
+export interface InputReactions {
+    readonly declarations?: Readonly<Record<string, {
+        readonly read: () => unknown;
+        readonly status: () => InputStatus;
+    }>>;
+    track(name: string, kind: "value" | "status" | "supplied"): void;
+    notify?(name: string, kind: "value" | "status" | "supplied"): void;
+    watch(run: () => void | (() => void)): () => void;
+    untracked<T>(run: () => T): T;
+}
+export declare class PropInputs {
+    #private;
+    constructor(options: PropInputOptions);
+    /** Imperative code reads the connected instance, even during a speculative render. */
+    get committed(): PropInputs;
+    /** Concurrent renderers may examine a candidate without changing the connected instance. */
+    fork(options: PropInputOptions): PropInputs;
+    commit(candidate: PropInputs): void;
+    value<T>(name: string, input: unknown, bindings?: InputBindings, flags?: Record<string, boolean>): T;
+    read<T = unknown>(name: string): T;
+    inputValue(name: string): unknown;
+    supplied(name: string): boolean;
+    revision(name: string): number;
+    status(name: string): InputStatus;
+    publish(name: string, snapshot: InputSnapshot): boolean;
+    port(reactions: InputReactions): ComponentInputs;
+}
+/** Declared event details use the same nested type and constraint check as typed values. */
+export declare function acceptsDeclaredEvent(value: unknown, type: Parameters<typeof parse>[1]): boolean;
+export declare function vuePropInputs(values: Record<string, unknown>, defaults: Readonly<Record<string, unknown>>, check: PropInputOptions["check"], prepare: () => void): {
+    inputs: PropInputs;
+    version: import("vue").ShallowRef<number, number>;
+    track(name: string, kind: "value" | "status" | "supplied"): void;
+    untracked<T>(run: () => T): T;
+};
+export {};