entangle-ui 0.8.2 → 0.9.0

package/dist/types/components/controls/Combobox/Combobox.d.ts

@@ -0,0 +1,29 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ComboboxProps } from './Combobox.types.js';
+
+/**
+ * Single-value select with an editable input. Filters the option list as the
+ * user types (built-in fuzzy matcher, configurable via `filterFn`), supports
+ * controlled and uncontrolled modes, optional `freeSolo` typing, optional
+ * `creatable` mode for adding new entries, and an `loading` state for async
+ * data sources.
+ *
+ * @example
+ * ```tsx
+ * <Combobox
+ *   label="Framework"
+ *   options={[
+ *     { value: 'react', label: 'React' },
+ *     { value: 'vue', label: 'Vue' },
+ *   ]}
+ *   value={framework}
+ *   onChange={setFramework}
+ * />
+ * ```
+ */
+declare function Combobox<T extends string = string>({ value, defaultValue, options, placeholder, filterFn, emptyMessage, loading, loadingMessage, freeSolo, creatable, createLabel, openOnFocus, size, variant, label, helperText, error, errorMessage, disabled, required, readOnly, clearable, maxDropdownHeight, minDropdownWidth, name, onChange, onInputChange, onCreate, onOpenChange, className, style, testId, ref, id: idProp, ...rest }: ComboboxProps<T>): react_jsx_runtime.JSX.Element;
+declare namespace Combobox {
+    var displayName: string;
+}
+
+export { Combobox };

package/dist/types/components/controls/Combobox/Combobox.types.d.ts

@@ -0,0 +1,109 @@
+import React from 'react';
+import { BaseComponent, Size } from '../../../types/common.js';
+import { Prettify } from '../../../types/utilities.js';
+
+type ComboboxSize = Size;
+type ComboboxVariant = 'default' | 'ghost' | 'filled';
+interface ComboboxOption<T extends string = string> {
+    /** Unique value used for selection */
+    value: T;
+    /** Display label (falls back to value when omitted) */
+    label?: string;
+    /** Optional description rendered next to the label */
+    description?: string;
+    /** Optional icon rendered before the label */
+    icon?: React.ReactNode;
+    /** Whether this option is disabled */
+    disabled?: boolean;
+}
+interface ComboboxBaseProps<T extends string = string> extends Omit<BaseComponent<HTMLInputElement>, 'onChange' | 'value' | 'defaultValue' | 'children'> {
+    /** Controlled selected value */
+    value?: T | null;
+    /** Default selected value (uncontrolled) */
+    defaultValue?: T;
+    /** Available options */
+    options: ComboboxOption<T>[];
+    /** Placeholder rendered when the input is empty */
+    placeholder?: string;
+    /**
+     * Custom filter function. Receives the raw query and the option, returns
+     * either a boolean (`true` to keep) or a numeric score (higher = better).
+     * When omitted, options are filtered by the built-in fuzzy matcher
+     * (`fuzzyScore`).
+     */
+    filterFn?: (option: ComboboxOption<T>, query: string) => boolean | number;
+    /** Message shown when filtering yields no results */
+    emptyMessage?: string;
+    /** Loading indicator state — replaces options with a spinner row */
+    loading?: boolean;
+    /** Message shown while loading */
+    loadingMessage?: string;
+    /**
+     * Allow values not present in `options`. The `onChange` handler still fires
+     * with the user-typed string when the input is blurred or `Enter` is pressed
+     * with no active suggestion.
+     * @default false
+     */
+    freeSolo?: boolean;
+    /**
+     * When true the user can create a brand new option by pressing Enter on a
+     * value that doesn't match any existing option. The `onCreate` callback (or
+     * `onChange` when omitted) is invoked. Implies `freeSolo`.
+     * @default false
+     */
+    creatable?: boolean;
+    /**
+     * Render the "create" row when `creatable` is true and the query has no
+     * exact match. Defaults to `'Create "<query>"'`.
+     */
+    createLabel?: (query: string) => React.ReactNode;
+    /**
+     * Open the dropdown automatically when the input gains focus, even when no
+     * query is typed yet.
+     * @default false
+     */
+    openOnFocus?: boolean;
+    /** Component size */
+    size?: ComboboxSize;
+    /** Visual variant */
+    variant?: ComboboxVariant;
+    /** Label rendered above the input */
+    label?: string;
+    /** Helper text rendered below */
+    helperText?: string;
+    /** Error state */
+    error?: boolean;
+    /** Error message — overrides `helperText` when `error` is true */
+    errorMessage?: string;
+    /** Disable the input */
+    disabled?: boolean;
+    /** Mark the field as required */
+    required?: boolean;
+    /** Read-only — input value is fixed */
+    readOnly?: boolean;
+    /** Show a clear button when a value is selected */
+    clearable?: boolean;
+    /** Maximum dropdown height in pixels */
+    maxDropdownHeight?: number;
+    /** Minimum dropdown width in pixels */
+    minDropdownWidth?: number;
+    /** Hidden form-input name */
+    name?: string;
+    /** Selection change handler. `null` is passed when the value is cleared. */
+    onChange?: (value: T | null) => void;
+    /**
+     * Free-text change handler. Fires every keystroke regardless of selection
+     * status. Useful for async option loading.
+     */
+    onInputChange?: (input: string) => void;
+    /**
+     * Called when the user creates a new option (only when `creatable` is set).
+     * Falls back to `onChange` with the typed string cast as `T` when omitted.
+     */
+    onCreate?: (input: string) => void;
+    /** Open state change handler */
+    onOpenChange?: (open: boolean) => void;
+}
+type ComboboxProps<T extends string = string> = Prettify<ComboboxBaseProps<T>>;
+
+export type { ComboboxBaseProps, ComboboxOption, ComboboxProps, ComboboxSize, ComboboxVariant };

