@rokkit/ui 1.0.0-next.98 → 1.0.1

package/src/types/toggle.ts

@@ -0,0 +1,68 @@
+/**
+ * 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'
+
+// =============================================================================
+// Toggle Item Types
+// =============================================================================
+
+/**
+ * Generic toggle item - can be any object with mapped fields
+ */
+export type ToggleItem = Record<string, unknown>
+
+// =============================================================================
+// Snippet Types
+// =============================================================================
+
+/**
+ * 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]>
+
+// =============================================================================
+// Component Props Types
+// =============================================================================
+
+/**
+ * Props for the Toggle component
+ */
+export interface ToggleProps {
+	/** 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
+}

package/src/types/toolbar.ts

@@ -0,0 +1,167 @@
+/**
+ * Toolbar Component Types
+ *
+ * Provides types for the data-driven Toolbar component.
+ * Field mapping and data access is handled by ProxyItem from @rokkit/states.
+ */
+
+// =============================================================================
+// Field Mapping Types
+// =============================================================================
+
+/**
+ * Field mapping configuration for toolbar data.
+ * Maps custom data field names to the component's expected properties.
+ */
+export interface ToolbarFields {
+	/** Field for display text/tooltip - default: 'text' */
+	text?: string
+
+	/** Field for the value to emit on click - default: 'value' */
+	value?: string
+
+	/** Field for icon class name - default: 'icon' */
+	icon?: string
+
+	/** Field for disabled state - default: 'disabled' */
+	disabled?: string
+
+	/** Field for active/pressed state - default: 'active' */
+	active?: string
+
+	/** Field for item type (button, toggle, separator, spacer, custom) - default: 'type' */
+	type?: string
+
+	/** Field for custom snippet name - default: 'snippet' */
+	snippet?: string
+
+	/** Field for aria-label override - default: 'label' */
+	label?: string
+
+	/** Field for keyboard shortcut display - default: 'shortcut' */
+	shortcut?: string
+}
+
+/**
+ * Default field mapping values
+ */
+export const defaultToolbarFields: Required<ToolbarFields> = {
+	text: 'text',
+	value: 'value',
+	icon: 'icon',
+	disabled: 'disabled',
+	active: 'active',
+	type: 'type',
+	snippet: 'snippet',
+	label: 'label',
+	shortcut: 'shortcut'
+}
+
+// =============================================================================
+// Toolbar Item Types
+// =============================================================================
+
+/**
+ * Generic toolbar item - can be any object with mapped fields
+ */
+export type ToolbarItem = Record<string, unknown>
+
+/**
+ * Built-in toolbar item types
+ */
+export type ToolbarItemType = 'button' | 'toggle' | 'separator' | 'spacer' | 'custom'
+
+// =============================================================================
+// Snippet Types
+// =============================================================================
+
+/**
+ * Handlers passed to custom item snippets
+ */
+export interface ToolbarItemHandlers {
+	/** Call to trigger item action */
+	onclick: () => void
+	/** Forward keyboard events for accessibility */
+	onkeydown: (event: KeyboardEvent) => void
+}
+
+/**
+ * Snippet type for rendering toolbar items
+ */
+export type ToolbarItemSnippet = import('svelte').Snippet<
+	[ToolbarItem, ToolbarFields, ToolbarItemHandlers]
+>
+
+// =============================================================================
+// Component Props Types
+// =============================================================================
+
+/**
+ * Props for the Toolbar component
+ */
+export interface ToolbarProps {
+	/** Array of toolbar items */
+	items?: ToolbarItem[]
+
+	/** Field mapping configuration */
+	fields?: ToolbarFields
+
+	/** Position of toolbar - affects border and sticky positioning */
+	position?: 'top' | 'bottom' | 'left' | 'right'
+
+	/** Size variant */
+	size?: 'sm' | 'md' | 'lg'
+
+	/** Width behaviour: full stretches to container, fit sizes to content */
+	width?: 'full' | 'fit'
+
+	/** Whether toolbar should stick to its position */
+	sticky?: boolean
+
+	/** Compact mode with reduced padding */
+	compact?: boolean
+
+	/** Show dividers between sections */
+	showDividers?: boolean
+
+	/** Whether the entire toolbar is disabled */
+	disabled?: boolean
+
+	/** Called when an item is clicked */
+	onclick?: (value: unknown, item: ToolbarItem) => void
+
+	/** Additional CSS classes */
+	class?: string
+
+	/** Custom snippet for rendering toolbar items */
+	item?: ToolbarItemSnippet
+
+	/** Slot for start section content */
+	start?: import('svelte').Snippet
+
+	/** Slot for center section content */
+	center?: import('svelte').Snippet
+
+	/** Slot for end section content */
+	end?: import('svelte').Snippet
+
+	/** Default slot for children */
+	children?: import('svelte').Snippet
+}
+
+/**
+ * Props for the ToolbarGroup component
+ */
+export interface ToolbarGroupProps {
+	/** Accessibility label for the group */
+	label?: string
+
+	/** Gap between items in the group */
+	gap?: 'none' | 'sm' | 'md' | 'lg'
+
+	/** Additional CSS classes */
+	class?: string
+
+	/** Group content */
+	children?: import('svelte').Snippet
+}

package/src/types/tooltip.ts

@@ -0,0 +1,21 @@
+import type { Snippet } from 'svelte'
+
+export interface TooltipProps {
+	/** Tooltip text (alternative: use tooltipContent snippet for rich content) */
+	content?: string
+
+	/** Preferred position — auto-flips when the preferred side overflows the viewport */
+	position?: 'top' | 'bottom' | 'left' | 'right'
+
+	/** Show delay in ms (default: 300) */
+	delay?: number
+
+	/** Additional CSS classes on the root wrapper */
+	class?: string
+
+	/** Trigger element(s) */
+	children?: Snippet
+
+	/** Rich tooltip content — overrides the content string */
+	tooltipContent?: Snippet
+}

package/src/types/tree.ts

@@ -0,0 +1,250 @@
+/**
+ * Tree Component Types
+ *
+ * Provides types for the data-driven Tree component.
+ * Supports hierarchical data with expand/collapse, tree lines, and custom icons.
+ * Field mapping and data access is handled by ProxyItem from @rokkit/states.
+ */
+
+import type { Snippet } from 'svelte'
+import { DEFAULT_STATE_ICONS } from '@rokkit/core'
+
+// =============================================================================
+// Field Mapping Types
+// =============================================================================
+
+/**
+ * Field mapping configuration for tree data.
+ * Extends base field mapping with tree-specific fields.
+ */
+export interface TreeFields extends Record<string, string> {
+	/** Field for expanded state - default: 'expanded' */
+	expanded?: string
+
+	/** Field for node level/depth - default: 'level' */
+	level?: string
+}
+
+/**
+ * Default field mapping values for tree
+ */
+export const defaultTreeFields: Required<Omit<TreeFields, 'fields'>> = {
+	text: 'text',
+	value: 'value',
+	icon: 'icon',
+	description: 'description',
+	shortcut: 'shortcut',
+	label: 'label',
+	disabled: 'disabled',
+	active: 'active',
+	type: 'type',
+	children: 'children',
+	snippet: 'snippet',
+	href: 'href',
+	badge: 'badge',
+	expanded: 'expanded',
+	level: 'level'
+}
+
+// =============================================================================
+// Tree Item Types
+// =============================================================================
+
+/**
+ * Generic tree item - can be any object with mapped fields
+ */
+export type TreeItem = Record<string, unknown>
+
+// =============================================================================
+// Tree Line/Connector Types
+// =============================================================================
+
+/**
+ * Types of tree line connectors
+ */
+export type TreeLineType = 'child' | 'last' | 'sibling' | 'empty' | 'icon'
+
+/**
+ * Connector types (without 'icon' which is handled separately)
+ */
+export type ConnectorType = 'child' | 'last' | 'sibling' | 'empty'
+
+/**
+ * Icons configuration for tree expand/collapse states.
+ * Keys match the naming convention in @rokkit/core DEFAULT_STATE_ICONS.
+ */
+export interface TreeStateIcons {
+	/** Icon class for expanded/opened state */
+	opened?: string
+	/** Icon class for collapsed/closed state */
+	closed?: string
+}
+
+/**
+ * Default state icons — uses semantic names from @rokkit/core
+ * that get resolved to actual icon classes via UnoCSS shortcuts.
+ */
+export const defaultTreeStateIcons: TreeStateIcons = {
+	opened: DEFAULT_STATE_ICONS.node.opened,
+	closed: DEFAULT_STATE_ICONS.node.closed
+}
+
+// =============================================================================
+// Snippet Types
+// =============================================================================
+
+/**
+ * Handlers passed to custom item snippets
+ */
+export interface TreeItemHandlers {
+	/** Call to trigger item selection */
+	onclick: () => void
+	/** Call to toggle expand/collapse */
+	ontoggle: () => void
+	/** Forward keyboard events for accessibility */
+	onkeydown: (event: KeyboardEvent) => void
+}
+
+/**
+ * Snippet type for rendering tree nodes.
+ * Parameters: item, fields, handlers, isActive, isExpanded, level
+ */
+export type TreeItemSnippet = Snippet<
+	[TreeItem, TreeFields, TreeItemHandlers, boolean, boolean, number]
+>
+
+/**
+ * Snippet type for rendering the expand/collapse icon
+ * Parameters: isExpanded, hasChildren, icons
+ */
+export type TreeToggleSnippet = Snippet<[boolean, boolean, TreeStateIcons]>
+
+/**
+ * Snippet type for rendering tree line connectors
+ * Parameters: lineType
+ */
+export type TreeConnectorSnippet = Snippet<[TreeLineType]>
+
+// =============================================================================
+// Component Props Types
+// =============================================================================
+
+/**
+ * Props for the Tree component
+ */
+export interface TreeProps {
+	/** Array of tree items (hierarchical) */
+	items?: TreeItem[]
+
+	/** Field mapping configuration */
+	fields?: TreeFields
+
+	/** Currently selected value */
+	value?: unknown
+
+	/** Size variant */
+	size?: 'sm' | 'md' | 'lg'
+
+	/** Tree line connector style — 'none' hides lines, 'solid'|'dashed'|'dotted' set the line style */
+	lineStyle?: 'none' | 'solid' | 'dashed' | 'dotted'
+
+	/** Enable multiple item selection (Ctrl+click toggle, Shift+click range) */
+	multiselect?: boolean
+
+	/** Which nodes are expanded (bindable) - keyed by node value */
+	expanded?: Record<string, boolean>
+
+	/** Selected items array (bindable) - populated in multiselect mode */
+	selected?: unknown[]
+
+	/** Expand all nodes by default */
+	expandAll?: boolean
+
+	/** Active item value - Tree looks up item by this value to highlight it */
+	active?: unknown
+
+	/** Icons for expand/collapse states */
+	icons?: TreeStateIcons
+
+	/** Called when an item is selected */
+	onselect?: (value: unknown, item: TreeItem) => void
+
+	/** Called when selected items change in multiselect mode */
+	onselectedchange?: (selected: unknown[]) => void
+
+	/** Called when expanded state changes */
+	onexpandedchange?: (expanded: Record<string, boolean>) => void
+
+	/** Called when a node is toggled */
+	ontoggle?: (value: unknown, item: TreeItem, isExpanded: boolean) => void
+
+	/** Called when expanding a node with unloaded children (children: true). Returns the children array. */
+	onloadchildren?: (value: unknown, item: TreeItem) => Promise<TreeItem[]>
+
+	/** Additional CSS classes */
+	class?: string
+
+	/** Custom snippet for rendering tree items */
+	item?: TreeItemSnippet
+
+	/** Custom snippet for rendering expand/collapse toggle */
+	toggle?: TreeToggleSnippet
+
+	/** Custom snippet for rendering tree line connectors */
+	connector?: TreeConnectorSnippet
+}
+
+// =============================================================================
+// Helper Functions
+// =============================================================================
+
+/**
+ * Mapping for calculating next line type based on parent type
+ * Based on @rokkit/core connector implementation
+ */
+const nextLineType: Record<TreeLineType, TreeLineType> = {
+	child: 'sibling',
+	last: 'empty',
+	sibling: 'sibling',
+	empty: 'empty',
+	icon: 'empty'
+}
+
+/**
+ * Constructs an array of line types for tree visualization.
+ * This determines what connectors to show at each depth level.
+ *
+ * Algorithm from @rokkit/core getLineTypes:
+ * - For all but the last parent type, convert to continuation type
+ * - For the last parent type, use the current node's position
+ * - Append 'icon' for nodes with children, 'empty' for leaf nodes
+ *
+ * @param hasChildren - Whether the node has children
+ * @param parentTypes - Line types from parent nodes
+ * @param position - Current position type ('child' or 'last')
+ * @returns Array of line types for rendering connectors
+ */
+export function getLineTypes(
+	hasChildren: boolean = false,
+	parentTypes: TreeLineType[] = [],
+	position: 'child' | 'last' = 'child'
+): TreeLineType[] {
+	const result = parentTypes.reduce<TreeLineType[]>((acc, type, index) => {
+		// For all but the last parent type, convert to next type
+		// 'child' -> 'sibling' (vertical line continues)
+		// 'last' -> 'empty' (no line, branch ended)
+		if (index < parentTypes.length - 1) {
+			return [...acc, nextLineType[type]]
+		}
+		// For the last parent type, use the current node's position
+		return [...acc, position]
+	}, [])
+
+	// Append icon slot for expandable nodes, empty for leaf nodes
+	return result.concat(hasChildren ? 'icon' : 'empty')
+}
+
+// Keep old name as alias for backward compatibility
+export const getTreeLineTypes = getLineTypes
+
+export { getSnippet } from './menu.js'

package/src/types/upload-file-status.ts

@@ -0,0 +1,45 @@
+/**
+ * UploadFileStatus Component Types
+ *
+ * Renders a single file's upload status with progress bar, action buttons
+ * (cancel/retry/remove), and file metadata (icon, name, size, status label).
+ * Action button visibility driven by cancelWhen/retryWhen/removeWhen arrays.
+ */
+
+import type { ProxyItem } from '@rokkit/states'
+
+// =============================================================================
+// Component Props
+// =============================================================================
+
+/**
+ * Props for the UploadFileStatus component
+ */
+export interface UploadFileStatusProps {
+	/** ProxyItem wrapping the file data */
+	proxy: ProxyItem
+
+	/** Status values that show the cancel button */
+	cancelWhen?: string[]
+
+	/** Status values that show the retry button */
+	retryWhen?: string[]
+
+	/** Status values that show the remove button */
+	removeWhen?: string[]
+
+	/** Called when cancel is clicked */
+	oncancel?: (proxy: ProxyItem) => void
+
+	/** Called when retry is clicked */
+	onretry?: (proxy: ProxyItem) => void
+
+	/** Called when remove is clicked */
+	onremove?: (proxy: ProxyItem) => void
+
+	/** Label overrides merged with messages.uploadProgress */
+	labels?: Record<string, string>
+
+	/** Icon class overrides for action buttons (cancel, retry, remove) */
+	icons?: Record<string, string>
+}

package/src/types/upload-progress.ts

@@ -0,0 +1,111 @@
+/**
+ * UploadProgress Component Types
+ *
+ * File upload status orchestrator. Thin composition layer that renders
+ * a header + List or Grid layout. Default itemContent snippet renders
+ * UploadFileStatus for each file. Consumer can override with custom snippet.
+ */
+
+import type { Snippet } from 'svelte'
+import type { ProxyItem } from '@rokkit/states'
+
+// =============================================================================
+// Item Types
+// =============================================================================
+
+/**
+ * Generic upload file item — any object with mapped fields
+ */
+export type UploadItem = Record<string, unknown>
+
+// =============================================================================
+// Field Mapping Types
+// =============================================================================
+
+/**
+ * Field mapping for upload file data.
+ * Maps semantic field names to keys in the data objects.
+ */
+export interface UploadFields {
+	/** Field for display text - default: 'text' */
+	label?: string
+
+	/** Field for unique value - default: 'value' */
+	value?: string
+
+	/** Field for icon class - default: 'icon' */
+	icon?: string
+
+	/** Field for upload status key - default: 'status' */
+	status?: string
+
+	/** Field for progress percentage (0-100) - default: 'progress' */
+	progress?: string
+
+	/** Field for file size in bytes - default: 'size' */
+	size?: string
+
+	/** Field for MIME type - default: 'type' */
+	type?: string
+
+	/** Field for error message - default: 'error' */
+	error?: string
+}
+
+// =============================================================================
+// Snippet Types
+// =============================================================================
+
+/**
+ * Snippet for custom per-file rendering inside List/Grid.
+ * Receives the ProxyItem wrapping the file data.
+ */
+export type UploadItemSnippet = Snippet<[proxy: ProxyItem]>
+
+// =============================================================================
+// Component Props
+// =============================================================================
+
+/**
+ * Props for the UploadProgress component
+ */
+export interface UploadProgressProps {
+	/** Array of file data objects */
+	files?: UploadItem[]
+
+	/** Field mapping configuration */
+	fields?: UploadFields
+
+	/** Layout mode */
+	view?: 'list' | 'grid'
+
+	/** Status values that show the cancel button */
+	cancelWhen?: string[]
+
+	/** Status values that show the retry button */
+	retryWhen?: string[]
+
+	/** Status values that show the remove button */
+	removeWhen?: string[]
+
+	/** Called when cancel is clicked (receives raw file object) */
+	oncancel?: (file: UploadItem) => void
+
+	/** Called when retry is clicked (receives raw file object) */
+	onretry?: (file: UploadItem) => void
+
+	/** Called when remove is clicked (receives raw file object) */
+	onremove?: (file: UploadItem) => void
+
+	/** Called when clear all is clicked */
+	onclear?: () => void
+
+	/** Label overrides merged with messages.uploadProgress */
+	labels?: Record<string, string>
+
+	/** Additional CSS classes */
+	class?: string
+
+	/** Custom snippet for per-file rendering (overrides default UploadFileStatus) */
+	itemContent?: UploadItemSnippet
+}