@nan0web/ui 1.0.0

package/src/App/Core/UI.js

@@ -0,0 +1,116 @@
+import View from "../../View/View.js"
+import CoreApp from "./CoreApp.js"
+import Widget from "./Widget.js"
+import { notEmpty } from "@nan0web/types"
+import { CommandMessage } from "../Command/index.js"
+
+/** @typedef {import("../../View/View.js").ComponentFn} ComponentFn */
+
+/**
+ * Abstract UI class to connect apps and widgets.
+ * Supports input/output data typed classes and views.
+ */
+class UI extends Widget {
+	/** @type {CoreApp} The app instance connected to this UI */
+	app
+
+	/**
+	 * 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, view = new View()) {
+		super(view)
+		this.app = app
+	}
+
+	/**
+	 * 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) {
+		throw new Error("convertInput must be implemented by subclass")
+	}
+
+	/**
+	 * 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
+	 */
+	async process(rawInput) {
+		const commands = this.convertInput(rawInput).filter(notEmpty)
+		const results = []
+		let count = commands.length
+
+		const proc = this.view.get("UIProcess")
+		if (proc) {
+			this.show(proc)
+		}
+
+		if (0 === count && this.app.selectCommand) {
+			const answer = await this.app.selectCommand(this)
+			if (answer) {
+				const [input] = this.convertInput(rawInput)
+				const cmd = new CommandMessage({
+					argv: [answer],
+					opts: input?.opts ?? {},
+				})
+				commands.push(cmd)
+				++count
+			} else {
+				this.emit("end", { commands, results })
+				return results
+			}
+		}
+		this.emit("start", { commands })
+		for (let i = 0; i < count; i++) {
+			const command = commands[i]
+			this.emit("data", { i, count, command })
+			const result = await this.app.processCommand(command, this)
+			results.push(result)
+		}
+		this.emit("end", { commands, results })
+		// this.output(results)
+		return results
+	}
+
+	/**
+	 * Sets up event handlers for UI process events.
+	 * @param {ComponentFn} UIProcess - Process view component
+	 */
+	show(UIProcess) {
+		if (!UIProcess) return
+		const onStart = () => {
+			// this.view.render(UIProcess)
+		}
+		const onData = () => {
+
+		}
+		const onEnd = () => {
+
+		}
+
+		this.on("start", onStart)
+		this.on("data", onData)
+		this.on("end", onEnd)
+	}
+
+	/**
+	 * Output results to the interface.
+	 * @param {any[]} results - Results to output
+	 */
+	output(results) {
+		results.forEach(result => {
+			this.view.info(JSON.stringify(result))
+		})
+	}
+}
+
+export default UI

package/src/App/Core/Widget.js

@@ -0,0 +1,67 @@
+import EventProcessor from "@nan0web/event/oop"
+import View from "../../View/View.js"
+import InputMessage from "../../core/Message/InputMessage.js"
+import { StreamEntry } from "@nan0web/db"
+
+/** @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.
+ */
+class Widget extends EventProcessor {
+	/** @type {View} The view associated with this widget */
+	view
+
+	/**
+	 * Creates a new Widget instance.
+	 * @param {View} [view] - View instance (default: new View())
+	 */
+	constructor(view = new View()) {
+		super()
+		this.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
+	 */
+	async ask(input) {
+		return await this.view.ask(input)
+	}
+
+	/**
+	 * @param {AsyncGenerator<StreamEntry>} stream
+	 * @returns {Promise<void>}
+	 */
+	async read(stream) {
+		for await (const entry of stream) {
+			this.view.progress(true)(entry)
+		}
+	}
+
+	/**
+	 * 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, outputData) {
+		/** @type {Function | ComponentFn | undefined} */
+		const viewFn = typeof viewFnOrName === "string"
+			? this.view.get(viewFnOrName)
+			: viewFnOrName
+
+		if (!viewFn) {
+			throw new Error([
+				"View component not found", ": ", viewFnOrName
+			].join(""))
+		}
+		return this.view.render(viewFn)(outputData)
+	}
+}
+
+export default Widget

package/src/App/Core/index.js

@@ -0,0 +1,11 @@
+import CoreApp from "./CoreApp.js"
+import UI from "./UI.js"
+import Widget from "./Widget.js"
+
+export { CoreApp, UI }
+
+export default {
+	App: CoreApp,
+	UI,
+	Widget,
+}

package/src/App/Scenario.js

