@joewinke/jatui 0.42.0 → 0.44.0

package/CLAUDE.md

@@ -21,7 +21,8 @@ Then import:
 
 | Component | Purpose | Key Props |
 |-----------|---------|-----------|
-| `TextInput` | Text input with label, error, icon slots | `label`, `value` (bindable), `placeholder`, `error`, `disabled` |
+| `TextInput` | Text input with label, error, help, count, floating label. `leading`/`trailing` snippets put an icon or addon ("https://", "kg", a clear button) inside the field — the DaisyUI `input` skin moves to a wrapper and the error shake follows it. `labelTooltip` adds an info button after the label (shared `use:tooltip`). Label and help/error lines are the exported `FieldLabel` / `FieldHint`. | `label`, `value` (bindable), `placeholder`, `error`, `helpText`, `disabled`, `leading?`/`trailing?` (snippets), `labelTooltip?`, `floatingLabel?` |
+| `FieldLabel` / `FieldHint` | The label row and help/error line TextInput uses, exported so custom controls (selects, PhoneInput, your own) line up identically. FieldLabel: `required` asterisk, `tooltip` info button (24px target, keyboard-focusable, rendered outside the `<label>` so it never focuses the input); with no tooltip it renders the exact bare `<label class="label">` TextInput always had. FieldHint: `error` → error tone + `role="alert"`. | FieldLabel: `for`, `text`, `required?`, `tooltip?`, `tooltipLabel?`, `children?` · FieldHint: `id`, `text`, `error?` |
 | `TextArea` | Multiline text input. Auto-grow (`autoResize`, or implied by `maxRows`) grows a whole line at a time from `minRows` (default `rows`) to `maxRows`, then scrolls — CSS `field-sizing: content` where supported, row-quantized JS fallback (`textareaRowsHeight`) elsewhere. | `label`, `value` (bindable), `placeholder`, `rows`, `minRows?`, `maxRows?`, `autoResize?`, `error`, `maxlength` |
 | `SelectInput` | Dropdown select | `label`, `value` (bindable), `options: SelectOption[]`, `placeholder` |
 | `SegmentedControl` | Single-select toggle group that SETS A VALUE (Tabs switch panels): `role="radiogroup"` + `role="radio"`, roving tabindex, arrows move AND select, Home/End, disabled options skipped; sliding thumb on motion tokens (jumps under reduced motion). `solid` (track + raised thumb) or `plain`. Options may be plain strings. | `options: (SegmentedOption \| string)[]`, `value` (bindable), `size?` (`xs\|sm\|md`), `variant?`, `fullWidth?`, `disabled?`, `ariaLabel?`, `option?` (snippet), `onChange?` |
@@ -38,8 +39,14 @@ Then import:
 | `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?` |
