@tempots/beatui 0.17.0 → 0.18.0

package/dist/types/components/json-schema/validation/error-aggregation.d.ts

@@ -0,0 +1,84 @@
+import type { ErrorObject } from 'ajv';
+import type { ControllerValidation } from '../../form/controller/controller-validation';
+/**
+ * Aggregated validation error information
+ */
+export interface AggregatedError {
+    /** Field path where the error occurred */
+    path: string;
+    /** Human-readable field name */
+    fieldName: string;
+    /** Error message */
+    message: string;
+    /** Error severity level */
+    severity: 'error' | 'warning' | 'info';
+    /** Error source/type */
+    source: 'schema' | 'conditional' | 'crossField' | 'async' | 'custom';
+    /** Additional context */
+    context?: Record<string, unknown>;
+    /** Original error object */
+    originalError?: ErrorObject;
+}
+/**
+ * Error aggregation configuration
+ */
+export interface ErrorAggregationConfig {
+    /** Whether to include warnings in aggregation */
+    includeWarnings?: boolean;
+    /** Whether to include info messages */
+    includeInfo?: boolean;
+    /** Maximum number of errors to aggregate per field */
+    maxErrorsPerField?: number;
+    /** Custom field name resolver */
+    fieldNameResolver?: (path: string) => string;
+    /** Custom error message formatter */
+    messageFormatter?: (error: AggregatedError) => string;
+    /** Error priority resolver (higher numbers = higher priority) */
+    priorityResolver?: (error: AggregatedError) => number;
+}
+/**
+ * Error aggregation result
+ */
+export interface ErrorAggregationResult {
+    /** All aggregated errors */
+    errors: AggregatedError[];
+    /** Errors grouped by field path */
+    errorsByField: Record<string, AggregatedError[]>;
+    /** Error summary statistics */
+    summary: {
+        totalErrors: number;
+        errorCount: number;
+        warningCount: number;
+        infoCount: number;
+        fieldsWithErrors: number;
+    };
+    /** Whether the form has any validation errors */
+    hasErrors: boolean;
+    /** Whether the form has any warnings */
+    hasWarnings: boolean;
+}
+/**
+ * Aggregate validation errors from multiple sources
+ */
+export declare function aggregateValidationErrors(sources: {
+    ajvErrors?: ErrorObject[];
+    controllerValidation?: ControllerValidation;
+    asyncErrors?: Record<string, ControllerValidation>;
+    customErrors?: AggregatedError[];
+}, config?: ErrorAggregationConfig): ErrorAggregationResult;
+/**
+ * Create a formatted error summary for display
+ */
+export declare function formatErrorSummary(result: ErrorAggregationResult, config?: ErrorAggregationConfig): string[];
+/**
+ * Get the first error for each field (useful for inline validation display)
+ */
+export declare function getFirstErrorPerField(result: ErrorAggregationResult): Record<string, AggregatedError>;
+/**
+ * Check if a specific field has errors
+ */
+export declare function fieldHasErrors(result: ErrorAggregationResult, fieldPath: string): boolean;
+/**
+ * Get errors for a specific field
+ */
+export declare function getFieldErrors(result: ErrorAggregationResult, fieldPath: string): AggregatedError[];

package/dist/types/components/json-schema/validation/performance-optimization.d.ts

