@nuvia-ui/components 4.0.1

package/src/ds-thumbnail/ds-thumbnail.js

@@ -0,0 +1,207 @@
+import { LitElement, html, css, nothing } from 'lit';
+import '../ds-icon/ds-icon.js';
+
+/**
+ * Thumbnail — a fluid image component with loading skeleton, fallback, and aspect ratio control.
+ *
+ * @element ds-thumbnail
+ * @summary Displays an image with skeleton loading state, error fallback, and aspect ratio support.
+ *
+ * @prop {string} src - Image source URL
+ * @prop {string} alt - Alt text for the image (required when src is set)
+ * @prop {string} aspect-ratio - Aspect ratio: '1:1' | '16:9' (default: '1:1')
+ * @prop {string} fit - Object-fit mode: 'cover' | 'contain' (default: 'cover')
+ * @prop {boolean} disabled - Whether the thumbnail is visually disabled
+ * @prop {string} icon - Fallback icon name (default: 'image')
+ *
+ * @fires ds-load - Dispatched when the image loads successfully
+ * @fires ds-error - Dispatched when the image fails to load
+ *
+ * @csspart container - The outer thumbnail container
+ * @csspart image - The img element
+ * @csspart fallback - The fallback icon container
+ */
+export class DsThumbnail extends LitElement {
+  static properties = {
+    src: { type: String },
+    alt: { type: String },
+    aspectRatio: { type: String, attribute: 'aspect-ratio', reflect: true },
+    fit: { type: String, reflect: true },
+    disabled: { type: Boolean, reflect: true },
+    icon: { type: String },
+    // Internal state
+    _state: { type: String, attribute: false } // 'empty' | 'loading' | 'loaded' | 'error'
+  };
+
+  static styles = css`
+    :host {
+      display: block;
+      width: 100%;
+      box-sizing: border-box;
+    }
+
+    /* ─── Container ─── */
+    .thumbnail {
+      position: relative;
+      width: 100%;
+      overflow: hidden;
+      border-radius: var(--ds-radius-media, 4px);
+      background: var(--ds-color-bg-skeleton);
+    }
+
+    /* ─── Aspect Ratios ─── */
+    :host([aspect-ratio="1:1"]) .thumbnail,
+    :host(:not([aspect-ratio])) .thumbnail {
+      aspect-ratio: 1 / 1;
+    }
+
+    :host([aspect-ratio="16:9"]) .thumbnail {
+      aspect-ratio: 16 / 9;
+    }
+
+    /* ─── Image ─── */
+    .thumbnail__image {
+      position: absolute;
+      inset: 0;
+      width: 100%;
+      height: 100%;
+      display: block;
+      opacity: 0;
+      transition: opacity 0.25s ease;
+    }
+
+    :host([fit="contain"]) .thumbnail__image {
+      object-fit: contain;
+    }
+
+    :host(:not([fit="contain"])) .thumbnail__image {
+      object-fit: cover;
+    }
+
+    /* Image visible when loaded */
+    .thumbnail__image--loaded {
+      opacity: 1;
+    }
+
+    /* ─── Fallback ─── */
+    .thumbnail__fallback {
+      position: absolute;
+      inset: 0;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      background: var(--ds-color-bg-secondary);
+      color: var(--ds-color-icon-secondary);
+    }
+
+    /* ─── Skeleton Shimmer ─── */
+    .thumbnail__skeleton {
+      position: absolute;
+      inset: 0;
+    }
+
+    .thumbnail__skeleton::after {
+      content: '';
+      position: absolute;
+      inset: 0;
+      background: linear-gradient(
+        90deg,
+        transparent 25%,
+        rgba(255, 255, 255, 0.6) 50%,
+        transparent 75%
+      );
+      animation: shimmer 1.8s ease-in-out infinite;
+    }
+
+    @keyframes shimmer {
+      0% { transform: translateX(-150%); }
+      100% { transform: translateX(150%); }
+    }
+
+    /* ─── Disabled ─── */
+    :host([disabled]) {
+      pointer-events: none;
+    }
+
+    :host([disabled]) .thumbnail {
+      opacity: 0.5;
+    }
+  `;
+
+  constructor() {
+    super();
+    this.src = '';
+    this.alt = '';
+    this.aspectRatio = '1:1';
+    this.fit = 'cover';
+    this.disabled = false;
+    this.icon = 'image';
+    this._state = 'empty';
+  }
+
+  willUpdate(changedProperties) {
+    if (changedProperties.has('src')) {
+      if (this.src) {
+        this._state = 'loading';
+      } else {
+        this._state = 'empty';
+      }
+    }
+  }
+
+  _handleLoad() {
+    this._state = 'loaded';
+    this.dispatchEvent(new CustomEvent('ds-load', {
+      bubbles: true,
+      composed: true
+    }));
+  }
+
+  _handleError() {
+    this._state = 'error';
+    this.dispatchEvent(new CustomEvent('ds-error', {
+      bubbles: true,
+      composed: true
+    }));
+  }
+
+  _renderFallback() {
+    return html`
+      <div class="thumbnail__fallback" part="fallback">
+        <ds-icon name="${this.icon}" size="md"></ds-icon>
+      </div>
+    `;
+  }
+
+  _renderSkeleton() {
+    return html`<div class="thumbnail__skeleton"></div>`;
+  }
+
+  render() {
+    const showImage = this.src && (this._state === 'loading' || this._state === 'loaded');
+    const showFallback = this._state === 'empty' || this._state === 'error';
+    const showSkeleton = this._state === 'loading';
+
+    return html`
+      <div class="thumbnail" part="container">
+        ${showFallback ? this._renderFallback() : nothing}
+        ${showSkeleton ? this._renderSkeleton() : nothing}
+        ${showImage ? html`
+          <img
+            class="thumbnail__image ${this._state === 'loaded' ? 'thumbnail__image--loaded' : ''}"
+            src="${this.src}"
+            alt="${this.alt}"
+            loading="lazy"
+            part="image"
+            @load=${this._handleLoad}
+            @error=${this._handleError}
+          />
+        ` : nothing}
+      </div>
+    `;
+  }
+}
+
+if (!customElements.get('ds-thumbnail')) {
+  customElements.define('ds-thumbnail', DsThumbnail);
+}

