@rokkit/ui 1.1.1 → 1.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rokkit/ui",
-  "version": "1.1.1",
+  "version": "1.1.4",
   "description": "Data driven UI components for Rokkit applications",
   "repository": {
     "type": "git",
@@ -44,10 +44,10 @@
     "dropdown"
   ],
   "dependencies": {
-    "@rokkit/core": "1.1.1",
-    "@rokkit/data": "1.1.1",
-    "@rokkit/states": "1.1.1",
-    "@rokkit/actions": "1.1.1",
+    "@rokkit/core": "1.1.4",
+    "@rokkit/data": "1.1.4",
+    "@rokkit/states": "1.1.4",
+    "@rokkit/actions": "1.1.4",
     "marked": "^15.0.0",
     "dompurify": "^3.0.0"
   },

package/src/components/Table.svelte

@@ -1,9 +1,8 @@
 <script lang="ts">
 	import type { TableProps, TableColumn, TableSortIcons } from '../types/table.js'
 	import { defaultTableSortIcons } from '../types/table.js'
-	import { TableController, messages } from '@rokkit/states'
-	import { navigator } from '@rokkit/actions'
-	import { untrack } from 'svelte'
+	import { ProxyItem, ProxyTable, Wrapper, messages } from '@rokkit/states'
+	import { Navigator } from '@rokkit/actions'
 
 	let {
 		data = [],
@@ -29,109 +28,59 @@
 
 	const icons = $derived<TableSortIcons>({ ...defaultTableSortIcons, ...userIcons })
 
-	// ─── Controller ─────────────────────────────────────────────────
+	// ─── ProxyTable + Wrapper ───────────────────────────────────────
 
-	let controller = untrack(
-		() =>
-			new TableController(data, {
-				columns: userColumns,
-				fields: userFields,
-				value,
-				multiselect: selectable === 'multi'
-			})
+	const multiselect = $derived(selectable === 'multi')
+
+	const proxyTable = $derived(
+		new ProxyTable(data, { columns: userColumns, fields: userFields, onsort })
 	)
 
-	// Sync values binding from controller selection in multi-select mode
-	$effect(() => {
-		if (selectable === 'multi') {
-			values = controller.selected.slice()
-		}
-	})
-	let tableRef = $state<HTMLElement | null>(null)
+	const wrapper = $derived(
+		new Wrapper(proxyTable, {
+			onselect: (_v: unknown, proxy: ProxyItem) => {
+				if (selectable === false || disabled) return
+				onselect?.(proxy.value, proxy.value as Record<string, unknown>)
+			},
+			collapsible: false,
+			multiselect
+		})
+	)
 
-	// Sync data changes to controller
+	// Sync value bindings out
 	$effect(() => {
-		controller.update(data)
+		wrapper.moveToValue(value)
 	})
-
-	// Sync columns changes
 	$effect(() => {
-		if (userColumns) {
-			controller.columns = userColumns.map((c) => ({
-				sortable: true,
-				sorted: 'none',
-				...c
-			}))
-		}
+		if (multiselect) values = (wrapper.selected as unknown[]).slice()
 	})
 
-	// ─── Focus management ───────────────────────────────────────────
-
-	function focusByKey(el: HTMLElement, key: string) {
-		const target = el.querySelector(`[data-path="${key}"]`) as HTMLElement | null
-		if (target && target !== document.activeElement) {
-			target.focus()
-			target.scrollIntoView?.({ block: 'nearest', inline: 'nearest' })
-		}
-	}
-
+	// Mount Navigator on the table root
+	let tableRef = $state<HTMLElement | null>(null)
 	$effect(() => {
 		if (!tableRef) return
-		const el = tableRef
-
-		function onAction(event: Event) {
-			const detail = (event as CustomEvent).detail
-			if (detail.name === 'move') {
-				const key = controller.focusedKey
-				if (key) focusByKey(el, key)
-			}
-			if (detail.name === 'select') handleSelectAction()
-		}
-
-		el.addEventListener('action', onAction)
-		return () => el.removeEventListener('action', onAction)
+		const w = wrapper
+		const dir = getComputedStyle(tableRef).direction === 'rtl' ? 'rtl' : 'ltr'
+		const nav = new Navigator(tableRef, w, { orientation: 'vertical', dir })
+		return () => nav.destroy()
 	})
 
-	function handleFocusIn(event: FocusEvent) {
-		const target = event.target as HTMLElement
-		if (!target) return
-		const path = target.dataset.path
-		if (path !== undefined) {
-			controller.moveTo(path)
-		}
-	}
-
-	function handleSelectAction() {
-		if (selectable === false || disabled) return
-
-		const key = controller.focusedKey
-		if (!key) return
-
-		const proxy = controller.lookup.get(key)
-		if (!proxy) return
-
-		onselect?.(proxy.value, proxy.value as Record<string, unknown>)
-	}
-
-	// ─── Sort ───────────────────────────────────────────────────────
+	// ─── Sort + cell rendering helpers ──────────────────────────────
 
 	function handleSort(event: MouseEvent, column: TableColumn) {
 		if (column.sortable === false || disabled) return
-		controller.sortBy(column.name, event.shiftKey)
-		onsort?.(controller.sortState)
+		proxyTable.sortBy(column.name, event.shiftKey)
 	}
 
-	// ─── Cell rendering helpers ─────────────────────────────────────
-
 	function getCellValue(row: Record<string, unknown>, column: TableColumn): unknown {
 		const fieldName = column.fields?.text ?? column.name
 		return row[fieldName]
 	}
 
 	function formatCellValue(row: Record<string, unknown>, column: TableColumn): string {
-		const value = getCellValue(row, column)
-		if (column.formatter) return column.formatter(value, row)
-		return value !== null && value !== undefined ? String(value) : ''
+		const cellValue = getCellValue(row, column)
+		if (column.formatter) return column.formatter(cellValue, row)
+		return cellValue !== null && cellValue !== undefined ? String(cellValue) : ''
 	}
 
 	function getCellIcon(row: Record<string, unknown>, column: TableColumn): string | null {
@@ -151,8 +100,6 @@
 	data-disabled={disabled || undefined}
 	data-table-responsive={responsive || undefined}
 	class={className || undefined}
-	onfocusin={handleFocusIn}
-	use:navigator={{ wrapper: controller, orientation: 'vertical' }}
 >
 	<table role="grid" aria-label={caption} data-table-striped={striped || undefined}>
 		{#if caption}
@@ -161,10 +108,10 @@
 
 		<thead data-table-header>
 			{#if headerSnippet}
-				{@render headerSnippet(controller.columns, controller.sortState)}
+				{@render headerSnippet(proxyTable.columns, proxyTable.sortState)}
 			{:else}
 				<tr>
-					{#each controller.columns as column (column.name)}
+					{#each proxyTable.columns as column (column.name)}
 						<th
 							data-table-header-cell
 							data-column={column.name}
@@ -192,25 +139,27 @@
 		</thead>
 
 		<tbody data-table-body>
-			{#if controller.data.length === 0}
+			{#if wrapper.flatView.length === 0}
 				{#if emptySnippet}
 					<tr data-table-empty-row>
-						<td colspan={controller.columns.length}>
+						<td colspan={proxyTable.columns.length}>
 							{@render emptySnippet()}
 						</td>
 					</tr>
 				{:else}
 					<tr data-table-empty-row>
-						<td data-table-empty colspan={controller.columns.length}>{messages.table.empty}</td>
+						<td data-table-empty colspan={proxyTable.columns.length}
+							>{messages.table.empty}</td
+						>
 					</tr>
 				{/if}
 			{:else}
-				{#each controller.data as entry, rowIndex (entry.key)}
-					{@const row = entry.value as Record<string, unknown>}
-					{@const isSelected = controller.selectedKeys.has(entry.key)}
-					{@const isFocused = controller.focusedKey === entry.key}
+				{#each wrapper.flatView as entry, rowIndex (entry.key)}
+					{@const row = entry.proxy.value as Record<string, unknown>}
+					{@const isSelected = wrapper.selectedKeys.has(entry.key)}
+					{@const isFocused = wrapper.focusedKey === entry.key}
 					{#if rowSnippet}
-						{@render rowSnippet(row, controller.columns, rowIndex, isSelected)}
+						{@render rowSnippet(row, proxyTable.columns, rowIndex, isSelected)}
 					{:else}
 						<tr
 							data-table-row
@@ -221,7 +170,7 @@
 							aria-rowindex={rowIndex + 1}
 							tabindex={isFocused ? 0 : -1}
 						>
-							{#each controller.columns as column (column.name)}
+							{#each proxyTable.columns as column (column.name)}
 								{#if cellSnippet}
 									<td data-table-cell data-column={column.name} data-label={column.label ?? column.name} style:text-align={column.align}>
 										{@render cellSnippet(getCellValue(row, column), column, row)}

package/src/components/Toolbar.svelte

@@ -6,11 +6,8 @@
 		ToolbarItemHandlers
 	} from '../types/toolbar.js'
 	import { getSnippet } from '../types/menu.js'
-	import { ProxyItem, messages } from '@rokkit/states'
-	import { ListController } from '@rokkit/states'
-	import { SvelteMap } from 'svelte/reactivity'
-	import { navigator } from '@rokkit/actions'
-	import { untrack } from 'svelte'
+	import { ProxyItem, ProxyTree, Wrapper, messages } from '@rokkit/states'
+	import { Navigator } from '@rokkit/actions'
 
 	const {
 		items = [],
@@ -40,125 +37,53 @@
 		return new ProxyItem(item, userFields)
 	}
 
-	// ─── Controller + Navigator ────────────────────────────────────
-
-	/** Only interactive items are tracked by the controller */
-	function isInteractive(item: ToolbarItem): boolean {
-		const proxy = createProxy(item)
-		const type = proxy.type
-		return type !== 'separator' && type !== 'spacer'
-	}
-
-	const interactiveItems = $derived(items.filter(isInteractive))
-
-	/** Map from item → its data-path key (index within interactive items) */
-	const itemPathMap = $derived.by(() => {
-		const map = new SvelteMap<unknown, string>()
-		let idx = 0
-		for (const item of items) {
-			if (isInteractive(item)) {
-				map.set(item, String(idx))
-				idx++
-			}
-		}
-		return map
-	})
+	// ─── Wrapper + Navigator ────────────────────────────────────
 
 	const orientation = $derived<'horizontal' | 'vertical'>(
 		position === 'left' || position === 'right' ? 'vertical' : 'horizontal'
 	)
 
-	let controller = untrack(() => {
-		const c = new ListController(interactiveItems, undefined, userFields)
-		c.moveFirst()
-		return c
-	})
-	let containerRef: HTMLElement | null = $state(null)
-
-	$effect(() => {
-		controller.update(interactiveItems)
-	})
-
-	// Sync controller position when a toolbar item receives focus (e.g. Tab from outside)
-	$effect(() => {
-		if (!containerRef) return
-		const el = containerRef
-
-		function onFocusIn(event: Event) {
-			const target = event.target as HTMLElement
-			const path = target.closest('[data-path]')?.getAttribute('data-path')
-			if (path) {
-				controller.moveTo(path)
-			}
-		}
+	function handleItemClick(proxy: ProxyItem) {
+		if (proxy.disabled || disabled) return
+		onclick?.(proxy.value, proxy.original as ToolbarItem)
+	}
 
-		el.addEventListener('focusin', onFocusIn)
-		return () => el.removeEventListener('focusin', onFocusIn)
-	})
+	const proxyTree = $derived(new ProxyTree(items, userFields))
+	const wrapper = $derived(
+		new Wrapper(proxyTree, {
+			onselect: (_value: unknown, proxy: ProxyItem) => handleItemClick(proxy),
+			collapsible: false
+		})
+	)
 
-	function focusKeyedItem(el: HTMLElement, key: string) {
-		const target = el.querySelector(`[data-path="${key}"]`) as HTMLElement | null
-		if (target && target !== document.activeElement) target.focus()
-	}
+	let containerRef: HTMLElement | null = $state(null)
 
-	// Focus the item matching controller.focusedKey on navigator action events
+	// Mount Navigator on the root; destroy + re-mount when wrapper recreates.
 	$effect(() => {
 		if (!containerRef) return
-		const el = containerRef
-
-		function onAction(event: Event) {
-			const detail = (event as CustomEvent).detail
-			if (detail.name === 'move') {
-				const key = controller.focusedKey
-				if (key) focusKeyedItem(el, key)
-			}
-			if (detail.name === 'select') handleSelectAction()
-		}
-
-		el.addEventListener('action', onAction)
-		return () => el.removeEventListener('action', onAction)
+		const w = wrapper
+		const dir = getComputedStyle(containerRef).direction === 'rtl' ? 'rtl' : 'ltr'
+		const nav = new Navigator(containerRef, w, { orientation, dir })
+		// Park focus on the first interactive item so Tab into the toolbar lands there.
+		w.first(null)
+		return () => nav.destroy()
 	})
 
-	/**
-	 * Handle the navigator's select action (Enter/Space or click on data-path item)
-	 */
-	function handleSelectAction() {
-		const key = controller.focusedKey
-		if (!key) return
-		const proxy = controller.lookup.get(key)
-		if (!proxy) return
-		const itemProxy = createProxy(proxy.value)
-		handleItemClick(itemProxy)
-	}
-
-	/**
-	 * Get the data-path key for an item
-	 */
-	function getPathKey(item: ToolbarItem): string | undefined {
-		return itemPathMap.get(item)
-	}
-
 	// ─── Item Handlers ─────────────────────────────────────────────
 
-	function handleItemClick(proxy: ProxyItem) {
-		if (proxy.disabled || disabled) return
-		onclick?.(proxy.value, proxy.original as ToolbarItem)
-	}
-
-	function handleItemKeyDown(event: KeyboardEvent, proxy: ProxyItem) {
-		if (event.key === 'Enter' || event.key === ' ') {
-			event.preventDefault()
-			handleItemClick(proxy)
-		}
-	}
-
 	/**
-	 * Create handlers object for custom snippets
+	 * Handlers passed to custom snippets so they can wire click/keydown
+	 * back through the toolbar's onclick + disabled semantics.
 	 */
 	function createHandlers(proxy: ProxyItem): ToolbarItemHandlers {
 		return {
 			onclick: () => handleItemClick(proxy),
-			onkeydown: (event: KeyboardEvent) => handleItemKeyDown(event, proxy)
+			onkeydown: (event: KeyboardEvent) => {
+				if (event.key === 'Enter' || event.key === ' ') {
+					event.preventDefault()
+					handleItemClick(proxy)
+				}
+			}
 		}
 	}
 
@@ -224,11 +149,10 @@
 	<div data-toolbar-divider aria-hidden="true"></div>
 {/snippet}
 
-{#snippet renderItem(proxy: ProxyItem, item: ToolbarItem)}
+{#snippet renderItem(proxy: ProxyItem, pathKey: string)}
 	{@const customSnippet = resolveItemSnippet(proxy)}
 	{@const handlers = createHandlers(proxy)}
 	{@const itemType = proxy.type}
-	{@const pathKey = getPathKey(item)}
 
 	{#if itemType === 'separator'}
 		{@render separator()}
@@ -261,13 +185,12 @@
 	role="toolbar"
 	aria-label={label}
 	aria-disabled={disabled || undefined}
-	use:navigator={{ wrapper: controller, orientation }}
 >
 	{#if hasItems}
 		<!-- Data-driven items -->
 		{#each items as item, index (index)}
 			{@const proxy = createProxy(item)}
-			{@render renderItem(proxy, item)}
+			{@render renderItem(proxy, String(index))}
 		{/each}
 	{:else if hasSlots}
 		<!-- Slot-based content -->

package/src/components/TreeTable.svelte

@@ -0,0 +1,317 @@
+<script lang="ts">
+	/**
+	 * TreeTable — hierarchical rows in a sortable grid.
+	 *
+	 * Accepts nested rows (each row may carry a `children: []` array).
+	 * One designated "hierarchy" column owns the chevron + indent + tree
+	 * connectors; other columns render plain cell values.
+	 *
+	 * Architecture mirrors Table.svelte:
+	 *   ProxyTableTree → Wrapper → Navigator class
+	 *
+	 * The difference is in the data layer: ProxyTableTree's sort is
+	 * applied per-sibling group so the parent/child structure survives
+	 * any column sort.
+	 */
+
+	import type { TableColumn, TableSortIcons } from '../types/table.js'
+	import type { TreeTableColumn, TreeTableProps } from '../types/tree-table.js'
+	import { defaultTableSortIcons } from '../types/table.js'
+	import { ProxyItem, ProxyTableTree, Wrapper, messages } from '@rokkit/states'
+	import { Navigator } from '@rokkit/actions'
+	import { DEFAULT_STATE_ICONS } from '@rokkit/core'
+	import Connector from './Connector.svelte'
+
+	let {
+		data = [],
+		columns: userColumns,
+		value,
+		values = $bindable<unknown[]>([]),
+		selectable = 'single' as 'single' | 'multi' | false,
+		caption,
+		size = 'md',
+		striped = false,
+		disabled = false,
+		lineStyle = 'solid',
+		fields: userFields,
+		onselect,
+		onsort,
+		class: className = '',
+		icons: userIcons,
+		header: headerSnippet,
+		row: rowSnippet,
+		cell: cellSnippet,
+		empty: emptySnippet
+	}: TreeTableProps = $props()
+
+	const icons = $derived<TableSortIcons & { opened: string; closed: string }>({
+		...defaultTableSortIcons,
+		...DEFAULT_STATE_ICONS.node,
+		...userIcons
+	})
+
+	// ─── ProxyTableTree + Wrapper ───────────────────────────────────
+
+	const multiselect = $derived(selectable === 'multi')
+
+	const proxyTable = $derived(
+		new ProxyTableTree(data, { columns: userColumns, fields: userFields, onsort })
+	)
+
+	const wrapper = $derived(
+		new Wrapper(proxyTable, {
+			onselect: (_v: unknown, proxy: ProxyItem) => {
+				if (selectable === false || disabled) return
+				onselect?.(proxy.value, proxy.value as Record<string, unknown>)
+			},
+			collapsible: true,
+			multiselect
+		})
+	)
+
+	$effect(() => {
+		wrapper.moveToValue(value)
+	})
+	$effect(() => {
+		if (multiselect) values = (wrapper.selected as unknown[]).slice()
+	})
+
+	// ─── Hierarchy column resolution ────────────────────────────────
+
+	const hierarchyColumn = $derived(
+		proxyTable.columns.find((c: TreeTableColumn) => c.hierarchy) ?? proxyTable.columns[0]
+	)
+
+	function isHierarchyColumn(column: TreeTableColumn): boolean {
+		return hierarchyColumn?.name === column.name
+	}
+
+	// Mount Navigator on the table root
+	let tableRef = $state<HTMLElement | null>(null)
+	$effect(() => {
+		if (!tableRef) return
+		const w = wrapper
+		const dir = getComputedStyle(tableRef).direction === 'rtl' ? 'rtl' : 'ltr'
+		const nav = new Navigator(tableRef, w, { orientation: 'vertical', collapsible: true, dir })
+		return () => nav.destroy()
+	})
+
+	// ─── Sort + cell rendering helpers ──────────────────────────────
+
+	function handleSort(event: MouseEvent, column: TableColumn) {
+		if (column.sortable === false || disabled) return
+		proxyTable.sortBy(column.name, event.shiftKey)
+	}
+
+	function getCellValue(row: Record<string, unknown>, column: TableColumn): unknown {
+		const fieldName = column.fields?.text ?? column.name
+		return row[fieldName]
+	}
+
+	function formatCellValue(row: Record<string, unknown>, column: TableColumn): string {
+		const cellValue = getCellValue(row, column)
+		if (column.formatter) return column.formatter(cellValue, row)
+		return cellValue !== null && cellValue !== undefined ? String(cellValue) : ''
+	}
+
+	/**
+	 * The hierarchy cell shows the same column at every level. Group rows
+	 * synthesised by `nestByColumns` carry `__label` (the grouping value),
+	 * which we render in place of the column's normal field — that way the
+	 * tree column displays e.g. "EMEA", "France", "Paris" at each depth
+	 * even though the actual grouping column changes per level.
+	 *
+	 * Leaf rows (no `__label`) fall through to the column's regular value.
+	 */
+	function formatHierarchyValue(row: Record<string, unknown>, column: TableColumn): string {
+		if (row.__label !== undefined && row.__label !== null) return String(row.__label)
+		return formatCellValue(row, column)
+	}
+
+	function getCellIcon(row: Record<string, unknown>, column: TableColumn): string | null {
+		if (!column.fields?.icon) return null
+		const iconValue = row[column.fields.icon]
+		if (!iconValue) return null
+		if (column.iconFormatter) return column.iconFormatter(iconValue)
+		return String(iconValue)
+	}
+</script>
+
+<div
+	bind:this={tableRef}
+	data-table
+	data-tree-table
+	data-size={size}
+	data-selectable={selectable || undefined}
+	data-disabled={disabled || undefined}
+	data-line-style={lineStyle}
+	class={className || undefined}
+>
+	<!-- svelte-ignore a11y_no_noninteractive_element_to_interactive_role -->
+	<table role="treegrid" aria-label={caption} data-table-striped={striped || undefined}>
+		{#if caption}
+			<caption data-table-caption>{caption}</caption>
+		{/if}
+
+		<thead data-table-header>
+			{#if headerSnippet}
+				{@render headerSnippet(proxyTable.columns, proxyTable.sortState)}
+			{:else}
+				<tr>
+					{#each proxyTable.columns as column (column.name)}
+						<th
+							data-table-header-cell
+							data-column={column.name}
+							data-sortable={column.sortable !== false || undefined}
+							data-sort-order={column.sorted ?? 'none'}
+							data-hierarchy={isHierarchyColumn(column) || undefined}
+							scope="col"
+							aria-sort={column.sorted === 'ascending'
+								? 'ascending'
+								: column.sorted === 'descending'
+									? 'descending'
+									: 'none'}
+							style:width={column.width}
+							style:text-align={column.align}
+							onclick={(e) => handleSort(e, column)}
+						>
+							<span data-table-header-text>{column.label ?? column.name}</span>
+							{#if column.sortable !== false}
+								{@const sortIcon = icons[column.sorted ?? 'none'] ?? icons.none}
+								<span data-table-sort-icon class={sortIcon} aria-hidden="true"></span>
+							{/if}
+						</th>
+					{/each}
+				</tr>
+			{/if}
+		</thead>
+
+		<tbody data-table-body>
+			{#if wrapper.flatView.length === 0}
+				{#if emptySnippet}
+					<tr data-table-empty-row>
+						<td colspan={proxyTable.columns.length}>
+							{@render emptySnippet()}
+						</td>
+					</tr>
+				{:else}
+					<tr data-table-empty-row>
+						<td data-table-empty colspan={proxyTable.columns.length}
+							>{messages.table.empty}</td
+						>
+					</tr>
+				{/if}
+			{:else}
+				{#each wrapper.flatView as entry, rowIndex (entry.key)}
+					{@const proxy = entry.proxy}
+					{@const row = proxy.value as Record<string, unknown>}
+					{@const isSelected = wrapper.selectedKeys.has(entry.key)}
+					{@const isFocused = wrapper.focusedKey === entry.key}
+					{@const isGroup = row.__group === true}
+					{#if rowSnippet}
+						{@render rowSnippet(row, proxyTable.columns, rowIndex, isSelected)}
+					{:else}
+						<tr
+							data-table-row
+							data-tree-table-row
+							data-path={entry.key}
+							data-tree-level={entry.level - 1}
+							data-tree-has-children={entry.isExpandable || undefined}
+							data-selected={isSelected || undefined}
+							data-focused={isFocused || undefined}
+							data-group={isGroup || undefined}
+							aria-selected={isSelected}
+							aria-rowindex={rowIndex + 1}
+							aria-level={entry.level}
+							aria-expanded={entry.isExpandable ? proxy.expanded : undefined}
+							tabindex={isFocused ? 0 : -1}
+						>
+							{#each proxyTable.columns as column (column.name)}
+								{@const hierarchy = isHierarchyColumn(column)}
+								{#if cellSnippet}
+									<td
+										data-table-cell
+										data-column={column.name}
+										data-label={column.label ?? column.name}
+										data-hierarchy={hierarchy || undefined}
+										style:text-align={column.align}
+									>
+										{#if hierarchy}
+											<span data-tree-table-cell-prefix>
+												{#each entry.lineTypes as lineType, lineIndex (lineIndex)}
+													{#if lineType === 'icon'}
+														<button
+															type="button"
+															data-tree-table-toggle
+															data-accordion-trigger
+															aria-label={proxy.expanded ? 'Collapse' : 'Expand'}
+															tabindex={-1}
+														>
+															<span
+																class={proxy.expanded ? icons.opened : icons.closed}
+																aria-hidden="true"
+															></span>
+														</button>
+													{:else}
+														<Connector type={lineType} />
+													{/if}
+												{/each}
+												{#if !entry.isExpandable}
+													<span data-tree-table-empty aria-hidden="true"></span>
+												{/if}
+											</span>
+										{/if}
+										{@render cellSnippet(getCellValue(row, column), column, row)}
+									</td>
+								{:else}
+									{@const cellIcon = getCellIcon(row, column)}
+									<td
+										data-table-cell
+										data-column={column.name}
+										data-label={column.label ?? column.name}
+										data-hierarchy={hierarchy || undefined}
+										style:text-align={column.align}
+									>
+										{#if hierarchy}
+											<span data-tree-table-cell-prefix>
+												{#each entry.lineTypes as lineType, lineIndex (lineIndex)}
+													{#if lineType === 'icon'}
+														<button
+															type="button"
+															data-tree-table-toggle
+															data-accordion-trigger
+															aria-label={proxy.expanded ? 'Collapse' : 'Expand'}
+															tabindex={-1}
+														>
+															<span
+																class={proxy.expanded ? icons.opened : icons.closed}
+																aria-hidden="true"
+															></span>
+														</button>
+													{:else}
+														<Connector type={lineType} />
+													{/if}
+												{/each}
+												{#if !entry.isExpandable}
+													<span data-tree-table-empty aria-hidden="true"></span>
+												{/if}
+											</span>
+										{/if}
+										{#if cellIcon}
+											<span data-cell-icon class={cellIcon} aria-hidden="true"></span>
+										{/if}
+										<span data-cell-value
+											>{hierarchy
+												? formatHierarchyValue(row, column)
+												: formatCellValue(row, column)}</span
+										>
+									</td>
+								{/if}
+							{/each}
+						</tr>
+					{/if}
+				{/each}
+			{/if}
+		</tbody>
+	</table>
+</div>

package/src/components/index.ts

@@ -32,6 +32,7 @@ export { default as Rating } from './Rating.svelte'
 export { default as Stepper } from './Stepper.svelte'
 export { default as Switch } from './Switch.svelte'
 export { default as Table } from './Table.svelte'
+export { default as TreeTable } from './TreeTable.svelte'
 export { default as SearchFilter } from './SearchFilter.svelte'
 export { default as Range } from './Range.svelte'
 export { default as Timeline } from './Timeline.svelte'

package/src/index.ts

@@ -34,6 +34,7 @@ export {
 	Stepper,
 	Switch,
 	Table,
+	TreeTable,
 	SearchFilter,
 	Range,
 	Timeline,

package/src/types/index.ts

@@ -36,6 +36,7 @@ export * from './palette.js'
 
 // Table Types
 export * from './table.js'
+export * from './tree-table.js'
 
 // SearchFilter Types
 export * from './search-filter.js'

package/src/types/tree-table.ts

@@ -0,0 +1,103 @@
+/**
+ * TreeTable Component Types
+ *
+ * Hierarchical analog of Table — accepts nested rows (each row may
+ * carry a `children: []` array) and renders the hierarchy in one
+ * designated column with chevron + indent + tree connectors.
+ *
+ * Reuses the column / sort / cell types from Table.
+ */
+
+import type { Snippet } from 'svelte'
+import type { TableColumn, TableSortIcons, SortState, TableFields } from './table.js'
+
+// =============================================================================
+// Column extension
+// =============================================================================
+
+/**
+ * Column definition for TreeTable — adds an optional `hierarchy` flag
+ * to mark which column renders the chevron + indent connectors. When
+ * no column is flagged, the first column is treated as the hierarchy
+ * column by default.
+ */
+export interface TreeTableColumn extends TableColumn {
+	/** Render chevron + tree connectors in this column. Defaults to the first column. */
+	hierarchy?: boolean
+}
+
+// =============================================================================
+// Snippets
+// =============================================================================
+
+export type TreeTableHeaderSnippet = Snippet<[TreeTableColumn[], SortState[]]>
+export type TreeTableRowSnippet = Snippet<
+	[Record<string, unknown>, TreeTableColumn[], number, boolean]
+>
+export type TreeTableCellSnippet = Snippet<
+	[unknown, TreeTableColumn, Record<string, unknown>]
+>
+export type TreeTableEmptySnippet = Snippet<[]>
+
+// =============================================================================
+// Component Props
+// =============================================================================
+
+export interface TreeTableProps {
+	/** Nested row data — each row may carry a `children: []` array. */
+	data?: Record<string, unknown>[]
+
+	/** Column definitions (auto-derived from the first row if not provided). */
+	columns?: TreeTableColumn[]
+
+	/** 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
+
+	/** Whether the entire table is disabled */
+	disabled?: boolean
+
+	/** Tree connector line style — same options as the Tree component */
+	lineStyle?: 'none' | 'solid' | 'dashed' | 'dotted'
+
+	/** Row-level field mapping (incl. the `children` field name). */
+	fields?: TableFields & { children?: string }
+
+	/** 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 & { opened?: string; closed?: string }
+
+	/** Custom header snippet */
+	header?: TreeTableHeaderSnippet
+
+	/** Custom row snippet */
+	row?: TreeTableRowSnippet
+
+	/** Custom cell snippet */
+	cell?: TreeTableCellSnippet
+
+	/** Empty state snippet */
+	empty?: TreeTableEmptySnippet
+}

package/src/types/tree.ts

@@ -24,7 +24,13 @@ import { DEFAULT_STATE_ICONS } from '@rokkit/core'
  * Downstream code that needs string field names without null-guards
  * should use `ResolvedTreeFields` rather than `TreeFields`.
  */
-export interface TreeFields extends Record<string, string> {
+export interface TreeFields {
+	// Index signature must allow `undefined` so the optional keys below
+	// (typed as `string | undefined`) are assignable. Extending
+	// `Record<string, string>` here would conflict with the optionals
+	// and produce TS2411 in any strict downstream consumer.
+	[field: string]: string | undefined
+
 	/**
 	 * Name of the field on each tree item that holds its expanded state.
 	 * The value at that field is expected to be a `boolean`.
@@ -64,7 +70,11 @@ export type ResolvedTreeFields = Required<TreeFields>
  * builders.
  */
 export function resolveTreeFields(fields: TreeFields = {}): ResolvedTreeFields {
-	return { ...defaultTreeFields, ...fields }
+	// `Required<TreeFields>` cannot strip `undefined` from the index
+	// signature on its own, so spread-inference fails the contract even
+	// though `defaultTreeFields` provides every key. Cast through unknown
+	// to assert the post-merge shape.
+	return { ...defaultTreeFields, ...fields } as unknown as ResolvedTreeFields
 }
 
 /**