@tempots/beatui 0.69.0 → 0.71.0

package/dist/types/components/json-structure/controls/enum-const-controls.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Enum and Const Controls for JSON Structure
+ *
+ * Handles enum selection and const value display
+ */
+import { Renderable } from '@tempots/dom';
+import { type Controller } from '../../form';
+import type { StructureContext } from '../structure-context';
+/**
+ * Control for enum schemas
+ */
+export declare function StructureEnumControl({ ctx, controller, }: {
+    ctx: StructureContext;
+    controller: Controller<unknown>;
+}): Renderable;
+/**
+ * Control for const schemas
+ */
+export declare function StructureConstControl({ ctx, controller, }: {
+    ctx: StructureContext;
+    controller: Controller<unknown>;
+}): Renderable;

package/dist/types/components/json-structure/controls/generic-control.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Generic Control Dispatcher
+ *
+ * Routes to appropriate control based on type definition.
+ */
+import { Renderable } from '@tempots/dom';
+import { type Controller } from '../../form';
+import type { StructureContext } from '../structure-context';
+import type { JSONStructureSchema } from '../structure-types';
+import type { WidgetRegistry } from '../widgets/widget-registry';
+/**
+ * Props for the generic control
+ */
+export interface GenericControlProps<T = unknown> {
+    controller: Controller<T>;
+    ctx: StructureContext;
+}
+/**
+ * Generic control dispatcher that routes to appropriate control based on type
+ */
+export declare function StructureGenericControl<T>({ ctx, controller, }: GenericControlProps<T>): Renderable;
+/**
+ * Main entry point for JSON Structure controls
+ */
+export declare function StructureControl<T>({ schema, controller, widgetRegistry, readOnly, locale, }: {
+    schema: JSONStructureSchema;
+    controller: Controller<T>;
+    widgetRegistry?: WidgetRegistry;
+    readOnly?: boolean;
+    locale?: string;
+}): Renderable;

package/dist/types/components/json-structure/controls/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Controls module exports
+ */
+export * from './generic-control';
+export * from './string-control';
+export * from './boolean-control';
+export * from './integer-control';
+export * from './decimal-control';
+export * from './uuid-control';
+export * from './temporal-control';
+export * from './uri-control';
+export * from './binary-control';
+export * from './any-control';
+export * from './object-control';
+export * from './array-control';
+export * from './set-control';
+export * from './map-control';
+export * from './tuple-control';
+export * from './choice-control';
+export * from './enum-const-controls';
+export * from './union-control';

package/dist/types/components/json-structure/controls/integer-control.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Integer Control for JSON Structure
+ *
+ * Handles all integer types (int8/16/32/64/128, uint8/16/32/64/128)
+ * with appropriate Number or BigInt inputs
+ */
+import { Renderable } from '@tempots/dom';
+import { type Controller } from '../../form';
+import type { StructureContext } from '../structure-context';
+import { type IntegerType } from '../structure-types';
+/**
+ * Control for integer types
+ */
+export declare function StructureIntegerControl({ ctx, controller, intType, }: {
+    ctx: StructureContext;
+    controller: Controller<number | bigint | null>;
+    intType: IntegerType;
+}): Renderable;

package/dist/types/components/json-structure/controls/map-control.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Map Control for JSON Structure
+ *
+ * Handles map type with key-value pairs and minProperties/maxProperties constraints
+ */
+import { Renderable } from '@tempots/dom';
+import { ObjectController } from '../../form';
+import type { StructureContext } from '../structure-context';
+/**
+ * Control for map type (key-value pairs)
+ */
+export declare function StructureMapControl({ ctx, controller, }: {
+    ctx: StructureContext;
+    controller: ObjectController<{
+        [key: string]: unknown;
+    }>;
+}): Renderable;

