entangle-ui 0.8.2 → 0.9.0

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

@@ -0,0 +1,159 @@
+import React from 'react';
+import { BaseComponent } from '../../../types/common.js';
+import { Prettify } from '../../../types/utilities.js';
+
+/** Visual density. Affects row height and cell padding. */
+type DataTableDensity = 'comfortable' | 'compact' | 'dense';
+/** Cell horizontal alignment. */
+type DataTableAlign = 'left' | 'center' | 'right';
+/** Sort direction. `null` means unsorted (third state of the sort cycle). */
+type DataTableSortDirection = 'asc' | 'desc' | null;
+/** Selection behavior. */
+type DataTableSelectionMode = 'single' | 'multiple' | false;
+/**
+ * Description of a single column.
+ *
+ * `R` is the row data type.
+ *
+ * `accessor` may be a string (key of `R`) or a function returning the cell
+ * value. When omitted, `id` is used as a key into `R` if it matches a key,
+ * otherwise the cell is empty.
+ */
+interface DataTableColumn<R> {
+    /** Stable column identifier. Required. */
+    id: string;
+    /** Header content (string or any node). */
+    header?: React.ReactNode;
+    /** How to read the cell value from a row. */
+    accessor?: keyof R | ((row: R, rowIndex: number) => unknown);
+    /**
+     * Cell renderer. Receives the resolved value and the row.
+     * When omitted, the value is rendered with `String(value)` (or empty for
+     * `null`/`undefined`).
+     */
+    cell?: (info: {
+        value: unknown;
+        row: R;
+        rowIndex: number;
+        column: DataTableColumn<R>;
+    }) => React.ReactNode;
+    /** Fixed column width (px or any CSS dimension). */
+    width?: number | string;
+    /** Minimum column width in px (used for resizing). */
+    minWidth?: number;
+    /** Maximum column width in px (used for resizing). */
+    maxWidth?: number;
+    /** When true, header click toggles sort on this column. */
+    sortable?: boolean;
+    /**
+     * Custom comparator. Receives the resolved cell values for two rows.
+     * Default: `localeCompare` for strings, `<` for numbers, `Date`,
+     * `null`/`undefined` ordered last.
+     */
+    sortComparator?: (a: unknown, b: unknown, rowA: R, rowB: R) => number;
+    /** Cell horizontal alignment. @default "left" */
+    align?: DataTableAlign;
+    /** Per-column className. */
+    className?: string;
+    /** When true, this column sticks to the left edge while scrolling. */
+    sticky?: boolean;
+    /** When false, the column header is not focusable for keyboard users. */
+    ariaHidden?: boolean;
+    /** When true, this column cannot be resized even if `resizableColumns` is on. */
+    disableResize?: boolean;
+}
+/** Controlled sort state. */
+interface DataTableSortState {
+    /** Column id, or null when no sort is applied. */
+    columnId: string | null;
+    /** Direction. `null` is treated as no sort. */
+    direction: DataTableSortDirection;
+}
+/** Selection state. Always an array of row keys; for `single` it has 0 or 1 items. */
+type DataTableSelectionState = string[];
+/** Argument passed to render slot helpers. */
+interface DataTableRowRenderInfo<R> {
+    row: R;
+    rowIndex: number;
+    selected: boolean;
+}
+/** Virtualization mode. `'auto'` enables virtualization above the threshold. */
+type DataTableVirtualizationMode = boolean | 'auto';
+interface DataTableBaseProps<R> extends Omit<BaseComponent<HTMLDivElement>, 'onSelect' | 'children' | 'onChange'> {
+    /** Row data. */
+    rows: readonly R[];
+    /** Column definitions. */
+    columns: readonly DataTableColumn<R>[];
+    /**
+     * How to derive a stable key for each row. Either a string key on `R` or a
+     * function. Required for selection and virtualization stability.
+     */
+    rowKey: keyof R | ((row: R, rowIndex: number) => string);
+    /** Visual density. @default "comfortable" */
+    density?: DataTableDensity;
+    /** Sticky column header. @default true */
+    stickyHeader?: boolean;
+    /** Controlled sort state. */
+    sort?: DataTableSortState | null;
+    /** Default sort state for the uncontrolled mode. */
+    defaultSort?: DataTableSortState | null;
+    /** Called when the user changes the sort. */
+    onSortChange?: (state: DataTableSortState) => void;
+    /**
+     * When true, the consumer fully owns sorting and the table renders rows
+     * as-is. Useful for server-side sorting. @default false
+     */
+    manualSort?: boolean;
+    /** Selection mode. @default false */
+    selectionMode?: DataTableSelectionMode;
+    /** Controlled selection (array of row keys). */
+    selection?: DataTableSelectionState;
+    /** Default selection for the uncontrolled mode. */
+    defaultSelection?: DataTableSelectionState;
+    /** Called when selection changes. */
+    onSelectionChange?: (next: DataTableSelectionState) => void;
+    /** Disable selection of a specific row. */
+    isRowSelectable?: (row: R, rowIndex: number) => boolean;
+    /** Row click handler. Independent of selection. */
+    onRowClick?: (row: R, rowIndex: number, event: React.MouseEvent) => void;
+    /** Row activation (Enter key or double click). */
+    onRowActivate?: (row: R, rowIndex: number) => void;
+    /** Custom row renderer. Receives the default cells; consumer wraps them. */
+    renderRow?: (info: DataTableRowRenderInfo<R>, cells: React.ReactNode) => React.ReactNode;
+    /** Empty state slot (or text). Rendered when `rows.length === 0`. */
+    emptyState?: React.ReactNode;
+    /** Loading flag — renders skeleton rows. @default false */
+    loading?: boolean;
+    /** Number of skeleton rows shown while loading. @default 5 */
+    loadingRowCount?: number;
+    /**
+     * Virtualization mode. `'auto'` enables it once `rows.length` exceeds
+     * `virtualizationThreshold`. Set to `false` for tests / a11y tools or for
+     * very small tables.
+     * @default "auto"
+     */
+    virtualized?: DataTableVirtualizationMode;
+    /** Threshold above which `'auto'` mode flips on. @default 100 */
+    virtualizationThreshold?: number;
+    /** Estimated row height in px. @default depends on density */
+    estimatedRowHeight?: number;
+    /** Number of off-screen rows kept mounted. @default 8 */
+    overscan?: number;
+    /** Total scroll container height. Required when virtualized. @default 480 */
+    height?: number | string;
+    /** Maximum height before scroll engages (non-virtualized mode). */
+    maxHeight?: number | string;
+    /** Resizable columns (drag the right edge of the header). @default false */
+    resizableColumns?: boolean;
+    /** Called when a column is resized. */
+    onColumnResize?: (columnId: string, width: number) => void;
+    /** Optional aria-label for the grid. */
+    'aria-label'?: string;
+    /** Optional aria-labelledby for the grid. */
+    'aria-labelledby'?: string;
+    /** Hidden form id. Forwarded to the root element. */
+    id?: string;
+}
+type DataTableProps<R> = Prettify<DataTableBaseProps<R>>;
+
+export type { DataTableAlign, DataTableBaseProps, DataTableColumn, DataTableDensity, DataTableProps, DataTableRowRenderInfo, DataTableSelectionMode, DataTableSelectionState, DataTableSortDirection, DataTableSortState, DataTableVirtualizationMode };

