@rokkit/ui 1.1.18 → 1.2.0

package/dist/types/search-filter.d.ts

@@ -0,0 +1,43 @@
+/**
+ * SearchFilter Component Types
+ *
+ * Provides types for the standalone SearchFilter component.
+ * Parses user input into structured filter objects using parseFilters() from @rokkit/data.
+ */
+/**
+ * A parsed filter condition.
+ */
+export interface FilterObject {
+    /** Column to filter (undefined = search all columns) */
+    column?: string;
+    /** Comparison operator */
+    operator: string;
+    /** Filter value */
+    value: string | number | RegExp;
+}
+/**
+ * Snippet for custom filter tag rendering.
+ * Parameters: filter, remove callback
+ */
+export type SearchFilterTagSnippet = import('svelte').Snippet<[FilterObject, () => void]>;
+/**
+ * Props for the SearchFilter component.
+ */
+export interface SearchFilterProps {
+    /** Parsed filter array (bindable) */
+    filters?: FilterObject[];
+    /** Debounce delay in ms — default: 300 */
+    debounce?: number;
+    /** Input placeholder text */
+    placeholder?: string;
+    /** Column name hints for autocomplete (future use) */
+    columns?: string[];
+    /** Called when filters change */
+    onfilter?: (filters: FilterObject[]) => void;
+    /** Additional CSS classes */
+    class?: string;
+    /** Size variant */
+    size?: 'sm' | 'md' | 'lg';
+    /** Custom filter tag snippet */
+    tag?: SearchFilterTagSnippet;
+}

package/dist/types/select.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Select Component Types
+ *
+ * Provides types for the data-driven Select and MultiSelect components.
+ * Field mapping and data access is handled by ProxyItem from @rokkit/states.
+ */
+import type { Snippet } from 'svelte';
+import type { ProxyItem } from '@rokkit/states';
+/**
+ * Generic select item - can be any object with mapped fields
+ */
+export type SelectItem = Record<string, unknown>;
+/** @deprecated Legacy handlers — will be removed when PaletteManager migrates to Navigator stack */
+export interface SelectItemHandlers {
+    onclick: () => void;
+    onkeydown: (event: KeyboardEvent) => void;
+}
+/**
+ * Snippet type for rendering a single option in the dropdown.
+ * The component renders the focusable wrapper; the snippet renders the inner content.
+ * Navigator handles click selection via data-path — no handlers needed in snippet.
+ */
+export type SelectOptionSnippet = Snippet<[ProxyItem]>;
+/**
+ * Snippet type for rendering a group header label.
+ */
+export type SelectGroupLabelSnippet = Snippet<[ProxyItem]>;
+/**
+ * Snippet type for rendering the selected value display in the trigger button.
+ */
+export type SelectValueSnippet = Snippet<[ProxyItem]>;
+/**
+ * Snippet type for rendering selected values in MultiSelect trigger.
+ * Receives the array of selected ProxyItems.
+ */
+export type MultiSelectValueSnippet = Snippet<[ProxyItem[]]>;
+/**
+ * Common props shared between Select and MultiSelect
+ */
+export interface SelectBaseProps {
+    /** Array of select options or groups */
+    options?: SelectItem[];
+    /** Field mapping — overrides BASE_FIELDS defaults (text → 'label', value → 'value', …) */
+    fields?: Record<string, string>;
+    /** Placeholder text when no selection */
+    placeholder?: string;
+    /** Size variant */
+    size?: 'sm' | 'md' | 'lg';
+    /** Dropdown alignment relative to trigger */
+    align?: 'left' | 'right' | 'start' | 'end';
+    /** Dropdown slide direction */
+    direction?: 'up' | 'down';
+    /** Maximum visible rows in dropdown (default: 5) */
+    maxRows?: number;
+    /** Whether the select is disabled */
+    disabled?: boolean;
+    /** Additional CSS classes on root element */
+    class?: string;
+    /** Icons for select states (dropdown arrow, check, remove) */
+    icons?: SelectStateIcons;
+    /** Custom snippet for rendering options in dropdown */
+    option?: SelectOptionSnippet;
+    /** Custom snippet for rendering group labels */
+    groupLabel?: SelectGroupLabelSnippet;
+    /** Enable typeahead filter input in dropdown header */
+    filterable?: boolean;
+    /** Placeholder text for the filter input */
+    filterPlaceholder?: string;
+}
+/**
+ * Props for the Select component (single selection)
+ */
+export interface SelectProps extends SelectBaseProps {
+    /** Currently selected value (bindable) — extracted via item[fields.value] */
+    value?: unknown;
+    /** Currently selected raw item (bindable) — full object from options array */
+    selected?: SelectItem | null;
+    /** Called when selection changes */
+    onchange?: (value: unknown, item: SelectItem) => void;
+    /** Custom snippet for rendering the selected value in the trigger */
+    selectedValue?: SelectValueSnippet;
+}
+/**
+ * Props for the MultiSelect component (multiple selection)
+ */
+export interface MultiSelectProps extends SelectBaseProps {
+    /** Currently selected values (bindable) - extracted primitives */
+    value?: unknown[];
+    /** Currently selected items (bindable) - full item objects for convenience */
+    selected?: SelectItem[];
+    /** Called when selection changes */
+    onchange?: (values: unknown[], items: SelectItem[]) => void;
+    /** Maximum number of tags to show before collapsing to count */
+    maxDisplay?: number;
+}
+/**
+ * Icons configuration for select expand/collapse and selection states.
+ */
+export interface SelectStateIcons {
+    /** Icon class for dropdown arrow (open state) */
+    opened?: string;
+    /** Icon class for dropdown arrow (closed state) */
+    closed?: string;
+    /** Icon class for selected item indicator */
+    checked?: string;
+    /** Icon class for tag remove button (MultiSelect) */
+    remove?: string;
+}
+/**
+ * Default state icons — uses semantic names from @rokkit/core
+ * that get resolved to actual icon classes via UnoCSS shortcuts.
+ */
+export declare const defaultSelectStateIcons: SelectStateIcons;
+export { getSnippet } from './menu.js';

