@kubex/zinc 1.1.94 → 1.1.96

package/src/components/inline-edit/inline-edit.component.ts

@@ -117,12 +117,15 @@ export default class ZnInlineEdit extends ZincElement implements ZincFormControl
   /** The characters that open the slash menu. */
   @property({ attribute: 'slash-trigger' }) slashTrigger = '/';
 
-  /** The heading shown above the slash menu's items. */
+  /** The name the slash menu's list is announced by. */
   @property({ attribute: 'slash-heading' }) slashHeading = 'Insert';
 
   /** Hides the insertion keys normally shown against the slash menu's items. */
   @property({ attribute: 'slash-hide-keys', type: Boolean }) slashHideKeys = false;
 
+  /** Lists the slash menu items most recently chosen here above the rest, remembered under this key. */
+  @property({ attribute: 'slash-recent-key' }) slashRecentKey = '';
+
   /** Resolves additional slash menu items each time the menu opens. JavaScript only. */
   @property({ attribute: false }) slashItemsProvider?: (query: string) => SlashMenuItem[] | Promise<SlashMenuItem[]>;
 
@@ -466,6 +469,7 @@ export default class ZnInlineEdit extends ZincElement implements ZincFormControl
         slash-trigger="${this.slashTrigger}"
         slash-heading="${this.slashHeading}"
         slash-preset="${this.slashPreset}"
+        slash-recent-key="${this.slashRecentKey}"
         ?slash-hide-keys="${this.slashHideKeys}"
         .slashItems="${this.slashItems}"
         .slashItemsProvider="${this.slashItemsProvider}"
@@ -489,6 +493,7 @@ export default class ZnInlineEdit extends ZincElement implements ZincFormControl
                 slash-trigger="${this.slashTrigger}"
                 slash-heading="${this.slashHeading}"
                 slash-preset="${this.slashPreset}"
+                slash-recent-key="${this.slashRecentKey}"
                 ?slash-hide-keys="${this.slashHideKeys}"
                 .slashItems="${this.slashItems}"
                 .slashItemsProvider="${this.slashItemsProvider}"

package/src/components/input/input.component.ts