package/dist/types/components/controls/FileUploader/FileUploader.d.ts

@@ -0,0 +1,34 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { FileUploaderProps } from './FileUploader.types.js';
+
+/**
+ * Drag-and-drop file uploader with click-to-browse fallback. Renders a list
+ * of uploaded items with per-file status (`pending` / `uploading` / `done` /
+ * `error`) and an animated progress bar.
+ *
+ * The component itself is purely presentational around the file list — it
+ * does not perform the actual upload. The consumer is expected to:
+ *   1. Listen to `onFilesAdd` (or `onChange`) to know which files were
+ *      accepted by the uploader.
+ *   2. Drive the upload (fetch / XHR / SDK) externally.
+ *   3. Reflect progress back into the component by passing a controlled
+ *      `value` and updating the `status` / `progress` of each item.
+ *
+ * @example
+ * ```tsx
+ * const [items, setItems] = useState<FileUploaderItem[]>([]);
+ * <FileUploader
+ *   value={items}
+ *   onChange={setItems}
+ *   accept="image/*,.pdf"
+ *   maxSize={5 * 1024 * 1024}
+ *   onFilesAdd={files => uploadAll(files, setItems)}
+ * />
+ * ```
+ */
+declare function FileUploader({ value, defaultValue, onChange, onFilesAdd, onFileRemove, onReject, accept, multiple, maxFiles, maxSize, minSize, validate, renderItem, size, label, helperText, error, errorMessage, disabled, required, dropZoneText, dropZoneHint, name, className, style, testId, id: idProp, ref, ...rest }: FileUploaderProps): react_jsx_runtime.JSX.Element;
+declare namespace FileUploader {
+    var displayName: string;
+}
+
+export { FileUploader };

package/dist/types/components/controls/FileUploader/FileUploader.types.d.ts

