@nan0web/ui 1.0.0

package/types/core/Form/Form.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Abstract form for data entry.
+ *
+ * @class UIForm
+ * @extends FormMessage
+ * @property {FormInput[]} fields - Form fields.
+ * @property {Object} state - Current form state (field values).
+ * @property {string} title - Form title.
+ * @property {Object} schema - Validation schema (optional).
+ */
+export default class UIForm extends FormMessage {
+    /** @type {Object<string,Function>} */
+    static _validators: {
+        [x: string]: Function;
+    };
+    /**
+     * Register a custom validator that can be referenced by name in a schema.
+     *
+     * @param {string} name - Identifier used in schema.validator.
+     * @param {(value:any)=>true|string} fn - Function returns true if valid,
+     *   otherwise returns an error message.
+     */
+    static addValidator(name: string, fn: (value: any) => true | string): void;
+    /**
+     * @param {*} input
+     * @returns {UIForm}
+     */
+    static from(input: any): UIForm;
+    /**
+     * Auto‑generates form fields from a plain object.
+     *
+     * @param {Object} data - Example data object; its own enumerable keys become field names.
+     * @param {Object<string, Partial<import("./Input.js").default>>} [overrides={}]
+     *        Optional per‑field overrides (e.g. type, required, label).
+     *
+     * @returns {UIForm} Form with Array of `FormInput` instances as form.fields
+     *
+     * Example:
+     *   const fields = generateFieldsFromObject({ name: "", age: 0 }, {
+     *     age: { type: FormInput.TYPES.NUMBER, required: true }
+     *   })
+     */
+    static parse(data: any, overrides?: {
+        [x: string]: Partial<FormInput>;
+    } | undefined): UIForm;
+    /**
+     * Create a new UIForm.
+     *
+     * @param {Object} [props={}] - Form properties.
+     * @param {string} [props.title] - Form title.
+     * @param {FormInput[]} [props.fields=[]] - Form fields.
+     * @param {Object} [props.state={}] - Initial form state.
+     * @param {Object} [props.schema] - Validation schema.
+     */
+    constructor(props?: {
+        title?: string | undefined;
+        fields?: FormInput[] | undefined;
+        state?: any;
+        schema?: any;
+    } | undefined);
+    /** @type {FormInput[]} */ fields: FormInput[];
+    /** @type {Object} */ state: any;
+    /** @type {string} */ title: string;
+    meta: {
+        title: string;
+        fields: any[];
+        initialState: any;
+    };
+    /**
+     * Returns a new UIForm instance with updated state.
+     *
+     * @param {Object} data - Partial state to merge.
+     * @returns {UIForm}
+     */
+    setData(data: any): UIForm;
+    /**
+     * Retrieves a field definition by its name.
+     *
+     * @param {string} name - Field name.
+     * @returns {FormInput|undefined}
+     */
+    getField(name: string): FormInput | undefined;
+    /**
+     * Returns current form values.
+     *
+     * @returns {Object}
+     */
+    getValues(): any;
+    /**
+     * Validates the entire form.
+     *
+     * @returns {{isValid: boolean, errors: Object}} Validation result.
+     */
+    validate(): {
+        isValid: boolean;
+        errors: any;
+    };
+    /**
+     * Validates a single field.
+     *
+     * @param {string} fieldName - Name of the field.
+     * @param {*} value - Value to validate.
+     * @returns {{isValid: boolean, errors: Object}}
+     */
+    validateField(fieldName: string, value: any): {
+        isValid: boolean;
+        errors: any;
+    };
+    /**
+     * Validates a value against a schema.
+     *
+     * @param {string} fieldName - Name of the field.
+     * @param {*} value - Value to validate.
+     * @param {Object} schema - Validation schema.
+     * @returns {{isValid: boolean, errors: Object}}
+     */
+    validateValue(fieldName: string, value: any, schema: any): {
+        isValid: boolean;
+        errors: any;
+    };
+}
+import FormMessage from "./Message.js";
+import FormInput from "./Input.js";

