@nan0web/ui 1.6.2 → 1.8.0

package/src/domain/components/TableModel.js

@@ -0,0 +1,60 @@
+import { Model } from '@nan0web/core'
+
+/**
+ * @typedef {Object} TableData
+ * @property {string[]} [columns]
+ * @property {string[][]} [rows]
+ */
+
+/**
+ * Model-as-Schema for Table Data component.
+ * Displays tabular string data in rows and columns.
+ */
+export class TableModel extends Model {
+	// ==========================================
+	// 1. MODEL AS SCHEMA (Static Definition)
+	// ==========================================
+
+	static columns = {
+		help: 'Array of column headers',
+		type: 'string[]',
+		default: ['Header 1', 'Header 2'],
+	}
+
+	static rows = {
+		help: '2D Array of table cells matching column length',
+		type: 'string[][]',
+		default: [
+			['Cell 1.1', 'Cell 1.2'],
+			['Cell 2.1', 'Cell 2.2'],
+		],
+	}
+
+	/**
+	 * @param {TableData | any} [data]
+	 */
+	constructor(data = {}) {
+		super(data)
+		/** @type {string[]|undefined} */ this.columns
+		/** @type {string[][]|undefined} */ this.rows
+	}
+
+	// ==========================================
+	// 2. AGNOSTIC LOGIC (Async Generator)
+	// ==========================================
+
+	async *run() {
+		// Tables are naturally result or log displays.
+		// For an interactive flow, we could ask the user to 'select' a row,
+		// but by default a table simply presents data.
+		yield {
+			type: 'log',
+			level: 'info',
+			message: `Displaying table with ${this.rows?.length || 0} rows`,
+			component: 'Table',
+			model: /** @type {any} */ (this),
+		}
+
+		return { type: 'result', data: { rowsCount: this.rows?.length || 0 } }
+	}
+}

package/src/domain/components/ToastModel.js

@@ -0,0 +1,77 @@
+import { Model } from '@nan0web/core'
+
+/**
+ * @typedef {'success'|'error'|'info'|'warning'} ToastVariant
+ * @typedef {Object} ToastData
+ * @property {string} [message]
+ * @property {ToastVariant} [variant]
+ * @property {number} [duration]
+ * @property {boolean} [open]
+ */
+
+/**
+ * Model-as-Schema for Toast notification component.
+ * Represents a transient message displayed to the user.
+ */
+export class ToastModel extends Model {
+	// ==========================================
+	// 1. MODEL AS SCHEMA (Static Definition)
+	// ==========================================
+
+	static message = {
+		help: 'The message content of the toast',
+		default: 'Saved successfully!',
+		type: 'string',
+	}
+
+	static variant = {
+		help: 'Visual styling representing the message severity',
+		default: 'success',
+		options: ['success', 'error', 'info', 'warning'],
+	}
+
+	static duration = {
+		help: 'Time in ms before auto-dismissal. 0 to keep open indefinitely.',
+		default: 3000,
+		type: 'number',
+	}
+
+	static open = {
+		help: 'Controls visibility state',
+		default: true,
+		type: 'boolean',
+	}
+
+	/**
+	 * @param {ToastData | any} [data]
+	 */
+	constructor(data = {}) {
+		super(data)
+		/** @type {string|undefined} */ this.message
+		/** @type {ToastVariant|undefined} */ this.variant
+		/** @type {number|undefined} */ this.duration
+		/** @type {boolean|undefined} */ this.open
+	}
+
+	// ==========================================
+	// 2. AGNOSTIC LOGIC (Async Generator)
+	// ==========================================
+
+	async *run() {
+		// Maps naturally to the 'log' intent for OLMUI runners.
+		yield {
+			type: 'log',
+			level: this.variant === 'error' ? 'error' : this.variant === 'warning' ? 'warn' : 'info',
+			message: this.message,
+			component: 'Toast', // Hint for specific UI visual rendering
+			model: /** @type {any} */ (this),
+		}
+
+		// Wait exactly 'duration' ms before completing (unless duration is 0)
+		if (this.duration && this.duration > 0) {
+			await new Promise((resolve) => setTimeout(resolve, this.duration))
+		}
+
+		return { type: 'result', data: { closed: true } }
+	}
+}

package/src/domain/components/TreeModel.js