package/dist/types/components/json-structure/controls/object-control.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Object Control for JSON Structure
+ *
+ * Handles object type with properties and additionalProperties support
+ */
+import { Renderable } from '@tempots/dom';
+import { ObjectController } from '../../form';
+import type { StructureContext } from '../structure-context';
+/**
+ * Control for object type
+ */
+export declare function StructureObjectControl({ ctx, controller, }: {
+    ctx: StructureContext;
+    controller: ObjectController<{
+        [key: string]: unknown;
+    }>;
+}): Renderable;

package/dist/types/components/json-structure/controls/set-control.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Set Control for JSON Structure
+ *
+ * Handles set type with items definition, uniqueness validation, and minItems/maxItems constraints
+ */
+import { Renderable } from '@tempots/dom';
+import { ArrayController } from '../../form';
+import type { StructureContext } from '../structure-context';
+/**
+ * Control for set type (array with uniqueness enforcement)
+ */
+export declare function StructureSetControl({ ctx, controller, }: {
+    ctx: StructureContext;
+    controller: ArrayController<unknown[]>;
+}): Renderable;

package/dist/types/components/json-structure/controls/string-control.d.ts

@@ -0,0 +1,15 @@
+/**
+ * String Control for JSON Structure
+ *
+ * Handles string type with TextInput
+ */
+import { Renderable } from '@tempots/dom';
+import { type Controller } from '../../form';
+import type { StructureContext } from '../structure-context';
+/**
+ * Control for string type
+ */
+export declare function StructureStringControl({ ctx, controller, }: {
+    ctx: StructureContext;
+    controller: Controller<string | undefined>;
+}): Renderable;

package/dist/types/components/json-structure/controls/temporal-control.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Temporal Control for JSON Structure
+ *
+ * Handles date, datetime, time, and duration types with appropriate temporal inputs
+ */
+import { Renderable } from '@tempots/dom';
+import { type Controller } from '../../form';
+import type { StructureContext } from '../structure-context';
+import type { TemporalType } from '../structure-types';
+import { Temporal } from '@js-temporal/polyfill';
+/**
+ * Control for temporal types (date, datetime, time, duration)
+ */
+export declare function StructureTemporalControl({ ctx, controller, temporalType, }: {
+    ctx: StructureContext;
+    controller: Controller<Temporal.PlainDate | Temporal.PlainDateTime | Temporal.PlainTime | Temporal.Duration | null>;
+    temporalType: TemporalType;
+}): Renderable;

package/dist/types/components/json-structure/controls/tuple-control.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Tuple Control for JSON Structure
+ *
+ * Handles tuple type with fixed-length ordered elements.
+ * Each element has a named definition, but serializes to a JSON array in the specified order.
+ */
+import { Renderable } from '@tempots/dom';
+import { ArrayController } from '../../form';
+import type { StructureContext } from '../structure-context';
+/**
+ * Control for tuple type
+ *
+ * Tuples are fixed-length arrays where each position has a specific type.
+ * The `tuple` array defines the order of elements by referencing keys in `properties`.
+ */
+export declare function StructureTupleControl({ ctx, controller, }: {
+    ctx: StructureContext;
+    controller: ArrayController<unknown[]>;
+}): Renderable;

package/dist/types/components/json-structure/controls/union-control.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Union Control for JSON Structure
+ *
+ * Handles union types (type arrays) like ["string", "number"] or ["string", "null"]
+ */
+import { Renderable } from '@tempots/dom';
+import { type Controller } from '../../form';
+import type { StructureContext } from '../structure-context';
+/**
+ * Control for union type definitions
+ */
+export declare function StructureUnionControl<T>({ ctx, controller, }: {
+    ctx: StructureContext;
+    controller: Controller<T>;
+}): Renderable;

package/dist/types/components/json-structure/controls/uri-control.d.ts