@@ -0,0 +1,120 @@
+import type { ValidateFunction } from 'ajv';
+import type { ControllerValidation } from '../../form/controller/controller-validation';
+/**
+ * Performance optimization configuration
+ */
+export interface ValidationPerformanceConfig {
+    /** Enable validation result caching */
+    enableCaching?: boolean;
+    /** Cache TTL in milliseconds (default: 5 minutes) */
+    cacheTTL?: number;
+    /** Maximum cache size (default: 1000 entries) */
+    maxCacheSize?: number;
+    /** Enable validation batching */
+    enableBatching?: boolean;
+    /** Batch delay in milliseconds (default: 50ms) */
+    batchDelay?: number;
+    /** Enable incremental validation */
+    enableIncremental?: boolean;
+    /** Enable validation prioritization */
+    enablePrioritization?: boolean;
+    /** Validation timeout in milliseconds */
+    validationTimeout?: number;
+}
+/**
+ * Performance metrics
+ */
+export interface ValidationMetrics {
+    /** Total validations performed */
+    totalValidations: number;
+    /** Cache hits */
+    cacheHits: number;
+    /** Cache misses */
+    cacheMisses: number;
+    /** Average validation time (ms) */
+    averageValidationTime: number;
+    /** Batched validations */
+    batchedValidations: number;
+    /** Skipped validations (incremental) */
+    skippedValidations: number;
+}
+/**
+ * Validation performance optimizer
+ */
+export declare class ValidationPerformanceOptimizer {
+    private config;
+    private cache;
+    private batchQueue;
+    private batchTimeout;
+    private metrics;
+    private validationTimes;
+    constructor(config?: ValidationPerformanceConfig);
+    /**
+     * Create a hash of a value for caching
+     */
+    private createValueHash;
+    /**
+     * Check if cache entry is valid
+     */
+    private isCacheEntryValid;
+    /**
+     * Clean expired cache entries
+     */
+    private cleanCache;
+    /**
+     * Get cached validation result
+     */
+    private getCachedResult;
+    /**
+     * Cache validation result
+     */
+    private setCachedResult;
+    /**
+     * Process validation batch
+     */
+    private processBatch;
+    /**
+     * Record validation timing
+     */
+    private recordValidationTime;
+    /**
+     * Optimized validation with caching, batching, and performance tracking
+     */
+    validateOptimized(value: unknown, validator: ValidateFunction, cacheKey: string, options?: {
+        priority?: number;
+        dependencies?: string[];
+        skipIncremental?: boolean;
+    }): Promise<ControllerValidation>;
+    /**
+     * Invalidate cache entries that depend on changed fields
+     */
+    invalidateDependentCache(changedFields: string[]): void;
+    /**
+     * Check if incremental validation should be skipped
+     */
+    shouldSkipValidation(newValue: unknown, oldValue: unknown, _fieldPath: string): boolean;
+    /**
+     * Get performance metrics
+     */
+    getMetrics(): ValidationMetrics;
+    /**
+     * Reset performance metrics
+     */
+    resetMetrics(): void;
+    /**
+     * Clear all caches
+     */
+    clearCache(): void;
+    /**
+     * Get cache statistics
+     */
+    getCacheStats(): {
+        size: number;
+        hitRate: number;
+        averageAge: number;
+    };
+    /**
+     * Dispose of resources
+     */
+    dispose(): void;
+}

package/dist/types/components/json-schema/validator.d.ts

@@ -0,0 +1,10 @@
+import type { StandardSchemaV1 } from '../form/schema/standard-schema-v1';
+import Ajv, { type JSONSchemaType } from 'ajv';
+/**
+ * Create a StandardSchemaV1 validator from a JSON Schema using AJV.
+ * - Vendor: 'ajv'
+ * - Returns StandardSchemaV1-compliant validate() that maps AJV errors to standard issues
+ */
+export declare function createAJVStandardSchema<T = unknown>(schema: JSONSchemaType<T>, options?: {
+    ajv?: Ajv;
+}): StandardSchemaV1<T>;

package/dist/types/components/json-schema/visibility/visibility-evaluation.d.ts