package/dist/types/shine.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Shine Component Types
+ *
+ * Renders an SVG specular-lighting filter that tracks pointer position to
+ * give wrapped content a moving highlight.
+ */
+import type { Snippet } from 'svelte';
+/**
+ * Props for the Shine component.
+ */
+export interface ShineProps {
+    /** Light color. Default `'rgb(var(--primary-500))'`. */
+    color?: string;
+    /** Light source distance / height — controls highlight spread. Default `300`. */
+    radius?: number;
+    /** Gaussian blur depth applied to the highlight. Default `1`. */
+    depth?: number;
+    /** Surface height for the light filter. Default `2`. */
+    surfaceScale?: number;
+    /** Reflection size — bigger = bigger reflection. Default `0.75`. */
+    specularConstant?: number;
+    /** Light source focus — bigger = brighter. Default `120`. */
+    specularExponent?: number;
+    /** Additional CSS class. */
+    class?: string;
+    /** Content the highlight wraps. */
+    children?: Snippet;
+}

package/dist/types/stack.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Stack Component Types
+ */
+import type { Snippet } from 'svelte';
+/** Layout direction. */
+export type StackDirection = 'vertical' | 'horizontal';
+/** Gap size between children — maps to the theme's spacing scale. */
+export type StackGap = 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+/** Cross-axis alignment. */
+export type StackAlign = 'start' | 'center' | 'end' | 'stretch';
+/** Main-axis justification. */
+export type StackJustify = 'start' | 'center' | 'end' | 'between' | 'around';
+/**
+ * Props for the Stack component.
+ */
+export interface StackProps {
+    /** Layout direction. */
+    direction?: StackDirection;
+    /** Gap size between children. */
+    gap?: StackGap;
+    /** Cross-axis alignment. */
+    align?: StackAlign;
+    /** Main-axis justification. */
+    justify?: StackJustify;
+    /** Stack children. */
+    children: Snippet;
+    /** Additional CSS class. */
+    class?: string;
+}

