@kubex/zinc 1.1.62 → 1.1.63

package/dist/web-types.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://raw.githubusercontent.com/JetBrains/web-types/master/schema/web-types.json",
   "name": "@kubex/zinc",
-  "version": "1.1.62",
+  "version": "1.1.63",
   "description-markup": "markdown",
   "contributions": {
     "html": {
@@ -4084,7 +4084,7 @@
         },
         {
           "name": "zn-form-group",
-          "description": "Short summary of the component's intended use.\n---\n\n\n### **Slots:**\n - _default_ - The default slot.",
+          "description": "Short summary of the component's intended use.\n---\n\n\n### **Slots:**\n - _default_ - The default slot.\n- **chip** - A chip displayed under the form group's help text.",
           "doc-url": "",
           "attributes": [
             {
@@ -4109,9 +4109,19 @@
             {
               "name": "layout",
               "value": { "type": "string", "default": "\"1,2\"" }
+            },
+            {
+              "name": "pad",
+              "value": { "type": "boolean", "default": "false" }
+            }
+          ],
+          "slots": [
+            { "name": "", "description": "The default slot." },
+            {
+              "name": "chip",
+              "description": "A chip displayed under the form group's help text."
             }
           ],
-          "slots": [{ "name": "", "description": "The default slot." }],
           "events": [],
           "js": {
             "properties": [
@@ -4131,7 +4141,8 @@
                 "type": "string"
               },
               { "name": "forceCols", "type": "boolean" },
-              { "name": "layout", "type": "string" }
+              { "name": "layout", "type": "string" },
+              { "name": "pad", "type": "boolean" }
             ],
             "events": []
           }
@@ -6789,6 +6800,100 @@
             ]
           }
         },
