@human-kit/svelte-components 1.0.0-alpha.4 → 1.0.0-alpha.5

package/dist/table/footer/README.md

@@ -0,0 +1,24 @@
+<!-- markdownlint-disable MD024 -->
+
+# Table.Footer
+
+## API reference
+
+### Table.Footer
+
+Name: `Table.Footer`
+Description: Footer rowgroup for summary rows or aggregate information. In v1 it is semantic only and excluded from keyboard navigation.
+
+| Prop       | Type      | Default     | Description                          |
+| ---------- | --------- | ----------- | ------------------------------------ |
+| `class`    | `string`  | `''`        | Class names for the `tfoot` element. |
+| `children` | `Snippet` | `undefined` | Footer rows.                         |
+
+### Context utilities
+
+Name: `Table.Footer` section context
+Description: Publishes the `footer` section scope for descendant rows and cells.
+
+| Prop                     | Type                        | Default | Description                      |
+| ------------------------ | --------------------------- | ------- | -------------------------------- |
+| `useTableSectionContext` | `() => TableSectionContext` | `-`     | Reads the current section scope. |

package/dist/table/footer/table-footer.svelte

@@ -0,0 +1,19 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+	import type { HTMLAttributes } from 'svelte/elements';
+	import { setTableSectionContext } from '../root/context';
+
+	type TableFooterProps = Omit<HTMLAttributes<HTMLTableSectionElement>, 'children'> & {
+		children?: Snippet;
+		class?: string;
+	};
+
+	let { children, class: className = '', ...restProps }: TableFooterProps = $props();
+	setTableSectionContext({ section: 'footer' });
+</script>
+
+<tfoot role="none" class={className} data-table-footer {...restProps}>
+	{#if children}
+		{@render children()}
+	{/if}
+</tfoot>

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

@@ -0,0 +1,9 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+type TableFooterProps = Omit<HTMLAttributes<HTMLTableSectionElement>, 'children'> & {
+    children?: Snippet;
+    class?: string;
+};
+declare const TableFooter: import("svelte").Component<TableFooterProps, {}, "">;
+type TableFooter = ReturnType<typeof TableFooter>;
+export default TableFooter;

package/dist/table/header/README.md

@@ -0,0 +1,24 @@
+<!-- markdownlint-disable MD024 -->
+
+# Table.Header
+
+## API reference
+
+### Table.Header
+
+Name: `Table.Header`
+Description: Header rowgroup for a `Table`, typically containing a single row of sortable or static column headers.
+
+| Prop       | Type      | Default     | Description                          |
+| ---------- | --------- | ----------- | ------------------------------------ |
+| `class`    | `string`  | `''`        | Class names for the `thead` element. |
+| `children` | `Snippet` | `undefined` | Header rows and columns.             |
+
+### Context utilities
+
+Name: `Table.Header` section context
+Description: Publishes the `header` section scope for descendant rows and cells.
+
+| Prop                     | Type                        | Default | Description                      |
+| ------------------------ | --------------------------- | ------- | -------------------------------- |
+| `useTableSectionContext` | `() => TableSectionContext` | `-`     | Reads the current section scope. |

package/dist/table/header/table-header.svelte

@@ -0,0 +1,19 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+	import type { HTMLAttributes } from 'svelte/elements';
+	import { setTableSectionContext } from '../root/context';
+
+	type TableHeaderProps = Omit<HTMLAttributes<HTMLTableSectionElement>, 'children'> & {
+		children?: Snippet;
+		class?: string;
+	};
+
+	let { children, class: className = '', ...restProps }: TableHeaderProps = $props();
+	setTableSectionContext({ section: 'header' });
+</script>
+
+<thead class={className} data-table-header {...restProps}>
+	{#if children}
+		{@render children()}
+	{/if}
+</thead>

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

@@ -0,0 +1,9 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+type TableHeaderProps = Omit<HTMLAttributes<HTMLTableSectionElement>, 'children'> & {
+    children?: Snippet;
+    class?: string;
+};
+declare const TableHeader: import("svelte").Component<TableHeaderProps, {}, "">;
+type TableHeader = ReturnType<typeof TableHeader>;
+export default TableHeader;

package/dist/table/index.d.ts

@@ -0,0 +1,16 @@
+export * as Table from './index.parts.ts';
+export { default as TableRoot } from './root/table-root.svelte';
+export { default as TableColumn } from './column/table-column.svelte';
+export { default as TableHeader } from './header/table-header.svelte';
+export { default as TableBody } from './body/table-body.svelte';
+export { default as TableEmptyState } from './empty-state/table-empty-state.svelte';
+export { default as TableFooter } from './footer/table-footer.svelte';
+export { default as TableRow } from './row/table-row.svelte';
+export { default as TableColumnHeaderCell } from './column-header-cell/table-column-header-cell.svelte';
+export { default as TableColumnResizer } from './column-resizer/table-column-resizer.svelte';
+export { default as TableCheckbox } from './checkbox/table-checkbox.svelte';
+export { default as TableCheckboxIndicator } from './checkbox-indicator/table-checkbox-indicator.svelte';
+export { default as TableCell } from './cell/table-cell.svelte';
+export { createTableContext, getTableContext, setTableContext, useTableContext, getTableSectionContext, setTableSectionContext, useTableSectionContext, getTableRowContext, setTableRowContext, useTableRowContext, getTableColumnContext, setTableColumnContext, useTableColumnContext, type TableContext, type TableSelectionBehavior, type TableSelectionCheckboxState, type TableSelectionKey, type TableSelectionMode, type TableSortDirection, type TableSortDescriptor, type TableColumnWidth, type TableGridCoord, type TableColumnRegistration, type TableSectionKind, type TableSectionContext, type TableRowContext, type TableColumnContext, type CreateTableContextOptions } from './root/context';
+import * as TableParts from './index.parts.ts';
+export default TableParts;

package/dist/table/index.js

@@ -0,0 +1,16 @@
+export * as Table from './index.parts.ts';
+export { default as TableRoot } from './root/table-root.svelte';
+export { default as TableColumn } from './column/table-column.svelte';
+export { default as TableHeader } from './header/table-header.svelte';
+export { default as TableBody } from './body/table-body.svelte';
+export { default as TableEmptyState } from './empty-state/table-empty-state.svelte';
+export { default as TableFooter } from './footer/table-footer.svelte';
+export { default as TableRow } from './row/table-row.svelte';
+export { default as TableColumnHeaderCell } from './column-header-cell/table-column-header-cell.svelte';
+export { default as TableColumnResizer } from './column-resizer/table-column-resizer.svelte';
+export { default as TableCheckbox } from './checkbox/table-checkbox.svelte';
+export { default as TableCheckboxIndicator } from './checkbox-indicator/table-checkbox-indicator.svelte';
+export { default as TableCell } from './cell/table-cell.svelte';
+export { createTableContext, getTableContext, setTableContext, useTableContext, getTableSectionContext, setTableSectionContext, useTableSectionContext, getTableRowContext, setTableRowContext, useTableRowContext, getTableColumnContext, setTableColumnContext, useTableColumnContext } from './root/context';
+import * as TableParts from './index.parts.ts';
+export default TableParts;

package/dist/table/index.parts.d.ts

@@ -0,0 +1,12 @@
+export { default as Root } from './root/table-root.svelte';
+export { default as Column } from './column/table-column.svelte';
+export { default as Header } from './header/table-header.svelte';
+export { default as Body } from './body/table-body.svelte';
+export { default as EmptyState } from './empty-state/table-empty-state.svelte';
+export { default as Footer } from './footer/table-footer.svelte';
+export { default as Row } from './row/table-row.svelte';
+export { default as ColumnHeaderCell } from './column-header-cell/table-column-header-cell.svelte';
+export { default as ColumnResizer } from './column-resizer/table-column-resizer.svelte';
+export { default as Checkbox } from './checkbox/table-checkbox.svelte';
+export { default as CheckboxIndicator } from './checkbox-indicator/table-checkbox-indicator.svelte';
+export { default as Cell } from './cell/table-cell.svelte';

package/dist/table/index.parts.js

@@ -0,0 +1,12 @@
+export { default as Root } from './root/table-root.svelte';
+export { default as Column } from './column/table-column.svelte';
+export { default as Header } from './header/table-header.svelte';
+export { default as Body } from './body/table-body.svelte';
+export { default as EmptyState } from './empty-state/table-empty-state.svelte';
+export { default as Footer } from './footer/table-footer.svelte';
+export { default as Row } from './row/table-row.svelte';
+export { default as ColumnHeaderCell } from './column-header-cell/table-column-header-cell.svelte';
+export { default as ColumnResizer } from './column-resizer/table-column-resizer.svelte';
+export { default as Checkbox } from './checkbox/table-checkbox.svelte';
+export { default as CheckboxIndicator } from './checkbox-indicator/table-checkbox-indicator.svelte';
+export { default as Cell } from './cell/table-cell.svelte';

package/dist/table/root/README.md

@@ -0,0 +1,56 @@
+<!-- markdownlint-disable MD024 MD060 -->
+
+# Table.Root
+
+## API reference
+
+### Table.Root
+
+Name: `Table.Root`
+Description: State container for interactive table behavior, including roving focus, row selection, disabled row handling, and sortable column state.
+
+| Prop                    | Type                                                         | Default     | Description                                                                                                                                          |
+| ----------------------- | ------------------------------------------------------------ | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `selectionMode`         | `'none' \| 'single' \| 'multiple'`                           | `'none'`    | Controls row selection behavior.                                                                                                                     |
+| `selectionBehavior`     | `'toggle' \| 'replace'`                                      | `'toggle'`  | `toggle` uses checkbox-style selection. `replace` makes click replace selection, vertical arrows move selection, and `Shift+ArrowUp/Down` extend it. |
+| `selectedKeys`          | `Iterable<string \| number>`                                 | `undefined` | Controlled selected row ids. Supports `bind:selectedKeys`.                                                                                           |
+| `defaultSelectedKeys`   | `Iterable<string \| number>`                                 | `undefined` | Initial selected row ids for uncontrolled usage. When `selectionMode` later becomes `none`, the internal selection is cleared.                       |
+| `sortDescriptor`        | `{ column: string; direction: 'ascending' \| 'descending' }` | `undefined` | Controlled sort state. Supports `bind:sortDescriptor`. Setting it back to `undefined` clears the sort.                                               |
+| `defaultSortDescriptor` | `{ column: string; direction: 'ascending' \| 'descending' }` | `undefined` | Initial sort state for uncontrolled usage.                                                                                                           |
+| `columnWidths`          | `Map<string, number>`                                        | `undefined` | Controlled column width state in px. Supports `bind:columnWidths`.                                                                                   |
+| `defaultColumnWidths`   | `Iterable<[string, number]>`                                 | `undefined` | Initial uncontrolled column widths in px.                                                                                                            |
+| `disabledKeys`          | `Iterable<string \| number>`                                 | `undefined` | Row ids that should be non-selectable.                                                                                                               |
+| `onSelectionChange`     | `(keys: Set<string \| number>) => void`                      | `undefined` | Called when row selection changes.                                                                                                                   |
+| `onSortChange`          | `(descriptor) => void`                                       | `undefined` | Called when sortable header state changes.                                                                                                           |
+| `onColumnWidthsChange`  | `(widths: Map<string, number>) => void`                      | `undefined` | Called when resize interactions update column widths.                                                                                                |
+| `onColumnResizeStart`   | `(columnId: string) => void`                                 | `undefined` | Called when a column resize drag starts.                                                                                                             |
+| `onColumnResizeEnd`     | `(widths: Map<string, number>) => void`                      | `undefined` | Called when a column resize drag ends.                                                                                                               |
+| `aria-label`            | `string`                                                     | `undefined` | Accessible name when no external label is present.                                                                                                   |
+| `aria-labelledby`       | `string`                                                     | `undefined` | Id reference for an external label.                                                                                                                  |
+| `class`                 | `string`                                                     | `''`        | Class names for the root table element.                                                                                                              |
+| `children`              | `Snippet`                                                    | `undefined` | Composed table parts.                                                                                                                                |
+
+### Behavior notes
+
+Name: Selection and sorting notes
+Description: Current v1 interaction constraints that affect consumer expectations.
+
+| Topic                   | Behavior                                                                                                                                                                                                                                                                                                                                                          |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `selectionMode="none"`  | Clears existing row selection internally and prevents further row selection until another mode is set.                                                                                                                                                                                                                                                            |
+| Text selection and copy | Browser-native text selection and `Ctrl+C` behavior are preserved; the component does not implement custom clipboard logic.                                                                                                                                                                                                                                       |
+| `replace` mode blur     | Clicking or tabbing outside the table clears focus state but does not clear row selection.                                                                                                                                                                                                                                                                        |
+| Sort announcements      | Sort changes are mirrored into a polite live region. Use `Table.Column.textValue` when the announced label should differ from the column `id`.                                                                                                                                                                                                                    |
+| Column resizing         | Width state is normalized to px values and a resize handle only affects the `Table.Column` it is composed within.                                                                                                                                                                                                                                                 |
+| Row edge focus          | In body rows, `ArrowLeft` before the first cell and `ArrowRight` after the last cell move focus onto the row itself; `ArrowUp` / `ArrowDown` keep that row-edge focus aligned across rows, repeating the same horizontal arrow loops back into the opposite edge cell, and `Home` / `End` jump to the first or last focusable body row while row focus is active. |
+
+### Context utilities
+
+Name: `context.ts` helpers
+Description: Internal and advanced APIs for reading and publishing table state.
+
+| Prop                 | Type                        | Default | Description                                             |
+| -------------------- | --------------------------- | ------- | ------------------------------------------------------- |
+| `createTableContext` | `(options) => TableContext` | `-`     | Creates the internal state contract.                    |
+| `setTableContext`    | `(context) => TableContext` | `-`     | Publishes context from `Table.Root`.                    |
+| `useTableContext`    | `() => TableContext`        | `-`     | Consumes table context and throws outside `Table.Root`. |

package/dist/table/root/context.d.ts

@@ -0,0 +1,198 @@
+import { type Readable } from 'svelte/store';
+export type TableSelectionKey = string | number;
+export type TableSelectionMode = 'none' | 'single' | 'multiple';
+export type TableSelectionBehavior = 'toggle' | 'replace';
+export type TableSortDirection = 'ascending' | 'descending';
+export type TableSectionKind = 'header' | 'body' | 'footer';
+type TableSelectionInteraction = {
+    shiftKey?: boolean;
+    ctrlKey?: boolean;
+    metaKey?: boolean;
+    altKey?: boolean;
+};
+export type TableSortDescriptor = {
+    column: string;
+    direction: TableSortDirection;
+};
+export type TableColumnWidth = number | `${number}px`;
+export type TableGridCoord = {
+    row: number;
+    col: number;
+};
+export type TableRowFocusEdge = 'start' | 'end';
+export type TableColumnRegistration = {
+    token: string;
+    id: string;
+    allowsSorting: boolean;
+    allowsResizing: boolean;
+    isRowHeader: boolean;
+    textValue?: string;
+    width?: TableColumnWidth;
+    defaultWidth?: TableColumnWidth;
+    minWidth?: number;
+    maxWidth?: number;
+};
+export type TableSelectionCheckboxState = 'none' | 'some' | 'all';
+type TableRowRegistration = {
+    token: string;
+    section: TableSectionKind;
+    id?: TableSelectionKey;
+    disabled: boolean;
+    element?: HTMLTableRowElement;
+};
+type TableCellRegistration = {
+    key: string;
+    rowToken: string;
+    section: Extract<TableSectionKind, 'header' | 'body'>;
+    columnIndex?: number;
+    columnToken?: string;
+    element?: HTMLElement;
+    focusDelegate?: () => HTMLElement | undefined;
+};
+export type CreateTableContextOptions = {
+    selectionMode?: TableSelectionMode;
+    selectionBehavior?: TableSelectionBehavior;
+    initialSelectedKeys?: Iterable<TableSelectionKey>;
+    initialSortDescriptor?: TableSortDescriptor;
+    initialColumnWidths?: Iterable<readonly [string, number]>;
+    initialHiddenColumns?: Iterable<string>;
+    disabledKeys?: Iterable<TableSelectionKey>;
+    onSelectionChange?: (keys: Set<TableSelectionKey>) => void;
+    onSortChange?: (descriptor: TableSortDescriptor | undefined) => void;
+    onColumnWidthsChange?: (widths: Map<string, number>) => void;
+    onHiddenColumnsChange?: (columnIds: string[]) => void;
+    onColumnResizeStart?: (columnId: string) => void;
+    onColumnResizeEnd?: (widths: Map<string, number>) => void;
+};
+export type TableContext = {
+    layoutVersion: Readable<number>;
+    selectionVersion: Readable<number>;
+    focusVersion: Readable<number>;
+    sortVersion: Readable<number>;
+    widthVersion: Readable<number>;
+    resizeVersion: Readable<number>;
+    createInstanceToken: (prefix: string) => string;
+    selectionMode: TableSelectionMode;
+    selectionBehavior: TableSelectionBehavior;
+    disabledKeys: Set<TableSelectionKey>;
+    focusedCellKey: string | null;
+    focusVisible: boolean;
+    sortDescriptor: TableSortDescriptor | undefined;
+    resizingColumnId: string | null;
+    registerColumn: (column: TableColumnRegistration) => void;
+    unregisterColumn: (token: string) => void;
+    registerColumnResizer: (columnToken: string) => void;
+    unregisterColumnResizer: (columnToken: string) => void;
+    getColumnCount: () => number;
+    getVisibleColumnCount: () => number;
+    getColumnAt: (index: number) => TableColumnRegistration | undefined;
+    getColumnIndexByToken: (token: string) => number;
+    getVisibleColumnIndexByToken: (token: string) => number;
+    getColumnTextValue: (columnId: string) => string | undefined;
+    getColumnWidth: (columnId: string) => number | undefined;
+    getColumnMinWidth: (columnId: string) => number | undefined;
+    getColumnMaxWidth: (columnId: string) => number | undefined;
+    isColumnHidden: (columnId: string) => boolean;
+    isColumnResizable: (columnId: string) => boolean;
+    getColumnWidths: () => Map<string, number>;
+    getVisibleColumnWidths: () => Map<string, number>;
+    setColumnWidths: (widths?: Iterable<readonly [string, number]>) => void;
+    setColumnWidth: (columnId: string, width: number) => void;
+    setHiddenColumns: (columnIds?: Iterable<string>) => void;
+    measureColumnContentWidth: (columnId: string) => number | undefined;
+    startColumnResize: (columnId: string) => void;
+    endColumnResize: () => void;
+    suppressHeaderClickOnce: () => void;
+    consumeHeaderClickSuppression: () => boolean;
+    hasResizableColumns: () => boolean;
+    registerRow: (row: TableRowRegistration) => void;
+    unregisterRow: (token: string) => void;
+    getHeaderRowCount: () => number;
+    getBodyRowCount: () => number;
+    isRowSelected: (id: TableSelectionKey | undefined) => boolean;
+    isRowFocused: (token: string) => boolean;
+    isRowFocusTarget: (token: string) => boolean;
+    getRowFocusEdge: (token: string) => TableRowFocusEdge | null;
+    isRowDisabled: (id: TableSelectionKey | undefined, localDisabled?: boolean) => boolean;
+    hasSelectableRows: () => boolean;
+    getSelectionCheckboxState: () => TableSelectionCheckboxState;
+    registerCell: (cell: TableCellRegistration) => void;
+    unregisterCell: (key: string) => void;
+    isCellFocused: (key: string) => boolean;
+    isCellTabStop: (key: string) => boolean;
+    isRowTabStop: (token: string) => boolean;
+    focusCellByKey: (key: string | null) => void;
+    focusRowByToken: (token: string, edge: TableRowFocusEdge) => void;
+    pressRow: (id: TableSelectionKey | undefined, interaction?: TableSelectionInteraction) => void;
+    setFocusedCell: (key: string | null) => void;
+    setFocusedRow: (token: string | null, edge?: TableRowFocusEdge) => void;
+    setFocusVisible: (visible: boolean) => void;
+    moveFocus: (direction: 'up' | 'down' | 'left' | 'right', interaction?: TableSelectionInteraction) => void;
+    moveToRowStart: () => void;
+    moveToRowEnd: () => void;
+    moveToBodyRowStart: () => void;
+    moveToBodyRowEnd: () => void;
+    moveToGridStart: () => void;
+    moveToGridEnd: () => void;
+    toggleRowSelection: (id: TableSelectionKey | undefined) => void;
+    selectAllRows: () => void;
+    deselectAllRows: () => void;
+    setSelection: (keys: Iterable<TableSelectionKey>) => void;
+    setSelectionMode: (mode: TableSelectionMode) => void;
+    setSelectionBehavior: (behavior: TableSelectionBehavior) => void;
+    setDisabledKeys: (keys?: Iterable<TableSelectionKey>) => void;
+    setSortDescriptor: (descriptor: TableSortDescriptor | undefined) => void;
+    toggleSort: (columnId: string) => void;
+    isColumnSortable: (columnId: string) => boolean;
+    getSortDirection: (columnId: string) => TableSortDirection | undefined;
+};
+export type TableSectionContext = {
+    section: TableSectionKind;
+};
+export type TableRowContext = {
+    rowToken: string;
+    section: TableSectionKind;
+    rowId?: TableSelectionKey;
+    isDisabled: boolean;
+    cellOrderVersion: Readable<number>;
+    registerCellToken: (token: string, getElement?: () => HTMLElement | undefined) => void;
+    unregisterCellToken: (token: string) => void;
+    getCellIndex: (token: string) => number;
+};
+export type TableColumnContext = {
+    token: string;
+    id: string;
+    allowsSorting: boolean;
+    allowsResizing: boolean;
+    isHidden: boolean;
+    isRowHeader: boolean;
+    textValue?: string;
+    width?: TableColumnWidth;
+    defaultWidth?: TableColumnWidth;
+    minWidth?: number;
+    maxWidth?: number;
+};
+export type TableCellContext = {
+    cellKey: string;
+    registerFocusDelegate: (getElement: () => HTMLElement | undefined) => void;
+    unregisterFocusDelegate: () => void;
+    notifyResizerPresent?: () => void;
+    notifyResizerRemoved?: () => void;
+};
+export declare function createTableContext(options?: CreateTableContextOptions): TableContext;
+export declare function setTableContext(context: TableContext): TableContext;
+export declare function getTableContext(): TableContext | undefined;
+export declare function useTableContext(): TableContext;
+export declare function setTableSectionContext(context: TableSectionContext): TableSectionContext;
+export declare function getTableSectionContext(): TableSectionContext | undefined;
+export declare function useTableSectionContext(): TableSectionContext;
+export declare function setTableRowContext(context: TableRowContext): TableRowContext;
+export declare function getTableRowContext(): TableRowContext | undefined;
+export declare function useTableRowContext(): TableRowContext;
+export declare function setTableCellContext(context: TableCellContext): TableCellContext;
+export declare function getTableCellContext(): TableCellContext | undefined;
+export declare function useTableCellContext(): TableCellContext;
+export declare function setTableColumnContext(context: TableColumnContext): TableColumnContext;
+export declare function getTableColumnContext(): TableColumnContext | undefined;
+export declare function useTableColumnContext(): TableColumnContext;
+export {};