package/dist/types/status-list.d.ts

@@ -0,0 +1,35 @@
+/**
+ * StatusList Component Types
+ *
+ * Renders a vertical list of status rows — each with a label and a status
+ * keyword that maps to a badge icon (e.g. `pass`, `fail`, `warn`).
+ */
+import { DEFAULT_STATE_ICONS } from '@rokkit/core';
+/**
+ * Built-in badge status keys provided by `@rokkit/core`. Consumers may also
+ * pass any other string and supply a matching entry via the `icons` prop.
+ */
+export type StatusListStatus = keyof typeof DEFAULT_STATE_ICONS.badge | (string & {});
+/**
+ * One row in a StatusList — a label paired with a status keyword.
+ */
+export interface StatusListItem {
+    /** Text rendered for this row. */
+    text: string;
+    /** Status keyword used to look up the badge icon. */
+    status: StatusListStatus;
+}
+/**
+ * Props for the StatusList component.
+ */
+export interface StatusListProps {
+    /** Additional CSS class applied to the root element. */
+    class?: string;
+    /** Rows to render. */
+    items: StatusListItem[];
+    /**
+     * Override the default badge icon map (`pass` / `fail` / `warn` / `unknown`).
+     * Merged on top of `DEFAULT_STATE_ICONS.badge` from `@rokkit/core`.
+     */
+    icons?: Partial<Record<string, string>>;
+}

package/dist/types/stepper.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Stepper Component Types
+ */
+import type { Snippet } from 'svelte';
+/** Layout orientation for the stepper. */
+export type StepperOrientation = 'horizontal' | 'vertical';
+/**
+ * Definition for a single step in the stepper.
+ */
+export interface StepperStep {
+    /** Step label (shown below the circle). */
+    text: string;
+    /** Short text shown inside the circle. Default: step number. */
+    label?: string;
+    /** Step is finished — shows the check icon. */
+    completed?: boolean;
+    /** Step cannot be navigated to. */
+    disabled?: boolean;
+    /** Number of sub-stages within this step. Default `1`. */
+    stages?: number;
+}
+/**
+ * Icon overrides for the Stepper component.
+ */
+export interface StepperIcons {
+    /** Icon class for the check / completed state. */
+    check?: string;
+}
+/**
+ * Props for the Stepper component.
+ */
+export interface StepperProps {
+    /** Array of step definitions. */
+    steps?: StepperStep[];
+    /** Current step index (bindable). */
+    current?: number;
+    /** Current sub-stage within the step (bindable, 0-based). */
+    currentStage?: number;
+    /**
+     * In linear mode only completed steps + the first incomplete step
+     * are clickable.
+     */
+    linear?: boolean;
+    /** Layout orientation. */
+    orientation?: StepperOrientation;
+    /** Accessible label for the surrounding group. */
+    label?: string;
+    /** Custom icon overrides. */
+    icons?: StepperIcons;
+    /** Called when a step (or sub-stage dot) is clicked. */
+    onclick?: (step: number, stage?: number) => void;
+    /** Content snippet rendered below the stepper. */
+    content?: Snippet<[StepperStep, number]>;
+    /** Additional CSS class. */
+    class?: string;
+}

package/dist/types/switch.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Switch Component Types
+ *
+ * Provides types for the iOS-style Switch component.
+ * Field mapping and data access is handled by ProxyItem from @rokkit/states.
+ */
+/**
+ * Field mapping configuration for switch option data.
+ * Maps custom data field names to the component's expected properties.
+ */
+export interface SwitchFields {
+    text?: string;
+    value?: string;
+    icon?: string;
+    disabled?: string;
+    description?: string;
+}
+/**
+ * A switch option — can be any object, primitive, or boolean.
+ * Processed through ProxyItem for field resolution.
+ */
+export type SwitchItem = Record<string, unknown> | string | number | boolean;
+/**
+ * Props for the Switch component
+ */
+export interface SwitchProps {
+    /**
+     * Exactly two options. First = off/unchecked. Second = on/checked.
+     * @default [false, true]
+     */
+    options?: [SwitchItem, SwitchItem];
+    /** Field mapping configuration */
+    fields?: SwitchFields;
+    /** Currently selected value */
+    value?: unknown;
+    /** Called when the switch changes */
+    onchange?: (value: unknown, item: SwitchItem) => void;
+    /** Whether to show text labels beside the track */
+    showLabels?: boolean;
+    /** Size variant */
+    size?: 'sm' | 'md' | 'lg';
+    /** Whether the switch is disabled */
+    disabled?: boolean;
+    /** Additional CSS classes */
+    class?: string;
+}

