@joewinke/jatui 0.1.23 → 0.1.24

package/CLAUDE.md

@@ -0,0 +1,244 @@
+# jatui — Shared Svelte 5 + DaisyUI Component Library
+
+Reusable UI components extracted from JAT projects. Svelte 5 runes syntax, DaisyUI + Tailwind CSS v4.
+
+## Setup
+
+```bash
+npm install ../jatui    # or "file:../jatui" in package.json
+```
+
+Then import:
+```svelte
+<script>
+  import { SearchDropdown, Button, Modal } from "jatui"
+</script>
+```
+
+## Component Catalog
+
+### Form Inputs
+
+| Component | Purpose | Key Props |
+|-----------|---------|-----------|
+| `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` |
+| `ChipInput` | Tag/chip entry with suggestions | `chips` (bindable), `suggestions: SuggestionGroup[]`, `placeholder` |
+| `SearchDropdown` | Searchable dropdown with grouped results | `groups: SearchDropdownGroup[]`, `placeholder`, `onSelect` |
+| `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` |
+| `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[]` |
+| `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?` |
+| `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` |
+
+### Scheduling & Time
+
+| Component | Purpose | Key Props |
+|-----------|---------|-----------|
+| `CalendarPicker` | Month calendar with day selection | `selectedDate` (bindable), `availabilityCounts`, `onDateSelect` |
+| `DateRangePicker` | Start/end date range | `selectedRange` (bindable), `onRangeChange` |
+| `TimeSlotPicker` | Time slot grid selector | `slots: TimeSlot[]`, `selectedSlot` (bindable), `onSlotSelect` |
+| `AvailabilityModal` | Date override editor (modal) | `date`, `overrides`, `onSave`, `onClose` |
+| `BookingForm` | Guest info form for booking | `onSubmit`, `submitting`, `requirePhone`, `accentColor`, `showAttendeeOption` |
+| `CountdownTimer` | Countdown to target date | `targetDate: Date`, `label` |
+
+### Display & Feedback
+
+| Component | Purpose | Key Props |
+|-----------|---------|-----------|
+| `Button` | Styled button with variants | `variant`, `size`, `loading`, `disabled`, `onclick` |
+| `Badge` | Status/label badge | `variant`, `size`, `children` (snippet) |
+| `StatusBadge` | Status indicator with dot | `status: StatusValue`, `label` |
+| `Card` | Content card container | `title`, `children` (snippet) |
+| `Modal` | Dialog overlay | `open` (bindable), `title`, `children` (snippet) |
+| `ConfirmModal` | Yes/no confirmation dialog | `open` (bindable), `title`, `message`, `onConfirm`, `onCancel` |
+| `Drawer` | Slide-out side panel | `open` (bindable), `side`, `children` (snippet) |
+| `LoadingSpinner` | Spinner animation | `size`, `color` |
+| `Sparkline` | Inline mini chart | `data: number[]`, `width`, `height`, `color` |
+| `LazyImage` | Image with lazy loading + placeholder | `src`, `alt`, `placeholder` |
+| `HunkDiffView` | Side-by-side diff with line numbers, red/green backgrounds, strikethrough on removed lines, inline word-level highlights via the `diff` lib. Used for reviewing YAML/text changes per hunk. | `oldText: string \| null`, `newText: string \| null`, `unified?: boolean` |
+
+### Media
+
+| Component | Purpose | Key Props |
+|-----------|---------|-----------|
+| `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?` |
+
+### Layout
+
+| Component | Purpose | Key Props |
+|-----------|---------|-----------|
+| `ResizablePanel` | Resizable container | `minWidth`, `maxWidth`, `defaultWidth` |
+| `ResizableDivider` | Drag handle between panels | `onResize` |
+
+### Audio & Voice
+
+| Component | Purpose | Key Props |
+|-----------|---------|-----------|
+| `AudioWaveform` | Audio waveform visualizer | `audioUrl`, `isPlaying` |
+| `VoicePlayer` | Audio playback with controls | `src`, `autoplay` |
+| `SpeechForm` | Voice-to-text form input | `onTranscript` |
+
+### PDF
+
+| Component | Purpose | Key Props |
+|-----------|---------|-----------|
+| `PDFViewer` | Server-rendered PDF viewer — pages rendered as `<img>` via PDFium WASM (no client pdf.js). Cache-first: rendered PNGs stored in MinIO. Requires host app to expose pdf-info + pdf-page API routes (JST provides `/api/files/[id]/pdf-info` and `/api/files/[id]/pdf-page/[page]`). | `fileId`, `fileName`, `pdfUrl` (raw PDF URL for Open/Download), `infoUrl?` (custom info endpoint), `pageUrlTemplate?` (custom page template with `{page}` and `{scale}` placeholders) |
+
+**Usage (JST default routes):**
+```svelte
+<PDFViewer fileId={file.id} fileName={file.fileName} pdfUrl="/api/files/{file.id}?download=1" />
+```
+
+**Server-side setup (JST):** `src/lib/server/pdfToImage.ts` + routes at `/api/files/[id]/pdf-info` and `/api/files/[id]/pdf-page/[page]`. Requires `@hyzyla/pdfium`, `unpdf`, `sharp` in host app.
+
+### Document Annotation Suite
+
+| Component | Purpose | Key Props |
+|-----------|---------|-----------|
+| `MarkupEditor` | Fullscreen canvas markup tool — draw arrows, boxes, ellipses, revision clouds, freehand, text over an image | `imageUrl`, `initialShapes?: MarkupShape[]`, `onsave: (shapes) => void`, `oncancel: () => void` |
+| `MarkupOverlay` | Read-only canvas layer that renders saved `MarkupShape[]` over an image | `shapes: MarkupShape[]`, `imageUrl` |
+| `ImageLightbox` | Inline image viewer with fullscreen modal, zoom controls, optional markup + annotation overlays | `imageUrl`, `filename?`, `markupShapes?`, `annotations?`, `activeAnnotationId?`, `annotationMode?`, `onAnnotationClick?`, `onImageClick?`, `onClose?` |
+| `AnnotationLayer` | Absolute-positioned pin overlay — renders threaded annotation pins at `x_percent`/`y_percent` coordinates | `annotations: Annotation[]`, `activeAnnotationId?`, `annotationMode?`, `showResolved?`, `onAnnotationClick?`, `onImageClick?` |
+| `AnnotationPanel` | Sidebar thread list for annotations — reply, resolve, edit, delete. Uses callback props for async ops. | `annotations`, `profiles`, `activeAnnotationId?`, `currentUserId`, `callbacks: AnnotationCallbacks`, `onAnnotationSelect?`, `onAnnotationsChanged?` |
+
+**Types & utilities:**
+```typescript
+import type { MarkupShape, MarkupTool, Point, Annotation, AnnotationProfile, AnnotationCallbacks } from "jatui"
+import { MARKUP_COLORS, DEFAULT_STROKE_WIDTH, renderShape, renderAllShapes, nextShapeId } from "jatui"
+```
+
+**Usage pattern** — `AnnotationPanel` is decoupled from HTTP: pass an `AnnotationCallbacks` object:
+```typescript
+const callbacks: AnnotationCallbacks = {
+  onAddReply: async (parentId, content) => { /* POST /api/.../annotations */ },
+  onResolve:  async (id, resolved)     => { /* PATCH */ },
+  onDelete:   async (id)               => { /* DELETE */ },
+  onEdit:     async (id, content)      => { /* PATCH */ },
+}
+```
+
+**`MarkupShape` is JSON-serializable** — store in a JSONB column and pass back as `initialShapes`.
+
+### Theme
+
+| Component | Purpose | Key Props |
+|-----------|---------|-----------|
+| `ThemeSelector` | DaisyUI theme switcher with preview dots | `themes`, `defaultTheme`, `dropUp`, `storageKey`, `onThemeChange` |
+
+### Keyboard Navigation
+
+| 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) |
+
+### Maps (Google Maps)
+
+Require a `PUBLIC_GOOGLE_MAPS_API_KEY` env var passed explicitly (no SvelteKit `$env` dependency in jatui).
+
+| Component | Purpose | Key Props |
+|-----------|---------|-----------|
+| `MapView` | Multi-marker dispatch map — job pins (colored by status) + agent avatars with GPS or active-job fallback position. Auto-fits bounds. | `apiKey`, `jobs?: MapJob[]`, `agents?: MapAgent[]`, `defaultCenter?`, `showLegend?`, `onJobClick?`, `onAgentClick?` |
+| `LocationMap` | Single-location embed with pulsing dot + accuracy circle. Shows "Waiting for GPS signal…" while no coords. | `apiKey`, `latitude?`, `longitude?`, `accuracy?`, `showAccuracyCircle?`, `height?` |
+| `GPSTracker` | Headless GPS tracker — watches device position, fires `onLocationUpdate(pos)` on each fix. Host app sends coords to server. Mobile: `watchPosition`; desktop: interval polling. Renders a small fixed status indicator. | `enabled?`, `updateInterval?`, `onLocationUpdate?`, `onError?` |
+
+**MapView types:**
+```typescript
+import type { MapJob, MapAgent } from 'jatui'
+// MapJob — id, status, type?, customer?, location? (address/lat/lng)
+// MapAgent — id, name, email?, avatarUrl?, status?, location? (lat/lng/age_seconds), dispatches?
+```
+
+**Google Maps loader (util):**
+```typescript
+import { loadGoogleMapsAPI, isGoogleMapsLoaded } from 'jatui'
+await loadGoogleMapsAPI({ apiKey, libraries: ['marker', 'geometry'] })
+```
+
+## Utilities
+
+```typescript
+// Date formatting
+import { formatRelativeTime, formatDate, formatShortDate, formatDateTime } from "jatui"
+
+// Task age — color-coded staleness indicator for task rows
+// Returns { label: "3d", color: "oklch(...)" } — green→blue→amber→orange→red
+import { taskAge } from "jatui"
+
+// Task display helpers (project_tasks domain)
+import { statusColor, priorityColor, typeIcon, statusLabel } from "jatui"
+// statusColor(status)   → DaisyUI badge class ("badge-info", "badge-warning", ...)
+// priorityColor(priority) → Tailwind text class ("text-error font-bold", ...)
+// typeIcon(type)        → emoji ("🐛", "✨", "📋", "🏔️", "📄")
+// statusLabel(status)   → "in_progress" → "In Progress"
+
+// Phone formatting
+import { formatPhoneNumber, isValidPhoneNumber } from "jatui"
+
+// Currency
+import { formatCurrency } from "jatui"
+
+// DaisyUI color access (for Canvas/JS)
+import { getDaisyUIColor, isDarkTheme, getCurrentTheme } from "jatui"
+```
+
+## Types
+
+```typescript
+// Component types
+import type {
+  SearchDropdownOption, SearchDropdownGroup,
+  ChipSuggestion, SuggestionGroup, ChipInfo,
+  SortOption, SelectOption, StatusValue,
+  DisplaySegment
+} from "jatui"
+
+// Booking types (from src/lib/types/booking.ts)
+import type {
+  LocationType, BookingStatus, OverrideType,
+  Host, EventType, WeeklyAvailability, DateOverride,
+  Booking, BookingAttendee, TimeSlot, BookingFormData,
+  AvailabilityCounts
+} from "jatui"
+
+// Booking constants
+import { DAYS_OF_WEEK, DAYS_SHORT, LOCATION_LABELS, LOCATION_ICONS } from "jatui"
+
+// FileDropzone types
+import type { FileDropzoneFile } from "jatui"
+// FileDropzoneFile — { file?: File, name, mimeType, size?, url?, meta? }
+
+// SmartImageEditor types
+import type {
+  ImageProcessingSpec, ImageVariantSpec,
+  VariantResult, VariantState
+} from "jatui"
+// ImageProcessingSpec — { removeBackground?, aspectRatio?, variants: ImageVariantSpec[] }
+// ImageVariantSpec    — { name, width, height, fit?, background? }
+// VariantResult       — { name, url, width, height, backgroundRemovalFailed? }
+// VariantState        — union: idle | loading | done (VariantResult) | error (message)
+```
+
+## Live Demos
+
+If the project uses JST (Joe's Software Template), browse component demos at `/components/{component-name}` (kebab-case).
+
+## Notes for Agents
+
+- All components use **Svelte 5 runes** (`$state`, `$derived`, `$props`, `$bindable`)
+- All components use **DaisyUI classes** (not custom CSS) — they inherit the project's theme
+- Bindable props use `$bindable()` — bind with `bind:value={myVar}`
+- Check the component source in `src/lib/components/` for full prop types
+- Prefer jatui components over building custom ones when there's a match
+
+# Accessibility (a11y)
+
+@~/code/jat/shared/a11y-patterns.md

package/package.json

@@ -1,38 +1,51 @@
 {
   "name": "@joewinke/jatui",
-  "version": "0.1.23",
+  "version": "0.1.24",
   "private": false,
   "description": "Shared Svelte 5 component library for JAT projects",
   "type": "module",
-  "svelte": "./src/lib/index.ts",
-  "types": "./src/lib/index.ts",
+  "svelte": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "types": "./src/lib/index.ts",
-      "svelte": "./src/lib/index.ts",
-      "default": "./src/lib/index.ts"
-    }
+      "types": "./dist/index.d.ts",
+      "svelte": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./styles/rail.css": "./dist/styles/rail.css"
   },
   "files": [
-    "src/lib"
+    "dist",
+    "CLAUDE.md",
+    "README.md"
   ],
   "scripts": {
     "dev": "vite dev --port 5180",
     "build": "vite build",
-    "preview": "vite preview"
+    "preview": "vite preview",
+    "package": "svelte-package --input src/lib --output dist"
   },
   "peerDependencies": {
     "d3": "^7.0.0",
-    "svelte": "^5.0.0"
+    "daisyui": "^5.0.0",
+    "svelte": "^5.0.0",
+    "tailwindcss": "^4.0.0"
   },
   "peerDependenciesMeta": {
     "d3": {
       "optional": true
+    },
+    "daisyui": {
+      "optional": false
+    },
+    "tailwindcss": {
+      "optional": false
     }
   },
   "devDependencies": {
     "@sveltejs/adapter-auto": "^6.0.0",
     "@sveltejs/kit": "^2.21.0",
+    "@sveltejs/package": "^2.5.8",
     "@sveltejs/vite-plugin-svelte": "^5.0.0",
     "@tailwindcss/vite": "^4.0.0",
     "@types/d3": "^7.4.3",

package/src/lib/actions/collapse.ts

@@ -1,136 +0,0 @@
-/**
- * Tall-content collapse — Svelte action.
- *
- * Caps an arbitrarily-tall block at a max height with a fade-out gradient so it
- * shows a preview instead of overflowing its container. The consumer renders the
- * "Show more / Show less" toggle and owns the `expanded` boolean; the action does
- * the measuring and applies the collapse styling.
- *
- * Why an action (not a wrapper-only component): most adoption sites are existing
- * elements (`<p>`, a `prose` div, a `<ul>`, a `<pre>`), and an action attaches
- * with zero DOM restructuring. A batteries-included `<Collapse>` wrapper that
- * uses this action is also provided for greenfield use.
- *
- * ─── Why inline styles, not a CSS class ───────────────────────────────────────
- *
- * The action writes `max-height` / `overflow` / `mask-image` directly on the node
- * when collapsed. That means it needs NO accompanying stylesheet — it works
- * identically in Tailwind-utility components and scoped-CSS components, and
- * consumers don't have to copy a `.collapse-*` rule into their app.css (the same
- * trap rail.css has). Expanding clears the inline styles.
- *
- * ─── Why ResizeObserver, not a one-shot rAF ───────────────────────────────────
- *
- * Streaming chat answers and `{@html}` markdown bodies grow AFTER mount. A
- * one-shot measurement on mount would miss them (and would wrongly hide the
- * toggle on content that hasn't streamed in yet). A ResizeObserver re-measures
- * whenever the content's natural height changes, so `collapsible` stays correct.
- *
- * `scrollHeight` reports the FULL content height even while `max-height` +
- * `overflow:hidden` are applied, so the action can keep measuring without ever
- * having to un-collapse first.
- *
- * ─── Usage — action form (most sites) ─────────────────────────────────────────
- *
- *   <script>
- *     import { collapse } from 'jatui'
- *     let collapsible = $state(false)
- *     let expanded = $state(false)
- *   </script>
- *
- *   <div use:collapse={{ expanded, onCollapsible: (c) => (collapsible = c) }}>
- *     {content}
- *   </div>
- *   {#if collapsible}
- *     <button onclick={() => (expanded = !expanded)}>
- *       {expanded ? 'Show less ↑' : 'Show more ↓'}
- *     </button>
- *   {/if}
- *
- * For mapped lists, give each row its own `expanded` / `collapsible` state
- * (e.g. a `SvelteSet` of ids) — one action instance attaches per row element.
- */
-
-export interface CollapseOptions {
-	/** Max collapsed height in px. Content taller than this collapses. Default 120. */
-	threshold?: number;
-	/** Controlled expand state. When true, the node is never collapsed. Default false. */
-	expanded?: boolean;
-	/** Where the fade-to-transparent begins, as a %. Default 55. */
-	fadeStart?: number;
-	/** Slack (px) added to the threshold so a near-fit doesn't toggle. Default 4. */
-	epsilon?: number;
-	/**
-	 * Called whenever collapsibility changes (content crosses the threshold).
-	 * Drive the toggle button's visibility from this — it self-hides when the
-	 * content is shorter than the threshold.
-	 */
-	onCollapsible?: (collapsible: boolean) => void;
-}
-
-const DEFAULTS = { threshold: 120, expanded: false, fadeStart: 55, epsilon: 4 } as const;
-
-export function collapse(node: HTMLElement, options: CollapseOptions = {}) {
-	let opts = { ...DEFAULTS, ...options };
-	let collapsible = false;
-	let rafId = 0;
-	let applied = false;
-
-	function gradient() {
-		return `linear-gradient(to bottom, black ${opts.fadeStart}%, transparent 100%)`;
-	}
-
-	function apply() {
-		const shouldCollapse = collapsible && !opts.expanded;
-		if (shouldCollapse === applied) return; // idempotent — avoids RO feedback loops
-		applied = shouldCollapse;
-		if (shouldCollapse) {
-			node.style.maxHeight = `${opts.threshold}px`;
-			node.style.overflow = 'hidden';
-			node.style.maskImage = gradient();
-			node.style.webkitMaskImage = gradient();
-		} else {
-			node.style.maxHeight = '';
-			node.style.overflow = '';
-			node.style.maskImage = '';
-			node.style.webkitMaskImage = '';
-		}
-	}
-
-	function measure() {
-		// scrollHeight is the full content height even while collapsed.
-		const next = node.scrollHeight > opts.threshold + opts.epsilon;
-		if (next !== collapsible) {
-			collapsible = next;
-			opts.onCollapsible?.(collapsible);
-		}
-		apply();
-	}
-
-	function scheduleMeasure() {
-		cancelAnimationFrame(rafId);
-		rafId = requestAnimationFrame(measure);
-	}
-
-	// Re-measure when the content's natural size changes (streaming, {@html}, lazy images).
-	const ro = new ResizeObserver(scheduleMeasure);
-	ro.observe(node);
-
-	scheduleMeasure();
-
-	return {
-		update(next: CollapseOptions = {}) {
-			opts = { ...DEFAULTS, ...next };
-			// expanded/threshold/fade may have changed — re-measure and let
-			// apply() compare the freshly computed shouldCollapse against the
-			// real last-applied state. (Force-flipping `applied` here used to make
-			// that comparison spuriously match on a plain expand/collapse toggle,
-			// silently skipping the style update.)
-			scheduleMeasure();
-		},
-		destroy() {
-			cancelAnimationFrame(rafId);
-			ro.disconnect();
-		},
-	};
-}