@tempots/beatui 0.82.0 → 0.83.0

package/dist/types/components/form/use-form.d.ts

@@ -1,36 +1,120 @@
 import { Signal, Value } from '@tempots/dom';
 import { StandardSchemaV1 } from './schema/standard-schema-v1';
 import { ControllerValidation, Controller, ObjectController } from './controller';
+/**
+ * Configuration options for creating a form with useForm.
+ *
+ * @template T - The form data type (must be an object)
+ */
 export interface UseFormOptions<T> {
+    /** Optional schema for validation (supports Standard Schema v1, including Zod schemas). */
     schema?: StandardSchemaV1<T, T>;
+    /** Initial form values (can be a static value or a reactive Signal). */
     initialValue?: Value<T>;
+    /** Optional async submit handler that can return validation errors. */
     onSubmit?: (value: T) => Promise<ControllerValidation>;
+    /** When to show validation errors: 'onSubmit' (default), 'eager' (immediately), or 'onTouched' (after blur). */
     validationMode?: 'onSubmit' | 'eager' | 'onTouched';
+    /** Debounce delay in milliseconds for validation (useful for 'eager' mode). */
     validateDebounceMs?: number;
 }
+/**
+ * Configuration options for creating a standalone controller with useController.
+ *
+ * @template T - The controller value type
+ */
 export interface UseControllerOptions<T> {
+    /** Initial controller value (can be a static value or a reactive Signal). */
     initialValue: Value<T>;
+    /** Optional callback invoked when the value changes. */
     onChange?: (value: T) => void;
+    /** Optional validation function (sync or async). */
     validate?: (value: T) => Promise<ControllerValidation> | ControllerValidation;
+    /** Equality function for dirty tracking (defaults to strictEqual). */
     equals?: (a: T, b: T) => boolean;
+    /** When to show validation errors: 'onSubmit', 'eager', or 'onTouched' (default). */
     validationMode?: 'onSubmit' | 'eager' | 'onTouched';
+    /** Debounce delay in milliseconds for validation. */
     validateDebounceMs?: number;
 }
 /**
- * Creates a Controller instance with automatic resource cleanup.
- * The controller will be automatically disposed when the component unmounts.
+ * Creates a standalone reactive controller for managing a single form field or value.
+ * Provides reactive state management, validation, and touched/dirty tracking.
+ *
+ * @template T - The value type managed by the controller
+ * @param options - Controller configuration options
+ * @returns An object with the controller instance and a setStatus function for manual validation updates
+ *
+ * @example
+ * ```typescript
+ * import { useController, Control, TextInput } from '@tempots/beatui'
+ * import { html } from '@tempots/dom'
+ * import { z } from 'zod'
+ * import { Validation } from '@tempots/std'
+ *
+ * const emailSchema = z.string().email()
+ *
+ * const { controller } = useController({
+ *   initialValue: '',
+ *   validate: async (value) => {
+ *     const result = emailSchema.safeParse(value)
+ *     return result.success
+ *       ? Validation.valid
+ *       : Validation.invalid({ message: result.error.errors[0].message })
+ *   },
+ *   validationMode: 'onTouched',
+ * })
+ *
+ * const emailInput = Control(TextInput, {
+ *   controller,
+ *   label: 'Email',
+ *   placeholder: 'you@example.com',
+ * })
+ * ```
  */
 export declare function useController<T>({ initialValue, onChange, validate, equals, validationMode, validateDebounceMs, }: UseControllerOptions<T>): {
     controller: Controller<T>;
     setStatus: (result: ControllerValidation) => void;
 };
+/**
+ * Connects common HTML attributes (disabled, name) from a controller to a DOM element.
+ * This is a lower-level utility; most users should use Control/BaseControl instead.
+ *
+ * @template T - The controller value type
+ * @param value - The controller to connect
+ * @returns A Fragment with attribute bindings
+ */
 export declare function connectCommonAttributes<T>(value: Controller<T>): import("@tempots/dom").Renderable<import("@tempots/dom").DOMContext>;
