@nan0web/ui-cli 1.1.0 → 2.0.0

package/src/components/prompt/Confirm.js

@@ -0,0 +1,29 @@
+import { createPrompt } from '../../core/Component.js'
+import { confirm as baseConfirm } from '../../ui/confirm.js'
+import { validateString, validateBoolean } from '../../core/PropValidation.js'
+
+export function Confirm(props) {
+	return createPrompt('Confirm', props, async (p) => {
+		// Validate props
+		validateString(p.message || p.children, 'message/children', 'Confirm', true)
+		validateBoolean(p.initial, 'initial', 'Confirm')
+
+		const yesLabel = p.t ? p.t('yes') : 'yes'
+		const noLabel = p.t ? p.t('no') : 'no'
+
+		const result = await baseConfirm({
+			message: p.message || p.children,
+			initial: p.initial,
+			format: (val) => (val ? yesLabel : noLabel),
+			active: yesLabel,
+			inactive: noLabel,
+		})
+
+		// Restore boolean value from formatted string
+		if (typeof result.value === 'string') {
+			result.value = result.value === yesLabel
+		}
+
+		return result
+	})
+}

package/src/components/prompt/DateTime.js

@@ -0,0 +1,26 @@
+import { createPrompt } from '../../core/Component.js'
+import { datetime as baseDateTime } from '../../ui/date-time.js'
+import { validateDate, validateString, validateFunction } from '../../core/PropValidation.js'
+
+export function DateTime(props) {
+	return createPrompt('DateTime', props, async (p) => {
+		// Validate props
+		validateString(p.message || p.label, 'message/label', 'DateTime', true)
+		validateDate(p.initial, 'initial', 'DateTime')
+		validateString(p.mask, 'mask', 'DateTime')
+		validateFunction(p.t, 't', 'DateTime')
+
+		// Auto-convert initial to Date if it's a string
+		let initial = p.initial
+		if (typeof initial === 'string') {
+			initial = new Date(initial)
+		}
+
+		return await baseDateTime({
+			message: p.message || p.label,
+			initial: initial,
+			mask: p.mask,
+			t: p.t,
+		})
+	})
+}

package/src/components/prompt/Input.js

@@ -0,0 +1,15 @@
+import { createPrompt } from '../../core/Component.js'
+import { text } from '../../ui/input.js'
+
+export function Input(props) {
+	return createPrompt('Input', props, async (p) => {
+		const config = {
+			message: p.message || p.label,
+			initial: p.initial || p.defaultValue,
+			type: p.type || 'text',
+			validate: p.validate || p.validator,
+			format: p.format,
+		}
+		return await text(config)
+	})
+}

package/src/components/prompt/Mask.js

@@ -0,0 +1,12 @@
+import { createPrompt } from '../../core/Component.js'
+import { mask as baseMask } from '../../ui/mask.js'
+
+export function Mask(props) {
+	return createPrompt('Mask', props, async (p) => {
+		return await baseMask({
+			message: p.message || p.label,
+			mask: p.mask,
+			placeholder: p.placeholder,
+		})
+	})
+}

package/src/components/prompt/Multiselect.js

@@ -0,0 +1,26 @@
+import { createPrompt } from '../../core/Component.js'
+import { multiselect as baseMultiselect } from '../../ui/multiselect.js'
+
+function getMultiselectInstructions(t) {
+	if (!t) return undefined
+	return (
+		`\n${t('Instructions')}:\n` +
+		`    ↑/↓: ${t('Highlight option')}\n` +
+		`    ←/→/[space]: ${t('Toggle selection')}\n` +
+		`    a: ${t('Toggle all')}\n` +
+		`    enter/return: ${t('Complete answer')}`
+	)
+}
+
+export function Multiselect(props) {
+	return createPrompt('Multiselect', props, async (p) => {
+		return await baseMultiselect({
+			message: p.message || p.label,
+			options: p.options,
+			limit: p.limit,
+			initial: p.initial,
+			instructions: p.instructions !== undefined ? p.instructions : getMultiselectInstructions(p.t),
+			hint: p.hint || (p.t ? p.t('hint.multiselect') : undefined),
+		})
+	})
+}

package/src/components/prompt/Next.js

@@ -0,0 +1,8 @@
+import { createPrompt } from '../../core/Component.js'
+import { next } from '../../ui/next.js'
+
+export function Next(props) {
+	return createPrompt('Next', props, async (p) => {
+		return await next(p.conf || p.keys)
+	})
+}

