@tempots/beatui 0.82.1 → 0.83.0

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

@@ -1,11 +1,122 @@
 import { DropdownOption } from './option';
+/**
+ * Toggles the presence of a value in a list. If the value exists, it is removed;
+ * if it does not exist, it is appended.
+ *
+ * @typeParam T - The type of list elements.
+ * @param list - The current list of values.
+ * @param value - The value to toggle.
+ * @param equality - A function to compare two values for equality.
+ * @returns A new list with the value toggled.
+ *
+ * @example
+ * ```ts
+ * const updated = toggleValue(['a', 'b'], 'c', (a, b) => a === b)
+ * // ['a', 'b', 'c']
+ * const removed = toggleValue(['a', 'b', 'c'], 'b', (a, b) => a === b)
+ * // ['a', 'c']
+ * ```
+ */
 export declare function toggleValue<T>(list: T[], value: T, equality: (a: T, b: T) => boolean): T[];
+/**
+ * Removes all occurrences of a value from a list.
+ *
+ * @typeParam T - The type of list elements.
+ * @param list - The current list of values.
+ * @param value - The value to remove.
+ * @param equality - A function to compare two values for equality.
+ * @returns A new list with the value removed.
+ *
+ * @example
+ * ```ts
+ * const updated = removeValue(['a', 'b', 'c'], 'b', (a, b) => a === b)
+ * // ['a', 'c']
+ * ```
+ */
 export declare function removeValue<T>(list: T[], value: T, equality: (a: T, b: T) => boolean): T[];
+/**
+ * Checks whether a list contains a specific value.
+ *
+ * @typeParam T - The type of list elements.
+ * @param list - The list to search.
+ * @param value - The value to look for.
+ * @param equality - A function to compare two values for equality.
+ * @returns `true` if the value is found in the list, `false` otherwise.
+ *
+ * @example
+ * ```ts
+ * containsValue(['a', 'b'], 'b', (a, b) => a === b) // true
+ * containsValue(['a', 'b'], 'c', (a, b) => a === b) // false
+ * ```
+ */
 export declare function containsValue<T>(list: T[], value: T, equality: (a: T, b: T) => boolean): boolean;
+/**
+ * Searches a hierarchical list of dropdown options for a value and returns its label.
+ * Supports nested group options by recursing into group children.
+ *
+ * @typeParam T - The type of option values.
+ * @param options - The list of dropdown options to search.
+ * @param target - The value to find.
+ * @param equality - A function to compare two values for equality.
+ * @returns An object with the matching `label`, or `undefined` if not found.
+ *
+ * @example
+ * ```ts
+ * const opt = findOptionByValue(
+ *   [{ type: 'value', value: 1, label: 'One' }],
+ *   1,
+ *   (a, b) => a === b
+ * )
+ * // { label: 'One' }
+ * ```
+ */
 export declare function findOptionByValue<T>(options: DropdownOption<T>[], target: T, equality: (a: T, b: T) => boolean): {
     label: string;
 } | undefined;
+/**
+ * Gets the display label for a value from a list of dropdown options.
+ * Falls back to `String(target)` if the value is not found.
+ *
+ * @typeParam T - The type of option values.
+ * @param options - The list of dropdown options to search.
+ * @param target - The value to look up.
+ * @param equality - A function to compare two values for equality.
+ * @returns The label string for the matching option, or the stringified target as fallback.
+ *
+ * @example
+ * ```ts
+ * const label = getLabelByValue(
+ *   [{ type: 'value', value: 'us', label: 'United States' }],
+ *   'us',
+ *   (a, b) => a === b
+ * )
+ * // 'United States'
+ * ```
+ */
 export declare function getLabelByValue<T>(options: DropdownOption<T>[], target: T, equality: (a: T, b: T) => boolean): string;
+/**
+ * Filters a hierarchical list of dropdown options by a search query string.
+ * By default, matches options whose label contains the query (case-insensitive).
+ * Group options are preserved if any of their children match.
+ *
+ * @typeParam T - The type of option values.
+ * @param options - The list of dropdown options to filter.
+ * @param query - The search query string.
+ * @param predicate - Optional custom match function. Receives the lowercased query and option.
+ * @returns A new filtered list of dropdown options.
+ *
+ * @example
+ * ```ts
+ * const filtered = filterOptionsByQuery(
+ *   [
+ *     { type: 'value', value: 1, label: 'Apple' },
+ *     { type: 'value', value: 2, label: 'Banana' },
+ *   ],
+ *   'app',
+ * )
+ * // [{ type: 'value', value: 1, label: 'Apple' }]
+ * ```
+ */
 export declare function filterOptionsByQuery<T>(options: DropdownOption<T>[], query: string, predicate?: (q: string, opt: {
     label: string;
 }) => boolean): DropdownOption<T>[];

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

