@nan0web/ui 1.0.3 → 1.0.4

package/src/core/Form/Form.js

@@ -1,6 +1,6 @@
+import Message from "@nan0web/co"
 import FormMessage from "./Message.js"
 import FormInput from "./Input.js"
-import Message from "@nan0web/co"
 
 /**
  * Abstract form for data entry.
@@ -112,10 +112,10 @@ export default class UIForm extends FormMessage {
 	/**
 	 * Validates the entire form.
 	 *
-	 * @returns {{isValid: boolean, errors: Object}} Validation result.
+	 * @returns {Map<string, string>} Map of validation errors, empty if valid.
 	 */
 	validate() {
-		const errors = {}
+		const errors = new Map()
 		let isValid = true
 
 		this.fields.forEach((field) => {
@@ -123,7 +123,7 @@ export default class UIForm extends FormMessage {
 
 			// Required validation based on field definition or schema
 			if (field.required && (fieldValue === '' || fieldValue === null || fieldValue === undefined)) {
-				errors[field.name] = 'This field is required'
+				errors.set(field.name, 'This field is required')
 				isValid = false
 				return
 			}
@@ -132,12 +132,14 @@ export default class UIForm extends FormMessage {
 			const { isValid: fieldValid, errors: fieldErrors } = this.validateField(field.name, fieldValue)
 
 			if (!fieldValid) {
-				Object.assign(errors, fieldErrors)
+				for (const [key, err] of Object.entries(fieldErrors)) {
+					errors.set(key, err)
+				}
 				isValid = false
 			}
 		})
 
-		return { isValid, errors }
+		return errors
 	}
 
 	/**

package/src/core/Form/Input.js

@@ -27,7 +27,7 @@ export default class FormInput {
 	/** @type {boolean} */ required = false
 	/** @type {string} */ placeholder = ''
 	/** @type {InputOptions} */ options = []
-	/** @type {Function|null} */ validation = null
+	/** @type {import("@nan0web/co").ValidateFn|null} */ validation = null
 	/** @type {*} */ defaultValue = null
 
 	/**

package/src/core/Form/Message.js

@@ -1,12 +1,13 @@
-import InputMessage from "../Message/InputMessage.js"
+import UiMessage from "../Message/Message.js"
 
 /**
- * FormMessage – specialized InputMessage for forms.
+ * FormMessage – specialized UiMessage for forms.
+ * It carries form-specific data and schema for validation.
  *
  * @class FormMessage
- * @extends InputMessage
+ * @extends UiMessage
  */
-export default class FormMessage extends InputMessage {
+export default class FormMessage extends UiMessage {
 	/**
 	 * Creates a FormMessage.
 	 *
@@ -80,4 +81,4 @@ export default class FormMessage extends InputMessage {
 
 		return { isValid: Object.keys(errors).length === 0, errors }
 	}
-}
+}

package/src/core/InputAdapter.js

@@ -1,6 +1,6 @@
 import Event from "@nan0web/event/oop"
-import InputMessage from "./Message/InputMessage.js"
 import CancelError from "./Error/CancelError.js"
+import UiMessage from "./Message/Message.js"
 
 /**
  * Abstract input adapter for UI implementations.
@@ -21,7 +21,7 @@ export default class InputAdapter extends Event {
 	 */
 	start() {
 		this.emit('input',
-			InputMessage.from({ value: "Adapter started" })
+			UiMessage.from({ body: "Adapter started" })
 		)
 	}
 

package/src/core/Message/Message.js

@@ -1,12 +1,36 @@
-import { Message as BaseMessage } from "@nan0web/co"
+import { Message } from "@nan0web/co"
 
 /**
- * Base UI message class.
+ * @typedef {Object} MessageBodySchema
+ * @property {boolean} [required]
+ * @property {string} [help]
+ * @property {RegExp} [pattern]
+ * @property {string[]} [options]
+ * @property {*} [defaultValue]
+ * @property {Function} [validate]
+ */
+
+/**
+ * Base message class for UI communications.
+ * A message holds structured data (body) defined by a static Body class.
+ * It can represent commands, forms, alerts, or any UI unit.
+ *
+ * @class UiMessage
+ * @extends Message
  *
- * @class UIMessage
- * @extends BaseMessage
+ * @example
+ * class UserLoginMessage extends UiMessage {
+ *   static Body = class {
+ *     static username = { required: true, help: "Enter username" }
+ *     static password = { required: true, type: "password" }
+ *     constructor({ username = "", password = "" }) {
+ *       this.username = username
+ *       this.password = password
+ *     }
+ *   }
+ * }
  */
-class UIMessage extends BaseMessage {
+export default class UiMessage extends Message {
 	static TYPES = {
 		TEXT: 'text',
 		FORM: 'form',
@@ -25,7 +49,7 @@ class UIMessage extends BaseMessage {
 	id = ""
 
 	/**
-	 * Creates a UIMessage.
+	 * Creates a UiMessage.
 	 *
 	 * @param {Object} [input={}] - Message properties.
 	 */
@@ -45,14 +69,62 @@ class UIMessage extends BaseMessage {
 	}
 
 	/**
-	 * Creates a UIMessage instance from plain data.
+	 * Checks whether the message contains any body content.
 	 *
-	 * @param {Object} data - Message data.
-	 * @returns {UIMessage}
+	 * @returns {boolean}
 	 */
-	static from(data) {
-		if (data instanceof UIMessage) return data
-		return new this(data)
+	get empty() {
+		return !this.body
+	}
+
+	/**
+	 * Validates the message body against its schema.
+	 *
+	 * NOTE: The signature must exactly match `Message.validate` – it returns a
+	 * `Map<string,string>` regardless of the generic type, otherwise TypeScript
+	 * reports incompatibility with the base class.
+	 *
+	 * @param {any} [body=this.body] - Optional body to validate.
+	 * @returns {Map<string,string>} Map of validation errors, empty if valid.
+	 */
+	validate(body = this.body) {
+		/** @type {any} */
+		const Class = /** @type {typeof Message} */ (this.constructor).Body
+		const result = new Map()
+		const entries = /** @type {Array<[string, MessageBodySchema]>} */ (Object.entries(Class))
+
+		for (const [field, schema] of entries) {
+			const value = body[field]
+			const fn = schema?.validate
+			if ("function" === typeof fn) {
+				const ok = fn.apply(body, [value])
+				if (ok !== true) {
+					result.set(field, String(ok))
+					continue
+				}
+			}
+			const required = schema?.required ?? false
+			if (required && !value) {
+				result.set(field, "Required")
+				continue
+			}
+			if (schema?.pattern && schema.pattern instanceof RegExp) {
+				if (!schema.pattern.test(value)) {
+					result.set(field, `Does not match pattern: ${schema.pattern}`)
+					continue
+				}
+			}
+			if (schema?.options) {
+				if (!Array.isArray(schema.options)) {
+					throw new Error("Schema options must be an array of possible values")
+				}
+				if (!schema.options.includes(value)) {
+					result.set(field, "Enumeration must have one value")
+					continue
+				}
+			}
+		}
+		return result
 	}
 
 	/**
@@ -61,17 +133,35 @@ class UIMessage extends BaseMessage {
 	 * @returns {boolean}
 	 */
 	isValidType() {
-		return Object.values(UIMessage.TYPES).includes(this.type)
+		return Object.values(UiMessage.TYPES).includes(this.type)
 	}
 
 	/**
-	 * Checks whether the message contains any body content.
+	 * Creates a UiMessage instance from plain data.
 	 *
-	 * @returns {boolean}
+	 * @param {Object} data - Message data.
+	 * @returns {UiMessage}
 	 */
-	isEmpty() {
-		return !this.body || this.body.length === 0
+	static from(data) {
+		if (data instanceof UiMessage) return data
+		return new this(data)
 	}
-}
 
-export default UIMessage
+	/**
+	 * Initializes body from input using static Body schema.
+	 *
+	 * @param {Object} input - Input object.
+	 * @param {Function} BodyClass - Static body class with defaults and schema.
+	 * @returns {Object} Parsed body.
+	 */
+	static parseBody(input = {}, BodyClass) {
+		const result = {}
+		const entries = /** @type {Array<[string, MessageBodySchema]>} */ (Object.entries(BodyClass))
+
+		for (const [field, schema] of entries) {
+			const { defaultValue = undefined, ...schemaProps } = schema
+			result[field] = input[field] ?? defaultValue
+		}
+		return result
+	}
+}

package/src/core/Message/OutputMessage.js

@@ -1,12 +1,12 @@
-import UIMessage from "./Message.js"
+import UiMessage from "./Message.js"
 
 /**
  * OutputMessage – message sent from the system to the UI.
  *
  * @class OutputMessage
- * @extends UIMessage
+ * @extends UiMessage
  */
-export default class OutputMessage extends UIMessage {
+export default class OutputMessage extends UiMessage {
 	static PRIORITY = {
 		LOW: 0,
 		NORMAL: 1,
@@ -52,9 +52,9 @@ export default class OutputMessage extends UIMessage {
 		this.priority = Number(priority)
 
 		if (!this.type && this.error) {
-			this.type = UIMessage.TYPES.ERROR
+			this.type = UiMessage.TYPES.ERROR
 		} else if (!this.type) {
-			this.type = UIMessage.TYPES.INFO
+			this.type = UiMessage.TYPES.INFO
 		}
 	}
 
@@ -72,11 +72,11 @@ export default class OutputMessage extends UIMessage {
 	}
 	/** @returns {boolean} */
 	get isError() {
-		return this.error !== null || this.type === UIMessage.TYPES.ERROR
+		return this.error !== null || this.type === UiMessage.TYPES.ERROR
 	}
 	/** @returns {boolean} */
 	get isInfo() {
-		return this.type === UIMessage.TYPES.INFO || this.type === UIMessage.TYPES.SUCCESS
+		return this.type === UiMessage.TYPES.INFO || this.type === UiMessage.TYPES.SUCCESS
 	}
 
 	/**

package/src/core/Message/index.js

@@ -1,7 +1,6 @@
-import UIMessage from "./Message.js"
-import InputMessage from "./InputMessage.js"
+import UiMessage from "./Message.js"
 import OutputMessage from "./OutputMessage.js"
 
-export { UIMessage, InputMessage, OutputMessage }
+export { UiMessage, OutputMessage }
 
-export default UIMessage
+export default UiMessage

package/src/core/Stream.js

@@ -1,7 +1,9 @@
 import StreamEntry from "./StreamEntry.js"
 
+export { StreamEntry } // Export if needed
+
 /**
- * Agnostic UI stream for processing progress.
+ * Agnostic UI stream for processing progress using async generators.
  *
  * @class UIStream
  */
@@ -29,17 +31,17 @@ export default class UIStream {
 	}
 
 	/**
-	 * Runs a generator with progress callbacks and abort handling.
+	 * Runs an async generator with progress callbacks and abort handling.
 	 *
 	 * @param {AbortSignal} signal - Abort signal.
-	 * @param {Function} generator - Function returning an async iterator.
+	 * @param {() => AsyncGenerator<StreamEntry>} generatorFn - Function that returns an async generator.
 	 * @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 async process(signal, generator, onProgress, onError, onComplete) {
-		const iter = generator()
+	static async process(signal, generatorFn, onProgress, onError, onComplete) {
+		const iter = generatorFn()
 
 		try {
 			for await (const item of iter) {
@@ -47,13 +49,11 @@ export default class UIStream {
 					throw new DOMException('Aborted', 'AbortError')
 				}
 
-				if (item.progress !== undefined) {
-					onProgress?.(item.progress, item)
-				} else if (item.error) {
-					onError?.(item.error, item)
-				} else if (item.done) {
+				if (item.done) {
 					onComplete?.(item)
 					break
+				} else if (item.error) {
+					onError?.(item.error, item)
 				} else {
 					// Intermediate results
 					onProgress?.(null, item)

package/src/core/UiAdapter.js

@@ -0,0 +1,189 @@
+import EventProcessor from "@nan0web/event/oop"
+import CancelError from "./Error/CancelError.js"
+import UIMessage from "./Message/Message.js"
+import UIForm from "./Form/Form.js"
+import FormInput from "./Form/Input.js"
+
+/**
+ * Unified UI Adapter that handles both input and output operations.
+ * It manages user interactions and rendering of messages, forms, and progress.
+ *
+ * @class UiAdapter
+ * @extends EventProcessor
+ *
+ * @example
+ * const adapter = new UiAdapter()
+ * adapter.output = new View()
+ *
+ * const result = await adapter.requireInput(new LoginMessage())
+ * console.log(result) // { username: "user", password: "pass" }
+ */
+export default class UiAdapter extends EventProcessor {
+	static CancelError = CancelError
+	/** @returns {typeof CancelError} */
+	get CancelError() {
+		return /** @type {typeof UiAdapter} */ (this.constructor).CancelError
+	}
+
+	/** @type {OutputAdapter | null} Output interface for rendering */
+	output = null
+
+	/**
+	 * Starts listening for input and emits an `input` event.
+	 *
+	 * @returns {void}
+	 */
+	start() {
+		this.emit('input', UIMessage.from({ body: "Adapter started" }))
+	}
+
+	/**
+	 * Stops listening for input and output streams.
+	 * Default implementation does nothing; override in subclasses to perform cleanup.
+	 *
+	 * @returns {void}
+	 */
+	stop() {
+		// Default implementation – does nothing
+	}
+
+	/**
+	 * Checks whether the adapter is ready to receive input.
+	 *
+	 * @returns {boolean} Always true in base class; override for specific checks.
+	 */
+	isReady() {
+		return true
+	}
+
+	/**
+	 * Helper to ask a question.
+	 * Must be implemented by subclasses.
+	 *
+	 * @param {string} question - Question to ask the user.
+	 * @returns {Promise<string>} User's response.
+	 * @throws {Error} If not implemented in subclass.
+	 */
+	async ask(question) {
+		throw new Error('ask() method must be implemented in subclass')
+	}
+
+	/**
+	 * Generic selection prompt.
+	 * Must be implemented by subclasses.
+	 *
+	 * @param {object} config - Selection configuration.
+	 * @param {string[]} [config.options=[]] - List of options to choose from.
+	 * @returns {Promise<{ index: number, value: string | null }>} Selected option.
+	 * @throws {Error} If not implemented in subclass.
+	 */
+	async select(config) {
+		throw new Error('select() method must be implemented in subclass')
+	}
+
+	/**
+	 * Ensures a message's body is fully and validly filled.
+	 * Generates a form from the message's static Body schema,
+	 * then iteratively collects input until all fields are valid or cancelled.
+	 *
+	 * @template {UIMessage} T
+	 * @param {T} msg - Message instance needing input.
+	 * @returns {Promise<T['body']>} Updated and validated message body.
+	 *
+	 * @example
+	 * const body = await adapter.requireInput(new LoginMessage({ body: { username: "user" } }))
+	 * // → prompts for password, returns { username: "user", password: "..." }
+	 */
+	async requireInput(msg) {
+		if (!msg) {
+			throw new Error("Message instance is required")
+		}
+		if (!(msg instanceof UIMessage)) {
+			throw new TypeError("Message must be an instance of UIMessage")
+		}
+		/** @type {Map<string,string>} */
+		let errors = msg.validate()
+		while (errors.size > 0) {
+			const form = generateForm(
+				/** @type {any} */ (msg.constructor).Body,
+				{ initialState: msg.body }
+			)
+
+			const formResult = await this.processForm ? this.processForm(form, msg.body) : {} // Assume method exists or handle differently, but error indicates missing method; perhaps remove if not used
+			if (formResult.escaped) {
+				throw new CancelError("User cancelled form")
+			}
+
+			const updatedBody = { ...msg.body, ...formResult.form.state }
+			const updatedErrors = msg.validate(updatedBody)
+
+			if (updatedErrors.size > 0) {
+				if (this.output) {
+					await this.output.render("Alert", {
+						variant: "error",
+						content: Array.from(updatedErrors.values()).join("\n")
+					})
+				}
+				errors = updatedErrors
+				continue
+			}
+			msg.body = updatedBody
+			break
+		}
+		return msg.body
+	}
+
+	/**
+	 * Renders a message to the user interface.
+	 * Must be implemented by subclasses.
+	 *
+	 * @param {UIMessage} message - Message to render.
+	 * @emits rendered
+	 * @throws {Error} If not implemented in subclass.
+	 */
+	render(message) {
+		throw new Error("render() must be implemented by subclass")
+		this.emit("rendered", message)
+	}
+}
+
+/**
+ * Generates a UIForm from a static Body schema.
+ *
+ * @param {Function} BodyClass - Class defining field schema.
+ * @param {Object} [options={}] - Generation options.
+ * @param {Object} [options.initialState={}] - Pre-filled form values.
+ * @param {Function} [options.t] - Optional translation function.
+ * @returns {UIForm} Form instance ready for input.
+ */
+export function generateForm(BodyClass, options = {}) {
+	const { initialState = {}, t = v => v } = options
+	const fields = []
+
+	for (const [name, schema] of Object.entries(BodyClass)) {
+		if (typeof schema !== "object" || schema === null || !name || !schema.help) continue
+
+		const label = t(schema.help) || name
+		const placeholder = t(schema.placeholder || schema.defaultValue || "")
+		const isRequired = !!schema.required
+
+		fields.push(
+			new FormInput({
+				name,
+				label,
+				type: schema.type || FormInput.TYPES.TEXT,
+				required: isRequired,
+				placeholder,
+				options: schema.options ? schema.options.map(o => String(o)) : [],
+				validation: schema.validate
+					? (value) => {
+						const res = schema.validate(value)
+						return res === true ? true : typeof res === "string" ? res : `Invalid ${name}`
+					}
+					: () => true,
+			}),
+		)
+	}
+
+	return new UIForm({ fields })
+}

package/src/core/index.js

@@ -1,15 +1,12 @@
-// export default App
-
 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 UiMessage } from "./Message/Message.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"
 
 export { default as Error, CancelError } from "./Error/index.js"
+
+export { default as UiAdapter } from "./UiAdapter.js"

package/src/index.js

@@ -26,10 +26,10 @@ export {
 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"
+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"
 export { default as Error, CancelError } from "./core/Error/index.js"
+export { default as UiAdapter } from "./core/UiAdapter.js"

package/types/App/Core/UI.d.ts

@@ -22,16 +22,6 @@ declare class UI extends Widget {
      * @throws {Error} Always thrown as this method must be implemented by subclasses
      */
     convertInput(rawInput: any): Message[];
-    /**
-     * Process input, run commands on app, and output results.
-     * Supports progress callback.
-     * @emits {start} Emitted when processing begins
-     * @emits {data} Emitted for each command being processed
-     * @emits {end} Emitted when all commands have been processed
-     * @param {any} rawInput - Raw input to process
-     * @returns {Promise<any[]>} Results of command processing
-     */
-    process(rawInput: any): Promise<any[]>;
     /**
      * Sets up event handlers for UI process events.
      * @param {ComponentFn} UIProcess - Process view component

package/types/App/Core/Widget.d.ts

@@ -1,12 +1,10 @@
-export default Widget;
-export type ComponentFn = import("./UI.js").ComponentFn;
 /** @typedef {import("./UI.js").ComponentFn} ComponentFn */
 /**
  * Abstract Widget class.
  * Widget is a view with ability to input data in a specific format.
  * Input and output data are typed classes.
  */
-declare class Widget extends EventProcessor {
+export default class Widget extends EventProcessor {
     /**
      * Creates a new Widget instance.
      * @param {View} [view] - View instance (default: new View())
@@ -16,10 +14,10 @@ declare class Widget extends EventProcessor {
     view: View;
     /**
      * Ask user for input data of specific class.
-     * @param {InputMessage} input - instance of InputMessage or similar
-     * @returns {Promise<InputMessage | null>} instance of InputMessage or null
+     * @param {UiMessage} input - instance of UiMessage or similar
+     * @returns {Promise<UiMessage | null>} instance of UiMessage or null
      */
-    ask(input: InputMessage): Promise<InputMessage | null>;
+    ask(input: UiMessage): Promise<UiMessage | null>;
     /**
      * @param {AsyncGenerator<StreamEntry>} stream
      * @returns {Promise<void>}
@@ -34,7 +32,8 @@ declare class Widget extends EventProcessor {
      */
     render(viewFnOrName: Function | string, outputData: object): any;
 }
+export type ComponentFn = import("./UI.js").ComponentFn;
 import EventProcessor from "@nan0web/event/oop";
 import View from "../../View/View.js";
-import InputMessage from "../../core/Message/InputMessage.js";
+import { UiMessage } from "../../core/index.js";
 import { StreamEntry } from "@nan0web/db";