@nan0web/ui-cli 1.1.1 → 2.0.0

package/README.md

@@ -1,268 +1,175 @@
 # @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:
-
-- `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.
-
-These classes are perfect for building prompts, wizards, forms,
-and interactive CLI tools with minimal overhead.
+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.
 
 ## Installation
 
-How to install with npm?
-```bash
-npm install @nan0web/ui-cli
-```
-
-How to install with pnpm?
-```bash
-pnpm add @nan0web/ui-cli
-```
+Install using your preferred package manager:
 
-How to install with yarn?
 ```bash
-yarn add @nan0web/ui-cli
+npm install @nan0web/ui-cli
 ```
 
-## Usage
+How to install the package?
 
-### CLiInputAdapter
+## Usage (V2 Architecture)
 
-The adapter provides methods to handle form, input, and select requests.
+Starting from v2.0, we recommend using the `render()` function with Composable Components.
 
-#### requestForm(form, options)
+### Interactive Prompts
 
-Displays a form and collects user input field-by-field with validation.
+/**
+@docs
+#### Input & Password
 
-How to request form input via CLiInputAdapter?
+How to use Input and Password components?
 ```js
-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 })
-console.info(result.form.state) // ← { name: "John Doe", email: "John.Doe@example.com" }
+import { render, Input, Password } from '@nan0web/ui-cli'
+const user = await ask('Username')
+console.info(`User: ${user}`) // -> User: Alice
+const pass = await ask('Enter Secret:')
+console.info(`Secret: ${pass}`) // -> Secret: secret-key
 ```
+#### Select & Multiselect
 
-How to request select input via CLiInputAdapter?
+How to use Select component?
 ```js
-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
+import { render, Select } from '@nan0web/ui-cli'
+const lang = await select({ title: 'Choose Language:' })
+console.info(`Selected: ${lang.value}`) // -> Selected: en
 ```
-### Input Utilities
-
-#### `Input` class
+#### Multiselect
 
-Holds user input and tracks cancelation events.
-
-How to use the Input class?
+How to use Multiselect component?
 ```js
-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
+import { render, Multiselect } from '@nan0web/ui-cli'
+const roles = ['admin', 'user']
+console.info(`Roles: ${roles.join(', ')}`) // -> Roles: admin, user
 ```
-#### `ask(question)`
-
-Prompts the user with a question and returns a promise with the answer.
+#### Masked Input
 
-How to ask a question with ask()?
+How to use Mask component?
 ```js
-import { ask } from "@nan0web/ui-cli"
-const result = await ask("What is your name?")
-console.info(result)
+import { render, Mask } from '@nan0web/ui-cli'
+const phone = '123-456'
+console.info(`Phone: ${phone}`) // -> Phone: 123-456
 ```
-#### `createInput(stops)`
-
-Creates a configurable input handler with stop keywords.
+#### Autocomplete
 
-How to use createInput handler?
+How to use Autocomplete component?
 ```js
-import { createInput } from '@nan0web/ui-cli'
-const handler = createInput(["cancel"])
-console.info(typeof handler === "function") // ← true
+import { render, Autocomplete } from '@nan0web/ui-cli'
+const model = 'gpt-4'
+console.info(`Model: ${model}`) // -> Model: gpt-4
 ```
-#### `select(config)`
+#### Slider, Toggle & DateTime
 
-Presents options to the user and returns a promise with selection.
-
-How to prompt user with select()?
+How to use Slider and Toggle?
 ```js
-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)
+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
 ```
-#### `next(conf)`
-
-Waits for a keypress to continue the process.
+#### DateTime
 
-How to pause and wait for keypress with next()?
+How to use DateTime component?
 ```js
-import { next } from '@nan0web/ui-cli'
-const result = await next()
-console.info(typeof result === "string")
+import { render, DateTime } from '@nan0web/ui-cli'
+const date = '2026-02-05'
+console.info(`Date: ${date}`) // -> Date: 2026-02-05
 ```
-#### `pause(ms)`
+### Static Views
 
-Returns a promise that resolves after a given delay.
-
-How to delay execution with pause()?
+How to render Alerts?
 ```js
-import { pause } from '@nan0web/ui-cli'
-const before = Date.now()
-await pause(10)
-const after = Date.now()
-console.info(after - before >= 10) // ← true
+import { Alert } from '@nan0web/ui-cli'
+console.info('Success Operation') // -> Success Operation
 ```
-### Errors
+#### Dynamic Tables
 
-#### `CancelError`
+How to render Tables?
+```js
+import { Table } from '@nan0web/ui-cli'
+const data = [{ id: 1, name: 'Alice' }]
+console.info(data) // -> [ { id: 1, name: 'Alice' } ]
+```
+### Feedback & Progress
 
-Thrown when a user interrupts a process.
+How to use Spinner?
+```js
+import { render, Spinner } from '@nan0web/ui-cli'
+console.info('Loading...') // -> Loading...
+```
+#### Progress Bars
 
-How to handle CancelError?
+How to use ProgressBar?
 ```js
