@kubex/zinc 1.1.184 → 2.0.0

package/docs/pages/components/copy-button.md

@@ -87,8 +87,8 @@ Use the `src` attribute to change the copy icon.
 Use the `size` attribute to control the icon size.
 
 ```html:preview
-<zn-copy-button value="Small icon" size="16"></zn-copy-button>
-<zn-copy-button value="Default size" size="24"></zn-copy-button>
+<zn-copy-button value="Small icon" size="12"></zn-copy-button>
+<zn-copy-button value="Default size" size="16"></zn-copy-button>
 <zn-copy-button value="Large icon" size="32"></zn-copy-button>
 <zn-copy-button value="Extra large" size="48"></zn-copy-button>
 ```

package/docs/pages/components/data-table-filter.md

@@ -1,7 +1,7 @@
 ---
 meta:
   title: Data Table Filter
-  description: An inline filter bar for data tables. Each active filter is a pill whose dropdown sets its value, alongside an add-filter control and a clear.
+  description: The filter for data tables. A funnel opens a builder of field, operator and value rules, and the rules that apply show as removable chips.
 layout: component
 ---
 
@@ -12,60 +12,56 @@ layout: component
 </zn-data-table-filter>
 ```
 
-Filters render inline rather than in a slideout. Each active filter is a pill showing its name, and its value once set; the pill's dropdown lists the filter's `options` as checkable values, or a text input for a filter that declares none. Each pill carries an X that drops that filter. `+ Add filter` lists the filters that are not yet active, and `Clear` removes them all.
+The funnel opens a popover headed **Filters · Show records that match all of these**. Each row is a rule: pick a field, an operator and a value, or remove the row with its trash button. **+ Add filter** adds a row for a field not yet used, and **Clear all** removes every rule. Nothing reaches the table until **Apply**, which closes the popover and applies every rule that has a field, an operator and a value; while any row is still empty the heading says so. Closing the popover with Escape or a click outside it discards the edits.
 
-A filter starts on its **first declared operator**. Declare more than one and the pill offers a choice: a value editor gets a row of operator chips above it, an options menu lists the operators above its values, and the pill then reads `Age ≥ 18` rather than `Age: 18`. Switching operator keeps the value — a date is re-encoded for the new comparator.
+The rules that apply show as chips after the funnel, and the funnel's badge counts them. A chip's text opens the popover again, and its X removes that rule. Inside a [`zn-data-table`](/components/data-table#filtering) or [`zn-report-table`](/components/report-table) the funnel sits in the header and the chips get a row of their own under it.
 
-Declare `in` or `nin` to let a filter hold several values at once — the pill then counts them, e.g. `Role (2)`, and its dropdown stays open so you can pick more. Any other operator holds a single value: the dropdown closes on select, and picking the same value again clears it.
+A rule starts on its field's **first declared operator**, and the operator list offers the rest. Picking another field resets the operator and the value. The value control follows the field:
 
-Picking a filter from `+ Add filter` opens its pill straight away, with a text field focused, so naming a filter and giving it a value is one pass. A typed value is one value however many spaces it contains; only a comma starts another.
+- A field with `options`, or a `bool` field, gets a select. With `in` or `nin` it becomes a multi-select.
+- A `number` field gets a number input, and a `date` or `dateTime` field a date input.
+- Any other field gets a text input. With `in` or `nin`, separate values with commas.
 
-`default-filters` takes a comma-separated list of filter ids to show a pill for up front. Inside a `zn-data-table` the bar is hidden until the header's filter toggle is clicked, and `activeCount` reports how many filters currently hold a value.
+With more than eight fields, the field select is searchable: open it and type, and the placeholder reads `Search N fields...`.
+
+`default-filters` takes a comma-separated list of field ids. When the popover opens with nothing applied, it starts with an empty row for each of them, rather than one blank row.
 
 ```html:preview
 <zn-data-table-filter
   default-filters="status"
   filters='[
