@nan0web/ui-cli 1.0.0 → 1.0.2

package/docs/uk/README.md

@@ -1,294 +0,0 @@
-# @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/playground/forms/addressForm.js

@@ -1,37 +0,0 @@
-import { UIForm, FormInput } from '@nan0web/ui'
-
-/**
- * Creates an address information form
- * @param {Function} t - Translation function
- * @returns {UIForm} Address form
- */
-export function createAddressForm(t) {
-	return new UIForm({
-		title: t('Address information'),
-		id: 'address-form',
-		state: {},
-		fields: [
-			new FormInput({
-				name: 'street',
-				label: t('Street'),
-				required: true
-			}),
-			new FormInput({
-				name: 'city',
-				label: t('City'),
-				required: true
-			}),
-			new FormInput({
-				name: 'postalCode',
-				label: t('Postal code'),
-				type: FormInput.TYPES.TEXT,
-				required: false
-			}),
-			new FormInput({
-				name: 'country',
-				label: t('Country'),
-				required: true
-			})
-		]
-	})
-}

package/playground/forms/ageForm.js

@@ -1,26 +0,0 @@
-import { UIForm, FormInput } from '@nan0web/ui'
-
-/**
- * Creates an age confirmation form
- * @param {Function} t - Translation function
- * @returns {UIForm} Age confirmation form
- */
-export function createAgeForm(t) {
-	return new UIForm({
-		title: t('Age confirmation form'),
-		id: 'age-confirmation',
-		state: {},
-		fields: [
-			new FormInput({
-				name: 'age',
-				label: t('Please enter your age'),
-				type: FormInput.TYPES.NUMBER,
-				validator: (value) => {
-					const num = Number(value)
-					return num >= 18 ? null : t('You must be at least 18 years old')
-				},
-				required: true
-			})
-		]
-	})
-}

package/playground/forms/profileForm.js

@@ -1,33 +0,0 @@
-import { UIForm, FormInput } from '@nan0web/ui'
-
-/**
- * Creates a profile update form
- * @param {Function} t - Translation function
- * @returns {UIForm} Profile update form
- */
-export function createProfileForm(t) {
-	return new UIForm({
-		title: t('Profile update form'),
-		id: 'profile-update',
-		state: {},
-		fields: [
-			new FormInput({
-				name: 'username',
-				label: t('Username'),
-				required: true
-			}),
-			new FormInput({
-				name: 'bio',
-				label: t('Biography'),
-				type: FormInput.TYPES.TEXTAREA,
-				required: false
-			}),
-			new FormInput({
-				name: 'newsletter',
-				label: t('Subscribe to newsletter'),
-				type: FormInput.TYPES.CHECKBOX,
-				required: false
-			})
-		]
-	})
-}

package/playground/forms/userForm.js

@@ -1,36 +0,0 @@
-import { UIForm, FormInput } from '@nan0web/ui'
-
-/**
- * Creates a user registration form
- * @param {Function} t - Translation function
- * @returns {UIForm} User registration form
- */
-export function createUserForm(t) {
-	return new UIForm({
-		title: t('User Registration Form'),
-		id: 'user-registration',
-		state: {},
-		fields: [
-			new FormInput({
-				name: 'name',
-				label: t('Full name'),
-				required: true
-			}),
-			new FormInput({
-				name: 'email',
-				label: t('Email address'),
-				type: FormInput.TYPES.EMAIL,
-				required: true
-			}),
-			new FormInput({
-				name: 'phone',
-				label: t('Phone number'),
-				type: FormInput.TYPES.TEXT,
-				validator: (value) => {
-					return value.length >= 10 && value.length <= 15 ? null : t('Invalid phone number')
-				},
-				required: false
-			})
-		]
-	})
-}

package/playground/main.js

