@kubex/zinc 1.1.94 → 1.1.95

package/src/components/remarkd-editor/remarkd-editor.component.ts

@@ -28,6 +28,7 @@ interface BlockType {
   /** Where the caret lands within `prefix`. Defaults to the end. */
   caretOffset?: number;
   image?: boolean;
+  include?: boolean;
 }
 
 interface ImageBlockData {
@@ -39,6 +40,21 @@ interface ImageBlockData {
   height: string;
 }
 
+interface IncludeBlockData {
+  target: string;
+  label: string;
+}
+
+interface IncludeOption {
+  id: string;
+  title: string;
+  description?: string;
+  scope?: string;
+  keywords?: string[];
+  languages?: string;
+  url?: string;
+}
+
 const BLOCK_TYPES: BlockType[] = [
   {label: 'Text', icon: 'text@lu', prefix: ''},
   {label: 'Heading 1', icon: 'heading-1@lu', prefix: '# '},
@@ -49,11 +65,25 @@ const BLOCK_TYPES: BlockType[] = [
   {label: 'Warning', icon: 'triangle-alert@lu', prefix: 'WARNING: '},
   {label: 'Code', icon: 'code@lu', prefix: '```\n\n```', caretOffset: 4},
   {label: 'Image', icon: 'image@lu', image: true},
+  {label: 'Include', icon: 'blocks@lu', include: true},
 ];
 
+/** remarkd's include directive on a line of its own: `include::<target>[<label>]`. */
+const INCLUDE_LINE = /^include::([^[]+)\[(.*)]\s*$/;
+
+/**
+ * The marker a document body carries for an embed. Mirrors app-kb's
+ * `model.IncludeEmbedMarker`: brackets and newlines in the title would break the
+ * directive, so they are replaced rather than escaped.
+ */
+function includeMarker(id: string, title: string): string {
+  const label = title.replace(/[\r\n]+/g, ' ').replace(/\[/g, '(').replace(/]/g, ')').trim();
+  return `include::${id}[${label}]`;
+}
+
 /** The block types as slash menu insertions. Image opens the picker, so it inserts nothing. */
-const SLASH_ITEMS: SlashMenuItem[] = BLOCK_TYPES.map(item => item.image
-  ? {label: item.label, icon: item.icon, action: 'image'}
+const SLASH_ITEMS: SlashMenuItem[] = BLOCK_TYPES.map(item => item.image || item.include
+  ? {label: item.label, icon: item.icon, action: item.image ? 'image' : 'include'}
   : {label: item.label, icon: item.icon, value: item.prefix ?? '', caretOffset: item.caretOffset});
 
 /**
@@ -80,6 +110,8 @@ const SLASH_ITEMS: SlashMenuItem[] = BLOCK_TYPES.map(item => item.image
  * @csspart raw - The full-document textarea shown in raw source mode.
  * @csspart slash-menu - The `zn-slash-menu` opened by typing "/" in an empty block.
  * @csspart image-controls - The caption / alignment / size panel shown when an image block is clicked.
+ * @csspart include - The chip rendered in place of an `include::` directive.
+ * @csspart include-picker - The inline Include picker opened from the toolbar or "/include".
  */
 export default class ZnRemarkdEditor extends ZincElement implements ZincFormControl {
   static styles: CSSResultGroup = unsafeCSS(styles);
@@ -95,11 +127,14 @@ export default class ZnRemarkdEditor extends ZincElement implements ZincFormCont
     menu: () => this.mountSlashMenu(),
     // The menu only belongs in a block that is nothing but the slash command — a
     // block prefix like "## " is not valid remarkd part-way through a line.
-    items: () => this.isSlashBlock() ? SLASH_ITEMS : [],
+    items: () => this.isSlashBlock()
+      ? SLASH_ITEMS.filter(item => item.action !== 'include' || !!this.includeUrl)
+      : [],
     onSelect: item => this.handleSlashSelect(item)
   });
 
   private editingDraft = '';
+  private includeRequest: Promise<IncludeOption[]> | null = null;
   private rawEntryValue = '';
   private suppressValueSync = false;
   private suppressBlurCommit = false;
@@ -109,6 +144,12 @@ export default class ZnRemarkdEditor extends ZincElement implements ZincFormCont
 
   @state() private blocks: string[] = [];
   @state() private editingIndex: number | null = null;
+  /**
+   * Lists the blocks most recently inserted here above the rest of the slash menu, remembered in
+   * `localStorage` under this key. Leave unset to offer no recently used section.
+   */
+  @property({attribute: 'slash-recent-key'}) slashRecentKey = '';
+
   /** Renders the slash menu only once it has been needed. */
   @state() private hasSlashMenu = false;
   @state() private imagePickerIndex: number | null = null;
@@ -117,6 +158,9 @@ export default class ZnRemarkdEditor extends ZincElement implements ZincFormCont
   @state() private dragIndex: number | null = null;
   @state() private editShell = '';
   @state() private rawMode = false;
+  @state() private includeOptions: IncludeOption[] | null = null;
+  @state() private includePickerIndex: number | null = null;
+  @state() private includeQuery = '';
 
   private pendingDragHandle: HTMLElement | null = null;
   private dragStartX = 0;
@@ -142,6 +186,13 @@ export default class ZnRemarkdEditor extends ZincElement implements ZincFormCont
    */
   @property({attribute: 'attachment-url'}) attachmentUrl = '';
 
+  /**
+   * Endpoint listing the Includes this document may embed, as
+   * `{"items":[{id,title,description,scope,keywords,languages,url}]}`. Labels the
+   * chips rendered for `include::` directives and feeds the include picker.
+   */
+  @property({attribute: 'include-url'}) includeUrl = '';
+
   /** Adds a toolbar toggle that swaps the block view for the full remarkd source. */
   @property({type: Boolean, attribute: 'allow-raw', reflect: true}) allowRaw = false;
 
@@ -201,6 +252,7 @@ export default class ZnRemarkdEditor extends ZincElement implements ZincFormCont
   protected firstUpdated(_changedProperties: PropertyValues) {
     super.firstUpdated(_changedProperties);
     this.formControlController.updateValidity();
+    if (this.hasIncludeBlock()) void this.loadIncludeOptions();
   }
 
   disconnectedCallback() {
@@ -215,6 +267,14 @@ export default class ZnRemarkdEditor extends ZincElement implements ZincFormCont
       return;
     }
     this.blocks = this.splitBlocks(this.value || '');
+    if (this.hasUpdated && this.hasIncludeBlock()) void this.loadIncludeOptions();
+  }
+
+  @watch('includeUrl', {waitUntilFirstUpdate: true})
+  handleIncludeUrlChange() {
+    this.includeRequest = null;
+    this.includeOptions = null;
+    if (this.hasIncludeBlock()) void this.loadIncludeOptions();
   }
 
   /**
@@ -246,6 +306,12 @@ export default class ZnRemarkdEditor extends ZincElement implements ZincFormCont
         fence = marker;
         continue;
       }
+      if (INCLUDE_LINE.test(trimmed)) {
+        push();
+        current.push(line);
+        push();
+        continue;
+      }
       if (trimmed === '') {
         push();
         continue;
@@ -337,6 +403,13 @@ export default class ZnRemarkdEditor extends ZincElement implements ZincFormCont
     return found ? data : null;
   }
 
+  /** Parses a block that is nothing but an include directive. */
+  private parseIncludeBlock(block: string): IncludeBlockData | null {
+    const match = INCLUDE_LINE.exec((block ?? '').trim());
+    if (!match) return null;
+    return {target: match[1].trim(), label: match[2].trim()};
+  }
+
   private serializeImageBlock(data: ImageBlockData): string {
     const lines: string[] = [];
     if (data.caption.trim()) lines.push(`.${data.caption.trim()}`);
@@ -549,14 +622,18 @@ export default class ZnRemarkdEditor extends ZincElement implements ZincFormCont
 
   /** Returns false for items the controller should not insert text for. */
   private handleSlashSelect(item: SlashMenuItem): boolean {
-    if (item.action !== 'image') return true;
+    if (item.action !== 'image' && item.action !== 'include') return true;
 
     const index = this.editingIndex ?? this.blocks.length;
     // Let the controller strip the "/…" text first, then drop the empty draft
-    // block and run the image flow in its place.
+    // block and run the picker in its place.
     void this.updateComplete.then(() => {
       this.blur();
-      this.pickImage(index);
+      if (item.action === 'image') {
+        this.pickImage(index);
+      } else {
+        this.pickInclude(index);
+      }
     });
     return false;
   }
@@ -682,9 +759,28 @@ export default class ZnRemarkdEditor extends ZincElement implements ZincFormCont
 
   private pickImage(index: number) {
     if (this.disabled || this.readonly) return;
+    this.includePickerIndex = null;
     this.imagePickerIndex = index;
   }
 
+  private pickInclude(index: number) {
+    if (this.disabled || this.readonly || !this.includeUrl) return;
+    this.imagePickerIndex = null;
+    this.includeQuery = '';
+    this.includePickerIndex = index;
+    void this.loadIncludeOptions();
+  }
+
+  private closeIncludePicker = () => {
+    this.includePickerIndex = null;
+  };
+
+  private insertInclude(item: IncludeOption) {
+    const index = this.includePickerIndex ?? this.blocks.length;
+    this.includePickerIndex = null;
+    this.addBlockAt(index, includeMarker(item.id, item.title));
+  }
+
   private closeImagePicker = () => {
     this.imagePickerIndex = null;
   };
@@ -731,6 +827,29 @@ export default class ZnRemarkdEditor extends ZincElement implements ZincFormCont
     return data.uploadPath;
   }
 
+  private hasIncludeBlock(): boolean {
+    return this.blocks.some(block => this.parseIncludeBlock(block) !== null);
+  }
+
+  /** Fetches the include list once; every later caller shares the same promise. */
+  private loadIncludeOptions(): Promise<IncludeOption[]> {
+    if (!this.includeUrl) return Promise.resolve([]);
+    if (!this.includeRequest) {
+      this.includeRequest = fetch(this.includeUrl, {headers: {Accept: 'application/json'}})
+        .then(res => res.ok ? res.json() as Promise<{items?: IncludeOption[]}> : {items: []})
+        .then(data => data.items ?? [])
+        .catch(error => {
+          console.error('[zn-remarkd-editor] include list failed', error);
+          return [] as IncludeOption[];
+        })
+        .then(items => {
+          this.includeOptions = items;
+          return items;
+        });
+    }
+    return this.includeRequest;
+  }
+
   private autosize(input: HTMLTextAreaElement) {
     input.style.height = 'auto';
     input.style.height = `${input.scrollHeight}px`;
@@ -796,6 +915,8 @@ export default class ZnRemarkdEditor extends ZincElement implements ZincFormCont
     const index = this.editingIndex !== null ? this.commitEdit() : this.blocks.length;
     if (item.image) {
       this.pickImage(index);
+    } else if (item.include) {
+      this.pickInclude(index);
     } else {
       this.insertDraftBlock(index, item.prefix ?? '');
     }
@@ -867,6 +988,32 @@ export default class ZnRemarkdEditor extends ZincElement implements ZincFormCont
       </div>`;
   }
 
+  private renderIncludeChip(data: IncludeBlockData) {
+    const option = this.includeOptions?.find(item => item.id === data.target);
+    // A path-like target is remarkd's file include, which this editor cannot
+    // resolve and must not call broken.
+    const filePath = /[/.]/.test(data.target);
+    const pending = !this.includeUrl || this.includeOptions === null;
+    const missing = !option && !pending && !filePath;
+    return html`
+      <div part="include"
+           class=${classMap({
+             'remarkd-editor__include': true,
+             'remarkd-editor__include--missing': missing,
+           })}>
+        <zn-icon src=${missing ? 'triangle-alert@lu' : 'blocks@lu'} size="16"></zn-icon>
+        <span class="remarkd-editor__include-title">${option?.title || data.label || data.target}</span>
+        ${option?.scope ? html`
+          <span class="remarkd-editor__include-scope">${option.scope}</span>` : ''}
+        <span class="remarkd-editor__include-meta">${missing
+          ? `Include not found · ${data.target}`
+          : !option && filePath ? 'File include' : 'Included content'}</span>
+        ${option?.url ? html`
+          <a class="remarkd-editor__include-link" href=${option.url} target="_blank" rel="noreferrer"
+             @click=${(e: MouseEvent) => e.stopPropagation()}>Open</a>` : ''}
+      </div>`;
+  }
+
   private renderBlock(block: string, index: number) {
     if (this.editingIndex === index) {
       if (this.imageEdit) {
@@ -890,6 +1037,7 @@ export default class ZnRemarkdEditor extends ZincElement implements ZincFormCont
         </div>`;
     }
 
+    const include = this.parseIncludeBlock(block);
     return html`
       <div part="block"
            class=${classMap({
@@ -914,7 +1062,8 @@ export default class ZnRemarkdEditor extends ZincElement implements ZincFormCont
                      tooltip="Delete block"
                      @click=${() => this.deleteBlock(index)}></zn-button>`}
         <div part="rendered" class="remarkd-editor__rendered remarkd-rendered"
-             @click=${(e: MouseEvent) => this.handleRenderedClick(e, index)}>${unsafeHTML(remarkdParse(block))}
+             @click=${(e: MouseEvent) => this.handleRenderedClick(e, index)}>${
+          include ? this.renderIncludeChip(include) : unsafeHTML(remarkdParse(block))}
         </div>
       </div>`;
   }
@@ -932,7 +1081,9 @@ export default class ZnRemarkdEditor extends ZincElement implements ZincFormCont
            @drop=${this.handleDrop}>
         ${editable ? html`
           <div part="toolbar" class="remarkd-editor__toolbar">
-            ${this.rawMode ? '' : BLOCK_TYPES.map(item => html`
+            ${this.rawMode ? '' : BLOCK_TYPES
+              .filter(item => !item.include || !!this.includeUrl)
+              .map(item => html`
               <zn-button type="button" icon-button plain icon=${item.icon} icon-size="18"
                          tooltip=${item.label}
                          @click=${() => this.handleToolbarInsert(item)}></zn-button>`)}
@@ -954,7 +1105,10 @@ export default class ZnRemarkdEditor extends ZincElement implements ZincFormCont
             </div>`}
         </div>
         ${this.hasSlashMenu ? html`
-          <zn-slash-menu part="slash-menu" heading="Insert block"></zn-slash-menu>` : ''}
+          <zn-slash-menu
+            part="slash-menu"
+            heading="Insert block"
+            recent-key=${this.slashRecentKey}></zn-slash-menu>` : ''}
         <textarea class="remarkd-editor__validation"
                   .value=${this.value}
                   ?required=${this.required}
@@ -980,9 +1134,44 @@ export default class ZnRemarkdEditor extends ZincElement implements ZincFormCont
     if (this.imagePickerIndex !== null) {
       views.splice(this.imagePickerIndex, 0, this.renderImagePicker());
     }
+    if (this.includePickerIndex !== null) {
+      views.splice(this.includePickerIndex, 0, this.renderIncludePicker());
+    }
     return views;
   }
 
+  private renderIncludePicker() {
+    const filter = this.includeQuery.trim().toLowerCase();
+    const items = (this.includeOptions ?? []).filter(item => !filter || [
+      item.title, item.description ?? '', (item.keywords ?? []).join(' '),
+    ].some(field => field.toLowerCase().includes(filter)));
+    return html`
+      <div part="include-picker" class="remarkd-editor__include-picker">
+        <div class="remarkd-editor__include-picker-head">
+          <input class="remarkd-editor__include-filter"
+                 placeholder="Find an Include"
+                 .value=${this.includeQuery}
+                 @input=${(e: Event) => {
+                   this.includeQuery = (e.target as HTMLInputElement).value;
+                 }}>
+          <zn-button type="button" icon-button="small" plain icon="x@lu"
+                     tooltip="Cancel" @click=${this.closeIncludePicker}></zn-button>
+        </div>
+        ${this.includeOptions === null
+          ? html`<div class="remarkd-editor__include-picker-empty">Loading…</div>`
+          : items.length
+            ? items.map(item => html`
+              <button type="button" class="remarkd-editor__include-option"
+                      ?disabled=${!item.languages}
+                      @click=${() => this.insertInclude(item)}>
+                <span class="remarkd-editor__include-option-title">${item.title}</span>
+                <span class="remarkd-editor__include-option-meta">${item.scope ?? ''}${
+                  item.languages ? ` · ${item.languages}` : ' · No content'}</span>
+              </button>`)
+            : html`<div class="remarkd-editor__include-picker-empty">No Includes found</div>`}
+      </div>`;
+  }
+
   private renderImagePicker() {
     return html`
       <div class="remarkd-editor__image-picker">

package/src/components/remarkd-editor/remarkd-editor.scss

@@ -224,6 +224,87 @@
   }
 }
 