-    {"id":"status","name":"Status","options":{"open":"Open","closed":"Closed"},"operators":["eq"]},
-    {"id":"tag","name":"Tag","options":{"bug":"Bug","chore":"Chore","feature":"Feature"},"operators":["in"]},
-    {"id":"owner","name":"Owner","operators":["contains"]}
+    {"id":"status","name":"Status","options":{"open":"Open","closed":"Closed"},"operators":["eq","neq"]},
+    {"id":"tag","name":"Tag","options":{"bug":"Bug","chore":"Chore","feature":"Feature"},"operators":["in","nin"]},
+    {"id":"owner","name":"Owner","operators":["contains","eq"]}
   ]'>
 </zn-data-table-filter>
 ```
 
-The component emits `zn-filter-change` and exposes the query on `value`, encoded exactly as `zn-query-builder` encodes it — base64 of `[{key, comparator, value}]` — so a backend built against the query builder needs no changes.
+The component emits `zn-filter-change` and exposes the query on `value`, encoded as `zn-query-builder` encodes it: base64 of `[{key, comparator, value}]`, or `''` when no rule applies. It only emits when that value changes. A multi-select's values are joined with spaces, and `activeCount` reports how many rules apply.
+
+Setting `value` from outside rebuilds the rules, so a filter restored from a shared URL through `zn-data-table`'s [`sharable`](/components/data-table#shareable-url-state) sync shows its chips straight away.
 
-Setting `value` round-trips: assigning that same base64 string back — for example restoring it from a shared URL via `zn-data-table`'s [`sharable`](/components/data-table#shareable-url-state) sync — rebuilds the active pills, so the bar reopens in the state it was encoded in. Restoration needs the `filters` schema present to resolve each key, and it stands down once any filter already holds a value, so a shared filter still wins over an empty `default-filters` pill while a filter the user is mid-way through setting is never clobbered.
+### Typeahead
 
-One caveat: a restored **date** filter shows its raw encoded value on the pill (a timestamp, or a minutes-from-now offset) rather than a formatted date, because the human-readable label is not part of the encoded query. The filter still applies correctly; only the pill text differs until the value is re-picked.
+Inside a `zn-data-table`, a text field suggests values from the rows the table has already loaded, matched case-insensitively against what has been typed, keyed on the column whose name matches the field's id. Set `suggestions` yourself, as `{[fieldId]: string[]}`, to offer something else.
 
-### Long Option Lists
+### Showing the Chips Elsewhere
 
-An option list caps its height at 320px and scrolls inside the panel rather than running off the
-screen, with the scrollbar drawn rather than left to the platform's overlay one. Past eight options
-the pill also gains a search field, merged into the top of the panel and pinned there, that narrows
-the list case-insensitively.
+Set another filter as a filter's `source` property and it shows only that filter's chips, while that filter stops showing its own. The tables use this to keep the funnel in their header and the chips in a row under it.
 
 ```html:preview
-<zn-data-table-filter
-  default-filters="category"
-  filters='[
-    {"id":"category","name":"Category","operators":["eq","in"],"options":{
-      "how-to":"How To","linux":"Linux","beta":"Beta","router":"Router","tv":"TV","other":"Other",
-      "mac":"Mac Hotspot Shield","general":"General","android":"Android Hotspot Shield",
-      "educational":"Educational","windows":"Windows Hotspot Shield","ios":"iOS",
-      "getting-started":"Getting Started","payments":"Payments & Subscriptions",
-      "accounts":"Manage Account & Devices","troubleshoot":"Troubleshoot issues",
-      "releases":"Release Notes","archived":"Archived Articles","internal":"Internal Information",
-      "tutorials":"Tutorials"}}
-  ]'>
-</zn-data-table-filter>
+<div>
+  <zn-data-table-filter id="chips-source"
+    filters='[{"id":"status","name":"Status","options":{"open":"Open","closed":"Closed"},"operators":["eq"]}]'>
+  </zn-data-table-filter>
+  <zn-data-table-filter id="chips-row"></zn-data-table-filter>
+</div>
+
+<script>
+  document.getElementById('chips-row').source = document.getElementById('chips-source');
+</script>
 ```
 
-### Typeahead
-
-Inside a `zn-data-table` a text filter suggests values from the rows the table has already loaded, matched case-insensitively against what has been typed, keyed on the column whose name matches the filter's id. Set `suggestions` yourself — `{[filterId]: string[]}` — to offer something else.
-
 ## Examples
 
 ### Basic Text Filters
@@ -81,8 +77,7 @@ Create simple text-based filters with equality and fuzzy search operators.
 
 ### Number Filters with Operators
 
-Use number type filters with comparison operators like equal, greater than, less than. The pill's
-editor shows a chip per operator; `>`, `≥`, `<` and `≤` keep their symbols, and the rest read as words.
+Use number fields with comparison operators: they read `is more than`, `is at least`, `is less than` and `is at most`.
 
 ```html:preview
 <zn-data-table-filter
