@nan0web/ui 1.6.2 → 1.7.0

package/types/core/IntentErrorModel.d.ts

@@ -0,0 +1,55 @@
+export class IntentErrorModel {
+    static intent_not_object: {
+        help: string;
+        error: string;
+    };
+    static intent_unknown_type: {
+        help: string;
+        error: string;
+    };
+    static ask_missing_field: {
+        help: string;
+        error: string;
+    };
+    static ask_missing_schema_help: {
+        help: string;
+        error: string;
+    };
+    static intent_missing_message: {
+        help: string;
+        error: string;
+    };
+    static adapter_missing_ask: {
+        help: string;
+        error: string;
+    };
+    static ask_wrong_response: {
+        help: string;
+        error: string;
+    };
+    static validation_failed: {
+        help: string;
+        error: string;
+    };
+    static unhandled_intent: {
+        help: string;
+        error: string;
+    };
+    static timeout: {
+        help: string;
+        error: string;
+    };
+    static aborted: {
+        help: string;
+        error: string;
+    };
+    /**
+     * Build a ModelError for a specific error field.
+     *
+     * @param {string} field - Static field name on IntentErrorModel.
+     * @param {Record<string, *>} [params] - Template parameters to substitute {key} placeholders.
+     * @returns {ModelError}
+     */
+    static error(field: string, params?: Record<string, any>): ModelError;
+}
+import { ModelError } from '@nan0web/types';

package/types/core/MaskHandler.d.ts

@@ -0,0 +1,33 @@
+export class MaskHandler {
+    constructor(mask: any);
+    mask: any;
+    raw: string;
+    /** How many placeholder positions the mask has */
+    get _slotCount(): number;
+    /** Static prefix of the mask (literal characters before first placeholder) */
+    get _prefix(): string;
+    get isComplete(): boolean;
+    get formatted(): string;
+    /**
+     * Append a digit/letter character.
+     * Only accepts characters that fit into placeholders.
+     *
+     * @param {string} char
+     * @returns {boolean} true if accepted
+     */
+    input(char: string): boolean;
+    /**
+     * Remove last character
+     */
+    backspace(): boolean;
+    /**
+     * 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: string): void;
+}

package/types/core/index.d.ts

@@ -4,9 +4,13 @@ export { default as UiMessage } from "./Message/Message.js";
 export { default as FormMessage } from "./Form/Message.js";
 export { default as FormInput } from "./Form/Input.js";
 export { default as UiAdapter } from "./UiAdapter.js";
+export { IntentErrorModel } from "./IntentErrorModel.js";
+export { runGenerator } from "./GeneratorRunner.js";
+export { MaskHandler } from "./MaskHandler.js";
 import UIStream from './Stream.js';
 import StreamEntry from './StreamEntry.js';
 import UIForm from './Form/Form.js';
 export { UIStream, UIStream as UiStream, StreamEntry, StreamEntry as UiStreamEntry, UIForm, UIForm as UiForm };
 export { default as Error, CancelError } from "./Error/index.js";
 export { runFlow, flow, View, Prompt, Stream, Alert, Toast, Badge, Text, Table, Input, Select, Confirm, Multiselect, Mask, Password, Spinner, Progress, default as Flow } from "./Flow.js";
+export { validateIntent, ask, progress, log, result, INTENT_TYPES, isModelSchema } from "./Intent.js";

package/types/domain/SandboxModel.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @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 {
+    static components: {
+        help: string;
+        type: string;
+        default: never[];
+    };
+    static selectedComponent: {
+        help: string;
+        type: string;
+    };
+    static themeFormat: {
+        help: string;
+        options: string[];
+        default: string;
+    };
+    /**
+     * @param {SandboxData | any} [data]
+     */
+    constructor(data?: SandboxData | any);
+    /** @type {string[]|undefined} */ components: string[] | undefined;
+    /** @type {string|undefined} */ selectedComponent: string | undefined;
+    /** @type {string|undefined} */ themeFormat: string | undefined;
+    run(): AsyncGenerator<any, {
+        type: string;
+        data: {
+            targetComponent: string | undefined;
+            themeConfig: any;
+            exportFormat: string | undefined;
+            breadcrumb: string;
+        };
+    }, any>;
+}
+export type SandboxData = {
+    components?: string[] | undefined;
+    selectedComponent?: string | undefined;
+    themeFormat?: string | undefined;
+};
+import { Model } from '@nan0web/core';

