@nan0web/ui 1.5.2 → 1.7.0

package/types/InterfaceTemplate/InterfaceTemplate.d.ts

@@ -0,0 +1,67 @@
+/**
+ * InterfaceTemplate — base class for defining new UI interfaces.
+ *
+ * Establishes the inheritance pattern for the "One Logic, Many UI" architecture.
+ * Each UI interface (CLI, Web, Mobile, Chat, Audio) extends this template
+ * and overrides the required methods.
+ *
+ * @example
+ * class CliInterface extends InterfaceTemplate {
+ *   render(data) { return formatForTerminal(data) }
+ *   async ask(prompt) { return readlinePrompt(prompt) }
+ * }
+ *
+ * @abstract
+ */
+export default class InterfaceTemplate {
+    /**
+     * List of methods that MUST be overridden by concrete implementations.
+     * Used for documentation and runtime validation.
+     *
+     * @type {string[]}
+     */
+    static requiredMethods: string[];
+    /**
+     * The name of this interface (e.g. 'cli', 'web', 'mobile').
+     * Override in subclass.
+     *
+     * @type {string}
+     */
+    name: string;
+    /**
+     * Render data to the user through the interface.
+     * Must be overridden by each concrete implementation.
+     *
+     * @param {any} [data] - data to render
+     * @returns {any} rendered output (string for CLI, DOM for web, etc.)
+     * @throws {Error} if not overridden
+     */
+    render(data?: any): any;
+    /**
+     * Request input from the user through the interface.
+     * Must be overridden by each concrete implementation.
+     *
+     * @param {string} prompt - question or label for the input
+     * @param {object} [options] - options (type, choices, default, etc.)
+     * @returns {Promise<any>} user's response
+     * @throws {Error} if not overridden
+     */
+    ask(prompt: string, options?: object): Promise<any>;
+    /**
+     * Validate that all required methods have been overridden.
+     * Call this in the subclass constructor to get early feedback.
+     *
+     * @returns {string[]} list of missing method overrides (empty = valid)
+     */
+    validate(): string[];
+    /**
+     * Get interface capabilities info.
+     *
+     * @returns {{ name: string, requiredMethods: string[], isComplete: boolean }}
+     */
+    info(): {
+        name: string;
+        requiredMethods: string[];
+        isComplete: boolean;
+    };
+}

package/types/InterfaceTemplate/index.d.ts

@@ -0,0 +1 @@
+export { default, InterfaceTemplate } from "./InterfaceTemplate.js";

package/types/core/GeneratorRunner.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Runs an OLMUI async generator through the provided adapter handlers.
+ *
+ * This function is the SINGLE point of execution for all adapters.
+ * It guarantees:
+ * - Every yielded intent is validated (contract enforcement).
+ * - Every 'ask' intent gets a response or times out (if timeoutMs > 0).
+ * - External abort signals are respected.
+ * - The final result is returned.
+ *
+ * @template T
+ * @param {AsyncGenerator<import('./Intent.js').Intent, import('./Intent.js').ResultIntent, import('./Intent.js').IntentResponse>} generator
+ *   The model's async generator (from Model.run()).
+ * @param {AdapterHandlers} handlers
+ *   Platform-specific handlers for each intent type.
+ * @param {RunnerOptions} [options={}]
+ *   Runner configuration (timeout, abort signal).
+ * @returns {Promise<T>}
+ *   The final result data from the generator.
+ */
+export function runGenerator<T>(generator: AsyncGenerator<import("./Intent.js").Intent, import("./Intent.js").ResultIntent, import("./Intent.js").IntentResponse>, handlers: AdapterHandlers, options?: RunnerOptions): Promise<T>;
+export type AdapterHandlers = {
+    /**
+     *   Handler for 'ask' intents. Must return { value: ... }.
+     */
+    ask: (intent: import("./Intent.js").AskIntent) => Promise<import("./Intent.js").AskResponse>;
+    /**
+     * Handler for 'progress' intents. Optional (defaults to no-op).
+     */
+    progress?: ((intent: import("./Intent.js").ProgressIntent) => void | Promise<void>) | undefined;
+    /**
+     * Handler for 'log' intents. Optional (defaults to no-op).
+     */
+    log?: ((intent: import("./Intent.js").LogIntent) => void | Promise<void>) | undefined;
+    /**
+     * Handler for the final 'result'. Optional (defaults to no-op).
+     */
+    result?: ((intent: import("./Intent.js").ResultIntent) => void | Promise<void>) | undefined;
+};
+export type RunnerOptions = {
+    /**
+     * Maximum milliseconds to wait for an adapter handler to respond.
+     * Default is 0 (disabled) — web forms may wait indefinitely.
+     * Set to a positive value for CLI/Chat adapters where hanging is unacceptable.
+     */
+    timeoutMs?: number | undefined;
+    /**
+     * External AbortSignal for cancellation from outside.
+     */
+    signal?: AbortSignal | undefined;
+};

