@nan0web/ui 1.6.2 → 1.7.0

package/package.json

@@ -1,86 +1,90 @@
 {
-	"name": "@nan0web/ui",
-	"version": "1.6.2",
-	"description": "NaN•Web UI. One application logic (algorithm) and many UI.",
-	"main": "src/index.js",
-	"types": "types/index.d.ts",
-	"type": "module",
-	"files": [
-		"src/**/*.js",
-		"!src/**/*.test.js",
-		"types/**/*.d.ts"
-	],
-	"scripts": {
-		"build": "tsc",
-		"play": "node play/main.js",
-		"test": "node --test --test-timeout=3333 \"src/**/*.test.js\"",
-		"test:nan0test": "node --test --test-timeout=3333 \"src/**/*.test.js\" | nan0test parse --fail",
-		"test:coverage": "node --experimental-test-coverage --test-coverage-include=\"src/**/*.js\" --test-coverage-exclude=\"src/**/*.test.js\" --test \"src/**/*.test.js\"",
-		"test:coverage:collect": "nan0test coverage",
-		"test:docs": "node --test src/README.md.js",
-		"release:spec": "node --test \"releases/**/*.spec.js\"",
-		"test:release": "node --test \"releases/**/*.test.js\"",
-		"test:status": "nan0test status --hide-name",
-		"test:play": "node --test --test-timeout=3333 \"play/**/*.test.js\"",
-		"test:e2e": "playwright test --ignore-snapshots e2e/components.spec.js e2e/debug-label.spec.js",
-		"test:e2e:slow": "E2E_SLOW=1 playwright test e2e/visual.spec.js",
-		"test:all": "npm run test && npm run test:docs && npm run test:play && npm run test:e2e && npm run build && npm run knip",
-		"knip": "knip --production",
-		"precommit": "npm test",
-		"prepush": "npm test",
-		"prepare": "husky",
-		"release": "nan0release publish",
-		"clean": "rm -rf .cache/ && rm -rf dist/",
-		"clean:modules": "rm -rf node_modules",
-		"docs:dev": "node docs/site/scripts/generate-pages.js && vite docs/site",
-		"docs:build": "node docs/site/scripts/generate-pages.js && vite build docs/site"
-	},
-	"exports": {
-		".": {
-			"import": "./src/index.js",
-			"types": "./types/index.d.ts"
-		},
-		"./components": {
-			"import": "./src/Component/index.js",
-			"types": "./types/Component/index.d.ts"
-		},
-		"./core": {
-			"import": "./src/core/index.js",
-			"types": "./types/core/index.d.ts"
-		},
-		"./cli-app": "./apps/cli/src/index.js",
-		"./mobile-app": "./apps/mobile/src/index.js",
-		"./web-app": "./apps/web/src/App.jsx"
-	},
-	"keywords": [
-		"ui",
-		"nanoweb"
-	],
-	"author": "YaRaSLove (ЯRаСлав) <support@yaro.page>",
-	"license": "ISC",
-	"packageManager": "pnpm@10.11.0",
-	"devDependencies": {
-		"@nan0web/event": "*",
-		"@nan0web/i18n": "*",
-		"@nan0web/release": "*",
-		"@nan0web/test": "*",
-		"@nan0web/ui-cli": "*",
-		"@nan0web/ui-lit": "workspace:*",
-		"@playwright/test": "^1.58.2",
-		"@rollup/plugin-yaml": "^4.1.2",
-		"@vitest/coverage-v8": "^3.2.4",
-		"husky": "^9.1.7",
-		"js-yaml": "^4.1.1",
-		"knip": "^5.83.1",
-		"lit": "^3.3.2",
-		"vite": "^6.0.0",
-		"vitest": "^3.2.4"
-	},
-	"dependencies": {
-		"@nan0web/co": "*",
-		"@nan0web/event": "*",
-		"@nan0web/log": "*",
-		"@nan0web/types": "*",
-		"string-width": "^7.2.0"
-	}
-}
+  "name": "@nan0web/ui",
+  "version": "1.7.0",
+  "description": "NaN•Web UI. One application logic (algorithm) and many UI.",
+  "main": "src/index.js",
+  "types": "types/index.d.ts",
+  "type": "module",
+  "files": [
+    "src/**/*.js",
+    "!src/**/*.test.js",
+    "types/**/*.d.ts"
+  ],
+  "exports": {
+    ".": {
+      "import": "./src/index.js",
+      "types": "./types/index.d.ts"
+    },
+    "./components": {
+      "import": "./src/Component/index.js",
+      "types": "./types/Component/index.d.ts"
+    },
+    "./core": {
+      "import": "./src/core/index.js",
+      "types": "./types/core/index.d.ts"
+    },
+    "./domain": {
+      "import": "./src/domain/index.js"
+    },
+    "./cli-app": "./apps/cli/src/index.js",
+    "./mobile-app": "./apps/mobile/src/index.js",
+    "./web-app": "./apps/web/src/App.jsx"
+  },
+  "keywords": [
+    "ui",
+    "nanoweb"
+  ],
+  "author": "YaRaSLove (ЯRаСлав) <support@yaro.page>",
+  "license": "ISC",
+  "devDependencies": {
+    "@nan0web/event": "*",
+    "@nan0web/i18n": "^1.1.0",
+    "@nan0web/release": "^1.0.2",
+    "@nan0web/test": "^1.1.3",
+    "@nan0web/ui-cli": "^2.3.0",
+    "@playwright/test": "^1.58.2",
+    "@rollup/plugin-yaml": "^4.1.2",
+    "@vitest/coverage-v8": "^3.2.4",
+    "husky": "^9.1.7",
+    "js-yaml": "^4.1.1",
+    "knip": "^5.86.0",
+    "lit": "^3.3.2",
+    "vite": "^6.4.1",
+    "vitest": "^3.2.4",
+    "@nan0web/ui-lit": "1.1.0"
+  },
+  "dependencies": {
+    "@nan0web/co": "^2.0.0",
+    "@nan0web/event": "^1.0.1",
+    "@nan0web/log": "^1.1.1",
+    "@nan0web/types": "^1.4.0",
+    "string-width": "^7.2.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "play": "node play/main.js",
+    "test:unit": "node --test --test-timeout=3333 \"src/**/*.test.js\"",
+    "test": "npm run test:unit && npm run test:ssg && npm run build",
+    "test:nan0test": "node --test --test-timeout=3333 \"src/**/*.test.js\" | nan0test parse --fail",
+    "test:coverage": "node --experimental-test-coverage --test-coverage-include=\"src/**/*.js\" --test-coverage-exclude=\"src/**/*.test.js\" --test \"src/**/*.test.js\"",
+    "test:coverage:collect": "nan0test coverage",
+    "test:docs": "node --test src/README.md.js",
+    "release:spec": "node --test \"releases/**/*.spec.js\"",
+    "test:release": "node --test \"releases/**/*.test.js\"",
+    "test:status": "nan0test status --hide-name",
+    "test:play": "node --test --test-timeout=3333 \"play/**/*.test.js\"",
+    "test:ssg": "node --test --test-timeout=5000 \"ssg/ssg.test.js\"",
+    "test:e2e": "playwright test --ignore-snapshots e2e/components.spec.js e2e/debug-label.spec.js",
+    "test:e2e:slow": "E2E_SLOW=1 playwright test e2e/visual.spec.js",
+    "test:all": "npm run test && npm run test:docs && npm run test:play && npm run test:e2e && npm run knip",
+    "knip": "knip --production",
+    "precommit": "npm test",
+    "prepush": "npm test",
+    "release": "nan0release publish",
+    "clean": "rm -rf .cache/ && rm -rf dist/",
+    "clean:modules": "rm -rf node_modules",
+    "docs:build-data": "node docs/site/scripts/generate-data.js",
+    "docs:dev": "node docs/site/scripts/generate-data.js && node docs/site/scripts/generate-pages.js && vite docs/site",
+    "docs:build": "node docs/site/scripts/generate-data.js && node docs/site/scripts/generate-pages.js && vite build docs/site"
+  }
+}

