@nan0web/ui 1.0.3 → 1.1.0

package/src/core/UiAdapter.js

@@ -0,0 +1,216 @@
+import EventProcessor from "@nan0web/event/oop"
+import CancelError from "./Error/CancelError.js"
+import UIMessage from "./Message/Message.js"
+import UIForm from "./Form/Form.js"
+import FormInput from "./Form/Input.js"
+import OutputAdapter from "./OutputAdapter.js"
+import OutputMessage from "./Message/OutputMessage.js"
+
+/**
+ * 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 = CancelError
+	/** @returns {typeof CancelError} */
+	get CancelError() {
+		return /** @type {typeof UiAdapter} */ (this.constructor).CancelError
+	}
+
+	/** @type {OutputAdapter | null} Output interface for rendering */
+	output = null
+
+	/**
+	 * Starts listening for input and emits an `input` event.
+	 *
+	 * @returns {void}
+	 */
+	start() {
+		this.emit('input', UIMessage.from({ body: "Adapter started" }))
+	}
+
+	/**
+	 * Stops listening for input and output streams.
+	 * Default implementation does nothing; override in subclasses to perform cleanup.
+	 *
+	 * @returns {void}
+	 */
+	stop() {
+		// Default implementation – does nothing
+	}
+
+	/**
+	 * Checks whether the adapter is ready to receive input.
+	 *
+	 * @returns {boolean} Always true in base class; override for specific checks.
+	 */
+	isReady() {
+		return true
+	}
+
+	/**
+	 * 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.
+	 */
+	async ask(question) {
+		throw new Error('ask() method must be implemented in subclass')
+	}
+
+	/**
+	 * 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.
+	 */
+	async select(config) {
+		throw new Error('select() method must be implemented in subclass')
+	}
+
+	/**
+	 * Process a UIForm and return its result.
+	 *
+	 * This default implementation follows an **agnostic UI** approach:
+	 * it simply returns the form instance (with optional initial state merged)
+	 * without UI interaction. Concrete adapters (CLI, Web, etc.) can override
+	 * this method to render the form, collect user input and return a richer
+	 * result object (`{ form, cancelled }`).
+	 *
+	 * @param {UIForm} form - The UIForm instance to process.
+	 * @param {object} [initialState={}] - Pre‑filled values for the form.
+	 * @returns {Promise<{ form: UIForm, cancelled?: boolean }>} Form processing result.
+	 */
+	async processForm(form, initialState = {}) {
+		// Merge any provided initial state into the form's internal state.
+		if (initialState && typeof initialState === 'object') {
+			form.state = { ...form.state, ...initialState }
+		}
+		// In the agnostic baseline we do not perform any interactive I/O.
+		// Sub‑classes may provide a UI (render, ask, etc.) and return
+		// `{ form, cancelled: true/false, ... }`.
+		return { form }
+	}
+
+	/**
+	 * 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: "..." }
+	 */
+	async requireInput(msg) {
+		if (!msg) {
+			throw new Error("Message instance is required")
+		}
+		if (!(msg instanceof UIMessage)) {
+			throw new TypeError("Message must be an instance of UIMessage")
+		}
+		/** @type {Map<string,string>} */
+		let errors = msg.validate()
+		while (errors.size > 0) {
+			const form = generateForm(
+				/** @type {any} */(msg.constructor).Body,
+				{ initialState: msg.body }
+			)
+
+			const formResult = await this.processForm ? this.processForm(form, msg.body) : {} // Assume method exists or handle differently, but error indicates missing method; perhaps remove if not used
+			if (formResult.cancelled) {
+				throw new CancelError("User cancelled form")
+			}
+
+			const updatedBody = { ...msg.body, ...formResult.form.state }
+			const updatedErrors = msg.validate(updatedBody)
+
+			if (updatedErrors.size > 0) {
+				if (this.output) {
+					this.output.render(new OutputMessage({
+						type: "Alert",
+						variant: "error",
+						body: Array.from(updatedErrors.values()).join("\n")
+					}))
+				}
+				errors = updatedErrors
+				continue
+			}
+			msg.body = updatedBody
+			break
+		}
+		return msg.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) {
+		throw new Error("render() must be implemented by subclass")
+		this.emit("rendered", message)
+	}
+}
+
+/**
+ * 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, options = {}) {
+	const { initialState = {}, t = v => v } = options
+	const fields = []
+
+	for (const [name, schema] of Object.entries(BodyClass)) {
+		if (typeof schema !== "object" || schema === null || !name || !schema.help) continue
+
+		const label = t(schema.help) || name
+		const placeholder = t(schema.placeholder || schema.defaultValue || "")
+		const isRequired = !!schema.required
+
+		fields.push(
+			new FormInput({
+				name,
+				label,
+				type: schema.type || FormInput.TYPES.TEXT,
+				required: isRequired,
+				placeholder,
+				options: schema.options ? schema.options.map(o => String(o)) : [],
+				validation: schema.validate
+					? (value) => {
+						const res = schema.validate(value)
+						return res === true ? true : typeof res === "string" ? res : `Invalid ${name}`
+					}
+					: () => true,
+			}),
+		)
+	}
+
+	return new UIForm({ fields })
+}

package/src/core/index.js

@@ -1,15 +1,18 @@
-// export default App
-
 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"
+import UIStream from "./Stream.js"
+export { UIStream, UIStream as UiStream }
+import StreamEntry from "./StreamEntry.js"
+export { StreamEntry, StreamEntry as UiStreamEntry }
 
+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"
+
+import UIForm from "./Form/Form.js"
+export { UIForm, UIForm as UiForm }
 
 export { default as Error, CancelError } from "./Error/index.js"
+
+export { default as UiAdapter } from "./UiAdapter.js"

package/src/index.js

@@ -26,10 +26,10 @@ export {
 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 Error, CancelError } from "./core/Error/index.js"
+export { default as UiAdapter } from "./core/UiAdapter.js"

package/types/App/Command/DepsCommand.d.ts

@@ -0,0 +1,16 @@
+export class DepsCommand extends UiMessage {
+    static Body: typeof DepsCommandBody;
+    constructor(input?: {});
+    /** @type {DepsCommandBody} */
+    body: DepsCommandBody;
+}
+export default DepsCommand;
+import UiMessage from "../../core/Message/Message.js";
+declare class DepsCommandBody {
+    static fix: {
+        help: string;
+        defaultValue: boolean;
+    };
+    constructor(input?: {});
+    fix: boolean;
+}

