@tempots/beatui 0.82.1 → 0.83.3

package/dist/types/components/data/table.d.ts

@@ -1,27 +1,54 @@
 import { TNode, Value } from '@tempots/dom';
 import { ControlSize } from '../theme';
+/**
+ * Configuration options for the {@link Table} component.
+ * Controls visual presentation including size, borders, hover effects, and sticky headers.
+ */
 export interface TableOptions {
-    /** Size of the table (affects padding and spacing) */
+    /** Size of the table affecting cell padding and font size. @default 'md' */
     size?: Value<ControlSize>;
-    /** Enable hover effect on rows */
+    /** Enable background color change on row hover. @default false */
     hoverable?: Value<boolean>;
-    /** Make the header sticky when scrolling */
+    /** Make the header row sticky when scrolling vertically. @default false */
     stickyHeader?: Value<boolean>;
-    /** Table takes full width of container */
+    /** Whether the table takes the full width of its container. @default false */
     fullWidth?: Value<boolean>;
-    /** Stripe rows for better readability */
+    /** Alternate row background colors for improved readability. @default false */
     withStripedRows?: Value<boolean>;
-    /** Show outer table border */
+    /** Show a border around the entire table container. @default true */
     withTableBorder?: Value<boolean>;
-    /** Show vertical borders between columns */
+    /** Show vertical borders between columns. @default false */
     withColumnBorders?: Value<boolean>;
-    /** Show horizontal borders between rows */
+    /** Show horizontal borders between rows. @default true */
     withRowBorders?: Value<boolean>;
-    /** Custom border radius (CSS value) */
+    /** Border radius of the table container. @default undefined */
     borderRadius?: Value<'none' | 'sm' | 'md' | 'lg' | 'xl'>;
 }
 /**
- * Table component with styling variants
- * Focused on presentation, not data management
+ * A styled table component focused on presentation with configurable borders,
+ * hover effects, sticky headers, and striped rows. Wraps a standard HTML table
+ * in a container that handles overflow scrolling and border radius.
+ *
+ * This component provides styling only — data management and row rendering
+ * are handled by the caller using standard `html.thead`, `html.tbody`, `html.tr`,
+ * `html.th`, and `html.td` elements.
+ *
+ * @param options - Visual configuration for the table
+ * @param children - Table content (thead, tbody, tfoot elements)
+ * @returns A container div wrapping a styled table element
+ *
+ * @example
+ * ```typescript
+ * Table(
+ *   { hoverable: true, withStripedRows: true, fullWidth: true },
+ *   html.thead(
+ *     html.tr(html.th('Name'), html.th('Email'), html.th('Role'))
+ *   ),
+ *   html.tbody(
+ *     html.tr(html.td('Alice'), html.td('alice@example.com'), html.td('Admin')),
+ *     html.tr(html.td('Bob'), html.td('bob@example.com'), html.td('User'))
+ *   )
+ * )
+ * ```
  */
 export declare function Table({ size, hoverable, stickyHeader, fullWidth, withStripedRows, withTableBorder, withColumnBorders, withRowBorders, borderRadius, }?: TableOptions, ...children: TNode[]): import("@tempots/dom").Renderable;

package/dist/types/components/data/tag.d.ts

@@ -1,11 +1,51 @@
 import { Value } from '@tempots/dom';
 import { ThemeColorName } from '../../tokens';
 import { ControlSize } from '../theme';