package/types/domain/ShowcaseAppModel.d.ts

@@ -0,0 +1,62 @@
+/**
+ * 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 {
+    static appName: {
+        help: string;
+        default: string;
+        type: string;
+    };
+    appName: string;
+    run(): AsyncGenerator<{
+        type: string;
+        field: string;
+        schema: {
+            help: string;
+        };
+        component: string;
+        model: any;
+    } | {
+        type: string;
+        field: string;
+        schema: {
+            help: string | undefined;
+            type: string;
+        };
+        component: string;
+        model: any;
+    } | {
+        type: string;
+        level: string;
+        message: string | undefined;
+        component: string;
+        model: any;
+    } | {
+        type: string;
+        message: string;
+        component: string;
+        model: any;
+    }, {
+        type: string;
+        data: {
+            success: boolean;
+            reason: string;
+            profile?: undefined;
+            rowsDisplayed?: undefined;
+        };
+    } | {
+        type: string;
+        data: {
+            success: boolean;
+            profile: {
+                userName: string;
+                role: string;
+                tool: string;
+            };
+            rowsDisplayed: number;
+            reason?: undefined;
+        };
+    }, unknown>;
+}

package/types/domain/components/AutocompleteModel.d.ts

@@ -0,0 +1,47 @@
+/**
+ * @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 {
+    static content: {
+        help: string;
+        default: string;
+        type: string;
+    };
+    static options: {
+        help: string;
+        default: never[];
+        type: string;
+    };
+    /**
+     * @param {AutocompleteData | any} [data]
+     */
+    constructor(data?: AutocompleteData | any);
+    /** @type {string|undefined} */ content: string | undefined;
+    /** @type {string[]|undefined} */ options: string[] | undefined;
+    run(): AsyncGenerator<{
+        type: string;
+        field: string;
+        schema: {
+            help: string;
+            options: string[] | undefined;
+        };
+        component: string;
+        model: any;
+    }, {
+        type: string;
+        data: {
+            selected: string | undefined;
+        };
+    }, unknown>;
+}
+export type AutocompleteData = {
+    content?: string | undefined;
+    options?: string[] | undefined;
+};
+import { Model } from '@nan0web/core';

package/types/domain/components/BreadcrumbModel.d.ts

