@tempots/beatui 0.82.1 → 0.83.0

package/dist/types/components/form/controller/path.d.ts

@@ -1,5 +1,74 @@
+/**
+ * A single segment in a controller path.
+ *
+ * - `string` represents a named property (e.g., `'name'`, `'address'`)
+ * - `number` represents an array index (e.g., `0`, `1`)
+ */
 export type PathSegment = string | number;
+/**
+ * An array of path segments representing the location of a value within a nested data structure.
+ *
+ * @example
+ * ```typescript
+ * const path: Path = ['users', 0, 'name']
+ * // Represents: users[0].name
+ * ```
+ */
 export type Path = PathSegment[];
+/**
+ * Parses a dot-separated path string into an array of path segments.
+ *
+ * String segments are treated as property names. Segments matching the pattern
+ * `[n]` (where `n` is a number) are parsed as numeric array indices.
+ *
+ * @param path - The dot-separated path string to parse (e.g., `'users.[0].name'`)
+ * @returns An array of path segments
+ *
+ * @example
+ * ```typescript
+ * parsePath('users.[0].name')
+ * // => ['users', 0, 'name']
+ *
+ * parsePath('settings.theme')
+ * // => ['settings', 'theme']
+ * ```
+ */
 export declare function parsePath(path: string): Path;
+/**
+ * Wraps a single path segment into its string representation for path serialization.
+ *
+ * - Numeric segments are wrapped in brackets: `0` becomes `[0]`
+ * - String segments are prefixed with a dot: `'name'` becomes `.name`
+ *
+ * @param v - The path segment to wrap
+ * @returns The formatted segment string
+ *
+ * @example
+ * ```typescript
+ * wrapSegment(0)       // => '[0]'
+ * wrapSegment('name')  // => '.name'
+ * ```
+ */
 export declare function wrapSegment(v: number | string): string;
+/**
+ * Converts an array of path segments into a human-readable string representation.
+ *
+ * The first segment is rendered without a leading dot. Subsequent segments use
+ * {@link wrapSegment} formatting.
+ *
+ * @param path - The path segments to serialize
+ * @returns The string representation of the path, or an empty string if the path is empty
+ *
+ * @example
+ * ```typescript
+ * pathToString(['users', 0, 'name'])
+ * // => 'users[0].name'
+ *
+ * pathToString(['settings', 'theme'])
+ * // => 'settings.theme'
+ *
+ * pathToString([])
+ * // => ''
+ * ```
+ */
 export declare function pathToString(path: Path): string;

package/dist/types/components/form/controller/union-controller.d.ts

@@ -3,51 +3,146 @@ import { Path } from './path';
 import { Controller } from './controller';
 import { ControllerValidation } from './controller-validation';
 /**
- * Union type definition for the controller
+ * Defines a single branch (variant) within a union type for use with {@link UnionController}.
+ *
+ * Each branch has a unique key, a display label, a detection predicate, an optional
+ * conversion function for migrating values between branches, and a factory for default values.
+ *
+ * @typeParam T - The value type produced by this branch
+ *
+ * @example
+ * ```typescript
+ * const stringBranch: UnionBranch<string> = {
+ *   key: 'string',
+ *   label: 'Text',
+ *   detect: (v) => typeof v === 'string',
+ *   defaultValue: () => '',
+ * }
+ *
+ * const numberBranch: UnionBranch<number> = {
+ *   key: 'number',
+ *   label: 'Number',
+ *   detect: (v) => typeof v === 'number',
+ *   convert: (v) => {
+ *     const n = Number(v)
+ *     return isNaN(n) ? { ok: false } : { ok: true, value: n }
+ *   },
+ *   defaultValue: () => 0,
+ * }
+ * ```
  */
 export interface UnionBranch<T = unknown> {
-    /** Unique identifier for this branch */
+    /** Unique identifier for this branch (used as path segment and lookup key) */
     key: string;
-    /** Display label for this branch */
+    /** Human-readable display label for this branch, shown in UI selectors */
     label: string;
-    /** Type guard function to detect if a value belongs to this branch */
+    /** Type guard function that returns `true` if a value belongs to this branch */
     detect: (value: unknown) => boolean;
-    /** Function to convert a value to this branch type */
+    /** Optional function to convert a value from another branch to this branch's type. Returns `{ ok: true, value }` on success or `{ ok: false }` on failure. */
     convert?: (value: unknown) => {
         ok: true;
         value: T;
     } | {
         ok: false;
     };
-    /** Default value for this branch when switching to it */
+    /** Factory function that produces the default value when switching to this branch */
     defaultValue: () => T;
 }
