@nan0web/ui 1.0.0

package/src/Model/index.js

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

package/src/README.md.js

@@ -0,0 +1,371 @@
+import { describe, it, before, beforeEach } from "node:test"
+import assert from "node:assert/strict"
+import FS from "@nan0web/db-fs"
+import { NoConsole } from "@nan0web/log"
+import {
+	DatasetParser,
+	DocsParser,
+	runSpawn,
+} from "@nan0web/test"
+import {
+	App,
+	Component,
+	Frame,
+	InputMessage,
+	Model,
+	OutputMessage,
+	UIMessage,
+	UIForm,
+	UIStream,
+	View,
+	FormInput,
+} from "./index.js"
+import { Welcome } from "./Component/index.js"
+
+const fs = new FS()
+let pkg
+
+// Load package.json once before tests
+before(async () => {
+	const doc = await fs.loadDocument("package.json", {})
+	pkg = doc || {}
+})
+
+let console = new NoConsole()
+
+beforeEach((info) => {
+	console = new NoConsole()
+})
+
+/**
+ * Core test suite that also serves as the source for README generation.
+ *
+ * The block comments inside each `it` block are extracted to build
+ * the final `README.md`. Keeping the comments here ensures the
+ * documentation stays close to the code.
+ */
+function testRender() {
+	/**
+	 * @docs
+	 * # @nan0web/ui
+	 *
+	 * <!-- %PACKAGE_STATUS% -->
+	 *
+	 * A lightweight, agnostic UI framework designed with the **nan0web philosophy**
+	 * — one application logic, many UI implementations.
+	 *
+	 * This library provides core classes and utilities for building structured user interfaces.
+	 * It supports:
+	 *
+	 * - Messaging (Input/Output)
+	 * - Forms with validation
+	 * - Progress tracking
+	 * - Component rendering
+	 * - View management with Frame rendering
+	 * - App structure with core and user apps
+	 *
+	 * Built to work in sync or async, terminal-based or web-based apps,
+	 * focusing on type safety, minimalism, and pure JavaScript design.
+	 *
+	 * ## Installation
+	 */
+	it("How to install with npm?", () => {
+		/**
+		 * ```bash
+		 * npm install @nan0web/ui
+		 * ```
+		 */
+		assert.equal(pkg.name, "@nan0web/ui")
+	})
+	/**
+	 * @docs
+	 */
+	it("How to install with pnpm?", () => {
+		/**
+		 * ```bash
+		 * pnpm add @nan0web/ui
+		 * ```
+		 */
+		assert.equal(pkg.name, "@nan0web/ui")
+	})
+	/**
+	 * @docs
+	 */
+	it("How to install with yarn?", () => {
+		/**
+		 * ```bash
+		 * yarn add @nan0web/ui
+		 * ```
+		 */
+		assert.equal(pkg.name, "@nan0web/ui")
+	})
+
+	/**
+	 * @docs
+	 * ## Concepts & Architecture
+	 *
+	 * ### Message Flow
+	 *
+	 * UI communication is built around messages:
+	 *
+	 * - **`UIMessage`** – abstract message base class
+	 * - **`InputMessage`** – user input message (value, options)
+	 * - **`OutputMessage`** – system output (content, error, priority)
+	 *
+	 * Messages are simple, serializable data containers. They help build
+	 * decoupled communication systems between UI components.
+	 */
+	it("How to create input and output messages?", () => {
+		//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(output.content[0]) // ← Welcome to @nan0web/ui
+		assert.equal(input.value, 'Hello User')
+		assert.equal(output.content[0], 'Welcome to @nan0web/ui')
+	})
+
+	/**
+	 * @docs
+	 * ### Forms
+	 *
+	 * `UIForm` supports field definitions, data management, and schema validation.
+	 * Every form includes a title, fields, and current state.
+	 *
+	 * Field types include:
+	 *
+	 * - `text`
+	 * - `email`
+	 * - `number`
+	 * - `select`
+	 * - `checkbox`
+	 * - `textarea`
+	 */
+	it("How to define and validate a UIForm?", () => {
+		//import { UIForm } from '@nan0web/ui'
+
+		const form = new UIForm({
+			title: "Contact Form",
+			fields: [
+				FormInput.from({ name: "email", label: "Email Address", type: "email", required: true }),
+				FormInput.from({ name: "message", label: "Your Message", type: "textarea", required: true })
+			],
+			state: {
+				email: "invalid-email",
+				message: "Hello!"
+			}
+		})
+
+		const result = form.validate()
+		console.info(result.isValid) // ← false
+		console.info(result.errors.email) // ← Invalid email format
+
+		assert.equal(result.isValid, false)
+		assert.equal(result.errors.email, "Invalid email format")
+	})
+
+	/**
+	 * @docs
+	 * ### Components
+	 *
+	 * Components render data as frame-ready output.
+	 *
+	 * - `Welcome` – greets user by name
+	 * - `Process` – shows progress bar and time
+	 */
+	it("How to render the Welcome component?", () => {
+		//import { Welcome } from '@nan0web/ui'
+
+		const frame = Welcome({ user: { name: "Alice" } })
+		const firstLine = frame[0].join("")
+		console.info(firstLine) // ← Welcome Alice!
+		assert.equal(console.output()[0][1], "Welcome Alice!")
+	})
+
+	/**
+	 * @docs
+	 * ### View Manager
+	 *
+	 * `View` combines components and renders frames.
+	 *
+	 * Every view has:
+	 *
+	 * - Locale – formatted text, numbers, currency
+	 * - StdIn / StdOut – input/output streams
+	 * - Frame – output buffer with visual properties
+	 */
+	it("How to render frame with View?", () => {
+		//import { View } from '@nan0web/ui'
+
+		const view = new View()
+		view.render(1)(["Hello, world"])
+		console.info(String(view.frame)) // ← "\rHello, world"
+		assert.ok(String(view.frame).includes("Hello, world"))
+	})
+
+	/**
+	 * @docs
+	 * ### Frame Rendering
+	 *
+	 * `Frame` manages visual rendering with width and height limits.
+	 * Useful for fixed-size terminals or UI blocks.
+	 */
+	it("How to create a Frame with fixed size?", () => {
+		//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
+		assert.ok(rendered.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
+	 *
+	 * UI models are plain data objects managed by `Model` classes.
+	 *
+	 * - `User` – user data
+	 */
+	it("How to use a User model?", () => {
+		//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
+		assert.equal(user.name, "Charlie")
+		assert.equal(user.email, "charlie@example.com")
+	})
+
+	/**
+	 * @docs
+	 * ### Testing UI
+	 *
+	 * Core unit-tested to ensure stability in different environments.
+	 *
+	 * All components, adapters, and models are designed to be testable
+	 * with minimal setup.
+	 */
+	it("How to test UI components with assertions?", () => {
+		//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!
+		assert.equal(console.output()[0][1], "Welcome Test!")
+		assert.ok(input instanceof InputMessage)
+	})
+
+	/**
+	 * @docs
+	 * ## Playground Demos
+	 *
+	 * 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)
+	 *
+	 * Run to explore live functionality:
+	 */
+	it("How to run the playground?", async () => {
+		/**
+		 * ```bash
+		 * # Clone repository and run playground
+		 * git clone https://github.com/nan0web/ui.git
+		 * cd ui
+		 * npm install
+		 * npm run playground
+		 * ```
+		 */
+		assert.ok(String(pkg.scripts?.playground).includes("node playground"))
+		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"))
+	})
+
+	/**
+	 * @docs
+	 * ## API Documentation
+	 *
+	 * Detailed API docs are available in each class JSDoc.
+	 * Explore:
+	 *
+	 * - [Messages](./src/core/Message/)
+	 * - [Forms](./src/core/Form/)
+	 * - [Stream](./src/core/Stream.js)
+	 * - [Components](./src/Component/)
+	 * - [View](./src/View/)
+	 * - [App](./src/App/)
+	 * - [Models](./src/Model/)
+	 *
+	 * ## Contributing
+	 */
+	it("How to contribute? - [check here](./CONTRIBUTING.md)", async () => {
+		assert.equal(pkg.scripts?.precommit, "npm test")
+		assert.equal(pkg.scripts?.prepush, "npm test")
+		assert.equal(pkg.scripts?.prepare, "husky")
+		const text = await fs.loadDocument("CONTRIBUTING.md")
+		const str = String(text)
+		assert.ok(str.includes("# Contributing"))
+	})
+
+	/**
+	 * @docs
+	 * ## License
+	 */
+	it("How to license ISC? - [check here](./LICENSE)", async () => {
+		/** @docs */
+		const text = await fs.loadDocument("LICENSE")
+		assert.ok(String(text).includes("ISC"))
+	})
+}
+
+describe("README.md testing", testRender)
+
+describe("Rendering README.md", async () => {
+	let text = ""
+	const format = new Intl.NumberFormat("en-US").format
+	const parser = new DocsParser()
+	text = String(parser.decode(testRender))
+	await fs.saveDocument("README.md", text)
+	const dataset = DatasetParser.parse(text, pkg.name)
+	await fs.saveDocument(".datasets/README.dataset.jsonl", dataset)
+
+	it(`document is rendered in README.md [${format(Buffer.byteLength(text))}b]`, async () => {
+		const text = await fs.loadDocument("README.md")
+		assert.ok(text.includes("## License"))
+	})
+})

package/src/StdIn.js

@@ -0,0 +1,111 @@
+import EventProcessor from "@nan0web/event/oop"
+import { CommandMessage } from "@nan0web/co"
+import { typeOf } from "@nan0web/types"
+import InputMessage from "./core/Message/InputMessage.js"
+
+class Processor extends EventProcessor { }
+
+/**
+ * Handles standard input stream with message buffering.
+ */
+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 */
+	stream = []
+
+	/** @type {Processor} Input processor */
+	processor
+
+	/**
+	 * Creates a new StdIn instance.
+	 * @param {object} props - StdIn properties
+	 * @param {Processor} [props.processor] - Input processor
+	 * @param {InputMessage[]} [props.stream=[]] - Initial input stream
+	 */
+	constructor(props = {}) {
+		super()
+		const {
+			processor = new Processor(),
+			stream = [],
+		} = props
+		this.processor = processor
+		this.stream = stream
+		this.processor?.on("data", (data) => {
+			this.write(data)
+		})
+	}
+
+	/**
+	 * Checks if there are messages waiting in the input stream.
+	 * @returns {boolean} True if waiting messages, false otherwise
+	 */
+	get waiting() {
+		return this.stream.length > 0
+	}
+
+	/**
+	 * Checks if the input stream has ended (no messages left).
+	 * @returns {boolean} True if no messages left, false otherwise
+	 */
+	get ended() {
+		return 0 === this.stream.length
+	}
+
+	/**
+	 * Reads a message from the input stream.
+	 * Waits until messages are available if stream is empty.
+	 * @returns {Promise<InputMessage>} Next input message
+	 */
+	async read() {
+		while (this.ended) {
+			await new Promise(resolve => setTimeout(resolve, StdIn.READ_INTERVAL))
+		}
+		return this.stream.shift() ?? new InputMessage()
+	}
+
+	/**
+	 * Writes a message to the input stream.
+	 * @param {string} message - Message to write
+	 * @returns {boolean} True if message accepted, False if ignored
+	 */
+	write(message) {
+		// this.processor?.emit("data", message)
+		const text = String(message)
+		if (StdIn.IGNORE_MESSAGES.includes(text)) {
+			return false
+		}
+		this.stream.push(this.decode(text))
+		return true
+	}
+
+	/**
+	 * Decodes a message into an InputMessage instance.
+	 * @param {InputMessage | string[] | any} message - Message to decode
+	 * @returns {InputMessage} Decoded input message
+	 */
+	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(message)
+	}
+
+	/**
+	 * Creates a StdIn instance from the given input.
+	 * @param {StdIn|object} input - The input to create from
+	 * @returns {StdIn} A StdIn instance
+	 */
+	static from(input) {
+		if (input instanceof StdIn) return input
+		return new this(input)
+	}
+}
+
+export default StdIn

package/src/StdOut.js

@@ -0,0 +1,99 @@
+import { typeOf } from "@nan0web/types"
+import EventProcessor from "@nan0web/event/oop"
+
+/**
+ * Handles standard output stream with formatting capabilities.
+ */
+class StdOut extends EventProcessor {
+	/** @type {string} End of line character */
+	static EOL = "\n"
+
+	/** @type {string} Beginning of line character */
+	static BOL = "\r"
+
+	/** @type {string} Reset formatting escape code */
+	static RESET = "\x1b[0m"
+
+	/** @type {string} Clear screen escape code */
+	static CLEAR = "\x1b[2J\x1b[H"
+
+	/** @type {object} Color escape codes */
+	static COLORS = {
+		red: "\x1b[31m",
+		green: "\x1b[32m",
+		yellow: "\x1b[33m",
+		blue: "\x1b[34m",
+		magenta: "\x1b[35m",
+		cyan: "\x1b[36m",
+		white: "\x1b[37m",
+		gray: "\x1b[90m",
+		black: "\x1b[30m",
+	}
+
+	/** @type {Record<string, string>} Style escape codes */
+	static STYLES = {
+		dim: "\x1b[2m",
+		bold: "\x1b[1m",
+		underline: "\x1b[4m",
+	}
+
+	/**
+	 * @todo define go top by rows constants.
+	 */
+
+	/** @type {string[]} Output stream buffer */
+	stream = []
+
+	/** @type {number[]} Window size [width, height] */
+	windowSize = []
+
+	/** @type {any} Output processor */
+	processor
+
+	/**
+	 * Creates a new StdOut instance.
+	 * @param {object} props - StdOut properties
+	 * @param {any} [props.processor] - Output processor
+	 * @param {string[]} [props.stream=[]] - Initial output stream
+	 * @param {number[]} [props.windowSize=[144, 33]] - Window size [width, height]
+	 */
+	constructor(props = {}) {
+		super()
+		const {
+			processor,
+			stream = [],
+			windowSize = [144, 33],
+		} = props
+		this.processor = processor
+		this.stream = stream
+		this.windowSize = windowSize
+	}
+
+	/**
+	 * Writes output to the output stream.
+	 * Must be overwritten by other apps.
+	 * @param {any} output - Output to write
+	 * @param {Function} onError - Error handler callback
+	 */
+	write(output, onError = v => 1) {
+			/**
+		 * @todo manage the
+		 */
+		if (typeOf(Array)(output)) {
+			output = output.join("\n")
+		}
+		this.stream.push(output)
+		this.processor?.write(output, onError)
+		this.emit("data", output)
+	}
+
+	/**
+	 * Gets the window size.
+	 * @returns {number[]} Window size [width, height]
+	 */
+	getWindowSize() {
+		return this.processor?.getWindowSize?.() ?? this.windowSize
+	}
+}
+
+export default StdOut

package/src/View/RenderOptions.js

@@ -0,0 +1,48 @@
+import Frame from "../Frame/Frame.js"
+
+class RenderOptions {
+	static DEFAULTS = {
+		resizeToView: false,
+		translateFrame: false,
+		render: true,
+		renderMethod: Frame.RenderMethod.VISIBLE,
+	}
+	/** @type {boolean} [false] */
+	resizeToView
+	/** @type {boolean} [false] */
+	translateFrame
+	/** @type {boolean} [true] */
+	render
+	/** @type {string} */
+	renderMethod
+	/** @type {number} */
+	width
+	/** @type {number} */
+	height
+	constructor(props = {}) {
+		const DEFAULTS = this.DEFAULTS
+		const {
+			resizeToView = DEFAULTS.resizeToView,
+			translateFrame = DEFAULTS.translateFrame,
+			render = DEFAULTS.render,
+			renderMethod = DEFAULTS.renderMethod,
+			width = 0,
+			height = 0,
+		} = props
+		this.resizeToView = resizeToView
+		this.translateFrame = translateFrame
+		this.render = render
+		this.renderMethod = renderMethod
+		this.width = width
+		this.height = height
+	}
+	get DEFAULTS() {
+		return /** @type {typeof RenderOptions} */ (this.constructor).DEFAULTS
+	}
+	static from(props = {}) {
+		if (props instanceof RenderOptions) return props
+		return new this(props)
+	}
+}
+
+export default RenderOptions