@@ -1,2 +1,20 @@
 import { InputOptions } from './input-options';
+/**
+ * A free-form tags input component that allows users to add and remove string tags.
+ *
+ * Users type a tag into a text field and press Enter/change to add it. Tags are
+ * displayed as removable chips. Duplicate tags are prevented.
+ *
+ * @param options - Standard input options for a `string[]` value.
+ * @returns A renderable tags input component.
+ *
+ * @example
+ * ```ts
+ * TagsInput({
+ *   value: prop<string[]>(['react', 'typescript']),
+ *   onChange: tags => console.log('Tags:', tags),
+ *   placeholder: 'Add a tag...',
+ * })
+ * ```
+ */
 export declare const TagsInput: (options: InputOptions<string[]>) => import("@tempots/dom").Renderable;

package/dist/types/components/form/input/text-area.d.ts

@@ -1,7 +1,49 @@
 import { Value } from '@tempots/dom';
 import { InputOptions } from './input-options';
 import { Merge } from '@tempots/std';
+/**
+ * Configuration options for the {@link TextArea} component.
+ *
+ * Extends {@link InputOptions} for string values with an additional `rows` property
+ * to control the visible height of the textarea.
+ */
 export type TextAreaOptions = Merge<InputOptions<string>, {
+    /** Number of visible text rows. @default 3 */
     rows?: Value<number>;
 }>;
+/**
+ * A multi-line text input component wrapping a native `<textarea>` element.
+ *
+ * Renders a styled textarea inside an {@link InputContainer} with support for
+ * reactive values, configurable row count, placeholder text, disabled state, and
+ * all standard {@link InputOptions} properties. The container uses `baseContainer`
+ * mode for proper textarea sizing.
+ *
+ * @param options - Configuration options for the textarea
+ * @returns A styled textarea element wrapped in an InputContainer
+ *
+ * @example
+ * ```ts
+ * import { prop } from '@tempots/dom'
+ * import { TextArea } from '@tempots/beatui'
+ *
+ * const bio = prop('')
+ * TextArea({
+ *   value: bio,
+ *   onChange: bio.set,
+ *   placeholder: 'Tell us about yourself...',
+ *   rows: 5,
+ *   size: 'md',
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Minimal usage with default 3 rows
+ * TextArea({
+ *   value: prop(''),
+ *   onInput: (v) => console.log('Typing:', v),
+ * })
+ * ```
+ */
 export declare const TextArea: (options: TextAreaOptions) => import("@tempots/dom").Renderable;

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

@@ -1,2 +1,64 @@
+import { Value } from '@tempots/dom';
 import { InputOptions } from './input-options';
-export declare const TextInput: (options: InputOptions<string>) => import("@tempots/dom").Renderable;
+import { Merge } from '@tempots/std';
+/**
+ * Configuration options for {@link TextInput}.
+ *
+ * Extends {@link InputOptions} with an optional `type` attribute to support
+ * different HTML input types (e.g., 'text', 'email', 'url', 'tel', 'password').
+ */
+export type TextInputOptions = Merge<InputOptions<string>, {
+    /**
+     * HTML input type attribute.
+     * @default 'text'
+     */
+    type?: Value<string>;
+}>;
+/**
+ * A single-line text input component wrapping a native `<input>` element.
+ *
+ * Renders a styled text field inside an {@link InputContainer} with support for
+ * reactive values, placeholder text, disabled state, and all standard
+ * {@link InputOptions} properties.
+ *
+ * @param options - Configuration options following the {@link TextInputOptions} pattern
+ * @returns A styled text input element wrapped in an InputContainer
+ *
+ * @example
+ * ```ts
+ * import { prop } from '@tempots/dom'
+ * import { TextInput } from '@tempots/beatui'
+ *
+ * const name = prop('John')
+ * TextInput({
+ *   value: name,
+ *   onChange: name.set,
+ *   placeholder: 'Enter your name',
+ *   size: 'md',
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * // With prefix/suffix using InputAdornment
+ * TextInput({
+ *   value: prop(''),
+ *   onInput: (v) => console.log('Typing:', v),
+ *   before: InputAdornment({ filled: true }, 'https://'),
+ *   placeholder: 'example.com',
+ *   type: 'url',
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * // With icon decoration
+ * TextInput({
+ *   value: prop(''),
+ *   onInput: (v) => console.log('Typing:', v),
+ *   before: InputIcon({ icon: 'line-md:search' }),
+ *   placeholder: 'Search...',
+ * })
+ * ```
+ */
+export declare const TextInput: (options: TextInputOptions) => import("@tempots/dom").Renderable;

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

