@kubex/zinc 1.1.97 → 1.1.99

package/docs/pages/components/radio.md

@@ -111,6 +111,194 @@ Add the `contained` attribute to draw a card-like container around a radio. This
 <zn-radio name="payment" value="bank" description="Direct bank transfer (3-5 business days)" contained>Bank Transfer</zn-radio>
 ```
 
+Containers are rounded by default. Add `square` to square off the corners; setting it on a
+[radio group](/components/radio-group) squares every radio in the group.
+
+```html:preview
+<zn-radio-group name="delivery" value="standard" contained square>
+  <zn-radio value="standard" description="Arrives in 3-5 working days">Standard delivery</zn-radio>
+  <zn-radio value="express" description="Arrives the next working day">Express delivery</zn-radio>
+</zn-radio-group>
+```
+
+### Selection Cards
+
+A contained radio can combine an image, title, supporting text, and a freely positioned radio indicator. Set the title
+with `card-title` (or use the default slot), and set supporting text with `description` (or the `description` slot).
+Provide an image with `src` and `image-alt`, or place richer content such as `zn-icon` in the `image` slot.
+
+Use these cards inside [`zn-radio-group`](/components/radio-group) for a single-select form input. Adding both
+`contained` and `horizontal` to the group produces a responsive grid of equal-height cards that stacks when the
+available width becomes narrow.
+
+```html:preview
+<zn-radio-group label="Choose a pricing plan" name="plan" value="complete" contained horizontal>
+  <zn-radio
+    value="basic"
+    card-title="Basic"
+    description="For smaller businesses, with simple salaries and pay schedules."
+    control-position="top-right">
+    <zn-icon slot="image" src="support" size="64"></zn-icon>
+  </zn-radio>
+  <zn-radio
+    value="complete"
+    card-title="Complete"
+    description="For growing businesses that want to create a rewarding place to work."
+    control-position="top-right">
+    <zn-icon slot="image" src="potted_plant" size="64"></zn-icon>
+  </zn-radio>
+</zn-radio-group>
+```
+
+#### Image and Indicator Positions
+
+Set `image-position` to `top`, `right`, `bottom`, or `left` (the default), and `control-position` to any corner,
+edge centre, or `center`. Content is never placed underneath a positioned indicator — the card reserves a gutter for
+it — so wider columns leave more room for text. Use `--zn-radio-group-column-width` on the group to control how many
+cards sit in a row, or add `wrap` to the group to let cards grow to fill each line instead of sharing equal-width
+columns.
+
+```html:preview
+<zn-radio-group
+  label="Card position examples"
+  name="position-example"
+  contained
+  horizontal
+  style="--zn-radio-group-column-width: 24rem;">
+  <zn-radio
+    value="top"
+    card-title="Image above"
+    description="Top image, top-left control."
+    image-position="top"
+    control-position="top-left"
+    checked>
+    <zn-icon slot="image" src="image" size="48"></zn-icon>
+  </zn-radio>
+  <zn-radio
+    value="right"
+    card-title="Image right"
+    description="Right image, top-right control."
+    image-position="right"
+    control-position="top-right">
+    <zn-icon slot="image" src="image" size="48"></zn-icon>
+  </zn-radio>
+  <zn-radio
+    value="bottom"
+    card-title="Image below"
+    description="Bottom image, bottom-left control."
+    image-position="bottom"
+    control-position="bottom-left">
+    <zn-icon slot="image" src="image" size="48"></zn-icon>
+  </zn-radio>
+  <zn-radio
+    value="left"
+    card-title="Image left"
+    description="Left image, bottom-right control."
+    image-position="left"
+    control-position="bottom-right">
+    <zn-icon slot="image" src="image" size="48"></zn-icon>
+  </zn-radio>
+</zn-radio-group>
+```
+
+#### Indicators on an Edge
+
+The indicator can also be centred along any edge of the card.
+
+```html:preview
+<zn-radio-group
+  label="Additional indicator positions"
+  name="control-example"
+  contained
+  horizontal
+  style="--zn-radio-group-column-width: 18rem;">
+  <zn-radio
+    value="top-center"
+    card-title="Top center"
+    description="Centered along the top edge."
+    control-position="top-center">
+    <zn-icon slot="image" src="filter_center_focus" size="48"></zn-icon>
+  </zn-radio>
+  <zn-radio
+    value="center-right"
+    card-title="Center right"
+    description="Centered along the right edge."
+    control-position="center-right">
+    <zn-icon slot="image" src="filter_center_focus" size="48"></zn-icon>
+  </zn-radio>
+  <zn-radio
+    value="bottom-center"
+    card-title="Bottom center"
+    description="Centered along the bottom edge."
+    control-position="bottom-center">
+    <zn-icon slot="image" src="filter_center_focus" size="48"></zn-icon>
+  </zn-radio>
+</zn-radio-group>
+```
+
+#### Hiding the Radio Input
+
+Set `control-position="none"` to hide the radio itself so the card *is* the control — selection is shown by the card's
+highlighted border and background alone. Nothing is removed from the DOM: the native radio still receives focus, still
+responds to arrow keys within a [radio group](/components/radio-group), still submits its value, and the whole card
+stays clickable. Focusing a card in this state draws a focus ring around the card.
+
+```html:preview
+<zn-radio-group label="Choose a theme" name="theme" value="light" contained horizontal>
+  <zn-radio
+    value="light"
+    card-title="Light"
+    description="Bright background with dark text."
+    image-position="top"
+    control-position="none">
+    <zn-icon slot="image" src="light_mode" size="48"></zn-icon>
+  </zn-radio>
+  <zn-radio
+    value="dark"
+    card-title="Dark"
+    description="Dark background with light text."
+    image-position="top"
+    control-position="none">
+    <zn-icon slot="image" src="dark_mode" size="48"></zn-icon>
+  </zn-radio>
+  <zn-radio
+    value="system"
+    card-title="System"
+    description="Follows your device setting."
+    image-position="top"
+    control-position="none">
+    <zn-icon slot="image" src="contrast" size="48"></zn-icon>
+  </zn-radio>
+</zn-radio-group>
+```
+
+It works just as well without an image, which gives a compact set of button-like options.
+
+```html:preview
+<zn-radio-group label="Billing period" name="billing" value="annual" contained horizontal wrap>
+  <zn-radio value="monthly" card-title="Monthly" description="£29 per month" control-position="none"></zn-radio>
+  <zn-radio value="annual" card-title="Annual" description="£290 per year, two months free" control-position="none"></zn-radio>
+</zn-radio-group>
+```
+
+:::warning
+Because a hidden indicator removes the usual radio affordance, keep the selected state obvious — a short title with
+supporting text, as above, reads better than an image on its own.
+:::
+
+:::tip
+Card attributes only apply to `contained` radios. `control-position` accepts `top-left`, `top-center`, `top-right`,
+`center-left`, `center`, `center-right`, `bottom-left`, `bottom-center`, `bottom-right`, `none`, and the default
+`start`, which keeps the standard inline radio.
+:::
+
+Card dimensions can be adjusted with `--zn-selection-card-image-width`, `--zn-selection-card-image-height`,
+`--zn-selection-card-min-height`, and `--zn-selection-card-title-font-size`. Use `--zn-selection-card-padding` for the
+inset around the card, `--zn-selection-card-gap` for the space between its regions,
+`--zn-selection-card-control-offset` to change the indicator's distance from an edge,
+`--zn-selection-card-content-min-width` for the width the text keeps before it wraps below a side image, and
+`--zn-selection-card-border-radius` for the corner radius.
+
 ### Horizontal Layout
 
 Use the `horizontal` attribute to apply styles relevant to radios in a horizontal layout.

package/docs/pages/components/remarkd-editor.md

@@ -135,6 +135,28 @@ NOTE: The value is the same remarkd source either way."
 ></zn-remarkd-editor>
 ```
 