package/types/core/Form/Input.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Form input field descriptor.
+ *
+ * @class FormInput
+ * @property {string} name - Field name.
+ * @property {string} label - Display label.
+ * @property {string} type - Input type (text, email, number, select, etc.).
+ * @property {boolean} required - Whether the field is required.
+ * @property {string} placeholder - Placeholder text.
+ * @property {Array<string>} options - Select options (if type is 'select').
+ * @property {Function|null} validator - Custom validation function.
+ * @property {*} defaultValue - Default value.
+ */
+export default class FormInput {
+    /**
+     * Predefined input types.
+     */
+    static TYPES: {
+        TEXT: string;
+        EMAIL: string;
+        NUMBER: string;
+        SELECT: string;
+        CHECKBOX: string;
+        TEXTAREA: string;
+    };
+    /**
+     * @param {*} input
+     * @returns {FormInput}
+     */
+    static from(input: any): FormInput;
+    /**
+     * Create a new form input.
+     *
+     * @param {Object} props - Input properties.
+     * @param {string} props.name - Field name.
+     * @param {string} [props.label=props.name] - Display label.
+     * @param {string} [props.type='text'] - Input type.
+     * @param {boolean} [props.required=false] - Is required.
+     * @param {string} [props.placeholder=''] - Placeholder.
+     * @param {Array<string>} [props.options=[]] - Select options.
+     * @param {Function} [props.validator=null] - Custom validator.
+     * @param {*} [props.defaultValue=null] - Default value.
+     */
+    constructor(props: {
+        name: string;
+        label?: string | undefined;
+        type?: string | undefined;
+        required?: boolean | undefined;
+        placeholder?: string | undefined;
+        options?: string[] | undefined;
+        validator?: Function | undefined;
+        defaultValue?: any;
+    });
+    /** @type {string} */ name: string;
+    /** @type {string} */ label: string;
+    /** @type {string} */ type: string;
+    /** @type {boolean} */ required: boolean;
+    /** @type {string} */ placeholder: string;
+    /** @type {Array<string>} */ options: Array<string>;
+    /** @type {Function|null} */ validator: Function | null;
+    /** @type {*} */ defaultValue: any;
+    requireValidType(): void;
+    /**
+     * Serialises the input to a plain JSON object.
+     *
+     * @returns {Object}
+     */
+    toJSON(): any;
+}

package/types/core/Form/Message.d.ts

@@ -0,0 +1,28 @@
+/**
+ * FormMessage – specialized OutputMessage for forms.
+ *
+ * @class FormMessage
+ * @extends OutputMessage
+ */
+export default class FormMessage extends OutputMessage {
+    data: any;
+    schema: any;
+    /**
+     * Returns a new FormMessage with merged data.
+     *
+     * @param {Object} newData - Data to merge.
+     * @returns {FormMessage}
+     */
+    addData(newData: any): FormMessage;
+    /**
+     * Validates the provided data against the schema.
+     *
+     * @param {Object} data - Data to validate.
+     * @returns {{isValid: boolean, errors: Object}}
+     */
+    validateData(data: any): {
+        isValid: boolean;
+        errors: any;
+    };
+}
+import OutputMessage from "../Message/OutputMessage.js";

package/types/core/Form/index.d.ts

@@ -0,0 +1,5 @@
+export default Form;
+import FormInput from "./Input.js";
+import FormMessage from "./Message.js";
+import Form from "./Form.js";
+export { FormInput, FormMessage, Form };

package/types/core/InputAdapter.d.ts

@@ -0,0 +1,28 @@
+export default InputAdapter;
+/**
+ * Abstract input adapter for UI implementations.
+ *
+ * @class InputAdapter
+ * @extends Event
+ */
+declare class InputAdapter extends Event {
+    /**
+     * Starts listening for input and emits an `input` event.
+     *
+     * @returns {void}
+     */
+    start(): void;
+    /**
+     * Stops listening for input. Default implementation does nothing.
+     *
+     * @returns {void}
+     */
+    stop(): void;
+    /**
+     * Checks whether the adapter is ready to receive input.
+     *
+     * @returns {boolean} Always true in base class.
+     */
+    isReady(): boolean;
+}
+import Event from "@nan0web/event/oop";

package/types/core/Message/InputMessage.d.ts

