@nan0web/ui 1.0.0

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

@@ -0,0 +1,46 @@
+export default CommandOptions;
+/**
+ * Represents command options with default values.
+ * Provides utilities for handling command line options.
+ */
+declare class CommandOptions {
+    /**
+     * Default option values.
+     * @type {object}
+     * @property {boolean} help - Whether help is requested
+     * @property {string} cwd - Current working directory
+     */
+    static DEFAULTS: object;
+    /**
+     * Creates a CommandOptions instance from the given props.
+     * @param {CommandOptions|object} props - The properties to create from
+     * @returns {CommandOptions} A CommandOptions instance
+     */
+    static from(props: CommandOptions | object): CommandOptions;
+    /**
+     * Creates a new CommandOptions instance.
+     * @param {object} props - The properties for command options
+     * @param {boolean} [props.help=false] - Whether help is requested
+     * @param {string} [props.cwd=""] - Current working directory
+     */
+    constructor(props?: {
+        help?: boolean | undefined;
+        cwd?: string | undefined;
+    });
+    /** @type {boolean} Whether help is requested */
+    help: boolean;
+    /** @type {string} Current working directory */
+    cwd: string;
+    /** @type {Record<string, any>} */
+    get DEFAULTS(): Record<string, any>;
+    /**
+     * Checks if all options have their default values.
+     * @returns {boolean} True if all options are at their default values, false otherwise
+     */
+    get empty(): boolean;
+    /**
+     * Converts the options to a string representation.
+     * @returns {string} String representation of the options or "<no options>" if none set
+     */
+    toString(): string;
+}

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

@@ -0,0 +1,8 @@
+declare namespace _default {
+    export { CommandMessage as Message };
+    export { CommandOptions as Options };
+}
+export default _default;
+import { CommandMessage } from "@nan0web/co";
+import CommandOptions from "./Options.js";
+export { CommandMessage, CommandOptions };

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

@@ -0,0 +1,70 @@
+/** @typedef {Function} CommandFn */
+/**
+ * Abstract base class for all apps.
+ * Each app processes input commands and produces output.
+ */
+export default class CoreApp {
+    /**
+     * Creates a new CoreApp instance.
+     * @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
+     */
+    constructor(props?: {
+        name?: string | undefined;
+        state?: object;
+        argv?: string[] | undefined;
+    });
+    /** @type {string} App name */
+    name: string;
+    /** @type {Map<string, CommandFn>} Registered command handlers */
+    commands: Map<string, CommandFn>;
+    /** @type {object} App state */
+    state: object;
+    /** @type {CommandMessage} Starting command parsed from argv */
+    startCommand: CommandMessage;
+    /**
+     * Sets app state.
+     * @param {string|object} state - State key or object with multiple keys
+     * @param {any} [value] - State value if state is a string key
+     * @returns {object} Updated state
+     */
+    set(state: string | object, value?: any): object;
+    /**
+     * Register a command handler.
+     * @param {string} commandName - Name of the command to register
+     * @param {Function} handler - async function or sync function that accepts params and returns output
+     */
+    registerCommand(commandName: string, handler: Function): void;
+    /**
+     * Returns a string representation of the app.
+     * @returns {string} String representation including name and state
+     */
+    toString(): string;
+    /**
+     * Process a command message.
+     * @param {CommandMessage} commandMessage - 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>;
+    /**
+     * Process an array of command messages sequentially.
+     * @param {CommandMessage[]} commandMessages - 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[]>;
+    /**
+     * Select a command to run. Must be implemented by subclasses.
+     * @param {UI} ui - UI instance for interaction
+     * @returns {Promise<string>} Command name to execute
+     * @throws {Error} Always thrown as this method must be implemented by subclasses
+     */
+    selectCommand(ui: UI): Promise<string>;
+}
+export type CommandFn = Function;
+import { CommandMessage } from "../Command/index.js";
+import UI from "./UI.js";

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

@@ -0,0 +1,49 @@
+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 {
+    /**
+     * Creates a new UI instance.
+     * @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);
+    /** @type {CoreApp} The app instance connected to this UI */
+    app: CoreApp;
+    /**
+     * Convert raw input to CommandMessage array.
+     * Must be implemented by subclasses.
+     * @param {any} rawInput - Raw input to convert
+     * @returns {CommandMessage[]} Array of command messages
+     * @throws {Error} Always thrown as this method must be implemented by subclasses
+     */
+    convertInput(rawInput: any): CommandMessage[];
+    /**
+     * 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
+     */
+    show(UIProcess: ComponentFn): void;
+    /**
+     * Output results to the interface.
+     * @param {any[]} results - Results to output
+     */
+    output(results: any[]): void;
+}
+import Widget from "./Widget.js";
+import CoreApp from "./CoreApp.js";
+import { CommandMessage } from "../Command/index.js";
+import View from "../../View/View.js";

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

