@kubex/zinc 1.1.68 → 1.1.70

package/docs/pages/components/collapsible.md

@@ -109,11 +109,15 @@ Use the `count-element` attribute to count specific elements instead of all chil
 
 ### Flush Content
 
-Use the `flush` attribute to remove the left padding/margin from the content area, making it align with the edges.
+Use the `flush` attribute to remove the horizontal padding from both the content
+area and the header, so the caption and the content align with the container's
+edges. This matches `flush` on [`zn-pane`](/components/pane/),
+[`zn-panel`](/components/panel/) and [`zn-tabs`](/components/tabs/), and suits a
+narrow column where an indent wastes width.
 
 ```html:preview
 <zn-collapsible caption="Flush Content"
-                description="No left padding on content"
+                description="No horizontal padding on the header or content"
                 flush>
   <zn-button>This button aligns with the left edge</zn-button>
   <p>Content starts at the container edge</p>

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

@@ -87,6 +87,20 @@ Use the `avatar` library to generate initials from a name.
 <zn-icon-picker name="av" label="Avatar" icon="John Smith" library="avatar" no-color></zn-icon-picker>
 ```
 
+### Upload Image
+
+By default the picker only offers library icons. Add the `allow-upload` attribute to enable a secondary "Upload Image" mode in the dialog, letting users upload an image file instead of picking an icon. Use the `accept` attribute to restrict the accepted file types (defaults to `image/*`).
+
+An uploaded file replaces the icon value: on submit, the file is sent under `name` in place of the icon string — the two are mutually exclusive. The chosen file is also available via the element's `file` property.
+
+```html:preview
+<zn-icon-picker name="logo" label="Logo" allow-upload></zn-icon-picker>
+```
+
+```html:preview
+<zn-icon-picker name="photo" label="Photo (PNG only)" allow-upload accept="image/png"></zn-icon-picker>
+```
+
 ### Help Text
 
 Add descriptive text below the picker with the `help-text` attribute.

package/docs/pages/components/input.md

@@ -136,7 +136,7 @@ the [Properties table](#properties) for the full list of options.
 
 #### Color Input
 
-The color input type displays a clickable color swatch on the left that opens the browser's native color picker. The color value is shown as editable text in the input field, allowing users to either pick a color visually or enter a color value directly.
+The color input type displays a clickable color swatch on the right that opens the browser's native color picker. The color value is shown as editable text in the input field, allowing users to either pick a color visually or enter a color value directly.
 
 Use the `color-format` attribute to specify the format: `hex` (default), `rgb`, or `oklch`.
 
@@ -159,6 +159,24 @@ Use the `color-format` attribute to specify the format: `hex` (default), `rgb`,
 <br />
 ```
 
+#### Range Input
+
+The range input type renders as a bare track with no field chrome. The current value is displayed above the track, on
+the right, and updates as the thumb is dragged. Use `value-suffix` to append a unit to that value, and `min`, `max` and
+`step` to control the range.
+
+```html:preview
+<zn-input type="range" label="Base radius" min="0" max="2" step="0.125" value="0.5" value-suffix="rem"></zn-input>
+<br />
+<zn-input type="range" label="Volume" min="0" max="100" value="70" value-suffix="%">
+  <div slot="help-text">Set <code>context-note</code> to replace the value readout with your own text.</div>
+</zn-input>
+<br />
+<zn-input type="range" label="Small" size="small" min="0" max="10" value="4"></zn-input>
+<br />
+<zn-input type="range" label="Disabled" min="0" max="10" value="4" disabled></zn-input>
+```
+
 #### Other Input Types
 
 ```html:preview

package/docs/pages/components/preview-frame-demo.njk

@@ -9,12 +9,12 @@ permalink: /components/preview-frame-demo/index.html
 ---
 {% raw %}
 <div class="shell">
-  <p id="waiting">Waiting for hp-preview:config…</p>
+  <p id="waiting">Waiting for the host…</p>
 
   <div class="card" id="card" hidden>
     <div class="card__accent"></div>
-    <h2 id="merchant"></h2>
-    <p class="card__amount" id="amount"></p>
+    <h2 id="merchant">Merchant</h2>
+    <p class="card__amount" id="amount">£24.99</p>
     <label>Card number
       <input type="text" placeholder="4242 4242 4242 4242" disabled>
     </label>
@@ -26,7 +26,7 @@ permalink: /components/preview-frame-demo/index.html
         <input type="text" placeholder="123" disabled>
       </label>
     </div>
-    <button id="pay" type="button"></button>
+    <button id="pay" type="button">Pay now</button>
   </div>
 </div>
 
@@ -106,6 +106,16 @@ permalink: /components/preview-frame-demo/index.html
     font-weight: 600;
     cursor: pointer;
   }
