@nan0web/ui 1.1.0 → 1.5.2

package/README.md

@@ -1,5 +1,7 @@
 # @nan0web/ui
 
+🏴󠁧󠁢󠁥󠁮󠁧󠁿 [English](./README.md) | 🇺🇦 [Українською](./docs/uk/README.md)
+
 <!-- %PACKAGE_STATUS% -->
 
 A lightweight, agnostic UI framework designed with the **nan0web philosophy**
@@ -73,19 +75,24 @@ How to define and validate a UiForm?
 ```js
 import { UiForm } from '@nan0web/ui'
 const form = new UiForm({
-	title: "Contact Form",
+	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 })
+		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!"
-	}
+		email: 'invalid-email',
+		message: 'Hello!',
+	},
 })
 const errors = form.validate()
 console.info(errors.size) // ← 1
-console.info(errors.get("email")) // ← Invalid email format
+console.info(errors.get('email')) // ← Invalid email format
 ```
 ### Components
 
@@ -97,8 +104,8 @@ 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("")
+const frame = Welcome({ user: { name: 'Alice' } })
+const firstLine = frame[0].join('')
 console.info(firstLine) // ← Welcome Alice!
 ```
 ### View Manager
@@ -115,7 +122,7 @@ How to render frame with View?
 ```js
 import { View } from '@nan0web/ui'
 const view = new View()
-view.render(1)(["Hello, world"])
+view.render(1)(['Hello, world'])
 console.info(String(view.frame)) // ← "\rHello, world"
 ```
 ### Frame Rendering
@@ -133,13 +140,13 @@ How to create a Frame with fixed size?
 ```js
 import { Frame } from '@nan0web/ui'
 const frame = new Frame({
-	value: [["Frame content"]],
+	value: [['Frame content']],
 	width: 20,
 	height: 5,
 	renderMethod: Frame.RenderMethod.APPEND,
 })
 const rendered = frame.render()
-console.info(rendered.includes("Frame content")) // ← true
+console.info(rendered.includes('Frame content')) // ← true
 ```
 ### Models
 
@@ -150,7 +157,7 @@ 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" })
+const user = new Model.User({ name: 'Charlie', email: 'charlie@example.com' })
 console.info(user.name) // ← Charlie
 console.info(user.email) // ← charlie@example.com
 ```
@@ -164,9 +171,32 @@ with minimal setup.
 How to test UI components with assertions?
 ```js
 import { Welcome } from '@nan0web/ui'
-const output = Welcome({ user: { name: "Test" } })
+const output = Welcome({ user: { name: 'Test' } })
 console.info(output) // ← Welcome Test!
 ```
+### Master IDE (Component Sandbox)
+
+The Master IDE (OlmuiInspector) provides a unified environment for testing and documenting
+web components across platforms. It supports:
+
+- **NaN0 Spec** — a concise YAML-based shorthand for declaring component variations.
+- **OlmuiInspector** — unified UI for exploring component models and props.
+- **Live Preview** — real-time rendering of component states.
+- **i18n UI** — fully localized interface for global developers.
+
+It follows the **Olmui** core pattern: *One Logic — Many UI* (same manifest powers both CLI and Web).
+
+#### NaN0 Spec (YAML)
+
+Concise format for defining variations:
+
+How to define a component variation using NaN0 Spec?
+```yaml
+- Button: Primary
+  $variant: brand
+  $outline: true
+```
+
 ## Playground Demos
 
 The library includes rich playground demos:
@@ -200,6 +230,10 @@ Explore:
 - [App](./src/App/)
 - [Models](./src/Model/)
 
+## Project Architecture & Specs
+
+How the universal block spec is designed? - [check Universal Blocks Spec (`project.md`)](./project.md)
+
 ## Contributing
 
 How to contribute? - [check here](./CONTRIBUTING.md)

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nan0web/ui",
-	"version": "1.1.0",
+	"version": "1.5.2",
 	"description": "NaN•Web UI. One application logic (algorithm) and many UI.",
 	"main": "src/index.js",
 	"types": "types/index.d.ts",
@@ -18,16 +18,21 @@
 		"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",
+		"release:spec": "node --test \"releases/**/*.spec.js\"",
 		"test:release": "node --test \"releases/**/*.test.js\"",
 		"test:status": "nan0test status --hide-name",
 		"test:play": "node --test --test-timeout=3333 \"play/**/*.test.js\"",
