@kubex/zinc 1.1.94 → 1.1.96

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

@@ -282,4 +282,262 @@ 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');
+  });
+  // A list that never arrived is not evidence an embed is broken: flagging every
+  // chip "not found" on a failed request sends people hunting for the wrong bug.
+  it('should not flag includes when the list request fails', async () => {
+    const original = window.fetch;
+    window.fetch = () => Promise.resolve(new Response('nope', {status: 404}));
+    try {
+      const el = await fixture<ZnRemarkdEditor>(html`
+        <zn-remarkd-editor include-url="/options"
+                           value="include::inc-1[Payment Terms]"></zn-remarkd-editor>`);
+      await el.updateComplete;
+      await waitUntil(() => el.shadowRoot!.querySelector('.remarkd-editor__include'),
+        'the chip never rendered');
+
+      const chip = el.shadowRoot!.querySelector('.remarkd-editor__include')!;
+      expect(chip.classList.contains('remarkd-editor__include--missing')).to.be.false;
+      expect(chip.querySelector('.remarkd-editor__include-title')!.textContent).to.contain('Payment Terms');
+    } finally {
+      window.fetch = original;
+    }
+  });
+
+  it('should say so in the picker when the list request fails', async () => {
+    const original = window.fetch;
+    window.fetch = () => Promise.resolve(new Response('nope', {status: 500}));
+    try {
+      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!.querySelector('.remarkd-editor__include-picker-empty')?.textContent
+        ?.includes('Could not load'), 'the picker never reported the failure');
+    } finally {
+      window.fetch = original;
+    }
+  });
+  // An app fragment's URLs are relative to its app base, and the console puts the
+  // app's gaid on the host element. A link built client-side from JSON is inside
+  // the shadow root, where a click retargets to the host, so the pagelet handler
+  // never sees it — the href has to carry the base itself.
+  it('should resolve an include link against the app base from gaid', async () => {
+    stubIncludeList([{id: 'inc-1', title: 'Payment Terms', scope: 'Global',
+      languages: 'English', url: '/global/includes/inc-1'}]);
+    const el = await fixture<ZnRemarkdEditor>(html`
+      <zn-remarkd-editor include-url="/ch/kb/kb/kb1/documents/doc1/includes/options"
+                         gaid="ch/kb"
+                         value="include::inc-1[Payment Terms]"></zn-remarkd-editor>`);
+
+    await waitUntil(() => el.shadowRoot!.querySelector('.remarkd-editor__include-link'),
+      'the include list never resolved');
+    expect(el.shadowRoot!.querySelector<HTMLAnchorElement>('.remarkd-editor__include-link')!
+      .getAttribute('href')).to.equal('/ch/kb/global/includes/inc-1');
+  });
+
+  it('should leave an include link alone when it already carries the app base', async () => {
+    stubIncludeList([{id: 'inc-1', title: 'Payment Terms', languages: 'English',
+      url: '/ch/kb/global/includes/inc-1'}]);
+    const el = await fixture<ZnRemarkdEditor>(html`
+      <zn-remarkd-editor include-url="/options" gaid="ch/kb"
+                         value="include::inc-1[Payment Terms]"></zn-remarkd-editor>`);
+
+    await waitUntil(() => el.shadowRoot!.querySelector('.remarkd-editor__include-link'),
+      'the include list never resolved');
+    expect(el.shadowRoot!.querySelector<HTMLAnchorElement>('.remarkd-editor__include-link')!
+      .getAttribute('href')).to.equal('/ch/kb/global/includes/inc-1');
+  });
+
+  it('should leave an include link alone without a gaid', async () => {
+    stubIncludeList([{id: 'inc-1', title: 'Payment Terms', languages: 'English',
+      url: '/global/includes/inc-1'}]);
+    const el = await fixture<ZnRemarkdEditor>(html`
+      <zn-remarkd-editor include-url="/options"
+                         value="include::inc-1[Payment Terms]"></zn-remarkd-editor>`);
+
+    await waitUntil(() => el.shadowRoot!.querySelector('.remarkd-editor__include-link'),
+      'the include list never resolved');
+    expect(el.shadowRoot!.querySelector<HTMLAnchorElement>('.remarkd-editor__include-link')!
+      .getAttribute('href')).to.equal('/global/includes/inc-1');
+  });
 });

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';
 

package/src/components/slash-menu/slash-menu-items.ts

@@ -120,3 +120,51 @@ export function filterSlashItems(items: SlashMenuItem[], query: string): SlashMe
       a.index - b.index)
     .map(entry => entry.item);
 }
