@tempots/beatui 0.68.0 → 0.71.0

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;

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

@@ -0,0 +1,46 @@
+/**
+ * JSON Structure Default Value Extraction
+ *
+ * Utilities to recursively extract default values from JSON Structure schema definitions.
+ * Priority order:
+ * 1. Explicit `default` property (highest)
+ * 2. First item of `examples` array
+ * 3. `const` value
+ * 4. First `enum` value
+ * 5. Smart type-based defaults (computed)
+ */
+import type { JSONStructureSchema } from './structure-types';
+/**
+ * Extract default values from a JSON Structure schema.
+ *
+ * Recursively walks the schema and builds an object containing all defined defaults.
+ * For object types, extracts defaults only for required properties.
+ * For nullable types (union with null), returns null.
+ * For arrays/sets with minItems, generates the minimum required items.
+ *
+ * @param schema - The JSON Structure schema
+ * @returns The extracted default value, or undefined if none found
+ *
+ * @example
+ * ```typescript
+ * const schema = {
+ *   $schema: 'https://json-structure.org/draft/2024-12/schema',
+ *   $id: 'example',
+ *   name: 'Example',
+ *   $root: 'Root',
+ *   definitions: {
+ *     Root: {
+ *       type: 'object',
+ *       properties: {
+ *         name: { type: 'string' },
+ *         age: { type: 'int32', minimum: 0, maximum: 120 }
+ *       },
+ *       required: ['name', 'age']
+ *     }
+ *   }
+ * }
+ * const defaults = extractStructureDefaults(schema)
+ * // { name: '', age: 60 }  // only required props, smart defaults
+ * ```
+ */
+export declare function extractStructureDefaults(schema: JSONStructureSchema): unknown;

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