@@ -0,0 +1,71 @@
+/** @typedef {Message | string | null} InputMessageValue */
+/**
+ * Represents a message input with value, options, and metadata.
+ */
+export default class InputMessage {
+    static ESCAPE: string;
+    /**
+     * Creates an InputMessage instance from the given value.
+     * @param {InputMessage|object|string} value - The value to create from
+     * @returns {InputMessage} An InputMessage instance
+     */
+    static from(value: InputMessage | object | string): InputMessage;
+    /**
+     * Creates a new InputMessage instance.
+     * @param {object} props - Input message properties
+     * @param {InputMessageValue} [props.value=""] - Input value
+     * @param {string[]|string} [props.options=[]] - Available options
+     * @param {boolean} [props.waiting=false] - Waiting state flag
+     * @param {boolean} [props.escaped=false] - Sets value to escape when true
+     */
+    constructor(props?: {
+        value?: InputMessageValue | undefined;
+        options?: string | string[] | undefined;
+        waiting?: boolean | undefined;
+        escaped?: boolean | undefined;
+    });
+    /** @type {InputMessageValue} Input value */
+    value: InputMessageValue;
+    /** @type {string[]} Available options for this input */
+    options: string[];
+    /** @type {boolean} Whether this input is waiting for response */
+    waiting: boolean;
+    /**
+     * Checks if the input value is empty.
+     * @returns {boolean} True if value is empty or null, false otherwise
+     */
+    get empty(): boolean;
+    /**
+     * Gets the timestamp when input was created.
+     * @returns {number} Creation timestamp
+     */
+    get time(): number;
+    /**
+     * Returns the escape value.
+     * @returns {string}
+     */
+    get ESCAPE(): string;
+    /**
+     * Checks if the input is an escape sequence.
+     * @returns {boolean} True if input value is escape sequence, false otherwise
+     */
+    get escaped(): boolean;
+    /**
+     * Validates if the input has a non-empty value.
+     * @returns {boolean} True if input is valid, false otherwise
+     */
+    get isValid(): boolean;
+    /**
+     * Converts the input to a plain object representation.
+     * @returns {object} Object with all properties including timestamp
+     */
+    toObject(): object;
+    /**
+     * Converts the input to a string representation including timestamp.
+     * @returns {string} String representation with timestamp and value
+     */
+    toString(): string;
+    #private;
+}
+export type InputMessageValue = Message | string | null;
+import { Message } from "@nan0web/co";

package/types/core/Message/Message.d.ts

@@ -0,0 +1,50 @@
+export default UIMessage;
+/**
+ * Base UI message class.
+ *
+ * @class UIMessage
+ * @extends BaseMessage
+ */
+declare class UIMessage extends BaseMessage {
+    static TYPES: {
+        TEXT: string;
+        FORM: string;
+        PROGRESS: string;
+        ERROR: string;
+        INFO: string;
+        SUCCESS: string;
+        WARNING: string;
+        COMMAND: string;
+        NAVIGATION: string;
+    };
+    /**
+     * Creates a UIMessage instance from plain data.
+     *
+     * @param {Object} data - Message data.
+     * @returns {UIMessage}
+     */
+    static from(data: any): UIMessage;
+    /**
+     * Creates a UIMessage.
+     *
+     * @param {Object} [input={}] - Message properties.
+     */
+    constructor(input?: any);
+    /** @type {string} */
+    type: string;
+    /** @type {string} */
+    id: string;
+    /**
+     * Checks if the message type is valid.
+     *
+     * @returns {boolean}
+     */
+    isValidType(): boolean;
+    /**
+     * Checks whether the message contains any body content.
+     *
+     * @returns {boolean}
+     */
+    isEmpty(): boolean;
+}
+import { Message as BaseMessage } from "@nan0web/co";

package/types/core/Message/OutputMessage.d.ts