@@ -0,0 +1,77 @@
+import type { JSONSchema } from '../schema-context';
+import { type Signal } from '@tempots/dom';
+/**
+ * Visibility condition configuration
+ */
+export interface VisibilityCondition {
+    /** Field path to watch (relative to current context) */
+    field: string;
+    /** Comparison operator */
+    operator: 'equals' | 'notEquals' | 'truthy' | 'falsy' | 'contains' | 'notContains' | 'greaterThan' | 'lessThan' | 'greaterThanOrEqual' | 'lessThanOrEqual' | 'in' | 'notIn';
+    /** Value to compare against (not needed for truthy/falsy) */
+    value?: unknown;
+    /** Multiple values for 'in'/'notIn' operators */
+    values?: unknown[];
+}
+/**
+ * Complex visibility expression
+ */
+export interface VisibilityExpression {
+    /** Logical operator */
+    operator: 'and' | 'or' | 'not';
+    /** Child conditions or expressions */
+    conditions: (VisibilityCondition | VisibilityExpression)[];
+}
+/**
+ * Visibility configuration from x:ui
+ */
+export type VisibilityConfig = VisibilityCondition | VisibilityExpression | string;
+/**
+ * Extract visibility configuration from schema x:ui
+ */
+export declare function getVisibilityConfig(schema: JSONSchema): VisibilityConfig | undefined;
+/**
+ * Evaluate visibility configuration against form data
+ */
+export declare function evaluateVisibility(config: VisibilityConfig, formData: unknown): boolean;
+/**
+ * Create a reactive visibility signal based on form data
+ */
+export declare function createVisibilitySignal(config: VisibilityConfig, formDataSignal: Signal<unknown>): Signal<boolean>;
+/**
+ * Get all field paths referenced in a visibility configuration
+ */
+export declare function getReferencedFields(config: VisibilityConfig): string[];
+/**
+ * Helper to create common visibility conditions
+ */
+export declare const VisibilityConditions: {
+    /**
+     * Field equals specific value
+     */
+    equals: (field: string, value: unknown) => VisibilityCondition;
+    /**
+     * Field is truthy
+     */
+    truthy: (field: string) => VisibilityCondition;
+    /**
+     * Field is falsy
+     */
+    falsy: (field: string) => VisibilityCondition;
+    /**
+     * Field value is in array
+     */
+    in: (field: string, values: unknown[]) => VisibilityCondition;
+    /**
+     * Combine conditions with AND
+     */
+    and: (...conditions: (VisibilityCondition | VisibilityExpression)[]) => VisibilityExpression;
+    /**
+     * Combine conditions with OR
+     */
+    or: (...conditions: (VisibilityCondition | VisibilityExpression)[]) => VisibilityExpression;
+    /**
+     * Negate condition
+     */
+    not: (condition: VisibilityCondition | VisibilityExpression) => VisibilityExpression;
+};

package/dist/types/components/json-schema/visibility/visibility-wrapper.d.ts

@@ -0,0 +1,56 @@
+import { Renderable } from '@tempots/dom';
+import type { Controller } from '../../form';
+import type { SchemaContext } from '../schema-context';
+import { type VisibilityConfig, type VisibilityCondition, type VisibilityExpression } from './visibility-evaluation';
+/**
+ * Visibility behavior options
+ */
+export interface VisibilityOptions {
+    /** How to handle hidden fields */
+    behavior: 'hide' | 'unmount';
+    /** Whether to clear field value when hidden */
+    clearOnHide?: boolean;
+}
+/**
+ * Wrapper component that handles field visibility based on x:ui.visibleIf
+ */
+export declare function WithVisibility<T>({ ctx, controller, children, options, }: {
+    ctx: SchemaContext;
+    controller: Controller<T>;
+    children: Renderable;
+    options?: Partial<VisibilityOptions>;
+}): Renderable;
+/**
+ * Enhanced visibility wrapper that also handles CSS classes for hiding
+ */
+export declare function WithVisibilityAndCSS<T>({ ctx, controller, children, options, }: {
+    ctx: SchemaContext;
+    controller: Controller<T>;
+    children: Renderable;
+    options?: Partial<VisibilityOptions>;
+    hiddenClass?: string;
+}): Renderable;
+/**
+ * Utility to check if a schema has visibility conditions
+ */
+export declare function hasVisibilityConditions(ctx: SchemaContext): boolean;
+/**
+ * Utility to get all fields referenced by visibility conditions in a schema
+ */
+export declare function getVisibilityDependencies(ctx: SchemaContext): string[];
+/**
+ * Helper to create visibility conditions programmatically
+ */
+export declare function createVisibilityCondition(field: string, operator: 'equals' | 'notEquals' | 'truthy' | 'falsy', value?: unknown): VisibilityConfig;
+/**
+ * Helper to create complex visibility expressions
+ */
+export declare function createVisibilityExpression(operator: 'and' | 'or' | 'not', conditions: (VisibilityCondition | VisibilityExpression)[]): VisibilityExpression;
+/**
+ * Validation helper to check if visibility configuration is valid
+ */
+export declare function validateVisibilityConfig(config: unknown): config is VisibilityConfig;
+/**
+ * Debug helper to log visibility evaluation
+ */
+export declare function debugVisibility(config: VisibilityConfig, formData: unknown, fieldPath?: string): void;

