@nan0web/ui 1.0.2 → 1.0.4

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
 	}
 
 	/**
@@ -140,4 +140,4 @@ export default class OutputMessage extends UIMessage {
 		if (input instanceof OutputMessage) return input
 		return new OutputMessage(input)
 	}
-}
+}

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,13 +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,9 +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/CoreApp.d.ts

@@ -9,12 +9,12 @@ export default class CoreApp {
      * @param {object} props - CoreApp properties
      * @param {string} [props.name="CoreApp"] - App name
      * @param {object} [props.state={}] - Initial state object
-     * @param {string[]} [props.argv=[]] - Command line arguments to parse
+     * @param {Message} [props.startCommand=new Message()] - Command line arguments to parse
      */
     constructor(props?: {
         name?: string | undefined;
         state?: object;
-        argv?: string[] | undefined;
+        startCommand?: Message | undefined;
     });
     /** @type {string} App name */
     name: string;
@@ -22,8 +22,8 @@ export default class CoreApp {
     commands: Map<string, CommandFn>;
     /** @type {object} App state */
     state: object;
-    /** @type {CommandMessage} Starting command parsed from argv */
-    startCommand: CommandMessage;
+    /** @type {Message} Starting command parsed from argv */
+    startCommand: Message;
     /**
      * Sets app state.
      * @param {string|object} state - State key or object with multiple keys
@@ -44,19 +44,19 @@ export default class CoreApp {
     toString(): string;
     /**
      * Process a command message.
-     * @param {CommandMessage} commandMessage - Command to process
+     * @param {Message} msg - Command to process
      * @param {UI} ui - UI instance to use for rendering
      * @returns {Promise<any>} Output of the command
      * @throws {Error} If the command is not registered
      */
-    processCommand(commandMessage: CommandMessage, ui: UI): Promise<any>;
+    processCommand(msg: Message, ui: UI): Promise<any>;
     /**
      * Process an array of command messages sequentially.
-     * @param {CommandMessage[]} commandMessages - Array of commands to process
+     * @param {Message[]} Messages - Array of commands to process
      * @param {UI} ui - UI instance to use for rendering
      * @returns {Promise<any[]>} Array of command outputs
      */
-    processCommands(commandMessages: CommandMessage[], ui: UI): Promise<any[]>;
+    processCommands(Messages: Message[], ui: UI): Promise<any[]>;
     /**
      * Select a command to run. Must be implemented by subclasses.
      * @param {UI} ui - UI instance for interaction
@@ -66,5 +66,5 @@ export default class CoreApp {
     selectCommand(ui: UI): Promise<string>;
 }
 export type CommandFn = Function;
-import { CommandMessage } from "../Command/index.js";
+import { Message } from "@nan0web/co";
 import UI from "./UI.js";

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

@@ -11,27 +11,17 @@ declare class UI extends Widget {
      * @param {CoreApp} app - The app to connect to this UI
      * @param {View} [view] - View instance for rendering (default: new View())
      */
-    constructor(app: CoreApp, view?: View | undefined);
+    constructor(app: CoreApp, view?: View);
     /** @type {CoreApp} The app instance connected to this UI */
     app: CoreApp;
     /**
-     * Convert raw input to CommandMessage array.
+     * Convert raw input to Message array.
      * Must be implemented by subclasses.
      * @param {any} rawInput - Raw input to convert
-     * @returns {CommandMessage[]} Array of command messages
+     * @returns {Message[]} Array of command messages
      * @throws {Error} Always thrown as this method must be implemented by subclasses
      */
-    convertInput(rawInput: any): CommandMessage[];
-    /**
-     * 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[]>;
+    convertInput(rawInput: any): Message[];
     /**
      * Sets up event handlers for UI process events.
      * @param {ComponentFn} UIProcess - Process view component
@@ -45,5 +35,5 @@ declare class UI extends Widget {
 }
 import Widget from "./Widget.js";
 import CoreApp from "./CoreApp.js";
-import { CommandMessage } from "../Command/index.js";
+import { Message } from "@nan0web/co";
 import View from "../../View/View.js";

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

@@ -1,25 +1,23 @@
-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())
      */
-    constructor(view?: View | undefined);
+    constructor(view?: View);
     /** @type {View} The view associated with this widget */
     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";

package/types/App/User/Command/Message.d.ts

@@ -1,30 +1,16 @@
-export default UserAppCommandMessage;
-/**
- * Extends Command.Message to include user-specific command options.
- */
-declare class UserAppCommandMessage extends CommandMessage {
-    /**
-     * Parses an array of strings into a UserAppCommandMessage.
-     * @param {string[] | string} value - Arguments to parse
-     * @returns {UserAppCommandMessage} Parsed command message
-     */
-    static parse(value?: string[] | string): UserAppCommandMessage;
-    /**
-     * Creates a new UserAppCommandMessage instance.
-     * @param {object} props - Command message properties
-     * @param {string[]} [props.args=[]] - Command arguments
-     * @param {Partial<UserAppCommandOptions>} [props.opts={}] - User-specific options
-     */
-    constructor(props?: {
-        args?: string[] | undefined;
-        opts?: Partial<UserAppCommandOptions> | undefined;
-    });
-    /**
-     * @param {Partial<UserAppCommandOptions>} value
-     */
-    set opts(arg: UserAppCommandOptions);
-    /** @returns {UserAppCommandOptions} */
-    get opts(): UserAppCommandOptions;
+export class DepsCommand extends UIMessage {
+    static Body: typeof DepsCommandParams;
+    constructor(input?: {});
+    /** @type {DepsCommandParams} */
+    body: DepsCommandParams;
+}
+export default DepsCommand;
+import UIMessage from "../../../core/Message/Message.js";
+declare class DepsCommandParams {
+    static fix: {
+        help: string;
+        defaultValue: boolean;
+    };
+    constructor(input?: {});
+    fix: boolean;
 }
-import { CommandMessage } from "../../Command/index.js";
-import UserAppCommandOptions from "./Options.js";