@@ -1,2 +1,36 @@
 import { InputOptions } from './input-options';
+/**
+ * A URL input component wrapping a native `<input type="url">` element.
+ *
+ * Renders a styled URL field inside an {@link InputContainer} with browser-native
+ * URL validation support. Accepts all standard {@link InputOptions} properties for
+ * string values.
+ *
+ * @param options - Configuration options following the {@link InputOptions} pattern for string values
+ * @returns A styled URL input element wrapped in an InputContainer
+ *
+ * @example
+ * ```ts
+ * import { prop } from '@tempots/dom'
+ * import { UrlInput } from '@tempots/beatui'
+ *
+ * const website = prop('https://')
+ * UrlInput({
+ *   value: website,
+ *   onChange: website.set,
+ *   placeholder: 'https://example.com',
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * // With a before icon and error state
+ * UrlInput({
+ *   value: prop(''),
+ *   onChange: (v) => console.log('URL:', v),
+ *   before: Icon({ icon: 'line-md:link' }),
+ *   hasError: prop(true),
+ * })
+ * ```
+ */
 export declare const UrlInput: (options: InputOptions<string>) => import("@tempots/dom").Renderable;

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

@@ -1,2 +1,21 @@
 import { InputOptions } from './input-options';
+/**
+ * A UUID input component with an 8-4-4-4-12 hex digit mask.
+ *
+ * Accepts case-insensitive hexadecimal input and normalizes to lowercase.
+ * Automatically inserts hyphens at the correct positions. Built on top of
+ * {@link MaskInput} with a pre-configured hex pattern mask.
+ *
+ * @param options - Standard input options for a string value. The `placeholder`
+ *   defaults to `'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'` if not provided.
+ * @returns A renderable UUID input component.
+ *
+ * @example
+ * ```ts
+ * UUIDInput({
+ *   value: prop(''),
+ *   onChange: uuid => console.log('UUID:', uuid),
+ * })
+ * ```
+ */
 export declare const UUIDInput: (options: InputOptions<string>) => import("@tempots/dom").Renderable;

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

@@ -1,3 +1,23 @@
 import { InputOptions } from './input-options';
 import { ZonedDateTime } from '../../../temporal';
+/**
+ * An input component for `Temporal.ZonedDateTime` values.
+ *
+ * Renders a `datetime-local` HTML input. The time zone is inferred from
+ * the `placeholder` option or defaults to the user's local time zone via
+ * `Intl.DateTimeFormat`. Requires the Temporal polyfill.
+ *
+ * @param options - Standard input options for a `ZonedDateTime` value.
+ *   The `placeholder` option can be used to specify a time zone string.
+ * @returns A renderable zoned date-time input component.
+ *
+ * @example
+ * ```ts
+ * ZonedDateTimeInput({
+ *   value: prop(Temporal.Now.zonedDateTimeISO()),
+ *   placeholder: 'America/New_York',
+ *   onChange: zdt => console.log('ZonedDateTime:', zdt.toString()),
+ * })
+ * ```
+ */
 export declare const ZonedDateTimeInput: (options: InputOptions<ZonedDateTime>) => import("@tempots/dom").Renderable;

package/dist/types/components/form/schema/standard-schema-v1.d.ts