package/dist/types/table.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Table Component Types
+ *
+ * Provides types for the data-driven Table component.
+ * Supports flat tables with sortable columns, row selection, and keyboard navigation.
+ * Field mapping and data access is handled by ProxyItem from @rokkit/states per cell.
+ */
+/**
+ * Column definition for the Table component.
+ * Can be auto-derived from data or provided explicitly.
+ */
+export interface TableColumn {
+    /** Data key for this column */
+    name: string;
+    /** Display header text (defaults to name) */
+    label?: string;
+    /** Data type (auto-derived: 'string', 'number', etc.) */
+    type?: string;
+    /** Whether this column is sortable — default: true */
+    sortable?: boolean;
+    /** Current sort direction */
+    sorted?: 'none' | 'ascending' | 'descending';
+    /** CSS width (e.g., '200px', '20%') */
+    width?: string;
+    /** Text alignment */
+    align?: 'left' | 'center' | 'right';
+    /** Field mapping — maps ProxyItem slots to data keys */
+    fields?: {
+        text?: string;
+        icon?: string;
+        badge?: string;
+        description?: string;
+    };
+    /** Value formatter for display */
+    formatter?: (value: unknown, row: Record<string, unknown>) => string;
+    /** Icon formatter — transforms icon field value to icon class */
+    iconFormatter?: (value: unknown) => string;
+    /** Named snippet for custom cell rendering */
+    snippet?: string;
+}
+/**
+ * Represents the sort state for a single column.
+ */
+export interface SortState {
+    /** Column name */
+    column: string;
+    /** Sort direction */
+    direction: 'ascending' | 'descending';
+}
+/**
+ * Row-level field mapping configuration.
+ */
+export interface TableFields {
+    /** Field for row value used in selection matching — default: 'id' */
+    value?: string;
+    /** Field for disabled state — default: 'disabled' */
+    disabled?: string;
+}
+/**
+ * Default row-level field mapping values.
+ */
+export declare const defaultTableFields: Required<TableFields>;
+/**
+ * Icons for sort state indicators.
+ */
+export interface TableSortIcons {
+    /** Icon for unsorted column */
+    none?: string;
+    /** Icon for ascending sort */
+    ascending?: string;
+    /** Icon for descending sort */
+    descending?: string;
+}
+/**
+ * Default sort icons from @rokkit/core state icons.
+ */
+export declare const defaultTableSortIcons: TableSortIcons;
+/**
+ * Snippet for custom header rendering.
+ * Parameters: columns, sortState
+ */
+export type TableHeaderSnippet = import('svelte').Snippet<[TableColumn[], SortState[]]>;
+/**
+ * Snippet for custom row rendering.
+ * Parameters: row, columns, index, isSelected
+ */
+export type TableRowSnippet = import('svelte').Snippet<[
+    Record<string, unknown>,
+    TableColumn[],
+    number,
+    boolean
+]>;
+/**
+ * Snippet for custom cell rendering.
+ * Parameters: value, column, row
+ */
+export type TableCellSnippet = import('svelte').Snippet<[
+    unknown,
+    TableColumn,
+    Record<string, unknown>
+]>;
+/**
+ * Snippet for empty state.
+ */
+export type TableEmptySnippet = import('svelte').Snippet<[]>;
+/**
+ * Props for the Table component.
+ */
+export interface TableProps {
+    /** Data array — each object is a row */
+    data?: Record<string, unknown>[];
+    /** Column definitions (auto-derived from data if not provided) */
+    columns?: TableColumn[];
+    /** Currently selected row value (single-select) */
+    value?: unknown;
+    /** Currently selected row values (multi-select, bindable) */
+    values?: unknown[];
+    /** Selection mode: 'single' (default), 'multi', or false (no selection) */
+    selectable?: 'single' | 'multi' | false;
+    /** Table caption for accessibility */
+    caption?: string;
+    /** Size variant */
+    size?: 'sm' | 'md' | 'lg';
+    /** Enable alternating row colors */
+    striped?: boolean;
+    /** Enable responsive card layout on mobile (< 640px) */
+    responsive?: boolean;
+    /** Whether the entire table is disabled */
+    disabled?: boolean;
+    /** Row-level field mapping */
+    fields?: TableFields;
+    /** Called when a row is selected */
+    onselect?: (value: unknown, row: Record<string, unknown>) => void;
+    /** Called when sort state changes */
+    onsort?: (sortState: SortState[]) => void;
+    /** Additional CSS classes */
+    class?: string;
+    /** Sort indicator icons */
+    icons?: TableSortIcons;
+    /** Custom header snippet */
+    header?: TableHeaderSnippet;
+    /** Custom row snippet */
+    row?: TableRowSnippet;
+    /** Custom cell snippet */
+    cell?: TableCellSnippet;
+    /** Empty state snippet */
+    empty?: TableEmptySnippet;
+}