+/**
+ * Determines when validation errors are displayed.
+ *
+ * - `'onSubmit'` - Errors shown only after form submission
+ * - `'eager'` - Errors shown immediately as values change
+ * - `'onTouched'` - Errors shown after the field has been touched/blurred
+ */
 export type ValidationMode = 'onSubmit' | 'eager' | 'onTouched';
 /**
- * Controller for union types that manages multiple possible value types
+ * Controller for union/discriminated types that manages multiple possible value branches.
+ *
+ * Extends `Controller<T>` to support values that can be one of several types.
+ * Automatically detects which branch is active based on the current value,
+ * creates per-branch sub-controllers lazily, and supports switching between branches
+ * with optional value conversion.
+ *
+ * @typeParam T - The union type representing all possible value shapes
+ *
+ * @example
+ * ```typescript
+ * import { UnionController, UnionBranch } from '@tempots/beatui'
+ *
+ * type Value = string | number
+ *
+ * const branches: UnionBranch[] = [
+ *   { key: 'string', label: 'Text', detect: v => typeof v === 'string', defaultValue: () => '' },
+ *   { key: 'number', label: 'Number', detect: v => typeof v === 'number', defaultValue: () => 0 },
+ * ]
+ *
+ * // The active branch is automatically detected from the current value
+ * console.log(unionCtrl.activeBranch.value) // 'string' or 'number'
+ *
+ * // Switch to a different branch
+ * unionCtrl.switchToBranch('number')
+ * ```
  */
 export declare class UnionController<T> extends Controller<T> {
     #private;
+    /** The immutable list of branch definitions for this union */
     readonly branches: readonly UnionBranch[];
+    /** Reactive signal containing the key of the currently active branch */
     readonly activeBranch: Signal<string>;
+    /**
+     * Creates a new UnionController.
+     *
+     * @param path - The path segments identifying this controller in the form tree
+     * @param change - Callback to propagate value changes to the parent
+     * @param signal - Reactive signal holding the current union value
+     * @param status - Reactive signal holding the current validation status
+     * @param parent - Parent context providing disabled state and optional validation mode
+     * @param branches - Array of branch definitions describing the possible value types
+     * @param equals - Optional equality function for comparing values. Defaults to `strictEqual`.
+     */
     constructor(path: Path, change: (value: T) => void, signal: Signal<T>, status: Signal<ControllerValidation>, parent: {
         disabled: Signal<boolean>;
         validationMode?: Signal<ValidationMode>;
     }, branches: UnionBranch[], equals?: (a: T, b: T) => boolean);
     /**
-     * Get the controller for the currently active branch
+     * Gets the controller for the currently active branch.
+     *
+     * The returned controller's value and type correspond to the branch that
+     * matches the current union value.
+     *
+     * @returns The `Controller<unknown>` for the active branch
      */
     get activeController(): Controller<unknown>;
     /**
-     * Get a controller for a specific branch
+     * Gets or creates a controller for a specific branch by key.
+     *
+     * Controllers are created lazily and cached for subsequent calls.
+     *
+     * @param branchKey - The unique key of the branch to get a controller for
+     * @returns The `Controller<unknown>` for the specified branch
+     * @throws Error if the branch key is not found in the branches array
      */
     getBranchController(branchKey: string): Controller<unknown>;
     /**
-     * Switch to a different branch
+     * Switches the union value to a different branch.
+     *
+     * Attempts the following in order:
+     * 1. If already on the target branch, returns `true` immediately
+     * 2. If the branch has a `convert` function, tries to convert the current value
+     * 3. If conversion fails and `confirmChange` is true, prompts the user with `window.confirm`
+     * 4. Sets the value to the branch's default value
+     *
+     * @param branchKey - The key of the branch to switch to
+     * @param confirmChange - If true, prompts the user before losing the current value when conversion fails
+     * @returns `true` if the switch was successful, `false` if the user cancelled
+     * @throws Error if the branch key is not found in the branches array
      */
     switchToBranch(branchKey: string, confirmChange?: boolean): boolean;
     /**
-     * Get the current active branch definition
+     * Gets the {@link UnionBranch} definition for the currently active branch.
+     *
+     * @returns The active branch definition, or `undefined` if no branch matches
      */
     get activeBranchDefinition(): UnionBranch | undefined;
 }

