@kubex/zinc 1.1.79 → 1.1.80

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

@@ -1,7 +1,19 @@
 import '../../../dist/zn.min.js';
-import { expect, fixture, html } from '@open-wc/testing';
+import { expect, fixture, html, waitUntil } from '@open-wc/testing';
 import type ZnInlineEdit from './inline-edit.component';
 import type ZnSelect from '../select/select.component';
+import type ZnSlashMenu from '../slash-menu/slash-menu.component';
+import type ZnTextarea from '../textarea/textarea.component';
+
+// The auto-resizing textarea's ResizeObserver can emit a benign "loop completed with undelivered
+// notifications" warning while the slash menu is positioned. It's not a real error — ignore it so the
+// test runner doesn't treat it as an uncaught exception (capture phase runs before the runner's).
+window.addEventListener('error', (e: ErrorEvent) => {
+  if (typeof e.message === 'string' && e.message.includes('ResizeObserver loop')) {
+    e.stopImmediatePropagation();
+    e.preventDefault();
+  }
+}, true);
 
 describe('<zn-inline-edit>', () => {
   it('should render a component', async () => {
@@ -483,4 +495,74 @@ describe('<zn-inline-edit>', () => {
     expect(el.shadowRoot!.querySelector('.ai--editing')).to.not.exist;
     expect(el.value).to.equal('real@example.com');
   });
+
+  // -- Slash menu --
+
+  describe('slash menu', () => {
+    async function openSlashMenu(el: ZnInlineEdit) {
+      await el.updateComplete;
+
+      el.shadowRoot!.querySelector<HTMLElement>('.ai__left')!
+        .dispatchEvent(new MouseEvent('click', {bubbles: true, composed: true}));
+      await el.updateComplete;
+
+      const textarea = el.shadowRoot!.querySelector<ZnTextarea>('zn-textarea')!;
+      await textarea.updateComplete;
+
+      textarea.focus();
+      textarea.input.value = '/';
+      textarea.input.setSelectionRange(1, 1);
+      textarea.input.dispatchEvent(new InputEvent('input', {bubbles: true, composed: true}));
+
+      const menuOf = () => textarea.shadowRoot!.querySelector<ZnSlashMenu>('zn-slash-menu');
+      await waitUntil(() => menuOf()?.open, 'the slash menu never opened');
+
+      return {textarea, menu: menuOf()!};
+    }
+
+    it('offers its slash items on the inner textarea', async () => {
+      const el = await fixture<ZnInlineEdit>(html`
+        <zn-inline-edit input-type="textarea"
+                        slash-items="Brand name={{BRAND_NAME}}, Support email={{SUPPORT_EMAIL}}"></zn-inline-edit>`);
+      const {menu} = await openSlashMenu(el);
+
+      expect(menu.items.map(item => item.label)).to.deep.equal(['Brand name', 'Support email']);
+    });
+
+    it('forwards a custom trigger', async () => {
+      const el = await fixture<ZnInlineEdit>(html`
+        <zn-inline-edit input-type="textarea" slash-trigger="{{"
+                        slash-items="Brand name={{BRAND_NAME}}"></zn-inline-edit>`);
+      await el.updateComplete;
+
+      const textarea = el.shadowRoot!.querySelector<ZnTextarea>('zn-textarea')!;
+      expect(textarea.slashTrigger).to.equal('{{');
+    });
+
+    it('does not submit the form when Enter chooses an item', async () => {
+      const form = await fixture<HTMLFormElement>(html`
+        <form>
+          <zn-inline-edit input-type="textarea" slash-items="Brand name={{BRAND_NAME}}"></zn-inline-edit>
+        </form>`);
+      const el = form.querySelector<ZnInlineEdit>('zn-inline-edit')!;
+
+      let submits = 0;
+      form.addEventListener('submit', event => {
+        event.preventDefault();
+        submits++;
+      });
+
+      const {textarea} = await openSlashMenu(el);
+      textarea.input.dispatchEvent(new KeyboardEvent('keydown', {
+        key: 'Enter',
+        bubbles: true,
+        composed: true,
+        cancelable: true
+      }));
+      await el.updateComplete;
+
+      expect(el.value, 'the token should have replaced the trigger').to.equal('{{BRAND_NAME}}');
+      expect(submits, 'Enter belongs to the open menu, not the form').to.equal(0);
+    });
+  });
 });

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

@@ -0,0 +1,12 @@
+import ZnSlashItem from './slash-item.component';
+
+export * from './slash-item.component';
+export default ZnSlashItem;
+
+ZnSlashItem.define('zn-slash-item');
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'zn-slash-item': ZnSlashItem;
+  }
+}

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