package/dist/types/components/feedback/Alert/Alert.d.ts

@@ -41,6 +41,7 @@ declare const AlertImpl: React.NamedExoticComponent<{
     icon?: React.ReactNode;
     onClose?: (() => void) | undefined;
     title?: React.ReactNode;
+    width?: number | string | undefined;
     children?: React.ReactNode;
     popover?: "" | "auto" | "manual" | "hint" | undefined | undefined;
     id?: string | undefined | undefined;

package/dist/types/components/feedback/Alert/Alert.types.d.ts

@@ -54,6 +54,13 @@ interface AlertBaseProps extends Omit<BaseComponent<HTMLDivElement>, 'title'> {
      * (don't do this; pick one).
      */
     title?: React.ReactNode;
+    /**
+     * Width of the alert. Number → px, string → CSS value.
+     * Defaults to `100%` so the alert fills its parent and keeps a stable width
+     * regardless of content length; long text wraps inside.
+     * @default "100%"
+     */
+    width?: number | string;
     /**
      * Children — typically `Alert.Title` / `Alert.Description` / `Alert.Actions`.
      * Plain string content is also fine (treated as description).

package/dist/types/components/feedback/CommandPalette/CommandPalette.d.ts

@@ -0,0 +1,29 @@
+import React from 'react';
+import { CommandPaletteProps } from './CommandPalette.types.js';
+
+/**
+ * Search-driven command list shown as a centred floating dialog. Type to
+ * fuzzy-filter, ArrowUp/ArrowDown to navigate, Enter to select, Escape to
+ * close. Recent selections are tracked in localStorage when `recentKey` is
+ * set. The component does not bind a global hotkey — wire `useHotkey` in
+ * the consumer.
+ *
+ * @example
+ * ```tsx
+ * useHotkey('Mod+K', () => { setOpen(true); });
+ *
+ * <CommandPalette
+ *   open={open}
+ *   onClose={() => setOpen(false)}
+ *   items={[
+ *     { id: 'open', label: 'Open File', shortcut: 'Cmd+O', group: 'File' },
+ *     { id: 'save', label: 'Save', shortcut: 'Cmd+S', group: 'File' },
+ *   ]}
+ *   onSelect={(item) => runCommand(item.id)}
+ *   recentKey="myapp:command-palette"
+ * />
+ * ```
+ */
+declare const CommandPalette: React.FC<CommandPaletteProps>;
+
+export { CommandPalette };

package/dist/types/components/feedback/CommandPalette/CommandPalette.types.d.ts

@@ -0,0 +1,61 @@
+import React from 'react';
+import { BaseComponent } from '../../../types/common.js';
+import { Prettify } from '../../../types/utilities.js';
+
+interface CommandItem {
+    /** Stable unique identifier — used for keys and the recent list. */
+    id: string;
+    /** Visible label. */
+    label: string;
+    /** Optional secondary description. */
+    description?: string;
+    /** Group name for sectioning the list. Items without a group go into "default". */
+    group?: string;
+    /** Leading icon. */
+    icon?: React.ReactNode;
+    /** Keyboard shortcut to display (e.g. "Cmd+S"). */
+    shortcut?: string;
+    /** Extra strings used by the fuzzy matcher in addition to label/description. */
+    keywords?: string[];
+    /** When true, the item is rendered but cannot be selected. */
+    disabled?: boolean;
+    /** Callback fired when this item is chosen. Falls back to top-level `onSelect`. */
+    onSelect?: () => void;
+}
+interface CommandPaletteRenderItemState {
+    selected: boolean;
+    query: string;
+}
+interface CommandPaletteBaseProps extends Omit<BaseComponent, 'onSelect'> {
+    /** Whether the palette is open. */
+    open: boolean;
+    /** Called when the palette requests close (Escape, overlay, after select). */
+    onClose: () => void;
+    /** All commands. The component filters them as the user types. */
+    items: readonly CommandItem[];
+    /** Default handler invoked when an item without its own `onSelect` is chosen. */
+    onSelect?: (item: CommandItem) => void;
+    /** Placeholder text for the search input. @default "Type a command or search..." */
+    placeholder?: string;
+    /** Custom node when no items match the current query. */
+    emptyState?: React.ReactNode;
+    /** Localised label for the recent items group header. @default "Recent" */
+    recentLabel?: string;
+    /** localStorage key for tracking recently selected items. Recent tracking is off when omitted. */
+    recentKey?: string;
+    /** Maximum number of recent items to track. @default 5 */
+    maxRecent?: number;
+    /** Debounce in ms applied to the search query. @default 150 */
+    debounceMs?: number;
+    /** Custom renderer for each item — replaces the default row layout. */
+    renderItem?: (item: CommandItem, state: CommandPaletteRenderItemState) => React.ReactNode;
+    /** Render in a portal. @default true */
+    portal?: boolean;
+    /** Maximum height of the results list in px. @default 400 */
+    maxHeight?: number;
+    /** Width in px or any CSS value. @default 640 */
+    width?: number | string;
+}
+type CommandPaletteProps = Prettify<CommandPaletteBaseProps>;
+
+export type { CommandItem, CommandPaletteBaseProps, CommandPaletteProps, CommandPaletteRenderItemState };

package/dist/types/components/feedback/CommandPalette/fuzzySearch.d.ts

@@ -0,0 +1,6 @@
+interface FuzzyMatch<T> {
+    item: T;
+    score: number;
+}
+
+export type { FuzzyMatch };

package/dist/types/components/feedback/Drawer/Drawer.d.ts

@@ -0,0 +1,12 @@
+import React from 'react';
+import { DrawerProps, DrawerHeaderProps, DrawerBodyProps, DrawerFooterProps, DrawerCloseButtonProps } from './Drawer.types.js';
+
+interface DrawerComponent extends React.FC<DrawerProps> {
+    Header: React.FC<DrawerHeaderProps>;
+    Body: React.FC<DrawerBodyProps>;
+    Footer: React.FC<DrawerFooterProps>;
+    CloseButton: React.FC<DrawerCloseButtonProps>;
+}
+declare const Drawer: DrawerComponent;
+
+export { Drawer };

package/dist/types/components/feedback/Drawer/Drawer.types.d.ts

@@ -0,0 +1,70 @@
+import React from 'react';
+import { BaseComponent } from '../../../types/common.js';
+import { Prettify } from '../../../types/utilities.js';
+
+type DrawerAnchor = 'left' | 'right' | 'top' | 'bottom';
+type DrawerSizePreset = 'sm' | 'md' | 'lg' | 'xl';
+type DrawerSize = DrawerSizePreset | (string & {}) | number;
+type DrawerFooterAlign = 'left' | 'center' | 'right' | 'space-between';
+interface DrawerBaseProps extends BaseComponent {
+    /** Whether the drawer is open. */
+    open: boolean;
+    /** Called when the drawer requests close (overlay click, Escape, close button). */
+    onClose: () => void;
+    /** Edge from which the drawer enters. @default "right" */
+    anchor?: DrawerAnchor;
+    /** Drawer size on the cross axis. Strings like "sm" use presets, number = px, string = CSS. @default "md" */
+    size?: DrawerSize;
+    /** Modal mode renders a backdrop and traps focus. @default true */
+    modal?: boolean;
+    /** Close when the overlay is clicked. Only applies when modal. @default true */
+    closeOnOverlayClick?: boolean;
+    /** Close on Escape. @default true */
+    closeOnEscape?: boolean;
+    /** Trap focus inside the drawer. Defaults to `modal`. */
+    trapFocus?: boolean;
+    /** Element to focus on open. */
+    initialFocusRef?: React.RefObject<HTMLElement | null>;
+    /** Render in a portal on document.body. @default true */
+    portal?: boolean;
+    /** Used as aria-labelledby reference. Pass as a string or use Drawer.Header. */
+    title?: string;
+    /** Used as aria-describedby reference. */
+    description?: string;
+    /** Drawer content (typically Drawer.Header/Body/Footer). */
+    children: React.ReactNode;
+}
+type DrawerProps = Prettify<DrawerBaseProps>;
+interface DrawerHeaderBaseProps extends BaseComponent {
+    /** Title content. */
+    children: React.ReactNode;
+    /** Whether to render a close button on the right. @default true */
+    showClose?: boolean;
+    /** Optional description below the title. */
+    description?: string;
+}
+type DrawerHeaderProps = Prettify<DrawerHeaderBaseProps>;
+interface DrawerBodyBaseProps extends BaseComponent {
+    children: React.ReactNode;
+}
+type DrawerBodyProps = Prettify<DrawerBodyBaseProps>;
+interface DrawerFooterBaseProps extends BaseComponent {
+    children: React.ReactNode;
+    /** Horizontal alignment. @default "right" */
+    align?: DrawerFooterAlign;
+}
+type DrawerFooterProps = Prettify<DrawerFooterBaseProps>;
+interface DrawerCloseButtonBaseProps extends Omit<BaseComponent<HTMLButtonElement>, 'children'> {
+    /** Custom button content; defaults to an X icon. */
+    children?: React.ReactNode;
+    /** Override aria-label. @default "Close drawer" */
+    'aria-label'?: string;
+}
+type DrawerCloseButtonProps = Prettify<DrawerCloseButtonBaseProps>;
+interface DrawerContextValue {
+    onClose: () => void;
+    titleId: string;
+    descriptionId: string;
+}
+
+export type { DrawerAnchor, DrawerBaseProps, DrawerBodyBaseProps, DrawerBodyProps, DrawerCloseButtonBaseProps, DrawerCloseButtonProps, DrawerContextValue, DrawerFooterAlign, DrawerFooterBaseProps, DrawerFooterProps, DrawerHeaderBaseProps, DrawerHeaderProps, DrawerProps, DrawerSize, DrawerSizePreset };

package/dist/types/components/feedback/Skeleton/Skeleton.types.d.ts

@@ -78,5 +78,48 @@ interface SkeletonGroupBaseProps extends BaseComponent<HTMLDivElement> {
     children?: React.ReactNode;
 }
 type SkeletonGroupProps = Prettify<SkeletonGroupBaseProps>;
+/**
+ * Pre-built skeleton arrangement.
+ *
+ * - `card`  — circular avatar, a few text lines, and a thumbnail block
+ * - `list`  — vertical rows of avatar + two text lines
+ * - `table` — header row + data rows laid out on a CSS grid
+ * - `grid`  — uniform grid of square blocks (no animation by default)
+ * - `chat`  — alternating left/right message bubbles
+ */
+type SkeletonLayoutVariant = 'card' | 'list' | 'table' | 'grid' | 'chat';
+interface SkeletonLayoutBaseProps extends BaseComponent<HTMLDivElement> {
+    /**
+     * Which pre-built arrangement to render.
+     */
+    variant: SkeletonLayoutVariant;
+    /**
+     * Number of repeating units in the layout.
+     *
+     * - `list` — number of rows (default 5)
+     * - `table` — number of data rows excluding the header (default 5)
+     * - `grid` — total number of cells (default 12)
+     * - `chat` — number of message bubbles (default 4)
+     * - `card` — ignored (a card is a single unit)
+     */
+    count?: number;
+    /**
+     * Number of columns. Only meaningful for `grid` and `table` variants.
+     * @default 4
+     */
+    columns?: number;
+    /**
+     * Animation applied to every nested skeleton.
+     * Defaults to `pulse` for most variants and `none` for `grid` — running
+     * dozens of animations at once is more noise than help on dense surfaces.
+     */
+    animation?: SkeletonAnimation;
+    /**
+     * Width of the layout container. Number → px, string → CSS value.
+     * @default "100%"
+     */
+    width?: number | string;
+}
+type SkeletonLayoutProps = Prettify<SkeletonLayoutBaseProps>;
 
-export type { SkeletonAnimation, SkeletonBaseProps, SkeletonGroupBaseProps, SkeletonGroupProps, SkeletonProps, SkeletonShape };
+export type { SkeletonAnimation, SkeletonBaseProps, SkeletonGroupBaseProps, SkeletonGroupProps, SkeletonLayoutBaseProps, SkeletonLayoutProps, SkeletonLayoutVariant, SkeletonProps, SkeletonShape };