@nan0web/ui 1.0.2 → 1.0.4

package/types/core/Message/Message.d.ts

@@ -1,11 +1,33 @@
-export default UIMessage;
 /**
- * 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
+ *     }
+ *   }
+ * }
  */
-declare class UIMessage extends BaseMessage {
+export default class UiMessage extends Message {
     static TYPES: {
         TEXT: string;
         FORM: string;
@@ -18,14 +40,22 @@ declare class UIMessage extends BaseMessage {
         NAVIGATION: string;
     };
     /**
-     * Creates a UIMessage instance from plain data.
+     * Creates a UiMessage instance from plain data.
      *
      * @param {Object} data - Message data.
-     * @returns {UIMessage}
+     * @returns {UiMessage}
+     */
+    static from(data: any): 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 from(data: any): UIMessage;
+    static parseBody(input: any, BodyClass: Function): any;
     /**
-     * Creates a UIMessage.
+     * Creates a UiMessage.
      *
      * @param {Object} [input={}] - Message properties.
      */
@@ -35,16 +65,29 @@ declare class UIMessage extends BaseMessage {
     /** @type {string} */
     id: string;
     /**
-     * Checks if the message type is valid.
+     * Validates the message body against its schema.
      *
-     * @returns {boolean}
+     * 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.
      */
-    isValidType(): boolean;
+    validate(body?: any): Map<string, string>;
     /**
-     * Checks whether the message contains any body content.
+     * Checks if the message type is valid.
      *
      * @returns {boolean}
      */
-    isEmpty(): boolean;
+    isValidType(): boolean;
 }
-import { Message as BaseMessage } from "@nan0web/co";
+export type MessageBodySchema = {
+    required?: boolean | undefined;
+    help?: string | undefined;
+    pattern?: RegExp | undefined;
+    options?: string[] | undefined;
+    defaultValue?: any;
+    validate?: Function | undefined;
+};
+import { Message } from "@nan0web/co";

package/types/core/Message/OutputMessage.d.ts

@@ -2,9 +2,9 @@
  * 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: number;
         NORMAL: number;
@@ -27,7 +27,7 @@ export default class OutputMessage extends UIMessage {
     /** @type {number} */
     priority: number;
     /** @param {string[]|string} value */
-    set content(arg: string[]);
+    set content(value: string[] | string);
     /** @returns {string[]} */
     get content(): string[];
     /** @returns {number} */
@@ -50,4 +50,4 @@ export default class OutputMessage extends UIMessage {
      */
     toJSON(): any;
 }
-import UIMessage from "./Message.js";
+import UiMessage from "./Message.js";

package/types/core/Message/index.d.ts

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

package/types/core/Stream.d.ts

@@ -1,5 +1,6 @@
+export { StreamEntry };
 /**
- * Agnostic UI stream for processing progress.
+ * Agnostic UI stream for processing progress using async generators.
  *
  * @class UIStream
  */
@@ -13,15 +14,15 @@ export default class UIStream {
      */
     static createProcessor(signal: AbortSignal, processorFn: () => Promise<StreamEntry>): () => AsyncGenerator<StreamEntry>;
     /**
-     * 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 process(signal: AbortSignal, generator: Function, onProgress?: Function | undefined, onError?: Function | undefined, onComplete?: Function | undefined): Promise<void>;
+    static process(signal: AbortSignal, generatorFn: () => AsyncGenerator<StreamEntry>, onProgress?: Function, onError?: Function, onComplete?: Function): Promise<void>;
 }
 import StreamEntry from "./StreamEntry.js";

package/types/core/StreamEntry.d.ts

@@ -21,7 +21,7 @@ export default class StreamEntry {
         done?: boolean | undefined;
         cancelled?: boolean | undefined;
         error?: string | undefined;
-    } | undefined);
+    });
     /**
      * The value of the stream entry.
      * @type {any}

package/types/core/UiAdapter.d.ts

@@ -0,0 +1,104 @@
+/**
+ * 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: Function, options?: {
+    initialState?: any;
+    t?: Function | undefined;
+}): UIForm;
+/**
+ * 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: typeof CancelError;
+    /** @returns {typeof CancelError} */
+    get CancelError(): typeof CancelError;
+    /** @type {OutputAdapter | null} Output interface for rendering */
+    output: OutputAdapter | null;
+    /**
+     * Starts listening for input and emits an `input` event.
+     *
+     * @returns {void}
+     */
+    start(): void;
+    /**
+     * Stops listening for input and output streams.
+     * Default implementation does nothing; override in subclasses to perform cleanup.
+     *
+     * @returns {void}
+     */
+    stop(): void;
+    /**
+     * Checks whether the adapter is ready to receive input.
+     *
+     * @returns {boolean} Always true in base class; override for specific checks.
+     */
+    isReady(): boolean;
+    /**
+     * 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.
+     */
+    ask(question: string): Promise<string>;
+    /**
+     * 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.
+     */
+    select(config: {
+        options?: string[] | undefined;
+    }): Promise<{
+        index: number;
+        value: string | null;
+    }>;
+    /**
+     * 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: "..." }
+     */
+    requireInput<T extends UIMessage>(msg: T): Promise<T["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: UIMessage): void;
+}
+import UIForm from "./Form/Form.js";
+import EventProcessor from "@nan0web/event/oop";
+import CancelError from "./Error/CancelError.js";
+import UIMessage from "./Message/Message.js";

package/types/core/index.d.ts

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

package/types/index.d.ts

@@ -1,12 +1,12 @@
 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 UiAdapter } from "./core/UiAdapter.js";
 import Frame from "./Frame/Frame.js";
 import FrameProps from "./Frame/Props.js";
 import Locale from "./Locale.js";
@@ -18,3 +18,4 @@ import Model from "./Model/index.js";
 import Component from "./Component/index.js";
 import App from "./App/index.js";
 export { Frame, FrameProps, Locale, StdIn, StdOut, View, RenderOptions, Model, Component, App };
+export { default as Error, CancelError } from "./core/Error/index.js";

package/src/App/Command/Options.js

@@ -1,78 +0,0 @@
-/**
- * Represents command options with default values.
- * Provides utilities for handling command line options.
- */
-class CommandOptions {
-	/**
-	 * Default option values.
-	 * @type {object}
-	 * @property {boolean} help - Whether help is requested
-	 * @property {string} cwd - Current working directory
-	 */
-	static DEFAULTS = {
-		help: false,
-		cwd: "",
-	}
-
-	/** @type {boolean} Whether help is requested */
-	help
-
-	/** @type {string} Current working directory */
-	cwd
-
-	/**
-	 * Creates a new CommandOptions instance.
-	 * @param {object} props - The properties for command options
-	 * @param {boolean} [props.help=false] - Whether help is requested
-	 * @param {string} [props.cwd=""] - Current working directory
-	 */
-	constructor(props = {}) {
-		const {
-			help = CommandOptions.DEFAULTS.help,
-			cwd = CommandOptions.DEFAULTS.cwd,
-		} = props
-		this.help = Boolean(help)
-		this.cwd = String(cwd)
-	}
-
-	/** @type {Record<string, any>} */
-	get DEFAULTS() {
-		return /** @type {typeof CommandOptions} */ (this.constructor).DEFAULTS
-	}
-
-	/**
-	 * Checks if all options have their default values.
-	 * @returns {boolean} True if all options are at their default values, false otherwise
-	 */
-	get empty() {
-		return Object.entries(this).every(
-			([key, value]) => CommandOptions.DEFAULTS[key] === value
-		)
-	}
-
-	/**
-	 * Converts the options to a string representation.
-	 * @returns {string} String representation of the options or "<no options>" if none set
-	 */
-	toString() {
-		const opts = Object.entries(this).map(([key, value]) => {
-			if (this.DEFAULTS[key] === value) return false
-			const prefix = true === value ? "--" : "-"
-			return `${prefix}${key}${value ? ` ${value}` : ""}`
-		}).filter(Boolean)
-		if (0 === opts.length) return "<no options>"
-		return opts.join(" ")
-	}
-
-	/**
-	 * Creates a CommandOptions instance from the given props.
-	 * @param {CommandOptions|object} props - The properties to create from
-	 * @returns {CommandOptions} A CommandOptions instance
-	 */
-	static from(props) {
-		if (props instanceof CommandOptions) return props
-		return new this(props)
-	}
-}
-
-export default CommandOptions

package/src/App/Command/index.js

@@ -1,9 +0,0 @@
-import { CommandMessage } from "@nan0web/co"
-import CommandOptions from "./Options.js"
-
-export { CommandMessage, CommandOptions }
-
-export default {
-	Message: CommandMessage,
-	Options: CommandOptions,
-}

package/src/App/User/Command/Options.js

@@ -1,48 +0,0 @@
-import CommandOptions from "../../Command/Options.js"
-
-/**
- * Extends CommandOptions to include user-specific options.
- */
-class UserAppCommandOptions extends CommandOptions {
-	/**
-	 * Default option values including inherited ones.
-	 * @type {object}
-	 * @property {boolean} help - Whether help is requested
-	 * @property {string} cwd - Current working directory
-	 * @property {string} user - User name
-	 */
-	static DEFAULTS = {
-		...CommandOptions.DEFAULTS,
-		user: "",
-	}
-	
-	/** @type {string} User name */
-	user
-	
-	/**
-	 * Creates a new UserAppCommandOptions instance.
-	 * @param {object} props - Options properties
-	 * @param {boolean} [props.help=false] - Whether help is requested
-	 * @param {string} [props.cwd=""] - Current working directory
-	 * @param {string} [props.user=""] - User name
-	 */
-	constructor(props = {}) {
-		const {
-			user = UserAppCommandOptions.DEFAULTS.user,
-		} = props
-		super(props)
-		this.user = String(user)
-	}
-	
-	/**
-	 * Creates a UserAppCommandOptions instance from the given props.
-	 * @param {UserAppCommandOptions|object} props - The properties to create from
-	 * @returns {UserAppCommandOptions} A UserAppCommandOptions instance
-	 */
-	static from(props) {
-		if (props instanceof UserAppCommandOptions) return props
-		return new this(props)
-	}
-}
-
-export default UserAppCommandOptions

package/src/core/Message/InputMessage.js

@@ -1,119 +0,0 @@
-import { notEmpty } from "@nan0web/types"
-import { Message } from "@nan0web/co"
-
-/** @typedef {Message | string | null} InputMessageValue */
-
-/**
- * Represents a message input with value, options, and metadata.
- */
-export default class InputMessage {
-	static ESCAPE = String.fromCharCode(27)
-	/** @type {InputMessageValue} Input value */
-	value
-
-	/** @type {string[]} Available options for this input */
-	options
-
-	/** @type {boolean} Whether this input is waiting for response */
-	waiting
-
-	/** @type {number} Timestamp when input was created */
-	#time
-
-	/**
-	 * Creates a new InputMessage instance.
-	 * @param {object} props - Input message properties
-	 * @param {InputMessageValue} [props.value=""] - Input value
-	 * @param {string[]|string} [props.options=[]] - Available options
-	 * @param {boolean} [props.waiting=false] - Waiting state flag
-	 * @param {boolean} [props.escaped=false] - Sets value to escape when true
-	 */
-	constructor(props = {}) {
-		if ("string" === typeof props) {
-			props = { value: props }
-		}
-		const {
-			value = "",
-			waiting = false,
-			options = [],
-			escaped = false,
-		} = props
-		this.#time = Date.now()
-		this.waiting = Boolean(waiting)
-
-		// Properly handle string options by converting to array
-		this.options = Array.isArray(options) ? options.map(String) : [String(options)]
-		this.value = String(value)
-		if (!this.value && escaped) {
-			this.value = this.ESCAPE
-		}
-	}
-
-	/**
-	 * Checks if the input value is empty.
-	 * @returns {boolean} True if value is empty or null, false otherwise
-	 */
-	get empty() {
-		return null === this.value || 0 === String(this.value).length
-	}
-
-	/**
-	 * Gets the timestamp when input was created.
-	 * @returns {number} Creation timestamp
-	 */
-	get time() {
-		return this.#time
-	}
-
-	/**
-	 * Returns the escape value.
-	 * @returns {string}
-	 */
-	get ESCAPE() {
-		return /** @type {typeof InputMessage} */ (this.constructor).ESCAPE
-	}
-
-	/**
-	 * Checks if the input is an escape sequence.
-	 * @returns {boolean} True if input value is escape sequence, false otherwise
-	 */
-	get escaped() {
-		return this.ESCAPE === this.value
-	}
-
-	/**
-	 * Validates if the input has a non-empty value.
-	 * @returns {boolean} True if input is valid, false otherwise
-	 */
-	get isValid() {
-		// An input is valid only if it has a non-empty value and is not an escape sequence
-		return notEmpty(this.value) && this.value !== this.ESCAPE
-	}
-
-	/**
-	 * Converts the input to a plain object representation.
-	 * @returns {object} Object with all properties including timestamp
-	 */
-	toObject() {
-		return { ...this, time: this.time }
-	}
-
-	/**
-	 * Converts the input to a string representation including timestamp.
-	 * @returns {string} String representation with timestamp and value
-	 */
-	toString() {
-		const date = new Date(this.time)
-		return `${date.toISOString().split(".")[0]} ${this.value}`
-	}
-
-	/**
-	 * Creates an InputMessage instance from the given value.
-	 * @param {InputMessage|object|string} value - The value to create from
-	 * @returns {InputMessage} An InputMessage instance
-	 */
-	static from(value) {
-		if (value instanceof InputMessage) return value
-		return new this(value)
-	}
-}