@@ -0,0 +1,76 @@
+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 styles from './slash-item.scss';
+
+/**
+ * @summary Declares a single insertion for a slash menu. Renders nothing itself — it describes an
+ *  entry for the component it is slotted into, e.g. `<zn-textarea>`'s `slash-items` slot.
+ * @documentation https://zinc.style/components/slash-item
+ * @status experimental
+ * @since 1.1
+ *
+ * @slot - The text to insert, for values that are long or span multiple lines. Ignored when the
+ *  `value` attribute is set.
+ */
+export default class ZnSlashItem extends ZincElement {
+  static styles: CSSResultGroup = unsafeCSS(styles);
+
+  /** The text shown in the menu. */
+  @property() label = '';
+
+  /** The text inserted into the field. Falls back to this element's text content. */
+  @property() value: string;
+
+  /** Icon shown against the item, e.g. `tag@lu`. */
+  @property() icon: string;
+
+  /** Supporting text shown under the label. */
+  @property() description: string;
+
+  /** Extra terms the item can be found by, comma separated. */
+  @property() keywords: string;
+
+  /** Heading the item is listed under. */
+  @property() group: string;
+
+  /** Overrides the item's position in the menu. Lower sorts first. */
+  @property({type: Number}) order: number;
+
+  /** Where the caret lands after insertion, as an offset into the inserted value. */
+  @property({attribute: 'caret-offset', type: Number}) caretOffset: number;
+
+  /** Identifier passed through on `zn-slash-select`, for items that do something other than insert. */
+  @property() action: string;
+
+  /** Listed, but not selectable. */
+  @property({type: Boolean, reflect: true}) disabled = false;
+
+  /** The item as the slash menu consumes it. */
+  toSlashMenuItem(): SlashMenuItem {
+    return {
+      label: this.label || this.insertValue,
+      value: this.insertValue,
+      icon: this.icon,
+      description: this.description,
+      keywords: this.keywords,
+      group: this.group,
+      order: this.order,
+      action: this.action,
+      caretOffset: this.caretOffset,
+      disabled: this.disabled
+    };
+  }
+
+  private get insertValue(): string {
+    return this.value ?? (this.textContent ?? '').trim();
+  }
+
+  render() {
+    return html`
+      <slot></slot>`;
+  }
+}

package/src/components/slash-item/slash-item.scss

@@ -0,0 +1,5 @@
+@use "../../wc";
+
+:host {
+  display: none;
+}

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

@@ -0,0 +1,14 @@
+import ZnSlashMenu from './slash-menu.component';
+
+export * from './slash-menu.component';
+export * from './slash-menu-controller';
+export * from './slash-menu-items';
+export default ZnSlashMenu;
+
+ZnSlashMenu.define('zn-slash-menu');
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'zn-slash-menu': ZnSlashMenu;
+  }
+}

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