package/src/components/prompt/Password.js

@@ -0,0 +1,13 @@
+import { createPrompt } from '../../core/Component.js'
+import { text } from '../../ui/input.js'
+
+export function Password(props) {
+	return createPrompt('Password', props, async (p) => {
+		return await text({
+			message: p.message || p.label,
+			initial: p.initial,
+			type: 'password',
+			validate: p.validate || p.validator,
+		})
+	})
+}

package/src/components/prompt/Pause.js

@@ -0,0 +1,9 @@
+import { createPrompt } from '../../core/Component.js'
+import { pause } from '../../ui/next.js'
+
+export function Pause(props) {
+	if (typeof props === 'number') props = { ms: props }
+	return createPrompt('Pause', props, async (p) => {
+		return await pause(p.ms || 1000)
+	})
+}

package/src/components/prompt/ProgressBar.js

@@ -0,0 +1,16 @@
+import { createPrompt } from '../../core/Component.js'
+import { progress as baseProgress } from '../../ui/progress.js'
+
+/**
+ * ProgressBar Component.
+ * usage:
+ * const bar = await render(ProgressBar({ total: 100 }));
+ * bar.update(50);
+ */
+export function ProgressBar(props) {
+	return createPrompt('ProgressBar', props, async (p) => {
+		const bar = baseProgress(p)
+		// If action is provided, we could auto-run it, but progress bars usually strictly driven
+		return bar
+	})
+}

package/src/components/prompt/Select.js

@@ -0,0 +1,29 @@
+import { createPrompt } from '../../core/Component.js'
+import { select } from '../../ui/select.js'
+
+/**
+ * Select Prompt Component.
+ *
+ * @param {Object} props
+ * @param {string} props.message - Question/Title.
+ * @param {Array} props.options - Options list.
+ * @param {number} [props.limit] - Max visible options.
+ */
+export function Select(props) {
+	return createPrompt('Select', props, async (p) => {
+		// Map props to legacy select config
+		// New API uses 'message', 'children'?, 'options'
+		// Legacy used 'title', 'prompt', 'options'
+
+		const config = {
+			title: p.title || p.message, // Support both
+			options: p.options || p.children, // Support children as options?
+			limit: p.limit,
+			hint: p.hint || (p.t ? p.t('hint.select') : undefined),
+			// Pass other potential legacy props
+			...p,
+		}
+
+		return await select(config)
+	})
+}

package/src/components/prompt/Slider.js

@@ -0,0 +1,16 @@
+import { createPrompt } from '../../core/Component.js'
+import { slider as baseSlider } from '../../ui/slider.js'
+
+export function Slider(props) {
+	return createPrompt('Slider', props, async (p) => {
+		return await baseSlider({
+			message: p.message || p.label,
+			initial: p.initial,
+			min: p.min,
+			max: p.max,
+			step: p.step,
+			jump: p.jump,
+			t: p.t,
+		})
+	})
+}

package/src/components/prompt/Spinner.js

@@ -0,0 +1,29 @@
+import { createPrompt } from '../../core/Component.js'
+import { spinner as baseSpinner } from '../../ui/spinner.js'
+
+/**
+ * Spinner Component.
+ * Usage: await render(Spinner({ message: 'Loading...', action: promise }))
+ *
+ * @param {Object} props
+ * @param {string} props.message - Main message.
+ * @param {Promise<any>} [props.action] - Async action to wait for.
+ * @param {string} [props.successMessage] - Message on success.
+ * @param {string} [props.errorMessage] - Message on error.
+ */
+export function Spinner(props) {
+	return createPrompt('Spinner', props, async (p) => {
+		const spin = baseSpinner(p.message)
+		if (p.action && p.action.then) {
+			try {
+				const res = await p.action
+				spin.success(p.successMessage || 'Done')
+				return res
+			} catch (err) {
+				spin.error(p.errorMessage || 'Error')
+				throw err
+			}
+		}
+		return spin // Return controller if no action (legacy behavior)
+	})
+}

package/src/components/prompt/Toggle.js

@@ -0,0 +1,13 @@
+import { createPrompt } from '../../core/Component.js'
+import { toggle as baseToggle } from '../../ui/toggle.js'
+
+export function Toggle(props) {
+	return createPrompt('Toggle', props, async (p) => {
+		return await baseToggle({
+			message: p.message || p.children,
+			initial: p.initial,
+			active: p.active,
+			inactive: p.inactive,
+		})
+	})
+}