+/**
+ * A small label component for categorization, filtering, or displaying metadata.
+ * Supports optional close button for removable tags and theme-aware color styling.
+ *
+ * When an `onClose` callback is provided, a close button is rendered alongside the tag text.
+ * The tag automatically adapts to light and dark themes using CSS custom properties.
+ *
+ * @param options - Tag configuration
+ * @param options.value - Reactive string displayed as the tag label
+ * @param options.color - Theme color for the tag background and text (default: 'base')
+ * @param options.onClose - Callback when the close button is clicked; receives the current tag value
+ * @param options.size - Size of the tag (default: 'md')
+ * @param options.class - Additional CSS class(es) to apply
+ * @param options.disabled - Whether the tag and its close button are disabled
+ * @returns A styled span element representing the tag
+ *
+ * @example
+ * ```typescript
+ * Tag({ value: 'TypeScript', color: 'primary' })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Removable tag
+ * const tags = prop(['React', 'Vue', 'Solid'])
+ * ForEach(tags, tag =>
+ *   Tag({
+ *     value: tag,
+ *     color: 'info',
+ *     onClose: (v) => tags.set(tags.value.filter(t => t !== v))
+ *   })
+ * )
+ * ```
+ */
 export declare const Tag: ({ value, color, onClose, size, class: cls, disabled, }: {
+    /** Reactive string displayed as the tag label. */
     value: Value<string>;
+    /** Theme color for the tag background and text. @default 'base' */
     color?: Value<ThemeColorName>;
+    /** Callback when the close button is clicked; receives the current tag value. */
     onClose?: (value: string) => void;
+    /** Size of the tag. @default 'md' */
     size?: Value<ControlSize>;
+    /** Additional CSS class(es) to apply. */
     class?: Value<string>;
+    /** Whether the tag and its close button are disabled. */
     disabled?: Value<boolean>;
 }) => import("@tempots/dom").Renderable;

package/dist/types/components/data/unstyled-drop-zone.d.ts

@@ -1,15 +1,88 @@
 import { TNode, Value, Signal } from '@tempots/dom';
+/**
+ * Configuration options for the {@link UnstyledDropZone} component.
+ */
 export type DropZoneOptions = {
+    /**
+     * Callback invoked when files are selected, either via drag-and-drop
+     * or the file picker dialog. The `via` parameter indicates the selection method.
+     */
     onChange: (files: File[], via: 'dragdrop' | 'click') => void;
+    /**
+     * Optional external reactive file list. When provided, the drop zone
+     * derives its internal file state from this value.
+     */
     value?: Value<File[]>;
+    /**
+     * MIME type filter for accepted files (e.g., `'image/*'`, `'application/pdf'`).
+     * Passed to the hidden `<input type="file">` element.
+     * @default '*\/*'
+     */
     accept?: Value<string>;
+    /**
+     * Whether clicking the drop zone opens the native file picker dialog.
+     * @default true
+     */
     enableClick?: Value<boolean>;
+    /**
+     * Render function for the drop zone content. Receives reactive state
+     * and control functions to build a custom UI.
+     *
+     * @param options.files - Reactive signal containing the current file list.
+     * @param options.clear - Clears the current file selection.
+     * @param options.change - Programmatically sets the file list.
+     */
     content: (options: {
         files: Signal<File[]>;
         clear: () => void;
         change: (files: File[]) => void;
     }) => TNode;
+    /**
+     * Whether the drop zone is disabled. Disabled zones do not accept drops or clicks.
+     * @default false
+     */
     disabled?: Value<boolean>;
+    /**
+     * Whether multiple files can be selected at once.
+     */
     allowMultiple?: Value<boolean>;
 };
+/**
+ * Renders an unstyled file drop zone that supports both drag-and-drop and
+ * click-to-browse file selection. This component provides the behavior
+ * and accessibility without any visual styling, allowing complete UI
+ * customization through the `content` render function.
+ *
+ * The component:
+ * - Handles `dragover`, `dragleave`, and `drop` events
+ * - Opens a native file picker on click (when `enableClick` is `true`)
+ * - Supports keyboard activation (Enter/Space)
+ * - Applies `role="button"` and ARIA labels for accessibility
+ * - Synchronizes a hidden `<input type="file">` with the reactive file state
+ *
+ * @param options - Configuration options for the drop zone.
+ * @returns A renderable drop zone container.
+ *
+ * @example
+ * ```typescript
+ * UnstyledDropZone({
+ *   accept: 'image/*',
+ *   allowMultiple: true,
+ *   onChange: (files, via) => {
+ *     console.log(`${files.length} files selected via ${via}`)
+ *   },
+ *   content: ({ files, clear }) =>
+ *     html.div(
+ *       attr.class('drop-area'),
+ *       files.map(f => f.length > 0
+ *         ? html.div(
+ *             `${f.length} file(s) selected`,
+ *             html.button(on.click(clear), 'Clear')
+ *           )
+ *         : html.div('Drop files here or click to browse')
+ *       )
+ *     ),
+ * })
+ * ```
+ */
 export declare function UnstyledDropZone({ onChange, value, accept, enableClick, content, disabled, allowMultiple, }: DropZoneOptions): import("@tempots/dom").Renderable;

