@nan0web/ui 1.0.1 → 1.0.3

package/README.md

@@ -1,8 +1,6 @@
 # @nan0web/ui
 
-|[Status](https://github.com/nan0web/monorepo/blob/main/system.md#написання-сценаріїв)|Documentation|Test coverage|Features|Npm version|
-|---|---|---|---|---|
- |🟢 `96.6%` |🧪 [English 🏴󠁧󠁢󠁥󠁮󠁧󠁿](https://github.com/nan0web/ui/blob/main/README.md)<br />[Українською 🇺🇦](https://github.com/nan0web/ui/blob/main/docs/uk/README.md) |🟡 `80.9%` |✅ d.ts 📜 system.md 🕹️ playground |— |
+<!-- %PACKAGE_STATUS% -->
 
 A lightweight, agnostic UI framework designed with the **nan0web philosophy**
 — one application logic, many UI implementations.
@@ -53,10 +51,9 @@ decoupled communication systems between UI components.
 How to create input and output messages?
 ```js
 import { InputMessage, OutputMessage } from '@nan0web/ui'
-
 const input = InputMessage.from({ value: 'Hello User' })
 const output = OutputMessage.from({ content: ['Welcome to @nan0web/ui'] })
-console.info(input.value) // ← Hello User
+console.info(input.value) // ← Message { body: "Hello User", head: {} }
 console.info(output.content[0]) // ← Welcome to @nan0web/ui
 ```
 ### Forms
@@ -76,7 +73,6 @@ Field types include:
 How to define and validate a UIForm?
 ```js
 import { UIForm } from '@nan0web/ui'
-
 const form = new UIForm({
 	title: "Contact Form",
 	fields: [
@@ -88,11 +84,9 @@ const form = new UIForm({
 		message: "Hello!"
 	}
 })
-
 const result = form.validate()
 console.info(result.isValid) // ← false
 console.info(result.errors.email) // ← Invalid email format
-
 ```
 ### Components
 
@@ -104,7 +98,6 @@ Components render data as frame-ready output.
 How to render the Welcome component?
 ```js
 import { Welcome } from '@nan0web/ui'
-
 const frame = Welcome({ user: { name: "Alice" } })
 const firstLine = frame[0].join("")
 console.info(firstLine) // ← Welcome Alice!
@@ -122,7 +115,6 @@ Every view has:
 How to render frame with View?
 ```js
 import { View } from '@nan0web/ui'
-
 const view = new View()
 view.render(1)(["Hello, world"])
 console.info(String(view.frame)) // ← "\rHello, world"
@@ -132,41 +124,24 @@ console.info(String(view.frame)) // ← "\rHello, world"
 `Frame` manages visual rendering with width and height limits.
 Useful for fixed-size terminals or UI blocks.
 
+Render methods:
+
+- `APPEND` – adds content after previous frame
+- `REPLACE` – erases and replaces full frame area
+- `VISIBLE` – renders only visible part of frame
+
 How to create a Frame with fixed size?
 ```js
 import { Frame } from '@nan0web/ui'
-
 const frame = new Frame({
 	value: [["Frame content"]],
 	width: 20,
 	height: 5,
 	renderMethod: Frame.RenderMethod.APPEND,
 })
-
 const rendered = frame.render()
 console.info(rendered.includes("Frame content")) // ← true
 ```
-### 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.
-
-How to create a basic user app that greets?
-```js
-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!
-```
 ### Models
 
 UI models are plain data objects managed by `Model` classes.
@@ -176,7 +151,6 @@ UI models are plain data objects managed by `Model` classes.
 How to use a User model?
 ```js
 import { Model } from '@nan0web/ui'
-
 const user = new Model.User({ name: "Charlie", email: "charlie@example.com" })
 console.info(user.name) // ← Charlie
 console.info(user.email) // ← charlie@example.com
@@ -191,7 +165,6 @@ with minimal setup.
 How to test UI components with assertions?
 ```js
 import { Welcome, InputMessage } from '@nan0web/ui'
-
 const output = Welcome({ user: { name: "Test" } })
 const input = InputMessage.from({ value: "test" })
 console.log(output[0].join("")) // ← Welcome Test!

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nan0web/ui",
-	"version": "1.0.1",
+	"version": "1.0.3",
 	"description": "NaN•Web UI. One application logic (algorithm) and many UI.",
 	"main": "src/index.js",
 	"types": "types/index.d.ts",
@@ -13,7 +13,8 @@
 	"scripts": {
 		"build": "tsc",
 		"playground": "node playground/main.js",
-		"test": "node --test --test-timeout=3333 \"src/**/*.test.js\" | nan0test parse --fail",
+		"test": "node --test --test-timeout=3333 \"src/**/*.test.js\"",
+		"test:nan0test": "node --test --test-timeout=3333 \"src/**/*.test.js\" | nan0test parse --fail",
 		"test:coverage": "node --experimental-test-coverage --test-coverage-include=\"src/**/*.js\" --test-coverage-exclude=\"src/**/*.test.js\" --test \"src/**/*.test.js\"",
 		"test:coverage:collect": "nan0test coverage",
 		"test:docs": "node --test src/README.md.js",
@@ -35,6 +36,10 @@
 			"import": "./src/Component/index.js",
 			"types": "./types/Component/index.d.ts"
 		},
+		"./core": {
+			"import": "./src/core/index.js",
+			"types": "./types/core/index.d.ts"
+		},
 		"./cli-app": "./apps/cli/src/index.js",
 		"./mobile-app": "./apps/mobile/src/index.js",
 		"./web-app": "./apps/web/src/App.jsx"

package/src/App/Core/CoreApp.js

@@ -1,5 +1,5 @@
+import { Message } from "@nan0web/co"
 import { typeOf } from "@nan0web/types"
-import { CommandMessage } from "../Command/index.js"
 import UI from "./UI.js"
 
 /** @typedef {Function} CommandFn */
@@ -18,7 +18,7 @@ export default class CoreApp {
 	/** @type {object} App state */
 	state
 
-	/** @type {CommandMessage} Starting command parsed from argv */
+	/** @type {Message} Starting command parsed from argv */
 	startCommand
 
 	/**
@@ -26,18 +26,19 @@ export default class CoreApp {
 	 * @param {object} props - CoreApp properties
 	 * @param {string} [props.name="CoreApp"] - App name
 	 * @param {object} [props.state={}] - Initial state object
-	 * @param {string[]} [props.argv=[]] - Command line arguments to parse
+	 * @param {Message} [props.startCommand=new Message()] - Command line arguments to parse
 	 */
 	constructor(props = {}) {
 		const {
 			name = "CoreApp",
 			state = {},
-			argv = [],
+			startCommand = new Message(),
 		} = props
 		this.name = String(name)
 		this.state = state
 		this.commands = new Map()
-		this.startCommand = CommandMessage.parse(argv)
+		// @deprecated @todo fix the argv by moving to ui-cli.
+		this.startCommand = Message.from(startCommand ?? {})
 	}
 
 	/**
@@ -78,39 +79,33 @@ export default class CoreApp {
 
 	/**
 	 * Process a command message.
-	 * @param {CommandMessage} commandMessage - Command to process
+	 * @param {Message} msg - Command to process
 	 * @param {UI} ui - UI instance to use for rendering
 	 * @returns {Promise<any>} Output of the command
 	 * @throws {Error} If the command is not registered
 	 */
-	async processCommand(commandMessage, ui) {
-		const cmd = commandMessage.args[0]
-		const handler = this.commands.get(cmd)
+	async processCommand(msg, ui) {
+		const handler = this.commands.get(msg.constructor.name)
 		if (!handler) {
 			throw new Error([
 				"Unknown command", ": ",
-				cmd, "\n",
+				msg.constructor.name, "\n",
 				"Available commands", ": ",
 				[...this.commands.keys()].join(", "),
 			].join(""))
 		}
-		const Class = /** @type {typeof CommandMessage} */ (commandMessage.constructor)
-		const command = Class.from({
-			args: commandMessage.args.slice(1),
-			opts: commandMessage.opts,
-		})
-		return await handler.apply(this, [command, ui])
+		return await handler.apply(this, [msg, ui])
 	}
 
 	/**
 	 * Process an array of command messages sequentially.
-	 * @param {CommandMessage[]} commandMessages - Array of commands to process
+	 * @param {Message[]} Messages - Array of commands to process
 	 * @param {UI} ui - UI instance to use for rendering
 	 * @returns {Promise<any[]>} Array of command outputs
 	 */
-	async processCommands(commandMessages, ui) {
+	async processCommands(Messages, ui) {
 		const results = []
-		for (const cmdMsg of commandMessages) {
+		for (const cmdMsg of Messages) {
 			const result = await this.processCommand(cmdMsg, ui)
 			results.push(result)
 		}

package/src/App/Core/UI.js

@@ -1,8 +1,8 @@
+import { Message } from "@nan0web/co"
+import { notEmpty } from "@nan0web/types"
 import View from "../../View/View.js"
 import CoreApp from "./CoreApp.js"
 import Widget from "./Widget.js"
-import { notEmpty } from "@nan0web/types"
-import { CommandMessage } from "../Command/index.js"
 
 /** @typedef {import("../../View/View.js").ComponentFn} ComponentFn */
 
@@ -25,10 +25,10 @@ class UI extends Widget {
 	}
 
 	/**
-	 * Convert raw input to CommandMessage array.
+	 * Convert raw input to Message array.
 	 * Must be implemented by subclasses.
 	 * @param {any} rawInput - Raw input to convert
-	 * @returns {CommandMessage[]} Array of command messages
+	 * @returns {Message[]} Array of command messages
 	 * @throws {Error} Always thrown as this method must be implemented by subclasses
 	 */
 	convertInput(rawInput) {
@@ -58,7 +58,7 @@ class UI extends Widget {
 			const answer = await this.app.selectCommand(this)
 			if (answer) {
 				const [input] = this.convertInput(rawInput)
-				const cmd = new CommandMessage({
+				const cmd = new Message({
 					argv: [answer],
 					opts: input?.opts ?? {},
 				})

package/src/App/User/UserApp.js

@@ -1,6 +1,6 @@
+import { Message } from "@nan0web/co"
 import { notEmpty } from "@nan0web/types"
 import CoreApp from "../Core/CoreApp.js"
-import Command, { CommandMessage } from "./Command/index.js"
 import User from "../../Model/User/User.js"
 import UserUI from "./UserUI.js"
 import InputMessage from "../../core/Message/InputMessage.js"
@@ -11,34 +11,19 @@ import InputMessage from "../../core/Message/InputMessage.js"
  * User can change user data to see another Welcome view.
  */
 class UserApp extends CoreApp {
-	/** @type {CommandMessage} Starting command parsed from argv */
-	startCommand
-
-	/** @type {object} App state */
-	state
-
 	/**
 	 * Creates a new UserApp instance.
-	 * @param {object} props - UserApp properties
-	 * @param {string} [props.name="UserApp"] - App name
-	 * @param {object} [props.state={}] - Initial state object
-	 * @param {string[]} [props.argv=[]] - Command line arguments to parse
+	 * @param {Partial<CoreApp>} [props={}] - UserApp properties
 	 */
 	constructor(props = {}) {
 		super(props)
-		const {
-			argv = [],
-			state = {},
-		} = props
-		this.state = state
-		this.startCommand = CommandMessage.parse(argv)
 		this.registerCommand("setUser", this.setUser.bind(this))
 		this.registerCommand("welcome", this.welcome.bind(this))
 	}
 
 	/**
 	 * Set user data from params.
-	 * @param {CommandMessage} cmd - Command message with user data
+	 * @param {Message} cmd - Command message with user data
 	 * @param {UserUI} ui - UI instance
 	 * @returns {Promise<{ message: string }>} Welcome message
 	 */
@@ -52,7 +37,7 @@ class UserApp extends CoreApp {
 
 	/**
 	 * Show welcome message for current user.
-	 * @param {CommandMessage} cmd - Command message
+	 * @param {Message} cmd - Command message
 	 * @param {UserUI} ui - UI instance
 	 * @returns {Promise<string[][]>} Welcome view output
 	 */

package/src/App/User/UserUI.js

@@ -1,5 +1,5 @@
+import { Message } from "@nan0web/co"
 import App from "../Core/index.js"
-import { CommandMessage } from "./Command/index.js"
 
 /**
  * UserUI connects UserApp and View.
@@ -8,13 +8,13 @@ import { CommandMessage } from "./Command/index.js"
  */
 export default class UserUI extends App.UI {
 	/**
-	 * Convert raw input to CommandMessage array.
+	 * Convert raw input to Message array.
 	 * If user.name provided in rawInput, use it directly.
 	 * Otherwise ask user for name.
 	 * @param {any} rawInput - Raw input to convert
-	 * @returns {CommandMessage[]} Array of command messages
+	 * @returns {Message[]} Array of command messages
 	 */
 	convertInput(rawInput) {
-		return [CommandMessage.parse(rawInput)]
+		return [new Message({ body: rawInput })]
 	}
 }

package/src/App/User/index.js

@@ -1,15 +1,9 @@
 import UserApp from "./UserApp.js"
 import UserUI from "./UserUI.js"
-import UserCommand from "./Command/index.js"
-import Command from "../Command/index.js"
 
 export { UserApp, UserUI }
 
 export default {
 	App: UserApp,
 	UI: UserUI,
-	Command: {
-		...Command,
-		...UserCommand,
-	},
 }

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

@@ -120,10 +120,10 @@ function testRender() {
 
 		const input = InputMessage.from({ value: 'Hello User' })
 		const output = OutputMessage.from({ content: ['Welcome to @nan0web/ui'] })
-		console.info(input.value) // ← Hello User
+		console.info(input.value) // ← Message { body: "Hello User", head: {} }
 		console.info(output.content[0]) // ← Welcome to @nan0web/ui
-		assert.equal(input.value, 'Hello User')
-		assert.equal(output.content[0], 'Welcome to @nan0web/ui')
+		assert.deepStrictEqual({ ...console.output()[0][1] }, { body: "Hello User", head: {} })
+		assert.equal(console.output()[1][1], 'Welcome to @nan0web/ui')
 	})
 
 	/**
@@ -210,6 +210,12 @@ function testRender() {
 	 *
 	 * `Frame` manages visual rendering with width and height limits.
 	 * Useful for fixed-size terminals or UI blocks.
+	 *
+	 * Render methods:
+	 *
+	 * - `APPEND` – adds content after previous frame
+	 * - `REPLACE` – erases and replaces full frame area
+	 * - `VISIBLE` – renders only visible part of frame
 	 */
 	it("How to create a Frame with fixed size?", () => {
 		//import { Frame } from '@nan0web/ui'
@@ -225,29 +231,22 @@ function testRender() {
 		console.info(rendered.includes("Frame content")) // ← true
 		assert.ok(rendered.includes("Frame content"))
 	})
+	it("How to create a Frame with different render methods?", () => {
+		//import { Frame } from '@nan0web/ui'
 
-	/**
-	 * @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 frame = new Frame({
+			value: [["Frame content"]],
+			width: 20,
+			height: 5,
+		})
 
-		const app = new App.User.App({ name: "GreetApp" })
-		const view = new View()
-		view.register("Welcome", Welcome)
+		frame.renderMethod = Frame.RenderMethod.REPLACE
+		const renderedReplace = frame.render()
+		assert.ok(renderedReplace.includes("Frame content"))
 
-		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!"))
+		frame.renderMethod = Frame.RenderMethod.VISIBLE
+		const renderedVisible = frame.render()
+		assert.ok(renderedVisible.includes("Frame content"))
 	})
 
 	/**

package/src/StdIn.js

@@ -1,5 +1,4 @@
 import EventProcessor from "@nan0web/event/oop"
-import { CommandMessage } from "@nan0web/co"
 import { typeOf } from "@nan0web/types"
 import InputMessage from "./core/Message/InputMessage.js"
 
@@ -91,8 +90,7 @@ class StdIn extends EventProcessor {
 	decode(message) {
 		if (message instanceof InputMessage) return message
 		if (Array.isArray(message) && message.every(typeOf(String))) {
-			const parsed = CommandMessage.parse(message)
-			return new InputMessage({ value: parsed })
+			return new InputMessage({ value: message })
 		}
 		return new InputMessage(message)
 	}

package/src/core/Error/CancelError.js

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

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,5 +1,6 @@
 import FormMessage from "./Message.js"
 import FormInput from "./Input.js"
+import Message from "@nan0web/co"
 
 /**
  * Abstract form for data entry.
@@ -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
 	}
 
 	/**
@@ -208,15 +209,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 +237,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 +251,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 +298,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 {Function|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()