@human-kit/svelte-components 1.0.0-alpha.2 → 1.0.0-alpha.20

package/dist/table/root/table-test.svelte

@@ -0,0 +1,206 @@
+<script lang="ts">
+	import { Table } from '../index';
+	import type {
+		TableDisabledBehavior,
+		TableSelectionBehavior,
+		TableSelectionKey,
+		TableSelectionMode,
+		TableSortDescriptor
+	} from './context';
+
+	type DemoRow = {
+		id: string;
+		email: string;
+		group: string;
+	};
+
+	const defaultRows: DemoRow[] = [
+		{ id: 'danilo', email: 'danilo@example.com', group: 'Developer' },
+		{ id: 'zahra', email: 'zahra@example.com', group: 'Admin' },
+		{ id: 'jasper', email: 'jasper@example.com', group: 'Developer' }
+	];
+
+	type TableTestProps = {
+		rows?: DemoRow[];
+		ariaLabel?: string;
+		ariaLabelledby?: string;
+		selectionMode?: TableSelectionMode;
+		selectionBehavior?: TableSelectionBehavior;
+		disabledBehavior?: TableDisabledBehavior;
+		disallowEmptySelection?: boolean;
+		hiddenColumns?: string[];
+		defaultHiddenColumns?: string[];
+		disabledKeys?: Iterable<TableSelectionKey>;
+		initialSelectedKeys?: Iterable<TableSelectionKey>;
+		initialSortDescriptor?: TableSortDescriptor;
+		onRowAction?: (id: TableSelectionKey) => void;
+		onSelectionChange?: (keys: Set<TableSelectionKey>) => void;
+		showSelectionModeToggle?: boolean;
+		showSingleSelectionModeToggle?: boolean;
+		showSortClearButton?: boolean;
+		showHiddenColumnsToggle?: boolean;
+	};
+
+	let {
+		rows = defaultRows,
+		ariaLabel = 'Users table',
+		ariaLabelledby,
+		selectionMode = $bindable<TableSelectionMode>('multiple'),
+		selectionBehavior = 'toggle',
+		disabledBehavior = 'all',
+		disallowEmptySelection = false,
+		hiddenColumns = $bindable<string[] | undefined>(),
+		defaultHiddenColumns,
+		disabledKeys,
+		initialSelectedKeys,
+		initialSortDescriptor,
+		onRowAction,
+		onSelectionChange,
+		showSelectionModeToggle = false,
+		showSingleSelectionModeToggle = false,
+		showSortClearButton = false,
+		showHiddenColumnsToggle = false
+	}: TableTestProps = $props();
+
+	let currentSelectedKeys = $state<Set<TableSelectionKey>>(
+		new Set((() => initialSelectedKeys ?? [])())
+	);
+	let currentSortDescriptor = $state<TableSortDescriptor | undefined>(
+		(() => initialSortDescriptor)()
+	);
+	let rowActionLog = $state<string[]>([]);
+	let eventLog = $state<string[]>([]);
+
+	const renderedRows = $derived.by(() => {
+		const nextRows = [...rows];
+		const descriptor = currentSortDescriptor;
+		if (!descriptor) return nextRows;
+		const direction = descriptor.direction === 'ascending' ? 1 : -1;
+		return nextRows.sort((a, b) => {
+			const left = a[descriptor.column as keyof DemoRow];
+			const right = b[descriptor.column as keyof DemoRow];
+			return String(left).localeCompare(String(right)) * direction;
+		});
+	});
+
+	function handleSelectionChange(keys: Set<TableSelectionKey>) {
+		currentSelectedKeys = new Set(keys);
+		eventLog = [...eventLog, `selection:${JSON.stringify([...keys])}`];
+		onSelectionChange?.(new Set(keys));
+	}
+
+	function handleRowAction(id: TableSelectionKey) {
+		rowActionLog = [...rowActionLog, String(id)];
+		eventLog = [...eventLog, `action:${String(id)}`];
+		onRowAction?.(id);
+	}
+</script>
+
+<Table.Root
+	aria-label={ariaLabel}
+	aria-labelledby={ariaLabelledby}
+	{selectionMode}
+	{selectionBehavior}
+	{disabledBehavior}
+	{disallowEmptySelection}
+	bind:hiddenColumns
+	{defaultHiddenColumns}
+	bind:selectedKeys={currentSelectedKeys}
+	bind:sortDescriptor={currentSortDescriptor}
+	{disabledKeys}
+	onRowAction={handleRowAction}
+	onSelectionChange={handleSelectionChange}
+	class="table-root"
+>
+	<Table.Header>
+		<Table.Row>
+			<Table.Column id="email" isRowHeader textValue="Email">
+				<Table.ColumnHeaderCell>Email</Table.ColumnHeaderCell>
+			</Table.Column>
+			<Table.Column id="group" textValue="Group">
+				<Table.ColumnHeaderCell>
+					<Table.SortTrigger>
+						{#snippet children({ sortDirection })}
+							<button
+								type="button"
+								data-testid="group-sort-trigger"
+								data-sort-direction-state={sortDirection ?? 'none'}
+							>
+								Group
+							</button>
+						{/snippet}
+					</Table.SortTrigger>
+				</Table.ColumnHeaderCell>
+			</Table.Column>
+		</Table.Row>
+	</Table.Header>
+
+	<Table.Body>
+		{#each renderedRows as row (row.id)}
+			<Table.Row
+				id={row.id}
+				isDisabled={disabledKeys ? Array.from(disabledKeys).includes(row.id) : false}
+			>
+				<Table.Cell>{row.email}</Table.Cell>
+				<Table.Cell>{row.group}</Table.Cell>
+			</Table.Row>
+		{/each}
+		<Table.EmptyState>No users found.</Table.EmptyState>
+	</Table.Body>
+
+	<Table.Footer>
+		<Table.Row>
+			<Table.Cell>Total</Table.Cell>
+			<Table.Cell>{renderedRows.length} users</Table.Cell>
+		</Table.Row>
+	</Table.Footer>
+</Table.Root>
+
+{#if showSelectionModeToggle}
+	<button
+		type="button"
+		data-testid="set-selection-mode-none"
+		onclick={() => (selectionMode = 'none')}
+	>
+		Selection none
+	</button>
+{/if}
+
+{#if showSingleSelectionModeToggle}
+	<button
+		type="button"
+		data-testid="set-selection-mode-single"
+		onclick={() => (selectionMode = 'single')}
+	>
+		Selection single
+	</button>
+{/if}
+
+{#if showSortClearButton}
+	<button
+		type="button"
+		data-testid="clear-sort"
+		onclick={() => (currentSortDescriptor = undefined)}
+	>
+		Clear sort
+	</button>
+{/if}
+
+{#if showHiddenColumnsToggle}
+	<button type="button" data-testid="hide-group-column" onclick={() => (hiddenColumns = ['group'])}>
+		Hide group
+	</button>
+	<button type="button" data-testid="show-all-columns" onclick={() => (hiddenColumns = [])}>
+		Show all
+	</button>
+{/if}
+
+<output data-testid="selected-keys">{JSON.stringify([...currentSelectedKeys])}</output>
+<output data-testid="row-action-log">{JSON.stringify(rowActionLog)}</output>
+<output data-testid="event-log">{JSON.stringify(eventLog)}</output>
+<output data-testid="sort-descriptor"
+	>{currentSortDescriptor
+		? `${currentSortDescriptor.column}:${currentSortDescriptor.direction}`
+		: ''}</output
+>
+<output data-testid="hidden-columns">{JSON.stringify(hiddenColumns ?? [])}</output>

package/dist/table/root/table-test.svelte.d.ts

@@ -0,0 +1,29 @@
+import type { TableDisabledBehavior, TableSelectionBehavior, TableSelectionKey, TableSelectionMode, TableSortDescriptor } from './context';
+type DemoRow = {
+    id: string;
+    email: string;
+    group: string;
+};
+type TableTestProps = {
+    rows?: DemoRow[];
+    ariaLabel?: string;
+    ariaLabelledby?: string;
+    selectionMode?: TableSelectionMode;
+    selectionBehavior?: TableSelectionBehavior;
+    disabledBehavior?: TableDisabledBehavior;
+    disallowEmptySelection?: boolean;
+    hiddenColumns?: string[];
+    defaultHiddenColumns?: string[];
+    disabledKeys?: Iterable<TableSelectionKey>;
+    initialSelectedKeys?: Iterable<TableSelectionKey>;
+    initialSortDescriptor?: TableSortDescriptor;
+    onRowAction?: (id: TableSelectionKey) => void;
+    onSelectionChange?: (keys: Set<TableSelectionKey>) => void;
+    showSelectionModeToggle?: boolean;
+    showSingleSelectionModeToggle?: boolean;
+    showSortClearButton?: boolean;
+    showHiddenColumnsToggle?: boolean;
+};
+declare const TableTest: import("svelte").Component<TableTestProps, {}, "selectionMode" | "hiddenColumns">;
+type TableTest = ReturnType<typeof TableTest>;
+export default TableTest;

package/dist/table/row/README.md

@@ -0,0 +1,29 @@
+<!-- markdownlint-disable MD024 -->
+
+# Table.Row
+
+## API reference
+
+### Table.Row
+
+Name: `Table.Row`
+Description: Semantic table row part used in the header, body, or footer. In body scope it reflects row focus, selection, and disabled state.
+
+Public prop type: `TableRowProps`
+
+| Prop         | Type               | Default     | Description                                                     |
+| ------------ | ------------------ | ----------- | --------------------------------------------------------------- |
+| `id`         | `string \| number` | `undefined` | Stable row identifier used for selection state in `Table.Body`. |
+| `isDisabled` | `boolean`          | `false`     | Marks a body row as non-selectable.                             |
+| `textValue`  | `string`           | `undefined` | Reserved for future text-based navigation features.             |
+| `class`      | `string`           | `''`        | Class names for the `tr` element.                               |
+| `children`   | `Snippet`          | `undefined` | Row cells.                                                      |
+
+### Context utilities
+
+Name: `Table.Row` row context
+Description: Publishes row registration and cell-order helpers to descendant cells.
+
+| Prop                 | Type                    | Default | Description                                          |
+| -------------------- | ----------------------- | ------- | ---------------------------------------------------- |
+| `useTableRowContext` | `() => TableRowContext` | `-`     | Reads the current row token and cell-order contract. |

package/dist/table/row/table-row.svelte

@@ -0,0 +1,244 @@
+<script lang="ts">
+	import { onDestroy } from 'svelte';
+	import { writable } from 'svelte/store';
+	import { setTableRowContext, useTableContext, useTableSectionContext } from '../root/context';
+	import type { TableRowProps } from '../types.js';
+	import {
+		shouldShowFocusVisible,
+		trackInteractionModality
+	} from '../../primitives/input-modality';
+	import { handleTableBodyKeydown } from '../utils/handle-body-keydown';
+
+	let {
+		id,
+		isDisabled = false,
+		children,
+		class: className = '',
+		...restProps
+	}: TableRowProps = $props();
+
+	const table = useTableContext();
+	const section = useTableSectionContext();
+	const rowToken = table.createInstanceToken('row');
+	const cellOrder: string[] = [];
+	const cellElements: Record<string, () => HTMLElement | undefined> = {};
+	const cellOrderVersion = writable(0);
+
+	let rowElement = $state<HTMLTableRowElement | undefined>(undefined);
+
+	function notifyCellOrderChange() {
+		cellOrderVersion.update((value) => value + 1);
+	}
+
+	function registerCellToken(token: string, getElement?: () => HTMLElement | undefined) {
+		if (!cellOrder.includes(token)) {
+			cellOrder.push(token);
+			notifyCellOrderChange();
+		}
+		if (getElement) {
+			cellElements[token] = getElement;
+		}
+	}
+
+	function unregisterCellToken(token: string) {
+		delete cellElements[token];
+		const index = cellOrder.indexOf(token);
+		if (index >= 0) {
+			cellOrder.splice(index, 1);
+			notifyCellOrderChange();
+		}
+	}
+
+	function getCellIndex(token: string) {
+		const element = cellElements[token]?.();
+		if (rowElement && element) {
+			const index = Array.from(rowElement.children).indexOf(element);
+			if (index >= 0) return index;
+		}
+		return cellOrder.indexOf(token);
+	}
+
+	setTableRowContext({
+		rowToken,
+		section: section.section,
+		get rowId() {
+			return id;
+		},
+		get isDisabled() {
+			return isDisabled;
+		},
+		cellOrderVersion,
+		registerCellToken,
+		unregisterCellToken,
+		getCellIndex
+	});
+
+	function syncRowRegistration() {
+		table.registerRow({
+			token: rowToken,
+			section: section.section,
+			id,
+			disabled: isDisabled,
+			element: rowElement
+		});
+	}
+
+	syncRowRegistration();
+
+	$effect(() => {
+		syncRowRegistration();
+	});
+
+	$effect(() => {
+		if (!rowElement) {
+			return;
+		}
+
+		const observer = new MutationObserver(() => {
+			scheduleCellOrderNotify();
+		});
+		observer.observe(rowElement, { childList: true });
+
+		return () => {
+			observer.disconnect();
+		};
+	});
+
+	let pendingCellOrderNotify = false;
+
+	function scheduleCellOrderNotify() {
+		if (!pendingCellOrderNotify) {
+			pendingCellOrderNotify = true;
+			queueMicrotask(() => {
+				pendingCellOrderNotify = false;
+				notifyCellOrderChange();
+			});
+		}
+	}
+
+	onDestroy(() => {
+		table.unregisterRow(rowToken);
+	});
+
+	const selectionVersion = table.selectionVersion;
+	const focusVersion = table.focusVersion;
+	const isSelected = $derived.by(() => {
+		void $selectionVersion;
+		return section.section === 'body' ? table.isRowSelected(id) : false;
+	});
+	const isFocusWithin = $derived.by(() => {
+		void $focusVersion;
+		return section.section === 'body' ? table.isRowFocused(rowToken) : false;
+	});
+	const isFocused = $derived.by(() => {
+		void $focusVersion;
+		return section.section === 'body' ? table.isRowFocusTarget(rowToken) : false;
+	});
+	const isFocusVisible = $derived.by(() => {
+		void $focusVersion;
+		return section.section === 'body' ? isFocused && table.focusVisible : false;
+	});
+	const isFocusVisibleWithin = $derived.by(() => {
+		void $focusVersion;
+		return section.section === 'body' ? isFocusWithin && table.focusVisible : false;
+	});
+	const isAriaDisabled = $derived.by(() => {
+		void $selectionVersion;
+		return section.section === 'body' ? table.isRowDisabled(id, isDisabled) : isDisabled;
+	});
+	const isSelectionDisabled = $derived.by(() => {
+		void $selectionVersion;
+		return section.section === 'body' ? table.isRowSelectionDisabled(id, isDisabled) : isDisabled;
+	});
+	const isActionable = $derived.by(() => {
+		void $selectionVersion;
+		return section.section === 'body' ? table.isRowActionable(id, isDisabled) : false;
+	});
+
+	function handleFocus() {
+		if (section.section !== 'body') return;
+		if (isAriaDisabled) return;
+		if (!table.isRowTabStop(rowToken)) return;
+		table.setFocusedRow(rowToken, table.getRowFocusEdge(rowToken) ?? 'start');
+		table.setFocusVisible(shouldShowFocusVisible(rowElement ?? null));
+	}
+
+	function handleMouseDown(event: MouseEvent) {
+		trackInteractionModality(event, rowElement ?? null);
+		table.setFocusVisible(false);
+	}
+
+	function handleKeyDown(event: KeyboardEvent) {
+		if (section.section !== 'body') return;
+		if (event.target !== rowElement) return;
+		handleTableBodyKeydown({
+			event,
+			table,
+			focusTarget: rowElement,
+			isDisabled: isAriaDisabled,
+			onHome: () => table.moveToBodyRowStart(),
+			onEnd: () => table.moveToBodyRowEnd(),
+			onEnter: () =>
+				table.pressRow(
+					id,
+					'keyboard-enter',
+					{
+						shiftKey: event.shiftKey,
+						ctrlKey: event.ctrlKey,
+						metaKey: event.metaKey,
+						altKey: event.altKey
+					},
+					isDisabled
+				),
+			onSpace: () =>
+				table.pressRow(
+					id,
+					'keyboard-space',
+					{
+						shiftKey: event.shiftKey,
+						ctrlKey: event.ctrlKey,
+						metaKey: event.metaKey,
+						altKey: event.altKey
+					},
+					isDisabled
+				)
+		});
+	}
+</script>
+
+<tr
+	bind:this={rowElement}
+	class={className}
+	tabindex={section.section === 'body'
+		? !isAriaDisabled
+			? table.isRowTabStop(rowToken)
+				? 0
+				: -1
+			: undefined
+		: undefined}
+	data-focused={isFocused ? 'true' : undefined}
+	data-focus-visible={isFocusVisible ? 'true' : undefined}
+	data-focus-within={isFocusWithin ? 'true' : undefined}
+	data-focus-visible-within={isFocusVisibleWithin ? 'true' : undefined}
+	data-actionable={isActionable ? 'true' : undefined}
+	data-selected={isSelected ? 'true' : undefined}
+	data-selection-disabled={section.section === 'body' &&
+	table.selectionMode !== 'none' &&
+	!isAriaDisabled &&
+	isSelectionDisabled
+		? 'true'
+		: undefined}
+	data-disabled={isAriaDisabled || undefined}
+	aria-selected={section.section === 'body' && table.selectionMode !== 'none'
+		? isSelected
+		: undefined}
+	aria-disabled={section.section === 'body' && isAriaDisabled ? true : undefined}
+	onfocus={handleFocus}
+	onmousedown={handleMouseDown}
+	onkeydown={handleKeyDown}
+	{...restProps}
+>
+	{#if children}
+		{@render children()}
+	{/if}
+</tr>

package/dist/table/row/table-row.svelte.d.ts

@@ -0,0 +1,4 @@
+import type { TableRowProps } from '../types.js';
+declare const TableRow: import("svelte").Component<TableRowProps, {}, "">;
+type TableRow = ReturnType<typeof TableRow>;
+export default TableRow;

package/dist/table/sort-trigger/README.md

@@ -0,0 +1,45 @@
+<!-- markdownlint-disable MD024 -->
+
+# Table.SortTrigger
+
+## API reference
+
+### Table.SortTrigger
+
+Name: `Table.SortTrigger`
+Description: Headless wrapper that makes the owning `Table.Column` sortable. It must be composed inside `Table.ColumnHeaderCell` and contain a `button` or `[role="button"]` child that acts as the actual trigger element.
+
+Public prop type: `TableSortTriggerProps`
+
+| Prop       | Type                                                | Default     | Description                                                                                                                |
+| ---------- | --------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `children` | `Snippet<[TableSortTriggerRenderState]> \| Snippet` | `undefined` | Child content that includes the actual trigger button or role=button UI. The snippet receives the current `sortDirection`. |
+
+## Usage notes
+
+- `Table.SortTrigger` must be used inside `Table.ColumnHeaderCell`.
+- Rendering `Table.SortTrigger` inside `Table.ColumnHeaderCell` is enough to make the owning `Table.Column` sortable.
+- The trigger resolves the active column from `Table.Column` context. It does not accept a separate `columnId` prop.
+- The wrapper finds the first nested `button` or `[role="button"]` and wires sorting behavior plus sort-state data attributes onto that element.
+- `children` can read the current `sortDirection` render state to adjust accessible labels or icons without reaching into `Table.Root.sortDescriptor`.
+- The header cell remains the roving-focus target for arrow-key grid navigation; use `Tab` to move into the nested trigger button.
+- Use separate controls for secondary header actions such as filter popovers or menus.
+
+```svelte
+<Table.Column id="group" textValue="Group">
+	<Table.ColumnHeaderCell>
+		<Table.SortTrigger>
+			{#snippet children({ sortDirection })}
+				<button
+					type="button"
+					class="inline-flex items-center gap-2 rounded-sm"
+					aria-label={`Group sort button. ${sortDirection ?? 'not sorted'}.`}
+				>
+					<span>Sort group</span>
+					<SortIcon data-direction={sortDirection} />
+				</button>
+			{/snippet}
+		</Table.SortTrigger>
+	</Table.ColumnHeaderCell>
+</Table.Column>
+```