@@ -1,55 +1,130 @@
-/** The Standard Schema interface. */
+/**
+ * The Standard Schema v1 interface for schema validation libraries.
+ *
+ * This is an implementation of the
+ * [Standard Schema](https://github.com/standard-schema/standard-schema) specification (v1),
+ * which provides a common interface that schema validation libraries (Zod, Valibot, ArkType, etc.)
+ * can implement so they are interchangeable.
+ *
+ * BeatUI uses this interface to accept any compatible schema library for form validation
+ * without coupling to a specific implementation.
+ *
+ * @typeParam Input - The type accepted as input for validation
+ * @typeParam Output - The type produced after successful validation (defaults to `Input`)
+ *
+ * @example
+ * ```typescript
+ * import type { StandardSchemaV1 } from '@tempots/beatui'
+ * import { z } from 'zod'
+ *
+ * // Zod schemas already implement StandardSchemaV1
+ * const schema: StandardSchemaV1<string, string> = z.string().email()
+ *
+ * // Validate a value
+ * const result = await schema['~standard'].validate('test@example.com')
+ * if (!result.issues) {
+ *   console.log('Valid:', result.value)
+ * }
+ * ```
+ */
 export interface StandardSchemaV1<Input = unknown, Output = Input> {
-    /** The Standard Schema properties. */
+    /** The Standard Schema properties, accessed via the `~standard` key to avoid naming conflicts. */
     readonly '~standard': StandardSchemaV1.Props<Input, Output>;
 }
 export declare namespace StandardSchemaV1 {
-    /** The Standard Schema properties interface. */
+    /**
+     * The Standard Schema properties interface containing version, vendor, validation function, and type info.
+     *
+     * @typeParam Input - The type accepted as input for validation
+     * @typeParam Output - The type produced after successful validation
+     */
     interface Props<Input = unknown, Output = Input> {
-        /** The version number of the standard. */
+        /** The version number of the Standard Schema specification (always `1` for v1). */
         readonly version: 1;
-        /** The vendor name of the schema library. */
+        /** The vendor name of the schema library (e.g., `'zod'`, `'valibot'`, `'arktype'`). */
         readonly vendor: string;
-        /** Validates unknown input values. */
+        /**
+         * Validates an unknown input value against the schema.
+         *
+         * @param value - The value to validate
+         * @returns A result indicating success (with typed output) or failure (with issues)
+         */
         readonly validate: (value: unknown) => Result<Output> | Promise<Result<Output>>;
-        /** Inferred types associated with the schema. */
+        /** Optional type information for inferring input and output types at the type level. */
         readonly types?: Types<Input, Output> | undefined;
     }
-    /** The result interface of the validate function. */
+    /**
+     * Discriminated union representing the result of a validation operation.
+     *
+     * @typeParam Output - The type of the validated output value
+     */
     type Result<Output> = SuccessResult<Output> | FailureResult;
-    /** The result interface if validation succeeds. */
+    /**
+     * The result when validation succeeds, containing the typed output value.
+     *
+     * @typeParam Output - The type of the validated output value
+     */
     interface SuccessResult<Output> {
-        /** The typed output value. */
+        /** The typed output value after successful validation. */
         readonly value: Output;
-        /** The non-existent issues. */
+        /** Always `undefined` for success results, enabling discrimination from failure results. */
         readonly issues?: undefined;
     }
-    /** The result interface if validation fails. */
+    /**
+     * The result when validation fails, containing an array of validation issues.
+     */
     interface FailureResult {
-        /** The issues of failed validation. */
+        /** The array of validation issues describing what went wrong. */
         readonly issues: ReadonlyArray<Issue>;
     }
-    /** The issue interface of the failure output. */
+    /**
+     * A single validation issue describing an error found during validation.
+     */
     interface Issue {
-        /** The error message of the issue. */
+        /** The human-readable error message describing the validation failure. */
         readonly message: string;
-        /** The path of the issue, if any. */
+        /** The path to the field that caused the issue, if applicable. Each element is either a `PropertyKey` or a {@link PathSegment}. */
         readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
     }
-    /** The path segment interface of the issue. */
+    /**
+     * A path segment identifying a specific location within a nested data structure.
+     */
     interface PathSegment {
-        /** The key representing a path segment. */
+        /** The key (property name or array index) representing this path segment. */
         readonly key: PropertyKey;
     }
-    /** The Standard Schema types interface. */
+    /**
+     * Type information interface for inferring input and output types from a schema.
+     *
+     * @typeParam Input - The input type of the schema
+     * @typeParam Output - The output type of the schema
+     */
     interface Types<Input = unknown, Output = Input> {
-        /** The input type of the schema. */
+        /** The input type that the schema accepts for validation. */
         readonly input: Input;
-        /** The output type of the schema. */
+        /** The output type that the schema produces after successful validation. */
         readonly output: Output;
     }
-    /** Infers the input type of a Standard Schema. */
+    /**
+     * Utility type that infers the input type from a Standard Schema.
+     *
+     * @typeParam Schema - The Standard Schema to extract the input type from
+     *
+     * @example
+     * ```typescript
+     * type Input = StandardSchemaV1.InferInput<typeof mySchema>
+     * ```
+     */
     type InferInput<Schema extends StandardSchemaV1> = NonNullable<Schema['~standard']['types']>['input'];
-    /** Infers the output type of a Standard Schema. */
+    /**
+     * Utility type that infers the output type from a Standard Schema.
+     *
+     * @typeParam Schema - The Standard Schema to extract the output type from
+     *
+     * @example
+     * ```typescript
+     * type Output = StandardSchemaV1.InferOutput<typeof mySchema>
+     * ```
+     */
     type InferOutput<Schema extends StandardSchemaV1> = NonNullable<Schema['~standard']['types']>['output'];
 }