@classic-homes/theme-svelte 1.2.3 → 1.4.0

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

@@ -0,0 +1,99 @@
+/**
+   * MediaEmbed - Lazy YouTube, Vimeo, Cloudflare Stream, and Matterport embeds
+   *
+   * Renders a poster facade and only injects the provider's iframe once the
+   * viewer clicks, so the page loads no third-party player scripts and sets no
+   * tracking cookies on arrival.
+   *
+   * Features:
+   * - Accepts a full watch URL, or an explicit provider + id
+   * - YouTube routes through `youtube-nocookie.com` by default
+   * - YouTube and Cloudflare Stream posters are derived; Vimeo needs `poster`
+   * - Matterport publishes no thumbnail: pass `poster`, or opt into
+   *   `fetchMetadata` to look one up at runtime
+   * - A Matterport space is spatial rather than timed, so its facade offers to
+   *   open a 3D tour rather than to play something
+   * - Keyboard accessible facade with a required accessible `title`
+   *
+   * For Cloudflare Stream this embeds Cloudflare's own player. To play a
+   * Stream video with this design system's controls instead, use `Video`
+   * together with `cloudflareStream()`.
+   *
+   * Note: a derived YouTube poster is still fetched from `i.ytimg.com`, which
+   * is a static image host rather than the player. Pass your own `poster` to
+   * avoid contacting the provider entirely before playback.
+   *
+   * @example
+   * ```svelte
+   * <MediaEmbed url="https://youtu.be/dQw4w9WgXcQ" title="Never Gonna Give You Up" />
+   * ```
+   *
+   * @example Cloudflare Stream
+   * ```svelte
+   * <MediaEmbed
+   *   provider="cloudflare"
+   *   videoId="a1b2c3"
+   *   customerCode="abc123"
+   *   title="Product tour"
+   * />
+   * ```
+   */
+import type { MatterportPlayerOptions, MediaAspectRatio, MediaEmbedProvider } from '../../types/components.js';
+interface Props {
+    /** Full provider URL. Ignored when `provider` and `videoId` are given. */
+    url?: string;
+    /** Hosting provider */
+    provider?: MediaEmbedProvider;
+    /** Provider-specific video identifier */
+    videoId?: string;
+    /** Matterport space id. An alias for `videoId`, named for what it is. */
+    modelId?: string;
+    /** Showcase options, for `provider="matterport"` */
+    matterport?: MatterportPlayerOptions;
+    /**
+     * Look up the space's preview image and name from Matterport.
+     *
+     * Off by default: contacting the provider before the viewer clicks is
+     * what the lazy facade exists to avoid. Matterport publishes no derivable
+     * thumbnail, so without this, supply `poster` or accept a placeholder.
+     */
+    fetchMetadata?: boolean;
+    /**
+     * Accessible name for the embedded player. Required — an iframe with no
+     * title is announced only as "frame".
+     */
+    title: string;
+    /**
+     * Poster image. Derived automatically for YouTube and Cloudflare Stream;
+     * required for Vimeo.
+     */
+    poster?: string;
+    /** Route YouTube through the no-cookie domain (default `true`) */
+    privacy?: boolean;
+    /** Start offset in seconds */
+    start?: number;
+    /** Show the provider's related-video suggestions after playback */
+    showRelated?: boolean;
+    /**
+     * Cloudflare Stream customer code, from the Stream dashboard. Required for
+     * `provider="cloudflare"` unless `domain` is given or a full `url` is used.
+     */
+    customerCode?: string;
+    /** Custom hostname serving Cloudflare Stream */
+    domain?: string;
+    /** Accent colour for the Cloudflare player UI, any CSS colour */
+    primaryColor?: string;
+    /** Letterbox colour for the Cloudflare player, any CSS colour */
+    letterboxColor?: string;
+    /** BCP-47 language code of the captions track the Cloudflare player enables */
+    defaultTextTrack?: string;
+    /** Aspect ratio of the embed box */
+    ratio?: MediaAspectRatio | number;
+    /** Load the iframe immediately instead of showing a facade */
+    eager?: boolean;
+    /** Additional classes */
+    class?: string;
+}
+declare const MediaEmbed: import("svelte").Component<Props, {}, "">;
+type MediaEmbed = ReturnType<typeof MediaEmbed>;
+export default MediaEmbed;

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

