@nan0web/ui-cli 1.0.0

package/playground/forms/addressForm.js

@@ -0,0 +1,37 @@
+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

@@ -0,0 +1,26 @@
+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

@@ -0,0 +1,33 @@
+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

@@ -0,0 +1,36 @@
+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

@@ -0,0 +1,81 @@
+#!/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

@@ -0,0 +1,25 @@
+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

@@ -0,0 +1,12 @@
+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

@@ -0,0 +1,25 @@
+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.js

@@ -0,0 +1,219 @@
+import { Message } from '@nan0web/co'
+import { UIForm, InputAdapter as BaseInputAdapter, InputMessage as BaseInputMessage } from '@nan0web/ui'
+import { ask } from './ui/input.js'
+import { select } from './ui/select.js'
+
+/** @typedef {Partial<UIForm>} FormMessageValue */
+/** @typedef {Partial<Message> | null} InputMessageValue */
+
+/**
+ * Extends the generic {@link BaseInputMessage} to carry a {@link UIForm}
+ * instance alongside the usual input message payload.
+ *
+ * The original {@link BaseInputMessage} expects a `value` of type
+ * {@link InputMessageValue} (a {@link Message} payload).  To remain
+ * compatible we keep `value` unchanged and store the form data in a
+ * separate `form` property.
+ */
+class FormMessage extends BaseInputMessage {
+	/** @type {UIForm} Form data associated with the message */
+	form
+
+	/**
+	 * Creates a new {@link FormMessage}.
+	 *
+	 * @param {object} props - Message properties.
+	 * @param {FormMessageValue} [props.form={}] UIForm instance or data.
+	 * @param {InputMessageValue} [props.value=null] Retained for compatibility.
+	 * @param {string[]|string} [props.options=[]] Available options.
+	 * @param {boolean} [props.waiting=false] Waiting flag.
+	 * @param {boolean} [props.escaped=false] Escape flag.
+	 */
+	constructor(props = {}) {
+		const {
+			form = {},
+			...rest
+		} = props
+		// Initialise the parent with the remaining properties.
+		// Cast to `any` to avoid type‑mismatch between duplicated InputMessage
+		// definitions across packages.
+		super(/** @type {any} */ (rest))
+
+		// Store the UIForm; accept an object, UIForm or a plain payload.
+		this.form = UIForm.from(form)
+	}
+
+	/**
+	 * Creates a {@link FormMessage} from an existing instance or plain data.
+	 *
+	 * @param {FormMessage|object} input – Existing message or raw data.
+	 * @returns {FormMessage}
+	 */
+	static from(input) {
+		if (input instanceof FormMessage) return input
+		const {
+			form = {},
+			...rest
+		} = input ?? {}
+		return new FormMessage({ form, ...rest })
+	}
+}
+
+/**
+ * CLI specific adapter extending the generic {@link BaseInputAdapter}.
+ * Implements concrete `ask` and `select` helpers that rely on the CLI utilities.
+ */
+export default class CLIInputAdapter extends BaseInputAdapter {
+	/**
+	 * Interactively fill a {@link UIForm} field‑by‑field.
+	 *
+	 * @param {UIForm} form – Form definition to be filled.
+	 * @param {Object} options – Request options.
+	 * @param {boolean} [options.silent=true] Suppress title output when `true`.
+	 * @returns {Promise<FormMessage>} Message with `escaped` = true on cancel,
+	 *                                 otherwise `escaped` = false and the completed form attached as `form`.
+	 */
+	async requestForm(form, options = {}) {
+		const { silent = true } = options
+
+		if (!silent) {
+			console.log(`\n${form.title}\n`)
+		}
+
+		let formData = { ...form.state }
+		let currentFieldIndex = 0
+
+		while (currentFieldIndex < form.fields.length) {
+			const field = form.fields[currentFieldIndex]
+			const prompt = field.label || field.name
+
+			const input = await this.ask(`${prompt}${field.required ? ' *' : ''}: `)
+
+			// Cancel (Esc or empty string)
+			if ([FormMessage.ESCAPE, ''].includes(input)) {
+				return FormMessage.from({
+					form: {},
+					escaped: true,
+					action: 'form-cancel',
+					id: form.id,
+				})
+			}
+
+			// Navigation shortcuts
+			const trimmed = input.trim()
+			if (trimmed === '::prev' || trimmed === '::back') {
+				currentFieldIndex = Math.max(0, currentFieldIndex - 1)
+				continue
+			}
+			if (trimmed === '::next' || trimmed === '::skip') {
+				currentFieldIndex++
+				continue
+			}
+
+			// Skip optional fields when empty
+			if (trimmed === '' && !field.required) {
+				currentFieldIndex++
+				continue
+			}
+
+			// Validate using the form's schema / field definition
+			const schema = field.constructor
+			const { isValid, errors } = form.validateValue(field.name, trimmed, schema)
+			if (!isValid) {
+				const errorMessages = Object.values(errors)
+				console.log(`\x1b[31mError: ${errorMessages.join(', ')}\x1b[0m`)
+				continue // stay on current field
+			}
+
+			// Store validated value
+			formData[field.name] = trimmed
+			currentFieldIndex++
+		}
+
+		// Final form validation
+		const finalForm = form.setData(formData)
+		const { isValid, errors } = finalForm.validate()
+		if (!isValid) {
+			console.log('\n' + Object.values(errors).join('\n'))
+			return await this.requestForm(form, options) // retry recursively
+		}
+
+		return FormMessage.from({
+			form: finalForm,
+			escaped: false,
+			action: 'form-submit',
+			id: form.id,
+		})
+	}
+
+	/**
+	 * Request a selection from a list of options.
+	 *
+	 * @param {Object} config – Selection configuration.
+	 * @param {string} config.title – Title displayed before the list.
+	 * @param {string} config.prompt – Prompt text.
+	 * @param {Array<string>|Map<string,string>|Array<{label:string,value:string}>} config.options – Options to choose from.
+	 * @param {string} config.id – Identifier for the resulting message.
+	 * @returns {Promise<BaseInputMessage>} Message containing chosen value and metadata.
+	 */
+	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,
+			})
+			return BaseInputMessage.from({
+				value: result.value,
+				data: result,
+				id: config.id,
+			})
+		} catch (error) {
+			if (error instanceof this.CancelError) {
+				return BaseInputMessage.from({
+					value: '',
+					id: config.id,
+				})
+			}
+			throw error
+		}
+	}
+
+	/**
+	 * Simple string input request.
+	 *
+	 * @param {Object} config Input configuration.
+	 * @param {string} config.prompt Prompt text.
+	 * @param {string} config.id Identifier for the resulting message.
+	 * @param {string} [config.label] Optional label used as fallback.
+	 * @param {string} [config.name] Optional name used as fallback.
+	 * @returns {Promise<BaseInputMessage>} Message containing the entered text.
+	 */
+	async requestInput(config) {
+		const prompt = config.prompt ?? `${config.label ?? config.name}: `
+		const input = await this.ask(prompt)
+
+		if (input === '') {
+			return BaseInputMessage.from({
+				value: '',
+				id: config.id,
+			})
+		}
+
+		return BaseInputMessage.from({
+			value: input,
+			id: config.id,
+		})
+	}
+
+	/** @inheritDoc */
+	async ask(question) {
+		return ask(question)
+	}
+
+	/** @inheritDoc */
+	async select(config) {
+		return select(config)
+	}
+}

package/src/InputAdapter.test.js

@@ -0,0 +1,117 @@
+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
+	})
+})