package/types/core/Intent.d.ts

@@ -1,88 +1,230 @@
 /**
- * Intent represents the user's declared will to perform an action.
- * It is interface-agnostic and can be validated or executed without
- * any UI, CLI, or external dependencies.
+ * Detects if a value is a Model-as-Schema class (has static fields with `help`).
+ * @param {*} schema
+ * @returns {boolean}
+ */
+export function isModelSchema(schema: any): boolean;
+/**
+ * Validates that an object is a well-formed Intent.
+ * Throws ModelError if the intent is malformed (the "Judge").
  *
- * An Intent may be:
- * - Ready: all required data is valid → can be executed immediately
- * - Partial: some data missing or invalid → requires user action
- * - Invalid: cannot be fulfilled under any interface (e.g., restricted field)
+ * @param {*} intent
+ * @returns {intent is Intent}
+ */
+export function validateIntent(intent: any): intent is Intent;
+/**
+ * @typedef {Object} FieldSchema
+ * @property {string} help - Human-readable label / i18n key.
+ * @property {*} default - Default value for the field.
+ * @property {string} [type] - Field type hint ('text', 'number', 'text/markdown').
+ * @property {Array<{value: *, label: string}>} [options] - Enum options for select.
+ * @property {(val: *) => true | string} [validate] - Validator: true = ok, string = error key from Model.
+ * @property {boolean} [hidden] - If true, field is excluded from UI forms.
+ */
+/**
+ * Model needs data from the environment (user input, LLM extraction, test fixture).
+ * Adapter MUST return an `AskResponse`.
+ * @typedef {Object} AskIntent
+ * @property {'ask'} type
+ * @property {string} field - Property name on the model.
+ * @property {FieldSchema | Function} schema - Field metadata or Model-as-Schema class constructor.
+ * @property {true} [model] - When true, schema is a Model-as-Schema class (full form).
+ */
+/**
+ * Model informs about a long-running operation. No response expected.
+ * Message MUST come from the Model (i18n static field value).
+ * @typedef {Object} ProgressIntent
+ * @property {'progress'} type
+ * @property {number} [value] - Progress value (0-1).
+ * @property {string} [id] - Progress ID for tracking multiple parallel operations.
+ * @property {string} message - Status message from Model (i18n static field value).
+ */
+/**
+ * Model emits a log message. No response expected.
+ * Message MUST come from the Model (i18n static field value).
+ * @typedef {Object} LogIntent
+ * @property {'log'} type
+ * @property {'info' | 'warn' | 'error' | 'success'} level
+ * @property {string} message - Log message from Model (i18n static field value).
+ */
+/**
+ * Final return value from the generator.
+ * @typedef {Object} ResultIntent
+ * @property {'result'} type
+ * @property {*} data - The raw result data (JSON-serializable).
+ */
+/**
+ * Union of all possible yielded intents.
+ * @typedef {AskIntent | ProgressIntent | LogIntent} Intent
+ */
+/**
+ * Response to an AskIntent. Adapter provides the collected value.
+ * The value MUST conform to the type described in the requested FieldSchema.
+ * @typedef {Object} AskResponse
+ * @property {*} value - The value matching schema.type (collected from user / LLM / test fixture).
+ * @property {boolean} [cancelled] - Whether the user cancelled this interaction (e.g. pressed ESC).
+ */
+/**
+ * Special response that Adapters can send to abort the generator.
+ *
+ * The `reason` is a KEY from the Model's static `abort` dictionary,
+ * not a freeform message. This enables proper i18n translation:
  *
- * @example
- * const intent = new Intent({
- *   target: LoginMessage,
- *   body: { username: "alice" }
- * })
- * if (!intent.isReady()) {
- *   const validMsg = await handleIntent(intent, adapter)
- * }
- */
-declare class Intent extends Message {
-	/**
-	 * Create a new Intent.
-	 *
-	 * @param {object} input
-	 * @param {typeof Message} input.target - message class this intent wants to create
-	 * @param {any} [input.context] - execution context
-	 * @param {object} [body] - partial or complete data for the target message
-	 */
-	constructor({ target, context, ...body }?: { target: typeof Message; context?: any })
-	/**
-	 * The target Message class this Intent aims to produce.
-	 * Must be a class with a static `.Body` schema.
-	 *
-	 * @type {typeof Message | null}
-	 */
-	target: typeof Message | null
-	/**
-	 * Optional context for execution (session, locale, state, etc.).
-	 *
-	 * @type {any}
-	 */
-	context: any
-	/**
-	 * Validates all fields in the Intent's body against the target's schema.
-	 *
-	 * Checks:
-	 * - Required fields presence and non-emptiness
-	 * - Pattern matching (RegExp)
-	 * - Value within allowed options (if defined)
-	 * - Custom validation logic (if `validate` function is defined)
-	 *
-	 * @returns {Map<string, string>} Map of field → error message, empty if valid
-	 */
-	validateIntent(): Map<string, string>
-	/**
-	 * Executes the Intent by creating a valid instance of the target message.
-	 *
-	 * If the Intent is not ready (has validation errors), returns null.
-	 *
-	 * @returns {Message | null} the created message, or null if invalid
-	 */
-	execute(): Message | null
-	/**
-	 * Checks if the Intent can be executed immediately, without user input.
-	 *
-	 * @returns {boolean} true if all required fields are valid
-	 */
-	isReady(): boolean
-	/**
-	 * Converts the Intent to a plain object for logging or inspection.
-	 *
-	 * @returns {object} serializable object with intent, body, and context
-	 */
-	toObject(): object
-}
-declare namespace Intent {
-	/**
-	 * Handles an Intent by fulfilling missing or invalid fields.
-	 *
-	 * @param {Intent} intent - the declared intent to handle
-	 * @param {object} inputAdapter - must have `.ask(prompt)`
-	 * @returns {Promise<Message | null>} resolved when intent is fulfilled
-	 * @throws {CancelError} if user cancels
-	 */
-	function handleIntent(intent: Intent, inputAdapter: object): Promise<Message | null>
-}
-export default Intent
-import { Message } from '@nan0web/co'
+ *   Model defines:  static abort = { user_cancelled: 'Скасовано', timeout: 'Час вичерпано' }
+ *   Adapter sends:  { abort: true, reason: 'user_cancelled' }
+ *   UI translates:  t(Model.abort[reason])
+ *
+ * @typedef {Object} AbortResponse
+ * @property {true} abort - Signal to the model that execution was cancelled.
+ * @property {string} [reason] - Key from Model's static abort dictionary (not a freeform message).
+ */
+/**
+ * Union of all possible responses an Adapter can send back via iterator.next().
+ * @typedef {AskResponse | AbortResponse | undefined} IntentResponse
+ */
+export const INTENT_TYPES: readonly ["ask", "progress", "log"];
+export function ask(field: string, schema: object | Function): AskIntent;
+export function progress(message: any): {
+    type: string;
+    message: any;
+};
+export function log(level: any, message: any, data?: {}): {
+    type: string;
+    level: any;
+    message: any;
+};
+export function result(data: any): {
+    type: string;
+    data: any;
+};
+export type FieldSchema = {
+    /**
+     * - Human-readable label / i18n key.
+     */
+    help: string;
+    /**
+     * - Default value for the field.
+     */
+    default: any;
+    /**
+     * - Field type hint ('text', 'number', 'text/markdown').
+     */
+    type?: string | undefined;
+    /**
+     * - Enum options for select.
+     */
+    options?: {
+        value: any;
+        label: string;
+    }[] | undefined;
+    /**
+     * - Validator: true = ok, string = error key from Model.
+     */
+    validate?: ((val: any) => true | string) | undefined;
+    /**
+     * - If true, field is excluded from UI forms.
+     */
+    hidden?: boolean | undefined;
+};
+/**
+ * Model needs data from the environment (user input, LLM extraction, test fixture).
+ * Adapter MUST return an `AskResponse`.
+ */
+export type AskIntent = {
+    type: "ask";
+    /**
+     * - Property name on the model.
+     */
+    field: string;
+    /**
+     * - Field metadata or Model-as-Schema class constructor.
+     */
+    schema: FieldSchema | Function;
+    /**
+     * - When true, schema is a Model-as-Schema class (full form).
+     */
+    model?: true | undefined;
+};
+/**
+ * Model informs about a long-running operation. No response expected.
+ * Message MUST come from the Model (i18n static field value).
+ */
+export type ProgressIntent = {
+    type: "progress";
+    /**
+     * - Progress value (0-1).
+     */
+    value?: number | undefined;
+    /**
+     * - Progress ID for tracking multiple parallel operations.
+     */
+    id?: string | undefined;
+    /**
+     * - Status message from Model (i18n static field value).
+     */
+    message: string;
+};
+/**
+ * Model emits a log message. No response expected.
+ * Message MUST come from the Model (i18n static field value).
+ */
+export type LogIntent = {
+    type: "log";
+    level: "info" | "warn" | "error" | "success";
+    /**
+     * - Log message from Model (i18n static field value).
+     */
+    message: string;
+};
+/**
+ * Final return value from the generator.
+ */
+export type ResultIntent = {
+    type: "result";
+    /**
+     * - The raw result data (JSON-serializable).
+     */
+    data: any;
+};
+/**
+ * Union of all possible yielded intents.
+ */
+export type Intent = AskIntent | ProgressIntent | LogIntent;
+/**
+ * Response to an AskIntent. Adapter provides the collected value.
+ * The value MUST conform to the type described in the requested FieldSchema.
+ */
+export type AskResponse = {
+    /**
+     * - The value matching schema.type (collected from user / LLM / test fixture).
+     */
+    value: any;
+    /**
+     * - Whether the user cancelled this interaction (e.g. pressed ESC).
+     */
+    cancelled?: boolean | undefined;
+};
+/**
+ * Special response that Adapters can send to abort the generator.
+ *
+ * The `reason` is a KEY from the Model's static `abort` dictionary,
+ * not a freeform message. This enables proper i18n translation:
+ *
+ *   Model defines:  static abort = { user_cancelled: 'Скасовано', timeout: 'Час вичерпано' }
+ *   Adapter sends:  { abort: true, reason: 'user_cancelled' }
+ *   UI translates:  t(Model.abort[reason])
+ */
+export type AbortResponse = {
+    /**
+     * - Signal to the model that execution was cancelled.
+     */
+    abort: true;
+    /**
+     * - Key from Model's static abort dictionary (not a freeform message).
+     */
+    reason?: string | undefined;
+};
+/**
+ * Union of all possible responses an Adapter can send back via iterator.next().
+ */
+export type IntentResponse = AskResponse | AbortResponse | undefined;