+/**
+ * Connects a string controller to a text input element with value binding and event handlers.
+ * This is a lower-level utility; most users should use Control/BaseControl instead.
+ *
+ * @param value - The string controller to connect
+ * @param options - Configuration for when to trigger updates
+ * @returns A Fragment with attribute and event bindings
+ */
 export declare function connectStringInput(value: Controller<string>, { triggerOn, }?: {
     triggerOn?: 'change' | 'input';
 }): import("@tempots/dom").Renderable<import("@tempots/dom").DOMContext>;
+/**
+ * Connects a number controller to a number input element with value binding and event handlers.
+ * This is a lower-level utility; most users should use Control/BaseControl instead.
+ *
+ * @param value - The number controller to connect
+ * @param options - Configuration for when to trigger updates
+ * @returns A Fragment with attribute and event bindings
+ */
 export declare function connectNumberInput(value: Controller<number>, { triggerOn, }?: {
     triggerOn?: 'change' | 'input';
 }): import("@tempots/dom").Renderable<import("@tempots/dom").DOMContext>;
+/**
+ * Converts a Standard Schema v1 validation result into a ControllerValidation.
+ * Used internally to integrate Standard Schema validators (including Zod) with the form system.
+ *
+ * @template Out - The validated output type
+ * @param result - The Standard Schema validation result
+ * @returns A ControllerValidation representing the result
+ */
 export declare function standardSchemaResultToValidation<Out>(result: StandardSchemaV1.Result<Out>): ControllerValidation;
 /**
  * Wraps an async operation and converts any thrown errors into a ControllerValidation.
@@ -56,10 +140,70 @@ export declare function taskToValidation<T>({ task, errorMessage, errorPath, val
     errorPath?: string[];
     validation?: (result: T) => ControllerValidation;
 }): Promise<ControllerValidation>;
+/**
+ * The result returned by useForm, providing form state management and submission handling.
+ *
+ * @template T - The form data type
+ */
 export type UseFormResult<T extends object> = {
+    /** The root ObjectController for accessing form fields via controller.field(). */
     controller: ObjectController<T>;
+    /** Manually set the form's validation status (useful for server-side errors). */
     setStatus: (result: ControllerValidation) => void;
+    /** Submit handler to attach to form onSubmit event. */
     submit: (e?: Event) => Promise<void>;
+    /** Reactive signal indicating whether the form is currently submitting. */
     submitting: Signal<boolean>;
 };
+/**
+ * Creates a complete form with validation, submission handling, and reactive state management.
+ * Returns an ObjectController that provides field-level access and form-wide operations.
+ *
+ * @template T - The form data type (must be an object)
+ * @param options - Form configuration options
+ * @returns An object with controller, setStatus, submit handler, and submitting signal
+ *
+ * @example
+ * ```typescript
+ * import { useForm, Control, TextInput, Button } from '@tempots/beatui'
+ * import { html, on } from '@tempots/dom'
+ * import { z } from 'zod'
+ *
+ * const loginSchema = z.object({
+ *   email: z.string().email('Invalid email address'),
+ *   password: z.string().min(8, 'Password must be at least 8 characters'),
+ * })
+ *
+ * const { controller, submit, submitting } = useForm({
+ *   initialValue: { email: '', password: '' },
+ *   schema: loginSchema,
+ *   validationMode: 'onTouched',
+ *   onSubmit: async (data) => {
+ *     const response = await fetch('/api/login', {
+ *       method: 'POST',
+ *       body: JSON.stringify(data),
+ *     })
+ *     if (!response.ok) {
+ *       return Validation.invalid({ message: 'Login failed' })
+ *     }
+ *     return Validation.valid
+ *   },
+ * })
+ *
+ * const loginForm = html.form(
+ *   on.submit(submit),
+ *   Control(TextInput, {
+ *     controller: controller.field('email'),
+ *     label: 'Email',
+ *     type: 'email',
+ *   }),
+ *   Control(TextInput, {
+ *     controller: controller.field('password'),
+ *     label: 'Password',
+ *     type: 'password',
+ *   }),
+ *   Button({ type: 'submit', disabled: submitting }, 'Sign In')
+ * )
+ * ```
+ */
 export declare function useForm<T extends object>({ initialValue, schema, onSubmit, validationMode, validateDebounceMs, }: UseFormOptions<T>): UseFormResult<T>;