@@ -0,0 +1,327 @@
+<script lang="ts" module>
+  const COLUMN_CLASSES = {
+    base: {
+      1: 'grid-cols-1',
+      2: 'grid-cols-2',
+      3: 'grid-cols-3',
+      4: 'grid-cols-4',
+      5: 'grid-cols-5',
+      6: 'grid-cols-6',
+    } as Record<number, string>,
+    sm: {
+      1: 'sm:grid-cols-1',
+      2: 'sm:grid-cols-2',
+      3: 'sm:grid-cols-3',
+      4: 'sm:grid-cols-4',
+      5: 'sm:grid-cols-5',
+      6: 'sm:grid-cols-6',
+    } as Record<number, string>,
+    md: {
+      1: 'md:grid-cols-1',
+      2: 'md:grid-cols-2',
+      3: 'md:grid-cols-3',
+      4: 'md:grid-cols-4',
+      5: 'md:grid-cols-5',
+      6: 'md:grid-cols-6',
+    } as Record<number, string>,
+    lg: {
+      1: 'lg:grid-cols-1',
+      2: 'lg:grid-cols-2',
+      3: 'lg:grid-cols-3',
+      4: 'lg:grid-cols-4',
+      5: 'lg:grid-cols-5',
+      6: 'lg:grid-cols-6',
+    } as Record<number, string>,
+    xl: {
+      1: 'xl:grid-cols-1',
+      2: 'xl:grid-cols-2',
+      3: 'xl:grid-cols-3',
+      4: 'xl:grid-cols-4',
+      5: 'xl:grid-cols-5',
+      6: 'xl:grid-cols-6',
+    } as Record<number, string>,
+  };
+
+  const MASONRY_CLASSES = {
+    base: {
+      1: 'columns-1',
+      2: 'columns-2',
+      3: 'columns-3',
+      4: 'columns-4',
+      5: 'columns-5',
+      6: 'columns-6',
+    } as Record<number, string>,
+    sm: {
+      1: 'sm:columns-1',
+      2: 'sm:columns-2',
+      3: 'sm:columns-3',
+      4: 'sm:columns-4',
+      5: 'sm:columns-5',
+      6: 'sm:columns-6',
+    } as Record<number, string>,
+    md: {
+      1: 'md:columns-1',
+      2: 'md:columns-2',
+      3: 'md:columns-3',
+      4: 'md:columns-4',
+      5: 'md:columns-5',
+      6: 'md:columns-6',
+    } as Record<number, string>,
+    lg: {
+      1: 'lg:columns-1',
+      2: 'lg:columns-2',
+      3: 'lg:columns-3',
+      4: 'lg:columns-4',
+      5: 'lg:columns-5',
+      6: 'lg:columns-6',
+    } as Record<number, string>,
+    xl: {
+      1: 'xl:columns-1',
+      2: 'xl:columns-2',
+      3: 'xl:columns-3',
+      4: 'xl:columns-4',
+      5: 'xl:columns-5',
+      6: 'xl:columns-6',
+    } as Record<number, string>,
+  };
+</script>
+
+<script lang="ts">
+  /**
+   * MediaGrid - Responsive gallery of media thumbnails
+   *
+   * Features:
+   * - Responsive grid, or a masonry layout for mixed-height images
+   * - Arrow-key navigation that moves a row at a time, not an item at a time
+   * - A single tab stop by default, so a large gallery does not flood tab order
+   * - Play affordance and duration badge for video, audio, and embeds
+   * - Opens the built-in Lightbox on selection unless `lightbox` is disabled
+   *
+   * @example
+   * ```svelte
+   * <MediaGrid items={photos} columns={{ base: 2, md: 3, lg: 4 }} label="Project photos" />
+   * ```
+   */
+  import type { MediaAspectRatio, MediaItem } from '../../types/components.js';
+  import { cn } from '../../utils.js';
+  import Lightbox from './Lightbox.svelte';
+  import MediaTile from './internal/MediaTile.svelte';
+
+  /** Responsive column counts, keyed by breakpoint. */
+  export interface MediaGridColumns {
+    base?: number;
+    sm?: number;
+    md?: number;
+    lg?: number;
+    xl?: number;
+  }
+
+  interface Props {
+    /** Items to display */
+    items: MediaItem[];
+    /** Accessible name for the gallery list */
+    label?: string;
+    /**
+     * `grid` keeps every tile the same size (best for uniform thumbnails).
+     * `masonry` preserves each image's own height via CSS columns — note that
+     * CSS columns fill top-to-bottom, so the visual order runs down each
+     * column rather than across each row.
+     */
+    variant?: 'grid' | 'masonry';
+    /** Column counts per breakpoint */
+    columns?: MediaGridColumns;
+    /** Gap between tiles */
+    gap?: 'none' | 'sm' | 'md' | 'lg';
+    /** Aspect ratio of each tile (ignored in `masonry`) */
+    ratio?: MediaAspectRatio | number;
+    /** Open the built-in lightbox when a tile is selected */
+    lightbox?: boolean;
+    /**
+     * Keep the gallery to a single tab stop and move between tiles with the
+     * arrow keys. Set `false` to make every tile individually tabbable.
+     */
+    singleTabStop?: boolean;
+    /** Called with the selected index, whether or not the lightbox opens */
+    onSelect?: (index: number, item: MediaItem) => void;
+    /** Additional classes */
+    class?: string;
+  }
+
+  let {
+    items,
+    label = 'Media gallery',
+    variant = 'grid',
+    columns = { base: 2, md: 3, lg: 4 },
+    gap = 'md',
+    ratio = 'square',
+    lightbox = true,
+    singleTabStop = true,
+    onSelect,
+    class: className,
+  }: Props = $props();
+
+  let listElement = $state<HTMLElement | null>(null);
+  let activeIndex = $state(0);
+  let lightboxOpen = $state(false);
+  let lightboxIndex = $state(0);
+
+  const gapClass = $derived(
+    ({ none: 'gap-0', sm: 'gap-2', md: 'gap-4', lg: 'gap-6' } as const)[gap]
+  );
+
+  // CSS multi-column honours `gap` horizontally only, so vertical rhythm in
+  // masonry has to come from a bottom margin on each item.
+  const masonryItemGapClass = $derived(
+    ({ none: '', sm: 'mb-2', md: 'mb-4', lg: 'mb-6' } as const)[gap]
+  );
+
+  // Column utilities are written out in full rather than interpolated, because
+  // Tailwind only ships classes it can find as complete strings in the source.
+  const gridColsClass = $derived(
+    [
+      COLUMN_CLASSES.base[columns.base ?? 2],
+      columns.sm ? COLUMN_CLASSES.sm[columns.sm] : '',
+      columns.md ? COLUMN_CLASSES.md[columns.md] : '',
+      columns.lg ? COLUMN_CLASSES.lg[columns.lg] : '',
+      columns.xl ? COLUMN_CLASSES.xl[columns.xl] : '',
+    ]
+      .filter(Boolean)
+      .join(' ')
+  );
+
+  const masonryColsClass = $derived(
+    [
+      MASONRY_CLASSES.base[columns.base ?? 2],
+      columns.sm ? MASONRY_CLASSES.sm[columns.sm] : '',
+      columns.md ? MASONRY_CLASSES.md[columns.md] : '',
+      columns.lg ? MASONRY_CLASSES.lg[columns.lg] : '',
+      columns.xl ? MASONRY_CLASSES.xl[columns.xl] : '',
+    ]
+      .filter(Boolean)
+      .join(' ')
+  );
+
+  function getTiles(): HTMLElement[] {
+    if (!listElement) return [];
+    return Array.from(listElement.querySelectorAll<HTMLElement>('[data-media-tile]'));
+  }
+
+  /**
+   * Number of tiles per visual row, read from layout rather than from the
+   * `columns` prop — the prop describes breakpoints, only the DOM knows which
+   * one is active. Tiles sharing an `offsetTop` are on the same row.
+   */
+  function getColumnCount(tiles: HTMLElement[]): number {
+    if (tiles.length === 0) return 1;
+    const firstTop = tiles[0].offsetTop;
+    let count = 0;
+    for (const tile of tiles) {
+      if (tile.offsetTop !== firstTop) break;
+      count += 1;
+    }
+    return Math.max(count, 1);
+  }
+
+  function focusTile(index: number) {
+    const tiles = getTiles();
+    if (tiles.length === 0) return;
+    const clamped = Math.max(0, Math.min(index, tiles.length - 1));
+    activeIndex = clamped;
+    tiles[clamped].focus();
+  }
+
+  function handleKeyDown(event: KeyboardEvent) {
+    const tiles = getTiles();
+    if (tiles.length === 0) return;
+
+    // Masonry lays out in columns, so a computed "row" would be meaningless;
+    // fall back to linear movement there.
+    const columnCount = variant === 'masonry' ? 1 : getColumnCount(tiles);
+    const current = tiles.findIndex((tile) => tile === document.activeElement);
+    const from = current === -1 ? activeIndex : current;
+
+    let next: number | null = null;
+
+    switch (event.key) {
+      case 'ArrowRight':
+        next = from + 1;
+        break;
+      case 'ArrowLeft':
+        next = from - 1;
+        break;
+      case 'ArrowDown':
+        next = from + columnCount;
+        break;
+      case 'ArrowUp':
+        next = from - columnCount;
+        break;
+      case 'Home':
+        next = 0;
+        break;
+      case 'End':
+        next = tiles.length - 1;
+        break;
+      default:
+        return;
+    }
+
+    if (next === null || next < 0 || next >= tiles.length) {
+      // Swallow the key at the edges so the page does not scroll unexpectedly
+      // mid-navigation, but leave focus where it is.
+      if (event.key.startsWith('Arrow')) event.preventDefault();
+      return;
+    }
+
+    event.preventDefault();
+    focusTile(next);
+  }
+
+  function handleSelect(index: number) {
+    activeIndex = index;
+    onSelect?.(index, items[index]);
+    if (lightbox) {
+      lightboxIndex = index;
+      lightboxOpen = true;
+    }
+  }
+</script>
+
+{#if items.length === 0}
+  <p class={cn('py-8 text-center text-sm text-muted-foreground', className)}>No media to show.</p>
+{:else}
+  <!--
+    The keydown handler is delegated from the list purely to move focus
+    between the tile buttons inside it; the buttons themselves remain the
+    interactive elements.
+  -->
+  <!-- svelte-ignore a11y_no_noninteractive_element_interactions -->
+  <ul
+    bind:this={listElement}
+    aria-label={label}
+    class={cn(
+      variant === 'masonry' ? masonryColsClass : cn('grid', gridColsClass),
+      gapClass,
+      'list-none p-0',
+      className
+    )}
+    onkeydown={handleKeyDown}
+  >
+    {#each items as item, index (item.id)}
+      <li class={cn(variant === 'masonry' && cn('break-inside-avoid', masonryItemGapClass))}>
+        <MediaTile
+          {item}
+          {index}
+          ratio={variant === 'masonry' ? undefined : ratio}
+          onselect={handleSelect}
+          class="h-full"
+          data-media-tile
+          tabindex={!singleTabStop || index === activeIndex ? 0 : -1}
+        />
+      </li>
+    {/each}
+  </ul>
+
+  {#if lightbox}
+    <Lightbox {items} bind:open={lightboxOpen} bind:index={lightboxIndex} />
+  {/if}
+{/if}

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

@@ -0,0 +1,57 @@
+/**
+   * MediaGrid - Responsive gallery of media thumbnails
+   *
+   * Features:
+   * - Responsive grid, or a masonry layout for mixed-height images
+   * - Arrow-key navigation that moves a row at a time, not an item at a time
+   * - A single tab stop by default, so a large gallery does not flood tab order
+   * - Play affordance and duration badge for video, audio, and embeds
+   * - Opens the built-in Lightbox on selection unless `lightbox` is disabled
+   *
+   * @example
+   * ```svelte
+   * <MediaGrid items={photos} columns={{ base: 2, md: 3, lg: 4 }} label="Project photos" />
+   * ```
+   */
+import type { MediaAspectRatio, MediaItem } from '../../types/components.js';
+/** Responsive column counts, keyed by breakpoint. */
+export interface MediaGridColumns {
+    base?: number;
+    sm?: number;
+    md?: number;
+    lg?: number;
+    xl?: number;
+}
+interface Props {
+    /** Items to display */
+    items: MediaItem[];
+    /** Accessible name for the gallery list */
+    label?: string;
+    /**
+     * `grid` keeps every tile the same size (best for uniform thumbnails).
+     * `masonry` preserves each image's own height via CSS columns — note that
+     * CSS columns fill top-to-bottom, so the visual order runs down each
+     * column rather than across each row.
+     */
+    variant?: 'grid' | 'masonry';
+    /** Column counts per breakpoint */
+    columns?: MediaGridColumns;
+    /** Gap between tiles */
+    gap?: 'none' | 'sm' | 'md' | 'lg';
+    /** Aspect ratio of each tile (ignored in `masonry`) */
+    ratio?: MediaAspectRatio | number;
+    /** Open the built-in lightbox when a tile is selected */
+    lightbox?: boolean;
+    /**
+     * Keep the gallery to a single tab stop and move between tiles with the
+     * arrow keys. Set `false` to make every tile individually tabbable.
+     */
+    singleTabStop?: boolean;
+    /** Called with the selected index, whether or not the lightbox opens */
+    onSelect?: (index: number, item: MediaItem) => void;
+    /** Additional classes */
+    class?: string;
+}
+declare const MediaGrid: import("svelte").Component<Props, {}, "">;
+type MediaGrid = ReturnType<typeof MediaGrid>;
+export default MediaGrid;