@nan0web/ui 1.3.0 → 1.6.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**
@@ -172,6 +174,64 @@ import { Welcome } from '@nan0web/ui'
 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 (UK/EN) for global developers.
+- **Theme Editor** — Bootstrap-like CSS variable system with live preview.
+
+It follows the **Olmui** core pattern: *One Logic — Many UI* (same manifest powers both CLI and Web).
+
+#### Theme Editor (CSS Variables)
+
+Professional-grade theming with live preview. Supports:
+
+- **Palette**: primary, secondary, success, warning, danger, info
+- **Geometry**: border-radius (sm/md/lg/pill/circle), spacing (sm/md/lg)
+- **Type-safe inputs**: `type="color"` for colors, number inputs for dimensions
+
+#### Component Rendering Architecture
+
+The IDE handles data transformation between YAML models and web components:
+
+- **Table**: `rows[][] + columns[]` → `data[]` (array of objects)
+- **Tree**: `data` → `items` mapping with 4-level taxonomy
+- **Markdown**: Raw markdown → HTML via `_md2html()` converter
+- **ProgressBar**: Tag alias (`ui-progress-bar` → `ui-progress`), variant colors
+- **LangSelect**: `string[]` → `{code,title}[]` conversion
+- **Hyphenated props**: Auto `camelCase` conversion (`show-label` → `showLabel`)
+
+#### NaN0 Spec (YAML)
+
+Concise format for defining variations:
+
+How to define a component variation using NaN0 Spec?
+```yaml
+- Button: Primary
+  $variant: brand
+  $outline: true
+```
+
+#### Documentation Site
+
+The IDE includes an auto-generated documentation site.
+HTML pages are generated from `ide.html` template via `generate-pages.js`:
+
+- Per-language pages (`/uk/Data/Table.html`, `/en/Feedback/Alert.html`)
+- SEO-optimized with `<title>` and `<meta>` per component
+- Category-based URL routing (`/Data/`, `/Feedback/`, `/Forms/`, `/Actions/`, `/System/`)
+- i18n navbar with `data-i18n` attributes
+
+How to run the documentation site?
+```bash
+npm run docs:dev
+```
+
 ## Playground Demos
 
 The library includes rich playground demos:
@@ -205,6 +265,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.3.0",
+	"version": "1.6.2",
 	"description": "NaN•Web UI. One application logic (algorithm) and many UI.",
 	"main": "src/index.js",
 	"types": "types/index.d.ts",
@@ -18,17 +18,22 @@
 		"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 && npm run knip",
+		"test:e2e": "playwright test --ignore-snapshots e2e/components.spec.js e2e/debug-label.spec.js",
+		"test:e2e:slow": "E2E_SLOW=1 playwright test e2e/visual.spec.js",
+		"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": {
 		".": {
@@ -55,21 +60,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/log": "1.1.1",
-		"@nan0web/types": "^1.2.0",
+		"@nan0web/co": "*",
+		"@nan0web/event": "*",
+		"@nan0web/log": "*",
+		"@nan0web/types": "*",
 		"string-width": "^7.2.0"
 	}
 }

package/src/ArchitectureMap/ArchitectureMap.js

