@kubex/zinc 1.1.72 → 1.1.74

package/docs/data/preview-frame-payload-tall.json

@@ -0,0 +1,7 @@
+{
+  "merchant": "Acme Donuts",
+  "amount": "£24.99",
+  "accent": "#6936f5",
+  "buttonLabel": "Pay £24.99",
+  "lines": 16
+}

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

@@ -26,6 +26,7 @@ permalink: /components/preview-frame-demo/index.html
         <input type="text" placeholder="123" disabled>
       </label>
     </div>
+    <div class="card__lines" id="lines"></div>
     <button id="pay" type="button">Pay now</button>
   </div>
 </div>
@@ -38,6 +39,13 @@ permalink: /components/preview-frame-demo/index.html
     justify-content: center;
   }
 
+  /* A page taller than the frame: top-aligned, or the overflow clips the top. */
+  .shell--tall {
+    height: auto;
+    align-items: flex-start;
+    padding: 24px 0;
+  }
+
   #waiting {
     color: rgb(var(--zn-color-muted-text));
   }
@@ -91,6 +99,20 @@ permalink: /components/preview-frame-demo/index.html
     gap: 12px;
   }
 
+  .card__lines:not(:empty) {
+    display: flex;
+    flex-direction: column;
+    gap: 8px;
+    font-size: 0.8125rem;
+  }
+
+  .card__line {
+    display: flex;
+    justify-content: space-between;
+    padding-bottom: 8px;
+    border-bottom: 1px solid rgb(var(--zn-border-color));
+  }
+
   .card__row label {
     flex: 1;
   }
@@ -124,6 +146,26 @@ permalink: /components/preview-frame-demo/index.html
   // should use the host's origin instead of '*'.
   const post = message => window.parent.postMessage(message, '*');
 
+  // Reporting a height lets the host grow the frame to fit, so an overflowing
+  // page is scrolled by the panel instead of inside the frame. Measured after a
+  // frame so the layout has settled.
+  const postRendered = () => requestAnimationFrame(() => post({
+    type: 'hp-preview:rendered',
+    height: document.documentElement.scrollHeight
+  }));
+
+  const renderLines = count => {
+    const lines = document.getElementById('lines');
+    lines.innerHTML = '';
+    document.querySelector('.shell').classList.toggle('shell--tall', count > 0);
+    for (let i = 1; i <= count; i++) {
+      const line = document.createElement('div');
+      line.className = 'card__line';
+      line.innerHTML = `<span>Line item ${i}</span><span>£${(i * 1.5).toFixed(2)}</span>`;
+      lines.append(line);
+    }
+  };
+
   window.addEventListener('message', e => {
     const data = e.data;
     if (data?.type !== 'hp-preview:config') return;
@@ -140,7 +182,8 @@ permalink: /components/preview-frame-demo/index.html
     document.getElementById('merchant').textContent = data.merchant || 'Merchant';
     document.getElementById('amount').textContent = data.amount || '';
     document.getElementById('pay').textContent = data.buttonLabel || 'Pay now';
-    post({type: 'hp-preview:rendered'});
+    renderLines(Number(data.lines) || 0);
+    postRendered();
   });
 
   // The theme half of the protocol: applied independently of the config, so
@@ -159,7 +202,7 @@ permalink: /components/preview-frame-demo/index.html
       card.style.borderRadius = values.radius + 'px';
     }
     document.getElementById('waiting').hidden = true;
-    post({type: 'hp-preview:rendered'});
+    postRendered();
   });
 
   post({type: 'hp-preview:ready'});

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

@@ -47,6 +47,85 @@ 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.
 
