@kubex/zinc 1.1.62 → 1.1.63

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

@@ -0,0 +1,4 @@
+{
+  "fail": true,
+  "message": "Example error: the configured theme colour is invalid."
+}

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

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

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

@@ -48,6 +48,18 @@ Add descriptive help text to a form group with the `help-text` attribute. For he
 </zn-form-group>
 ```
 
+### Chip
+
+Use the `chip` slot to display a chip under the form group's help text.
+
+```html:preview
+<zn-form-group label="Team Members" help-text="Manage who has access to this project">
+  <zn-chip slot="chip" type="success">Pro Plan</zn-chip>
+  <zn-input label="Name" placeholder="Team member name"></zn-input>
+  <zn-input label="Email" type="email" placeholder="email@example.com"></zn-input>
+</zn-form-group>
+```
+
 ### Label with Tooltip
 
 Use the `label-tooltip` attribute to add text that appears in a tooltip triggered by an info icon next to the label.

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

@@ -0,0 +1,138 @@
+---
+meta:
+  title: Preview Frame — Demo Embed
+  description: A demo embed page implementing the hp-preview postMessage protocol, for iframing into zn-preview-frame examples.
+layout: full-page
+toc: false
+eleventyExcludeFromCollections: true
+permalink: /components/preview-frame-demo/index.html
+---
+{% raw %}
+<div class="shell">
+  <p id="waiting">Waiting for hp-preview:config…</p>
+
+  <div class="card" id="card" hidden>
+    <div class="card__accent"></div>
+    <h2 id="merchant"></h2>
+    <p class="card__amount" id="amount"></p>
+    <label>Card number
+      <input type="text" placeholder="4242 4242 4242 4242" disabled>
+    </label>
+    <div class="card__row">
+      <label>Expiry
+        <input type="text" placeholder="12/28" disabled>
+      </label>
+      <label>CVC
+        <input type="text" placeholder="123" disabled>
+      </label>
+    </div>
+    <button id="pay" type="button"></button>
+  </div>
+</div>
+
+<style>
+  .shell {
+    height: 100%;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+  }
+
+  #waiting {
+    color: rgb(var(--zn-color-muted-text));
+  }
+
+  .card {
+    --accent: #6936f5;
+    width: 320px;
+    padding: 24px;
+    border: 1px solid rgb(var(--zn-border-color));
+    border-radius: 12px;
+    background: rgb(var(--zn-panel));
+    display: flex;
+    flex-direction: column;
+    gap: 12px;
+  }
+
+  .card__accent {
+    height: 6px;
+    border-radius: 3px;
+    background: var(--accent);
+  }
+
+  .card h2 {
+    margin: 0;
+    font-size: 1.125rem;
+  }
+
+  .card__amount {
+    margin: 0;
+    font-size: 1.75rem;
+    font-weight: 700;
+  }
+
+  .card label {
+    display: flex;
+    flex-direction: column;
+    gap: 4px;
+    font-size: 0.75rem;
+    font-weight: 600;
+  }
+
+  .card input {
+    padding: 8px 10px;
+    border: 1px solid rgb(var(--zn-border-color));
+    border-radius: 6px;
+    font: inherit;
+  }
+
+  .card__row {
+    display: flex;
+    gap: 12px;
+  }
+
+  .card__row label {
+    flex: 1;
+  }
+
+  /* id selector: zn.min.css targets native buttons at higher specificity */
+  .card #pay {
+    padding: 10px;
+    border: 0;
+    border-radius: 6px;
+    background: var(--accent);
+    color: #fff;
+    font: inherit;
+    font-weight: 600;
+    cursor: pointer;
+  }
+</style>
+
+<script>
+  // The embed side of the hp-preview protocol: announce readiness, wait for the
+  // config payload, render it, then report rendered (or error). A real embed
+  // should use the host's origin instead of '*'.
+  const post = message => window.parent.postMessage(message, '*');
+
+  window.addEventListener('message', e => {
+    const data = e.data;
+    if (data?.type !== 'hp-preview:config') return;
+
+    if (data.fail) {
+      post({type: 'hp-preview:error', message: data.message || 'Preview failed to render'});
+      return;
+    }
+
+    document.getElementById('waiting').hidden = true;
+    const card = document.getElementById('card');
+    card.hidden = false;
+    card.style.setProperty('--accent', data.accent || '#6936f5');
+    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'});
+  });
+
+  post({type: 'hp-preview:ready'});
+</script>
+{% endraw %}

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

@@ -0,0 +1,105 @@
+---
+meta:
+  title: Preview Frame
+  description: Embeds a live preview iframe and keeps it in sync with surrounding forms via the hp-preview postMessage protocol.
+layout: component
+---
+
+The frame loads the embed page from `src`, waits for it to post `hp-preview:ready`, fetches the JSON payload from `data-uri` and posts it back into the frame as `hp-preview:config`. The embed then reports `hp-preview:rendered` or `hp-preview:error`.
+
+The example below embeds the [demo embed page](/components/preview-frame-demo/), which implements the embed side of the protocol. `frame-origin` must match the embed's origin exactly — messages from any other origin are ignored — so the example sets it at runtime since the docs demo is same-origin.
+
+```html:preview
+<zn-preview-frame
+  id="preview-frame-demo"
+  src="/components/preview-frame-demo/"
+  data-uri="/data/preview-frame-payload.json"
+  watch="#preview-frame-demo-form"></zn-preview-frame>
+
+<script>
+  document.getElementById('preview-frame-demo').frameOrigin = location.origin;
+</script>
+```
+
+:::tip
+`watch` defaults to `form[data-auto-save]`, so only forms explicitly opted in via a `data-auto-save` attribute are watched — unmarked forms keep normal submit behavior and are never intercepted. Override `watch` with your own selector to widen or change the scope — the examples here point it at a form that doesn't exist. Watched forms are auto-saved via a POST to their `action` on change, which needs a real endpoint, so it isn't demonstrated here.
+:::
+
+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.
+
+## 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.
+
+```html:preview
+<form id="preview-frame-live-form" class="preview-frame-live-form">
+  <zn-input name="merchant" label="Merchant" value="Acme Donuts"></zn-input>
+  <zn-input name="amount" label="Amount" value="£24.99"></zn-input>
+  <zn-input name="buttonLabel" label="Button label" value="Pay £24.99"></zn-input>
+  <label class="preview-frame-live-form__color">Accent
+    <input type="color" name="accent" value="#6936f5">
+  </label>
+</form>
+
+<zn-preview-frame
+  id="preview-frame-live"
+  src="/components/preview-frame-demo/"
+  watch="#preview-frame-live-none"></zn-preview-frame>
+
+<script>
+  customElements.whenDefined('zn-preview-frame').then(() => {
+    const frame = document.getElementById('preview-frame-live');
+    const form = document.getElementById('preview-frame-live-form');
+    frame.frameOrigin = location.origin;
+
+    const update = () => {
+      const payload = Object.fromEntries(new FormData(form));
+      frame.dataUri = 'data:application/json,' + encodeURIComponent(JSON.stringify(payload));
+      frame.refresh();
+    };
+
+    form.addEventListener('zn-input', update);
+    form.addEventListener('input', update);
+    update();
+  });
+</script>
+
+<style>
+  .preview-frame-live-form {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 16px;
+    align-items: flex-end;
+    margin-bottom: 16px;
+  }
+
+  .preview-frame-live-form zn-input {
+    flex: 1;
+    min-width: 140px;
+  }
+
+  .preview-frame-live-form__color {
+    display: flex;
+    flex-direction: column;
+    gap: 4px;
+    font-size: 0.875rem;
+    font-weight: 500;
+  }
+</style>
+```
+
+## Error Overlay
+
+When the embed reports `hp-preview:error` (or fetching the payload fails), the message is shown in an overlay and `zn-error` is emitted. This example uses a payload that asks the demo embed to fail.
+
+```html:preview
+<zn-preview-frame
+  id="preview-frame-demo-error"
+  src="/components/preview-frame-demo/"
+  data-uri="/data/preview-frame-payload-error.json"
+  watch="#preview-frame-demo-error-form"></zn-preview-frame>
+
+<script>
+  document.getElementById('preview-frame-demo-error').frameOrigin = location.origin;
+</script>
+```

package/docs/pages/components/toggle.md

@@ -170,7 +170,7 @@ Toggles support keyboard navigation using arrow keys. Press the left arrow to tu
 
 ### Form Integration
 
-Toggles work seamlessly with forms and will be submitted with form data.
+Toggles work seamlessly with forms and always submit a value: the toggle's `value` (or `on`) when checked, and `off` when unchecked. Use the `fallback` attribute to customize the unchecked value.
 
 ```html:preview
 <form id="toggle-form">
