@nan0web/ui 1.0.3 → 1.1.0

package/types/core/Intent.d.ts

@@ -0,0 +1,91 @@
+/**
+ * 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.
+ *
+ * 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)
+ *
+ * @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";

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;
@@ -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,5 @@
 /**
- * Agnostic UI stream for processing progress.
+ * Agnostic UI stream for processing progress using async generators.
  *
  * @class UIStream
  */
@@ -13,15 +13,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, onError?: Function, onComplete?: Function): 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/UiAdapter.d.ts

@@ -0,0 +1,122 @@
+/**
+ * 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;
+    }>;
+    /**
+     * Process a UIForm and return its result.
+     *
+     * This default implementation follows an **agnostic UI** approach:
+     * it simply returns the form instance (with optional initial state merged)
+     * without UI interaction. Concrete adapters (CLI, Web, etc.) can override
+     * this method to render the form, collect user input and return a richer
+     * result object (`{ form, cancelled }`).
+     *
+     * @param {UIForm} form - The UIForm instance to process.
+     * @param {object} [initialState={}] - Pre‑filled values for the form.
+     * @returns {Promise<{ form: UIForm, cancelled?: boolean }>} Form processing result.
+     */
+    processForm(form: UIForm, initialState?: object): Promise<{
+        form: UIForm;
+        cancelled?: boolean;
+    }>;
+    /**
+     * 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 OutputAdapter from "./OutputAdapter.js";
+import UIMessage from "./Message/Message.js";

package/types/core/index.d.ts

@@ -1,10 +1,11 @@
 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";
+import UIStream from "./Stream.js";
+import StreamEntry from "./StreamEntry.js";
+import UIForm from "./Form/Form.js";
+export { UIStream, UIStream as UiStream, StreamEntry, StreamEntry as UiStreamEntry, UIForm, UIForm as UiForm };
 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";

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 {Partial<Message> | null} InputMessageValue */
-
-/**
- * Represents a message input with value, options, and metadata.
- */
-export default class InputMessage {
-	static ESCAPE = String.fromCharCode(27)
-	/** @type {Message} 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=null] - 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: { body: props } }
-		}
-		const {
-			value = { body: "" },
-			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 = Message.from(escaped ? { body: this.ESCAPE } : value)
-	}
-
-	/**
-	 * Checks if the input value is empty.
-	 * @returns {boolean} True if value is empty or null, false otherwise
-	 */
-	get empty() {
-		if (this.value instanceof Message) {
-			return this.value.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.body
-	}
-
-	/**
-	 * 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.body !== 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)
-	}
-}