@@ -0,0 +1,15 @@
+/**
+ * URI Control for JSON Structure
+ *
+ * Handles uri type with URLInput
+ */
+import { Renderable } from '@tempots/dom';
+import { type Controller } from '../../form';
+import type { StructureContext } from '../structure-context';
+/**
+ * Control for uri type
+ */
+export declare function StructureUriControl({ ctx, controller, }: {
+    ctx: StructureContext;
+    controller: Controller<string | undefined>;
+}): Renderable;

package/dist/types/components/json-structure/controls/uuid-control.d.ts

@@ -0,0 +1,15 @@
+/**
+ * UUID Control for JSON Structure
+ *
+ * Handles uuid type with UUIDInput
+ */
+import { Renderable } from '@tempots/dom';
+import { type Controller } from '../../form';
+import type { StructureContext } from '../structure-context';
+/**
+ * Control for uuid type
+ */
+export declare function StructureUuidControl({ ctx, controller, }: {
+    ctx: StructureContext;
+    controller: Controller<string | undefined>;
+}): Renderable;

package/dist/types/components/json-structure/extends-utils.d.ts

@@ -0,0 +1,36 @@
+/**
+ * $extends Inheritance Utilities for JSON Structure
+ *
+ * Handles resolution of $extends inheritance within JSON Structure schemas.
+ */
+import type { JSONStructureSchema, TypeDefinition } from './structure-types';
+import { RefResolver } from './ref-utils';
+/**
+ * Result of resolving inheritance
+ */
+export interface InheritanceResult {
+    /** The merged type definition with all inherited properties */
+    merged: TypeDefinition;
+    /** Chain of base types (from most base to most derived) */
+    inheritanceChain: string[];
+    /** Any errors encountered during resolution */
+    errors: InheritanceError[];
+}
+export interface InheritanceError {
+    path: string;
+    message: string;
+}
+/**
+ * Resolve $extends for a type definition
+ *
+ * Properties are merged with derived type taking precedence over base types.
+ * For multiple inheritance, types are processed left-to-right with later
+ * types taking precedence.
+ */
+export declare function resolveExtends(definition: TypeDefinition, schema: JSONStructureSchema, _refResolver?: RefResolver): InheritanceResult;
+/**
+ * Create an extends resolver for a schema (convenience function)
+ */
+export declare function createExtendsResolver(schema: JSONStructureSchema): {
+    resolve: (definition: TypeDefinition) => InheritanceResult;
+};

package/dist/types/components/json-structure/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * JSON Structure Form Components
+ *
+ * @packageDocumentation
+ */
+export * from './structure-types';
+export { StructureContext, createStructureContext } from './structure-context';
+export type { StructureContextOptions, StructureContextUpdates, } from './structure-context';
+export { resolveRef, resolveTypeReference, parseRefPath, RefResolver, createRefResolver, } from './ref-utils';
+export { resolveExtends, createExtendsResolver } from './extends-utils';
+export type { InheritanceResult, InheritanceError } from './extends-utils';
+export { StructureGenericControl, StructureControl, } from './controls/generic-control';
+export type { GenericControlProps } from './controls/generic-control';
+export { createValidator, validate } from './validation/sdk-validator';
+export type { ValidationResult, ValidatorOptions, StructureValidator, } from './validation/sdk-validator';
+export { formatValidationError, formatValidationErrors, groupErrorsByPath, getErrorsForPath, hasErrorsAtPath, getChildErrors, } from './validation/error-transform';
+export type { RawValidationError, FormattedValidationError, } from './validation/error-transform';
+export { DefaultWidgetRegistry, getGlobalWidgetRegistry, setGlobalWidgetRegistry, createWidgetRegistry, forType, forFormat, forTypeAndFormat, forMatcher, } from './widgets/widget-registry';
+export type { WidgetProps, WidgetFactory, WidgetRegistration, ResolvedWidget, WidgetRegistry, WidgetRegistrationOptions, } from './widgets/widget-registry';
+export { resolveWidget, getWidgetOptions, getExplicitWidgetName, hasCustomWidget, resolveWidgetWithOverride, mergeWidgetOptions, } from './widgets/widget-utils';
+export type { WidgetOptions } from './widgets/widget-utils';
+export { registerDefaultWidgets, hasDefaultWidgets, ensureDefaultWidgets, } from './widgets/default-widgets';
+export { extractStructureDefaults } from './structure-defaults';
+export { JSONStructureForm } from './json-structure-form';
+export type { JSONStructureFormProps, ValidationMode, } from './json-structure-form';

