@nan0web/ui 1.1.0 → 1.3.0

package/types/core/Flow.d.ts

@@ -0,0 +1,320 @@
+/**
+ * Component types that can be yielded from a Flow.
+ *
+ * @typedef {'view' | 'prompt' | 'stream' | 'action' | 'flow'} ComponentType
+ */
+/**
+ * Base interface for all UI components.
+ *
+ * @typedef {Object} FlowComponent
+ * @property {ComponentType} type - Component type discriminator.
+ * @property {string} [name] - Optional component name for debugging.
+ */
+/**
+ * Static view component (no user input required).
+ * Examples: Alert, Badge, Toast, Table, Text
+ *
+ * @typedef {Object} ViewComponent
+ * @property {'view'} type - Always 'view'.
+ * @property {string} name - Component name (e.g., 'Alert', 'Toast').
+ * @property {Object} props - Component-specific properties.
+ */
+/**
+ * Interactive prompt component (requires user input).
+ * Examples: Input, Select, Confirm, Multiselect, Mask
+ *
+ * @typedef {Object} PromptComponent
+ * @property {'prompt'} type - Always 'prompt'.
+ * @property {string} name - Component name (e.g., 'Select', 'Input').
+ * @property {Object} props - Component-specific properties.
+ * @property {string} [props.message] - Prompt message to display.
+ * @property {any[]} [props.choices] - Options for Select/Multiselect.
+ * @property {Function} [props.validate] - Validation function.
+ */
+/**
+ * Streaming component for progress/async operations.
+ * Examples: Spinner, ProgressBar, StreamChunk
+ *
+ * @typedef {Object} StreamComponent
+ * @property {'stream'} type - Always 'stream'.
+ * @property {string} name - Component name (e.g., 'Spinner', 'Progress').
+ * @property {Object} props - Component-specific properties.
+ * @property {AsyncIterable} [iterable] - Async iterator for streaming content.
+ */
+/**
+ * Action component for physical or side-effect operations.
+ * Examples: Move, Sound, Light, Notify
+ *
+ * @typedef {Object} ActionComponent
+ * @property {'action'} type - Always 'action'.
+ * @property {string} name - Component name (e.g., 'Move', 'Beep').
+ * @property {Object} props - Component-specific properties.
+ */
+/**
+ * Result returned by prompt components.
+ *
+ * @typedef {Object} PromptResult
+ * @property {any} value - The value entered/selected by user.
+ * @property {boolean} [cancelled] - True if user cancelled the prompt.
+ */
+/**
+ * Adapter interface that all platform adapters must implement.
+ *
+ * @typedef {Object} FlowAdapter
+ * @property {(component: ViewComponent) => void | Promise<void>} renderView
+ *   Renders a static view component.
+ * @property {(component: PromptComponent) => Promise<PromptResult>} executePrompt
+ *   Execute an interactive prompt and returns user input.
+ * @property {(component: StreamComponent) => AsyncIterable} streamProgress
+ *   Handles streaming components.
+ * @property {(component: ActionComponent) => Promise<any>} [executeAction]
+ *   Executes an action component (physical or side-effect).
+ */
+/**
+ * Creates a View component.
+ *
+ * @param {string} name - Component name (e.g., 'Alert', 'Toast').
+ * @param {Object} props - Component properties.
+ * @returns {ViewComponent}
+ *
+ * @example
+ * yield View('Alert', { variant: 'success', message: 'Done!' })
+ */
+export function View(name: string, props?: any): ViewComponent;
+/**
+ * Creates a Prompt component.
+ *
+ * @param {string} name - Component name (e.g., 'Select', 'Input').
+ * @param {Object} props - Component properties.
+ * @returns {PromptComponent}
+ *
+ * @example
+ * const value = yield Prompt('Select', { message: 'Choose:', choices: ['a', 'b'] })
+ */
+export function Prompt(name: string, props?: any): PromptComponent;
+/**
+ * Creates a Stream component.
+ *
+ * @param {string} name - Component name (e.g., 'Spinner', 'Progress').
+ * @param {Object} props - Component properties.
+ * @returns {StreamComponent}
+ *
+ * @example
+ * yield* Stream('Progress', { total: 100, current: 50 })
+ */
+export function Stream(name: string, props?: any): StreamComponent;
+/**
+ * Creates an Action component.
+ *
+ * @param {string} name - Action name.
+ * @param {Object} props - Action properties.
+ * @returns {ActionComponent}
+ */
+export function Action(name: string, props?: any): ActionComponent;
+/**
+ * Runs a Flow (async generator) with the provided adapter.
+ *
+ * The Flow runner iterates through yielded components and dispatches them
+ * to the appropriate adapter method based on component type.
+ *
+ * @param {AsyncGenerator} flow - The flow generator to execute.
+ * @param {FlowAdapter} adapter - The platform-specific adapter.
+ * @param {Object} [options={}] - Additional options.
+ * @param {AbortSignal} [options.signal] - Abort signal for cancellation.
+ * @returns {Promise<any>} The final return value of the flow.
+ *
+ * @example
+ * async function* loginFlow() {
+ *     yield Alert({ message: 'Welcome!' })
+ *     const username = yield Input({ message: 'Username:' })
+ *     const password = yield Password({ message: 'Password:' })
+ *     return { username, password }
+ * }
+ *
+ * const result = await runFlow(loginFlow(), cliAdapter)
+ */
+export function runFlow(flow: AsyncGenerator, adapter: FlowAdapter, options?: {
+    signal?: AbortSignal | undefined;
+}): Promise<any>;
+/**
+ * Wraps a nested flow for composition with yield*.
+ *
+ * @param {Function} flowFn - Flow generator function.
+ * @param {...any} args - Arguments to pass to the flow function.
+ * @returns {Object} A flow component.
+ *
+ * @example
+ * async function* mainFlow() {
+ *     yield Alert({ message: 'Starting...' })
+ *     const user = yield* flow(loginFlow)
+ *     yield Alert({ message: `Welcome, ${user.name}!` })
+ * }
+ */
+export function flow(flowFn: Function, ...args: any[]): any;
+export function Alert(props: any): ViewComponent;
+export function Toast(props: any): ViewComponent;
+export function Badge(props: any): ViewComponent;
+export function Text(props: any): ViewComponent;
+export function Table(props: any): ViewComponent;
+export function Input(props: any): PromptComponent;
+export function Select(props: any): PromptComponent;
+export function Confirm(props: any): PromptComponent;
+export function Multiselect(props: any): PromptComponent;
+export function Mask(props: any): PromptComponent;
+export function Password(props: any): PromptComponent;
+export function Spinner(props: any): StreamComponent;
+export function Progress(props: any): StreamComponent;
+export function Beep(props: any): ActionComponent;
+export function Move(props: any): ActionComponent;
+declare namespace _default {
+    export { runFlow };
+    export { flow };
+    export { View };
+    export { Prompt };
+    export { Stream };
+    export { Alert };
+    export { Toast };
+    export { Badge };
+    export { Text };
+    export { Table };
+    export { Input };
+    export { Select };
+    export { Confirm };
+    export { Multiselect };
+    export { Mask };
+    export { Password };
+    export { Spinner };
+    export { Progress };
+}
+export default _default;
+/**
+ * Component types that can be yielded from a Flow.
+ */
+export type ComponentType = "view" | "prompt" | "stream" | "action" | "flow";
+/**
+ * Base interface for all UI components.
+ */
+export type FlowComponent = {
+    /**
+     * - Component type discriminator.
+     */
+    type: ComponentType;
+    /**
+     * - Optional component name for debugging.
+     */
+    name?: string | undefined;
+};
+/**
+ * Static view component (no user input required).
+ * Examples: Alert, Badge, Toast, Table, Text
+ */
+export type ViewComponent = {
+    /**
+     * - Always 'view'.
+     */
+    type: "view";
+    /**
+     * - Component name (e.g., 'Alert', 'Toast').
+     */
+    name: string;
+    /**
+     * - Component-specific properties.
+     */
+    props: any;
+};
+/**
+ * Interactive prompt component (requires user input).
+ * Examples: Input, Select, Confirm, Multiselect, Mask
+ */
+export type PromptComponent = {
+    /**
+     * - Always 'prompt'.
+     */
+    type: "prompt";
+    /**
+     * - Component name (e.g., 'Select', 'Input').
+     */
+    name: string;
+    /**
+     * - Component-specific properties.
+     */
+    props: {
+        message?: string | undefined;
+        choices?: any[] | undefined;
+        validate?: Function | undefined;
+    };
+};
+/**
+ * Streaming component for progress/async operations.
+ * Examples: Spinner, ProgressBar, StreamChunk
+ */
+export type StreamComponent = {
+    /**
+     * - Always 'stream'.
+     */
+    type: "stream";
+    /**
+     * - Component name (e.g., 'Spinner', 'Progress').
+     */
+    name: string;
+    /**
+     * - Component-specific properties.
+     */
+    props: any;
+    /**
+     * - Async iterator for streaming content.
+     */
+    iterable?: AsyncIterable<any> | undefined;
+};
+/**
+ * Action component for physical or side-effect operations.
+ * Examples: Move, Sound, Light, Notify
+ */
+export type ActionComponent = {
+    /**
+     * - Always 'action'.
+     */
+    type: "action";
+    /**
+     * - Component name (e.g., 'Move', 'Beep').
+     */
+    name: string;
+    /**
+     * - Component-specific properties.
+     */
+    props: any;
+};
+/**
+ * Result returned by prompt components.
+ */
+export type PromptResult = {
+    /**
+     * - The value entered/selected by user.
+     */
+    value: any;
+    /**
+     * - True if user cancelled the prompt.
+     */
+    cancelled?: boolean | undefined;
+};
+/**
+ * Adapter interface that all platform adapters must implement.
+ */
+export type FlowAdapter = {
+    /**
+     *   Renders a static view component.
+     */
+    renderView: (component: ViewComponent) => void | Promise<void>;
+    /**
+     *   Execute an interactive prompt and returns user input.
+     */
+    executePrompt: (component: PromptComponent) => Promise<PromptResult>;
+    /**
+     *   Handles streaming components.
+     */
+    streamProgress: (component: StreamComponent) => AsyncIterable<any>;
+    /**
+     * Executes an action component (physical or side-effect).
+     */
+    executeAction?: ((component: ActionComponent) => Promise<any>) | undefined;
+};

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