+| `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. Pass `progress` (0–100) to draw upload progress on the zone's own border (dashed border cross-fades into a primary stroke that fills clockwise, plus a sliding `%` badge; `role="progressbar"`, no layout shift, reduced-motion/calm gated). | `accept?: string[]`, `maxSize?`, `maxFiles?`, `multiple?`, `uploadedFiles?`, `isUploading?`, `isExtracting?`, `progress?`, `progressLabel?`, `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?` |
+| `Checkbox` | Native checkbox with label, indeterminate, variants and a 24px target. `animated` draws the box with the shared `CheckGlyph` and draws the tick on (`--motion-fast` × `--motion-glide`, `pathLength=1` dashoffset) when the user checks it — never on load; the native input stays in the DOM, visually hidden. | `checked` (bindable), `label`, `size`, `variant`, `indeterminate`, `animated?`, `onchange` |
+| `CheckboxCard` | Whole-card checkbox: title + description (+ `icon` snippet) on a `ChoiceCard`, animated `CheckGlyph` tick, description wired as `aria-describedby`. Selected = primary border + 6% tint, flat at rest. | `checked` (bindable), `title`, `description?`, `icon?`, `indeterminate?`, `disabled?`, `name?`, `value?`, `size?` (`sm`\|`md`), `variant?`, `controlPosition?` (`start`), `animated?` (true), `onchange?` |
+| `SwitchCard` | Settings row where the whole card toggles a `role="switch"` (DaisyUI `toggle`, motion-token spring). No selected tint — on/off is a setting, not a pick. | `checked` (bindable), `title`, `description?`, `icon?`, `disabled?`, `size?`, `variant?`, `controlPosition?` (`end`), `onchange?` |
+| `RadioGroup` | Native radio group (arrow keys rove natively). `display="card"` renders each option as a `ChoiceCard` with `description`/`icon` per option; `label` names the group. | `value` (bindable), `options: RadioOption[]` (`{value, label, description?, icon?, disabled?}`), `name`, `display?` (`default`\|`card`), `orientation?`, `label?`, `controlPosition?`, `variant`, `size` |
+| `ChoiceCard` / `CheckGlyph` | The shared pieces: ChoiceCard is the `<label>` card shell (pass any native control as the `control` snippet; checked/focus/disabled styling reads the control via `:has()`); CheckGlyph is the presentational box + draw-on tick (`aria-hidden` — pair it with a real input). | ChoiceCard: `title`, `description?`, `control` (snippet), `icon?`, `for?`, `descriptionId?`, `selectedTint?`, `controlPosition?`, `size?` · CheckGlyph: `checked`, `indeterminate`, `animate`, `size`, `variant` |
+| `Slider` | DaisyUI range. Pass a number for one thumb (unchanged markup) or a `[lo, hi]` pair for two thumbs — two stacked native ranges over one drawn track, so native keys + AT work; thumbs can't cross (`minGap`). `bubble` (`always`\|`drag`\|`none`) shows a value bubble that tracks each thumb; `formatValue` feeds the bubble, `showValue` and `aria-valuetext`. Pure helpers exported (`snapToStep`, `moveThumb`, `normalizePair`, `percentOf`, `bubbleLeft`). | `value` (bindable `number \| [number, number]`), `min`, `max`, `step`, `bubble?`, `formatValue?`, `label?`, `thumbLabels?`, `minGap?`, `showValue?`, `onchange?`, `onvaluechange?` |
 | `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
@@ -68,6 +75,8 @@ Then import:
 | `CloseButton` | The one ✕ for dialogs, drawers, sheets, toasts and lightboxes — an IconButton with a built-in X whose stroke is a true CSS pixel at every size. Modal, Drawer, BottomSheet and MediaLightbox use it. | `label?` ('Close'), `size?` ('sm'), `variant?`, `shape?` ('circle'), `tooltip?`, `onclick` |
 | `LinkButton` | Text action styled as a link: `<a>` with `href`, `<button>` without; underline on hover (or always). `external` adds new-tab + rel=noopener + an SR hint. | `href?`, `tone?` (inherit\|primary\|muted\|error), `size?`, `underline?`, `external?`, `disabled?`, `onclick?`, `children` |
 | `ProgressButton` | Multi-phase async submit button (upstreamed from the JAT IDE): walks through the **named phases** of the work (`phases: [{key,label}]` in order) instead of a blank spinner — spinner + current phase label with shimmer, a fill bar that advances to `(index+1)/N`, disabled while busy, green check-flash on `success`. Caller owns the state machine (`phase` / `success`). Renders through the shared `Button`, so `class` composes with join patterns. | `phase?` (null = idle), `phases?: Phase[]`, `idleLabel?`, `success?`, `successLabel?`, `variant?`, `size?`, `disabled?`, `type?`, `class?`, `onclick?`, `children` |
