@nan0web/ui 1.6.2 → 1.7.0

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

package/src/domain/components/ConfirmModel.js

@@ -0,0 +1,64 @@
+import { Model } from '@nan0web/core'
+
+/**
+ * @typedef {Object} ConfirmData
+ * @property {string} [message]
+ * @property {string} [confirmText]
+ * @property {string} [cancelText]
+ */
+
+/**
+ * Model-as-Schema for Confirm component.
+ */
+export class ConfirmModel extends Model {
+	// ==========================================
+	// 1. MODEL AS SCHEMA (Static Definition)
+	// ==========================================
+
+	static message = {
+		help: 'Dialog message displayed to the user',
+		default: 'Are you sure?',
+		type: 'string',
+	}
+
+	static confirmText = {
+		help: 'Label for the positive confirmation button',
+		default: 'Yes',
+		type: 'string',
+	}
+
+	static cancelText = {
+		help: 'Label for the negative rejection button',
+		default: 'No',
+		type: 'string',
+	}
+
+	/**
+	 * @param {ConfirmData | any} [data]
+	 */
+	constructor(data = {}) {
+		super(data)
+		/** @type {string|undefined} */ this.message
+		/** @type {string|undefined} */ this.confirmText
+		/** @type {string|undefined} */ this.cancelText
+	}
+
+	// ==========================================
+	// 2. AGNOSTIC LOGIC (Async Generator)
+	// ==========================================
+
+	async *run() {
+		const response = yield {
+			type: 'ask',
+			field: 'confirmed',
+			schema: {
+				help: this.message,
+				type: 'boolean',
+			},
+			component: 'Confirm',
+			model: /** @type {any} */ (this), // Attached for richer UI metadata
+		}
+
+		return { type: 'result', data: { confirmed: !!response.value } }
+	}
+}

package/src/domain/components/InputModel.js

@@ -0,0 +1,142 @@
+import { Model } from '@nan0web/core'
+
+/**
+ * @typedef {'text'|'email'|'password'|'number'|'tel'|'url'|'date'} InputType
+ * @typedef {Object} InputData
+ * @property {InputType} [type]
+ * @property {string} [label]
+ * @property {string} [placeholder]
+ * @property {boolean} [required]
+ * @property {string} [pattern]
+ * @property {string} [min]
+ * @property {string} [max]
+ * @property {string} [step]
+ * @property {string} [hint]
+ * @property {boolean} [disabled]
+ * @property {string} [content]
+ */
+
+/**
+ * Model-as-Schema for Input component.
+ * Used exclusively for schema definition, validation, and editor reflection.
+ */
+export class InputModel extends Model {
+	// ==========================================
+	// 1. MODEL AS SCHEMA (Static Definition)
+	// ==========================================
+
+	static type = {
+		help: 'HTML5 Input type attribute',
+		default: 'text',
+		options: ['text', 'email', 'password', 'number', 'tel', 'url', 'date'],
+	}
+
+	static label = {
+		help: 'Label displayed above the input',
+		default: '',
+		type: 'string',
+	}
+
+	static placeholder = {
+		help: 'Placeholder text shown when empty',
+		default: '',
+		type: 'string',
+	}
+
+	static required = {
+		help: 'Whether the field must be filled out',
+		default: false,
+		type: 'boolean',
+	}
+
+	static pattern = {
+		help: 'RegExp pattern for validation (e.g. [A-Z]{3})',
+		default: '',
+		type: 'string',
+	}
+
+	static min = {
+		help: 'Minimum value (for number/date types)',
+		default: '',
+		type: 'string',
+	}
+
+	static max = {
+		help: 'Maximum value (for number/date types)',
+		default: '',
+		type: 'string',
+	}
+
+	static step = {
+		help: 'Step interval (for number/date types)',
+		default: '',
+		type: 'string',
+	}
+
+	static hint = {
+		help: 'Helper text displayed below the input',
+		default: '',
+		type: 'string',
+	}
+
+	static disabled = {
+		help: 'Whether the input is greyed out and uneditable',
+		default: false,
+		type: 'boolean',
+	}
+
+	static content = {
+		help: 'The actual value of the input',
+		default: '',
+		type: 'string',
+	}
+
+	/**
+	 * @param {InputData | any} [data]
+	 */
+	constructor(data = {}) {
+		super(data)
+		/** @type {InputType|undefined} */ this.type
+		/** @type {string|undefined} */ this.label
+		/** @type {string|undefined} */ this.placeholder
+		/** @type {boolean|undefined} */ this.required
+		/** @type {string|undefined} */ this.pattern
+		/** @type {string|undefined} */ this.min
+		/** @type {string|undefined} */ this.max
+		/** @type {string|undefined} */ this.step
+		/** @type {string|undefined} */ this.hint
+		/** @type {boolean|undefined} */ this.disabled
+		/** @type {string|undefined} */ this.content
+	}
+
+	// ==========================================
+	// 2. AGNOSTIC LOGIC (Async Generator)
+	// ==========================================
+
+	async *run() {
+		const response = yield {
+			type: 'ask',
+			field: 'content',
+			schema: {
+				help: this.label || this.placeholder || 'Enter value',
+				validate: (val) => {
+					if (this.required && !val) return 'This field is required'
+					if (this.pattern && val) {
+						try {
+							const re = new RegExp(`^${this.pattern}$`)
+							if (!re.test(val)) return 'Invalid format'
+						} catch (e) {
+							// fallback if pattern is malformed
+						}
+					}
+					return true
+				},
+			},
+			component: 'Input',
+			model: /** @type {any} */ (this),
+		}
+
+		this.content = response.value
+		return { type: 'result', data: { value: this.content } }
+	}
+}