package/dist/types/components/i18n/index.d.ts

@@ -1,3 +1,12 @@
+/**
+ * @fileoverview BeatUI i18n Component Module
+ *
+ * Exports locale management components and utilities:
+ * - {@link Locale} - Provider for managing the current locale and text direction
+ * - {@link LocaleSelector} - Dropdown component for locale selection
+ * - {@link makeI18nProvider} - Factory for creating i18n providers with dynamic translation loading
+ * - {@link LocaleDirection} - Component that applies text direction class to the body element
+ */
 export * from './locale';
 export * from './locale-selector';
 export * from './make-i18nprovider';

package/dist/types/components/i18n/locale-direction.d.ts

@@ -1,4 +1,24 @@
 /**
- * Combined theme and direction component that applies both appearance and direction classes to body
+ * Component that applies the current text direction class to the document body.
+ *
+ * Reads the `direction` signal from the `Locale` provider and applies a CSS class
+ * of the form `b-ltr` or `b-rtl` to the `<body>` element via a Portal. This enables
+ * CSS rules to respond to text direction changes throughout the application.
+ *
+ * Must be used within a `Provide(Locale, ...)` context.
+ *
+ * @returns A renderable TNode that manages the body direction class
+ *
+ * @example
+ * ```typescript
+ * import { Provide } from '@tempots/dom'
+ * import { Locale, LocaleDirection } from '@tempots/beatui'
+ *
+ * // Include in your app root to enable automatic direction management
+ * Provide(Locale, {}, () => Fragment(
+ *   LocaleDirection(),
+ *   // ... rest of app
+ * ))
+ * ```
  */
 export declare const LocaleDirection: () => import("@tempots/dom").Renderable;

package/dist/types/components/i18n/locale-selector.d.ts

@@ -1,12 +1,57 @@
 import { Value } from '@tempots/dom';
+/**
+ * Represents a single locale entry for display in the locale selector.
+ */
 export type LocaleItem = {
+    /** The locale code (e.g., `'en'`, `'es'`, `'fr'`) */
     code: string;
+    /** The display name of the locale in the application's current language (e.g., `'Spanish'`) */
     name: string;
+    /** The native name of the locale in its own language (e.g., `'Espanol'`). Shown in parentheses after the name if different. */
     nativeName?: string;
 };
+/**
+ * Configuration options for the {@link LocaleSelector} component.
+ */
 export type LocaleSelectorOptions = {
+    /** Reactive list of available locales to display in the dropdown */
     locales: Value<LocaleItem[]>;
+    /** Optional callback invoked when the user selects a different locale */
     onChange?: (locale: string) => void;
+    /**
+     * Whether to automatically update the `Locale` provider when the selection changes.
+     * @default true
+     */
     updateLocale?: boolean;
 };
+/**
+ * A dropdown component for selecting the application locale.
+ *
+ * Renders a native `<select>` element wrapped in an `InputWrapper` with a language icon.
+ * The component reads the current locale from the `Locale` provider and optionally updates it
+ * when the user makes a selection.
+ *
+ * @param options - Configuration options for the locale selector
+ * @param options.locales - Reactive list of available locales
+ * @param options.onChange - Optional callback invoked on locale change
+ * @param options.updateLocale - Whether to update the Locale provider automatically
+ *
+ * @returns A renderable TNode representing the locale selector component
+ *
+ * @example
+ * ```typescript
+ * import { LocaleSelector, LocaleItem } from '@tempots/beatui'
+ *
+ * const locales: LocaleItem[] = [
+ *   { code: 'en', name: 'English' },
+ *   { code: 'es', name: 'Spanish', nativeName: 'Espanol' },
+ *   { code: 'fr', name: 'French', nativeName: 'Francais' },
+ * ]
+ *
+ * LocaleSelector({
+ *   locales,
+ *   onChange: (locale) => console.log('Selected:', locale),
+ * })
+ * ```
+ */
 export declare function LocaleSelector({ locales, onChange, updateLocale, }: LocaleSelectorOptions): import("@tempots/dom").Renderable;

package/dist/types/components/i18n/make-i18nprovider.d.ts

@@ -1,7 +1,49 @@
 import { Provider, Signal } from '@tempots/dom';
