@kubex/zinc 1.1.78 → 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/rating/rating.component.ts

@@ -112,7 +112,16 @@ export default class ZnRating extends ZincElement implements ZincFormControl {
 
   private _getValueFromXCoordinate(coordinate: number): number {
     const {left, width} = this.symbols.getBoundingClientRect();
-    const value = this._roundToPrecision(((coordinate - left) / width) * this.max, this.precision);
+    // Symbols are spaced with a gap rather than padding, so the symbols only cover part of the
+    // container and a plain width-to-value ratio would skew fractions within each symbol.
+    const gap = parseFloat(getComputedStyle(this.symbols).columnGap) || 0;
+    const symbolWidth = (width - gap * (this.max - 1)) / this.max;
+    const stride = symbolWidth + gap;
+    const position = Math.min(Math.max(coordinate - left, 0), width);
+    const index = Math.min(Math.floor(position / stride), this.max - 1);
+    // Landing in a gap reads as the preceding symbol being complete.
+    const fraction = Math.min((position - index * stride) / symbolWidth, 1);
+    const value = this._roundToPrecision(index + fraction, this.precision);
 
     return Math.min(Math.max(value, 0), this.max);
   }

package/src/components/rating/rating.scss

@@ -5,7 +5,7 @@
   --symbol-color: rgb(var(--zn-border-color));
   --symbol-color-active: var(--zn-color-amber-400);
   --symbol-size: 1.2rem;
-  --symbol-spacing: 4px;
+  --symbol-spacing: var(--zn-spacing-x-small);
   --preview-color: rgb(var(--zn-text));
   --preview-size: 0.875rem;
 
@@ -31,15 +31,12 @@
   &__symbols {
     display: inline-flex;
     position: relative;
+    gap: var(--symbol-spacing);
     font-size: var(--symbol-size);
     line-height: 0;
     color: var(--symbol-color);
     white-space: nowrap;
     cursor: pointer;
-
-    > * {
-      padding: var(--symbol-spacing);
-    }
   }
 
   &__symbol--active,
@@ -53,8 +50,8 @@
 
   &__partial--filled {
     position: absolute;
-    top: var(--symbol-spacing);
-    left: var(--symbol-spacing);
+    top: 0;
+    left: 0;
   }
 
   &__symbol {
@@ -106,7 +103,7 @@
 
   &--small {
     --symbol-size: 1rem;
-    --symbol-spacing: 2px;
+    --symbol-spacing: var(--zn-spacing-2x-small);
   }
 
   &--medium {
@@ -115,6 +112,6 @@
 
   &--large {
     --symbol-size: 1.5rem;
-    --symbol-spacing: 6px;
+    --symbol-spacing: 12px;
   }
 }

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();
+  }
+}