@nan0web/ui 1.5.2 → 1.7.0

package/src/domain/SandboxModel.js

@@ -0,0 +1,193 @@
+import { Model } from '@nan0web/core'
+import * as ComponentModels from './components/index.js'
+import { BreadcrumbModel } from './components/BreadcrumbModel.js'
+
+/**
+ * @typedef {Object} SandboxData
+ * @property {string[]} [components]
+ * @property {string} [selectedComponent]
+ * @property {string} [themeFormat]
+ */
+
+/**
+ * Model-as-Schema for the UI Sandbox environment.
+ * Represents a tool wrapping standard OLMUI components, allowing
+ * users to inspect their models, tweak variables interactively,
+ * and export the configuration as themes for the Marketplace.
+ *
+ * Navigation uses BreadcrumbModel:
+ *   ESC = pop one level (if stack has no parent → exit app)
+ *   Ctrl+C = always exit (handled by prompts.js wrapper)
+ *
+ * URL mapping:
+ *   /sandbox             → Select Component
+ *   /sandbox/button      → Edit Button properties
+ *   /sandbox/button/export → Choose export format
+ */
+export class SandboxModel extends Model {
+	// ==========================================
+	// 1. MODEL AS SCHEMA (Static Definition)
+	// ==========================================
+
+	static components = {
+		help: 'List of registered UI components available for inspection',
+		type: 'string[]',
+		default: []
+	}
+
+	static selectedComponent = {
+		help: 'The specific component chosen by the user for theming',
+		type: 'string',
+	}
+
+	static themeFormat = {
+		help: 'The file format chosen to export the custom theme configuration',
+		options: ['yaml', 'css', 'json'],
+		default: 'yaml'
+	}
+
+	/**
+	 * @param {SandboxData | any} [data]
+	 */
+	constructor(data = {}) {
+		super(data)
+		/** @type {string[]|undefined} */ this.components
+		/** @type {string|undefined} */ this.selectedComponent
+		/** @type {string|undefined} */ this.themeFormat
+	}
+
+	// ==========================================
+	// 2. AGNOSTIC LOGIC (Async Generator)
+	// ==========================================
+
+	async *run() {
+		/** @type {any} */
+		let targetInstance = null
+
+		// ── BreadcrumbModel as navigation stack ──
+		const nav = new BreadcrumbModel()
+		nav.push('🏖 Sandbox', 'sandbox')
+
+		while (true) {
+			// ── Level 1: Select Component ──
+			if (!this.selectedComponent) {
+				// Show breadcrumb
+				yield /** @type {any} */ ({
+					type: 'log', level: 'info',
+					message: `\n${nav}`,
+					component: 'Breadcrumbs',
+					model: /** @type {any} */ (nav),
+				})
+
+				// ESC here = CancelError not caught → bubbles out → app exits
+				const listResponse = yield {
+					type: 'ask',
+					field: 'selectedComponent',
+					schema: {
+						help: 'Select a component to inspect and theme',
+						options: this.components || [],
+						validate: (/** @type {string} */ val) =>
+							(this.components || []).includes(val) || 'Component not found in sandbox registry',
+					},
+					component: 'Select',
+					model: /** @type {any} */ (this),
+				}
+				this.selectedComponent = listResponse.value
+				nav.push(/** @type {string} */ (this.selectedComponent))
+
+				// Instantiate the selected model class
+				const Ctor = ComponentModels[`${this.selectedComponent}Model`]
+				targetInstance = Ctor ? new Ctor() : this
+			}
+
+			// ── Level 2: Edit Component Properties ──
+			// URL: /sandbox/button  Data: data/sandbox/button/index.yaml
+			/** @type {any} */
+			let configResponse
+			try {
+				yield /** @type {any} */ ({
+					type: 'log', level: 'info',
+					message: `\n${nav}`,
+					component: 'Breadcrumbs',
+					model: /** @type {any} */ (nav),
+				})
+
+				configResponse = yield {
+					type: 'ask',
+					field: 'componentThemeConfig',
+					schema: ComponentModels[`${this.selectedComponent}Model`] || {
+						help: `Configure properties for ${this.selectedComponent} to create a theme variation`,
+					},
+					component: 'SandboxWrapper',
+					model: true,
+					instance: /** @type {any} */ (targetInstance),
+				}
+			} catch (e) {
+				const err = /** @type {Error} */ (e)
+				if (err.name === 'CancelError') {
+					// Pop: Level 2 → Level 1
+					nav.pop()
+					this.selectedComponent = undefined
+					continue
+				}
+				throw e
+			}
+
+			// Persist edits for potential back-navigation
+			targetInstance = configResponse.value
+
+			// ── Level 3: Choose Export Format ──
+			// URL: /sandbox/button/export  Data: data/sandbox/button/export/index.yaml
+			/** @type {any} */
+			let formatResponse
+			try {
+				nav.push('Export', 'export')
+				yield /** @type {any} */ ({
+					type: 'log', level: 'info',
+					message: `\n${nav}`,
+					component: 'Breadcrumbs',
+					model: /** @type {any} */ (nav),
+				})
+
+				formatResponse = yield {
+					type: 'ask',
+					field: 'themeFormat',
+					schema: {
+						help: 'Choose how to export the theme configuration',
+						options: SandboxModel.themeFormat.options,
+					},
+					component: 'Select',
+					model: /** @type {any} */ (this),
+				}
+			} catch (e) {
+				const err = /** @type {Error} */ (e)
+				if (err.name === 'CancelError') {
+					// Pop: Level 3 → Level 2 (same targetInstance preserved)
+					nav.pop()
+					continue
+				}
+				throw e
+			}
+
+			this.themeFormat = formatResponse.value
+
+			// 4. Success notification
+			yield /** @type {any} */ ({
+				type: 'log',
+				level: 'success',
+				message: `Theme exported as ${(this.themeFormat || 'json').toUpperCase()}! Path: ${nav.path}`,
+			})
+
+			// 5. Return result with navigation context
+			return {
+				type: 'result',
+				data: {
+					targetComponent: this.selectedComponent,
+					themeConfig: configResponse.value,
+					exportFormat: this.themeFormat,
+					breadcrumb: nav.path,
+				}
+			}
+		}
+	}
+}