@@ -0,0 +1,173 @@
+/**
+ * JSON Structure Schema Type Definitions
+ *
+ * Based on JSON Structure Core specification
+ * https://json-structure.org/
+ */
+export type PrimitiveType = 'string' | 'boolean' | 'null' | 'int8' | 'int16' | 'int32' | 'int64' | 'int128' | 'uint8' | 'uint16' | 'uint32' | 'uint64' | 'uint128' | 'float' | 'double' | 'decimal' | 'date' | 'datetime' | 'time' | 'duration' | 'uuid' | 'uri' | 'binary';
+export type CompoundType = 'object' | 'array' | 'set' | 'map' | 'tuple' | 'choice' | 'any';
+export type TypeKeyword = PrimitiveType | CompoundType;
+/** Integer types that require BigInt for full precision */
+export type BigIntType = 'int64' | 'int128' | 'uint64' | 'uint128';
+/** Check if a type requires BigInt handling */
+export declare function isBigIntType(type: string): type is BigIntType;
+/** All signed integer types */
+export type SignedIntegerType = 'int8' | 'int16' | 'int32' | 'int64' | 'int128';
+/** All unsigned integer types */
+export type UnsignedIntegerType = 'uint8' | 'uint16' | 'uint32' | 'uint64' | 'uint128';
+/** All integer types */
+export type IntegerType = SignedIntegerType | UnsignedIntegerType;
+/** Check if a type is an integer type */
+export declare function isIntegerType(type: string): type is IntegerType;
+/** All floating-point types */
+export type FloatType = 'float' | 'double' | 'decimal';
+/** Check if a type is a floating-point type */
+export declare function isFloatType(type: string): type is FloatType;
+/** All numeric types */
+export type NumericType = IntegerType | FloatType;
+/** Check if a type is numeric */
+export declare function isNumericType(type: string): type is NumericType;
+/** All temporal types */
+export type TemporalType = 'date' | 'datetime' | 'time' | 'duration';
+/** Check if a type is temporal */
+export declare function isTemporalType(type: string): type is TemporalType;
+/** Check if a type is primitive */
+export declare function isPrimitiveType(type: string): type is PrimitiveType;
+/** Check if a type is compound/complex */
+export declare function isCompoundType(type: string): type is CompoundType;
+export interface TypeReference {
+    $ref: string;
+}
+export type TypeSpecifier = TypeKeyword | TypeKeyword[] | TypeReference;
+/** Check if a value is a type reference */
+export declare function isTypeReference(value: unknown): value is TypeReference;
+export interface StringValidation {
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    format?: string;
+}
+export interface NumericValidation {
+    minimum?: number | string;
+    maximum?: number | string;
+    exclusiveMinimum?: number | string;
+    exclusiveMaximum?: number | string;
+    multipleOf?: number;
+}
+export interface ArrayValidation {
+    minItems?: number;
+    maxItems?: number;
+    uniqueItems?: boolean;
+    contains?: TypeDefinition;
+    minContains?: number;
+    maxContains?: number;
+}
+export interface ObjectValidation {
+    minProperties?: number;
+    maxProperties?: number;
+    dependentRequired?: Record<string, string[]>;
+}
+export interface Altnames {
+    json?: string;
+    [key: `lang:${string}`]: string | undefined;
+}
+export interface TypeMetadata {
+    name?: string;
+    description?: string;
+    examples?: unknown[];
+    deprecated?: boolean;
+    abstract?: boolean;
+    altnames?: Altnames;
+    unit?: string;
+    currency?: string;
+    default?: unknown;
+}
+export interface BaseTypeDefinition extends TypeMetadata {
+    type?: TypeSpecifier;
+    $extends?: string | string[];
+    enum?: unknown[];
+    const?: unknown;
+}
+export interface ObjectTypeDefinition extends BaseTypeDefinition, ObjectValidation {
+    type: 'object';
+    properties: Record<string, TypeDefinition>;
+    required?: string[] | string[][];
+    additionalProperties?: boolean | TypeDefinition;
+}
+export interface ArrayTypeDefinition extends BaseTypeDefinition, ArrayValidation {
+    type: 'array';
+    items: TypeDefinition;
+}
+export interface SetTypeDefinition extends BaseTypeDefinition, ArrayValidation {
+    type: 'set';
+    items: TypeDefinition;
+}
+export interface MapTypeDefinition extends BaseTypeDefinition, ObjectValidation {
+    type: 'map';
+    values: TypeDefinition;
+}
+export interface TupleTypeDefinition extends BaseTypeDefinition {
+    type: 'tuple';
+    properties: Record<string, TypeDefinition>;
+    tuple: string[];
+}
+export interface ChoiceTypeDefinition extends BaseTypeDefinition {
+    type: 'choice';
+    choices: Record<string, TypeDefinition>;
+    selector?: string;
+}
+export interface DecimalTypeDefinition extends BaseTypeDefinition, NumericValidation {
+    type: 'decimal';
+    precision?: number;
+    scale?: number;
+}
+export interface StringTypeDefinition extends BaseTypeDefinition, StringValidation {
+    type: 'string';
+}
+export interface IntegerTypeDefinition extends BaseTypeDefinition, NumericValidation {
+    type: IntegerType;
+}
+export interface FloatTypeDefinition extends BaseTypeDefinition, NumericValidation {
+    type: 'float' | 'double';
+}
+export type TypeDefinition = BaseTypeDefinition | ObjectTypeDefinition | ArrayTypeDefinition | SetTypeDefinition | MapTypeDefinition | TupleTypeDefinition | ChoiceTypeDefinition | DecimalTypeDefinition | StringTypeDefinition | IntegerTypeDefinition | FloatTypeDefinition;
+export interface JSONStructureSchema extends BaseTypeDefinition, ObjectValidation {
+    $schema: string;
+    $id: string;
+    name: string;
+    $root?: string;
+    definitions?: Record<string, TypeDefinition | Namespace>;
+    $uses?: string[];
+    properties?: Record<string, TypeDefinition>;
+    required?: string[] | string[][];
+}
+export interface Namespace {
+    [key: string]: TypeDefinition | Namespace;
+}
+/** Check if a value is a namespace (contains nested definitions but isn't a type itself) */
+export declare function isNamespace(value: unknown): value is Namespace;
+/** Check if a value is a type definition */
+export declare function isTypeDefinition(value: unknown): value is TypeDefinition;
+export declare function isObjectTypeDefinition(def: TypeDefinition): def is ObjectTypeDefinition;
+export declare function isArrayTypeDefinition(def: TypeDefinition): def is ArrayTypeDefinition;
+export declare function isSetTypeDefinition(def: TypeDefinition): def is SetTypeDefinition;
+export declare function isMapTypeDefinition(def: TypeDefinition): def is MapTypeDefinition;
+export declare function isTupleTypeDefinition(def: TypeDefinition): def is TupleTypeDefinition;
+export declare function isChoiceTypeDefinition(def: TypeDefinition): def is ChoiceTypeDefinition;
+export declare function hasEnumValue(def: TypeDefinition): def is TypeDefinition & {
+    enum: unknown[];
+};
+export declare function hasConstValue(def: TypeDefinition): def is TypeDefinition & {
+    const: unknown;
+};
+/** Get the resolved type from a type specifier, handling arrays and references */
+export declare function getResolvedType(specifier: TypeSpecifier | undefined): string | string[] | null;
+/** Check if a type specifier includes null (making the type nullable) */
+export declare function isNullableType(specifier: TypeSpecifier | undefined): boolean;
+/** Get non-null types from a type specifier array */
+export declare function getNonNullTypes(specifier: TypeSpecifier): TypeKeyword[];
+/** Integer type bounds */
+export declare const INTEGER_BOUNDS: Record<IntegerType, {
+    min: bigint;
+    max: bigint;
+}>;

