@nan0web/ui-cli 1.0.2 → 1.1.0

package/src/InputAdapter.js

@@ -1,36 +1,128 @@
 /**
- * CLIInputAdapter – bridges UI‑CLI utilities with generic UI core.
+ * CLiInputAdapter – bridges UI‑CLI utilities with generic UI core.
  *
  * @module InputAdapter
  */
 
-import { Message } from "@nan0web/co"
 import {
-	UIForm,
+	UiForm,
 	InputAdapter as BaseInputAdapter,
+	UiMessage,
 } from "@nan0web/ui"
-import { ask } from "./ui/input.js"
-import { select } from "./ui/select.js"
 import { CancelError } from "@nan0web/ui/core"
 
+import { ask as baseAsk, createInput, createPredefinedInput, Input } from "./ui/input.js"
+import { select as baseSelect } from "./ui/select.js"
+import { generateForm } from "./ui/form.js"
+
+/** @typedef {import("./ui/select.js").InputFn} InputFn */
+/** @typedef {import("./ui/select.js").ConsoleLike} ConsoleLike */
+
 /**
  * Extends the generic {@link BaseInputAdapter} with CLI‑specific behaviour.
  *
  * @class
  * @extends BaseInputAdapter
  */
-export default class CLIInputAdapter extends BaseInputAdapter {
+export default class CLiInputAdapter extends BaseInputAdapter {
+	/** @type {string[]} Queue of predefined answers. */
+	#answers = []
+	/** @type {number} Current position in the answers queue. */
+	#cursor = 0
+	/** @type {ConsoleLike} */
+	#console
+	#stdout
+	/** @type {Map<string, () => Promise<Function>>} */
+	#components = new Map()
+
+	constructor(options = {}) {
+		super()
+		const {
+			predefined = process.env.PLAY_DEMO_SEQUENCE ?? [],
+			divider = process.env.PLAY_DEMO_DIVIDER ?? ",",
+			console: initialConsole = console,
+			stdout = process.stdout,
+			components = new Map(),
+		} = options
+
+		this.#console = initialConsole
+		this.#stdout = stdout
+		this.#components = components
+
+		if (Array.isArray(predefined)) {
+			this.#answers = predefined.map(v => String(v))
+		} else if (typeof predefined === "string") {
+			this.#answers = predefined
+				.split(divider)
+				.map(v => v.trim())
+				.filter(Boolean)
+		} else {
+			this.#answers = []
+		}
+	}
+
+	/** @returns {ConsoleLike} */
+	get console() { return this.#console }
+	/** @returns {NodeJS.WriteStream} */
+	get stdout() { return this.#stdout }
+
+	#nextAnswer() {
+		if (this.#cursor < this.#answers.length) {
+			const val = this.#answers[this.#cursor]
+			this.#cursor++
+			return val
+		}
+		return null
+	}
+
+	/**
+	 * Normalise a value that can be either a raw string or an {@link Input}
+	 * instance (which carries the actual value in its `value` property).
+	 *
+	 * @param {any} val – Raw value or {@link Input}.
+	 * @returns {string} Plain string value.
+	 */
+	#normalise(val) {
+		if (val && typeof val === "object" && "value" in val) {
+			return String(val.value)
+		}
+		return String(val ?? "")
+	}
+
+	/**
+	 * Create a handler with stop words that supports predefined answers.
+	 *
+	 * @param {string[]} stops - Stop words for cancellation.
+	 * @returns {InputFn}
+	 */
+	createHandler(stops = []) {
+		const self = this
+		return async (question, loop = false, nextQuestion = undefined) => {
+			const predefined = self.#nextAnswer()
+			if (predefined !== null) {
+				this.stdout.write(`${question}${predefined}\n`)
+				const input = new Input({ value: predefined, stops })
+				if (input.cancelled) {
+					throw new CancelError("Cancelled via stop word")
+				}
+				return input
+			}
+			const interactive = createInput(stops)
+			return interactive(question, loop, nextQuestion)
+		}
+	}
+
 	/**
 	 * Prompt the user for a full form, handling navigation and validation.
 	 *
-	 * @param {UIForm} form - Form definition to present.
+	 * @param {UiForm} form - Form definition to present.
 	 * @param {Object} [options={}]
 	 * @param {boolean} [options.silent=true] - Suppress console output if `true`.
 	 * @returns {Promise<Object>} Result object containing form data and meta‑information.
 	 */
 	async requestForm(form, options = {}) {
 		const { silent = true } = options
-		if (!silent) console.log(`\n${form.title}\n`)
+		if (!silent) this.console.info(`\n${form.title}\n`)
 
 		let formData = { ...form.state }
 		let idx = 0
@@ -38,23 +130,56 @@ export default class CLIInputAdapter extends BaseInputAdapter {
 		while (idx < form.fields.length) {
 			const field = form.fields[idx]
 			const prompt = `${field.label || field.name}${field.required ? " *" : ""}: `
-			const answer = await this.ask(prompt)
 
-			if (["", "esc"].includes(answer)) {
-				// @ts-ignore – `UIForm` may not expose `id` in its TS definition
-				// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+			// ---- Handle select fields (options) ----------------------------------------
+			if (Array.isArray(field.options ?? 0) && field.options.length) {
+				const options = /** @type {any[]} */ (field.options)
+
+				const predefined = this.#nextAnswer()
+				const selConfig = {
+					title: field.label,
+					prompt: "Choose (number): ",
+					options: options.map(opt =>
+						typeof opt === "string"
+							? { label: opt, value: opt }
+							: opt
+					),
+					console: { info: this.console.info.bind(this.console) },
+				}
+
+				let selResult
+				if (predefined !== null) {
+					selConfig.ask = createPredefinedInput([predefined], this.console)
+					selResult = await this.select(selConfig)
+				} else {
+					selConfig.ask = this.createHandler(["cancel", "quit", "exit"])
+					selResult = await this.select(selConfig)
+				}
+
+				const chosen = selResult?.value
+				if (!options.includes(chosen)) {
+					this.console.error("\nEnumeration must have one value")
+					continue
+				}
+				formData[field.name] = String(chosen)
+				idx++
+				continue
+			}
+			// ---------------------------------------------------------------------------
+
+			const rawAnswer = await this.ask(prompt)
+			const answerStr = this.#normalise(rawAnswer)
+
+			if (["", "esc"].includes(answerStr)) {
 				return {
-					// @ts-ignore
-					body: { action: "form-cancel", escaped: true, form: {}, id: form.id },
+					body: { action: "form-cancel", cancelled: true, form: {} },
 					form: {},
-					escaped: true,
+					cancelled: true,
 					action: "form-cancel",
-					// @ts-ignore
-					id: form.id,
 				}
 			}
 
-			const trimmed = answer.trim()
+			const trimmed = answerStr.trim()
 			if (trimmed === "::prev" || trimmed === "::back") {
 				idx = Math.max(0, idx - 1)
 				continue
@@ -68,13 +193,13 @@ export default class CLIInputAdapter extends BaseInputAdapter {
 				continue
 			}
 			if (field.required && trimmed === "") {
-				console.log("\nField is required.")
+				this.console.info("\nField is required.")
 				continue
 			}
 			const schema = field.constructor
 			const { isValid, errors } = form.validateValue(field.name, trimmed, schema)
 			if (!isValid) {
-				console.log("\n" + Object.values(errors).join("\n"))
+				this.console.warn("\n" + Object.values(errors).join("\n"))
 				continue
 			}
 			formData[field.name] = trimmed
@@ -82,39 +207,78 @@ export default class CLIInputAdapter extends BaseInputAdapter {
 		}
 
 		const finalForm = form.setData(formData)
-		const { isValid, errors } = finalForm.validate()
-		if (!isValid) {
-			console.log("\n" + Object.values(errors).join("\n"))
+		const errors = finalForm.validate()
+		if (errors.size) {
+			this.console.warn("\n" + Object.values(errors).join("\n"))
 			return await this.requestForm(form, options)
 		}
-
-		// @ts-ignore – `UIForm` may not expose `id`
-		// eslint-disable-next-line @typescript-eslint/ban-ts-comment
 		return {
-			// @ts-ignore
-			body: { action: "form-submit", escaped: false, form: finalForm, id: form.id },
+			body: { action: "form-submit", cancelled: false, form: finalForm },
 			form: finalForm,
-			escaped: false,
+			cancelled: false,
 			action: "form-submit",
-			// @ts-ignore
-			id: form.id,
 		}
 	}
 
+	/**
+	 * Render a UI component in the CLI environment.
+	 *
+	 * The current CLI adapter only supports simple textual rendering.
+	 *
+	 * @param {string} component - Component name (e.g. `"Alert"`).
+	 * @param {object} props - Props object passed to the component.
+	 * @returns {Promise<void>}
+	 */
+	async render(component, props) {
+		const compLoader = this.#components.get(component)
+		if (compLoader) {
+			try {
+				const compFn = await compLoader()
+				if (typeof compFn === "function") {
+					compFn.call(this, props)
+					return
+				}
+			} catch (/** @type {any} */ err) {
+				this.console.error(`Failed to render component "${component}": ${err.message}`)
+				this.console.debug?.(err.stack)
+			}
+		}
+		if (props && typeof props === "object") {
+			const { variant, content } = props
+			const prefix = variant ? `[${variant}]` : ""
+			this.console.info(`${prefix} ${String(content)}`)
+		} else {
+			this.console.info(String(component))
+		}
+	}
+
+	/**
+	 * Process a full form – thin wrapper around {@link requestForm}.
+	 *
+	 * @param {UiForm} form - Form definition.
+	 * @param {object} [_state] - Unused, kept for compatibility with `CLiMessage`.
+	 * @returns {Promise<Object>} Same shape as {@link requestForm} result.
+	 */
+	async processForm(form, _state) {
+		return this.requestForm(form)
+	}
+
 	/**
 	 * Prompt the user to select an option from a list.
 	 *
-	 * @param {Object} config - Configuration passed to {@link select}.
-	 * @returns {Promise<any>} Selected value, or empty string on cancellation.
+	 * @param {Object} config - Configuration object.
+	 * @returns {Promise<string>} Selected value (or empty string on cancel).
 	 */
 	async requestSelect(config) {
 		try {
-			const result = await this.select({
-				title: config.title ?? "Select an option:",
-				prompt: config.prompt ?? "Choose (1‑N): ",
-				options: config.options,
-				console: console,
-			})
+			const predefined = this.#nextAnswer()
+			if (!config.console) config.console = { info: () => { } }
+
+			if (predefined !== null) {
+				config.yes = true
+				config.ask = createPredefinedInput([predefined], config.console)
+			}
+			const result = await this.select(config)
 			return result.value
 		} catch (e) {
 			if (e instanceof CancelError) return ""
@@ -126,23 +290,86 @@ export default class CLIInputAdapter extends BaseInputAdapter {
 	 * Prompt for a single string input.
 	 *
 	 * @param {Object} config - Prompt configuration.
-	 * @param {string} [config.prompt] - Prompt text.
-	 * @param {string} [config.label] - Optional label.
-	 * @param {string} [config.name] - Optional identifier.
 	 * @returns {Promise<string>} User response string.
 	 */
 	async requestInput(config) {
+		const predefined = this.#nextAnswer()
+		if (predefined !== null) return predefined
+
+		if (config.yes === true && config.value !== undefined) {
+			return config.value
+		}
 		const prompt = config.prompt ?? `${config.label ?? config.name}: `
-		const input = await this.ask(prompt)
-		return input
+		const answer = await this.ask(prompt)
+		return this.#normalise(answer)
 	}
 
-	/** @inheritDoc */
-	async ask(question) {
-		return ask(question)
+	/**
+	 * Asks user a question or form and returns the completed form
+	 * @param {string | UiForm} question
+	 * @param {object} [options={}]
+	 *
+	 */
+	async ask(question, options = {}) {
+		if (question instanceof UiForm) {
+			return await this.requestForm(question, options)
+		}
+		const predefined = this.#nextAnswer()
+		if (predefined !== null) {
+			this.stdout.write(`${question}${predefined}\n`)
+			return predefined
+		}
+		const input = await baseAsk(question)
+		return input.value
 	}
+
 	/** @inheritDoc */
 	async select(cfg) {
-		return select(cfg)
+		return baseSelect(cfg)
+	}
+
+	/**
+	 * **New API** – Require input for a {@link UiMessage} instance.
+	 *
+	 * This method mirrors the previous `UiMessage.requireInput` logic, but is now
+	 * owned by the UI adapter. It validates the message according to its static
+	 * {@link UiMessage.Body} schema, presents a generated {@link UiForm} and
+	 * returns the updated body.  Cancellation results in a {@link CancelError}.
+	 *
+	 * @param {UiMessage} msg - Message instance needing input.
+	 * @returns {Promise<any>} Updated message body.
+	 * @throws {CancelError} When user cancels the input process.
+	 */
+	async requireInput(msg) {
+		if (!msg) {
+			throw new Error("Message instance is required")
+		}
+		if (!(msg instanceof UiMessage)) {
+			throw new TypeError("Message must be an instance 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(form, msg.body)
+			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) {
+				errors = updatedErrors
+				continue
+			}
+			msg.body = updatedBody
+			break
+		}
+		return /** @type {any} */ (msg.body)
 	}
 }

package/src/OutputAdapter.js

@@ -0,0 +1,61 @@
+/**
+ * OutputAdapter handles UI output operations in command-line environment.
+ * @class
+ */
+export default class OutputAdapter {
+	/** @type {any} */
+	#console
+	/** @type {Map<string, () => Promise<Function>>} */
+	#components = new Map()
+
+	/**
+	 * Creates new output adapter.
+	 * @param {Object} [options] - Configuration options.
+	 * @param {any} [options.console] - Console implementation.
+	 * @param {Map<string, () => Promise<Function>>} [options.components] - Component loaders.
+	 */
+	constructor(options = {}) {
+		const {
+			console: initialConsole = console,
+			components = new Map(),
+		} = options
+
+		this.#console = initialConsole
+		this.#components = components
+	}
+
+	/** @returns {any} */
+	get console() { return this.#console; }
+
+	/**
+	 * Render a UI component in the CLI environment.
+	 *
+	 * The current implementation supports simple textual rendering.
+	 *
+	 * @param {string} component - Component name (e.g. `"Alert"`).
+	 * @param {object} props - Props object passed to the component.
+	 * @returns {Promise<void>}
+	 */
+	async render(component, props) {
+		const loader = this.#components.get(component)
+		if (loader) {
+			try {
+				const compFn = await loader()
+				if (typeof compFn === "function") {
+					compFn.call(this, props)
+					return
+				}
+			} catch (/** @type {any} */ err) {
+				this.#console.error(`Failed to render component "${component}": ${err.message}`)
+				this.#console.debug?.(err.stack)
+			}
+		}
+		if (props && typeof props === "object") {
+			const { variant, content } = props
+			const prefix = variant ? `[${variant}]` : ""
+			this.#console.info(`${prefix} ${String(content)}`)
+		} else {
+			this.#console.info(String(component))
+		}
+	}
+}

package/src/README.md.js

@@ -2,8 +2,7 @@
 import { describe, it, before, beforeEach } from "node:test"
 import assert from "node:assert/strict"
 import FS from "@nan0web/db-fs"
-import Message from "@nan0web/co"
-import { UIForm } from "@nan0web/ui"
+import { UiForm } from "@nan0web/ui"
 import { NoConsole } from "@nan0web/log"
 import {
 	DatasetParser,
@@ -11,7 +10,7 @@ import {
 	runSpawn,
 } from "@nan0web/test"
 import {
-	CLIInputAdapter as BaseCLIInputAdapter,
+	CLiInputAdapter as BaseCLiInputAdapter,
 	CancelError,
 	createInput,
 	Input,
@@ -39,7 +38,7 @@ async function next() {
 	return Promise.resolve(" ")
 }
 
-class CLIInputAdapter extends BaseCLIInputAdapter {
+class CLiInputAdapter extends BaseCLiInputAdapter {
 	async ask(question) {
 		return await ask(question)
 	}
@@ -89,7 +88,7 @@ function testRender() {
 	 *
 	 * Core classes:
 	 *
-	 * - `CLIInputAdapter` — handles form, input, and select requests in CLI.
+	 * - `CLiInputAdapter` — handles form, input, and select requests in CLI.
 	 * - `Input` — wraps user input with value and cancellation status.
 	 * - `CancelError` — thrown when a user cancels an operation.
 	 *
@@ -133,7 +132,7 @@ function testRender() {
 	 * @docs
 	 * ## Usage
 	 *
-	 * ### CLIInputAdapter
+	 * ### CLiInputAdapter
 	 *
 	 * The adapter provides methods to handle form, input, and select requests.
 	 *
@@ -141,9 +140,9 @@ function testRender() {
 	 *
 	 * Displays a form and collects user input field-by-field with validation.
 	 */
-	it("How to request form input via CLIInputAdapter?", async () => {
-		//import { CLIInputAdapter } from '@nan0web/ui-cli'
-		const adapter = new CLIInputAdapter()
+	it("How to request form input via CLiInputAdapter?", async () => {
+		//import { CLiInputAdapter } from '@nan0web/ui-cli'
+		const adapter = new CLiInputAdapter()
 		const fields = [
 			{ name: "name", label: "Full Name", required: true },
 			{ name: "email", label: "Email", type: "email", required: true },
@@ -159,7 +158,7 @@ function testRender() {
 			newForm.state = data
 			return newForm
 		}
-		const form = UIForm.from({
+		const form = UiForm.from({
 			title: "User Profile",
 			fields,
 			id: "user-profile-form",
@@ -177,9 +176,9 @@ function testRender() {
 	/**
 	 * @docs
 	 */
-	it("How to request select input via CLIInputAdapter?", async () => {
-		//import { CLIInputAdapter } from '@nan0web/ui-cli'
-		const adapter = new CLIInputAdapter()
+	it("How to request select input via CLiInputAdapter?", async () => {
+		//import { CLiInputAdapter } from '@nan0web/ui-cli'
+		const adapter = new CLiInputAdapter()
 		const config = {
 			title: "Choose Language:",
 			prompt: "Language (1-2): ",
@@ -313,7 +312,7 @@ function testRender() {
 	 * @docs
 	 * ## API
 	 *
-	 * ### CLIInputAdapter
+	 * ### CLiInputAdapter
 	 *
 	 * * **Methods**
 	 *   * `requestForm(form, options)` — (async) handles form request
@@ -368,7 +367,7 @@ function testRender() {
 	 * Extends `Error`, thrown when an input is cancelled.
 	 */
 	it("All exported classes and functions should pass basic tests", () => {
-		assert.ok(CLIInputAdapter)
+		assert.ok(CLiInputAdapter)
 		assert.ok(CancelError)
 		assert.ok(createInput)
 		assert.ok(baseAsk)
@@ -404,7 +403,7 @@ function testRender() {
 		assert.ok(String(pkg.scripts?.playground))
 		const response = await runSpawn("git", ["remote", "get-url", "origin"], { timeout: 2_000 })
 		if (response.code === 0) {
-			assert.ok(response.text.trim().endsWith(":nan0web/ui-cli.git"))
+			assert.ok(response.text.trim().endsWith("nan0web/ui-cli.git"))
 		} else {
 			// git command may fail if not in a repo or no remote, skip assertion
 			console.warn("Git command skipped due to non-zero exit code or timeout.")

package/src/components/Alert.js

@@ -0,0 +1,22 @@
+/** @typedef {import("../InputAdapter.js").default} InputAdapter */
+
+/**
+ * Alert component for CLI rendering.
+ *
+ * @this {InputAdapter}
+ * @param {Object} input - Component props.
+ * @param {string} [input.variant="info"] - Alert variant (maps to console method).
+ * @param {string} [input.content=""] - Alert message content.
+ * @throws {Error} If variant maps to undefined console method.
+ */
+export default function (input = {}) {
+	const {
+		variant = "info",
+		content = "",
+	} = input
+	const fn = variant === "success" ? "info" : variant
+	if (typeof this.console[fn] !== "function") {
+		throw new Error(`Undefined variant: ${variant}`)
+	}
+	this.console[fn](content)
+}

package/src/index.js

@@ -1,5 +1,7 @@
-import CLIInputAdapter from "./InputAdapter.js"
 import { CancelError } from "@nan0web/ui/core"
+
+import CLiInputAdapter from "./InputAdapter.js"
+import OutputAdapter from "./OutputAdapter.js"
 import CLI from "./CLI.js"
 import Command from "./Command.js"
 import CommandError from "./CommandError.js"
@@ -21,8 +23,9 @@ export {
 
 export {
 	CLI,
-	CLIInputAdapter,
+	CLiInputAdapter,
 	CancelError,
+	OutputAdapter,
 
 	/** @deprecated */
 	Command,
@@ -35,6 +38,9 @@ export {
 	CommandHelp,
 }
 
+/* New public API */
+export { generateForm } from "./ui/form.js"
+
 export const renderers = new Map([
 	[
 		"UIProcess",
@@ -44,4 +50,4 @@ export const renderers = new Map([
 	],
 ])
 
-export default CLIInputAdapter
+export default CLiInputAdapter