package/dist/types/components/form/controller/utils.d.ts

@@ -1,4 +1,71 @@
 import { Controller } from './controller';
+/**
+ * Transforms a controller that uses `undefined` for absent values into one that uses `null`.
+ *
+ * Useful for bridging between APIs that represent missing values differently.
+ * The returned controller exposes `null` to consumers while the underlying controller stores `undefined`.
+ *
+ * @typeParam T - The non-nullable base value type
+ *
+ * @param controller - A controller whose value is `NonNullable<T> | undefined`
+ * @returns A new controller whose value is `NonNullable<T> | null`
+ *
+ * @example
+ * ```typescript
+ * import { transformNullToUndefined } from '@tempots/beatui'
+ *
+ * // Original controller uses undefined for absent values
+ * const undefinedCtrl: Controller<string | undefined> = ...
+ *
+ * // Transform to use null instead
+ * const nullCtrl = transformNullToUndefined(undefinedCtrl)
+ * // nullCtrl.signal.value is string | null
+ * ```
+ */
 export declare function transformNullToUndefined<T>(controller: Controller<NonNullable<T> | undefined>): Controller<NonNullable<T> | null>;
+/**
+ * Transforms a controller that uses `undefined` for absent values into one that uses empty strings.
+ *
+ * Maps `undefined` to `''` when reading and `''` to `undefined` when writing.
+ * Useful for text inputs that need to represent "no value" as an empty string.
+ *
+ * @param controller - A controller whose value is `string | undefined`
+ * @returns A new controller whose value is always `string` (never undefined)
+ *
+ * @example
+ * ```typescript
+ * import { transformEmptyStringToUndefined } from '@tempots/beatui'
+ *
+ * // Original controller uses undefined for empty
+ * const optionalCtrl: Controller<string | undefined> = ...
+ *
+ * // Transform so empty string maps to undefined
+ * const stringCtrl = transformEmptyStringToUndefined(optionalCtrl)
+ * // stringCtrl.signal.value is always string
+ * ```
+ */
 export declare function transformEmptyStringToUndefined(controller: Controller<NonNullable<string> | undefined>): Controller<NonNullable<string>>;
+/**
+ * Transforms a controller that uses `null` for absent values into one that uses `undefined`.
+ *
+ * The inverse of {@link transformNullToUndefined}. Maps `null` to `undefined` when reading
+ * and `undefined` to `null` when writing.
+ *
+ * @typeParam T - The non-nullable base value type
+ *
+ * @param controller - A controller whose value is `NonNullable<T> | null`
+ * @returns A new controller whose value is `NonNullable<T> | undefined`
+ *
+ * @example
+ * ```typescript
+ * import { transformUndefinedToNull } from '@tempots/beatui'
+ *
+ * // Original controller uses null for absent values
+ * const nullCtrl: Controller<string | null> = ...
+ *
+ * // Transform to use undefined instead
+ * const undefinedCtrl = transformUndefinedToNull(nullCtrl)
+ * // undefinedCtrl.signal.value is string | undefined
+ * ```
+ */
 export declare function transformUndefinedToNull<T>(controller: Controller<NonNullable<T> | null>): Controller<NonNullable<T> | undefined>;

package/dist/types/components/form/input/advanced-slider.d.ts