package/dist/types/components/form/control/control.d.ts

@@ -2,23 +2,178 @@ import { Merge, TNode } from '@tempots/dom';
 import { InputOptions } from '../input/input-options';
 import { Controller } from '../controller';
 import { InputWrapperOptions } from '../input';
+/**
+ * Creates a blur event handler that marks the controller as touched.
+ *
+ * @param _controller - The controller to mark as touched
+ * @param onBlur - Optional additional blur handler to invoke
+ * @returns A blur event handler function
+ */
 export declare const makeOnBlurHandler: (_controller: Controller<any>, onBlur?: () => void) => () => void;
+/**
+ * Creates a change event handler that updates the controller value.
+ *
+ * @template T - The value type
+ * @param controller - The controller to update
+ * @param onChange - Optional additional change handler to invoke
+ * @returns A change event handler function
+ */
 export declare const makeOnChangeHandler: <T>(controller: Controller<T>, onChange?: (value: T) => void) => (value: T) => void;
+/**
+ * Base options type for any input component, derived from InputOptions.
+ */
 export type BaseControlOptions = InputOptions<any>;
+/**
+ * Options for a control that includes both input and wrapper options.
+ */
 export type ControlOptions = Merge<BaseControlOptions, InputWrapperOptions>;
+/**
+ * Options for connecting a controller to an input component without a wrapper.
+ *
+ * @template T - The controller value type
+ * @template O - The input component options type
+ */
 export type BaseControllerOptions<T, O extends BaseControlOptions> = Merge<Omit<O, 'value'>, {
     controller: Controller<T>;
     triggerOn?: 'input' | 'change';
 }>;
+/**
+ * Options for connecting a controller to an input component with a wrapper.
+ *
+ * @template T - The controller value type
+ * @template O - The input component options type
+ */
 export type ControllerOptions<T, O extends BaseControlOptions> = Merge<Omit<InputWrapperOptions, 'content'>, Merge<Omit<O, 'value'>, {
     controller: Controller<T>;
     triggerOn?: 'input' | 'change';
 }>>;
+/**
+ * Options for connecting a controller to an input with bidirectional value transformation.
+ *
+ * @template T - The controller value type
+ * @template U - The input component value type
+ * @template O - The input component options type
+ */
 export type MappedControllerOptions<T, U, O extends BaseControlOptions> = Merge<ControllerOptions<T, O>, {
+    /** Transforms controller value to input value. */
     toInput: (value: T) => U;
+    /** Transforms input value back to controller value. */
     fromInput: (value: U) => T;
 }>;
+/**
+ * Connects an input component to a controller without a wrapper (no label, error display, etc.).
+ * Automatically binds the controller's value, disabled state, error state, and event handlers.
+ *
+ * @template T - The controller value type
+ * @template O - The input component options type
+ * @param InputComponent - The input component factory function
+ * @param options - Controller connection options including the controller and optional event handlers
+ * @returns A TNode representing the connected input
+ *
+ * @example
+ * ```typescript
+ * import { BaseControl, useController } from '@tempots/beatui'
+ * import { TextInput } from '@tempots/beatui'
+ * import { prop } from '@tempots/dom'
+ *
+ * const { controller } = useController({
+ *   initialValue: 'Hello',
+ * })
+ *
+ * const input = BaseControl(TextInput, {
+ *   controller,
+ *   placeholder: 'Enter text...',
+ * })
+ * ```
+ */
 export declare function BaseControl<T, O extends BaseControlOptions>(InputComponent: (options: O) => TNode, options: BaseControllerOptions<T, O>): any;