+### Height
+
+The editor never grows taller than the viewport: past that, its body scrolls and
+the toolbar stays in reach. Override the cap with `--remarkd-editor-max-height` —
+useful when the editor sits below a header and should only fill the space left on
+screen.
+
+All scrolling stays inside the editor's own body: adding a block or opening the
+image / include picker brings the new content into view, and dragging a block to a
+scroll edge keeps the content moving. Neither touches the page or panel around the
+editor.
+
+```html:preview
+<zn-remarkd-editor
+  style="--remarkd-editor-max-height: 20rem"
+  value="A short editor.
+
+Add blocks from the toolbar and the body starts scrolling once the content
+outgrows the 20rem cap set here."
+></zn-remarkd-editor>
+```
+
 ### Form Integration
 
 `zn-remarkd-editor` is a [form control](/getting-started/form-controls); its

package/docs/pages/components/scroll-container.md

@@ -5,10 +5,10 @@ meta:
 layout: component
 ---
 
-The scroll container provides a flexible scrolling area with optional header and footer slots that remain fixed while the main content scrolls. It supports automatic scrolling to the bottom, making it ideal for chat applications, activity feeds, and log viewers.
+The scroll container provides a flexible scrolling area with optional header and footer slots that remain fixed while the main content scrolls. It supports automatic scrolling to the bottom, making it ideal for chat applications, activity feeds, and log viewers. Set `height` to constrain the block-level container and enable scrolling when its content exceeds that height.
 
 ```html:preview
-<zn-scroll-container style="height: 300px; display: block; border: 1px solid var(--zn-color-neutral-200);">
+<zn-scroll-container height="300px" style="border: 1px solid var(--zn-color-neutral-200);">
   <div slot="header" style="padding: 1rem; background: var(--zn-color-neutral-100); border-bottom: 1px solid var(--zn-color-neutral-200);">
     <strong>Header Area</strong>
   </div>
@@ -39,7 +39,7 @@ The scroll container provides a flexible scrolling area with optional header and
 The most common use case is a simple vertical scrolling container. The main content area scrolls while header and footer remain fixed.
 
 ```html:preview