@@ -1,81 +0,0 @@
-#!/usr/bin/env node
-
-import Logger from '@nan0web/log'
-import { CLIInputAdapter } from '../src/index.js'
-import { createUserForm } from './forms/userForm.js'
-import { createAgeForm } from './forms/ageForm.js'
-import { createAddressForm } from './forms/addressForm.js'
-import { createProfileForm } from './forms/profileForm.js'
-import createT, { localesMap } from "./vocabs/index.js"
-
-console = new Logger()
-
-const adapter = new CLIInputAdapter()
-
-console.info(Logger.style(Logger.LOGO, { color: "magenta" }))
-console.warn('=== @nan0web/ui CLI Playground ===\n')
-
-// Language selection
-const langResult = await adapter.requestSelect({
-	title: "Language selection",
-	prompt: "Choose language (1-2): ",
-	options: localesMap,
-	elementId: "language-select"
-})
-
-if (langResult.action === 'select-cancel') {
-	console.warn('Language selection cancelled')
-	process.exit(0)
-}
-
-const selectedLang = langResult.value
-const t = createT(selectedLang)
-
-console.success(`${t('Language selection')}: ${t(selectedLang)}`)
-console.info()
-
-// User registration form
-const userForm = createUserForm(t)
-const userResult = await adapter.requestForm(userForm, { silent: false })
-
-if (userResult.action === 'form-submit') {
-	console.success(t('Welcome to our platform!'))
-	console.info('User data:', userResult.data)
-	console.info()
-} else {
-	console.warn('User registration cancelled')
-}
-
-// Age confirmation form
-const ageForm = createAgeForm(t)
-const ageResult = await adapter.requestForm(ageForm, { silent: false })
-
-if (ageResult.action === 'form-submit') {
-	console.success(`Confirmed age: ${ageResult.data.age}`)
-} else {
-	console.warn('Age confirmation cancelled')
-}
-
-// Address information form
-const addressForm = createAddressForm(t)
-const addressResult = await adapter.requestForm(addressForm, { silent: false })
-
-if (addressResult.action === 'form-submit') {
-	console.success('Address information collected')
-	console.info('Address data:', addressResult.data)
-	console.info()
-} else {
-	console.warn('Address form cancelled')
-}
-
-// Profile update form
-const profileForm = createProfileForm(t)
-const profileResult = await adapter.requestForm(profileForm, { silent: false })
-
-if (profileResult.action === 'form-submit') {
-	console.success('Profile updated')
-	console.info('Profile data:', profileResult.data)
-	console.info()
-} else {
-	console.warn('Profile update cancelled')
-}

package/playground/vocabs/en.js

@@ -1,25 +0,0 @@
-export default {
-	"User Registration Form": "User Registration Form",
-	"Full name": "Full name",
-	"Email address": "Email address",
-	"Phone number": "Phone number",
-	"Age confirmation form": "Age confirmation form",
-	"Please enter your age": "Please enter your age",
-	"Language selection": "Language selection",
-	"Choose language": "Choose language",
-	"English": "English",
-	"Ukrainian": "Ukrainian",
-	"You must be at least 18 years old": "You must be at least 18 years old",
-	"Invalid phone number": "Invalid phone number",
-	"Welcome to our platform!": "Welcome to our platform!",
-	"Address information": "Address information",
-	"Street": "Street",
-	"City": "City",
-	"Postal code": "Postal code",
-	"Country": "Country",
-	"Profile update form": "Profile update form",
-	"Username": "Username",
-	"Biography": "Biography",
-	"Newsletter subscription": "Newsletter subscription",
-	"Subscribe to newsletter": "Subscribe to newsletter"
-}

package/playground/vocabs/index.js

@@ -1,12 +0,0 @@
-import i18n, { createT } from "@nan0web/i18n"
-import en from "./en.js"
-import uk from "./uk.js"
-
-const getVocab = i18n({ en, uk })
-
-export const localesMap = new Map([
-	["en", "English"],
-	["uk", "Українська"],
-])
-
-export default (locale) => createT(getVocab(locale))

package/playground/vocabs/uk.js

@@ -1,25 +0,0 @@
-export default {
-	"User Registration Form": "Форма реєстрації користувача",
-	"Full name": "Повне ім'я",
-	"Email address": "Електронна пошта",
-	"Phone number": "Номер телефону",
-	"Age confirmation form": "Форма підтвердження віку",
-	"Please enter your age": "Будь ласка, введіть ваш вік",
-	"Language selection": "Вибір мови",
-	"Choose language": "Виберіть мову",
-	"English": "Англійська",
-	"Ukrainian": "Українська",
-	"You must be at least 18 years old": "Вам має бути не менше 18 років",
-	"Invalid phone number": "Невірний номер телефону",
-	"Welcome to our platform!": "Ласкаво просимо на нашу платформу!",
-	"Address information": "Інформація про адресу",
-	"Street": "Вулиця",
-	"City": "Місто",
-	"Postal code": "Поштовий код",
-	"Country": "Країна",
-	"Profile update form": "Форма оновлення профілю",
-	"Username": "Ім'я користувача",
-	"Biography": "Біографія",
-	"Newsletter subscription": "Підписка на розсилку",
-	"Subscribe to newsletter": "Підписатися на розсилку"
-}

