@nan0web/ui 1.0.3 → 1.0.4

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

@@ -1,29 +1,16 @@
-export default UserAppCommandMessage;
-/**
- * Extends Command.Message to include user-specific command options.
- */
-declare class UserAppCommandMessage {
-    /**
-     * 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(value: Partial<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 UserAppCommandOptions from "./Options.js";

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

@@ -1,5 +1,4 @@
-declare const _default: any;
-export default _default;
+export default CommandMessage;
 import CommandMessage from "./Message.js";
-import CommandOptions from "./Options.js";
-export { CommandMessage, CommandOptions };
+import DepsCommand from "./Message.js";
+export { CommandMessage, DepsCommand };

package/types/App/User/UserApp.d.ts

@@ -1,34 +1,41 @@
-export default UserApp;
 /**
  * UserApp requires user name and shows Welcome view.
  * If user.name is provided in command input, ignores user input.
  * User can change user data to see another Welcome view.
  */
-declare class UserApp extends CoreApp {
+export default class UserApp extends CoreApp {
     /**
      * Creates a new UserApp instance.
      * @param {Partial<CoreApp>} [props={}] - UserApp properties
      */
     constructor(props?: Partial<CoreApp>);
+    /**
+     * Handle deps command with async generator for stream processing.
+     * @param {DepsCommand} cmd - Command message with deps parameters
+     * @param {UserUI} ui - UI instance
+     * @returns {Promise<Object>} Command output
+     */
+    handleDeps(cmd: DepsCommand, ui: UserUI): Promise<any>;
     /**
      * Set user data from params.
-     * @param {Message} cmd - Command message with user data
+     * @param {UserAppCommandMessage} cmd - Command message with user data
      * @param {UserUI} ui - UI instance
      * @returns {Promise<{ message: string }>} Welcome message
      */
-    setUser(cmd: Message, ui: UserUI): Promise<{
+    setUser(cmd: UserAppCommandMessage, ui: UserUI): Promise<{
         message: string;
     }>;
     /**
      * Show welcome message for current user.
-     * @param {Message} cmd - Command message
+     * @param {UserAppCommandMessage} cmd - Command message
      * @param {UserUI} ui - UI instance
      * @returns {Promise<string[][]>} Welcome view output
      */
-    welcome(cmd: Message, ui: UserUI): Promise<string[][]>;
+    welcome(cmd: UserAppCommandMessage, ui: UserUI): Promise<string[][]>;
     user: User | undefined;
 }
 import CoreApp from "../Core/CoreApp.js";
-import { Message } from "@nan0web/co";
+import DepsCommand from "./Command/Message.js";
 import UserUI from "./UserUI.js";
+import UserAppCommandMessage from "./Command/Message.js";
 import User from "../../Model/User/User.js";

package/types/StdIn.d.ts

@@ -1,8 +1,7 @@
-export default StdIn;
 /**
  * Handles standard input stream with message buffering.
  */
-declare class StdIn extends EventProcessor {
+export default class StdIn extends EventProcessor {
     /** @type {number} Read interval in milliseconds */
     static READ_INTERVAL: number;
     /** @type {string[]} Messages to ignore */
@@ -17,14 +16,14 @@ declare class StdIn extends EventProcessor {
      * Creates a new StdIn instance.
      * @param {object} props - StdIn properties
      * @param {Processor} [props.processor] - Input processor
-     * @param {InputMessage[]} [props.stream=[]] - Initial input stream
+     * @param {UiMessage[]} [props.stream=[]] - Initial input stream
      */
     constructor(props?: {
         processor?: Processor | undefined;
-        stream?: InputMessage[] | undefined;
+        stream?: UiMessage[] | undefined;
     });
-    /** @type {InputMessage[]} Input message buffer */
-    stream: InputMessage[];
+    /** @type {UiMessage[]} Input message buffer */
+    stream: UiMessage[];
     /** @type {Processor} Input processor */
     processor: Processor;
     /**
@@ -40,9 +39,9 @@ declare class StdIn extends EventProcessor {
     /**
      * Reads a message from the input stream.
      * Waits until messages are available if stream is empty.
-     * @returns {Promise<InputMessage>} Next input message
+     * @returns {Promise<UiMessage>} Next input message
      */
-    read(): Promise<InputMessage>;
+    read(): Promise<UiMessage>;
     /**
      * Writes a message to the input stream.
      * @param {string} message - Message to write
@@ -50,13 +49,14 @@ declare class StdIn extends EventProcessor {
      */
     write(message: string): boolean;
     /**
-     * Decodes a message into an InputMessage instance.
-     * @param {InputMessage | string[] | any} message - Message to decode
-     * @returns {InputMessage} Decoded input message
+     * Decodes a message into an UiMessage instance.
+     * @param {UiMessage | string[] | any} message - Message to decode
+     * @returns {UiMessage} Decoded input message
      */
-    decode(message: InputMessage | string[] | any): InputMessage;
+    decode(message: UiMessage | string[] | any): UiMessage;
 }
 import EventProcessor from "@nan0web/event/oop";
-import InputMessage from "./core/Message/InputMessage.js";
+import { UiMessage } from "./core/index.js";
 declare class Processor extends EventProcessor {
 }
+export {};

package/types/View/View.d.ts

@@ -1,7 +1,7 @@
 /**
  * @typedef {Object} ComponentFn
  * @property {string} name
- * @property {(input: InputMessage) => Promise<any>} ask
+ * @property {(input: UiMessage) => Promise<any>} ask
  * @property {Function} bind
  */
 export default class View {
@@ -96,14 +96,14 @@ export default class View {
      */
     get(name: string): ComponentFn | undefined;
     /**
-     * @param {InputMessage} input
-     * @returns {Promise<InputMessage | null>}
+     * @param {UiMessage} input
+     * @returns {Promise<UiMessage | null>}
      */
-    ask(input: InputMessage): Promise<InputMessage | null>;
+    ask(input: UiMessage): Promise<UiMessage | null>;
 }
 export type ComponentFn = {
     name: string;
-    ask: (input: InputMessage) => Promise<any>;
+    ask: (input: UiMessage) => Promise<any>;
     bind: Function;
 };
 import StdIn from "../StdIn.js";
@@ -112,4 +112,4 @@ import Frame from "../Frame/Frame.js";
 import Locale from "../Locale.js";
 import { FrameRenderMethod } from "../Frame/Frame.js";
 import RenderOptions from "./RenderOptions.js";
-import InputMessage from "../core/Message/InputMessage.js";
+import UiMessage from "../core/Message/Message.js";

package/types/core/Form/Form.d.ts

@@ -89,12 +89,9 @@ 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(): {
-        isValid: boolean;
-        errors: any;
-    };
+    validate(): Map<string, string>;
     /**
      * Validates a single field.
      *

package/types/core/Form/Input.d.ts

@@ -64,7 +64,7 @@ export default class FormInput {
     /** @type {boolean} */ required: boolean;
     /** @type {string} */ placeholder: string;
     /** @type {InputOptions} */ options: InputOptions;
-    /** @type {Function|null} */ validation: Function | null;
+    /** @type {import("@nan0web/co").ValidateFn|null} */ validation: import("@nan0web/co").ValidateFn | null;
     /** @type {*} */ defaultValue: any;
     requireValidType(): void;
     /**

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

@@ -1,16 +1,11 @@
 /**
- * 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 {
-    /**
-     * Creates a FormMessage.
-     *
-     * @param {Object} [input={}] - Message properties.
-     */
-    constructor(input?: any);
+export default class FormMessage extends UiMessage {
     data: any;
     schema: any;
     /**
@@ -31,4 +26,4 @@ export default class FormMessage extends InputMessage {
         errors: any;
     };
 }
-import InputMessage from "../Message/InputMessage.js";
+import UiMessage from "../Message/Message.js";

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,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, 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,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,10 +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";