@rokkit/ui 1.0.0-next.99 → 1.0.2

package/src/types/search-filter.ts

@@ -0,0 +1,67 @@
+/**
+ * SearchFilter Component Types
+ *
+ * Provides types for the standalone SearchFilter component.
+ * Parses user input into structured filter objects using parseFilters() from @rokkit/data.
+ */
+
+// =============================================================================
+// Filter Types
+// =============================================================================
+
+/**
+ * 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 Types
+// =============================================================================
+
+/**
+ * Snippet for custom filter tag rendering.
+ * Parameters: filter, remove callback
+ */
+export type SearchFilterTagSnippet = import('svelte').Snippet<[FilterObject, () => void]>
+
+// =============================================================================
+// Component Props
+// =============================================================================
+
+/**
+ * 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/src/types/select.ts

@@ -0,0 +1,176 @@
+/**
+ * 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'
+import { DEFAULT_STATE_ICONS } from '@rokkit/core'
+
+// =============================================================================
+// Select Item Types
+// =============================================================================
+
+/**
+ * Generic select item - can be any object with mapped fields
+ */
+export type SelectItem = Record<string, unknown>
+
+// =============================================================================
+// Legacy types — retained while PaletteManager still uses old snippet API
+// =============================================================================
+
+/** @deprecated Legacy handlers — will be removed when PaletteManager migrates to Navigator stack */
+export interface SelectItemHandlers {
+	onclick: () => void
+	onkeydown: (event: KeyboardEvent) => void
+}
+
+// =============================================================================
+// Snippet Types — ProxyItem-based API
+// =============================================================================
+
+/**
+ * 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[]]>
+
+// =============================================================================
+// Component Props Types
+// =============================================================================
+
+/**
+ * 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
+}
+
+// =============================================================================
+// State Icons
+// =============================================================================
+
+/**
+ * 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 const defaultSelectStateIcons: SelectStateIcons = {
+	opened: DEFAULT_STATE_ICONS.selector.opened,
+	closed: DEFAULT_STATE_ICONS.selector.closed,
+	checked: DEFAULT_STATE_ICONS.checkbox.checked,
+	remove: DEFAULT_STATE_ICONS.action.remove
+}
+
+// =============================================================================
+// Helper Functions
+// =============================================================================
+
+export { getSnippet } from './menu.js'

package/src/types/switch.ts

@@ -0,0 +1,68 @@
+/**
+ * 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 Types
+// =============================================================================
+
+/**
+ * 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
+}
+
+// =============================================================================
+// Switch Item Types
+// =============================================================================
+
+/**
+ * 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
+
+// =============================================================================
+// Component Props Types
+// =============================================================================
+
+/**
+ * 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/src/types/table.ts

@@ -0,0 +1,219 @@
+/**
+ * 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.
+ */
+
+import { DEFAULT_STATE_ICONS } from '@rokkit/core'
+
+// =============================================================================
+// Column Types
+// =============================================================================
+
+/**
+ * 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
+}
+
+// =============================================================================
+// Sort Types
+// =============================================================================
+
+/**
+ * Represents the sort state for a single column.
+ */
+export interface SortState {
+	/** Column name */
+	column: string
+
+	/** Sort direction */
+	direction: 'ascending' | 'descending'
+}
+
+// =============================================================================
+// Field Mapping Types
+// =============================================================================
+
+/**
+ * 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 const defaultTableFields: Required<TableFields> = {
+	value: 'id',
+	disabled: 'disabled'
+}
+
+// =============================================================================
+// Sort Icons
+// =============================================================================
+
+/**
+ * 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 const defaultTableSortIcons: TableSortIcons = {
+	none: DEFAULT_STATE_ICONS.sort.none,
+	ascending: DEFAULT_STATE_ICONS.sort.ascending,
+	descending: DEFAULT_STATE_ICONS.sort.descending
+}
+
+// =============================================================================
+// Snippet Types
+// =============================================================================
+
+/**
+ * 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<[]>
+
+// =============================================================================
+// Component Props
+// =============================================================================
+
+/**
+ * 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/src/types/tabs.ts

@@ -0,0 +1,103 @@
+/**
+ * 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'
+
+// =============================================================================
+// Tabs Item Types
+// =============================================================================
+
+/**
+ * Generic tab item - can be any object with mapped fields
+ */
+export type TabsItem = Record<string, unknown>
+
+// =============================================================================
+// Snippet Types — ProxyItem-based API
+// =============================================================================
+
+/**
+ * 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<[]>
+
+// =============================================================================
+// Component Props Types
+// =============================================================================
+
+/**
+ * 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 */
+	onchange?: (value: unknown, item: TabsItem) => void
+
+	/** Called when a tab is selected (fires on every click, including same tab) */
+	onselect?: (value: unknown, item: TabsItem) => 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/src/types/timeline.ts

@@ -0,0 +1,53 @@
+/**
+ * Timeline Component Types
+ *
+ * View-only vertical steps for instructions, changelogs,
+ * or process visualization. No interaction.
+ */
+
+import type { Snippet } from 'svelte'
+// =============================================================================
+// Field Mapping Types
+// =============================================================================
+
+export interface TimelineFields {
+	label?: string
+	icon?: string
+	subtext?: string
+}
+
+export const defaultTimelineFields: Required<TimelineFields> = {
+	label: 'label',
+	icon: 'icon',
+	subtext: 'description'
+}
+
+// =============================================================================
+// Component Props Types
+// =============================================================================
+
+export interface TimelineIcons {
+	/** Icon class for completed state (default: i-lucide:check) */
+	completed?: string
+}
+
+export const defaultTimelineIcons: Required<TimelineIcons> = {
+	completed: 'i-lucide:check'
+}
+
+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]>
+}