+/**
+ * Connects an input component to a controller with a wrapper that provides label, error display, and layout.
+ * Automatically binds the controller's value, disabled state, error state, and event handlers.
+ *
+ * @template T - The controller value type
+ * @template O - The input component options type
+ * @param InputComponent - The input component factory function
+ * @param options - Controller connection options including wrapper options (label, error display, etc.)
+ * @param children - Optional child nodes to render alongside the input
+ * @returns A TNode representing the wrapped input with label and error display
+ *
+ * @example
+ * ```typescript
+ * import { Control, useForm } from '@tempots/beatui'
+ * import { TextInput } from '@tempots/beatui'
+ * import { html } from '@tempots/dom'
+ *
+ * const { controller } = useForm({
+ *   initialValue: { email: '' },
+ * })
+ *
+ * const emailControl = Control(TextInput, {
+ *   controller: controller.field('email'),
+ *   label: 'Email Address',
+ *   placeholder: 'you@example.com',
+ *   triggerOn: 'input',
+ * })
+ * ```
+ */
 export declare function Control<T, O extends BaseControlOptions>(InputComponent: (options: O) => TNode, { id: idArg, labelFor: labelForArg, ...options }: ControllerOptions<T, O>, ...children: TNode[]): import("@tempots/dom").Renderable;
+/**
+ * Connects an input component to a controller with bidirectional value transformation, without a wrapper.
+ * Useful when the controller value type differs from the input component's expected value type.
+ *
+ * @template T - The controller value type
+ * @template U - The input component value type
+ * @template O - The input component options type
+ * @param InputComponent - The input component factory function
+ * @param options - Controller connection options including transform functions
+ * @returns A TNode representing the connected input with value transformation
+ *
+ * @example
+ * ```typescript
+ * import { BaseMappedControl, useController } from '@tempots/beatui'
+ * import { TextInput } from '@tempots/beatui'
+ *
+ * const { controller } = useController({
+ *   initialValue: 42, // number
+ * })
+ *
+ * const input = BaseMappedControl(TextInput, {
+ *   controller,
+ *   toInput: (n) => n.toString(),
+ *   fromInput: (s) => parseFloat(s) || 0,
+ *   placeholder: 'Enter a number...',
+ * })
+ * ```
+ */
 export declare function BaseMappedControl<T, U, O extends BaseControlOptions>(InputComponent: (options: O) => TNode, options: MappedControllerOptions<T, U, O>): any;
+/**
+ * Connects an input component to a controller with bidirectional value transformation and a wrapper.
+ * Combines value transformation with label, error display, and layout features.
+ *
+ * @template T - The controller value type
+ * @template U - The input component value type
+ * @template O - The input component options type
+ * @param InputComponent - The input component factory function
+ * @param options - Controller connection options including transform functions and wrapper options
+ * @param children - Optional child nodes to render alongside the input
+ * @returns A TNode representing the wrapped input with value transformation
+ *
+ * @example
+ * ```typescript
+ * import { MappedControl, useForm } from '@tempots/beatui'
+ * import { TextInput } from '@tempots/beatui'
+ *
+ * const { controller } = useForm({
+ *   initialValue: { age: 25 },
+ * })
+ *
+ * const ageControl = MappedControl(TextInput, {
+ *   controller: controller.field('age'),
+ *   toInput: (n) => n.toString(),
+ *   fromInput: (s) => parseInt(s, 10) || 0,
+ *   label: 'Age',
+ *   placeholder: 'Enter your age',
+ * })
+ * ```
+ */
 export declare function MappedControl<T, U, O extends BaseControlOptions>(InputComponent: (options: O) => TNode, { id: idArg, labelFor: labelForArg, ...options }: MappedControllerOptions<T, U, O>, ...children: TNode[]): import("@tempots/dom").Renderable;

package/dist/types/components/form/control/date-utils.d.ts