package/types/core/IntentErrorModel.d.ts

@@ -0,0 +1,55 @@
+export class IntentErrorModel {
+    static intent_not_object: {
+        help: string;
+        error: string;
+    };
+    static intent_unknown_type: {
+        help: string;
+        error: string;
+    };
+    static ask_missing_field: {
+        help: string;
+        error: string;
+    };
+    static ask_missing_schema_help: {
+        help: string;
+        error: string;
+    };
+    static intent_missing_message: {
+        help: string;
+        error: string;
+    };
+    static adapter_missing_ask: {
+        help: string;
+        error: string;
+    };
+    static ask_wrong_response: {
+        help: string;
+        error: string;
+    };
+    static validation_failed: {
+        help: string;
+        error: string;
+    };
+    static unhandled_intent: {
+        help: string;
+        error: string;
+    };
+    static timeout: {
+        help: string;
+        error: string;
+    };
+    static aborted: {
+        help: string;
+        error: string;
+    };
+    /**
+     * Build a ModelError for a specific error field.
+     *
+     * @param {string} field - Static field name on IntentErrorModel.
+     * @param {Record<string, *>} [params] - Template parameters to substitute {key} placeholders.
+     * @returns {ModelError}
+     */
+    static error(field: string, params?: Record<string, any>): ModelError;
+}
+import { ModelError } from '@nan0web/types';