+/**
+ * Creates an i18n provider that manages reactive translations for a given message type.
+ *
+ * The factory creates a `Provider` that automatically hooks into the `Locale` provider
+ * to detect locale changes and dynamically load the corresponding translation messages.
+ * It uses `makeMessages` internally for reactive translation management with fallback support.
+ *
+ * @typeParam M - The shape of the messages object (must extend `object`)
+ *
+ * @param config - Configuration object for the i18n provider
+ * @param config.defaultLocale - The default locale code to use as fallback (e.g., `'en'`)
+ * @param config.defaultMessages - The default messages object used before any locale is loaded
+ * @param config.localeLoader - Async function that loads messages for a given locale string
+ * @param config.providerName - Optional name for the provider mark, used for debugging
+ * @default config.providerName `'I18nProvider'`
+ *
+ * @returns A `Provider<Signal<M>, object>` that provides a reactive signal of the current messages
+ *
+ * @example
+ * ```typescript
+ * import { makeI18nProvider } from '@tempots/beatui'
+ *
+ * type MyMessages = { greeting: string; farewell: string }
+ *
+ * const MyI18n = makeI18nProvider<MyMessages>({
+ *   defaultLocale: 'en',
+ *   defaultMessages: { greeting: 'Hello', farewell: 'Goodbye' },
+ *   localeLoader: async (locale) => {
+ *     const mod = await import(`./locales/${locale}.ts`)
+ *     return mod.default
+ *   },
+ *   providerName: 'MyI18n',
+ * })
+ *
+ * // Use in a component
+ * Use(MyI18n, t => html.p(t.$.greeting))
+ * ```
+ */
 export declare function makeI18nProvider<M extends object>({ defaultLocale, defaultMessages, localeLoader, providerName, }: {
+    /** The default locale code to use as fallback (e.g., `'en'`) */
     defaultLocale: string;
+    /** The default messages object used before any locale is loaded */
     defaultMessages: M;
+    /** Async function that loads messages for a given locale string */
     localeLoader: (locale: string) => Promise<M>;
+    /** Optional name for the provider mark, used for debugging. @default 'I18nProvider' */
     providerName?: string;
 }): Provider<Signal<M>, object>;

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

@@ -1,85 +1,218 @@
 import type Ajv from 'ajv';
+/**
+ * Universal JSON Schema type identifiers that work across draft-07, 2019-09, and 2020-12.
+ *
+ * These represent the fundamental data types recognized by all JSON Schema drafts.
+ *
+ * @example
+ * ```ts
+ * const schema: JSONSchema = { type: 'string' }
+ * const multiType: JSONSchema = { type: ['string', 'null'] }
+ * ```
+ */
 export type JSONSchemaType = 'null' | 'boolean' | 'object' | 'array' | 'number' | 'string' | 'integer';
+/**
+ * A JSON Schema definition, which can be either a full schema object or a boolean.
+ *
+ * When `true`, it accepts any value. When `false`, it rejects all values.
+ * This is used in subschema positions like `additionalProperties`, `items`, etc.
+ */
 export type JSONSchemaDefinition = JSONSchema | boolean;
