@kubex/zinc 1.1.153 → 1.1.155

package/docs/pages/components/panel.md

@@ -8,7 +8,7 @@ layout: component
 Panels are a fundamental component in the Zinc framework, providing a structured container for displaying content with consistent styling, borders, and spacing. They support various layouts including headers with actions and footers.
 
 ```html:preview
-<zn-panel caption="Example Panel" description="Full example with all features" flush tabbed>
+<zn-panel caption="Example Panel" flush tabbed>
   <!-- Panel actions -->
   <zn-chip slot="actions" icon="home">Awesome</zn-chip>
   <zn-chip slot="actions" icon="phone" type="info">example</zn-chip>
@@ -42,10 +42,10 @@ Panels are a fundamental component in the Zinc framework, providing a structured
 
 ### Basic Panel
 
-Basic panels provide a simple container with consistent borders, rounded corners, and background styling. The panel can display a caption and description in its header.
+Basic panels provide a simple container with consistent borders, rounded corners, and background styling. The panel can display a caption in its header.
 
 ```html:preview
-<zn-panel caption="Example Panel" description="Simple panels are the best">
+<zn-panel caption="Example Panel">
   <div>Panel Content</div>
 </zn-panel>
 ```
@@ -55,7 +55,7 @@ Basic panels provide a simple container with consistent borders, rounded corners
 Use the `icon` attribute to add an icon to the panel header.
 
 ```html:preview
-<zn-panel caption="Settings Panel" description="Configure your preferences" icon="settings">
+<zn-panel caption="Settings Panel" icon="settings">
   <div style="padding: 20px;">
     <p>Panel content goes here</p>
   </div>
@@ -67,7 +67,7 @@ Use the `icon` attribute to add an icon to the panel header.
 Use the `actions` slot to add action buttons or chips to the panel header.
 
 ```html:preview
-<zn-panel caption="Project Details" description="Manage your project">
+<zn-panel caption="Project Details">
   <zn-chip slot="actions" icon="edit" type="info">Edit</zn-chip>
   <zn-chip slot="actions" icon="delete" type="error">Delete</zn-chip>
 
@@ -99,7 +99,7 @@ Use the `footer` slot to add footer content to the panel.
 Panel headers include a border by default. Use the `header-borderless` attribute to remove the border beneath the header.
 
 ```html:preview
-<zn-panel caption="Borderless Header" description="Without a visible separator" header-borderless>
+<zn-panel caption="Borderless Header" header-borderless>
   <div style="padding: 20px;">
     <p>Panel content with a borderless header</p>
   </div>
@@ -192,7 +192,7 @@ Use the `tabbed` attribute for panels containing tabs. This automatically remove
 Use the `transparent` attribute to remove the panel background and border, creating a borderless container.
 
 ```html:preview
-<zn-panel caption="Transparent Panel" description="No background or border" transparent>
+<zn-panel caption="Transparent Panel" transparent>
   <div style="padding: 20px; background: rgba(var(--zn-color-info), 0.1);">
     Content in transparent panel
   </div>
@@ -204,7 +204,7 @@ Use the `transparent` attribute to remove the panel background and border, creat
 Use the `shadow` attribute to add a prominent drop shadow to the panel.
 
 ```html:preview
-<zn-panel caption="Shadow Panel" description="With drop shadow effect" shadow>
+<zn-panel caption="Shadow Panel" shadow>
   <div style="padding: 20px;">
     Content with enhanced shadow
   </div>