package/src/InputAdapter.test.js

@@ -1,117 +0,0 @@
-import { describe, it } from 'node:test'
-import assert from 'node:assert/strict'
-import { UIForm, FormInput, InputMessage } from '@nan0web/ui'
-import { CancelError } from '@nan0web/ui/core'
-import CLIInputAdapter from './InputAdapter.js'
-
-// Awaits for the user input.
-describe('CLIInputAdapter', () => {
-	it('should create instance', () => {
-		const adapter = new CLIInputAdapter()
-		assert.ok(adapter instanceof CLIInputAdapter)
-	})
-
-	it('should validate form fields', async () => {
-		const adapter = new CLIInputAdapter()
-
-		// Mock ask for testing
-		adapter.ask = () => Promise.resolve('test@example.com')
-
-		const form = new UIForm({
-			title: 'Test Form',
-			elementId: 'test-form',
-			fields: [
-				new FormInput({
-					name: 'email',
-					label: 'Email',
-					type: 'email',
-					required: true
-				})
-			]
-		})
-
-		const result = await adapter.requestForm(form, { silent: true })
-		assert.equal(result.form.state.email, 'test@example.com')
-	})
-
-	it('should handle form cancellation', async () => {
-		const adapter = new CLIInputAdapter()
-
-		// Mock ask for cancellation
-		adapter.ask = () => Promise.resolve(InputMessage.ESCAPE)
-
-		const form = new UIForm({
-			title: 'Test Form',
-			elementId: 'test-form',
-			fields: [
-				new FormInput({
-					name: 'name',
-					label: 'Name',
-					required: true
-				})
-			]
-		})
-
-		const result = await adapter.requestForm(form, { silent: true })
-		assert.equal(result.escaped, true)
-	})
-
-	it('should have CancelError static property', () => {
-		assert.ok(CLIInputAdapter.CancelError)
-		const error = new CLIInputAdapter.CancelError()
-		assert.equal(error.name, "CancelError")
-		assert.equal(error.message, "Operation cancelled by user")
-	})
-
-	it('should implement ask method', async () => {
-		const adapter = new CLIInputAdapter()
-		// Mock internal ask to avoid stdin interaction
-		const originalAsk = adapter.ask
-		adapter.ask = () => Promise.resolve('test answer')
-
-		const answer = await adapter.ask('Test question?')
-		assert.equal(answer, 'test answer')
-
-		// Restore original
-		adapter.ask = originalAsk
-	})
-
-	it('should implement select method', async () => {
-		const adapter = new CLIInputAdapter()
-		// Mock internal select to avoid stdin interaction
-		const originalSelect = adapter.select
-		adapter.select = () => Promise.resolve({ value: 'option1', index: 0 })
-
-		const result = await adapter.select({
-			title: 'Test Select',
-			prompt: 'Choose:',
-			options: ['option1', 'option2']
-		})
-		assert.equal(result.value, 'option1')
-		assert.equal(result.index, 0)
-
-		// Restore original
-		adapter.select = originalSelect
-	})
-
-	it('should handle select cancellation', async () => {
-		const adapter = new CLIInputAdapter()
-
-		// Mock select to throw CancelError
-		const originalSelect = adapter.select
-		adapter.select = () => Promise.reject(new CancelError())
-
-		const config = {
-			title: 'Test Select',
-			prompt: 'Choose:',
-			id: 'test-select',
-			options: ['option1', 'option2']
-		}
-
-		const result = await adapter.requestSelect(config)
-		assert.deepStrictEqual(result.value, InputMessage.from({}).value)
-
-		// Restore original
-		adapter.select = originalSelect
-	})
-})