+/**
+ * Represents a complete JSON Schema object supporting draft-07, 2019-09, and 2020-12 keywords.
+ *
+ * This interface provides a unified type covering all standard JSON Schema keywords across
+ * multiple specification drafts. It serves as the primary schema representation used throughout
+ * the BeatUI JSON Schema form generation system.
+ *
+ * @example
+ * ```ts
+ * const userSchema: JSONSchema = {
+ *   type: 'object',
+ *   title: 'User',
+ *   properties: {
+ *     name: { type: 'string', minLength: 1 },
+ *     age: { type: 'integer', minimum: 0 },
+ *   },
+ *   required: ['name'],
+ * }
+ * ```
+ */
 export interface JSONSchema {
+    /** Unique identifier for the schema */
     $id?: string;
+    /** URI identifying the JSON Schema draft version */
     $schema?: string;
+    /** Reference to another schema by URI */
     $ref?: string;
+    /** Human-readable comment for schema maintainers */
     $comment?: string;
+    /** Human-readable title for the schema */
     title?: string;
+    /** Human-readable description of the schema's purpose */
     description?: string;
+    /** Default value for the schema */
     default?: unknown;
+    /** Example values conforming to this schema */
     examples?: unknown[];
+    /** Whether the value is read-only (informational, not enforced) */
     readOnly?: boolean;
+    /** Whether the value is write-only (e.g., passwords) */
     writeOnly?: boolean;
+    /** Whether the schema is deprecated */
     deprecated?: boolean;
+    /** The data type(s) allowed by this schema */
     type?: JSONSchemaType | JSONSchemaType[];
+    /** Array of allowed values */
     enum?: unknown[];
+    /** The exact value required */
     const?: unknown;
+    /** Number must be a multiple of this value */
     multipleOf?: number;
+    /** Maximum allowed value (inclusive) */
     maximum?: number;
+    /** Maximum allowed value (exclusive) */
     exclusiveMaximum?: number;
+    /** Minimum allowed value (inclusive) */
     minimum?: number;
+    /** Minimum allowed value (exclusive) */
     exclusiveMinimum?: number;
+    /** Maximum allowed string length */
     maxLength?: number;
+    /** Minimum required string length */
     minLength?: number;
+    /** Regular expression pattern the string must match */
     pattern?: string;
+    /** Semantic format identifier (e.g., 'email', 'date-time', 'uri') */
     format?: string;
+    /** Schema(s) for array items; a single schema applies to all items */
     items?: JSONSchemaDefinition | JSONSchemaDefinition[];
+    /** Schema for items beyond those specified in tuple-style `items` */
     additionalItems?: JSONSchemaDefinition;
+    /** Maximum allowed array length */
     maxItems?: number;
+    /** Minimum required array length */
     minItems?: number;
+    /** Whether all array items must be unique */
     uniqueItems?: boolean;
+    /** Schema that at least one array item must match */
     contains?: JSONSchemaDefinition;
+    /** Minimum number of items matching `contains` (2019-09+) */
     minContains?: number;
+    /** Maximum number of items matching `contains` (2019-09+) */
     maxContains?: number;
+    /** Maximum allowed number of properties */
     maxProperties?: number;
+    /** Minimum required number of properties */
     minProperties?: number;
+    /** List of required property names */
     required?: string[];
+    /** Schemas for known properties by name */
     properties?: Record<string, JSONSchemaDefinition>;
+    /** Schemas for properties matching regex patterns */
     patternProperties?: Record<string, JSONSchemaDefinition>;
+    /** Schema for properties not covered by `properties` or `patternProperties` */
     additionalProperties?: JSONSchemaDefinition;
+    /** Property dependencies (draft-07): maps property name to required properties or subschema */
     dependencies?: Record<string, JSONSchemaDefinition | string[]>;
+    /** Schema that property names must conform to */
     propertyNames?: JSONSchemaDefinition;
+    /** Conditional schema: if the value matches this, apply `then`; otherwise apply `else` */
     if?: JSONSchemaDefinition;
+    /** Schema applied when `if` matches */
     then?: JSONSchemaDefinition;
+    /** Schema applied when `if` does not match */
     else?: JSONSchemaDefinition;
+    /** Value must match all of these schemas */
     allOf?: JSONSchemaDefinition[];
+    /** Value must match at least one of these schemas */
     anyOf?: JSONSchemaDefinition[];
+    /** Value must match exactly one of these schemas */
     oneOf?: JSONSchemaDefinition[];
+    /** Value must not match this schema */
     not?: JSONSchemaDefinition;
+    /** Maps property name to list of other required properties when that property is present */
     dependentRequired?: Record<string, string[]>;
+    /** Maps property name to additional schema applied when that property is present */
     dependentSchemas?: Record<string, JSONSchemaDefinition>;
+    /** Schema for items not evaluated by other keywords (2019-09+) */
     unevaluatedItems?: JSONSchemaDefinition;
+    /** Schema for properties not evaluated by other keywords (2019-09+) */
     unevaluatedProperties?: JSONSchemaDefinition;
+    /** Tuple-style item schemas for array positions (2020-12; replaces tuple-style `items`) */
     prefixItems?: JSONSchemaDefinition[];
+    /** Encoding used for content (e.g., 'base64') */
     contentEncoding?: string;
+    /** MIME type of the content */
     contentMediaType?: string;
+    /** Schema describing the decoded content */
     contentSchema?: JSONSchemaDefinition;
+    /** Reusable schema definitions (draft-07: `definitions`) */
     definitions?: Record<string, JSONSchemaDefinition>;
+    /** Reusable schema definitions (2019-09+: `$defs`) */
     $defs?: Record<string, JSONSchemaDefinition>;
+    /** Extension point for custom keywords */
     [key: string]: unknown;
 }