@@ -93,10 +88,9 @@ editor shows a chip per operator; `>`, `≥`, `<` and `≤` keep their symbols,
 
 ### Date Filters
 
-Filter by dates with before, after, and equal operators. A `date` pill opens a calendar and closes
-once a day is picked; a `dateTime` pill adds a time selector and stays open while it's set.
+Filter by dates with before, after and equal operators. A `date` field takes a date, and a `dateTime` field a date and a time.
 
-Values are encoded the way `zn-query-builder` encodes them, so `dateSubmitFormat` picks the wire
+Values are encoded the way `zn-query-builder` encodes them, and changing the operator re-encodes the date. `dateSubmitFormat` picks the wire
 format: `legacy` (the default — seconds for `eq`/`neq`, otherwise minutes from now, negated for
 `before`), `timestamp` (milliseconds) or `iso`.
 
@@ -118,17 +112,6 @@ Use predefined options for select-based filtering.
 </zn-data-table-filter>
 ```
 
-### Limited Options Display
-
-Control how many options are initially visible using `maxOptionsVisible`.
-
-```html:preview
-<zn-data-table-filter
-  filters="[{&quot;id&quot;:&quot;category&quot;,&quot;name&quot;:&quot;Category&quot;,&quot;options&quot;:{&quot;cat1&quot;:&quot;Category 1&quot;,&quot;cat2&quot;:&quot;Category 2&quot;,&quot;cat3&quot;:&quot;Category 3&quot;,&quot;cat4&quot;:&quot;Category 4&quot;,&quot;cat5&quot;:&quot;Category 5&quot;,&quot;cat6&quot;:&quot;Category 6&quot;},&quot;maxOptionsVisible&quot;:3,&quot;operators&quot;:[&quot;eq&quot;,&quot;in&quot;]}]"
-  name="limited-options">
-</zn-data-table-filter>
-```
-
 ### Mixed Filter Types
 
 Combine different field types in a single filter component.

package/docs/pages/components/data-table-search.md

@@ -9,7 +9,7 @@ layout: component
 
 ### Basic Search
 
-Use the `zn-data-table-search` component to provide search functionality for data tables. The component includes a search input with a trailing search icon and is clearable by default.
+Use the `zn-data-table-search` component to provide search functionality for data tables. The component includes a search input with a leading search icon and is clearable by default.
 
 ```html:preview
 <zn-data-table-search></zn-data-table-search>
@@ -30,7 +30,7 @@ Use the `placeholder` attribute to customize the input placeholder text.
 ### Help Text
 
 Use the `help-text` attribute to explain what can be searched. It shows an information icon inside the search field,
-before the search icon, and reads out as a tooltip on hover or focus.
+after the input text, and reads out as a tooltip on hover or focus.
 
 ```html:preview
 <zn-data-table-search
@@ -402,7 +402,7 @@ Use the `getFormData()` method to retrieve all form data from the search compone
 The component is built with accessibility in mind:
 
 - Uses semantic HTML with proper input type (`search`)
-- Includes a visible trailing search icon for visual recognition
+- Includes a visible leading search icon for visual recognition
 - Supports keyboard navigation and clearing via the clearable input
 - Integrates with form validation and submission
 - Explains what is searchable through the help-text attribute, shown from an information icon
@@ -449,4 +449,4 @@ The component is built with accessibility in mind:
 ## Dependencies
 
 - `zn-input` - Used for the search input field
-- `zn-icon` - Used for the trailing search icon
+- `zn-icon` - Used for the leading search icon

package/docs/pages/components/data-table.md

@@ -23,6 +23,8 @@ fullWidth: true
 </zn-data-table>
 ```
 
