@kubex/zinc 1.1.97 → 1.1.99

package/src/components/thumbnail/thumbnail.test.ts

@@ -0,0 +1,379 @@
+import '../../../dist/zn.min.js';
+import {expect, fixture, html, waitUntil} from '@open-wc/testing';
+import type ZnThumbnail from './thumbnail.component';
+
+const link = (el: ZnThumbnail) => el.shadowRoot!.querySelector<HTMLElement>('.thumbnail__link')!;
+
+// The test harness loads no theme stylesheet, so tests that assert position or shape stamp on the
+// handful of design tokens a themed page would otherwise provide.
+const tokens = '--zn-spacing-2x-small: 4px; --zn-spacing-x-small: 8px;'
+  + '--zn-border-radius: 6px; --zn-border-radius-small: 2px; --zn-border-radius-pill: 9999px;';
+
+describe('<zn-thumbnail>', () => {
+  it('should render a component', async () => {
+    const el = await fixture(html`
+      <zn-thumbnail></zn-thumbnail>`);
+
+    expect(el).to.exist;
+  });
+
+  it('should render the caption and the image', async () => {
+    const el = await fixture<ZnThumbnail>(html`
+      <zn-thumbnail src="/thumb.jpg" caption="Tahoe Day"></zn-thumbnail>`);
+
+    const img = el.shadowRoot!.querySelector<HTMLImageElement>('.thumbnail__image')!;
+    expect(img.getAttribute('src')).to.equal('/thumb.jpg');
+    expect(img.getAttribute('alt')).to.equal('Tahoe Day');
+    expect(el.shadowRoot!.querySelector('.thumbnail__caption')!.textContent).to.contain('Tahoe Day');
+  });
+
+  it('should render an anchor when href is set', async () => {
+    const el = await fixture<ZnThumbnail>(html`
+      <zn-thumbnail href="/media/1" caption="Linked"></zn-thumbnail>`);
+
+    expect(el.shadowRoot!.querySelector('a.thumbnail__link')).to.exist;
+  });
+
+  it('should not render an anchor when disabled', async () => {
+    const el = await fixture<ZnThumbnail>(html`
+      <zn-thumbnail href="/media/1" caption="Linked" disabled></zn-thumbnail>`);
+
+    expect(el.shadowRoot!.querySelector('a.thumbnail__link')).to.not.exist;
+  });
+
+  it('should emit zn-select when clicked', async () => {
+    const el = await fixture<ZnThumbnail>(html`
+      <zn-thumbnail caption="Tahoe Day" value="tahoe"></zn-thumbnail>`);
+
+    let detail: unknown = null;
+    el.addEventListener('zn-select', (e: Event) => {
+      detail = (e as CustomEvent).detail;
+    });
+
+    link(el).click();
+    await el.updateComplete;
+
+    expect(detail).to.deep.equal({item: el});
+  });
+
+  it('should not emit zn-select when disabled', async () => {
+    const el = await fixture<ZnThumbnail>(html`
+      <zn-thumbnail caption="Tahoe Day" disabled></zn-thumbnail>`);
+
+    let fired = false;
+    el.addEventListener('zn-select', () => (fired = true));
+
+    link(el).click();
+    await el.updateComplete;
+
+    expect(fired).to.be.false;
+  });
+
+  describe('actions', () => {
+    it('should render actions outside the link so their own clicks still work', async () => {
+      const el = await fixture<ZnThumbnail>(html`
+        <zn-thumbnail caption="Tahoe Day">
+          <button slot="actions">Download</button>
+        </zn-thumbnail>`);
+
+      // The actions overlay must not be a descendant of the link, or the link's own click
+      // handling would have to cancel the action's default behaviour to stay put.
+      const overlay = el.shadowRoot!.querySelector('.thumbnail__overlay')!;
+      expect(overlay).to.exist;
+      expect(link(el).contains(overlay)).to.be.false;
+    });
+
+    it('should let a slotted action handle its own click', async () => {
+      const el = await fixture<ZnThumbnail>(html`
+        <zn-thumbnail caption="Tahoe Day">
+          <button slot="actions">Download</button>
+        </zn-thumbnail>`);
+
+      let clicked = false;
+      let defaultPrevented = false;
+      const action = el.querySelector<HTMLButtonElement>('[slot="actions"]')!;
+      action.addEventListener('click', (event: MouseEvent) => {
+        clicked = true;
+        // The thumbnail used to cancel this, which broke every interactive action.
+        setTimeout(() => (defaultPrevented = event.defaultPrevented));
+      });
+
+      action.click();
+      await waitUntil(() => clicked);
+
+      expect(clicked).to.be.true;
+      expect(defaultPrevented).to.be.false;
+    });
+
+    it('should not emit zn-select when an action is clicked', async () => {
+      const el = await fixture<ZnThumbnail>(html`
+        <zn-thumbnail caption="Tahoe Day">
+          <button slot="actions">Download</button>
+        </zn-thumbnail>`);
+
+      let fired = false;
+      el.addEventListener('zn-select', () => (fired = true));
+
+      el.querySelector<HTMLElement>('[slot="actions"]')!.click();
+      await el.updateComplete;
+
+      expect(fired).to.be.false;
+    });
+
+    it('should hold badges back from the action chips beside them', async () => {
+      const el = await fixture<ZnThumbnail>(html`
+        <zn-thumbnail caption="Tahoe Day" icon="play_arrow" style="width: 200px; ${tokens}">
+          <button slot="actions">Download</button>
+        </zn-thumbnail>`);
+
+      const badge = el.shadowRoot!.querySelector<HTMLElement>('.thumbnail__badge-icon')!;
+      const action = el.querySelector<HTMLElement>('[slot="actions"]')!;
+
+      // A badge describes the asset, so it must not behave like a control.
+      expect(getComputedStyle(badge).pointerEvents).to.equal('none');
+      expect(getComputedStyle(badge).cursor).to.not.equal('pointer');
+      expect(getComputedStyle(action).cursor).to.equal('pointer');
+
+      // It keeps the chip's shape, and is held back on opacity instead.
+      expect(getComputedStyle(badge).borderTopLeftRadius)
+        .to.equal(getComputedStyle(action).borderTopLeftRadius);
+      expect(parseFloat(getComputedStyle(badge).opacity))
+        .to.be.lessThan(parseFloat(getComputedStyle(action).opacity));
+    });
+
+    it('should lay multiple actions out as separate chips', async () => {
+      // The gap is set here rather than left to --zn-spacing-2x-small, so the test measures
+      // the layout instead of whether the theme stylesheet is loaded.
+      const el = await fixture<ZnThumbnail>(html`
+        <zn-thumbnail caption="Tahoe Day" style="width: 200px; --zn-thumbnail-chip-gap: 6px;">
+          <button slot="actions" id="one">1</button>
+          <button slot="actions" id="two">2</button>
+        </zn-thumbnail>`);
+
+      const actions = el.shadowRoot!.querySelector<HTMLElement>('.thumbnail__actions')!;
+      const slot = actions.querySelector<HTMLSlotElement>('slot')!;
+      expect(slot.assignedElements()).to.have.lengthOf(2);
+
+      // The slot collapses so each action is its own gapped flex item of the positioner,
+      // rather than several icons sharing one container box.
+      expect(getComputedStyle(slot).display).to.equal('contents');
+
+      const [one, two] = el.querySelectorAll<HTMLElement>('[slot="actions"]');
+      const gap = two.getBoundingClientRect().left - one.getBoundingClientRect().right;
+      expect(gap).to.be.closeTo(6, 0.5);
+    });
+  });
+
+  describe('rings', () => {
+    it('should set the aspect ratio from the attribute', async () => {
+      const el = await fixture<ZnThumbnail>(html`
+        <zn-thumbnail caption="Square" aspect-ratio="1 / 1" style="width: 200px;"></zn-thumbnail>`);
+
+      const media = el.shadowRoot!.querySelector<HTMLElement>('.thumbnail__media')!;
+      const rect = media.getBoundingClientRect();
+      expect(rect.height).to.be.closeTo(rect.width, 1);
+    });
+
+    it('should inherit the aspect ratio from an ancestor custom property', async () => {
+      const el = await fixture<ZnThumbnail>(html`
+        <div style="width: 200px; --zn-thumbnail-aspect-ratio: 1 / 1;">
+          <zn-thumbnail caption="Square"></zn-thumbnail>
+        </div>`);
+
+      const thumbnail = el.querySelector<ZnThumbnail>('zn-thumbnail')!;
+      const rect = thumbnail.shadowRoot!.querySelector<HTMLElement>('.thumbnail__media')!.getBoundingClientRect();
+      expect(rect.height).to.be.closeTo(rect.width, 1);
+    });
+
+    it('should let the aspect-ratio attribute win over an inherited custom property', async () => {
+      const el = await fixture<ZnThumbnail>(html`
+        <div style="width: 200px; --zn-thumbnail-aspect-ratio: 1 / 1;">
+          <zn-thumbnail caption="Wide" aspect-ratio="2 / 1"></zn-thumbnail>
+        </div>`);
+
+      const thumbnail = el.querySelector<ZnThumbnail>('zn-thumbnail')!;
+      const rect = thumbnail.shadowRoot!.querySelector<HTMLElement>('.thumbnail__media')!.getBoundingClientRect();
+      expect(rect.width / rect.height).to.be.closeTo(2, 0.05);
+    });
+
+    it('should draw a wider ring when selected', async () => {
+      const el = await fixture<ZnThumbnail>(html`
+        <zn-thumbnail caption="Tahoe Day" style="width: 200px;"></zn-thumbnail>`);
+      const media = el.shadowRoot!.querySelector<HTMLElement>('.thumbnail__media')!;
+      const width = () => getComputedStyle(media).getPropertyValue('--thumbnail-ring-width').trim();
+
+      expect(width()).to.equal('1px');
+
+      el.selected = true;
+      await el.updateComplete;
+
+      expect(width()).to.equal('2px');
+    });
+
+    it('should draw a distinct ring colour when active', async () => {
+      const el = await fixture<ZnThumbnail>(html`
+        <zn-thumbnail caption="Tahoe Day" style="width: 200px; --zn-thumbnail-active-color: rgb(0, 128, 0);"></zn-thumbnail>`);
+      const media = el.shadowRoot!.querySelector<HTMLElement>('.thumbnail__media')!;
+      const color = () => getComputedStyle(media).getPropertyValue('--thumbnail-ring-color').trim();
+
+      const idle = color();
+
+      el.active = true;
+      await el.updateComplete;
+
+      expect(el.hasAttribute('active')).to.be.true;
+      expect(color()).to.equal('rgb(0, 128, 0)');
+      expect(color()).to.not.equal(idle);
+    });
+
+    it('should paint the ring above the media so an image cannot cover it', async () => {
+      const el = await fixture<ZnThumbnail>(html`
+        <zn-thumbnail
+          caption="Tahoe Day"
+          src="/thumb.jpg"
+          active
+          style="width: 200px; --zn-body: 255, 255, 255; --zn-thumbnail-active-color: rgb(0, 128, 0);">
+        </zn-thumbnail>`);
+
+      const media = el.shadowRoot!.querySelector<HTMLElement>('.thumbnail__media')!;
+      const ring = getComputedStyle(media, '::after');
+
+      // An inset shadow on the frame itself paints under the frame's content, so the image would
+      // hide it — the ring has to live on a positioned layer over the media.
+      expect(getComputedStyle(media).boxShadow).to.match(/none/);
+      expect(ring.boxShadow).to.contain('rgb(0, 128, 0)');
+      expect(ring.position).to.equal('absolute');
+    });
+
+    it('should give the active ring colour precedence over the selected ring colour', async () => {
+      const el = await fixture<ZnThumbnail>(html`
+        <zn-thumbnail
+          caption="Tahoe Day"
+          selected
+          active
+          style="width: 200px; --zn-thumbnail-selected-color: rgb(1, 2, 3); --zn-thumbnail-active-color: rgb(4, 5, 6);">
+        </zn-thumbnail>`);
+
+      const media = el.shadowRoot!.querySelector<HTMLElement>('.thumbnail__media')!;
+      expect(getComputedStyle(media).getPropertyValue('--thumbnail-ring-color').trim()).to.equal('rgb(4, 5, 6)');
+    });
+  });
+
+  describe('preview', () => {
+    it('should not render a preview without full-uri', async () => {
+      const el = await fixture<ZnThumbnail>(html`
+        <zn-thumbnail caption="Tahoe Day" src="/thumb.jpg"></zn-thumbnail>`);
+
+      expect(el.shadowRoot!.querySelector('dialog')).to.not.exist;
+    });
+
+    it('should open the preview when clicked', async () => {
+      const el = await fixture<ZnThumbnail>(html`
+        <zn-thumbnail caption="Tahoe Day" src="/thumb.jpg" full-uri="/full.jpg"></zn-thumbnail>`);
+
+      let shown = false;
+      el.addEventListener('zn-show', () => (shown = true));
+
+      link(el).click();
+      await waitUntil(() => el.shadowRoot!.querySelector<HTMLDialogElement>('dialog')?.open);
+
+      const dialog = el.shadowRoot!.querySelector<HTMLDialogElement>('dialog')!;
+      expect(shown).to.be.true;
+      expect(dialog.open).to.be.true;
+      expect(el.shadowRoot!.querySelector<HTMLImageElement>('.thumbnail__preview-image')!.getAttribute('src'))
+        .to.equal('/full.jpg');
+    });
+
+    it('should size the preview to the asset ratio rather than a fixed one', async () => {
+      // A deliberately tall asset: a fixed 16 / 9 panel would letterbox it and leave the close
+      // button floating on the panel instead of the image.
+      const tall = 'data:image/svg+xml,' + encodeURIComponent(
+        '<svg xmlns="http://www.w3.org/2000/svg" width="200" height="400"></svg>');
+
+      const el = await fixture<ZnThumbnail>(html`
+        <zn-thumbnail caption="Tall" src="${tall}" full-uri="${tall}" style="width: 200px;"></zn-thumbnail>`);
+
+      const image = el.shadowRoot!.querySelector<HTMLImageElement>('.thumbnail__image')!;
+      await waitUntil(() => image.complete && image.naturalWidth > 0);
+
+      await el.showPreview();
+
+      const frame = el.shadowRoot!.querySelector<HTMLElement>('.thumbnail__preview-frame')!.getBoundingClientRect();
+      expect(frame.width / frame.height).to.be.closeTo(0.5, 0.02);
+
+      // ...and it stays inside 70% of the viewport in both directions.
+      expect(frame.width).to.be.at.most(window.innerWidth * 0.7 + 1);
+      expect(frame.height).to.be.at.most(window.innerHeight * 0.7 + 1);
+    });
+
+    it('should keep the close button over the preview image', async () => {
+      const el = await fixture<ZnThumbnail>(html`
+        <zn-thumbnail caption="Tahoe Day" full-uri="/full.jpg" style="width: 200px; ${tokens}"></zn-thumbnail>`);
+
+      await el.showPreview();
+
+      const frame = el.shadowRoot!.querySelector<HTMLElement>('.thumbnail__preview-frame')!.getBoundingClientRect();
+      const close = el.shadowRoot!.querySelector<HTMLElement>('.thumbnail__preview-close')!.getBoundingClientRect();
+
+      // The frame is the image, so being inside the frame's top-right puts it on the image.
+      expect(close.top).to.be.at.least(frame.top - 1);
+      expect(close.right).to.be.at.most(frame.right + 1);
+      expect(close.bottom).to.be.at.most(frame.bottom + 1);
+      expect(frame.right - close.right).to.be.lessThan(frame.width / 2);
+      expect(close.top - frame.top).to.be.lessThan(frame.height / 2);
+    });
+
+    it('should close the preview from the backdrop', async () => {
+      const el = await fixture<ZnThumbnail>(html`
+        <zn-thumbnail caption="Tahoe Day" full-uri="/full.jpg"></zn-thumbnail>`);
+
+      await el.showPreview();
+      const dialog = el.shadowRoot!.querySelector<HTMLDialogElement>('dialog')!;
+      expect(dialog.open).to.be.true;
+
+      let closed = false;
+      el.addEventListener('zn-close', () => (closed = true));
+
+      el.shadowRoot!.querySelector<HTMLElement>('.thumbnail__preview-backdrop')!.click();
+      await waitUntil(() => !dialog.open);
+
+      expect(closed).to.be.true;
+    });
+
+    it('should not open the preview on click when preview-trigger is button', async () => {
+      const el = await fixture<ZnThumbnail>(html`
+        <zn-thumbnail caption="Tahoe Day" full-uri="/full.jpg" preview-trigger="button"></zn-thumbnail>`);
+
+      link(el).click();
+      await el.updateComplete;
+
+      expect(el.shadowRoot!.querySelector<HTMLDialogElement>('dialog')!.open).to.be.false;
+
+      el.shadowRoot!.querySelector<HTMLElement>('.thumbnail__preview-button')!.click();
+      await waitUntil(() => el.shadowRoot!.querySelector<HTMLDialogElement>('dialog')!.open);
+
+      expect(el.shadowRoot!.querySelector<HTMLDialogElement>('dialog')!.open).to.be.true;
+    });
+
+    it('should not open the preview when zn-select is canceled', async () => {
+      const el = await fixture<ZnThumbnail>(html`
+        <zn-thumbnail caption="Tahoe Day" full-uri="/full.jpg"></zn-thumbnail>`);
+
+      el.addEventListener('zn-select', (event: Event) => event.preventDefault());
+
+      link(el).click();
+      await el.updateComplete;
+
+      expect(el.shadowRoot!.querySelector<HTMLDialogElement>('dialog')!.open).to.be.false;
+    });
+
+    it('should not open the preview when disabled', async () => {
+      const el = await fixture<ZnThumbnail>(html`
+        <zn-thumbnail caption="Tahoe Day" full-uri="/full.jpg" disabled></zn-thumbnail>`);
+
+      await el.showPreview();
+
+      expect(el.shadowRoot!.querySelector('dialog')).to.not.exist;
+    });
+  });
+});

