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

package/dist/primitives/focus-trap.js

@@ -2,6 +2,7 @@
  * Focus trap primitive.
  * Traps keyboard focus within a container element.
  */
+import { focusWithModality, getInteractionModality } from './input-modality';
 const FOCUSABLE_SELECTOR = [
     'a[href]',
     'button:not([disabled])',
@@ -11,8 +12,29 @@ const FOCUSABLE_SELECTOR = [
     '[tabindex]:not([tabindex="-1"])',
     '[contenteditable="true"]'
 ].join(', ');
+function resolveEnabled(options) {
+    if (typeof options === 'boolean')
+        return options;
+    return options.enabled ?? true;
+}
+function resolveRestoreFocus(options) {
+    if (typeof options === 'boolean')
+        return true;
+    return options.restoreFocus ?? true;
+}
+function resolveInitialFocus(container, initialFocus) {
+    if (!initialFocus)
+        return null;
+    if (typeof initialFocus === 'function') {
+        return initialFocus() ?? null;
+    }
+    if (typeof initialFocus === 'string') {
+        return container.querySelector(initialFocus);
+    }
+    return initialFocus;
+}
 function getFocusableElements(container) {
-    return Array.from(container.querySelectorAll(FOCUSABLE_SELECTOR)).filter((el) => el.offsetParent !== null);
+    return Array.from(container.querySelectorAll(FOCUSABLE_SELECTOR)).filter((element) => element.offsetParent !== null);
 }
 /**
  * Svelte action that traps focus within an element.
@@ -25,8 +47,11 @@ function getFocusableElements(container) {
  * </div>
  * ```
  */
-export function focusTrap(node, enabled = true) {
+export function focusTrap(node, options = true) {
     let previousActiveElement = null;
+    let enabled = resolveEnabled(options);
+    let restoreFocus = resolveRestoreFocus(options);
+    let initialFocus = typeof options === 'boolean' ? undefined : options.initialFocus;
     function handleKeydown(event) {
         if (event.key !== 'Tab')
             return;
@@ -49,12 +74,11 @@ export function focusTrap(node, enabled = true) {
                 event.preventDefault();
                 lastElement.focus();
             }
+            return;
         }
-        else {
-            if (document.activeElement === lastElement || document.activeElement === node) {
-                event.preventDefault();
-                firstElement.focus();
-            }
+        if (document.activeElement === lastElement || document.activeElement === node) {
+            event.preventDefault();
+            firstElement.focus();
         }
     }
     function activate() {
@@ -62,21 +86,25 @@ export function focusTrap(node, enabled = true) {
         if (!node.hasAttribute('tabindex')) {
             node.setAttribute('tabindex', '-1');
         }
-        // Focus first focusable element, or the container if none
         requestAnimationFrame(() => {
+            const initialFocusTarget = resolveInitialFocus(node, initialFocus);
+            const modality = getInteractionModality();
+            if (initialFocusTarget && initialFocusTarget.isConnected) {
+                focusWithModality(initialFocusTarget, modality);
+                return;
+            }
             const focusableElements = getFocusableElements(node);
             if (focusableElements.length > 0) {
-                focusableElements[0].focus();
-            }
-            else {
-                node.focus();
+                focusWithModality(focusableElements[0], modality);
+                return;
             }
+            focusWithModality(node, modality);
         });
         document.addEventListener('keydown', handleKeydown, true);
     }
     function deactivate() {
         document.removeEventListener('keydown', handleKeydown, true);
-        if (previousActiveElement && previousActiveElement.focus) {
+        if (restoreFocus && previousActiveElement && previousActiveElement.focus) {
             previousActiveElement.focus();
         }
     }
@@ -84,14 +112,19 @@ export function focusTrap(node, enabled = true) {
         activate();
     }
     return {
-        update(newEnabled) {
-            if (newEnabled && !enabled) {
+        update(newOptions) {
+            const nextEnabled = resolveEnabled(newOptions);
+            const nextRestoreFocus = resolveRestoreFocus(newOptions);
+            if (nextEnabled && !enabled) {
                 activate();
             }
-            else if (!newEnabled && enabled) {
+            else if (!nextEnabled && enabled) {
                 deactivate();
             }
-            enabled = newEnabled;
+            options = newOptions;
+            enabled = nextEnabled;
+            restoreFocus = nextRestoreFocus;
+            initialFocus = typeof newOptions === 'boolean' ? undefined : newOptions.initialFocus;
         },
         destroy() {
             if (enabled) {

package/dist/primitives/index.d.ts

@@ -4,3 +4,4 @@ export * from './keyboard-navigation.js';
 export * from './scroll-lock.js';
 export * from './aria-hide-outside.js';
 export * from './click-outside.js';
+export * from './input-modality.js';

package/dist/primitives/index.js

@@ -5,3 +5,4 @@ export * from './keyboard-navigation.js';
 export * from './scroll-lock.js';
 export * from './aria-hide-outside.js';
 export * from './click-outside.js';
+export * from './input-modality.js';

package/dist/primitives/input-modality.d.ts

@@ -0,0 +1,7 @@
+export type InputModality = 'keyboard' | 'pointer' | 'virtual';
+export declare function initInputModality(target?: HTMLElement | null): void;
+export declare function trackInteractionModality(event?: Event, target?: HTMLElement | null): void;
+export declare function getInteractionModality(): InputModality;
+export declare function shouldShowFocusVisible(target: HTMLElement | null): boolean;
+export declare function focusWithModality(target: HTMLElement, modality: InputModality, options?: FocusOptions): void;
+export declare function resolveCloseInteractionModality(reason: string, event?: Event): InputModality;

package/dist/primitives/input-modality.js

@@ -0,0 +1,125 @@
+let currentModality = 'virtual';
+const listenedWindows = new WeakSet();
+let forcedFocusTarget = null;
+let forcedFocusModality = null;
+function isModifierOnlyKey(event) {
+    return (event.key === 'Shift' || event.key === 'Control' || event.key === 'Alt' || event.key === 'Meta');
+}
+function isKeyboardModalityKey(event) {
+    if (event.ctrlKey || event.metaKey || event.altKey)
+        return false;
+    if (isModifierOnlyKey(event))
+        return false;
+    return true;
+}
+function ensureWindowListeners(win) {
+    if (!win)
+        return;
+    if (listenedWindows.has(win))
+        return;
+    const onKeyDown = (event) => {
+        if (!isKeyboardModalityKey(event))
+            return;
+        currentModality = 'keyboard';
+    };
+    const onPointerDown = () => {
+        currentModality = 'pointer';
+    };
+    const onFocusIn = () => {
+        if (currentModality === 'pointer' || currentModality === 'keyboard')
+            return;
+        currentModality = 'virtual';
+    };
+    win.addEventListener('keydown', onKeyDown, true);
+    win.addEventListener('pointerdown', onPointerDown, true);
+    win.addEventListener('mousedown', onPointerDown, true);
+    win.addEventListener('focusin', onFocusIn, true);
+    listenedWindows.add(win);
+}
+export function initInputModality(target) {
+    const ownerWindow = target?.ownerDocument?.defaultView;
+    if (ownerWindow) {
+        ensureWindowListeners(ownerWindow);
+        return;
+    }
+    if (typeof window !== 'undefined') {
+        ensureWindowListeners(window);
+    }
+}
+function inferModalityFromEvent(event) {
+    if (!event)
+        return undefined;
+    if (event instanceof KeyboardEvent) {
+        return isKeyboardModalityKey(event) ? 'keyboard' : undefined;
+    }
+    if (event instanceof MouseEvent && event.type === 'click' && event.detail === 0) {
+        return 'keyboard';
+    }
+    if (event instanceof PointerEvent || event instanceof MouseEvent) {
+        return 'pointer';
+    }
+    return undefined;
+}
+function resolveModalityForTarget(target) {
+    if (target && forcedFocusTarget === target && forcedFocusModality) {
+        const modality = forcedFocusModality;
+        forcedFocusTarget = null;
+        forcedFocusModality = null;
+        return modality;
+    }
+    return currentModality;
+}
+export function trackInteractionModality(event, target) {
+    initInputModality(target);
+    const inferred = inferModalityFromEvent(event);
+    if (inferred) {
+        currentModality = inferred;
+    }
+}
+export function getInteractionModality() {
+    return currentModality;
+}
+export function shouldShowFocusVisible(target) {
+    if (!target)
+        return false;
+    const modality = resolveModalityForTarget(target);
+    if (modality === 'pointer')
+        return false;
+    return target.matches(':focus-visible');
+}
+export function focusWithModality(target, modality, options) {
+    initInputModality(target);
+    // The forced target/modality pair is a synchronous safety net so a focus handler that runs
+    // immediately after target.focus() can resolve the intended modality without racing async timing.
+    // If it is consumed later, currentModality still preserves the same modality as fallback.
+    forcedFocusTarget = target;
+    forcedFocusModality = modality;
+    currentModality = modality;
+    if (modality === 'pointer') {
+        const pointerFocusOptions = {
+            ...(options ?? {}),
+            focusVisible: false
+        };
+        target.focus(pointerFocusOptions);
+    }
+    else {
+        target.focus(options);
+    }
+    queueMicrotask(() => {
+        if (forcedFocusTarget !== target)
+            return;
+        forcedFocusTarget = null;
+        forcedFocusModality = null;
+    });
+}
+export function resolveCloseInteractionModality(reason, event) {
+    if (reason === 'escape-key')
+        return 'keyboard';
+    if (event instanceof KeyboardEvent)
+        return 'keyboard';
+    if (event instanceof PointerEvent || event instanceof MouseEvent)
+        return 'pointer';
+    if (reason === 'outside-press')
+        return 'pointer';
+    return 'virtual';
+}

package/dist/primitives/keyboard-navigation.d.ts

@@ -53,6 +53,7 @@ export type KeyboardNavigationReturn = {
     focusFirst: () => void;
     focusLast: () => void;
     focusById: (id: string | number) => void;
+    setCurrentId: (id: string | number | null) => void;
     /** Update items (call after DOM changes) */
     updateItems: () => void;
 };

package/dist/primitives/keyboard-navigation.js

@@ -130,6 +130,22 @@ export function createKeyboardNavigation(options = {}) {
             focusItem(element);
         }
     }
+    function setCurrentId(id) {
+        if (id === null) {
+            focusedId.set(null);
+            focusedElement.set(null);
+            onFocusChange?.(null, null);
+            return;
+        }
+        items = getItems();
+        const element = items.find((el) => {
+            const itemId = getItemId(el);
+            return itemId === id || String(itemId) === String(id);
+        });
+        focusedId.set(id);
+        focusedElement.set(element ?? null);
+        onFocusChange?.(id, element ?? null);
+    }
     function handleTypeahead(char) {
         if (!typeahead)
             return;
@@ -254,6 +270,7 @@ export function createKeyboardNavigation(options = {}) {
         focusFirst,
         focusLast,
         focusById,
+        setCurrentId,
         updateItems
     };
 }

package/dist/table/IMPLEMENTATION_NOTES.md

@@ -0,0 +1,9 @@
+# Table Implementation Notes
+
+## Open questions
+
+- Disabled body rows are currently rendered and treated with an all-or-nothing disabled model. The planned `disabledBehavior` API (`'selection' | 'all'`) will require splitting focus/action disabling from selection disabling.
+- `Table.Column` is implemented as a logical wrapper and currently assumes the intended child is a single `Table.ColumnHeaderCell`.
+- `Table.Footer` renders semantic table cells but is intentionally excluded from the roving-focus model in v1.
+- Interactive controls nested inside `Table.Cell` are still intentionally out of scope for v1.
+- `pressRow()` is currently selection-oriented. The planned `onRowAction` feature will require a clearer interaction pipeline so pointer click, double click, `Enter`, and `Space` can route to action and selection independently.

package/dist/table/PLAN-HIDDEN-COLUMNS.md

@@ -0,0 +1,152 @@
+# Plan: `hiddenColumns` prop for Table.Root
+
+## Objective
+
+Add a `hiddenColumns` prop to `Table.Root` that accepts an array of column IDs and hides those columns automatically across header, body, and footer — without breaking the positional column↔cell mapping.
+
+## Reviewed decisions
+
+- Keep **physical column order** for cell-to-column mapping in body/footer rows.
+- Add a separate **visible column model** for aria counts, keyboard navigation, and visible `data-column-index` values.
+- Preserve hidden column widths in state so re-showing a column restores its prior size.
+
+## API Design
+
+### New props on `Table.Root`
+
+```ts
+hiddenColumns?: string[];              // controlled (bindable)
+defaultHiddenColumns?: string[];       // uncontrolled initial state
+onHiddenColumnsChange?: (ids: string[]) => void;
+```
+
+- `hiddenColumns` is **bindable** (`bind:hiddenColumns`) so consumers can sync external state (e.g. a column-visibility dropdown).
+- Follows the same controlled/uncontrolled pattern as `selectedKeys`, `sortDescriptor`, and `columnWidths`.
+
+### Internal context method
+
+```ts
+isColumnHidden(columnId: string): boolean;
+```
+
+## Hiding strategy: `display: none` — not DOM removal
+
+Body cells map their column by DOM position (`columnIndex`). Removing a `<Table.Column>` from the DOM with `{#if}` causes body cells to misalign because the index shifts.
+
+Using `display: none`:
+
+- DOM order is preserved → index mapping never breaks.
+- Users don't need paired `{#if}` guards in both header and every body row.
+- `display: none` on native `<th>`/`<td>` is valid — the table reflows correctly.
+
+## Implementation tasks
+
+### 1. Context (`table/root/context.ts`)
+
+- Add `hiddenColumnsSet: Set<string>` as reactive internal state (derived from the array prop).
+- Expose `isColumnHidden(columnId: string): boolean`.
+- Add `hiddenColumnsVersion` store for efficient reactive invalidation.
+- Update `getColumnCount()` to exclude hidden columns from the navigable count.
+- Update navigable-cells cache (`navigableCellsCache`) to skip cells belonging to hidden columns.
+- Update `getRowsWithCells()` so keyboard navigation sees only visible cells.
+
+### 2. Root component (`table/root/table-root.svelte`)
+
+- Add props: `hiddenColumns` (bindable), `defaultHiddenColumns`, `onHiddenColumnsChange`.
+- Implement controlled/uncontrolled pattern (identical to `selectedKeys`).
+- Pass `hiddenColumnsSet` into the context.
+
+### 3. Column (`table/column/table-column.svelte`)
+
+- Read `isColumnHidden(id)` from context.
+- If hidden → propagate hidden state to column context so children can react.
+
+### 4. ColumnHeaderCell (`table/column-header-cell/`)
+
+- Apply `display: none` when column is hidden.
+- Set `aria-hidden="true"` when hidden.
+- Exclude from tab order.
+
+### 5. Cell (`table/cell/table-cell.svelte`)
+
+- Resolve column from `columnIndex` (existing behavior).
+- If column is hidden → apply `display: none` and `aria-hidden="true"`.
+- Exclude from tab order and focus navigation.
+
+### 6. ColumnResizer (`table/column-resizer/`)
+
+- Not navigable or interactive while its column is hidden.
+
+### 7. Keyboard navigation
+
+- Arrow left/right must skip cells of hidden columns.
+- Home/End must target the first/last **visible** cell.
+- If the currently focused cell becomes hidden, move focus to the nearest visible cell.
+- Ctrl+A is unaffected (operates on rows, not columns).
+
+### 8. Sorting and column widths
+
+- Sorting a hidden column: keep the descriptor but do not render a visual indicator.
+- Column widths: hidden columns retain their width in the Map but do not affect layout.
+
+## Tests
+
+### Rendering
+
+- Hidden column is not visible in the DOM (`display: none` on header, body, and footer cells).
+- Columns not listed in `hiddenColumns` render normally.
+- Dynamically changing `hiddenColumns` shows/hides columns reactively.
+
+### Bindable / controlled
+
+- `bind:hiddenColumns` reflects bidirectional changes.
+- `defaultHiddenColumns` applies only on initial mount.
+- `onHiddenColumnsChange` fires when the set changes internally.
+
+### Keyboard navigation
+
+- Arrow left/right skip cells of hidden columns.
+- Home/End target the first/last visible cell.
+- Tab enters the grid on a visible cell (never a hidden one).
+- Hiding the column of the currently focused cell moves focus to the nearest visible neighbor.
+
+### Feature interactions
+
+- Selection checkboxes in a hidden column: row selection still works.
+- Sorting by a hidden column does not crash; descriptor is preserved.
+- Column resize: hidden column is not resizable while hidden.
+- `getColumnCount()` returns only visible columns.
+- Empty `hiddenColumns` array has no effect.
+
+### Accessibility
+
+- Hidden cells carry `aria-hidden="true"` in header, body, and footer.
+- `aria-colcount` on the `<table>` reflects only **visible** columns.
+- `aria-colindex` on visible cells is recalculated excluding hidden columns.
+- Screen readers do not announce hidden columns during navigation.
+
+## Files affected
+
+| File                                                       | Change                                     |
+| ---------------------------------------------------------- | ------------------------------------------ |
+| `table/root/context.ts`                                    | State, methods, caches                     |
+| `table/root/table-root.svelte`                             | Props, binding, controlled pattern         |
+| `table/column/table-column.svelte`                         | Propagate hidden state                     |
+| `table/column-header-cell/table-column-header-cell.svelte` | `display: none`, `aria-hidden`             |
+| `table/cell/table-cell.svelte`                             | `display: none`, `aria-hidden`, skip focus |
+| `table/column-resizer/table-column-resizer.svelte`         | Skip interaction when hidden               |
+| `table/index.parts.ts`                                     | Type exports if needed                     |
+| `table/index.ts`                                           | Type exports if needed                     |
+| `table/root/*.test.ts`                                     | New test cases                             |
+
+## Execution order
+
+1. Context — state + methods (foundation)
+2. Root — props + binding (public API → context)
+3. Column + ColumnHeaderCell — hide header
+4. Cell — hide body/footer cells
+5. ColumnResizer — disable interaction
+6. Navigation — update keyboard nav to skip hidden cells
+7. Tests — validate all above
+8. Accessibility — audit aria attributes
+9. Demo page — add visibility toggle to the playground