@@ -1,6 +1,87 @@
+/**
+ * Converts a `Date` to a full ISO 8601 date-time string (e.g., `'2024-01-15T10:30:00.000Z'`).
+ *
+ * @param date - The Date object to convert
+ * @returns The ISO 8601 date-time string representation
+ *
+ * @example
+ * ```typescript
+ * dateTimeToISO(new Date('2024-01-15T10:30:00Z'))
+ * // => '2024-01-15T10:30:00.000Z'
+ * ```
+ */
 export declare const dateTimeToISO: (date: Date) => string;
+/**
+ * Converts a `Date` to an ISO 8601 date-only string (e.g., `'2024-01-15'`).
+ *
+ * Strips the time portion from the ISO string, returning only the `YYYY-MM-DD` part.
+ *
+ * @param date - The Date object to convert
+ * @returns The ISO 8601 date-only string (YYYY-MM-DD)
+ *
+ * @example
+ * ```typescript
+ * dateToISO(new Date('2024-01-15T10:30:00Z'))
+ * // => '2024-01-15'
+ * ```
+ */
 export declare const dateToISO: (date: Date) => string;
+/**
+ * Parses a date string into a `Date` object.
+ *
+ * @param value - The date string to parse (any format accepted by `new Date()`)
+ * @returns A new Date object
+ *
+ * @example
+ * ```typescript
+ * stringToDate('2024-01-15')
+ * // => Date Mon Jan 15 2024 ...
+ * ```
+ */
 export declare const stringToDate: (value: string) => Date;
+/**
+ * Parses a nullable date string into a `Date` or `null`.
+ *
+ * Returns `null` if the input is `null` or an empty string.
+ *
+ * @param value - The date string to parse, or `null`
+ * @returns A Date object if the value is a non-empty string, otherwise `null`
+ *
+ * @example
+ * ```typescript
+ * nullableStringToDate('2024-01-15') // => Date
+ * nullableStringToDate(null)          // => null
+ * nullableStringToDate('')            // => null
+ * ```
+ */
 export declare const nullableStringToDate: (value: string | null) => Date | null;
+/**
+ * Converts a nullable `Date` to a full ISO 8601 date-time string, or `null`.
+ *
+ * @param date - The Date object to convert, or `null`
+ * @returns The ISO 8601 date-time string, or `null` if the input is `null`
+ *
+ * @example
+ * ```typescript
+ * nullableDateTimeToISO(new Date('2024-01-15T10:30:00Z'))
+ * // => '2024-01-15T10:30:00.000Z'
+ * nullableDateTimeToISO(null)
+ * // => null
+ * ```
+ */
 export declare const nullableDateTimeToISO: (date: Date | null) => string | null;
+/**
+ * Converts a nullable `Date` to an ISO 8601 date-only string, or `null`.
+ *
+ * @param date - The Date object to convert, or `null`
+ * @returns The ISO 8601 date-only string (YYYY-MM-DD), or `null` if the input is `null`
+ *
+ * @example
+ * ```typescript
+ * nullableDateToISO(new Date('2024-01-15T10:30:00Z'))
+ * // => '2024-01-15'
+ * nullableDateToISO(null)
+ * // => null
+ * ```
+ */
 export declare const nullableDateToISO: (date: Date | null) => string | null;

package/dist/types/components/form/control/ensure-control.d.ts

@@ -1,3 +1,31 @@
 import { TNode } from '@tempots/dom';
 import { Controller } from '../controller/controller';
