@character-foundry/character-foundry 0.1.3 → 0.1.6

package/dist/app-framework.d.cts

@@ -0,0 +1,896 @@
+/// <reference types="react" />
+
+import { z } from 'zod';
+
+/**
+ * Restricted context object passed to extensions during activation.
+ * Provides access to configuration and core services.
+ */
+export interface ExtensionContext<TConfig> {
+	/** Current configuration (validated) */
+	readonly config: TConfig;
+	/** Update configuration (triggers re-validation) */
+	setConfig: (update: Partial<TConfig>) => void;
+	/** Core services available to extensions */
+	services: ExtensionServices;
+}
+/**
+ * Core services available to all extensions
+ */
+export interface ExtensionServices {
+	/** Toast notification service */
+	toast: ToastService;
+	/** Modal dialog service */
+	dialog: DialogService;
+	/** Event bus for cross-extension communication */
+	events: EventBus;
+}
+/**
+ * Toast notification service interface
+ */
+export interface ToastService {
+	/** Show success message */
+	success(message: string): void;
+	/** Show error message */
+	error(message: string): void;
+	/** Show info message */
+	info(message: string): void;
+	/** Show warning message */
+	warning(message: string): void;
+}
+/**
+ * Modal dialog service interface
+ */
+export interface DialogService {
+	/** Show confirmation dialog, returns true if confirmed */
+	confirm(message: string, title?: string): Promise<boolean>;
+	/** Show alert dialog */
+	alert(message: string, title?: string): Promise<void>;
+	/** Show prompt dialog, returns input value or null if cancelled */
+	prompt(message: string, defaultValue?: string): Promise<string | null>;
+}
+/**
+ * Event bus for cross-extension communication
+ */
+export interface EventBus {
+	/** Emit an event with optional payload */
+	emit(event: string, payload?: unknown): void;
+	/** Subscribe to an event, returns unsubscribe function */
+	on(event: string, handler: (payload: unknown) => void): () => void;
+	/** Subscribe to an event once */
+	once(event: string, handler: (payload: unknown) => void): () => void;
+}
+/**
+ * No-op implementations of services for testing or standalone usage
+ */
+export declare const noopServices: ExtensionServices;
+/**
+ * Base extension interface - all modular pieces implement this.
+ * Extensions are the building blocks of the plugin system.
+ *
+ * @template TConfig - Zod schema type for the configuration
+ */
+export interface Extension<TConfig extends z.ZodType = z.ZodType> {
+	/** Unique identifier, e.g., "com.foundry.openai" */
+	id: string;
+	/** Human-readable name, e.g., "OpenAI Provider" */
+	name: string;
+	/** SemVer version string */
+	version: string;
+	/** Zod schema defining the configuration shape (source of truth) */
+	configSchema: TConfig;
+	/** Default configuration values */
+	defaultConfig?: z.infer<TConfig>;
+	/** Called when extension is activated */
+	onActivate?: (context: ExtensionContext<z.infer<TConfig>>) => void | Promise<void>;
+	/** Called when extension is deactivated */
+	onDeactivate?: () => void | Promise<void>;
+}
+/**
+ * Extension state during runtime
+ */
+export interface ExtensionState<TConfig = unknown> {
+	/** The extension definition */
+	extension: Extension<z.ZodType<TConfig>>;
+	/** Whether the extension is currently active */
+	active: boolean;
+	/** Current validated configuration */
+	config: TConfig;
+	/** Error message if extension failed to activate */
+	error?: string;
+}
+/**
+ * Built-in widget types that AutoForm understands
+ */
+export type BuiltinWidget = "text" | "number" | "password" | "textarea" | "switch" | "checkbox" | "select" | "searchable-select" | "radio" | "slider" | "color-picker" | "tag-input" | "file-upload";
+/**
+ * Props passed to custom widget components.
+ *
+ * This interface is designed to be compatible with external editors
+ * like Milkdown, CodeMirror, or any custom component. The minimum
+ * required props are `value` and `onChange`.
+ *
+ * @example
+ * ```tsx
+ * // Wrapping an external editor
+ * function MilkdownWrapper({ value, onChange }: FieldWidgetProps<string>) {
+ *   return <Milkdown value={value} onChange={onChange} />;
+ * }
+ *
+ * // Usage
+ * <AutoForm
+ *   schema={schema}
+ *   uiHints={{ content: { widget: MilkdownWrapper } }}
+ * />
+ * ```
+ */
+export interface FieldWidgetProps<T = unknown> {
+	/** Current field value */
+	value: T;
+	/** Callback to update the value */
+	onChange: (value: T) => void;
+	/** Field name from schema (supports dot notation for nested: "parent.child") */
+	name: string;
+	/** Label text (from hint or schema .describe()) */
+	label?: string;
+	/** Validation error message */
+	error?: string;
+	/** Whether the field is disabled */
+	disabled?: boolean;
+	/** Whether the field is required */
+	required?: boolean;
+	/** Additional UI hints for the field */
+	hint?: FieldUIHint;
+}
+/**
+ * Condition for showing/hiding a field based on another field's value.
+ *
+ * @example
+ * ```tsx
+ * // Show only when advancedMode is true
+ * { field: 'advancedMode', equals: true }
+ *
+ * // Show only when kind is one of these values
+ * { field: 'kind', oneOf: ['openai', 'openai-compatible'] }
+ *
+ * // Show only when kind is NOT 'disabled'
+ * { field: 'kind', notEquals: 'disabled' }
+ * ```
+ */
+export interface FieldCondition {
+	/** The field name to check (supports dot notation for nested fields) */
+	field: string;
+	/** Show when field equals this exact value */
+	equals?: unknown;
+	/** Show when field does NOT equal this value */
+	notEquals?: unknown;
+	/** Show when field value is one of these values */
+	oneOf?: unknown[];
+	/** Show when field value is NOT one of these values */
+	notOneOf?: unknown[];
+	/** Custom predicate function for complex conditions */
+	when?: (value: unknown, allValues: Record<string, unknown>) => boolean;
+}
+/**
+ * Field-level UI configuration
+ */
+export interface FieldUIHint {
+	/** Override the rendered widget */
+	widget?: BuiltinWidget | ComponentType<FieldWidgetProps<unknown>>;
+	/** Custom label (overrides schema .describe()) */
+	label?: string;
+	/** Helper text shown below field */
+	helperText?: string;
+	/** Placeholder text */
+	placeholder?: string;
+	/** For sliders/numbers: min value */
+	min?: number;
+	/** For sliders/numbers: max value */
+	max?: number;
+	/** For sliders/numbers: step increment */
+	step?: number;
+	/** For select/radio: explicit options (overrides z.enum) */
+	options?: Array<{
+		value: string;
+		label: string;
+	}>;
+	/** Hide this field from the form */
+	hidden?: boolean;
+	/** Make this field read-only */
+	readOnly?: boolean;
+	/** CSS class name to apply */
+	className?: string;
+	/** For textarea: number of rows */
+	rows?: number;
+	/** Custom validation message */
+	validationMessage?: string;
+	/**
+	 * Condition for showing this field.
+	 * If not met, the field is hidden (not just visually - removed from DOM).
+	 */
+	condition?: FieldCondition;
+	/** For file-upload: accepted file types (e.g., "image/*", ".pdf,.doc") */
+	accept?: string;
+	/** For file-upload: allow multiple files */
+	multiple?: boolean;
+	/** For file-upload: max file size in bytes */
+	maxSize?: number;
+	/** For select: enable search/filter functionality */
+	searchable?: boolean;
+	/** For searchable-select: placeholder for search input */
+	searchPlaceholder?: string;
+	/** For searchable-select: "no results" message */
+	noResultsText?: string;
+	/** Group this field belongs to (for organization) */
+	group?: string;
+}
+/**
+ * Props for the FieldGroup component
+ */
+export interface FieldGroupProps {
+	/** Group title */
+	title: string;
+	/** Group description/subtitle */
+	description?: string;
+	/** Allow collapsing the group */
+	collapsible?: boolean;
+	/** Start collapsed (requires collapsible=true) */
+	defaultCollapsed?: boolean;
+	/** CSS class name */
+	className?: string;
+	/** Children (field elements) */
+	children: React.ReactNode;
+}
+/**
+ * UI hints map for a schema.
+ * Keys correspond to field names in the Zod object schema.
+ * Supports nested objects via dot notation or nested hint objects.
+ *
+ * @example
+ * ```tsx
+ * // Flat schema
+ * uiHints={{ name: { label: 'Full Name' } }}
+ *
+ * // Nested schema - both syntaxes work
+ * uiHints={{
+ *   'profile.name': { label: 'Profile Name' },  // dot notation
+ *   profile: { name: { label: 'Profile Name' } } // nested object
+ * }}
+ * ```
+ */
+export type UIHints<T extends Record<string, unknown>> = {
+	[K in keyof T]?: T[K] extends Record<string, unknown> ? FieldUIHint | UIHints<T[K]> : FieldUIHint;
+} & {
+	[key: string]: FieldUIHint | undefined;
+};
+/**
+ * Listener function type for registry changes
+ */
+export type RegistryListener<TId, TItem> = (id: TId, item: TItem | null, action: "register" | "unregister") => void;
+/**
+ * Base options for registry items
+ */
+export interface RegistryItemBase {
+	/** Unique identifier */
+	id: string;
+	/** Human-readable name */
+	name?: string;
+	/** Description */
+	description?: string;
+	/** Icon identifier or URL */
+	icon?: string;
+	/** Order priority (lower = earlier) */
+	order?: number;
+}
+/**
+ * Generic registry pattern for managing registered items.
+ * Provides registration, lookup, and subscription capabilities.
+ *
+ * @template TId - Type of the item identifier (usually string)
+ * @template TItem - Type of the registered item
+ */
+export declare class Registry<TId extends string = string, TItem = unknown> {
+	private items;
+	private listeners;
+	/**
+	 * Register an item with the given ID.
+	 * Overwrites existing item with same ID (with warning).
+	 */
+	register(id: TId, item: TItem): void;
+	/**
+	 * Unregister an item by ID.
+	 * @returns true if item existed and was removed
+	 */
+	unregister(id: TId): boolean;
+	/**
+	 * Get an item by ID.
+	 * @returns The item or undefined if not found
+	 */
+	get(id: TId): TItem | undefined;
+	/**
+	 * Check if an item with the given ID exists.
+	 */
+	has(id: TId): boolean;
+	/**
+	 * Get all registered items as a Map.
+	 * Returns a copy to prevent external modification.
+	 */
+	getAll(): Map<TId, TItem>;
+	/**
+	 * Get all registered item IDs.
+	 */
+	getAllIds(): TId[];
+	/**
+	 * Get the number of registered items.
+	 */
+	get size(): number;
+	/**
+	 * Subscribe to registry changes.
+	 * @returns Unsubscribe function
+	 */
+	subscribe(listener: RegistryListener<TId, TItem>): () => void;
+	/**
+	 * Clear all registered items.
+	 * Notifies listeners for each removed item.
+	 */
+	clear(): void;
+	/**
+	 * Iterate over all items.
+	 */
+	forEach(callback: (item: TItem, id: TId) => void): void;
+	/**
+	 * Find items matching a predicate.
+	 */
+	filter(predicate: (item: TItem, id: TId) => boolean): TItem[];
+	private notify;
+}
+/**
+ * A settings panel definition that can be registered.
+ * Settings panels appear in the application settings UI.
+ *
+ * @template TSchema - Zod object schema type for the settings
+ */
+export interface SettingsPanel<TSchema extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>> {
+	/** Unique identifier for the panel */
+	id: string;
+	/** Display title for the panel */
+	title: string;
+	/** Optional description */
+	description?: string;
+	/** Icon identifier or URL */
+	icon?: string;
+	/** Zod schema defining the settings shape */
+	schema: TSchema;
+	/** Default values for settings */
+	defaultValues?: z.infer<TSchema>;
+	/** UI hints for customizing field rendering */
+	uiHints?: UIHints<z.infer<TSchema>>;
+	/** Order priority (lower = earlier in list) */
+	order?: number;
+	/** Whether this panel is hidden from the UI */
+	hidden?: boolean;
+}
+/**
+ * Registry for settings panels.
+ * Allows extensions to inject settings panels into the app settings UI.
+ */
+export declare class SettingsRegistry extends Registry<string, SettingsPanel> {
+	/**
+	 * Register a settings panel.
+	 */
+	registerPanel<T extends z.ZodObject<z.ZodRawShape>>(panel: SettingsPanel<T>): void;
+	/**
+	 * Get all panels sorted by order (lower order = earlier).
+	 * Hidden panels are excluded.
+	 */
+	getSortedPanels(): SettingsPanel[];
+	/**
+	 * Get a panel by ID with proper typing.
+	 */
+	getPanel<T extends z.ZodObject<z.ZodRawShape>>(id: string): SettingsPanel<T> | undefined;
+}
+/**
+ * Default settings registry instance.
+ * Can be used directly or replaced with a custom instance.
+ */
+export declare const settingsRegistry: SettingsRegistry;
+/**
+ * A provider definition that can be registered.
+ * Providers are services like LLM backends, storage adapters, etc.
+ *
+ * @template TConfig - Zod object schema type for the provider config
+ * @template TClient - Type of the client/service instance created by the provider
+ */
+export interface Provider<TConfig extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>, TClient = unknown> {
+	/** Unique identifier for the provider */
+	id: string;
+	/** Display name for the provider */
+	name: string;
+	/** Optional description */
+	description?: string;
+	/** Icon identifier or URL */
+	icon?: string;
+	/** Zod schema defining the configuration shape */
+	configSchema: TConfig;
+	/** Default configuration values */
+	defaultConfig?: z.infer<TConfig>;
+	/** UI hints for customizing config form rendering */
+	uiHints?: UIHints<z.infer<TConfig>>;
+	/** Factory function to create the client/service instance */
+	createClient: (config: z.infer<TConfig>) => TClient | Promise<TClient>;
+	/** Optional validation beyond Zod schema (e.g., API key verification) */
+	validateConfig?: (config: z.infer<TConfig>) => Promise<{
+		valid: boolean;
+		error?: string;
+	}>;
+}
+/**
+ * Registry for providers of a specific type.
+ * Use separate instances for different provider types (LLM, Storage, etc.).
+ *
+ * @template TClient - Common client interface type for this registry
+ */
+export declare class ProviderRegistry<TClient = unknown> extends Registry<string, Provider<z.ZodObject<z.ZodRawShape>, TClient>> {
+	private readonly providerType?;
+	constructor(providerType?: string | undefined);
+	/**
+	 * Register a provider.
+	 */
+	registerProvider<T extends z.ZodObject<z.ZodRawShape>>(provider: Provider<T, TClient>): void;
+	/**
+	 * Get a provider by ID with proper typing.
+	 */
+	getProvider<T extends z.ZodObject<z.ZodRawShape>>(id: string): Provider<T, TClient> | undefined;
+	/**
+	 * Create a client instance for a provider.
+	 * Validates config against schema and runs custom validation if provided.
+	 *
+	 * @throws Error if provider not found, config invalid, or custom validation fails
+	 */
+	createClient<T extends z.ZodObject<z.ZodRawShape>>(providerId: string, config: z.infer<T>): Promise<TClient>;
+	/**
+	 * Get all providers as an array.
+	 */
+	getAllProviders(): Provider<z.ZodObject<z.ZodRawShape>, TClient>[];
+}
+/**
+ * Create a typed provider registry for a specific client type.
+ */
+export declare function createProviderRegistry<TClient>(providerType?: string): ProviderRegistry<TClient>;
+/**
+ * Widget component type for the registry.
+ */
+export type WidgetComponent = ComponentType<FieldWidgetProps<unknown>>;
+/**
+ * Widget definition for registration.
+ */
+export interface WidgetDefinition {
+	/** Unique identifier for the widget */
+	id: string;
+	/** Display name */
+	name?: string;
+	/** The React component to render */
+	component: WidgetComponent;
+	/** Description of when to use this widget */
+	description?: string;
+}
+/**
+ * Registry for custom form widgets.
+ * Allows extensions to add custom field rendering components.
+ */
+export declare class WidgetRegistry extends Registry<string, WidgetDefinition> {
+	/**
+	 * Register a custom widget.
+	 */
+	registerWidget(definition: WidgetDefinition): void;
+	/**
+	 * Register a widget component directly with just an ID.
+	 */
+	registerComponent(id: string, component: WidgetComponent): void;
+	/**
+	 * Get a widget component by ID.
+	 * Returns the component directly, not the definition.
+	 */
+	getComponent(id: string): WidgetComponent | undefined;
+	/**
+	 * Check if a widget ID is a built-in widget type.
+	 * This list must stay in sync with the BuiltinWidget type in ui-hints.ts.
+	 */
+	isBuiltinWidget(id: string): id is BuiltinWidget;
+}
+/**
+ * Default widget registry instance.
+ */
+export declare const widgetRegistry: WidgetRegistry;
+/**
+ * Props for the AutoForm component.
+ *
+ * @template T - Zod object schema type
+ */
+export interface AutoFormProps<T extends z.ZodObject<z.ZodRawShape>> {
+	/** Zod object schema defining the form shape */
+	schema: T;
+	/** Current values (for controlled mode) */
+	values?: z.infer<T>;
+	/** Default values for the form */
+	defaultValues?: Partial<z.infer<T>>;
+	/** Called when values change (controlled mode) */
+	onChange?: (values: z.infer<T>) => void;
+	/** Called on form submit with validated data */
+	onSubmit?: (values: z.infer<T>) => void | Promise<void>;
+	/** UI hints for customizing field rendering */
+	uiHints?: UIHints<z.infer<T>>;
+	/** Custom field order (array of field names) */
+	fieldOrder?: Array<keyof z.infer<T>>;
+	/** Disable all fields */
+	disabled?: boolean;
+	/** Show submit button */
+	withSubmit?: boolean;
+	/** Submit button text */
+	submitText?: string;
+	/** Custom className for form container */
+	className?: string;
+	/** Custom widget registry */
+	widgetRegistry?: WidgetRegistry;
+	/**
+	 * Render prop for custom form layout.
+	 * If provided, you control how fields and submit button are rendered.
+	 */
+	children?: (props: {
+		/** Array of rendered field elements */
+		fields: ReactNode[];
+		/** Submit button element (null if withSubmit=false) */
+		submit: ReactNode;
+		/** Form state from react-hook-form */
+		formState: {
+			isSubmitting: boolean;
+			isValid: boolean;
+			isDirty: boolean;
+		};
+		/**
+		 * Get a specific field by name.
+		 * Supports dot notation for nested fields: getField('profile.name')
+		 */
+		getField: (name: string) => ReactNode | null;
+		/**
+		 * Get fields belonging to a group (from uiHints.group).
+		 */
+		getFieldsByGroup: (group: string) => ReactNode[];
+	}) => ReactNode;
+}
+/**
+ * Schema-driven form component that automatically renders fields
+ * based on a Zod object schema.
+ *
+ * Features:
+ * - Nested object support
+ * - Conditional field visibility
+ * - Custom widget integration
+ * - Full react-hook-form integration
+ *
+ * @example
+ * ```tsx
+ * const schema = z.object({
+ *   name: z.string().describe('Your name'),
+ *   profile: z.object({
+ *     bio: z.string(),
+ *     website: z.string().url().optional(),
+ *   }),
+ *   kind: z.enum(['basic', 'advanced']),
+ *   advancedOption: z.string().optional(),
+ * });
+ *
+ * <AutoForm
+ *   schema={schema}
+ *   uiHints={{
+ *     advancedOption: {
+ *       condition: { field: 'kind', equals: 'advanced' }
+ *     }
+ *   }}
+ *   onSubmit={(data) => console.log(data)}
+ *   withSubmit
+ * />
+ * ```
+ */
+export declare function AutoForm<T extends z.ZodObject<z.ZodRawShape>>({ schema, values, defaultValues, onChange, onSubmit, uiHints, fieldOrder, disabled, withSubmit, submitText, className, widgetRegistry, children, }: AutoFormProps<T>): react_jsx_runtime.JSX.Element;
+/**
+ * Analyzed field information extracted from a Zod schema.
+ */
+export interface FieldInfo {
+	/** Field name in the schema */
+	name: string;
+	/** The Zod type (unwrapped from optional/nullable/default) */
+	zodType: z.ZodTypeAny;
+	/** Zod type constructor name (e.g., 'ZodString', 'ZodNumber', 'ZodObject') */
+	typeName: string;
+	/** Whether the field is optional */
+	isOptional: boolean;
+	/** Whether the field is nullable */
+	isNullable: boolean;
+	/** Default value if specified */
+	defaultValue?: unknown;
+	/** Description from .describe() */
+	description?: string;
+	/** Enum values for z.enum() or z.nativeEnum() */
+	enumValues?: string[];
+	/** Inner type info for arrays, optionals, etc. */
+	innerType?: FieldInfo;
+	/**
+	 * For nested objects: Map of child field names to their FieldInfo.
+	 * Only populated when typeName === 'ZodObject'.
+	 */
+	nestedFields?: Map<string, FieldInfo>;
+	/**
+	 * For nested objects: The inner ZodObject schema.
+	 * Useful for recursive AutoForm rendering.
+	 */
+	innerSchema?: z.ZodObject<z.ZodRawShape>;
+	/** Validation constraints extracted from the schema */
+	constraints?: FieldConstraints;
+}
+/**
+ * Validation constraints extracted from Zod checks.
+ */
+export interface FieldConstraints {
+	min?: number;
+	max?: number;
+	minLength?: number;
+	maxLength?: number;
+	regex?: RegExp;
+	email?: boolean;
+	url?: boolean;
+	uuid?: boolean;
+	int?: boolean;
+	positive?: boolean;
+	negative?: boolean;
+	multipleOf?: number;
+}
+/**
+ * Extract field information from a ZodObject schema.
+ *
+ * @param schema - Zod object schema to analyze
+ * @param prefix - Optional prefix for nested field names (e.g., "parent.")
+ * @returns Map of field names to their analyzed information
+ */
+export declare function analyzeSchema<T extends z.ZodRawShape>(schema: z.ZodObject<T>, prefix?: string): Map<string, FieldInfo>;
+/**
+ * Flatten a nested schema into a single Map with dot-notation keys.
+ * Useful for forms that need flat access to all fields.
+ *
+ * @example
+ * ```ts
+ * const schema = z.object({
+ *   name: z.string(),
+ *   profile: z.object({
+ *     bio: z.string(),
+ *   }),
+ * });
+ *
+ * const flat = flattenSchema(schema);
+ * // Map { 'name' => ..., 'profile' => ..., 'profile.bio' => ... }
+ * ```
+ */
+export declare function flattenSchema<T extends z.ZodRawShape>(schema: z.ZodObject<T>, prefix?: string): Map<string, FieldInfo>;
+/**
+ * Analyze a single Zod field to extract its type information.
+ *
+ * @param name - Field name (can include dots for nested paths)
+ * @param zodType - Zod type to analyze
+ * @returns Analyzed field information
+ */
+export declare function analyzeField(name: string, zodType: z.ZodTypeAny): FieldInfo;
+/**
+ * Get the value at a dot-notation path from an object.
+ * SECURITY: Rejects dangerous keys (__proto__, constructor, prototype) to prevent prototype pollution.
+ *
+ * @example
+ * ```ts
+ * getValueAtPath({ profile: { name: 'John' } }, 'profile.name') // 'John'
+ * ```
+ */
+export declare function getValueAtPath(obj: Record<string, unknown>, path: string): unknown;
+/**
+ * Set a value at a dot-notation path in an object (immutably).
+ * SECURITY: Rejects dangerous keys (__proto__, constructor, prototype) to prevent prototype pollution.
+ *
+ * @example
+ * ```ts
+ * setValueAtPath({ profile: { name: 'John' } }, 'profile.name', 'Jane')
+ * // { profile: { name: 'Jane' } }
+ * ```
+ */
+export declare function setValueAtPath(obj: Record<string, unknown>, path: string, value: unknown): Record<string, unknown>;
+/**
+ * Determine the default widget type for a Zod field.
+ */
+export declare function getDefaultWidgetType(fieldInfo: FieldInfo): string;
+/**
+ * Check if a field should be treated as a secret/password field.
+ */
+export declare function isSecretField(fieldInfo: FieldInfo): boolean;
+/**
+ * Check if a field is a nested object type.
+ */
+export declare function isNestedObject(fieldInfo: FieldInfo): boolean;
+/**
+ * Props for the FieldRenderer component.
+ */
+export interface FieldRendererProps {
+	/** Analyzed field information from Zod schema */
+	fieldInfo: FieldInfo;
+	/** UI hints for this field */
+	hint?: FieldUIHint;
+	/** Current field value */
+	value: unknown;
+	/** Callback to update the value */
+	onChange: (value: unknown) => void;
+	/** Validation error message */
+	error?: string;
+	/** Whether the field is disabled */
+	disabled?: boolean;
+	/**
+	 * For nested objects: render function for nested fields.
+	 * Called with the nested field info to recursively render.
+	 */
+	renderNestedField?: (fieldInfo: FieldInfo) => React.ReactNode;
+}
+/**
+ * Renders a single field based on its Zod type and UI hints.
+ * Automatically selects the appropriate widget component.
+ */
+export declare function FieldRenderer({ fieldInfo, hint, value, onChange, error, disabled, renderNestedField, }: FieldRendererProps): react_jsx_runtime.JSX.Element;
+/**
+ * Headless field group component for organizing form sections.
+ * Can be used standalone or with AutoForm's render prop.
+ *
+ * @example
+ * ```tsx
+ * // Standalone usage
+ * <FieldGroup title="Basic Settings">
+ *   <TextInput ... />
+ *   <NumberInput ... />
+ * </FieldGroup>
+ *
+ * // Collapsible group
+ * <FieldGroup title="Advanced" collapsible defaultCollapsed>
+ *   <Switch ... />
+ * </FieldGroup>
+ *
+ * // With AutoForm render prop
+ * <AutoForm schema={schema}>
+ *   {({ getField }) => (
+ *     <>
+ *       <FieldGroup title="Profile">
+ *         {getField('name')}
+ *         {getField('email')}
+ *       </FieldGroup>
+ *       <FieldGroup title="Preferences" collapsible>
+ *         {getField('theme')}
+ *         {getField('notifications')}
+ *       </FieldGroup>
+ *     </>
+ *   )}
+ * </AutoForm>
+ * ```
+ */
+export declare function FieldGroup({ title, description, collapsible, defaultCollapsed, className, children, }: FieldGroupProps): react_jsx_runtime.JSX.Element;
+/**
+ * Props for the FieldSection component (alias for FieldGroup).
+ */
+export type FieldSectionProps = FieldGroupProps;
+/**
+ * Alias for FieldGroup with semantic naming.
+ * Use when you prefer "section" terminology over "group".
+ */
+export declare const FieldSection: typeof FieldGroup;
+/**
+ * Context for providing a custom WidgetRegistry to AutoForm.
+ */
+export declare const WidgetRegistryContext: react.Context<WidgetRegistry>;
+/**
+ * Hook to access the current WidgetRegistry.
+ * Returns the default registry if not wrapped in a provider.
+ */
+export declare function useWidgetRegistry(): WidgetRegistry;
+/**
+ * Headless text input widget.
+ * Renders a basic text input with label, error display, and helper text.
+ */
+export declare function TextInput({ value, onChange, name, label, error, disabled, required, hint, }: FieldWidgetProps<string>): react_jsx_runtime.JSX.Element;
+/**
+ * Headless multi-line text input widget.
+ * Renders a textarea with configurable rows.
+ *
+ * @example
+ * ```tsx
+ * // Via uiHints
+ * <AutoForm
+ *   schema={schema}
+ *   uiHints={{ bio: { widget: 'textarea', rows: 5 } }}
+ * />
+ * ```
+ */
+export declare function Textarea({ value, onChange, name, label, error, disabled, required, hint, }: FieldWidgetProps<string>): react_jsx_runtime.JSX.Element;
+/**
+ * Props for NumberInput - allows number | undefined since empty inputs are undefined
+ */
+export type NumberInputProps = Omit<FieldWidgetProps<number | undefined>, "onChange"> & {
+	/** Value can be number or undefined (empty) */
+	value: number | undefined;
+	/** onChange receives number or undefined (empty) */
+	onChange: (value: number | undefined) => void;
+};
+/**
+ * Headless number input widget.
+ * Renders a number input with min/max/step support.
+ *
+ * Note: This widget properly handles empty inputs as `undefined`,
+ * not as a type-cast lie. The form resolver handles validation
+ * for required fields.
+ */
+export declare function NumberInput({ value, onChange, name, label, error, disabled, required, hint, }: NumberInputProps): react_jsx_runtime.JSX.Element;
+/**
+ * Headless switch/toggle widget.
+ * Renders a checkbox with switch semantics (role="switch").
+ */
+export declare function Switch({ value, onChange, name, label, error, disabled, hint, }: FieldWidgetProps<boolean>): react_jsx_runtime.JSX.Element;
+/**
+ * Headless select dropdown widget.
+ * Renders a native select element with options from hint or enum values.
+ */
+export declare function Select({ value, onChange, name, label, error, disabled, required, hint, }: FieldWidgetProps<string>): react_jsx_runtime.JSX.Element;
+/**
+ * Headless searchable select widget.
+ * Renders a select with search/filter functionality for large option lists.
+ *
+ * @example
+ * ```tsx
+ * // Via uiHints
+ * <AutoForm
+ *   schema={z.object({ country: z.enum([...countries]) })}
+ *   uiHints={{
+ *     country: {
+ *       widget: 'searchable-select',
+ *       searchPlaceholder: 'Search countries...',
+ *       noResultsText: 'No countries found',
+ *     }
+ *   }}
+ * />
+ * ```
+ */
+export declare function SearchableSelect({ value, onChange, name, label, error, disabled, required, hint, }: FieldWidgetProps<string>): react_jsx_runtime.JSX.Element;
+/**
+ * Headless tag/chip input widget.
+ * Renders an input that converts text into tags on Enter/comma.
+ */
+export declare function TagInput({ value, onChange, name, label, error, disabled, required, hint, }: FieldWidgetProps<string[]>): react_jsx_runtime.JSX.Element;
+/**
+ * Headless password/secret input widget.
+ * Renders a password input with toggle visibility button.
+ */
+export declare function SecretInput({ value, onChange, name, label, error, disabled, required, hint, }: FieldWidgetProps<string>): react_jsx_runtime.JSX.Element;
+/**
+ * File or array of files depending on `multiple` hint.
+ */
+export type FileUploadValue = File | File[] | null;
+/**
+ * Headless file upload widget with drag-and-drop support.
+ *
+ * @example
+ * ```tsx
+ * // Single file
+ * <AutoForm
+ *   schema={z.object({ avatar: z.instanceof(File).optional() })}
+ *   uiHints={{ avatar: { widget: 'file-upload', accept: 'image/*' } }}
+ * />
+ *
+ * // Multiple files
+ * <AutoForm
+ *   schema={z.object({ attachments: z.array(z.instanceof(File)) })}
+ *   uiHints={{ attachments: { widget: 'file-upload', multiple: true, accept: '.pdf,.doc' } }}
+ * />
+ * ```
+ */
+export declare function FileUpload({ value, onChange, name, label, error, disabled, required, hint, }: FieldWidgetProps<FileUploadValue>): react_jsx_runtime.JSX.Element;
+
+export {};