@nan0web/ui 1.12.2 → 1.12.3

package/README.md

@@ -1,373 +1,36 @@
 # @nan0web/ui
 
-🏴󠁧󠁢󠁥󠁮󠁧󠁿 [English](./README.md) | 🇺🇦 [Українською](./docs/uk/README.md)
+Легкий, агностичний UI-фреймворк, розроблений за філософією **nan0web** — одна логіка додатка, багато UI-реалізацій (One Logic — Many UI).
 
-<!-- %PACKAGE_STATUS% -->
+## Documentation / Документація
 
-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:
+- 🏴󠁧󠁢󠁥󠁮󠁧󠁿 [**English Documentation**](./docs/en/README.md)
+- 🇺🇦 [**Українська документація**](./docs/uk/README.md)
 
-- 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.
+## Quick Start / Швидкий старт
 
-## Installation
-
-How to install with npm?
 ```bash
 npm install @nan0web/ui
 ```
 
-How to install with pnpm?
-```bash
-pnpm add @nan0web/ui
-```
-
-How to install with yarn?
-```bash
-yarn add @nan0web/ui
-```
-
-## Concepts & Architecture
-
-### Message Flow
-
-UI communication is built around messages:
-
-- **`UiMessage`** – abstract message base class
-- **`OutputMessage`** – system output (content, error, priority)
-
-Messages are simple, serializable data containers. They help build
-decoupled communication systems between UI components.
-
-How to create input and output messages?
-```js
-import { InputMessage, OutputMessage } from '@nan0web/ui'
-const input = UiMessage.from({ body: 'Hello User' })
-const output = OutputMessage.from({ content: ['Welcome to @nan0web/ui'] })
-console.info(input) // ← Message { body: "Hello User", head: {}, id: "....", type: "" }
-console.info(String(output)) // ← Welcome to @nan0web/ui
-```
-### 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`
-
-How to define and validate a UiForm?
 ```js
-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 { isValid, errors } = form.validate()
-console.info(Object.keys(errors).length) // ← 1
-console.info(errors.email) // ← Invalid email format
-```
-### Components
-
-Components render data as frame-ready output.
-
-- `Welcome` – greets user by name
-- `Process` – shows progress bar and time
+import { Models } from '@nan0web/ui'
+const { HeaderModel } = Models
 