@@ -197,7 +197,7 @@ Toggles work seamlessly with forms and will be submitted with form data.
 
 ### Fallback Value
 
-Use the `fallback` attribute to submit a specific value when the toggle is unchecked. This is useful when you need to ensure a value is always submitted for the field.
+The toggle always submits a value, even when unchecked — `off` by default. Use the `fallback` attribute to submit a specific value instead when the toggle is unchecked.
 
 ```html:preview
 <form id="fallback-form">

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubex/zinc",
-  "version": "1.1.62",
+  "version": "1.1.63",
   "description": "A collection of web components for building web applications based off of @shoelace-style/Shoelace",
   "keywords": [
     "web components",

package/src/components/form-group/form-group.component.ts

@@ -1,7 +1,7 @@
-import {classMap} from "lit/directives/class-map.js";
-import {type CSSResultGroup, html, unsafeCSS} from 'lit';
-import {HasSlotController} from "../../internal/slot";
-import {property} from 'lit/decorators.js';
+import { classMap } from "lit/directives/class-map.js";
+import { type CSSResultGroup, html, unsafeCSS } from 'lit';
+import { HasSlotController } from "../../internal/slot";
+import { property } from 'lit/decorators.js';
 import ZincElement from '../../internal/zinc-element';
 
 import styles from './form-group.scss';
@@ -13,12 +13,13 @@ import styles from './form-group.scss';
  * @since 1.0
  *
  * @slot - The default slot.
+ * @slot chip - A chip displayed under the form group's help text.
  *
  */
 export default class ZnFormGroup extends ZincElement {
   static styles: CSSResultGroup = unsafeCSS(styles);
 
-  private readonly hasSlotController = new HasSlotController(this, 'help-text', 'label');
+  private readonly hasSlotController = new HasSlotController(this, 'help-text', 'label', 'chip');
 
   /**
    * The form group's label. Required for proper accessibility. If you need to display HTML, use the `label` slot
@@ -30,12 +31,14 @@ export default class ZnFormGroup extends ZincElement {
    * Text that appears in a tooltip next to the label. If you need to display HTML in the tooltip, use the
    * `label-tooltip` slot instead.
    */
-  @property({attribute: 'label-tooltip'}) labelTooltip = '';
+  @property({ attribute: 'label-tooltip' }) labelTooltip = '';
 
   /** The form groups help text. If you need to display HTML, use the `help-text` slot instead. */
-  @property({attribute: 'help-text'}) helpText = '';
-  @property({attribute: 'cols', type: Boolean}) forceCols = false;
-  @property({attribute: 'layout', type: String}) layout = "1,2";
+  @property({ attribute: 'help-text' }) helpText = '';
+  @property({ attribute: 'cols', type: Boolean }) forceCols = false;
+  @property({ attribute: 'layout', type: String }) layout = "1,2";
+
+  @property({ attribute: 'pad', type: Boolean }) pad: boolean = false;
 
   render() {
     const hasLabelSlot = this.hasSlotController.test('label');
@@ -44,6 +47,7 @@ export default class ZnFormGroup extends ZincElement {
     const hasLabel = this.label ? true : hasLabelSlot;
     const hasLabelTooltip = this.labelTooltip ? true : hasLabelTooltipSlot;
     const hasHelpText = this.helpText ? true : hasHelpTextSlot;
+    const hasChip = this.hasSlotController.test('chip');
 
     return html`
       <fieldset