-<zn-scroll-container style="height: 400px; display: block; border: 1px solid var(--zn-color-neutral-200); border-radius: 4px; overflow: hidden;">
+<zn-scroll-container height="400px" style="border: 1px solid var(--zn-color-neutral-200); border-radius: 4px; overflow: hidden;">
   <div style="padding: 1rem;">
     <h3 style="margin-top: 0;">Scrollable Content Area</h3>
     <p>This container has a fixed height and the content will scroll vertically when it exceeds the available space.</p>
@@ -60,7 +60,7 @@ The most common use case is a simple vertical scrolling container. The main cont
 Use the `header` slot to add a fixed header that remains visible while content scrolls.
 
 ```html:preview
-<zn-scroll-container style="height: 350px; display: block; border: 1px solid var(--zn-color-neutral-200); border-radius: 4px; overflow: hidden;">
+<zn-scroll-container height="350px" style="border: 1px solid var(--zn-color-neutral-200); border-radius: 4px; overflow: hidden;">
   <div slot="header" style="padding: 1rem; background: var(--zn-color-primary-50); border-bottom: 2px solid var(--zn-color-primary-200);">
     <h3 style="margin: 0;">Document Title</h3>
     <p style="margin: 0.5rem 0 0 0; font-size: 0.875rem; color: var(--zn-color-neutral-600);">Last updated: January 23, 2026</p>
@@ -91,7 +91,7 @@ Use the `header` slot to add a fixed header that remains visible while content s
 Use the `footer` slot to add a fixed footer that remains at the bottom. The footer is positioned absolutely and the scrollable area has padding to account for its height.
 
 ```html:preview
-<zn-scroll-container style="height: 350px; display: block; border: 1px solid var(--zn-color-neutral-200); border-radius: 4px; overflow: hidden;">
+<zn-scroll-container height="350px" style="border: 1px solid var(--zn-color-neutral-200); border-radius: 4px; overflow: hidden;">
   <div style="padding: 1rem;">
     <h4>Content Area</h4>
     <p>The footer remains fixed at the bottom while this content scrolls.</p>
@@ -116,7 +116,7 @@ Use the `footer` slot to add a fixed footer that remains at the bottom. The foot
 Combine both header and footer slots for maximum control. The scrollable area sits between them.
 
 ```html:preview
-<zn-scroll-container style="height: 400px; display: block; border: 1px solid var(--zn-color-neutral-200); border-radius: 4px; overflow: hidden;">
+<zn-scroll-container height="400px" style="border: 1px solid var(--zn-color-neutral-200); border-radius: 4px; overflow: hidden;">
   <div slot="header" style="padding: 1rem; background: var(--zn-color-neutral-100); border-bottom: 1px solid var(--zn-color-neutral-200);">
     <h3 style="margin: 0;">Messages</h3>
   </div>
@@ -156,7 +156,7 @@ Combine both header and footer slots for maximum control. The scrollable area si
 Use the `start-scrolled` attribute to automatically scroll to the bottom when the component loads or when new content is added. This is perfect for chat interfaces, activity logs, and notification feeds.
 
 ```html:preview
-<zn-scroll-container start-scrolled style="height: 300px; display: block; border: 1px solid var(--zn-color-neutral-200); border-radius: 4px; overflow: hidden;">
+<zn-scroll-container height="300px" start-scrolled style="border: 1px solid var(--zn-color-neutral-200); border-radius: 4px; overflow: hidden;">
   <div slot="header" style="padding: 1rem; background: var(--zn-color-neutral-100); border-bottom: 1px solid var(--zn-color-neutral-200);">
     <h4 style="margin: 0;">Activity Log</h4>
   </div>
@@ -198,7 +198,7 @@ Use the `start-scrolled` attribute to automatically scroll to the bottom when th
 A practical example showing how to build a chat interface with auto-scrolling and dynamic content.
 
 ```html:preview
-<zn-scroll-container id="chat-example" start-scrolled style="height: 450px; display: block; border: 1px solid var(--zn-color-neutral-200); border-radius: 8px; overflow: hidden; box-shadow: 0 2px 8px rgba(0,0,0,0.1);">
+<zn-scroll-container id="chat-example" height="450px" start-scrolled style="border: 1px solid var(--zn-color-neutral-200); border-radius: 8px; overflow: hidden; box-shadow: 0 2px 8px rgba(0,0,0,0.1);">
   <div slot="header" style="padding: 1rem; background: var(--zn-color-primary); color: white; display: flex; align-items: center; gap: 0.75rem;">
     <div style="width: 40px; height: 40px; border-radius: 50%; background: var(--zn-color-primary-700); display: flex; align-items: center; justify-content: center; font-weight: bold;">
       TC
@@ -274,7 +274,7 @@ A practical example showing how to build a chat interface with auto-scrolling an
 Perfect for displaying server logs, build output, or any streaming text content.
 
 ```html:preview