+For reports grouped by a dimension over a date range, with grouped headings and a total row, use [Report Table](/components/report-table).
+
 ## Examples
 
 ### Basic Data Table
@@ -415,9 +417,9 @@ Or use the built-in empty state with custom text:
 
 ### Filtering
 
-Add filtering with the `zn-data-table-filter` component. The header carries a filter toggle beside the refresh button; clicking it reveals a row between the header and the rows holding the `filter` slot, where the filter component shows one pill per active filter alongside add-filter and clear controls. The row stays hidden until the toggle is clicked, and the toggle carries a count of the filters currently applied. Use `default-filters` to show a pill for a filter before the user adds it.
+Add filtering with the [`zn-data-table-filter`](/components/data-table-filter) component in the `filter` slot. It is a funnel in the header, after the search and before the column picker and refresh, with a badge counting the rules that apply. The funnel opens a popover of field / operator / value rules, and each rule that applies shows as a chip in a row under the tabs, with a remove button and Clear all. The row is there only while rules apply. The rules are sent as `filter`. Use `default-filters` to offer a rule for a field when the popover opens with nothing applied.
 
-The table also feeds the bar typeahead values for its text filters, taken from the rows it has loaded and keyed on the column whose name matches the filter's id.
+The table also feeds a slotted filter typeahead values for its text fields, taken from the rows it has loaded and keyed on the column whose name matches the field's id.
 
 :::tip
 In this preview, filter parameters are sent with the request but the static data file returns the same results regardless. With a real server endpoint, results would be filtered based on the applied criteria.
