@nan0web/ui 1.0.4 → 1.3.0

package/src/View/View.js

@@ -1,10 +1,10 @@
-import { empty, equal, typeOf } from "@nan0web/types"
-import Frame, { FrameRenderMethod } from "../Frame/Frame.js"
-import Locale from "../Locale.js"
-import StdOut from "../StdOut.js"
-import StdIn from "../StdIn.js"
-import RenderOptions from "./RenderOptions.js"
-import UiMessage from "../core/Message/Message.js"
+import { empty, equal, typeOf } from '@nan0web/types'
+import Frame, { FrameRenderMethod } from '../Frame/Frame.js'
+import Locale from '../Locale.js'
+import StdOut from '../StdOut.js'
+import StdIn from '../StdIn.js'
+import RenderOptions from './RenderOptions.js'
+import UiMessage from '../core/Message/Message.js'
 
 /**
  * @typedef {Object} ComponentFn
@@ -54,7 +54,7 @@ export default class View {
 			stdout = new StdOut(),
 			startedAt = Date.now(),
 			frame = new Frame(),
-			locale = Locale.from("uk-UA"),
+			locale = Locale.from('uk-UA'),
 			vocab = new Map(),
 			windowSize = [0, 0],
 			components = new Map(),
@@ -103,14 +103,18 @@ export default class View {
 		const [width, height] = this.getWindowSize()
 		options = this.RenderOptions.from({
 			...options,
-			renderMethod: this.renderMethod, width, height,
+			renderMethod: this.renderMethod,
+			width,
+			height,
 			// @ts-ignore
 		})
-		const renderFn = "function" === typeof shouldRender // no errors.
-			// const renderFn = typeOf(Function)(shouldRender) // Property 'bind' does not exist on type 'number | boolean | Function'.
-			? shouldRender.bind(this) : "string" === typeof shouldRender
-				? this.components.get(shouldRender)?.bind(this)
-				: null
+		const renderFn =
+			'function' === typeof shouldRender // no errors.
+				? // const renderFn = typeOf(Function)(shouldRender) // Property 'bind' does not exist on type 'number | boolean | Function'.
+					shouldRender.bind(this)
+				: 'string' === typeof shouldRender
+					? this.components.get(shouldRender)?.bind(this)
+					: null
 
 		return (value, ...args) => {
 			if (renderFn) {
@@ -137,7 +141,7 @@ export default class View {
 			let frame = Frame.from({ ...options, value })
 			frame = View.fixFrame(frame, options)
 			let clearFrame = false
-			if (String(frame.value[0] ?? "") === Frame.BOF) {
+			if (String(frame.value[0] ?? '') === Frame.BOF) {
 				frame.value = frame.value.slice(1)
 				clearFrame = true
 			}
@@ -179,9 +183,9 @@ export default class View {
 
 	t(value) {
 		if (typeOf(Array)(value)) {
-			value = value.map(row => {
+			value = value.map((row) => {
 				if (typeOf(Array)(row)) {
-					return row.map(col => {
+					return row.map((col) => {
 						return this.vocab.has(col) ? this.vocab.get(col) : col
 					})
 				}
@@ -193,31 +197,32 @@ export default class View {
 	}
 
 	debug(...args) {
-		return this.render(1)(
-			[StdOut.STYLES.dim,
-				"Debug: ", args.join(" "), Frame.EOL, StdOut.RESET],
-		)
+		return this.render(1)([StdOut.STYLES.dim, 'Debug: ', args.join(' '), Frame.EOL, StdOut.RESET])
 	}
 
 	info(...args) {
-		return this.render(1)(
-			[StdOut.COLORS.green,
-				"Info : ", args.join(" "), Frame.EOL, StdOut.RESET],
-		)
+		return this.render(1)([StdOut.COLORS.green, 'Info : ', args.join(' '), Frame.EOL, StdOut.RESET])
 	}
 
 	warn(...args) {
-		return this.render(1)(
-			[StdOut.COLORS.yellow,
-				"Warn : ", args.join(" "), Frame.EOL, StdOut.RESET],
-		)
+		return this.render(1)([
+			StdOut.COLORS.yellow,
+			'Warn : ',
+			args.join(' '),
+			Frame.EOL,
+			StdOut.RESET,
+		])
 	}
 
 	error(...args) {
-		return this.render(1)(
-			[StdOut.COLORS.red, StdOut.STYLES.bold,
-				"Error: ", args.join(" "), Frame.EOL, StdOut.RESET],
-		)
+		return this.render(1)([
+			StdOut.COLORS.red,
+			StdOut.STYLES.bold,
+			'Error: ',
+			args.join(' '),
+			Frame.EOL,
+			StdOut.RESET,
+		])
 	}
 
 	/**
@@ -225,7 +230,7 @@ export default class View {
 	 * @param {ComponentFn} component
 	 */
 	register(name, component) {
-		if (undefined === component && "function" === typeof name) {
+		if (undefined === component && 'function' === typeof name) {
 			component = name
 			name = component.name
 		}
@@ -260,7 +265,7 @@ export default class View {
 	 * @returns {Promise<UiMessage | null>}
 	 */
 	async ask(input) {
-		const name = input.constructor.name.replace(/Input$/, "")
+		const name = input.constructor.name.replace(/Input$/, '')
 		const component = this.get(name)
 		if (component) {
 			return await component.ask.apply(this, [input])
@@ -269,8 +274,8 @@ export default class View {
 		do {
 			const answer = await this.stdin.read()
 			result = /** @type {typeof UiMessage} */ (input.constructor).from(answer)
-		} while (!result.isValid && !result.escaped)
-		return result.escaped ? null : result
+		} while (!result.isValid && !result.head.cancelled)
+		return result.head.cancelled ? null : result
 	}
 
 	/**
@@ -285,5 +290,4 @@ export default class View {
 		// @todo add multiline visibility, for instance extended frame row into rows if it's wider than width.
 		return frame
 	}
-
 }

package/src/core/Error/CancelError.js

@@ -1,6 +1,6 @@
 export default class CancelError extends Error {
-	constructor(message = "Operation cancelled by user") {
+	constructor(message = 'Operation cancelled by user') {
 		super(message)
-		this.name = "CancelError"
+		this.name = 'CancelError'
 	}
 }

package/src/core/Error/index.js

@@ -1,9 +1,7 @@
-import CancelError from "./CancelError.js"
+import CancelError from './CancelError.js'
 
-export {
-	CancelError
-}
+export { CancelError }
 
 export default {
-	CancelError
+	CancelError,
 }

package/src/core/Flow.js

@@ -0,0 +1,347 @@
+/**
+ * @fileoverview Universal Flow Runner for yield-based UI architecture.
+ *
+ * The Flow pattern enables "One Logic, Many UI" by separating business logic
+ * from presentation. A Flow is an async generator that yields Components,
+ * which are then rendered by platform-specific Adapters.
+ *
+ * @module @nan0web/ui/core/Flow
+ */
+
+import CancelError from './Error/CancelError.js'
+
+// ═══════════════════════════════════════════════════════════════════════════
+// TYPES (JSDoc for pure JavaScript, TypeScript-compatible)
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Component types that can be yielded from a Flow.
+ *
+ * @typedef {'view' | 'prompt' | 'stream' | 'action' | 'flow'} ComponentType
+ */
+
+/**
+ * Base interface for all UI components.
+ *
+ * @typedef {Object} FlowComponent
+ * @property {ComponentType} type - Component type discriminator.
+ * @property {string} [name] - Optional component name for debugging.
+ */
+
+/**
+ * Static view component (no user input required).
+ * Examples: Alert, Badge, Toast, Table, Text
+ *
+ * @typedef {Object} ViewComponent
+ * @property {'view'} type - Always 'view'.
+ * @property {string} name - Component name (e.g., 'Alert', 'Toast').
+ * @property {Object} props - Component-specific properties.
+ */
+
+/**
+ * Interactive prompt component (requires user input).
+ * Examples: Input, Select, Confirm, Multiselect, Mask
+ *
+ * @typedef {Object} PromptComponent
+ * @property {'prompt'} type - Always 'prompt'.
+ * @property {string} name - Component name (e.g., 'Select', 'Input').
+ * @property {Object} props - Component-specific properties.
+ * @property {string} [props.message] - Prompt message to display.
+ * @property {any[]} [props.choices] - Options for Select/Multiselect.
+ * @property {Function} [props.validate] - Validation function.
+ */
+
+/**
+ * Streaming component for progress/async operations.
+ * Examples: Spinner, ProgressBar, StreamChunk
+ *
+ * @typedef {Object} StreamComponent
+ * @property {'stream'} type - Always 'stream'.
+ * @property {string} name - Component name (e.g., 'Spinner', 'Progress').
+ * @property {Object} props - Component-specific properties.
+ * @property {AsyncIterable} [iterable] - Async iterator for streaming content.
+ */
+
+/**
+ * Action component for physical or side-effect operations.
+ * Examples: Move, Sound, Light, Notify
+ *
+ * @typedef {Object} ActionComponent
+ * @property {'action'} type - Always 'action'.
+ * @property {string} name - Component name (e.g., 'Move', 'Beep').
+ * @property {Object} props - Component-specific properties.
+ */
+
+/**
+ * Result returned by prompt components.
+ *
+ * @typedef {Object} PromptResult
+ * @property {any} value - The value entered/selected by user.
+ * @property {boolean} [cancelled] - True if user cancelled the prompt.
+ */
+
+/**
+ * Adapter interface that all platform adapters must implement.
+ *
+ * @typedef {Object} FlowAdapter
+ * @property {(component: ViewComponent) => void | Promise<void>} renderView
+ *   Renders a static view component.
+ * @property {(component: PromptComponent) => Promise<PromptResult>} executePrompt
+ *   Execute an interactive prompt and returns user input.
+ * @property {(component: StreamComponent) => AsyncIterable} streamProgress
+ *   Handles streaming components.
+ * @property {(component: ActionComponent) => Promise<any>} [executeAction]
+ *   Executes an action component (physical or side-effect).
+ */
+
+// ═══════════════════════════════════════════════════════════════════════════
+// COMPONENT FACTORIES
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Creates a View component.
+ *
+ * @param {string} name - Component name (e.g., 'Alert', 'Toast').
+ * @param {Object} props - Component properties.
+ * @returns {ViewComponent}
+ *
+ * @example
+ * yield View('Alert', { variant: 'success', message: 'Done!' })
+ */
+export function View(name, props = {}) {
+	return { type: 'view', name, props }
+}
+
+/**
+ * Creates a Prompt component.
+ *
+ * @param {string} name - Component name (e.g., 'Select', 'Input').
+ * @param {Object} props - Component properties.
+ * @returns {PromptComponent}
+ *
+ * @example
+ * const value = yield Prompt('Select', { message: 'Choose:', choices: ['a', 'b'] })
+ */
+export function Prompt(name, props = {}) {
+	return { type: 'prompt', name, props }
+}
+
+/**
+ * Creates a Stream component.
+ *
+ * @param {string} name - Component name (e.g., 'Spinner', 'Progress').
+ * @param {Object} props - Component properties.
+ * @returns {StreamComponent}
+ *
+ * @example
+ * yield* Stream('Progress', { total: 100, current: 50 })
+ */
+export function Stream(name, props = {}) {
+	return { type: 'stream', name, props }
+}
+
+/**
+ * Creates an Action component.
+ *
+ * @param {string} name - Action name.
+ * @param {Object} props - Action properties.
+ * @returns {ActionComponent}
+ */
+export function Action(name, props = {}) {
+	return { type: 'action', name, props }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// CONVENIENCE FACTORIES (Pre-defined components)
+// ═══════════════════════════════════════════════════════════════════════════
+
+/** @param {Object} props */
+export const Alert = (props) => View('Alert', props)
+
+/** @param {Object} props */
+export const Toast = (props) => View('Toast', props)
+
+/** @param {Object} props */
+export const Badge = (props) => View('Badge', props)
+
+/** @param {Object} props */
+export const Text = (props) => View('Text', props)
+
+/** @param {Object} props */
+export const Table = (props) => View('Table', props)
+
+/** @param {Object} props */
+export const Input = (props) => Prompt('Input', props)
+
+/** @param {Object} props */
+export const Select = (props) => Prompt('Select', props)
+
+/** @param {Object} props */
+export const Confirm = (props) => Prompt('Confirm', props)
+
+/** @param {Object} props */
+export const Multiselect = (props) => Prompt('Multiselect', props)
+
+/** @param {Object} props */
+export const Mask = (props) => Prompt('Mask', props)
+
+/** @param {Object} props */
+export const Password = (props) => Prompt('Password', props)
+
+/** @param {Object} props */
+export const Spinner = (props) => Stream('Spinner', props)
+
+/** @param {Object} props */
+export const Progress = (props) => Stream('Progress', props)
+
+/** @param {Object} props */
+export const Beep = (props) => Action('Beep', props)
+
+/** @param {Object} props */
+export const Move = (props) => Action('Move', props)
+
+// ═══════════════════════════════════════════════════════════════════════════
+// FLOW RUNNER
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Runs a Flow (async generator) with the provided adapter.
+ *
+ * The Flow runner iterates through yielded components and dispatches them
+ * to the appropriate adapter method based on component type.
+ *
+ * @param {AsyncGenerator} flow - The flow generator to execute.
+ * @param {FlowAdapter} adapter - The platform-specific adapter.
+ * @param {Object} [options={}] - Additional options.
+ * @param {AbortSignal} [options.signal] - Abort signal for cancellation.
+ * @returns {Promise<any>} The final return value of the flow.
+ *
+ * @example
+ * async function* loginFlow() {
+ *     yield Alert({ message: 'Welcome!' })
+ *     const username = yield Input({ message: 'Username:' })
+ *     const password = yield Password({ message: 'Password:' })
+ *     return { username, password }
+ * }
+ *
+ * const result = await runFlow(loginFlow(), cliAdapter)
+ */
+export async function runFlow(flow, adapter, options = {}) {
+	const { signal } = options
+	let nextValue = undefined
+
+	while (true) {
+		// Check for abort
+		if (signal?.aborted) {
+			throw new CancelError('Flow aborted')
+		}
+
+		// Get next component from flow
+		const { value: component, done } = await flow.next(nextValue)
+
+		if (done) {
+			return component // Final return value
+		}
+
+		// Handle null/undefined yields
+		if (!component) {
+			nextValue = undefined
+			continue
+		}
+
+		// Dispatch based on component type
+		switch (component.type) {
+			case 'view':
+				await adapter.renderView?.(component)
+				nextValue = undefined
+				break
+
+			case 'prompt': {
+				const result = await adapter.executePrompt?.(component)
+				if (result?.cancelled) {
+					throw new CancelError('User cancelled prompt')
+				}
+				nextValue = result?.value
+				break
+			}
+
+			case 'stream':
+				// For streams, we iterate and yield each chunk
+				if (adapter.streamProgress) {
+					for await (const chunk of adapter.streamProgress(component)) {
+						// Optionally allow flow to react to stream chunks
+						// by using a specific protocol if needed
+					}
+				}
+				nextValue = undefined
+				break
+
+			case 'action':
+				nextValue = await adapter.executeAction?.(component)
+				break
+
+			case 'flow':
+				// Nested flow - recursive execution
+				nextValue = await runFlow(component.generator, adapter, options)
+				break
+
+			default:
+				// Unknown component type - try to render as view
+				if (typeof component === 'string') {
+					await adapter.renderView?.({ type: 'view', name: 'Text', props: { content: component } })
+				} else if (typeof component.toString === 'function') {
+					await adapter.renderView?.({
+						type: 'view',
+						name: 'Text',
+						props: { content: String(component) },
+					})
+				}
+				nextValue = undefined
+		}
+	}
+}
+
+/**
+ * Wraps a nested flow for composition with yield*.
+ *
+ * @param {Function} flowFn - Flow generator function.
+ * @param {...any} args - Arguments to pass to the flow function.
+ * @returns {Object} A flow component.
+ *
+ * @example
+ * async function* mainFlow() {
+ *     yield Alert({ message: 'Starting...' })
+ *     const user = yield* flow(loginFlow)
+ *     yield Alert({ message: `Welcome, ${user.name}!` })
+ * }
+ */
+export function flow(flowFn, ...args) {
+	return { type: 'flow', generator: flowFn(...args) }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// EXPORTS
+// ═══════════════════════════════════════════════════════════════════════════
+
+export default {
+	runFlow,
+	flow,
+	// Factories
+	View,
+	Prompt,
+	Stream,
+	// Components
+	Alert,
+	Toast,
+	Badge,
+	Text,
+	Table,
+	Input,
+	Select,
+	Confirm,
+	Multiselect,
+	Mask,
+	Password,
+	Spinner,
+	Progress,
+}

package/src/core/Form/Form.js

@@ -1,6 +1,6 @@
-import Message from "@nan0web/co"
-import FormMessage from "./Message.js"
-import FormInput from "./Input.js"
+import Message from '@nan0web/co'
+import FormMessage from './Message.js'
+import FormInput from './Input.js'
 
 /**
  * Abstract form for data entry.
@@ -33,8 +33,8 @@ export default class UIForm extends FormMessage {
 	 *   otherwise returns an error message.
 	 */
 	static addValidation(name, fn) {
-		if (typeof name !== "string" || typeof fn !== "function") {
-			throw new Error("validation name must be a string and fn must be a function")
+		if (typeof name !== 'string' || typeof fn !== 'function') {
+			throw new Error('validation name must be a string and fn must be a function')
 		}
 		UIForm._validations[name] = fn
 	}
@@ -51,16 +51,10 @@ export default class UIForm extends FormMessage {
 	constructor(props = {}) {
 		super(props)
 
-		const {
-			title = '',
-			fields = [],
-			state = {},
-			schema = {},
-			...rest
-		} = props
+		const { title = '', fields = [], state = {}, schema = {}, ...rest } = props
 
 		// Normalise fields
-		this.fields = fields.map(f => FormInput.from(f))
+		this.fields = fields.map((f) => FormInput.from(f))
 		this.title = title
 		this.state = { ...state }
 		this.schema = schema
@@ -68,8 +62,8 @@ export default class UIForm extends FormMessage {
 		// Update meta with form data
 		this.meta = {
 			title: this.title,
-			fields: this.fields.map(f => f.toJSON ? f.toJSON() : f),
-			initialState: this.state
+			fields: this.fields.map((f) => (f.toJSON ? f.toJSON() : f)),
+			initialState: this.state,
 		}
 	}
 
@@ -86,7 +80,7 @@ export default class UIForm extends FormMessage {
 	setData(data) {
 		return new UIForm({
 			...this,
-			state: { ...this.state, ...data }
+			state: { ...this.state, ...data },
 		})
 	}
 
@@ -97,7 +91,7 @@ export default class UIForm extends FormMessage {
 	 * @returns {FormInput|undefined}
 	 */
 	getField(name) {
-		return this.fields.find(f => f.name === name)
+		return this.fields.find((f) => f.name === name)
 	}
 
 	/**
@@ -122,14 +116,20 @@ export default class UIForm extends FormMessage {
 			const fieldValue = this.state[field.name]
 
 			// Required validation based on field definition or schema
-			if (field.required && (fieldValue === '' || fieldValue === null || fieldValue === undefined)) {
+			if (
+				field.required &&
+				(fieldValue === '' || fieldValue === null || fieldValue === undefined)
+			) {
 				errors.set(field.name, 'This field is required')
 				isValid = false
 				return
 			}
 
 			// Validation via schema (if provided) or field type
-			const { isValid: fieldValid, errors: fieldErrors } = this.validateField(field.name, fieldValue)
+			const { isValid: fieldValid, errors: fieldErrors } = this.validateField(
+				field.name,
+				fieldValue,
+			)
 
 			if (!fieldValid) {
 				for (const [key, err] of Object.entries(fieldErrors)) {
@@ -241,9 +241,9 @@ export default class UIForm extends FormMessage {
 		return {
 			time: new Date(this.time).toISOString(),
 			title: this.title,
-			fields: this.fields.map(f => f.toJSON ? f.toJSON() : f),
+			fields: this.fields.map((f) => (f.toJSON ? f.toJSON() : f)),
 			state: this.state,
-			meta: this.meta
+			meta: this.meta,
 		}
 	}
 
@@ -257,19 +257,21 @@ export default class UIForm extends FormMessage {
 			const Class = input.constructor
 			const fields = []
 			for (const [name, value] of Object.entries(input)) {
-				fields.push(new FormInput({
-					name,
-					label: Class[name]?.label ?? Class[`${name}Label`] ?? name,
-					type: Class[name]?.type ?? Class[`${name}Type`] ?? typeof value,
-					required: Class[name]?.required ?? Class[`${name}Required`] ?? false,
-					placeholder: Class[name]?.placeholder ?? Class[`${name}Placeholder`] ?? "",
-					defaultValue: Class[name]?.defaultValue ?? Class[`${name}Default`] ?? "",
-					validation: Class[name]?.validation ?? Class[`${name}Validation`] ?? (() => true),
-				}))
+				fields.push(
+					new FormInput({
+						name,
+						label: Class[name]?.label ?? Class[`${name}Label`] ?? name,
+						type: Class[name]?.type ?? Class[`${name}Type`] ?? typeof value,
+						required: Class[name]?.required ?? Class[`${name}Required`] ?? false,
+						placeholder: Class[name]?.placeholder ?? Class[`${name}Placeholder`] ?? '',
+						defaultValue: Class[name]?.defaultValue ?? Class[`${name}Default`] ?? '',
+						validation: Class[name]?.validation ?? Class[`${name}Validation`] ?? (() => true),
+					}),
+				)
 			}
 			return new UIForm({
 				title: Class.name,
-				fields
+				fields,
 			})
 		}
 		return new UIForm(input)
@@ -298,10 +300,10 @@ export default class UIForm extends FormMessage {
 				label,
 				type: custom.type ?? FormInput.TYPES.TEXT,
 				required: !!custom.required,
-				placeholder: custom.placeholder ?? "",
+				placeholder: custom.placeholder ?? '',
 				options: custom.options ?? [],
 				validation: custom.validation ?? undefined,
-				defaultValue: custom.defaultValue ?? "",
+				defaultValue: custom.defaultValue ?? '',
 			})
 		})
 		return new UIForm({ fields })