@@ -284,7 +284,6 @@ All panel features can be combined to create rich, complex layouts.
 ```html:preview
 <zn-panel
   caption="Advanced Panel"
-  description="Combining multiple features"
   icon="dashboard"
   shadow>
 

package/package.json

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

package/src/components/page-builder/page-builder.component.ts

@@ -24,8 +24,10 @@ import ZincElement from '../../internal/zinc-element';
 import ZnCollapsible from '../collapsible';
 import ZnIcon from '../icon';
 import ZnInput from '../input';
+import ZnOption from '../option';
 import ZnPagePaletteItem from './modules/page-palette-item';
 import ZnPageSectionCard from './modules/page-section-card';
+import ZnSelect from '../select';
 
 import styles from './page-builder.scss';
 
@@ -96,8 +98,10 @@ export default class ZnPageBuilder extends ZincElement {
     'zn-collapsible': ZnCollapsible,
     'zn-icon': ZnIcon,
     'zn-input': ZnInput,
+    'zn-option': ZnOption,
     'zn-page-palette-item': ZnPagePaletteItem,
     'zn-page-section-card': ZnPageSectionCard,
+    'zn-select': ZnSelect,
   };
 
   private readonly formControlController = new FormControlController(this);
@@ -115,10 +119,12 @@ export default class ZnPageBuilder extends ZincElement {
   @property({ reflect: true }) subheading = '';
 
   /**
-   * Section type key that must lead the page. The builder hoists an existing section of
-   * that type to the top, or inserts an empty one, and pins it there: it can't be
-   * removed, reordered or dragged into a slot, and nothing can be dropped above it.
-   * Its content stays fully editable in the inspector.
+   * Section type keys that may lead the page, comma separated. The builder hoists an
+   * existing section of any of them to the top, or inserts an empty one of the first,
+   * and pins it there: it can't be removed, reordered or dragged into a slot, and
+   * nothing can be dropped above it. Its content stays fully editable in the
+   * inspector, which offers a swap between the allowed types when there is more
+   * than one.
    */
   @property({ attribute: 'required-first', reflect: true }) requiredFirst = '';
 
@@ -520,27 +526,45 @@ export default class ZnPageBuilder extends ZincElement {
    */
   private get _pinnedId(): string | null {
     const first = this._state.sections[0];
-    return this.requiredFirst && first?.type === this.requiredFirst ? first.id : null;
+    const types = this._requiredFirstTypes;
+    return first && types.includes(first.type) ? first.id : null;
+  }
+
+  /** The types `required-first` allows to lead the page, in the order given. */
+  private get _requiredFirstTypes(): string[] {
+    return this.requiredFirst.split(',').map(t => t.trim()).filter(Boolean);
   }
 
   private _isPinned(id: string): boolean {
     return this._pinnedId === id;
   }
 
+  /**
+   * Whether the pinned section may be removed: only while another section can take
+   * the lead in its place, so the page is never left without one. It stays undraggable
+   * either way — the replacement arrives by removing this one, not by reordering.
+   */
+  private get _canUnpin(): boolean {
+    const types = this._requiredFirstTypes;
+    return this._state.sections.slice(1).some(s => types.includes(s.type));
+  }
+
   /** Lowest top-level index a section may be added or moved to. */
   private get _firstFreeIndex(): number {
     return this._pinnedId === null ? 0 : 1;
   }
 
   /**
-   * Sections reordered so `required-first` leads the page: an existing section of that
-   * type is hoisted to the front, otherwise an empty one is prepended. Returns the
+   * Sections reordered so `required-first` leads the page: an existing section of an
+   * allowed type is hoisted to the front, otherwise an empty one of the first type is
+   * prepended. Returns the
    * argument unchanged when there is nothing to do, so callers can compare by identity.
    */
   private _requireFirst(sections: PageSection[]): PageSection[] {
-    if (!this.requiredFirst || sections[0]?.type === this.requiredFirst) return sections;
-    const at = sections.findIndex(s => s.type === this.requiredFirst);
-    if (at === -1) return [{ id: generateSectionId(), type: this.requiredFirst, data: {} }, ...sections];
+    const types = this._requiredFirstTypes;
+    if (!types.length || types.includes(sections[0]?.type)) return sections;
+    const at = sections.findIndex(s => types.includes(s.type));
+    if (at === -1) return [{ id: generateSectionId(), type: types[0], data: {} }, ...sections];
     const hoisted = [...sections];
     hoisted.unshift(...hoisted.splice(at, 1));
     return hoisted;
@@ -693,7 +717,7 @@ export default class ZnPageBuilder extends ZincElement {
   }
 
   private _removeSection(id: string) {
-    if (this._isPinned(id)) return;
+    if (this._isPinned(id) && !this._canUnpin) return;
     const [removed, sections] = this._extract(id);
     if (!removed) return;
     this._pushHistory();
@@ -704,7 +728,8 @@ export default class ZnPageBuilder extends ZincElement {
     if (this._selectedId === id || removed.children?.some(c => c?.id === this._selectedId)) {
       this._select(null);
     }
-    this._commit({ sections });
+    // Removing the leading section hands the lead to the next one that may hold it.
+    this._commit({ sections: this._requireFirst(sections) });
   }
 
   private _duplicateSection(id: string) {
@@ -1139,6 +1164,7 @@ export default class ZnPageBuilder extends ZincElement {
   ) {
     const type = this.registry.get(section.type);
     const pinned = this._isPinned(section.id);
+    const locked = pinned && !this._canUnpin;
     return html`
       <zn-page-section-card
         class="${extraClass} ${this._draggingId === section.id ? 'dragging' : ''}"
