@kubex/zinc 1.1.68 → 1.1.70

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.68",
+  "version": "1.1.70",
   "description-markup": "markdown",
   "contributions": {
     "html": {
@@ -1663,7 +1663,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.",
           "doc-url": "",
           "attributes": [
             {
@@ -3663,7 +3663,7 @@
         },
         {
           "name": "zn-file",
-          "description": "File controls allow selecting an arbitrary number of files for uploading.\n---\n\n\n### **Events:**\n - **zn-blur** - Emitted when the control loses focus.\n- **zn-change** - Emitted when an alteration to the control's value is committed by the user.\n- **zn-clear** - Emitted when the user confirms clearing the selected file or `src`.\n- **zn-error** - Emitted when multiple files are selected via drag and drop, without the `multiple` property being set.\n- **zn-focus** - Emitted when the control gains focus.\n- **zn-input** - Emitted when the control receives input.\n\n### **Methods:**\n - **checkValidity()** - Checks for validity but does not show a validation message.\nReturns `true` when valid and `false` when invalid.\n- **getForm(): _HTMLFormElement | null_** - Gets the associated form, if one exists.\n- **reportValidity()** - Checks for validity and shows the browser's validation message if the control is invalid.\n- **setCustomValidity(message: _string_)** - Sets a custom validation message. Pass an empty string to restore validity.\n- **focus(options: _FocusOptions_)** - Sets focus on the button or droparea.\n- **blur()** - Removes focus from the button or droparea.\n\n### **Slots:**\n - **label** - The file control's label. Alternatively, you can use the `label` attribute.\n- **help-text** - Text that describes how to use the file control. Alternatively, you can use the `help-text` attribute.\n- **trigger** - Optional content to be used as trigger instead of the default content. Opening the file dialog on click and as well as drag and drop will work for this content. Following attributes will no longer work: *label*, *droparea*, *help-text*, *size*, *hide-value*. Also if using the disabled attribute, the disabled styling will not be applied and must be taken care of yourself.\n\n### **CSS Parts:**\n - **form-control** - The form control that wraps the label, input, and help text.\n- **form-control-label** - The label's wrapper.\n- **form-control-input** - The input's wrapper.\n- **form-control-help-text** - The help text's wrapper.\n- **button-wrapper** - The wrapper around the button and text value.\n- **button** - The zn-button acting as a file input.\n- **button__base** - The zn-button's exported `base` part.\n- **value** - The chosen files or placeholder text for the file input.\n- **droparea** - The element wrapping the drop zone.\n- **droparea-background** - The background of the drop zone.\n- **upload** - The upload button shown in the droparea when no file is selected.\n- **preview** - The image preview rendered in the droparea for previewable files.\n- **filename** - The filename label rendered in the droparea for non-previewable files.\n- **clear** - The clear button rendered in the droparea when a file is present.\n- **clear-confirm** - The confirmation dialog shown before clearing the file.\n- **link** - The current link anchor rendered when `show-link` is enabled.\n- **trigger** - The container that wraps the trigger.",
+          "description": "File controls allow selecting an arbitrary number of files for uploading.\n---\n\n\n### **Events:**\n - **zn-blur** - Emitted when the control loses focus.\n- **zn-change** - Emitted when an alteration to the control's value is committed by the user.\n- **zn-clear** - Emitted when the user confirms clearing the selected file or `src`.\n- **zn-error** - Emitted when multiple files are selected via drag and drop, without the `multiple` property being set.\n- **zn-focus** - Emitted when the control gains focus.\n- **zn-input** - Emitted when the control receives input.\n\n### **Methods:**\n - **checkValidity()** - Checks for validity but does not show a validation message.\nReturns `true` when valid and `false` when invalid.\n- **getForm(): _HTMLFormElement | null_** - Gets the associated form, if one exists.\n- **reportValidity()** - Checks for validity and shows the browser's validation message if the control is invalid.\n- **setCustomValidity(message: _string_)** - Sets a custom validation message. Pass an empty string to restore validity.\n- **focus(options: _FocusOptions_)** - Sets focus on the button or droparea.\n- **blur()** - Removes focus from the button or droparea.\n- **clear()** - Programmatically clears the selected file and any external `src` without\nconfirmation. Unlike a user-initiated clear, this does not flag the control\nto submit an empty value.\n\n### **Slots:**\n - **label** - The file control's label. Alternatively, you can use the `label` attribute.\n- **help-text** - Text that describes how to use the file control. Alternatively, you can use the `help-text` attribute.\n- **trigger** - Optional content to be used as trigger instead of the default content. Opening the file dialog on click and as well as drag and drop will work for this content. Following attributes will no longer work: *label*, *droparea*, *help-text*, *size*, *hide-value*. Also if using the disabled attribute, the disabled styling will not be applied and must be taken care of yourself.\n\n### **CSS Parts:**\n - **form-control** - The form control that wraps the label, input, and help text.\n- **form-control-label** - The label's wrapper.\n- **form-control-input** - The input's wrapper.\n- **form-control-help-text** - The help text's wrapper.\n- **button-wrapper** - The wrapper around the button and text value.\n- **button** - The zn-button acting as a file input.\n- **button__base** - The zn-button's exported `base` part.\n- **value** - The chosen files or placeholder text for the file input.\n- **droparea** - The element wrapping the drop zone.\n- **droparea-background** - The background of the drop zone.\n- **upload** - The upload button shown in the droparea when no file is selected.\n- **preview** - The image preview rendered in the droparea for previewable files.\n- **filename** - The filename label rendered in the droparea for non-previewable files.\n- **clear** - The clear button rendered in the droparea when a file is present.\n- **clear-confirm** - The confirmation dialog shown before clearing the file.\n- **link** - The current link anchor rendered when `show-link` is enabled.\n- **trigger** - The container that wraps the trigger.",
           "doc-url": "",
           "attributes": [
             {
@@ -4207,6 +4207,63 @@
             "events": []
           }
         },
+        {
+          "name": "zn-header",
+          "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.",
+          "doc-url": "",
+          "attributes": [
+            { "name": "full-location", "value": { "type": "string" } },
+            { "name": "entity-id", "value": { "type": "string" } },
+            { "name": "entity-id-show", "value": { "type": "boolean" } },
+            {
+              "name": "transparent",
+              "value": { "type": "boolean", "default": "false" }
+            },
+            { "name": "caption", "value": { "type": "string" } },
+            { "name": "icon", "value": { "type": "string" } },
+            {
+              "name": "navigation",
+              "value": { "type": "array", "default": "[]" }
+            },
+            { "name": "full-width", "value": { "type": "boolean" } },
+            { "name": "previous-path", "value": { "type": "string" } },
+            { "name": "previous-target", "value": { "type": "string" } },
+            {
+              "name": "hide-breadcrumb",
+              "value": { "type": "boolean", "default": "false" }
+            }
+          ],
+          "slots": [
+            { "name": "", "description": "The default slot." },
+            { "name": "example", "description": "An example slot." }
+          ],
+          "events": [
+            { "name": "zn-event-name", "description": "Emitted as an example." }
+          ],
+          "js": {
+            "properties": [
+              { "name": "fullLocation", "type": "string" },
+              { "name": "entityId", "type": "string" },
+              { "name": "entityIdShow", "type": "boolean" },
+              { "name": "transparent", "type": "boolean" },
+              { "name": "caption", "type": "string" },
+              { "name": "icon", "type": "string" },
+              { "name": "navigation", "type": "array" },
+              { "name": "fullWidth", "type": "boolean" },
+              { "name": "previousPath", "type": "string" },
+              { "name": "previousTarget", "type": "string" },
+              { "name": "hideBreadcrumb", "type": "boolean" },
+              { "name": "handleAltPress" },
+              { "name": "handleAltUp" }
+            ],
+            "events": [
+              {
+                "name": "zn-event-name",
+                "description": "Emitted as an example."
+              }
+            ]
+          }
+        },
         {
           "name": "zn-hover-container",
           "description": "The HoverContainer component is used to display additional information when a user hovers over or clicks\non an element.\n---\n\n\n### **Events:**\n - **zn-show** - Emitted when the hover-container is shown.\n- **zn-after-show** - Emitted after the hover-container is shown.\n- **zn-hide** - Emitted when the hover-container is hidden.\n- **zn-after-hide** - Emitted after the hover-container is hidden.\n\n### **Slots:**\n - _default_ - The content of the hover-container\n- **anchor** - The anchor the hover-container is attached to.",
@@ -4310,63 +4367,6 @@
             ]
           }
         },
-        {
-          "name": "zn-header",
-          "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.",
-          "doc-url": "",
-          "attributes": [
-            { "name": "full-location", "value": { "type": "string" } },
-            { "name": "entity-id", "value": { "type": "string" } },
-            { "name": "entity-id-show", "value": { "type": "boolean" } },
-            {
-              "name": "transparent",
-              "value": { "type": "boolean", "default": "false" }
-            },
-            { "name": "caption", "value": { "type": "string" } },
-            { "name": "icon", "value": { "type": "string" } },
-            {
-              "name": "navigation",
-              "value": { "type": "array", "default": "[]" }
-            },
-            { "name": "full-width", "value": { "type": "boolean" } },
-            { "name": "previous-path", "value": { "type": "string" } },
-            { "name": "previous-target", "value": { "type": "string" } },
-            {
-              "name": "hide-breadcrumb",
-              "value": { "type": "boolean", "default": "false" }
-            }
-          ],
-          "slots": [
-            { "name": "", "description": "The default slot." },
-            { "name": "example", "description": "An example slot." }
-          ],
-          "events": [
-            { "name": "zn-event-name", "description": "Emitted as an example." }
-          ],
-          "js": {
-            "properties": [
-              { "name": "fullLocation", "type": "string" },
-              { "name": "entityId", "type": "string" },
-              { "name": "entityIdShow", "type": "boolean" },
-              { "name": "transparent", "type": "boolean" },
-              { "name": "caption", "type": "string" },
-              { "name": "icon", "type": "string" },
-              { "name": "navigation", "type": "array" },
-              { "name": "fullWidth", "type": "boolean" },
-              { "name": "previousPath", "type": "string" },
-              { "name": "previousTarget", "type": "string" },
-              { "name": "hideBreadcrumb", "type": "boolean" },
-              { "name": "handleAltPress" },
-              { "name": "handleAltUp" }
-            ],
-            "events": [
-              {
-                "name": "zn-event-name",
-                "description": "Emitted as an example."
-              }
-            ]
-          }
-        },
         {
           "name": "zn-icon",
           "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.",
@@ -4445,7 +4445,10 @@
             { "name": "label", "value": { "type": "string", "default": "''" } },
             {
               "name": "library",
-              "value": { "type": "string", "default": "'material'" }
+              "value": {
+                "type": "string",
+                "default": "'material-symbols-outlined'"
+              }
             },
             { "name": "color", "value": { "type": "string", "default": "''" } },
             {
@@ -4468,6 +4471,18 @@
               "name": "required",
               "value": { "type": "boolean", "default": "false" }
             },
+            {
+              "name": "trigger-submit",
+              "value": { "type": "boolean", "default": "false" }
+            },
+            {
+              "name": "allow-upload",
+              "value": { "type": "boolean", "default": "false" }
+            },
+            {
+              "name": "accept",
+              "value": { "type": "string", "default": "'image/*'" }
+            },
             { "name": "form", "value": { "type": "string" } }
           ],
           "events": [],
@@ -4483,9 +4498,22 @@
               { "name": "helpText", "type": "string" },
               { "name": "disabled", "type": "boolean" },
               { "name": "required", "type": "boolean" },
+              { "name": "triggerSubmit", "type": "boolean" },
+              { "name": "allowUpload", "type": "boolean" },
+              { "name": "accept", "type": "string" },
               { "name": "form", "type": "string" },
               { "name": "defaultValue", "type": "string" },
               { "name": "value", "type": "string" },
+              {
+                "name": "file",
+                "description": "The chosen file when the user uploaded an image instead of picking an icon.",
+                "type": "File | null"
+              },
+              {
+                "name": "isImageValue",
+                "description": "True when the current value renders as an image (an uploaded file or a URL) rather than a library icon.",
+                "type": "boolean"
+              },
               { "name": "validity", "type": "ValidityState" },
               { "name": "validationMessage", "type": "string" }
             ],
@@ -4702,7 +4730,7 @@
         },
         {
           "name": "zn-input",
-          "description": "Short summary of the component's intended use.\n---\n\n\n### **Events:**\n - **zn-blur** - Emitted when the control loses focus.\n- **zn-change** - Emitted when an alteration to the control's value is committed by the user.\n- **zn-clear** - Emitted when the clear button is activated.\n- **zn-focus** - Emitted when the control gains focus.\n- **zn-input** - Emitted when the control receives input.\n- **zn-invalid** - Emitted when the form control has been checked for validity and its constraints aren't satisfied.\n\n### **Methods:**\n - **focus(options: _FocusOptions_)** - Sets focus on the input.\n- **blur()** - Removes focus from the input.\n- **select()** - Selects all the text in the input.\n- **setSelectionRange(selectionStart: _number_, selectionEnd: _number_, selectionDirection: _'forward' | 'backward' | 'none'_)** - Sets the start and end positions of the text selection (0-based).\n- **setRangeText(replacement: _string_, start: _number_, end: _number_, selectMode: _'select' | 'start' | 'end' | 'preserve'_)** - Replaces a range of text with a new string.\n- **showPicker()** - Displays the browser picker for an input element (only works if the browser supports it for the input type).\n- **stepUp()** - Increments the value of a numeric input type by the value of the step attribute.\n- **stepDown()** - Decrements the value of a numeric input type by the value of the step attribute.\n- **checkValidity(): _boolean_** - Checks the validity but does not show a validation message. Returns `true` when valid and `false` when invalid.\n- **getForm(): _HTMLFormElement | null_** - Gets the associated form, if one exists.\n- **reportValidity()** - Checks for validity and shows the browser's validation message if the control is invalid.\n- **setCustomValidity(message: _string_)** - Sets a custom validation message. Pass an empty string to restore validity.\n\n### **Slots:**\n - **label** - The input's label. Alternatively, you can use the `label` attribute.\n- **label-tooltip** - Used to add text that is displayed in a tooltip next to the label. Alternatively, you can use the `label-tooltip` attribute.\n- **context-note** - Used to add contextual text that is displayed above the input, on the right. Alternatively, you can use the `context-note` attribute.\n- **prefix** - Used to prepend a presentational icon or similar element to the input.\n- **suffix** - Used to append a presentational icon or similar element to the input.\n- **clear-icon** - An icon to use in lieu of the default clear icon.\n- **show-password-icon** - An icon to use in lieu of the default show password icon.\n- **hide-password-icon** - An icon to use in lieu of the default hide password icon.\n- **help-text** - Text that describes how to use the input. Alternatively, you can use the `help-text` attribute.\n\n### **CSS Parts:**\n - **form-control** - The form control that wraps the label, input, and help text.\n- **form-control-label** - The label's wrapper.\n- **form-control-input** - The input's wrapper.\n- **form-control-help-text** - The help text's wrapper.\n- **base** - The component's base wrapper.\n- **input** - The internal `<input>` control.\n- **prefix** - The container that wraps the prefix.\n- **clear-button** - The clear button.\n- **password-toggle-button** - The password toggle button.\n- **suffix** - The container that wraps the suffix.",
+          "description": "Short summary of the component's intended use.\n---\n\n\n### **Events:**\n - **zn-blur** - Emitted when the control loses focus.\n- **zn-change** - Emitted when an alteration to the control's value is committed by the user.\n- **zn-clear** - Emitted when the clear button is activated.\n- **zn-focus** - Emitted when the control gains focus.\n- **zn-input** - Emitted when the control receives input.\n- **zn-invalid** - Emitted when the form control has been checked for validity and its constraints aren't satisfied.\n\n### **Methods:**\n - **focus(options: _FocusOptions_)** - Sets focus on the input.\n- **blur()** - Removes focus from the input.\n- **select()** - Selects all the text in the input.\n- **setSelectionRange(selectionStart: _number_, selectionEnd: _number_, selectionDirection: _'forward' | 'backward' | 'none'_)** - Sets the start and end positions of the text selection (0-based).\n- **setRangeText(replacement: _string_, start: _number_, end: _number_, selectMode: _'select' | 'start' | 'end' | 'preserve'_)** - Replaces a range of text with a new string.\n- **showPicker()** - Displays the browser picker for an input element (only works if the browser supports it for the input type).\n- **stepUp()** - Increments the value of a numeric input type by the value of the step attribute.\n- **stepDown()** - Decrements the value of a numeric input type by the value of the step attribute.\n- **checkValidity(): _boolean_** - Checks the validity but does not show a validation message. Returns `true` when valid and `false` when invalid.\n- **getForm(): _HTMLFormElement | null_** - Gets the associated form, if one exists.\n- **reportValidity()** - Checks for validity and shows the browser's validation message if the control is invalid.\n- **setCustomValidity(message: _string_)** - Sets a custom validation message. Pass an empty string to restore validity.\n\n### **Slots:**\n - **label** - The input's label. Alternatively, you can use the `label` attribute.\n- **label-tooltip** - Used to add text that is displayed in a tooltip next to the label. Alternatively, you can use the `label-tooltip` attribute.\n- **context-note** - Used to add contextual text that is displayed above the input, on the right. Alternatively, you can use the `context-note` attribute. Range inputs display their live value here unless this is set.\n- **prefix** - Used to prepend a presentational icon or similar element to the input.\n- **suffix** - Used to append a presentational icon or similar element to the input.\n- **clear-icon** - An icon to use in lieu of the default clear icon.\n- **show-password-icon** - An icon to use in lieu of the default show password icon.\n- **hide-password-icon** - An icon to use in lieu of the default hide password icon.\n- **help-text** - Text that describes how to use the input. Alternatively, you can use the `help-text` attribute.\n\n### **CSS Properties:**\n - **--zn-range-track-height** - The height of a range input's track. _(default: undefined)_\n- **--zn-range-track-color** - The color of a range input's track. _(default: undefined)_\n- **--zn-range-thumb-size** - The diameter of a range input's thumb. _(default: undefined)_\n- **--zn-range-thumb-color** - The color of a range input's thumb. _(default: undefined)_\n- **--zn-range-thumb-ring-width** - The width of the ring drawn around a range input's thumb. _(default: undefined)_\n\n### **CSS Parts:**\n - **form-control** - The form control that wraps the label, input, and help text.\n- **form-control-label** - The label's wrapper.\n- **form-control-input** - The input's wrapper.\n- **form-control-help-text** - The help text's wrapper.\n- **base** - The component's base wrapper.\n- **input** - The internal `<input>` control.\n- **prefix** - The container that wraps the prefix.\n- **clear-button** - The clear button.\n- **password-toggle-button** - The password toggle button.\n- **suffix** - The container that wraps the suffix.",
           "doc-url": "",
           "attributes": [
             {
@@ -4713,7 +4741,7 @@
               "name": "type",
               "description": "The type of input. Works the same as native `<input>` element. But only a subset of types is supported. Defaults\nto `text`",
               "value": {
-                "type": "'color' | 'currency' | 'date' | 'datetime-local' | 'email' | 'number' | 'password' |\n    'search' | 'tel' | 'text' | 'time' | 'url'",
+                "type": "'color' | 'currency' | 'date' | 'datetime-local' | 'email' | 'number' | 'password' |\n    'range' | 'search' | 'tel' | 'text' | 'time' | 'url'",
                 "default": "'text'"
               }
             },
@@ -4813,6 +4841,11 @@
                 "default": "'hex'"
               }
             },
