@joewinke/jatui 0.43.0 → 0.44.0

package/CLAUDE.md

@@ -92,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` |

package/dist/components/ImageReveal.svelte

@@ -0,0 +1,353 @@
+<!--
+  ImageReveal — a frame that shows a "generating" ripple until its image
+  exists, then brings the image in blur-to-sharp. Built for slots whose image
+  arrives late: a logo being looked up, an AI generation, a thumbnail still
+  rendering.
+
+    src null / undefined → generating: ripple on the tone, role="status",
+                           aria-busy
+    src set, not decoded → still the ripple (no half-loaded image is shown)
+    src loaded           → blur + slight scale → sharp, ripple fades; onReveal
+    src '' or onerror    → calm initials (from alt) or an image glyph — never a
+                           broken image
+
+  Colours are one tone mixed with color-mix (no hex). The ripple is a
+  decorative loop: .jatui-motion-ambient, and under data-motion="calm" or
+  prefers-reduced-motion it becomes a static tint and the image swaps in
+  without the blur.
+
+  Clean-room (jatui-vui9q): BoardUI's image-generation effect is a Pro item;
+  nothing from it was read or copied.
+-->
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+	import {
+		IMAGE_REVEAL_RADIUS,
+		imageRevealBusy,
+		imageRevealInitials,
+		imageRevealPhase,
+		imageRevealSize,
+		imageRevealTone,
+		type ImageRevealPhase,
+		type ImageRevealShape,
+		type ImageRevealSizeName,
+		type ImageRevealToneName
+	} from './imageReveal';
+
+	interface Props {
+		/** null / undefined = still generating. '' = nothing to show (fallback). */
+		src?: string | null;
+		/** Alt text for the image; also the source of the fallback initials. */
+		alt?: string;
+		shape?: ImageRevealShape;
+		/** Named size, px number, any CSS length, or 'fill' (100% width). Always square. */
+		size?: ImageRevealSizeName | number | (string & {});
+		/** DaisyUI semantic name or any CSS colour. */
+		tone?: ImageRevealToneName | (string & {});
+		/** Screen-reader status while generating. */
+		label?: string;
+		/** Override the letters derived from `alt`. '' forces the glyph. */
+		initials?: string;
+		/** object-fit for the image. Logos usually want 'contain'. */
+		fit?: 'cover' | 'contain';
+		/** Read-only: the current phase. */
+		phase?: ImageRevealPhase;
+		/** Fires once per src, when that image has loaded. */
+		onReveal?: (src: string) => void;
+		/** Fires once per src, when that image failed to load. */
+		onError?: (src: string) => void;
+		/** Replaces the initials / glyph fallback. */
+		fallback?: Snippet;
+		class?: string;
+	}
+
+	let {
+		src = null,
+		alt = '',
+		shape = 'rounded',
+		size = 'md',
+		tone = 'primary',
+		label = 'Generating image',
+		initials,
+		fit = 'cover',
+		phase = $bindable('generating'),
+		onReveal,
+		onError,
+		fallback,
+		class: className = ''
+	}: Props = $props();
+
+	let loadedSrc = $state<string | null>(null);
+	let failedSrc = $state<string | null>(null);
+	let img = $state<HTMLImageElement | null>(null);
+
+	const current = $derived(imageRevealPhase({ src, loadedSrc, failedSrc }));
+	const busy = $derived(imageRevealBusy(current));
+	const letters = $derived(initials ?? imageRevealInitials(alt));
+
+	$effect.pre(() => {
+		phase = current;
+	});
+
+	function loaded(from: string) {
+		if (from !== src || loadedSrc === from) return;
+		loadedSrc = from;
+		onReveal?.(from);
+	}
+
+	function failed(from: string) {
+		if (from !== src || failedSrc === from) return;
+		failedSrc = from;
+		onError?.(from);
+	}
+
+	// An image served from cache (or loaded before hydration) can finish before
+	// the load listener exists, so read its state once it is in the DOM.
+	$effect(() => {
+		if (!img || !src) return;
+		const el = img;
+		const from = src;
+		if (el.complete) {
+			if (el.naturalWidth > 0) loaded(from);
+			else if (el.currentSrc || el.getAttribute('src')) failed(from);
+		}
+	});
+</script>
+
+<div
+	class="jatui-image-reveal is-{current} {className}"
+	style:--jatui-ir-tone={imageRevealTone(tone)}
+	style:--jatui-ir-size={imageRevealSize(size)}
+	style:--jatui-ir-radius={IMAGE_REVEAL_RADIUS[shape]}
+	aria-busy={busy}
+	data-phase={current}
+>
+	<span class="jatui-ir-status" role="status">{busy ? label : ''}</span>
+
+	{#if current !== 'fallback'}
+		<div class="jatui-ir-ripple" class:jatui-motion-ambient={busy} aria-hidden="true">
+			<span class="jatui-ir-ring"></span>
+			<span class="jatui-ir-ring"></span>
+			<span class="jatui-ir-ring"></span>
+			<span class="jatui-ir-core"></span>
+		</div>
+	{/if}
+
+	{#if src && current !== 'fallback'}
+		{#key src}
+			<img
+				bind:this={img}
+				class="jatui-ir-img"
+				class:is-shown={current === 'revealed'}
+				style:object-fit={fit}
+				{src}
+				{alt}
+				decoding="async"
+				onload={() => loaded(src!)}
+				onerror={() => failed(src!)}
+			/>
+		{/key}
+	{:else if current === 'fallback'}
+		{#if fallback}
+			<div class="jatui-ir-fallback">{@render fallback()}</div>
+		{:else if letters}
+			<div class="jatui-ir-fallback" role={alt ? 'img' : undefined} aria-label={alt || undefined}>
+				<span class="jatui-ir-initials" aria-hidden="true">{letters}</span>
+			</div>
+		{:else}
+			<div class="jatui-ir-fallback" role={alt ? 'img' : undefined} aria-label={alt || undefined}>
+				<svg class="jatui-ir-glyph" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" aria-hidden="true">
+					<rect x="3" y="4" width="18" height="16" rx="2" />
+					<circle cx="9" cy="10" r="1.75" />
+					<path d="m21 16-5-5-9 9" stroke-linecap="round" stroke-linejoin="round" />
+				</svg>
+			</div>
+		{/if}
+	{/if}
+</div>
+
+<style>
+	.jatui-image-reveal {
+		--jatui-ir-reveal: calc(var(--motion-move, 300ms) * 2);
+		position: relative;
+		display: inline-grid;
+		place-items: center;
+		width: var(--jatui-ir-size);
+		max-width: 100%;
+		aspect-ratio: 1;
+		overflow: hidden;
+		isolation: isolate;
+		container-type: inline-size;
+		border-radius: var(--jatui-ir-radius);
+		background: color-mix(in oklab, var(--jatui-ir-tone) 7%, var(--color-base-100, Canvas));
+		box-shadow: inset 0 0 0 1px color-mix(in oklab, var(--jatui-ir-tone) 14%, transparent);
+		vertical-align: middle;
+	}
+
+	.jatui-ir-status {
+		position: absolute;
+		width: 1px;
+		height: 1px;
+		margin: -1px;
+		overflow: hidden;
+		clip-path: inset(50%);
+		white-space: nowrap;
+	}
+
+	/* ---- generating: ripple ---- */
+	.jatui-ir-ripple {
+		position: absolute;
+		inset: 0;
+		display: grid;
+		place-items: center;
+		background: radial-gradient(
+			circle at 50% 50%,
+			color-mix(in oklab, var(--jatui-ir-tone) 16%, transparent) 0%,
+			transparent 70%
+		);
+		transition: opacity var(--jatui-ir-reveal) var(--motion-glide, ease-out);
+	}
+
+	.jatui-ir-ring,
+	.jatui-ir-core {
+		grid-area: 1 / 1;
+		border-radius: 9999px;
+	}
+
+	.jatui-ir-ring {
+		width: 90%;
+		aspect-ratio: 1;
+		border: max(1px, 2cqi) solid
+			color-mix(in oklab, var(--jatui-ir-tone) 45%, transparent);
+		opacity: 0;
+		transform: scale(0.2);
+		animation: jatui-ir-ripple 2400ms var(--motion-glide, ease-out) infinite;
+	}
+
+	.jatui-ir-ring:nth-child(2) {
+		animation-delay: 800ms;
+	}
+
+	.jatui-ir-ring:nth-child(3) {
+		animation-delay: 1600ms;
+	}
+
+	.jatui-ir-core {
+		width: 22%;
+		aspect-ratio: 1;
+		background: color-mix(in oklab, var(--jatui-ir-tone) 55%, transparent);
+		filter: blur(4cqi);
+		animation: jatui-ir-breathe 2400ms ease-in-out infinite;
+	}
+
+	@keyframes jatui-ir-ripple {
+		0% {
+			opacity: 0;
+			transform: scale(0.2);
+		}
+		15% {
+			opacity: 1;
+		}
+		100% {
+			opacity: 0;
+			transform: scale(1.35);
+		}
+	}
+
+	@keyframes jatui-ir-breathe {
+		0%,
+		100% {
+			opacity: 0.55;
+			transform: scale(0.85);
+		}
+		50% {
+			opacity: 1;
+			transform: scale(1.1);
+		}
+	}
+
+	/* ---- reveal ---- */
+	.jatui-ir-img {
+		position: absolute;
+		inset: 0;
+		width: 100%;
+		height: 100%;
+		opacity: 0;
+		filter: blur(calc(12cqi + 4px));
+		transform: scale(1.06);
+		transition:
+			opacity var(--jatui-ir-reveal) var(--motion-glide, ease-out),
+			filter var(--jatui-ir-reveal) var(--motion-glide, ease-out),
+			transform var(--jatui-ir-reveal) var(--motion-glide, ease-out);
+	}
+
+	.jatui-ir-img.is-shown {
+		opacity: 1;
+		filter: none;
+		transform: none;
+	}
+
+	.is-revealed .jatui-ir-ripple {
+		opacity: 0;
+		visibility: hidden;
+		transition:
+			opacity var(--jatui-ir-reveal) var(--motion-glide, ease-out),
+			visibility 0s linear var(--jatui-ir-reveal);
+	}
+
+	.is-revealed {
+		background: transparent;
+		box-shadow: none;
+	}
+
+	/* ---- fallback ---- */
+	.jatui-ir-fallback {
+		position: absolute;
+		inset: 0;
+		display: grid;
+		place-items: center;
+		color: color-mix(in oklab, var(--jatui-ir-tone) 75%, var(--color-base-content, CanvasText));
+	}
+
+	.jatui-ir-initials {
+		font-weight: 600;
+		font-size: 36cqi;
+		line-height: 1;
+		letter-spacing: 0.02em;
+	}
+
+	.jatui-ir-glyph {
+		width: 42%;
+		height: 42%;
+		opacity: 0.7;
+	}
+
+	/* ---- calm / reduced motion: static tint, instant swap ---- */
+	:global([data-motion='calm']) .jatui-ir-ring,
+	:global([data-motion='calm']) .jatui-ir-core,
+	.jatui-image-reveal:global([data-motion='calm']) .jatui-ir-ring,
+	.jatui-image-reveal:global([data-motion='calm']) .jatui-ir-core {
+		animation: none;
+	}
+	:global([data-motion='calm']) .jatui-ir-ring,
+	.jatui-image-reveal:global([data-motion='calm']) .jatui-ir-ring {
+		opacity: 0;
+	}
+	:global([data-motion='calm']) .jatui-image-reveal,
+	.jatui-image-reveal:global([data-motion='calm']) {
+		--jatui-ir-reveal: 0s;
+	}
+
+	@media (prefers-reduced-motion: reduce) {
+		.jatui-image-reveal {
+			--jatui-ir-reveal: 0s;
+		}
+		.jatui-ir-ring,
+		.jatui-ir-core {
+			animation: none;
+		}
+		.jatui-ir-ring {
+			opacity: 0;
+		}
+	}
+</style>

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

@@ -0,0 +1,31 @@
+import type { Snippet } from 'svelte';
+import { type ImageRevealPhase, type ImageRevealShape, type ImageRevealSizeName, type ImageRevealToneName } from './imageReveal';
+interface Props {
+    /** null / undefined = still generating. '' = nothing to show (fallback). */
+    src?: string | null;
+    /** Alt text for the image; also the source of the fallback initials. */
+    alt?: string;
+    shape?: ImageRevealShape;
+    /** Named size, px number, any CSS length, or 'fill' (100% width). Always square. */
+    size?: ImageRevealSizeName | number | (string & {});
+    /** DaisyUI semantic name or any CSS colour. */
+    tone?: ImageRevealToneName | (string & {});
+    /** Screen-reader status while generating. */
+    label?: string;
+    /** Override the letters derived from `alt`. '' forces the glyph. */
+    initials?: string;
+    /** object-fit for the image. Logos usually want 'contain'. */
+    fit?: 'cover' | 'contain';
+    /** Read-only: the current phase. */
+    phase?: ImageRevealPhase;
+    /** Fires once per src, when that image has loaded. */
+    onReveal?: (src: string) => void;
+    /** Fires once per src, when that image failed to load. */
+    onError?: (src: string) => void;
+    /** Replaces the initials / glyph fallback. */
+    fallback?: Snippet;
+    class?: string;
+}
+declare const ImageReveal: import("svelte").Component<Props, {}, "phase">;
+type ImageReveal = ReturnType<typeof ImageReveal>;
+export default ImageReveal;

package/dist/components/imageReveal.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Pure helpers behind ImageReveal: which phase the frame is in, the initials
+ * fallback, and the size / shape / tone lookups. No DOM, so
+ * tests/unit/imageReveal.test.ts runs them in node.
+ *
+ * Clean-room (jatui-vui9q): BoardUI's "AI Image Generation" item is in the
+ * Pro tier, so no BoardUI source was read or copied.
+ */
+/**
+ * generating — no src yet (`null`/`undefined`): the ripple runs.
+ * loading    — a src arrived but the bytes haven't decoded: the ripple keeps
+ *              running, the image waits underneath at blur + opacity 0.
+ * revealed   — the image loaded: blur-to-sharp, the ripple fades out.
+ * fallback   — `src === ''` or the image failed: calm initials / empty glyph.
+ */
+export type ImageRevealPhase = 'generating' | 'loading' | 'revealed' | 'fallback';
+export type ImageRevealShape = 'square' | 'rounded' | 'circle';
+export type ImageRevealSizeName = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'fill';
+/** DaisyUI semantic colour names accepted as a `tone`. */
+export type ImageRevealToneName = 'primary' | 'secondary' | 'accent' | 'neutral' | 'info' | 'success' | 'warning' | 'error';
+export interface ImageRevealState {
+    src: string | null | undefined;
+    /** The src whose load event fired (null if none has). */
+    loadedSrc: string | null;
+    /** The src whose error event fired (null if none has). */
+    failedSrc: string | null;
+}
+/**
+ * Phase from the current src plus what the browser reported for it. Load and
+ * error are keyed by src, so a new src starts over at `loading` without the
+ * component having to reset flags.
+ */
+export declare function imageRevealPhase({ src, loadedSrc, failedSrc }: ImageRevealState): ImageRevealPhase;
+/** True while the frame is still waiting for something to show. */
+export declare function imageRevealBusy(phase: ImageRevealPhase): boolean;
+/**
+ * Up to two letters from the alt text: "Acme Corp" → "AC", "acme" → "A",
+ * "the-north-face" → "TN". Symbols and digits-only words are skipped, so a
+ * logo alt like "Acme logo" gives "AL" — callers who want "A" pass
+ * `initials` explicitly.
+ */
+export declare function imageRevealInitials(alt: string | null | undefined): string;
+export declare const IMAGE_REVEAL_SIZES: Record<Exclude<ImageRevealSizeName, 'fill'>, number>;
+/**
+ * A CSS length for the frame's width. Named sizes and numbers are px; any
+ * other string (`'10rem'`, `'50%'`) passes through; `'fill'` is 100%.
+ */
+export declare function imageRevealSize(size: ImageRevealSizeName | number | (string & {})): string;
+export declare const IMAGE_REVEAL_RADIUS: Record<ImageRevealShape, string>;
+/** A semantic name → its DaisyUI variable; any other string is a CSS colour. */
+export declare function imageRevealTone(tone: ImageRevealToneName | (string & {})): string;

package/dist/components/imageReveal.js

@@ -0,0 +1,83 @@
+/**
+ * Pure helpers behind ImageReveal: which phase the frame is in, the initials
+ * fallback, and the size / shape / tone lookups. No DOM, so
+ * tests/unit/imageReveal.test.ts runs them in node.
+ *
+ * Clean-room (jatui-vui9q): BoardUI's "AI Image Generation" item is in the
+ * Pro tier, so no BoardUI source was read or copied.
+ */
+/**
+ * Phase from the current src plus what the browser reported for it. Load and
+ * error are keyed by src, so a new src starts over at `loading` without the
+ * component having to reset flags.
+ */
+export function imageRevealPhase({ src, loadedSrc, failedSrc }) {
+    if (src == null)
+        return 'generating';
+    if (src.trim() === '' || failedSrc === src)
+        return 'fallback';
+    if (loadedSrc === src)
+        return 'revealed';
+    return 'loading';
+}
+/** True while the frame is still waiting for something to show. */
+export function imageRevealBusy(phase) {
+    return phase === 'generating' || phase === 'loading';
+}
+/**
+ * Up to two letters from the alt text: "Acme Corp" → "AC", "acme" → "A",
+ * "the-north-face" → "TN". Symbols and digits-only words are skipped, so a
+ * logo alt like "Acme logo" gives "AL" — callers who want "A" pass
+ * `initials` explicitly.
+ */
+export function imageRevealInitials(alt) {
+    if (!alt)
+        return '';
+    const words = alt
+        .split(/[\s\-_./]+/)
+        .map((w) => w.match(/\p{L}/u)?.[0] ?? '')
+        .filter(Boolean);
+    return words
+        .slice(0, 2)
+        .join('')
+        .toLocaleUpperCase();
+}
+export const IMAGE_REVEAL_SIZES = {
+    xs: 32,
+    sm: 48,
+    md: 64,
+    lg: 96,
+    xl: 128
+};
+/**
+ * A CSS length for the frame's width. Named sizes and numbers are px; any
+ * other string (`'10rem'`, `'50%'`) passes through; `'fill'` is 100%.
+ */
+export function imageRevealSize(size) {
+    if (typeof size === 'number')
+        return `${size}px`;
+    if (size === 'fill')
+        return '100%';
+    if (size in IMAGE_REVEAL_SIZES)
+        return `${IMAGE_REVEAL_SIZES[size]}px`;
+    return size;
+}
+export const IMAGE_REVEAL_RADIUS = {
+    square: '0',
+    rounded: 'var(--jatui-radius-box, var(--radius-box, 0.5rem))',
+    circle: '9999px'
+};
+const TONE_NAMES = new Set([
+    'primary',
+    'secondary',
+    'accent',
+    'neutral',
+    'info',
+    'success',
+    'warning',
+    'error'
+]);
+/** A semantic name → its DaisyUI variable; any other string is a CSS colour. */
+export function imageRevealTone(tone) {
+    return TONE_NAMES.has(tone) ? `var(--color-${tone})` : tone;
+}

package/dist/index.d.ts

@@ -400,3 +400,6 @@ export { default as SettingsSection } from './components/settings/SettingsSectio
 export { default as SettingsRow } from './components/settings/SettingsRow.svelte';
 export type { SettingsRowContext } from './components/settings/SettingsRow.svelte';
 export * from './data/grid/index';
+export { default as ImageReveal } from './components/ImageReveal.svelte';
+export { imageRevealPhase, imageRevealBusy, imageRevealInitials, imageRevealSize, imageRevealTone, IMAGE_REVEAL_SIZES, IMAGE_REVEAL_RADIUS } from './components/imageReveal';
+export type { ImageRevealPhase, ImageRevealShape, ImageRevealSizeName, ImageRevealToneName, ImageRevealState } from './components/imageReveal';

package/dist/index.js

@@ -435,3 +435,5 @@ export { default as SegmentedControl } from './components/SegmentedControl.svelt
 export { default as SettingsSection } from './components/settings/SettingsSection.svelte';
 export { default as SettingsRow } from './components/settings/SettingsRow.svelte';
 export * from './data/grid/index';
+export { default as ImageReveal } from './components/ImageReveal.svelte';
+export { imageRevealPhase, imageRevealBusy, imageRevealInitials, imageRevealSize, imageRevealTone, IMAGE_REVEAL_SIZES, IMAGE_REVEAL_RADIUS } from './components/imageReveal';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joewinke/jatui",
-  "version": "0.43.0",
+  "version": "0.44.0",
   "private": false,
   "description": "Shared Svelte 5 component library for JAT projects",
   "type": "module",