@joewinke/jatui 0.22.0 → 0.23.0

package/CLAUDE.md

@@ -33,6 +33,7 @@ Then import:
 | `VariablePicker` | Browse/insert template merge vars at caret | `groups: TemplateVarGroup[]`, `targetEl`, `onInsert` |
 | `CharacterCounter` | Shows chars remaining | `current: number`, `max: number` |
 | `ColorSelector` | Color picker from palette | `value` (bindable), `colors: string[]` |
+| `IconSelector` | Searchable, paged icon picker — icon set is fully prop-driven (any component accepting `{ size, class }`, e.g. lucide-svelte), so no icon-library dependency; optional `icon` snippet for custom rendering. Keyboard: arrows move, Enter selects, Home/End, PgUp/PgDn page, Esc closes. | `icons: IconSelectorOption[]`, `selectedIcon` (bindable), `onSelect`, `label`, `colorClass`, `compact`, `columns`, `perPage`, `icon` |
 | `ImageUpload` | Drag-drop image upload | `value` (bindable), `accept`, `maxSize` |
 | `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?` |
@@ -71,11 +72,15 @@ Then import:
 | `PresenceStack` | "Who's here" avatar stack for live-collaboration UI — max `maxVisible` avatars + "+N more" overflow bubble, tooltip per avatar ("X is editing FIELD" / "X is viewing"). Purely presentational — feed it viewers from any presence source (e.g. an SSE-backed presence composable). | `viewers: PresenceViewer[]`, `maxVisible?` (default 5), `size?`, `class?` |
 | `DirtyFormHost` | Composable form dirty-state manager — renders your form body plus a floating "Unsaved changes" pill + Cancel button; wires `beforeunload` and (optional) SvelteKit `beforeNavigate`. Callers who want bespoke pill/Cancel chrome use `createDirtyGuard()` directly and skip the component. Extracted from the F12 pattern in `/admin/roles/[id]`. | `baseline: T`, `current: T`, `onCancel?`, `beforeNavigate?`, `discardPrompt?`, `equals?`, `hideChrome?`, `children` (snippet with `{dirty, cancel}`) |
 | `BulkActionBar` | Floating action bar that appears when a `listNav` selection is non-empty. Simpler API than `FloatingActionBar`: takes a `Set`, `Array`, or plain number for `selection`; a flat `actions[]` with `{label, onSelect, destructive?}`; and now `groups[]` for dropdown-menu actions (each group is one button on the bar that opens a menu of `{label, onSelect}` items — same shape as `BulkAction`). Flat + grouped can be mixed. Reach for `FloatingActionBar` directly only when you need finer per-item dropdown styling (dot colors, icon snippets). | `selection: Set \| Array \| number`, `actions?: BulkAction[]`, `groups?: BulkActionGroup[]`, `onClear?`, `loading?`, `countLabel?` |