+| `Alert` | Contextual feedback (info/success/warning/error). Optional `dismissible` × button (real `<button>`, `dismissLabel`) — exits on `motionScale`, then `onClose` fires; `action` snippet for a CTA; `introDelay` (ms) enters after surrounding UI settles (reduced motion: waits, then appears instantly); `variant="card"` = vertical sidebar density (icon on top, title, text, full-width CTA). | `type`, `title`, `dismissible?`, `onClose?`, `action?` (snippet), `introDelay?`, `variant?` ('default'\|'card'), `children` |
+| `ToastHost` | Toast mount point — place once at app root; `showToast()` renders into it. `position` = `bottom-end` (default) \| `bottom-start` \| `bottom-center` \| `top-end` \| `top-start` \| `top-center` (logical start/end; top positions stack newest nearest the edge). Toasts keep pause-on-hover, drag-to-dismiss, undo countdown, collapsible `details`; add an optional `title`, `avatar` or `icon`, several `actions` (`{label, onClick, variant?: 'primary'\|'ghost'}` — legacy single `action` still works), and `showProgress` (countdown bar that pauses with the timer). Enter/exit blur is off under `data-motion="calm"` and reduced motion. `showToast({ type?, message, title?, icon?, avatar?, actions?, action?, details?, meta?, durationMs?, onUndo?, showProgress? })`. | `position?` |
 | `Badge` | Status/label badge | `variant`, `size`, `children` (snippet) |
 | `AnimatedNumber` | Number that animates to its new value. `mode='roll'` (default) is the per-digit odometer; `mode='tween'` counts from the previous value (`svelte/motion` Tween, `--motion-move` duration scaled by `data-motion`, instant under reduced motion; screen readers get the final value only). | `value`, `format?: Intl.NumberFormatOptions`, `mode?`, `duration?` (ms) |
 | `StatCard` | KPI tile: label, a value that tweens to its new number, delta chip toned by sign (success/error/neutral tokens; `invertDelta` for metrics where down is good), caption, icon tile (`tone`), info tooltip, inline SVG sparkline (no d3). `variant='footer'` moves caption + delta into a footer band; `href` makes the card a link; `loading` skeleton. A numeric `delta` is a FRACTION (0.125 → "+12.5%"). | `label`, `value`, `format?`, `animate?` (`tween\|roll\|false`), `delta?`, `deltaFormat?`, `deltaTone?`, `invertDelta?`, `caption?`, `info?`, `sparkline?: number[]`, `variant?`, `tone?`, `size?`, `href?`, `loading?`, `icon?`/`children?` (snippets) |
@@ -83,6 +92,7 @@ Then import:
 | `LoadingSpinner` | Spinner animation | `size`, `color` |
 | `Sparkline` | Inline mini chart | `data: number[]`, `width`, `height`, `color` |
 | `LazyImage` | Image with lazy loading + placeholder | `src`, `alt`, `placeholder` |