package/src/core/GeneratorRunner.js

@@ -0,0 +1,213 @@
+/**
+ * @file GeneratorRunner — Universal Adapter Loop with Timeout, Abort, and Contract Enforcement.
+ *
+ * This is the core engine that runs any OLMUI async generator (Model.run())
+ * through a set of adapter handlers. It enforces:
+ *
+ * 1. Intent validation (the "Judge" — Ярослав Мудрий).
+ * 2. Timeout / Abort support (Іван Сірко).
+ * 3. Type-safe handler dispatch (Борис Патон).
+ *
+ * Every UI Adapter (CLI, Lit, Chat, Test) uses this runner
+ * instead of writing its own while(true) loop.
+ */
+
+import { validateIntent } from './Intent.js'
+import { IntentErrorModel } from './IntentErrorModel.js'
+
+/**
+ * @typedef {Object} AdapterHandlers
+ * @property {(intent: import('./Intent.js').AskIntent) => Promise<import('./Intent.js').AskResponse>} ask
+ *   Handler for 'ask' intents. Must return { value: ... }.
+ * @property {(intent: import('./Intent.js').ProgressIntent) => void | Promise<void>} [progress]
+ *   Handler for 'progress' intents. Optional (defaults to no-op).
+ * @property {(intent: import('./Intent.js').LogIntent) => void | Promise<void>} [log]
+ *   Handler for 'log' intents. Optional (defaults to no-op).
+ * @property {(intent: import('./Intent.js').ResultIntent) => void | Promise<void>} [result]
+ *   Handler for the final 'result'. Optional (defaults to no-op).
+ */
+
+/**
+ * @typedef {Object} RunnerOptions
+ * @property {number} [timeoutMs=0]
+ *   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.
+ * @property {AbortSignal} [signal]
+ *   External AbortSignal for cancellation from outside.
+ */
+
+/**
+ * Wraps a promise with a timeout. Rejects if the promise doesn't resolve in time.
+ * If ms <= 0, timeout is disabled (promise runs without time limit).
+ *
+ * @template T
+ * @param {Promise<T>} promise
+ * @param {number} ms
+ * @param {string} label - Description for the timeout error.
+ * @returns {Promise<T>}
+ */
+function withTimeout(promise, ms, label) {
+	if (!ms || ms <= 0) return promise
+
+	return new Promise((resolve, reject) => {
+		const timer = setTimeout(() => {
+			const error = IntentErrorModel.error('timeout', { label, ms })
+			reject(error)
+		}, ms)
+
+		promise.then(
+			(val) => {
+				clearTimeout(timer)
+				resolve(val)
+			},
+			(err) => {
+				clearTimeout(timer)
+				reject(err)
+			},
+		)
+	})
+}
+
+/**
+ * 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 async function runGenerator(generator, handlers, options = {}) {
+	const { timeoutMs = 0, signal } = options
+
+	// Validate that at least 'ask' handler is provided (Ярослав Мудрий's law)
+	if (!handlers || typeof handlers.ask !== 'function') {
+		throw IntentErrorModel.error('adapter_missing_ask')
+	}
+
+	/** @type {import('./Intent.js').IntentResponse | Error | undefined} */
+	let nextVal = undefined
+
+	while (true) {
+		// ─── Check external abort signal ───
+		if (signal?.aborted) {
+			await generator.return({ type: 'result', data: null })
+			const error = IntentErrorModel.error('aborted')
+			error.name = 'AbortError'
+			throw error
+		}
+
+		let nextEvent
+		try {
+			if (nextVal instanceof Error) {
+				nextEvent = await generator.throw(nextVal)
+			} else {
+				nextEvent = await generator.next(nextVal)
+			}
+		} catch (e) {
+			// If the generator didn't catch the CancelError, we gracefully abort the runner.
+			const err = /** @type {Error} */ (e)
+			if (err.name === 'CancelError') {
+				return /** @type {T} */ (null)
+			}
+			throw e // Bubble up unexpected runtime errors
+		}
+
+		const { value: intent, done } = nextEvent
+
+		// ─── Generator completed (return statement) ───
+		if (done) {
+			if (handlers.result) {
+				await handlers.result(intent)
+			}
+			return intent?.data
+		}
+
+		// ─── Validate intent structure (the Judge) ───
+		validateIntent(intent)
+
+		// ─── Dispatch to adapter handler ───
+		switch (intent.type) {
+			case 'ask': {
+				const response = await withTimeout(
+					handlers.ask(intent),
+					timeoutMs,
+					`ask("${intent.field}")`,
+				)
+
+				// Validate response shape (Борис Патон's weld check)
+				if (!response || typeof response !== 'object' || !('value' in response)) {
+					throw IntentErrorModel.error('ask_wrong_response', {
+						field: intent.field,
+						actual: JSON.stringify(response),
+					})
+				}
+
+				// ─── Handle cancellation (ESC / back navigation) ───
+				if (response.cancelled) {
+					// Prepare CancelError to be thrown INTO the generator on the next loop iteration.
+					// This allows the Model to elegantly intercept ESC using try...catch!
+					const err = new Error('User cancelled interaction')
+					err.name = 'CancelError'
+					nextVal = err
+					break
+				}
+
+				// Run field validation if schema has a validator (the Judge again)
+				if (!intent.model) {
+					/** @type {import('./Intent.js').FieldSchema} */
+					const fieldSchema = /** @type {import('./Intent.js').FieldSchema} */ (intent.schema)
+					if (fieldSchema.validate) {
+						const validationResult = fieldSchema.validate(response.value)
+						if (validationResult !== true) {
+							throw IntentErrorModel.error('validation_failed', {
+								field: intent.field,
+								reason: validationResult,
+							})
+						}
+					}
+				}
+
+				// Instantiate Model-as-Schema class with collected data
+				if (intent.model && typeof intent.schema === 'function') {
+					const ModelClass = /** @type {new (data: any) => any} */ (intent.schema)
+					response.value = new ModelClass(response.value)
+				}
+
+				nextVal = response
+				break
+			}
+
+			case 'progress': {
+				if (handlers.progress) {
+					await handlers.progress(intent)
+				}
+				nextVal = undefined
+				break
+			}
+
+			case 'log': {
+				if (handlers.log) {
+					await handlers.log(intent)
+				}
+				nextVal = undefined
+				break
+			}
+
+			default:
+				throw IntentErrorModel.error('unhandled_intent', { type: /** @type {any} */ (intent).type })
+		}
+	}
+}