+
+const RECENT_PREFIX = 'zn-slash-recent:';
+/** Kept deeper than any menu shows, so history survives items that aren't in the current list. */
+const RECENT_LIMIT = 10;
+
+/** The identity an item is remembered by in a menu's recently used list. */
+export function slashItemKey(item: SlashMenuItem): string {
+  return item.action ? `action:${item.action}` : `value:${item.value || item.label}`;
+}
+
+/** The keys of the items most recently chosen from the menu stored under `key`, newest first. */
+export function readRecentSlashItems(key: string): string[] {
+  if (!key) return [];
+
+  try {
+    const parsed: unknown = JSON.parse(localStorage.getItem(RECENT_PREFIX + key) ?? '[]');
+    return Array.isArray(parsed) ? parsed.filter((entry): entry is string => typeof entry === 'string') : [];
+  } catch {
+    return [];
+  }
+}
+
+/** Moves an item to the front of the recently used list stored under `key`, and returns the list. */
+export function recordRecentSlashItem(key: string, item: SlashMenuItem): string[] {
+  if (!key) return [];
+
+  const itemKey = slashItemKey(item);
+  const keys = [itemKey, ...readRecentSlashItems(key).filter(entry => entry !== itemKey)].slice(0, RECENT_LIMIT);
+
+  try {
+    localStorage.setItem(RECENT_PREFIX + key, JSON.stringify(keys));
+  } catch {
+    // No storage (private browsing, quota) — the list just doesn't outlive the page
+  }
+
+  return keys;
+}
+
+/** Forgets the recently used items stored under `key`. */
+export function clearRecentSlashItems(key: string) {
+  if (!key) return;
+
+  try {
+    localStorage.removeItem(RECENT_PREFIX + key);
+  } catch {
+    // As above
+  }
+}

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

@@ -1,10 +1,11 @@
 import {autoUpdate, computePosition, flip, offset, shift, size} from '@floating-ui/dom';
 import {classMap} from 'lit/directives/class-map.js';
+import {clearRecentSlashItems, readRecentSlashItems, recordRecentSlashItem, slashItemKey} from './slash-menu-items';
 import {html, unsafeCSS} from 'lit';
 import {property, query, state} from 'lit/decorators.js';
 import ZincElement from '../../internal/zinc-element';
 import ZnIcon from '../icon';
-import type {CSSResultGroup, PropertyValues} from 'lit';
+import type {CSSResultGroup, PropertyValues, TemplateResult} from 'lit';
 import type {Placement, VirtualElement} from '@floating-ui/dom';
 import type {SlashMenuItem} from './slash-menu-items';
 
@@ -29,12 +30,19 @@ function sameItems(a: SlashMenuItem[] | undefined, b: SlashMenuItem[]): boolean
  *  component driving the menu (e.g. `zn-textarea`) re-emits it as `zn-slash-select`.
  *
  * @csspart panel - The floating panel that holds the list.
- * @csspart heading - The panel's heading.
+ * @csspart list - The scrolling list of items.
  * @csspart item - An item in the list.
+ * @csspart icon - The chip holding an item's icon.
  * @csspart group-heading - A group heading between items.
+ * @csspart divider - The rule closing the recently used section, when the items below it have no heading of their own.
  * @csspart footer - The truncation footer, shown when not every match fits.
+ * @csspart hints - The pinned footer of keyboard hints.
+ * @csspart hint - A single keyboard hint within the footer.
+ * @csspart hint-key - The key shown against a hint.
  *
  * @cssproperty --slash-menu-width - The width of the panel.
