@kubex/zinc 1.1.97 → 1.1.98

package/docs/pages/components/button.md

@@ -117,6 +117,15 @@ Buttons can be used with just an icon and no text by omitting the button label.
 <zn-button icon="add" color="info"></zn-button>
 ```
 
+An icon-only button has no text for assistive technology to read, so give it a name
+with the `label` attribute. A `tooltip` is used as the name when no `label` is set,
+which covers most icon-only buttons without extra markup.
+
+```html:preview
+<zn-button icon="settings" label="Settings"></zn-button>
+<zn-button icon="delete" color="error" tooltip="Delete"></zn-button>
+```
+
 ### Icon Buttons
 
 Use `icon-button` to render a chromed icon button: a 40x36 white button with a border, a 6px radius, and a centred 20px icon. Pass `small` for the 36x36 variant or `round` for a 36x36 circle on the tab tint. The icon button style takes precedence over color variants like `secondary` — the `color` attribute only tints the icon.
@@ -216,7 +225,8 @@ Use `muted-notifications` for a subtle notification style.
 
 ### Tooltip
 
-Use the `tooltip` attribute to add a tooltip to the button.
+Use the `tooltip` attribute to add a tooltip to the button. On a button with no text,
+the tooltip also becomes the accessible name — see [Icon-Only Buttons](#icon-only-buttons).
 
 ```html:preview
 <zn-button icon="info" tooltip="This button provides additional information"></zn-button>

package/docs/pages/components/chart.md

@@ -1,7 +1,7 @@
 ---
 meta:
   title: Data Chart
-  description: Charts visualize data using various chart types powered by Apache ECharts. Display line charts, bar charts, area charts, sankey diagrams, and more with full customization options.
+  description: Charts visualize data using line, bar, area, circular, statistical, hierarchical, and flow layouts powered by Apache ECharts.
 layout: component
 ---
 
@@ -281,6 +281,135 @@ Use `type="sankey"` to render a Sankey flow diagram. Each item in the series `da
 </zn-chart>
 ```
 