package/src/components/prompt/Tree.js

@@ -0,0 +1,17 @@
+import { createPrompt } from '../../core/Component.js'
+import { tree } from '../../ui/tree.js'
+
+export function Tree(props) {
+	return createPrompt('Tree', props, async (p) => {
+		return await tree({
+			message: p.message || p.title,
+			mode: p.mode,
+			tree: p.tree || p.options || p.data,
+			loader: p.loader,
+			limit: p.limit,
+			initialExpanded: p.expanded,
+			multiselect: p.multiselect,
+			t: p.t,
+		})
+	})
+}

package/src/components/view/Alert.js

@@ -0,0 +1,78 @@
+import { createView } from '../../core/Component.js'
+import Logger from '@nan0web/log'
+import { beep } from '../../ui/input.js'
+
+/**
+ * Alert View Component.
+ *
+ * @param {Object} props
+ * @param {string} props.title - Title of the alert.
+ * @param {string} props.children - Message content.
+ * @param {'info'|'success'|'warning'|'error'} [props.variant='info'] - Style variant.
+ * @param {string} [props.message] - Alias for children (legacy support).
+ * @param {boolean} [props.sound] - Play sound (side-effect during toString is acceptable here as it invokes on print).
+ */
+export function Alert(props) {
+	// Normalize props (allow string argument as children shorthand)
+	const defaults = { title: '', children: '', variant: 'info' }
+
+	// If props is string, treat as children, otherwise merge with defaults
+	const safeProps =
+		typeof props === 'string' ? { ...defaults, children: props } : { ...defaults, ...props }
+
+	const { title, children, message = children, variant } = safeProps
+
+	return createView('Alert', props, () => {
+		// Logic extracted from old alert.js
+		const sound = props.sound || variant === 'error' || variant === 'warning'
+
+		// Note: beep() is technically a side effect.
+		// In "toString" pattern, side effects happen when string conversion receives focus.
+		// It's acceptable for sound, but we should be careful.
+		if (sound) beep()
+
+		const colors = {
+			info: Logger.CYAN,
+			success: Logger.GREEN,
+			warning: Logger.YELLOW,
+			error: Logger.RED,
+		}
+
+		const color = colors[variant] || Logger.WHITE
+		const icon =
+			{
+				info: 'ℹ',
+				success: '✔',
+				warning: '⚠',
+				error: '✖',
+			}[variant] || '•'
+
+		const msgStr = String(message || '')
+		const lines = msgStr.split('\n')
+		const paddedLines = lines.map((line) => `   ${line}`)
+
+		// Calculate max line length for border (at least 60 chars or based on content)
+		const contentLengths = [title ? title.length + 6 : 0, ...paddedLines.map((l) => l.length)]
+		const maxContentLen = Math.max(...contentLengths)
+		const len = Math.max(60, maxContentLen + 2)
+
+		const border = Logger.style('━'.repeat(len), { color })
+		let out = ''
+
+		out += `\n${border}\n`
+		if (title) {
+			out += Logger.style(` ${icon} ${title} `, { color }) + ' \n'
+			out += Logger.style('─'.repeat(len) + '\n', { color: Logger.DIM })
+		}
+		lines.forEach((line) => {
+			if (line.trim()) {
+				out += '   ' + Logger.style(line.trim(), { color }) + '\n'
+			} else {
+				out += '\n'
+			}
+		})
+		out += `${border}\n`
+
+		return out
+	})
+}

package/src/components/view/Badge.js

@@ -0,0 +1,11 @@
+import { createView } from '../../core/Component.js'
+import { badge as baseBadge } from '../../ui/badge.js'
+
+export function Badge(props) {
+	if (typeof props === 'string') {
+		props = { label: props }
+	}
+	return createView('Badge', props, (p) => {
+		return baseBadge(p.label, p.variant)
+	})
+}

package/src/components/view/Nav.js

