@classic-homes/theme-svelte 1.2.2 → 1.3.0

package/README.md

@@ -102,6 +102,49 @@ Or in your root layout:
 - `DropdownMenu` - Dropdown menus
 - `Avatar` - User avatars
 
+### Media
+
+- `AspectRatio` - Constrains content to a fixed width-to-height ratio
+- `Image` - Responsive image with lazy loading, placeholders, and error fallback
+- `Video` - Video player with themed controls, full keyboard support, and HLS/Cloudflare Stream playback
+- `Audio` - Compact audio player with themed controls
+- `MediaEmbed` - Lazy YouTube, Vimeo, Cloudflare Stream, and Matterport 3D tour embeds that load nothing until clicked
+- `MediaGrid` - Responsive gallery of media thumbnails
+- `MediaCarousel` - Swipeable media slides with dots, thumbnails, and optional autoplay
+- `Lightbox` - Full-screen media viewer with zoom, pan, and keyboard navigation
+
+#### Adaptive streaming and Cloudflare Stream
+
+`Video` plays HLS playlists, including Cloudflare Stream, with the same controls as a self-hosted file. Safari plays HLS natively; other browsers need [hls.js](https://github.com/video-dev/hls.js), an **optional peer dependency**:
+
+```bash
+npm install hls.js
+```
+
+```ts
+// once, at app startup
+import { setHlsLoader } from '@classic-homes/theme-svelte';
+
+setHlsLoader(() => import('hls.js').then((m) => m.default));
+```
+
+The import lives in your code rather than in this package, so consumers who never play a stream are not forced to install hls.js to build.
+
+```svelte
+<script lang="ts">
+  import { Video, cloudflareStream } from '@classic-homes/theme-svelte';
+
+  const tour = cloudflareStream('a1b2c3d4e5f6', {
+    customerCode: 'abc123',
+    title: 'Product tour',
+  });
+</script>
+
+<Video item={tour} />
+```
+
+`cloudflareStream()` derives the HLS playlist and poster from Stream's URL scheme with no API call. Pass a signed playback token in place of the video id for private videos. For Cloudflare's own player, use `MediaEmbed` with `provider="cloudflare"`.
+
 ### Branding
 
 - `LogoMain` - Main logo component

package/dist/__tests__/a11y/Media.a11y.test.js

@@ -0,0 +1,145 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { render, screen } from '@testing-library/svelte';
+import { axe } from 'vitest-axe';
+import Audio from '../../lib/components/media/Audio.svelte';
+import Image from '../../lib/components/media/Image.svelte';
+import Lightbox from '../../lib/components/media/Lightbox.svelte';
+import MediaCarousel from '../../lib/components/media/MediaCarousel.svelte';
+import MediaEmbed from '../../lib/components/media/MediaEmbed.svelte';
+import MediaGrid from '../../lib/components/media/MediaGrid.svelte';
+import Video from '../../lib/components/media/Video.svelte';
+const items = [
+    { id: '1', kind: 'image', src: '/one.jpg', alt: 'A harbour at dawn', caption: 'Dawn' },
+    { id: '2', kind: 'image', src: '/two.jpg', alt: 'A field of wheat' },
+    { id: '3', kind: 'video', src: '/clip.mp4', poster: '/clip.jpg', title: 'Walkthrough' },
+];
+const captions = [{ src: '/clip.en.vtt', srclang: 'en', label: 'English', default: true }];
+beforeEach(() => {
+    // Video warns when captions are missing; those cases are covered elsewhere.
+    vi.spyOn(console, 'warn').mockImplementation(() => { });
+});
+describe('Image accessibility', () => {
+    it('has no axe violations', async () => {
+        const { container } = render(Image, { props: { src: '/photo.jpg', alt: 'A landscape' } });
+        expect(await axe(container)).toHaveNoViolations();
+    });
+    it('has no violations with a decorative empty alt', async () => {
+        const { container } = render(Image, { props: { src: '/divider.png', alt: '' } });
+        expect(await axe(container)).toHaveNoViolations();
+    });
+    it('exposes the alt text as the image name', () => {
+        render(Image, { props: { src: '/photo.jpg', alt: 'A landscape' } });
+        expect(screen.getByRole('img', { name: 'A landscape' })).toBeInTheDocument();
+    });
+});
+describe('Video accessibility', () => {
+    it('has no axe violations', async () => {
+        const { container } = render(Video, {
+            props: { src: '/clip.mp4', label: 'Product tour', tracks: captions },
+        });
+        expect(await axe(container)).toHaveNoViolations();
+    });
+    it('names the region and every transport control', () => {
+        render(Video, { props: { src: '/clip.mp4', label: 'Product tour', tracks: captions } });
+        expect(screen.getByRole('region')).toHaveAccessibleName('Product tour');
+        expect(screen.getByRole('button', { name: 'Play' })).toBeInTheDocument();
+        expect(screen.getByRole('slider', { name: 'Seek' })).toBeInTheDocument();
+        expect(screen.getByRole('slider', { name: 'Volume' })).toBeInTheDocument();
+    });
+    it('announces the seek position as a spoken timestamp, not raw seconds', () => {
+        render(Video, { props: { src: '/clip.mp4', tracks: captions } });
+        expect(screen.getByRole('slider', { name: 'Seek' })).toHaveAttribute('aria-valuetext', '0 seconds of 0 seconds');
+    });
+});
+describe('Audio accessibility', () => {
+    it('has no axe violations', async () => {
+        const { container } = render(Audio, {
+            props: { src: '/episode.mp3', title: 'Episode 12', artist: 'Design Notes' },
+        });
+        expect(await axe(container)).toHaveNoViolations();
+    });
+});
+describe('MediaEmbed accessibility', () => {
+    it('has no axe violations in its facade state', async () => {
+        const { container } = render(MediaEmbed, {
+            props: { url: 'https://youtu.be/dQw4w9WgXcQ', title: 'A song' },
+        });
+        expect(await axe(container)).toHaveNoViolations();
+    });
+    it('names the facade with the provider and title', () => {
+        render(MediaEmbed, { props: { url: 'https://youtu.be/dQw4w9WgXcQ', title: 'A song' } });
+        expect(screen.getByRole('button')).toHaveAccessibleName('Play A song on YouTube');
+    });
+    it('has no axe violations for a Matterport tour facade', async () => {
+        const { container } = render(MediaEmbed, {
+            props: { provider: 'matterport', modelId: 'SxQL3iGyoDo', title: 'Show home' },
+        });
+        expect(await axe(container)).toHaveNoViolations();
+    });
+    it('says a tour opens rather than plays', () => {
+        render(MediaEmbed, {
+            props: { provider: 'matterport', modelId: 'SxQL3iGyoDo', title: 'Show home' },
+        });
+        expect(screen.getByRole('button')).toHaveAccessibleName('Open Show home as a 3D tour on Matterport');
+    });
+});
+describe('MediaGrid accessibility', () => {
+    it('has no axe violations', async () => {
+        const { container } = render(MediaGrid, { props: { items, label: 'Project photos' } });
+        expect(await axe(container)).toHaveNoViolations();
+    });
+    it('names the list and every tile', () => {
+        render(MediaGrid, { props: { items, label: 'Project photos' } });
+        expect(screen.getByRole('list')).toHaveAccessibleName('Project photos');
+        expect(screen.getByRole('button', { name: 'A harbour at dawn' })).toBeInTheDocument();
+        expect(screen.getByRole('button', { name: 'Walkthrough' })).toBeInTheDocument();
+    });
+    it('has no violations in the masonry variant', async () => {
+        const { container } = render(MediaGrid, { props: { items, variant: 'masonry' } });
+        expect(await axe(container)).toHaveNoViolations();
+    });
+});
+describe('MediaCarousel accessibility', () => {
+    it('has no axe violations', async () => {
+        const { container } = render(MediaCarousel, {
+            props: { items, label: 'Project gallery' },
+        });
+        expect(await axe(container)).toHaveNoViolations();
+    });
+    it('carries the carousel and slide role descriptions', () => {
+        render(MediaCarousel, { props: { items, label: 'Project gallery' } });
+        const carousel = screen.getByRole('region', { name: 'Project gallery' });
+        expect(carousel).toHaveAttribute('aria-roledescription', 'carousel');
+        const slides = screen.getAllByRole('group');
+        expect(slides[0]).toHaveAttribute('aria-roledescription', 'slide');
+        expect(slides[0]).toHaveAccessibleName('1 of 3');
+    });
+    it('offers a pause control whenever autoplay is enabled (WCAG 2.2.2)', () => {
+        render(MediaCarousel, { props: { items, autoplay: true } });
+        expect(screen.getByRole('button', { name: 'Stop automatic slideshow' })).toBeInTheDocument();
+    });
+    it('has no violations with the thumbnail strip shown', async () => {
+        const { container } = render(MediaCarousel, { props: { items, showThumbnails: true } });
+        expect(await axe(container)).toHaveNoViolations();
+    });
+});
+describe('Lightbox accessibility', () => {
+    it('has no axe violations when open', async () => {
+        render(Lightbox, { props: { items, open: true } });
+        await screen.findByRole('dialog');
+        // The dialog is portalled to the body, so axe has to run against it.
+        expect(await axe(document.body)).toHaveNoViolations();
+    });
+    it('is a modal dialog with an accessible name and description', async () => {
+        render(Lightbox, { props: { items, open: true } });
+        const dialog = await screen.findByRole('dialog');
+        expect(dialog).toHaveAttribute('aria-modal', 'true');
+        expect(dialog).toHaveAccessibleName('A harbour at dawn');
+        expect(dialog).toHaveAccessibleDescription('Dawn');
+    });
+    it('has no violations with the thumbnail strip shown', async () => {
+        render(Lightbox, { props: { items, open: true, showThumbnails: true } });
+        await screen.findByRole('dialog');
+        expect(await axe(document.body)).toHaveNoViolations();
+    });
+});

package/dist/__tests__/media-components.test.js

@@ -0,0 +1,206 @@
+import { describe, expect, it, vi } from 'vitest';
+import { fireEvent, render, screen, waitFor } from '@testing-library/svelte';
+import userEvent from '@testing-library/user-event';
+import Image from '../lib/components/media/Image.svelte';
+import MediaEmbed from '../lib/components/media/MediaEmbed.svelte';
+import MediaGrid from '../lib/components/media/MediaGrid.svelte';
+import Lightbox from '../lib/components/media/Lightbox.svelte';
+const photos = [
+    { id: '1', kind: 'image', src: '/one.jpg', alt: 'First photo' },
+    { id: '2', kind: 'image', src: '/two.jpg', alt: 'Second photo' },
+    { id: '3', kind: 'image', src: '/three.jpg', alt: 'Third photo' },
+];
+describe('Image', () => {
+    it('renders the image with its alt text and lazy-loads by default', () => {
+        render(Image, { props: { src: '/photo.jpg', alt: 'A landscape' } });
+        const img = screen.getByAltText('A landscape');
+        expect(img).toBeInTheDocument();
+        expect(img).toHaveAttribute('loading', 'lazy');
+        expect(img).toHaveAttribute('decoding', 'async');
+    });
+    it('honours an explicit loading override', () => {
+        render(Image, { props: { src: '/hero.jpg', alt: 'Hero', loading: 'eager' } });
+        expect(screen.getByAltText('Hero')).toHaveAttribute('loading', 'eager');
+    });
+    it('swaps in the fallback when the source fails', async () => {
+        render(Image, { props: { src: '/missing.jpg', alt: 'Missing' } });
+        const img = screen.getByAltText('Missing');
+        await fireEvent.error(img);
+        await waitFor(() => {
+            expect(screen.queryByAltText('Missing')).not.toBeInTheDocument();
+        });
+        // The fallback icon carries the alt text so the failure is still described.
+        expect(screen.getByText('Failed to load: Missing')).toBeInTheDocument();
+    });
+    it('reports load and error through the callbacks', async () => {
+        const onload = vi.fn();
+        render(Image, { props: { src: '/photo.jpg', alt: 'Photo', onload } });
+        await fireEvent.load(screen.getByAltText('Photo'));
+        expect(onload).toHaveBeenCalledOnce();
+    });
+    it('applies sizing classes to the element that carries the size', async () => {
+        // Regression: `class` used to land on the ratio box's inner, absolutely
+        // inset element, so `w-24` and friends were silently dropped.
+        const { container } = render(Image, {
+            props: { src: '/photo.jpg', alt: 'Photo', ratio: 'square', class: 'w-24' },
+        });
+        const sized = container.querySelector('.w-24');
+        expect(sized).not.toBeNull();
+        expect(getComputedStyle(sized).position).not.toBe('absolute');
+    });
+    it('renders a blurred placeholder behind the image while loading', () => {
+        const { container } = render(Image, {
+            props: { src: '/photo.jpg', alt: 'Photo', placeholder: 'data:image/gif;base64,AAAA' },
+        });
+        const placeholder = container.querySelector('img[aria-hidden="true"]');
+        expect(placeholder).toHaveAttribute('src', 'data:image/gif;base64,AAAA');
+        // Decorative, so it must not be exposed as a second image.
+        expect(placeholder).toHaveAttribute('alt', '');
+    });
+});
+describe('MediaEmbed', () => {
+    it('shows a facade and requests nothing from the provider before activation', () => {
+        const { container } = render(MediaEmbed, {
+            props: { url: 'https://youtu.be/dQw4w9WgXcQ', title: 'A song' },
+        });
+        expect(container.querySelector('iframe')).toBeNull();
+        expect(screen.getByRole('button', { name: 'Play A song on YouTube' })).toBeInTheDocument();
+    });
+    it('injects a privacy-domain iframe once the facade is clicked', async () => {
+        const user = userEvent.setup();
+        const { container } = render(MediaEmbed, {
+            props: { url: 'https://youtu.be/dQw4w9WgXcQ', title: 'A song' },
+        });
+        await user.click(screen.getByRole('button', { name: /Play A song/ }));
+        const iframe = container.querySelector('iframe');
+        expect(iframe).not.toBeNull();
+        expect(iframe).toHaveAttribute('title', 'A song');
+        expect(iframe?.getAttribute('src')).toContain('youtube-nocookie.com');
+        // Autoplay is only added after the click, satisfying the user-gesture rule.
+        expect(iframe?.getAttribute('src')).toContain('autoplay=1');
+    });
+    it('renders an error state for an unrecognised URL rather than a broken frame', () => {
+        const { container } = render(MediaEmbed, {
+            props: { url: 'https://example.com/video', title: 'Unknown' },
+        });
+        expect(container.querySelector('iframe')).toBeNull();
+        expect(screen.getByRole('alert')).toHaveTextContent('This video could not be loaded.');
+    });
+});
+describe('MediaGrid', () => {
+    it('renders one labelled tile per item', () => {
+        render(MediaGrid, { props: { items: photos, label: 'Project photos' } });
+        expect(screen.getByRole('list', { name: 'Project photos' })).toBeInTheDocument();
+        expect(screen.getByRole('button', { name: 'First photo' })).toBeInTheDocument();
+        expect(screen.getByRole('button', { name: 'Third photo' })).toBeInTheDocument();
+    });
+    it('keeps a single tab stop by default', () => {
+        render(MediaGrid, { props: { items: photos } });
+        const tiles = screen.getAllByRole('button');
+        expect(tiles[0]).toHaveAttribute('tabindex', '0');
+        expect(tiles[1]).toHaveAttribute('tabindex', '-1');
+    });
+    it('makes every tile tabbable when singleTabStop is off', () => {
+        render(MediaGrid, { props: { items: photos, singleTabStop: false } });
+        for (const tile of screen.getAllByRole('button')) {
+            expect(tile).toHaveAttribute('tabindex', '0');
+        }
+    });
+    it('moves focus with the arrow keys', async () => {
+        render(MediaGrid, { props: { items: photos, lightbox: false } });
+        const tiles = screen.getAllByRole('button');
+        tiles[0].focus();
+        await fireEvent.keyDown(screen.getByRole('list'), { key: 'ArrowRight' });
+        expect(document.activeElement).toBe(tiles[1]);
+        await fireEvent.keyDown(screen.getByRole('list'), { key: 'End' });
+        expect(document.activeElement).toBe(tiles[2]);
+        await fireEvent.keyDown(screen.getByRole('list'), { key: 'Home' });
+        expect(document.activeElement).toBe(tiles[0]);
+    });
+    it('reports the selected index without opening a lightbox when disabled', async () => {
+        const user = userEvent.setup();
+        const onSelect = vi.fn();
+        render(MediaGrid, { props: { items: photos, lightbox: false, onSelect } });
+        await user.click(screen.getByRole('button', { name: 'Second photo' }));
+        expect(onSelect).toHaveBeenCalledWith(1, photos[1]);
+        expect(screen.queryByRole('dialog')).not.toBeInTheDocument();
+    });
+    it('renders an empty state rather than a bare list', () => {
+        render(MediaGrid, { props: { items: [] } });
+        expect(screen.getByText('No media to show.')).toBeInTheDocument();
+        expect(screen.queryByRole('list')).not.toBeInTheDocument();
+    });
+});
+describe('Lightbox', () => {
+    it('renders nothing until it is opened', () => {
+        render(Lightbox, { props: { items: photos } });
+        expect(screen.queryByRole('dialog')).not.toBeInTheDocument();
+    });
+    it('exposes an accessible name taken from the active item', async () => {
+        render(Lightbox, { props: { items: photos, open: true } });
+        const dialog = await screen.findByRole('dialog');
+        expect(dialog).toHaveAccessibleName('First photo');
+    });
+    it('navigates between items with the arrow keys', async () => {
+        render(Lightbox, { props: { items: photos, open: true } });
+        const dialog = await screen.findByRole('dialog');
+        expect(dialog).toHaveAccessibleName('First photo');
+        await fireEvent.keyDown(dialog, { key: 'ArrowRight' });
+        await waitFor(() => expect(dialog).toHaveAccessibleName('Second photo'));
+        await fireEvent.keyDown(dialog, { key: 'End' });
+        await waitFor(() => expect(dialog).toHaveAccessibleName('Third photo'));
+        // Wraps by default, so Next from the last item returns to the first.
+        await fireEvent.keyDown(dialog, { key: 'ArrowRight' });
+        await waitFor(() => expect(dialog).toHaveAccessibleName('First photo'));
+    });
+    it('stops at the ends when looping is disabled', async () => {
+        render(Lightbox, { props: { items: photos, open: true, loop: false } });
+        const dialog = await screen.findByRole('dialog');
+        await fireEvent.keyDown(dialog, { key: 'ArrowLeft' });
+        await waitFor(() => expect(dialog).toHaveAccessibleName('First photo'));
+    });
+    it('offers labelled navigation and close controls', async () => {
+        render(Lightbox, { props: { items: photos, open: true } });
+        await screen.findByRole('dialog');
+        expect(screen.getByRole('button', { name: 'Previous item' })).toBeInTheDocument();
+        expect(screen.getByRole('button', { name: 'Next item' })).toBeInTheDocument();
+        expect(screen.getByRole('button', { name: 'Close viewer' })).toBeInTheDocument();
+    });
+    it('hides the navigation controls for a single item', async () => {
+        render(Lightbox, { props: { items: [photos[0]], open: true } });
+        await screen.findByRole('dialog');
+        expect(screen.queryByRole('button', { name: 'Next item' })).not.toBeInTheDocument();
+    });
+    it('renders an empty state instead of a blank stage', async () => {
+        render(Lightbox, { props: { items: [], open: true } });
+        await screen.findByRole('dialog');
+        expect(screen.getByText('No media to show.')).toBeInTheDocument();
+    });
+    it('keeps a zoom applied instead of snapping it straight back', async () => {
+        // Regression: the effect that resets zoom on navigation used to read the
+        // zoom state while tracking, so it subscribed to the scale it had just
+        // written and undid every zoom immediately.
+        const user = userEvent.setup();
+        render(Lightbox, { props: { items: photos, open: true } });
+        const dialog = await screen.findByRole('dialog');
+        const image = dialog.querySelector('img');
+        expect(image.style.transform).toContain('scale(1)');
+        await user.click(screen.getByRole('button', { name: 'Zoom in' }));
+        await waitFor(() => expect(image.style.transform).toContain('scale(1.5)'));
+        // Zoom out is only enabled once zoomed, so its state proves the same thing.
+        expect(screen.getByRole('button', { name: 'Zoom out' })).toBeEnabled();
+    });
+    it('resets zoom when the item changes', async () => {
+        const user = userEvent.setup();
+        render(Lightbox, { props: { items: photos, open: true } });
+        const dialog = await screen.findByRole('dialog');
+        await user.click(screen.getByRole('button', { name: 'Zoom in' }));
+        await waitFor(() => expect(dialog.querySelector('img').style.transform).toContain('scale(1.5)'));
+        await user.click(screen.getByRole('button', { name: 'Next item' }));
+        await waitFor(() => {
+            const next = dialog.querySelector('img');
+            expect(next.style.transform).toContain('scale(1)');
+            expect(next.style.transform).not.toContain('scale(1.5)');
+        });
+    });
+});