@nan0web/ui 1.6.2 → 1.7.0

package/src/core/MaskHandler.js

@@ -0,0 +1,125 @@
+/**
+ * MaskHandler — Universal interactive mask controller.
+ *
+ * Supports masks where:
+ *   `9`, `0`, `#` = digit placeholder
+ *   `A` = letter placeholder
+ *   `_` = any character placeholder
+ *   anything else = literal (displayed as-is)
+ *
+ * Recognises the mask's static prefix (e.g. "+38" in "+38 (099) 999 9999")
+ * and strips it from raw user input to avoid duplication.
+ *
+ * @module core/MaskHandler
+ */
+
+/**
+ * @param {string} ch - single mask character
+ * @returns {boolean}
+ */
+function isPlaceholder(ch) {
+	return ch === '9' || ch === '0' || ch === '#' || ch === '_' || ch === 'A'
+}
+
+export class MaskHandler {
+	constructor(mask) {
+		this.mask = mask // e.g. "+38 (099) 999 9999"
+		this.raw = '' // raw user digits (without mask prefix)
+	}
+
+	/** How many placeholder positions the mask has */
+	get _slotCount() {
+		let n = 0
+		for (const ch of this.mask) if (isPlaceholder(ch)) n++
+		return n
+	}
+
+	/** Static prefix of the mask (literal characters before first placeholder) */
+	get _prefix() {
+		let p = ''
+		for (const ch of this.mask) {
+			if (isPlaceholder(ch)) break
+			p += ch
+		}
+		return p
+	}
+
+	get isComplete() {
+		return this.raw.length >= this._slotCount
+	}
+
+	get formatted() {
+		let result = ''
+		let rawIndex = 0
+
+		for (let i = 0; i < this.mask.length; i++) {
+			const m = this.mask[i]
+
+			if (isPlaceholder(m)) {
+				if (rawIndex < this.raw.length) {
+					result += this.raw[rawIndex++]
+				} else {
+					result += '_' // visual unfilled placeholder
+				}
+			} else {
+				// Literal character in the mask
+				result += m
+			}
+		}
+		return result
+	}
+
+	/**
+	 * Append a digit/letter character.
+	 * Only accepts characters that fit into placeholders.
+	 *
+	 * @param {string} char
+	 * @returns {boolean} true if accepted
+	 */
+	input(char) {
+		if (this.raw.length >= this._slotCount) return false // already full
+
+		if (/[0-9a-zA-Z]/.test(char)) {
+			this.raw += char
+			return true
+		}
+		return false
+	}
+
+	/**
+	 * Remove last character
+	 */
+	backspace() {
+		if (this.raw.length > 0) {
+			this.raw = this.raw.slice(0, -1)
+			return true
+		}
+		return false
+	}
+
+	/**
+	 * Set a full value, intelligently stripping the mask's static prefix
+	 * if the user pasted or injected the full formatted number.
+	 *
+	 * e.g. setValue('+380660848404') with mask '+38 (099) 999 9999'
+	 *      strips "+38" → raw = '0660848404'
+	 *
+	 * @param {string} val
+	 */
+	setValue(val) {
+		this.raw = ''
+		// Strip all non-alphanumeric from the value
+		let clean = String(val).replace(/[^a-zA-Z0-9]/g, '')
+
+		// Strip mask's static prefix digits if present
+		const prefixDigits = this._prefix.replace(/[^a-zA-Z0-9]/g, '')
+		if (prefixDigits && clean.startsWith(prefixDigits)) {
+			clean = clean.substring(prefixDigits.length)
+		}
+
+		// Feed only as many characters as we have slots
+		for (const c of clean) {
+			if (!this.input(c)) break
+		}
+	}
+}

package/src/core/index.js

@@ -39,3 +39,10 @@ export {
 	Progress,
 } from './Flow.js'
 export { default as Flow } from './Flow.js'
+
+// OLMUI Generator Engine — Intent-based Model→Adapter contract
+export { validateIntent, ask, progress, log, result, INTENT_TYPES, isModelSchema } from './Intent.js'
+export { IntentErrorModel } from './IntentErrorModel.js'
+export { runGenerator } from './GeneratorRunner.js'
+
+export { MaskHandler } from './MaskHandler.js'

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 } }
+	}
+}