@@ -0,0 +1,143 @@
+import { Value, TNode } from '@tempots/dom';
+import { ControlSize } from '../../theme';
+import { ThemeColorName } from '../../../tokens';
+/**
+ * Definition of a tick mark on the slider track.
+ */
+export interface SliderTick {
+    /** The numeric value where this tick appears */
+    value: number;
+    /** Optional label displayed below the tick mark */
+    label?: string;
+}
+/**
+ * Configuration options for the {@link AdvancedSlider} component.
+ *
+ * Supports single value, range (two thumbs), and multi-point (arbitrary number
+ * of thumbs) modes. Features tick marks, value labels, and customizable colors.
+ */
+export interface AdvancedSliderOptions {
+    /** Minimum value of the slider range */
+    min?: number;
+    /** Maximum value of the slider range */
+    max?: number;
+    /** Step increment between valid values. @default 1 */
+    step?: number;
+    /** Whether the slider is disabled. @default false */
+    disabled?: Value<boolean>;
+    /** Visual size of the slider. @default 'md' */
+    size?: Value<ControlSize>;
+    /** Theme color for the filled track and thumbs. @default 'primary' */
+    color?: Value<ThemeColorName>;
+    /**
+     * Single value mode: the current slider value.
+     * Use this for a simple single-thumb slider.
+     */
+    value?: Value<number>;
+    /** Callback for single-value mode changes */
+    onChange?: (value: number) => void;
+    /**
+     * Range mode: a two-element array `[low, high]`.
+     * When provided, two thumbs are rendered.
+     */
+    range?: Value<[number, number]>;
+    /** Callback for range mode changes */
+    onRangeChange?: (range: [number, number]) => void;
+    /**
+     * Multi-point mode: an array of values, each getting its own thumb.
+     * When provided, multiple thumbs are rendered at initialization time.
+     * The number of points is fixed after component creation.
+     */
+    points?: Value<number[]>;
+    /** Callback for multi-point mode changes */
+    onPointsChange?: (points: number[]) => void;
+    /**
+     * Tick marks along the slider track.
+     * Can be `true` for automatic step-based ticks, or an array of custom tick definitions.
+     */
+    ticks?: boolean | SliderTick[];
+    /**
+     * Whether to show the current value label(s) above the thumb(s).
+     * @default false
+     */
+    showValue?: boolean;
+    /**
+     * Custom formatter for the displayed value labels.
+     * @default (v) => String(v)
+     */
+    formatValue?: (value: number) => string;
+    /**
+     * Colors for individual segments between consecutive thumbs in multi-point mode.
+     * Each entry corresponds to the segment between thumb[i] and thumb[i+1].
+     * If fewer colors than segments are provided, remaining segments use the default color.
+     * If not provided, a single fill spanning all thumbs is used (existing behavior).
+     */
+    segmentColors?: ThemeColorName[];
+    /**
+     * Custom renderer for the thumb element. When provided, replaces the default
+     * circular thumb with your custom content. The rendered content is placed
+     * inside the thumb container that handles positioning, ARIA attributes,
+     * keyboard navigation, and pointer events.
+     *
+     * @param index - The zero-based index of the thumb
+     * @param value - A reactive value holding the current thumb position
+     * @returns A TNode to render as the thumb
+     */
+    renderThumb?: (index: number, value: Value<number>) => TNode;
+}
+/**
+ * An advanced slider component supporting single value, range selection,
+ * and multi-point modes with tick marks and value display.
+ *
+ * - **Single mode**: Pass `value` and `onChange` for a standard single-thumb slider.
+ * - **Range mode**: Pass `range` and `onRangeChange` for a two-thumb range selector.
+ * - **Multi-point mode**: Pass `points` and `onPointsChange` for arbitrary number of thumbs.
+ *
+ * Additional features include configurable tick marks (automatic or custom),
+ * value labels above the thumbs, step snapping, and theme-aware coloring.
+ *
+ * @param options - Configuration for the slider
+ * @returns A styled slider element
+ *
+ * @example
+ * ```ts
+ * // Simple slider with value display
+ * const vol = prop(50)
+ * AdvancedSlider({
+ *   value: vol, onChange: vol.set,
+ *   min: 0, max: 100,
+ *   showValue: true,
+ *   ticks: true,
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Range slider
+ * const priceRange = prop<[number, number]>([20, 80])
+ * AdvancedSlider({
+ *   range: priceRange, onRangeChange: priceRange.set,
+ *   min: 0, max: 100, step: 5,
+ *   ticks: [
+ *     { value: 0, label: '$0' },
+ *     { value: 50, label: '$50' },
+ *     { value: 100, label: '$100' },
+ *   ],
+ *   showValue: true,
+ *   formatValue: v => `$${v}`,
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Multi-point slider
+ * const pts = prop([10, 40, 70])
+ * AdvancedSlider({
+ *   points: pts, onPointsChange: pts.set,
+ *   min: 0, max: 100,
+ *   showValue: true,
+ *   color: 'green',
+ * })
+ * ```
+ */
+export declare function AdvancedSlider({ min, max, step, disabled, size, color, value, onChange, range, points, onRangeChange, onPointsChange, ticks, showValue, formatValue, segmentColors, renderThumb, }: AdvancedSliderOptions): import("@tempots/dom").Renderable;