+| `BatchJobTable` | Generic queue runner (harvested from vid-gen's BatchGenerator) — `<BatchJobTable generics T>` over bindable `JobRow<T>[]`; host supplies async `run(data, {signal, attempt, reportProgress})`. Concurrency cap, optional per-run `processLimit` (quota budget), rolling-average ETA, per-row status badge / progress / elapsed / retry / skip / cancel / reorder — each cell a snippet override (`statusCell`, `progressCell`, `elapsedCell`, `actionsCell`), host data columns via `headers` + `cells`, extra toolbar content via `toolbar`. Uses `showToast` / `showConfirm` (mount `ToastHost` + `ConfirmDialog`). Exposes `start()`/`pause()`/`cancel()`/`retryFailed()`/`clearFinished()`. Pure scheduling helpers exported too (`nextJobsToStart`, `moveJob`, `summarizeJobs`, `toJobRows`). | `jobs` (bindable), `run`, `concurrencyLimit?` (3), `processLimit?`, `autoStart?`, `notify?`, `confirmDestructive?`, `onJobDone?`, `onJobFailed?`, `onBatchDone?` |
+| `QuotaMeter` | "312 / 500 credits · resets in 4h 10m" bar — warning tint at `warnAt`, error at 100%. Presentational; the host owns the ledger. | `used`, `limit`, `resetsAt?`, `label?`, `unit?`, `warnAt?` (0.8), `size?` |
+| `VariantMatrixPicker` | Category/option chip grid for building a combinatorial variant matrix (harvested from vid-gen's FrameVariantGenerator, presets stripped — caller-supplied `categories`). Each category tab shows a live selection count and an additive/multiplicative badge: multiplicative selections cartesian-multiply the total, additive ones stack flat onto every combination. Live combination count in the footer; algebra exported separately as pure functions (`generateCombinations`, `countCombinations`, `variantCategoryMode`, `findVariantOption`, `generateVariantFilename`). | `categories: VariantCategory[]`, `selected` (bindable `VariantSelection`), `forceMode?`, `showCount?` (true), `countLabel?`, `onChange?`, `class?` |
 
 ### Media
 
 | Component | Purpose | Key Props |
 |-----------|---------|-----------|
+| `ThumbnailGrid` | Generic thumbnail strip (chimaro port) — image tiles with text-tile fallback, +N overflow counter, remove/add affordances. Decoupled from any media library: pass `{id, url, alt}` items, or a `cell` snippet for full control of tile contents. | `items: ThumbnailItem[]`, `max`, `size` (`xs\|sm\|md\|lg`), `removable`+`onRemove`, `addable`+`onAdd`, `onSelect`, `cell` snippet |
 | `MediaWorkbench` | Full-featured image editor modal — upload, AI generate, AI edit, background removal, annotation canvas. **Preferred over `SmartImageEditor` for new image fields.** Two-column modal: preview left, 4 action tabs right (Generate, Edit, Remove BG, Annotate). Save uploads blob to `uploadEndpoint` or emits `onComplete`. Requires proxy endpoints from jst-23w1l.2. | `value` (bindable `string \| null`), `uploadEndpoint?` (default `/api/media`), `onComplete?`, `accept?` |
 | `MediaLightbox` | Full-screen media preview — z-9040 backdrop, arrow-key paging when given an array, `+/-/0` zoom, download action, Escape/backdrop close. **Use this for the general "just show it big" case** — replaces hand-rolled `fixed inset-0 z-[9040]` modals. For annotated / markup-overlaid image previews, use `ImageLightbox` instead. | `src?`, `filename?`, `kind?: 'image' \| 'video'`, `downloadUrl?`, `items?: MediaItem[]`, `initialIndex?`, `onClose?`, `zIndex?` |
 | `VideoPlayer` | **The default video surface — reach for this over a bare `<video controls>`.** One timeline band carrying a waveform-envelope scrubber, chapter flags (top edge), bookmark diamonds (bottom edge), diarized speaker colouring and scroll-to-zoom, plus an optional transcript pane (click to seek, active line auto-scroll, solo/skip per speaker, `T` toggle) and talk-time legend. **Every intelligence prop is optional** — a bare mp4 still gets the scrubber, hover-time card, wheel volume and the full keyboard map (Space/K, arrows/J/L, vol/mute, −/= speed + Backspace reset, </> frame step, [/] chapters, B bookmark, ? help overlay), and each pane lights up as its data arrives (nothing shifts layout when diarization lands late). Wheel means volume over the video (shift = seek, alt = speed) and zoom over the band. Internals live in `src/lib/video/` (band/keys/rate/deepLink/settings + contracts for audio/night/presence — see that README; gap audit vs the extension: `VIDEO-PLAYER-GAP-AUDIT.md`). | `src`, `chapters?`, `speakers?`, `transcript?`, `bookmarks?`, `waveform?`, `talkTime?`, `startAt?`, `poster?`, `captionsSrc?`, `crossorigin?` (`'anonymous'` — what frame-reading features need), `syncUrlTime?` (`?t=` deep-link, opt-in), `transcriptPosition?` (`'below' \| 'side'`), `onTimeUpdate?`, `onAddBookmark?`, `onBookmarkContext?` |
@@ -134,6 +139,8 @@ import { loadLiveKit, isLiveKitAvailable, LiveKitNotInstalledError } from 'jatui
 |-----------|---------|-----------|
 | `ResizablePanel` | Resizable container | `minWidth`, `maxWidth`, `defaultWidth` |
 | `ResizableDivider` | Drag handle between panels | `onResize` |
+| `InfiniteGrid` | Cursor-paged infinite-scroll grid (from chimaro). `loadMore(cursor, {signal})` resolves `{items, nextCursor, total?}` (`nextCursor: null` = end); cells render through the `renderItem(item, i)` snippet. Change `resetKey` to start over — the in-flight page is aborted and a late page for the old key is dropped. One request in flight; items de-duped by `getKey`; short pages auto-chain until the sentinel leaves the screen; distinct skeleton / empty / exhausted / error(+Retry) states; non-item rows are `overflow-anchor: none` so scroll anchoring can't runaway-load. Scroll root = `root` or nearest scrollable ancestor. Exposes `reset()`/`retry()`. Not virtualized. Pure core: `createInfiniteLoader`. | `loadMore`, `renderItem` (snippet), `getKey?`, `resetKey?`, `columns?` / `minItemWidth?`, `gap?`, `root?`, `loadAhead?` (400px), `skeleton?`/`empty?`/`end?`/`error?` (snippets), `emptyText?`, `endText?`, `onStateChange?` |
+| `InfiniteSearchGrid` | Search box + `InfiniteGrid`. Query is debounced, then becomes the grid's `resetKey` (Enter commits now, Escape clears). Below `minQueryLength` no request is made and `prompt` shows. All other `InfiniteGrid` props pass through. | `search(query, cursor, {signal})`, `renderItem` (snippet), `query` (bindable), `debounceMs?` (300), `minQueryLength?` (0), `placeholder?`, `noResultsText?`/`noResults?`, `prompt?`/`promptText?`, `toolbar?` (snippet) |
 | `SectionNav` | Sticky in-page section index for long single-column pages — vertical rail beside the content on xl+, wrapping chip row above it below xl. Built-in scroll-spy (omit `activeId` and it just works; `bind:activeId` to observe/control — the spy writes back to it): on every observer callback + rAF-throttled scroll/resize it measures ALL sections and activates the last one whose top is at/above the activation line (`activationRatio`, default 0.3 of the scroller height); at the bottom of the page the last section wins. Clicking an item activates it immediately and holds the spy off until the smooth scroll lands (`scrollend`, or 800ms after the last scroll event); reduced-motion scrolls instantly. Pure decision fn exported as `computeActiveSection(rects, viewport, scroll, ratio?)`. Amber dot per `dirtyIds` marks sections holding unsaved edits. `go()` scrolls AND moves focus so keyboard/SR users land where the click did. j/k/Enter via `listNav`. Layout contract: parent is a `flex flex-wrap gap-8 items-start` row, content column `flex-1 min-w-0`; sections need `id` + `scroll-mt-*`. | `sections: {id,label}[]`, `activeId?` (bindable), `dirtyIds?: Set<string>`, `ariaLabel?`, `spy?`, `activationRatio?` (0.3) |
 
 ### Audio & Voice
@@ -195,7 +202,26 @@ const callbacks: AnnotationCallbacks = {
 
 | Component | Purpose | Key Props |
 |-----------|---------|-----------|
-| `KeyboardShortcutsOverlay` | `?`-triggered modal listing keyboard shortcuts. Ignores typing targets and Ctrl/Meta/Alt combos. Supports a flat `shortcuts` list or grouped `sections` with optional per-key color tinting. | `shortcuts?: KeyboardShortcut[]`, `sections?: KeyboardShortcutSection[]`, `title?`, `open` (bindable) |
+| `KeyboardShortcutsOverlay` | `?`-triggered modal listing keyboard shortcuts. Ignores typing targets and Ctrl/Meta/Alt combos. Supports a flat `shortcuts` list, grouped `sections` with optional per-key color tinting, or a shortcut `registry` (lists what can fire right now, and pushes a modal context while open so page shortcuts don't fire behind it). Precedence: `sections` > `registry` > `shortcuts`. | `shortcuts?: KeyboardShortcut[]`, `sections?: KeyboardShortcutSection[]`, `registry?: ShortcutRegistry`, `title?`, `open` (bindable) |
+
+**Shortcut registry** (`createShortcutRegistry()`, or the lazy `getShortcutRegistry()` singleton) — the data source for the overlay, so apps stop hand-wiring a keydown handler plus a separate list for the overlay. Shortcuts register against a **context** and return an unregister fn (return it from `$effect`). Contexts form a stack: `global` is the bottom, `pushContext(name, { modal?, label? })` returns a pop fn, the top context shadows the same combo lower down, and a `modal` context suppresses everything beneath it (including `global`). Handled for you: no firing while typing in text inputs/textarea/select/contenteditable (opt in per shortcut with `allowInInput`), IME composition and `defaultPrevented` events are skipped, `mod` = ⌘ on macOS / Ctrl elsewhere, exact modifier matching (`?` doesn't need `shift`), and macOS Option combos fall back to `event.code`. Per shortcut: `enabled()`, `allowRepeat`, `preventDefault`, `group` (overlay section), `hidden`, `label` (keycap override).
+
+```svelte
+<script>
+  import { createShortcutRegistry, KeyboardShortcutsOverlay, SIDEBAR_TOGGLE_KEY } from "jatui"
+  const shortcuts = createShortcutRegistry({ contextLabels: { list: "Task list" } })
+  $effect(() => shortcuts.attach())                       // keydown on window
+  $effect(() => shortcuts.pushContext("list"))
+  $effect(() => shortcuts.register([
+    { key: "j", description: "Next", context: "list", action: next },
+    { key: "mod+k", description: "Search", action: openPalette, allowInInput: true },
+    { key: SIDEBAR_TOGGLE_KEY, description: "Toggle sidebar", action: toggleSidebar },
+  ]))
+</script>
+<KeyboardShortcutsOverlay registry={shortcuts} />
+```
+
+**Sidebar convention: `SIDEBAR_TOGGLE_KEY` = `mod+\`** (Ctrl+\ / ⌘\). Do NOT use Ctrl+B: Chrome reserves it (bookmarks bar). Also avoid Ctrl+T/W/N, which the browser keeps. The overlay owns `?`, so don't register it. Helpers: `formatShortcut(def | "mod+k", platform?)` → `⌘K` / `Ctrl+K`, `isTypingTarget(el)`, `parseShortcutCombo`, `detectShortcutPlatform`.
 
 ### Maps (Google Maps)
 
@@ -258,6 +284,20 @@ import { qrMatrix, qrCanvas } from "jatui"                            // deep-li
 import { createHistory, pushState, undo, redo, beginChange, endChange, untracked, clearHistory, MAX_UNDO_DEPTH } from "jatui"
 import type { History } from "jatui"
 
+// Batch/queue primitives (jatui-m4uz3.7) — companions to BatchJobTable.
+import { useElapsedEstimate } from "jatui"   // rune: eta.record(ms); eta.remainingMs(queued, runningElapsed, concurrency)
+import { pollOperation, PollTimeoutError } from "jatui"
+// await pollOperation(async ({ signal, attempt }) => op.done ? { done: true, value } : { done: false, progress },
+//   { intervalMs, timeoutMs, backoff, signal, onProgress })  — rejects on timeout / abort / thrown check
+import { formatElapsed, rollingAverage, estimateRemainingMs } from "jatui"
+
+// Variant combination algebra (jatui-m4uz3.8) — pure functions behind VariantMatrixPicker.
+import { generateCombinations, countCombinations, type VariantCategory, type VariantSelection } from "jatui"
+// VariantCategory — { id, label, icon?, mode?: 'multiplicative' | 'additive', options: VariantOption[] }
+// VariantOption   — { id, label, prompt? }
+// VariantSelection — { [categoryId]: string[] }  (selected option ids per category)
+// generateCombinations(categories, selected, { forceMode? }) → [{ modifierIds, prompt, options }]
+
 // Date formatting
 import { formatRelativeTime, formatDate, formatShortDate, formatDateTime } from "jatui"
 

package/dist/actions/reveal.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Scroll-reveal action — reveals an element the first time it scrolls into
+ * the viewport (IntersectionObserver, fires once, then unobserves).
+ *
+ * Ported from chimaro's `use:reveal` (jatui-m4uz3.3). The public API is kept
+ * chimaro-compatible (animation / delay / threshold) so chimaro's local copy
+ * is deletable in favor of this import — but the animista.css dependency is
+ * NOT shipped: each named variant remaps onto a `jatui-reveal-*` class in
+ * `jatui/styles/motion.css`, whose keyframes and timing are built entirely
+ * from the `--motion-*` tokens.
+ *
+ * Usage:
+ *   <div use:reveal>                                → fade-in-bottom on scroll
+ *   <div use:reveal={{ animation: 'scale-in-center' }}>
+ *   <div use:reveal={{ delay: 0.2 }}>               → 200ms staggered delay
+ *   <div use:reveal={{ threshold: 0.3 }}>           → triggers at 30% visibility
+ *
+ * Note: `delay` is in SECONDS (chimaro's contract — CSS animation-delay
+ * units), unlike staggerEntrance's ms-based options. Use fractional values
+ * for staggers (0.2 = 200ms).
+ */
+export type RevealVariant = 'fade-in' | 'fade-in-bottom' | 'fade-in-top' | 'fade-in-left' | 'fade-in-right' | 'scale-in-center';
+export interface RevealOptions {
+    /** Named entrance variant, rendered by a `jatui-reveal-*` class in motion.css. Default 'fade-in-bottom'. */
+    animation?: RevealVariant;
+    /** Delay in SECONDS before the entrance runs (fill mode holds the from-state during the wait). Default 0. */
+    delay?: number;
+    /** Fraction of the element that must be visible before revealing (0–1). Default 0.1. */
+    threshold?: number;
+}
+/** Class applied while the element is waiting to be revealed (opacity: 0). */
+export declare const REVEAL_HIDDEN_CLASS = "jatui-reveal-hidden";
+/** Base class carrying the token-driven duration/easing/fill. */
+export declare const REVEAL_BASE_CLASS = "jatui-reveal";
+export declare function reveal(node: HTMLElement, options?: RevealOptions): {
+    destroy(): void;
+};

package/dist/actions/reveal.js

@@ -0,0 +1,42 @@
+/** Class applied while the element is waiting to be revealed (opacity: 0). */
+export const REVEAL_HIDDEN_CLASS = 'jatui-reveal-hidden';
+/** Base class carrying the token-driven duration/easing/fill. */
+export const REVEAL_BASE_CLASS = 'jatui-reveal';
+function variantClass(animation) {
+    return `${REVEAL_BASE_CLASS}-${animation}`;
+}
+export function reveal(node, options) {
+    const animation = options?.animation ?? 'fade-in-bottom';
+    const threshold = options?.threshold ?? 0.1;
+    // Respect prefers-reduced-motion: skip the animation entirely, show content.
+    const prefersReducedMotion = typeof window !== 'undefined' &&
+        window.matchMedia?.('(prefers-reduced-motion: reduce)').matches;
+    // No window (SSR) or no IntersectionObserver: stay visible, do nothing.
+    const canObserve = !prefersReducedMotion &&
+        typeof window !== 'undefined' &&
+        typeof IntersectionObserver !== 'undefined';
+    if (!canObserve) {
+        return { destroy() { } };
+    }
+    node.classList.add(REVEAL_HIDDEN_CLASS);
+    if (options?.delay) {
+        node.style.animationDelay = `${options.delay}s`;
+    }
+    const observer = new IntersectionObserver((entries) => {
+        for (const entry of entries) {
+            if (entry.isIntersecting) {
+                node.classList.remove(REVEAL_HIDDEN_CLASS);
+                node.classList.add(REVEAL_BASE_CLASS, variantClass(animation));
+                observer.unobserve(node);
+            }
+        }
+    }, { threshold });
+    observer.observe(node);
+    return {
+        destroy() {
+            observer.disconnect();
+            node.classList.remove(REVEAL_HIDDEN_CLASS, REVEAL_BASE_CLASS, variantClass(animation));
+            node.style.animationDelay = '';
+        },
+    };
+}