@@ -0,0 +1,164 @@
+/**
+ * @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 {
+    static items: {
+        help: string;
+        type: string;
+        default: never[];
+    };
+    static separator: {
+        help: string;
+        default: string;
+        type: string;
+    };
+    /**
+     * 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: string, labelMap?: Record<string, string>): BreadcrumbModel;
+    /**
+     * 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: string): string;
+    /**
+     * @param {BreadcrumbData | any} [data]
+     */
+    constructor(data?: BreadcrumbData | any);
+    /** @type {BreadcrumbItem[]} */ items: BreadcrumbItem[];
+    /** @type {string} */ separator: string;
+    /**
+     * 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: string, path?: string): this;
+    /**
+     * Pop the last level from the navigation stack.
+     *
+     * @returns {BreadcrumbItem|undefined} The removed item, or undefined if stack was empty.
+     */
+    pop(): BreadcrumbItem | undefined;
+    /**
+     * Whether the user can navigate back (stack has > 0 items after pop).
+     *
+     * @returns {boolean}
+     */
+    canGoBack(): boolean;
+    /**
+     * Navigate to a specific depth by truncating the stack.
+     *
+     * @param {number} depth - Target depth (0 = root only).
+     * @returns {this}
+     */
+    navigateTo(depth: number): this;
+    /**
+     * Full URL-style path: `/sandbox/button/export`
+     * @returns {string}
+     */
+    get path(): string;
+    /**
+     * Just the path segments array: `['sandbox', 'button', 'export']`
+     * @returns {string[]}
+     */
+    get segments(): string[];
+    /**
+     * Just the display labels: `['Sandbox', 'Button', 'Export']`
+     * @returns {string[]}
+     */
+    get labels(): string[];
+    /**
+     * Current (last) breadcrumb item.
+     * @returns {BreadcrumbItem|undefined}
+     */
+    get current(): BreadcrumbItem | undefined;
+    /**
+     * Current navigation depth (0 = no items).
+     * @returns {number}
+     */
+    get depth(): number;
+    /**
+     * Serialize to URL query param value: `sandbox/button/export`
+     * @returns {string}
+     */
+    toURL(): string;
+    /**
+     * 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?: string): string;
+    /**
+     * 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?: string): string;
+    /**
+     * Yields a log intent with the current breadcrumb path.
+     * This is a "display-only" run — it shows the navigation state.
+     */
+    run(): AsyncGenerator<any, {
+        type: string;
+        data: {
+            path: string;
+            items: BreadcrumbItem[];
+            depth: number;
+        };
+    }, unknown>;
+}
+export type BreadcrumbItem = {
+    /**
+     * - Human-readable display name (e.g. "Sandbox", "Кнопка")
+     */
+    label: string;
+    /**
+     * - URL-safe segment (e.g. "sandbox", "button")
+     */
+    path: string;
+};
+export type BreadcrumbData = {
+    items?: BreadcrumbItem[] | undefined;
+    separator?: string | undefined;
+};
+import { Model } from '@nan0web/core';

package/types/domain/components/ButtonModel.d.ts

@@ -0,0 +1,81 @@
+/**
+ * @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 {
+    static content: {
+        help: string;
+        default: string;
+        type: string;
+    };
+    static variant: {
+        help: string;
+        default: string;
+        options: string[];
+    };
+    static size: {
+        help: string;
+        default: string;
+        options: string[];
+    };
+    static outline: {
+        help: string;
+        default: boolean;
+        type: string;
+    };
+    static disabled: {
+        help: string;
+        default: boolean;
+        type: string;
+    };
+    static loading: {
+        help: string;
+        default: boolean;
+        type: string;
+    };
+    /**
+     * @param {ButtonData | any} [data]
+     */
+    constructor(data?: ButtonData | any);
+    /** @type {string|undefined} */ content: string | undefined;
+    /** @type {ButtonVariant|undefined} */ variant: ButtonVariant | undefined;
+    /** @type {ButtonSize|undefined} */ size: ButtonSize | undefined;
+    /** @type {boolean|undefined} */ outline: boolean | undefined;
+    /** @type {boolean|undefined} */ disabled: boolean | undefined;
+    /** @type {boolean|undefined} */ loading: boolean | undefined;
+    run(): AsyncGenerator<{
+        type: string;
+        field: string;
+        schema: {
+            help: string;
+        };
+        component: string;
+        model: any;
+    }, {
+        type: string;
+        data: any;
+    }, unknown>;
+}
+export type ButtonVariant = "primary" | "secondary" | "info" | "ok" | "warn" | "err" | "ghost";
+export type ButtonSize = "sm" | "md" | "lg";
+export type ButtonData = {
+    content?: string | undefined;
+    variant?: ButtonVariant | undefined;
+    size?: ButtonSize | undefined;
+    outline?: boolean | undefined;
+    disabled?: boolean | undefined;
+    loading?: boolean | undefined;
+};
+import { Model } from '@nan0web/core';