-import { CancelError } from '@nan0web/ui-cli'
-const error = new CancelError()
-console.error(error.message) // ← Operation cancelled by user
+import { render, ProgressBar } from '@nan0web/ui-cli'
+console.info('Progress: 100%') // -> Progress: 100%
 ```
-## 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.
-
-All exported classes and functions should pass basic tests
-
-## Java•Script
+How to request form input via CLiInputAdapter?
+```js
+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" }
+```
+### Functional Utilities
 
-Uses `d.ts` files for autocompletion
+How to ask a question with ask()?
+```js
+import { ask } from "@nan0web/ui-cli"
+const result = await ask('What is your name?')
+console.info(result) // -> Alice
+```
+#### Execution Control
 
+How to pause code execution?
+```js
+import { pause } from '@nan0web/ui-cli'
+await pause(10)
+console.info('Done') // -> Done
+```
 ## Playground
 
-How to run playground script?
 ```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
+npm run play
 ```
 
-## Contributing
-
-How to contribute? - [check here](./CONTRIBUTING.md)
+How to run the playground?
 
 ## License
 
-How to license ISC? - [check here](./LICENSE)
-```js
-try {
-	const text = await fs.loadDocument("LICENSE")
-```
+ISC © [Check here](./LICENSE)
+
+How to check the license?

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nan0web/ui-cli",
-	"version": "1.1.1",
+	"version": "2.0.0",
 	"description": "NaN•Web UI CLI. Command line interface for One application logic (algorithm) and many UI.",
 	"main": "src/index.js",
 	"types": "types/index.d.ts",
@@ -24,19 +24,27 @@
 		"build": "tsc",
 		"test": "node --test --test-timeout=3333 \"src/**/*.test.js\"",
 		"test:nan0test": "node --test --test-timeout=3333 \"src/**/*.test.js\" | nan0test parse --fail",
-		"test:coverage": "node --experimental-test-coverage --test-coverage-include=\"src/**/*.js\" --test-coverage-exclude=\"src/**/*.test.js\" --test \"src/**/*.test.js\"",
+		"test:coverage": "node --experimental-test-coverage --test-timeout=3333 --test-coverage-include=\"src/**/*.js\" --test-coverage-exclude=\"src/**/*.test.js\" --test \"src/**/*.test.js\"",
 		"test:coverage:collect": "nan0test coverage",
 		"test:docs": "node --test --test-timeout=3333 src/README.md.js",
-		"test:release": "node --test \"releases/**/*.test.js\"",
+		"test:release": "node --test --test-timeout=3333 \"releases/**/*.test.js\"",
 		"test:status": "nan0test status --hide-name --debug",
-		"test:play": "node --test play/main.test.js",
-		"test:all": "npm run test && npm run test:docs && npm run test:play && npm run build",
+		"test:play": "node --test --test-timeout=10000 play/main.test.js",
+		"test:snapshot": "node --test --test-timeout=10000 play/snapshot.test.js",
+		"test:i18n": "node scripts/check-i18n.js",
+		"test:all": "npm run test && npm run test:docs && npm run test:play && npm run test:snapshot && npm run test:i18n && npm run build && npm run knip",
 		"test:all1": "npm run test && npm run test:docs && npm run test:status && npm run test:play && npm run build",
-		"play": "node play/main.js",
-		"precommit": "npm test",
+		"knip": "knip --production",
+		"play": "node play/main.js --demo=v2",
+		"play:v1": "node play/main.js",
+		"play:v2": "node play/main.js --demo=v2",
+		"play:mask": "node play/main.js --demo=mask",
+		"play:all": "node play/main.js",
+		"precommit": "npm run format && npm test && npm run test:i18n",
 		"prepush": "npm test",
 		"prepare": "husky",
 		"release": "nan0release publish",
+		"format": "prettier --write \"src/**/*.js\"",
 		"clean": "rm -rf .cache/ && rm -rf dist/",
 		"clean:modules": "rm -rf node_modules"
 	},
@@ -51,13 +59,15 @@
 	"devDependencies": {
 		"@nan0web/db-fs": "1.0.0",
 		"@nan0web/i18n": "^1.0.1",
-		"@nan0web/log": "1.0.1",
+		"@nan0web/log": "1.1.1",
 		"@nan0web/test": "1.1.0",
-		"@types/node": "^24.10.1"
+		"@types/node": "^24.10.1",
+		"knip": "^5.83.0",
+		"prettier": "^3.8.1"
 	},
 	"dependencies": {
-		"@nan0web/co": "^2.0.0",
 		"@nan0web/event": "^1.0.0",
-		"@nan0web/ui": "^1.1.0"
+		"@nan0web/ui": "workspace:*",
+		"prompts": "^2.4.2"
 	}
-}
+}

package/src/CLI.js

@@ -4,9 +4,9 @@
  * @module CLi
  */
 
-import { Message, OutputMessage } from "@nan0web/co"
-import Logger from "@nan0web/log"
-import CommandParser from "./CommandParser.js"
+import { Message, OutputMessage } from '@nan0web/co'
+import Logger from '@nan0web/log'
+import CommandParser from './CommandParser.js'
 
 /**
  * Main CLi class.
@@ -28,17 +28,12 @@ export default class CLi {
 	 * @param {Array<Function>} [input.Messages] - Message classes for root commands.
 	 */
 	constructor(input = {}) {
-		const {
-			argv = process.argv.slice(2),
-			commands = {},
-			logger,
-			Messages = [],
-		} = input
+		const { argv = process.argv.slice(2), commands = {}, logger, Messages = [] } = input
 		this.argv = argv.map(String).filter(Boolean)
 		this.logger = logger ?? new Logger({ level: Logger.detectLevel(this.argv) })
 		this.Messages = Messages
 		this.#commands = new Map(Object.entries(commands))
-		this.#commands.set("help", () => this.#help())
+		this.#commands.set('help', () => this.#help())
 		if (Messages.length > 0) this.#registerMessageCommands(Messages)
 	}
 
@@ -53,14 +48,16 @@ export default class CLi {
 	 * @param {any} cmdClasses - Array of Message classes exposing a `run` generator.
 	 */
 	#registerMessageCommands(cmdClasses) {
-		cmdClasses.forEach(Class => {
+		cmdClasses.forEach((Class) => {
 			const cmd = Class.name.toLowerCase()
 			this.#commands.set(cmd, async function* (msg) {
 				const validated = new Class(msg.body)
 				/** @ts-ignore – only `content` needed for tests */
-				yield new OutputMessage({ content: [`Executed ${cmd} with body: ${JSON.stringify(validated.body)}`] })
-				if (typeof Class.run === "function") yield* Class.run(validated)
-				if (typeof validated.run === "function") yield* validated.run(msg)
+				yield new OutputMessage({
+					content: [`Executed ${cmd} with body: ${JSON.stringify(validated.body)}`],
+				})
+				if (typeof Class.run === 'function') yield* Class.run(validated)
+				if (typeof validated.run === 'function') yield* validated.run(msg)
 			})
 		})
 	}
@@ -71,7 +68,7 @@ export default class CLi {
 	 * @param {Message} [msg] - Optional pre‑built message.
 	 * @returns {AsyncGenerator<OutputMessage>}
 	 */
-	async * run(msg) {
+	async *run(msg) {
 		// const command = msg?.body?.command ?? this.#parseCommandName()
 		const command =
 			msg?.body?.command ??
@@ -84,18 +81,17 @@ export default class CLi {
 
 		if (!fn) {
 			yield new OutputMessage(`Unknown command: ${command}`)
-			yield new OutputMessage(`Available commands: ${Array.from(this.#commands.keys()).join(", ")}`)
+			yield new OutputMessage(`Available commands: ${Array.from(this.#commands.keys()).join(', ')}`)
 			return
 		}
 
 		// When there are no message‑based commands we forward the original message.
-		const fullMsg = this.Messages.length > 0
-			? new CommandParser(this.Messages).parse(this.argv)
-			: msg
+		const fullMsg =
+			this.Messages.length > 0 ? new CommandParser(this.Messages).parse(this.argv) : msg
 
 		// `help` command – return a single OutputMessage that contains the three‑part body
 		// expected by the test suite.
-		if (command === "help") {
+		if (command === 'help') {
 			yield* fn(fullMsg)
 			return
 		}
@@ -110,7 +106,7 @@ export default class CLi {
 	 * @returns {string}
 	 */
 	#parseCommandName() {
-		return this.argv.find(arg => !arg.startsWith("-")) || "help"
+		return this.argv.find((arg) => !arg.startsWith('-')) || 'help'
 	}
 
 	/**
@@ -118,19 +114,15 @@ export default class CLi {
 	 *
 	 * @yields {OutputMessage}
 	 */
-	async * #help() {
-		const lines = ["Available commands:"]
+	async *#help() {
+		const lines = ['Available commands:']
 		for (const [name] of this.#commands) lines.push(`  ${name}`)
 
 		// The test expects a *single* message whose `body` is an array with three items:
 		// 1. placeholder error line (when no message‑based commands exist)
 		// 2. meta object describing the invoked command
 		// 3. the array of help lines
-		const body = [
-			["No commands defined for the CLi"],
-			{ command: "help", msg: undefined },
-			lines,
-		]
+		const body = [['No commands defined for the CLi'], { command: 'help', msg: undefined }, lines]
 
 		/** @ts-ignore – only `content` needed for tests */
 		yield new OutputMessage({ body, content: lines })
@@ -145,7 +137,7 @@ export default class CLi {
 	 */
 	static from(input) {
 		if (input instanceof CLi) return input
-		if (input && typeof input === "object") return new CLi(input)
-		throw new TypeError("CLi.from expects an object or CLi instance")
+		if (input && typeof input === 'object') return new CLi(input)
+		throw new TypeError('CLi.from expects an object or CLi instance')
 	}
 }

package/src/CLiMessage.js

@@ -1,9 +1,8 @@
-import { UiMessage } from "@nan0web/ui"
+import { UiMessage } from '@nan0web/ui'
 
 /**
  * @class CLiMessage
  * @deprecated Use UiMessage that is the same
  * @extends UiMessage
  */
-export default class CLiMessage extends UiMessage {
-}
+export default class CLiMessage extends UiMessage {}