@@ -52,14 +56,15 @@ export default class ZnFormGroup extends ZincElement {
           'form-control': true,
           'form-control--has-label': hasLabel,
           'form-control--has-label-tooltip': hasLabelTooltip,
-          'form-control--has-help-text': hasHelpText
+          'form-control--has-help-text': hasHelpText,
+          'form-control--pad': this.pad
         })}"
         aria-labelledby="label"
         aria-describedby="help-text">
 
         <zn-cols layout="${this.layout}" part="form-control-container" class="form-control__container">
-          ${hasLabel || hasHelpText || this.forceCols ? html`
-            <div>
+          ${hasLabel || hasHelpText || hasChip || this.forceCols ? html`
+            <div class="form-control__text">
 
               ${hasLabel ? html`
                 <label
@@ -87,6 +92,13 @@ export default class ZnFormGroup extends ZincElement {
                   <slot name="help-text">${this.helpText}</slot>
                 </div>` : html``}
 
+              ${hasChip ? html`
+                <div
+                  part="form-control-chip"
+                  class="form-control__chip">
+                  <slot name="chip"></slot>
+                </div>` : html``}
+
             </div>` : html``}
 
           <div part="form-control-input" class="form-control-input">

package/src/components/form-group/form-group.scss

@@ -28,6 +28,10 @@
   --zn-col-basis: 200px;
 }
 
+.form-control__chip {
+  margin-top: var(--zn-spacing-x-small);
+}
+
 .visually-hidden {
   position: absolute;
   width: 1px;
@@ -87,3 +91,9 @@
 zn-cols::part(base) {
   gap: 70px;
 }
+
+
+.form-control--pad .form-control__text {
+  padding-top: var(--zn-base-gap);
+  padding-left: var(--zn-base-gap);
+}

package/src/components/form-group/form-group.test.ts

@@ -7,4 +7,23 @@ describe('<zn-form-group>', () => {
 
     expect(el).to.exist;
   });
+
+  it('should render the chip slot under the help text', async () => {
+    const el = await fixture<HTMLElement>(html`
+      <zn-form-group label="Settings" help-text="Configure your settings">
+        <zn-chip slot="chip">New</zn-chip>
+      </zn-form-group>`);
+
+    const helpText = el.shadowRoot!.querySelector('[part="form-control-help-text"]')!;
+    const chip = el.shadowRoot!.querySelector('[part="form-control-chip"]')!;
+
+    expect(chip).to.exist;
+    expect(helpText.nextElementSibling).to.equal(chip);
+  });
+
+  it('should not render the chip container without a chip slot', async () => {
+    const el = await fixture<HTMLElement>(html` <zn-form-group label="Settings"></zn-form-group> `);
+
+    expect(el.shadowRoot!.querySelector('[part="form-control-chip"]')).to.not.exist;
+  });
 });

package/src/components/preview-frame/index.ts

@@ -0,0 +1,12 @@
+import ZnPreviewFrame from './preview-frame.component';
+
+export * from './preview-frame.component';
+export default ZnPreviewFrame;
+
+ZnPreviewFrame.define('zn-preview-frame');
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'zn-preview-frame': ZnPreviewFrame;
+  }
+}