@@ -276,12 +276,18 @@ export default class ZnInput extends ZincElement implements ZincFormControl {
   /** The characters that open the slash menu. */
   @property({attribute: 'slash-trigger'}) slashTrigger = '/';
 
-  /** The heading shown above the slash menu's items. */
+  /** The name the slash menu's list is announced by. */
   @property({attribute: 'slash-heading'}) slashHeading = 'Insert';
 
   /** Hides the insertion keys normally shown against the slash menu's items. */
   @property({attribute: 'slash-hide-keys', type: Boolean}) slashHideKeys = false;
 
+  /**
+   * Lists the items most recently chosen here above the rest, remembered in `localStorage` under this
+   * key. Share a key between the fields that should share a history; leave unset to offer no such list.
+   */
+  @property({attribute: 'slash-recent-key'}) slashRecentKey = '';
+
   /**
    * Resolves additional items each time the menu opens, for lists that come from elsewhere (e.g. an
    * API). Receives the current query and may return a promise. JavaScript only.
@@ -1100,7 +1106,11 @@ export default class ZnInput extends ZincElement implements ZincFormControl {
           </div>
           ${this.hasSlashMenu
             ? html`
-              <zn-slash-menu part="slash-menu" heading=${this.slashHeading} ?hide-keys=${this.slashHideKeys}></zn-slash-menu>`
+              <zn-slash-menu
+                part="slash-menu"
+                heading=${this.slashHeading}
+                recent-key=${this.slashRecentKey}
+                ?hide-keys=${this.slashHideKeys}></zn-slash-menu>`
             : ''}
           <slot name="slash-menu"></slot>
           <slot name="slash-items" hidden></slot>

package/src/components/page/page.scss

@@ -93,8 +93,13 @@
     background-repeat: no-repeat;
     background-position: bottom center;
     background-size: cover;
-    mix-blend-mode: color-burn;
-    opacity: 0.2;
+    // PERF: mix-blend-mode forces .page__header .header — which contains the tab
+    // navbar — into its own render surface with a backdrop readback. Dropped in
+    // favour of plain alpha compositing. This is a small visual change to the
+    // aurora wave (it no longer darkens what it sits on); restore the blend mode
+    // if the look regresses, but expect the GPU cost back with it.
+    //mix-blend-mode: color-burn;
+    opacity: 0.04;
     pointer-events: none;
   }
 

package/src/components/page-builder/modules/page-section-card/page-section-card.component.ts

@@ -39,6 +39,8 @@ export default class ZnPageSectionCard extends ZincElement {
   @property({type: Boolean, reflect: true}) selected = false;
   /** Set when the section's type has no registered template — renders greyed. */
   @property({type: Boolean, reflect: true}) unknown = false;
+  /** Set when the builder pins this section to the page — drops the remove action. */
+  @property({type: Boolean, reflect: true}) locked = false;
 
   protected updated(changed: PropertyValues) {
     super.updated(changed);
@@ -67,6 +69,10 @@ export default class ZnPageSectionCard extends ZincElement {
           <span class="card__label">${this.label}</span>
           ${this.summary ? html`<span class="card__summary">${this.summary}</span>` : ''}
         </span>
+        ${this.locked ? html`
+          <span class="card__lock" title="This section cannot be removed">
+            <zn-icon src="lock" size="14"></zn-icon>
+          </span>` : ''}
         <span class="card__actions" @keydown="${this._actionKeydown}">
           <zn-button
             class="card__action"
@@ -77,15 +83,16 @@ export default class ZnPageSectionCard extends ZincElement {
             title="Duplicate section"
             aria-label="Duplicate section"
             @click="${(e: Event) => this._action(e, 'page-card-duplicate')}"></zn-button>
-          <zn-button
-            class="card__action"
-            icon-button="small"
-            plain
-            icon="delete"
-            icon-size="14"
-            title="Remove section"
-            aria-label="Remove section"
-            @click="${(e: Event) => this._action(e, 'page-card-remove')}"></zn-button>
+          ${this.locked ? '' : html`
+            <zn-button
+              class="card__action"
+              icon-button="small"
+              plain
+              icon="delete"
+              icon-size="14"
+              title="Remove section"
+              aria-label="Remove section"
+              @click="${(e: Event) => this._action(e, 'page-card-remove')}"></zn-button>`}
         </span>
       </div>
     `;

package/src/components/page-builder/modules/page-section-card/page-section-card.scss

@@ -15,6 +15,11 @@
   cursor: grabbing;
 }
 
+:host([locked]),
+:host([locked]:active) {
+  cursor: default;
+}
+
 .card {
   display: flex;
   align-items: center;
@@ -77,6 +82,14 @@
   text-overflow: ellipsis;
 }
 
+// Always visible, unlike the hover actions — it is what explains their absence.
+.card__lock {
+  display: flex;
+  flex: 0 0 auto;
+  align-items: center;
+  opacity: 0.45;
+}
+
 // Space is always reserved (visibility, not display) so the card never
 // changes size or shifts its text when the actions appear on hover.
 .card__actions {

package/src/components/page-builder/modules/page-section-card/page-section-card.test.ts

@@ -41,6 +41,15 @@ describe('<zn-page-section-card>', () => {
     expect(hostSawKeydown, 'host keydown suppressed for button activation keys').to.be.false;
   });
 
+  it('should drop the remove action and show a lock when locked', async () => {
+    const el = await fixture<ZnPageSectionCard>(html`
+      <zn-page-section-card label="Hero" locked></zn-page-section-card>`);
+    expect(el.hasAttribute('locked')).to.be.true;
+    expect(el.shadowRoot!.querySelector('zn-button[title="Remove section"]'), 'remove gone').to.not.exist;
+    expect(el.shadowRoot!.querySelector('zn-button[title="Duplicate section"]'), 'duplicate kept').to.exist;
+    expect(el.shadowRoot!.querySelector('.card__lock'), 'lock indicator').to.exist;
+  });
+
   it('should reflect selected and unknown states', async () => {
     const el = await fixture<ZnPageSectionCard>(html`
       <zn-page-section-card label="Hero" selected unknown></zn-page-section-card>`);

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

@@ -105,6 +105,14 @@ export default class ZnPageBuilder extends ZincElement {
   @property({ reflect: true }) heading = '';
   @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.
+   */
+  @property({ attribute: 'required-first', reflect: true }) requiredFirst = '';
+
   /** Section types to make available, registered into the internal registry. */
   @property({ attribute: false }) sectionTypes: PageSectionType[] = [];
 
@@ -224,6 +232,15 @@ export default class ZnPageBuilder extends ZincElement {
     }
   }
 
+  // Idempotent, so it does not matter whether this or handleConfigChange runs first.
+  @watch('requiredFirst')
+  handleRequiredFirstChange() {
+    const sections = this._requireFirst(this._state.sections);
+    if (sections === this._state.sections) return;
+    this._state = { sections };
+    this.defaultValue = JSON.stringify(this._state);
+  }
+
   @watch('sectionTypes')
   handleSectionTypesChange() {
     this.registry.registerAll(this.sectionTypes ?? []);
@@ -450,13 +467,48 @@ export default class ZnPageBuilder extends ZincElement {
     }
     this._history = [];
     this._redoStack = [];
-    this._state = { sections };
+    this._state = { sections: this._requireFirst(sections) };
     this.defaultValue = JSON.stringify(this._state);
     this._selectedId = null;
     this._pickerIndex = null;
     this._offerRestoreIfNewer();
   }
 
+  // --- The pinned leading section (`required-first`) ---------------------------
+
+  /**
+   * Id of the section pinned to the top of the page, or null when `required-first`
+   * is unset. Derived from the state rather than stored on it, so nothing about the
+   * lock leaks into the persisted config.
+   */
+  private get _pinnedId(): string | null {
+    const first = this._state.sections[0];
+    return this.requiredFirst && first?.type === this.requiredFirst ? first.id : null;
+  }
+
+  private _isPinned(id: string): boolean {
+    return this._pinnedId === id;
+  }
+
+  /** 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
+   * 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 hoisted = [...sections];
+    hoisted.unshift(...hoisted.splice(at, 1));
+    return hoisted;
+  }
+
   /** Finds a section by id, searching top-level sections and slotted children. */
   private _findSection(id: string | null): PageSection | undefined {
     if (!id) return undefined;
@@ -551,7 +603,7 @@ export default class ZnPageBuilder extends ZincElement {
     this._pushHistory();
     const section: PageSection = { id: generateSectionId(), type, data: {} };
     const sections = [...this._state.sections];
-    sections.splice(index ?? sections.length, 0, section);
+    sections.splice(Math.max(index ?? sections.length, this._firstFreeIndex), 0, section);
     this._commit({ sections });
     this._select(section.id);
     return section;
@@ -576,6 +628,7 @@ export default class ZnPageBuilder extends ZincElement {
   }
 
   private _removeSection(id: string) {
+    if (this._isPinned(id)) return;
     const [removed, sections] = this._extract(id);
     if (!removed) return;
     this._pushHistory();
@@ -620,6 +673,8 @@ export default class ZnPageBuilder extends ZincElement {
 
   /** Moves a section (top-level or slotted) to a top-level position. */
   private _moveSection(id: string, index: number) {
+    if (this._isPinned(id)) return;
+    index = Math.max(index, this._firstFreeIndex);
     const from = this._state.sections.findIndex(s => s.id === id);
     if (from !== -1) {
       const to = index > from ? index - 1 : index;
@@ -648,6 +703,7 @@ export default class ZnPageBuilder extends ZincElement {
     const container = this._findSection(containerId);
     const containerType = container ? this.registry.get(container.type) : undefined;
     if (!moved || !container || !containerType?.slots || id === containerId) return;
+    if (this._isPinned(id)) return; // the pinned section stays at the top of the page
     if (this.registry.get(moved.type)?.slots) return; // no containers inside slots
     if (containerType.accepts && !containerType.accepts.includes(moved.type)) return;
     if (slotIndex < 0 || slotIndex >= containerType.slots) return;
@@ -866,7 +922,7 @@ export default class ZnPageBuilder extends ZincElement {
               Drag sections here to build your page
             </div>` : ''}
           ${sections.map((section, i) => html`
-            ${this._renderDropZone(i)}
+            ${i === 0 && this._pinnedId !== null ? '' : this._renderDropZone(i)}
             ${this._renderCard(section, i)}
           `)}
           ${this._renderDropZone(sections.length)}
@@ -881,10 +937,11 @@ export default class ZnPageBuilder extends ZincElement {
     extraClass = ''
   ) {
     const type = this.registry.get(section.type);
+    const pinned = this._isPinned(section.id);
     return html`
       <zn-page-section-card
         class="${extraClass}"
-        draggable="true"
+        draggable="${pinned ? 'false' : 'true'}"
         tabindex="0"
         label="${section.label ?? type?.label ?? section.type}"
         summary="${type ? sectionSummary(section, type) : `Unknown type "${section.type}"`}"
@@ -893,6 +950,7 @@ export default class ZnPageBuilder extends ZincElement {
         color="${ifDefined(type?.color)}"
         ?selected="${this._selectedId === section.id}"
         ?unknown="${!type}"
+        ?locked="${pinned}"
         @click="${(e: Event) => {
           e.stopPropagation();
           this._select(section.id);

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

@@ -1,5 +1,6 @@
 import '../../../dist/zn.min.js';
 import {expect, fixture, html} from '@open-wc/testing';
+import type {PageState} from './page.types';
 import type ZnPageBuilder from './page-builder.component';
 
 describe('<zn-page-builder>', () => {
@@ -575,6 +576,99 @@ describe('<zn-page-builder>', () => {
     expect(el.state.sections[0].children?.[0] ?? null, 'Delete removes the child').to.be.null;
   });
 
+  it('should pin a required-first section, inserting one when the page has none', async () => {
+    const el = await fixture<ZnPageBuilder>(html`
+      <zn-page-builder required-first="hero">
+        <template type="hero" slot="config" label="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.type), 'inserted into an empty page').to.deep.equal(['hero']);
+    // The submitted value carries the pinned section, so a save can't miss it.
+    expect((JSON.parse(el.value) as PageState).sections).to.have.length(1);
+
+    const card = el.shadowRoot!.querySelector('zn-page-section-card')!;
+    expect(card.hasAttribute('locked'), 'card is locked').to.be.true;
+    expect(card.getAttribute('draggable'), 'card is not draggable').to.equal('false');
+    // No "+" strip above it — the first drop zone follows the pinned card.
+    expect(el.shadowRoot!.querySelector('.canvas > *')?.tagName.toLowerCase()).to.equal('zn-page-section-card');
+  });
+
+  it('should hoist an existing required-first section to the top of the page', async () => {
+    const el = await fixture<ZnPageBuilder>(html`
+      <zn-page-builder required-first="hero"
+                       config='{"sections":[{"id":"t","type":"rich-text","data":{}},{"id":"h","type":"hero","data":{"title":"Help"}}]}'>
+        <template type="hero" slot="config" label="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)).to.deep.equal(['h', 't']);
+    expect(el.state.sections[0].data, 'hoisted with its data intact').to.deep.equal({title: 'Help'});
+  });
+
+  it('should refuse to remove, reorder or displace the pinned section', async () => {
+    const el = await fixture<ZnPageBuilder>(html`
+      <zn-page-builder required-first="hero"
+                       config='{"sections":[{"id":"h","type":"hero","data":{}},{"id":"t","type":"rich-text","data":{}}]}'>
+        <template type="hero" slot="config" label="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.shadowRoot!.querySelector('zn-button[title="Remove section"]'), 'no remove action').to.not.exist;
+
+    pinnedCard.dispatchEvent(new CustomEvent('page-card-remove', {bubbles: true, composed: true}));
+    pinnedCard.dispatchEvent(new KeyboardEvent('keydown', {key: 'Delete', bubbles: true, cancelable: true}));
+    await el.updateComplete;
+    expect(el.state.sections.map(s => s.id), 'survives remove and Delete').to.deep.equal(['h', 't']);
+
+    // Dropping another section on the topmost zone lands it below the pinned one.
+    const dataTransfer = new DataTransfer();
+    dataTransfer.setData('application/x-zn-page-section', 't');
+    el.shadowRoot!.querySelector('.drop')!
+      .dispatchEvent(new DragEvent('drop', {dataTransfer, bubbles: true, cancelable: true}));
+    await el.updateComplete;
+    expect(el.state.sections.map(s => s.id), 'nothing lands above the pinned section').to.deep.equal(['h', 't']);
+
+    expect(el.addSection('rich-text', 0)).to.not.be.null;
+    expect(el.state.sections[0].id, 'addSection index 0 is clamped').to.equal('h');
+  });
+
+  it('should keep the pinned section out of container slots', async () => {
+    const el = await fixture<ZnPageBuilder>(html`
+      <zn-page-builder required-first="hero"
+                       config='{"sections":[{"id":"h","type":"hero","data":{}},{"id":"grid","type":"article-grid","data":{}}]}'>
+        <template type="hero" slot="config" label="Hero"></template>
+        <template type="article-grid" slot="config" label="Article Grid" slots="2"></template>
+      </zn-page-builder>`);
+    await el.updateComplete;
+
+    const dataTransfer = new DataTransfer();
+    dataTransfer.setData('application/x-zn-page-section', 'h');
+    el.shadowRoot!.querySelector('.slot--empty')!
+      .dispatchEvent(new DragEvent('drop', {dataTransfer, bubbles: true, cancelable: true}));
+    await el.updateComplete;
+
+    expect(el.state.sections[0].id, 'still leading the page').to.equal('h');
+    expect(el.state.sections[1].children?.[0] ?? null, 'slot left empty').to.be.null;
+  });
+
+  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":{}}]}'>
+        <template type="rich-text" slot="config" label="Rich Text"></template>
+      </zn-page-builder>`);
+    await el.updateComplete;
+
+    expect(el.state.sections.map(s => s.type)).to.deep.equal(['rich-text']);
+    const card = el.shadowRoot!.querySelector('zn-page-section-card')!;
+    expect(card.hasAttribute('locked')).to.be.false;
+    expect(card.getAttribute('draggable')).to.equal('true');
+  });
+
   it('should accept a palette drop anywhere on the empty canvas', async () => {
     const el = await fixture<ZnPageBuilder>(html`
       <zn-page-builder>