package/dist/types/tabs.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Tabs Component Types
+ *
+ * Provides types for the data-driven Tabs component.
+ * Field mapping and data access is handled by ProxyItem from @rokkit/states.
+ */
+import type { Snippet } from 'svelte';
+import type { ProxyItem } from '@rokkit/states';
+/**
+ * Generic tab item - can be any object with mapped fields
+ */
+export type TabsItem = Record<string, unknown>;
+/**
+ * Snippet type for rendering tab triggers (headers).
+ * The component renders the focusable wrapper; the snippet renders the inner content.
+ * Navigator handles click selection via data-path — no handlers needed in snippet.
+ * Receives the ProxyItem and whether this item is currently selected.
+ */
+export type TabsItemSnippet = Snippet<[ProxyItem, boolean]>;
+/**
+ * Snippet type for rendering tab panel content.
+ */
+export type TabsPanelSnippet = Snippet<[ProxyItem]>;
+/**
+ * Snippet type for rendering the empty state.
+ */
+export type TabsEmptySnippet = Snippet<[]>;
+/**
+ * Props for the Tabs component
+ */
+export interface TabsProps {
+    /** Array of tab options */
+    options?: TabsItem[];
+    /** Field mapping — overrides BASE_FIELDS defaults (text → 'label', value → 'value', …) */
+    fields?: Record<string, string>;
+    /** Currently selected tab value */
+    value?: unknown;
+    /** Orientation of the tab list */
+    orientation?: 'horizontal' | 'vertical';
+    /** Position of the tab list relative to panels */
+    position?: 'before' | 'after';
+    /** Alignment of tabs within the tab list */
+    align?: 'start' | 'center' | 'end';
+    /** Accessible name for the tab list */
+    name?: string;
+    /** Whether tabs can be added/removed */
+    editable?: boolean;
+    /** Placeholder text when no tab is selected */
+    placeholder?: string;
+    /** Whether the entire tab component is disabled */
+    disabled?: boolean;
+    /** Additional CSS classes */
+    class?: string;
+    /** Called when selection changes — receives the value and the tab's ProxyItem */
+    onchange?: (value: unknown, item: ProxyItem) => void;
+    /** Called when a tab is selected (fires on every click, including same tab) — receives the value and the tab's ProxyItem */
+    onselect?: (value: unknown, item: ProxyItem) => void;
+    /** Called when a new tab is requested (editable mode) */
+    onadd?: () => void;
+    /** Called when a tab removal is requested (editable mode) */
+    onremove?: (value: unknown) => void;
+    /** Custom snippet for rendering tab triggers */
+    tabItem?: TabsItemSnippet;
+    /** Custom snippet for rendering tab panel content */
+    tabPanel?: TabsPanelSnippet;
+    /** Custom snippet for rendering the empty state */
+    empty?: TabsEmptySnippet;
+}