package/types/core/MaskHandler.d.ts

@@ -0,0 +1,33 @@
+export class MaskHandler {
+    constructor(mask: any);
+    mask: any;
+    raw: string;
+    /** How many placeholder positions the mask has */
+    get _slotCount(): number;
+    /** Static prefix of the mask (literal characters before first placeholder) */
+    get _prefix(): string;
+    get isComplete(): boolean;
+    get formatted(): string;
+    /**
+     * Append a digit/letter character.
+     * Only accepts characters that fit into placeholders.
+     *
+     * @param {string} char
+     * @returns {boolean} true if accepted
+     */
+    input(char: string): boolean;
+    /**
+     * Remove last character
+     */
+    backspace(): boolean;
+    /**
+     * Set a full value, intelligently stripping the mask's static prefix
+     * if the user pasted or injected the full formatted number.
+     *
+     * e.g. setValue('+380660848404') with mask '+38 (099) 999 9999'
+     *      strips "+38" → raw = '0660848404'
+     *
+     * @param {string} val
+     */
+    setValue(val: string): void;
+}

package/types/core/index.d.ts

@@ -4,9 +4,13 @@ export { default as UiMessage } from "./Message/Message.js";
 export { default as FormMessage } from "./Form/Message.js";
 export { default as FormInput } from "./Form/Input.js";
 export { default as UiAdapter } from "./UiAdapter.js";