+## Interactivity
+
+The preview is display-only: the iframe takes `pointer-events: none`, so clicks
+never reach the embedded page and the previewed form can't be submitted or
+navigated away from inside the frame. The embed is cross-origin, so its own
+handlers can't be cancelled from out here — blocking pointer input is the only
+way to stop them, and hover goes with it. Scrolling doesn't: an overflowing page
+is scrolled by the panel instead, as below.
+
+Set `interactive` when the embed is meant to be used rather than looked at.
+
+```html:preview
+<zn-preview-frame
+  id="preview-frame-interactive"
+  src="/components/preview-frame-demo/"
+  data-uri="/data/preview-frame-payload.json"
+  watch="#preview-frame-interactive-none"
+  interactive></zn-preview-frame>
+
+<script>
+  document.getElementById('preview-frame-interactive').frameOrigin = location.origin;
+</script>
+```
+
+## Overflowing Content
+
+A page taller than the panel is scrolled by the panel, not inside the frame. The
+frame can't do it itself: a cross-origin document can't be scrolled from the host
+(`contentWindow.scrollTo` is blocked), and with pointer input off the wheel never
+reaches it anyway. So the frame is instead laid out at its full content height —
+nothing scrolls inside it — and the panel scrolls that.
+
+For the frame to be sized that way, the embed reports its height alongside
+`hp-preview:rendered`:
+
+```js
+post({
+  type: 'hp-preview:rendered',
+  height: document.documentElement.scrollHeight
+});
+```
+
+A page that grows after its first render — a revealed section, a lazy-loaded
+image — reports the new height on its own:
+
+```js
+post({type: 'hp-preview:height', height: document.documentElement.scrollHeight});
+```
+
+Heights that aren't a positive number are ignored, as is one reported while the
+error overlay is up. A height under the panel's own is kept but changes nothing:
+the frame still fills the panel, so the backdrop never shows under a short page.
+The height is dropped whenever `src` changes, since the next page has its own.
+
+The example below previews a long itemised page, so the panel scrolls. Scrolling
+works with the frame inert — clicking `Pay` still does nothing.
+
+```html:preview
+<zn-preview-frame
+  id="preview-frame-tall"
+  src="/components/preview-frame-demo/"
+  data-uri="/data/preview-frame-payload-tall.json"
+  watch="#preview-frame-tall-none"></zn-preview-frame>
+
+<script>
+  document.getElementById('preview-frame-tall').frameOrigin = location.origin;
+</script>
+```
+
+:::tip
+A **same-origin** embed doesn't need to report anything — its document is
+measured directly. The measurement only ever grows the frame: the frame's own
+height feeds back into it, so a value at or under the current height is ignored
+rather than flipping the frame between two sizes forever. An embed that shrinks
+has to report its height to be followed back down, and one whose root is sized
+to the viewport (`html {height: 100%}`) can't be measured at all — it reports or
+it clips.
+:::
+
 ## 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/tabs.md

@@ -200,8 +200,15 @@ Use the `active` attribute to specify which tab should be active by default.
 
 ### Storage Persistence
 
-Use `store-key` to persist the active tab selection across page reloads. By default, uses session storage with a
-5-minute TTL. Use `local-storage` for persistent storage beyond the session.
+Use `store-key` to persist the active tab selection.
+
+Each tab you open becomes its own history entry, so Back and Forward step through the tabs you visited before leaving the
+page, and the entry the page was first rendered on returns you to the default tab. Reloading restores the tab you were
+on. Navigating to the page — including a client-side navigation back to somewhere visited earlier — starts from the
+default tab.
+
+Selections are held in session storage, keyed by location. Use `local-storage` when a selection should survive fresh
+navigation and browser sessions; it is then keyed by `store-key` alone and takes no part in history.
 
 ```html:preview
 <zn-tabs flush store-key="my-tabs">

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubex/zinc",
-  "version": "1.1.72",
+  "version": "1.1.74",
   "description": "A collection of web components for building web applications based off of @shoelace-style/Shoelace",
   "keywords": [
     "web components",
@@ -82,7 +82,6 @@
     "custom-element-vuejs-integration": "^1.4.0",
     "del": "^8.0.0",
     "esbuild": "^0.27.7",
-    "esbuild-plugin-replace": "^1.4.0",
     "esbuild-sass-plugin": "^3.7.0",
     "eslint": "^8.57.1",
     "eslint-plugin-chai-expect": "^3.1.0",

package/scripts/build.js

@@ -9,7 +9,6 @@ import * as path from 'path';
 import chalk from 'chalk';
 import fs from 'fs/promises';
 import {readFileSync} from 'fs';
-import {replace} from 'esbuild-plugin-replace';
 import {sassPlugin} from 'esbuild-sass-plugin';
 import getPort, {portNumbers} from 'get-port';
 import postCSS from 'postcss';
@@ -144,7 +143,11 @@ async function buildTheSource()
     entryPoints,
     define:    {
       // Floating UI requires this to be set
-      'process.env.NODE_ENV': '"production"'
+      'process.env.NODE_ENV': '"production"',
+      // Substituted natively by esbuild. Don't move this to an onLoad-based replace plugin: those
+      // read every module in the graph from Node with no concurrency cap, which exhausts the file
+      // table (ENFILE) once deps with thousands of modules (echarts, lucide) are bundled.
+      __ZINC_VERSION__:       zincVersion
     },
     bundle:    true,
     splitting: true,
@@ -165,9 +168,6 @@ async function buildTheSource()
             console.error(err);
           }
         }
-      }),
-      replace({
-        __ZINC_VERSION__: zincVersion
       })
     ]
   };

package/src/components/defined-label/defined-label.component.ts

@@ -149,21 +149,15 @@ export default class ZnDefinedLabel extends ZincElement implements ZincFormContr
   private handleInputValueChange(e: Event) {
     const target = e.target as HTMLInputElement | HTMLSelectElement;
     this.inputValue = target.value.toLowerCase();
-
-    if (target.hasAttribute('data-label')) this.value = target.getAttribute('data-label') ?? "";
   }
 
-  private handleFormSubmit(e: Event, label?: string) {
-    // Sync from the submitted row so a partially typed filter never wins over
-    // the row's actual label key, and stale values from other rows are discarded
+  private handleFormSubmit(e: Event, label: string) {
+    // Submit the key shown on the clicked row — a predefined name, or the typed
+    // key for the custom row — and discard values left behind on other rows
     const row = (e.currentTarget as HTMLElement).closest('.defined-label__row');
     const control = row?.querySelector<ZnInput | ZnSelect>('.defined-label__value');
-    if (label) {
-      this.value = label;
-    }
-    if (control) {
-      this.inputValue = String(control.value ?? '').toLowerCase();
-    }
+    this.value = label;
+    this.inputValue = control ? String(control.value ?? '').toLowerCase() : '';
 
     const form = this.formControlController.getForm();
 
@@ -181,7 +175,6 @@ export default class ZnDefinedLabel extends ZincElement implements ZincFormContr
         <zn-select
           part="input-value"
           class="defined-label__value"
-          data-label="${label.name}"
           size="small"
           @zn-change="${this.handleInputValueChange}"
           @zn-input="${this.handleInputValueChange}">
@@ -197,16 +190,15 @@ export default class ZnDefinedLabel extends ZincElement implements ZincFormContr
         class="defined-label__value"
         type="text"
         placeholder="Label Value"
-        data-label="${label.name}"
         size="small"
         @zn-change="${this.handleInputValueChange}"
         @zn-input="${this.handleInputValueChange}"></zn-input>`;
   }
 