+
+  body.is-dark {
+    background: #101014;
+    color: #f4f4f5;
+  }
+
+  body.is-dark .card {
+    background: #18181b;
+    border-color: #33333a;
+  }
 </style>
 
 <script>
@@ -133,6 +143,25 @@ permalink: /components/preview-frame-demo/index.html
     post({type: 'hp-preview:rendered'});
   });
 
+  // The theme half of the protocol: applied independently of the config, so
+  // the editor can push values before any config exists.
+  window.addEventListener('message', e => {
+    const data = e.data;
+    if (data?.type !== 'hp-preview:theme') return;
+
+    const values = data.values || {};
+    document.body.classList.toggle('is-dark', data.mode === 'dark');
+    const card = document.getElementById('card');
+    card.hidden = false;
+    if (values.background) card.style.background = values.background;
+    if (values.accent) card.style.setProperty('--accent', values.accent);
+    if (values.radius !== undefined && values.radius !== '') {
+      card.style.borderRadius = values.radius + 'px';
+    }
+    document.getElementById('waiting').hidden = true;
+    post({type: 'hp-preview:rendered'});
+  });
+
   post({type: 'hp-preview:ready'});
 </script>
 {% endraw %}

package/docs/pages/components/preview-frame.md

@@ -27,6 +27,26 @@ The example below embeds the [demo embed page](/components/preview-frame-demo/),
 
 The frame always fills the panel; `zoom` (0–1, default `1`) zooms the previewed page out browser-style — e.g. `zoom="0.4"` renders the content at 40% size with correspondingly more of the page visible. `min-height` (default `480`) sets the visible panel height in pixels.
 
+Set `fill` to make the panel fill its container's height instead — `min-height` then becomes a floor rather than the height, for hosts (like [`zn-theme-editor`](/components/theme-editor/)) whose layout already stretches the panel to match a taller sibling. `zoom` is ignored when `fill` is set, since its oversize maths needs a known pixel height to scale against, which `fill` deliberately doesn't have.
+
+`device` constrains and centres the preview to `desktop` (full width), `tablet`
+(768px) or `mobile` (390px), resizing the iframe itself so the embedded page's
+media queries fire. `setTheme({mode, values})` posts an `hp-preview:theme` message and
+replays it after each ready handshake, which is how
+[`zn-theme-editor`](/components/theme-editor/) drives a live preview.
+
+The panel behind the preview is a dot grid, so the frame's bounds stay visible
+instead of blending into the page — at `tablet` or `mobile` the dots fill the
+gutters either side of the narrowed iframe. Tune it with
+`--zn-preview-frame-dot-spacing` (default `20px`) and
+`--zn-preview-frame-dot-opacity` (default `0.08`). The iframe itself is given an
+opaque background, so the dots never show through the previewed page.
+
+Set `backdrop="panel"` to swap the dot grid for a plain `rgb(var(--zn-panel))`
+fill — used by [`zn-theme-editor`](/components/theme-editor/)'s `standalone`
+mode, where the frame is already inside its own bordered panel. `backdrop="dots"`
+is the default.
+
 ## Live Form Updates
 
 In a real deployment, editing a watched form auto-saves it and the preview refreshes with the newly saved config. This docs site is static, so the example simulates the save: form changes are encoded into a `data:` payload URI and `refresh()` re-runs the fetch → `hp-preview:config` cycle — the same path a real save triggers.

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

