@joewinke/jatui 0.1.26 → 0.1.28

package/CLAUDE.md

@@ -24,9 +24,9 @@ Then import:
 | `TextInput` | Text input with label, error, icon slots | `label`, `value` (bindable), `placeholder`, `error`, `disabled` |
 | `TextArea` | Multiline text input | `label`, `value` (bindable), `placeholder`, `rows`, `error`, `maxlength` |
 | `SelectInput` | Dropdown select | `label`, `value` (bindable), `options: SelectOption[]`, `placeholder` |
-| `PhoneInput` | Intl phone (country dropdown + tel input, outputs E.164) | `value` (bindable), `name`, `defaultCountry`, `required` |
+| `PhoneInput` | Intl phone (country dropdown + tel input, outputs E.164; caps national digits per country). Fires `onChange(value)` on every change. | `value` (bindable), `name`, `defaultCountry`, `required`, `onChange` |
 | `ChipInput` | Tag/chip entry with suggestions | `chips` (bindable), `suggestions: SuggestionGroup[]`, `placeholder` |
-| `SearchDropdown` | Searchable dropdown with grouped results | `groups: SearchDropdownGroup[]`, `placeholder`, `onSelect` |
+| `SearchDropdown` | Searchable dropdown with grouped results, keyboard nav, avatar/initials options. `appendToBody` escapes table/overflow stacking contexts; `variant='chip'` renders a compact pill; `size='sm'` a smaller trigger; `dropup` opens upward; `clearable` shows an × when a value is set. Exposes `openDropdown()`. | `groups: SearchDropdownGroup[]`, `value`, `onChange`, `placeholder`, `variant`, `size`, `dropup`, `appendToBody`, `clearable`, `colorFn` |
 | `FilterDropdown` | Multi-select filter dropdown | `label`, `options: string[]`, `selected: Set<string>` (bindable) |
 | `SortDropdown` | Sort by column with direction | `options: SortOption[]`, `sortBy` (bindable), `sortDir` (bindable) |
 | `InlineEdit` | Click-to-edit text | `value` (bindable), `segments: DisplaySegment[]`, `onSave` |
@@ -37,7 +37,7 @@ Then import:
 | `SmartImageEditor` | AI-powered image upload with background removal and multi-variant processing pipeline. **Preferred over `ImageUpload` in editor contexts.** Two modes: simple (drop-in replacement, outputs blob URL) and editor (POST multipart to backend → variant grid). | `value` (bindable), `spec?: ImageProcessingSpec`, `uploadEndpoint?`, `onComplete?`, `accept?`, `maxSizeMb?` |
 | `FileDropzone` | Multi-file/folder/ZIP drag-drop upload zone. Handles FileSystem API folder recursion, MIME/size validation, and shows a pending-file grid. Calls `onFilesSelected(files, errors)` with validated `File[]`. Accepts already-uploaded files via `uploadedFiles: FileDropzoneFile[]` for post-upload display. | `accept?: string[]`, `maxSize?`, `maxFiles?`, `multiple?`, `uploadedFiles?`, `isUploading?`, `isExtracting?`, `dropLabel?`, `dropSubtext?`, `onFilesSelected?` |
 | `FileThumbnail` | File thumbnail with MIME-aware icon fallback. Shows an `<img>` for image files (with loading/error states) and typed icons for PDF, ZIP, CAD, and generic files. Size variants: `sm`, `md`, `lg`, `xl`. | `name`, `mimeType`, `url?`, `size?` |
-| `SignaturePad` | Draw signature on canvas | `onSave: (dataUrl: string) => void` |
+| `SignaturePad` | Draw signature on canvas (mouse + touch). Emits base64 PNG on each stroke-end via bindable `signatureData` or `onSignatureChange(data)`. Exposes `clear()`/`isEmpty()`. Pass `disabled` for a dimmed, non-interactive preview. | `signatureData` (bindable), `onSignatureChange`, `label`, `width`, `height`, `disabled`, `required` |
 
 ### Scheduling & Time
 

package/dist/actions/collapse.d.ts

@@ -33,7 +33,7 @@
  * ─── Usage — action form (most sites) ─────────────────────────────────────────
  *
  *   <script>
- *     import { collapse } from 'jatui'
+ *     import { collapse } from '../../../dist'
  *     let collapsible = $state(false)
  *     let expanded = $state(false)
  *     const bodyId = `collapse-${$props.id()}`

package/dist/actions/collapse.js

@@ -33,7 +33,7 @@
  * ─── Usage — action form (most sites) ─────────────────────────────────────────
  *
  *   <script>
- *     import { collapse } from 'jatui'
+ *     import { collapse } from '../../../dist'
  *     let collapsible = $state(false)
  *     let expanded = $state(false)
  *     const bodyId = `collapse-${$props.id()}`