@@ -450,6 +452,27 @@ In this preview, filter parameters are sent with the request but the static data
 </zn-data-table>
 ```
 
+Without a slotted filter, set `filter-fields` to the fields and the table renders the funnel itself, in the same place. Its applied rules also reset the table to page 1.
+
+```html:preview
+<zn-data-table
+  standalone
+  caption="Users"
+  data-uri="/data/data-table.json"
+  method="GET"
+  headers='[
+    {"key":"name","label":"Name"},
+    {"key":"email","label":"Email"},
+    {"key":"status","label":"Status"}
+  ]'
+  filter-fields='[
+    {"id":"name","name":"Name","operators":["contains","eq"]},
+    {"id":"status","name":"Status","options":{"active":"Active","inactive":"Inactive"},"operators":["eq","neq"]}
+  ]'>
+  <zn-data-table-search slot="search" placeholder="Search..."></zn-data-table-search>
+</zn-data-table>
+```
+
 ### Filter Top Slot
 
 Add complex filtering options above the table using the `filter-top` slot. Perfect for search forms and advanced filters.
@@ -781,7 +804,7 @@ Cells support various styling options through the data response format. Each cel
       "id": "1",
       "cells": [
         {"text": "John Doe", "column": "name", "style": "bold"},
-        {"text": "Active", "column": "status", "chipColor": "success"},
+        {"text": "Active", "column": "status", "badgeType": "success"},
         {"text": "admin@example.com", "column": "email", "copyable": true},
         {"text": "View", "column": "action", "uri": "/users/1", "color": "info"}
       ]
@@ -799,6 +822,7 @@ Available cell properties:
 - `style`: Comma-separated styles (bold, italic, mono, code, border, center)
 - `color`: Text color
 - `chipColor`: Renders as a chip with specified color
+- `badgeType`: Renders as a badge of the given type (`neutral`, `success`, `warning`, `danger`, `info` or `ai`)
 - `uri`: Makes cell content a link
 - `target`: Link target attribute
 - `copyable`: Adds a copy button

package/docs/pages/components/date-range.md

@@ -0,0 +1,116 @@
+---
+meta:
+  title: Date Range
+  description: A button showing a date range that opens a two-month calendar with quick ranges.
+layout: component
+---
+
+```html:preview
+<zn-date-range from="2026-10-07" to="2026-10-20"></zn-date-range>
+```
+
+## Examples
+
+### Basic Date Range
+
+Click the button to open the picker. A quick range on the left applies straight away. On the calendar, click a first day and then a last day, then press Apply. The dates can also be typed in the From and To fields. Escape, Cancel or a click outside closes the picker without changing anything.
+
+When `from` and `to` are missing, the range is today.
+
+```html:preview
+<zn-date-range></zn-date-range>
+```
+
+### Limiting the Range
+
+Use `max` and `min` to limit which days can be picked. Days outside the limits are greyed out.
+
+```html:preview
+<zn-date-range from="2026-10-01" to="2026-10-15" min="2026-09-01" max="2026-10-20"></zn-date-range>
+```
+
+### Custom Quick Ranges
+
+Pass `presets` as a JSON array of `{label, from, to}` to replace the default quick ranges (Today, Yesterday, Last 7, 14 and 30 days, This month, Last month and Last 90 days). Quick ranges are cut to `min` and `max`; one that lies wholly outside them is greyed out.
+
+```html:preview
+<zn-date-range from="2026-07-01" to="2026-09-30"
+               presets='[
+                 {"label":"Q1 2026","from":"2026-01-01","to":"2026-03-31"},
+                 {"label":"Q2 2026","from":"2026-04-01","to":"2026-06-30"},
+                 {"label":"Q3 2026","from":"2026-07-01","to":"2026-09-30"}
+               ]'></zn-date-range>
+```
+
+### Note
+
+Use `note` for a short line under the calendar, such as how the range is used.
+
+```html:preview
+<zn-date-range from="2026-10-19" to="2026-10-20" note="Day Compare sets the first day against the last."></zn-date-range>
+```
+
+### Forms
+
+Give the date range a `name` and it submits `name[from]` and `name[to]` with its form.
+
+```html:preview
+<form class="date-range-form">
+  <zn-date-range name="period" from="2026-10-01" to="2026-10-20"></zn-date-range>
+  <br><br>
+  <zn-button type="submit" color="primary">Submit</zn-button>
+  <pre class="date-range-form__output"></pre>
+</form>
+
+<script type="module">
+  const form = document.querySelector('.date-range-form');
+  const output = form.querySelector('.date-range-form__output');
+
+  form.addEventListener('submit', event => {
+    event.preventDefault();
+    output.textContent = [...new FormData(form)].map(([key, value]) => `${key} = ${value}`).join('\n');
+  });
+</script>
+```
+
+### Listening for Changes
+
+`zn-change` is emitted when a range is applied, by Apply or a quick range, with `{from, to}` in its detail. Picking days without pressing Apply does not emit it.
+
+```html:preview
+<div class="date-range-events">
+  <zn-date-range from="2026-10-13" to="2026-10-20"></zn-date-range>
+  <p class="date-range-events__output">Pick a range and press Apply.</p>
+</div>
+
+<script type="module">
+  const container = document.querySelector('.date-range-events');
+  const output = container.querySelector('.date-range-events__output');
+
+  container.querySelector('zn-date-range').addEventListener('zn-change', event => {
+    output.textContent = `Applied ${event.detail.from} to ${event.detail.to}`;
+  });
+</script>
+```
+
+### Opening from Script
+
+Call `show()` and `hide()` to open and close the picker.
+
+```html:preview
+<div class="date-range-methods">
+  <zn-date-range from="2026-10-13" to="2026-10-20"></zn-date-range>
+  <zn-button size="small" color="secondary">Open picker</zn-button>
+</div>
+
+<script type="module">
+  const container = document.querySelector('.date-range-methods');
+  const range = container.querySelector('zn-date-range');
+
+  container.querySelector('zn-button').addEventListener('click', async event => {
+    event.stopPropagation();
+    await customElements.whenDefined('zn-date-range');
+    range.show();
+  });
+</script>
+```

package/docs/pages/components/dialog.md

@@ -1,7 +1,7 @@
 ---
 meta:
   title: Dialog
-  description: 'Dialogs, also called "modals", appear above the page and require the users immediate attention.'
+  description: 'Dialogs, also called "modals", appear above the page and require the user''s immediate attention.'
 layout: component
 ---
 
@@ -9,28 +9,19 @@ layout: component
 
 ### Basic Dialog
 
-This is a basic dialog. It has a trigger button that opens the dialog. The dialog has a close button and two buttons in
-the footer.
+Use a dialog only for a decision that blocks the flow. Set `trigger` to the `id` of the element that opens it. The
+header has a close button, and the footer holds the actions: the one that dismisses the dialog first, then the one that
+carries out the decision.
 
 ```html:preview