package/types/App/Core/UI.d.ts

@@ -1,11 +1,9 @@
-export default UI;
-export type ComponentFn = import("../../View/View.js").ComponentFn;
 /** @typedef {import("../../View/View.js").ComponentFn} ComponentFn */
 /**
  * Abstract UI class to connect apps and widgets.
  * Supports input/output data typed classes and views.
  */
-declare class UI extends Widget {
+export default class UI extends Widget {
     /**
      * Creates a new UI instance.
      * @param {CoreApp} app - The app to connect to this UI
@@ -22,16 +20,6 @@ declare class UI extends Widget {
      * @throws {Error} Always thrown as this method must be implemented by subclasses
      */
     convertInput(rawInput: any): Message[];
-    /**
-     * Process input, run commands on app, and output results.
-     * Supports progress callback.
-     * @emits {start} Emitted when processing begins
-     * @emits {data} Emitted for each command being processed
-     * @emits {end} Emitted when all commands have been processed
-     * @param {any} rawInput - Raw input to process
-     * @returns {Promise<any[]>} Results of command processing
-     */
-    process(rawInput: any): Promise<any[]>;
     /**
      * Sets up event handlers for UI process events.
      * @param {ComponentFn} UIProcess - Process view component
@@ -43,6 +31,7 @@ declare class UI extends Widget {
      */
     output(results: any[]): void;
 }
+export type ComponentFn = import("../../View/View.js").ComponentFn;
 import Widget from "./Widget.js";
 import CoreApp from "./CoreApp.js";
 import { Message } from "@nan0web/co";

package/types/App/Core/Widget.d.ts

@@ -1,12 +1,10 @@
-export default Widget;
-export type ComponentFn = import("./UI.js").ComponentFn;
 /** @typedef {import("./UI.js").ComponentFn} ComponentFn */
 /**
  * Abstract Widget class.
  * Widget is a view with ability to input data in a specific format.
  * Input and output data are typed classes.
  */
-declare class Widget extends EventProcessor {
+export default class Widget extends EventProcessor {
     /**
      * Creates a new Widget instance.
      * @param {View} [view] - View instance (default: new View())
@@ -16,10 +14,10 @@ declare class Widget extends EventProcessor {
     view: View;
     /**
      * Ask user for input data of specific class.
-     * @param {InputMessage} input - instance of InputMessage or similar
-     * @returns {Promise<InputMessage | null>} instance of InputMessage or null
+     * @param {UiMessage} input - instance of UiMessage or similar
+     * @returns {Promise<UiMessage | null>} instance of UiMessage or null
      */
-    ask(input: InputMessage): Promise<InputMessage | null>;
+    ask(input: UiMessage): Promise<UiMessage | null>;
     /**
      * @param {AsyncGenerator<StreamEntry>} stream
      * @returns {Promise<void>}
@@ -34,7 +32,8 @@ declare class Widget extends EventProcessor {
      */
     render(viewFnOrName: Function | string, outputData: object): any;
 }
+export type ComponentFn = import("./UI.js").ComponentFn;
 import EventProcessor from "@nan0web/event/oop";
 import View from "../../View/View.js";
-import InputMessage from "../../core/Message/InputMessage.js";
+import { UiMessage } from "../../core/index.js";
 import { StreamEntry } from "@nan0web/db";

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

@@ -1,29 +1,2 @@
-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;
-}
-import UserAppCommandOptions from "./Options.js";
+export default UiMessage;
+import UiMessage from "../../../core/Message/Message.js";

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

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

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

@@ -14,8 +14,8 @@
  * @property {string} type - Input type (text, email, number, select, etc.).
  * @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} validation - Custom validation function.
+ * @property {InputOptions} options - Select options (if type is 'select').
+ * @property {Function} validation - Custom validation function.
  * @property {*} defaultValue - Default value.
  */
 export default class FormInput {
@@ -45,7 +45,7 @@ export default class FormInput {
      * @param {boolean} [props.required=false] - Is required.
      * @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=null] - Custom validation.
+     * @param {Function} [props.validation] - Custom validation.
      * @param {*} [props.defaultValue=null] - Default value.
      */
     constructor(props: {
@@ -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 {Function} */ validation: Function;
     /** @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";