@@ -0,0 +1,94 @@
+import React from 'react';
+import { BaseComponent, Size } from '../../../types/common.js';
+import { Prettify } from '../../../types/utilities.js';
+
+type FileUploaderSize = Size;
+type FileUploaderItemStatus = 'pending' | 'uploading' | 'done' | 'error';
+interface FileUploaderItem {
+    /** Stable identifier — generated for new items, preserved across renders */
+    id: string;
+    /** Underlying File object */
+    file: File;
+    /** Current status of the upload pipeline */
+    status: FileUploaderItemStatus;
+    /** Upload progress, 0-100. Optional in `pending` / `done` states. */
+    progress?: number;
+    /** Error message displayed when `status === 'error'` */
+    errorMessage?: string;
+}
+type FileUploaderRejectReason = 'too-large' | 'too-small' | 'wrong-type' | 'max-files' | 'invalid' | (string & {});
+interface FileUploaderRenderItemState {
+    item: FileUploaderItem;
+    index: number;
+    remove: () => void;
+    disabled: boolean;
+}
+interface FileUploaderBaseProps extends Omit<BaseComponent<HTMLDivElement>, 'onChange' | 'children' | 'defaultValue'> {
+    /** Controlled list of items */
+    value?: FileUploaderItem[];
+    /** Default list (uncontrolled) */
+    defaultValue?: FileUploaderItem[];
+    /** Called whenever the items list changes */
+    onChange?: (items: FileUploaderItem[]) => void;
+    /**
+     * Called with the raw `File` objects that were just accepted (after type/size
+     * validation, before they appear in the list as `pending`). The consumer
+     * should kick off the upload here and update `value` as progress changes.
+     */
+    onFilesAdd?: (files: File[]) => void;
+    /** Called when a single item is removed */
+    onFileRemove?: (item: FileUploaderItem) => void;
+    /** Called for files rejected by validation */
+    onReject?: (file: File, reason: FileUploaderRejectReason) => void;
+    /**
+     * Comma-separated list of accepted MIME types and/or extensions, e.g.
+     * `'image/*,.pdf'`. When omitted, every file type is accepted.
+     */
+    accept?: string;
+    /**
+     * Allow selecting more than one file at a time.
+     * @default true
+     */
+    multiple?: boolean;
+    /**
+     * Maximum number of files the uploader will hold. Additional files are
+     * rejected with reason `'max-files'`.
+     */
+    maxFiles?: number;
+    /** Maximum file size in bytes. Files above are rejected as `'too-large'`. */
+    maxSize?: number;
+    /** Minimum file size in bytes. Files below are rejected as `'too-small'`. */
+    minSize?: number;
+    /**
+     * Synchronous validator. Return `false` (or a string with a reason) to
+     * reject. Called after type/size checks pass.
+     */
+    validate?: (file: File) => boolean | string;
+    /**
+     * Custom renderer for a file row. When omitted the built-in row is used.
+     */
+    renderItem?: (state: FileUploaderRenderItemState) => React.ReactNode;
+    /** Component size */
+    size?: FileUploaderSize;
+    /** Label rendered above the dropzone */
+    label?: string;
+    /** Helper text rendered below */
+    helperText?: string;
+    /** Error state */
+    error?: boolean;
+    /** Error message — overrides `helperText` when `error` is true */
+    errorMessage?: string;
+    /** Disable interaction with the uploader */
+    disabled?: boolean;
+    /** Mark the field as required */
+    required?: boolean;
+    /** Primary text shown inside the dropzone */
+    dropZoneText?: React.ReactNode;
+    /** Secondary text shown inside the dropzone */
+    dropZoneHint?: React.ReactNode;
+    /** Hidden form-input name attribute (for native form submission) */
+    name?: string;
+}
+type FileUploaderProps = Prettify<FileUploaderBaseProps>;
+
+export type { FileUploaderBaseProps, FileUploaderItem, FileUploaderItemStatus, FileUploaderProps, FileUploaderRejectReason, FileUploaderRenderItemState, FileUploaderSize };

package/dist/types/components/controls/MultiSelect/MultiSelect.d.ts

@@ -0,0 +1,31 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { MultiSelectProps } from './MultiSelect.types.js';
+
+/**
+ * Multi-value select that lets the user pick several options from a dropdown.
+ * Selected values are rendered as inline chips inside the trigger; the rest
+ * collapse into a "+N more" badge.
+ *
+ * Supports searchable mode, grouped options, controlled and uncontrolled
+ * modes, keyboard navigation, an optional `max` cap, and a clear-all button.
+ *
+ * @example
+ * ```tsx
+ * <MultiSelect
+ *   label="Tags"
+ *   options={[
+ *     { value: 'react', label: 'React' },
+ *     { value: 'vue', label: 'Vue' },
+ *     { value: 'svelte', label: 'Svelte' },
+ *   ]}
+ *   value={tags}
+ *   onChange={setTags}
+ * />
+ * ```
+ */
+declare function MultiSelect<T extends string = string>({ value, defaultValue, options, placeholder, searchable, searchPlaceholder, filterFn, emptyMessage, max, maxInlineChips, size, variant, label, helperText, error, errorMessage, disabled, required, clearable, maxDropdownHeight, minDropdownWidth, closeOnSelect, name, onChange, onOpenChange, className, style, testId, ref, id: idProp, ...rest }: MultiSelectProps<T>): react_jsx_runtime.JSX.Element;
+declare namespace MultiSelect {
+    var displayName: string;
+}
+
+export { MultiSelect };

package/dist/types/components/controls/MultiSelect/MultiSelect.types.d.ts