@@ -1152,7 +1178,7 @@ export default class ZnPageBuilder extends ZincElement {
         color="${ifDefined(type?.color)}"
         ?selected="${this._selectedId === section.id}"
         ?unknown="${!type}"
-        ?locked="${pinned}"
+        ?locked="${locked}"
         @click="${(e: Event) => {
           e.stopPropagation();
           this._select(section.id);
@@ -1340,6 +1366,21 @@ export default class ZnPageBuilder extends ZincElement {
     this._commit({ sections: this._patchSection(id, s => ({ ...s, data: { ...s.data, ...patch } })) });
   }
 
+  /**
+   * Retypes the pinned section, keeping its id, name and data so the copy shared by
+   * the allowed types survives; keys the new type has no field for stay unread. The
+   * inspector form is stamped from the type's template, so it is rebuilt by hand —
+   * selection has not changed.
+   */
+  private _swapPinnedType(type: string) {
+    const id = this._pinnedId;
+    const section = this._findSection(id);
+    if (!id || !section || section.type === type || !this._requiredFirstTypes.includes(type)) return;
+    this._pushHistory();
+    this._commit({ sections: this._patchSection(id, s => ({ ...s, type })) });
+    this._buildInspectorForm();
+  }
+
   private _renameSection(id: string, label: string) {
     this._pushHistory();
     this._commit({ sections: this._patchSection(id, s => ({ ...s, label: label || undefined })) });
@@ -1380,6 +1421,22 @@ export default class ZnPageBuilder extends ZincElement {
     this._inspectorWidth = this._clampInspector((this._inspectorWidth ?? this._inspectorRect()) + step);
   };
 
+  /** Offered on the pinned section alone, and only where there is another type to take. */
+  private _renderSwapControl(section: PageSection) {
+    const types = this._requiredFirstTypes;
+    if (types.length < 2 || !this._isPinned(section.id)) return '';
+    return html`
+      <zn-select
+        class="inspector__swap"
+        label="Section type"
+        help-text="Swaps the section leading the page, keeping the settings both types share."
+        .value="${section.type}"
+        @zn-change="${(e: Event) => this._swapPinnedType(String((e.target as ZnSelect).value ?? ''))}">
+        ${types.map(t => html`
+          <zn-option value="${t}">${this.registry.get(t)?.label ?? t}</zn-option>`)}
+      </zn-select>`;
+  }
+
   private _renderInspector() {
     const section = this._selectedSection();
     if (!section) return html``;
@@ -1430,6 +1487,7 @@ export default class ZnPageBuilder extends ZincElement {
             label="Section name"
             .value="${section.label ?? type?.label ?? ''}"
             @zn-change="${(e: Event) => this._renameSection(section.id, String((e.target as ZnInput).value ?? ''))}"></zn-input>
+          ${this._renderSwapControl(section)}
           ${type?.slotsMax === undefined ? '' : html`
             <zn-input
               class="inspector__slots"

package/src/components/page-builder/page-builder.test.ts

@@ -988,6 +988,112 @@ describe('<zn-page-builder>', () => {
     expect(el.state.sections[1].children?.[0] ?? null, 'slot left empty').to.be.null;
   });
 
+  it('should accept any of several required-first types', async () => {
+    const el = await fixture<ZnPageBuilder>(html`
+      <zn-page-builder required-first="hero,hero-split"
+                       config='{"sections":[{"id":"t","type":"rich-text","data":{}},{"id":"h","type":"hero-split","data":{"title":"Help"}}]}'>
+        <template type="hero" slot="config" label="Hero"></template>
+        <template type="hero-split" slot="config" label="Split Hero"></template>
+        <template type="rich-text" slot="config" label="Rich Text"></template>
+      </zn-page-builder>`);
+    await el.updateComplete;
+
+    expect(el.state.sections.map(s => s.id), 'the alternate type is hoisted too').to.deep.equal(['h', 't']);
+    expect(el.shadowRoot!.querySelector('zn-page-section-card')!.hasAttribute('locked')).to.be.true;
+
+    const empty = await fixture<ZnPageBuilder>(html`
+      <zn-page-builder required-first="hero,hero-split">
+        <template type="hero" slot="config" label="Hero"></template>
+        <template type="hero-split" slot="config" label="Split Hero"></template>
+      </zn-page-builder>`);
+    await empty.updateComplete;
+    expect(empty.state.sections.map(s => s.type), 'an empty page gets the first type').to.deep.equal(['hero']);
+  });
+
+  it('should swap the pinned section for another allowed type, keeping its content', async () => {
+    const el = await fixture<ZnPageBuilder>(html`
+      <zn-page-builder required-first="hero,hero-split"
+                       config='{"sections":[{"id":"h","type":"hero","label":"Top","data":{"title":"Help","search":true}},{"id":"t","type":"rich-text","data":{}}]}'>
+        <template type="hero" slot="config" label="Hero"></template>
+        <template type="hero-split" slot="config" label="Split Hero">
+          <zn-input name="title"></zn-input>
+        </template>
+        <template type="rich-text" slot="config" label="Rich Text"></template>
+      </zn-page-builder>`);
+    await el.updateComplete;
+
+    el.shadowRoot!.querySelector('zn-page-section-card')!.dispatchEvent(new Event('click'));
+    await el.updateComplete;
+
+    const swap = el.shadowRoot!.querySelector<HTMLElement & { value: string }>('.inspector__swap')!;
+    expect(swap, 'swap control on the pinned section').to.exist;
+    expect([...swap.querySelectorAll('zn-option')].map(o => o.getAttribute('value')))
+      .to.deep.equal(['hero', 'hero-split']);
+
+    swap.value = 'hero-split';
+    swap.dispatchEvent(new CustomEvent('zn-change', {bubbles: true}));
+    await el.updateComplete;
+
+    const [pinned, rest] = el.state.sections;
+    expect(pinned.type, 'type swapped').to.equal('hero-split');
+    expect(pinned.id, 'same section').to.equal('h');
+    expect(pinned.label, 'keeps its name').to.equal('Top');
+    expect(pinned.data, 'keeps its content').to.deep.equal({title: 'Help', search: true});
+    expect(rest.id, 'the rest of the page is untouched').to.equal('t');
+    expect(el.shadowRoot!.querySelector('zn-page-section-card')!.hasAttribute('locked'), 'still pinned').to.be.true;
+
+    // The inspector now stamps the new type's fields, filled from the kept data.
+    const title = el.shadowRoot!.querySelector<HTMLInputElement>('.inspector__form [name="title"]');
+    expect(title?.value, 'inspector rebuilt for the new type').to.equal('Help');
+
+    el.undo();
+    await el.updateComplete;
+    expect(el.state.sections[0].type, 'undo puts the original type back').to.equal('hero');
+  });
+
+  it('should let the pinned section go once another may lead in its place', async () => {
+    const el = await fixture<ZnPageBuilder>(html`
+      <zn-page-builder required-first="hero,hero-split"
+                       config='{"sections":[{"id":"h","type":"hero","data":{}},{"id":"t","type":"rich-text","data":{}},{"id":"s","type":"hero-split","data":{}}]}'>
+        <template type="hero" slot="config" label="Hero"></template>
+        <template type="hero-split" slot="config" label="Split Hero"></template>
+        <template type="rich-text" slot="config" label="Rich Text"></template>
+      </zn-page-builder>`);
+    await el.updateComplete;
+
+    const pinnedCard = el.shadowRoot!.querySelector('zn-page-section-card')!;
+    expect(pinnedCard.hasAttribute('locked'), 'a replaceable hero shows no lock').to.be.false;
+    expect(pinnedCard.getAttribute('draggable'), 'but still cannot be dragged').to.equal('false');
+    expect(pinnedCard.shadowRoot!.querySelector('zn-button[title="Remove section"]'), 'remove offered').to.exist;
+
+    pinnedCard.dispatchEvent(new CustomEvent('page-card-remove', {bubbles: true, composed: true}));
+    await el.updateComplete;
+
+    expect(el.state.sections.map(s => s.id), 'the other hero takes the lead').to.deep.equal(['s', 't']);
+    const nowPinned = el.shadowRoot!.querySelector('zn-page-section-card')!;
+    expect(nowPinned.hasAttribute('locked'), 'the last hero locks again').to.be.true;
+
+    nowPinned.dispatchEvent(new CustomEvent('page-card-remove', {bubbles: true, composed: true}));
+    await el.updateComplete;
+    expect(el.state.sections.map(s => s.id), 'the last hero cannot go').to.deep.equal(['s', 't']);
+
+    el.undo();
+    await el.updateComplete;
+    expect(el.state.sections.map(s => s.id), 'undo brings the removed hero back').to.deep.equal(['h', 't', 's']);
+  });
+
+  it('should offer no swap control when only one type may lead', async () => {
+    const el = await fixture<ZnPageBuilder>(html`
+      <zn-page-builder required-first="hero" config='{"sections":[{"id":"h","type":"hero","data":{}}]}'>
+        <template type="hero" slot="config" label="Hero"></template>
+      </zn-page-builder>`);
+    await el.updateComplete;
+
+    el.shadowRoot!.querySelector('zn-page-section-card')!.dispatchEvent(new Event('click'));
+    await el.updateComplete;
+    expect(el.shadowRoot!.querySelector('.inspector__swap')).to.not.exist;
+  });
+
   it('should leave the page alone without required-first', async () => {
     const el = await fixture<ZnPageBuilder>(html`
       <zn-page-builder config='{"sections":[{"id":"t","type":"rich-text","data":{}}]}'>