@@ -0,0 +1,23 @@
+import { createView } from '../../core/Component.js'
+import { breadcrumbs, tabs, steps } from '../../ui/nav.js'
+
+export function Breadcrumbs(props) {
+	if (Array.isArray(props)) props = { items: props }
+	return createView('Breadcrumbs', props, (p) => {
+		return breadcrumbs(p.items, p.options)
+	})
+}
+
+export function Tabs(props) {
+	if (Array.isArray(props)) props = { items: props }
+	return createView('Tabs', props, (p) => {
+		return tabs(p.items, p.active)
+	})
+}
+
+export function Steps(props) {
+	if (Array.isArray(props)) props = { items: props }
+	return createView('Steps', props, (p) => {
+		return steps(p.items, p.current)
+	})
+}

package/src/components/view/Table.js

@@ -0,0 +1,12 @@
+import { createPrompt } from '../../core/Component.js'
+import { table as baseTable } from '../../ui/table.js'
+
+/**
+ * Table Component.
+ * Can be static (display only) or interactive (filter/select).
+ */
+export function Table(props) {
+	return createPrompt('Table', props, async (p) => {
+		return await baseTable(p)
+	})
+}

package/src/components/view/Toast.js

@@ -0,0 +1,9 @@
+import { createView } from '../../core/Component.js'
+import { toast as baseToast } from '../../ui/toast.js'
+
+export function Toast(props) {
+	if (typeof props === 'string') props = { message: props, variant: 'info' }
+	return createView('Toast', props, (p) => {
+		return baseToast(p.message, p.variant)
+	})
+}

package/src/core/Component.js

@@ -0,0 +1,79 @@
+/**
+ * Core Component logic.
+ *
+ * Defines the contract for View (static) and Prompt (interactive) components.
+ */
+
+export const ComponentSymbol = Symbol.for('ui.component')
+export const PromptSymbol = Symbol.for('ui.prompt')
+
+/**
+ * Creates a Static View Component.
+ * These components are synchronous and can be stringified directly.
+ *
+ * @param {string} displayName - Name of the component (e.g. 'Alert').
+ * @param {any} props - Props passed to the component.
+ * @param {Function} formatFn - Pure function (props) => string.
+ */
+export function createView(displayName, props, formatFn) {
+	const component = {
+		$$typeof: ComponentSymbol,
+		type: displayName,
+		props,
+	}
+
+	// Magic: toString calls the formatter
+	// We also implement nodejs.util.inspect.custom so console.log works directly
+	const toString = () => {
+		try {
+			return formatFn(props)
+		} catch (originalError) {
+			const e = /** @type {Error} */ (originalError)
+			return `[${displayName} Error: ${e.message}]`
+		}
+	}
+
+	Object.defineProperty(component, 'toString', {
+		value: toString,
+		enumerable: false,
+	})
+
+	Object.defineProperty(component, Symbol.for('nodejs.util.inspect.custom'), {
+		value: () => toString(),
+		enumerable: false,
+	})
+
+	return component
+}
+
+/**
+ * Creates an Interactive Prompt Component.
+ * These components are asynchronous and require `render()` or `await` handling.
+ *
+ * @param {string} displayName - Name of the component.
+ * @param {any} props - Props.
+ * @param {Function} executorFn - Async function (props) => Promise<result>.
+ */
+export function createPrompt(displayName, props, executorFn) {
+	const component = {
+		$$typeof: PromptSymbol,
+		type: displayName,
+		props,
+		execute: () => executorFn(props),
+	}
+
+	// Prompts cannot be stringified meaningfully
+	const toString = () => `[Prompt: ${displayName}]`
+
+	Object.defineProperty(component, 'toString', {
+		value: toString,
+		enumerable: false,
+	})
+
+	Object.defineProperty(component, Symbol.for('nodejs.util.inspect.custom'), {
+		value: toString,
+		enumerable: false,
+	})
+
+	return component
+}

package/src/core/PropValidation.js