+### Pie Chart
+
+Use `type="pie"` for part-to-whole data. The first series supplies the slice values and `categories` supplies their
+names.
+
+```html:preview
+<zn-chart
+  type="pie"
+  categories="[&quot;Configuration suggestion&quot;,&quot;Insecure configuration&quot;]"
+  data="[{&quot;name&quot;:&quot;Insights&quot;,&quot;data&quot;:[8,1]}]"
+  height="300">
+</zn-chart>
+```
+
+### Donut Chart
+
+Use `type="donut"` for a pie chart with a hollow centre. Adjust the ring with `inner-radius` and `outer-radius`; both
+accept an ECharts pixel value or percentage. Add `show-labels` to render labels beside the slices.
+
+```html:preview
+<zn-chart
+  type="donut"
+  inner-radius="45%"
+  outer-radius="75%"
+  colors="[&quot;#ffe29a&quot;,&quot;#f78ab3&quot;]"
+  categories="[&quot;Configuration suggestion&quot;,&quot;Insecure configuration&quot;]"
+  data="[{&quot;name&quot;:&quot;Insights&quot;,&quot;data&quot;:[8,1]}]"
+  height="300">
+</zn-chart>
+```
+
+### Scatter Chart
+
+Use `type="scatter"` with `[x, y]` coordinate pairs. `d-size` controls point size, and `xaxis="datetime"` can be used
+for time-based scatter plots.
+
+```html:preview
+<zn-chart
+  type="scatter"
+  d-size="14"
+  data="[{&quot;name&quot;:&quot;Latency&quot;,&quot;data&quot;:[[12,110],[24,180],[38,140],[52,260],[70,220]]}]"
+  height="300">
+</zn-chart>
+```
+
+### Radar Chart
+
+Use `type="radar"` with an `indicators` array describing each axis. Each normal series becomes one radar shape.
+
+```html:preview
+<zn-chart
+  type="radar"
+  indicators="[{&quot;name&quot;:&quot;Security&quot;,&quot;max&quot;:100},{&quot;name&quot;:&quot;Performance&quot;,&quot;max&quot;:100},{&quot;name&quot;:&quot;Reliability&quot;,&quot;max&quot;:100},{&quot;name&quot;:&quot;Usability&quot;,&quot;max&quot;:100}]"
+  data="[{&quot;name&quot;:&quot;Current&quot;,&quot;data&quot;:[82,71,94,76]},{&quot;name&quot;:&quot;Target&quot;,&quot;data&quot;:[95,90,98,90]}]"
+  height="320">
+</zn-chart>
+```
+
+### Gauge Chart
+
+Use `type="gauge"` for a single current value. `min-value`, `max-value`, and `y-axis-append` configure its range and
+displayed unit.
+
+```html:preview
+<zn-chart
+  type="gauge"
+  min-value="0"
+  max-value="100"
+  y-axis-append="%"
+  data="[{&quot;name&quot;:&quot;Security score&quot;,&quot;data&quot;:[82]}]"
+  height="300">
+</zn-chart>
+```
+
+### Funnel Chart
+
+Use `type="funnel"` for ordered stages. Numeric values pair with `categories`, using the same compact format as pie
+charts.
+
+```html:preview
+<zn-chart
+  type="funnel"
+  categories="[&quot;Visitors&quot;,&quot;Trials&quot;,&quot;Customers&quot;]"
+  data="[{&quot;name&quot;:&quot;Conversion&quot;,&quot;data&quot;:[1000,320,85]}]"
+  height="320">
+</zn-chart>
+```
+
+### Heatmap Chart
+
+Use `type="heatmap"` with x-axis `categories`, `y-categories`, and `[xIndex, yIndex, value]` data points. The visual
+range is derived from the values unless `min-value` or `max-value` is provided.
+
+```html:preview
+<zn-chart
+  type="heatmap"
+  show-labels
+  categories="[&quot;Mon&quot;,&quot;Tue&quot;,&quot;Wed&quot;,&quot;Thu&quot;,&quot;Fri&quot;]"
+  y-categories="[&quot;API&quot;,&quot;Web&quot;,&quot;Worker&quot;]"
+  data="[{&quot;name&quot;:&quot;Requests&quot;,&quot;data&quot;:[[0,0,5],[1,0,12],[2,0,8],[3,0,16],[4,0,11],[0,1,9],[1,1,15],[2,1,12],[3,1,20],[4,1,14],[0,2,3],[1,2,7],[2,2,5],[3,2,10],[4,2,8]]}]"
+  height="320">
+</zn-chart>
+```
+
+### Treemap Chart
+
+Use `type="treemap"` with hierarchical `children` data to compare nested values by area.
+
+```html:preview
+<zn-chart
+  type="treemap"
+  data="[{&quot;name&quot;:&quot;Insights&quot;,&quot;data&quot;:[{&quot;name&quot;:&quot;Security&quot;,&quot;children&quot;:[{&quot;name&quot;:&quot;Configuration&quot;,&quot;value&quot;:8},{&quot;name&quot;:&quot;Insecure&quot;,&quot;value&quot;:1}]},{&quot;name&quot;:&quot;Performance&quot;,&quot;value&quot;:4}]}]"
+  height="320">
+</zn-chart>
+```
+
+### Sunburst Chart
+
+Use `type="sunburst"` for radial hierarchical data. `inner-radius` and `outer-radius` adjust the occupied area.
+
+```html:preview
+<zn-chart
+  type="sunburst"
+  outer-radius="90%"
+  data="[{&quot;name&quot;:&quot;Insights&quot;,&quot;data&quot;:[{&quot;name&quot;:&quot;Security&quot;,&quot;children&quot;:[{&quot;name&quot;:&quot;Configuration&quot;,&quot;value&quot;:8},{&quot;name&quot;:&quot;Insecure&quot;,&quot;value&quot;:1}]},{&quot;name&quot;:&quot;Performance&quot;,&quot;children&quot;:[{&quot;name&quot;:&quot;Latency&quot;,&quot;value&quot;:4}]}]}]"
+  height="340">
+</zn-chart>
+```
+
 ### Cross-Chart Tooltip Sync
 
 Use `sync-group="<id>"` on two or more charts to synchronise hover tooltips, zoom, and legend selection across them.