package/src/domain/components/SelectModel.js

@@ -0,0 +1,59 @@
+import { Model } from '@nan0web/core'
+
+/**
+ * @typedef {Object} SelectData
+ * @property {string} [content]
+ * @property {string[]} [options]
+ */
+
+/**
+ * Model-as-Schema for Select component.
+ * Represents a dropdown choice selection.
+ */
+export class SelectModel extends Model {
+	// ==========================================
+	// 1. MODEL AS SCHEMA (Static Definition)
+	// ==========================================
+
+	static content = {
+		help: 'Currently selected item or default placeholder',
+		default: 'Choose option',
+		type: 'string',
+	}
+
+	static options = {
+		help: 'List of available options for selection',
+		default: ['Alpha', 'Beta', 'Gamma'],
+		type: 'string[]',
+	}
+
+	/**
+	 * @param {SelectData | 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: 'Select an option',
+				options: this.options,
+				validate: (val) => this.options?.includes(val) || 'Invalid option selected',
+			},
+			component: 'Select',
+			model: /** @type {any} */ (this),
+		}
+
+		this.content = response.value
+		return { type: 'result', data: { selected: this.content } }
+	}
+}

package/src/domain/components/SpinnerModel.js

@@ -0,0 +1,58 @@
+import { Model } from '@nan0web/core'
+
+/**
+ * @typedef {'sm'|'md'|'lg'} SpinnerSize
+ * @typedef {Object} SpinnerData
+ * @property {SpinnerSize} [size]
+ * @property {string} [color]
+ */
+
+/**
+ * Model-as-Schema for Spinner component.
+ * Represents a loading or progress state without user interaction.
+ */
+export class SpinnerModel extends Model {
+	// ==========================================
+	// 1. MODEL AS SCHEMA (Static Definition)
+	// ==========================================
+
+	static size = {
+		help: 'Spinner diameter',
+		default: 'md',
+		options: ['sm', 'md', 'lg'],
+	}
+
+	static color = {
+		help: 'Override for base color token',
+		type: 'color',
+		default: '',
+	}
+
+	/**
+	 * @param {SpinnerData | any} [data]
+	 */
+	constructor(data = {}) {
+		super(data)
+		/** @type {SpinnerSize|undefined} */ this.size
+		/** @type {string|undefined} */ this.color
+	}
+
+	// ==========================================
+	// 2. AGNOSTIC LOGIC (Async Generator)
+	// ==========================================
+
+	async *run() {
+		// A spinner does not ask for anything, it simply indicates progress.
+		// However, as a pure component it doesn't do any work itself,
+		// so running it just means declaring its state.
+		yield {
+			type: 'progress',
+			message: 'Loading...',
+			component: 'Spinner',
+			model: /** @type {any} */ (this),
+		}
+
+		// Instant exit since it performs no async task internally
+		return { type: 'result', data: { completed: true } }
+	}
+}