-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!
+const header = new HeaderModel({ title: 'My App' })
+console.log(header.title)
 ```
-### 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
-
-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"
-```
-### Frame Rendering
-
-`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
-```
-### Domain Models (v1.9.0)
-
-v1.9.0 introduces a comprehensive set of domain models for layout and components.
-These models follow the **Model-as-Schema** pattern.
-
-#### Layout Models
-- `HeaderModel` — title, logo, navigation actions
-- `FooterModel` — copyright, version, social links
-- `HeroModel` — prominent call-to-action
-
-#### HTML5 Base Elements
-Fully typed zero-cost support for standard tags: `div`, `span`, `p`, `h1`-`h6`, `a`, `ul`, `table`, etc., plus SVG basics (`svg`, `path`, `rect`). Data must be standard `camelCase`.
-
-#### Component Models
-- `PricingModel` / `PricingSection` — plans with features and prices
-- `FeatureGrid` — grid of feature highlights
-- `ProfileDropdown` — user avatar and settings menu
-- `CommentModel` & `TestimonialModel` — social proof
-- `StatsModel` — data visualizations
-- `TimelineModel` — event history
-
-How to use the new Header and Hero models?
-```js
-import { Model } from '@nan0web/ui'
-const { HeaderModel, HeroModel } = Model
-const header = new HeaderModel({
-	title: 'NaN•Web',
-	logo: '/logo.svg',
-	actions: [{ title: 'Docs', href: '/docs' }],
-})
-const hero = new HeroModel({
-	title: 'One Logic — Many UI',
-	actions: [{ title: 'Get Started', href: '/start' }],
-})
-console.info(header.title) // ← NaN•Web
-console.info(hero.actions[0].title) // ← Get Started
-```
-### Intent Generators (v1.11.0)
-
-From v1.11.0, Intent creators are standard named functions generating
-strict interactions (ask, progress, show, render, result).
-
-- `ask(field, schema)` — requests input from the environment.
-- `progress(message)` — updates a visual loader.
-- `show(message, level, data)` — displays a notification (replaces deprecated `log`).
-- `render(component, props)` — renders a specific component view.
-- `result(data)` — ends the model execution cleanly.
-
-How to use Intent generators? (v1.11.0)
-```js
-import { ask, show, result } from '@nan0web/ui'
-const nameIntent = ask('name', { help: 'Your name' })
-const msgIntent = show('Processing...', 'info')
-const endIntent = result({ ok: true })
-```
-### Testing UI (v1.11.0 Deterministic Testing)
-
-Core unit-tested to ensure stability in different environments.
-With **v1.11.0**, the architecture formally introduces `ScenarioTest` for zero-I/O deterministic testing.
-
-By lifting the asynchronous logic and providing an explicit scenario array, models are evaluated instantly without waiting on user prompt delays.
-
-How to test Model pipelines deterministically?
-```js
-import { ModelAsApp, ask, result, show } from '@nan0web/ui'
-import { ScenarioTest } from '@nan0web/ui/test/ScenarioTest.js'
-const { ModelAsApp, ask, result, show } = await import('./index.js')
-const { ScenarioTest } = await import('./test/ScenarioTest.js')
-class ShoppingCartApp extends ModelAsApp {
-	*run() {
-		const product = yield ask('product', { help: 'Select product' })
-		if (product?.value === 'laptop') {
-			yield show('Good choice!', 'ok')
-		}
-		const confirm = yield ask('confirm', { help: 'Confirm purchase?' })
-		return result({ product: product?.value, confirm: confirm?.value })
-	}
-}
-const res = await ScenarioTest.run(ShoppingCartApp, [
-	{ field: 'product', value: 'laptop' },
-	{ field: 'confirm', value: true }
-])
-```
-You can also verify exceptions and validation rules by observing the final error in ScenarioTest.
-
-How to test validation errors with ScenarioTest?
-```js
-import { ModelAsApp, ask, result } from '@nan0web/ui'
-import { ScenarioTest } from '@nan0web/ui/test/ScenarioTest.js'
-const { ModelAsApp, ask, result } = await import('./index.js')
-const { ScenarioTest } = await import('./test/ScenarioTest.js')
-class ValidatedApp extends ModelAsApp {
-	*run() {
-		const code = yield ask('code', { help: 'Enter code', required: true })
-		if (!code?.value) throw new Error('Code is mandatory')
-		return result({ code: code?.value })
-	}
-}
-const res = await ScenarioTest.run(ValidatedApp, [
-	{ field: 'code', value: '' } // Simulating empty response
-])
-```
-### Story Testing (.nan0 spec files)
-
-The `SpecRunner.executeFile` helper allows running `.nan0` spec stories automatically without boilerplate DBFS setup.
-All manual assertions are omitted because `SpecAdapter` handles strict expectation matching internally.
-
-How to execute .nan0 spec files automatically?
-```js
-import { SpecRunner } from '@nan0web/ui/testing'
-const { SpecRunner } = await import('./testing/index.js')
-```
-All components, adapters, and models are designed to be testable
-with minimal setup.
-
-How to test visual UI components with assertions?
-```js
-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:
-
-- [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:
-
-How to run the playground?
-```bash
-# Clone repository and run playground
-git clone https://github.com/nan0web/ui.git
-cd ui
-npm install
-npm run play
-```
-
-## 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/)
-
-## 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)
+## Resources / Ресурси
 
-## License
+- 🏴󠁧󠁢󠁥󠁮󠁧󠁿 [Project Architecture (`project.md`)](./docs/en/project.md)
+- 🇺🇦 [Архітектура проєкту (`project.md`)](./docs/uk/project.md)
+- [Contributing](./CONTRIBUTING.md)
+- [License (ISC)](./LICENSE)
 
-How to license ISC? - [check here](./LICENSE)
+---
+© 2026 nan0web

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nan0web/ui",
-  "version": "1.12.2",
+  "version": "1.12.3",
   "description": "NaN•Web UI. One application logic (algorithm) and many UI.",
   "main": "src/index.js",
   "types": "types/index.d.ts",
@@ -8,7 +8,7 @@
   "files": [
     "src/**/*.js",
     "!src/**/*.test.js",
-    "!src/README.md.js",
+    "!src/docs/**/*.md.js",
     "types/**/*.d.ts"
   ],
   "exports": {
@@ -32,6 +32,10 @@
       "import": "./src/domain/index.js",
       "types": "./types/domain/index.d.ts"
     },
+    "./models": {
+      "import": "./src/Model/index.js",
+      "types": "./types/Model/index.d.ts"
+    },
     "./inspect": {
       "import": "./src/inspect.js",
       "types": "./types/inspect.d.ts"
@@ -67,6 +71,7 @@
   "devDependencies": {
     "@playwright/test": "^1.58.2",
     "@rollup/plugin-yaml": "^4.1.2",
+    "@types/node": "^25.6.0",
     "@vitest/coverage-v8": "^3.2.4",
     "husky": "^9.1.7",
     "js-yaml": "^4.1.1",
@@ -77,20 +82,20 @@
     "@nan0web/db-fs": "1.2.2",
     "@nan0web/event": "1.0.1",
     "@nan0web/i18n": "1.5.0",
+    "@nan0web/icons": "1.1.0",
     "@nan0web/inspect": "1.0.0",
     "@nan0web/test": "1.1.4",
-    "@nan0web/ui-cli": "2.13.1",
+    "@nan0web/ui-cli": "2.14.0",
     "@nan0web/release": "1.0.3",
-    "@nan0web/icons": "1.1.0",
-    "@nan0web/ui-lit": "1.1.0",
-    "@nan0web/nan0web.app": "0.1.0"
+    "@nan0web/nan0web.app": "0.1.0",
+    "@nan0web/ui-lit": "1.1.0"
   },
   "dependencies": {
     "string-width": "^7.2.0",
     "@nan0web/co": "2.0.1",
     "@nan0web/core": "1.1.3",
-    "@nan0web/types": "1.7.3",
-    "@nan0web/log": "1.1.1"
+    "@nan0web/log": "1.1.1",
+    "@nan0web/types": "1.7.6"
   },
   "scripts": {
     "prebuild": "rm -rf types/",
@@ -101,7 +106,7 @@
     "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",
+    "test:docs": "node --test --test-timeout=3333 'src/docs/**/*.md.js'",
     "release:spec": "node --test \"src/test/releases/**/*.test.js\"",
     "test:release": "node --test \"src/test/releases/**/*.test.js\"",
     "test:status": "nan0test status --hide-name",

package/src/Model/index.js

@@ -58,7 +58,7 @@ export {
 	ProfileDropdownModel,
 }
 
-const Model = {
+const Models = {
 	User,
 	HeaderModel,
 	FooterModel,
@@ -88,4 +88,4 @@ const Model = {
 	ProfileDropdownModel,
 }
 
-export default Model
+export default Models

package/src/core/resolvePositionalArgs.js

@@ -0,0 +1,51 @@
+import { Model, getMetadata } from '@nan0web/types'
+
+/**
+ * Resolves positional CLI arguments into named model fields.
+ *
+ * Scans a Model class for `static` field descriptors with `positional: true`.
+ * The order of positional fields follows the declaration order of static properties
+ * (guaranteed by JavaScript spec for non-integer keys).
+ *
+ * @example
+ * class MyModel {
+ *   static source = { help: 'Source path', default: '.', positional: true }
+ *   static target = { help: 'Target path', default: 'out', positional: true }
+ *   static quiet  = { help: 'Quiet mode', default: false, type: 'boolean' }
+ * }
+ *
+ * const data = resolvePositionalArgs(MyModel, ['src/', 'dist/'])
+ * // → { source: 'src/', target: 'dist/' }
+ *
+ * @param {typeof Model} ModelClass - The Model class with static field descriptors.
+ * @param {string[]} args - Positional arguments from the CLI (e.g., process.argv positionals).
+ * @param {Object} [existing={}] - Existing named options (take priority over positionals).
+ * @returns {Object} Merged data object with positional args resolved to named fields.
+ */
+export function resolvePositionalArgs(ModelClass, args = [], existing = {}) {
+	if (!args || !args.length) return { ...existing }
+
+	const metadata = getMetadata(ModelClass)
+	const positionalFields = []
+	for (const [key, descriptor] of Object.entries(metadata)) {
+		if (descriptor && typeof descriptor === 'object' && descriptor.positional === true) {
+			positionalFields.push(key)
+		}
+	}
+
+	const result = { ...existing }
+	for (let i = 0; i < positionalFields.length && i < args.length; i++) {
+		const field = positionalFields[i]
+		// Named options take priority over positionals
+		if (result[field] === undefined || result[field] === null) {
+			result[field] = args[i]
+		}
+	}
+
+	// Preserve remaining positional arguments for subcommands
+	if (args.length > positionalFields.length) {
+		result._positionals = args.slice(positionalFields.length)
+	}
+
+	return result
+}

package/src/domain/Content.js

@@ -1,6 +1,6 @@
 import { Model } from '@nan0web/types'
 
-/** 
+/**
  * @typedef {Object} HTML5Elements
  * @property {string|ContentData[]} [a]
  * @property {string|ContentData[]} [abbr]
@@ -126,7 +126,7 @@ import { Model } from '@nan0web/types'
  * @property {string|ContentData[]} [text]
  */
 
-/** 
+/**
  * @typedef {Object} CoreUIElements
  * @property {import('./components/AccordionModel.js').AccordionModel} [accordion]
  * @property {import('./components/AutocompleteModel.js').AutocompleteModel} [autocomplete]
@@ -162,8 +162,8 @@ import { Model } from '@nan0web/types'
  * @property {ContentData[]} [sortable] - Інтерактивний Drag-n-Drop контейнер
  */
 
-/** 
- * @typedef {Partial<Content & HTML5Elements & CoreUIElements> & Record<string, any>} ContentData 
+/**
+ * @typedef {Partial<Content & HTML5Elements & CoreUIElements> & Record<string, any>} ContentData
  */
 
 export class Content extends Model {
@@ -172,7 +172,7 @@ export class Content extends Model {
 
 	/**
 	 * @param {ContentData | string} [data={}]
-	 * @param {import('@nan0web/types').ModelOptions} [options={}]
+	 * @param {Partial<import('@nan0web/types').ModelOptions>} [options={}]
 	 */
 	constructor(data = {}, options = {}) {
 		if ('string' === typeof data) {

package/src/domain/Document.js

@@ -12,7 +12,7 @@ export class Document extends Model {
 	/**
 	 *
 	 * @param {Partial<Document>} [data]
-	 * @param {import('@nan0web/types').ModelOptions} [options]
+	 * @param {Partial<import('@nan0web/types').ModelOptions>} [options]
 	 */
 	constructor(data = {}, options = {}) {
 		super(data, options)

package/src/domain/HeroModel.js

@@ -37,7 +37,7 @@ export class HeroModel extends Model {
 
 	/**
 	 * @param {Partial<HeroModel | Record<string, any>>} [data={}]
-	 * @param {import('@nan0web/types').ModelOptions} [options={}]
+	 * @param {Partial<import('@nan0web/types').ModelOptions>} [options={}]
 	 */
 	constructor(data = {}, options = {}) {
 		super(data, options)