-<zn-button id="dialog-trigger">Open Basic dialog</zn-button>
-<zn-dialog class="dialog-basic" trigger="dialog-trigger" label="Dialog">
-  This is the dialog's body.
+<zn-button id="dialog-trigger">Issue refund</zn-button>
+<zn-dialog trigger="dialog-trigger" label="Issue a refund?" size="small">
+  <zn-icon src="undo" slot="header-icon"></zn-icon>
+  <p>$9.95 will be returned to Visa •••• 4242. This can't be undone.</p>
+  <zn-input label="Amount" value="$9.95"></zn-input>
 
-  <zn-button color="default" slot="footer">Do Something</zn-button>
-  <zn-button color="secondary" slot="footer" dialog-closer>Close Dialog</zn-button>
-</zn-dialog>
-```
-
-## test
-
-```html:preview
-<zn-button id="dialog-trigger">Open Basic dialog</zn-button>
-<zn-dialog class="dialog-basic" trigger="dialog-trigger" label="Verify longdomainwhitlotsofcharacters.somethignsomewhere.dev">
-  This is the dialog's body.
-
-  <zn-button color="default" slot="footer">Do Something</zn-button>
-  <zn-button color="secondary" slot="footer" dialog-closer>Close Dialog</zn-button>
+  <zn-button color="secondary" slot="footer" dialog-closer>Cancel</zn-button>
+  <zn-button slot="footer">Issue refund</zn-button>
 </zn-dialog>
 ```
 
@@ -70,7 +61,7 @@ styled based on the dialog variant.
 
 #### Default Variant
 
-Use the default variant for confirmation of neutral actions like submitting a form or displaying informational content.
+Use the default variant to confirm a neutral action, such as submitting a form, or to show information.
 
 ```html:preview
 <zn-button id="dialog-default-trigger">Open Default Dialog</zn-button>
@@ -85,7 +76,7 @@ Use the default variant for confirmation of neutral actions like submitting a fo
 
 #### Warning Variant
 
-Use the warning variant for confirmation of destructive actions like deleting or canceling something.
+Use the warning variant to confirm a destructive action, such as deleting or cancelling something.
 
 ```html:preview
 <zn-button id="dialog-warning-trigger">Open Warning Dialog</zn-button>
@@ -94,14 +85,15 @@ Use the warning variant for confirmation of destructive actions like deleting or
   This action cannot be undone. Are you sure you want to delete this item?
 
   <zn-button color="secondary" slot="footer" dialog-closer>Cancel</zn-button>
-  <zn-button color="warning" slot="footer">Delete</zn-button>
+  <zn-button color="error" slot="footer">Delete</zn-button>
 </zn-dialog>
 ```
 
 #### Announcement Variant
 