package/dist/types/components/json-structure/validation/error-transform.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Validation Error Transformation
+ *
+ * Transforms raw validation errors into user-friendly messages.
+ */
+import type { TypeDefinition } from '../structure-types';
+/**
+ * Validation error from the JSON Structure validator
+ */
+export interface RawValidationError {
+    /** JSON Pointer path to error location */
+    path: string;
+    /** Error type/code */
+    type: string;
+    /** Expected value/constraint */
+    expected?: unknown;
+    /** Actual value */
+    actual?: unknown;
+    /** Additional context */
+    context?: Record<string, unknown>;
+}
+/**
+ * User-friendly validation error
+ */
+export interface FormattedValidationError {
+    /** JSON Pointer path to error location */
+    path: string;
+    /** Human-readable error message */
+    message: string;
+    /** Original error type for programmatic handling */
+    code: string;
+}
+/**
+ * Transform a raw validation error into a user-friendly message
+ */
+export declare function formatValidationError(error: RawValidationError, definition?: TypeDefinition): FormattedValidationError;
+/**
+ * Transform multiple validation errors
+ */
+export declare function formatValidationErrors(errors: RawValidationError[], definitions?: Map<string, TypeDefinition>): FormattedValidationError[];
+/**
+ * Group errors by path for display
+ */
+export declare function groupErrorsByPath(errors: FormattedValidationError[]): Map<string, FormattedValidationError[]>;
+/**
+ * Get errors for a specific path
+ */
+export declare function getErrorsForPath(errors: FormattedValidationError[], path: string): FormattedValidationError[];
+/**
+ * Check if a path has errors
+ */
+export declare function hasErrorsAtPath(errors: FormattedValidationError[], path: string): boolean;
+/**
+ * Get child errors for a path (errors with paths that start with the given path)
+ */
+export declare function getChildErrors(errors: FormattedValidationError[], parentPath: string): FormattedValidationError[];

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

@@ -0,0 +1,5 @@
+/**
+ * Validation module exports
+ */
+export * from './sdk-validator';
+export * from './error-transform';

package/dist/types/components/json-structure/validation/sdk-validator.d.ts

@@ -0,0 +1,46 @@
+/**
+ * SDK Validator Wrapper
+ *
+ * Wraps the JSON Structure SDK validator (when available)
+ * or provides a basic fallback validator.
+ *
+ * Note: This is a placeholder implementation. When @json-structure/sdk
+ * becomes available, this should be updated to use the official validator.
+ */
+import type { JSONStructureSchema } from '../structure-types';
+import type { RawValidationError } from './error-transform';
+/**
+ * Validation result
+ */
+export interface ValidationResult {
+    /** Overall validity */
+    isValid: boolean;
+    /** List of validation errors */
+    errors: RawValidationError[];
+}
+/**
+ * Validator options
+ */
+export interface ValidatorOptions {
+    /** Stop at first error */
+    stopOnFirstError?: boolean;
+    /** Coerce types where possible */
+    coerceTypes?: boolean;
+}
+/**
+ * JSON Structure validator
+ */
+export interface StructureValidator {
+    /** Validate a value against the schema */
+    validate(value: unknown): ValidationResult;
+    /** Validate a value at a specific path */
+    validateAt(value: unknown, path: string): ValidationResult;
+}
+/**
+ * Create a validator for a schema
+ */
+export declare function createValidator(schema: JSONStructureSchema, options?: ValidatorOptions): StructureValidator;
+/**
+ * Validate a value against a schema (convenience function)
+ */
+export declare function validate(schema: JSONStructureSchema, value: unknown, options?: ValidatorOptions): ValidationResult;

package/dist/types/components/json-structure/widgets/default-widgets.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Default Widget Registrations
+ *
+ * Registers default widgets for all JSON Structure types.
+ */
+import type { WidgetRegistry } from './widget-registry';
+/**
+ * Register all default widgets for JSON Structure types
+ *
+ * @param registry - Widget registry to register to (defaults to global)
+ */
+export declare function registerDefaultWidgets(registry?: WidgetRegistry): void;
+/**
+ * Check if default widgets have been registered
+ *
+ * @param registry - Registry to check (defaults to global)
+ * @returns True if default widgets are registered
+ */
+export declare function hasDefaultWidgets(registry?: WidgetRegistry): boolean;
+/**
+ * Ensure default widgets are registered
+ *
+ * Only registers if not already registered.
+ *
+ * @param registry - Registry to ensure (defaults to global)
+ */
+export declare function ensureDefaultWidgets(registry?: WidgetRegistry): void;

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

@@ -0,0 +1,6 @@
+/**
+ * Widget system exports
+ */
+export * from './widget-registry';
+export * from './widget-utils';
+export * from './default-widgets';