package/src/components/thumbnail-group/index.ts

@@ -0,0 +1,12 @@
+import ZnThumbnailGroup from './thumbnail-group.component';
+
+export * from './thumbnail-group.component';
+export default ZnThumbnailGroup;
+
+ZnThumbnailGroup.define('zn-thumbnail-group');
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'zn-thumbnail-group': ZnThumbnailGroup;
+  }
+}

package/src/components/thumbnail-group/thumbnail-group.component.ts

@@ -0,0 +1,268 @@
+import {classMap} from "lit/directives/class-map.js";
+import {type CSSResultGroup, html, type PropertyValues, unsafeCSS} from 'lit';
+import {property, query, state} from 'lit/decorators.js';
+import ZincElement from '../../internal/zinc-element';
+import type {ZnSelectEvent} from "../../events/zn-select";
+import type ZnThumbnail from "../thumbnail";
+
+import styles from './thumbnail-group.scss';
+
+/**
+ * @summary Lays a set of `zn-thumbnail` elements out as a single scrollable row, with a
+ * "Show All" toggle that expands them into a wrapping grid.
+ * @documentation https://zinc.style/components/thumbnail-group
+ * @status experimental
+ * @since 1.0
+ *
+ * @dependency zn-thumbnail
+ *
+ * @event zn-expand - Emitted when the group expands into the full grid.
+ * @event zn-collapse - Emitted when the group collapses back to a single row.
+ * @event zn-change - Emitted when the selected thumbnail changes (`selectable` groups only).
+ *
+ * @slot - One or more `zn-thumbnail` elements.
+ * @slot caption - Replaces the heading text.
+ * @slot actions - Extra content in the header, before the toggle.
+ *
+ * @csspart base - The component's base wrapper.
+ * @csspart header - The header row holding the caption and toggle.
+ * @csspart caption - The heading text.
+ * @csspart toggle - The show all / show less button.
+ * @csspart items - The scrolling row / expanded grid that holds the thumbnails.
+ *
+ * @cssproperty --zn-thumbnail-width - Track width of a thumbnail. Defaults to 180px. Also settable
+ *  with the `thumbnail-width` attribute.
+ * @cssproperty --zn-thumbnail-gap - Gap between thumbnails. Also settable with the `gap` attribute.
+ * @cssproperty --zn-thumbnail-aspect-ratio - Aspect ratio of every thumbnail in the group. Also
+ *  settable with the `aspect-ratio` attribute. Any `zn-thumbnail` custom property set here is
+ *  inherited by the slotted thumbnails.
+ */
+export default class ZnThumbnailGroup extends ZincElement {
+  static styles: CSSResultGroup = unsafeCSS(styles);
+
+  /** The heading shown at the top left of the group. */
+  @property() caption: string = '';
+
+  /** Expands the group into the full wrapping grid. */
+  @property({type: Boolean, reflect: true}) expanded: boolean = false;
+
+  /**
+   * Total number of thumbnails in the underlying set, shown in the "Show All (n)" label. Set this when
+   * the row only holds the first page of a larger set; otherwise the slotted thumbnails are counted.
+   */
+  @property({type: Number}) total: number = 0;
+
+  /** Label of the expand toggle. The count is appended in brackets. */
+  @property({attribute: 'show-all-label'}) showAllLabel: string = 'Show All';
+
+  /** Label of the collapse toggle. */
+  @property({attribute: 'show-less-label'}) showLessLabel: string = 'Show Less';
+
+  /** Never render the toggle, even when the row overflows. */
+  @property({type: Boolean, attribute: 'hide-toggle'}) hideToggle: boolean = false;
+
+  /** Always render the toggle, even when every thumbnail already fits on the row. */
+  @property({type: Boolean, attribute: 'always-toggle'}) alwaysToggle: boolean = false;
+
+  /** Manages single selection across the slotted thumbnails. */
+  @property({type: Boolean, reflect: true}) selectable: boolean = false;
+
+  /**
+   * Aspect ratio for every thumbnail in the group, as any CSS `aspect-ratio` value (e.g. `1 / 1`).
+   * Shorthand for setting `--zn-thumbnail-aspect-ratio` on the group. A thumbnail's own
+   * `aspect-ratio` attribute still wins.
+   */
+  @property({attribute: 'aspect-ratio', reflect: true}) aspectRatio: string = '';
+
+  /** Track width of each thumbnail (e.g. `140px`). Shorthand for `--zn-thumbnail-width`. */
+  @property({attribute: 'thumbnail-width', reflect: true}) thumbnailWidth: string = '';
+
+  /** Gap between thumbnails (e.g. `8px`). Shorthand for `--zn-thumbnail-gap`. */
+  @property({reflect: true}) gap: string = '';
+
+  /** The `value` of the selected thumbnail (`selectable` groups only). */
+  @property() value: string = '';
+
+  @state() private _overflowing: boolean = false;
+
+  @state() private _count: number = 0;
+
+  @query('.thumbnail-group__items') private _items: HTMLElement;
+
+  private _resizeObserver: ResizeObserver | null = null;
+
+  connectedCallback() {
+    super.connectedCallback();
+    // Re-observe on reconnect — `firstUpdated` only runs once, so it can't do this on its own.
+    this._observe();
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    this._resizeObserver?.disconnect();
+    this._resizeObserver = null;
+  }
+
+  protected firstUpdated(changed: PropertyValues) {
+    super.firstUpdated(changed);
+    this._observe();
+    this._sync();
+  }
+
+  private _observe() {
+    if (!this._items) return;
+    this._resizeObserver ??= new ResizeObserver(() => this._measure());
+    this._resizeObserver.observe(this._items);
+  }
+
+  protected updated(changed: PropertyValues) {
+    super.updated(changed);
+
+    // Toggling `expanded` swaps the items container between nowrap and wrap. That changes
+    // scrollWidth without changing the element's box, so the ResizeObserver never fires and
+    // the overflow state has to be re-read by hand.
+    if (changed.has('expanded')) {
+      this._measure();
+    }
+
+    if (changed.has('selectable') || changed.has('value')) {
+      this._sync();
+    }
+
+    this._syncCustomProperties(changed);
+  }
+
+  /**
+   * Mirrors the shorthand attributes onto host custom properties. They go on the host rather than
+   * anywhere in the shadow root because the thumbnails are light-DOM children — inheriting from the
+   * host is the only way the values reach them.
+   */
+  private _syncCustomProperties(changed: PropertyValues) {
+    const bindings: [string, string, string][] = [
+      ['aspectRatio', '--zn-thumbnail-aspect-ratio', this.aspectRatio],
+      ['thumbnailWidth', '--zn-thumbnail-width', this.thumbnailWidth],
+      ['gap', '--zn-thumbnail-gap', this.gap]
+    ];
+
+    for (const [name, customProperty, value] of bindings) {
+      if (!changed.has(name)) continue;
+
+      if (value) {
+        this.style.setProperty(customProperty, value);
+      } else if (changed.get(name)) {
+        // Only clear a property this component previously set, so an inline custom property in
+        // the consumer's markup survives the first render.
+        this.style.removeProperty(customProperty);
+      }
+    }
+  }
+
+  /** Expands the group into the full grid. */
+  show() {
+    if (this.expanded) return;
+    this.expanded = true;
+    this.emit('zn-expand');
+  }
+
+  /** Collapses the group back to a single row. */
+  hide() {
+    if (!this.expanded) return;
+    this.expanded = false;
+    this.emit('zn-collapse');
+  }
+
+  private get _thumbnails(): ZnThumbnail[] {
+    return Array.from(this.querySelectorAll<ZnThumbnail>(':scope > zn-thumbnail'));
+  }
+
+  private _handleSlotChange = () => {
+    this._sync();
+    this._measure();
+  };
+
+  // Publish the child count for the toggle label and mirror the group's selection
+  // settings onto the thumbnails.
+  private _sync() {
+    const thumbnails = this._thumbnails;
+    this._count = thumbnails.length;
+
+    if (!this.selectable) return;
+
+    // Adopt a thumbnail that was marked selected in markup so `value` starts in step.
+    if (!this.value) {
+      this.value = thumbnails.find(thumbnail => thumbnail.selected)?.value ?? '';
+    }
+
+    for (const thumbnail of thumbnails) {
+      thumbnail.selectable = true;
+      if (this.value) {
+        thumbnail.selected = thumbnail.value === this.value;
+      }
+    }
+  }
+
+  private _measure() {
+    // Only the collapsed row can overflow horizontally; the expanded grid always wraps, so
+    // measuring it would clear the state that decides whether the toggle is offered at all.
+    if (this.expanded || !this._items) return;
+    this._overflowing = this._items.scrollWidth - this._items.clientWidth > 1;
+  }
+
+  private _handleSelect = (event: ZnSelectEvent) => {
+    if (!this.selectable) return;
+
+    const thumbnail = event.detail.item as ZnThumbnail;
+    if (thumbnail.parentElement !== this) return;
+
+    for (const item of this._thumbnails) {
+      item.selected = item === thumbnail;
+    }
+
+    this.value = thumbnail.value;
+    this.emit('zn-change');
+  };
+
+  private _handleToggle = () => {
+    if (this.expanded) {
+      this.hide();
+    } else {
+      this.show();
+    }
+  };
+
+  render() {
+    const count = this.total || this._count;
+    const showToggle = !this.hideToggle && (this.expanded || this.alwaysToggle || this._overflowing || count > this._count);
+    const hasHeader = Boolean(this.caption) || showToggle;
+
+    return html`
+      <div
+        part="base"
+        class="${classMap({
+          'thumbnail-group': true,
+          'thumbnail-group--expanded': this.expanded,
+        })}">
+        ${hasHeader ? html`
+          <div part="header" class="thumbnail-group__header">
+            <div part="caption" class="thumbnail-group__caption">
+              <slot name="caption">${this.caption}</slot>
+            </div>
+            <div class="thumbnail-group__header-actions">
+              <slot name="actions"></slot>
+              ${showToggle ? html`
+                <button
+                  part="toggle"
+                  type="button"
+                  class="thumbnail-group__toggle"
+                  aria-expanded="${this.expanded ? 'true' : 'false'}"
+                  @click="${this._handleToggle}">
+                  ${this.expanded ? this.showLessLabel : `${this.showAllLabel}${count ? ` (${count})` : ''}`}
+                </button>` : ''}
+            </div>
+          </div>` : ''}
+        <div part="items" class="thumbnail-group__items">
+          <slot @slotchange="${this._handleSlotChange}" @zn-select="${this._handleSelect}"></slot>
+        </div>
+      </div>`;
+  }
+}