@delightstack/components 0.1.0

package/dist/media/Gallery.svelte.d.ts

@@ -0,0 +1,82 @@
+import type { Component } from 'svelte';
+import type { CarouselItem } from './carousel';
+/** A single action button that can be shown on a gallery item or in the carousel header. */
+export interface GalleryItemAction {
+    /** The icon component to show for the action */
+    icon?: Component<Record<string, unknown>>;
+    /** The main action text - e.g. 'Download' or 'Pay now' */
+    name?: string;
+    /** A short descriptor of the action - e.g. file size or filename */
+    tooltip?: string;
+    /** The link that the button should go to */
+    href?: string;
+    /** Called when the button is clicked */
+    click?: (event: Event) => unknown;
+    /** Anchor target (only used if href is provided) */
+    target?: '_blank' | '_self';
+    /** The list of subactions (shown in a context menu) */
+    actions?: GalleryItemAction[];
+}
+export type GalleryDisplay = 'grid' | 'masonry' | 'masonry-row' | 'list' | 'slider' | 'slideshow' | 'lightbox';
+/**
+ * Thumbnail size on the delightstack numeric scale: `'1'` is the standard,
+ * lower (`'0'`, `'00'`) is smaller, higher (`'2'`, `'3'`) is larger.
+ */
+export type GallerySize = '00' | '0' | '1' | '2' | '3';
+/**
+ * Gap between gallery items on the delightstack numeric scale: `'0'` removes
+ * the gap, `'1'` is the standard, `'2'`/`'3'` are progressively larger.
+ */
+export type GallerySpacing = '0' | '1' | '2' | '3';
+/**
+ * Corner radius of gallery items on the delightstack numeric scale: `'0'` is
+ * square, `'1'` is the standard, `'2'`/`'3'` are progressively rounder.
+ */
+export type GalleryRadius = '0' | '1' | '2' | '3';
+export type GalleryItem = string | (Partial<CarouselItem> & {
+    favorite?: boolean;
+});
+import { type Snippet } from 'svelte';
+declare const Gallery: Component<{
+    display?: GalleryDisplay;
+    size?: GallerySize;
+    spacing?: GallerySpacing;
+    radius?: GalleryRadius;
+    slide?: number;
+    fit?: "cover" | "contain";
+    items?: GalleryItem[];
+    duration?: number;
+    autoplay?: boolean;
+    autoplay_video?: boolean;
+    aspect_ratio?: string | undefined;
+    disable_fullscreen?: boolean;
+    inline?: boolean | undefined;
+    controls?: "default" | "inline" | "overlay" | "disable";
+    page?: number;
+    num_pages?: number;
+    meta_display?: "none" | "always" | "hover";
+    meta_display_fullscreen?: "none" | "always";
+    action_display?: "none" | "always" | "hover";
+    actions?: GalleryItemAction[][];
+    custom?: Snippet<[{
+        item: CarouselItem;
+        onload: () => void;
+        onerror: (err: unknown) => void;
+        active: boolean;
+        gesture_disabled: boolean;
+    }]> | undefined;
+    onclick?: undefined | ((event: MouseEvent | KeyboardEvent, index: number) => void | false);
+    style?: string;
+}, {
+    open: (index: number, from?: HTMLElement) => void;
+    close: () => void;
+    goto: (i: number) => void;
+    next: (amount?: number) => void;
+    prev: (amount?: number) => void;
+    play: () => void;
+    pause: () => void;
+    toggleFullscreen: () => void;
+}, "page" | "slide" | "num_pages">;
+type Gallery = ReturnType<typeof Gallery>;
+export default Gallery;
+//# sourceMappingURL=Gallery.svelte.d.ts.map

