@tempots/beatui 0.68.0 → 0.71.0

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

@@ -30,6 +30,8 @@ export interface WidgetRegistration<T = unknown> {
     priority?: number;
     /** Whether this widget can be used as a fallback */
     canFallback?: boolean;
+    /** Custom matcher function for widget selection */
+    matcher?: (ctx: SchemaContext) => boolean;
 }
 /**
  * Widget customization configuration from x:ui
@@ -59,6 +61,29 @@ export interface WidgetCustomization {
         else?: WidgetCustomization;
     };
 }
+/**
+ * Custom widget registration for form-scoped widgets
+ */
+export interface CustomWidgetRegistration<T = unknown> {
+    /** Widget name */
+    name: string;
+    /** Widget factory function */
+    factory: WidgetFactory<T>;
+    /** Widget display name */
+    displayName?: string;
+    /** Widget description */
+    description?: string;
+    /** Supported JSON Schema types */
+    supportedTypes?: string[];
+    /** Widget priority (higher = preferred, default: 50) */
+    priority?: number;
+    /** Custom matcher function for widget selection */
+    matcher?: (ctx: SchemaContext) => boolean;
+}
+/**
+ * Array of custom widget registrations for the customWidgets option
+ */
+export type CustomWidgets = CustomWidgetRegistration[];
 /**
  * Widget registry for managing custom widgets
  */
@@ -118,3 +143,33 @@ export declare function registerEnhancedWidgets(registry?: WidgetRegistry): void
  * Helper to register a simple widget
  */
 export declare function registerWidget<T = unknown>(name: string, factory: WidgetFactory<T>, options?: Partial<WidgetRegistration<T>>, registry?: WidgetRegistry): void;
+/**
+ * Create a custom widget registration that matches by explicit x:ui widget name
+ *
+ * @example
+ * ```typescript
+ * forXUI('fancy-email', myEmailWidget)
+ * // Matches schema: { type: 'string', 'x:ui': 'fancy-email' }
+ * ```
+ */
+export declare function forXUI<T = unknown>(widgetName: string, factory: WidgetFactory<T>, options?: Partial<Omit<CustomWidgetRegistration<T>, 'name' | 'factory' | 'matcher'>>): CustomWidgetRegistration<T>;
+/**
+ * Create a custom widget registration that matches by schema format
+ *
+ * @example
+ * ```typescript
+ * forFormat('email', myEmailWidget)
+ * // Matches ANY schema with: { format: 'email' }
+ * ```
+ */
+export declare function forFormat<T = unknown>(format: string, factory: WidgetFactory<T>, options?: Partial<Omit<CustomWidgetRegistration<T>, 'factory' | 'matcher'>>): CustomWidgetRegistration<T>;
+/**
+ * Create a custom widget registration that matches by type + format combination
+ *
+ * @example
+ * ```typescript
+ * forTypeAndFormat('string', 'uuid', myUuidWidget)
+ * // Matches schema: { type: 'string', format: 'uuid' }
+ * ```
+ */
+export declare function forTypeAndFormat<T = unknown>(type: string, format: string, factory: WidgetFactory<T>, options?: Partial<Omit<CustomWidgetRegistration<T>, 'factory' | 'matcher'>>): CustomWidgetRegistration<T>;

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

@@ -0,0 +1,15 @@
+/**
+ * Any Control for JSON Structure
+ *
+ * Handles any type with JSON textarea
+ */
+import { Renderable } from '@tempots/dom';
+import { type Controller } from '../../form';
+import type { StructureContext } from '../structure-context';
+/**
+ * Control for any type (JSON textarea)
+ */
+export declare function StructureAnyControl({ ctx, controller, }: {
+    ctx: StructureContext;
+    controller: Controller<unknown>;
+}): Renderable;

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

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

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

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

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

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

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

@@ -0,0 +1,19 @@
+/**
+ * Choice Control for JSON Structure
+ *
+ * Handles choice type (tagged unions) with:
+ * - Dropdown to select which variant to use
+ * - Appropriate fields for selected variant
+ * - Optional discriminator property support
+ * - Tagged union serialization: { choiceName: variantValue }
+ */
+import { Renderable } from '@tempots/dom';
+import type { StructureContext } from '../structure-context';
+import { type Controller } from '../../form';
+/**
+ * Control for choice type (tagged unions)
+ */
+export declare function StructureChoiceControl({ ctx, controller, }: {
+    ctx: StructureContext;
+    controller: Controller<unknown>;
+}): Renderable;

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

@@ -0,0 +1,17 @@
+/**
+ * Decimal Control for JSON Structure
+ *
+ * Handles float, double, and decimal types with NumberInput
+ */
+import { Renderable } from '@tempots/dom';
+import { type Controller } from '../../form';
+import type { StructureContext } from '../structure-context';
+import type { FloatType } from '../structure-types';
+/**
+ * Control for float/double/decimal types
+ */
+export declare function StructureDecimalControl({ ctx, controller, floatType, }: {
+    ctx: StructureContext;
+    controller: Controller<number | null>;
+    floatType: FloatType;
+}): Renderable;

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

@@ -0,0 +1,14 @@
+/**
+ * Deprecation utilities for JSON Structure controls
+ *
+ * Helper functions for displaying deprecation indicators on deprecated fields
+ */
+import { type TNode } from '@tempots/dom';
+/**
+ * Create a deprecation indicator badge
+ */
+export declare function DeprecationBadge(): TNode;
+/**
+ * Wrap label with deprecation indicator if field is deprecated
+ */
+export declare function withDeprecationBadge(label: string | undefined, isDeprecated: boolean): TNode;

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;