@classic-homes/theme-svelte 1.2.2 → 1.3.0

package/dist/lib/components/media/Image.svelte

@@ -0,0 +1,209 @@
+<script lang="ts">
+  /**
+   * Image - Responsive image with loading, placeholder, and error handling
+   *
+   * Features:
+   * - Lazy loading and async decoding by default
+   * - Skeleton or blurred low-resolution placeholder while loading
+   * - Graceful fallback when the source fails to load
+   * - Optional aspect-ratio box that reserves layout space (no layout shift)
+   * - `alt` is required at the type level; pass an empty string for decorative images
+   */
+  import type { Snippet } from 'svelte';
+  import type { HTMLImgAttributes } from 'svelte/elements';
+  import { tv, type VariantProps } from 'tailwind-variants';
+  import type { MediaAspectRatio } from '../../types/components.js';
+  import { cn } from '../../utils.js';
+  import Icon from '../Icon.svelte';
+  import Skeleton from '../Skeleton.svelte';
+  import AspectRatio from './AspectRatio.svelte';
+
+  const imageVariants = tv({
+    slots: {
+      wrapper: 'relative isolate overflow-hidden bg-muted',
+      img: 'block h-full w-full',
+    },
+    variants: {
+      fit: {
+        cover: { img: 'object-cover' },
+        contain: { img: 'object-contain' },
+        fill: { img: 'object-fill' },
+        none: { img: 'object-none' },
+        'scale-down': { img: 'object-scale-down' },
+      },
+      rounded: {
+        none: { wrapper: 'rounded-none' },
+        sm: { wrapper: 'rounded-sm' },
+        md: { wrapper: 'rounded-md' },
+        lg: { wrapper: 'rounded-lg' },
+        xl: { wrapper: 'rounded-xl' },
+        full: { wrapper: 'rounded-full' },
+      },
+    },
+    defaultVariants: {
+      fit: 'cover',
+      rounded: 'none',
+    },
+  });
+
+  type ImageVariants = VariantProps<typeof imageVariants>;
+
+  interface Props extends Omit<HTMLImgAttributes, 'alt' | 'class' | 'onload' | 'onerror'> {
+    /** Image URL */
+    src: string;
+    /**
+     * Alternative text. Required — pass an empty string only when the image is
+     * purely decorative and the surrounding content already conveys its meaning.
+     */
+    alt: string;
+    /**
+     * Constrain the image to a ratio box. Omit to let the image size itself
+     * from its intrinsic dimensions.
+     */
+    ratio?: MediaAspectRatio | number;
+    /** How the image fills its box */
+    fit?: ImageVariants['fit'];
+    /** Corner rounding */
+    rounded?: ImageVariants['rounded'];
+    /**
+     * Low-resolution placeholder (typically a tiny data URL) blurred in behind
+     * the image and cross-faded out once the real image decodes.
+     */
+    placeholder?: string;
+    /** Show a pulsing skeleton while loading (ignored when `placeholder` is set) */
+    showSkeleton?: boolean;
+    /** Called once the image has loaded */
+    onload?: (event: Event) => void;
+    /** Called when the image fails to load */
+    onerror?: (event: Event) => void;
+    /** Custom content rendered in place of a failed image */
+    fallback?: Snippet;
+    /** Content overlaid on the image, such as a caption or badge */
+    overlay?: Snippet;
+    /** Additional classes applied to the wrapper */
+    class?: string;
+    /** Additional classes applied to the `<img>` element itself */
+    imgClass?: string;
+  }
+
+  let {
+    src,
+    alt,
+    ratio,
+    fit = 'cover',
+    rounded = 'none',
+    placeholder,
+    showSkeleton = true,
+    onload,
+    onerror,
+    fallback,
+    overlay,
+    class: className,
+    imgClass,
+    loading = 'lazy',
+    decoding = 'async',
+    ...restProps
+  }: Props = $props();
+
+  // Track load state per-URL rather than as a mutable flag, so swapping `src`
+  // automatically returns to the loading state without a reset effect.
+  let loadedSrc = $state<string | null>(null);
+  let erroredSrc = $state<string | null>(null);
+
+  const status = $derived<'loading' | 'loaded' | 'error'>(
+    erroredSrc === src ? 'error' : loadedSrc === src ? 'loaded' : 'loading'
+  );
+
+  const styles = $derived(imageVariants({ fit, rounded }));
+
+  function handleLoad(event: Event) {
+    loadedSrc = src;
+    onload?.(event);
+  }
+
+  function handleError(event: Event) {
+    erroredSrc = src;
+    onerror?.(event);
+  }
+
+  /**
+   * An image already in the memory cache can finish decoding before the `load`
+   * listener is attached, and then never fires it. `complete` covers that case.
+   */
+  function detectCached(node: HTMLImageElement) {
+    if (node.complete && node.currentSrc) {
+      if (node.naturalWidth > 0) loadedSrc = src;
+      else erroredSrc = src;
+    }
+  }
+
+  if (typeof process !== 'undefined' && process.env?.NODE_ENV !== 'production') {
+    $effect(() => {
+      if (alt === undefined) {
+        console.warn(
+          'Image: Missing "alt" prop. Provide descriptive alternative text, or an empty string ("") if the image is decorative.'
+        );
+      }
+    });
+  }
+</script>
+
+{#snippet layers()}
+  {#if status === 'error'}
+    <div
+      class="flex h-full w-full min-h-[3rem] items-center justify-center bg-muted text-muted-foreground"
+    >
+      {#if fallback}
+        {@render fallback()}
+      {:else}
+        <Icon name="image" size={32} label={alt ? `Failed to load: ${alt}` : 'Image unavailable'} />
+      {/if}
+    </div>
+  {:else}
+    {#if placeholder}
+      <img
+        src={placeholder}
+        alt=""
+        aria-hidden="true"
+        class={cn(
+          styles.img(),
+          'absolute inset-0 scale-105 blur-lg transition-opacity duration-300',
+          status === 'loaded' ? 'opacity-0' : 'opacity-100'
+        )}
+      />
+    {:else if showSkeleton && status === 'loading'}
+      <Skeleton class="absolute inset-0 h-full w-full rounded-none" />
+    {/if}
+
+    <img
+      {src}
+      {alt}
+      {loading}
+      {decoding}
+      class={cn(
+        styles.img(),
+        'relative transition-opacity duration-300',
+        status === 'loaded' ? 'opacity-100' : 'opacity-0',
+        imgClass
+      )}
+      onload={handleLoad}
+      onerror={handleError}
+      use:detectCached
+      {...restProps}
+    />
+  {/if}
+
+  {#if overlay}
+    {@render overlay()}
+  {/if}
+{/snippet}
+
+{#if ratio}
+  <AspectRatio {ratio} class={cn(styles.wrapper(), className)}>
+    {@render layers()}
+  </AspectRatio>
+{:else}
+  <div class={cn(styles.wrapper(), 'inline-block', className)}>
+    {@render layers()}
+  </div>
+{/if}

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

@@ -0,0 +1,52 @@
+/**
+   * Image - Responsive image with loading, placeholder, and error handling
+   *
+   * Features:
+   * - Lazy loading and async decoding by default
+   * - Skeleton or blurred low-resolution placeholder while loading
+   * - Graceful fallback when the source fails to load
+   * - Optional aspect-ratio box that reserves layout space (no layout shift)
+   * - `alt` is required at the type level; pass an empty string for decorative images
+   */
+import type { Snippet } from 'svelte';
+import type { HTMLImgAttributes } from 'svelte/elements';
+import type { MediaAspectRatio } from '../../types/components.js';
+declare const Image: import("svelte").Component<Omit<HTMLImgAttributes, "class" | "onload" | "onerror" | "alt"> & {
+    /** Image URL */
+    src: string;
+    /**
+     * Alternative text. Required — pass an empty string only when the image is
+     * purely decorative and the surrounding content already conveys its meaning.
+     */
+    alt: string;
+    /**
+     * Constrain the image to a ratio box. Omit to let the image size itself
+     * from its intrinsic dimensions.
+     */
+    ratio?: MediaAspectRatio | number;
+    /** How the image fills its box */
+    fit?: "none" | "cover" | "contain" | "fill" | "scale-down" | undefined;
+    /** Corner rounding */
+    rounded?: "sm" | "md" | "lg" | "xl" | "none" | "full" | undefined;
+    /**
+     * Low-resolution placeholder (typically a tiny data URL) blurred in behind
+     * the image and cross-faded out once the real image decodes.
+     */
+    placeholder?: string;
+    /** Show a pulsing skeleton while loading (ignored when `placeholder` is set) */
+    showSkeleton?: boolean;
+    /** Called once the image has loaded */
+    onload?: (event: Event) => void;
+    /** Called when the image fails to load */
+    onerror?: (event: Event) => void;
+    /** Custom content rendered in place of a failed image */
+    fallback?: Snippet;
+    /** Content overlaid on the image, such as a caption or badge */
+    overlay?: Snippet;
+    /** Additional classes applied to the wrapper */
+    class?: string;
+    /** Additional classes applied to the `<img>` element itself */
+    imgClass?: string;
+}, {}, "">;
+type Image = ReturnType<typeof Image>;
+export default Image;