@nan0web/ui 1.0.2 → 1.0.3

package/src/core/Message/InputMessage.js

@@ -1,14 +1,14 @@
 import { notEmpty } from "@nan0web/types"
 import { Message } from "@nan0web/co"
 
-/** @typedef {Message | string | null} InputMessageValue */
+/** @typedef {Partial<Message> | null} InputMessageValue */
 
 /**
  * Represents a message input with value, options, and metadata.
  */
 export default class InputMessage {
 	static ESCAPE = String.fromCharCode(27)
-	/** @type {InputMessageValue} Input value */
+	/** @type {Message} Input value */
 	value
 
 	/** @type {string[]} Available options for this input */
@@ -23,17 +23,17 @@ 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
 	 */
 	constructor(props = {}) {
 		if ("string" === typeof props) {
-			props = { value: props }
+			props = { value: { body: props } }
 		}
 		const {
-			value = "",
+			value = { body: "" },
 			waiting = false,
 			options = [],
 			escaped = false,
@@ -43,10 +43,7 @@ export default class InputMessage {
 
 		// 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
-		}
+		this.value = Message.from(escaped ? { body: this.ESCAPE } : value)
 	}
 
 	/**
@@ -54,6 +51,9 @@ export default class InputMessage {
 	 * @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
 	}
 
@@ -78,7 +78,7 @@ export default class InputMessage {
 	 * @returns {boolean} True if input value is escape sequence, false otherwise
 	 */
 	get escaped() {
-		return this.ESCAPE === this.value
+		return this.ESCAPE === this.value.body
 	}
 
 	/**
@@ -87,7 +87,7 @@ export default class InputMessage {
 	 */
 	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
+		return notEmpty(this.value) && this.value.body !== this.ESCAPE
 	}
 
 	/**

package/src/core/Message/OutputMessage.js

@@ -140,4 +140,4 @@ export default class OutputMessage extends UIMessage {
 		if (input instanceof OutputMessage) return input
 		return new OutputMessage(input)
 	}
-}
+}

package/src/core/index.js

@@ -11,3 +11,5 @@ export { default as OutputMessage } from "./Message/OutputMessage.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"

package/src/index.js

@@ -32,3 +32,4 @@ 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 Error, CancelError } from "./core/Error/index.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,17 +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[];
+    convertInput(rawInput: any): Message[];
     /**
      * Process input, run commands on app, and output results.
      * Supports progress callback.
@@ -45,5 +45,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

@@ -11,7 +11,7 @@ declare 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;
     /**

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

@@ -2,7 +2,7 @@ export default UserAppCommandMessage;
 /**
  * Extends Command.Message to include user-specific command options.
  */
-declare class UserAppCommandMessage extends CommandMessage {
+declare class UserAppCommandMessage {
     /**
      * Parses an array of strings into a UserAppCommandMessage.
      * @param {string[] | string} value - Arguments to parse
@@ -22,9 +22,8 @@ declare class UserAppCommandMessage extends CommandMessage {
     /**
      * @param {Partial<UserAppCommandOptions>} value
      */
-    set opts(arg: UserAppCommandOptions);
+    set opts(value: Partial<UserAppCommandOptions>);
     /** @returns {UserAppCommandOptions} */
     get opts(): UserAppCommandOptions;
 }
-import { CommandMessage } from "../../Command/index.js";
 import UserAppCommandOptions from "./Options.js";

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,7 +1,4 @@
-declare namespace _default {
-    export { CommandMessage as Message };
-    export { CommandOptions as Options };
-}
+declare const _default: any;
 export default _default;
 import CommandMessage from "./Message.js";
 import CommandOptions from "./Options.js";

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

@@ -5,27 +5,30 @@ export default UserApp;
  * User can change user data to see another Welcome view.
  */
 declare class UserApp extends CoreApp {
-    /** @type {CommandMessage} Starting command parsed from argv */
-    startCommand: CommandMessage;
+    /**
+     * Creates a new UserApp instance.
+     * @param {Partial<CoreApp>} [props={}] - UserApp properties
+     */
+    constructor(props?: Partial<CoreApp>);
     /**
      * Set user data from params.
-     * @param {CommandMessage} cmd - Command message with user data
+     * @param {Message} 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: Message, ui: UserUI): Promise<{
         message: string;
     }>;
     /**
      * Show welcome message for current user.
-     * @param {CommandMessage} cmd - Command message
+     * @param {Message} cmd - Command message
      * @param {UserUI} ui - UI instance
      * @returns {Promise<string[][]>} Welcome view output
      */
-    welcome(cmd: CommandMessage, ui: UserUI): Promise<string[][]>;
+    welcome(cmd: Message, ui: UserUI): Promise<string[][]>;
     user: User | undefined;
 }
 import CoreApp from "../Core/CoreApp.js";
-import { CommandMessage } from "./Command/index.js";
+import { Message } from "@nan0web/co";
 import UserUI from "./UserUI.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/View/View.d.ts

@@ -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;

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;
@@ -118,6 +118,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 {Function|null} */ validation: Function | 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,16 @@
 /**
- * FormMessage – specialized OutputMessage for forms.
+ * FormMessage – specialized InputMessage for forms.
  *
  * @class FormMessage
- * @extends OutputMessage
+ * @extends InputMessage
  */
-export default class FormMessage extends OutputMessage {
+export default class FormMessage extends InputMessage {
+    /**
+     * Creates a FormMessage.
+     *
+     * @param {Object} [input={}] - Message properties.
+     */
+    constructor(input?: any);
     data: any;
     schema: any;
     /**
@@ -25,4 +31,4 @@ export default class FormMessage extends OutputMessage {
         errors: any;
     };
 }
-import OutputMessage from "../Message/OutputMessage.js";
+import InputMessage from "../Message/InputMessage.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/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";

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

@@ -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} */

package/types/core/Stream.d.ts

@@ -22,6 +22,6 @@ export default class UIStream {
      * @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, generator: Function, 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/index.d.ts

@@ -7,3 +7,4 @@ export { default as OutputMessage } from "./Message/OutputMessage.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";

package/types/index.d.ts

@@ -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";