package/types/domain/components/ConfirmModel.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @typedef {Object} ConfirmData
+ * @property {string} [message]
+ * @property {string} [confirmText]
+ * @property {string} [cancelText]
+ */
+/**
+ * Model-as-Schema for Confirm component.
+ */
+export class ConfirmModel extends Model {
+    static message: {
+        help: string;
+        default: string;
+        type: string;
+    };
+    static confirmText: {
+        help: string;
+        default: string;
+        type: string;
+    };
+    static cancelText: {
+        help: string;
+        default: string;
+        type: string;
+    };
+    /**
+     * @param {ConfirmData | any} [data]
+     */
+    constructor(data?: ConfirmData | any);
+    /** @type {string|undefined} */ message: string | undefined;
+    /** @type {string|undefined} */ confirmText: string | undefined;
+    /** @type {string|undefined} */ cancelText: string | undefined;
+    run(): AsyncGenerator<{
+        type: string;
+        field: string;
+        schema: {
+            help: string | undefined;
+            type: string;
+        };
+        component: string;
+        model: any;
+    }, {
+        type: string;
+        data: {
+            confirmed: boolean;
+        };
+    }, unknown>;
+}
+export type ConfirmData = {
+    message?: string | undefined;
+    confirmText?: string | undefined;
+    cancelText?: string | undefined;
+};
+import { Model } from '@nan0web/core';

package/types/domain/components/InputModel.d.ts

@@ -0,0 +1,121 @@
+/**
+ * @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 {
+    static type: {
+        help: string;
+        default: string;
+        options: string[];
+    };
+    static label: {
+        help: string;
+        default: string;
+        type: string;
+    };
+    static placeholder: {
+        help: string;
+        default: string;
+        type: string;
+    };
+    static required: {
+        help: string;
+        default: boolean;
+        type: string;
+    };
+    static pattern: {
+        help: string;
+        default: string;
+        type: string;
+    };
+    static min: {
+        help: string;
+        default: string;
+        type: string;
+    };
+    static max: {
+        help: string;
+        default: string;
+        type: string;
+    };
+    static step: {
+        help: string;
+        default: string;
+        type: string;
+    };
+    static hint: {
+        help: string;
+        default: string;
+        type: string;
+    };
+    static disabled: {
+        help: string;
+        default: boolean;
+        type: string;
+    };
+    static content: {
+        help: string;
+        default: string;
+        type: string;
+    };
+    /**
+     * @param {InputData | any} [data]
+     */
+    constructor(data?: InputData | any);
+    /** @type {InputType|undefined} */ type: InputType | undefined;
+    /** @type {string|undefined} */ label: string | undefined;
+    /** @type {string|undefined} */ placeholder: string | undefined;
+    /** @type {boolean|undefined} */ required: boolean | undefined;
+    /** @type {string|undefined} */ pattern: string | undefined;
+    /** @type {string|undefined} */ min: string | undefined;
+    /** @type {string|undefined} */ max: string | undefined;
+    /** @type {string|undefined} */ step: string | undefined;
+    /** @type {string|undefined} */ hint: string | undefined;
+    /** @type {boolean|undefined} */ disabled: boolean | undefined;
+    /** @type {string|undefined} */ content: string | undefined;
+    run(): AsyncGenerator<{
+        type: string;
+        field: string;
+        schema: {
+            help: string;
+            validate: (val: any) => true | "This field is required" | "Invalid format";
+        };
+        component: string;
+        model: any;
+    }, {
+        type: string;
+        data: {
+            value: string | undefined;
+        };
+    }, unknown>;
+}
+export type InputType = "text" | "email" | "password" | "number" | "tel" | "url" | "date";
+export type InputData = {
+    type?: InputType | undefined;
+    label?: string | undefined;
+    placeholder?: string | undefined;
+    required?: boolean | undefined;
+    pattern?: string | undefined;
+    min?: string | undefined;
+    max?: string | undefined;
+    step?: string | undefined;
+    hint?: string | undefined;
+    disabled?: boolean | undefined;
+    content?: string | undefined;
+};
+import { Model } from '@nan0web/core';