+            {
+              "name": "value-suffix",
+              "description": "Appended to the value that range inputs display above the track, on the right, e.g. `rem`. Only applies when type\nis 'range' and no `context-note` is set.",
+              "value": { "type": "string", "default": "''" }
+            },
             {
               "name": "form",
               "description": "By default, form-controls are associated with the nearest containing `<form>` element. This attribute allows you\nto place the form control outside a form and associate it with the form that has this `id`. The form must be\nin the same document or shadow root for this to work.",
@@ -4911,7 +4944,7 @@
             },
             {
               "name": "context-note",
-              "description": "Used to add contextual text that is displayed above the input, on the right. Alternatively, you can use the `context-note` attribute."
+              "description": "Used to add contextual text that is displayed above the input, on the right. Alternatively, you can use the `context-note` attribute. Range inputs display their live value here unless this is set."
             },
             {
               "name": "prefix",
@@ -4972,7 +5005,7 @@
               {
                 "name": "type",
                 "description": "The type of input. Works the same as native `<input>` element. But only a subset of types is supported. Defaults\nto `text`",
-                "type": "'color' | 'currency' | 'date' | 'datetime-local' | 'email' | 'number' | 'password' |\n    'search' | 'tel' | 'text' | 'time' | 'url'"
+                "type": "'color' | 'currency' | 'date' | 'datetime-local' | 'email' | 'number' | 'password' |\n    'range' | 'search' | 'tel' | 'text' | 'time' | 'url'"
               },
               {
                 "name": "name",
@@ -5069,6 +5102,11 @@
                 "description": "The color format to display for color inputs. Only applies when type is 'color'. *",
                 "type": "'hex' | 'rgb' | 'hsl' | 'oklch'"
               },
+              {
+                "name": "valueSuffix",
+                "description": "Appended to the value that range inputs display above the track, on the right, e.g. `rem`. Only applies when type\nis 'range' and no `context-note` is set.",
+                "type": "string"
+              },
               {
                 "name": "form",
                 "description": "By default, form-controls are associated with the nearest containing `<form>` element. This attribute allows you\nto place the form control outside a form and associate it with the form that has this `id`. The form must be\nin the same document or shadow root for this to work.",
@@ -6901,7 +6939,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.",
           "doc-url": "",
           "attributes": [
             {
@@ -6924,6 +6962,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.",
               "value": { "type": "string", "default": "'form[data-auto-save]'" }
             },
+            {
+              "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.",
+              "value": { "type": "string", "default": "'form'" }
+            },
             {
               "name": "debounce",
               "description": "Debounce in ms between a form change and its auto-save.",
@@ -6931,13 +6974,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.",
               "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.",
+              "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.",
               "value": { "type": "number", "default": "480" }
+            },
+            {
+              "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.",
+              "value": { "type": "boolean", "default": "false" }
+            },
+            {
+              "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.",
+              "value": { "type": "PreviewFrameDevice", "default": "'desktop'" }
+            },
+            {
+              "name": "backdrop",
+              "description": "Backdrop behind the stage: `dots` (default) is the canvas dot grid; `panel` is a plain `rgb(var(--zn-panel))` fill.",
+              "value": { "type": "'dots' | 'panel'", "default": "'dots'" }
             }
           ],
           "events": [
@@ -6968,6 +7026,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.",
                 "type": "string"
               },
+              {
+                "name": "refreshOn",
+                "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.",
+                "type": "string"
+              },
               {
                 "name": "debounce",
                 "description": "Debounce in ms between a form change and its auto-save.",
@@ -6975,14 +7038,29 @@
               },
               {
                 "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.",
                 "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.",
+                "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.",
                 "type": "number"
               },
+              {
+                "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.",
+                "type": "boolean"
+              },
+              {
+                "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.",
+                "type": "PreviewFrameDevice"
+              },
+              {
+                "name": "backdrop",
+                "description": "Backdrop behind the stage: `dots` (default) is the canvas dot grid; `panel` is a plain `rgb(var(--zn-panel))` fill.",
+                "type": "'dots' | 'panel'"
+              },
               { "name": "frame", "type": "HTMLIFrameElement" }
             ],
             "events": [
@@ -9723,6 +9801,253 @@
             ]
           }
         },