package/dist/types/components/form/input/appearance-selector.d.ts

@@ -1,9 +1,48 @@
 import { AppearancePreference } from '../../theme';
 import { Value } from '@tempots/dom';
+/**
+ * Options for the {@link AppearanceSelector} component.
+ */
 export type AppearanceSelectorOptions = {
+    /** The current appearance preference value. */
     value: Value<AppearancePreference>;
+    /** Callback invoked when the user selects a different appearance. */
     onChange?: (value: AppearancePreference) => void;
+    /**
+     * Whether the selector is disabled.
+     * @default false
+     */
     disabled?: Value<boolean>;
 };
+/**
+ * A segmented input for selecting the application appearance (light, dark, or system).
+ *
+ * Renders three icon segments for system (laptop), light (sun), and dark (moon) modes
+ * using the {@link SegmentedInput} component.
+ *
+ * @param options - Configuration options for the appearance selector.
+ * @returns A renderable segmented appearance selector component.
+ *
+ * @example
+ * ```ts
+ * AppearanceSelector({
+ *   value: prop<AppearancePreference>('system'),
+ *   onChange: pref => console.log('Appearance:', pref),
+ * })
+ * ```
+ */
 export declare function AppearanceSelector({ value, onChange, disabled, }: AppearanceSelectorOptions): import("@tempots/dom").Renderable;
+/**
+ * A standalone appearance selector that automatically connects to the application's
+ * {@link Theme} provider. Reads and writes the appearance preference from the
+ * current theme context without requiring manual wiring.
+ *
+ * @returns A renderable standalone appearance selector component.
+ *
+ * @example
+ * ```ts
+ * // Just drop it in -- no props needed
+ * StandaloneAppearanceSelector()
+ * ```
+ */
 export declare function StandaloneAppearanceSelector(): import("@tempots/dom").Renderable;

package/dist/types/components/form/input/base64-input.d.ts

@@ -1,10 +1,44 @@
 import { Merge, Value } from '@tempots/dom';
 import { InputOptions } from './input-options';
 import { FileInputMode } from './files-input';
+/**
+ * Options for the {@link Base64Input} component.
+ * Extends standard `InputOptions` for a single base64-encoded file string.
+ */
 export type Base64InputOptions = Merge<InputOptions<string | undefined>, {
+    /** Comma-separated list of accepted MIME types or file extensions. */
     accept?: Value<string>;
+    /** Maximum allowed file size in bytes. */
     maxFileSize?: Value<number>;
+    /**
+     * Display mode for the file input.
+     * @default 'default'
+     */
     mode?: Value<FileInputMode>;
+    /**
+     * Whether to show the selected file in a list below the drop zone.
+     * @default true
+     */
     showFileList?: Value<boolean>;
 }>;
+/**
+ * A single-file input component that produces a base64-encoded string value.
+ *
+ * Wraps {@link Base64sInput} with `maxFiles: 1`, providing a file upload interface
+ * that converts the selected file to a base64 string. Useful for embedding small
+ * files (images, documents) directly as base64 data.
+ *
+ * @param options - Configuration options for the base64 file input.
+ * @returns A renderable base64 file input component.
+ *
+ * @example
+ * ```ts
+ * Base64Input({
+ *   value: prop<string | undefined>(undefined),
+ *   accept: 'image/png,image/jpeg',
+ *   maxFileSize: 2 * 1024 * 1024, // 2 MB
+ *   onChange: base64 => console.log('Base64 length:', base64?.length),
+ * })
+ * ```
+ */
 export declare function Base64Input(options: Base64InputOptions): import("@tempots/dom").Renderable;