package/dist/media/Gallery.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Gallery.svelte.d.ts","sourceRoot":"","sources":["../../src/media/Gallery.svelte.ts"],"names":[],"mappings":"AAGC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AACxC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C,4FAA4F;AAC5F,MAAM,WAAW,iBAAiB;IACjC,gDAAgD;IAChD,IAAI,CAAC,EAAE,SAAS,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAE1C,0DAA0D;IAC1D,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,oEAAoE;IACpE,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,4CAA4C;IAC5C,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,wCAAwC;IACxC,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC;IAElC,oDAAoD;IACpD,MAAM,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC;IAE5B,uDAAuD;IACvD,OAAO,CAAC,EAAE,iBAAiB,EAAE,CAAC;CAC9B;AAED,MAAM,MAAM,cAAc,GACvB,MAAM,GACN,SAAS,GACT,aAAa,GACb,MAAM,GACN,QAAQ,GACR,WAAW,GACX,UAAU,CAAC;AAEd;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,IAAI,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;AAEvD;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;AAEnD;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;AAElD,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,CAAC,OAAO,CAAC,YAAY,CAAC,GAAG;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC,CAAC;AAKrF,OAAO,EAA+B,KAAK,OAAO,EAAE,MAAM,QAAQ,CAAC;AA40BnE,QAAA,MAAM,OAAO;cA1hB2C,cAAc;WAAS,WAAW;cAAY,cAAc;aAAW,aAAa;YAAU,MAAM;UAAQ,OAAO,GAAG,SAAS;YAAU,WAAW,EAAE;eAAa,MAAM;eAAa,OAAO;qBAAmB,OAAO;mBAAiB,MAAM,GAAG,SAAS;yBAAuB,OAAO;aAAW,OAAO,GAAG,SAAS;eAAa,SAAS,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS;WAAS,MAAM;gBAAc,MAAM;mBAAiB,MAAM,GAAG,QAAQ,GAAG,OAAO;8BAA4B,MAAM,GAAG,QAAQ;qBAAmB,MAAM,GAAG,QAAQ,GAAG,OAAO;cAAY,iBAAiB,EAAE,EAAE;aAAa,OAAO,CACjoB,CACC;QACC,IAAI,EAAE,YAAY,CAAC;QACnB,MAAM,EAAE,MAAM,IAAI,CAAC;QACnB,OAAO,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,CAAC;QAChC,MAAM,EAAE,OAAO,CAAC;QAChB,gBAAgB,EAAE,OAAO,CAAC;KAC1B,CACD,CACA,GACD,SAAS;cAAc,SAAS,GAChC,CAAC,CAAC,KAAK,EAAE,UAAU,GAAG,aAAa,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,KAAK,CAAC;YAAU,MAAM;;kBAwNlE,MAAM,SAAS,WAAW;;cAqB9B,MAAM;;;;;;kCAiS4B,CAAC;AACtD,KAAK,OAAO,GAAG,UAAU,CAAC,OAAO,OAAO,CAAC,CAAC;AAC1C,eAAe,OAAO,CAAC"}

package/dist/media/Image.svelte