@@ -0,0 +1,85 @@
+import React from 'react';
+import { BaseComponent, Size } from '../../../types/common.js';
+import { Prettify } from '../../../types/utilities.js';
+
+type MultiSelectSize = Size;
+type MultiSelectVariant = 'default' | 'ghost' | 'filled';
+interface MultiSelectOption<T extends string = string> {
+    /** Unique value used for selection */
+    value: T;
+    /** Display label (falls back to value when omitted) */
+    label?: string;
+    /** Optional icon rendered before the label */
+    icon?: React.ReactNode;
+    /** Whether this option is disabled */
+    disabled?: boolean;
+}
+interface MultiSelectOptionGroup<T extends string = string> {
+    /** Group header label */
+    label: string;
+    /** Options inside this group */
+    options: MultiSelectOption<T>[];
+}
+interface MultiSelectBaseProps<T extends string = string> extends Omit<BaseComponent<HTMLButtonElement>, 'onChange' | 'value' | 'defaultValue' | 'children'> {
+    /** Controlled list of selected values */
+    value?: T[];
+    /** Default selection (uncontrolled) */
+    defaultValue?: T[];
+    /** Options — flat list or grouped */
+    options: Array<MultiSelectOption<T> | MultiSelectOptionGroup<T>>;
+    /** Placeholder shown when nothing is selected */
+    placeholder?: string;
+    /** Whether to render a search input inside the dropdown */
+    searchable?: boolean;
+    /** Placeholder for the search input */
+    searchPlaceholder?: string;
+    /** Custom filter for searchable mode */
+    filterFn?: (option: MultiSelectOption<T>, query: string) => boolean;
+    /** Message shown when search yields no results */
+    emptyMessage?: string;
+    /** Maximum number of selected items */
+    max?: number;
+    /**
+     * Cap of inline chips rendered in the trigger before falling back to a
+     * "+N more" badge. `Infinity` to render every chip. Set to `0` to never
+     * render chips and only show the count.
+     * @default 3
+     */
+    maxInlineChips?: number;
+    /** Component size */
+    size?: MultiSelectSize;
+    /** Visual variant */
+    variant?: MultiSelectVariant;
+    /** Label rendered above the trigger */
+    label?: string;
+    /** Helper text rendered below */
+    helperText?: string;
+    /** Error state */
+    error?: boolean;
+    /** Error message — overrides `helperText` when `error` is true */
+    errorMessage?: string;
+    /** Disable the entire control */
+    disabled?: boolean;
+    /** Mark the field as required */
+    required?: boolean;
+    /** Show a clear-all button when at least one value is selected */
+    clearable?: boolean;
+    /** Maximum dropdown height in pixels */
+    maxDropdownHeight?: number;
+    /** Minimum dropdown width in pixels */
+    minDropdownWidth?: number;
+    /**
+     * Close the dropdown after each selection.
+     * @default false
+     */
+    closeOnSelect?: boolean;
+    /** Hidden form-input name. Selected values are joined by `,`. */
+    name?: string;
+    /** Selection change handler */
+    onChange?: (values: T[]) => void;
+    /** Open state change handler */
+    onOpenChange?: (open: boolean) => void;
+}
+type MultiSelectProps<T extends string = string> = Prettify<MultiSelectBaseProps<T>>;
+
+export type { MultiSelectBaseProps, MultiSelectOption, MultiSelectOptionGroup, MultiSelectProps, MultiSelectSize, MultiSelectVariant };

package/dist/types/components/controls/TagInput/TagInput.d.ts

@@ -0,0 +1,24 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { TagInputProps } from './TagInput.types.js';
+
+/**
+ * Multi-value input that captures a list of strings ("tags") rendered as
+ * removable chips. Supports controlled and uncontrolled modes, validation,
+ * configurable commit keys, and custom chip rendering.
+ *
+ * @example
+ * ```tsx
+ * <TagInput
+ *   label="Keywords"
+ *   placeholder="Add a keyword..."
+ *   defaultValue={['react', 'typescript']}
+ *   onChange={setTags}
+ * />
+ * ```
+ */
+declare function TagInput({ value, defaultValue, onChange, placeholder, separators, addOnBlur, allowDuplicates, max, validate, normalize, onValidate, renderTag, size, variant, label, helperText, error, errorMessage, disabled, required, readOnly, name, inputAriaLabel, inputRef: inputRefProp, className, style, testId, id: idProp, ref, ...rest }: TagInputProps): react_jsx_runtime.JSX.Element;
+declare namespace TagInput {
+    var displayName: string;
+}
+
+export { TagInput };