package/src/domain/ShowcaseAppModel.js

@@ -0,0 +1,88 @@
+import { InputModel, ConfirmModel, SpinnerModel, ToastModel, TableModel, ButtonModel, AutocompleteModel, SelectModel } from './components/index.js'
+
+/**
+ * Model-as-Schema for the entire UI Sandbox Showcase.
+ * Represents a complete User Journey demonstrating all components.
+ * Showcases OLMUI Scenario Testing capabilities.
+ */
+export class ShowcaseAppModel {
+	// ==========================================
+	// 1. MODEL AS SCHEMA (Static Definition)
+	// ==========================================
+
+	static appName = {
+		help: 'Name of the showcase application',
+		default: 'Component Showcase (Zero Hallucination)',
+		type: 'string',
+	}
+
+	constructor() {
+		this.appName = ShowcaseAppModel.appName.default
+	}
+
+	// ==========================================
+	// 2. AGNOSTIC LOGIC (Async Generator)
+	// ==========================================
+
+	async *run() {
+		// 1. Initial interaction: User clicks "Start Showcase" Button
+		const btnIntent = yield* new ButtonModel({ content: 'Start Showcase', variant: 'primary', size: 'lg' }).run()
+
+		if (!btnIntent.data.clicked) {
+			return { type: 'result', data: { success: false, reason: 'start_cancelled' } }
+		}
+
+		// 2. Ask user for their name via Input
+		const { data: nameData } = yield* new InputModel({ 
+			label: 'Enter your name to begin', 
+			placeholder: 'e.g. Yaroslav',
+			required: true,
+			pattern: '.{3,}' 
+		}).run()
+
+		const userName = /** @type {string} */ (nameData.value)
+
+		// 3. Ask user to select their role via Select
+		const { data: roleData } = yield* new SelectModel({
+			options: ['Developer', 'Designer', 'Manager']
+		}).run()
+		
+		const role = /** @type {string} */ (roleData.selected)
+
+		// 4. Ask for their favorite tool via Autocomplete
+		const { data: toolData } = yield* new AutocompleteModel({
+			options: ['React', 'Lit', 'Node.js', 'Playwright', 'Vitest', 'Vite']
+		}).run()
+
+		const tool = /** @type {string} */ (toolData.selected)
+
+		// 5. Ask for confirmation before proceeding to heavy calculation
+		const confirmIntent = yield* new ConfirmModel({ message: `Ready to generate profile for ${userName} (${role})?` }).run()
+		
+		if (!confirmIntent.data.confirmed) {
+			yield* new ToastModel({ message: 'Operation aborted.', variant: 'warning', duration: 0 }).run()
+			return { type: 'result', data: { success: false, reason: 'user_aborted' } }
+		}
+
+		// 6. Demonstrate a long running progress via Spinner
+		yield* new SpinnerModel({ size: 'md' }).run()
+
+		// Simulate business logic processing delay if we were not mocked
+		// But in generators this just happens immediately between yields
+		
+		yield* new ToastModel({ message: 'Profile generated successfully!', variant: 'success', duration: 0 }).run()
+
+		// 7. Display the result of the showcase in a Table
+		const { data: tableData } = yield* new TableModel({
+			columns: ['Property', 'Value'],
+			rows: [
+				['Name', userName],
+				['Role', role],
+				['Favorite Tool', tool],
+				['Status', 'Active']
+			]
+		}).run()
+
+		return { type: 'result', data: { success: true, profile: { userName, role, tool }, rowsDisplayed: tableData.rowsCount } }
+	}
+}

