@nan0web/ui-cli 1.1.1 → 2.0.0

package/src/ui/mask.js

@@ -0,0 +1,132 @@
+/**
+ * Mask module – provides formatted input handling.
+ *
+ * @module ui/mask
+ */
+
+import prompts from 'prompts'
+import { CancelError } from '@nan0web/ui/core'
+import { beep } from './input.js'
+
+/**
+ * Validates and optionally formats user input based on a pattern.
+ * Pattern uses '#' for numbers and 'A' for letters.
+ * Example: '(###) ###-####'
+ *
+ * @param {Object} config
+ * @param {string} config.message - Prompt question
+ * @param {string} config.mask - Mask pattern (e.g., '###-###')
+ * @param {string} [config.placeholder] - Hint for the user
+ * @param {Function} [config.t] - Translation function
+ * @returns {Promise<{value: string, cancelled: boolean}>}
+ */
+/**
+ * Cleans the input value by stripping non-alphanumerics and smart prefix.
+ */
+export function cleanMaskInput(value, mask) {
+	let cleanValue = value.toString().replace(/[^a-zA-Z0-9]/g, '')
+
+	// Smart Prefix Detection:
+	// If the user typed the mask's static prefix (e.g. '38' for '+38'),
+	// remove it from the input to prevent duplication.
+	const firstPlaceholderIndex = mask.search(/[#0A]/)
+	if (firstPlaceholderIndex > 0) {
+		const maskPrefix = mask.substring(0, firstPlaceholderIndex).replace(/[^a-zA-Z0-9]/g, '')
+		if (maskPrefix && cleanValue.startsWith(maskPrefix)) {
+			// Special Check: If the user typed ONLY the prefix so far, don't strip it yet?
+			// Actually, removing it is safer to avoid "Format must be: +38 (38)" error midway?
+			// But for full validation, we strip it.
+			cleanValue = cleanValue.substring(maskPrefix.length)
+		}
+	}
+	return cleanValue
+}
+
+/**
+ * Formats a value according to the given mask.
+ * pattern: # = digit, A = letter, 0 = digit.
+ *
+ * @param {string} value
+ * @param {string} mask
+ * @returns {string}
+ */
+export function formatMask(value, mask) {
+	let i = 0
+	let v = 0
+	let result = ''
+
+	const cleanValue = cleanMaskInput(value, mask)
+
+	while (i < mask.length && v < cleanValue.length) {
+		const maskChar = mask[i]
+		if (maskChar === '#' || maskChar === '0' || maskChar === 'A') {
+			result += cleanValue[v]
+			v++
+		} else {
+			result += maskChar
+		}
+		i++
+	}
+	return result
+}
+
+export async function mask(config) {
+	const { message, mask, placeholder, t } = config
+
+	const validate = (val) => {
+		if (!val) {
+			beep()
+			return 'Input is required'
+		}
+
+		// Support '#', '0' for numbers and 'A' for letters.
+		const cleanMask = mask.replace(/[^#0A]/g, '')
+		const cleanVal = cleanMaskInput(val, mask)
+
+		if (cleanVal.length !== cleanMask.length) {
+			beep()
+			return `${config.t ? config.t('Format must be:') : 'Format must be:'} ${mask}`
+		}
+
+		return true
+	}
+
+	/*
+	 */
+
+	// Pre-format the placeholder if it exists so the default value is visual
+	const initialValue = placeholder ? formatMask(placeholder, mask) : undefined
+
+	const response = await prompts(
+		{
+			type: 'text',
+			name: 'value',
+			message,
+			initial: initialValue,
+			validate,
+			format: (val) => formatMask(val, mask),
+		},
+		{
+			onCancel: () => {
+				throw new CancelError()
+			},
+		}
+	)
+
+	// Ensure the returned value is always formatted
+	const formatted = formatMask(response.value, mask)
+
+	// Manual Stdout Override:
+	// prompts library might verify correctly but display raw input on the final line in some environments.
+	// We force a clean UI by removing the last line and printing our own.
+	if (process.stdout.isTTY) {
+		process.stdout.moveCursor(0, -1) // Move up one line
+		process.stdout.clearLine(0) // Clear the line
+		// Re-print the message and value manually with proper formatting
+		// Note: We use '✔' to match prompts style, or we can use our own if desired.
+		// prompts default style: '✔ Message … Value'
+		console.log(`✔ ${message} … ${formatted}`)
+	}
+
+	return { value: formatted, cancelled: false }
+}

package/src/ui/multiselect.js

@@ -0,0 +1,59 @@
+/**
+ * Multiselect module – provides interactive multiple-choice selection list.
+ *
+ * @module ui/multiselect
+ */
+
+import prompts from 'prompts'
+import { CancelError } from '@nan0web/ui/core'
+
+/**
+ * Interactive multiple selection with checkboxes.
+ *
+ * @param {Object} config
+ * @param {string} config.message - Prompt question
+ * @param {Array<string|Object>} config.options - List of choices
+ * @param {number} [config.limit=10] - Visible items limit
+ * @param {Array<any>} [config.initial=[]] - Initial selected values
+ * @param {string|boolean} [config.instructions] - Custom instructions
+ * @param {string} [config.hint] - Navigation hint
+ * @param {Function} [config.t] - Translation function
+ * @returns {Promise<{value: Array<any>, cancelled: boolean}>}
+ */
+export async function multiselect(config) {
+	const { message, options, limit = 10, initial = [], t } = config
+
+	if (!Array.isArray(options) || options.length === 0) {
+		throw new Error('Options array is required and must not be empty')
+	}
+
+	const choices = options.map((el) => {
+		if (typeof el === 'string') {
+			return { title: el, value: el, selected: initial.includes(el) }
+		}
+		return {
+			title: el.label || el.title,
+			value: el.value,
+			selected: initial.includes(el.value),
+		}
+	})
+
+	const response = await prompts(
+		{
+			type: 'multiselect',
+			name: 'value',
+			message,
+			choices,
+			limit,
+			instructions: config.instructions !== undefined ? config.instructions : false,
+			hint: config.hint || (t ? t('hint.multiselect') : undefined),
+		},
+		{
+			onCancel: () => {
+				throw new CancelError()
+			},
+		}
+	)
+
+	return { value: response.value || [], cancelled: false }
+}

package/src/ui/nav.js

@@ -0,0 +1,74 @@
+/**
+ * Navigation components – Breadcrumbs, Tabs, Steps.
+ *
+ * @module ui/nav
+ */
+
+import Logger from '@nan0web/log'
+
+/**
+ * Renders a breadcrumb trail.
+ *
+ * @param {string[]} items - List of path segments.
+ * @param {Object} [options]
+ * @param {string} [options.separator='›'] - Separator character.
+ * @returns {string} Styled string.
+ */
+export function breadcrumbs(items, options = {}) {
+	const { separator = '›' } = options
+	const sepStyle = Logger.style(` ${separator} `, { color: Logger.DIM })
+
+	return items
+		.map((item, index) => {
+			const isLast = index === items.length - 1
+			// Last item usually bold or white, previous dimmed
+			return Logger.style(item, { color: isLast ? Logger.WHITE : Logger.DIM })
+		})
+		.join(sepStyle)
+}
+
+/**
+ * Renders a tab bar (visual only).
+ *
+ * @param {string[]} items - List of tab labels.
+ * @param {number} [active=0] - Index of active tab.
+ * @returns {string} Styled string.
+ */
+export function tabs(items, active = 0) {
+	return items
+		.map((item, index) => {
+			const isActive = index === active
+			if (isActive) {
+				// Active: Inverse or highlighted
+				const bg = 'BLUE' // Logger looks up keys or constant values
+				return Logger.style(` ${item} `, { color: Logger.WHITE, bgColor: bg })
+			}
+			// Inactive: Dimmed or standard
+			return Logger.style(` ${item} `, { color: Logger.DIM })
+		})
+		.join(Logger.style('│', { color: Logger.DIM }))
+}
+
+/**
+ * Renders a step indicator (wizard).
+ *
+ * @param {string[]} items - List of step labels.
+ * @param {number} [current=0] - Index of current step.
+ * @returns {string} Styled string.
+ */
+export function steps(items, current = 0) {
+	return items
+		.map((item, index) => {
+			if (index < current) {
+				// Completed
+				return Logger.style(`✔ ${item}`, { color: Logger.GREEN })
+			} else if (index === current) {
+				// Current
+				return Logger.style(`● ${item}`, { color: Logger.CYAN })
+			} else {
+				// Future
+				return Logger.style(`○ ${item}`, { color: Logger.DIM })
+			}
+		})
+		.join(Logger.style(' ─ ', { color: Logger.DIM }))
+}

package/src/ui/next.js

@@ -4,7 +4,7 @@
  * @module ui/next
  */
 
-import process from "node:process"
+import process from 'node:process'
 
 /**
  * Pause execution for a given amount of milliseconds.
@@ -13,7 +13,7 @@ import process from "node:process"
  * @returns {Promise<true>} Resolves with `true` after the timeout.
  */
 export async function pause(ms) {
-	return new Promise(resolve => setTimeout(() => resolve(true), ms))
+	return new Promise((resolve) => setTimeout(() => resolve(true), ms))
 }
 
 /**
@@ -24,21 +24,26 @@ export async function pause(ms) {
  * @throws {Error} If stdin is already in raw mode.
  */
 export async function next(conf = undefined) {
+	// Automated environments support via PLAY_DEMO_SEQUENCE
+	if (process.env.PLAY_DEMO_SEQUENCE) {
+		return Promise.resolve('[SIMULATED KEY]')
+	}
+
 	return new Promise((resolve, reject) => {
 		if (process.stdin.isRaw) {
-			reject(new Error("stdin is already in raw mode"))
+			reject(new Error('stdin is already in raw mode'))
 			return
 		}
-		let buffer = ""
+		let buffer = ''
 
-		const onData = chunk => {
+		const onData = (chunk) => {
 			const str = chunk.toString()
 			buffer += str
 
 			if (conf === undefined) {
 				cleanup()
 				resolve(str)
-			} else if (typeof conf === "string") {
+			} else if (typeof conf === 'string') {
 				if (buffer === conf || buffer.endsWith(conf)) {
 					cleanup()
 					resolve(buffer)
@@ -54,21 +59,21 @@ export async function next(conf = undefined) {
 			}
 		}
 
-		const errorHandler = err => {
+		const errorHandler = (err) => {
 			cleanup()
 			reject(err)
 		}
 
 		const cleanup = () => {
-			process.stdin.off("data", onData)
-			process.stdin.off("error", errorHandler)
+			process.stdin.off('data', onData)
+			process.stdin.off('error', errorHandler)
 			process.stdin.setRawMode(false)
-			process.stdin.resume()
+			process.stdin.pause()
 		}
 
 		process.stdin.setRawMode(true)
 		process.stdin.resume()
-		process.stdin.once("error", errorHandler)
-		process.stdin.on("data", onData)
+		process.stdin.once('error', errorHandler)
+		process.stdin.on('data', onData)
 	})
-}
+}

package/src/ui/progress.js

@@ -0,0 +1,88 @@
+/**
+ * Progress module – visual progress bar with timers.
+ * @module ui/progress
+ */
+
+/**
+ * Renders a progress bar.
+ */
+export class ProgressBar {
+	/**
+	 * @param {Object} options
+	 * @param {number} options.total
+	 * @param {string} [options.title]
+	 * @param {number} [options.width=40]
+	 */
+	constructor(options) {
+		this.total = options.total
+		this.title = options.title
+		this.width = options.width || 40
+		this.current = 0
+		this.startTime = Date.now()
+	}
+
+	/**
+	 * Update progress.
+	 * @param {number} current
+	 */
+	update(current) {
+		this.current = current
+		this.render()
+	}
+
+	/**
+	 * Increment progress.
+	 * @param {number} [step=1]
+	 */
+	tick(step = 1) {
+		this.current += step
+		this.render()
+	}
+
+	render() {
+		const percent = Math.min(100, Math.max(0, (this.current / this.total) * 100))
+		const filledWidth = Math.round((this.width * percent) / 100)
+		const emptyWidth = this.width - filledWidth
+
+		const elapsed = (Date.now() - this.startTime) / 1000
+		const rate = this.current / elapsed
+		const remaining = rate > 0 ? (this.total - this.current) / rate : 0
+
+		const bar =
+			'='.repeat(filledWidth) +
+			(filledWidth < this.width ? '>' : '') +
+			'-'.repeat(Math.max(0, emptyWidth - 1))
+
+		const timeStr = `[${this.formatTime(elapsed)} < ${this.formatTime(remaining)}]`
+
+		const output = `\r${this.title ? this.title + ' ' : ''}[${bar}] ${percent.toFixed(0)}% ${timeStr}`
+		process.stdout.write(output)
+
+		if (this.current >= this.total) {
+			process.stdout.write('\n')
+		}
+	}
+
+	formatTime(seconds) {
+		if (!isFinite(seconds) || seconds < 0) return '--:--'
+		const h = Math.floor(seconds / 3600)
+		const m = Math.floor((seconds % 3600) / 60)
+		const s = Math.floor(seconds % 60)
+
+		const parts = []
+		if (h > 0) parts.push(h.toString().padStart(2, '0'))
+		parts.push(m.toString().padStart(2, '0'))
+		parts.push(s.toString().padStart(2, '0'))
+
+		return parts.join(':')
+	}
+}
+
+/**
+ * Functional helper for progress.
+ * @param {Object} options
+ * @returns {ProgressBar}
+ */
+export function progress(options) {
+	return new ProgressBar(options)
+}

package/src/ui/select.js

@@ -4,97 +4,74 @@
  * @module ui/select
  */
 
-import { CancelError } from "@nan0web/ui/core"
-import createInput from "./input.js"
-
-/** @typedef {import("./input.js").Input} Input */
-/** @typedef {import("./input.js").InputFn} InputFn */
-
-/**
- * @typedef {Object} ConsoleLike
- * @property {(...args: any[]) => void} debug
- * @property {(...args: any[]) => void} log
- * @property {(...args: any[]) => void} info
- * @property {(...args: any[]) => void} warn
- * @property {(...args: any[]) => void} error
- */
-
-/**
- * @typedef {Object} SelectConfig
- * @property {string} title – Title displayed above the options list.
- * @property {string} prompt – Prompt displayed for the answer.
- * @property {Array|Map} options – Collection of selectable items.
- * @property {ConsoleLike} console – Console‑like object with an `info` method.
- * @property {string[]} [stops=[]] Words that trigger cancellation.
- * @property {InputFn} [ask] Custom ask function (defaults to {@link createInput}).
- * @property {string} [invalidPrompt="Invalid choice, try again: "] Message shown on invalid input.
- */
+import prompts from 'prompts'
+import { CancelError } from '@nan0web/ui/core'
+import { validateString, validateFunction, validateNumber } from '../core/PropValidation.js'
 
 /**
  * Configuration object for {@link select}.
  *
- * @param {SelectConfig} input
- * @returns {Promise<{index:number,value:any}>} Resolves with the selected index and its value.
+ * @param {Object} input
+ * @param {string} input.title - Title displayed above the options list.
+ * @param {string} [input.prompt] - Prompt displayed for the answer.
+ * @param {Array|Map} input.options - Collection of selectable items.
+ * @param {Object} [input.console] - Deprecated. Ignored in new implementation.
+ * @param {string[]} [input.stops=[]] - Deprecated. Ignored in new implementation.
+ * @param {any} [input.ask] - Deprecated. Ignored in new implementation.
+ * @param {string} [input.invalidPrompt] - Deprecated. Ignored in new implementation.
+ * @param {number} [input.limit=10] - Max visible items.
+ * @param {string} [input.hint] - Hint text.
+ * @param {Function} [input.t] - Translation function.
+ * @returns {Promise<{index:number,value:any,cancelled:boolean}>} Resolves with the selected index and its value.
  *
  * @throws {CancelError} When the user cancels the operation.
- * @throws {Error} When options are missing or an incorrect value is supplied and no
- *   `invalidPrompt` is defined.
  */
 export async function select(input) {
-	const {
-		title,
-		prompt,
-		invalidPrompt = "Invalid choice, try again: ",
-		options: initOptins,
-		console,
-		stops = [],
-		ask: initAsk,
-	} = input
+	const { title, prompt, options: initOptins, limit = 30 } = input
+
+	// Prop Validation
+	validateString(title || prompt, 'title', 'Select', true)
+	validateNumber(limit, 'limit', 'Select')
+	validateFunction(input.t, 't', 'Select')
+	validateString(input.hint, 'hint', 'Select')
+
 	let options = initOptins
-	/** @type {InputFn} */
-	const ask = initAsk ?? createInput(stops)
 
 	// Normalise Map → Array of {label,value}
 	if (options instanceof Map) {
-		options = Array.from(options.entries()).map(
-			([value, label]) => ({ label, value }))
+		options = Array.from(options.entries()).map(([value, label]) => ({ label, value }))
 	}
 	if (!Array.isArray(options) || options.length === 0) {
-		throw new Error("Options array is required and must not be empty")
+		throw new Error('Options array is required and must not be empty')
 	}
-	const list = options.map(el =>
-		typeof el === "string" ? { label: el, value: el } : el,
-	)
-
-	console.info(title)
-	list.forEach(({ label }, i) => console.info(` ${i + 1}) ${label}`))
-
-	/**
-	 * Validation function passed to `ask` as the *loop* argument.
-	 * @type {import("./input.js").LoopFn}
-	 */
-	const validator = async (input) => {
-		if (input.cancelled) {
-			throw new CancelError()
+	// Prepare options for prompts
+	const choices = options.map((el) => {
+		if (typeof el === 'string') {
+			return { title: el, value: el }
 		}
-		const idx = Number(input.value) - 1
-		if (isNaN(idx) || idx < 0 || idx >= list.length) {
-			if (invalidPrompt) {
-				return true // repeat asking
-			}
-			throw new Error("Incorrect value provided")
+		return { title: el.label || el.title, value: el.value }
+	})
+
+	const response = await prompts(
+		{
+			type: 'select',
+			name: 'value',
+			message: title ? title : prompt,
+			choices: choices,
+			hint: input.hint || (input.t ? input.t('hint.select') : undefined),
+			instructions: false,
+			limit,
+		},
+		{
+			onCancel: () => {
+				throw new CancelError()
+			},
 		}
-		// valid selection – store index for later return
-		// we reuse `idx` after ask resolves
-		return false // stop looping
-	}
+	)
 
-	// Ask with validator loop; when validator returns false we have a valid answer.
-	const answer = await ask(prompt, validator, invalidPrompt)
+	const index = choices.findIndex((c) => c.value === response.value)
 
-	// After validator passes, compute the final index once more (safe)
-	const finalIdx = Number(answer.value) - 1
-	return { index: finalIdx, value: list[finalIdx].value }
+	return { index, value: response.value, cancelled: response.value === undefined }
 }
 
 /**