package/dist/types/tilt.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Tilt Component Types
+ */
+import type { Snippet } from 'svelte';
+/**
+ * Props for the Tilt component.
+ *
+ * Wraps content in a container that rotates in response to pointer
+ * movement, with optional brightness modulation.
+ */
+export interface TiltProps {
+    /** Maximum rotation angle in degrees. Default `10`. */
+    maxRotation?: number;
+    /** Whether to adjust brightness based on pointer Y position. */
+    setBrightness?: boolean;
+    /** CSS perspective value in pixels. Default `600`. */
+    perspective?: number;
+    /** Additional CSS class. */
+    class?: string;
+    /** Content to tilt. */
+    children?: Snippet;
+}

package/dist/types/timeline.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Timeline Component Types
+ *
+ * View-only vertical steps for instructions, changelogs,
+ * or process visualization. No interaction.
+ */
+import type { Snippet } from 'svelte';
+export interface TimelineFields {
+    label?: string;
+    icon?: string;
+    subtext?: string;
+}
+export declare const defaultTimelineFields: Required<TimelineFields>;
+export interface TimelineIcons {
+    /** Icon class for completed state (default: i-lucide:check) */
+    completed?: string;
+}
+export declare const defaultTimelineIcons: Required<TimelineIcons>;
+export interface TimelineProps {
+    /** Array of timeline items */
+    items?: Record<string, unknown>[];
+    /** Field mapping configuration */
+    fields?: TimelineFields;
+    /** Custom icons */
+    icons?: TimelineIcons;
+    /** Additional CSS class */
+    class?: string;
+    /** Custom content snippet for each item: (item, index) */
+    content?: Snippet<[Record<string, unknown>, number]>;
+}

package/dist/types/toggle.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Toggle Component Types
+ *
+ * Provides types for the data-driven Toggle component.
+ * Field mapping and data access is handled by ProxyItem from @rokkit/states.
+ */
+import type { Snippet } from 'svelte';
+import type { ProxyItem } from '@rokkit/states';
+/**
+ * Generic toggle item — data-driven, so it accepts primitives
+ * (string/number) as well as objects with mapped fields.
+ */
+export type ToggleItem = string | number | Record<string, unknown>;
+/**
+ * Snippet for rendering a toggle option.
+ * The component renders the button wrapper; the snippet renders inner content.
+ * Receives the ProxyItem and whether this item is currently selected.
+ */
+export type ToggleItemSnippet = Snippet<[ProxyItem, boolean]>;
+/**
+ * Visual variant of the Toggle.
+ * - `'group'` (default) — segmented radio-group rendering, one button per option.
+ * - `'button'` — single button that cycles through the options on each click.
+ *   The rendered content represents the *next* option (the one you'd switch to),
+ *   so users can read the click destination at a glance.
+ */
+export type ToggleVariant = 'group' | 'button';
+/**
+ * Props for the Toggle component
+ */
+export interface ToggleProps {
+    /** Visual variant. Default: 'group'. */
+    variant?: ToggleVariant;
+    /** Array of toggle options (strings, numbers, or objects) */
+    options?: ToggleItem[];
+    /** Field mapping — overrides BASE_FIELDS defaults (text → 'label', value → 'value', …) */
+    fields?: Record<string, string>;
+    /** Currently selected value (bindable) */
+    value?: unknown;
+    /** Called when selection changes */
+    onchange?: (value: unknown, item: ToggleItem) => void;
+    /** Whether to show text labels alongside icons */
+    showLabels?: boolean;
+    /** Size variant */
+    size?: 'sm' | 'md' | 'lg';
+    /** Whether the entire toggle is disabled */
+    disabled?: boolean;
+    /** Accessible label for the radiogroup. Default: messages.toggle.label */
+    label?: string;
+    /** Additional CSS classes */
+    class?: string;
+    /** Custom snippet for rendering toggle options */
+    item?: ToggleItemSnippet;
+}