@@ -0,0 +1,53 @@
+/**
+ * OutputMessage – message sent from the system to the UI.
+ *
+ * @class OutputMessage
+ * @extends UIMessage
+ */
+export default class OutputMessage extends UIMessage {
+    static PRIORITY: {
+        LOW: number;
+        NORMAL: number;
+        HIGH: number;
+        CRITICAL: number;
+    };
+    /**
+     * Creates an OutputMessage from plain input.
+     *
+     * @param {Object} input - Message data.
+     * @returns {OutputMessage}
+     */
+    static from(input: any): OutputMessage;
+    /** @type {string[]} */
+    body: string[];
+    /** @type {Object} */
+    meta: any;
+    /** @type {Error|null} */
+    error: Error | null;
+    /** @type {number} */
+    priority: number;
+    /** @param {string[]|string} value */
+    set content(arg: string[]);
+    /** @returns {string[]} */
+    get content(): string[];
+    /** @returns {number} */
+    get size(): number;
+    /** @returns {boolean} */
+    get isError(): boolean;
+    /** @returns {boolean} */
+    get isInfo(): boolean;
+    /**
+     * Combines multiple messages into a new one.
+     *
+     * @param {...OutputMessage} messages - Messages to combine.
+     * @returns {OutputMessage}
+     */
+    combine(...messages: OutputMessage[]): OutputMessage;
+    /**
+     * Serialises the message to a plain JSON object.
+     *
+     * @returns {Object}
+     */
+    toJSON(): any;
+}
+import UIMessage from "./Message.js";

package/types/core/Message/index.d.ts

@@ -0,0 +1,5 @@
+export default UIMessage;
+import UIMessage from "./Message.js";
+import InputMessage from "./InputMessage.js";
+import OutputMessage from "./OutputMessage.js";
+export { UIMessage, InputMessage, OutputMessage };

package/types/core/OutputAdapter.d.ts

@@ -0,0 +1,33 @@
+export default OutputAdapter;
+/**
+ * Abstract output adapter for UI implementations.
+ *
+ * @class OutputAdapter
+ * @extends Event
+ */
+declare class OutputAdapter extends Event {
+    /**
+     * Renders a message to the user.
+     *
+     * @param {OutputMessage|FormMessage} message - Message to render.
+     * @throws {Error} If not overridden by a subclass.
+     */
+    render(message: OutputMessage | FormMessage): void;
+    /**
+     * Shows progress of a long‑running operation.
+     *
+     * @param {number} progress - Progress value in range 0‑1.
+     * @param {Object} [metadata={}] - Additional metadata.
+     * @returns {void}
+     */
+    progress(progress: number, metadata?: any): void;
+    /**
+     * Stops the output stream. Default implementation does nothing.
+     *
+     * @returns {void}
+     */
+    stop(): void;
+}
+import Event from '@nan0web/event/oop';
+import OutputMessage from './Message/OutputMessage.js';
+import FormMessage from './Form/Message.js';

package/types/core/Stream.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Agnostic UI stream for processing progress.
+ *
+ * @class UIStream
+ */
+export default class UIStream {
+    /**
+     * Creates an async generator that runs the supplied processor function.
+     *
+     * @param {AbortSignal} signal - Abort signal.
+     * @param {() => Promise<StreamEntry>} processorFn - Async function that returns a result.
+     * @returns {() => AsyncGenerator<StreamEntry>} Async generator function.
+     */
+    static createProcessor(signal: AbortSignal, processorFn: () => Promise<StreamEntry>): () => AsyncGenerator<StreamEntry>;
+    /**
+     * Runs a generator with progress callbacks and abort handling.
+     *
+     * @param {AbortSignal} signal - Abort signal.
+     * @param {Function} generator - Function returning an async iterator.
+     * @param {Function} [onProgress] - Called with (progress, item).
+     * @param {Function} [onError] - Called with (errorMessage, item).
+     * @param {Function} [onComplete] - Called with (item) when done.
+     * @returns {Promise<void>}
+     */
+    static process(signal: AbortSignal, generator: Function, onProgress?: Function | undefined, onError?: Function | undefined, onComplete?: Function | undefined): Promise<void>;
+}
+import StreamEntry from "./StreamEntry.js";

