@kubex/zinc 1.1.69 → 1.1.70

package/docs/pages/components/icon-picker.md

@@ -87,6 +87,20 @@ Use the `avatar` library to generate initials from a name.
 <zn-icon-picker name="av" label="Avatar" icon="John Smith" library="avatar" no-color></zn-icon-picker>
 ```
 
+### Upload Image
+
+By default the picker only offers library icons. Add the `allow-upload` attribute to enable a secondary "Upload Image" mode in the dialog, letting users upload an image file instead of picking an icon. Use the `accept` attribute to restrict the accepted file types (defaults to `image/*`).
+
+An uploaded file replaces the icon value: on submit, the file is sent under `name` in place of the icon string — the two are mutually exclusive. The chosen file is also available via the element's `file` property.
+
+```html:preview
+<zn-icon-picker name="logo" label="Logo" allow-upload></zn-icon-picker>
+```
+
+```html:preview
+<zn-icon-picker name="photo" label="Photo (PNG only)" allow-upload accept="image/png"></zn-icon-picker>
+```
+
 ### Help Text
 
 Add descriptive text below the picker with the `help-text` attribute.

package/docs/pages/components/input.md

@@ -136,7 +136,7 @@ the [Properties table](#properties) for the full list of options.
 
 #### Color Input
 
-The color input type displays a clickable color swatch on the left that opens the browser's native color picker. The color value is shown as editable text in the input field, allowing users to either pick a color visually or enter a color value directly.
+The color input type displays a clickable color swatch on the right that opens the browser's native color picker. The color value is shown as editable text in the input field, allowing users to either pick a color visually or enter a color value directly.
 
 Use the `color-format` attribute to specify the format: `hex` (default), `rgb`, or `oklch`.
 
@@ -159,6 +159,24 @@ Use the `color-format` attribute to specify the format: `hex` (default), `rgb`,
 <br />
 ```
 
+#### Range Input
+
+The range input type renders as a bare track with no field chrome. The current value is displayed above the track, on
+the right, and updates as the thumb is dragged. Use `value-suffix` to append a unit to that value, and `min`, `max` and
+`step` to control the range.
+
+```html:preview
+<zn-input type="range" label="Base radius" min="0" max="2" step="0.125" value="0.5" value-suffix="rem"></zn-input>
+<br />
+<zn-input type="range" label="Volume" min="0" max="100" value="70" value-suffix="%">
+  <div slot="help-text">Set <code>context-note</code> to replace the value readout with your own text.</div>
+</zn-input>
+<br />
+<zn-input type="range" label="Small" size="small" min="0" max="10" value="4"></zn-input>
+<br />
+<zn-input type="range" label="Disabled" min="0" max="10" value="4" disabled></zn-input>
+```
+
 #### Other Input Types
 
 ```html:preview

package/docs/pages/components/theme-editor.md

@@ -29,8 +29,9 @@ The preview always fills its column, leaving no dead space beneath it.
 it's still forwarded to the [preview frame](/components/preview-frame/), which
 uses it the same way.
 
-Controls can be organized into tabs with collapsible groups inside each —
-`sections` with `groups` below is the canonical arrangement:
+Controls organize themselves into tabs with collapsible groups inside each:
+give each one a `group` and a `category` and the editor builds the structure
+around them, no slot names required.
 
 ```html:preview
 <zn-theme-editor
@@ -38,19 +39,10 @@ Controls can be organized into tabs with collapsible groups inside each —
   src="/components/preview-frame-demo/"
   min-height="420"
   controls-caption="Theme Builder"
-  preview-caption="Live Preview"
-  sections='[
-    {"name":"colors","caption":"Colors","groups":[
-      {"name":"brand","caption":"Brand","open":true},
-      {"name":"background","caption":"Background"}
-    ]},
-    {"name":"shapes","caption":"Shapes","groups":[
-      {"name":"radius","caption":"Radius"}
-    ]}
-  ]'>
-  <zn-input slot="brand" name="accent" label="Accent" value="#6936f5" dark-value="#f5c542" type="color"></zn-input>
-  <zn-input slot="background" name="background" label="Background" value="#ffffff" dark-value="#18181b" type="color"></zn-input>
-  <zn-input slot="radius" name="radius" label="Corner radius" type="number" value="4"></zn-input>
+  preview-caption="Live Preview">
+  <zn-input group="Colors" category="Brand" name="accent" label="Accent" value="#6936f5" dark-value="#f5c542" type="color"></zn-input>
+  <zn-input group="Colors" category="Background" name="background" label="Background" value="#ffffff" dark-value="#18181b" type="color"></zn-input>
+  <zn-input group="Shapes" category="Radius" name="radius" label="Corner radius" type="number" value="4"></zn-input>
 </zn-theme-editor>
 
 <script>
@@ -172,9 +164,44 @@ Set the controls column width with `--zn-theme-editor-controls-width`
 (default `343px`, matching page-builder's palette). Below 768px the columns
 stack.
 
-## Grouping controls into tabs and collapsibles
+## Grouping controls with `group` and `category`
+
+The simplest way to structure an editor is to let the controls describe their
+own place in it. Leave `sections` unset and give each control a `group` (which
+becomes a tab) and a `category` (a collapsible inside that tab) — the editor
+builds the tabs and collapsibles from those labels and slots each control into
+the right one for you, so there are no slot names to keep in sync by hand:
+
+```html
+<zn-theme-editor src="/embed?t=..." frame-origin="https://pay.example">
+  <zn-color-select group="Background &amp; Foreground" category="Colors"
+                   name="background" label="Background" value="#ffffff"></zn-color-select>
+  <zn-color-select group="Background &amp; Foreground" category="Colors"
+                   name="foreground" label="Foreground" value="#18181b"></zn-color-select>
+  <zn-input group="Background &amp; Foreground" category="Spacing"
+            name="gap" label="Gap" type="number" value="8"></zn-input>
+  <zn-input group="Typography" category="Family"
+            name="font" label="Font" value="Inter"></zn-input>
+</zn-theme-editor>
+```
 
-Set `sections` to a JSON array of `{name, caption, groups}`. Each section
+That renders a **Background & Foreground** tab holding *Colors* and *Spacing*
+collapsibles, and a **Typography** tab holding *Family*. Labels are free text —
+they're slugged into slot names internally, and two tabs can each hold a
+category of the same name without colliding.
+
+Either attribute works on its own: a control with only `group` sits directly in
+its tab above any collapsibles, and one with only `category` becomes its own
+top-level section. A control with neither stays in the default slot, ungrouped
+above everything else. Tabs and collapsibles appear in the order the controls
+first mention them, and controls added after mount are derived and slotted the
+same way.
+
+### Declaring the structure explicitly with `sections`
+
+Set `sections` to take full control instead — it disables the attribute
+derivation entirely, and is the way to set a group's `description` or have it
+render `open`. It takes a JSON array of `{name, caption, groups}`. Each section
 becomes a `zn-tabs` tab; each entry in its `groups` — `{name, caption,
 description?, open?}` — becomes a collapsible inside that tab, and a control
 is assigned to a group with `slot="<group-name>"`:
@@ -200,6 +227,12 @@ config" rule flat sections already followed. Every tab's panel stays mounted
 while hidden (`zn-tabs` toggles visibility, never removes a panel), so
 switching tabs never drops a value out of the theme, a preview push or a save.
 
+The editor never shows a tab with everything shut: on load, and again whenever
+a tab is clicked, its first collapsible expands unless one in that tab is
+already open. `open: true` therefore only matters for picking *which* group
+opens — and closing them all yourself sticks, since nothing reopens until the
+next tab click.
+
 ### Flat sections (no groups)
 
 A section can omit `groups` and just take controls directly via
@@ -207,7 +240,8 @@ A section can omit `groups` and just take controls directly via
 then decides the presentation — stacked `zn-collapsible`s (`"collapsible"`,
 the default) or a `zn-tabs` strip (`"tabs"`) — and is otherwise ignored: once
 *any* section has a populated `groups`, every section renders as a nested tab
-regardless of `section-layout`.
+regardless of `section-layout`. Stacked sections get the same load-time
+expansion as tabs: the first one opens unless another already has `open`.
 
 ```html
 <zn-theme-editor

package/package.json

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

package/src/components/collapsible/collapsible.scss

@@ -60,13 +60,6 @@
   }
 }
 
-// flush means flush on every edge, matching zn-pane/zn-panel/zn-tabs; without
-// this the caption stays indented while the content sits at the edge.
-:host([flush]) .header {
-  padding-left: 0;
-  padding-right: 0;
-}
-
 :host([error-label]) {
   .header {
     .caption {
@@ -88,9 +81,6 @@
 }
 
 .content {
-  display: flex;
-  flex-direction: column;
-  gap: var(--zn-spacing-medium);
   transition: .1s all ease-out;
 }
 

package/src/components/file/file.component.ts

@@ -590,6 +590,21 @@ export default class ZnFile extends ZincElement implements ZincFormControl {
     this.emit('zn-clear');
   }
 
+  /**
+   * Programmatically clears the selected file and any external `src` without
+   * confirmation. Unlike a user-initiated clear, this does not flag the control
+   * to submit an empty value.
+   */
+  clear() {
+    if (this.input) {
+      this.input.value = '';
+    }
+    this.files = null;
+    this.src = '';
+    this.updatePreview();
+    this.formControlController.updateValidity();
+  }
+
   private updatePreview() {
     if (this.fileObjectUrl) {
       URL.revokeObjectURL(this.fileObjectUrl);

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

@@ -26,19 +26,27 @@ export default class ZnIconPicker extends ZincElement implements ZincFormControl
   };
 
   private readonly formControlController = new FormControlController(this, {
-    assumeInteractionOn: ['zn-change']
+    assumeInteractionOn: ['zn-change'],
+    // With allow-upload, a chosen file is submitted under `name` in place of
+    // the icon string — the two are mutually exclusive.
+    value: (el: ZnIconPicker) => el._file ?? el.icon
   });
 
   @property() name = '';
   @property() icon = '';
   @property() label = '';
-  @property() library: string = 'material';
+  // Matches zn-icon's defaultLibrary so the picked icon previews the same way
+  // it will render wherever the stored name is displayed.
+  @property() library: string = 'material-symbols-outlined';
   @property() color: string = '';
   @property({type: Boolean, attribute: 'no-color'}) noColor: boolean = false;
   @property({type: Boolean, attribute: 'no-library'}) noLibrary: boolean = false;
   @property({attribute: 'help-text'}) helpText: string = '';
   @property({type: Boolean, reflect: true}) disabled = false;
   @property({type: Boolean, reflect: true}) required = false;
+  @property({type: Boolean, attribute: 'trigger-submit'}) triggerSubmit = false;
+  @property({type: Boolean, attribute: 'allow-upload'}) allowUpload = false;
+  @property() accept = 'image/*';
   @property({reflect: true}) form: string;
 
   @defaultValue() defaultValue = '';
@@ -52,8 +60,16 @@ export default class ZnIconPicker extends ZincElement implements ZincFormControl
   @state() private _pendingIcon = '';
   @state() private _pendingLibrary = '';
   @state() private _pendingColor = '';
+  @state() private _pendingFile: File | null = null;
+  @state() private _pendingFileUrl: string | null = null;
+  @state() private _mode: 'icon' | 'upload' = 'icon';
+
+  // Committed upload (allow-upload mode)
+  @state() private _file: File | null = null;
+  @state() private _fileUrl: string | null = null;
 
   @query('zn-dialog') private _dialog: ZnDialog;
+  @query('.icon-picker__file-input') private _fileInput: HTMLInputElement;
 
   get value(): string {
     return this.icon;
@@ -63,8 +79,18 @@ export default class ZnIconPicker extends ZincElement implements ZincFormControl
     this.icon = val;
   }
 
+  /** The chosen file when the user uploaded an image instead of picking an icon. */
+  get file(): File | null {
+    return this._file;
+  }
+
+  /** True when the current value renders as an image (an uploaded file or a URL) rather than a library icon. */
+  get isImageValue(): boolean {
+    return !!this._file || this.icon.includes('/');
+  }
+
   get validity(): ValidityState {
-    if (this.required && !this.icon) {
+    if (this.required && !this.icon && !this._file) {
       return {
         valid: false,
         valueMissing: true,
@@ -81,7 +107,7 @@ export default class ZnIconPicker extends ZincElement implements ZincFormControl
   }
 
   get validationMessage(): string {
-    return this.required && !this.icon ? 'Please select an icon.' : '';
+    return this.required && !this.icon && !this._file ? 'Please select an icon.' : '';
   }
 
   checkValidity(): boolean { return this.validity.valid; }
@@ -129,10 +155,11 @@ export default class ZnIconPicker extends ZincElement implements ZincFormControl
   }
 
   private async openDialog() {
-    this._pendingIcon = this.icon;
+    this._pendingIcon = this.isImageValue ? '' : this.icon;
     this._pendingLibrary = this.library;
     this._pendingColor = this.color;
     this._searchQuery = '';
+    this._mode = this.allowUpload && this.isImageValue ? 'upload' : 'icon';
     this._iconList = await this.getIconsForLibrary(this.library);
     this._filteredIcons = this._iconList.slice(0, 200);
     this._dialogOpen = true;
@@ -142,22 +169,74 @@ export default class ZnIconPicker extends ZincElement implements ZincFormControl
   }
 
   private closeDialog() {
+    this.discardPendingFile();
     this._dialog.hide();
     this._dialogOpen = false;
   }
 
   private handleConfirm() {
-    this.icon = this._pendingIcon;
-    this.library = this._pendingLibrary;
-    this.color = this._pendingColor;
+    if (this._mode === 'upload') {
+      if (this._pendingFile) {
+        if (this._fileUrl) {
+          URL.revokeObjectURL(this._fileUrl);
+        }
+        this._file = this._pendingFile;
+        this._fileUrl = this._pendingFileUrl;
+        this._pendingFile = null;
+        this._pendingFileUrl = null;
+        this.icon = '';
+      }
+    } else {
+      this.icon = this._pendingIcon;
+      this.library = this._pendingLibrary;
+      this.color = this._pendingColor;
+      this.clearFile();
+    }
     this.closeDialog();
     this.emit('zn-change');
+    if (this.triggerSubmit) {
+      this.formControlController.submit();
+    }
   }
 
   private handleCancel() {
     this.closeDialog();
   }
 
+  private handleFileSelect(e: Event) {
+    const input = e.target as HTMLInputElement;
+    const file = input.files?.[0] ?? null;
+    if (!file) return;
+    this.discardPendingFile();
+    this._pendingFile = file;
+    this._pendingFileUrl = URL.createObjectURL(file);
+    input.value = '';
+  }
+
+  private discardPendingFile() {
+    if (this._pendingFileUrl) {
+      URL.revokeObjectURL(this._pendingFileUrl);
+    }
+    this._pendingFile = null;
+    this._pendingFileUrl = null;
+  }
+
+  private clearFile() {
+    if (this._fileUrl) {
+      URL.revokeObjectURL(this._fileUrl);
+    }
+    this._file = null;
+    this._fileUrl = null;
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    this.discardPendingFile();
+    if (this._fileUrl) {
+      URL.revokeObjectURL(this._fileUrl);
+    }
+  }
+
   private handleSearchInput(e: Event) {
     const input = e.target as HTMLInputElement;
     this._searchQuery = input.value.toLowerCase();
@@ -209,7 +288,11 @@ export default class ZnIconPicker extends ZincElement implements ZincFormControl
     e.stopPropagation();
     this.icon = '';
     this.color = '';
+    this.clearFile();
     this.emit('zn-change');
+    if (this.triggerSubmit) {
+      this.formControlController.submit();
+    }
   }
 
   private _handleTriggerClick() {
@@ -220,7 +303,12 @@ export default class ZnIconPicker extends ZincElement implements ZincFormControl
   render() {
     const hasLabel = !!this.label;
     const hasHelpText = !!this.helpText;
-    const hasIcon = !!this.icon;
+    const hasValue = !!this.icon || !!this._file;
+    // Image values (uploaded file or URL) omit the library so zn-icon's URL
+    // auto-detection renders an <img> instead of a font ligature.
+    const triggerIcon = this._fileUrl ?? this.icon;
+    const triggerLibrary = hasValue && !this.isImageValue ? this.library : nothing;
+    const pendingPreviewUrl = this._pendingFileUrl ?? (this.isImageValue && !this._file ? this.icon : this._fileUrl);
 
     return html`
       <div part="form-control"
@@ -236,15 +324,15 @@ export default class ZnIconPicker extends ZincElement implements ZincFormControl
             part="trigger"
             class="icon-picker__trigger"
             panel-bg
-            icon=${hasIcon ? this.icon : nothing}
-            icon-library=${hasIcon ? this.library : nothing}
-            icon-color=${(hasIcon && this.color) || nothing}
+            icon=${hasValue ? triggerIcon : nothing}
+            icon-library=${triggerLibrary}
+            icon-color=${(hasValue && !this.isImageValue && this.color) || nothing}
             icon-size="24"
             ?disabled=${this.disabled}
             @click=${this._handleTriggerClick}>
-            ${hasIcon ? 'Click to edit' : 'Set an icon'}
+            ${hasValue ? 'Click to edit' : 'Set an icon'}
           </zn-button>
-          ${hasIcon ? html`
+          ${hasValue ? html`
             <zn-button
               class="icon-picker__clear"
               color="transparent"
@@ -272,6 +360,38 @@ export default class ZnIconPicker extends ZincElement implements ZincFormControl
           <zn-dialog size="custom" label="Select Icon" @zn-close=${this.handleCancel}>
             <div class="icon-picker__dialog-layout">
               <div class="icon-picker__dialog-main">
+                ${this.allowUpload ? html`
+                  <div class="icon-picker__mode-switch">
+                    <zn-button
+                      size="small"
+                      color=${this._mode === 'icon' ? 'secondary' : 'transparent'}
+                      icon="apps"
+                      @click=${() => this._mode = 'icon'}>
+                      Icon Library
+                    </zn-button>
+                    <zn-button
+                      size="small"
+                      color=${this._mode === 'upload' ? 'secondary' : 'transparent'}
+                      icon="upload"
+                      @click=${() => this._mode = 'upload'}>
+                      Upload Image
+                    </zn-button>
+                  </div>
+                ` : nothing}
+
+                ${this._mode === 'upload' ? html`
+                  <div class="icon-picker__upload">
+                    <input class="icon-picker__file-input" type="file" accept=${this.accept} hidden
+                           @change=${this.handleFileSelect}>
+                    <zn-icon src="image" size="48"></zn-icon>
+                    ${this._pendingFile ? html`
+                      <span class="icon-picker__upload-filename">${this._pendingFile.name}</span>
+                    ` : nothing}
+                    <zn-button icon="upload" color="secondary" @click=${() => this._fileInput.click()}>
+                      ${pendingPreviewUrl ? 'Choose a different file' : 'Choose a file'}
+                    </zn-button>
+                  </div>
+                ` : html`
                 <div class="icon-picker__dialog-controls">
                   ${!this.noLibrary ? html`
                     <zn-select
@@ -354,10 +474,21 @@ export default class ZnIconPicker extends ZincElement implements ZincFormControl
                     `)}
                   </div>
                 `}
+                `}
               </div>
 
               <div class="icon-picker__dialog-sidebar">
-                ${this._pendingIcon ? html`
+                ${this._mode === 'upload' ? html`
+                  <div class="icon-picker__preview ${pendingPreviewUrl ? '' : 'icon-picker__preview--empty'}">
+                    ${pendingPreviewUrl ? html`
+                      <img class="icon-picker__upload-preview" src=${pendingPreviewUrl} alt="">
+                      <span class="icon-picker__preview-name">${this._pendingFile?.name ?? ''}</span>
+                    ` : html`
+                      <zn-icon src="image" size="48"></zn-icon>
+                      <span class="icon-picker__preview-hint">Choose an image</span>
+                    `}
+                  </div>
+                ` : this._pendingIcon ? html`
                   <div class="icon-picker__preview">
                     <zn-icon
                       src=${this._pendingIcon}
@@ -379,7 +510,10 @@ export default class ZnIconPicker extends ZincElement implements ZincFormControl
 
             <div slot="footer">
               <zn-button color="default" @click=${this.handleCancel}>Cancel</zn-button>
-              <zn-button color="primary" @click=${this.handleConfirm} ?disabled=${!this._pendingIcon}>Confirm</zn-button>
+              <zn-button color="primary" @click=${this.handleConfirm}
+                         ?disabled=${this._mode === 'upload' ? !this._pendingFile && !this.isImageValue : !this._pendingIcon}>
+                Confirm
+              </zn-button>
             </div>
           </zn-dialog>
         ` : nothing}

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

@@ -60,6 +60,38 @@ zn-dialog {
   }
 }
 
+.icon-picker__mode-switch {
+  display: flex;
+  gap: var(--zn-spacing-x-small);
+  margin-bottom: var(--zn-spacing-small);
+}
+
+.icon-picker__upload {
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: var(--zn-spacing-small);
+  border: dashed 1px rgb(var(--zn-border-color));
+  border-radius: var(--zn-border-radius);
+  padding: var(--zn-spacing-large);
+  color: rgb(var(--zn-text-muted));
+}
+
+.icon-picker__upload-preview {
+  max-width: 100%;
+  max-height: 160px;
+  object-fit: contain;
+  border-radius: var(--zn-border-radius);
+}
+
+.icon-picker__upload-filename {
+  font-size: var(--zn-font-size-small);
+  color: rgb(var(--zn-text-muted));
+  word-break: break-all;
+}
+
 .icon-picker__dialog-controls {
   display: flex;
   gap: var(--zn-spacing-small);