-<zn-scroll-container start-scrolled style="height: 350px; display: block; border: 1px solid var(--zn-color-neutral-800); border-radius: 4px; overflow: hidden; background: var(--zn-color-neutral-900);">
+<zn-scroll-container height="350px" start-scrolled style="border: 1px solid var(--zn-color-neutral-800); border-radius: 4px; overflow: hidden; background: var(--zn-color-neutral-900);">
   <div slot="header" style="padding: 0.75rem 1rem; background: var(--zn-color-neutral-800); color: var(--zn-color-neutral-200); font-family: monospace; font-size: 0.875rem; border-bottom: 1px solid var(--zn-color-neutral-700);">
     <strong>build.log</strong> - Application Build Output
   </div>
@@ -307,7 +307,7 @@ Perfect for displaying server logs, build output, or any streaming text content.
 A practical example showing an activity feed that automatically scrolls to show the latest activity.
 
 ```html:preview
-<zn-scroll-container id="activity-feed" start-scrolled style="height: 400px; display: block; border: 1px solid var(--zn-color-neutral-200); border-radius: 4px; overflow: hidden;">
+<zn-scroll-container id="activity-feed" height="400px" start-scrolled style="border: 1px solid var(--zn-color-neutral-200); border-radius: 4px; overflow: hidden;">
   <div slot="header" style="padding: 1rem; background: var(--zn-color-neutral-50); border-bottom: 1px solid var(--zn-color-neutral-200); display: flex; justify-content: space-between; align-items: center;">
     <h4 style="margin: 0;">Recent Activity</h4>
     <zn-chip size="small" type="info">Live</zn-chip>
@@ -358,7 +358,7 @@ A practical example showing an activity feed that automatically scrolls to show
 A comprehensive example showing how to build a notification center with categorized notifications.
 
 ```html:preview
-<zn-scroll-container start-scrolled style="height: 450px; display: block; border: 1px solid var(--zn-color-neutral-200); border-radius: 8px; overflow: hidden; box-shadow: 0 4px 12px rgba(0,0,0,0.1);">
+<zn-scroll-container height="450px" start-scrolled style="border: 1px solid var(--zn-color-neutral-200); border-radius: 8px; overflow: hidden; box-shadow: 0 4px 12px rgba(0,0,0,0.1);">
   <div slot="header" style="padding: 1.25rem; background: var(--zn-color-white); border-bottom: 1px solid var(--zn-color-neutral-200);">
     <div style="display: flex; justify-content: space-between; align-items: center;">
       <div>
@@ -460,7 +460,7 @@ A comprehensive example showing how to build a notification center with categori
 You can programmatically scroll to the bottom using the `scrollEnd()` method.
 
 ```html:preview
-<zn-scroll-container id="programmatic-scroll" style="height: 300px; display: block; border: 1px solid var(--zn-color-neutral-200); border-radius: 4px; overflow: hidden;">
+<zn-scroll-container id="programmatic-scroll" height="300px" style="border: 1px solid var(--zn-color-neutral-200); border-radius: 4px; overflow: hidden;">
   <div id="scroll-content" style="padding: 1rem;">
     <p>Content line 1</p>
     <p>Content line 2</p>
@@ -507,7 +507,7 @@ You can programmatically scroll to the bottom using the `scrollEnd()` method.
 The footer's height is automatically tracked and the scrollable area adjusts accordingly. This happens dynamically when the footer content changes size.
 
 ```html:preview
-<zn-scroll-container start-scrolled style="height: 400px; display: block; border: 1px solid var(--zn-color-neutral-200); border-radius: 4px; overflow: hidden;">
+<zn-scroll-container height="400px" start-scrolled style="border: 1px solid var(--zn-color-neutral-200); border-radius: 4px; overflow: hidden;">
   <div style="padding: 1rem;">
     <p>The scrollable area automatically adjusts its padding based on the footer's height.</p>
     <p>This ensures that content is never hidden behind the fixed footer.</p>
@@ -552,7 +552,7 @@ The footer's height is automatically tracked and the scrollable area adjusts acc
 A minimal example showing just the essential markup.
 
 ```html:preview
-<zn-scroll-container style="height: 250px; display: block; border: 1px solid var(--zn-color-neutral-200);">
+<zn-scroll-container height="250px" style="border: 1px solid var(--zn-color-neutral-200);">
   <div style="padding: 1rem;">
     <p>Simple scrollable content without header or footer.</p>
     <p>Just add content to the default slot.</p>
@@ -565,4 +565,3 @@ A minimal example showing just the essential markup.
 </zn-scroll-container>
 ```
 
-

package/docs/pages/components/thumbnail-group.md