@@ -0,0 +1,361 @@
+import {caretRectFrom, getCaretCoordinates} from '../../utilities/caret-position';
+import {filterSlashItems} from './slash-menu-items';
+import {SLASH_ITEM_SELECT} from './slash-menu.component';
+import type {CaretCoordinates, TextField} from '../../utilities/caret-position';
+import type {ReactiveController, ReactiveControllerHost} from 'lit';
+import type {SlashMenuItem} from './slash-menu-items';
+import type {VirtualElement} from '../popup';
+import type ZnSlashMenu from './slash-menu.component';
+
+export interface SlashMenuControllerOptions {
+  /**
+   * Resolves the menu to render results into. Called the first time the menu is needed, so the host
+   * can render it lazily; may return a promise (e.g. after awaiting `updateComplete`).
+   */
+  menu: () => ZnSlashMenu | null | Promise<ZnSlashMenu | null>;
+  /** The available items, unfiltered. Receives the current query so lists can be resolved remotely. */
+  items: (query: string) => SlashMenuItem[] | Promise<SlashMenuItem[]>;
+  /** The characters that open the menu. Defaults to `/`. */
+  trigger?: () => string;
+  /** Called before an item is inserted. Return `false` to handle the item yourself. */
+  onSelect?: (item: SlashMenuItem, query: string) => boolean;
+  /** Called after an item's value has been written into the field. */
+  onInsert?: (item: SlashMenuItem, value: string) => void;
+}
+
+/** Queries longer than this are treated as prose the user never meant as a menu search. */
+const MAX_QUERY_LENGTH = 40;
+
+/**
+ * Drives a slash menu for a plain `<textarea>` or `<input>`: watches the caret for the trigger
+ * sequence, resolves and filters items, and inserts the chosen value.
+ *
+ * The host owns the field and the menu element; this controller owns the interaction.
+ */
+export class SlashMenuController implements ReactiveController {
+  private readonly host: ReactiveControllerHost & HTMLElement;
+  private readonly options: SlashMenuControllerOptions;
+  private readonly caretAnchor: VirtualElement = {
+    getBoundingClientRect: () => this.caretRect()
+  };
+
+  private field: TextField | null = null;
+  private menu: ZnSlashMenu | null = null;
+  private triggerIndex = -1;
+  private query = '';
+  /** Trigger position the user dismissed with Escape; the menu stays shut until they move off it. */
+  private dismissedIndex = -1;
+  private resolveToken = 0;
+  private inserting = false;
+  private isOpen = false;
+  private listening = false;
+  /** Caret measurement is the expensive part of positioning, so the last one is reused. */
+  private measured?: {value: string; index: number; width: number; coordinates: CaretCoordinates};
+
+  constructor(host: ReactiveControllerHost & HTMLElement, options: SlashMenuControllerOptions) {
+    this.host = host;
+    this.options = options;
+    host.addController(this);
+  }
+
+  /** Whether the menu is currently showing. */
+  get open(): boolean {
+    return this.isOpen;
+  }
+
+  hostConnected() {
+    this.addListeners();
+  }
+
+  hostDisconnected() {
+    // The field is kept, so reconnecting the host resumes where it left off
+    this.removeListeners();
+  }
+
+  /** Starts watching a field. Safe to call repeatedly with the same field. */
+  attach(field: TextField) {
+    if (this.field === field && this.listening) return;
+
+    this.removeListeners();
+    this.field = field;
+    this.caretAnchor.contextElement = field;
+    this.addListeners();
+  }
+
+  /** Stops watching the current field and closes the menu. */
+  detach() {
+    this.removeListeners();
+    this.field = null;
+  }
+
+  private addListeners() {
+    const field = this.field;
+    if (!field || this.listening) return;
+
+    // Capture phase, so menu navigation keys are claimed before the host's own key handling
+    field.addEventListener('keydown', this.handleKeyDown, {capture: true});
+    field.addEventListener('input', this.handleInput);
+    field.addEventListener('keyup', this.handleKeyUp);
+    field.addEventListener('click', this.handleCaretMove);
+    field.addEventListener('blur', this.handleBlur);
+    field.addEventListener('scroll', this.handleScroll);
+    this.listening = true;
+  }
+
+  private removeListeners() {
+    const field = this.field;
+    if (!field || !this.listening) return;
+
+    this.close();
+    field.removeEventListener('keydown', this.handleKeyDown, {capture: true});
+    field.removeEventListener('input', this.handleInput);
+    field.removeEventListener('keyup', this.handleKeyUp);
+    field.removeEventListener('click', this.handleCaretMove);
+    field.removeEventListener('blur', this.handleBlur);
+    field.removeEventListener('scroll', this.handleScroll);
+    this.listening = false;
+  }
+
+  /** Closes the menu without marking the trigger as dismissed. */
+  close() {
+    this.resolveToken++;
+    this.triggerIndex = -1;
+    this.query = '';
+
+    if (this.isOpen) {
+      this.isOpen = false;
+      this.menu?.hide();
+      this.field?.setAttribute('aria-expanded', 'false');
+    }
+  }
+
+  /** Opens the menu at the caret, as a toolbar button or keyboard shortcut would. */
+  requestOpen() {
+    this.dismissedIndex = -1;
+    this.detect();
+  }
+
+  private caretRect(): DOMRect {
+    const field = this.field;
+    if (!field) return new DOMRect();
+
+    const index = this.triggerIndex >= 0 ? this.triggerIndex : (field.selectionStart ?? 0);
+    const width = field.clientWidth;
+    const cached = this.measured;
+
+    if (!cached || cached.index !== index || cached.width !== width || cached.value !== field.value) {
+      this.measured = {value: field.value, index, width, coordinates: getCaretCoordinates(field, index)};
+    }
+
+    return caretRectFrom(field, this.measured!.coordinates);
+  }
+
+  private readonly handleInput = () => this.detect();
+
+  private readonly handleCaretMove = () => this.detect();
+
+  private readonly handleKeyUp = (event: KeyboardEvent) => {
+    // The vertical arrows belong to the open menu, and its keydown handler stopped them from moving
+    // the caret — re-detecting here would rebuild the list and drop the user's place in it
+    if (this.isOpen && (event.key === 'ArrowDown' || event.key === 'ArrowUp')) return;
+
+    // Typing is covered by `input`; this catches caret moves that don't change the value
+    if (event.key.startsWith('Arrow') || event.key === 'Home' || event.key === 'End') {
+      this.detect();
+    }
+  };
+
+  private readonly handleBlur = () => this.close();
+
+  private readonly handleScroll = () => {
+    if (this.isOpen) this.menu?.reposition();
+  };
+
+  private readonly handleKeyDown = (event: KeyboardEvent) => {
+    if (!this.isOpen || event.isComposing) return;
+
+    const claim = () => {
+      event.preventDefault();
+      event.stopPropagation();
+    };
+
+    switch (event.key) {
+      case 'Escape':
+        claim();
+        this.dismissedIndex = this.triggerIndex;
+        this.close();
+        return;
+
+      case 'ArrowDown':
+        claim();
+        this.menu?.moveActive(1);
+        return;
+
+      case 'ArrowUp':
+        claim();
+        this.menu?.moveActive(-1);
+        return;
+
+      case 'Enter':
+      case 'Tab': {
+        if (event.shiftKey || event.metaKey || event.ctrlKey || event.altKey) return;
+
+        const item = this.menu?.activeItem;
+        if (!item) {
+          this.close();
+          return;
+        }
+
+        claim();
+        this.select(item);
+      }
+    }
+  };
+
+  private readonly handleItemSelect = (event: Event) => {
+    const {item} = (event as CustomEvent<{item: SlashMenuItem}>).detail;
+    if (item) this.select(item);
+  };
+
+  private detect() {
+    if (this.inserting) return;
+
+    const field = this.field;
+    if (!field || field.disabled || field.readOnly) {
+      this.close();
+      return;
+    }
+
+    const trigger = this.options.trigger?.() || '/';
+    const caret = field.selectionStart;
+    // Only a collapsed caret opens the menu — a selection means the user is doing something else
+    if (!trigger || caret === null || field.selectionEnd !== caret) {
+      this.close();
+      return;
+    }
+
+    const value = field.value;
+    const index = value.lastIndexOf(trigger, Math.max(0, caret - trigger.length));
+    if (index === -1 || index + trigger.length > caret) {
+      this.close();
+      return;
+    }
+
+    // The trigger only counts at the start of a word
+    const preceding = index > 0 ? value.charAt(index - 1) : '';
+    if (preceding !== '' && !/\s/.test(preceding)) {
+      this.close();
+      return;
+    }
+
+    const query = value.slice(index + trigger.length, caret);
+    if (query.length > MAX_QUERY_LENGTH || /[\r\n]/.test(query)) {
+      this.close();
+      return;
+    }
+
+    if (index === this.dismissedIndex) {
+      this.close();
+      return;
+    }
+
+    this.triggerIndex = index;
+    this.query = query;
+    void this.resolve(query);
+  }
+
+  private async resolve(query: string) {
+    const token = ++this.resolveToken;
+
+    let items: SlashMenuItem[] = [];
+    try {
+      items = await this.options.items(query);
+    } catch (error: unknown) {
+      console.warn('slash menu items could not be resolved', error);
+    }
+
+    if (token !== this.resolveToken) return;
+
+    const matches = filterSlashItems(items, query);
+    if (!matches.length) {
+      this.close();
+      return;
+    }
+
+    const menu = await this.options.menu();
+    if (!menu || token !== this.resolveToken) return;
+
+    if (menu !== this.menu) {
+      this.menu?.removeEventListener(SLASH_ITEM_SELECT, this.handleItemSelect);
+      menu.addEventListener(SLASH_ITEM_SELECT, this.handleItemSelect);
+      this.menu = menu;
+    }
+
+    menu.anchor = this.caretAnchor;
+    menu.query = query;
+    menu.items = matches;
+
+    if (!this.isOpen) {
+      this.isOpen = true;
+      this.dismissedIndex = -1;
+      menu.show();
+      this.field?.setAttribute('aria-expanded', 'true');
+      this.field?.setAttribute('aria-haspopup', 'listbox');
+    }
+
+    await menu.updateComplete;
+    if (this.isOpen) menu.reposition();
+  }
+
+  private select(item: SlashMenuItem) {
+    const field = this.field;
+    const start = this.triggerIndex;
+    const end = field?.selectionStart ?? start;
+    const query = this.query;
+    const trigger = this.options.trigger?.() || '/';
+
+    if (item.disabled) return;
+
+    this.close();
+    if (!field || start < 0) return;
+
+    const cancelled = this.options.onSelect?.(item, query) === false;
+    const value = cancelled ? '' : (item.value ?? '');
+
+    // A handler may have rewritten the field already; only touch text we still recognise as ours
+    if (field.value.slice(start, end) !== trigger + query) return;
+
+    // The trigger and query are a command rather than content, so they go either way
+    this.replace(field, start, end, value, item);
+
+    if (!cancelled && value) this.options.onInsert?.(item, value);
+  }
+
+  private replace(field: TextField, start: number, end: number, value: string, item: SlashMenuItem) {
+    this.inserting = true;
+    try {
+      field.focus({preventScroll: true});
+      field.setSelectionRange(start, end);
+
+      // execCommand keeps the field's native undo history intact; setRangeText does not
+      let handled = false;
+      try {
+        handled = field.ownerDocument.execCommand('insertText', false, value);
+      } catch {
+        handled = false;
+      }
+
+      if (!handled) {
+        field.setRangeText(value, start, end, 'end');
+        field.dispatchEvent(new Event('input', {bubbles: true, composed: true}));
+      }
+
+      const offset = Math.min(Math.max(item.caretOffset ?? value.length, 0), value.length);
+      field.setSelectionRange(start + offset, start + offset);
+    } finally {
+      this.inserting = false;
+    }
+
+    this.host.requestUpdate();
+  }
+}

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