package/dist/actions/listNav.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Shared keyboard-navigation action + composable for list-like UIs.
+ *
+ * Base motions — j/k / ArrowDown/ArrowUp with wraparound, Enter/Space to
+ * trigger select, Escape to clear focus. Typing targets (input, textarea,
+ * select, contenteditable) and most modifier combos are skipped so the
+ * shortcuts never interfere with typing or app-level keybindings.
+ *
+ * Vim-motion layer (always on):
+ *
+ *   gg           jump to first item
+ *   G            jump to last item
+ *   {n}j / {n}k  move `n` items (count-prefix buffer with 1.5s timeout)
+ *   {n}G, {n}gg  jump to 1-indexed line `n` (clamped to list length)
+ *   Ctrl+D / Ctrl+U  move roughly half a viewport's worth of items
+ *   zz           scroll the focused item to the centre of its viewport
+ *
+ * Selection layer (opt-in via `selectable: true`):
+ *
+ *   V              toggle visual mode (anchor at current focus, selects it)
+ *   j / k          while visual mode is on, also extends the range from anchor
+ *   x              toggle selection of the focused item (no movement)
+ *   Shift+J / K    toggle current + move down/up + toggle new focus (range-build)
+ *   *              toggle select-all of the currently visible items
+ *   Escape         backs out one layer at a time:
+ *                    pending motion → visual mode → selection → focus / onEscape
+ *
+ *   Selected items get the `selected-class` (default `jk-selected`) so pages
+ *   can style them. The controller exposes selectedIds()/clearSelection()/
+ *   selectAll()/toggleSelection()/isSelecting() and fires onSelectionChange
+ *   whenever the set mutates. A floating `BulkActionBar` is the canonical
+ *   chip for surfacing the count + per-route bulk actions.
+ *
+ * Usage — action form (simplest):
+ *
+ *   <div use:listNav={{
+ *     onSelect: (el, idx) => openDetail(el.dataset.navId!),
+ *     onEscape: () => closeDetail(),
+ *   }}>
+ *     {#each items as item}
+ *       <button data-nav-id={item.id}>{item.title}</button>
+ *     {/each}
+ *   </div>
+ *
+ * Usage — composable form (when you already have a keydown handler):
+ *
+ *   const nav = createListNav({
+ *     getItems: () => Array.from(container.querySelectorAll('[data-nav-id]')),
+ *     onSelect: (el) => openDetail(el.dataset.navId!),
+ *     selectable: true,
+ *     onSelectionChange: (ids) => { selectedIds = ids; },
+ *   });
+ *
+ *   function onKeydown(e: KeyboardEvent) {
+ *     if (nav.handleKeydown(e)) return;
+ *     // ...page-specific shortcuts
+ *   }
+ */
+import type { Action } from 'svelte/action';
+export interface ListNavOptions {
+    /**
+     * Return the navigable HTML elements in list order. Called on every
+     * navigation event so reactive lists stay in sync. When omitted in the
+     * action form, the action queries the node itself using {@link itemSelector}.
+     */
+    getItems?: () => HTMLElement[] | ArrayLike<HTMLElement>;
+    /** CSS selector used by the action to locate items. Default: `[data-nav-id]`. */
+    itemSelector?: string;
+    /** Fired when Enter or Space is pressed on the focused item. */
+    onSelect?: (item: HTMLElement, index: number) => void;
+    /** Fired when Escape is pressed. Default behaviour: clears focus. */
+    onEscape?: () => void;
+    /** Fired whenever the focused index changes (including cleared focus). */
+    onFocusChange?: (item: HTMLElement | null, index: number) => void;
+    /** When true, j at the last item wraps to first (and vice-versa). Default: true. */
+    wraparound?: boolean;
+    /** Class applied to the currently focused item. Default: `jk-focused`. */
+    focusedClass?: string;
+    /** When false, all shortcuts no-op. Default: true. */
+    enabled?: boolean;
+    /** Action-only. When true, listen on window; when false, on the node. Default: true. */
+    global?: boolean;
+    /**
+     * Enable the selection layer (V / Shift+J / Shift+K / x / *). Default: false.
+     * When false, those keys pass through unhandled so pages can keep them.
+     */
+    selectable?: boolean;
+    /** Class applied to selected items. Default: `jk-selected`. */
+    selectedClass?: string;
+    /** Fires whenever the selection set mutates. Receives a fresh Set snapshot. */
+    onSelectionChange?: (ids: Set<string>) => void;
+    /**
+     * Resolve an item's stable id. Default: `el.dataset.navId`. Override if
+     * your items use a different attribute (e.g. `data-rule-nav-id`).
+     */
+    getItemId?: (el: HTMLElement) => string | null | undefined;
+}
+export interface KeyboardShortcut {
+    key: string;
+    description: string;
+}
+export interface ListNavController {
+    /** Returns true if the event was handled (preventDefault was called). */
+    handleKeydown(event: KeyboardEvent): boolean;
+    focusedIndex(): number;
+    focus(index: number): void;
+    focusFirst(): void;
+    focusLast(): void;
+    clear(): void;
+    /** Re-apply the focused class after items change (e.g. after a filter). */
+    refresh(): void;
+    /** Read-only snapshot of selected item ids. */
+    selectedIds(): Set<string>;
+    /** Toggle selection. With no arg, toggles the focused item. */
+    toggleSelection(navId?: string): void;
+    /** Replace the selection with the given ids (or clear if empty). */
+    setSelection(ids: Iterable<string>): void;
+    /** Drop the selection and exit visual mode. */
+    clearSelection(): void;
+    /** Toggle select-all of the currently visible items. */
+    selectAll(): void;
+    /** True while visual-mode (V) is active. */
+    isSelecting(): boolean;
+}
+/**
+ * Imperative composable — use when you already own a keydown handler and want
+ * listNav to decide whether to consume the event.
+ */
+export declare function createListNav(options: ListNavOptions): ListNavController;
+/**
+ * Svelte action — attaches a keydown listener (window by default) and handles
+ * j/k/ArrowDown/ArrowUp/Enter/Space/Escape navigation over children of `node`.
+ */
+export declare const listNav: Action<HTMLElement, ListNavOptions | undefined>;