@@ -0,0 +1,216 @@
+---
+meta:
+  title: Thumbnail Group
+  description: Lays a set of thumbnails out as a single scrollable row, with a Show All toggle that expands them into a wrapping grid.
+layout: component
+---
+
+A thumbnail group holds [thumbnails](/components/thumbnail) in one horizontally scrollable row. When they don't all fit,
+a **Show All** toggle appears in the header; expanding drops the single-row restriction and reflows everything into a
+wrapping grid. **Show Less** rolls it back to the row.
+
+```html:preview
+<zn-thumbnail-group caption="Landscape">
+  <zn-thumbnail src="https://images.unsplash.com/photo-1439066615861-d1af74d74000?w=600&q=60" caption="Tahoe Day" icon="play_arrow"></zn-thumbnail>
+  <zn-thumbnail src="https://images.unsplash.com/photo-1441974231531-c6227db76b6e?w=600&q=60" caption="Sequoia Sunrise" icon="play_arrow"></zn-thumbnail>
+  <zn-thumbnail src="https://images.unsplash.com/photo-1470071459604-3b5ec3a7fe05?w=600&q=60" caption="Sonoma Horizon" icon="play_arrow"></zn-thumbnail>
+  <zn-thumbnail src="https://images.unsplash.com/photo-1507525428034-b723cf961d3e?w=600&q=60" caption="Goa Beaches" icon="play_arrow"></zn-thumbnail>
+  <zn-thumbnail src="https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=600&q=60" caption="Big Sur" icon="play_arrow"></zn-thumbnail>
+  <zn-thumbnail src="https://images.unsplash.com/photo-1418065460487-3e41a6c84dc5?w=600&q=60" caption="Yosemite Valley" icon="play_arrow"></zn-thumbnail>
+  <zn-thumbnail src="https://images.unsplash.com/photo-1501785888041-af3ef285b470?w=600&q=60" caption="Hallstatt" icon="play_arrow"></zn-thumbnail>
+  <zn-thumbnail src="https://images.unsplash.com/photo-1433086966358-54859d0ed716?w=600&q=60" caption="Falls" icon="play_arrow"></zn-thumbnail>
+  <zn-thumbnail src="https://images.unsplash.com/photo-1472214103451-9374bd1c798e?w=600&q=60" caption="Rolling Hills" icon="play_arrow"></zn-thumbnail>
+  <zn-thumbnail src="https://images.unsplash.com/photo-1444927714506-8492d94b4e3d?w=600&q=60" caption="Coastline" icon="play_arrow"></zn-thumbnail>
+</zn-thumbnail-group>
+```
+
+The toggle is only rendered when it's needed — a group whose thumbnails already fit shows no toggle at all.
+
+```html:preview
+<zn-thumbnail-group caption="Fits on one row">
+  <zn-thumbnail src="https://images.unsplash.com/photo-1439066615861-d1af74d74000?w=600&q=60" caption="Tahoe Day"></zn-thumbnail>
+  <zn-thumbnail src="https://images.unsplash.com/photo-1441974231531-c6227db76b6e?w=600&q=60" caption="Sequoia Sunrise"></zn-thumbnail>
+</zn-thumbnail-group>
+```
+
+## Examples
+
+### Thumbnail Size and Shape
+
+`thumbnail-width` sets the row's track width and, when expanded, the minimum column width the grid packs against.
+`gap` sets the spacing between thumbnails, and `aspect-ratio` reshapes every thumbnail in the group.
+
+```html:preview
+<zn-thumbnail-group caption="Square, compact" thumbnail-width="120px" gap="8px" aspect-ratio="1 / 1">
+  <zn-thumbnail src="https://images.unsplash.com/photo-1439066615861-d1af74d74000?w=600&q=60" caption="Tahoe Day"></zn-thumbnail>
+  <zn-thumbnail src="https://images.unsplash.com/photo-1441974231531-c6227db76b6e?w=600&q=60" caption="Sequoia Sunrise"></zn-thumbnail>
+  <zn-thumbnail src="https://images.unsplash.com/photo-1470071459604-3b5ec3a7fe05?w=600&q=60" caption="Sonoma Horizon"></zn-thumbnail>
+  <zn-thumbnail src="https://images.unsplash.com/photo-1507525428034-b723cf961d3e?w=600&q=60" caption="Goa Beaches"></zn-thumbnail>
+  <zn-thumbnail src="https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=600&q=60" caption="Big Sur"></zn-thumbnail>
+  <zn-thumbnail src="https://images.unsplash.com/photo-1418065460487-3e41a6c84dc5?w=600&q=60" caption="Yosemite Valley"></zn-thumbnail>
+  <zn-thumbnail src="https://images.unsplash.com/photo-1501785888041-af3ef285b470?w=600&q=60" caption="Hallstatt"></zn-thumbnail>
+  <zn-thumbnail src="https://images.unsplash.com/photo-1433086966358-54859d0ed716?w=600&q=60" caption="Falls"></zn-thumbnail>
+  <zn-thumbnail src="https://images.unsplash.com/photo-1472214103451-9374bd1c798e?w=600&q=60" caption="Rolling Hills"></zn-thumbnail>
+  <zn-thumbnail src="https://images.unsplash.com/photo-1444927714506-8492d94b4e3d?w=600&q=60" caption="Coastline"></zn-thumbnail>
+</zn-thumbnail-group>
+```
+
+Those three attributes are shorthand for `--zn-thumbnail-width`, `--zn-thumbnail-gap` and
+`--zn-thumbnail-aspect-ratio`, which you can set on the group directly instead. Because
+[thumbnail](/components/thumbnail)'s custom properties all inherit, **any** of them — chip colours, corner radii,
+preview sizing — can be set once on the group and will apply to every thumbnail in it.
+
+```html:preview
+<zn-thumbnail-group
+  caption="Restyled from the group"
+  style="--zn-thumbnail-width: 120px;
+         --zn-thumbnail-gap: 8px;
+         --zn-thumbnail-radius: 16px;
+         --zn-thumbnail-chip-background: rgb(var(--zn-primary));
+         --zn-thumbnail-selected-color: rgb(var(--zn-color-warning));">
+  <zn-thumbnail src="https://images.unsplash.com/photo-1439066615861-d1af74d74000?w=600&q=60" caption="Tahoe Day" icon="play_arrow" selected></zn-thumbnail>
+  <zn-thumbnail src="https://images.unsplash.com/photo-1441974231531-c6227db76b6e?w=600&q=60" caption="Sequoia Sunrise" icon="play_arrow"></zn-thumbnail>
+  <zn-thumbnail src="https://images.unsplash.com/photo-1470071459604-3b5ec3a7fe05?w=600&q=60" caption="Sonoma Horizon" icon="play_arrow"></zn-thumbnail>
+  <zn-thumbnail src="https://images.unsplash.com/photo-1507525428034-b723cf961d3e?w=600&q=60" caption="Goa Beaches" icon="play_arrow"></zn-thumbnail>
+  <zn-thumbnail src="https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=600&q=60" caption="Big Sur" icon="play_arrow"></zn-thumbnail>
+  <zn-thumbnail src="https://images.unsplash.com/photo-1418065460487-3e41a6c84dc5?w=600&q=60" caption="Yosemite Valley" icon="play_arrow"></zn-thumbnail>
+  <zn-thumbnail src="https://images.unsplash.com/photo-1501785888041-af3ef285b470?w=600&q=60" caption="Hallstatt" icon="play_arrow"></zn-thumbnail>
+  <zn-thumbnail src="https://images.unsplash.com/photo-1433086966358-54859d0ed716?w=600&q=60" caption="Falls" icon="play_arrow"></zn-thumbnail>
+  <zn-thumbnail src="https://images.unsplash.com/photo-1472214103451-9374bd1c798e?w=600&q=60" caption="Rolling Hills" icon="play_arrow"></zn-thumbnail>
+  <zn-thumbnail src="https://images.unsplash.com/photo-1444927714506-8492d94b4e3d?w=600&q=60" caption="Coastline" icon="play_arrow"></zn-thumbnail>
+</zn-thumbnail-group>
+```
+
+### Preview
+
+Give the thumbnails a `full-uri` and clicking one opens a full-screen preview that grows out of its position in the
+row. The preview opens in the browser's top layer, so it escapes the scrolling row instead of being clipped by it. See
+[thumbnail](/components/thumbnail#preview) for the trigger options.
+
+```html:preview
+<zn-thumbnail-group caption="Landscape">
+  <zn-thumbnail src="https://images.unsplash.com/photo-1439066615861-d1af74d74000?w=400&q=50" full-uri="https://images.unsplash.com/photo-1439066615861-d1af74d74000?w=2000&q=80" caption="Tahoe Day" icon="play_arrow"></zn-thumbnail>
+  <zn-thumbnail src="https://images.unsplash.com/photo-1441974231531-c6227db76b6e?w=400&q=50" full-uri="https://images.unsplash.com/photo-1441974231531-c6227db76b6e?w=2000&q=80" caption="Sequoia Sunrise" icon="play_arrow"></zn-thumbnail>
+  <zn-thumbnail src="https://images.unsplash.com/photo-1470071459604-3b5ec3a7fe05?w=400&q=50" full-uri="https://images.unsplash.com/photo-1470071459604-3b5ec3a7fe05?w=2000&q=80" caption="Sonoma Horizon" icon="play_arrow"></zn-thumbnail>
+  <zn-thumbnail src="https://images.unsplash.com/photo-1507525428034-b723cf961d3e?w=400&q=50" full-uri="https://images.unsplash.com/photo-1507525428034-b723cf961d3e?w=2000&q=80" caption="Goa Beaches" icon="play_arrow"></zn-thumbnail>
+  <zn-thumbnail src="https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=400&q=50" full-uri="https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=2000&q=80" caption="Big Sur" icon="play_arrow"></zn-thumbnail>
+  <zn-thumbnail src="https://images.unsplash.com/photo-1418065460487-3e41a6c84dc5?w=400&q=50" full-uri="https://images.unsplash.com/photo-1418065460487-3e41a6c84dc5?w=2000&q=80" caption="Yosemite Valley" icon="play_arrow"></zn-thumbnail>
+  <zn-thumbnail src="https://images.unsplash.com/photo-1501785888041-af3ef285b470?w=400&q=50" full-uri="https://images.unsplash.com/photo-1501785888041-af3ef285b470?w=2000&q=80" caption="Hallstatt" icon="play_arrow"></zn-thumbnail>
+  <zn-thumbnail src="https://images.unsplash.com/photo-1433086966358-54859d0ed716?w=400&q=50" full-uri="https://images.unsplash.com/photo-1433086966358-54859d0ed716?w=2000&q=80" caption="Falls" icon="play_arrow"></zn-thumbnail>
+</zn-thumbnail-group>
+```
+
+### Selection
+
+Add `selectable` and the group tracks a single selection for you: clicking a thumbnail moves the accent ring, updates
+the group's `value`, and emits `zn-change`. A thumbnail marked `selected` in markup becomes the starting value.
+
+```html:preview
+<zn-thumbnail-group caption="Pick a still" selectable>
+  <zn-thumbnail value="tahoe" src="https://images.unsplash.com/photo-1439066615861-d1af74d74000?w=600&q=60" caption="Tahoe Day" selected></zn-thumbnail>
+  <zn-thumbnail value="sequoia" src="https://images.unsplash.com/photo-1441974231531-c6227db76b6e?w=600&q=60" caption="Sequoia Sunrise"></zn-thumbnail>
+  <zn-thumbnail value="sonoma" src="https://images.unsplash.com/photo-1470071459604-3b5ec3a7fe05?w=600&q=60" caption="Sonoma Horizon"></zn-thumbnail>
+  <zn-thumbnail value="goa" src="https://images.unsplash.com/photo-1507525428034-b723cf961d3e?w=600&q=60" caption="Goa Beaches"></zn-thumbnail>
+</zn-thumbnail-group>
+```
+
+### Counting a Larger Set
+
+When the row only holds the first page of a much larger set, set `total` so the toggle advertises the real size. The
+toggle appears whenever `total` exceeds the number of slotted thumbnails, even if those all fit. Listen for `zn-expand`
+to fetch and append the rest.
+
+```html:preview
+<zn-thumbnail-group caption="Landscape" total="79" id="thumbnail-group-lazy">
+  <zn-thumbnail src="https://images.unsplash.com/photo-1439066615861-d1af74d74000?w=600&q=60" caption="Tahoe Day"></zn-thumbnail>
+  <zn-thumbnail src="https://images.unsplash.com/photo-1441974231531-c6227db76b6e?w=600&q=60" caption="Sequoia Sunrise"></zn-thumbnail>
+  <zn-thumbnail src="https://images.unsplash.com/photo-1470071459604-3b5ec3a7fe05?w=600&q=60" caption="Sonoma Horizon"></zn-thumbnail>
+</zn-thumbnail-group>
+
+<script>
+  const group = document.getElementById('thumbnail-group-lazy');
+
+  group.addEventListener('zn-expand', () => {
+    // Load the rest of the set the first time the group is expanded.
+    if (group.dataset.loaded) return;
+    group.dataset.loaded = 'true';
+
+    for (let i = 4; i <= group.total; i++) {
+      const thumbnail = document.createElement('zn-thumbnail');
+      thumbnail.caption = `Landscape ${i}`;
+      thumbnail.src = `https://picsum.photos/seed/landscape-${i}/480/270`;
+      group.append(thumbnail);
+    }
+  });
+</script>
+```
+
+### Custom Labels
+
+Override `show-all-label` and `show-less-label` for wording that suits the content. The count is appended to the
+expand label in brackets.
+
+```html:preview
+<zn-thumbnail-group
+  caption="Recordings"
+  total="24"
+  show-all-label="Browse all recordings"
+  show-less-label="Collapse">
+  <zn-thumbnail src="https://images.unsplash.com/photo-1439066615861-d1af74d74000?w=600&q=60" caption="Tahoe Day"></zn-thumbnail>
+  <zn-thumbnail src="https://images.unsplash.com/photo-1441974231531-c6227db76b6e?w=600&q=60" caption="Sequoia Sunrise"></zn-thumbnail>
+</zn-thumbnail-group>
+```
+
+### Header Actions
+
+The `actions` slot sits in the header before the toggle.
+
+```html:preview
+<zn-thumbnail-group caption="Cityscape" total="41">
+  <zn-button slot="actions" outline icon="upload">Upload</zn-button>
+  <zn-thumbnail src="https://images.unsplash.com/photo-1512453979798-5ea266f8880c?w=600&q=60" caption="Dubai Skyline" icon="play_arrow"></zn-thumbnail>
+  <zn-thumbnail src="https://images.unsplash.com/photo-1518684079-3c830dcef090?w=600&q=60" caption="Dubai at Night" icon="play_arrow"></zn-thumbnail>
+  <zn-thumbnail src="https://images.unsplash.com/photo-1546412414-e1885259563a?w=600&q=60" caption="Dubai Creek" icon="play_arrow"></zn-thumbnail>
+</zn-thumbnail-group>
+```
+
+### Always Showing the Toggle
+
+`always-toggle` keeps the toggle on screen even when everything already fits — useful when the row is one of several
+sibling groups and you want the headers to line up. `hide-toggle` does the opposite and suppresses it entirely,
+leaving a plain scrolling row.
+
+```html:preview
+<zn-thumbnail-group caption="Always" always-toggle>
+  <zn-thumbnail src="https://images.unsplash.com/photo-1439066615861-d1af74d74000?w=600&q=60" caption="Tahoe Day"></zn-thumbnail>
+  <zn-thumbnail src="https://images.unsplash.com/photo-1441974231531-c6227db76b6e?w=600&q=60" caption="Sequoia Sunrise"></zn-thumbnail>
+</zn-thumbnail-group>
+
+<zn-thumbnail-group caption="Never" hide-toggle>
+  <zn-thumbnail src="https://images.unsplash.com/photo-1439066615861-d1af74d74000?w=600&q=60" caption="Tahoe Day"></zn-thumbnail>
+  <zn-thumbnail src="https://images.unsplash.com/photo-1441974231531-c6227db76b6e?w=600&q=60" caption="Sequoia Sunrise"></zn-thumbnail>
+  <zn-thumbnail src="https://images.unsplash.com/photo-1470071459604-3b5ec3a7fe05?w=600&q=60" caption="Sonoma Horizon"></zn-thumbnail>
+  <zn-thumbnail src="https://images.unsplash.com/photo-1507525428034-b723cf961d3e?w=600&q=60" caption="Goa Beaches"></zn-thumbnail>
+  <zn-thumbnail src="https://images.unsplash.com/photo-1506905925346-21bda4d32df4?w=600&q=60" caption="Big Sur"></zn-thumbnail>
+  <zn-thumbnail src="https://images.unsplash.com/photo-1418065460487-3e41a6c84dc5?w=600&q=60" caption="Yosemite Valley"></zn-thumbnail>
+  <zn-thumbnail src="https://images.unsplash.com/photo-1501785888041-af3ef285b470?w=600&q=60" caption="Hallstatt"></zn-thumbnail>
+  <zn-thumbnail src="https://images.unsplash.com/photo-1433086966358-54859d0ed716?w=600&q=60" caption="Falls"></zn-thumbnail>
+</zn-thumbnail-group>
+```
+
+### Starting Expanded
+
+Set `expanded` to open the grid on first paint, or call `show()` / `hide()` to drive it from script.
+
+```html:preview
+<zn-thumbnail-group caption="Cityscape" expanded>
+  <zn-thumbnail src="https://images.unsplash.com/photo-1512453979798-5ea266f8880c?w=600&q=60" caption="Dubai Skyline" icon="play_arrow"></zn-thumbnail>
+  <zn-thumbnail src="https://images.unsplash.com/photo-1518684079-3c830dcef090?w=600&q=60" caption="Dubai at Night" icon="play_arrow"></zn-thumbnail>
+  <zn-thumbnail src="https://images.unsplash.com/photo-1546412414-e1885259563a?w=600&q=60" caption="Dubai Creek" icon="play_arrow"></zn-thumbnail>
+  <zn-thumbnail src="https://images.unsplash.com/photo-1502920917128-1aa500764cbd?w=600&q=60" caption="Dubai from Above" icon="play_arrow"></zn-thumbnail>
+  <zn-thumbnail src="https://images.unsplash.com/photo-1449824913935-59a10b8d2000?w=600&q=60" caption="Los Angeles Flyover" icon="play_arrow"></zn-thumbnail>
+  <zn-thumbnail src="https://images.unsplash.com/photo-1534190760961-74e8c1b5c3da?w=600&q=60" caption="Los Angeles Beach" icon="play_arrow"></zn-thumbnail>
+  <zn-thumbnail src="https://images.unsplash.com/photo-1444723121867-7a241cacace9?w=600&q=60" caption="Los Angeles at Night" icon="play_arrow"></zn-thumbnail>
+  <zn-thumbnail src="https://images.unsplash.com/photo-1513635269975-59663e0ac1ad?w=600&q=60" caption="London Evening" icon="play_arrow"></zn-thumbnail>
+</zn-thumbnail-group>
+```