package/types/core/StreamEntry.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Represents an entry in a stream with value, completion status, cancellation status, and error message.
+ */
+export default class StreamEntry {
+    /**
+     * Creates a StreamEntry instance from the given input.
+     * @param {any} input - The input to create a StreamEntry from.
+     * @returns {StreamEntry} A new or existing StreamEntry instance.
+     */
+    static from(input: any): StreamEntry;
+    /**
+     * Creates a new StreamEntry instance.
+     * @param {Object} [input={}] - Input object to initialize the stream entry.
+     * @param {any} [input.value] - The value for the stream entry.
+     * @param {boolean} [input.done] - Whether the stream entry is completed.
+     * @param {boolean} [input.cancelled] - Whether the stream entry is cancelled.
+     * @param {string} [input.error] - Error message for the stream entry.
+     */
+    constructor(input?: {
+        value?: any;
+        done?: boolean | undefined;
+        cancelled?: boolean | undefined;
+        error?: string | undefined;
+    } | undefined);
+    /**
+     * The value of the stream entry.
+     * @type {any}
+     */
+    value: any;
+    /**
+     * Indicates if the stream entry is done (completed).
+     * @type {boolean}
+     */
+    done: boolean;
+    /**
+     * Indicates if the stream entry has been cancelled.
+     * @type {boolean}
+     */
+    cancelled: boolean;
+    /**
+     * Error message associated with the stream entry.
+     * @type {string}
+     */
+    error: string;
+}

package/types/core/index.d.ts

@@ -0,0 +1,9 @@
+export { default as InputAdapter } from "./InputAdapter.js";
+export { default as OutputAdapter } from "./OutputAdapter.js";
+export { default as UIStream } from "./Stream.js";
+export { default as UIMessage } from "./Message/Message.js";
+export { default as InputMessage } from "./Message/InputMessage.js";
+export { default as OutputMessage } from "./Message/OutputMessage.js";
+export { default as FormMessage } from "./Form/Message.js";
+export { default as FormInput } from "./Form/Input.js";
+export { default as UIForm } from "./Form/Form.js";

package/types/functions.d.ts

@@ -0,0 +1,3 @@
+export function spaces(options?: {}): (row: any) => any;
+export function weight(arr: any): (Fn?: (v: any) => any) => any[];
+export function table(options?: {}): (arr: any) => any;

package/types/index.d.ts

@@ -0,0 +1,20 @@
+export { default as FormMessage } from "./core/Form/Message.js";
+export { default as FormInput } from "./core/Form/Input.js";
+export { default as InputAdapter } from "./core/InputAdapter.js";
+export { default as InputMessage } from "./core/Message/InputMessage.js";
+export { default as OutputAdapter } from "./core/OutputAdapter.js";
+export { default as OutputMessage } from "./core/Message/OutputMessage.js";
+export { default as UIForm } from "./core/Form/Form.js";
+export { default as UIMessage } from "./core/Message/Message.js";
+export { default as UIStream } from "./core/Stream.js";
+import Frame from "./Frame/Frame.js";
+import FrameProps from "./Frame/Props.js";
+import Locale from "./Locale.js";
+import StdIn from "./StdIn.js";
+import StdOut from "./StdOut.js";
+import View from "./View/View.js";
+import RenderOptions from "./View/RenderOptions.js";
+import Model from "./Model/index.js";
+import Component from "./Component/index.js";
+import App from "./App/index.js";
+export { Frame, FrameProps, Locale, StdIn, StdOut, View, RenderOptions, Model, Component, App };

package/types/models/SimpleUser.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Plain model without any UI‑specific extensions.
+ *
+ * The form for this model will be generated automatically from its properties.
+ */
+export default class SimpleUser {
+    /**
+     * @param {Object} data
+     * @param {string} [data.name]
+     * @param {string} [data.email]
+     * @param {number | null} [data.age]
+     */
+    constructor({ name, email, age }?: {
+        name?: string | undefined;
+        email?: string | undefined;
+        age?: number | null | undefined;
+    });
+    name: string;
+    email: string;
+    age: number | null;
+}

package/vitest.config.js

@@ -0,0 +1,26 @@
+import process from "node:process"
+import { defineConfig } from "vitest/config"
+
+export default defineConfig({
+	test: {
+		sourcemap: true,
+		environment: "node",
+		cache: false,
+		root: process.cwd(),
+		coverage: {
+			provider: "v8",
+		},
+		exclude: [
+			"apps/**",
+			"node_modules/**",
+		],
+		isolate: false,
+		// Try to force inline source maps for best debugging
+		// (Vite will use inline source maps for dev by default)
+	},
+	resolve: {
+		alias: {
+			"@": "/src",
+		},
+	},
+})