@@ -0,0 +1,40 @@
+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 {
+    /**
+     * Creates a new Widget instance.
+     * @param {View} [view] - View instance (default: new View())
+     */
+    constructor(view?: View | undefined);
+    /** @type {View} The view associated with this widget */
+    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
+     */
+    ask(input: InputMessage): Promise<InputMessage | null>;
+    /**
+     * @param {AsyncGenerator<StreamEntry>} stream
+     * @returns {Promise<void>}
+     */
+    read(stream: AsyncGenerator<StreamEntry>): Promise<void>;
+    /**
+     * Render output data using a view function.
+     * @param {Function|string} viewFnOrName - View function or registered view name
+     * @param {object} outputData - Typed output data instance
+     * @returns {any} Rendered output
+     * @throws {Error} If view component is not found when using string name
+     */
+    render(viewFnOrName: Function | string, outputData: object): any;
+}
+import EventProcessor from "@nan0web/event/oop";
+import View from "../../View/View.js";
+import InputMessage from "../../core/Message/InputMessage.js";
+import { StreamEntry } from "@nan0web/db";

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

@@ -0,0 +1,10 @@
+declare namespace _default {
+    export { CoreApp as App };
+    export { UI };
+    export { Widget };
+}
+export default _default;
+import CoreApp from "./CoreApp.js";
+import UI from "./UI.js";
+import Widget from "./Widget.js";
+export { CoreApp, UI };

package/types/App/Scenario.d.ts

@@ -0,0 +1,26 @@
+/** @typedef {import("./Core/CoreApp.js").default} CoreApp */
+/**
+ * Abstract Scenario class to test app logic.
+ * Scenarios run input commands and verify output.
+ */
+export default class Scenario {
+    /**
+     * Creates a new Scenario instance.
+     * @param {CoreApp} app - App instance to run scenarios against
+     * @param {UI} ui - User interface
+     * @throws {TypeError} If app is not an App.Core.App instance
+     */
+    constructor(app: CoreApp, ui: UI);
+    /** @type {CoreApp} The app to run scenarios against */
+    app: CoreApp;
+    ui: UI;
+    /**
+     * Run scenario with input commands and expected output.
+     * @param {Array<any[]>} inputCommands - Array of command arrays
+     * @param {Array<any>} expectedOutputs - Expected outputs for each command
+     * @returns {Promise<boolean>} True if all outputs match expected
+     */
+    run(inputCommands: Array<any[]>, expectedOutputs: Array<any>): Promise<boolean>;
+}
+export type CoreApp = import("./Core/CoreApp.js").default;
+import UI from "./Core/UI.js";

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

@@ -0,0 +1,30 @@
+export default UserAppCommandMessage;
+/**
+ * Extends Command.Message to include user-specific command options.
+ */
+declare class UserAppCommandMessage extends CommandMessage {
+    /**
+     * 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(arg: 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

@@ -0,0 +1,27 @@
+export default UserAppCommandOptions;
+/**
+ * Extends CommandOptions to include user-specific options.
+ */
+declare class UserAppCommandOptions extends CommandOptions {
+    /**
+     * Creates a UserAppCommandOptions instance from the given props.
+     * @param {UserAppCommandOptions|object} props - The properties to create from
+     * @returns {UserAppCommandOptions} A UserAppCommandOptions instance
+     */
+    static from(props: UserAppCommandOptions | object): UserAppCommandOptions;
+    /**
+     * Creates a new UserAppCommandOptions instance.
+     * @param {object} props - Options properties
+     * @param {boolean} [props.help=false] - Whether help is requested
+     * @param {string} [props.cwd=""] - Current working directory
+     * @param {string} [props.user=""] - User name
+     */
+    constructor(props?: {
+        help?: boolean | undefined;
+        cwd?: string | undefined;
+        user?: string | undefined;
+    });
+    /** @type {string} User name */
+    user: string;
+}
+import CommandOptions from "../../Command/Options.js";

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

@@ -0,0 +1,8 @@
+declare namespace _default {
+    export { CommandMessage as Message };
+    export { CommandOptions as Options };
+}
+export default _default;
+import CommandMessage from "./Message.js";
+import CommandOptions from "./Options.js";
+export { CommandMessage, CommandOptions };

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

@@ -0,0 +1,31 @@
+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;
+    /**
+     * Set user data from params.
+     * @param {CommandMessage} cmd - Command message with user data
+     * @param {UserUI} ui - UI instance
+     * @returns {Promise<{ message: string }>} Welcome message
+     */
+    setUser(cmd: CommandMessage, ui: UserUI): Promise<{
+        message: string;
+    }>;
+    /**
+     * Show welcome message for current user.
+     * @param {CommandMessage} cmd - Command message
+     * @param {UserUI} ui - UI instance
+     * @returns {Promise<string[][]>} Welcome view output
+     */
+    welcome(cmd: CommandMessage, ui: UserUI): Promise<string[][]>;
+    user: User | undefined;
+}
+import CoreApp from "../Core/CoreApp.js";
+import { CommandMessage } from "./Command/index.js";
+import UserUI from "./UserUI.js";
+import User from "../../Model/User/User.js";

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