+        {
+          "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. With `sections` left unset, the structure is instead derived from the controls' own attributes: `group=\"<label>\"` becomes a tab and `category=\"<label>\"` a collapsible within it, and the control is slotted into that collapsible automatically. Either attribute works alone - a control with only `group` sits directly in its tab, and one with only `category` becomes its own top-level section. Setting `sections` explicitly disables the derivation entirely.\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).",
+          "doc-url": "",
+          "attributes": [
+            {
+              "name": "src",
+              "description": "URL of the preview shell page; forwarded to the frame.",
+              "value": { "type": "string", "default": "''" }
+            },
+            {
+              "name": "frame-origin",
+              "description": "Expected origin of the iframe; forwarded to the frame.",
+              "value": { "type": "string", "default": "''" }
+            },
+            {
+              "name": "data-uri",
+              "description": "Optional endpoint returning the base hp-preview:config payload.",
+              "value": { "type": "string", "default": "''" }
+            },
+            {
+              "name": "mode",
+              "description": "Which mode the preview renders in. Travels in the theme payload.",
+              "value": { "type": "ThemeEditorMode", "default": "'light'" }
+            },
+            {
+              "name": "device",
+              "description": "Preview viewport width. Resizes the frame only; not part of the payload.",
+              "value": { "type": "ThemeEditorDevice", "default": "'desktop'" }
+            },
+            {
+              "name": "min-height",
+              "description": "Minimum height of the preview row, in pixels; forwarded to the frame as its own floor.",
+              "value": { "type": "number", "default": "480" }
+            },
+            {
+              "name": "debounce",
+              "description": "Debounce in ms between a control change and the push to the preview.",
+              "value": { "type": "number", "default": "150" }
+            },
+            {
+              "name": "action",
+              "description": "Optional endpoint the values are POSTed to. Empty = no persistence.",
+              "value": { "type": "string", "default": "''" }
+            },
+            {
+              "name": "save-debounce",
+              "description": "Debounce in ms between a control change and the save POST.",
+              "value": { "type": "number", "default": "1000" }
+            },
+            {
+              "name": "sections",
+              "description": "Groups controls into named sections. Empty/unset falls back to deriving the\nstructure from the controls' own `group`/`category` attributes, and renders\none ungrouped column when they carry neither. A section with a non-empty\n`groups` nests a collapsible per group inside a `zn-tabs` tab for that\nsection - see `groups` on `ThemeEditorSection`.",
+              "value": { "type": "ThemeEditorSection[]", "default": "[]" }
+            },
+            {
+              "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.",
+              "value": {
+                "type": "'collapsible' | 'tabs'",
+                "default": "'collapsible'"
+              }
+            },
+            {
+              "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.",
+              "value": { "type": "ThemeEditorSource[]", "default": "[]" }
+            },
+            {
+              "name": "controls-collapsed",
+              "description": "Collapses the controls column.",
+              "value": { "type": "boolean", "default": "false" }
+            },
+            {
+              "name": "standalone",
+              "description": "Presents the editor as its own bordered, rounded panel with a plain preview backdrop, rather than embedded in a dotted canvas.",
+              "value": { "type": "boolean", "default": "false" }
+            },
+            {
+              "name": "controls-caption",
+              "description": "Caption in the controls column's header row. Empty (default) renders no text; the row itself always renders.",
+              "value": { "type": "string", "default": "''" }
+            },
+            {
+              "name": "preview-caption",
+              "description": "Caption at the left of the toolbar, opposite the device and mode controls. Empty (default) renders no text.",
+              "value": { "type": "string", "default": "''" }
+            },
+            {
+              "name": "submit-label",
+              "description": "Label for the built-in submit button. Empty (default) renders no button.",
+              "value": { "type": "string", "default": "''" }
+            },
+            {
+              "name": "manual",
+              "description": "Disables the debounced auto-save; saving then happens only via submit. Preview pushes are unaffected.",
+              "value": { "type": "boolean", "default": "false" }
+            }
+          ],
+          "slots": [
+            {
+              "name": "",
+              "description": "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. With `sections` left unset, the structure is instead derived from the controls' own attributes: `group=\"<label>\"` becomes a tab and `category=\"<label>\"` a collapsible within it, and the control is slotted into that collapsible automatically. Either attribute works alone - a control with only `group` sits directly in its tab, and one with only `category` becomes its own top-level section. Setting `sections` explicitly disables the derivation entirely."
+            },
+            {
+              "name": "toolbar",
+              "description": "Actions in the toolbar, right-aligned beside the device controls. Where a save button belongs."
+            },
+            {
+              "name": "footer",
+              "description": "Actions pinned beneath the controls. The built-in submit button lives in the toolbar, not here."
+            }
+          ],
+          "events": [
+            {
+              "name": "zn-theme-change",
+              "description": "Emitted when the values, mode or device change."
+            },
+            {
+              "name": "zn-theme-submit",
+              "description": "Emitted on submit (button click), carrying the current values. With `action` set, only fires after a successful save."
+            },
+            {
+              "name": "zn-error",
+              "description": "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."
+            }
+          ],
+          "js": {
+            "properties": [
+              {
+                "name": "src",
+                "description": "URL of the preview shell page; forwarded to the frame.",
+                "type": "string"
+              },
+              {
+                "name": "frameOrigin",
+                "description": "Expected origin of the iframe; forwarded to the frame.",
+                "type": "string"
+              },
+              {
+                "name": "dataUri",
+                "description": "Optional endpoint returning the base hp-preview:config payload.",
+                "type": "string"
+              },
+              {
+                "name": "mode",
+                "description": "Which mode the preview renders in. Travels in the theme payload.",
+                "type": "ThemeEditorMode"
+              },
+              {
+                "name": "device",
+                "description": "Preview viewport width. Resizes the frame only; not part of the payload.",
+                "type": "ThemeEditorDevice"
+              },
+              {
+                "name": "minHeight",
+                "description": "Minimum height of the preview row, in pixels; forwarded to the frame as its own floor.",
+                "type": "number"
+              },
+              {
+                "name": "debounce",
+                "description": "Debounce in ms between a control change and the push to the preview.",
+                "type": "number"
+              },
+              {
+                "name": "action",
+                "description": "Optional endpoint the values are POSTed to. Empty = no persistence.",
+                "type": "string"
+              },
+              {
+                "name": "saveDebounce",
+                "description": "Debounce in ms between a control change and the save POST.",
+                "type": "number"
+              },
+              {
+                "name": "sections",
+                "description": "Groups controls into named sections. Empty/unset falls back to deriving the\nstructure from the controls' own `group`/`category` attributes, and renders\none ungrouped column when they carry neither. A section with a non-empty\n`groups` nests a collapsible per group inside a `zn-tabs` tab for that\nsection - see `groups` on `ThemeEditorSection`.",
+                "type": "ThemeEditorSection[]"
+              },
+              {
+                "name": "sectionLayout",
+                "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.",
+                "type": "'collapsible' | '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.",
+                "type": "ThemeEditorSource[]"
+              },
+              {
+                "name": "controlsCollapsed",
+                "description": "Collapses the controls column.",
+                "type": "boolean"
+              },
+              {
+                "name": "standalone",
+                "description": "Presents the editor as its own bordered, rounded panel with a plain preview backdrop, rather than embedded in a dotted canvas.",
+                "type": "boolean"
+              },
+              {
+                "name": "controlsCaption",
+                "description": "Caption in the controls column's header row. Empty (default) renders no text; the row itself always renders.",
+                "type": "string"
+              },
+              {
+                "name": "previewCaption",
+                "description": "Caption at the left of the toolbar, opposite the device and mode controls. Empty (default) renders no text.",
+                "type": "string"
+              },
+              {
+                "name": "submitLabel",
+                "description": "Label for the built-in submit button. Empty (default) renders no button.",
+                "type": "string"
+              },
+              {
+                "name": "manual",
+                "description": "Disables the debounced auto-save; saving then happens only via submit. Preview pushes are unaffected.",
+                "type": "boolean"
+              },
+              { "name": "frame", "type": "ZnPreviewFrame" },
+              {
+                "name": "values",
+                "description": "The current per-mode value sets. Returns copies.",
+                "type": "{ light: Record<string, unknown>; dark: Record<string, unknown> }"
+              },
+              {
+                "name": "activeValues",
+                "description": "The active mode's values - what gets pushed to the preview frame.",
+                "type": "Record<string, unknown>"
+              }
+            ],
+            "events": [
+              {
+                "name": "zn-theme-change",
+                "description": "Emitted when the values, mode or device change."
+              },
+              {
+                "name": "zn-theme-submit",
+                "description": "Emitted on submit (button click), carrying the current values. With `action` set, only fires after a successful save."
+              },
+              {
+                "name": "zn-error",
+                "description": "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."
+              }
+            ]
+          }
+        },
         {
           "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.",