@nan0web/ui 1.12.2 → 3.1.0

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": "3.1.0",
   "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"
@@ -52,11 +56,20 @@
   "nan0web": {
     "workflowDir": "docs/{locale}/workflows",
     "workflows": [
-      "olm-ui-architecture.md",
-      "olm-ui-architecture-core.md",
-      "olm-ui-architecture-adapters.md",
+      "architecture.md",
       "forge-component.md",
-      "interface-welding.md"
+      "interface-welding.md",
+      "nan0web-v2-roadmap.md",
+      "nan0web.md",
+      "olm-ui-architecture-adapters.md",
+      "olm-ui-architecture-core.md",
+      "olm-ui-architecture-i18n.md",
+      "olm-ui-architecture-testing.md",
+      "olm-ui-architecture.md",
+      "pipeline-no4-adapter.md",
+      "pipeline-no7-ui-web.md",
+      "pipeline-no8-ui-mobile.md",
+      "ui-update.md"
     ],
     "inspectors": [
       "./src/domain/app/SnapshotAuditor.js"
@@ -67,6 +80,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",
@@ -74,23 +88,23 @@
     "lit": "^3.3.2",
     "vite": "^6.4.1",
     "vitest": "^3.2.4",
-    "@nan0web/db-fs": "1.2.2",
-    "@nan0web/event": "1.0.1",
-    "@nan0web/i18n": "1.5.0",
-    "@nan0web/inspect": "1.0.0",
-    "@nan0web/test": "1.1.4",
-    "@nan0web/ui-cli": "2.13.1",
-    "@nan0web/release": "1.0.3",
-    "@nan0web/icons": "1.1.0",
-    "@nan0web/ui-lit": "1.1.0",
-    "@nan0web/nan0web.app": "0.1.0"
+    "@nan0web/db-fs": "3.1.0",
+    "@nan0web/i18n": "3.1.0",
+    "@nan0web/icons": "3.1.0",
+    "@nan0web/inspect": "3.1.0",
+    "@nan0web/test": "3.1.0",
+    "@nan0web/ui-lit": "3.1.0",
+    "@nan0web/ui-cli": "3.1.0",
+    "@nan0web/nan0web.app": "3.1.0",
+    "@nan0web/release": "3.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/co": "3.1.0",
+    "@nan0web/core": "3.1.0",
+    "@nan0web/event": "3.1.0",
+    "@nan0web/log": "3.1.0",
+    "@nan0web/types": "3.1.0"
   },
   "scripts": {
     "prebuild": "rm -rf types/",
@@ -101,14 +115,14 @@
     "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",
     "test:play": "node --test --test-timeout=3333 \"play/**/*.test.js\"",
     "test:snapshots": "node src/testing/GalleryGenerator.js",
     "test:gallery": "npm run test:snapshots && npx nan0gallery --dir=snapshots/core",
-    "test:audit": "nan0cli audit --dir snapshots/core --data .",
+    "test:audit": "nan0cli snapshots --dir snapshots/core --data .",
     "test:stories": "node --test \"src/**/*.story.js\"",
     "test:all": "npm run test && npm run test:docs && npm run test:play && npm run test:stories && npm run knip",
     "knip": "knip --production",

package/src/Component/index.js

@@ -1,11 +1,7 @@
-import Welcome from './Welcome/index.js'
-import Process from './Process/index.js'
 import SortableList from './SortableList/index.js'
 
-export { Welcome, Process, SortableList }
+export { SortableList }
 
 export default {
-	Welcome,
-	Process,
 	SortableList,
 }