-		"test:all": "npm run test && npm run test:docs && npm run test:play && npm run build",
+		"test:e2e": "playwright test",
+		"test:all": "npm run test && npm run test:docs && npm run test:play && npm run test:e2e && npm run build && npm run knip",
+		"knip": "knip --production",
 		"precommit": "npm test",
 		"prepush": "npm test",
 		"prepare": "husky",
 		"release": "nan0release publish",
 		"clean": "rm -rf .cache/ && rm -rf dist/",
-		"clean:modules": "rm -rf node_modules"
+		"clean:modules": "rm -rf node_modules",
+		"docs:dev": "node docs/site/scripts/generate-pages.js && vite docs/site",
+		"docs:build": "node docs/site/scripts/generate-pages.js && vite build docs/site"
 	},
 	"exports": {
 		".": {
@@ -54,20 +59,27 @@
 	"license": "ISC",
 	"packageManager": "pnpm@10.11.0",
 	"devDependencies": {
-		"@nan0web/event": "^1.0.0",
-		"@nan0web/i18n": "^1.0.1",
-		"@nan0web/release": "1.0.1",
-		"@nan0web/test": "1.1.0",
-		"@nan0web/ui-cli": "1.0.2",
+		"@nan0web/event": "*",
+		"@nan0web/i18n": "*",
+		"@nan0web/release": "*",
+		"@nan0web/test": "*",
+		"@nan0web/ui-cli": "*",
+		"@nan0web/ui-lit": "workspace:*",
+		"@playwright/test": "^1.58.2",
+		"@rollup/plugin-yaml": "^4.1.2",
 		"@vitest/coverage-v8": "^3.2.4",
 		"husky": "^9.1.7",
+		"js-yaml": "^4.1.1",
+		"knip": "^5.83.1",
+		"lit": "^3.3.2",
+		"vite": "^6.0.0",
 		"vitest": "^3.2.4"
 	},
 	"dependencies": {
-		"@nan0web/co": "^2.0.0",
-		"@nan0web/event": "^1.0.0",
-		"@nan0web/types": "^1.2.0",
+		"@nan0web/co": "*",
+		"@nan0web/event": "*",
+		"@nan0web/log": "*",
+		"@nan0web/types": "*",
 		"string-width": "^7.2.0"
-	},
-	"peerDependencies": {}
+	}
 }

package/src/App/Command/DepsCommand.js

@@ -1,15 +1,13 @@
-import UiMessage from "../../core/Message/Message.js"
+import UiMessage from '../../core/Message/Message.js'
 
 class DepsCommandBody {
 	fix = false
 	static fix = {
-		help: "Fix dependencies",
-		defaultValue: false
+		help: 'Fix dependencies',
+		defaultValue: false,
 	}
 	constructor(input = {}) {
-		const {
-			fix = this.fix
-		} = input
+		const { fix = this.fix } = input
 	}
 }
 