@@ -0,0 +1,389 @@
+<script lang="ts">
+	import { decodeThumbHash } from './carousel';
+
+	type ImageState = 'loading' | 'loaded' | 'error';
+
+	let {
+		/** The image source URL (required) */
+		src,
+
+		/** The alt text for the image (required) */
+		alt,
+
+		/** The intrinsic width of the image in pixels */
+		width = undefined as number | undefined,
+
+		/** The intrinsic height of the image in pixels */
+		height = undefined as number | undefined,
+
+		/** The aspect ratio of the container (e.g. '16/9') to prevent CLS */
+		aspect_ratio = undefined as string | undefined,
+
+		/** How the image should be scaled within its container */
+		fit = 'cover' as 'cover' | 'contain' | 'fill' | 'none',
+
+		/** The position of the image within its container */
+		position = 'center',
+
+		/** Whether the image should be lazily loaded */
+		lazy = true,
+
+		/**
+		 * A base64-encoded [ThumbHash](https://evanw.github.io/thumbhash/) used as
+		 * a tiny blurred placeholder while the full image loads. The component
+		 * decodes this internally. Takes precedence over {@link placeholder}.
+		 */
+		thumbhash = undefined as string | undefined,
+
+		/** A small placeholder image URL for the blur-up effect (used when no thumbhash) */
+		placeholder = undefined as string | undefined,
+
+		/**
+		 * A solid background colour painted on the container — paints before any
+		 * image data arrives (no JS needed). Useful for SSR where a dominant
+		 * colour avoids any flash of empty box even before the thumbhash decodes.
+		 * Accepts any CSS colour value.
+		 */
+		bg_color = undefined as string | undefined,
+
+		/**
+		 * Mark this image as above-the-fold for faster initial paint. When true,
+		 * the image uses `loading="eager"` + `fetchpriority="high"`.
+		 */
+		priority = false,
+
+		/**
+		 * Retry-on-error. `true` retries 3 times with exponential backoff
+		 * (1s, 4s, 9s); a number sets the max retry count; `false` (default)
+		 * disables retries and transitions to the error state immediately.
+		 */
+		retry = false as boolean | number,
+
+		/** Error fallback: true = built-in broken-image SVG, string = fallback image URL, false = disabled */
+		fallback = false as string | boolean,
+
+		/** Responsive srcset attribute passed through to the img element */
+		srcset = undefined as string | undefined,
+
+		/**
+		 * Responsive sizes attribute. If omitted and the image is lazy with a
+		 * srcset, defaults to `auto, 100vw` — modern browsers use the actual
+		 * rendered width to pick a variant, older browsers fall back to 100vw.
+		 */
+		sizes = undefined as string | undefined,
+
+		/** Whether to show a skeleton shimmer animation while loading */
+		skeleton = false,
+
+		/** The ID of the element */
+		id = undefined as string | undefined,
+
+		/** Specifies a custom class name for the container element */
+		class: class_name = '',
+
+		/** A bindable reference to the root HTML element */
+		element = $bindable(undefined as HTMLElement | undefined),
+
+		/** Callback fired when the full image loads */
+		onload = undefined as
+			| undefined
+			| ((detail: { natural_width: number; natural_height: number }) => void),
+
+		/** Callback fired when the image fails to load */
+		onerror = undefined as undefined | ((detail: { error: Event }) => void),
+	}: {
+		src: string;
+		alt: string;
+		width?: number;
+		height?: number;
+		aspect_ratio?: string;
+		fit?: 'cover' | 'contain' | 'fill' | 'none';
+		position?: string;
+		lazy?: boolean;
+		thumbhash?: string;
+		placeholder?: string;
+		bg_color?: string;
+		priority?: boolean;
+		retry?: boolean | number;
+		fallback?: string | boolean;
+		srcset?: string;
+		sizes?: string;
+		skeleton?: boolean;
+		id?: string;
+		class?: string;
+		element?: HTMLElement | undefined;
+		onload?: (detail: { natural_width: number; natural_height: number }) => void;
+		onerror?: (detail: { error: Event }) => void;
+	} = $props();
+
+	let load_state = $state<ImageState>('loading');
+	let fading = $state(false);
+	let img_el = $state<HTMLImageElement | undefined>(undefined);
+	let retry_count = $state(0);
+	let retry_timer: ReturnType<typeof setTimeout> | undefined;
+
+	const max_retries = $derived(
+		retry === true ? 3 : typeof retry === 'number' ? Math.max(0, retry) : 0,
+	);
+
+	const placeholder_src = $derived(thumbhash ? decodeThumbHash(thumbhash) : placeholder);
+	const has_placeholder = $derived(!!placeholder_src);
+	const show_skeleton = $derived(
+		skeleton && load_state === 'loading' && !has_placeholder,
+	);
+	const show_placeholder = $derived(has_placeholder && load_state !== 'error');
+	const show_fallback = $derived(load_state === 'error' && fallback !== false);
+	const fallback_is_url = $derived(typeof fallback === 'string');
+
+	const computed_sizes = $derived(sizes ?? (lazy && srcset ? 'auto, 100vw' : undefined));
+	const computed_loading = $derived(priority ? 'eager' : lazy ? 'lazy' : 'eager');
+
+	const container_style = $derived.by(() => {
+		const parts: string[] = [];
+		if (aspect_ratio) parts.push(`aspect-ratio: ${aspect_ratio}`);
+		if (width) parts.push(`width: ${width}px`);
+		if (height && !aspect_ratio) parts.push(`height: ${height}px`);
+		if (bg_color) parts.push(`background-color: ${bg_color}`);
+		return parts.join('; ') || undefined;
+	});
+
+	function handleLoad(e: Event) {
+		load_state = 'loaded';
+		fading = false;
+		retry_count = 0;
+		clearTimeout(retry_timer);
+		if (onload) {
+			const img = e.target as HTMLImageElement;
+			onload({
+				natural_width: img.naturalWidth,
+				natural_height: img.naturalHeight,
+			});
+		}
+	}
+
+	function handleError(e: Event) {
+		// Opt-in retry — schedule another attempt with exponential backoff
+		// before transitioning to the error state.
+		if (retry_count < max_retries) {
+			retry_count++;
+			clearTimeout(retry_timer);
+			const delay = retry_count ** 2 * 1000; // 1s, 4s, 9s, …
+			retry_timer = setTimeout(() => {
+				if (!img_el || load_state === 'loaded') return;
+				const current = img_el.src;
+				img_el.src = '';
+				img_el.src = current;
+			}, delay);
+			return;
+		}
+		load_state = 'error';
+		fading = false;
+		if (onerror) {
+			onerror({ error: e });
+		}
+	}
+
+	// Reset retry counter when src changes so a new src gets its own retry budget.
+	$effect(() => {
+		void src;
+		retry_count = 0;
+		clearTimeout(retry_timer);
+	});
+
+	// Cancel any pending retry on unmount.
+	$effect(() => () => clearTimeout(retry_timer));
+
+	/**
+	 * Sync load_state with the actual `<img>` load load_state. Runs once on mount and again
+	 * whenever `src` changes. For cached images, `el.complete` is `true`
+	 * synchronously — without this, the SSR/hydration race causes cached images
+	 * to stay invisible because the load event fires before Svelte attaches its
+	 * onload listener.
+	 */
+	$effect(() => {
+		// No src yet (e.g. progressively assigned) — stay in the loading state so
+		// the placeholder/skeleton shows rather than falling through to `error`.
+		if (!src) {
+			load_state = 'loading';
+			fading = true;
+			return;
+		}
+		if (!img_el) return;
+		if (img_el.complete && img_el.naturalWidth > 0) {
+			load_state = 'loaded';
+			fading = false;
+		} else if (img_el.complete && img_el.naturalWidth === 0) {
+			load_state = 'error';
+			fading = false;
+		} else {
+			load_state = 'loading';
+			fading = true;
+		}
+	});
+</script>
+
+<div
+	{id}
+	class={['image', class_name].filter(Boolean).join(' ')}
+	style={container_style}
+	bind:this={element}>
+	{#if show_skeleton}
+		<div class="skeleton"></div>
+	{/if}
+
+	{#if show_placeholder}
+		<img
+			class="placeholder"
+			src={placeholder_src}
+			alt=""
+			aria-hidden="true"
+			style:object-fit={fit}
+			style:object-position={position} />
+	{/if}
+
+	{#if src && load_state !== 'error'}
+		<img
+			class="main"
+			class:fading
+			bind:this={img_el}
+			{src}
+			{alt}
+			{width}
+			{height}
+			{srcset}
+			sizes={computed_sizes}
+			loading={computed_loading}
+			fetchpriority={priority ? 'high' : undefined}
+			style:object-fit={fit}
+			style:object-position={position}
+			onload={handleLoad}
+			onerror={handleError} />
+	{/if}
+
+	{#if show_fallback}
+		{#if fallback_is_url}
+			<img
+				class="fallback-img"
+				src={fallback as string}
+				{alt}
+				style:object-fit={fit}
+				style:object-position={position} />
+		{:else}
+			<div class="fallback">
+				<svg
+					xmlns="http://www.w3.org/2000/svg"
+					viewBox="0 0 24 24"
+					fill="none"
+					stroke="currentColor"
+					stroke-width="1.5"
+					stroke-linecap="round"
+					stroke-linejoin="round"
+					class="fallback-icon"
+					aria-hidden="true">
+					<rect x="3" y="3" width="18" height="18" rx="2" ry="2" />
+					<circle cx="8.5" cy="8.5" r="1.5" />
+					<polyline points="21 15 16 10 5 21" />
+					<line x1="2" y1="2" x2="22" y2="22" />
+				</svg>
+			</div>
+		{/if}
+	{/if}
+</div>
+
+<style>
+	.image {
+		position: relative;
+		overflow: hidden;
+		display: grid;
+		width: 100%;
+	}
+
+	.image > * {
+		grid-row: 1 / 1;
+		grid-column: 1 / 1;
+	}
+
+	/* Skeleton shimmer */
+	.skeleton {
+		position: relative;
+		overflow: hidden;
+		background: var(--skeleton-bg, rgb(from var(--color-text, #888) r g b / 0.1));
+		z-index: 0;
+
+		&::after {
+			content: '';
+			position: absolute;
+			inset: 0;
+			transform: translateX(-100%);
+			background-image: linear-gradient(
+				105deg,
+				transparent 25%,
+				var(--skeleton-sheen, rgb(from var(--color-text, #888) r g b / 0.12)) 50%,
+				transparent 75%
+			);
+			animation: delight-skeleton-shimmer var(--skeleton-duration, 2.4s) ease-in-out
+				infinite;
+		}
+	}
+
+	@keyframes -global-delight-skeleton-shimmer {
+		0% {
+			transform: translateX(-100%);
+		}
+		55%,
+		100% {
+			transform: translateX(100%);
+		}
+	}
+
+	/* Blur-up placeholder — always renders underneath the main image so it shows
+	   through while the main image is loading, and is covered once it paints.
+	   `transform` makes it form a stacking context, so an explicit z-index is
+	   required to keep it below the (later-painted but un-transformed) main image. */
+	.placeholder {
+		display: block;
+		width: 100%;
+		height: 100%;
+		filter: blur(20px);
+		transform: scale(1.1);
+		pointer-events: none;
+		z-index: 0;
+	}
+
+	/* Main image — defaults to opacity 1 so cached images paint instantly during
+	   SSR. The `fading` class is added by JS only when the image isn't already
+	   loaded; `onload` removes it, triggering the fade-in over the placeholder. */
+	.main {
+		display: block;
+		width: 100%;
+		height: 100%;
+		transition: opacity 300ms ease;
+		z-index: 1;
+	}
+
+	.main.fading {
+		opacity: 0;
+		transition: none;
+	}
+
+	.fallback-img {
+		display: block;
+		width: 100%;
+		height: 100%;
+		z-index: 2;
+	}
+
+	.fallback {
+		z-index: 2;
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		background-color: var(--color-bg-muted, rgba(128, 128, 128, 0.1));
+		color: var(--color-text-muted, rgba(128, 128, 128, 0.6));
+	}
+
+	.fallback-icon {
+		width: 2.5em;
+		height: 2.5em;
+	}
+</style>

package/dist/media/Image.svelte.d.ts

@@ -0,0 +1,33 @@
+type $$ComponentProps = {
+    src: string;
+    alt: string;
+    width?: number;
+    height?: number;
+    aspect_ratio?: string;
+    fit?: 'cover' | 'contain' | 'fill' | 'none';
+    position?: string;
+    lazy?: boolean;
+    thumbhash?: string;
+    placeholder?: string;
+    bg_color?: string;
+    priority?: boolean;
+    retry?: boolean | number;
+    fallback?: string | boolean;
+    srcset?: string;
+    sizes?: string;
+    skeleton?: boolean;
+    id?: string;
+    class?: string;
+    element?: HTMLElement | undefined;
+    onload?: (detail: {
+        natural_width: number;
+        natural_height: number;
+    }) => void;
+    onerror?: (detail: {
+        error: Event;
+    }) => void;
+};
+declare const Image: import("svelte").Component<$$ComponentProps, {}, "element">;
+type Image = ReturnType<typeof Image>;
+export default Image;
+//# sourceMappingURL=Image.svelte.d.ts.map

package/dist/media/Image.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Image.svelte.d.ts","sourceRoot":"","sources":["../../src/media/Image.svelte.ts"],"names":[],"mappings":"AAOC,KAAK,gBAAgB,GAAI;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,GAAG,CAAC,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,GAAG,MAAM,CAAC;IAC5C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,KAAK,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IAClC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE;QAAE,aAAa,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IAC7E,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE;QAAE,KAAK,EAAE,KAAK,CAAA;KAAE,KAAK,IAAI,CAAC;CAC7C,CAAC;AA0OH,QAAA,MAAM,KAAK,6DAAwC,CAAC;AACpD,KAAK,KAAK,GAAG,UAAU,CAAC,OAAO,KAAK,CAAC,CAAC;AACtC,eAAe,KAAK,CAAC"}