+| `ImageReveal` | Holds an image slot while the image doesn't exist yet (a logo lookup, an AI generation): a token-tinted ripple (`role="status"`, `aria-busy`) while `src` is null and while the bytes decode, then blur-to-sharp on `--motion-*` + `onReveal`. `src=''` or a failed load → calm initials from `alt` (or an image glyph) — never a broken `<img>`. Ripple is `.jatui-motion-ambient`: calm / reduced motion = static tint, instant swap. Clean-room (BoardUI's image-gen effect is Pro). Pure helpers: `imageRevealPhase`, `imageRevealInitials`. | `src` (`string \| null`), `alt`, `shape` (`square\|rounded\|circle`), `size` (`xs…xl` \| px \| CSS \| `fill`), `tone` (semantic or CSS colour), `label`, `initials?`, `fit?`, `phase` (bindable, read-only), `onReveal?(src)`, `onError?(src)`, `fallback?` (snippet) |
 | `Empty` | Zero-state surface — v1 thin copy/children block still works; pass `title` for the v2 hero layout (upstreamed from the IDE's EmptyState): named `glyph` (11 curated Heroicons), `size` (sm/md/lg), `pulse` (reduced-motion gated, tinted with `--color-primary`), `icon` snippet override, CTA `actions` snippet, `description`, extra `children` below. | `title` (opts into v2), `description`, `glyph`, `size`, `pulse`, `icon`/`actions` (snippets), `copy`, `class`, `children` |
 | `ErrorState` | Standard "this failed" surface (upstreamed from the IDE's ErrorState) — error-token themed icon, optional Retry button, extra `actions`, collapsible `details` block for raw error output. Centered card mirroring `Empty` v2. | `title`, `message`, `details`, `retryLabel`, `onRetry`, `size`, `actions` (snippet) |
 | `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` |
@@ -164,7 +174,7 @@ Item-by-item review surfaces (MOS review-ux, design mos-z8vgx). One `VerdictOpti
 
 | 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. `removeMode` — `'hover'` (default) reveals the × on hover/focus and keeps it visible on coarse (touch) pointers (ContextMenuTrigger pattern); `'always'` pins it for touch-first flows. `gridCols` (e.g. `'grid-cols-2 sm:grid-cols-4'`) switches the strip to a responsive CSS grid with column-filling tiles. | `items: ThumbnailItem[]`, `max`, `size` (`xs\|sm\|md\|lg`), `removable`+`onRemove`, `removeMode` (`hover\|always`), `addable`+`onAdd`, `onSelect`, `gridCols`, `class`, `cell` snippet |
+| `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. `removeMode` — `'hover'` (default) reveals the × on hover/focus and keeps it visible on coarse (touch) pointers (ContextMenuTrigger pattern); `'always'` pins it for touch-first flows. `gridCols` (e.g. `'grid-cols-2 sm:grid-cols-4'`) switches the strip to a responsive CSS grid with column-filling tiles. Items take optional `progress` (0–100): an upload ring draws around the tile and a tiny % occupies the remove-× corner, cross-fading into the × at 100 (same slot, no layout shift; per-tile `role="progressbar"`). | `items: ThumbnailItem[]` (`{id, url?, alt, progress?}`), `max`, `size` (`xs\|sm\|md\|lg`), `removable`+`onRemove`, `removeMode` (`hover\|always`), `addable`+`onAdd`, `onSelect`, `gridCols`, `class`, `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, `Shift+T` toggle) and a "Talk time" legend (2+ speakers only; one voice gets no legend and no per-row name). **`kind="audio"` renders no stage**, and **`transport="band"`** (the audio default) drops the native `<video controls>` bar for a transport row on the band (play/pause, `now / total`, speed, mute + volume, fullscreen for video), so the band is the ONE timeline. **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, t theater, ? 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; a wheel/keyboard volume change also flashes a clear volume OSD — glyph, level bar and %, "Muted" at 0, opacity-only fade) and zoom over the band; Shift+wheel over the transcript steps line by line (a plain wheel over the transcript scrolls the pane natively — the page is never trapped). 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`, `kind?` (`'video' \| 'audio'`), `transport?` (`'native' \| 'band'`), `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'`), `transcriptMaxHeight?` (pane bound — default `min(40vh, 28rem)` below, the player's height beside; the active-line follow scrolls only the pane; only a gesture that actually moves the PANE pauses it — a wheel that scrolls the page doesn't — behind a "Resume following" pill, and it resumes by itself on seek / line or chapter click / play after pause / `followResumeMs` (6000) idle while playing; a hovered chapter fills its whole span in the theme accent with full-height edges), `followResumeMs?`, `theater?` (bindable — theater mode, NOT fullscreen: control-bar button + `t`, the HOST lays the page out full-width; a side transcript moves below; remembered per viewer as the `player.theater` setting via `settingsStore`, else guarded localStorage), `theaterButton?` (true), `onTheaterChange?`, `onTimeUpdate?`, `onAddBookmark?`, `onBookmarkContext?` |
@@ -484,9 +494,20 @@ if (await showConfirm({ title: "Delete?", body: warnBody, danger: true })) { ...
 
 `text-2xs` — 11px / 16px line-height / +0.01em tracking. Ships in `styles/rail.css` (already imported by JST). Standardizes the ~13 sites of `text-[10px]` / `text-[0.7rem]` micro-captions across JST routes (timestamps, hint text, footnotes). Sits between Tailwind's `text-xs` (12px) and browser-min legibility.
 
+**Type ramp** (same file): composite utilities that set size + line-height + tracking + weight in one class — `text-jatui-caption` (12/16), `text-jatui-label` (11/16, uppercase, +0.08em, 600 — the instrument label), `text-jatui-body` (14/20), `text-jatui-body-strong` (14/20, 600), `text-jatui-title` (18/24, 600), `text-jatui-display` (30/36, 700). Use one instead of stacking `text-xs font-medium tracking-wide`; colour stays with the caller.
+
+**Motion utilities** (`styles/motion.css`, all on the tokens): `.jatui-check-draw` (SVG stroke with `pathLength="1"` draws on), `.jatui-row-exit` (row slides aside then collapses — remove it on `animationend`; set `--jatui-row-h` for tall rows), `.jatui-label-out` / `.jatui-label-in` (button label swap).
+
 ## Utilities
 
 ```typescript
+// Outside-press dismissal (BoardUI wave 5). Capture-phase pointerdown outside the
+// node AND every `refs` element (trigger, portalled panel) calls onDismiss; Escape
+// too unless defaultPrevented. `enabled: false` disarms. Core is DOM-injectable.
+import { dismissOutside, createDismissOutside, isInsidePath } from "jatui"
+// <div use:dismissOutside={{ onDismiss: (e, reason) => (open = false), refs: [triggerEl], enabled: open }}>
+import type { DismissOutsideOptions, DismissReason } from "jatui"
+
 // Streaming-transcript auto-scroll (upstreamed from the JAT IDE — jatui-rl7w6.3).
 // Reader-aware follow: follows the live edge ONLY while the reader is at it;
 // upward scroll/wheel/keys/selection suspend following; coalesces sticks per

package/THIRD_PARTY_NOTICES.md

@@ -80,3 +80,17 @@ follow ideas from BoardUI's free items:
 `BarList` and `ActivityHeatmap` follow BoardUI Pro ideas built from public
 behaviour only; no Pro source was read or copied. No BoardUI images, logos or
 palettes are included.
+
+### Wave 5 — form polish (jatui-bns3w)
+
+Written fresh for Svelte 5 / DaisyUI after the behaviour of these BoardUI items:
+
+- `checkbox-glyph`, `checkbox-card` → `CheckGlyph`, `CheckboxCard`, `Checkbox animated`
+- `switch-card` → `SwitchCard`; `radio-card` → `RadioGroup display="card"`; shared shell `ChoiceCard`
+- `slider` (two thumbs, value bubbles) → `Slider`
+- `input` / `label` / `hint-text` → `FieldLabel`, `FieldHint`, `TextInput` addons
+- `file-upload` (perimeter progress) → `FileDropzone progress`, `ThumbnailGrid` item progress
+- `notification` → toast `title` / `actions` / `avatar` / `ToastHost position`
+- `announcement` → `Alert` `dismissible` / `action` / `variant="card"`
+- `utils/use-dismiss-on-outside-press` → `dismissOutside`
+- `styles/typography.css`, `styles/globals.css` (`check-draw`) → `text-jatui-*` ramp, motion utilities

package/dist/actions/dismissOutside.d.ts

@@ -0,0 +1,52 @@
+/**
+ * dismissOutside — close a popover / menu / panel when the user presses
+ * outside it.
+ *
+ *   <div use:dismissOutside={{ onDismiss: close, refs: [triggerEl] }}>…</div>
+ *
+ * - Listens to `pointerdown` in the CAPTURE phase on the document, so a
+ *   child that stops propagation can't hide the outside press, and the panel
+ *   closes before the pressed element's own click runs.
+ * - "Inside" is the node plus every element in `refs` (a trigger button, a
+ *   portalled sub-panel…). It is tested with `composedPath()`, so presses
+ *   inside shadow roots and elements removed during the press still count.
+ * - `escape: true` (default) also dismisses on Escape, unless something
+ *   earlier already called `preventDefault()` on that keydown.
+ * - `enabled: false` disarms it without tearing it down (bind it to `open`).
+ *
+ * The core is `createDismissOutside()`, framework-free and DOM-injectable
+ * for tests and non-Svelte callers.
+ *
+ * Idea after BoardUI's use-dismiss-on-outside-press (MIT © 2026 Mertcan
+ * Dundar Esmergul); the RAC-specific trigger-toggle half is not ported.
+ */
+export type DismissReason = 'outside' | 'escape';
+export interface DismissOutsideOptions {
+    /** Called on an outside press (or Escape). */
+    onDismiss: (event: Event, reason: DismissReason) => void;
+    /** More elements that count as inside — a getter is re-read per event. */
+    refs?: Array<Element | null | undefined> | (() => Array<Element | null | undefined>);
+    /** Default true. */
+    enabled?: boolean;
+    /** Also dismiss on Escape. Default true. */
+    escape?: boolean;
+    /** Which pointer event counts as a press. Default `pointerdown`. */
+    event?: 'pointerdown' | 'mousedown' | 'click';
+}
+interface EventTargetLike {
+    addEventListener(type: string, fn: (e: Event) => void, opts?: boolean | AddEventListenerOptions): void;
+    removeEventListener(type: string, fn: (e: Event) => void, opts?: boolean | EventListenerOptions): void;
+}
+export interface DismissOutsideController {
+    update(next: DismissOutsideOptions): void;
+    destroy(): void;
+}
+/** True when the event's path passes through any of `roots`. */
+export declare function isInsidePath(event: Event, roots: readonly Element[]): boolean;
+export declare function createDismissOutside(getRoot: () => Element | null | undefined, initial: DismissOutsideOptions, doc?: EventTargetLike | undefined): DismissOutsideController;
+/** Svelte action form. */
+export declare function dismissOutside(node: Element, options: DismissOutsideOptions): {
+    update: (next: DismissOutsideOptions) => void;
+    destroy: () => void;
+};
+export {};

package/dist/actions/dismissOutside.js

@@ -0,0 +1,80 @@
+/**
+ * dismissOutside — close a popover / menu / panel when the user presses
+ * outside it.
+ *
+ *   <div use:dismissOutside={{ onDismiss: close, refs: [triggerEl] }}>…</div>
+ *
+ * - Listens to `pointerdown` in the CAPTURE phase on the document, so a
+ *   child that stops propagation can't hide the outside press, and the panel
+ *   closes before the pressed element's own click runs.
+ * - "Inside" is the node plus every element in `refs` (a trigger button, a
+ *   portalled sub-panel…). It is tested with `composedPath()`, so presses
+ *   inside shadow roots and elements removed during the press still count.
+ * - `escape: true` (default) also dismisses on Escape, unless something
+ *   earlier already called `preventDefault()` on that keydown.
+ * - `enabled: false` disarms it without tearing it down (bind it to `open`).
+ *
+ * The core is `createDismissOutside()`, framework-free and DOM-injectable
+ * for tests and non-Svelte callers.
+ *
+ * Idea after BoardUI's use-dismiss-on-outside-press (MIT © 2026 Mertcan
+ * Dundar Esmergul); the RAC-specific trigger-toggle half is not ported.
+ */
+function readRefs(refs) {
+    const list = typeof refs === 'function' ? refs() : (refs ?? []);
+    return list.filter((el) => !!el);
+}
+/** True when the event's path passes through any of `roots`. */
+export function isInsidePath(event, roots) {
+    const path = typeof event.composedPath === 'function' ? event.composedPath() : [];
+    if (path.length)
+        return roots.some((r) => path.includes(r));
+    const target = event.target;
+    return !!target && roots.some((r) => r === target || r.contains(target));
+}
+export function createDismissOutside(getRoot, initial, doc = typeof document !== 'undefined' ? document : undefined) {
+    let opts = initial;
+    const onPress = (e) => {
+        if (opts.enabled === false)
+            return;
+        const root = getRoot();
+        const roots = [...(root ? [root] : []), ...readRefs(opts.refs)];
+        if (isInsidePath(e, roots))
+            return;
+        opts.onDismiss(e, 'outside');
+    };
+    const onKey = (e) => {
+        if (opts.enabled === false || opts.escape === false)
+            return;
+        const ke = e;
+        if (ke.key !== 'Escape' || ke.defaultPrevented || ke.isComposing)
+            return;
+        opts.onDismiss(e, 'escape');
+    };
+    let pressType = opts.event ?? 'pointerdown';
+    doc?.addEventListener(pressType, onPress, true);
+    doc?.addEventListener('keydown', onKey);
+    return {
+        update(next) {
+            const nextType = next.event ?? 'pointerdown';
+            if (nextType !== pressType) {
+                doc?.removeEventListener(pressType, onPress, true);
+                doc?.addEventListener(nextType, onPress, true);
+                pressType = nextType;
+            }
+            opts = next;
+        },
+        destroy() {
+            doc?.removeEventListener(pressType, onPress, true);
+            doc?.removeEventListener('keydown', onKey);
+        }
+    };
+}
+/** Svelte action form. */
+export function dismissOutside(node, options) {
+    const ctl = createDismissOutside(() => node, options);
+    return {
+        update: (next) => ctl.update(next),
+        destroy: () => ctl.destroy()
+    };
+}

package/dist/components/FileDropzone.svelte

@@ -17,6 +17,7 @@
 
 <script lang="ts">
   import FileThumbnail from "./FileThumbnail.svelte"
+  import { clampProgress, dashOffset, perimeterRect, progressPercent } from "./uploadProgress.js"
 
   // Lightweight extension→MIME map (avoids mime-types dependency)
   const EXT_TO_MIME: Record<string, string> = {
@@ -87,6 +88,15 @@
     dropSubtext?: string
     /** Called when the user selects or drops files (after validation) */
     onFilesSelected?: (files: File[], errors: string[]) => void
+    /**
+     * Upload progress, 0–100. When set, the zone's dashed border cross-fades
+     * into a primary stroke that fills clockwise around the perimeter, and a
+     * `%` badge slides in on the top edge — no layout shift. Leave it
+     * undefined/null for the plain (indeterminate) behaviour.
+     */
+    progress?: number | null
+    /** Accessible name for the progress indicator (default "Upload progress"). */
+    progressLabel?: string
   }
 
   let {
@@ -107,6 +117,8 @@
     dropLabel = "Upload files",
     dropSubtext,
     onFilesSelected,
+    progress = null,
+    progressLabel = "Upload progress",
   }: Props = $props()
 
   let isDragOver = $state(false)
@@ -114,6 +126,27 @@
   let dropzoneRef = $state<HTMLElement>(undefined!)
   let selectedFiles = $state<File[]>([])
 
+  // Upload progress perimeter (jatui-bns3w). The rect tracks the zone's
+  // border-box via ResizeObserver so the stroke lands exactly on the 2px border.
+  const ZONE_BORDER = 2
+  const ZONE_RADIUS = 8 // rounded-lg
+  let zoneW = $state(0)
+  let zoneH = $state(0)
+  const progressValue = $derived(clampProgress(progress))
+  const progressActive = $derived(progressValue !== null)
+  const progressDone = $derived(progressValue === 100)
+  const progressRect = $derived(perimeterRect(zoneW, zoneH, ZONE_BORDER, ZONE_RADIUS))
+
+  $effect(() => {
+    if (!dropzoneRef || typeof ResizeObserver === "undefined") return
+    const ro = new ResizeObserver(() => {
+      zoneW = dropzoneRef.offsetWidth
+      zoneH = dropzoneRef.offsetHeight
+    })
+    ro.observe(dropzoneRef)
+    return () => ro.disconnect()
+  })
+
   // Human-readable accepted extensions for display
   const acceptedExtensions = $derived(
     accept
@@ -305,14 +338,17 @@
   />
 
   <!-- Dropzone -->
+  <div class="relative">
   <div
     bind:this={dropzoneRef}
     class="relative border-2 border-dashed rounded-lg p-6 transition-all duration-200 cursor-pointer
            {isDragOver
       ? 'border-primary bg-primary/5 scale-[1.02]'
-      : disabled
-        ? 'border-base-300 bg-base-200 cursor-not-allowed'
-        : 'border-base-300 hover:border-primary hover:bg-primary/5'}"
+      : progressActive
+        ? 'jatui-dz-border-hidden'
+        : disabled
+          ? 'border-base-300 bg-base-200 cursor-not-allowed'
+          : 'border-base-300 hover:border-primary hover:bg-primary/5'}"
     onclick={openFileDialog}
     ondragenter={handleDragEnter}
     ondragleave={handleDragLeave}
@@ -398,6 +434,50 @@
     {/if}
   </div>
 
+  <!-- Upload progress: perimeter stroke + % badge. A sibling of the
+       role="button" zone (a progressbar inside a button is flattened by AT). -->
+  <div
+    class="jatui-dz-progress"
+    class:is-active={progressActive && !isDragOver}
+    class:is-done={progressDone}
+    role={progressActive ? "progressbar" : undefined}
+    aria-label={progressActive ? progressLabel : undefined}
+    aria-valuemin={progressActive ? 0 : undefined}
+    aria-valuemax={progressActive ? 100 : undefined}
+    aria-valuenow={progressActive ? progressPercent(progressValue) : undefined}
+    aria-hidden={progressActive ? undefined : "true"}
+  >
+    {#if zoneW > 0 && zoneH > 0}
+      <svg class="jatui-dz-ring" width={zoneW} height={zoneH} aria-hidden="true">
+        <rect
+          class="jatui-dz-track"
+          x={progressRect.x}
+          y={progressRect.y}
+          width={progressRect.width}
+          height={progressRect.height}
+          rx={progressRect.rx}
+          stroke-width={ZONE_BORDER}
+        />
+        <rect
+          class="jatui-dz-fill"
+          x={progressRect.x}
+          y={progressRect.y}
+          width={progressRect.width}
+          height={progressRect.height}
+          rx={progressRect.rx}
+          stroke-width={ZONE_BORDER}
+          pathLength="100"
+          stroke-dasharray="100"
+          stroke-dashoffset={dashOffset(progressValue, 100)}
+        />
+      </svg>
+    {/if}
+    <span class="jatui-dz-badge badge badge-sm badge-primary tabular-nums" aria-hidden="true">
+      {progressPercent(progressValue)}%
+    </span>
+  </div>
+  </div>
+
   <!-- Selected Files (before upload) -->
   {#if selectedFiles.length > 0 && !isUploading && uploadedFiles.length === 0}
     <div class="mt-4 space-y-2">
@@ -490,4 +570,86 @@
     outline: 2px solid var(--color-primary);
     outline-offset: 2px;
   }
+
+  /* Upload progress perimeter (jatui-bns3w). The dashed border fades out and
+     an SVG stroke on the same 2px line fills clockwise; the % badge slides in
+     on the top edge. Opacity/transform only — the zone never changes size. */
+  .jatui-dz-border-hidden {
+    border-color: transparent;
+  }
+
+  .jatui-dz-progress {
+    position: absolute;
+    inset: 0;
+    pointer-events: none;
+  }
+
+  .jatui-dz-ring {
+    position: absolute;
+    inset: 0;
+    overflow: visible;
+    opacity: 0;
+    transition: opacity var(--motion-enter, 200ms) var(--motion-glide, ease-out);
+  }
+
+  .jatui-dz-progress.is-active .jatui-dz-ring {
+    opacity: 1;
+  }
+
+  .jatui-dz-track {
+    fill: none;
+    stroke: var(--color-base-300);
+  }
+
+  .jatui-dz-fill {
+    fill: none;
+    stroke: var(--color-primary);
+    stroke-linecap: round;
+    transition:
+      stroke-dashoffset var(--motion-move, 300ms) var(--motion-glide, ease-out),
+      stroke var(--motion-fast, 150ms) var(--motion-glide, ease-out);
+  }
+
+  .jatui-dz-progress.is-done .jatui-dz-fill {
+    stroke: var(--color-success);
+  }
+
+  .jatui-dz-badge {
+    position: absolute;
+    top: 0;
+    left: 50%;
+    opacity: 0;
+    transform: translate(-50%, calc(-50% - var(--motion-travel, 16px)));
+    transition:
+      opacity var(--motion-enter, 200ms) var(--motion-glide, ease-out),
+      transform var(--motion-enter, 200ms) var(--motion-glide, ease-out);
+  }
+
+  .jatui-dz-progress.is-active .jatui-dz-badge {
+    opacity: 1;
+    transform: translate(-50%, -50%);
+  }
+
+  .jatui-dz-progress.is-done .jatui-dz-badge {
+    background-color: var(--color-success);
+    border-color: var(--color-success);
+    color: var(--color-success-content);
+  }
+
+  /* Calm: no slide, the badge just appears. */
+  :global([data-motion="calm"]) .jatui-dz-badge {
+    transform: translate(-50%, -50%);
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .jatui-dz-ring,
+    .jatui-dz-fill,
+    .jatui-dz-badge {
+      transition: none;
+    }
+
+    .jatui-dz-badge {
+      transform: translate(-50%, -50%);
+    }
+  }
 </style>

package/dist/components/FileDropzone.svelte.d.ts

@@ -34,6 +34,15 @@ interface Props {
     dropSubtext?: string;
     /** Called when the user selects or drops files (after validation) */
     onFilesSelected?: (files: File[], errors: string[]) => void;
+    /**
+     * Upload progress, 0–100. When set, the zone's dashed border cross-fades
+     * into a primary stroke that fills clockwise around the perimeter, and a
+     * `%` badge slides in on the top edge — no layout shift. Leave it
+     * undefined/null for the plain (indeterminate) behaviour.
+     */
+    progress?: number | null;
+    /** Accessible name for the progress indicator (default "Upload progress"). */
+    progressLabel?: string;
 }
 declare const FileDropzone: import("svelte").Component<Props, {}, "">;
 type FileDropzone = ReturnType<typeof FileDropzone>;