@@ -0,0 +1,18 @@
+declare const UserUI_base: typeof import("../Core/UI.js").default;
+/**
+ * UserUI connects UserApp and View.
+ * It asks user for name if not provided in command input.
+ * 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

@@ -0,0 +1,12 @@
+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";
+import UserUI from "./UserUI.js";
+export { UserApp, UserUI };

package/types/App/index.d.ts

@@ -0,0 +1,14 @@
+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 };

package/types/Component/Process/Input.d.ts

@@ -0,0 +1,48 @@
+export default ProcessInput;
+/**
+ * Represents input data for the Process component.
+ * Holds configuration for rendering a progress bar.
+ */
+declare class ProcessInput {
+    /**
+     * Creates a ProcessInput instance from the given props.
+     * @param {ProcessInput|object} props - The properties to create from
+     * @returns {ProcessInput} A ProcessInput instance
+     */
+    static from(props?: ProcessInput | object): ProcessInput;
+    /**
+     * Creates a new ProcessInput instance.
+     * @param {object} props - Process input properties
+     * @param {string} [props.name="NaN•Coding"] - Process name
+     * @param {number} [props.i=0] - Current progress index
+     * @param {number} [props.top=9] - Top limit for progress normalization
+     * @param {number} [props.width=9] - Width of the progress bar
+     * @param {string} [props.space='•'] - Character for empty space
+     * @param {string} [props.char='*'] - Character for filled progress
+     */
+    constructor(props?: {
+        name?: string | undefined;
+        i?: number | undefined;
+        top?: number | undefined;
+        width?: number | undefined;
+        space?: string | undefined;
+        char?: string | undefined;
+    });
+    /** @type {string} Process name to display */
+    name: string;
+    /** @type {number} Current progress index */
+    i: number;
+    /** @type {number} Top limit for progress normalization */
+    top: number;
+    /** @type {number} Width of the progress bar */
+    width: number;
+    /** @type {string} Character to use for empty space */
+    space: string;
+    /** @type {string} Character to use for filled progress */
+    char: string;
+    /**
+     * Converts the input to a string representation.
+     * @returns {string} String representation of the ProcessInput
+     */
+    toString(): string;
+}

package/types/Component/Process/Process.d.ts

@@ -0,0 +1,13 @@
+export default Process;
+/**
+ * Renders a progress bar based on input configuration.
+ * @this {View}
+ * @param {ProcessInput|object} props - Process component properties
+ * @returns {string[][]} Rendered progress bar as array of strings
+ */
+declare function Process(this: View, props?: ProcessInput | object): string[][];
+declare namespace Process {
+    export { ProcessInput as Input };
+}
+import ProcessInput from "./Input.js";
+import View from "../../View/View.js";

package/types/Component/Process/index.d.ts

@@ -0,0 +1,4 @@
+export default Process;
+export { ProcessInput };
+import Process from "./Process.js";
+import ProcessInput from "./Input.js";

package/types/Component/Welcome/Input.d.ts

@@ -0,0 +1,34 @@
+export default WelcomeInput;
+/**
+ * Represents input data for the Welcome component.
+ * Holds user data to display in the welcome message.
+ */
+declare class WelcomeInput {
+    /**
+     * Creates a WelcomeInput instance from the given props.
+     * @param {WelcomeInput|object} props - The properties to create from
+     * @returns {WelcomeInput} A WelcomeInput instance
+     */
+    static from(props?: WelcomeInput | object): WelcomeInput;
+    /**
+     * Creates a new WelcomeInput instance.
+     * @param {object} props - Welcome input properties
+     * @param {User|object} [props.user=new User()] - User data
+     */
+    constructor(props?: {
+        user?: User | object;
+    });
+    /** @type {User} User data for welcome message */
+    user: User;
+    /**
+     * Checks if the input is empty (no user data).
+     * @returns {boolean} True if user data is empty, false otherwise
+     */
+    get empty(): boolean;
+    /**
+     * Converts the input to a string representation.
+     * @returns {string} String representation of the WelcomeInput
+     */
+    toString(): string;
+}
+import { User } from "../../Model/index.js";

package/types/Component/Welcome/Welcome.d.ts

@@ -0,0 +1,13 @@
+export default Welcome;
+/**
+ * Renders a welcome message for a user.
+ * @param {WelcomeInput|object} props - Welcome component properties
+ * @returns {string[][]} Rendered welcome message as array of strings
+ * @throws {Error} If no user data is provided
+ */
+declare function Welcome(props?: WelcomeInput | object): string[][];
+declare namespace Welcome {
+    export { WelcomeInput as Input };
+    export function ask(): Promise<string>;
+}
+import WelcomeInput from "./Input.js";

package/types/Component/Welcome/index.d.ts

@@ -0,0 +1,4 @@
+export default Welcome;
+export { WelcomeInput };
+import Welcome from "./Welcome.js";
+import WelcomeInput from "./Input.js";

package/types/Component/index.d.ts

@@ -0,0 +1,8 @@
+declare namespace _default {
+    export { Welcome };
+    export { Process };
+}
+export default _default;
+import Welcome from "./Welcome/index.js";
+import Process from "./Process/index.js";
+export { Welcome, Process };