@kubex/zinc 1.1.79 → 1.1.80

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

@@ -0,0 +1,305 @@
+import {autoUpdate, computePosition, flip, offset, shift, size} from '@floating-ui/dom';
+import {classMap} from 'lit/directives/class-map.js';
+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 {Placement, VirtualElement} from '@floating-ui/dom';
+import type {SlashMenuItem} from './slash-menu-items';
+
+import styles from './slash-menu.scss';
+
+export const SLASH_ITEM_SELECT = 'zn-slash-item-select';
+
+function sameItems(a: SlashMenuItem[] | undefined, b: SlashMenuItem[]): boolean {
+  return !!a && a.length === b.length && a.every((item, i) =>
+    item.label === b[i].label && item.value === b[i].value && item.disabled === b[i].disabled);
+}
+
+/**
+ * @summary A keyboard-driven list of insertions, anchored to the caret of the field that opened it.
+ * @documentation https://zinc.style/components/slash-menu
+ * @status experimental
+ * @since 1.1
+ *
+ * @dependency zn-icon
+ *
+ * @event zn-slash-item-select - Emitted when an item is chosen. Does not cross shadow boundaries; the
+ *  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 item - An item in the list.
+ * @csspart group-heading - A group heading between items.
+ * @csspart footer - The truncation footer, shown when not every match fits.
+ *
+ * @cssproperty --slash-menu-width - The width of the panel.
+ * @cssproperty --slash-menu-max-height - The maximum height of the panel before it scrolls.
+ */
+export default class ZnSlashMenu extends ZincElement {
+  static styles: CSSResultGroup = unsafeCSS(styles);
+  static dependencies = {
+    'zn-icon': ZnIcon
+  };
+
+  @query('.slash-menu__panel') private panel: HTMLElement;
+
+  private stopAutoUpdate?: () => void;
+
+  /** Whether the menu is showing. */
+  @property({type: Boolean, reflect: true}) open = false;
+
+  /** The items to list. Already filtered — the menu displays what it is given. */
+  @property({type: Array}) items: SlashMenuItem[] = [];
+
+  /** The query the items were matched against, shown in the heading. */
+  @property() query = '';
+
+  /** The heading shown when there is no query. */
+  @property() heading = 'Insert';
+
+  /** Shown in place of the list when there are no items. */
+  @property({attribute: 'empty-text'}) emptyText = 'No matches';
+
+  /** The most items to render at once. Remaining matches are reported in the footer. */
+  @property({attribute: 'max-items', type: Number}) maxItems = 25;
+
+  /** The element or caret rect the panel is positioned against. */
+  @property({attribute: false}) anchor: Element | VirtualElement | null = null;
+
+  /** The preferred placement of the panel. */
+  @property() placement: Placement = 'bottom-start';
+
+  /** The gap between the caret and the panel. */
+  @property({type: Number}) distance = 4;
+
+  @state() private activeIndex = 0;
+
+  private get visibleItems(): SlashMenuItem[] {
+    return this.maxItems > 0 ? this.items.slice(0, this.maxItems) : this.items;
+  }
+
+  /** The item that Enter would insert. */
+  get activeItem(): SlashMenuItem | undefined {
+    return this.visibleItems[this.activeIndex];
+  }
+
+  show() {
+    this.open = true;
+  }
+
+  hide() {
+    this.open = false;
+  }
+
+  /** Sets the active item by index, wrapping at both ends and skipping disabled items. */
+  setActiveIndex(index: number) {
+    const items = this.visibleItems;
+    const selectable = items.filter(item => !item.disabled).length;
+    if (!selectable) {
+      this.activeIndex = -1;
+      return;
+    }
+
+    let next = (index + items.length) % items.length;
+    // Walk in the direction of travel until a selectable item is found
+    const step = index < this.activeIndex ? -1 : 1;
+    while (items[next]?.disabled) {
+      next = (next + step + items.length) % items.length;
+    }
+
+    this.activeIndex = next;
+    void this.updateComplete.then(() => this.scrollActiveIntoView());
+  }
+
+  /** Moves the active item by `delta` places. */
+  moveActive(delta: number) {
+    this.setActiveIndex(this.activeIndex + delta);
+  }
+
+  /** Chooses the active item, as pressing Enter would. */
+  selectActive() {
+    const item = this.activeItem;
+    if (item) this.selectItem(item);
+  }
+
+  /** Recalculates the panel's position against its anchor. */
+  reposition() {
+    void this.position();
+  }
+
+  connectedCallback() {
+    super.connectedCallback();
+    if (this.open) void this.updateComplete.then(() => this.startPositioner());
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    this.stopPositioner();
+  }
+
+  private startPositioner() {
+    this.stopPositioner();
+    if (!this.anchor || !this.panel) return;
+
+    // autoUpdate keeps the panel on the caret through scrolling and resizes
+    this.stopAutoUpdate = autoUpdate(this.anchor, this.panel, () => void this.position());
+  }
+
+  private stopPositioner() {
+    this.stopAutoUpdate?.();
+    this.stopAutoUpdate = undefined;
+  }
+
+  private async position() {
+    const {anchor, panel} = this;
+    if (!this.open || !anchor || !panel) return;
+
+    const {x, y} = await computePosition(anchor, panel, {
+      placement: this.placement,
+      strategy: 'fixed',
+      middleware: [
+        offset(this.distance),
+        flip({padding: 8}),
+        shift({padding: 8}),
+        size({
+          padding: 8,
+          apply: ({availableHeight}) => {
+            panel.style.setProperty('--auto-size-available-height', `${Math.max(availableHeight, 0)}px`);
+          }
+        })
+      ]
+    });
+
+    Object.assign(panel.style, {left: `${x}px`, top: `${y}px`});
+  }
+
+  private selectItem(item: SlashMenuItem) {
+    if (item.disabled) return;
+
+    this.dispatchEvent(new CustomEvent(SLASH_ITEM_SELECT, {
+      bubbles: true,
+      cancelable: true,
+      composed: false,
+      detail: {item, query: this.query}
+    }));
+  }
+
+  private scrollActiveIntoView() {
+    const active = this.renderRoot.querySelector<HTMLElement>('[data-slash-item][aria-selected="true"]');
+    active?.scrollIntoView({block: 'nearest'});
+  }
+
+  // mousedown, not click: preventDefault keeps focus (and the caret) in the field
+  private readonly handleItemMouseDown = (event: MouseEvent) => {
+    event.preventDefault();
+
+    const index = Number((event.currentTarget as HTMLElement).dataset.index);
+    const item = this.visibleItems[index];
+    if (item) {
+      this.activeIndex = index;
+      this.selectItem(item);
+    }
+  };
+
+  protected willUpdate(changed: PropertyValues) {
+    super.willUpdate(changed);
+
+    // 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)) {
+      this.activeIndex = this.visibleItems.findIndex(item => !item.disabled);
+    }
+  }
+
+  protected updated(changed: PropertyValues) {
+    super.updated(changed);
+
+    if (changed.has('open') || changed.has('anchor')) {
+      if (this.open) {
+        this.startPositioner();
+      } else {
+        this.stopPositioner();
+      }
+    }
+
+    if (this.open) void this.position();
+  }
+
+  private renderItem(item: SlashMenuItem, index: number, showIcons: boolean) {
+    const isActive = index === this.activeIndex;
+    const token = item.value && item.value !== item.label && !item.value.includes('\n') ? item.value : '';
+
+    return html`
+      <button
+        type="button"
+        part="item"
+        class=${classMap({
+          'slash-menu__item': true,
+          'slash-menu__item--active': isActive,
+          'slash-menu__item--disabled': !!item.disabled
+        })}
+        role="option"
+        aria-selected=${isActive ? 'true' : 'false'}
+        aria-disabled=${item.disabled ? 'true' : 'false'}
+        data-slash-item
+        data-index=${index}
+        tabindex="-1"
+        @mousedown=${this.handleItemMouseDown}>
+        ${showIcons
+          ? html`
+            <span class="slash-menu__icon">
+              ${item.icon ? html`
+                <zn-icon src=${item.icon} size="16"></zn-icon>` : ''}
+            </span>`
+          : ''}
+        <span class="slash-menu__text">
+          <span class="slash-menu__label">${item.label}</span>
+          ${item.description ? html`
+            <span class="slash-menu__description">${item.description}</span>` : ''}
+        </span>
+        ${token ? html`
+          <code class="slash-menu__token">${token}</code>` : ''}
+      </button>`;
+  }
+
+  private renderItems() {
+    const items = this.visibleItems;
+    const showIcons = items.some(item => item.icon);
+    let lastGroup: string | undefined;
+
+    return items.map((item, index) => {
+      const group = 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)}`;
+    });
+  }
+
+  render() {
+    const hidden = this.items.length - this.visibleItems.length;
+
+    return html`
+      <div
+        part="panel"
+        class="slash-menu__panel"
+        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}
+        </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>` : ''}
+      </div>`;
+  }
+}

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