+export { IntentErrorModel } from "./IntentErrorModel.js";
+export { runGenerator } from "./GeneratorRunner.js";
+export { MaskHandler } from "./MaskHandler.js";
 import UIStream from './Stream.js';
 import StreamEntry from './StreamEntry.js';
 import UIForm from './Form/Form.js';
 export { UIStream, UIStream as UiStream, StreamEntry, StreamEntry as UiStreamEntry, UIForm, UIForm as UiForm };
 export { default as Error, CancelError } from "./Error/index.js";
 export { runFlow, flow, View, Prompt, Stream, Alert, Toast, Badge, Text, Table, Input, Select, Confirm, Multiselect, Mask, Password, Spinner, Progress, default as Flow } from "./Flow.js";
+export { validateIntent, ask, progress, log, result, INTENT_TYPES, isModelSchema } from "./Intent.js";

package/types/domain/SandboxModel.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @typedef {Object} SandboxData
+ * @property {string[]} [components]
+ * @property {string} [selectedComponent]
+ * @property {string} [themeFormat]
+ */
+/**
+ * Model-as-Schema for the UI Sandbox environment.
+ * Represents a tool wrapping standard OLMUI components, allowing
+ * users to inspect their models, tweak variables interactively,
+ * and export the configuration as themes for the Marketplace.
+ *
+ * Navigation uses BreadcrumbModel:
+ *   ESC = pop one level (if stack has no parent → exit app)
+ *   Ctrl+C = always exit (handled by prompts.js wrapper)
+ *
+ * URL mapping:
+ *   /sandbox             → Select Component
+ *   /sandbox/button      → Edit Button properties
+ *   /sandbox/button/export → Choose export format
+ */
+export class SandboxModel extends Model {
+    static components: {
+        help: string;
+        type: string;
+        default: never[];
+    };
+    static selectedComponent: {
+        help: string;
+        type: string;
+    };
+    static themeFormat: {
+        help: string;
+        options: string[];
+        default: string;
+    };
+    /**
+     * @param {SandboxData | any} [data]
+     */
+    constructor(data?: SandboxData | any);
+    /** @type {string[]|undefined} */ components: string[] | undefined;
+    /** @type {string|undefined} */ selectedComponent: string | undefined;
+    /** @type {string|undefined} */ themeFormat: string | undefined;
+    run(): AsyncGenerator<any, {
+        type: string;
+        data: {
+            targetComponent: string | undefined;
+            themeConfig: any;
+            exportFormat: string | undefined;
+            breadcrumb: string;
+        };
+    }, any>;
+}
+export type SandboxData = {
+    components?: string[] | undefined;
+    selectedComponent?: string | undefined;
+    themeFormat?: string | undefined;
+};
+import { Model } from '@nan0web/core';

package/types/domain/ShowcaseAppModel.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Model-as-Schema for the entire UI Sandbox Showcase.
+ * Represents a complete User Journey demonstrating all components.
+ * Showcases OLMUI Scenario Testing capabilities.
+ */
+export class ShowcaseAppModel {
+    static appName: {
+        help: string;
+        default: string;
+        type: string;
+    };
+    appName: string;
+    run(): AsyncGenerator<{
+        type: string;
+        field: string;
+        schema: {
+            help: string;
+        };
+        component: string;
+        model: any;
+    } | {
+        type: string;
+        field: string;
+        schema: {
+            help: string | undefined;
+            type: string;
+        };
+        component: string;
+        model: any;
+    } | {
+        type: string;
+        level: string;
+        message: string | undefined;
+        component: string;
+        model: any;
+    } | {
+        type: string;
+        message: string;
+        component: string;
+        model: any;
+    }, {
+        type: string;
+        data: {
+            success: boolean;
+            reason: string;
+            profile?: undefined;
+            rowsDisplayed?: undefined;
+        };
+    } | {
+        type: string;
+        data: {
+            success: boolean;
+            profile: {
+                userName: string;
+                role: string;
+                tool: string;
+            };
+            rowsDisplayed: number;
+            reason?: undefined;
+        };
+    }, unknown>;
+}