package/src/domain/components/AutocompleteModel.js

@@ -0,0 +1,58 @@
+import { Model } from '@nan0web/core'
+
+/**
+ * @typedef {Object} AutocompleteData
+ * @property {string} [content]
+ * @property {string[]} [options]
+ */
+
+/**
+ * Model-as-Schema for Autocomplete component.
+ * Represents a text input with search suggestions.
+ */
+export class AutocompleteModel extends Model {
+	// ==========================================
+	// 1. MODEL AS SCHEMA (Static Definition)
+	// ==========================================
+
+	static content = {
+		help: 'Current search text',
+		default: '',
+		type: 'string',
+	}
+
+	static options = {
+		help: 'List of suggestions based on input',
+		default: [],
+		type: 'string[]',
+	}
+
+	/**
+	 * @param {AutocompleteData | any} [data]
+	 */
+	constructor(data = {}) {
+		super(data)
+		/** @type {string|undefined} */ this.content
+		/** @type {string[]|undefined} */ this.options
+	}
+
+	// ==========================================
+	// 2. AGNOSTIC LOGIC (Async Generator)
+	// ==========================================
+
+	async *run() {
+		const response = yield {
+			type: 'ask',
+			field: 'content',
+			schema: {
+				help: 'Search or enter text',
+				options: this.options,
+			},
+			component: 'Autocomplete',
+			model: /** @type {any} */ (this),
+		}
+
+		this.content = response.value
+		return { type: 'result', data: { selected: this.content } }
+	}
+}

package/src/domain/components/BreadcrumbModel.js