package/dist/types/components/json-structure/json-structure-form.d.ts

@@ -0,0 +1,96 @@
+/**
+ * JSON Structure Form Component
+ *
+ * Main form component for JSON Structure schema-based forms.
+ * Provides validation, error handling, and form state management.
+ */
+import { Value, Renderable } from '@tempots/dom';
+import { Controller, ControllerValidation } from '../form';
+import { FormattedValidationError } from './validation/error-transform';
+import type { JSONStructureSchema } from './structure-types';
+import type { WidgetRegistry } from './widgets/widget-registry';
+/**
+ * Validation mode for the form
+ * - 'onSubmit': Validate only when form is submitted
+ * - 'onTouched': Validate fields after they are touched
+ * - 'eager': Validate fields as they change
+ */
+export type ValidationMode = 'onSubmit' | 'onTouched' | 'eager';
+/**
+ * Props for JSONStructureForm component
+ */
+export interface JSONStructureFormProps<T> {
+    /** The JSON Structure schema to render as a form */
+    schema: JSONStructureSchema;
+    /**
+     * Initial value for the form data.
+     *
+     * When omitted, the form will be auto-populated from schema defaults:
+     * - `default` property values (highest priority)
+     * - First item from `examples` array (fallback)
+     * - Empty object for object schemas (last resort)
+     *
+     * When provided, schema defaults are merged with the provided value
+     * (provided values take precedence) unless `applySchemaDefaults` is false.
+     */
+    initialValue?: Value<T>;
+    /** Validation behavior - when to validate the form */
+    validationMode?: ValidationMode;
+    /** Debounce delay in milliseconds for validation */
+    validateDebounceMs?: number;
+    /** Optional widget registry for custom widgets */
+    widgetRegistry?: WidgetRegistry;
+    /** Make all fields read-only */
+    readOnly?: boolean;
+    /** Locale for internationalization */
+    locale?: string;
+    /** Called when form value changes */
+    onChange?: (value: T) => void;
+    /** Called when validation runs */
+    onValidate?: (errors: FormattedValidationError[]) => void;
+    /**
+     * Whether to automatically populate form values from schema defaults.
+     * When true, extracts `default` values (with `examples[0]` as fallback)
+     * from the schema and merges them with the provided initialValue.
+     * Provided values take precedence over schema defaults.
+     *
+     * @default true
+     */
+    applySchemaDefaults?: boolean;
+}
+/**
+ * JSON Structure Form Component
+ *
+ * Renders a complete form based on a JSON Structure schema with validation.
+ *
+ * @example
+ * ```typescript
+ * JSONStructureForm(
+ *   {
+ *     schema: mySchema,
+ *     initialValue: prop(initialData),
+ *     validationMode: 'onTouched',
+ *   },
+ *   ({ Form, controller, setStatus }) => {
+ *     return html.form(
+ *       on.submit(async (e) => {
+ *         e.preventDefault()
+ *         // Validate and submit
+ *         const value = controller.signal.value
+ *         // ... handle submission
+ *       }),
+ *       Form,
+ *       html.button(
+ *         attr.type('submit'),
+ *         'Submit'
+ *       )
+ *     )
+ *   }
+ * )
+ * ```
+ */
+export declare function JSONStructureForm<T>({ schema, initialValue, validationMode, validateDebounceMs, widgetRegistry, readOnly, locale, onChange, onValidate, applySchemaDefaults, }: JSONStructureFormProps<T>, fn: ({ Form, controller, setStatus, }: {
+    Form: Renderable;
+    controller: Controller<T>;
+    setStatus: (result: ControllerValidation) => void;
+}) => Renderable): Renderable;