package/src/ds-thumbnail/ds-thumbnail.stories.js

@@ -0,0 +1,217 @@
+import { html } from 'lit';
+import './ds-thumbnail.js';
+
+export default {
+  title: 'Components/Thumbnail',
+  component: 'ds-thumbnail',
+  tags: ['autodocs'],
+  argTypes: {
+    src: {
+      control: 'text',
+      description: 'Image URL'
+    },
+    alt: {
+      control: 'text',
+      description: 'Alt text for the image'
+    },
+    'aspect-ratio': {
+      control: { type: 'select' },
+      options: ['1:1', '16:9'],
+      description: 'Aspect ratio of the thumbnail'
+    },
+    fit: {
+      control: { type: 'select' },
+      options: ['cover', 'contain'],
+      description: 'How the image fits within the container'
+    },
+    disabled: {
+      control: 'boolean',
+      description: 'Whether the thumbnail is visually disabled'
+    },
+    icon: {
+      control: 'text',
+      description: 'Fallback icon name when no image is provided'
+    }
+  }
+};
+
+// ─── Playground ───
+export const Playground = {
+  args: {
+    src: 'https://images.unsplash.com/photo-1506744038136-46273834b3fb?w=400&h=400&fit=crop',
+    alt: 'Beautiful landscape',
+    'aspect-ratio': '1:1',
+    fit: 'cover',
+    disabled: false,
+    icon: 'image'
+  },
+  render: (args) => html`
+    <div style="width: 200px;">
+      <ds-thumbnail
+        src="${args.src}"
+        alt="${args.alt}"
+        aspect-ratio="${args['aspect-ratio']}"
+        fit="${args.fit}"
+        ?disabled="${args.disabled}"
+        icon="${args.icon}"
+      ></ds-thumbnail>
+    </div>
+  `
+};
+
+// ─── Loading (Skeleton) ───
+export const Loading = {
+  render: () => html`
+    <div style="display: flex; gap: 24px; align-items: start;">
+      <div style="width: 120px;">
+        <p style="font: var(--ds-typo-content-caption-bold); color: var(--ds-color-text-secondary); margin: 0 0 8px;">1:1</p>
+        <ds-thumbnail id="skel-1" aspect-ratio="1:1"></ds-thumbnail>
+      </div>
+      <div style="width: 200px;">
+        <p style="font: var(--ds-typo-content-caption-bold); color: var(--ds-color-text-secondary); margin: 0 0 8px;">1:1 (larger)</p>
+        <ds-thumbnail id="skel-2" aspect-ratio="1:1"></ds-thumbnail>
+      </div>
+      <div style="width: 320px;">
+        <p style="font: var(--ds-typo-content-caption-bold); color: var(--ds-color-text-secondary); margin: 0 0 8px;">16:9</p>
+        <ds-thumbnail id="skel-3" aspect-ratio="16:9"></ds-thumbnail>
+      </div>
+    </div>
+  `,
+  play: async ({ canvasElement }) => {
+    // Force all thumbnails into permanent loading state
+    // (no src set, so willUpdate won't override _state)
+    const thumbnails = canvasElement.querySelectorAll('ds-thumbnail');
+    for (const el of thumbnails) {
+      await el.updateComplete;
+      el._state = 'loading';
+      await el.updateComplete;
+    }
+  }
+};
+
+// ─── Aspect Ratios ───
+export const AspectRatios = {
+  render: () => html`
+    <div style="display: flex; gap: 24px; align-items: start;">
+      <div style="width: 200px;">
+        <p style="font: var(--ds-typo-content-caption-bold); color: var(--ds-color-text-secondary); margin: 0 0 8px;">1:1 (Square)</p>
+        <ds-thumbnail
+          src="https://images.unsplash.com/photo-1506744038136-46273834b3fb?w=400&h=400&fit=crop"
+          alt="Landscape 1:1"
+          aspect-ratio="1:1"
+        ></ds-thumbnail>
+      </div>
+      <div style="width: 320px;">
+        <p style="font: var(--ds-typo-content-caption-bold); color: var(--ds-color-text-secondary); margin: 0 0 8px;">16:9 (Widescreen)</p>
+        <ds-thumbnail
+          src="https://images.unsplash.com/photo-1506744038136-46273834b3fb?w=600&h=338&fit=crop"
+          alt="Landscape 16:9"
+          aspect-ratio="16:9"
+        ></ds-thumbnail>
+      </div>
+    </div>
+  `
+};
+
+// ─── Object Fit ───
+export const ObjectFit = {
+  render: () => html`
+    <div style="display: flex; gap: 24px; align-items: start;">
+      <div style="width: 200px;">
+        <p style="font: var(--ds-typo-content-caption-bold); color: var(--ds-color-text-secondary); margin: 0 0 8px;">Cover (default)</p>
+        <ds-thumbnail
+          src="https://images.unsplash.com/photo-1506744038136-46273834b3fb?w=600&h=200&fit=crop"
+          alt="Cover example"
+          fit="cover"
+        ></ds-thumbnail>
+      </div>
+      <div style="width: 200px;">
+        <p style="font: var(--ds-typo-content-caption-bold); color: var(--ds-color-text-secondary); margin: 0 0 8px;">Contain (logos)</p>
+        <ds-thumbnail
+          src="https://images.unsplash.com/photo-1506744038136-46273834b3fb?w=600&h=200&fit=crop"
+          alt="Contain example"
+          fit="contain"
+        ></ds-thumbnail>
+      </div>
+    </div>
+  `
+};
+
+// ─── Fallback (No Image) ───
+export const Fallback = {
+  render: () => html`
+    <div style="display: flex; gap: 24px; align-items: start;">
+      <div style="width: 120px;">
+        <p style="font: var(--ds-typo-content-caption-bold); color: var(--ds-color-text-secondary); margin: 0 0 8px;">Default icon</p>
+        <ds-thumbnail></ds-thumbnail>
+      </div>
+      <div style="width: 120px;">
+        <p style="font: var(--ds-typo-content-caption-bold); color: var(--ds-color-text-secondary); margin: 0 0 8px;">Custom icon</p>
+        <ds-thumbnail icon="visibility"></ds-thumbnail>
+      </div>
+      <div style="width: 120px;">
+        <p style="font: var(--ds-typo-content-caption-bold); color: var(--ds-color-text-secondary); margin: 0 0 8px;">Broken src</p>
+        <ds-thumbnail src="https://broken-url.test/nope.jpg"></ds-thumbnail>
+      </div>
+    </div>
+  `
+};
+
+// ─── Sizes (Parent Controlled) ───
+export const ParentControlledSizes = {
+  render: () => html`
+    <div style="display: flex; gap: 24px; align-items: start;">
+      <div style="width: 40px;">
+        <p style="font: var(--ds-typo-content-viz-regular); color: var(--ds-color-text-secondary); margin: 0 0 4px;">40px</p>
+        <ds-thumbnail
+          src="https://images.unsplash.com/photo-1506744038136-46273834b3fb?w=100&h=100&fit=crop"
+          alt="Small"
+        ></ds-thumbnail>
+      </div>
+      <div style="width: 80px;">
+        <p style="font: var(--ds-typo-content-viz-regular); color: var(--ds-color-text-secondary); margin: 0 0 4px;">80px</p>
+        <ds-thumbnail
+          src="https://images.unsplash.com/photo-1506744038136-46273834b3fb?w=200&h=200&fit=crop"
+          alt="Medium"
+        ></ds-thumbnail>
+      </div>
+      <div style="width: 160px;">
+        <p style="font: var(--ds-typo-content-viz-regular); color: var(--ds-color-text-secondary); margin: 0 0 4px;">160px</p>
+        <ds-thumbnail
+          src="https://images.unsplash.com/photo-1506744038136-46273834b3fb?w=400&h=400&fit=crop"
+          alt="Large"
+        ></ds-thumbnail>
+      </div>
+      <div style="width: 300px;">
+        <p style="font: var(--ds-typo-content-viz-regular); color: var(--ds-color-text-secondary); margin: 0 0 4px;">300px</p>
+        <ds-thumbnail
+          src="https://images.unsplash.com/photo-1506744038136-46273834b3fb?w=600&h=600&fit=crop"
+          alt="XL"
+        ></ds-thumbnail>
+      </div>
+    </div>
+  `
+};
+
+// ─── Disabled ───
+export const Disabled = {
+  render: () => html`
+    <div style="display: flex; gap: 24px; align-items: start;">
+      <div style="width: 160px;">
+        <p style="font: var(--ds-typo-content-caption-bold); color: var(--ds-color-text-secondary); margin: 0 0 8px;">Enabled</p>
+        <ds-thumbnail
+          src="https://images.unsplash.com/photo-1506744038136-46273834b3fb?w=400&h=400&fit=crop"
+          alt="Enabled"
+        ></ds-thumbnail>
+      </div>
+      <div style="width: 160px;">
+        <p style="font: var(--ds-typo-content-caption-bold); color: var(--ds-color-text-secondary); margin: 0 0 8px;">Disabled</p>
+        <ds-thumbnail
+          src="https://images.unsplash.com/photo-1506744038136-46273834b3fb?w=400&h=400&fit=crop"
+          alt="Disabled"
+          disabled
+        ></ds-thumbnail>
+      </div>
+    </div>
+  `
+};