+/**
+ * Represents a conflict discovered when merging schemas in an `allOf` composition.
+ *
+ * Schema conflicts occur when two or more subschemas in an `allOf` specify
+ * incompatible constraints for the same property or keyword.
+ */
 export type SchemaConflict = {
+    /** JSON path segments identifying the location of the conflict */
     readonly path: ReadonlyArray<PropertyKey>;
+    /** Human-readable description of the conflict */
     readonly message: string;
+    /** The conflicting values from different subschemas */
     readonly conflictingValues: readonly unknown[];
 };
+/**
+ * Result of merging multiple schemas via `allOf` composition.
+ *
+ * Contains the successfully merged schema along with any conflicts
+ * that were encountered during the merge process.
+ */
 export type AllOfMergeResult = {
+    /** The merged schema combining all `allOf` subschemas */
     readonly mergedSchema: JSONSchema;
+    /** Any conflicts discovered during the merge */
     readonly conflicts: readonly SchemaConflict[];
 };
+/**
+ * Represents a violation of a `not` schema constraint.
+ *
+ * A not violation occurs when the current value matches a schema
+ * specified in the `not` keyword, meaning the value is disallowed.
+ */
 export type NotViolation = {
+    /** JSON path segments identifying the location of the violation */
     readonly path: ReadonlyArray<PropertyKey>;
+    /** Human-readable description of the violation */
     readonly message: string;
+    /** The `not` schema that the value incorrectly matches */
     readonly notSchema: JSONSchema;
 };
+/**
+ * Configuration options for creating a {@link SchemaContext}.
+ *
+ * These options define the complete state needed to render a JSON Schema form control,
+ * including the root schema, current definition, navigation path, and validation support.
+ */
 export type SchemaContextOptions = {
+    /** The root JSON Schema document */
     schema: JSONSchemaDefinition;
+    /** The current schema definition being rendered */
     definition: JSONSchemaDefinition;
+    /** Path segments from root to the current position in the schema tree */
     path: ReadonlyArray<PropertyKey>;
+    /** Path segments for the parent of the current position */
     parentPath: ReadonlyArray<PropertyKey>;
+    /** Name of the current property (if inside an object) */
     propertyName: PropertyKey | undefined;
+    /** Whether the current field is required */
     required: boolean;
+    /** AJV instance for schema compilation and validation */
     ajv: Ajv | undefined;
 };

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

@@ -0,0 +1,19 @@
+/**
+ * Shared utilities for JSON Structure controls
+ */
+import type { StructureContext } from '../structure-context';
+import type { TypeDefinition } from '../structure-types';
+/**
+ * Create input wrapper options from context
+ * Shared by all control components
+ */
+export declare function createInputOptions(ctx: StructureContext): {
+    label: string | undefined;
+    description: string | undefined;
+    required: boolean;
+};
+/**
+ * Get the default value for a type based on its definition
+ * Used when creating new items in arrays, sets, maps, tuples, and objects
+ */
+export declare function makeDefaultValue(definition: TypeDefinition): unknown;

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

@@ -3,12 +3,11 @@
  *
  * 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;
+export declare function DeprecationBadge(): import("@tempots/dom").Renderable;
 /**
  * Wrap label with deprecation indicator if field is deprecated
  */
-export declare function withDeprecationBadge(label: string | undefined, isDeprecated: boolean): TNode;
+export declare function withDeprecationBadge(label: string | undefined, isDeprecated: boolean): string | import("@tempots/dom").Renderable;

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

@@ -1,6 +1,7 @@
 /**
  * Controls module exports
  */
+export * from './control-utils';
 export * from './generic-control';
 export * from './string-control';
 export * from './boolean-control';