@@ -0,0 +1,120 @@
+@use "../../wc";
+
+:host {
+  --slash-menu-width: 320px;
+  --slash-menu-max-height: 260px;
+
+  display: contents;
+}
+
+:host(:not([open])) .slash-menu__panel {
+  display: none;
+}
+
+.slash-menu__panel {
+  display: flex;
+  flex-direction: column;
+  position: fixed;
+  top: 0;
+  left: 0;
+  width: var(--slash-menu-width);
+  max-width: var(--auto-size-available-width, none);
+  max-height: min(var(--slash-menu-max-height), var(--auto-size-available-height, 100vh));
+  overflow-y: auto;
+  overscroll-behavior: none;
+  z-index: var(--zn-z-index-dropdown);
+  padding: var(--zn-spacing-2x-small, 4px) 0;
+  background: var(--zn-panel-background-color);
+  border: solid var(--zn-panel-border-width, 1px) var(--zn-panel-border-color);
+  border-radius: var(--zn-border-radius, 6px);
+  box-shadow: var(--zn-shadow-medium);
+  font-family: var(--zn-font-sans);
+  font-size: var(--zn-font-size-medium);
+  color: rgb(var(--zn-text));
+}
+
+.slash-menu__heading,
+.slash-menu__group-heading,
+.slash-menu__footer,
+.slash-menu__empty {
+  padding: var(--zn-spacing-2x-small, 4px) var(--zn-spacing-small, 12px);
+  font-size: var(--zn-font-size-x-small);
+  color: var(--zn-color-neutral-500);
+  user-select: none;
+  -webkit-user-select: none;
+}
+
+.slash-menu__group-heading {
+  font-weight: var(--zn-font-weight-semibold);
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+}
+
+.slash-menu__footer {
+  border-top: solid var(--zn-panel-border-width, 1px) var(--zn-panel-border-color);
+  margin-top: var(--zn-spacing-2x-small, 4px);
+}
+
+.slash-menu__item {
+  display: flex;
+  align-items: center;
+  gap: var(--zn-spacing-x-small, 8px);
+  width: 100%;
+  padding: var(--zn-spacing-x-small, 8px) var(--zn-spacing-small, 12px);
+  border: none;
+  background: transparent;
+  color: inherit;
+  font: inherit;
+  text-align: left;
+  cursor: pointer;
+
+  &--active,
+  &:hover:not(&--disabled) {
+    background: var(--zn-input-background-color-hover);
+  }
+
+  &--disabled {
+    opacity: 0.5;
+    cursor: not-allowed;
+  }
+}
+
+.slash-menu__icon {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex: 0 0 16px;
+  color: var(--zn-color-neutral-500);
+}
+
+.slash-menu__text {
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+  flex: 1 1 auto;
+}
+
+.slash-menu__label {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.slash-menu__description {
+  font-size: var(--zn-font-size-x-small);
+  color: var(--zn-color-neutral-500);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.slash-menu__token {
+  flex: 0 1 auto;
+  max-width: 45%;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  font-family: var(--zn-font-mono);
+  font-size: var(--zn-font-size-x-small);
+  color: var(--zn-color-neutral-600);
+}

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

@@ -0,0 +1,154 @@
+import '../../../dist/zn.min.js';
+import {expect, fixture, html} from '@open-wc/testing';
+import {
+  filterSlashItems,
+  getSlashMenuPreset,
+  parseSlashItems,
+  registerSlashMenuPreset,
+  unregisterSlashMenuPreset
+} from './slash-menu-items';
+import type ZnSlashMenu from './slash-menu.component';
+
+describe('<zn-slash-menu>', () => {
+  it('should render a component', async () => {
+    const el = await fixture(html`
+      <zn-slash-menu></zn-slash-menu>`);
+
+    expect(el).to.exist;
+  });
+
+  it('lists the items it is given and starts on the first one', async () => {
+    const el = await fixture<ZnSlashMenu>(html`
+      <zn-slash-menu></zn-slash-menu>`);
+    el.items = [{label: 'Brand name', value: '{{BRAND_NAME}}'}, {label: 'Legal entity', value: '{{LEGAL_ENTITY}}'}];
+    el.show();
+    await el.updateComplete;
+
+    const items = el.shadowRoot!.querySelectorAll('[data-slash-item]');
+    expect(items.length).to.equal(2);
+    expect(el.activeItem?.label).to.equal('Brand name');
+  });
+
+  it('wraps when moving past either end and skips disabled items', async () => {
+    const el = await fixture<ZnSlashMenu>(html`
+      <zn-slash-menu></zn-slash-menu>`);
+    el.items = [
+      {label: 'One', value: '1'},
+      {label: 'Two', value: '2', disabled: true},
+      {label: 'Three', value: '3'}
+    ];
+    await el.updateComplete;
+
+    el.moveActive(1);
+    expect(el.activeItem?.label, 'skips the disabled item').to.equal('Three');
+
+    el.moveActive(1);
+    expect(el.activeItem?.label, 'wraps to the start').to.equal('One');
+
+    el.moveActive(-1);
+    expect(el.activeItem?.label, 'wraps to the end').to.equal('Three');
+  });
+
+  it('emits zn-slash-item-select when an item is clicked, without stealing focus', async () => {
+    const el = await fixture<ZnSlashMenu>(html`
+      <zn-slash-menu></zn-slash-menu>`);
+    el.items = [{label: 'Brand name', value: '{{BRAND_NAME}}'}];
+    el.show();
+    await el.updateComplete;
+
+    const selected: string[] = [];
+    el.addEventListener('zn-slash-item-select', (event: Event) => {
+      selected.push((event as CustomEvent<{item: {label: string}}>).detail.item.label);
+    });
+
+    const item = el.shadowRoot!.querySelector<HTMLButtonElement>('[data-slash-item]')!;
+    const event = new MouseEvent('mousedown', {bubbles: true, cancelable: true, composed: true});
+    item.dispatchEvent(event);
+
+    expect(selected).to.deep.equal(['Brand name']);
+    expect(event.defaultPrevented, 'mousedown is prevented so the field keeps focus').to.be.true;
+  });
+
+  it('reports how many matches were not rendered', async () => {
+    const el = await fixture<ZnSlashMenu>(html`
+      <zn-slash-menu max-items="2"></zn-slash-menu>`);
+    el.items = [{label: 'One'}, {label: 'Two'}, {label: 'Three'}];
+    el.show();
+    await el.updateComplete;
+
+    expect(el.shadowRoot!.querySelectorAll('[data-slash-item]').length).to.equal(2);
+    expect(el.shadowRoot!.querySelector('[part="footer"]')?.textContent).to.contain('1 more');
+  });
+});
+
+describe('slash menu items', () => {
+  describe('parseSlashItems', () => {
+    it('parses a JSON array', () => {
+      const items = parseSlashItems('[{"label":"Brand name","value":"{{BRAND_NAME}}"}]');
+
+      expect(items).to.deep.equal([{label: 'Brand name', value: '{{BRAND_NAME}}'}]);
+    });
+
+    it('parses the label=value shorthand', () => {
+      const items = parseSlashItems('Brand name={{BRAND_NAME}}, {{SUPPORT_EMAIL}}');
+
+      expect(items).to.deep.equal([
+        {label: 'Brand name', value: '{{BRAND_NAME}}'},
+        {label: '{{SUPPORT_EMAIL}}', value: '{{SUPPORT_EMAIL}}'}
+      ]);
+    });
+
+    it('returns nothing for empty or unparsable input', () => {
+      expect(parseSlashItems('')).to.deep.equal([]);
+      expect(parseSlashItems(null)).to.deep.equal([]);
+      expect(parseSlashItems('[{"nope":true}')).to.deep.equal([]);
+    });
+  });
+
+  describe('filterSlashItems', () => {
+    const items = [
+      {label: 'Support email', value: '{{SUPPORT_EMAIL}}', keywords: 'contact'},
+      {label: 'Brand name', value: '{{BRAND_NAME}}', description: 'Trading name'},
+      {label: 'Jurisdiction', value: '{{BRAND_JURISDICTION}}'}
+    ];
+
+    it('keeps declaration order for an empty query', () => {
+      expect(filterSlashItems(items, '').map(item => item.label))
+        .to.deep.equal(['Support email', 'Brand name', 'Jurisdiction']);
+    });
+
+    it('ranks label matches above value and keyword matches', () => {
+      expect(filterSlashItems(items, 'brand').map(item => item.label))
+        .to.deep.equal(['Brand name', 'Jurisdiction']);
+    });
+
+    it('matches keywords and descriptions', () => {
+      expect(filterSlashItems(items, 'contact').map(item => item.label)).to.deep.equal(['Support email']);
+      expect(filterSlashItems(items, 'trading').map(item => item.label)).to.deep.equal(['Brand name']);
+    });
+
+    it('honours order over declaration order', () => {
+      const ordered = filterSlashItems([{label: 'Second', order: 2}, {label: 'First', order: 1}], '');
+
+      expect(ordered.map(item => item.label)).to.deep.equal(['First', 'Second']);
+    });
+
+    it('drops items that match nothing', () => {
+      expect(filterSlashItems(items, 'nothing here')).to.deep.equal([]);
+    });
+  });
+
+  describe('presets', () => {
+    it('resolves registered presets by name', () => {
+      registerSlashMenuPreset('test-legal', [{label: 'Brand name', value: '{{BRAND_NAME}}'}]);
+      registerSlashMenuPreset('test-support', [{label: 'Support email', value: '{{SUPPORT_EMAIL}}'}]);
+
+      expect(getSlashMenuPreset('test-legal, test-support').map(item => item.label))
+        .to.deep.equal(['Brand name', 'Support email']);
+
+      unregisterSlashMenuPreset('test-legal');
+      unregisterSlashMenuPreset('test-support');
+      expect(getSlashMenuPreset('test-legal')).to.deep.equal([]);
+    });
+  });
+});