package/dist/types/components/form/input/base64s-input.d.ts

@@ -1,12 +1,59 @@
 import { Merge, Value } from '@tempots/dom';
 import { FileInputMode } from './files-input';
 import { InputOptions } from './input-options';
+/**
+ * Options for the {@link Base64sInput} component.
+ * Extends standard `InputOptions` for multiple base64-encoded file strings.
+ */
 export type Base64sInputOptions = Merge<InputOptions<string[]>, {
+    /** Comma-separated list of accepted MIME types or file extensions. */
     accept?: Value<string>;
+    /** Maximum number of files that can be selected. */
     maxFiles?: Value<number>;
+    /** Maximum allowed file size in bytes per file. */
     maxFileSize?: Value<number>;
+    /**
+     * Display mode for the file input.
+     * @default 'default'
+     */
     mode?: Value<FileInputMode>;
+    /**
+     * Whether to show the selected files in a list below the drop zone.
+     * @default true
+     */
     showFileList?: Value<boolean>;
 }>;
+/**
+ * Converts a `File` object to a base64-encoded string (without the data URL prefix).
+ *
+ * @param file - The file to convert.
+ * @returns A promise that resolves with the base64-encoded string content.
+ *
+ * @example
+ * ```ts
+ * const base64 = await fileToBase64(myFile)
+ * console.log(base64) // 'iVBORw0KGgoAAAANSUhEUg...'
+ * ```
+ */
 export declare function fileToBase64(file: File): Promise<string>;
+/**
+ * A multi-file input component that produces an array of base64-encoded strings.
+ *
+ * Wraps {@link FilesInput}, converting selected files to base64 and reconstructing
+ * `File` objects from base64 strings for display. Automatically detects MIME types
+ * from file magic bytes for proper thumbnail rendering.
+ *
+ * @param options - Configuration options for the multi-file base64 input.
+ * @returns A renderable multi-file base64 input component.
+ *
+ * @example
+ * ```ts
+ * Base64sInput({
+ *   value: prop<string[]>([]),
+ *   accept: 'image/*',
+ *   maxFiles: 3,
+ *   onChange: base64s => console.log('Files:', base64s.length),
+ * })
+ * ```
+ */
 export declare function Base64sInput(options: Base64sInputOptions): import("@tempots/dom").Renderable;

package/dist/types/components/form/input/bigint-input.d.ts

@@ -1,9 +1,36 @@
 import { Value } from '@tempots/dom';
 import { Merge } from '@tempots/std';
 import { InputOptions } from './input-options';
+/**
+ * Options for the {@link BigintInput} component.
+ * Extends standard `InputOptions` for `bigint` values with stepper and range constraints.
+ */
 export type BigintInputOptions = Merge<InputOptions<bigint>, {
+    /** Step value for increment/decrement buttons. If provided, stepper buttons are shown. */
     step?: Value<bigint>;
+    /** Minimum allowed value. Values below this are clamped. */
     min?: Value<bigint>;
+    /** Maximum allowed value. Values above this are clamped. */
     max?: Value<bigint>;
 }>;
+/**
+ * A numeric input component for `bigint` values with optional stepper buttons.
+ *
+ * Uses a masked input that only allows digit characters. Supports min/max
+ * clamping and increment/decrement buttons (with Shift+click for 10x step).
+ *
+ * @param options - Configuration options for the bigint input.
+ * @returns A renderable bigint input component.
+ *
+ * @example
+ * ```ts
+ * BigintInput({
+ *   value: prop(0n),
+ *   step: 1n,
+ *   min: 0n,
+ *   max: 1000n,
+ *   onChange: v => console.log('Value:', v),
+ * })
+ * ```
+ */
 export declare const BigintInput: (options: BigintInputOptions) => import("@tempots/dom").Renderable;