@@ -0,0 +1,45 @@
+import App from "./index.js"
+import UI from "./Core/UI.js"
+
+/** @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 {
+	/** @type {CoreApp} The app to run scenarios against */
+	app
+
+	/**
+	 * 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, ui) {
+		if (!(app instanceof App.Core.App)) {
+			throw new TypeError("Scenario requires a App.Core.App instance")
+		}
+		this.app = app
+		this.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
+	 */
+	async run(inputCommands, expectedOutputs) {
+		const commandMessages = inputCommands.map(arr => App.Command.Message.parse(arr))
+		const outputs = await this.app.processCommands(commandMessages, this.ui)
+		if (outputs.length !== expectedOutputs.length) return false
+		for (let i = 0; i < outputs.length; i++) {
+			if (JSON.stringify(outputs[i]) !== JSON.stringify(expectedOutputs[i])) {
+				return false
+			}
+		}
+		return true
+	}
+}

package/src/App/User/Command/Message.js

@@ -0,0 +1,44 @@
+import { CommandMessage } from "../../Command/index.js"
+import UserAppCommandOptions from "./Options.js"
+
+/**
+ * Extends Command.Message to include user-specific command options.
+ */
+class UserAppCommandMessage extends CommandMessage {
+	/**
+	 * 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 = {}) {
+		super(props)
+	}
+
+	/** @returns {UserAppCommandOptions} */
+	get opts() {
+		return UserAppCommandOptions.from(super.opts)
+	}
+
+	/**
+	 * @param {Partial<UserAppCommandOptions>} value
+	 */
+	set opts(value) {
+		super.opts = UserAppCommandOptions.from(value)
+	}
+
+	/**
+	 * Parses an array of strings into a UserAppCommandMessage.
+	 * @param {string[] | string} value - Arguments to parse
+	 * @returns {UserAppCommandMessage} Parsed command message
+	 */
+	static parse(value = []) {
+		if ("string" === typeof value) {
+			value = value.split(" ")
+		}
+		const result = super.parse(value)
+		return new this(result)
+	}
+}
+
+export default UserAppCommandMessage

package/src/App/User/Command/Options.js

