@nan0web/ui 1.0.4 → 1.3.0

package/src/core/Form/Input.js

@@ -16,8 +16,9 @@
  * @property {string} type - Input type (text, email, number, select, etc.).
  * @property {boolean} required - Whether the field is required.
  * @property {string} placeholder - Placeholder text.
- * @property {Array<string>} options - Select options (if type is 'select').
- * @property {Function|null} validation - Custom validation function.
+ * @property {InputOptions} options - Select options (if type is 'select').
+ * @property {Function} validation - Custom validation function.
+ * @property {string} mask - Mask pattern (e.g. '###-###').
  * @property {*} defaultValue - Default value.
  */
 export default class FormInput {
@@ -27,7 +28,8 @@ export default class FormInput {
 	/** @type {boolean} */ required = false
 	/** @type {string} */ placeholder = ''
 	/** @type {InputOptions} */ options = []
-	/** @type {import("@nan0web/co").ValidateFn|null} */ validation = null
+	/** @type {Function} */ validation = () => true
+	/** @type {string} */ mask = ''
 	/** @type {*} */ defaultValue = null
 
 	/**
@@ -39,7 +41,14 @@ export default class FormInput {
 		NUMBER: 'number',
 		SELECT: 'select',
 		CHECKBOX: 'checkbox',
-		TEXTAREA: 'textarea'
+		TEXTAREA: 'textarea',
+		PASSWORD: 'password',
+		SECRET: 'secret',
+		MASK: 'mask',
+		CONFIRM: 'confirm',
+		TOGGLE: 'toggle',
+		MULTISELECT: 'multiselect',
+		AUTOCOMPLETE: 'autocomplete',
 	}
 
 	/**
@@ -52,7 +61,8 @@ export default class FormInput {
 	 * @param {boolean} [props.required=false] - Is required.
 	 * @param {string} [props.placeholder=''] - Placeholder.
 	 * @param {InputOptions} [props.options=[]] - Select options or async function to retrieve data with the search and page.
-	 * @param {Function} [props.validation=null] - Custom validation.
+	 * @param {Function} [props.validation] - Custom validation.
+	 * @param {string} [props.mask=''] - Mask pattern.
 	 * @param {*} [props.defaultValue=null] - Default value.
 	 */
 	constructor(props) {
@@ -64,7 +74,8 @@ export default class FormInput {
 			placeholder = this.placeholder,
 			options = [],
 			validation = this.validation,
-			defaultValue = this.defaultValue
+			mask = '',
+			defaultValue = this.defaultValue,
 		} = props
 
 		if (!name) {
@@ -78,6 +89,7 @@ export default class FormInput {
 		this.placeholder = String(placeholder)
 		this.options = options
 		this.validation = validation
+		this.mask = String(mask)
 		this.defaultValue = defaultValue
 
 		this.requireValidType()
@@ -85,12 +97,14 @@ export default class FormInput {
 
 	requireValidType() {
 		if (!Object.values(FormInput.TYPES).includes(this.type)) {
-			throw new TypeError([
-				"FormInput.type is invalid!",
-				["Provided", this.type].join(": "),
-				"Available types:",
-				...Object.values(FormInput.TYPES).map(t => `  - ${t}`)
-			].join("\n"))
+			throw new TypeError(
+				[
+					'FormInput.type is invalid!',
+					['Provided', this.type].join(': '),
+					'Available types:',
+					...Object.values(FormInput.TYPES).map((t) => `  - ${t}`),
+				].join('\n'),
+			)
 		}
 	}
 
@@ -107,7 +121,8 @@ export default class FormInput {
 			required: this.required,
 			placeholder: this.placeholder,
 			options: this.options,
-			defaultValue: this.defaultValue
+			mask: this.mask,
+			defaultValue: this.defaultValue,
 		}
 	}
 
@@ -117,7 +132,7 @@ export default class FormInput {
 	 */
 	static from(input) {
 		if (input instanceof FormInput) return input
-		if ("string" === typeof input) {
+		if (typeof input === 'string') {
 			return new FormInput({ name: input, label: input })
 		}
 		return new FormInput(input)

package/src/core/Form/Message.js

@@ -1,4 +1,4 @@
-import UiMessage from "../Message/Message.js"
+import UiMessage from '../Message/Message.js'
 
 /**
  * FormMessage – specialized UiMessage for forms.
@@ -15,10 +15,7 @@ export default class FormMessage extends UiMessage {
 	 */
 	constructor(input = {}) {
 		super(input)
-		const {
-			data = {},
-			schema = {},
-		} = input
+		const { data = {}, schema = {} } = input
 
 		// Store data and schema for easy access
 		this.data = data
@@ -81,4 +78,4 @@ export default class FormMessage extends UiMessage {
 
 		return { isValid: Object.keys(errors).length === 0, errors }
 	}
-}
+}

package/src/core/Form/index.js

@@ -1,11 +1,7 @@
-import FormInput from "./Input.js"
-import FormMessage from "./Message.js"
-import Form from "./Form.js"
+import FormInput from './Input.js'
+import FormMessage from './Message.js'
+import Form from './Form.js'
 
-export {
-	FormInput,
-	FormMessage,
-	Form,
-}
+export { FormInput, FormMessage, Form }
 
 export default Form

package/src/core/InputAdapter.js

@@ -1,6 +1,6 @@
-import Event from "@nan0web/event/oop"
-import CancelError from "./Error/CancelError.js"
-import UiMessage from "./Message/Message.js"
+import Event from '@nan0web/event/oop'
+import CancelError from './Error/CancelError.js'
+import UiMessage from './Message/Message.js'
 
 /**
  * Abstract input adapter for UI implementations.
@@ -20,9 +20,7 @@ export default class InputAdapter extends Event {
 	 * @returns {void}
 	 */
 	start() {
-		this.emit('input',
-			UiMessage.from({ body: "Adapter started" })
-		)
+		this.emit('input', UiMessage.from({ body: 'Adapter started' }))
 	}
 
 	/**

package/src/core/Message/Message.js

@@ -1,4 +1,4 @@
-import { Message } from "@nan0web/co"
+import { Message } from '@nan0web/co'
 
 /**
  * @typedef {Object} MessageBodySchema
@@ -40,13 +40,13 @@ export default class UiMessage extends Message {
 		SUCCESS: 'success',
 		WARNING: 'warning',
 		COMMAND: 'command',
-		NAVIGATION: 'navigation'
+		NAVIGATION: 'navigation',
 	}
 
 	/** @type {string} */
-	type = ""
+	type = ''
 	/** @type {string} */
-	id = ""
+	id = ''
 
 	/**
 	 * Creates a UiMessage.
@@ -56,10 +56,7 @@ export default class UiMessage extends Message {
 	constructor(input = {}) {
 		super(input)
 
-		const {
-			type = this.type,
-			id = this.id,
-		} = input
+		const { type = this.type, id = this.id } = input
 		this.id = id || `ui-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`
 		this.type = String(type)
 
@@ -96,7 +93,7 @@ export default class UiMessage extends Message {
 		for (const [field, schema] of entries) {
 			const value = body[field]
 			const fn = schema?.validate
-			if ("function" === typeof fn) {
+			if ('function' === typeof fn) {
 				const ok = fn.apply(body, [value])
 				if (ok !== true) {
 					result.set(field, String(ok))
@@ -105,7 +102,7 @@ export default class UiMessage extends Message {
 			}
 			const required = schema?.required ?? false
 			if (required && !value) {
-				result.set(field, "Required")
+				result.set(field, 'Required')
 				continue
 			}
 			if (schema?.pattern && schema.pattern instanceof RegExp) {
@@ -116,10 +113,10 @@ export default class UiMessage extends Message {
 			}
 			if (schema?.options) {
 				if (!Array.isArray(schema.options)) {
-					throw new Error("Schema options must be an array of possible values")
+					throw new Error('Schema options must be an array of possible values')
 				}
 				if (!schema.options.includes(value)) {
-					result.set(field, "Enumeration must have one value")
+					result.set(field, 'Enumeration must have one value')
 					continue
 				}
 			}

package/src/core/Message/OutputMessage.js

@@ -1,4 +1,4 @@
-import UiMessage from "./Message.js"
+import UiMessage from './Message.js'
 
 /**
  * OutputMessage – message sent from the system to the UI.
@@ -11,7 +11,7 @@ export default class OutputMessage extends UiMessage {
 		LOW: 0,
 		NORMAL: 1,
 		HIGH: 2,
-		CRITICAL: 3
+		CRITICAL: 3,
 	}
 
 	/** @type {string[]} */
@@ -36,19 +36,19 @@ export default class OutputMessage extends UiMessage {
 			body = [],
 			meta = {},
 			error = null,
-			priority = OutputMessage.PRIORITY.NORMAL
+			priority = OutputMessage.PRIORITY.NORMAL,
 		} = input
 
-		const contentSource = 'body' in input ? body :
-			'content' in input ? content : []
+		const contentSource = 'body' in input ? body : 'content' in input ? content : []
 
-		this.body = Array.isArray(contentSource) ?
-			contentSource :
-			(contentSource ? [String(contentSource)] : [])
+		this.body = Array.isArray(contentSource)
+			? contentSource
+			: contentSource
+				? [String(contentSource)]
+				: []
 
 		this.meta = meta
-		this.error = error instanceof Error ? error :
-			error ? new Error(String(error)) : null
+		this.error = error instanceof Error ? error : error ? new Error(String(error)) : null
 		this.priority = Number(priority)
 
 		if (!this.type && this.error) {
@@ -91,7 +91,7 @@ export default class OutputMessage extends UiMessage {
 		let combinedError = this.error
 		let combinedPriority = this.priority
 
-		messages.forEach(msg => {
+		messages.forEach((msg) => {
 			if (msg instanceof OutputMessage) {
 				combinedContent.push(...msg.content)
 				combinedMeta = { ...combinedMeta, ...msg.meta }
@@ -105,7 +105,7 @@ export default class OutputMessage extends UiMessage {
 			meta: combinedMeta,
 			error: combinedError,
 			priority: combinedPriority,
-			type: this.type
+			type: this.type,
 		})
 	}
 
@@ -122,11 +122,13 @@ export default class OutputMessage extends UiMessage {
 			type: this.type,
 			id: this.id,
 			time: this.time.toISOString(),
-			error: this.error ? {
-				message: this.error.message,
-				stack: this.error.stack
-			} : null,
-			priority: this.priority
+			error: this.error
+				? {
+						message: this.error.message,
+						stack: this.error.stack,
+					}
+				: null,
+			priority: this.priority,
 		}
 	}
 

package/src/core/Message/index.js

@@ -1,5 +1,5 @@
-import UiMessage from "./Message.js"
-import OutputMessage from "./OutputMessage.js"
+import UiMessage from './Message.js'
+import OutputMessage from './OutputMessage.js'
 
 export { UiMessage, OutputMessage }
 

package/src/core/OutputAdapter.js

@@ -16,7 +16,7 @@ class OutputAdapter extends Event {
 	 * @throws {Error} If not overridden by a subclass.
 	 */
 	render(message) {
-		throw new Error("render() must be implemented by subclass")
+		throw new Error('render() must be implemented by subclass')
 	}
 
 	/**
@@ -27,14 +27,16 @@ class OutputAdapter extends Event {
 	 * @returns {void}
 	 */
 	progress(progress, metadata = {}) {
-		this.render(OutputMessage.from({
-			content: [],
-			metadata: {
-				...metadata,
-				progress,
-				elementType: "progress"
-			}
-		}))
+		this.render(
+			OutputMessage.from({
+				content: [],
+				metadata: {
+					...metadata,
+					progress,
+					elementType: 'progress',
+				},
+			}),
+		)
 	}
 
 	/**
@@ -47,4 +49,4 @@ class OutputAdapter extends Event {
 	}
 }
 
-export default OutputAdapter
+export default OutputAdapter

package/src/core/Stream.js

@@ -1,6 +1,4 @@
-import StreamEntry from "./StreamEntry.js"
-
-export { StreamEntry } // Export if needed
+import StreamEntry from './StreamEntry.js'
 
 /**
  * Agnostic UI stream for processing progress using async generators.
@@ -18,6 +16,9 @@ export default class UIStream {
 	static createProcessor(signal, processorFn) {
 		return async function* () {
 			try {
+				if (signal.aborted) {
+					throw new DOMException('Aborted', 'AbortError')
+				}
 				const result = await processorFn()
 				yield result
 			} catch (/** @type {any} */ error) {

package/src/core/StreamEntry.js

@@ -24,7 +24,7 @@ export default class StreamEntry {
 	 * Error message associated with the stream entry.
 	 * @type {string}
 	 */
-	error = ""
+	error = ''
 
 	/**
 	 * Creates a new StreamEntry instance.
@@ -56,4 +56,4 @@ export default class StreamEntry {
 		if (input instanceof StreamEntry) return input
 		return new StreamEntry(input)
 	}
-}
+}

package/src/core/UiAdapter.js

@@ -1,8 +1,10 @@
-import EventProcessor from "@nan0web/event/oop"
-import CancelError from "./Error/CancelError.js"
-import UIMessage from "./Message/Message.js"
-import UIForm from "./Form/Form.js"
-import FormInput from "./Form/Input.js"
+import EventProcessor from '@nan0web/event/oop'
+import CancelError from './Error/CancelError.js'
+import UIMessage from './Message/Message.js'
+import UIForm from './Form/Form.js'
+import FormInput from './Form/Input.js'
+import OutputAdapter from './OutputAdapter.js'
+import OutputMessage from './Message/OutputMessage.js'
 
 /**
  * Unified UI Adapter that handles both input and output operations.
@@ -34,7 +36,7 @@ export default class UiAdapter extends EventProcessor {
 	 * @returns {void}
 	 */
 	start() {
-		this.emit('input', UIMessage.from({ body: "Adapter started" }))
+		this.emit('input', UIMessage.from({ body: 'Adapter started' }))
 	}
 
 	/**
@@ -81,6 +83,30 @@ export default class UiAdapter extends EventProcessor {
 		throw new Error('select() method must be implemented in subclass')
 	}
 
+	/**
+	 * Process a UIForm and return its result.
+	 *
+	 * This default implementation follows an **agnostic UI** approach:
+	 * it simply returns the form instance (with optional initial state merged)
+	 * without UI interaction. Concrete adapters (CLI, Web, etc.) can override
+	 * this method to render the form, collect user input and return a richer
+	 * result object (`{ form, cancelled }`).
+	 *
+	 * @param {UIForm} form - The UIForm instance to process.
+	 * @param {object} [initialState={}] - Pre‑filled values for the form.
+	 * @returns {Promise<{ form: UIForm, cancelled?: boolean }>} Form processing result.
+	 */
+	async processForm(form, initialState = {}) {
+		// Merge any provided initial state into the form's internal state.
+		if (initialState && typeof initialState === 'object') {
+			form.state = { ...form.state, ...initialState }
+		}
+		// In the agnostic baseline we do not perform any interactive I/O.
+		// Sub‑classes may provide a UI (render, ask, etc.) and return
+		// `{ form, cancelled: true/false, ... }`.
+		return { form }
+	}
+
 	/**
 	 * Ensures a message's body is fully and validly filled.
 	 * Generates a form from the message's static Body schema,
@@ -96,22 +122,21 @@ export default class UiAdapter extends EventProcessor {
 	 */
 	async requireInput(msg) {
 		if (!msg) {
-			throw new Error("Message instance is required")
+			throw new Error('Message instance is required')
 		}
 		if (!(msg instanceof UIMessage)) {
-			throw new TypeError("Message must be an instance of UIMessage")
+			throw new TypeError('Message must be an instance of UIMessage')
 		}
 		/** @type {Map<string,string>} */
 		let errors = msg.validate()
 		while (errors.size > 0) {
-			const form = generateForm(
-				/** @type {any} */ (msg.constructor).Body,
-				{ initialState: msg.body }
-			)
-
-			const formResult = await this.processForm ? this.processForm(form, msg.body) : {} // Assume method exists or handle differently, but error indicates missing method; perhaps remove if not used
-			if (formResult.escaped) {
-				throw new CancelError("User cancelled form")
+			const form = generateForm(/** @type {any} */ (msg.constructor).Body, {
+				initialState: msg.body,
+			})
+
+			const formResult = (await this.processForm) ? this.processForm(form, msg.body) : {} // Assume method exists or handle differently, but error indicates missing method; perhaps remove if not used
+			if (formResult.cancelled) {
+				throw new CancelError('User cancelled form')
 			}
 
 			const updatedBody = { ...msg.body, ...formResult.form.state }
@@ -119,10 +144,13 @@ export default class UiAdapter extends EventProcessor {
 
 			if (updatedErrors.size > 0) {
 				if (this.output) {
-					await this.output.render("Alert", {
-						variant: "error",
-						content: Array.from(updatedErrors.values()).join("\n")
-					})
+					this.output.render(
+						new OutputMessage({
+							type: 'Alert',
+							variant: 'error',
+							body: Array.from(updatedErrors.values()).join('\n'),
+						}),
+					)
 				}
 				errors = updatedErrors
 				continue
@@ -142,8 +170,8 @@ export default class UiAdapter extends EventProcessor {
 	 * @throws {Error} If not implemented in subclass.
 	 */
 	render(message) {
-		throw new Error("render() must be implemented by subclass")
-		this.emit("rendered", message)
+		throw new Error('render() must be implemented by subclass')
+		this.emit('rendered', message)
 	}
 }
 
@@ -157,14 +185,14 @@ export default class UiAdapter extends EventProcessor {
  * @returns {UIForm} Form instance ready for input.
  */
 export function generateForm(BodyClass, options = {}) {
-	const { initialState = {}, t = v => v } = options
+	const { initialState = {}, t = (v) => v } = options
 	const fields = []
 
 	for (const [name, schema] of Object.entries(BodyClass)) {
-		if (typeof schema !== "object" || schema === null || !name || !schema.help) continue
+		if (typeof schema !== 'object' || schema === null || !name || !schema.help) continue
 
 		const label = t(schema.help) || name
-		const placeholder = t(schema.placeholder || schema.defaultValue || "")
+		const placeholder = t(schema.placeholder || schema.defaultValue || '')
 		const isRequired = !!schema.required
 
 		fields.push(
@@ -174,12 +202,12 @@ export function generateForm(BodyClass, options = {}) {
 				type: schema.type || FormInput.TYPES.TEXT,
 				required: isRequired,
 				placeholder,
-				options: schema.options ? schema.options.map(o => String(o)) : [],
+				options: schema.options ? schema.options.map((o) => String(o)) : [],
 				validation: schema.validate
 					? (value) => {
-						const res = schema.validate(value)
-						return res === true ? true : typeof res === "string" ? res : `Invalid ${name}`
-					}
+							const res = schema.validate(value)
+							return res === true ? true : typeof res === 'string' ? res : `Invalid ${name}`
+						}
 					: () => true,
 			}),
 		)

package/src/core/index.js

@@ -1,12 +1,41 @@
-export { default as InputAdapter } from "./InputAdapter.js"
-export { default as OutputAdapter } from "./OutputAdapter.js"
-export { default as UIStream } from "./Stream.js"
+export { default as InputAdapter } from './InputAdapter.js'
+export { default as OutputAdapter } from './OutputAdapter.js'
 
-export { default as UiMessage } from "./Message/Message.js"
-export { default as FormMessage } from "./Form/Message.js"
-export { default as FormInput } from "./Form/Input.js"
-export { default as UIForm } from "./Form/Form.js"
+import UIStream from './Stream.js'
+export { UIStream, UIStream as UiStream }
+import StreamEntry from './StreamEntry.js'
+export { StreamEntry, StreamEntry as UiStreamEntry }
 
-export { default as Error, CancelError } from "./Error/index.js"
+export { default as UiMessage } from './Message/Message.js'
+export { default as FormMessage } from './Form/Message.js'
+export { default as FormInput } from './Form/Input.js'
 
-export { default as UiAdapter } from "./UiAdapter.js"
+import UIForm from './Form/Form.js'
+export { UIForm, UIForm as UiForm }
+
+export { default as Error, CancelError } from './Error/index.js'
+
+export { default as UiAdapter } from './UiAdapter.js'
+
+// Flow — Yield-Based Universal UI Architecture
+export {
+	runFlow,
+	flow,
+	View,
+	Prompt,
+	Stream,
+	Alert,
+	Toast,
+	Badge,
+	Text,
+	Table,
+	Input,
+	Select,
+	Confirm,
+	Multiselect,
+	Mask,
+	Password,
+	Spinner,
+	Progress,
+} from './Flow.js'
+export { default as Flow } from './Flow.js'

package/src/functions.js

@@ -1,19 +1,18 @@
-import { empty } from "@nan0web/types"
+import { empty } from '@nan0web/types'
 
 export const spaces = (options = {}) => {
 	const { cols = [], padding = 1, aligns = [] } = options
-	return (row) => (
+	return (row) =>
 		row.map((str, i) => {
-			const pad = " ".repeat(cols[i] - str.length + padding)
-			return aligns[i] === "r" ? pad + str : str + pad
+			const pad = ' '.repeat(cols[i] - str.length + padding)
+			return aligns[i] === 'r' ? pad + str : str + pad
 		})
-	)
 }
 
 export const weight = (arr) => {
-	return (Fn = v => v) => {
+	return (Fn = (v) => v) => {
 		const cols = []
-		arr.forEach(m => {
+		arr.forEach((m) => {
 			Fn(m).forEach((str, i) => {
 				if (undefined === cols[i]) cols[i] = 0
 				cols[i] = Math.max(str.length, cols[i])
@@ -23,16 +22,10 @@ export const weight = (arr) => {
 	}
 }
 
-
 export const table = (options = {}) => {
-	const {
-		Fn = v => v,
-		cols = [],
-		padding = 1,
-		aligns = []
-	} = options
+	const { Fn = (v) => v, cols = [], padding = 1, aligns = [] } = options
 	return (arr) => {
 		const options = { cols: empty(cols) ? weight(arr)(Fn) : cols, padding, aligns }
-		return arr.map(row => spaces(options)(row))
+		return arr.map((row) => spaces(options)(row))
 	}
 }