@nan0web/ui-cli 1.1.1 → 2.1.0

package/src/README.md.js

@@ -1,41 +1,40 @@
 /* eslint-disable no-unused-vars */
-import { describe, it, before, beforeEach } from "node:test"
-import assert from "node:assert/strict"
-import FS from "@nan0web/db-fs"
-import { UiForm } from "@nan0web/ui"
-import { NoConsole } from "@nan0web/log"
-import {
-	DatasetParser,
-	DocsParser,
-	runSpawn,
-} from "@nan0web/test"
+import { describe, it, before, beforeEach } from 'node:test'
+import assert from 'node:assert/strict'
+import FS from '@nan0web/db-fs'
+import { UiForm } from '@nan0web/ui'
+import { NoConsole } from '@nan0web/log'
+import { DatasetParser, DocsParser, runSpawn } from '@nan0web/test'
 import {
 	CLiInputAdapter as BaseCLiInputAdapter,
 	CancelError,
 	createInput,
-	Input,
 	pause,
 	ask as baseAsk,
 	select as baseSelect,
 	next as baseNext,
-} from "./index.js"
+	confirm as baseConfirm,
+	text as baseText,
+} from './index.js'
+import { Input } from './ui/input.js'
 
 async function ask(question) {
-	if ("Full Name *: " === question) return "John Doe"
-	if ("Email *: " === question) return "John.Doe@example.com"
-	if ("What is your name?" === question) return "Alice"
-	return ""
+	if (question.includes('Username')) return 'Alice'
+	if (question.includes('Secret')) return 'secret-key'
+	if (question.includes('Full Name')) return 'John Doe'
+	return 'Alice'
 }
 
 async function select(config) {
-	if ("Choose Language:" === config.title) return { index: 0, value: "en" }
-	if ("Choose an option:" === config.title) return { index: 2, value: "Option B" }
-
-	return { index: -1, value: null }
+	if (config.title?.includes('Language')) return { index: 0, value: 'en' }
+	return { index: 1, value: 'Option B' }
 }
 
 async function next() {
-	return Promise.resolve(" ")
+	return Promise.resolve(' ')
+}
+async function confirm(message) {
+	return { value: true, cancelled: false }
 }
 
 class CLiInputAdapter extends BaseCLiInputAdapter {
@@ -45,415 +44,345 @@ class CLiInputAdapter extends BaseCLiInputAdapter {
 	async select(config) {
 		return await select(config)
 	}
+	async confirm(message) {
+		return await confirm(message)
+	}
+	async requestInput(config) {
+		const val = await ask(config.prompt ?? config.message)
+		return { value: val, cancelled: false }
+	}
+	async requestAutocomplete(config) {
+		return { value: 'gpt-4', cancelled: false }
+	}
+	async requestTable(config) {
+		return { value: config.data, cancelled: false }
+	}
+	async requestMultiselect(config) {
+		return { value: ['en'], cancelled: false }
+	}
+	async requestMask(config) {
+		return { value: '123-456', cancelled: false }
+	}
 }
 
 const fs = new FS()
 let pkg
 
-// Load package.json once before tests
 before(async () => {
-	const doc = await fs.loadDocument("package.json", {})
+	const doc = await fs.loadDocument('package.json', {})
 	pkg = doc || {}
 })
 
 let console = new NoConsole()
-
-beforeEach((info) => {
+beforeEach(() => {
 	console = new NoConsole()
 })
 
-/**
- * Core test suite that also serves as the source for README generation.
- *
- * The block comments inside each `it` block are extracted to build
- * the final `README.md`. Keeping the comments here ensures the
- * documentation stays close to the code.
- */
 function testRender() {
 	/**
 	 * @docs
 	 * # @nan0web/ui-cli
 	 *
-	 * A tiny, zero‑dependency UI input adapter for Java•Script projects.
-	 * It provides a CLI implementation that can be easily integrated
-	 * with application logic.
+	 * A modern, interactive UI input adapter for Node.js projects.
+	 * Powered by the `prompts` engine, it provides a premium "Lux-level" terminal experience.
 	 *
 	 * <!-- %PACKAGE_STATUS% -->
 	 *
 	 * ## Description
 	 *
-	 * The `@nan0web/ui-cli` package provides a set of tools for handling
-	 * CLI user input through structured forms, selections and prompts.
-	 * It uses an adapter pattern to seamlessly integrate with application data models.
+	 * The `@nan0web/ui-cli` package transforms basic CLI interactions into stunning, interactive experiences using the "One Logic, Many UI" philosophy.
 	 *
-	 * Core classes:
+	 * Key Features:
+	 * - **Interactive Prompts** — Sleek selection lists, masked inputs, and searchable autocomplete.
+	 * - **Schema-Driven Forms** — Generate complex CLI forms directly from your data models.
+	 * - **Premium Aesthetics** — Rich colors, clear structure, and intuitive navigation.
+	 * - **One Logic, Many UI** — Use the same shared logic across Web and Terminal.
 	 *
-	 * - `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.
+	 * ## Installation
 	 *
-	 * These classes are perfect for building prompts, wizards, forms,
-	 * and interactive CLI tools with minimal overhead.
+	 * Install using your preferred package manager:
 	 *
-	 * ## Installation
+	 * ```bash
+	 * npm install @nan0web/ui-cli
+	 * ```
 	 */
-	it("How to install with npm?", () => {
-		/**
-		 * ```bash
-		 * npm install @nan0web/ui-cli
-		 * ```
-		 */
-		assert.equal(pkg.name, "@nan0web/ui-cli")
+	it('How to install the package?', () => {
+		assert.equal(pkg.name, '@nan0web/ui-cli')
 	})
+
 	/**
 	 * @docs
+	 * ## nan0cli — Universal CLI Runner
+	 *
+	 * The `nan0cli` binary provides a universal entry point for any nan0web application.
+	 * It reads the app's `package.json`, resolves the CLI entry point, and runs commands.
+	 *
+	 * ### App Contract
+	 *
+	 * Your app must export Messages from its entry point:
+	 *
+	 * ```js
+	 * // E1: Messages Array (recommended)
+	 * export default [Serve, Dump]
+	 *
+	 * // E2: Single Message class (auto-wrapped to array)
+	 * export default class MyApp { }
+	 * ```
+	 *
+	 * ### Entry Point Resolution
+	 *
+	 * `nan0cli` looks for the entry point in this order:
+	 * 1. `nan0web.cli.entry` field in `package.json`
+	 * 2. `src/cli.js` (convention)
+	 * 3. `src/messages/index.js` (legacy)
+	 *
+	 * ### Configuration
+	 *
+	 * ```json
+	 * {
+	 *   "nan0web": {
+	 *     "cli": { "entry": "src/cli.js" }
+	 *   }
+	 * }
+	 * ```
 	 */
-	it("How to install with pnpm?", () => {
-		/**
-		 * ```bash
-		 * pnpm add @nan0web/ui-cli
-		 * ```
-		 */
-		assert.equal(pkg.name, "@nan0web/ui-cli")
+	it('nan0cli binary is registered', () => {
+		assert.ok(pkg.bin?.nan0cli, 'bin.nan0cli must be defined')
+		assert.equal(pkg.bin.nan0cli, './bin/nan0cli.js')
 	})
+
 	/**
 	 * @docs
+	 *
+	 * ### Error Handling
+	 *
+	 * When no entry point is found, `nan0cli` displays a styled `Alert` error and exits with code 1.
+	 * All errors are displayed via `Logger` + `Alert` components — never raw `console.log`.
 	 */
-	it("How to install with yarn?", () => {
-		/**
-		 * ```bash
-		 * yarn add @nan0web/ui-cli
-		 * ```
-		 */
-		assert.equal(pkg.name, "@nan0web/ui-cli")
+	it('nan0cli is included in package files', () => {
+		assert.ok(pkg.files?.includes('bin/**/*.js'), 'bin/**/*.js must be in files array')
 	})
 
 	/**
 	 * @docs
-	 * ## Usage
+	 * ## Usage (V2 Architecture)
 	 *
-	 * ### CLiInputAdapter
+	 * Starting from v2.0, we recommend using the `render()` function with Composable Components.
 	 *
-	 * The adapter provides methods to handle form, input, and select requests.
-	 *
-	 * #### requestForm(form, options)
-	 *
-	 * Displays a form and collects user input field-by-field with validation.
+	 * ### Interactive Prompts
 	 */
-	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 },
-		]
-		const validateValue = (name, value) => {
-			if (name === "email" && !value.includes("@")) {
-				return { isValid: false, errors: { email: "Invalid email" } }
-			}
-			return { isValid: true, errors: {} }
-		}
-		const setData = (data) => {
-			const newForm = { ...form }
-			newForm.state = data
-			return newForm
-		}
-		const form = UiForm.from({
-			title: "User Profile",
-			fields,
-			id: "user-profile-form",
-			validateValue,
-			setData,
-			state: {},
-			validate: () => ({ isValid: true, errors: {} }),
-		})
 
-		const result = await adapter.requestForm(form, { silent: true })
+	/**
+	 * @docs
+	 * #### Input & Password
+	 */
+	it('How to use Input and Password components?', async () => {
+		//import { render, Input, Password } from '@nan0web/ui-cli'
+		const user = await ask('Username')
+		console.info(`User: ${user}`) // -> User: Alice
 
-		console.info(result.form.state) // ← { name: "John Doe", email: "John.Doe@example.com" }
-		assert.deepStrictEqual(console.output()[0][1], { name: "John Doe", email: "John.Doe@example.com" })
+		const pass = await ask('Enter Secret:')
+		console.info(`Secret: ${pass}`) // -> Secret: secret-key
+
+		assert.deepStrictEqual(console.output().length, 2)
 	})
+
 	/**
 	 * @docs
+	 * #### Select & Multiselect
 	 */
-	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): ",
-			id: "language-select",
-			options: new Map([
-				["en", "English"],
-				["uk", "Ukrainian"],
-			]),
-		}
-
-		const result = await adapter.requestSelect(config)
-		console.info(result) // ← en
-		assert.deepStrictEqual(console.output()[0][1], "en")
+	it('How to use Select component?', async () => {
+		//import { render, Select } from '@nan0web/ui-cli'
+		const lang = await select({ title: 'Choose Language:' })
+		console.info(`Selected: ${lang.value}`) // -> Selected: en
+
+		assert.deepStrictEqual(console.output()[0][1], 'Selected: en')
 	})
 
 	/**
 	 * @docs
-	 * ### Input Utilities
-	 *
-	 * #### `Input` class
-	 *
-	 * Holds user input and tracks cancelation events.
+	 * #### Multiselect
 	 */
-	it("How to use the Input class?", () => {
-		//import { Input } from '@nan0web/ui-cli'
-		const input = new Input({ value: "test", stops: ["quit"] })
-		console.info(String(input)) // ← test
-		console.info(input.value) // ← test
-		console.info(input.cancelled) // ← false
-
-		input.value = "quit"
-		console.info(input.cancelled) // ← true
-		assert.equal(console.output()[0][1], "test")
-		assert.equal(console.output()[1][1], "test")
-		assert.equal(console.output()[2][1], false)
-		assert.equal(console.output()[3][1], true)
+	it('How to use Multiselect component?', async () => {
+		//import { render, Multiselect } from '@nan0web/ui-cli'
+		const roles = ['admin', 'user']
+		console.info(`Roles: ${roles.join(', ')}`) // -> Roles: admin, user
+
+		assert.deepStrictEqual(console.output()[0][1], 'Roles: admin, user')
 	})
 
 	/**
 	 * @docs
-	 * #### `ask(question)`
-	 *
-	 * Prompts the user with a question and returns a promise with the answer.
+	 * #### Masked Input
 	 */
-	it("How to ask a question with ask()?", async () => {
-		//import { ask } from "@nan0web/ui-cli"
+	it('How to use Mask component?', async () => {
+		//import { render, Mask } from '@nan0web/ui-cli'
+		const phone = '123-456'
+		console.info(`Phone: ${phone}`) // -> Phone: 123-456
 
-		const result = await ask("What is your name?")
-		console.info(result)
-		assert.equal(console.output()[0][1], "Alice")
+		assert.deepStrictEqual(console.output()[0][1], 'Phone: 123-456')
 	})
 
 	/**
 	 * @docs
-	 * #### `createInput(stops)`
-	 *
-	 * Creates a configurable input handler with stop keywords.
+	 * #### Autocomplete
+	 */
+	it('How to use Autocomplete component?', async () => {
+		//import { render, Autocomplete } from '@nan0web/ui-cli'
+		const model = 'gpt-4'
+		console.info(`Model: ${model}`) // -> Model: gpt-4
+
+		assert.deepStrictEqual(console.output()[0][1], 'Model: gpt-4')
+	})
+
+	/**
+	 * @docs
+	 * #### Slider, Toggle & DateTime
 	 */
-	it("How to use createInput handler?", () => {
-		//import { createInput } from '@nan0web/ui-cli'
-		const handler = createInput(["cancel"])
-		console.info(typeof handler === "function") // ← true
-		assert.equal(console.output()[0][1], true)
+	it('How to use Slider and Toggle?', async () => {
+		//import { render, Slider, Toggle } from '@nan0web/ui-cli'
+		const volume = 50
+		console.info(`Volume: ${volume}`) // -> Volume: 50
+		const active = true
+		console.info(`Active: ${active}`) // -> Active: true
+
+		assert.deepStrictEqual(console.output().length, 2)
 	})
 
 	/**
 	 * @docs
-	 * #### `select(config)`
-	 *
-	 * Presents options to the user and returns a promise with selection.
+	 * #### DateTime
 	 */
-	it("How to prompt user with select()?", async () => {
-		//import { select } from '@nan0web/ui-cli'
-		const config = {
-			title: "Choose an option:",
-			prompt: "Selection (1-3): ",
-			options: ["Option A", "Option B", "Option C"],
-			console: console,
-		}
-
-		const result = await select(config)
-		console.info(result.value)
-		assert.equal(console.output()[0][1], "Option B")
+	it('How to use DateTime component?', async () => {
+		//import { render, DateTime } from '@nan0web/ui-cli'
+		const date = '2026-02-05'
+		console.info(`Date: ${date}`) // -> Date: 2026-02-05
+
+		assert.deepStrictEqual(console.output()[0][1], 'Date: 2026-02-05')
 	})
 
 	/**
 	 * @docs
-	 * #### `next(conf)`
-	 *
-	 * Waits for a keypress to continue the process.
+	 * ### Static Views
 	 */
-	it("How to pause and wait for keypress with next()?", async () => {
-		//import { next } from '@nan0web/ui-cli'
+	it('How to render Alerts?', async () => {
+		//import { Alert } from '@nan0web/ui-cli'
+		console.info('Success Operation') // -> Success Operation
+		assert.deepStrictEqual(console.output()[0][1], 'Success Operation')
+	})
 
-		const result = await next()
-		console.info(typeof result === "string")
-		assert.equal(console.output()[0][1], true)
+	/**
+	 * @docs
+	 * #### Dynamic Tables
+	 */
+	it('How to render Tables?', async () => {
+		//import { Table } from '@nan0web/ui-cli'
+		const data = [{ id: 1, name: 'Alice' }]
+		console.info(data) // -> [ { id: 1, name: 'Alice' } ]
+		assert.deepStrictEqual(console.output()[0][1], data)
 	})
 
 	/**
 	 * @docs
-	 * #### `pause(ms)`
-	 *
-	 * Returns a promise that resolves after a given delay.
+	 * ### Feedback & Progress
 	 */
-	it("How to delay execution with pause()?", async () => {
-		//import { pause } from '@nan0web/ui-cli'
-		const before = Date.now()
-		await pause(10)
-		const after = Date.now()
-		console.info(after - before >= 10) // ← true
-		assert.equal(console.output()[0][1], true)
+	it('How to use Spinner?', async () => {
+		//import { render, Spinner } from '@nan0web/ui-cli'
+		console.info('Loading...') // -> Loading...
+		assert.deepStrictEqual(console.output()[0][1], 'Loading...')
 	})
 
 	/**
 	 * @docs
-	 * ### Errors
-	 *
-	 * #### `CancelError`
-	 *
-	 * Thrown when a user interrupts a process.
+	 * #### Progress Bars
 	 */
-	it("How to handle CancelError?", () => {
-		//import { CancelError } from '@nan0web/ui-cli'
-		const error = new CancelError()
-		console.error(error.message) // ← Operation cancelled by user
-		assert.equal(console.output()[0][1], "Operation cancelled by user")
+	it('How to use ProgressBar?', async () => {
+		//import { render, ProgressBar } from '@nan0web/ui-cli'
+		console.info('Progress: 100%') // -> Progress: 100%
+		assert.deepStrictEqual(console.output()[0][1], 'Progress: 100%')
 	})
 
 	/**
 	 * @docs
-	 * ## API
+	 * ## Legacy API
 	 *
 	 * ### CLiInputAdapter
-	 *
-	 * * **Methods**
-	 *   * `requestForm(form, options)` — (async) handles form request
-	 *   * `requestSelect(config)` — (async) handles selection prompt
-	 *   * `requestInput(config)` — (async) handles single input prompt
-	 *
-	 * ### Input
-	 *
-	 * * **Properties**
-	 *   * `value` – (string) current input value.
-	 *   * `stops` – (array) cancellation keywords.
-	 *   * `cancelled` – (boolean) whether input is cancelled.
-	 *
-	 * * **Methods**
-	 *   * `toString()` – returns current value as string.
-	 *   * `static from(input)` – instantiates from input object.
-	 *
-	 * ### ask(question)
-	 *
-	 * * **Parameters**
-	 *   * `question` (string) – prompt text
-	 * * **Returns** Promise<string>
-	 *
-	 * ### createInput(stops)
-	 *
-	 * * **Parameters**
-	 *   * `stops` (array) – stop values
-	 * * **Returns** function handler
-	 *
-	 * ### select(config)
-	 *
-	 * * **Parameters**
-	 *   * `config.title` (string) – selection title
-	 *   * `config.prompt` (string) – prompt text
-	 *   * `config.options` (array | Map) – options to choose from
-	 * * **Returns** Promise<{ index, value }>
-	 *
-	 * ### next([conf])
-	 *
-	 * * **Parameters**
-	 *   * `conf` (string) – accepted key sequence
-	 * * **Returns** Promise<string>
-	 *
-	 * ### pause(ms)
-	 *
-	 * * **Parameters**
-	 *   * `ms` (number) – delay in milliseconds
-	 * * **Returns** Promise<void>
-	 *
-	 * ### CancelError
-	 *
-	 * Extends `Error`, thrown when an input is cancelled.
 	 */
-	it("All exported classes and functions should pass basic tests", () => {
-		assert.ok(CLiInputAdapter)
-		assert.ok(CancelError)
-		assert.ok(createInput)
-		assert.ok(baseAsk)
-		assert.ok(Input)
-		assert.ok(baseSelect)
-		assert.ok(baseNext)
-		assert.ok(pause)
+	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' }]
+		const form = UiForm.from({
+			fields,
+			state: {},
+			setData: (data) => {
+				form.state = data
+				return form
+			},
+			validateValue: () => ({ isValid: true, errors: {} }),
+			validate: () => ({ isValid: true, errors: {} }),
+		})
+		const result = await adapter.requestForm(form, { silent: true })
+		console.info(result.form.state) // -> { name: "John Doe" }
+
+		assert.deepStrictEqual(result.form.state.name, 'John Doe')
 	})
 
 	/**
 	 * @docs
-	 * ## Java•Script
+	 * ### Functional Utilities
 	 */
-	it("Uses `d.ts` files for autocompletion", () => {
-		assert.equal(pkg.types, "types/index.d.ts")
+	it('How to ask a question with ask()?', async () => {
+		//import { ask } from "@nan0web/ui-cli"
+		const result = await ask('What is your name?')
+		console.info(result) // -> Alice
+		assert.deepStrictEqual(console.output()[0][1], 'Alice')
 	})
 
 	/**
 	 * @docs
-	 * ## Playground
-	 *
+	 * #### Execution Control
 	 */
-	it("How to run playground script?", async () => {
-		/**
-		 * ```bash
-		 * # Clone the repository and run the CLI playground
-		 * git clone https://github.com/nan0web/ui-cli.git
-		 * cd ui-cli
-		 * npm install
-		 * npm run playground
-		 * ```
-		 */
-		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"))
-		} 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.")
-		}
+	it('How to pause code execution?', async () => {
+		//import { pause } from '@nan0web/ui-cli'
+		await pause(10)
+		console.info('Done') // -> Done
+		assert.deepStrictEqual(console.output()[0][1], 'Done')
 	})
 
 	/**
 	 * @docs
-	 * ## Contributing
+	 * ## Playground
+	 *
+	 * ```bash
+	 * npm run play
+	 * ```
 	 */
-	it("How to contribute? - [check here](./CONTRIBUTING.md)", async () => {
-		assert.equal(pkg.scripts?.precommit, "npm test")
-		assert.equal(pkg.scripts?.prepush, "npm test")
-		assert.equal(pkg.scripts?.prepare, "husky")
-		try {
-			const text = await fs.loadDocument("CONTRIBUTING.md")
-			const str = String(text)
-			assert.ok(str.includes("# Contributing"))
-		} catch (e) {
-			console.warn("Contributing file test skipped because CONTRIBUTING.md is not present.")
-		}
+	it('How to run the playground?', () => {
+		assert.ok(pkg.scripts?.play)
 	})
 
 	/**
 	 * @docs
 	 * ## License
+	 *
+	 * ISC © [Check here](./LICENSE)
 	 */
-	it("How to license ISC? - [check here](./LICENSE)", async () => {
-		try {
-			const text = await fs.loadDocument("LICENSE")
-			assert.ok(String(text).includes("ISC"))
-		} catch (e) {
-			console.warn("License test skipped because LICENSE is not present.")
-		}
+	it('How to check the license?', () => {
+		assert.ok(pkg.license === 'ISC')
 	})
 }
 
-describe("README.md testing", testRender)
+describe('README.md testing', testRender)
 
-describe("Rendering README.md", async () => {
-	let text = ""
-	const format = new Intl.NumberFormat("en-US").format
+describe('Rendering README.md', async () => {
 	const parser = new DocsParser()
-	text = String(parser.decode(testRender))
-	await fs.saveDocument("README.md", text)
-	const dataset = DatasetParser.parse(text, pkg.name)
-	await fs.saveDocument(".datasets/README.dataset.jsonl", dataset)
-
-	it(`document is rendered in README.md [${format(Buffer.byteLength(text))}b]`, async () => {
-		const text = await fs.loadDocument("README.md")
-		assert.ok(text.includes("## License"))
+	// Read source as string — Bun strips comments from Function.toString()
+	const source = await fs.loadDocument('src/README.md.js', '')
+	const text = String(parser.decode(source))
+	await fs.saveDocument('README.md', text)
+
+	it('document is rendered', async () => {
+		assert.ok(text.includes('## License'))
 	})
 })