package/dist/types/components/json-schema/widgets/enhanced-widgets.d.ts

@@ -0,0 +1,70 @@
+import { Renderable } from '@tempots/dom';
+import { type Controller } from '../../form';
+/**
+ * File upload widget configuration
+ */
+export interface FileUploadConfig {
+    /** Accepted file types (MIME types or extensions) */
+    accept?: string[];
+    /** Maximum file size in bytes */
+    maxSize?: number;
+    /** Allow multiple files */
+    multiple?: boolean;
+    /** Upload endpoint URL */
+    uploadUrl?: string;
+    /** Custom upload handler */
+    onUpload?: (files: FileList) => Promise<string | string[]>;
+    /** Preview mode for images */
+    showPreview?: boolean;
+}
+/**
+ * Rich text editor configuration
+ */
+export interface RichTextConfig {
+    /** Toolbar options */
+    toolbar?: ('bold' | 'italic' | 'underline' | 'link' | 'list' | 'heading')[];
+    /** Maximum length */
+    maxLength?: number;
+    /** Placeholder text */
+    placeholder?: string;
+    /** Output format */
+    format?: 'html' | 'markdown' | 'text';
+}
+/**
+ * Code editor configuration
+ */
+export interface CodeEditorConfig {
+    /** Programming language */
+    language?: string;
+    /** Theme */
+    theme?: 'light' | 'dark' | 'auto';
+    /** Show line numbers */
+    lineNumbers?: boolean;
+    /** Enable syntax highlighting */
+    syntaxHighlighting?: boolean;
+    /** Tab size */
+    tabSize?: number;
+    /** Enable code folding */
+    codeFolding?: boolean;
+}
+/**
+ * File upload widget
+ */
+export declare function FileUploadWidget({ controller, config, }: {
+    controller: Controller<string | string[] | null>;
+    config?: FileUploadConfig;
+}): Renderable;
+/**
+ * Rich text editor widget (simplified implementation)
+ */
+export declare function RichTextWidget({ controller, config, }: {
+    controller: Controller<string | null>;
+    config?: RichTextConfig;
+}): Renderable;
+/**
+ * Code editor widget (simplified implementation)
+ */
+export declare function CodeEditorWidget({ controller, config, }: {
+    controller: Controller<string | null>;
+    config?: CodeEditorConfig;
+}): Renderable;

package/dist/types/components/json-schema/widgets/string-controls.d.ts

@@ -0,0 +1,8 @@
+import { Controller, InputWrapperOptions } from '@/components/form';
+import { SchemaContext } from '../schema-context';
+import { Renderable } from '@tempots/dom';
+export declare function StringControl({ ctx, options, controller, }: {
+    ctx: SchemaContext;
+    options: Partial<InputWrapperOptions>;
+    controller: Controller<string | undefined>;
+}): Renderable;

package/dist/types/components/json-schema/widgets/string-detection.d.ts

@@ -0,0 +1,3 @@
+import { AnyStringWidgetOptions } from './string-type';
+import { SchemaContext } from '../schema-context';
+export declare function stringFormatDetection(ctx: SchemaContext): AnyStringWidgetOptions | undefined;

package/dist/types/components/json-schema/widgets/string-type.d.ts