-Use the announcement variant for special announcements, feature introductions, or welcome messages. This variant
-supports additional slots for intro text and footer text.
+Use the announcement variant for an announcement, a feature introduction or a welcome message. The icon, label and
+body are centred, with the `announcement-intro` slot above the label and the `footer-text` slot below the footer
+buttons. It has no close button, so give it a footer action that closes it.
 
 ```html:preview
 <zn-button id="dialog-announcement-trigger">Open Announcement</zn-button>
@@ -152,12 +144,12 @@ attribute to control the dialog width.
 
 ### Custom Width
 
-You can set a custom dialog width using the `--width` CSS custom property. Note that the dialog will automatically
-shrink to accommodate smaller screens.
+Set `size="custom"` and the `--width` CSS custom property to give the dialog its own width. The size presets set their
+own width, which takes precedence over `--width`. The dialog shrinks to fit smaller screens.
 
 ```html:preview
 <zn-button id="dialog-custom-width-trigger">Open Custom Width Dialog</zn-button>
-<zn-dialog trigger="dialog-custom-width-trigger" label="Custom Width" style="--width: 800px;">
+<zn-dialog trigger="dialog-custom-width-trigger" label="Custom Width" size="custom" style="--width: 800px;">
   <zn-icon src="info" slot="header-icon"></zn-icon>
   This dialog has a custom width of 800px set using the --width CSS property.
 
@@ -202,11 +194,11 @@ is used for screen readers even when visually hidden.
 ```html:preview
 <zn-button id="dialog-no-header-trigger">Open No Header Dialog</zn-button>
 <zn-dialog trigger="dialog-no-header-trigger" label="Dialog without header" no-header>
-  <p>This dialog has no header. Notice there's no close button, so we've added one in the footer.</p>
+  <p>This dialog has no header, so there's no close button. The footer has one instead.</p>
   <p>The label attribute is still required for accessibility, even though it's not visible.</p>
 
-  <zn-button color="default" slot="footer">Continue</zn-button>
   <zn-button color="secondary" slot="footer" dialog-closer>Close</zn-button>
+  <zn-button color="default" slot="footer">Continue</zn-button>
 </zn-dialog>
 ```
 
@@ -229,7 +221,7 @@ Use the `header-actions` slot to add buttons or other interactive elements to th
 
 ### Dialogs as Forms
 
-Use dialogs as forms when you need to collect information from users. This example shows a dialog with a form inside it.
+Place the dialog inside a `<form>` to collect information. A footer button with `type="submit"` submits the form.
 
 ```html:preview
 <form method="post" action="#" style="display: inline-block">
@@ -242,7 +234,7 @@ Use dialogs as forms when you need to collect information from users. This examp
       label-tooltip="This information will be displayed on your public profile"
       help-text="All fields marked with an asterisk are required">
 
-      <div class="form-spacing">
+      <div>
         <zn-input type="text" name="name" label="Name" required></zn-input>
         <zn-select label="Favorite Animal" clearable required>
           <zn-option value="birds">Birds</zn-option>
@@ -255,7 +247,6 @@ Use dialogs as forms when you need to collect information from users. This examp
 
         <zn-checkbox required>I agree to the terms and conditions</zn-checkbox>
 
-        <br>
         <zn-checkbox-group label="Interests" help-text="Select at least one" label-tooltip="Choose your areas of interest"
                            required>
           <zn-checkbox value="technology">Technology</zn-checkbox>
@@ -415,20 +406,20 @@ on its cancel button.
   <zn-icon src="info" slot="header-icon"></zn-icon>
   <p>Any element with the dialog-closer attribute will close this dialog when clicked.</p>
 
-  <zn-button color="default" slot="footer">This Won't Close</zn-button>
   <zn-button color="secondary" slot="footer" dialog-closer>This Will Close</zn-button>
+  <zn-button color="default" slot="footer">This Won't Close</zn-button>
 </zn-dialog>
 ```
 
 ### Cosmic Effect
 