package/src/core/Intent.js

@@ -0,0 +1,168 @@
+/**
+ * @file Intent — Yield Contract Types for OLMUI Generators.
+ *
+ * Defines the strict set of intent types that a Model generator can yield,
+ * and the response shapes that Adapters must return.
+ *
+ * These types serve as the "welding contract" between Domain Models
+ * and UI Adapters (CLI, Lit, React, Chat, Test).
+ */
+
+import { IntentErrorModel } from './IntentErrorModel.js'
+
+// ─── Intent Types (Model → Adapter) ───
+
+/**
+ * @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 Types (Adapter → Model) ───
+
+/**
+ * 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).
+ */
+
+// ─── Abort Support ───
+
+/**
+ * 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])
+ *
+ * @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 = /** @type {const} */ (['ask', 'progress', 'log'])
+
+/**
+ * Detects if a value is a Model-as-Schema class (has static fields with `help`).
+ * @param {*} schema
+ * @returns {boolean}
+ */
+export function isModelSchema(schema) {
+	if (typeof schema !== 'function') return false
+	return Object.keys(schema).some((key) => {
+		const meta = schema[key]
+		return meta && typeof meta === 'object' && 'help' in meta
+	})
+}
+
+/**
+ * Validates that an object is a well-formed Intent.
+ * Throws ModelError if the intent is malformed (the "Judge").
+ *
+ * @param {*} intent
+ * @returns {intent is Intent}
+ */
+export function validateIntent(intent) {
+	if (!intent || typeof intent !== 'object') {
+		throw IntentErrorModel.error('intent_not_object', { actual: typeof intent })
+	}
+	if (!INTENT_TYPES.includes(intent.type) && intent.type !== 'result') {
+		throw IntentErrorModel.error('intent_unknown_type', {
+			type: intent.type,
+			allowed: INTENT_TYPES.join(', ') + ', result',
+		})
+	}
+	if (intent.type === 'ask') {
+		if (typeof intent.field !== 'string' || !intent.field) {
+			throw IntentErrorModel.error('ask_missing_field')
+		}
+		// Accept both: plain schema {help: '...'} and Model-as-Schema class
+		const isModel = intent.model === true
+		if (!isModel && (!intent.schema || typeof intent.schema !== 'object' || !('help' in intent.schema))) {
+			throw IntentErrorModel.error('ask_missing_schema_help')
+		}
+	}
+	if (intent.type === 'progress' || intent.type === 'log') {
+		if (typeof intent.message !== 'string') {
+			throw IntentErrorModel.error('intent_missing_message', { type: intent.type })
+		}
+	}
+	return true
+}
+
+/**
+ * Create an ask intent.
+ *
+ * Two modes:
+ *   ask('amount', { help: 'Enter amount', type: 'number' })  → single field
+ *   ask('transfer', TransferMoneyModel)                       → full Model form
+ *
+ * @param {string} field - Field name or form name.
+ * @param {object | Function} schema - Field descriptor or Model-as-Schema class.
+ * @returns {AskIntent}
+ */
+export const ask = (field, schema) => {
+	if (isModelSchema(schema)) {
+		return { type: 'ask', field, schema, model: true }
+	}
+	return { type: 'ask', field, schema }
+}
+
+export const progress = (message) => ({ type: 'progress', message })
+export const log = (level, message, data = {}) => ({ type: 'log', level, message, ...data })
+export const result = (data) => ({ type: 'result', data })

