@nan0web/ui 1.0.2 → 1.0.4

package/src/App/index.js

@@ -1,4 +1,3 @@
-import Command from "./Command/index.js"
 import Scenario from "./Scenario.js"
 import UI from "./Core/UI.js"
 
@@ -8,7 +7,6 @@ import User from "./User/index.js"
 export {
 	Core,
 	User,
-	Command,
 	Scenario,
 	UI,
 }
@@ -16,7 +14,6 @@ export {
 export default {
 	Core,
 	User,
-	Command,
 	Scenario,
 	UI,
 }

package/src/README.md.js

@@ -8,17 +8,13 @@ import {
 	runSpawn,
 } from "@nan0web/test"
 import {
-	App,
-	Component,
 	Frame,
-	InputMessage,
 	Model,
 	OutputMessage,
-	UIMessage,
-	UIForm,
-	UIStream,
 	View,
 	FormInput,
+	UiMessage,
+	UiForm,
 } from "./index.js"
 import { Welcome } from "./Component/index.js"
 
@@ -108,8 +104,7 @@ function testRender() {
 	 *
 	 * UI communication is built around messages:
 	 *
-	 * - **`UIMessage`** – abstract message base class
-	 * - **`InputMessage`** – user input message (value, options)
+	 * - **`UiMessage`** – abstract message base class
 	 * - **`OutputMessage`** – system output (content, error, priority)
 	 *
 	 * Messages are simple, serializable data containers. They help build
@@ -118,19 +113,22 @@ function testRender() {
 	it("How to create input and output messages?", () => {
 		//import { InputMessage, OutputMessage } from '@nan0web/ui'
 
-		const input = InputMessage.from({ value: 'Hello User' })
+		const input = UiMessage.from({ body: 'Hello User' })
 		const output = OutputMessage.from({ content: ['Welcome to @nan0web/ui'] })
-		console.info(input.value) // ← Hello User
-		console.info(output.content[0]) // ← Welcome to @nan0web/ui
-		assert.equal(input.value, 'Hello User')
-		assert.equal(output.content[0], 'Welcome to @nan0web/ui')
+		console.info(input) // ← Message { body: "Hello User", head: {}, id: "....", type: "" }
+		console.info(String(output)) // ← Welcome to @nan0web/ui
+		assert.deepStrictEqual(console.output()[0][1].body, "Hello User")
+		assert.deepStrictEqual(console.output()[0][1].head, {})
+		assert.deepStrictEqual(console.output()[0][1].type, "")
+		assert.ok(console.output()[0][1].id)
+		assert.ok(console.output()[1][1].endsWith('Welcome to @nan0web/ui'))
 	})
 
 	/**
 	 * @docs
 	 * ### Forms
 	 *
-	 * `UIForm` supports field definitions, data management, and schema validation.
+	 * `UiForm` supports field definitions, data management, and schema validation.
 	 * Every form includes a title, fields, and current state.
 	 *
 	 * Field types include:
@@ -142,10 +140,10 @@ function testRender() {
 	 * - `checkbox`
 	 * - `textarea`
 	 */
-	it("How to define and validate a UIForm?", () => {
-		//import { UIForm } from '@nan0web/ui'
+	it("How to define and validate a UiForm?", () => {
+		//import { UiForm } from '@nan0web/ui'
 
-		const form = new UIForm({
+		const form = new UiForm({
 			title: "Contact Form",
 			fields: [
 				FormInput.from({ name: "email", label: "Email Address", type: "email", required: true }),
@@ -157,12 +155,12 @@ function testRender() {
 			}
 		})
 
-		const result = form.validate()
-		console.info(result.isValid) // ← false
-		console.info(result.errors.email) // ← Invalid email format
+		const errors = form.validate()
+		console.info(errors.size) // ← 1
+		console.info(errors.get("email")) // ← Invalid email format
 
-		assert.equal(result.isValid, false)
-		assert.equal(result.errors.email, "Invalid email format")
+		assert.equal(console.output()[0][1], 1)
+		assert.equal(console.output()[1][1], "Invalid email format")
 	})
 
 	/**
@@ -249,30 +247,6 @@ function testRender() {
 		assert.ok(renderedVisible.includes("Frame content"))
 	})
 
-	/**
-	 * @docs
-	 * ### App Architecture
-	 *
-	 * `App` provides the main application logic.
-	 *
-	 * - Core – minimal UI layer
-	 * - User – user-specific UI commands
-	 *
-	 * Each app registers commands and binds them to UI actions.
-	 */
-	it("How to create a basic user app that greets?", async () => {
-		//import { App, View } from '@nan0web/ui'
-
-		const app = new App.User.App({ name: "GreetApp" })
-		const view = new View()
-		view.register("Welcome", Welcome)
-
-		const cmd = App.Command.Message.parse("welcome --user Bob")
-		const result = await app.processCommand(cmd, new App.User.UI(app, view))
-		console.info(String(result)) // ← Welcome Bob!
-		assert.ok(console.output()[0][1].includes("Welcome Bob!"))
-	})
-
 	/**
 	 * @docs
 	 * ### Models
@@ -301,13 +275,15 @@ function testRender() {
 	 * with minimal setup.
 	 */
 	it("How to test UI components with assertions?", () => {
-		//import { Welcome, InputMessage } from '@nan0web/ui'
+		//import { Welcome } from '@nan0web/ui'
 
 		const output = Welcome({ user: { name: "Test" } })
-		const input = InputMessage.from({ value: "test" })
-		console.log(output[0].join("")) // ← Welcome Test!
-		assert.equal(console.output()[0][1], "Welcome Test!")
-		assert.ok(input instanceof InputMessage)
+		console.info(output) // ← Welcome Test!
+		assert.deepStrictEqual(console.output()[0][1], [
+			["Welcome", " ", "Test", "!"],
+			["What can we do today great?"],
+			[""],
+		])
 	})
 
 	/**
@@ -316,10 +292,10 @@ function testRender() {
 	 *
 	 * The library includes rich playground demos:
 	 *
-	 * - [Registration Form](./playground/registration.form.js)
-	 * - [Currency Exchange](./playground/currency.exchange.js)
-	 * - [Mobile Top-up](./playground/topup.telephone.js)
-	 * - [Language Selector](./playground/language.form.js)
+	 * - [Registration Form](./play/registration.form.js)
+	 * - [Currency Exchange](./play/currency.exchange.js)
+	 * - [Mobile Top-up](./play/topup.telephone.js)
+	 * - [Language Selector](./play/language.form.js)
 	 *
 	 * Run to explore live functionality:
 	 */
@@ -330,10 +306,10 @@ function testRender() {
 		 * git clone https://github.com/nan0web/ui.git
 		 * cd ui
 		 * npm install
-		 * npm run playground
+		 * npm run play
 		 * ```
 		 */
-		assert.ok(String(pkg.scripts?.playground).includes("node playground"))
+		assert.ok(String(pkg.scripts?.play).includes("node play"))
 		const response = await runSpawn("git", ["remote", "get-url", "origin"])
 		assert.ok(response.code === 0, "git command fails (e.g., not in a git repo)")
 		assert.ok(response.text.trim().endsWith(":nan0web/ui.git"))

package/src/StdIn.js

@@ -1,21 +1,20 @@
 import EventProcessor from "@nan0web/event/oop"
-import { CommandMessage } from "@nan0web/co"
 import { typeOf } from "@nan0web/types"
-import InputMessage from "./core/Message/InputMessage.js"
+import { UiMessage } from "./core/index.js"
 
 class Processor extends EventProcessor { }
 
 /**
  * Handles standard input stream with message buffering.
  */
-class StdIn extends EventProcessor {
+export default class StdIn extends EventProcessor {
 	/** @type {number} Read interval in milliseconds */
 	static READ_INTERVAL = 99
 
 	/** @type {string[]} Messages to ignore */
 	static IGNORE_MESSAGES = ["", "undefined"]
 
-	/** @type {InputMessage[]} Input message buffer */
+	/** @type {UiMessage[]} Input message buffer */
 	stream = []
 
 	/** @type {Processor} Input processor */
@@ -25,7 +24,7 @@ class StdIn extends EventProcessor {
 	 * Creates a new StdIn instance.
 	 * @param {object} props - StdIn properties
 	 * @param {Processor} [props.processor] - Input processor
-	 * @param {InputMessage[]} [props.stream=[]] - Initial input stream
+	 * @param {UiMessage[]} [props.stream=[]] - Initial input stream
 	 */
 	constructor(props = {}) {
 		super()
@@ -59,13 +58,13 @@ class StdIn extends EventProcessor {
 	/**
 	 * Reads a message from the input stream.
 	 * Waits until messages are available if stream is empty.
-	 * @returns {Promise<InputMessage>} Next input message
+	 * @returns {Promise<UiMessage>} Next input message
 	 */
 	async read() {
 		while (this.ended) {
 			await new Promise(resolve => setTimeout(resolve, StdIn.READ_INTERVAL))
 		}
-		return this.stream.shift() ?? new InputMessage()
+		return this.stream.shift() ?? new UiMessage()
 	}
 
 	/**
@@ -84,17 +83,16 @@ class StdIn extends EventProcessor {
 	}
 
 	/**
-	 * Decodes a message into an InputMessage instance.
-	 * @param {InputMessage | string[] | any} message - Message to decode
-	 * @returns {InputMessage} Decoded input message
+	 * Decodes a message into an UiMessage instance.
+	 * @param {UiMessage | string[] | any} message - Message to decode
+	 * @returns {UiMessage} Decoded input message
 	 */
 	decode(message) {
-		if (message instanceof InputMessage) return message
+		if (message instanceof UiMessage) return message
 		if (Array.isArray(message) && message.every(typeOf(String))) {
-			const parsed = CommandMessage.parse(message)
-			return new InputMessage({ value: parsed })
+			return new UiMessage({ value: message })
 		}
-		return new InputMessage(message)
+		return new UiMessage(message)
 	}
 
 	/**
@@ -108,4 +106,3 @@ class StdIn extends EventProcessor {
 	}
 }
 
-export default StdIn

package/src/View/View.js

@@ -3,13 +3,13 @@ import Frame, { FrameRenderMethod } from "../Frame/Frame.js"
 import Locale from "../Locale.js"
 import StdOut from "../StdOut.js"
 import StdIn from "../StdIn.js"
-import InputMessage from "../core/Message/InputMessage.js"
 import RenderOptions from "./RenderOptions.js"
+import UiMessage from "../core/Message/Message.js"
 
 /**
  * @typedef {Object} ComponentFn
  * @property {string} name
- * @property {(input: InputMessage) => Promise<any>} ask
+ * @property {(input: UiMessage) => Promise<any>} ask
  * @property {Function} bind
  */
 
@@ -256,8 +256,8 @@ export default class View {
 	}
 
 	/**
-	 * @param {InputMessage} input
-	 * @returns {Promise<InputMessage | null>}
+	 * @param {UiMessage} input
+	 * @returns {Promise<UiMessage | null>}
 	 */
 	async ask(input) {
 		const name = input.constructor.name.replace(/Input$/, "")
@@ -268,7 +268,7 @@ export default class View {
 		let result = null
 		do {
 			const answer = await this.stdin.read()
-			result = /** @type {typeof InputMessage} */ (input.constructor).from(answer)
+			result = /** @type {typeof UiMessage} */ (input.constructor).from(answer)
 		} while (!result.isValid && !result.escaped)
 		return result.escaped ? null : result
 	}

package/src/core/Error/index.js

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

package/src/core/Form/Form.js

@@ -1,3 +1,4 @@
+import Message from "@nan0web/co"
 import FormMessage from "./Message.js"
 import FormInput from "./Input.js"
 
@@ -18,24 +19,24 @@ export default class UIForm extends FormMessage {
 	/** @type {Object} */ schema = {}
 
 	/* ------------------------------------------------------------------ */
-	/*                     static validator registry                       */
+	/*                     static validation registry                       */
 	/* ------------------------------------------------------------------ */
 
 	/** @type {Object<string,Function>} */
-	static _validators = {}
+	static _validations = {}
 
 	/**
-	 * Register a custom validator that can be referenced by name in a schema.
+	 * Register a custom validation that can be referenced by name in a schema.
 	 *
-	 * @param {string} name - Identifier used in schema.validator.
+	 * @param {string} name - Identifier used in schema.validation.
 	 * @param {(value:any)=>true|string} fn - Function returns true if valid,
 	 *   otherwise returns an error message.
 	 */
-	static addValidator(name, fn) {
+	static addValidation(name, fn) {
 		if (typeof name !== "string" || typeof fn !== "function") {
-			throw new Error("Validator name must be a string and fn must be a function")
+			throw new Error("validation name must be a string and fn must be a function")
 		}
-		UIForm._validators[name] = fn
+		UIForm._validations[name] = fn
 	}
 
 	/**
@@ -111,10 +112,10 @@ export default class UIForm extends FormMessage {
 	/**
 	 * Validates the entire form.
 	 *
-	 * @returns {{isValid: boolean, errors: Object}} Validation result.
+	 * @returns {Map<string, string>} Map of validation errors, empty if valid.
 	 */
 	validate() {
-		const errors = {}
+		const errors = new Map()
 		let isValid = true
 
 		this.fields.forEach((field) => {
@@ -122,7 +123,7 @@ export default class UIForm extends FormMessage {
 
 			// Required validation based on field definition or schema
 			if (field.required && (fieldValue === '' || fieldValue === null || fieldValue === undefined)) {
-				errors[field.name] = 'This field is required'
+				errors.set(field.name, 'This field is required')
 				isValid = false
 				return
 			}
@@ -131,12 +132,14 @@ export default class UIForm extends FormMessage {
 			const { isValid: fieldValid, errors: fieldErrors } = this.validateField(field.name, fieldValue)
 
 			if (!fieldValid) {
-				Object.assign(errors, fieldErrors)
+				for (const [key, err] of Object.entries(fieldErrors)) {
+					errors.set(key, err)
+				}
 				isValid = false
 			}
 		})
 
-		return { isValid, errors }
+		return errors
 	}
 
 	/**
@@ -208,15 +211,15 @@ export default class UIForm extends FormMessage {
 			}
 		}
 
-		// Custom validator – can be a function or a string referencing a static validator
-		if (schema.validator) {
+		// Custom validation – can be a function or a string referencing a static validation
+		if (schema.validation) {
 			let result
-			if (typeof schema.validator === 'function') {
-				result = schema.validator(value)
-			} else if (typeof schema.validator === 'string') {
-				const fn = UIForm._validators[schema.validator]
+			if (typeof schema.validation === 'function') {
+				result = schema.validation(value)
+			} else if (typeof schema.validation === 'string') {
+				const fn = UIForm._validations[schema.validation]
 				if (!fn) {
-					throw new Error(`Validator "${schema.validator}" not registered`)
+					throw new Error(`validation "${schema.validation}" not registered`)
 				}
 				result = fn(value)
 			}
@@ -236,9 +239,7 @@ export default class UIForm extends FormMessage {
 	 */
 	toJSON() {
 		return {
-			id: this.id,
-			type: this.type,
-			time: this.time.toISOString(),
+			time: new Date(this.time).toISOString(),
 			title: this.title,
 			fields: this.fields.map(f => f.toJSON ? f.toJSON() : f),
 			state: this.state,
@@ -252,6 +253,25 @@ export default class UIForm extends FormMessage {
 	 */
 	static from(input) {
 		if (input instanceof UIForm) return input
+		if (input instanceof Message) {
+			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),
+				}))
+			}
+			return new UIForm({
+				title: Class.name,
+				fields
+			})
+		}
 		return new UIForm(input)
 	}
 
@@ -280,7 +300,7 @@ export default class UIForm extends FormMessage {
 				required: !!custom.required,
 				placeholder: custom.placeholder ?? "",
 				options: custom.options ?? [],
-				validator: custom.validator ?? undefined,
+				validation: custom.validation ?? undefined,
 				defaultValue: custom.defaultValue ?? "",
 			})
 		})

package/src/core/Form/Input.js

@@ -1,3 +1,12 @@
+/**
+ * @typedef {Object} Filter
+ * @property {string} [q=""]
+ * @property {number} [offset=0]
+ * @property {number} [limit=36]
+ */
+
+/** @typedef {Array<string> | ((filter: Filter) => Promise<string[]>)} InputOptions */
+
 /**
  * Form input field descriptor.
  *
@@ -8,7 +17,7 @@
  * @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} validator - Custom validation function.
+ * @property {Function|null} validation - Custom validation function.
  * @property {*} defaultValue - Default value.
  */
 export default class FormInput {
@@ -17,8 +26,8 @@ export default class FormInput {
 	/** @type {string} */ type = 'text'
 	/** @type {boolean} */ required = false
 	/** @type {string} */ placeholder = ''
-	/** @type {Array<string>} */ options = []
-	/** @type {Function|null} */ validator = null
+	/** @type {InputOptions} */ options = []
+	/** @type {import("@nan0web/co").ValidateFn|null} */ validation = null
 	/** @type {*} */ defaultValue = null
 
 	/**
@@ -42,8 +51,8 @@ export default class FormInput {
 	 * @param {string} [props.type='text'] - Input type.
 	 * @param {boolean} [props.required=false] - Is required.
 	 * @param {string} [props.placeholder=''] - Placeholder.
-	 * @param {Array<string>} [props.options=[]] - Select options.
-	 * @param {Function} [props.validator=null] - Custom validator.
+	 * @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 {*} [props.defaultValue=null] - Default value.
 	 */
 	constructor(props) {
@@ -54,7 +63,7 @@ export default class FormInput {
 			required = this.required,
 			placeholder = this.placeholder,
 			options = [],
-			validator = this.validator,
+			validation = this.validation,
 			defaultValue = this.defaultValue
 		} = props
 
@@ -68,7 +77,7 @@ export default class FormInput {
 		this.required = Boolean(required)
 		this.placeholder = String(placeholder)
 		this.options = options
-		this.validator = validator
+		this.validation = validation
 		this.defaultValue = defaultValue
 
 		this.requireValidType()

package/src/core/Form/Message.js

@@ -1,22 +1,20 @@
-import OutputMessage from "../Message/OutputMessage.js"
+import UiMessage from "../Message/Message.js"
 
 /**
- * FormMessage – specialized OutputMessage for forms.
+ * FormMessage – specialized UiMessage for forms.
+ * It carries form-specific data and schema for validation.
  *
  * @class FormMessage
- * @extends OutputMessage
+ * @extends UiMessage
  */
-export default class FormMessage extends OutputMessage {
+export default class FormMessage extends UiMessage {
 	/**
 	 * Creates a FormMessage.
 	 *
 	 * @param {Object} [input={}] - Message properties.
 	 */
 	constructor(input = {}) {
-		super({
-			...input,
-			type: OutputMessage.TYPES.FORM,
-		})
+		super(input)
 		const {
 			data = {},
 			schema = {},

package/src/core/InputAdapter.js

@@ -1,6 +1,6 @@
 import Event from "@nan0web/event/oop"
-import InputMessage from "./Message/InputMessage.js"
 import CancelError from "./Error/CancelError.js"
+import UiMessage from "./Message/Message.js"
 
 /**
  * Abstract input adapter for UI implementations.
@@ -10,6 +10,10 @@ import CancelError from "./Error/CancelError.js"
  */
 export default class InputAdapter extends Event {
 	static CancelError = CancelError
+	/** @returns {typeof CancelError} */
+	get CancelError() {
+		return /** @type {typeof InputAdapter} */ (this.constructor).CancelError
+	}
 	/**
 	 * Starts listening for input and emits an `input` event.
 	 *
@@ -17,7 +21,7 @@ export default class InputAdapter extends Event {
 	 */
 	start() {
 		this.emit('input',
-			InputMessage.from({ value: "Adapter started" })
+			UiMessage.from({ body: "Adapter started" })
 		)
 	}