@@ -0,0 +1,62 @@
+export type StringWidgetOptions = {
+    pattern?: string;
+    minLength?: number;
+    maxLength?: number;
+};
+export type BinaryWidgetOptions = StringWidgetOptions & {
+    format: 'binary';
+    mediaType?: string;
+};
+export type DateTimeWidgetOptions = StringWidgetOptions & {
+    format: 'date-time';
+};
+export type DateWidgetOptions = StringWidgetOptions & {
+    format: 'date';
+};
+export type EmailWidgetOptions = StringWidgetOptions & {
+    format: 'email';
+};
+export type MarkdownWidgetOptions = StringWidgetOptions & {
+    format: 'markdown';
+};
+export type PasswordWidgetOptions = StringWidgetOptions & {
+    format: 'password';
+};
+export type TextAreaWidgetOptions = StringWidgetOptions & {
+    format: 'textarea';
+    rows?: number;
+};
+export type TimeWidgetOptions = StringWidgetOptions & {
+    format: 'time';
+};
+export type UUIDWidgetOptions = StringWidgetOptions & {
+    format: 'uuid';
+};
+export type URIWidgetOptions = StringWidgetOptions & {
+    format: 'uri';
+};
+export type URLWidgetOptions = StringWidgetOptions & {
+    format: 'url';
+};
+export type URIReferenceWidgetOptions = StringWidgetOptions & {
+    format: 'uri-reference';
+};
+export type HostnameWidgetOptions = StringWidgetOptions & {
+    format: 'hostname';
+};
+export type IPv4WidgetOptions = StringWidgetOptions & {
+    format: 'ipv4';
+};
+export type IPv6WidgetOptions = StringWidgetOptions & {
+    format: 'ipv6';
+};
+export type RegexWidgetOptions = StringWidgetOptions & {
+    format: 'regex';
+};
+export type DurationWidgetOptions = StringWidgetOptions & {
+    format: 'duration';
+};
+export type ColorWidgetOptions = StringWidgetOptions & {
+    format: 'color';
+};
+export type AnyStringWidgetOptions = BinaryWidgetOptions | DateTimeWidgetOptions | DateWidgetOptions | EmailWidgetOptions | MarkdownWidgetOptions | PasswordWidgetOptions | TextAreaWidgetOptions | TimeWidgetOptions | UUIDWidgetOptions | URIWidgetOptions | URLWidgetOptions | URIReferenceWidgetOptions | HostnameWidgetOptions | IPv4WidgetOptions | IPv6WidgetOptions | RegexWidgetOptions | DurationWidgetOptions | ColorWidgetOptions;

package/dist/types/components/json-schema/widgets/utils.d.ts

@@ -0,0 +1,45 @@
+import { JSONSchema } from '../schema-context';
+/**
+ * Unified x:ui configuration types
+ */
+export type XUIString = string;
+export interface XUIObject {
+    /** Widget type - takes precedence over format */
+    widget?: string;
+    /** Format type - fallback if widget not specified */
+    format?: string;
+    /** Widget-specific options */
+    [key: string]: unknown;
+}
+export type XUIConfig = XUIString | XUIObject;
+/**
+ * Resolved widget information with precedence applied
+ */
+export interface ResolvedWidget {
+    /** The effective widget type */
+    widget: string;
+    /** Source of the widget selection for debugging */
+    source: 'explicit-widget' | 'explicit-format' | 'schema-format' | 'schema-media' | 'constraints' | 'heuristics' | 'type-fallback';
+    /** Additional options from x:ui object */
+    options?: Record<string, unknown>;
+}
+/**
+ * Extract x:ui configuration from schema definition
+ */
+export declare function getXUIConfig(definition: JSONSchema): XUIConfig | undefined;
+/**
+ * Resolve effective widget with precedence rules:
+ * 1. Explicit x:ui.widget
+ * 2. Explicit x:ui.format (or x:ui as string)
+ * 3. Schema format property
+ * 4. Schema contentMediaType/contentEncoding
+ * 5. Schema constraints (enum, const, min/max, etc.)
+ * 6. Heuristics (property names, length bounds)
+ * 7. Type fallback
+ */
+export declare function resolveWidget(definition: JSONSchema, propertyName?: string): ResolvedWidget | undefined;
+/**
+ * Legacy function for backward compatibility
+ * @deprecated Use resolveWidget instead
+ */
+export declare function getUIFormat(definition: JSONSchema): string | undefined;

package/dist/types/components/json-schema/widgets/widget-composition.d.ts

