@nan0web/ui-cli 1.0.0

package/.editorconfig

@@ -0,0 +1,20 @@
+root = true
+
+[*]
+indent_style = tab
+indent_size = 2
+charset = utf-8
+end_of_line = lf
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.md]
+trim_trailing_whitespace = false
+
+[*.jsx]
+indent_style = tab
+indent_size = 2
+
+[*.{md,nano,yaml}]
+indent_style = space
+indent_size = 2

package/CONTRIBUTING.md

@@ -0,0 +1,42 @@
+# Contributing
+
+## Developer Certificate of Origin and License
+By contributing, You accept and agree to the following terms and conditions for your present and future contributions submitted.  
+Except for the license granted herein, You reserve all right, title, and interest in and to your Contributions.  
+All contributions are subject to the Developer Certificate of Origin and license as set out in the LICENSE file.
+
+## Code of Conduct
+As contributors and maintainers of this project, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities.  
+
+We are committed to making participation in this project a harassment-free experience for everyone, regardless of:
+- Level of experience,
+- Gender,
+- Gender identity and expression,
+- Sexual orientation,
+- Disability,
+- Personal appearance,
+- Body size,
+- Race,
+- Ethnicity,
+- Age,
+- Religion.
+
+> We recognize all people as the foundation of humanity, and our actions contribute to the continued existence and growth of our shared humanity.
+
+### Release versioning
+- Keep releases close to the minor versions and publish patches only if required.
+
+### Examples of unacceptable behavior by participants:
+- Use of sexual language or imagery.
+- Derogatory comments or personal attacks.
+- Trolling, public or private harassment.
+- Insults or other unprofessional conduct.
+
+### Enforcement
+Project maintainers have the right and responsibility to:
+- Remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions not aligned with this Code of Conduct.
+- Remove maintainers who violate this Code of Conduct.
+
+Instances of unacceptable behavior can be reported by contacting the project team.
+
+This Code of Conduct is adapted from the [Contributor Covenant, version 1.1.0](https://contributor-covenant.org/version/1/1/0/).

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2025, ЯRаСлав (YaRaSLove) <support@yaro.page>
+
+Permission to use, copy, modify, and distribute this software for any purpose
+with or without fee is hereby granted, provided that the above copyright notice
+and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,277 @@
+# @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.
+
+|[Status](https://github.com/nan0web/monorepo/blob/main/system.md#написання-сценаріїв)|Documentation|Test coverage|Features|Npm version|
+|---|---|---|---|---|
+ |🟢 `96.1%` |🧪 [English 🏴󠁧󠁢󠁥󠁮󠁧󠁿](https://github.com/nan0web/ui-cli/blob/main/README.md)<br />[Українською 🇺🇦](https://github.com/nan0web/ui-cli/blob/main/docs/uk/README.md) |🟡 `77.9%` |✅ d.ts 📜 system.md 🕹️ playground |— |
+
+## 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.
+
+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.
+
+## Installation
+
+How to install with npm?
+```bash
+npm install @nan0web/ui-cli
+```
+
+How to install with pnpm?
+```bash
+pnpm add @nan0web/ui-cli
+```
+
+How to install with yarn?
+```bash
+yarn add @nan0web/ui-cli
+```
+
+## Usage
+
+### CLIInputAdapter
+
+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.
+
+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", 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" }
+```
+
+How to request select input via CLIInputAdapter?
+```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.value) // ← Message { body: "en", head: {} }
+```
+### Input Utilities
+
+#### `Input` class
+
+Holds user input and tracks cancelation events.
+
+How to use the Input class?
+```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
+```
+#### `ask(question)`
+
+Prompts the user with a question and returns a promise with the answer.
+
+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)
+```
+#### `createInput(stops)`
+
+Creates a configurable input handler with stop keywords.
+
+How to use createInput handler?
+```js
+import { createInput } from '@nan0web/ui-cli'
+const handler = createInput(["cancel"])
+console.info(typeof handler === "function") // ← true
+```
+#### `select(config)`
+
+Presents options to the user and returns a promise with selection.
+
+How to prompt user with select()?
+```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)
+```
+#### `next(conf)`
+
+Waits for a keypress to continue the process.
+
+How to pause and wait for keypress with next()?
+```js
+import { next } from '@nan0web/ui-cli'
+
+const result = await next()
+console.info(typeof result === "string")
+```
+#### `pause(ms)`
+
+Returns a promise that resolves after a given delay.
+
+How to delay execution with pause()?
+```js
+import { pause } from '@nan0web/ui-cli'
+const before = Date.now()
+await pause(10)
+const after = Date.now()
+console.info(after - before >= 10) // ← true
+```
+### Errors
+
+#### `CancelError`
+
+Thrown when a user interrupts a process.
+
+How to handle CancelError?
+```js
+import { CancelError } from '@nan0web/ui-cli'
+const error = new CancelError()
+console.error(error.message) // ← Operation cancelled by user
+```
+## 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
+
+Uses `d.ts` files for autocompletion
+
+## 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
+```
+
+## Contributing
+
+How to contribute? - [check here](./CONTRIBUTING.md)
+
+## License
+
+How to license ISC? - [check here](./LICENSE)
+```js
+try {
+	const text = await fs.loadDocument("LICENSE")
+```

package/docs/uk/README.md

@@ -0,0 +1,294 @@
+# @nan0web/ui-cli
+
+Маленький, беззалежний UI‑адаптер вводу для JavaScript‑проєктів.  
+Надає CLI‑реалізацію, яку легко інтегрувати у логіку застосунку.
+
+|[Статус](https://github.com/nan0web/monorepo/blob/main/system.md#написання-сценаріїв)|Документація|Тестове покриття|Фічі|Версія npm|
+|---|---|---|---|---|
+|🟢 `96.1%`|🧪 [English 🏴󠁧󠁢󠁥󠁮󠁧󠁿](https://github.com/nan0web/ui-cli/blob/main/README.md)<br />[Українською 🇺🇦](https://github.com/nan0web/ui-cli/blob/main/docs/uk/README.md)|🟡 `77.9%`|✅ d.ts 📜 system.md 🕹️ playground|—|
+
+## Опис
+
+Пакет `@nan0web/ui-cli` надає набір інструментів для обробки вводу користувача в CLI через
+структуровані форми, вибір варіантів та підказки.
+Використовує патерн адаптера для безшовної інтеграції з моделями даних застосунку.
+
+### Основні класи
+
+- **`CLIInputAdapter`** — обробляє запити форм, вводу та вибору в CLI.  
+- **`Input`** — обгортає введене користувачем значення та статус скасування.  
+- **`CancelError`** — викидається, коли користувач скасовує операцію.
+
+Ці класи ідеальні для створення підказок, майстрів, форм та інтерактивних інструментів CLI з мінімальними накладними витратами.
+
+## Встановлення
+
+### Через npm
+```bash
+npm install @nan0web/ui-cli
+```
+
+### Через pnpm
+```bash
+pnpm add @nan0web/ui-cli
+```
+
+### Через yarn
+```bash
+yarn add @nan0web/ui-cli
+```
+
+## Приклади використання
+
+### CLIInputAdapter
+
+Адаптер містить методи для роботи з формами, ввідними та вибірковими запитами.
+
+#### `requestForm(form, options)`
+
+Відображає форму та послідовно збирає ввід полів з валідацією.
+
+```js
+import { CLIInputAdapter } from '@nan0web/ui-cli'
+
+const adapter = new CLIInputAdapter()
+
+const fields = [
+  { name: "name", label: "Повне ім’я", required: true },
+  { name: "email", label: "Email", type: "email", required: true },
+]
+
+const validateValue = (name, value) => {
+  if (name === "email" && !value.includes("@")) {
+    return { isValid: false, errors: { email: "Некоректний email" } }
+  }
+  return { isValid: true, errors: {} }
+}
+const setData = (data) => {
+  const newForm = { ...form }
+  newForm.state = data
+  return newForm
+}
+const form = UIForm.from({
+  title: "Профіль користувача",
+  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" }
+```
+
+#### `requestSelect(config)`
+
+Показує список варіантів і повертає обраний елемент.
+
+```js
+import { CLIInputAdapter } from '@nan0web/ui-cli'
+
+const adapter = new CLIInputAdapter()
+const config = {
+  title: "Виберіть мову:",
+  prompt: "Мова (1‑2): ",
+  id: "language-select",
+  options: new Map([
+    ["en", "English"],
+    ["uk", "Ukrainian"],
+  ]),
+}
+
+const result = await adapter.requestSelect(config)
+console.info(result.value) // ← Message { body: "en", head: {} }
+```
+
+### Утиліти вводу
+
+#### Клас `Input`
+
+Зберігає введене значення і відстежує скасування.
+
+```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
+```
+
+#### `ask(question)`
+
+Виводить питання та повертає відповідь у вигляді промісу.
+
+```js
+import { ask } from "@nan0web/ui-cli"
+
+const result = await ask("Яке ваше ім’я?")
+console.info(result)
+```
+
+#### `createInput(stops)`
+
+Створює налаштовуваний обробник вводів зі словами‑стопами.
+
+```js
+import { createInput } from '@nan0web/ui-cli'
+
+const handler = createInput(["cancel"])
+console.info(typeof handler === "function") // ← true
+```
+
+#### `select(config)`
+
+Показує список варіантів та повертає обраний елемент.
+
+```js
+import { select } from '@nan0web/ui-cli'
+
+const config = {
+  title: "Оберіть варіант:",
+  prompt: "Вибір (1‑3): ",
+  options: ["Варіант A", "Варіант B", "Варіант C"],
+  console: console,
+}
+
+const result = await select(config)
+console.info(result.value)
+```
+
+#### `next(conf)`
+
+Чекає натискання клавіші (або послідовності клавіш) для продовження процесу.
+
+```js
+import { next } from '@nan0web/ui-cli'
+
+const result = await next()
+console.info(typeof result === "string")
+```
+
+#### `pause(ms)`
+
+Повертає проміс, який виконується після заданої затримки.
+
+```js
+import { pause } from '@nan0web/ui-cli'
+const before = Date.now()
+await pause(10)
+const after = Date.now()
+console.info(after - before >= 10) // ← true
+```
+
+### Помилки
+
+#### `CancelError`
+
+Викидається, коли користувач перериває процес.
+
+```js
+import { CancelError } from '@nan0web/ui-cli'
+
+try {
+  // ... код, який може бути скасований
+} catch (err) {
+  if (err instanceof CancelError) {
+    console.error(err.message) // ← Операція скасована користувачем
+  }
+}
+```
+
+## API
+
+### `CLIInputAdapter`
+
+- **Методи**
+  - `requestForm(form, options)` — асинхронно обробляє запит форми.
+  - `requestSelect(config)` — асинхронно обробляє запит вибору.
+  - `requestInput(config)` — асинхронно обробляє запит одиничного вводу.
+
+### `Input`
+
+- **Властивості**
+  - `value` – (string) поточне введене значення.
+  - `stops` – (array) ключові слова‑стопи.
+  - `cancelled` – (boolean) чи було скасовано ввід.
+- **Методи**
+  - `toString()` – повертає поточне значення як рядок.
+  - `static from(input)` – створює інстанс з об’єкта вводу.
+
+### `ask(question)`
+
+- **Параметри**
+  - `question` (string) – текст підказки.
+- **Повертає**
+  - `Promise<string>` – відповідь користувача.
+
+### `createInput(stops)`
+
+- **Параметри**
+  - `stops` (array) – значення, при яких ввід скасовується.
+- **Повертає**
+  - функція‑обробник.
+
+### `select(config)`
+
+- **Параметри**
+  - `config.title` (string) – заголовок вибору.
+  - `config.prompt` (string) – підказка.
+  - `config.options` (array | Map) – варіанти вибору.
+- **Повертає**
+  - `Promise<{ index, value }>` – обраний елемент.
+
+### `next([conf])`
+
+- **Параметри**
+  - `conf` (string) – приймана послідовність клавіш.
+- **Повертає**
+  - `Promise<string>` – натиснута клавіша.
+
+### `pause(ms)`
+
+- **Параметри**
+  - `ms` (number) – затримка у мілісекундах.
+- **Повертає**
+  - `Promise<void>`.
+
+### `CancelError`
+
+Розширює `Error`, викидається при скасуванні вводу.
+
+## Тестування
+
+Усі експортовані класи та функції повинні проходити базові тести.
+
+## JavaScript
+
+Для автодоповнення використовується `d.ts` (type‑definition) файли.
+
+## Playground
+
+Як запустити скрипт Playground?
+
+```bash
+# Клонуємо репозиторій і запускаємо CLI playground
+git clone https://github.com/nan0web/ui-cli.git
+cd ui-cli
+npm install
+npm run playground
+```
+
+## Спільна розробка
+
+Як долучитися? – [дивіться тут](./CONTRIBUTING.md)
+
+## Ліцензія
+
+Як задокументовано у файлі ліцензії ISC – [дивіться тут](./LICENSE)

package/package.json

@@ -0,0 +1,38 @@
+{
+	"name": "@nan0web/ui-cli",
+	"version": "1.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",
+	"type": "module",
+	"scripts": {
+		"build": "tsc",
+		"test": "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:collect": "nan0test coverage",
+		"test:docs": "node --test --test-timeout=3333 src/README.md.js",
+		"test:release": "node --test \"releases/**/*.test.js\"",
+		"test:status": "nan0test status --hide-name --debug",
+		"playground": "node playground/main.js",
+		"precommit": "npm test",
+		"prepush": "npm test",
+		"prepare": "husky",
+		"release": "nan0release publish",
+		"clean": "rm -rf .cache/ && rm -rf dist/",
+		"clean:modules": "rm -rf node_modules"
+	},
+	"keywords": [
+		"ui",
+		"cli",
+		"input",
+		"adapter"
+	],
+	"author": "ЯRаСлав (YaRaSLove) <support@yaro.page>",
+	"license": "ISC",
+	"devDependencies": {
+		"@nan0web/log": "workspace:*",
+		"@nan0web/test": "workspace:*",
+		"@nan0web/ui": "workspace:*",
+		"@nan0web/db-fs": "workspace:*"
+	}
+}