@@ -0,0 +1,53 @@
+import { Model } from '@nan0web/core'
+
+/**
+ * @typedef {Object} TreeNode
+ * @property {string} label
+ * @property {boolean} [expanded]
+ * @property {TreeNode[]} [children]
+ */
+
+/**
+ * @typedef {Object} TreeData
+ * @property {TreeNode[]} [data]
+ */
+
+/**
+ * Model-as-Schema for Tree component.
+ * Represents a hierarchical selection or navigation structure.
+ */
+export class TreeModel extends Model {
+	// ==========================================
+	// 1. MODEL AS SCHEMA (Static Definition)
+	// ==========================================
+
+	static data = {
+		help: 'Tree nodes defining the hierarchy',
+		type: 'TreeNode[]',
+		default: [],
+	}
+
+	/**
+	 * @param {TreeData | any} [data]
+	 */
+	constructor(data = {}) {
+		super(data)
+		/** @type {TreeNode[]|undefined} */ this.data
+	}
+
+	// ==========================================
+	// 2. AGNOSTIC LOGIC (Async Generator)
+	// ==========================================
+
+	async *run() {
+		const response = yield {
+			type: 'ask',
+			field: 'selectedNode',
+			schema: { help: 'Select a node from the tree' },
+			component: 'Tree',
+			model: /** @type {any} */ (this),
+		}
+
+		return { type: 'result', data: { selected: response.value } }
+	}
+}

package/src/domain/components/index.js

@@ -0,0 +1,11 @@
+// Exports for Component Models
+export { BreadcrumbModel } from './BreadcrumbModel.js'
+export { ButtonModel } from './ButtonModel.js'
+export { ConfirmModel } from './ConfirmModel.js'
+export { InputModel } from './InputModel.js'
+export { SpinnerModel } from './SpinnerModel.js'
+export { TableModel } from './TableModel.js'
+export { ToastModel } from './ToastModel.js'
+export { SelectModel } from './SelectModel.js'
+export { AutocompleteModel } from './AutocompleteModel.js'
+export { TreeModel } from './TreeModel.js'

package/src/domain/index.js

@@ -0,0 +1,17 @@
+// Domain Models — OLMUI Model-as-Schema
+export { SandboxModel } from './SandboxModel.js'
+export { ShowcaseAppModel } from './ShowcaseAppModel.js'
+export { default as Navigation } from './Navigation.js'
+
+// Component Models
+export {
+	ButtonModel,
+	ConfirmModel,
+	InputModel,
+	SpinnerModel,
+	TableModel,
+	ToastModel,
+	SelectModel,
+	AutocompleteModel,
+	TreeModel,
+} from './components/index.js'

package/src/format.js

@@ -0,0 +1,21 @@
+export const format = {
+	currency: (value, currency = 'UAH', locale = 'uk-UA') => {
+		return new Intl.NumberFormat(locale, {
+			style: 'currency',
+			currency,
+			maximumFractionDigits: 0
+		}).format(value).replace(/,/g, ' ')
+	},
+	rate: (value, locale = 'uk-UA') => {
+		const rate = value < 1 ? value * 100 : value
+		return new Intl.NumberFormat(locale, {
+			style: 'percent',
+			maximumFractionDigits: 2
+		}).format(rate / 100)
+	},
+	number: (value, locale = 'uk-UA') => {
+		return new Intl.NumberFormat(locale, {
+			maximumFractionDigits: 2
+		}).format(value).replace(/,/g, ' ')
+	}
+}

package/src/index.js

@@ -10,6 +10,7 @@ import Component from './Component/index.js'
 import App from './App/index.js'
 
 export { Frame, FrameProps, Locale, StdIn, StdOut, View, RenderOptions, Model, Component, App }
+export { format } from './format.js'
 
 // export default App
 export { default as FormMessage } from './core/Form/Message.js'
@@ -22,3 +23,8 @@ export { default as UiMessage } from './core/Message/Message.js'
 export { default as UiStream } from './core/Stream.js'
 export { default as Error, CancelError } from './core/Error/index.js'
 export { default as UiAdapter } from './core/UiAdapter.js'
+
+// OLMUI Generator Engine
+export { validateIntent, ask, progress, log, result, INTENT_TYPES, isModelSchema } from './core/Intent.js'
+export { IntentErrorModel } from './core/IntentErrorModel.js'
+export { runGenerator } from './core/GeneratorRunner.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;