package/dist/types/components/json-structure/ref-utils.d.ts

@@ -0,0 +1,55 @@
+/**
+ * $ref Resolution Utilities for JSON Structure
+ *
+ * Handles resolution of $ref references within JSON Structure schemas.
+ */
+import type { JSONStructureSchema, TypeDefinition, Namespace, TypeReference } from './structure-types';
+/**
+ * Parse a $ref path into segments
+ * Examples:
+ *   "#/definitions/Address" -> ["definitions", "Address"]
+ *   "#/definitions/Types/Email" -> ["definitions", "Types", "Email"]
+ *   "Address" -> ["definitions", "Address"] (shorthand)
+ */
+export declare function parseRefPath(ref: string): string[];
+/**
+ * Resolve a $ref path to its definition within the schema
+ */
+export declare function resolveRefPath(schema: JSONStructureSchema, segments: string[]): TypeDefinition | Namespace | undefined;
+/**
+ * Resolve a $ref string to its type definition
+ */
+export declare function resolveRef(ref: string, schema: JSONStructureSchema): TypeDefinition | undefined;
+/**
+ * Resolve a TypeReference object to its type definition
+ */
+export declare function resolveTypeReference(ref: TypeReference, schema: JSONStructureSchema): TypeDefinition | undefined;
+/**
+ * Check if a definition contains a $ref and resolve it if so
+ * Returns the resolved definition merged with any sibling properties
+ */
+export declare function resolveDefinitionRef(definition: TypeDefinition, schema: JSONStructureSchema): TypeDefinition;
+/**
+ * Track visited refs to detect circular references
+ */
+export declare class RefResolver {
+    private readonly schema;
+    private readonly visited;
+    constructor(schema: JSONStructureSchema);
+    /**
+     * Resolve a reference, tracking visited refs to prevent infinite loops
+     */
+    resolve(ref: string): TypeDefinition | undefined;
+    /**
+     * Resolve a type definition, handling any $ref in its type specifier
+     */
+    resolveDefinition(definition: TypeDefinition): TypeDefinition;
+    /**
+     * Reset the visited tracking (use between independent resolution calls)
+     */
+    reset(): void;
+}
+/**
+ * Create a ref resolver for a schema
+ */
+export declare function createRefResolver(schema: JSONStructureSchema): RefResolver;

package/dist/types/components/json-structure/structure-context.d.ts