+        {
+          "name": "zn-preview-frame",
+          "description": "Embeds a live preview iframe and drives the hp-preview postMessage\nprotocol: answers the frame's ready handshake with a config payload fetched\nfrom data-uri, auto-saves watched forms on change, and refreshes the\npreview after each save.\n---\n\n\n### **Events:**\n - **zn-error** - Emitted when the preview reports a render error or a save fails.\n\n### **Methods:**\n - **refresh()** - Re-fetches the payload and pushes a fresh config to the preview.\n\n### **CSS Parts:**\n - **base** - The component's base wrapper.\n- **iframe** - The preview iframe.\n- **error** - The error overlay.",
+          "doc-url": "",
+          "attributes": [
+            {
+              "name": "src",
+              "description": "URL of the preview shell page (tokened embed URL).",
+              "value": { "type": "string", "default": "''" }
+            },
+            {
+              "name": "frame-origin",
+              "description": "Expected origin of the iframe; all postMessage traffic is checked against it.",
+              "value": { "type": "string", "default": "''" }
+            },
+            {
+              "name": "data-uri",
+              "description": "Endpoint returning the hp-preview:config payload JSON. The console proxy rewrites this attribute to an app-prefixed path for proper fetch resolution.",
+              "value": { "type": "string", "default": "''" }
+            },
+            {
+              "name": "watch",
+              "description": "Selector (resolved against the component's root node) for the forms to watch.\nDefaults to only forms explicitly opted in via a `data-auto-save` attribute —\nunmarked forms keep normal submit behavior and are never intercepted,\nauto-saved, or used to trigger a preview refresh. Override to widen the scope.",
+              "value": { "type": "string", "default": "'form[data-auto-save]'" }
+            },
+            {
+              "name": "debounce",
+              "description": "Debounce in ms between a form change and its auto-save.",
+              "value": { "type": "number", "default": "400" }
+            },
+            {
+              "name": "zoom",
+              "description": "Zooms the previewed page out (0–1]. The frame always fills the panel;\nzoom shrinks the content browser-style, so 0.4 shows the page at 40%\nsize with correspondingly more of it visible. 1 = natural size.",
+              "value": { "type": "number", "default": "1" }
+            },
+            {
+              "name": "min-height",
+              "description": "The visible height (in CSS pixels) of the preview panel. Fixed rather\nthan measured, because a measured height would feed back into the\nscaled iframe's layout box and grow unbounded.",
+              "value": { "type": "number", "default": "480" }
+            }
+          ],
+          "events": [
+            {
+              "name": "zn-error",
+              "description": "Emitted when the preview reports a render error or a save fails."
+            }
+          ],
+          "js": {
+            "properties": [
+              {
+                "name": "src",
+                "description": "URL of the preview shell page (tokened embed URL).",
+                "type": "string"
+              },
+              {
+                "name": "frameOrigin",
+                "description": "Expected origin of the iframe; all postMessage traffic is checked against it.",
+                "type": "string"
+              },
+              {
+                "name": "dataUri",
+                "description": "Endpoint returning the hp-preview:config payload JSON. The console proxy rewrites this attribute to an app-prefixed path for proper fetch resolution.",
+                "type": "string"
+              },
+              {
+                "name": "watch",
+                "description": "Selector (resolved against the component's root node) for the forms to watch.\nDefaults to only forms explicitly opted in via a `data-auto-save` attribute —\nunmarked forms keep normal submit behavior and are never intercepted,\nauto-saved, or used to trigger a preview refresh. Override to widen the scope.",
+                "type": "string"
+              },
+              {
+                "name": "debounce",
+                "description": "Debounce in ms between a form change and its auto-save.",
+                "type": "number"
+              },
+              {
+                "name": "zoom",
+                "description": "Zooms the previewed page out (0–1]. The frame always fills the panel;\nzoom shrinks the content browser-style, so 0.4 shows the page at 40%\nsize with correspondingly more of it visible. 1 = natural size.",
+                "type": "number"
+              },
+              {
+                "name": "minHeight",
+                "description": "The visible height (in CSS pixels) of the preview panel. Fixed rather\nthan measured, because a measured height would feed back into the\nscaled iframe's layout box and grow unbounded.",
+                "type": "number"
+              },
+              { "name": "frame", "type": "HTMLIFrameElement" }
+            ],
+            "events": [
+              {
+                "name": "zn-error",
+                "description": "Emitted when the preview reports a render error or a save fails."
+              }
+            ]
+          }
+        },
         {
           "name": "zn-priority-list",
           "description": "A reorderable list where each item receives a numerical priority based on its position. Supports drag-and-drop\nand keyboard reordering. Priority values are submitted as form data via hidden inputs.\n---\n\n\n### **Events:**\n - **zn-change** - Emitted when the order of items changes.\n- **zn-reorder** - Emitted when items are reordered. Call `getPriorityMap()` on the component to get the updated `{ key: string, priority: number }[]` array.\n\n### **Methods:**\n - **getPriorityMap(): _PriorityItem[]_** - Returns the priority map: an array of { key, priority } objects.\n- **checkValidity(): _boolean_** - Checks for validity but does not show a validation message.\n- **getForm(): _HTMLFormElement | null_** - Gets the associated form, if one exists.\n- **reportValidity(): _boolean_** - Checks for validity and shows the browser's validation message if the control is invalid.\n- **setCustomValidity(_message)** - Sets a custom validation message. Pass an empty string to restore validity.\n\n### **Slots:**\n - _default_ - The default slot where list items are placed. Each slotted element must have a `value` attribute that uniquely identifies the item. The component automatically assigns slot names to project each item into the correct position. The item's position in the list determines its priority (top = `priority-start`, incrementing).\n- **label** - The component's label. Required for proper accessibility. Alternatively, use the `label` attribute.\n- **label-tooltip** - Used to add text displayed in a tooltip next to the label.\n- **help-text** - Text that describes how to use the component. Alternatively, use the `help-text` attribute.\n\n### **CSS Properties:**\n - **--zn-priority-list-item-gap** - The gap between list items. Defaults to `var(--zn-spacing-2x-small)`. _(default: undefined)_\n- **--zn-priority-list-item-padding** - The padding inside each item. Defaults to `var(--zn-spacing-small) var(--zn-spacing-medium)`. _(default: undefined)_\n- **--zn-priority-list-handle-color** - The color of the drag handle. Defaults to `var(--zn-color-neutral-500)`. _(default: undefined)_\n- **--zn-priority-list-priority-color** - The color of the priority number. Defaults to `var(--zn-color-neutral-600)`. _(default: undefined)_\n\n### **CSS Parts:**\n - **form-control** - The form control wrapper.\n- **form-control-label** - The label wrapper.\n- **form-control-input** - The input area wrapper.\n- **form-control-help-text** - The help text wrapper.\n- **list** - The list container.\n- **item** - An individual list item row.\n- **drag-handle** - The drag handle icon.\n- **priority** - The priority number badge.\n- **content** - The content area of an item.",
@@ -9574,7 +9679,8 @@
             { "name": "value", "value": { "type": "string" } },
             {
               "name": "fallback",
-              "value": { "type": "string", "default": "''" }
+              "description": "The value submitted when the toggle is unchecked, so the toggle always submits a value.",
+              "value": { "type": "string", "default": "'off'" }
             },
             {
               "name": "size",
@@ -9654,7 +9760,11 @@
               { "name": "title", "type": "string" },
               { "name": "name", "type": "string" },
               { "name": "value", "type": "string" },
-              { "name": "fallbackValue", "type": "string" },
+              {
+                "name": "fallbackValue",
+                "description": "The value submitted when the toggle is unchecked, so the toggle always submits a value.",
+                "type": "string"
+              },
               { "name": "size", "type": "'small' | 'medium' | 'large'" },
               { "name": "disabled", "type": "boolean" },
               { "name": "checked", "type": "boolean" },

package/dist/zn.d.ts

@@ -1327,6 +1327,7 @@ declare module "components/toggle/toggle.component" {
         title: string;
         name: string;
         value: string;
+        /** The value submitted when the toggle is unchecked, so the toggle always submits a value. */
         fallbackValue: string;
         size: 'small' | 'medium' | 'large';
         disabled: boolean;
@@ -6572,6 +6573,7 @@ declare module "components/form-group/form-group.component" {
      * @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 {
@@ -6591,6 +6593,7 @@ declare module "components/form-group/form-group.component" {
         helpText: string;
         forceCols: boolean;
         layout: string;
+        pad: boolean;
         render(): import("lit-html").TemplateResult<1>;
     }
 }
@@ -10157,6 +10160,84 @@ declare module "components/page-builder/index" {
         }
     }
 }
+declare module "components/preview-frame/preview-frame.component" {
+    import { type CSSResultGroup } from 'lit';
+    import ZincElement from "internal/zinc-element";
+    /**
+     * @summary Embeds a live preview iframe and drives the hp-preview postMessage
+     * protocol: answers the frame's ready handshake with a config payload fetched
+     * from data-uri, auto-saves watched forms on change, and refreshes the
+     * preview after each save.
+     * @documentation https://zinc.style/components/preview-frame
+     * @status experimental
+     * @since 1.0
+     *
+     * @event zn-error - Emitted when the preview reports a render error or a save fails.
+     *
+     * @csspart base - The component's base wrapper.
+     * @csspart iframe - The preview iframe.
+     * @csspart error - The error overlay.
+     */
+    export default class ZnPreviewFrame extends ZincElement {
+        static styles: CSSResultGroup;
+        /** URL of the preview shell page (tokened embed URL). */
+        src: string;
+        /** Expected origin of the iframe; all postMessage traffic is checked against it. */
+        frameOrigin: string;
+        /** Endpoint returning the hp-preview:config payload JSON. The console proxy rewrites this attribute to an app-prefixed path for proper fetch resolution. */
+        dataUri: string;
+        /**
+         * Selector (resolved against the component's root node) for the forms to watch.
+         * Defaults to only forms explicitly opted in via a `data-auto-save` attribute —
+         * unmarked forms keep normal submit behavior and are never intercepted,
+         * auto-saved, or used to trigger a preview refresh. Override to widen the scope.
+         */
+        watch: string;
+        /** Debounce in ms between a form change and its auto-save. */
+        debounce: number;
+        /**
+         * Zooms the previewed page out (0–1]. The frame always fills the panel;
+         * zoom shrinks the content browser-style, so 0.4 shows the page at 40%
+         * size with correspondingly more of it visible. 1 = natural size.
+         */
+        zoom: number;
+        /**
+         * The visible height (in CSS pixels) of the preview panel. Fixed rather
+         * than measured, because a measured height would feed back into the
+         * scaled iframe's layout box and grow unbounded.
+         */
+        minHeight: number;
+        frame: HTMLIFrameElement;
+        private error;
+        private _generation;
+        private readonly _watchedForms;
+        private readonly _debounceTimers;
+        private readonly _formObserver;
+        connectedCallback(): void;
+        disconnectedCallback(): void;
+        private readonly _onMessage;
+        /** Re-fetches the payload and pushes a fresh config to the preview. */
+        refresh(): Promise<void>;
+        private _sendConfig;
+        private _attachForms;
+        private _detachForm;
+        private readonly _onChange;
+        private readonly _onSubmit;
+        private _save;
+        private _fail;
+        render(): import("lit-html").TemplateResult<1>;
+    }
+}
+declare module "components/preview-frame/index" {
+    import ZnPreviewFrame from "components/preview-frame/preview-frame.component";
+    export * from "components/preview-frame/preview-frame.component";
+    export default ZnPreviewFrame;
+    global {
+        interface HTMLElementTagNameMap {
+            'zn-preview-frame': ZnPreviewFrame;
+        }
+    }
+}
 declare module "utilities/form" {
     export { clearFormStoreValues } from "internal/form";
 }
@@ -10455,6 +10536,7 @@ declare module "zinc" {
     export { default as PageBuilder } from "components/page-builder/index";
     export { default as PagePaletteItem } from "components/page-builder/modules/page-palette-item/index";
     export { default as PageSectionCard } from "components/page-builder/modules/page-section-card/index";
+    export { default as PreviewFrame } from "components/preview-frame/index";
     export { default as ZincElement } from "internal/zinc-element";
     export * from "utilities/on";
     export * from "utilities/query";
@@ -10570,6 +10652,7 @@ declare module "events/zn-element-added" {
 declare module "events/zn-error" {
     export type ZnErrorEvent = CustomEvent<{
         status?: number;
+        message?: string;
     }>;
     global {
         interface GlobalEventHandlersEventMap {