@nan0web/ui 1.0.2 → 1.0.4

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

@@ -2,7 +2,15 @@ export default UserAppCommandOptions;
 /**
  * Extends CommandOptions to include user-specific options.
  */
-declare class UserAppCommandOptions extends CommandOptions {
+declare class UserAppCommandOptions {
+    /**
+     * 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: object;
     /**
      * Creates a UserAppCommandOptions instance from the given props.
      * @param {UserAppCommandOptions|object} props - The properties to create from
@@ -24,4 +32,3 @@ declare class UserAppCommandOptions extends CommandOptions {
     /** @type {string} User name */
     user: string;
 }
-import CommandOptions from "../../Command/Options.js";

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

@@ -1,8 +1,4 @@
-declare namespace _default {
-    export { CommandMessage as Message };
-    export { CommandOptions as Options };
-}
-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,31 +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 {
-    /** @type {CommandMessage} Starting command parsed from argv */
-    startCommand: CommandMessage;
+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 {CommandMessage} 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: CommandMessage, ui: UserUI): Promise<{
+    setUser(cmd: UserAppCommandMessage, ui: UserUI): Promise<{
         message: string;
     }>;
     /**
      * Show welcome message for current user.
-     * @param {CommandMessage} cmd - Command message
+     * @param {UserAppCommandMessage} cmd - Command message
      * @param {UserUI} ui - UI instance
      * @returns {Promise<string[][]>} Welcome view output
      */
-    welcome(cmd: CommandMessage, ui: UserUI): Promise<string[][]>;
+    welcome(cmd: UserAppCommandMessage, ui: UserUI): Promise<string[][]>;
     user: User | undefined;
 }
 import CoreApp from "../Core/CoreApp.js";
-import { CommandMessage } from "./Command/index.js";
+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/App/User/UserUI.d.ts

@@ -5,14 +5,5 @@ declare const UserUI_base: typeof import("../Core/UI.js").default;
  * Allows user to change user data to see another Welcome view.
  */
 export default class UserUI extends UserUI_base {
-    /**
-     * Convert raw input to CommandMessage array.
-     * If user.name provided in rawInput, use it directly.
-     * Otherwise ask user for name.
-     * @param {any} rawInput - Raw input to convert
-     * @returns {CommandMessage[]} Array of command messages
-     */
-    convertInput(rawInput: any): CommandMessage[];
 }
-import { CommandMessage } from "./Command/index.js";
 export {};

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

@@ -1,10 +1,6 @@
 declare namespace _default {
     export { UserApp as App };
     export { UserUI as UI };
-    export let Command: {
-        Message: typeof import("./Command/Message.js").default;
-        Options: typeof import("./Command/Options.js").default;
-    };
 }
 export default _default;
 import UserApp from "./UserApp.js";

package/types/App/index.d.ts

@@ -1,14 +1,12 @@
 declare namespace _default {
     export { Core };
     export { User };
-    export { Command };
     export { Scenario };
     export { UI };
 }
 export default _default;
 import Core from "./Core/index.js";
 import User from "./User/index.js";
-import Command from "./Command/index.js";
 import Scenario from "./Scenario.js";
 import UI from "./Core/UI.js";
-export { Core, User, Command, Scenario, UI };
+export { Core, User, Scenario, UI };

package/types/Frame/Frame.d.ts

@@ -85,19 +85,19 @@ export default class Frame {
      * @param {number} [lines=1] - Number of lines to move up.
      * @returns {string} ANSI escape code for cursor movement.
      */
-    static cursorUp(lines?: number | undefined): string;
+    static cursorUp(lines?: number): string;
     /**
      * Move cursor down by specified lines.
      * @param {number} [lines=1] - Number of lines to move down.
      * @returns {string} ANSI escape code for cursor movement.
      */
-    static cursorDown(lines?: number | undefined): string;
+    static cursorDown(lines?: number): string;
     /**
      * Clear the current line.
      * @param {string} [str="\r"] - String to append after clearing.
      * @returns {string} ANSI escape code for line clearing followed by the string.
      */
-    static clearLine(str?: string | undefined): string;
+    static clearLine(str?: string): string;
     /**
      * Clear the entire screen.
      * @returns {string} ANSI escape codes for screen clearing.
@@ -119,7 +119,7 @@ export default class Frame {
         imprint?: string | undefined;
         renderMethod?: string | undefined;
         defaultProps?: FrameProps | undefined;
-    } | undefined);
+    });
     /**
      * @example
      * ```js
@@ -163,7 +163,7 @@ export default class Frame {
     render(options?: {
         method?: string | undefined;
         props?: FrameProps | undefined;
-    } | undefined): string;
+    }): string;
     /**
      * Convert the frame to its string representation.
      * @returns {string} The frame's imprint.

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 {
@@ -14,7 +14,7 @@ export default class View {
      * @param {RenderOptions} [options]
      * @returns {Frame}
      */
-    static fixFrame(frame: Frame, options?: RenderOptions | undefined): Frame;
+    static fixFrame(frame: Frame, options?: RenderOptions): Frame;
     /**
      * @param {object} [input]
      * @param {StdIn} [input.stdin]
@@ -37,7 +37,7 @@ export default class View {
         windowSize?: number[] | undefined;
         components?: Map<string, ComponentFn> | undefined;
         renderMethod?: string | undefined;
-    } | undefined);
+    });
     /** @type {StdIn} */
     stdin: StdIn;
     /** @type {StdOut} */
@@ -68,7 +68,7 @@ export default class View {
      * @param {RenderOptions} [options]
      * @returns {(value: Frame|string|string[], ...args: any) => Frame}
      */
-    render(shouldRender?: number | boolean | Function | ComponentFn | undefined, options?: RenderOptions | undefined): (value: Frame | string | string[], ...args: any) => Frame;
+    render(shouldRender?: boolean | number | Function | ComponentFn, options?: RenderOptions): (value: Frame | string | string[], ...args: any) => Frame;
     clear(shouldRender?: number): Frame;
     progress(shouldRender?: boolean): (value: any) => Frame;
     t(value: any): any;
@@ -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/Error/index.d.ts

@@ -0,0 +1,6 @@
+export { CancelError };
+declare namespace _default {
+    export { CancelError };
+}
+export default _default;
+import CancelError from "./CancelError.js";

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

@@ -10,17 +10,17 @@
  */
 export default class UIForm extends FormMessage {
     /** @type {Object<string,Function>} */
-    static _validators: {
+    static _validations: {
         [x: string]: Function;
     };
     /**
-     * Register a custom validator that can be referenced by name in a schema.
+     * Register a custom validation that can be referenced by name in a schema.
      *
-     * @param {string} name - Identifier used in schema.validator.
+     * @param {string} name - Identifier used in schema.validation.
      * @param {(value:any)=>true|string} fn - Function returns true if valid,
      *   otherwise returns an error message.
      */
-    static addValidator(name: string, fn: (value: any) => true | string): void;
+    static addValidation(name: string, fn: (value: any) => true | string): void;
     /**
      * @param {*} input
      * @returns {UIForm}
@@ -42,7 +42,7 @@ export default class UIForm extends FormMessage {
      */
     static parse(data: any, overrides?: {
         [x: string]: Partial<FormInput>;
-    } | undefined): UIForm;
+    }): UIForm;
     /**
      * Create a new UIForm.
      *
@@ -57,7 +57,7 @@ export default class UIForm extends FormMessage {
         fields?: FormInput[] | undefined;
         state?: any;
         schema?: any;
-    } | undefined);
+    });
     /** @type {FormInput[]} */ fields: FormInput[];
     /** @type {Object} */ state: any;
     /** @type {string} */ title: string;
@@ -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.
      *
@@ -118,6 +115,12 @@ export default class UIForm extends FormMessage {
         isValid: boolean;
         errors: any;
     };
+    /**
+     * Serialises the form to a plain JSON object.
+     *
+     * @returns {Object}
+     */
+    toJSON(): any;
 }
 import FormMessage from "./Message.js";
 import FormInput from "./Input.js";

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

@@ -1,3 +1,10 @@
+/**
+ * @typedef {Object} Filter
+ * @property {string} [q=""]
+ * @property {number} [offset=0]
+ * @property {number} [limit=36]
+ */
+/** @typedef {Array<string> | ((filter: Filter) => Promise<string[]>)} InputOptions */
 /**
  * Form input field descriptor.
  *
@@ -8,7 +15,7 @@
  * @property {boolean} required - Whether the field is required.
  * @property {string} placeholder - Placeholder text.
  * @property {Array<string>} options - Select options (if type is 'select').
- * @property {Function|null} validator - Custom validation function.
+ * @property {Function|null} validation - Custom validation function.
  * @property {*} defaultValue - Default value.
  */
 export default class FormInput {
@@ -37,8 +44,8 @@ export default class FormInput {
      * @param {string} [props.type='text'] - Input type.
      * @param {boolean} [props.required=false] - Is required.
      * @param {string} [props.placeholder=''] - Placeholder.
-     * @param {Array<string>} [props.options=[]] - Select options.
-     * @param {Function} [props.validator=null] - Custom validator.
+     * @param {InputOptions} [props.options=[]] - Select options or async function to retrieve data with the search and page.
+     * @param {Function} [props.validation=null] - Custom validation.
      * @param {*} [props.defaultValue=null] - Default value.
      */
     constructor(props: {
@@ -47,8 +54,8 @@ export default class FormInput {
         type?: string | undefined;
         required?: boolean | undefined;
         placeholder?: string | undefined;
-        options?: string[] | undefined;
-        validator?: Function | undefined;
+        options?: InputOptions | undefined;
+        validation?: Function | undefined;
         defaultValue?: any;
     });
     /** @type {string} */ name: string;
@@ -56,8 +63,8 @@ export default class FormInput {
     /** @type {string} */ type: string;
     /** @type {boolean} */ required: boolean;
     /** @type {string} */ placeholder: string;
-    /** @type {Array<string>} */ options: Array<string>;
-    /** @type {Function|null} */ validator: Function | null;
+    /** @type {InputOptions} */ options: InputOptions;
+    /** @type {import("@nan0web/co").ValidateFn|null} */ validation: import("@nan0web/co").ValidateFn | null;
     /** @type {*} */ defaultValue: any;
     requireValidType(): void;
     /**
@@ -67,3 +74,9 @@ export default class FormInput {
      */
     toJSON(): any;
 }
+export type Filter = {
+    q?: string | undefined;
+    offset?: number | undefined;
+    limit?: number | undefined;
+};
+export type InputOptions = Array<string> | ((filter: Filter) => Promise<string[]>);

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

@@ -1,10 +1,11 @@
 /**
- * FormMessage – specialized OutputMessage for forms.
+ * FormMessage – specialized UiMessage for forms.
+ * It carries form-specific data and schema for validation.
  *
  * @class FormMessage
- * @extends OutputMessage
+ * @extends UiMessage
  */
-export default class FormMessage extends OutputMessage {
+export default class FormMessage extends UiMessage {
     data: any;
     schema: any;
     /**
@@ -25,4 +26,4 @@ export default class FormMessage extends OutputMessage {
         errors: any;
     };
 }
-import OutputMessage from "../Message/OutputMessage.js";
+import UiMessage from "../Message/Message.js";

package/types/core/InputAdapter.d.ts

@@ -6,6 +6,8 @@
  */
 export default class InputAdapter extends Event {
     static CancelError: typeof CancelError;
+    /** @returns {typeof CancelError} */
+    get CancelError(): typeof CancelError;
     /**
      * Starts listening for input and emits an `input` event.
      *

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/InputMessage.d.ts

@@ -1,4 +1,4 @@
-/** @typedef {Message | string | null} InputMessageValue */
+/** @typedef {Partial<Message> | null} InputMessageValue */
 /**
  * Represents a message input with value, options, and metadata.
  */
@@ -13,7 +13,7 @@ export default class InputMessage {
     /**
      * Creates a new InputMessage instance.
      * @param {object} props - Input message properties
-     * @param {InputMessageValue} [props.value=""] - Input value
+     * @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
@@ -24,8 +24,8 @@ export default class InputMessage {
         waiting?: boolean | undefined;
         escaped?: boolean | undefined;
     });
-    /** @type {InputMessageValue} Input value */
-    value: InputMessageValue;
+    /** @type {Message} Input value */
+    value: Message;
     /** @type {string[]} Available options for this input */
     options: string[];
     /** @type {boolean} Whether this input is waiting for response */
@@ -67,5 +67,5 @@ export default class InputMessage {
     toString(): string;
     #private;
 }
-export type InputMessageValue = Message | string | null;
+export type InputMessageValue = Partial<Message> | null;
 import { Message } from "@nan0web/co";