+.remarkd-editor__include {
+  display: flex;
+  align-items: center;
+  gap: var(--zn-spacing-small);
+  padding: var(--zn-spacing-small);
+  border: 1px dashed rgb(var(--zn-border-color));
+  border-radius: var(--zn-border-radius);
+  background: var(--zn-color-neutral-0, white);
+}
+
+.remarkd-editor__include-title {
+  font-weight: 600;
+}
+
+.remarkd-editor__include-meta {
+  color: var(--zn-color-neutral-400, #9aa4b2);
+  font-size: var(--zn-font-size-small);
+}
+
+.remarkd-editor__include--missing {
+  border-style: solid;
+  border-color: rgb(var(--zn-color-error));
+}
+
+.remarkd-editor__include-scope {
+  color: var(--zn-color-neutral-400, #9aa4b2);
+  font-size: var(--zn-font-size-small);
+}
+
+.remarkd-editor__include-link {
+  margin-left: auto;
+  font-size: var(--zn-font-size-small);
+}
+
+.remarkd-editor__include-picker {
+  display: flex;
+  flex-direction: column;
+  gap: var(--zn-spacing-x-small);
+  padding: var(--zn-spacing-small);
+  border: 1px solid rgb(var(--zn-border-color));
+  border-radius: var(--zn-border-radius);
+  background: var(--zn-color-neutral-0, white);
+}
+
+.remarkd-editor__include-picker-head {
+  display: flex;
+  align-items: center;
+  gap: var(--zn-spacing-x-small);
+}
+
+.remarkd-editor__include-filter {
+  flex: 1 1 auto;
+}
+
+.remarkd-editor__include-option {
+  display: flex;
+  justify-content: space-between;
+  gap: var(--zn-spacing-small);
+  padding: var(--zn-spacing-x-small) var(--zn-spacing-small);
+  border: 0;
+  border-radius: var(--zn-border-radius);
+  background: none;
+  cursor: pointer;
+  text-align: left;
+
+  &:hover:not(:disabled) {
+    background: var(--zn-color-neutral-100);
+  }
+
+  &:disabled {
+    cursor: default;
+    opacity: 0.6;
+  }
+}
+
+.remarkd-editor__include-option-meta,
+.remarkd-editor__include-picker-empty {
+  color: var(--zn-color-neutral-400, #9aa4b2);
+  font-size: var(--zn-font-size-small);
+}
+
 .remarkd-editor__image-controls {
   display: flex;
   flex-direction: column;

package/src/components/remarkd-editor/remarkd-editor.test.ts

@@ -282,4 +282,183 @@ Second"></zn-remarkd-editor>`);
 
     expect(fired).to.be.true;
   });
+  it('should keep an include directive in a block of its own', async () => {
+    const el = await fixture<ZnRemarkdEditor>(html`
+      <zn-remarkd-editor value="Intro
+include::inc-1[Payment Terms]
+Outro"></zn-remarkd-editor>`);
+
+    const blocks = el.shadowRoot!.querySelectorAll('.remarkd-editor__block');
+    expect(blocks.length).to.equal(3);
+    expect(blocks[1].querySelector('.remarkd-editor__include-title')!.textContent).to.contain('Payment Terms');
+    expect(blocks[0].querySelector('.remarkd-editor__include')).to.not.exist;
+  });
+
+  it('should leave an include directive inside a fence alone', async () => {
+    const fenced = '```\ninclude::inc-1[Payment Terms]\n```';
+    const el = await fixture<ZnRemarkdEditor>(html`
+      <zn-remarkd-editor value=${fenced}></zn-remarkd-editor>`);
+
+    expect(el.shadowRoot!.querySelectorAll('.remarkd-editor__block').length).to.equal(1);
+    expect(el.shadowRoot!.querySelector('.remarkd-editor__include')).to.not.exist;
+  });
+
+  it('should label an include chip from the marker when no list is configured', async () => {
+    const el = await fixture<ZnRemarkdEditor>(html`
+      <zn-remarkd-editor value="include::inc-1[Payment Terms]"></zn-remarkd-editor>`);
+
+    const chip = el.shadowRoot!.querySelector('.remarkd-editor__include')!;
+    expect(chip.querySelector('.remarkd-editor__include-title')!.textContent).to.contain('Payment Terms');
+    expect(chip.classList.contains('remarkd-editor__include--missing')).to.be.false;
+  });
+
+  // Ordering an embed within the content is the whole point of the chip: the
+  // block chrome's drag handle has to move it like any other block.
+  it('should reorder an include block by dragging its handle', async () => {
+    const el = await fixture<ZnRemarkdEditor>(html`
+      <zn-remarkd-editor value="Intro
+
+include::inc-1[Payment Terms]"></zn-remarkd-editor>`);
+
+    const first = el.shadowRoot!.querySelectorAll('.remarkd-editor__block')[0].getBoundingClientRect();
+    const handle = el.shadowRoot!.querySelectorAll<HTMLElement>('.remarkd-editor__drag-handle')[1];
+    const target = first.top + 1;
+
+    handle.dispatchEvent(new PointerEvent('pointerdown', {bubbles: true, button: 0, buttons: 1, clientX: 0, clientY: 0}));
+    document.dispatchEvent(new PointerEvent('pointermove', {bubbles: true, buttons: 1, clientX: 0, clientY: target}));
+    document.dispatchEvent(new PointerEvent('pointerup', {bubbles: true, buttons: 0, clientX: 0, clientY: target}));
+    await el.updateComplete;
+
+    expect(el.value).to.equal('include::inc-1[Payment Terms]\n\nIntro');
+  });
+  /** Serves one include list to the editor, and restores fetch when the test ends. */
+  function stubIncludeList(items: unknown[]): void {
+    const original = window.fetch;
+    window.fetch = () => Promise.resolve(new Response(JSON.stringify({items}),
+      {headers: {'Content-Type': 'application/json'}}));
+    afterEach(() => {
+      window.fetch = original;
+    });
+  }
+
+  it('should label an include chip from the fetched list', async () => {
+    stubIncludeList([{id: 'inc-1', title: 'Refund Policy', scope: 'Global',
+      languages: 'English', url: '/kb/kb1/includes/inc-1'}]);
+    const el = await fixture<ZnRemarkdEditor>(html`
+      <zn-remarkd-editor include-url="/options"
+                         value="include::inc-1[Stale Title]"></zn-remarkd-editor>`);
+
+    await waitUntil(() => el.shadowRoot!.querySelector('.remarkd-editor__include-link'),
+      'the include list never resolved');
+    const chip = el.shadowRoot!.querySelector('.remarkd-editor__include')!;
+    expect(chip.querySelector('.remarkd-editor__include-title')!.textContent).to.contain('Refund Policy');
+    expect(chip.querySelector('.remarkd-editor__include-scope')!.textContent).to.contain('Global');
+    expect(chip.querySelector<HTMLAnchorElement>('.remarkd-editor__include-link')!.getAttribute('href'))
+      .to.equal('/kb/kb1/includes/inc-1');
+    expect(chip.classList.contains('remarkd-editor__include--missing')).to.be.false;
+  });
+
+  it('should flag an include the list does not know', async () => {
+    stubIncludeList([{id: 'inc-1', title: 'Refund Policy'}]);
+    const el = await fixture<ZnRemarkdEditor>(html`
+      <zn-remarkd-editor include-url="/options"
+                         value="include::inc-9[Archived]"></zn-remarkd-editor>`);
+
+    await waitUntil(() => el.shadowRoot!.querySelector('.remarkd-editor__include--missing'),
+      'the missing state never rendered');
+    expect(el.shadowRoot!.querySelector('.remarkd-editor__include-meta')!.textContent).to.contain('inc-9');
+  });
+
+  // remarkd's file include shares the syntax, so an unknown path is not broken.
+  it('should not flag a file include the list does not know', async () => {
+    stubIncludeList([{id: 'inc-1', title: 'Refund Policy'}]);
+    const el = await fixture<ZnRemarkdEditor>(html`
+      <zn-remarkd-editor include-url="/options"
+                         value="include::partials/legal.adoc[Legal]"></zn-remarkd-editor>`);
+
+    await waitUntil(() => el.shadowRoot!.querySelector('.remarkd-editor__include'),
+      'the chip never rendered');
+    expect(el.shadowRoot!.querySelector('.remarkd-editor__include--missing')).to.not.exist;
+  });
+
+  it('should not request the include list for a document with no embeds', async () => {
+    const original = window.fetch;
+    let requests = 0;
+    window.fetch = () => {
+      requests++;
+      return Promise.resolve(new Response('{"items":[]}'));
+    };
+    try {
+      const el = await fixture<ZnRemarkdEditor>(html`
+        <zn-remarkd-editor include-url="/options" value="# Title"></zn-remarkd-editor>`);
+      await el.updateComplete;
+      expect(requests).to.equal(0);
+    } finally {
+      window.fetch = original;
+    }
+  });
+  it('should insert an include marker from the toolbar picker', async () => {
+    stubIncludeList([{id: 'inc-1', title: 'Refund Policy', scope: 'Global', languages: 'English'}]);
+    const el = await fixture<ZnRemarkdEditor>(html`
+      <zn-remarkd-editor include-url="/options" value="# Title"></zn-remarkd-editor>`);
+
+    const buttons = el.shadowRoot!.querySelectorAll<HTMLElement>('.remarkd-editor__toolbar zn-button');
+    const includeButton = buttons[buttons.length - 1];
+    includeButton.dispatchEvent(new MouseEvent('click', {bubbles: true, composed: true, cancelable: true}));
+
+    await waitUntil(() => el.shadowRoot!.querySelector('.remarkd-editor__include-option'),
+      'the include picker never listed anything');
+    el.shadowRoot!.querySelector<HTMLElement>('.remarkd-editor__include-option')!.click();
+    await el.updateComplete;
+
+    expect(el.value).to.equal('# Title\n\ninclude::inc-1[Refund Policy]');
+  });
+
+  it('should swap the slash command for the include picker when Include is chosen', async () => {
+    stubIncludeList([{id: 'inc-1', title: 'Refund Policy', languages: 'English'}]);
+    const el = await fixture<ZnRemarkdEditor>(html`
+      <zn-remarkd-editor include-url="/options" value="Hello"></zn-remarkd-editor>`);
+    el.shadowRoot!.querySelector<HTMLElement>('.remarkd-editor__rendered')!.click();
+    await el.updateComplete;
+
+    const input = typeInBlock(el, '/include');
+    await waitUntil(() => el.shadowRoot!.querySelector('zn-slash-menu[open]'), 'the slash menu never opened');
+
+    input.dispatchEvent(new KeyboardEvent('keydown', {key: 'Enter', bubbles: true, cancelable: true}));
+    await waitUntil(() => el.shadowRoot!.querySelector('.remarkd-editor__include-picker'),
+      'the include picker never opened');
+
+    // The "/include" draft is dropped rather than committed as a block.
+    expect(el.value).to.equal('');
+  });
+
+  it('should filter the include picker', async () => {
+    stubIncludeList([
+      {id: 'inc-1', title: 'Refund Policy', keywords: ['money'], languages: 'English'},
+      {id: 'inc-2', title: 'Shipping', languages: 'English'},
+    ]);
+    const el = await fixture<ZnRemarkdEditor>(html`
+      <zn-remarkd-editor include-url="/options" value="# Title"></zn-remarkd-editor>`);
+    const buttons = el.shadowRoot!.querySelectorAll<HTMLElement>('.remarkd-editor__toolbar zn-button');
+    buttons[buttons.length - 1].dispatchEvent(new MouseEvent('click', {bubbles: true, composed: true, cancelable: true}));
+    await waitUntil(() => el.shadowRoot!.querySelectorAll('.remarkd-editor__include-option').length === 2,
+      'the include picker never listed both');
+
+    const filter = el.shadowRoot!.querySelector<HTMLInputElement>('.remarkd-editor__include-filter')!;
+    filter.value = 'money';
+    filter.dispatchEvent(new Event('input', {bubbles: true}));
+    await el.updateComplete;
+
+    const options = el.shadowRoot!.querySelectorAll('.remarkd-editor__include-option');
+    expect(options.length).to.equal(1);
+    expect(options[0].textContent).to.contain('Refund Policy');
+  });
+
+  it('should offer no include entry points without an include-url', async () => {
+    const el = await fixture<ZnRemarkdEditor>(html`
+      <zn-remarkd-editor value="# Title"></zn-remarkd-editor>`);
+    const tooltips = Array.from(el.shadowRoot!.querySelectorAll('.remarkd-editor__toolbar zn-button'))
+      .map(button => button.getAttribute('tooltip'));
+    expect(tooltips).to.not.contain('Include');
+  });
 });

package/src/components/settings-container/settings-container.scss

@@ -105,7 +105,8 @@ zn-button {
     border-bottom-width: 0;
     border-radius: 0 0 0 var(--zn-border-radius);
     transition: grid-template-rows 0.22s ease, border-bottom-width 0s linear 0.22s;
-    will-change: grid-template-rows;
+    // PERF: grid-template-rows is not a compositable property, so will-change
+    // cannot help it — it only promoted a layer per settings container for free.
   }
 
   &--open &__panel {

package/src/components/slash-item/slash-item.component.ts

@@ -2,7 +2,7 @@ import {html, unsafeCSS} from 'lit';
 import {property} from 'lit/decorators.js';
 import ZincElement from '../../internal/zinc-element';
 import type {CSSResultGroup} from 'lit';
-import type {SlashMenuItem} from '../slash-menu/slash-menu-items';
+import type {SlashMenuItem} from '../slash-menu';
 
 import styles from './slash-item.scss';