@@ -0,0 +1,122 @@
+export interface SlashMenuItem {
+  /** The text shown in the menu. */
+  label: string;
+  /** The text inserted into the field. Omit for items handled entirely by the `zn-slash-select` event. */
+  value?: string;
+  /** Icon shown against the item, e.g. `tag@lu`. */
+  icon?: string;
+  /** Supporting text shown under the label. */
+  description?: string;
+  /** Extra terms the item can be found by. */
+  keywords?: string | string[];
+  /** Heading the item is listed under. Items without a group are listed first, in source order. */
+  group?: string;
+  /** Overrides the position of the item within its match band. Lower sorts first. */
+  order?: number;
+  /** Identifier passed through on `zn-slash-select`, for items that do something other than insert text. */
+  action?: string;
+  /** Where the caret lands after insertion, as an offset into `value`. Defaults to the end. */
+  caretOffset?: number;
+  /** Listed, but not selectable. */
+  disabled?: boolean;
+}
+
+const presets = new Map<string, SlashMenuItem[]>();
+
+/**
+ * Registers a named, reusable set of insertions, so a list defined once (e.g. the merge fields
+ * allowed in legal copy) can be referenced from markup with `slash-preset="<name>"`.
+ */
+export function registerSlashMenuPreset(name: string, items: SlashMenuItem[]) {
+  presets.set(name.trim(), items);
+}
+
+/** Removes a preset registered with `registerSlashMenuPreset`. */
+export function unregisterSlashMenuPreset(name: string) {
+  presets.delete(name.trim());
+}
+
+/** The names of every registered preset. */
+export function slashMenuPresetNames(): string[] {
+  return [...presets.keys()];
+}
+
+/** Resolves one or more preset names (comma separated, or an array) to their items. */
+export function getSlashMenuPreset(names: string | string[]): SlashMenuItem[] {
+  const list = Array.isArray(names) ? names : names.split(',');
+
+  return list.reduce<SlashMenuItem[]>((items, name) => {
+    const preset = presets.get(name.trim());
+    return preset ? [...items, ...preset] : items;
+  }, []);
+}
+
+function isItemLike(value: unknown): value is SlashMenuItem {
+  return typeof value === 'object' && value !== null && typeof (value as SlashMenuItem).label === 'string';
+}
+
+/**
+ * Parses the `slash-items` attribute. Accepts a JSON array of items, or the shorthand
+ * `Label={{TOKEN}}, Other={{OTHER}}` (the label may be omitted to use the token as its own label).
+ */
+export function parseSlashItems(value: string | null | undefined): SlashMenuItem[] {
+  const raw = value?.trim();
+  if (!raw) return [];
+
+  if (raw.startsWith('[')) {
+    try {
+      const parsed: unknown = JSON.parse(raw);
+      return Array.isArray(parsed) ? parsed.filter(isItemLike) : [];
+    } catch {
+      console.warn('slash-items could not be parsed as JSON', raw);
+      return [];
+    }
+  }
+
+  return raw
+    .split(',')
+    .map(entry => entry.trim())
+    .filter(entry => entry !== '')
+    .map(entry => {
+      const separator = entry.indexOf('=');
+      if (separator === -1) return {label: entry, value: entry};
+
+      const label = entry.slice(0, separator).trim();
+      const insert = entry.slice(separator + 1).trim();
+      return {label: label || insert, value: insert};
+    })
+    .filter(item => item.label !== '');
+}
+
+function keywordsOf(item: SlashMenuItem): string[] {
+  if (!item.keywords) return [];
+  const keywords = Array.isArray(item.keywords) ? item.keywords : item.keywords.split(',');
+  return keywords.map(keyword => keyword.trim().toLowerCase()).filter(keyword => keyword !== '');
+}
+
+// Lower bands sort first, so a label match always beats an incidental hit in a
+// description or in the token being inserted.
+function scoreItem(item: SlashMenuItem, query: string): number {
+  const label = item.label.toLowerCase();
+  if (label.startsWith(query)) return 0;
+  if (label.split(/\s+/).some(word => word.startsWith(query))) return 1;
+  if (label.includes(query)) return 2;
+  if (keywordsOf(item).some(keyword => keyword.includes(query))) return 3;
+  if (item.value?.toLowerCase().includes(query)) return 4;
+  if (item.description?.toLowerCase().includes(query)) return 5;
+  return -1;
+}
+
+/** Filters and ranks items against a query. An empty query keeps every item in its declared order. */
+export function filterSlashItems(items: SlashMenuItem[], query: string): SlashMenuItem[] {
+  const needle = query.trim().toLowerCase();
+
+  return items
+    .map((item, index) => ({item, index, score: needle ? scoreItem(item, needle) : 0}))
+    .filter(entry => entry.score !== -1)
+    .sort((a, b) =>
+      a.score - b.score ||
+      (a.item.order ?? a.index) - (b.item.order ?? b.index) ||
+      a.index - b.index)
+    .map(entry => entry.item);
+}