@kubex/zinc 1.1.67 → 1.1.69

package/dist/vscode.html-custom-data.json

@@ -762,7 +762,7 @@
     },
     {
       "name": "zn-collapsible",
-      "description": "Toggles between showing and hiding content when clicked\n---\n\n\n### **Slots:**\n - **header** - Clicking will toggle the show state of the data\n\n### **CSS Parts:**\n - **header** - The header row (toggle).\n- **caption** - The caption text.",
+      "description": "Toggles between showing and hiding content when clicked\n---\n\n\n### **Slots:**\n - **header** - Clicking will toggle the show state of the data\n\n### **CSS Parts:**\n - **header** - The header row (toggle).\n- **caption** - The caption text.\n- **content** - The expandable content wrapper.",
       "attributes": [
         { "name": "caption", "values": [] },
         { "name": "description", "values": [] },
@@ -1318,10 +1318,19 @@
       "name": "zn-defined-label",
       "description": "This component provides a labeled input with support for predefined and custom labels,\nallowing users to select or enter label-value pairs within a dropdown interface.\n---\n\n\n### **CSS Parts:**\n - **input** - The component's main input.\n- **input-value** - The label's value inputs.",
       "attributes": [
-        { "name": "value", "values": [] },
-        { "name": "inputValue", "values": [] },
+        {
+          "name": "value",
+          "description": "The selected label key. Also acts as the filter while typing.",
+          "values": []
+        },
+        {
+          "name": "inputValue",
+          "description": "The value entered for the selected label. Submitted as `label:value` when present.",
+          "values": []
+        },
         {
           "name": "input-size",
+          "description": "The size of the main input.",
           "values": [
             { "name": "x-small" },
             { "name": "small" },
@@ -1329,11 +1338,31 @@
             { "name": "large" }
           ]
         },
-        { "name": "name", "values": [] },
-        { "name": "title", "values": [] },
-        { "name": "disabled", "values": [] },
-        { "name": "allow-custom", "values": [] },
-        { "name": "predefined-labels", "values": [{ "name": "array" }] }
+        {
+          "name": "name",
+          "description": "The name of the control. Used for form submission.",
+          "values": []
+        },
+        {
+          "name": "title",
+          "description": "The title of the main input.",
+          "values": []
+        },
+        {
+          "name": "disabled",
+          "description": "Disables the control.",
+          "values": []
+        },
+        {
+          "name": "allow-custom",
+          "description": "Allows labels that aren't in the predefined list.",
+          "values": []
+        },
+        {
+          "name": "predefined-labels",
+          "description": "The predefined labels. Entries are either a string or `{name, options}`.",
+          "values": [{ "name": "(PredefinedLabel" }, { "name": "string)[]" }]
+        }
       ],
       "references": [
         {
@@ -1665,6 +1694,11 @@
           "name": "show-link",
           "description": "When enabled, render the current link (`previewSrc`) as a clickable URL below the control.\nUseful for showing the existing CDN link alongside the preview.",
           "values": []
+        },
+        {
+          "name": "upload-url",
+          "description": "When set, a chosen file is immediately POSTed (multipart, field `file`) to this URL.\nThe endpoint must respond with JSON `{\"url\": \"...\"}`; that URL becomes the control's\nvalue (and `src` preview) in place of the file bytes, so the control works inside\nJSON-serialising hosts such as `zn-page-builder`. Emits `zn-error` when the upload fails.",
+          "values": []
         }
       ],
       "references": [
@@ -2921,7 +2955,7 @@
     },
     {
       "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.",
+      "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, refreshes the preview\nafter each save (its own, or a shell-driven save of a `refresh-on` form),\nand accepts a theme payload via setTheme() that is retained and replayed\nafter every ready handshake.\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- **setTheme(theme: _Record<string, unknown>_)** - Pushes a theme payload into the preview. The payload is retained and\nre-posted after every ready handshake, so a frame reload doesn't drop an\nin-progress theme.\n\n### **CSS Properties:**\n - **--zn-preview-frame-dot-spacing** - Spacing of the backdrop dot grid (`backdrop=\"dots\"`). Defaults to 20px. _(default: undefined)_\n- **--zn-preview-frame-dot-opacity** - Opacity of the backdrop dots (`backdrop=\"dots\"`). Defaults to 0.08. _(default: undefined)_\n\n### **CSS Parts:**\n - **base** - The component's base wrapper.\n- **stage** - The device-width wrapper around the iframe.\n- **iframe** - The preview iframe.\n- **error** - The error overlay.",
       "attributes": [
         {
           "name": "src",
@@ -2943,6 +2977,11 @@
           "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.",
           "values": []
         },
+        {
+          "name": "refresh-on",
+          "description": "Selector for forms whose saves are left to the shell but should still\nrefresh the preview. These are never intercepted: the shell submits them\n(so its own response handling — alerts, refreshes — runs as normal) and the\npreview re-fetches its config once the shell reports the save complete.\nSet empty to disable.",
+          "values": []
+        },
         {
           "name": "debounce",
           "description": "Debounce in ms between a form change and its auto-save.",
@@ -2950,13 +2989,28 @@
         },
         {
           "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.",
+          "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.\nIgnored when `fill` is set.",
           "values": []
         },
         {
           "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.",
+          "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. With `fill` set, this\nbecomes a `min-height` floor instead of the height.",
+          "values": []
+        },
+        {
+          "name": "fill",
+          "description": "Fills the panel's own column height instead of using a fixed\n`min-height` pixel height — for hosts (like zn-theme-editor) whose\nlayout already stretches the column to match a taller sibling.\n`zoom` is ignored when set: its oversize maths depends on a known\npixel height, which `fill` deliberately doesn't have.",
           "values": []
+        },
+        {
+          "name": "device",
+          "description": "Constrains and centres the preview to a device width: `desktop` (100%),\n`tablet` (768px) or `mobile` (390px). The iframe element itself is\nnarrowed, so the embedded page's own media queries fire.",
+          "values": [{ "name": "PreviewFrameDevice" }]
+        },
+        {
+          "name": "backdrop",
+          "description": "Backdrop behind the stage: `dots` (default) is the canvas dot grid; `panel` is a plain `rgb(var(--zn-panel))` fill.",
+          "values": [{ "name": "dots" }, { "name": "panel" }]
         }
       ],
       "references": [
@@ -4085,6 +4139,108 @@
         }
       ]
     },
+    {
+      "name": "zn-theme-editor",
+      "description": "A theme editor: slotted form controls drive a live preview frame,\nwith a toolbar for the preview's light/dark mode and device width.\n---\n\n\n### **Events:**\n - **zn-theme-change** - Emitted when the values, mode or device change.\n- **zn-theme-submit** - Emitted on submit (button click), carrying the current values. With `action` set, only fires after a successful save.\n- **zn-error** - Emitted when a save fails. Also seen for preview render failures: the frame's zn-error is composed and not stopped, so it bubbles out through the editor too.\n\n### **Slots:**\n - _default_ - Ungrouped theme controls, rendered above any sections. Controls assigned `slot=\"<name>\"` matching a `sections` entry (or, when nested, a `groups` entry) render inside that section/group instead. Harvesting and change detection walk every slot's full assigned subtree, not just direct children.\n- **toolbar** - Actions in the toolbar, right-aligned beside the device controls. Where a save button belongs.\n- **footer** - Actions pinned beneath the controls. The built-in submit button lives in the toolbar, not here.\n\n### **CSS Properties:**\n - **--zn-theme-editor-controls-width** - Width of the controls column. _(default: undefined)_\n\n### **CSS Parts:**\n - **base** - The component's base wrapper.\n- **controls** - The left-hand controls column, full height.\n- **controls-header** - The controls column's header row: `controls-caption` on the left, the light/dark mode toggle on the right.\n- **toolbar** - The preview column's header row: `preview-caption` on the left, the device switcher (and sources/submit) on the right. Spans the preview column only.\n- **section** - A rendered section's or group's collapsible (`section-layout=\"collapsible\"`, or any nested group).\n- **footer** - The footer wrapper beneath the controls.\n- **preview** - The preview column.\n- **error** - The inline error strip.\n- **preview__base** - The frame's base wrapper (forwarded from zn-preview-frame).\n- **preview__stage** - The frame's device-width wrapper (forwarded from zn-preview-frame).\n- **preview__iframe** - The frame's iframe (forwarded from zn-preview-frame).\n- **preview__error** - The frame's own error overlay (forwarded from zn-preview-frame).",
+      "attributes": [
+        {
+          "name": "src",
+          "description": "URL of the preview shell page; forwarded to the frame.",
+          "values": []
+        },
+        {
+          "name": "frame-origin",
+          "description": "Expected origin of the iframe; forwarded to the frame.",
+          "values": []
+        },
+        {
+          "name": "data-uri",
+          "description": "Optional endpoint returning the base hp-preview:config payload.",
+          "values": []
+        },
+        {
+          "name": "mode",
+          "description": "Which mode the preview renders in. Travels in the theme payload.",
+          "values": [{ "name": "ThemeEditorMode" }]
+        },
+        {
+          "name": "device",
+          "description": "Preview viewport width. Resizes the frame only; not part of the payload.",
+          "values": [{ "name": "ThemeEditorDevice" }]
+        },
+        {
+          "name": "min-height",
+          "description": "Minimum height of the preview row, in pixels; forwarded to the frame as its own floor.",
+          "values": []
+        },
+        {
+          "name": "debounce",
+          "description": "Debounce in ms between a control change and the push to the preview.",
+          "values": []
+        },
+        {
+          "name": "action",
+          "description": "Optional endpoint the values are POSTed to. Empty = no persistence.",
+          "values": []
+        },
+        {
+          "name": "save-debounce",
+          "description": "Debounce in ms between a control change and the save POST.",
+          "values": []
+        },
+        {
+          "name": "sections",
+          "description": "Groups controls into named sections. Empty/unset renders one ungrouped\ncolumn. A section with a non-empty `groups` nests a collapsible per\ngroup inside a `zn-tabs` tab for that section - see `groups` on\n`ThemeEditorSection`.",
+          "values": [{ "name": "ThemeEditorSection[]" }]
+        },
+        {
+          "name": "section-layout",
+          "description": "Presentation for flat, group-less `sections`: stacked `zn-collapsible`s\n(default) or a `zn-tabs` strip. Ignored once any section has `groups` -\nnested sections always render as tabs.",
+          "values": [{ "name": "collapsible" }, { "name": "tabs" }]
+        },
+        {
+          "name": "sources",
+          "description": "Dropdown of preview sources, `{label, src}`, rendered in the toolbar. Empty/unset renders no dropdown; the first entry wins over an explicit `src` when non-empty.",
+          "values": [{ "name": "ThemeEditorSource[]" }]
+        },
+        {
+          "name": "controls-collapsed",
+          "description": "Collapses the controls column.",
+          "values": []
+        },
+        {
+          "name": "standalone",
+          "description": "Presents the editor as its own bordered, rounded panel with a plain preview backdrop, rather than embedded in a dotted canvas.",
+          "values": []
+        },
+        {
+          "name": "controls-caption",
+          "description": "Caption in the controls column's header row. Empty (default) renders no text; the row itself always renders.",
+          "values": []
+        },
+        {
+          "name": "preview-caption",
+          "description": "Caption at the left of the toolbar, opposite the device and mode controls. Empty (default) renders no text.",
+          "values": []
+        },
+        {
+          "name": "submit-label",
+          "description": "Label for the built-in submit button. Empty (default) renders no button.",
+          "values": []
+        },
+        {
+          "name": "manual",
+          "description": "Disables the debounced auto-save; saving then happens only via submit. Preview pushes are unaffected.",
+          "values": []
+        }
+      ],
+      "references": [
+        {
+          "name": "Documentation",
+          "url": "https://zinc.style/components/theme-editor"
+        }
+      ]
+    },
     {
       "name": "zn-tile",
       "description": "Short summary of the component's intended use.\n---\n\n\n### **Events:**\n - **zn-event-name** - Emitted as an example.\n\n### **Slots:**\n - _default_ - The default slot.\n- **example** - An example slot.\n\n### **CSS Properties:**\n - **--example** - An example CSS custom property. _(default: undefined)_\n\n### **CSS Parts:**\n - **base** - The component's base wrapper.",