-Add the `cosmic` attribute to apply a special visual effect to the dialog backdrop.
+Add the `cosmic` attribute to draw an animated gradient border around the dialog.
 
 ```html:preview
 <zn-button id="dialog-cosmic-trigger">Open Cosmic Dialog</zn-button>
 <zn-dialog trigger="dialog-cosmic-trigger" label="Cosmic Dialog" cosmic>
   <zn-icon src="star" slot="header-icon"></zn-icon>
-  This dialog has the cosmic effect applied to the backdrop.
+  This dialog has the cosmic border.
 
   <zn-button color="secondary" slot="footer" dialog-closer>Close</zn-button>
 </zn-dialog>
@@ -436,7 +427,8 @@ Add the `cosmic` attribute to apply a special visual effect to the dialog backdr
 
 ### Customizing Spacing
 
-Use CSS custom properties to customize the padding in different areas of the dialog.
+Set `--header-spacing`, `--body-spacing` and `--footer-spacing` on a dialog to change the padding of its header,
+body and footer. To restyle every dialog, a theme sets the `--zn-dialog-*` tokens listed under Custom Properties.
 
 ```html:preview
 <zn-button id="dialog-spacing-trigger">Open Dialog</zn-button>

package/docs/pages/components/diff-row.md

@@ -0,0 +1,28 @@
+---
+meta:
+  title: Diff Row
+  description: One aligned row of a diff, showing the same item in both versions and tinted by how it changed.
+layout: component
+---
+
+```html:preview
+<zn-diff before-caption="Before" after-caption="After">
+  <zn-diff-row caption="Section" heading></zn-diff-row>
+  <zn-diff-row caption="Unchanged">
+    <span slot="before">Same value</span>
+    <span slot="after">Same value</span>
+  </zn-diff-row>
+  <zn-diff-row caption="Changed" change="changed">
+    <span slot="before">Old value</span>
+    <span slot="after">New value</span>
+  </zn-diff-row>
+  <zn-diff-row caption="Added" change="added">
+    <span slot="after">New item</span>
+  </zn-diff-row>
+  <zn-diff-row caption="Removed" change="removed">
+    <span slot="before">Old item</span>
+  </zn-diff-row>
+</zn-diff>
+```
+
+Use `heading` for a row that names the group below it. `change` is `changed`, `added` or `removed`; leave it out for an unchanged item.

package/docs/pages/components/diff.md

@@ -0,0 +1,46 @@
+---
+meta:
+  title: Diff
+  description: Diffs compare two versions side by side, one column each, with every item aligned and tinted by how it changed.
+layout: component
+---
+
+```html:preview
+<zn-diff before-caption="Version 2" before-description="Published 30 Sep 2026"
+         after-caption="Version 3" after-description="Published 12 Oct 2026">
+  <zn-badge slot="after" type="success">Live</zn-badge>
+  <zn-diff-row caption="Settings" heading></zn-diff-row>
+  <zn-diff-row caption="Passing score" change="changed">
+    <span slot="before">75%</span>
+    <span slot="after">80%</span>
+  </zn-diff-row>
+  <zn-diff-row caption="Minimum scorer level">
+    <span slot="before">Senior scorer</span>
+    <span slot="after">Senior scorer</span>
+  </zn-diff-row>
+  <zn-diff-row caption="Resolution" heading></zn-diff-row>
+  <zn-diff-row caption="Was personal data shared correctly?" change="added">
+    <span slot="after">Yes / No · Compliance · score +15</span>
+  </zn-diff-row>
+  <zn-diff-row caption="Thanked the customer" change="removed" after-placeholder="Removed in version 3">
+    <span slot="before">Yes / No · Empathy · score +5</span>
+  </zn-diff-row>
+</zn-diff>
+```
+
+## Examples
+
+### Placeholders
+
+An added item has nothing on the left and a removed item nothing on the right; that side is hatched with a placeholder. Set `before-placeholder` or `after-placeholder` to name the version.
+
+```html:preview
+<zn-diff before-caption="Version 1" after-caption="Version 2">
+  <zn-diff-row caption="Closing tone" change="added" before-placeholder="Not in version 1">
+    <span slot="after">Sad / Neutral / Happy · score +25</span>
+  </zn-diff-row>
+  <zn-diff-row caption="Offered a survey" change="removed" after-placeholder="Removed in version 2">
+    <span slot="before">Yes / No · score +5</span>
+  </zn-diff-row>
+</zn-diff>
+```