@@ -0,0 +1,138 @@
+/**
+ * Prop validation utilities for UI components.
+ * @module core/PropValidation
+ */
+
+/**
+ * Validates that a value is a valid Date object or a parseable date string.
+ * @param {any} value
+ * @param {string} propName
+ * @param {string} componentName
+ * @throws {TypeError} if validation fails
+ */
+export function validateDate(value, propName, componentName) {
+	if (value === undefined || value === null) {
+		return // Optional prop
+	}
+
+	if (value instanceof Date) {
+		if (isNaN(value.getTime())) {
+			throw new TypeError(
+				`[${componentName}] Invalid Date object for prop "${propName}". Date is invalid.`
+			)
+		}
+		return
+	}
+
+	if (typeof value === 'string') {
+		const parsed = new Date(value)
+		if (isNaN(parsed.getTime())) {
+			throw new TypeError(
+				`[${componentName}] Invalid date string for prop "${propName}": "${value}". ` +
+					`Expected a valid ISO date string (e.g., "2026-02-05" or "2026-02-05T10:30:00").`
+			)
+		}
+		return
+	}
+
+	throw new TypeError(
+		`[${componentName}] Invalid type for prop "${propName}". ` +
+			`Expected Date object or date string, got ${typeof value}.`
+	)
+}
+
+/**
+ * Validates that a value is a string.
+ * @param {any} value
+ * @param {string} propName
+ * @param {string} componentName
+ * @param {boolean} required
+ * @throws {TypeError} if validation fails
+ */
+export function validateString(value, propName, componentName, required = false) {
+	if (value === undefined || value === null) {
+		if (required) {
+			throw new TypeError(`[${componentName}] Required prop "${propName}" is missing.`)
+		}
+		return
+	}
+
+	if (typeof value !== 'string') {
+		throw new TypeError(
+			`[${componentName}] Invalid type for prop "${propName}". ` +
+				`Expected string, got ${typeof value}.`
+		)
+	}
+}
+
+/**
+ * Validates that a value is a function.
+ * @param {any} value
+ * @param {string} propName
+ * @param {string} componentName
+ * @param {boolean} required
+ * @throws {TypeError} if validation fails
+ */
+export function validateFunction(value, propName, componentName, required = false) {
+	if (value === undefined || value === null) {
+		if (required) {
+			throw new TypeError(`[${componentName}] Required prop "${propName}" is missing.`)
+		}
+		return
+	}
+
+	if (typeof value !== 'function') {
+		throw new TypeError(
+			`[${componentName}] Invalid type for prop "${propName}". ` +
+				`Expected function, got ${typeof value}.`
+		)
+	}
+}
+
+/**
+ * Validates that a value is a boolean.
+ * @param {any} value
+ * @param {string} propName
+ * @param {string} componentName
+ * @param {boolean} required
+ * @throws {TypeError} if validation fails
+ */
+export function validateBoolean(value, propName, componentName, required = false) {
+	if (value === undefined || value === null) {
+		if (required) {
+			throw new TypeError(`[${componentName}] Required prop "${propName}" is missing.`)
+		}
+		return
+	}
+
+	if (typeof value !== 'boolean') {
+		throw new TypeError(
+			`[${componentName}] Invalid type for prop "${propName}". ` +
+				`Expected boolean, got ${typeof value}.`
+		)
+	}
+}
+
+/**
+ * Validates that a value is a number.
+ * @param {any} value
+ * @param {string} propName
+ * @param {string} componentName
+ * @param {boolean} required
+ * @throws {TypeError} if validation fails
+ */
+export function validateNumber(value, propName, componentName, required = false) {
+	if (value === undefined || value === null) {
+		if (required) {
+			throw new TypeError(`[${componentName}] Required prop "${propName}" is missing.`)
+		}
+		return
+	}
+
+	if (typeof value !== 'number' || isNaN(value)) {
+		throw new TypeError(
+			`[${componentName}] Invalid type for prop "${propName}". ` +
+				`Expected number, got ${typeof value}.`
+		)
+	}
+}

package/src/core/render.js

@@ -0,0 +1,37 @@
+/**
+ * Component Renderer.
+ *
+ * Handles both Static Views and Interactive Prompts.
+ */
+
+export async function render(component) {
+	// 1. Resolve Promises (if component is constructed async)
+	if (component instanceof Promise) {
+		component = await component
+	}
+
+	// 2. Handle null/undefined
+	if (!component) return
+
+	// 3. Handle Interactive Prompts (Active)
+	if (typeof component.execute === 'function') {
+		const result = await component.execute()
+		// If result is the unified return contract { value, cancelled }, unwrap it
+		if (result && typeof result === 'object' && 'value' in result) {
+			return result.value
+		}
+		return result
+	}
+
+	// 4. Handle Static Views (Passive)
+	// If it has a specific toString implementation (which our Views do), use it.
+	// Or if it's just a string.
+	const output = String(component)
+
+	// We append a newline for better UX in terminals, unless it's empty
+	if (output) {
+		process.stdout.write(output + '\n')
+	}
+
+	return output
+}