package/src/core/IntentErrorModel.js

@@ -0,0 +1,94 @@
+/**
+ * @file IntentErrorModel — Model-as-Schema for all OLMUI contract errors.
+ *
+ * All error messages in the Generator/Intent system are defined here
+ * as static fields with i18n-ready keys. No hardcoded strings in
+ * validators or runners.
+ *
+ * Pattern:
+ *   static field_name = {
+ *     help: 'Developer description (docs/IDE)',
+ *     error: 'User-facing message template with {params}',
+ *   }
+ */
+
+import { ModelError } from '@nan0web/types'
+
+export class IntentErrorModel {
+	// ─── Intent Validation Errors ───
+
+	static intent_not_object = {
+		help: 'Intent must be a valid object',
+		error: "Intent must be an object, got: '{actual}'",
+	}
+
+	static intent_unknown_type = {
+		help: 'Only ask, progress, log, result types are allowed',
+		error: "Unknown intent type: '{type}'. Allowed: {allowed}",
+	}
+
+	static ask_missing_field = {
+		help: 'AskIntent requires a field property name',
+		error: 'AskIntent requires a non-empty "field" string',
+	}
+
+	static ask_missing_schema_help = {
+		help: 'AskIntent schema must contain help for i18n',
+		error: 'AskIntent.schema must have at least a "help" property',
+	}
+
+	static intent_missing_message = {
+		help: 'Progress and Log intents require a message',
+		error: '\'{type}\' intent requires a "message" string',
+	}
+
+	// ─── Runner Contract Errors ───
+
+	static adapter_missing_ask = {
+		help: 'Every adapter must handle ask intents',
+		error:
+			'Adapter MUST provide at least an "ask" handler. This is the minimum contract for any UI adapter.',
+	}
+
+	static ask_wrong_response = {
+		help: 'Ask handler must return { value: ... }',
+		error: "ask('{field}') handler must return { value: ... }, got: {actual}",
+	}
+
+	static validation_failed = {
+		help: 'Value returned by adapter failed schema validation',
+		error: "Field '{field}' failed validation: {reason}",
+	}
+
+	static unhandled_intent = {
+		help: 'Intent type not handled by the runner dispatch',
+		error: "Unhandled intent type: '{type}'",
+	}
+
+	// ─── Timeout / Abort ───
+
+	static timeout = {
+		help: 'Adapter exceeded the allowed response time',
+		error: '{label} — adapter did not respond within {ms}ms',
+	}
+
+	static aborted = {
+		help: 'External signal cancelled the generator',
+		error: 'Generator aborted by external signal',
+	}
+
+	/**
+	 * 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, params = {}) {
+		let message = IntentErrorModel[field]?.error || field
+		for (const [key, val] of Object.entries(params)) {
+			message = message.replaceAll(`{${key}}`, String(val))
+		}
+		return new ModelError({ [field]: message })
+	}
+}