@@ -18,9 +16,7 @@ export class DepsCommand extends UiMessage {
 	/** @type {DepsCommandBody} */
 	body
 	constructor(input = {}) {
-		const {
-			body = new DepsCommandBody()
-		} = UiMessage.parseBody(input, DepsCommandBody)
+		const { body = new DepsCommandBody() } = UiMessage.parseBody(input, DepsCommandBody)
 		super(input)
 		this.body = body
 	}

package/src/App/Core/CoreApp.js

@@ -1,6 +1,6 @@
-import { Message } from "@nan0web/co"
-import { typeOf } from "@nan0web/types"
-import UI from "./UI.js"
+import { Message } from '@nan0web/co'
+import { typeOf } from '@nan0web/types'
+import UI from './UI.js'
 
 /** @typedef {Function} CommandFn */
 
@@ -29,11 +29,7 @@ export default class CoreApp {
 	 * @param {Message} [props.startCommand=new Message()] - Command line arguments to parse
 	 */
 	constructor(props = {}) {
-		const {
-			name = "CoreApp",
-			state = {},
-			startCommand = new Message(),
-		} = props
+		const { name = 'CoreApp', state = {}, startCommand = new Message() } = props
 		this.name = String(name)
 		this.state = state
 		this.commands = new Map()
@@ -48,7 +44,7 @@ export default class CoreApp {
 	 * @returns {object} Updated state
 	 */
 	set(state, value) {
-		if ("string" === typeof state) {
+		if ('string' === typeof state) {
 			this.state[state] = value
 		} else {
 			Object.assign(this.state, state)
@@ -64,7 +60,7 @@ export default class CoreApp {
 	 */
 	registerCommand(commandName, handler) {
 		if (!typeOf(Function)(handler)) {
-			throw new TypeError("Handler must be a function")
+			throw new TypeError('Handler must be a function')
 		}
 		this.commands.set(commandName, handler)
 	}
@@ -87,12 +83,17 @@ export default class CoreApp {
 	async processCommand(msg, ui) {
 		const handler = this.commands.get(msg.constructor.name)
 		if (!handler) {
-			throw new Error([
-				"Unknown command", ": ",
-				msg.constructor.name, "\n",
-				"Available commands", ": ",
-				[...this.commands.keys()].join(", "),
-			].join(""))
+			throw new Error(
+				[
+					'Unknown command',
+					': ',
+					msg.constructor.name,
+					'\n',
+					'Available commands',
+					': ',
+					[...this.commands.keys()].join(', '),
+				].join(''),
+			)
 		}
 		return await handler.apply(this, [msg, ui])
 	}
@@ -119,6 +120,6 @@ export default class CoreApp {
 	 * @throws {Error} Always thrown as this method must be implemented by subclasses
 	 */
 	async selectCommand(ui) {
-		throw new Error("Not implemented, must be implemented by subclass")
+		throw new Error('Not implemented, must be implemented by subclass')
 	}
 }

package/src/App/Core/UI.js

@@ -1,7 +1,7 @@
-import { Message } from "@nan0web/co"
-import View from "../../View/View.js"
-import CoreApp from "./CoreApp.js"
-import Widget from "./Widget.js"
+import { Message } from '@nan0web/co'
+import View from '../../View/View.js'
+import CoreApp from './CoreApp.js'
+import Widget from './Widget.js'
 
 /** @typedef {import("../../View/View.js").ComponentFn} ComponentFn */
 
@@ -31,7 +31,7 @@ export default class UI extends Widget {
 	 * @throws {Error} Always thrown as this method must be implemented by subclasses
 	 */
 	convertInput(rawInput) {
-		throw new Error("convertInput must be implemented by subclass")
+		throw new Error('convertInput must be implemented by subclass')
 	}
 
 	/**
@@ -43,16 +43,12 @@ export default class UI extends Widget {
 		const onStart = () => {
 			// this.view.render(UIProcess)
 		}
-		const onData = () => {
+		const onData = () => {}
+		const onEnd = () => {}
 
-		}
-		const onEnd = () => {
-
-		}
-
-		this.on("start", onStart)
-		this.on("data", onData)
-		this.on("end", onEnd)
+		this.on('start', onStart)
+		this.on('data', onData)
+		this.on('end', onEnd)
 	}
 
 	/**
@@ -60,7 +56,7 @@ export default class UI extends Widget {
 	 * @param {any[]} results - Results to output
 	 */
 	output(results) {
-		results.forEach(result => {
+		results.forEach((result) => {
 			this.view.info(JSON.stringify(result))
 		})
 	}

package/src/App/Core/Widget.js

@@ -1,7 +1,7 @@
-import EventProcessor from "@nan0web/event/oop"
-import View from "../../View/View.js"
-import { StreamEntry } from "@nan0web/db"
-import { UiMessage } from "../../core/index.js"
+import EventProcessor from '@nan0web/event/oop'
+import View from '../../View/View.js'
+import { StreamEntry } from '@nan0web/db'
+import { UiMessage } from '../../core/index.js'
 
 /** @typedef {import("./UI.js").ComponentFn} ComponentFn */
 
@@ -51,14 +51,10 @@ export default class Widget extends EventProcessor {
 	 */
 	render(viewFnOrName, outputData) {
 		/** @type {Function | ComponentFn | undefined} */
-		const viewFn = typeof viewFnOrName === "string"
-			? this.view.get(viewFnOrName)
-			: viewFnOrName
+		const viewFn = typeof viewFnOrName === 'string' ? this.view.get(viewFnOrName) : viewFnOrName
 
 		if (!viewFn) {
-			throw new Error([
-				"View component not found", ": ", viewFnOrName
-			].join(""))
+			throw new Error(['View component not found', ': ', viewFnOrName].join(''))
 		}
 		return this.view.render(viewFn)(outputData)
 	}

package/src/App/Core/index.js

@@ -1,6 +1,6 @@
-import CoreApp from "./CoreApp.js"
-import UI from "./UI.js"
-import Widget from "./Widget.js"
+import CoreApp from './CoreApp.js'
+import UI from './UI.js'
+import Widget from './Widget.js'
 
 export { CoreApp, UI }
 

package/src/App/Scenario.js

@@ -1,5 +1,5 @@
-import App from "./index.js"
-import UI from "./Core/UI.js"
+import App from './index.js'
+import UI from './Core/UI.js'
 
 /** @typedef {import("./Core/CoreApp.js").default} CoreApp */
 
@@ -19,7 +19,7 @@ export default class Scenario {
 	 */
 	constructor(app, ui) {
 		if (!(app instanceof App.Core.App)) {
-			throw new TypeError("Scenario requires a App.Core.App instance")
+			throw new TypeError('Scenario requires a App.Core.App instance')
 		}
 		this.app = app
 		this.ui = ui
@@ -32,7 +32,7 @@ export default class Scenario {
 	 * @returns {Promise<boolean>} True if all outputs match expected
 	 */
 	async run(inputCommands, expectedOutputs) {
-		const commandMessages = inputCommands.map(arr => App.Command.Message.parse(arr))
+		const commandMessages = inputCommands.map((arr) => App.Command.Message.parse(arr))
 		const outputs = await this.app.processCommands(commandMessages, this.ui)
 		if (outputs.length !== expectedOutputs.length) return false
 		for (let i = 0; i < outputs.length; i++) {

package/src/App/User/Command/Message.js

@@ -1,3 +1,3 @@
-import UiMessage from "../../../core/Message/Message.js"
+import UiMessage from '../../../core/Message/Message.js'
 
 export default UiMessage

package/src/App/User/Command/index.js

@@ -1,4 +1,4 @@
-import CommandMessage from "./Message.js"
+import CommandMessage from './Message.js'
 
 export { CommandMessage }
 

package/src/App/User/UserApp.js

@@ -1,12 +1,12 @@
-import { Message } from "@nan0web/co"
-import { notEmpty } from "@nan0web/types"
-import CoreApp from "../Core/CoreApp.js"
-import User from "../../Model/User/User.js"
-import UserUI from "./UserUI.js"
-import UserAppCommandMessage from "./Command/Message.js"
-import DepsCommand from "./Command/Message.js"
-import UIStream from "../../core/Stream.js"
-import { StreamEntry, UiMessage } from "../../core/index.js"
+import { Message } from '@nan0web/co'
+import { notEmpty } from '@nan0web/types'
+import CoreApp from '../Core/CoreApp.js'
+import User from '../../Model/User/User.js'
+import UserUI from './UserUI.js'
+import UserAppCommandMessage from './Command/Message.js'
+import DepsCommand from './Command/Message.js'
+import UIStream from '../../core/Stream.js'
+import { StreamEntry, UiMessage } from '../../core/index.js'
 
 /**
  * UserApp requires user name and shows Welcome view.
@@ -20,9 +20,9 @@ export default class UserApp extends CoreApp {
 	 */
 	constructor(props = {}) {
 		super(props)
-		this.registerCommand("setUser", this.setUser.bind(this))
-		this.registerCommand("welcome", this.welcome.bind(this))
-		this.registerCommand("deps", this.handleDeps.bind(this)) // Register new command
+		this.registerCommand('setUser', this.setUser.bind(this))
+		this.registerCommand('welcome', this.welcome.bind(this))
+		this.registerCommand('deps', this.handleDeps.bind(this)) // Register new command
 	}
 
 	/**
@@ -33,12 +33,18 @@ export default class UserApp extends CoreApp {
 	 */
 	async handleDeps(cmd, ui) {
 		// Example: Use async generator to stream deps processing
-		const processorFn = async () => new StreamEntry({ value: { message: `Deps command executed with fix: ${cmd.body.fix}` }, done: true })
+		const processorFn = async () =>
+			new StreamEntry({
+				value: { message: `Deps command executed with fix: ${cmd.body.fix}` },
+				done: true,
+			})
 		const generatorFn = UIStream.createProcessor(new AbortController().signal, processorFn)
-		await UIStream.process(new AbortController().signal, generatorFn,
+		await UIStream.process(
+			new AbortController().signal,
+			generatorFn,
 			(progress, item) => ui.output && ui.output(item.value), // Fix to output the value
 			(error) => ui.output && ui.output([error]), // Assume ui has output method
-			(item) => ui.output && ui.output(item.value) // Fix complete callback
+			(item) => ui.output && ui.output(item.value), // Fix complete callback
 		)
 		return { completed: true }
 	}
@@ -53,7 +59,7 @@ export default class UserApp extends CoreApp {
 		this.state.user = User.from(cmd.body.user) // cmd is UserAppCommandMessage, has user
 		const frame = await this.welcome(cmd, ui)
 		return {
-			message: String(frame)
+			message: String(frame),
 		}
 	}
 
@@ -64,15 +70,16 @@ export default class UserApp extends CoreApp {
 	 * @returns {Promise<string[][]>} Welcome view output
 	 */
 	async welcome(cmd, ui) {
-		if (cmd.body.user) { // cmd is UserAppCommandMessage, has user
+		if (cmd.body.user) {
+			// cmd is UserAppCommandMessage, has user
 			const user = User.from(cmd.body.user)
-			return ui.render("Welcome", { user })
+			return ui.render('Welcome', { user })
 		}
 		if (notEmpty(this.user)) {
-			return ui.render("Welcome", { user: this.user })
+			return ui.render('Welcome', { user: this.user })
 		}
-		const answer = await ui.ask(UiMessage.from("What is your name?"))
+		const answer = await ui.ask(UiMessage.from('What is your name?'))
 		this.user = User.from(answer?.body)
-		return ui.render("Welcome", { user: this.user })
+		return ui.render('Welcome', { user: this.user })
 	}
 }

package/src/App/User/UserUI.js

@@ -1,5 +1,5 @@
-import { Message } from "@nan0web/co"
-import App from "../Core/index.js"
+import { Message } from '@nan0web/co'
+import App from '../Core/index.js'
 
 /**
  * UserUI connects UserApp and View.

package/src/App/User/index.js

@@ -1,5 +1,5 @@
-import UserApp from "./UserApp.js"
-import UserUI from "./UserUI.js"
+import UserApp from './UserApp.js'
+import UserUI from './UserUI.js'
 
 export { UserApp, UserUI }
 

package/src/App/index.js

@@ -1,15 +1,10 @@
-import Scenario from "./Scenario.js"
-import UI from "./Core/UI.js"
+import Scenario from './Scenario.js'
+import UI from './Core/UI.js'
 
-import Core from "./Core/index.js"
-import User from "./User/index.js"
+import Core from './Core/index.js'
+import User from './User/index.js'
 
-export {
-	Core,
-	User,
-	Scenario,
-	UI,
-}
+export { Core, User, Scenario, UI }
 
 export default {
 	Core,

package/src/Component/Process/Input.js

@@ -5,22 +5,22 @@
 class ProcessInput {
 	/** @type {string} Process name to display */
 	name
-	
+
 	/** @type {number} Current progress index */
 	i
-	
+
 	/** @type {number} Top limit for progress normalization */
 	top
-	
+
 	/** @type {number} Width of the progress bar */
 	width
-	
+
 	/** @type {string} Character to use for empty space */
 	space
-	
+
 	/** @type {string} Character to use for filled progress */
 	char
-	
+
 	/**
 	 * Creates a new ProcessInput instance.
 	 * @param {object} props - Process input properties
@@ -32,14 +32,7 @@ class ProcessInput {
 	 * @param {string} [props.char='*'] - Character for filled progress
 	 */
 	constructor(props = {}) {
-		const {
-			name = "NaN•Coding",
-			i = 0,
-			top = 9,
-			width = 9,
-			space = '•',
-			char = '*'
-		} = props
+		const { name = 'NaN•Coding', i = 0, top = 9, width = 9, space = '•', char = '*' } = props
 		this.name = name
 		this.i = i
 		this.top = top
@@ -47,7 +40,7 @@ class ProcessInput {
 		this.space = space
 		this.char = char
 	}
-	
+
 	/**
 	 * Converts the input to a string representation.
 	 * @returns {string} String representation of the ProcessInput
@@ -55,7 +48,7 @@ class ProcessInput {
 	toString() {
 		return `ProcessInput(name=${this.name}, i=${this.i}, top=${this.top}, width=${this.width}, space=${this.space}, char=${this.char})`
 	}
-	
+
 	/**
 	 * Creates a ProcessInput instance from the given props.
 	 * @param {ProcessInput|object} props - The properties to create from
@@ -67,4 +60,4 @@ class ProcessInput {
 	}
 }
 
-export default ProcessInput
+export default ProcessInput

package/src/Component/Process/Process.js

@@ -1,5 +1,5 @@
-import ProcessInput from "./Input.js"
-import View from "../../View/View.js"
+import ProcessInput from './Input.js'
+import View from '../../View/View.js'
 
 /**
  * Renders a progress bar based on input configuration.
@@ -16,9 +16,7 @@ function Process(props = {}) {
 	// Provide empty options object to satisfy Locale.format signature
 	const format = this.locale.format(Number, {})
 	const num = format ? format(100 * per) : 100 * per
-	return [
-		[`I am ${input.name} ${bar} ${num}`]
-	]
+	return [[`I am ${input.name} ${bar} ${num}`]]
 }
 
 Process.Input = ProcessInput

package/src/Component/Process/index.js

@@ -1,5 +1,5 @@
-import Process from "./Process.js"
-import ProcessInput from "./Input.js"
+import Process from './Process.js'
+import ProcessInput from './Input.js'
 
 export default Process
 export { ProcessInput }