@@ -0,0 +1,176 @@
+/**
+ * Structure Context
+ *
+ * Immutable context object threaded through the form rendering tree.
+ * Provides access to schema, definition, path, and computed properties.
+ */
+import type { JSONStructureSchema, TypeDefinition, TypeKeyword, Altnames } from './structure-types';
+import { RefResolver } from './ref-utils';
+import type { WidgetRegistry } from './widgets/widget-registry';
+/**
+ * Options for creating a StructureContext
+ */
+export interface StructureContextOptions {
+    /** Root schema document */
+    schema: JSONStructureSchema;
+    /** Current type definition being rendered */
+    definition: TypeDefinition;
+    /** Path from root to current position */
+    path: ReadonlyArray<PropertyKey>;
+    /** Form-level read-only mode */
+    readOnly?: boolean;
+    /** Locale for altnames resolution */
+    locale?: string;
+    /** Custom widget registry */
+    widgetRegistry?: WidgetRegistry;
+    /** Whether this property is required by parent */
+    isPropertyRequired?: boolean;
+    /** Whether to suppress label rendering */
+    suppressLabel?: boolean;
+    /** Shared ref resolver for the schema */
+    refResolver?: RefResolver;
+}
+/**
+ * Updates that can be passed to context.with()
+ */
+export interface StructureContextUpdates {
+    definition?: TypeDefinition;
+    path?: ReadonlyArray<PropertyKey>;
+    readOnly?: boolean;
+    locale?: string;
+    widgetRegistry?: WidgetRegistry;
+    isPropertyRequired?: boolean;
+    suppressLabel?: boolean;
+}
+/**
+ * Immutable context for JSON Structure form rendering
+ */
+export declare class StructureContext {
+    readonly schema: JSONStructureSchema;
+    readonly definition: TypeDefinition;
+    readonly path: ReadonlyArray<PropertyKey>;
+    readonly readOnly: boolean;
+    readonly locale: string | undefined;
+    readonly widgetRegistry: WidgetRegistry | undefined;
+    readonly isPropertyRequired: boolean;
+    readonly suppressLabel: boolean;
+    private readonly refResolver;
+    constructor(options: StructureContextOptions);
+    /**
+     * Create a new context with updated fields
+     */
+    with(updates: StructureContextUpdates): StructureContext;
+    /**
+     * Create a child context by appending to the path
+     */
+    append(segment: PropertyKey): StructureContext;
+    /**
+     * Check if this is the root context
+     */
+    get isRoot(): boolean;
+    /**
+     * Get the property name (last segment of path)
+     */
+    get name(): string | undefined;
+    /**
+     * Get the widget name (dot-separated path)
+     */
+    get widgetName(): string;
+    /**
+     * Get the resolved type(s) from the definition
+     */
+    get resolvedType(): TypeKeyword | TypeKeyword[] | null;
+    /**
+     * Get the primary type (first non-null type)
+     */
+    get primaryType(): TypeKeyword | null;
+    /**
+     * Check if this type is nullable
+     */
+    get isNullable(): boolean;
+    /**
+     * Check if this is a required field
+     */
+    get isRequired(): boolean;
+    /**
+     * Check if this is an optional field (can be absent)
+     */
+    get isOptional(): boolean;
+    /**
+     * Check if this field is deprecated
+     */
+    get isDeprecated(): boolean;
+    /**
+     * Check if this type is abstract
+     */
+    get isAbstract(): boolean;
+    /**
+     * Check if this is a primitive type
+     */
+    get isPrimitive(): boolean;
+    /**
+     * Get the description from the definition
+     */
+    get description(): string | undefined;
+    /**
+     * Get examples from the definition
+     */
+    get examples(): unknown[] | undefined;
+    /**
+     * Get the default value from the definition
+     */
+    get defaultValue(): unknown;
+    /**
+     * Get the unit for numeric values
+     */
+    get unit(): string | undefined;
+    /**
+     * Get the currency for monetary values
+     */
+    get currency(): string | undefined;
+    /**
+     * Get the label for this field
+     *
+     * Resolution order:
+     * 1. Locale-specific altname (if locale is set)
+     * 2. Definition name
+     * 3. Humanized path name
+     */
+    get label(): string;
+    /**
+     * Get altnames from the definition
+     */
+    get altnames(): Altnames | undefined;
+    /**
+     * Get the JSON path string (for validation error matching)
+     */
+    get jsonPath(): string;
+    /**
+     * Resolve a $ref using the shared resolver
+     */
+    resolveRef(ref: string): TypeDefinition | undefined;
+    /**
+     * Check if this definition has an enum constraint
+     */
+    get hasEnum(): boolean;
+    /**
+     * Get enum values if present
+     */
+    get enumValues(): unknown[] | undefined;
+    /**
+     * Check if this definition has a const constraint
+     */
+    get hasConst(): boolean;
+    /**
+     * Get const value if present
+     */
+    get constValue(): unknown;
+    /**
+     * Get string format if defined (for string types)
+     */
+    get format(): string | undefined;
+}
+/**
+ * Create a root context from a schema
+ */
+export declare function createStructureContext(schema: JSONStructureSchema, options?: Partial<Omit<StructureContextOptions, 'schema' | 'definition' | 'path'>>): StructureContext;