@tempots/beatui 0.82.0 → 0.83.0

package/dist/types/components/form/input/plain-time-input.d.ts

@@ -1,3 +1,20 @@
+/**
+ * An input component for `Temporal.PlainTime` values.
+ *
+ * Renders a native HTML `time` input. Created via {@link createTemporalInput}
+ * with `PlainTime` serialization. Requires the Temporal polyfill.
+ *
+ * @param options - Standard input options for a `PlainTime` value.
+ * @returns A renderable plain time input component.
+ *
+ * @example
+ * ```ts
+ * PlainTimeInput({
+ *   value: prop(Temporal.PlainTime.from('14:30')),
+ *   onChange: time => console.log('Time:', time.toString()),
+ * })
+ * ```
+ */
 export declare const PlainTimeInput: (options: {
     autocomplete?: import("@tempots/dom").Value<string> | undefined;
     autofocus?: import("@tempots/dom").Value<boolean> | undefined;

package/dist/types/components/form/input/plain-year-month-input.d.ts

@@ -1,3 +1,20 @@
+/**
+ * An input component for `Temporal.PlainYearMonth` values.
+ *
+ * Renders a native HTML `month` input. Created via {@link createTemporalInput}
+ * with `PlainYearMonth` serialization. Requires the Temporal polyfill.
+ *
+ * @param options - Standard input options for a `PlainYearMonth` value.
+ * @returns A renderable plain year-month input component.
+ *
+ * @example
+ * ```ts
+ * PlainYearMonthInput({
+ *   value: prop(Temporal.PlainYearMonth.from('2024-01')),
+ *   onChange: ym => console.log('YearMonth:', ym.toString()),
+ * })
+ * ```
+ */
 export declare const PlainYearMonthInput: (options: {
     autocomplete?: import("@tempots/dom").Value<string> | undefined;
     autofocus?: import("@tempots/dom").Value<boolean> | undefined;

package/dist/types/components/form/input/radio-group.d.ts

@@ -0,0 +1,108 @@
+import { TNode, Value } from '@tempots/dom';
+import { ControlSize } from '../../theme';
+/**
+ * Configuration for a single radio option within a {@link RadioGroup}.
+ *
+ * @template V - The type of the option's value
+ */
+export interface RadioOption<V = string> {
+    /** The value associated with this radio option */
+    value: V;
+    /** Display label for the radio option */
+    label: string;
+    /** Optional description text displayed below the label */
+    description?: string;
+    /** Whether this specific option is disabled */
+    disabled?: boolean;
+}
+/**
+ * Configuration options for the {@link RadioGroup} component.
+ *
+ * @template V - The type of the radio values (defaults to string)
+ */
+export interface RadioGroupOptions<V = string> {
+    /** Array of radio options to render */
+    options: Value<RadioOption<V>[]>;
+    /** The currently selected value */
+    value: Value<V>;
+    /** Callback invoked when a different option is selected */
+    onChange?: (value: V) => void;
+    /** HTML name attribute for the radio group (generated if not provided) */
+    name?: string;
+    /** Whether the entire radio group is disabled */
+    disabled?: Value<boolean>;
+    /**
+     * Layout orientation of the radio options.
+     * @default 'vertical'
+     */
+    orientation?: Value<'horizontal' | 'vertical'>;
+    /**
+     * Visual size of the radio controls.
+     * @default 'md'
+     */
+    size?: Value<ControlSize>;
+    /**
+     * Additional CSS class name(s) to apply to the root element.
+     */
+    class?: Value<string>;
+}
+/**
+ * Renders a group of radio buttons allowing the user to select one option from
+ * a list of mutually exclusive choices.
+ *
+ * Uses native `<input type="radio">` elements for proper form integration and
+ * accessibility, but applies custom styling via CSS. Each option can have a
+ * label and optional description text. The radio group supports both horizontal
+ * and vertical layouts, multiple size variants, and individual or group-wide
+ * disabled states.
+ *
+ * @template V - The type of values for the radio options
+ * @param options - Configuration options for the radio group
+ * @returns A styled radio group element with native radio inputs
+ *
+ * @example
+ * ```typescript
+ * import { prop } from '@tempots/dom'
+ * import { RadioGroup } from '@tempots/beatui'
+ *
+ * const theme = prop<'light' | 'dark'>('light')
+ * RadioGroup({
+ *   options: [
+ *     { value: 'light', label: 'Light Mode' },
+ *     { value: 'dark', label: 'Dark Mode' },
+ *   ],
+ *   value: theme,
+ *   onChange: theme.set,
+ *   orientation: 'horizontal'
+ * })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With descriptions and disabled option
+ * RadioGroup({
+ *   options: [
+ *     {
+ *       value: 'basic',
+ *       label: 'Basic Plan',
+ *       description: '$10/month - Essential features'
+ *     },
+ *     {
+ *       value: 'pro',
+ *       label: 'Pro Plan',
+ *       description: '$30/month - Advanced features'
+ *     },
+ *     {
+ *       value: 'enterprise',
+ *       label: 'Enterprise',
+ *       description: 'Contact sales',
+ *       disabled: true
+ *     }
+ *   ],
+ *   value: prop('basic'),
+ *   onChange: (v) => console.log('Selected:', v),
+ *   size: 'lg'
+ * })
+ * ```
+ */
+export declare function RadioGroup<V = string>({ options, value, onChange, name, disabled, orientation, size, class: cls, }: RadioGroupOptions<V>): TNode;

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

@@ -2,14 +2,71 @@ import { Value } from '@tempots/dom';
 import { InputOptions } from './input-options';
 import { ThemeColorName } from '../../../tokens';
 import { ControlSize } from '../../theme/types';
+/**
+ * Configuration options for the {@link RatingInput} component.
+ *
+ * Extends {@link InputOptions} for numeric values with properties to control the
+ * maximum rating, icon appearance, theme colors, and rounding precision.
+ */
 type RatingInputOptions = InputOptions<number> & {
+    /** Maximum number of rating icons (stars). @default 5 */
     max?: Value<number>;
+    /** Theme color for filled (active) icons. @default 'yellow' */
     fullColor?: Value<ThemeColorName>;
+    /** Theme color for empty (inactive) icons. @default 'neutral' */
     emptyColor?: Value<ThemeColorName>;
+    /** Icon name for filled (active) rating icons. @default 'line-md:star-alt-filled' */
     fullIcon?: Value<string>;
+    /** Icon name for empty (inactive) rating icons. @default 'line-md:star-alt' */
     emptyIcon?: Value<string>;
+    /** Visual size of the rating icons. @default 'md' */
     size?: Value<ControlSize>;
+    /** Step size for rounding during keyboard interactions (e.g., 0.25 for quarter steps). @default 1 */
     rounding?: Value<number>;
 };
+/**
+ * A star rating input component with fractional precision support and ARIA slider semantics.
+ *
+ * Renders a row of rating icons (stars by default) inside an {@link InputContainer} that
+ * supports click-based fractional rating (the click position within each icon determines
+ * the fractional value) and full keyboard navigation via arrow keys, Home, and End.
+ * Each icon uses a CSS clip mask to show the precise fill level, enabling half-star or
+ * quarter-star precision based on the `rounding` option.
+ *
+ * Uses ARIA `role="slider"` with `aria-valuenow`, `aria-valuemin`, `aria-valuemax`,
+ * and `aria-valuetext` for accessibility.
+ *
+ * @param options - Configuration options for the rating input
+ * @returns A styled rating input element with interactive icons, wrapped in an InputContainer
+ *
+ * @example
+ * ```ts
+ * import { prop } from '@tempots/dom'
+ * import { RatingInput } from '@tempots/beatui'
+ *
+ * const rating = prop(3.5)
+ * RatingInput({
+ *   value: rating,
+ *   onChange: rating.set,
+ *   max: 5,
+ *   rounding: 0.5,
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Custom heart icons with quarter-step precision
+ * RatingInput({
+ *   value: prop(0),
+ *   onChange: (v) => console.log('Rating:', v),
+ *   max: 10,
+ *   fullIcon: 'mdi:heart',
+ *   emptyIcon: 'mdi:heart-outline',
+ *   fullColor: 'red',
+ *   rounding: 0.25,
+ *   size: 'lg',
+ * })
+ * ```
+ */
 export declare const RatingInput: (options: RatingInputOptions) => import("@tempots/dom").Renderable;
 export {};

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

@@ -1,10 +1,79 @@
 import { TNode, Value } from '@tempots/dom';
 import { ControlSize } from '../../theme';
+import { ThemeColorName } from '../../../tokens';
+/**
+ * Configuration options for the {@link SegmentedInput} component.
+ *
+ * @template T - A record type mapping segment keys to their display labels (as TNode)
+ * @template K - The key type of the record (defaults to keyof T)
+ */
 export interface SegmentedInputOptions<T extends Record<string, TNode>, K extends keyof T = keyof T> {
+    /** A record mapping segment identifiers to their display content (text, icons, or any TNode) */
     options: T;
+    /** The currently selected segment key */
     value: Value<K>;
+    /** Callback invoked when a different segment is selected */
     onChange?: (value: K) => void;
+    /** Visual size of the segmented control. @default 'md' */
     size?: Value<ControlSize>;
+    /** Whether the segmented control is disabled. @default false */
     disabled?: Value<boolean>;
+    /**
+     * Shape variant. `'pill'` uses fully rounded corners, `'squared'` uses control-like
+     * border-radius and taller padding to match the height of regular inputs like TextInput.
+     * @default 'pill'
+     */
+    variant?: Value<'pill' | 'squared'>;
+    /**
+     * Theme color for the active segment indicator and text, using solid button-style coloring.
+     * When not set, uses the default white indicator with primary-tinted active text.
+     */
+    color?: Value<ThemeColorName>;
 }
-export declare function SegmentedInput<T extends Record<string, TNode>>({ options, value, onChange, size, disabled, }: SegmentedInputOptions<T, keyof T>, ...children: TNode[]): import("@tempots/dom").Renderable;
+/**
+ * A segmented control input that allows selecting one of several mutually exclusive options.
+ *
+ * Renders a horizontal row of clickable segments with a sliding indicator that animates
+ * to highlight the currently selected segment. Each segment is defined by a key-value pair
+ * in the `options` record, where keys serve as identifiers and values are rendered as
+ * segment labels (text, icons, or any TNode). The sliding indicator width and position
+ * are dynamically measured from the DOM using {@link ElementRect} and updated via
+ * `requestAnimationFrame`.
+ *
+ * @template T - A record type mapping segment keys to their display labels
+ * @param options - Configuration options for the segmented control
+ * @param children - Additional child nodes to render after the segmented control
+ * @returns A styled segmented control element with animated indicator
+ *
+ * @example
+ * ```ts
+ * import { prop } from '@tempots/dom'
+ * import { SegmentedInput } from '@tempots/beatui'
+ *
+ * const view = prop<'list' | 'grid' | 'table'>('list')
+ * SegmentedInput({
+ *   options: {
+ *     list: 'List',
+ *     grid: 'Grid',
+ *     table: 'Table',
+ *   },
+ *   value: view,
+ *   onChange: view.set,
+ *   size: 'md',
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * // With icon labels
+ * SegmentedInput({
+ *   options: {
+ *     light: Icon({ icon: 'line-md:sun' }),
+ *     dark: Icon({ icon: 'line-md:moon' }),
+ *   },
+ *   value: prop<'light' | 'dark'>('light'),
+ *   onChange: (v) => console.log('Theme:', v),
+ * })
+ * ```
+ */
+export declare function SegmentedInput<T extends Record<string, TNode>>({ options, value, onChange, size, disabled, variant, color, }: SegmentedInputOptions<T, keyof T>, ...children: TNode[]): import("@tempots/dom").Renderable;

package/dist/types/components/form/input/select-tags-input.d.ts

@@ -2,11 +2,41 @@ import { Value } from '@tempots/dom';
 import { InputOptions } from './input-options';
 import { DropdownOption } from './option';
 import { BaseControllerOptions, ControllerOptions } from '../control';
+/**
+ * Options for the {@link SelectTagsInput} component.
+ * Combines tag selection with a click-to-open dropdown menu.
+ *
+ * @typeParam T - The type of tag values.
+ */
 export type SelectTagsOptions<T> = {
+    /** The available dropdown options to choose from. */
     options: Value<DropdownOption<T>[]>;
+    /**
+     * Custom equality function for comparing option values.
+     * @default (a, b) => a === b
+     */
     equality?: (a: T, b: T) => boolean;
+    /** Placeholder text shown when no tags are selected. */
     placeholder?: Value<string>;
 } & InputOptions<T[]>;
+/**
+ * Renders selected values as removable tag chips with labels resolved from
+ * dropdown options. Shows a placeholder when no values are selected.
+ *
+ * @typeParam T - The type of tag values.
+ * @param opts - Options for the chips display.
+ * @returns A renderable chips component.
+ *
+ * @example
+ * ```ts
+ * Chips({
+ *   values: prop(['react']),
+ *   options: [{ type: 'value', value: 'react', label: 'React' }],
+ *   equality: (a, b) => a === b,
+ *   onRemove: v => console.log('Remove:', v),
+ * })
+ * ```
+ */
 export declare function Chips<T>(opts: {
     values: Value<T[]>;
     placeholder?: Value<string>;
@@ -15,6 +45,45 @@ export declare function Chips<T>(opts: {
     disabled?: Value<boolean>;
     onRemove: (v: T) => void;
 }): import("@tempots/dom").Renderable;
+/**
+ * A multi-select tag input with a click-to-open dropdown menu.
+ *
+ * Selected values are displayed as removable chips. Clicking the input area
+ * opens a dropdown menu where items can be toggled on/off. Supports grouped
+ * options and custom equality comparisons.
+ *
+ * @typeParam T - The type of tag values.
+ * @param options - Configuration options for the select tags input.
+ * @returns A renderable select tags input component.
+ *
+ * @example
+ * ```ts
+ * SelectTagsInput({
+ *   value: prop<string[]>([]),
+ *   options: [
+ *     { type: 'value', value: 'red', label: 'Red' },
+ *     { type: 'value', value: 'blue', label: 'Blue' },
+ *     { type: 'value', value: 'green', label: 'Green' },
+ *   ],
+ *   placeholder: 'Select colors...',
+ *   onChange: tags => console.log('Selected:', tags),
+ * })
+ * ```
+ */
 export declare function SelectTagsInput<T>(options: SelectTagsOptions<T>): import("@tempots/dom").Renderable;
+/**
+ * A base form control wrapper for {@link SelectTagsInput} using a raw controller.
+ *
+ * @typeParam T - The type of tag values.
+ * @param options - Base controller options for the select tags control.
+ * @returns A renderable form control component.
+ */
 export declare function BaseSelectTagsControl<T>(options: BaseControllerOptions<T[], SelectTagsOptions<T>>): any;
+/**
+ * A full form control wrapper for {@link SelectTagsInput} with label, error, and description support.
+ *
+ * @typeParam T - The type of tag values.
+ * @param options - Controller options for the select tags control.
+ * @returns A renderable form control component with wrapper.
+ */
 export declare function SelectTagsControl<T>(options: ControllerOptions<T[], SelectTagsOptions<T>>): import("@tempots/dom").Renderable;

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

@@ -1,15 +1,97 @@
 import { Value } from '@tempots/dom';
 import { InputOptions } from './input-options';
 import { Merge } from '@tempots/std';
+/**
+ * Configuration options for the {@link SliderInput} component.
+ *
+ * Extends {@link InputOptions} for numeric values with properties to control the
+ * slider range boundaries and step increment.
+ */
 export type SliderInputOptions = Merge<InputOptions<number>, {
+    /** Step increment between valid values on the slider */
     step?: Value<number>;
+    /** Minimum value of the slider range */
     min?: Value<number>;
+    /** Maximum value of the slider range */
     max?: Value<number>;
 }>;
+/**
+ * A range slider input component wrapping a native `<input type="range">` element.
+ *
+ * Renders a styled range slider inside an {@link InputContainer} with support for
+ * reactive min, max, and step values. The slider value is maintained as a number
+ * and emitted through the standard onChange/onInput/onBlur callbacks.
+ *
+ * @param options - Configuration options for the slider input
+ * @returns A styled range slider element wrapped in an InputContainer
+ *
+ * @example
+ * ```ts
+ * import { prop } from '@tempots/dom'
+ * import { SliderInput } from '@tempots/beatui'
+ *
+ * const volume = prop(50)
+ * SliderInput({
+ *   value: volume,
+ *   onChange: volume.set,
+ *   min: 0,
+ *   max: 100,
+ *   step: 1,
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Fine-grained slider with decimal steps
+ * SliderInput({
+ *   value: prop(0.5),
+ *   onInput: (v) => console.log('Value:', v),
+ *   min: 0,
+ *   max: 1,
+ *   step: 0.01,
+ * })
+ * ```
+ */
 export declare const SliderInput: (options: SliderInputOptions) => import("@tempots/dom").Renderable;
+/**
+ * Configuration options for the {@link NullableSliderInput} component.
+ *
+ * Similar to {@link SliderInputOptions} but accepts `null` as a valid value,
+ * representing an unset state. The slider visually defaults to the minimum value
+ * (or 0) when the value is null.
+ */
 export type NullableSliderInputOptions = Merge<InputOptions<number | null>, {
+    /** Step increment between valid values on the slider */
     step?: Value<number>;
+    /** Minimum value of the slider range */
     min?: Value<number>;
+    /** Maximum value of the slider range */
     max?: Value<number>;
 }>;
+/**
+ * A nullable range slider input that supports an unset (null) state with a reset button.
+ *
+ * Behaves like {@link SliderInput} but allows a `null` value to represent "not set".
+ * When the value is null, the slider thumb visually rests at the minimum position
+ * (or 0 if no min is specified). A reset button appears when the value is non-null
+ * and the input is not disabled, allowing the user to clear back to null.
+ *
+ * @param options - Configuration options for the nullable slider input
+ * @returns A styled range slider element with optional reset button, wrapped in an InputContainer
+ *
+ * @example
+ * ```ts
+ * import { prop } from '@tempots/dom'
+ * import { NullableSliderInput } from '@tempots/beatui'
+ *
+ * const brightness = prop<number | null>(null)
+ * NullableSliderInput({
+ *   value: brightness,
+ *   onChange: brightness.set,
+ *   min: 0,
+ *   max: 100,
+ *   step: 5,
+ * })
+ * ```
+ */
 export declare const NullableSliderInput: (options: NullableSliderInputOptions) => import("@tempots/dom").Renderable;

package/dist/types/components/form/input/switch.d.ts

@@ -1,17 +1,75 @@
 import { Value, TNode } from '@tempots/dom';
 import { ControlSize } from '../../theme/types';
 import { ThemeColorName } from '../../../tokens';
+/**
+ * Configuration options for the {@link Switch} component.
+ *
+ * Defines the properties for a toggle switch including its value, event callbacks,
+ * optional on/off labels, visual size, theme color, and accessibility attributes.
+ */
 export type SwitchOptions = {
+    /** The current boolean state of the switch (on/off) */
     value: Value<boolean>;
+    /** Callback invoked when the switch value changes (typically on click or keyboard toggle) */
     onChange?: (value: boolean) => void;
+    /** Callback invoked on every input event (fires alongside onChange) */
     onInput?: (value: boolean) => void;
+    /** Callback invoked when the switch loses focus */
     onBlur?: () => void;
+    /** Optional label displayed when the switch is in the off state */
     offLabel?: TNode;
+    /** Optional label displayed when the switch is in the on state */
     onLabel?: TNode;
+    /** Whether the switch is disabled and cannot be toggled. @default false */
     disabled?: Value<boolean>;
+    /** Visual size of the switch. @default 'md' */
     size?: ControlSize;
+    /** Unique HTML id attribute for the switch element */
     id?: string;
+    /** Theme color for the switch track when on. @default 'primary' */
     color?: Value<ThemeColorName>;
+    /** Tab index for keyboard navigation order. @default 0 */
     tabIndex?: Value<number>;
+    /** Whether to add vertical padding so the switch matches the height of text inputs at the same size. @default true */
+    matchInputHeight?: boolean;
 };
-export declare const Switch: ({ value, onChange, onInput, onBlur, offLabel, onLabel, disabled, size, id, color, tabIndex, }: SwitchOptions) => import("@tempots/dom").Renderable;
+/**
+ * A toggle switch component for boolean on/off states with animated thumb transition.
+ *
+ * Renders a custom switch control with ARIA `role="switch"` semantics, full keyboard
+ * support (Space and Enter to toggle), and a sliding thumb animation. The switch track
+ * color is theme-aware and configurable via the `color` property. Optional on/off labels
+ * appear inside the track and cross-fade based on the current state. The thumb position
+ * is calculated dynamically based on the track width and adapts to RTL layout direction.
+ *
+ * @param options - Configuration options for the switch
+ * @returns A styled switch element with animated thumb and optional labels
+ *
+ * @example
+ * ```ts
+ * import { prop } from '@tempots/dom'
+ * import { Switch } from '@tempots/beatui'
+ *
+ * const enabled = prop(false)
+ * Switch({
+ *   value: enabled,
+ *   onChange: enabled.set,
+ *   size: 'md',
+ *   color: 'primary',
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * // With on/off labels
+ * Switch({
+ *   value: prop(true),
+ *   onChange: (v) => console.log('Toggled:', v),
+ *   onLabel: 'ON',
+ *   offLabel: 'OFF',
+ *   color: 'green',
+ *   size: 'lg',
+ * })
+ * ```
+ */
+export declare const Switch: ({ value, onChange, onInput, onBlur, offLabel, onLabel, disabled, size, id, color, tabIndex, matchInputHeight, }: SwitchOptions) => import("@tempots/dom").Renderable;

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

@@ -0,0 +1,19 @@
+import { TNode, Value } from '@tempots/dom';
+import { ControlSize } from '../../theme/types';
+export interface TagInputOptions {
+    /** Current list of tag values */
+    values: Value<string[]>;
+    /** Callback when tags change */
+    onChange?: (values: string[]) => void;
+    /** Placeholder text when no tags and input is empty */
+    placeholder?: Value<string>;
+    /** Control size */
+    size?: Value<ControlSize>;
+    /** Whether the input is disabled */
+    disabled?: Value<boolean>;
+    /** Maximum number of tags allowed */
+    maxTags?: Value<number>;
+    /** Whether the input has an error */
+    hasError?: Value<boolean>;
+}
+export declare function TagInput(options: TagInputOptions): TNode;