package/dist/types/components/controls/TagInput/TagInput.types.d.ts

@@ -0,0 +1,100 @@
+import React from 'react';
+import { BaseComponent, Size } from '../../../types/common.js';
+import { Prettify } from '../../../types/utilities.js';
+
+type TagInputSize = Size;
+type TagInputVariant = 'default' | 'ghost' | 'filled';
+/** Keys (or characters) that commit the current draft as a tag. */
+type TagInputSeparator = 'Enter' | 'Comma' | 'Space' | 'Tab';
+interface TagInputRenderTagState {
+    /** Tag value */
+    tag: string;
+    /** Position in the array */
+    index: number;
+    /** Whether the parent component is disabled */
+    disabled: boolean;
+    /** Remove this tag */
+    remove: () => void;
+}
+interface TagInputBaseProps extends Omit<BaseComponent<HTMLDivElement>, 'onChange' | 'defaultValue' | 'children'> {
+    /** Controlled list of tags */
+    value?: string[];
+    /** Default tags (uncontrolled) */
+    defaultValue?: string[];
+    /** Called whenever the tag list changes */
+    onChange?: (tags: string[]) => void;
+    /** Placeholder shown in the inner input when empty */
+    placeholder?: string;
+    /**
+     * Keys / characters that commit the current draft to a tag.
+     * @default ['Enter', 'Comma']
+     */
+    separators?: TagInputSeparator[];
+    /**
+     * Add the current draft as a tag when the input loses focus.
+     * @default false
+     */
+    addOnBlur?: boolean;
+    /**
+     * Allow duplicate tags. When `false`, attempts to add an existing tag
+     * are ignored (and `onValidate` receives `'duplicate'`).
+     * @default false
+     */
+    allowDuplicates?: boolean;
+    /**
+     * Maximum number of tags. When reached, the input is disabled.
+     */
+    max?: number;
+    /**
+     * Synchronous validator. Return `false` (or a string with an error message)
+     * to reject the candidate value. Return `true` to accept.
+     */
+    validate?: (value: string, current: string[]) => boolean | string;
+    /**
+     * Transform the candidate before validation. Defaults to trimming.
+     */
+    normalize?: (value: string) => string;
+    /**
+     * Called when a candidate fails validation. Receives the raw value, the
+     * normalized value, and the reason (`'duplicate'`, `'max'`, `'empty'`,
+     * `'invalid'`, or the validator's string).
+     */
+    onValidate?: (rawValue: string, reason: 'duplicate' | 'max' | 'empty' | 'invalid' | (string & {})) => void;
+    /**
+     * Render a single chip. When omitted the built-in chip is used.
+     */
+    renderTag?: (state: TagInputRenderTagState) => React.ReactNode;
+    /**
+     * Component size.
+     * @default 'md'
+     */
+    size?: TagInputSize;
+    /**
+     * Visual variant for the wrapper.
+     * @default 'default'
+     */
+    variant?: TagInputVariant;
+    /** Label rendered above the input */
+    label?: string;
+    /** Helper text rendered below the input */
+    helperText?: string;
+    /** Error state */
+    error?: boolean;
+    /** Error message — shown in place of `helperText` when `error` is true */
+    errorMessage?: string;
+    /** Disable the entire control */
+    disabled?: boolean;
+    /** Mark the field as required */
+    required?: boolean;
+    /** Read-only — chips are visible but not removable, input is hidden */
+    readOnly?: boolean;
+    /** Name attribute used for form submission (joined by `,`) */
+    name?: string;
+    /** ARIA label for the inner text input */
+    inputAriaLabel?: string;
+    /** Ref forwarded to the inner `<input>` */
+    inputRef?: React.Ref<HTMLInputElement>;
+}
+type TagInputProps = Prettify<TagInputBaseProps>;
+
+export type { TagInputBaseProps, TagInputProps, TagInputRenderTagState, TagInputSeparator, TagInputSize, TagInputVariant };

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

@@ -0,0 +1,8 @@
+import React from 'react';
+import { DataTableProps } from './DataTable.types.js';
+
+declare const DataTable: <R>(props: DataTableProps<R> & {
+    ref?: React.Ref<HTMLDivElement>;
+}) => React.ReactElement;
+
+export { DataTable };