-  private renderRow(name: string, control: TemplateResult, label?: string): TemplateResult {
+  private renderRow(label: string, control: TemplateResult): TemplateResult {
     return html`
       <div class="defined-label__row">
-        <small class="defined-label__row-label">${name}</small>
+        <small class="defined-label__row-label">${label}</small>
         <div class="defined-label__row-controls">
           ${control}
           <zn-button
@@ -219,6 +211,7 @@ export default class ZnDefinedLabel extends ZincElement implements ZincFormContr
 
   render() {
     const labels = this.getFilteredLabels();
+    const showCustom = this.allowCustom && this.value !== '' && !labels.some(label => label.name === this.value);
 
     return html`
       <zn-dropdown class="defined-label__dropdown" sync="width">
@@ -243,11 +236,11 @@ export default class ZnDefinedLabel extends ZincElement implements ZincFormContr
 
         <div class="defined-label__panel">
           ${labels.length > 0
-            ? labels.map(label => this.renderRow(label.name, this.renderValueControl(label), label.name))
+            ? labels.map(label => this.renderRow(label.name, this.renderValueControl(label)))
             : html`
               <div class="defined-label__empty">Cannot find any predefined labels</div>`}
 
-          ${this.allowCustom && this.value !== '' ? this.renderRow(this.value, html`
+          ${showCustom ? this.renderRow(this.value, html`
             <zn-input
               part="input-value"
               class="defined-label__value"

package/src/components/defined-label/defined-label.test.ts

@@ -1,5 +1,55 @@
 import '../../../dist/zn.min.js';
-import { expect, fixture, html } from '@open-wc/testing';
+import { expect, fixture, html, waitUntil } from '@open-wc/testing';
+import type ZnDefinedLabel from './defined-label.component';
+
+const predefined = [
+  { name: 'outbound', options: [] },
+  { name: 'another', options: ['one', 'two'] }
+];
+
+async function fixtureWithForm() {
+  const form: HTMLFormElement = await fixture(html`
+    <form>
+      <zn-defined-label allow-custom name="label" .predefinedLabels="${predefined}"></zn-defined-label>
+    </form>`);
+
+  const el = form.querySelector<ZnDefinedLabel>('zn-defined-label')!;
+  await el.updateComplete;
+
+  const submissions: string[] = [];
+  form.addEventListener('submit', event => {
+    event.preventDefault();
+    submissions.push([...new FormData(form).entries()].map(([key, value]) => `${key}=${String(value)}`).join('&'));
+  });
+
+  return { el, submissions };
+}
+
+async function type(el: ZnDefinedLabel, control: Element, text: string) {
+  const native = control.shadowRoot!.querySelector('input')!;
+  native.focus();
+
+  for (const character of text) {
+    native.value += character;
+    native.dispatchEvent(new InputEvent('input', { bubbles: true, composed: true }));
+    await el.updateComplete;
+  }
+}
+
+function rows(el: ZnDefinedLabel) {
+  return [...(el.shadowRoot?.querySelectorAll('.defined-label__row') ?? [])];
+}
+
+function rowLabels(el: ZnDefinedLabel) {
+  return rows(el).map(row => row.querySelector('.defined-label__row-label')?.textContent);
+}
+
+async function clickAdd(row: Element, submissions: string[]) {
+  const button = row.querySelector('zn-button')!.shadowRoot!.querySelector('button')!;
+  button.dispatchEvent(new MouseEvent('mousedown', { bubbles: true, composed: true }));
+  button.dispatchEvent(new MouseEvent('click', { bubbles: true, composed: true }));
+  await waitUntil(() => submissions.length > 0, 'the form never submitted');
+}
 
 describe('<zn-defined-label>', () => {
   it('should render a component', async () => {
@@ -7,4 +57,60 @@ describe('<zn-defined-label>', () => {
 
     expect(el).to.exist;
   });
+
+  it('should offer a custom row alongside partially matching predefined labels', async () => {
+    const { el } = await fixtureWithForm();
+
+    await type(el, el.input, 'out');
+
+    expect(rowLabels(el)).to.eql(['outbound', 'out']);
+  });
+
+  it('should keep the typed key when a value is entered on a partially matching predefined row', async () => {
+    const { el } = await fixtureWithForm();
+
+    await type(el, el.input, 'out');
+    await type(el, rows(el)[0].querySelector('.defined-label__value')!, 'x');
+
+    expect(el.value).to.equal('out');
+    expect(rowLabels(el)).to.eql(['outbound', 'out']);
+  });
+
+  it('should submit the typed key from the custom row, not a partially matching predefined label', async () => {
+    const { el, submissions } = await fixtureWithForm();
+
+    await type(el, el.input, 'out');
+    await type(el, rows(el)[1].querySelector('.defined-label__value')!, 'bob');
+    await clickAdd(rows(el)[1], submissions);
+
+    expect(submissions[0]).to.equal('label=out:bob');
+  });
+
+  it('should submit the predefined key when its own row is added', async () => {
+    const { el, submissions } = await fixtureWithForm();
+
+    await type(el, el.input, 'out');
+    await type(el, rows(el)[0].querySelector('.defined-label__value')!, 'x');
+    await clickAdd(rows(el)[0], submissions);
+
+    expect(submissions[0]).to.equal('label=outbound:x');
+  });
+
+  it('should discard a value left on another row', async () => {
+    const { el, submissions } = await fixtureWithForm();
+
+    await type(el, el.input, 'out');
+    await type(el, rows(el)[0].querySelector('.defined-label__value')!, 'x');
+    await clickAdd(rows(el)[1], submissions);
+
+    expect(submissions[0]).to.equal('label=out');
+  });
+
+  it('should not duplicate a predefined label as a custom row', async () => {
+    const { el } = await fixtureWithForm();
+
+    await type(el, el.input, 'outbound');
+
+    expect(rowLabels(el)).to.eql(['outbound']);
+  });
 });

package/src/components/icon-picker/icon-picker.component.ts

@@ -300,6 +300,13 @@ export default class ZnIconPicker extends ZincElement implements ZincFormControl
     this.openDialog();
   }
 
+  private _handleTriggerKeyDown(e: KeyboardEvent) {
+    if (e.key === 'Enter' || e.key === ' ') {
+      e.preventDefault();
+      this._handleTriggerClick();
+    }
+  }
+
   render() {
     const hasLabel = !!this.label;
     const hasHelpText = !!this.helpText;
@@ -320,27 +327,51 @@ export default class ZnIconPicker extends ZincElement implements ZincFormControl
         </label>
 
         <div part="form-control-input" class="form-control-input">
-          <zn-button
-            part="trigger"
-            class="icon-picker__trigger"
-            panel-bg
-            icon=${hasValue ? triggerIcon : nothing}
-            icon-library=${triggerLibrary}
-            icon-color=${(hasValue && !this.isImageValue && this.color) || nothing}
-            icon-size="24"
-            ?disabled=${this.disabled}
-            @click=${this._handleTriggerClick}>
-            ${hasValue ? 'Click to edit' : 'Set an icon'}
-          </zn-button>
-          ${hasValue ? html`
+          ${hasValue && this.isImageValue ? html`
+            <div
+              part="trigger"
+              class="icon-picker__image-trigger"
+              role="button"
+              aria-label="Click to edit"
+              tabindex=${this.disabled ? '-1' : '0'}
+              @click=${this._handleTriggerClick}
+              @keydown=${this._handleTriggerKeyDown}>
+              <zn-button
+                class="icon-picker__image-clear"
+                color="default"
+                outline
+                icon="close"
+                icon-size="18"
+                ?disabled=${this.disabled}
+                @click="${this.handleClear}"
+              ></zn-button>
+              <div class="icon-picker__image-trigger-background">
+                <img class="icon-picker__image-trigger-preview" src=${triggerIcon} alt="">
+              </div>
+            </div>
+          ` : html`
             <zn-button
-              class="icon-picker__clear"
-              color="transparent"
-              icon="close"
-              icon-size="16"
-              @click="${this.handleClear}"
-            ></zn-button>
-          ` : nothing}
+              part="trigger"
+              class="icon-picker__trigger"
+              panel-bg
+              icon=${hasValue ? triggerIcon : nothing}
+              icon-library=${triggerLibrary}
+              icon-color=${(hasValue && this.color) || nothing}
+              icon-size="24"
+              ?disabled=${this.disabled}
+              @click=${this._handleTriggerClick}>
+              ${hasValue ? 'Click to edit' : 'Set an icon'}
+            </zn-button>
+            ${hasValue ? html`
+              <zn-button
+                class="icon-picker__clear"
+                color="transparent"
+                icon="close"
+                icon-size="16"
+                @click="${this.handleClear}"
+              ></zn-button>
+            ` : nothing}
+          `}
         </div>
 
         ${this.name ? html`

package/src/components/icon-picker/icon-picker.scss

@@ -16,6 +16,77 @@ zn-dialog {
   --icon-color: rgb(var(--zn-text));
 }
 
+// Mirrors zn-file's droparea preview so a chosen image reads the same as an
+// uploaded file.
+.icon-picker__image-trigger {
+  position: relative;
+  flex: 1;
+  min-width: 0;
+  min-height: 180px;
+  border: 1px solid var(--zn-input-border-color);
+  border-radius: var(--zn-border-radius);
+  cursor: pointer;
+  transition: var(--zn-transition-medium) background,
+    var(--zn-transition-medium) border-color;
+
+  &:focus-visible {
+    border-color: var(--zn-color-primary-600);
+    outline: var(--zn-focus-ring);
+    outline-offset: var(--zn-focus-ring-offset);
+  }
+
+  &:not(:focus-visible):hover {
+    border-color: var(--zn-color-primary-700);
+  }
+}
+
+:host([disabled]) .icon-picker__image-trigger {
+  cursor: not-allowed;
+  opacity: 0.5;
+}
+
+.icon-picker__image-trigger-background {
+  --zn-droparea-checker-size: 12px;
+  --zn-droparea-checker-a: var(--zn-color-neutral-50);
+  --zn-droparea-checker-b: var(--zn-color-neutral-100);
+
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 100%;
+  height: 100%;
+  min-height: inherit;
+  padding: var(--zn-spacing-large) var(--zn-spacing-medium);
+  box-sizing: border-box;
+  background-color: var(--zn-droparea-checker-a);
+  background-image:
+    linear-gradient(45deg, var(--zn-droparea-checker-b) 25%, transparent 25%),
+    linear-gradient(-45deg, var(--zn-droparea-checker-b) 25%, transparent 25%),
+    linear-gradient(45deg, transparent 75%, var(--zn-droparea-checker-b) 75%),
+    linear-gradient(-45deg, transparent 75%, var(--zn-droparea-checker-b) 75%);
+  background-size: var(--zn-droparea-checker-size) var(--zn-droparea-checker-size);
+  background-position:
+    0 0,
+    0 calc(var(--zn-droparea-checker-size) / 2),
+    calc(var(--zn-droparea-checker-size) / 2) calc(var(--zn-droparea-checker-size) / -2),
+    calc(var(--zn-droparea-checker-size) / -2) 0;
+  border-radius: calc(var(--zn-border-radius) - 1px);
+}
+
+.icon-picker__image-trigger-preview {
+  display: block;
+  width: 100%;
+  height: 150px;
+  object-fit: contain;
+}
+
+.icon-picker__image-clear {
+  position: absolute;
+  top: var(--zn-spacing-small);
+  right: var(--zn-spacing-small);
+  z-index: 1;
+}
+
 .icon-picker__dialog-layout {
   display: flex;
   gap: var(--zn-spacing-large);