@@ -0,0 +1,111 @@
+/**
+ * ArchitectureMap — a cross-package component readiness registry.
+ *
+ * Tracks which UI components are implemented in which packages
+ * (ui-lit, ui-cli, ui-react-bootstrap, etc.) and provides
+ * a programmatic readiness matrix.
+ *
+ * @example
+ * const map = new ArchitectureMap()
+ * map.register('ui-lit', ['Button', 'Input', 'Select'])
+ * map.register('ui-cli', ['Button', 'Input'])
+ * map.getMatrix()
+ * // → { Button: { 'ui-lit': true, 'ui-cli': true },
+ * //     Input:  { 'ui-lit': true, 'ui-cli': true },
+ * //     Select: { 'ui-lit': true, 'ui-cli': false } }
+ * map.getReadiness('Button') // → true  (in all packages)
+ * map.getReadiness('Select') // → false (missing from ui-cli)
+ */
+export default class ArchitectureMap {
+	/** @type {Map<string, Set<string>>} packageName → Set of component names */
+	#packages = new Map()
+
+	/** @type {Set<string>} all known component names */
+	#components = new Set()
+
+	/**
+	 * Register a package and its exported components.
+	 *
+	 * @param {string} packageName — e.g. 'ui-lit', 'ui-cli', 'ui-react-bootstrap'
+	 * @param {string[]} componentsList — e.g. ['Button', 'Input', 'Select']
+	 */
+	register(packageName, componentsList = []) {
+		this.#packages.set(packageName, new Set(componentsList))
+		for (const name of componentsList) {
+			this.#components.add(name)
+		}
+	}
+
+	/**
+	 * Get the list of all registered package names.
+	 *
+	 * @returns {string[]}
+	 */
+	getPackages() {
+		return [...this.#packages.keys()]
+	}
+
+	/**
+	 * Get all known component names (union of all packages).
+	 *
+	 * @returns {string[]}
+	 */
+	getComponents() {
+		return [...this.#components].sort()
+	}
+
+	/**
+	 * Build a readiness matrix: { componentName → { packageName → boolean } }.
+	 *
+	 * Every known component gets an entry for every registered package.
+	 *
+	 * @returns {Object<string, Object<string, boolean>>}
+	 */
+	getMatrix() {
+		const packages = this.getPackages()
+		/** @type {Object<string, Object<string, boolean>>} */
+		const matrix = {}
+
+		for (const comp of this.#components) {
+			matrix[comp] = {}
+			for (const pkg of packages) {
+				matrix[comp][pkg] = this.#packages.get(pkg)?.has(comp) ?? false
+			}
+		}
+
+		return matrix
+	}
+
+	/**
+	 * Check if a component is implemented in ALL registered packages.
+	 *
+	 * @param {string} componentName
+	 * @returns {boolean}
+	 */
+	getReadiness(componentName) {
+		if (this.#packages.size === 0) return false
+		for (const components of this.#packages.values()) {
+			if (!components.has(componentName)) return false
+		}
+		return true
+	}
+
+	/**
+	 * Get a summary: { total, ready, notReady, readyPercent }.
+	 *
+	 * @returns {{ total: number, ready: number, notReady: number, readyPercent: number }}
+	 */
+	getSummary() {
+		const components = this.getComponents()
+		const total = components.length
+		const ready = components.filter((c) => this.getReadiness(c)).length
+		return {
+			total,
+			ready,
+			notReady: total - ready,
+			readyPercent: total > 0 ? Math.round((ready / total) * 100) : 0,
+		}
+	}
+}
+
+export { ArchitectureMap }

package/src/ArchitectureMap/index.js

@@ -0,0 +1 @@
+export { default, ArchitectureMap } from './ArchitectureMap.js'

package/src/InterfaceTemplate/InterfaceTemplate.js

@@ -0,0 +1,95 @@
+/**
+ * InterfaceTemplate — base class for defining new UI interfaces.
+ *
+ * Establishes the inheritance pattern for the "One Logic, Many UI" architecture.
+ * Each UI interface (CLI, Web, Mobile, Chat, Audio) extends this template
+ * and overrides the required methods.
+ *
+ * @example
+ * class CliInterface extends InterfaceTemplate {
+ *   render(data) { return formatForTerminal(data) }
+ *   async ask(prompt) { return readlinePrompt(prompt) }
+ * }
+ *
+ * @abstract
+ */
+export default class InterfaceTemplate {
+	/**
+	 * List of methods that MUST be overridden by concrete implementations.
+	 * Used for documentation and runtime validation.
+	 *
+	 * @type {string[]}
+	 */
+	static requiredMethods = ['render', 'ask']
+
+	/**
+	 * The name of this interface (e.g. 'cli', 'web', 'mobile').
+	 * Override in subclass.
+	 *
+	 * @type {string}
+	 */
+	name = 'base'
+
+	/**
+	 * Render data to the user through the interface.
+	 * Must be overridden by each concrete implementation.
+	 *
+	 * @param {any} [data] - data to render
+	 * @returns {any} rendered output (string for CLI, DOM for web, etc.)
+	 * @throws {Error} if not overridden
+	 */
+	render(data) {
+		throw new Error(
+			`InterfaceTemplate.render() must be overridden by ${this.name || 'subclass'}. ` +
+				'This is the primary output method for the interface.',
+		)
+	}
+
+	/**
+	 * Request input from the user through the interface.
+	 * Must be overridden by each concrete implementation.
+	 *
+	 * @param {string} prompt - question or label for the input
+	 * @param {object} [options] - options (type, choices, default, etc.)
+	 * @returns {Promise<any>} user's response
+	 * @throws {Error} if not overridden
+	 */
+	async ask(prompt, options = {}) {
+		throw new Error(
+			`InterfaceTemplate.ask() must be overridden by ${this.name || 'subclass'}. ` +
+				'This is the primary input method for the interface.',
+		)
+	}
+
+	/**
+	 * Validate that all required methods have been overridden.
+	 * Call this in the subclass constructor to get early feedback.
+	 *
+	 * @returns {string[]} list of missing method overrides (empty = valid)
+	 */
+	validate() {
+		const missing = []
+		for (const method of InterfaceTemplate.requiredMethods) {
+			if (this[method] === InterfaceTemplate.prototype[method]) {
+				missing.push(method)
+			}
+		}
+		return missing
+	}
+
+	/**
+	 * Get interface capabilities info.
+	 *
+	 * @returns {{ name: string, requiredMethods: string[], isComplete: boolean }}
+	 */
+	info() {
+		const missing = this.validate()
+		return {
+			name: this.name,
+			requiredMethods: [...InterfaceTemplate.requiredMethods],
+			isComplete: missing.length === 0,
+		}
+	}
+}
+
+export { InterfaceTemplate }

package/src/InterfaceTemplate/index.js

@@ -0,0 +1 @@
+export { default, InterfaceTemplate } from './InterfaceTemplate.js'

package/src/README.md.js

@@ -30,6 +30,8 @@ function testRender() {
 	 * @docs
 	 * # @nan0web/ui
 	 *
+	 * 🏴󠁧󠁢󠁥󠁮󠁧󠁿 [English](./README.md) | 🇺🇦 [Українською](./docs/uk/README.md)
+	 *
 	 * <!-- %PACKAGE_STATUS% -->
 	 *
 	 * A lightweight, agnostic UI framework designed with the **nan0web philosophy**
@@ -276,6 +278,76 @@ function testRender() {
 		])
 	})
 
+	/**
+	 * @docs
+	 * ### 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 (UK/EN) for global developers.
+	 * - **Theme Editor** — Bootstrap-like CSS variable system with live preview.
+	 *
+	 * It follows the **Olmui** core pattern: *One Logic — Many UI* (same manifest powers both CLI and Web).
+	 *
+	 * #### Theme Editor (CSS Variables)
+	 *
+	 * Professional-grade theming with live preview. Supports:
+	 *
+	 * - **Palette**: primary, secondary, success, warning, danger, info
+	 * - **Geometry**: border-radius (sm/md/lg/pill/circle), spacing (sm/md/lg)
+	 * - **Type-safe inputs**: `type="color"` for colors, number inputs for dimensions
+	 *
+	 * #### Component Rendering Architecture
+	 *
+	 * The IDE handles data transformation between YAML models and web components:
+	 *
+	 * - **Table**: `rows[][] + columns[]` → `data[]` (array of objects)
+	 * - **Tree**: `data` → `items` mapping with 4-level taxonomy
+	 * - **Markdown**: Raw markdown → HTML via `_md2html()` converter
+	 * - **ProgressBar**: Tag alias (`ui-progress-bar` → `ui-progress`), variant colors
+	 * - **LangSelect**: `string[]` → `{code,title}[]` conversion
+	 * - **Hyphenated props**: Auto `camelCase` conversion (`show-label` → `showLabel`)
+	 *
+	 * #### NaN0 Spec (YAML)
+	 *
+	 * Concise format for defining variations:
+	 */
+	it('How to define a component variation using NaN0 Spec?', () => {
+		/**
+		 * ```yaml
+		 * - Button: Primary
+		 *   $variant: brand
+		 *   $outline: true
+		 * ```
+		 */
+		assert.ok(pkg.name === '@nan0web/ui')
+	})
+
+	/**
+	 * @docs
+	 * #### Documentation Site
+	 *
+	 * The IDE includes an auto-generated documentation site.
+	 * HTML pages are generated from `ide.html` template via `generate-pages.js`:
+	 *
+	 * - Per-language pages (`/uk/Data/Table.html`, `/en/Feedback/Alert.html`)
+	 * - SEO-optimized with `<title>` and `<meta>` per component
+	 * - Category-based URL routing (`/Data/`, `/Feedback/`, `/Forms/`, `/Actions/`, `/System/`)
+	 * - i18n navbar with `data-i18n` attributes
+	 */
+	it('How to run the documentation site?', () => {
+		/**
+		 * ```bash
+		 * npm run docs:dev
+		 * ```
+		 */
+		assert.ok(pkg.scripts?.['docs:dev'])
+	})
+
 	/**
 	 * @docs
 	 * ## Playground Demos
@@ -320,6 +392,10 @@ function testRender() {
 	 * - [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
 	 */
 	it('How to contribute? - [check here](./CONTRIBUTING.md)', async () => {

package/types/ArchitectureMap/ArchitectureMap.d.ts

@@ -0,0 +1,70 @@
+/**
+ * ArchitectureMap — a cross-package component readiness registry.
+ *
+ * Tracks which UI components are implemented in which packages
+ * (ui-lit, ui-cli, ui-react-bootstrap, etc.) and provides
+ * a programmatic readiness matrix.
+ *
+ * @example
+ * const map = new ArchitectureMap()
+ * map.register('ui-lit', ['Button', 'Input', 'Select'])
+ * map.register('ui-cli', ['Button', 'Input'])
+ * map.getMatrix()
+ * // → { Button: { 'ui-lit': true, 'ui-cli': true },
+ * //     Input:  { 'ui-lit': true, 'ui-cli': true },
+ * //     Select: { 'ui-lit': true, 'ui-cli': false } }
+ * map.getReadiness('Button') // → true  (in all packages)
+ * map.getReadiness('Select') // → false (missing from ui-cli)
+ */
+export default class ArchitectureMap {
+    /**
+     * Register a package and its exported components.
+     *
+     * @param {string} packageName — e.g. 'ui-lit', 'ui-cli', 'ui-react-bootstrap'
+     * @param {string[]} componentsList — e.g. ['Button', 'Input', 'Select']
+     */
+    register(packageName: string, componentsList?: string[]): void;
+    /**
+     * Get the list of all registered package names.
+     *
+     * @returns {string[]}
+     */
+    getPackages(): string[];
+    /**
+     * Get all known component names (union of all packages).
+     *
+     * @returns {string[]}
+     */
+    getComponents(): string[];
+    /**
+     * Build a readiness matrix: { componentName → { packageName → boolean } }.
+     *
+     * Every known component gets an entry for every registered package.
+     *
+     * @returns {Object<string, Object<string, boolean>>}
+     */
+    getMatrix(): {
+        [x: string]: {
+            [x: string]: boolean;
+        };
+    };
+    /**
+     * Check if a component is implemented in ALL registered packages.
+     *
+     * @param {string} componentName
+     * @returns {boolean}
+     */
+    getReadiness(componentName: string): boolean;
+    /**
+     * Get a summary: { total, ready, notReady, readyPercent }.
+     *
+     * @returns {{ total: number, ready: number, notReady: number, readyPercent: number }}
+     */
+    getSummary(): {
+        total: number;
+        ready: number;
+        notReady: number;
+        readyPercent: number;
+    };
+    #private;
+}

package/types/ArchitectureMap/index.d.ts

@@ -0,0 +1 @@
+export { default, ArchitectureMap } from "./ArchitectureMap.js";

package/types/InterfaceTemplate/InterfaceTemplate.d.ts

@@ -0,0 +1,67 @@
+/**
+ * InterfaceTemplate — base class for defining new UI interfaces.
+ *
+ * Establishes the inheritance pattern for the "One Logic, Many UI" architecture.
+ * Each UI interface (CLI, Web, Mobile, Chat, Audio) extends this template
+ * and overrides the required methods.
+ *
+ * @example
+ * class CliInterface extends InterfaceTemplate {
+ *   render(data) { return formatForTerminal(data) }
+ *   async ask(prompt) { return readlinePrompt(prompt) }
+ * }
+ *
+ * @abstract
+ */
+export default class InterfaceTemplate {
+    /**
+     * List of methods that MUST be overridden by concrete implementations.
+     * Used for documentation and runtime validation.
+     *
+     * @type {string[]}
+     */
+    static requiredMethods: string[];
+    /**
+     * The name of this interface (e.g. 'cli', 'web', 'mobile').
+     * Override in subclass.
+     *
+     * @type {string}
+     */
+    name: string;
+    /**
+     * Render data to the user through the interface.
+     * Must be overridden by each concrete implementation.
+     *
+     * @param {any} [data] - data to render
+     * @returns {any} rendered output (string for CLI, DOM for web, etc.)
+     * @throws {Error} if not overridden
+     */
+    render(data?: any): any;
+    /**
+     * Request input from the user through the interface.
+     * Must be overridden by each concrete implementation.
+     *
+     * @param {string} prompt - question or label for the input
+     * @param {object} [options] - options (type, choices, default, etc.)
+     * @returns {Promise<any>} user's response
+     * @throws {Error} if not overridden
+     */
+    ask(prompt: string, options?: object): Promise<any>;
+    /**
+     * Validate that all required methods have been overridden.
+     * Call this in the subclass constructor to get early feedback.
+     *
+     * @returns {string[]} list of missing method overrides (empty = valid)
+     */
+    validate(): string[];
+    /**
+     * Get interface capabilities info.
+     *
+     * @returns {{ name: string, requiredMethods: string[], isComplete: boolean }}
+     */
+    info(): {
+        name: string;
+        requiredMethods: string[];
+        isComplete: boolean;
+    };
+}

package/types/InterfaceTemplate/index.d.ts

@@ -0,0 +1 @@
+export { default, InterfaceTemplate } from "./InterfaceTemplate.js";