+ * @cssproperty --slash-menu-border-radius - The corner radius of the panel.
+ * @cssproperty --slash-menu-item-border-radius - The corner radius of the items and their icon chips.
  * @cssproperty --slash-menu-max-height - The maximum height of the panel before it scrolls.
  */
 export default class ZnSlashMenu extends ZincElement {
@@ -44,6 +52,7 @@ export default class ZnSlashMenu extends ZincElement {
   };
 
   @query('.slash-menu__panel') private panel: HTMLElement;
+  @query('.slash-menu__list') private list: HTMLElement;
 
   private stopAutoUpdate?: () => void;
 
@@ -56,7 +65,7 @@ export default class ZnSlashMenu extends ZincElement {
   /** The query the items were matched against, shown in the heading. */
   @property() query = '';
 
-  /** The heading shown when there is no query. */
+  /** The name the list is announced by when there is no query. */
   @property() heading = 'Insert';
 
   /** Shown in place of the list when there are no items. */
@@ -68,6 +77,22 @@ export default class ZnSlashMenu extends ZincElement {
   /** Hides the insertion key (the item's value) normally shown against each item. */
   @property({attribute: 'hide-keys', type: Boolean}) hideKeys = false;
 
+  /** Hides the pinned footer of keyboard hints. */
+  @property({attribute: 'hide-hints', type: Boolean}) hideHints = false;
+
+  /**
+   * Remembers the items chosen here and lists the most recent of them first, under their own heading.
+   * The key scopes the list to where the menu is used, so each place keeps its own history in
+   * `localStorage`. Leave unset to offer no recently used section.
+   */
+  @property({attribute: 'recent-key'}) recentKey = '';
+
+  /** The most recently used items to list. */
+  @property({attribute: 'max-recent', type: Number}) maxRecent = 3;
+
+  /** The heading shown above the recently used items. */
+  @property({attribute: 'recent-heading'}) recentHeading = 'Recently used';
+
   /** The element or caret rect the panel is positioned against. */
   @property({attribute: false}) anchor: Element | VirtualElement | null = null;
 
@@ -78,11 +103,41 @@ export default class ZnSlashMenu extends ZincElement {
   @property({type: Number}) distance = 4;
 
   @state() private activeIndex = 0;
+  @state() private recentKeys: string[] = [];
 
-  private get visibleItems(): SlashMenuItem[] {
+  /** How many recently used items the last update listed, to spot the list appearing or reordering. */
+  private recentCount = 0;
+
+  private get listItems(): SlashMenuItem[] {
     return this.maxItems > 0 ? this.items.slice(0, this.maxItems) : this.items;
   }
 
+  /**
+   * The remembered items that are in the current list, newest first. Only offered without a query —
+   * once the user is searching, the ranked matches are the better answer.
+   */
+  private get recentItems(): SlashMenuItem[] {
+    if (!this.recentKey || this.maxRecent < 1 || this.query.trim() !== '') return [];
+
+    const available = new Map<string, SlashMenuItem>();
+    for (const item of this.items) {
+      const key = slashItemKey(item);
+      if (!item.disabled && !available.has(key)) available.set(key, item);
+    }
+
+    const recent = this.recentKeys
+      .map(key => available.get(key))
+      .filter((item): item is SlashMenuItem => item !== undefined)
+      .slice(0, this.maxRecent);
+
+    // A section holding everything on offer is nothing but a second copy of the list
+    return recent.length < this.items.length ? recent : [];
+  }
+
+  private get visibleItems(): SlashMenuItem[] {
+    return [...this.recentItems, ...this.listItems];
+  }
+
   /** The item that Enter would insert. */
   get activeItem(): SlashMenuItem | undefined {
     return this.visibleItems[this.activeIndex];
@@ -96,6 +151,12 @@ export default class ZnSlashMenu extends ZincElement {
     this.open = false;
   }
 
+  /** Forgets the items remembered under `recent-key`. */
+  clearRecent() {
+    clearRecentSlashItems(this.recentKey);
+    this.recentKeys = [];
+  }
+
   /** Sets the active item by index, wrapping at both ends and skipping disabled items. */
   setActiveIndex(index: number) {
     const items = this.visibleItems;
@@ -198,6 +259,8 @@ export default class ZnSlashMenu extends ZincElement {
   private selectItem(item: SlashMenuItem) {
     if (item.disabled) return;
 
+    if (this.recentKey) this.recentKeys = recordRecentSlashItem(this.recentKey, item);
+
     this.dispatchEvent(new CustomEvent(SLASH_ITEM_SELECT, {
       bubbles: true,
       cancelable: true,
@@ -211,17 +274,17 @@ export default class ZnSlashMenu extends ZincElement {
     if (!active) return;
 
     const items = this.visibleItems;
-    const panel = this.panel;
+    const list = this.list;
 
-    // The heading and footer scroll with the list, and `nearest` stops at the item's own box — so
-    // landing on the first or last item goes all the way to the panel's edge to bring them back
-    if (panel && items.slice(0, this.activeIndex).every(item => item.disabled)) {
-      panel.scrollTop = 0;
+    // Group headings scroll with the items, and `nearest` stops at the item's own box — so landing
+    // on the first or last item goes all the way to the list's edge to bring them back
+    if (list && items.slice(0, this.activeIndex).every(item => item.disabled)) {
+      list.scrollTop = 0;
       return;
     }
 
-    if (panel && items.slice(this.activeIndex + 1).every(item => item.disabled)) {
-      panel.scrollTop = panel.scrollHeight;
+    if (list && items.slice(this.activeIndex + 1).every(item => item.disabled)) {
+      list.scrollTop = list.scrollHeight;
       return;
     }
 
@@ -244,9 +307,20 @@ export default class ZnSlashMenu extends ZincElement {
   protected willUpdate(changed: PropertyValues) {
     super.willUpdate(changed);
 
+    // Another field may share the key, so the list is re-read each time the menu is shown
+    if (changed.has('recentKey') || (changed.has('open') && this.open)) {
+      this.recentKeys = readRecentSlashItems(this.recentKey);
+    }
+
     // A genuinely new result set starts on its first selectable item. Re-resolving the same query
     // hands over an equal-but-new array, which must not move the user's place in the list.
-    if (changed.has('items') && !sameItems(changed.get('items') as SlashMenuItem[] | undefined, this.items)) {
+    const isNewList = changed.has('items')
+      && !sameItems(changed.get('items') as SlashMenuItem[] | undefined, this.items);
+
+    // Items above the list shift every index below them, so the place is given up either way
+    const recentCount = this.recentItems.length;
+    if (isNewList || recentCount !== this.recentCount) {
+      this.recentCount = recentCount;
       this.activeIndex = this.visibleItems.findIndex(item => !item.disabled);
     }
   }
@@ -292,7 +366,9 @@ export default class ZnSlashMenu extends ZincElement {
         @mousedown=${this.handleItemMouseDown}>
         ${showIcons
           ? html`
-            <span class="slash-menu__icon">
+            <span
+              part="icon"
+              class=${classMap({'slash-menu__icon': true, 'slash-menu__icon--empty': !item.icon})}>
               ${item.icon ? html`
                 <zn-icon src=${item.icon} size="16"></zn-icon>` : ''}
             </span>`
@@ -309,41 +385,72 @@ export default class ZnSlashMenu extends ZincElement {
 
   private renderItems() {
     const items = this.visibleItems;
+    const recentCount = this.recentItems.length;
     const showIcons = items.some(item => item.icon);
     let lastGroup: string | undefined;
 
     return items.map((item, index) => {
-      const group = item.group;
+      const group = index < recentCount ? this.recentHeading : item.group;
       const heading = group && group !== lastGroup
         ? html`
           <div part="group-heading" class="slash-menu__group-heading">${group}</div>`
         : '';
       lastGroup = group;
 
-      return html`${heading}${this.renderItem(item, index, showIcons)}`;
+      // The recently used section needs closing off; a heading of its own does that for the items
+      // below it, and where they have none, a rule does it instead
+      const divider = index === recentCount && recentCount > 0 && !heading
+        ? html`
+          <div part="divider" class="slash-menu__divider"></div>`
+        : '';
+
+      return html`${divider}${heading}${this.renderItem(item, index, showIcons)}`;
     });
   }
 
+  private renderHint(keys: (TemplateResult | string)[], label: string) {
+    return html`
+      <span part="hint" class="slash-menu__hint">
+        ${keys.map(key => html`
+          <kbd part="hint-key" class="slash-menu__key">${key}</kbd>`)}
+        ${label}
+      </span>`;
+  }
+
+  private renderHints() {
+    const key = (icon: string) => html`
+      <zn-icon src="${icon}@lu" size="12"></zn-icon>`;
+
+    return html`
+      <div part="hints" class="slash-menu__hints">
+        ${this.renderHint([key('arrow-up'), key('arrow-down')], 'navigate')}
+        ${this.renderHint([key('corner-down-left')], 'select')}
+        ${this.renderHint(['esc'], 'dismiss')}
+      </div>`;
+  }
+
   render() {
-    const hidden = this.items.length - this.visibleItems.length;
+    const hidden = this.items.length - this.listItems.length;
 
     return html`
       <div
         part="panel"
         class="slash-menu__panel"
         popover="manual"
-        role="listbox"
-        aria-hidden=${this.open ? 'false' : 'true'}
-        aria-label=${this.query ? `Matches for ${this.query}` : this.heading}>
-        <div part="heading" class="slash-menu__heading">
-          ${this.query ? html`Matching <strong>${this.query}</strong>` : this.heading}
+        aria-hidden=${this.open ? 'false' : 'true'}>
+        <div
+          part="list"
+          class="slash-menu__list"
+          role="listbox"
+          aria-label=${this.query ? `Matches for ${this.query}` : this.heading}>
+          ${this.items.length
+            ? this.renderItems()
+            : html`
+              <div class="slash-menu__empty">${this.emptyText}</div>`}
+          ${hidden > 0 ? html`
+            <div part="footer" class="slash-menu__footer">${hidden} more — keep typing to narrow</div>` : ''}
         </div>
-        ${this.items.length
-          ? this.renderItems()
-          : html`
-            <div class="slash-menu__empty">${this.emptyText}</div>`}
-        ${hidden > 0 ? html`
-          <div part="footer" class="slash-menu__footer">${hidden} more — keep typing to narrow</div>` : ''}
+        ${this.hideHints ? '' : this.renderHints()}
       </div>`;
   }
 }