package/dist/types/components/json-structure/widgets/widget-registry.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Widget Registry for JSON Structure Forms
+ *
+ * Manages custom widget registrations and resolution.
+ */
+import type { Renderable } from '@tempots/dom';
+import type { Controller } from '../../form';
+import type { StructureContext } from '../structure-context';
+/**
+ * Props passed to widget factories
+ */
+export interface WidgetProps<T = unknown> {
+    /** Controller for this field's value */
+    controller: Controller<T>;
+    /** Current structure context */
+    ctx: StructureContext;
+    /** Widget-specific options */
+    options?: Record<string, unknown>;
+}
+/**
+ * Factory function to create a widget
+ */
+export interface WidgetFactory<T = unknown> {
+    (props: WidgetProps<T>): Renderable;
+}
+/**
+ * Widget registration entry
+ */
+export interface WidgetRegistration {
+    /** Factory function to create the widget */
+    factory: WidgetFactory;
+    /** Human-readable display name */
+    displayName: string;
+    /** Optional description */
+    description?: string;
+    /** JSON Structure types this widget handles */
+    supportedTypes?: string[];
+    /** JSON Structure formats this widget handles */
+    supportedFormats?: string[];
+    /** Resolution priority (higher = preferred) */
+    priority?: number;
+    /** Whether this can be used as fallback */
+    canFallback?: boolean;
+    /** Custom matching logic */
+    matcher?: (ctx: StructureContext) => boolean;
+}
+/**
+ * Resolved widget ready for use
+ */
+export interface ResolvedWidget {
+    name: string;
+    registration: WidgetRegistration;
+}
+/**
+ * Widget registry interface
+ */
+export interface WidgetRegistry {
+    /** Register a widget */
+    register(name: string, registration: WidgetRegistration): void;
+    /** Unregister a widget */
+    unregister(name: string): void;
+    /** Get all registrations for a type */
+    getForType(type: string): WidgetRegistration[];
+    /** Get all registrations for a format */
+    getForFormat(format: string): WidgetRegistration[];
+    /** Find best matching widget for context */
+    findBestWidget(ctx: StructureContext): ResolvedWidget | null;
+    /** Get registration by name */
+    get(name: string): WidgetRegistration | undefined;
+    /** Check if a widget is registered */
+    has(name: string): boolean;
+    /** Get all widget names */
+    names(): string[];
+    /** Create a child registry that inherits from this one */
+    createChild(): WidgetRegistry;
+}
+/**
+ * Default implementation of WidgetRegistry
+ */
+export declare class DefaultWidgetRegistry implements WidgetRegistry {
+    private readonly registrations;
+    private readonly parent;
+    constructor(parent?: WidgetRegistry);
+    register(name: string, registration: WidgetRegistration): void;
+    unregister(name: string): void;
+    get(name: string): WidgetRegistration | undefined;
+    has(name: string): boolean;
+    names(): string[];
+    getForType(type: string): WidgetRegistration[];
+    getForFormat(format: string): WidgetRegistration[];
+    findBestWidget(ctx: StructureContext): ResolvedWidget | null;
+    /**
+     * Score how well a widget matches the context
+     */
+    private scoreWidget;
+    createChild(): WidgetRegistry;
+}
+/**
+ * Get the global widget registry
+ */
+export declare function getGlobalWidgetRegistry(): WidgetRegistry;
+/**
+ * Set the global widget registry
+ */
+export declare function setGlobalWidgetRegistry(registry: WidgetRegistry): void;
+/**
+ * Create a new widget registry
+ */
+export declare function createWidgetRegistry(parent?: WidgetRegistry): WidgetRegistry;
+export interface WidgetRegistrationOptions {
+    displayName?: string;
+    description?: string;
+    priority?: number;
+    canFallback?: boolean;
+}
+/**
+ * Create a widget registration for a specific type
+ */
+export declare function forType(type: string, factory: WidgetFactory, options?: WidgetRegistrationOptions): {
+    name: string;
+    registration: WidgetRegistration;
+};
+/**
+ * Create a widget registration for a specific format
+ */
+export declare function forFormat(format: string, factory: WidgetFactory, options?: WidgetRegistrationOptions): {
+    name: string;
+    registration: WidgetRegistration;
+};
+/**
+ * Create a widget registration for a type+format combination
+ */
+export declare function forTypeAndFormat(type: string, format: string, factory: WidgetFactory, options?: WidgetRegistrationOptions): {
+    name: string;
+    registration: WidgetRegistration;
+};
+/**
+ * Create a widget registration with custom matcher
+ */
+export declare function forMatcher(name: string, matcher: (ctx: StructureContext) => boolean, factory: WidgetFactory, options?: WidgetRegistrationOptions): {
+    name: string;
+    registration: WidgetRegistration;
+};