@@ -0,0 +1,48 @@
+import CommandOptions from "../../Command/Options.js"
+
+/**
+ * Extends CommandOptions to include user-specific options.
+ */
+class UserAppCommandOptions extends CommandOptions {
+	/**
+	 * 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 = {
+		...CommandOptions.DEFAULTS,
+		user: "",
+	}
+	
+	/** @type {string} User name */
+	user
+	
+	/**
+	 * 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 = {}) {
+		const {
+			user = UserAppCommandOptions.DEFAULTS.user,
+		} = props
+		super(props)
+		this.user = String(user)
+	}
+	
+	/**
+	 * 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) {
+		if (props instanceof UserAppCommandOptions) return props
+		return new this(props)
+	}
+}
+
+export default UserAppCommandOptions

package/src/App/User/Command/index.js

@@ -0,0 +1,11 @@
+import Command from "../../Command/index.js"
+import CommandMessage from "./Message.js"
+import CommandOptions from "./Options.js"
+
+export { CommandMessage, CommandOptions }
+
+export default {
+	...Command,
+	Message: CommandMessage,
+	Options: CommandOptions,
+}

package/src/App/User/UserApp.js

@@ -0,0 +1,73 @@
+import { notEmpty } from "@nan0web/types"
+import CoreApp from "../Core/CoreApp.js"
+import Command, { CommandMessage } from "./Command/index.js"
+import User from "../../Model/User/User.js"
+import UserUI from "./UserUI.js"
+import InputMessage from "../../core/Message/InputMessage.js"
+
+/**
+ * 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.
+ */
+class UserApp extends CoreApp {
+	/** @type {CommandMessage} Starting command parsed from argv */
+	startCommand
+
+	/** @type {object} App state */
+	state
+
+	/**
+	 * Creates a new UserApp instance.
+	 * @param {object} props - UserApp properties
+	 * @param {string} [props.name="UserApp"] - App name
+	 * @param {object} [props.state={}] - Initial state object
+	 * @param {string[]} [props.argv=[]] - Command line arguments to parse
+	 */
+	constructor(props = {}) {
+		super(props)
+		const {
+			argv = [],
+			state = {},
+		} = props
+		this.state = state
+		this.startCommand = CommandMessage.parse(argv)
+		this.registerCommand("setUser", this.setUser.bind(this))
+		this.registerCommand("welcome", this.welcome.bind(this))
+	}
+
+	/**
+	 * Set user data from params.
+	 * @param {CommandMessage} cmd - Command message with user data
+	 * @param {UserUI} ui - UI instance
+	 * @returns {Promise<{ message: string }>} Welcome message
+	 */
+	async setUser(cmd, ui) {
+		this.state.user = User.from(cmd.opts.user)
+		const frame = await this.welcome(cmd, ui)
+		return {
+			message: String(frame)
+		}
+	}
+
+	/**
+	 * Show welcome message for current user.
+	 * @param {CommandMessage} cmd - Command message
+	 * @param {UserUI} ui - UI instance
+	 * @returns {Promise<string[][]>} Welcome view output
+	 */
+	async welcome(cmd, ui) {
+		if (cmd.opts.user) {
+			const user = User.from(cmd.opts.user)
+			return ui.render("Welcome", { user })
+		}
+		if (notEmpty(this.user)) {
+			return ui.render("Welcome", { user: this.user })
+		}
+		const answer = await ui.ask(InputMessage.from("What is your name?"))
+		this.user = User.from(answer?.value)
+		return ui.render("Welcome", { user: this.user })
+	}
+}
+
+export default UserApp

package/src/App/User/UserApp.test.js

@@ -0,0 +1,56 @@
+import { describe, it } from "node:test"
+import { strict as assert } from "node:assert"
+import UserApp from "./UserApp.js"
+import View from "../../View/View.js"
+import UserUI from "./UserUI.js"
+import Command from "./Command/index.js"
+import Frame from "../../Frame/Frame.js"
+
+describe("UserApp", () => {
+	/** @type {UserApp} */
+	let app
+	/** @type {View} */
+	let view
+	/** @type {UserUI} */
+	let ui
+
+	it("should set user and welcome", async () => {
+		app = new UserApp()
+		view = new View()
+		view.register("Welcome", (input) => {
+			return ["Welcome " + input.user.name]
+		})
+		ui = new UserUI(app, view)
+		const cmd = Command.Message.parse("setUser --user Alice")
+		const result = await app.processCommand(cmd, ui)
+		assert.equal(String(result.message), Frame.CLEAR_LINE + "\r" + "Welcome Alice")
+	})
+
+	it("should welcome with user", async () => {
+		app = new UserApp()
+		view = new View()
+		view.register("Welcome", (input) => {
+			return ["Welcome " + input.user.name]
+		})
+		ui = new UserUI(app, view)
+		const cmd = Command.Message.parse("welcome --user YaRa")
+		const result = await app.processCommand(cmd, ui)
+		assert.equal(String(result), Frame.CLEAR_LINE + "\r" + "Welcome YaRa")
+	})
+
+	it("should ask for a user name and welcome with user", async () => {
+		app = new UserApp()
+		view = new View()
+		view.register("Welcome", (input) => {
+			return ["Welcome " + input.user.name]
+		})
+		ui = new UserUI(app, view)
+		const cmd = Command.Message.parse("welcome")
+
+		// Mock the stdin to provide input immediately
+		view.stdin.write("Alice\n")
+
+		const result = await app.processCommand(cmd, ui)
+		assert.equal(String(result), Frame.CLEAR_LINE + "\r" + "Welcome Alice\n")
+	})
+})

package/src/App/User/UserUI.js

@@ -0,0 +1,20 @@
+import App from "../Core/index.js"
+import { CommandMessage } from "./Command/index.js"
+
+/**
+ * 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 App.UI {
+	/**
+	 * 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) {
+		return [CommandMessage.parse(rawInput)]
+	}
+}

package/src/App/User/UserUI.test.js

@@ -0,0 +1,51 @@
+import { describe, it } from "node:test"
+import { strict as assert } from "node:assert"
+import UserApp from "./UserApp.js"
+import UserUI from "./UserUI.js"
+import View from "../../View/View.js"
+import InputMessage from "../../core/Message/InputMessage.js"
+import Welcome from "../../Component/Welcome/index.js"
+
+describe("UserUI", () => {
+	it("should convert input with user.name to commands", () => {
+		const app = new UserApp()
+		const view = new View()
+		const ui = new UserUI(app, view)
+
+		const commands = ui.convertInput("setUser --user Bob welcome")
+		assert.equal(commands.length, 1)
+		assert.equal(commands[0].args[0], "setUser")
+		assert.equal(commands[0].args[1], "welcome")
+		assert.equal(commands[0].opts.user, "Bob")
+	})
+
+	it("should convert input without user.name to askUserName command", () => {
+		const app = new UserApp()
+		const view = new View()
+		const ui = new UserUI(app, view)
+
+		const commands = ui.convertInput("")
+		assert.equal(commands.length, 1)
+		assert.equal(commands[0].args.length, 0)
+		assert.equal(commands[0].opts.user, "")
+	})
+
+	it("should process askUserName command interactively", async () => {
+		const app = new UserApp()
+		const view = new View()
+		const ui = new UserUI(app, view)
+		view.register("Welcome", Welcome)
+
+		// Mock view.ask to return a name
+		view.ask = (input) => Promise.resolve(new InputMessage("Charlie"))
+		// Mock output to collect outputs
+		const outputs = []
+		ui.output = (results) => outputs.push(...results)
+
+		const results = await ui.process(["welcome"])
+		assert.ok(view.ask)
+		assert.equal(results.length, 1)
+		assert.ok(results[0].value[0][0].includes("Welcome"))
+		assert.ok(view.stdout.stream[0].includes("Welcome Charlie!"))
+	})
+})

package/src/App/User/index.js

@@ -0,0 +1,15 @@
+import UserApp from "./UserApp.js"
+import UserUI from "./UserUI.js"
+import UserCommand from "./Command/index.js"
+import Command from "../Command/index.js"
+
+export { UserApp, UserUI }
+
+export default {
+	App: UserApp,
+	UI: UserUI,
+	Command: {
+		...Command,
+		...UserCommand,
+	},
+}

package/src/App/index.js

@@ -0,0 +1,22 @@
+import Command from "./Command/index.js"
+import Scenario from "./Scenario.js"
+import UI from "./Core/UI.js"
+
+import Core from "./Core/index.js"
+import User from "./User/index.js"
+
+export {
+	Core,
+	User,
+	Command,
+	Scenario,
+	UI,
+}
+
+export default {
+	Core,
+	User,
+	Command,
+	Scenario,
+	UI,
+}

package/src/Component/Process/Input.js

@@ -0,0 +1,70 @@
+/**
+ * Represents input data for the Process component.
+ * Holds configuration for rendering a progress bar.
+ */
+class ProcessInput {
+	/** @type {string} Process name to display */
+	name
+	
+	/** @type {number} Current progress index */
+	i
+	
+	/** @type {number} Top limit for progress normalization */
+	top
+	
+	/** @type {number} Width of the progress bar */
+	width
+	
+	/** @type {string} Character to use for empty space */
+	space
+	
+	/** @type {string} Character to use for filled progress */
+	char
+	
+	/**
+	 * 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 = {}) {
+		const {
+			name = "NaN•Coding",
+			i = 0,
+			top = 9,
+			width = 9,
+			space = '•',
+			char = '*'
+		} = props
+		this.name = name
+		this.i = i
+		this.top = top
+		this.width = width
+		this.space = space
+		this.char = char
+	}
+	
+	/**
+	 * Converts the input to a string representation.
+	 * @returns {string} String representation of the ProcessInput
+	 */
+	toString() {
+		return `ProcessInput(name=${this.name}, i=${this.i}, top=${this.top}, width=${this.width}, space=${this.space}, char=${this.char})`
+	}
+	
+	/**
+	 * 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 = {}) {
+		if (props instanceof ProcessInput) return props
+		return new ProcessInput(props)
+	}
+}
+
+export default ProcessInput

package/src/Component/Process/Process.js

@@ -0,0 +1,26 @@
+import ProcessInput from "./Input.js"
+import View from "../../View/View.js"
+
+/**
+ * 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
+ */
+function Process(props = {}) {
+	const input = ProcessInput.from(props)
+	const valid = input.top || 1
+	const per = (input.i > valid ? valid : input.i) / valid
+	const done = per * input.width
+	const bar = input.char.repeat(done) + input.space.repeat(input.width - done)
+	// Provide empty options object to satisfy Locale.format signature
+	const format = this.locale.format(Number, {})
+	const num = format ? format(100 * per) : 100 * per
+	return [
+		[`I am ${input.name} ${bar} ${num}`]
+	]
+}
+
+Process.Input = ProcessInput
+
+export default Process

package/src/Component/Process/index.js

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