@@ -0,0 +1,303 @@
+---
+meta:
+  title: Theme Editor
+  description: Theme controls on the left, a live preview frame on the right, with light/dark and device switching.
+layout: component
+fullWidth: true
+---
+
+Put form controls in the default slot and give each a `name`. Every control is
+per-mode: it holds a light value and a dark value, and the sidebar's mode
+toggle swaps which one the control displays. Changing a control harvests every
+named control's *currently displayed* value and pushes the active mode's set
+into the embedded [preview frame](/components/preview-frame/) as an
+`hp-preview:theme` message — no save, no fetch, no page reload.
+
+The controls column runs the full height of the component, with its own
+header row on top holding the light/dark mode toggle beside its caption. The
+toolbar sits opposite it, above the preview only, and switches the width the
+preview renders at: desktop (full width), tablet (768px) or mobile (390px).
+Because the iframe itself is resized, the embedded page's own media queries
+fire.
+
+Set `controls-caption` and `preview-caption` to label each column's header
+row — both are empty by default, rendering no text (the controls column's
+header row still renders either way, so the two columns stay aligned).
+
+The preview always fills its column, leaving no dead space beneath it.
+`min-height` (default `480`) is a floor for that column, not a fixed height —
+it's still forwarded to the [preview frame](/components/preview-frame/), which
+uses it the same way.
+
+Controls organize themselves into tabs with collapsible groups inside each:
+give each one a `group` and a `category` and the editor builds the structure
+around them, no slot names required.
+
+```html:preview
+<zn-theme-editor
+  id="theme-editor-demo"
+  src="/components/preview-frame-demo/"
+  min-height="420"
+  controls-caption="Theme Builder"
+  preview-caption="Live Preview">
+  <zn-input group="Colors" category="Brand" name="accent" label="Accent" value="#6936f5" dark-value="#f5c542" type="color"></zn-input>
+  <zn-input group="Colors" category="Background" name="background" label="Background" value="#ffffff" dark-value="#18181b" type="color"></zn-input>
+  <zn-input group="Shapes" category="Radius" name="radius" label="Corner radius" type="number" value="4"></zn-input>
+</zn-theme-editor>
+
+<script>
+  document.getElementById('theme-editor-demo').frameOrigin = location.origin;
+</script>
+```
+
+:::tip
+`frame-origin` must match the embed's origin exactly — messages from any other
+origin are ignored. The example sets it at runtime because the docs site is
+same-origin.
+:::
+
+## Dark values
+
+Give a control a `dark-value` attribute alongside `value` to author its dark
+variant, as `accent` and `background` do above. A control with no
+`dark-value` falls back to its `value` in dark mode, so adding dark support to
+an existing editor is additive:
+
+```html
+<zn-color-select name="accent" label="Accent" value="#6936f5" dark-value="#f5c542"></zn-color-select>
+```
+
+For boolean controls (`zn-checkbox`, `zn-toggle`, `input[type=checkbox]`),
+two separate rules apply depending on whether `dark-value` is present:
+
+- **Present** — parsed as truthy: `dark-value="1"` or `dark-value="true"`
+  seeds the dark state checked, any other value seeds it unchecked.
+- **Absent** — the dark state mirrors the control's own light `checked`
+  state, whatever that is (including `true`), the same fallback rule
+  non-boolean controls get.
+
+## Reading and Persisting Values
+
+Every change emits `zn-theme-change` with `{values, mode, device}`, where
+`values` is `{light, dark}` — both full sets, regardless of which mode is
+active:
+
+```js
+editor.addEventListener('zn-theme-change', event => {
+  console.log(event.detail.values.light, event.detail.values.dark);
+});
+```
+
+Set `action` to persist automatically instead — both sets are POSTed as
+`FormData` on a longer debounce (`save-debounce`, default `1000`ms), with every
+key bracketed by mode: `light[accent]`, `dark[accent]`, `light[radius]`,
+`dark[radius]`. `mode` and `device` are view state and are never saved.
+
+```html
+<zn-theme-editor src="/embed?t=..." frame-origin="https://pay.example" action="/theme/save">
+  <zn-color-select name="accent" label="Accent" value="#6936f5" dark-value="#f5c542"></zn-color-select>
+</zn-theme-editor>
+```
+
+Saves are serialized: if changes land while a POST is in flight, exactly one
+further save runs afterwards with the latest values.
+
+### Manual saving with a submit button
+
+Set `submit-label` to render a built-in save button at the right of the toolbar,
+opposite the device controls —
+empty (the default) renders no button. Add `manual` to disable the debounced
+auto-save entirely, so persistence only happens when the button is clicked;
+the live preview keeps updating on every change either way, only saving
+becomes explicit:
+
+```html
+<zn-theme-editor
+  src="/embed?t=..." frame-origin="https://pay.example"
+  manual
+  submit-label="Save theme">
+  <zn-color-select name="accent" label="Accent" value="#6936f5" dark-value="#f5c542"></zn-color-select>
+</zn-theme-editor>
+```
+
+Clicking the button flushes any pending edit, then saves immediately through
+the same single-slot save queue used for auto-save — it never opens a second
+concurrent request. With `action` set, a successful save emits `zn-theme-submit`
+carrying `{values}` (both `light` and `dark` sets); a failed save surfaces
+through the same error strip and `zn-error` as auto-save. With no `action`,
+nothing is POSTed but `zn-theme-submit` still fires, so a host can persist the
+values itself:
+
+```js
+editor.addEventListener('zn-theme-submit', event => {
+  console.log(event.detail.values.light, event.detail.values.dark);
+});
+```
+
+The button shows a loading state while its save is in flight and ignores
+further clicks until it resolves.
+
+## Controls
+
+Any Zinc form control works. Controls must carry `name` as an **attribute** —
+`zn-checkbox` and `zn-toggle` contribute their `checked` state as a boolean,
+everything else contributes `value`. Disabled and unnamed controls are skipped.
+Every control is per-mode with no opt-in attribute, so mode-independent values
+(like `radius` above) end up duplicated across `light` and `dark` — accepted
+knowingly to keep the rule uniform.
+
+The value store is the theme, not a mirror of the currently visible controls:
+removing a control from the markup keeps its key in both value sets, and it
+keeps being pushed to the preview and included in saves. Clear it server-side
+or re-add the control under the same name to edit it again.
+
+The `footer` slot holds actions beneath the controls:
+
+```html
+<zn-theme-editor src="/embed?t=..." frame-origin="https://pay.example">
+  <zn-color-select name="accent" label="Accent"></zn-color-select>
+  <zn-button slot="footer">Save</zn-button>
+</zn-theme-editor>
+```
+
+Set the controls column width with `--zn-theme-editor-controls-width`
+(default `343px`, matching page-builder's palette). Below 768px the columns
+stack.
+
+## Grouping controls with `group` and `category`
+
+The simplest way to structure an editor is to let the controls describe their
+own place in it. Leave `sections` unset and give each control a `group` (which
+becomes a tab) and a `category` (a collapsible inside that tab) — the editor
+builds the tabs and collapsibles from those labels and slots each control into
+the right one for you, so there are no slot names to keep in sync by hand:
+
+```html
+<zn-theme-editor src="/embed?t=..." frame-origin="https://pay.example">
+  <zn-color-select group="Background &amp; Foreground" category="Colors"
+                   name="background" label="Background" value="#ffffff"></zn-color-select>
+  <zn-color-select group="Background &amp; Foreground" category="Colors"
+                   name="foreground" label="Foreground" value="#18181b"></zn-color-select>
+  <zn-input group="Background &amp; Foreground" category="Spacing"
+            name="gap" label="Gap" type="number" value="8"></zn-input>
+  <zn-input group="Typography" category="Family"
+            name="font" label="Font" value="Inter"></zn-input>
+</zn-theme-editor>
+```
+
+That renders a **Background & Foreground** tab holding *Colors* and *Spacing*
+collapsibles, and a **Typography** tab holding *Family*. Labels are free text —
+they're slugged into slot names internally, and two tabs can each hold a
+category of the same name without colliding.
+
+Either attribute works on its own: a control with only `group` sits directly in
+its tab above any collapsibles, and one with only `category` becomes its own
+top-level section. A control with neither stays in the default slot, ungrouped
+above everything else. Tabs and collapsibles appear in the order the controls
+first mention them, and controls added after mount are derived and slotted the
+same way.
+
+### Declaring the structure explicitly with `sections`
+
+Set `sections` to take full control instead — it disables the attribute
+derivation entirely, and is the way to set a group's `description` or have it
+render `open`. It takes a JSON array of `{name, caption, groups}`. Each section
+becomes a `zn-tabs` tab; each entry in its `groups` — `{name, caption,
+description?, open?}` — becomes a collapsible inside that tab, and a control
+is assigned to a group with `slot="<group-name>"`:
+
+```html
+<zn-theme-editor
+  src="/embed?t=..." frame-origin="https://pay.example"
+  sections='[
+    {"name":"colors","caption":"Colors","groups":[
+      {"name":"brand","caption":"Brand","open":true},
+      {"name":"semantic","caption":"Semantic"}
+    ]},
+    {"name":"shapes","caption":"Shapes","groups":[{"name":"radius","caption":"Radius"}]}
+  ]'>
+  <zn-color-select slot="brand" name="accent" label="Accent" value="#6936f5"></zn-color-select>
+  <zn-input slot="radius" name="radius" label="Corner radius" type="number" value="4"></zn-input>
+</zn-theme-editor>
+```
+
+A group with no assigned controls renders no collapsible, and a section none
+of whose groups are populated renders no tab — the same "no chrome for empty
+config" rule flat sections already followed. Every tab's panel stays mounted
+while hidden (`zn-tabs` toggles visibility, never removes a panel), so
+switching tabs never drops a value out of the theme, a preview push or a save.
+
+The editor never shows a tab with everything shut: on load, and again whenever
+a tab is clicked, its first collapsible expands unless one in that tab is
+already open. `open: true` therefore only matters for picking *which* group
+opens — and closing them all yourself sticks, since nothing reopens until the
+next tab click.
+
+### Flat sections (no groups)
+
+A section can omit `groups` and just take controls directly via
+`slot="<section-name>"`, exactly as before nesting existed. `section-layout`
+then decides the presentation — stacked `zn-collapsible`s (`"collapsible"`,
+the default) or a `zn-tabs` strip (`"tabs"`) — and is otherwise ignored: once
+*any* section has a populated `groups`, every section renders as a nested tab
+regardless of `section-layout`. Stacked sections get the same load-time
+expansion as tabs: the first one opens unless another already has `open`.
+
+```html
+<zn-theme-editor
+  src="/embed?t=..." frame-origin="https://pay.example"
+  section-layout="tabs"
+  sections='[{"name":"colors","caption":"Colors"},{"name":"layout","caption":"Layout"}]'>
+  <zn-color-select slot="colors" name="accent" label="Accent" value="#6936f5"></zn-color-select>
+  <zn-input slot="layout" name="radius" label="Corner radius" type="number" value="4"></zn-input>
+</zn-theme-editor>
+```
+
+An author can also slot their own `zn-collapsible` into any named slot (or the
+default slot) instead of relying on `groups` — its presentation is then
+entirely its own; add `flush` yourself if you want it to run the full width of
+the column.
+
+## Preview sources
+
+Set `sources` to a JSON array of `{label, src}` to render a dropdown in the
+toolbar, beside the device buttons, for switching which page the preview
+loads:
+
+```html
+<zn-theme-editor
+  src="/embed?t=..." frame-origin="https://pay.example"
+  sources='[{"label":"Checkout","src":"/embed/checkout"},{"label":"Storefront","src":"/embed/storefront"}]'>
+  <zn-color-select name="accent" label="Accent" value="#6936f5"></zn-color-select>
+</zn-theme-editor>
+```
+
+The first entry is the initial selection — it wins over an explicit `src` when
+`sources` is non-empty. Selecting a different entry reloads the iframe; nothing
+further is needed to keep the theme, since the frame retains the last pushed
+payload and replays it once the reloaded page re-announces itself ready. Leave
+`sources` unset (the default) and `src` behaves exactly as it always has, with
+no dropdown rendered.
+
+## Collapsing the controls column
+
+Set `controls-collapsed` to hide the controls column, or click the chevron
+toggle that sits on the seam between the columns. Collapsing is purely a
+layout change — it never affects harvested values or pushes a new theme to
+the preview. Below the 768px stacked breakpoint the toggle is hidden, since
+there's no side-by-side seam to tuck into — the editor also un-collapses
+itself if it's already showing `controls-collapsed` when the layout narrows
+that far, so the controls are never stuck unreachable.
+
+## Standalone panel
+
+Set `standalone` to present the editor as its own bordered, rounded panel —
+useful when it isn't already embedded in a page shell that provides that
+chrome. It also switches the preview's [backdrop](/components/preview-frame/)
+from the dot grid to a plain panel to match.
+
+```html
+<zn-theme-editor src="/embed?t=..." frame-origin="https://pay.example" standalone>
+  <zn-color-select name="accent" label="Accent" value="#6936f5" dark-value="#f5c542"></zn-color-select>
+</zn-theme-editor>
+```