@@ -0,0 +1,144 @@
+import type { Renderable } from '@tempots/dom';
+import type { Controller } from '../../form';
+import type { SchemaContext, JSONSchemaDefinition } from '../schema-context';
+import type { WidgetFactory } from './widget-customization';
+/**
+ * Widget composition configuration
+ */
+export interface WidgetComposition {
+    /** Layout type for composition */
+    layout: 'horizontal' | 'vertical' | 'grid' | 'tabs' | 'accordion' | 'custom';
+    /** Widgets to compose */
+    widgets: ComposedWidget[];
+    /** Layout-specific options */
+    layoutOptions?: {
+        /** Grid columns (for grid layout) */
+        columns?: number;
+        /** Gap between widgets */
+        gap?: string;
+        /** Alignment */
+        align?: 'start' | 'center' | 'end' | 'stretch';
+        /** Custom CSS classes */
+        className?: string;
+    };
+    /** Conditional composition rules */
+    conditions?: CompositionCondition[];
+}
+/**
+ * Individual widget in a composition
+ */
+export interface ComposedWidget {
+    /** Widget type/name */
+    type: string;
+    /** Widget-specific configuration */
+    config?: Record<string, unknown>;
+    /** Widget label/title */
+    label?: string;
+    /** Widget description */
+    description?: string;
+    /** Conditional visibility */
+    condition?: string | ((value: unknown, formData: unknown) => boolean);
+    /** Layout constraints */
+    layout?: {
+        /** Grid column span */
+        colSpan?: number;
+        /** Grid row span */
+        rowSpan?: number;
+        /** Flex grow factor */
+        grow?: number;
+        /** Flex shrink factor */
+        shrink?: number;
+        /** Minimum width */
+        minWidth?: string;
+        /** Maximum width */
+        maxWidth?: string;
+    };
+    /** Custom styling */
+    style?: Record<string, string>;
+    /** Custom CSS classes */
+    className?: string;
+}
+/**
+ * Composition condition for dynamic widget selection
+ */
+export interface CompositionCondition {
+    /** Condition to evaluate */
+    condition: string | ((value: unknown, formData: unknown) => boolean);
+    /** Composition to use when condition is true */
+    then: WidgetComposition;
+    /** Composition to use when condition is false */
+    else?: WidgetComposition;
+}
+/**
+ * Widget composition renderer
+ */
+export declare class WidgetComposer {
+    private widgetFactories;
+    /**
+     * Register a widget factory for composition
+     */
+    registerWidget(name: string, factory: WidgetFactory): void;
+    /**
+     * Unregister a widget factory
+     */
+    unregisterWidget(name: string): void;
+    /**
+     * Render a composed widget
+     */
+    renderComposition(composition: WidgetComposition, controller: Controller<unknown>, ctx: SchemaContext): Renderable;
+    /**
+     * Evaluate composition conditions
+     */
+    private evaluateConditions;
+    /**
+     * Evaluate widget visibility condition
+     */
+    private evaluateWidgetCondition;
+    /**
+     * Evaluate a condition
+     */
+    private evaluateCondition;
+    /**
+     * Render an individual widget
+     */
+    private renderWidget;
+    /**
+     * Wrap widget with layout constraints and styling
+     */
+    private wrapWidget;
+    /**
+     * Apply layout to rendered widgets
+     */
+    private applyLayout;
+}
+/**
+ * Global widget composer instance
+ */
+export declare const globalWidgetComposer: WidgetComposer;
+/**
+ * Extract widget composition from schema x:ui
+ */
+export declare function getWidgetComposition(schema: JSONSchemaDefinition): WidgetComposition | undefined;
+/**
+ * Helper to create a simple horizontal composition
+ */
+export declare function createHorizontalComposition(widgets: Array<{
+    type: string;
+    config?: Record<string, unknown>;
+    label?: string;
+}>, options?: {
+    gap?: string;
+    align?: 'start' | 'center' | 'end' | 'stretch';
+}): WidgetComposition;
+/**
+ * Helper to create a simple grid composition
+ */
+export declare function createGridComposition(widgets: Array<{
+    type: string;
+    config?: Record<string, unknown>;
+    label?: string;
+    colSpan?: number;
+    rowSpan?: number;
+}>, columns: number, options?: {
+    gap?: string;
+}): WidgetComposition;