@@ -0,0 +1,265 @@
+import { Model } from '@nan0web/core'
+
+/**
+ * @typedef {Object} BreadcrumbItem
+ * @property {string} label  - Human-readable display name (e.g. "Sandbox", "Кнопка")
+ * @property {string} path   - URL-safe segment (e.g. "sandbox", "button")
+ */
+
+/**
+ * @typedef {Object} BreadcrumbData
+ * @property {BreadcrumbItem[]} [items]
+ * @property {string} [separator]
+ */
+
+/**
+ * Model-as-Schema for Breadcrumb navigation.
+ *
+ * Each breadcrumb item has a `label` (display) and a `path` (URL segment).
+ * The full path is the join of all segments, mirroring both:
+ *   - Web URL:    /sandbox/button/export
+ *   - DBFS URI:   sandbox/button/export/index  (relative to db.root)
+ *   - Data path:  {db.root}/sandbox/button/export/index.yaml
+ *   - CLI nav:    🏖 Sandbox › Button › Export
+ *
+ * This is the universal "where am I?" model for any OLMUI application.
+ *
+ * ESC/Back = pop() one item. Empty stack = app exit.
+ * Ctrl+C   = always exit (adapter responsibility).
+ */
+export class BreadcrumbModel extends Model {
+	// ==========================================
+	// 1. MODEL AS SCHEMA (Static Definition)
+	// ==========================================
+
+	static items = {
+		help: 'Navigation path segments forming the breadcrumb trail',
+		type: 'array',
+		default: [],
+	}
+
+	static separator = {
+		help: 'Visual separator between breadcrumb segments',
+		default: '›',
+		type: 'string',
+	}
+
+	/**
+	 * @param {BreadcrumbData | any} [data]
+	 */
+	constructor(data = {}) {
+		super(data)
+		/** @type {BreadcrumbItem[]} */ this.items
+		/** @type {string} */ this.separator
+		// Normalize: if items were passed as plain strings, convert to {label, path}
+		if (Array.isArray(this.items)) {
+			this.items = this.items.map((item) =>
+				typeof item === 'string'
+					? { label: item, path: BreadcrumbModel.slugify(item) }
+					: item
+			)
+		}
+	}
+
+	// ==========================================
+	// 2. NAVIGATION API (Imperative)
+	// ==========================================
+
+	/**
+	 * Push a new level onto the navigation stack.
+	 *
+	 * @param {string} label - Display label (e.g. "Button", "Кнопка")
+	 * @param {string} [path] - URL segment. Auto-slugified from label if omitted.
+	 * @returns {this}
+	 */
+	push(label, path) {
+		this.items.push({
+			label,
+			path: path || BreadcrumbModel.slugify(label),
+		})
+		return this
+	}
+
+	/**
+	 * Pop the last level from the navigation stack.
+	 *
+	 * @returns {BreadcrumbItem|undefined} The removed item, or undefined if stack was empty.
+	 */
+	pop() {
+		return this.items.pop()
+	}
+
+	/**
+	 * Whether the user can navigate back (stack has > 0 items after pop).
+	 *
+	 * @returns {boolean}
+	 */
+	canGoBack() {
+		return this.items.length > 1
+	}
+
+	/**
+	 * Navigate to a specific depth by truncating the stack.
+	 *
+	 * @param {number} depth - Target depth (0 = root only).
+	 * @returns {this}
+	 */
+	navigateTo(depth) {
+		this.items = this.items.slice(0, depth + 1)
+		return this
+	}
+
+	// ==========================================
+	// 3. PATH / URL API (Serialization)
+	// ==========================================
+
+	/**
+	 * Full URL-style path: `/sandbox/button/export`
+	 * @returns {string}
+	 */
+	get path() {
+		if (this.items.length === 0) return '/'
+		return '/' + this.items.map((i) => i.path).join('/')
+	}
+
+	/**
+	 * Just the path segments array: `['sandbox', 'button', 'export']`
+	 * @returns {string[]}
+	 */
+	get segments() {
+		return this.items.map((i) => i.path)
+	}
+
+	/**
+	 * Just the display labels: `['Sandbox', 'Button', 'Export']`
+	 * @returns {string[]}
+	 */
+	get labels() {
+		return this.items.map((i) => i.label)
+	}
+
+	/**
+	 * Current (last) breadcrumb item.
+	 * @returns {BreadcrumbItem|undefined}
+	 */
+	get current() {
+		return this.items[this.items.length - 1]
+	}
+
+	/**
+	 * Current navigation depth (0 = no items).
+	 * @returns {number}
+	 */
+	get depth() {
+		return this.items.length
+	}
+
+	/**
+	 * Display string: `Sandbox › Button › Export`
+	 * @returns {string}
+	 */
+	toString() {
+		return this.labels.join(` ${this.separator} `)
+	}
+
+	/**
+	 * Serialize to URL query param value: `sandbox/button/export`
+	 * @returns {string}
+	 */
+	toURL() {
+		return this.segments.join('/')
+	}
+
+	/**
+	 * DBFS document URI — the key you pass to `db.fetch()` or `db.get()`.
+	 * Relative to `db.root`, without extension (DBFS resolves `.yaml`/`.json` automatically).
+	 *
+	 * @example
+	 * nav.push('sandbox').push('button')
+	 * nav.toURI()        // → 'sandbox/button/index'
+	 * db.fetch(nav.toURI()) // ← DBFS resolves to {root}/sandbox/button/index.yaml
+	 *
+	 * @param {string} [leaf='index'] - Document name without extension.
+	 * @returns {string}
+	 */
+	toURI(leaf = 'index') {
+		if (this.items.length === 0) return leaf
+		return `${this.segments.join('/')}/${leaf}`
+	}
+
+	/**
+	 * Full filesystem path relative to db.root: `sandbox/button/export/index.yaml`
+	 * This is what DBFS resolves to on disk: `{cwd}/{root}/{toDataPath()}`.
+	 *
+	 * @param {string} [filename='index.yaml'] - Leaf filename with extension.
+	 * @returns {string}
+	 */
+	toDataPath(filename = 'index.yaml') {
+		if (this.items.length === 0) return filename
+		return `${this.segments.join('/')}/${filename}`
+	}
+
+	/**
+	 * Reconstruct a BreadcrumbModel from a URL path string.
+	 *
+	 * @param {string} urlPath - e.g. "/sandbox/button" or "sandbox/button"
+	 * @param {Record<string,string>} [labelMap={}] - Optional map of path→label for display names.
+	 * @returns {BreadcrumbModel}
+	 */
+	static fromPath(urlPath, labelMap = {}) {
+		const segments = urlPath
+			.replace(/^\//, '')
+			.split('/')
+			.filter(Boolean)
+
+		const items = segments.map((seg) => ({
+			label: labelMap[seg] || seg,
+			path: seg,
+		}))
+
+		return new BreadcrumbModel({ items })
+	}
+
+	/**
+	 * Create a URL-safe slug from any label.
+	 * Handles Unicode (Cyrillic, etc.) by lowercasing and replacing spaces/special chars.
+	 *
+	 * @param {string} label
+	 * @returns {string}
+	 */
+	static slugify(label) {
+		return label
+			.toLowerCase()
+			.replace(/\s+/g, '-')
+			.replace(/[^\p{L}\p{N}\-]/gu, '')
+			.replace(/-+/g, '-')
+			.replace(/^-|-$/g, '')
+	}
+
+	// ==========================================
+	// 4. AGNOSTIC LOGIC (Async Generator)
+	// ==========================================
+
+	/**
+	 * Yields a log intent with the current breadcrumb path.
+	 * This is a "display-only" run — it shows the navigation state.
+	 */
+	async *run() {
+		yield /** @type {any} */ ({
+			type: 'log',
+			level: 'info',
+			message: this.toString(),
+			component: 'Breadcrumbs',
+			model: /** @type {any} */ (this),
+		})
+
+		return {
+			type: 'result',
+			data: {
+				path: this.path,
+				items: this.items,
+				depth: this.depth,
+			},
+		}
+	}
+}

package/src/domain/components/ButtonModel.js

@@ -0,0 +1,92 @@
+import { Model } from '@nan0web/core'
+
+/**
+ * @typedef {'primary'|'secondary'|'info'|'ok'|'warn'|'err'|'ghost'} ButtonVariant
+ * @typedef {'sm'|'md'|'lg'} ButtonSize
+ * @typedef {Object} ButtonData
+ * @property {string} [content]
+ * @property {ButtonVariant} [variant]
+ * @property {ButtonSize} [size]
+ * @property {boolean} [outline]
+ * @property {boolean} [disabled]
+ * @property {boolean} [loading]
+ */
+
+/**
+ * Model-as-Schema for Button component.
+ * Represents the intention and state of a Button interaction.
+ * Used exclusively for schema definition and editor validation.
+ */
+export class ButtonModel extends Model {
+	// ==========================================
+	// 1. MODEL AS SCHEMA (Static Definition)
+	// ==========================================
+
+	static content = {
+		help: 'Text or content inside the button',
+		default: 'Click Me',
+		type: 'string',
+	}
+
+	static variant = {
+		help: 'Visual importance and semantic meaning',
+		default: 'primary',
+		options: ['primary', 'secondary', 'info', 'ok', 'warn', 'err', 'ghost'],
+	}
+
+	static size = {
+		help: 'Size of the button',
+		default: 'md',
+		options: ['sm', 'md', 'lg'],
+	}
+
+	static outline = {
+		help: 'Whether the button has a transparent background with border',
+		default: false,
+		type: 'boolean',
+	}
+
+	static disabled = {
+		help: 'Whether the button is disabled and unclickable',
+		default: false,
+		type: 'boolean',
+	}
+
+	static loading = {
+		help: 'Whether the button shows a loading spinner instead of content',
+		default: false,
+		type: 'boolean',
+	}
+
+	/**
+	 * @param {ButtonData | any} [data]
+	 */
+	constructor(data = {}) {
+		super(data)
+		/** @type {string|undefined} */ this.content
+		/** @type {ButtonVariant|undefined} */ this.variant
+		/** @type {ButtonSize|undefined} */ this.size
+		/** @type {boolean|undefined} */ this.outline
+		/** @type {boolean|undefined} */ this.disabled
+		/** @type {boolean|undefined} */ this.loading
+	}
+
+	// ==========================================
+	// 2. AGNOSTIC LOGIC (Async Generator)
+	// ==========================================
+
+	async *run() {
+		// A basic button interaction intention:
+		// We simply yield ourselves as a 'button_click' intent.
+		// Adaptors will render the button and wait for the click event.
+		const response = yield {
+			type: 'ask',
+			field: 'action',
+			schema: { help: 'Click the button to proceed' },
+			component: 'Button',
+			model: /** @type {any} */ (this),
+		}
+
+		return { type: 'result', data: { clicked: true, ...response } }
+	}
+}