@@ -439,6 +568,32 @@ When `type="sankey"`, each item in the series `data` array is an edge:
 
 Nodes are auto-derived from unique source/target values. To customise node appearance or ordering, include an explicit `nodes` key on the series object.
 
+### Pie and Donut Data
+
+Pie and donut charts use the first series. The standard numeric format pairs each value with the category at the same
+index. You can alternatively pass ECharts-style named slices when each slice needs its own metadata or colour:
+
+```json
+[{
+  "name": "Insights",
+  "data": [
+    {"name": "Configuration suggestion", "value": 8, "color": "#ffe29a"},
+    {"name": "Insecure configuration", "value": 1, "color": "#f78ab3"}
+  ]
+}]
+```
+
+### Specialized Data Formats
+
+- Scatter points use `[x, y]` or `{ "x": value, "y": value }`.
+- Radar charts accept an `indicators` array of `{ "name": string, "min"?: number, "max"?: number }`; each series
+  contains one value per indicator.
+- Gauge charts use the first value in the first series.
+- Funnel charts accept the same numeric/category or named-value formats as pie charts.
+- Heatmaps use `[xIndex, yIndex, value]` points with `categories` and `y-categories`.
+- Treemaps and sunbursts accept hierarchical nodes containing `name`, optional `value`, and optional recursive
+  `children`.
+
 ### HTML Encoding
 
 When using the data attribute in HTML, JSON must be properly encoded. Use `&quot;` for quotes:
@@ -483,6 +638,15 @@ chart.enableAnimations = true;
 - **Line Charts**: Best for showing trends over time or continuous data
 - **Bar Charts**: Ideal for comparing discrete categories or values
 - **Area Charts**: Good for showing cumulative totals or part-to-whole relationships over time
+- **Pie Charts**: Useful for compact part-to-whole comparisons with a small number of slices
+- **Donut Charts**: Useful when a pie chart needs a lighter visual weight or centred annotation space
+- **Scatter Charts**: Show relationships, distributions, and clusters between two numeric dimensions
+- **Radar Charts**: Compare a small number of entities across a shared set of metrics
+- **Gauge Charts**: Display one value against a meaningful bounded range
+- **Funnel Charts**: Show progressive reduction through ordered stages
+- **Heatmaps**: Reveal density and patterns across two categorical dimensions
+- **Treemaps**: Compare hierarchical values by area
+- **Sunburst Charts**: Explore hierarchical proportions across radial levels
 - **Stacked Charts**: Use when showing how categories contribute to a total
 
 ### Performance Considerations
@@ -505,5 +669,3 @@ chart.enableAnimations = true;
 - Round values appropriately for readability
 - Use `y-axis-append` to add units or symbols to values
 - Format dates consistently when using time series data
-
-

package/docs/pages/components/icon-picker.md

@@ -71,6 +71,14 @@ Use the `line` library for Lineicons.
 <zn-icon-picker name="line" label="Line Icon" icon="heart" library="line"></zn-icon-picker>
 ```
 
+### Lucide Icons
+
+Use the `lucide` library for [Lucide](https://lucide.dev/icons) icons, rendered as inline SVGs. Icon names use kebab-case.
+
+```html:preview
+<zn-icon-picker name="lucide" label="Lucide Icon" icon="rocket" library="lucide"></zn-icon-picker>
+```
+
 ### Gravatar
 
 Use the `gravatar` library to display a Gravatar from an email address.

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>
+```