package/src/ds-thumbnail/ds-thumbnail.test.js

@@ -0,0 +1,220 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import './ds-thumbnail.js';
+
+describe('ds-thumbnail', () => {
+    let container;
+
+    beforeEach(() => {
+        container = document.createElement('div');
+        document.body.appendChild(container);
+    });
+
+    afterEach(() => {
+        container.remove();
+    });
+
+    async function createThumbnail(attrs = {}) {
+        const attrStr = Object.entries(attrs)
+            .map(([k, v]) => {
+                if (typeof v === 'boolean') return v ? k : '';
+                return `${k}="${v}"`;
+            })
+            .filter(Boolean)
+            .join(' ');
+        container.innerHTML = `<ds-thumbnail ${attrStr}></ds-thumbnail>`;
+        const el = container.querySelector('ds-thumbnail');
+        await el.updateComplete;
+        return el;
+    }
+
+    // ─── Rendering ───
+
+    it('renders with default props', async () => {
+        const el = await createThumbnail();
+        expect(el).toBeTruthy();
+        expect(el.src).toBe('');
+        expect(el.alt).toBe('');
+        expect(el.aspectRatio).toBe('1:1');
+        expect(el.fit).toBe('cover');
+        expect(el.disabled).toBe(false);
+        expect(el.icon).toBe('image');
+    });
+
+    it('renders fallback icon when no src is provided', async () => {
+        const el = await createThumbnail();
+        const fallback = el.shadowRoot.querySelector('.thumbnail__fallback');
+        expect(fallback).toBeTruthy();
+        const icon = fallback.querySelector('ds-icon');
+        expect(icon).toBeTruthy();
+        expect(icon.getAttribute('name')).toBe('image');
+    });
+
+    it('renders custom fallback icon', async () => {
+        const el = await createThumbnail({ icon: 'photo_camera' });
+        const icon = el.shadowRoot.querySelector('.thumbnail__fallback ds-icon');
+        expect(icon.getAttribute('name')).toBe('photo_camera');
+    });
+
+    it('does not render img element when no src', async () => {
+        const el = await createThumbnail();
+        const img = el.shadowRoot.querySelector('img');
+        expect(img).toBeFalsy();
+    });
+
+    // ─── Image Loading ───
+
+    it('shows skeleton shimmer when src is set', async () => {
+        const el = await createThumbnail({ src: 'https://example.com/img.jpg' });
+        const skeleton = el.shadowRoot.querySelector('.thumbnail__skeleton');
+        expect(skeleton).toBeTruthy();
+    });
+
+    it('renders img element when src is set', async () => {
+        const el = await createThumbnail({ src: 'https://example.com/img.jpg' });
+        const img = el.shadowRoot.querySelector('img');
+        expect(img).toBeTruthy();
+        expect(img.getAttribute('src')).toBe('https://example.com/img.jpg');
+    });
+
+    it('sets loading="lazy" on img', async () => {
+        const el = await createThumbnail({ src: 'https://example.com/img.jpg' });
+        const img = el.shadowRoot.querySelector('img');
+        expect(img.getAttribute('loading')).toBe('lazy');
+    });
+
+    it('sets alt attribute on img', async () => {
+        const el = await createThumbnail({ src: 'https://example.com/img.jpg', alt: 'Test alt' });
+        const img = el.shadowRoot.querySelector('img');
+        expect(img.getAttribute('alt')).toBe('Test alt');
+    });
+
+    it('transitions to loaded state on image load', async () => {
+        const el = await createThumbnail({ src: 'https://example.com/img.jpg' });
+        const img = el.shadowRoot.querySelector('img');
+        img.dispatchEvent(new Event('load'));
+        await el.updateComplete;
+
+        expect(el._state).toBe('loaded');
+        expect(img.classList.contains('thumbnail__image--loaded')).toBe(true);
+    });
+
+    it('hides skeleton after image loads', async () => {
+        const el = await createThumbnail({ src: 'https://example.com/img.jpg' });
+        const img = el.shadowRoot.querySelector('img');
+        img.dispatchEvent(new Event('load'));
+        await el.updateComplete;
+
+        const skeleton = el.shadowRoot.querySelector('.thumbnail__skeleton');
+        expect(skeleton).toBeFalsy();
+    });
+
+    it('shows fallback on image error', async () => {
+        const el = await createThumbnail({ src: 'https://example.com/broken.jpg' });
+        const img = el.shadowRoot.querySelector('img');
+        img.dispatchEvent(new Event('error'));
+        await el.updateComplete;
+
+        expect(el._state).toBe('error');
+        const fallback = el.shadowRoot.querySelector('.thumbnail__fallback');
+        expect(fallback).toBeTruthy();
+    });
+
+    // ─── Events ───
+
+    it('dispatches ds-load event on successful load', async () => {
+        const el = await createThumbnail({ src: 'https://example.com/img.jpg' });
+        let fired = false;
+        el.addEventListener('ds-load', () => { fired = true; });
+
+        const img = el.shadowRoot.querySelector('img');
+        img.dispatchEvent(new Event('load'));
+
+        expect(fired).toBe(true);
+    });
+
+    it('dispatches ds-error event on image error', async () => {
+        const el = await createThumbnail({ src: 'https://example.com/broken.jpg' });
+        let fired = false;
+        el.addEventListener('ds-error', () => { fired = true; });
+
+        const img = el.shadowRoot.querySelector('img');
+        img.dispatchEvent(new Event('error'));
+
+        expect(fired).toBe(true);
+    });
+
+    // ─── Aspect Ratios ───
+
+    it('defaults to 1:1 aspect ratio', async () => {
+        const el = await createThumbnail();
+        expect(el.aspectRatio).toBe('1:1');
+    });
+
+    it('supports 16:9 aspect ratio', async () => {
+        const el = await createThumbnail({ 'aspect-ratio': '16:9' });
+        expect(el.getAttribute('aspect-ratio')).toBe('16:9');
+    });
+
+    // ─── Object Fit ───
+
+    it('defaults to cover fit', async () => {
+        const el = await createThumbnail();
+        expect(el.fit).toBe('cover');
+    });
+
+    it('supports contain fit', async () => {
+        const el = await createThumbnail({ fit: 'contain' });
+        expect(el.getAttribute('fit')).toBe('contain');
+    });
+
+    // ─── Disabled ───
+
+    it('applies disabled attribute', async () => {
+        const el = await createThumbnail({ disabled: true });
+        expect(el.hasAttribute('disabled')).toBe(true);
+    });
+
+    // ─── State Transitions ───
+
+    it('resets to loading when src changes', async () => {
+        const el = await createThumbnail({ src: 'https://example.com/1.jpg' });
+
+        // Simulate load
+        const img = el.shadowRoot.querySelector('img');
+        img.dispatchEvent(new Event('load'));
+        await el.updateComplete;
+        expect(el._state).toBe('loaded');
+
+        // Change src
+        el.src = 'https://example.com/2.jpg';
+        await el.updateComplete;
+        expect(el._state).toBe('loading');
+    });
+
+    it('returns to empty when src is cleared', async () => {
+        const el = await createThumbnail({ src: 'https://example.com/1.jpg' });
+        el.src = '';
+        await el.updateComplete;
+        expect(el._state).toBe('empty');
+    });
+
+    // ─── CSS Parts ───
+
+    it('exposes container part', async () => {
+        const el = await createThumbnail();
+        const part = el.shadowRoot.querySelector('[part="container"]');
+        expect(part).toBeTruthy();
+    });
+
+    it('exposes image part', async () => {
+        const el = await createThumbnail({ src: 'https://example.com/img.jpg' });
+        const part = el.shadowRoot.querySelector('[part="image"]');
+        expect(part).toBeTruthy();
+    });
+
+    it('exposes fallback part', async () => {
+        const el = await createThumbnail();
+        const part = el.shadowRoot.querySelector('[part="fallback"]');
+        expect(part).toBeTruthy();
+    });
+});