+/**
+ * Conditionally renders content only when a controller's value is non-null and non-undefined.
+ *
+ * Similar to the `Ensure` primitive from `@tempots/dom`, but works with `Controller` instances.
+ * When the controller's signal holds a non-nullish value, it creates a transformed controller
+ * with `NonNullable<T>` type and passes it to the `then` callback. When the value is null or
+ * undefined, it renders the optional `otherwise` fallback.
+ *
+ * @typeParam T - The non-nullable base type of the controller's value
+ *
+ * @param controller - A controller whose value may be `null`, `undefined`, or `T`
+ * @param then - Callback invoked with a `Controller<NonNullable<T>>` when the value is present
+ * @param otherwise - Optional callback invoked when the value is null or undefined
+ *
+ * @returns A renderable TNode that conditionally renders based on the controller's value
+ *
+ * @example
+ * ```typescript
+ * import { EnsureControl } from '@tempots/beatui'
+ *
+ * // Only render the text input when the controller value is non-null
+ * EnsureControl(
+ *   nullableStringController,
+ *   (ctrl) => TextInput({ value: ctrl.signal, onChange: ctrl.change }),
+ *   () => html.p('No value set')
+ * )
+ * ```
+ */
 export declare function EnsureControl<T>(controller: Controller<T | null | undefined> | Controller<T | null> | Controller<T | undefined>, then: (controller: Controller<NonNullable<T>>) => TNode, otherwise?: () => TNode): import("@tempots/dom").Renderable;

package/dist/types/components/form/control/form-status.d.ts

@@ -1,20 +1,83 @@
+/**
+ * Status indicating the form is being filled out by the user.
+ */
 export type FormFilling = {
     type: 'filling';
 };
+/**
+ * Status indicating the form is currently being submitted.
+ */
 export type FormSubmitting = {
     type: 'submitting';
 };
+/**
+ * Status indicating the form submission encountered an error.
+ */
 export type FormError = {
+    /** Discriminant for the error status */
     type: 'error';
+    /** The error message describing what went wrong */
     error: string;
 };
+/**
+ * Status indicating the form was submitted successfully.
+ */
 export type FormSuccess = {
     type: 'success';
 };
+/**
+ * Discriminated union representing the current state of a form.
+ *
+ * The form progresses through these states during its lifecycle:
+ * 1. `'filling'` - User is entering data
+ * 2. `'submitting'` - Form is being submitted (e.g., API call in progress)
+ * 3. `'success'` or `'error'` - Submission result
+ *
+ * Use the `type` discriminant to narrow the union in conditional logic.
+ *
+ * @example
+ * ```typescript
+ * import { FormStatus } from '@tempots/beatui'
+ *
+ * const status: FormStatus = FormStatus.filling
+ *
+ * switch (status.type) {
+ *   case 'filling': // show form
+ *   case 'submitting': // show spinner
+ *   case 'success': // show success message
+ *   case 'error': // show error: status.error
+ * }
+ * ```
+ */
 export type FormStatus = FormFilling | FormSubmitting | FormError | FormSuccess;
+/**
+ * Factory object for creating {@link FormStatus} values.
+ *
+ * Provides pre-built instances for `filling`, `submitting`, and `success`,
+ * and a factory function for creating `error` statuses with a message.
+ *
+ * @example
+ * ```typescript
+ * import { FormStatus } from '@tempots/beatui'
+ *
+ * const initial = FormStatus.filling
+ * const loading = FormStatus.submitting
+ * const done = FormStatus.success
+ * const failed = FormStatus.error('Network timeout')
+ * ```
+ */
 export declare const FormStatus: {
+    /** A pre-built `FormFilling` status instance */
     filling: FormStatus;
+    /** A pre-built `FormSubmitting` status instance */
     submitting: FormStatus;
+    /**
+     * Creates a `FormError` status with the given error message.
+     *
+     * @param error - The error message describing what went wrong
+     * @returns A `FormStatus` of type `'error'`
+     */
     error: (error: string) => FormStatus;
+    /** A pre-built `FormSuccess` status instance */
     success: FormStatus;
 };

package/dist/types/components/form/control/index.d.ts

@@ -1,4 +1,14 @@
+/**
+ * @fileoverview Form Control Module
+ *
+ * Exports form control components and utilities:
+ * - {@link Control} - Base form control wrapper
+ * - {@link EnsureControl} - Conditional rendering for nullable controllers
+ * - {@link BaseListControl} / {@link ListControl} - List management with add/remove/reorder
+ * - {@link FormStatus} - Form submission state management
+ */
 export * from './control';
 export * from './ensure-control';
+export * from './list-item-controls';
 export * from './list-control';
 export * from './form-status';