@@ -122,5 +122,5 @@ export default class UIForm extends FormMessage {
      */
     toJSON(): any;
 }
-import FormMessage from "./Message.js";
-import FormInput from "./Input.js";
+import FormMessage from './Message.js';
+import FormInput from './Input.js';

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

@@ -16,6 +16,7 @@
  * @property {string} placeholder - Placeholder text.
  * @property {InputOptions} options - Select options (if type is 'select').
  * @property {Function} validation - Custom validation function.
+ * @property {string} mask - Mask pattern (e.g. '###-###').
  * @property {*} defaultValue - Default value.
  */
 export default class FormInput {
@@ -29,6 +30,13 @@ export default class FormInput {
         SELECT: string;
         CHECKBOX: string;
         TEXTAREA: string;
+        PASSWORD: string;
+        SECRET: string;
+        MASK: string;
+        CONFIRM: string;
+        TOGGLE: string;
+        MULTISELECT: string;
+        AUTOCOMPLETE: string;
     };
     /**
      * @param {*} input
@@ -46,6 +54,7 @@ export default class FormInput {
      * @param {string} [props.placeholder=''] - Placeholder.
      * @param {InputOptions} [props.options=[]] - Select options or async function to retrieve data with the search and page.
      * @param {Function} [props.validation] - Custom validation.
+     * @param {string} [props.mask=''] - Mask pattern.
      * @param {*} [props.defaultValue=null] - Default value.
      */
     constructor(props: {
@@ -56,6 +65,7 @@ export default class FormInput {
         placeholder?: string | undefined;
         options?: InputOptions | undefined;
         validation?: Function | undefined;
+        mask?: string | undefined;
         defaultValue?: any;
     });
     /** @type {string} */ name: string;
@@ -65,6 +75,7 @@ export default class FormInput {
     /** @type {string} */ placeholder: string;
     /** @type {InputOptions} */ options: InputOptions;
     /** @type {Function} */ validation: Function;
+    /** @type {string} */ mask: string;
     /** @type {*} */ defaultValue: any;
     requireValidType(): void;
     /**

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

@@ -26,4 +26,4 @@ export default class FormMessage extends UiMessage {
         errors: any;
     };
 }
-import UiMessage from "../Message/Message.js";
+import UiMessage from '../Message/Message.js';

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

@@ -1,5 +1,5 @@
 export default Form;
-import FormInput from "./Input.js";
-import FormMessage from "./Message.js";
-import Form from "./Form.js";
+import FormInput from './Input.js';
+import FormMessage from './Message.js';
+import Form from './Form.js';
 export { FormInput, FormMessage, Form };

package/types/core/InputAdapter.d.ts

@@ -42,5 +42,5 @@ export default class InputAdapter extends Event {
         value: string | null;
     }>;
 }
-import Event from "@nan0web/event/oop";
-import CancelError from "./Error/CancelError.js";
+import Event from '@nan0web/event/oop';
+import CancelError from './Error/CancelError.js';

package/types/core/Intent.d.ts

@@ -18,74 +18,71 @@
  * }
  */
 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;
+	/**
+	 * 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>;
+	/**
+	 * 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";
+export default Intent
+import { Message } from '@nan0web/co'

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

@@ -3,69 +3,69 @@
  * Represents a message input with value, options, and metadata.
  */
 export default class InputMessage {
-    static ESCAPE: string;
-    /**
-     * 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: InputMessage | object | string): InputMessage;
-    /**
-     * 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?: {
-        value?: InputMessageValue | undefined;
-        options?: string | string[] | undefined;
-        waiting?: boolean | undefined;
-        escaped?: boolean | undefined;
-    });
-    /** @type {Message} Input value */
-    value: Message;
-    /** @type {string[]} Available options for this input */
-    options: string[];
-    /** @type {boolean} Whether this input is waiting for response */
-    waiting: boolean;
-    /**
-     * Checks if the input value is empty.
-     * @returns {boolean} True if value is empty or null, false otherwise
-     */
-    get empty(): boolean;
-    /**
-     * Gets the timestamp when input was created.
-     * @returns {number} Creation timestamp
-     */
-    get time(): number;
-    /**
-     * Returns the escape value.
-     * @returns {string}
-     */
-    get ESCAPE(): string;
-    /**
-     * Checks if the input is an escape sequence.
-     * @returns {boolean} True if input value is escape sequence, false otherwise
-     */
-    get escaped(): boolean;
-    /**
-     * Validates if the input has a non-empty value.
-     * @returns {boolean} True if input is valid, false otherwise
-     */
-    get isValid(): boolean;
-    /**
-     * Converts the input to a plain object representation.
-     * @returns {object} Object with all properties including timestamp
-     */
-    toObject(): object;
-    /**
-     * Converts the input to a string representation including timestamp.
-     * @returns {string} String representation with timestamp and value
-     */
-    toString(): string;
-    #private;
+	static ESCAPE: string
+	/**
+	 * 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: InputMessage | object | string): InputMessage
+	/**
+	 * 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?: {
+		value?: InputMessageValue | undefined
+		options?: string | string[] | undefined
+		waiting?: boolean | undefined
+		escaped?: boolean | undefined
+	})
+	/** @type {Message} Input value */
+	value: Message
+	/** @type {string[]} Available options for this input */
+	options: string[]
+	/** @type {boolean} Whether this input is waiting for response */
+	waiting: boolean
+	/**
+	 * Checks if the input value is empty.
+	 * @returns {boolean} True if value is empty or null, false otherwise
+	 */
+	get empty(): boolean
+	/**
+	 * Gets the timestamp when input was created.
+	 * @returns {number} Creation timestamp
+	 */
+	get time(): number
+	/**
+	 * Returns the escape value.
+	 * @returns {string}
+	 */
+	get ESCAPE(): string
+	/**
+	 * Checks if the input is an escape sequence.
+	 * @returns {boolean} True if input value is escape sequence, false otherwise
+	 */
+	get escaped(): boolean
+	/**
+	 * Validates if the input has a non-empty value.
+	 * @returns {boolean} True if input is valid, false otherwise
+	 */
+	get isValid(): boolean
+	/**
+	 * Converts the input to a plain object representation.
+	 * @returns {object} Object with all properties including timestamp
+	 */
+	toObject(): object
+	/**
+	 * Converts the input to a string representation including timestamp.
+	 * @returns {string} String representation with timestamp and value
+	 */
+	toString(): string
+	#private
 }
-export type InputMessageValue = Partial<Message> | null;
-import { Message } from "@nan0web/co";
+export type InputMessageValue = Partial<Message> | null
+import { Message } from '@nan0web/co'