@kubex/zinc 1.1.80 → 1.1.81

package/docs/pages/components/inline-edit.md

@@ -122,8 +122,9 @@ Use `input-type="textarea"` for multi-line text content.
 {% raw %}
 
 `slash-items`, `slash-preset`, `slash-trigger` and `slash-heading` are forwarded to the inner
-[`zn-textarea`](/components/textarea#slash-menu-quick-insertions), so typing `/` offers replacement strings at the
-caret. The menu claims `Enter` and `Escape` while it is open, so choosing an item neither submits nor cancels the edit.
+[`zn-textarea`](/components/textarea#slash-menu-quick-insertions) or
+[`zn-input`](/components/input#slash-menu-quick-insertions), so typing `/` offers replacement strings at the caret on
+both. The menu claims `Enter` and `Escape` while it is open, so choosing an item neither submits nor cancels the edit.
 
 ```html:preview
 <zn-inline-edit

package/docs/pages/components/input.md

@@ -464,6 +464,27 @@ Add the `trigger-submit` attribute to make pressing Enter in the input always su
 </script>
 ```
 
+### Slash Menu Quick Insertions
+
+{% raw %}
+
+Typing `/` opens a menu at the caret, exactly as it does on
+[`zn-textarea`](/components/textarea#slash-menu-quick-insertions) — useful for short single-line copy that carries
+replacement strings, such as a headline or a button label. The same `slash-items`, `slash-preset`, `slash-trigger` and
+`slash-heading` attributes apply, and `zn-slash-item` children work too.
+
+```html:preview
+<zn-input
+  label="Confirmation headline"
+  help-text="Type / to insert a replacement string"
+  slash-items="Brand name={{BRAND_NAME}}, Customer email={{CUSTOMER_EMAIL}}"></zn-input>
+```
+
+While the menu is open it claims `↑`, `↓`, `Enter`, `Tab` and `Escape`, so choosing an item does not submit the
+surrounding form the way `Enter` otherwise would.
+
+{% endraw %}
+
 ### Customizing Label Position
 
 Use [CSS parts](#css-parts) to customize the way form controls are drawn. This example uses CSS grid to position the

package/docs/pages/components/remarkd-editor.md

@@ -42,6 +42,28 @@ block committed empty is removed.
 ></zn-remarkd-editor>
 ```
 
+### Slash Menu
+
+Typing `/` in an empty block opens a [slash menu](/components/slash-menu) of
+block types at the caret. Keep typing to narrow it, `↑`/`↓` to move, `Enter` or
+`Tab` to insert, `Escape` to dismiss. The menu only appears in a block that is
+nothing but the slash command — a prefix like `## ` is not valid remarkd
+part-way through a line — so `/` in the middle of a sentence stays literal
+text.
+
+Choosing a block type replaces the command with its remarkd prefix and leaves
+the caret ready to type: `Heading 2` gives you `## `, `Code` opens a fence with
+the caret inside it, and `Image` opens the upload picker instead of inserting
+text. The same block types are on the toolbar, which inserts them as new blocks
+at the end of the document.
+
+```html:preview
+<zn-remarkd-editor
+  name="content"
+  value="Click the empty space below this block, then type / to see the menu."
+></zn-remarkd-editor>
+```
+
 ### Images
 
 Adding an image shows a `zn-file` drop area inline, at the point in the
@@ -92,6 +114,27 @@ with a blank line inside
 ></zn-remarkd-editor>
 ````
 
+### Raw Source
+
+Add `allow-raw` for a toolbar toggle that swaps the block view for the whole
+document as editable remarkd source. Useful for pasting in a finished document
+or fixing syntax the block view makes awkward. Toggling back re-splits the
+source into blocks, normalising the spacing between them to a single blank
+line. The toggle is only offered on editable editors — `readonly` and
+`disabled` instances hide the toolbar entirely.
+
+```html:preview
+<zn-remarkd-editor
+  name="content"
+  allow-raw
+  value="# Raw Source
+
+Hit the toggle at the right of the toolbar to edit this whole document at once.
+
+NOTE: The value is the same remarkd source either way."
+></zn-remarkd-editor>
+```
+
 ### Form Integration
 
 `zn-remarkd-editor` is a [form control](/getting-started/form-controls); its

package/docs/pages/components/slash-menu.md

@@ -113,20 +113,13 @@ The menu doesn't listen for keys itself — whatever owns the field decides whic
 scrolls when its content exceeds `--slash-menu-max-height`.
 
 ```html:preview
-<zn-button id="capped-toggle">Show 3 of 9</zn-button>
-<zn-slash-menu id="capped-menu" max-items="3"></zn-slash-menu>
-
-<script type="module">
-  const menu = document.getElementById('capped-menu');
-  const toggle = document.getElementById('capped-toggle');
-
-  await customElements.whenDefined('zn-slash-menu');
-
-  menu.items = Array.from({length: 9}, (_, i) => ({label: `Replacement ${i + 1}`, value: `{{TOKEN_${i + 1}}}`}));
-  menu.anchor = toggle;
-
-  toggle.addEventListener('click', () => menu.open ? menu.hide() : menu.show());
-</script>
+<zn-textarea label="Terms and conditions" rows="5" help-text="Type / to see 3 of 9, then keep typing to narrow"
+             slash-items="Brand name={{BRAND_NAME}}, Legal entity={{LEGAL_ENTITY}}, Jurisdiction={{JURISDICTION}},
+                          Customer name={{CUSTOMER_NAME}}, Customer email={{CUSTOMER_EMAIL}},
+                          Invoice number={{INVOICE_NUMBER}}, Invoice date={{INVOICE_DATE}},
+                          Support email={{SUPPORT_EMAIL}}, Support phone={{SUPPORT_PHONE}}">
+  <zn-slash-menu slot="slash-menu" heading="Replacement strings" max-items="3"></zn-slash-menu>
+</zn-textarea>
 ```
 
 ### Attaching It To Your Own Field

package/docs/pages/components/translations.md

@@ -328,8 +328,8 @@ A complete example showing product content management with translations.
 {% raw %}
 
 Copy that carries replacement strings — `{{BRAND_NAME}}` and the like — needs the same tokens in every language. Set
-`slash-items` alongside `input-type="textarea"` and typing `/` offers them at the caret, in whichever language is
-being edited. The attribute takes the same shorthand and JSON that
+`slash-items` and typing `/` offers them at the caret, in whichever language is being edited. This works on both the
+single-line default and `input-type="textarea"`. The attribute takes the same shorthand and JSON that
 [`zn-textarea`](/components/textarea#slash-menu-quick-insertions) accepts, and `slash-preset`, `slash-trigger` and
 `slash-heading` are forwarded too.
 
@@ -365,7 +365,7 @@ way `Enter` otherwise would.
 | `flush`     | `boolean`                   | `false`         | Removes padding for compact layout                                   |
 | `languages` | `Record<string, string>`    | `{en: "EN"}`    | Object mapping language codes to display names                       |
 | `values`    | `Record<string, string>`    | `{}`            | Object mapping language codes to translation text                    |
-| `slash-items`   | `SlashMenuItem[]`       | `[]`            | Quick insertions offered by the slash menu on a `textarea` input     |
+| `slash-items`   | `SlashMenuItem[]`       | `[]`            | Quick insertions offered by the slash menu                           |
 | `slash-preset`  | `string`                | `''`            | Registered item sets to offer, comma separated                       |
 | `slash-trigger` | `string`                | `'/'`           | The characters that open the slash menu                              |
 | `slash-heading` | `string`                | `'Insert'`      | Heading shown above the slash menu's items                           |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubex/zinc",
-  "version": "1.1.80",
+  "version": "1.1.81",
   "description": "A collection of web components for building web applications based off of @shoelace-style/Shoelace",
   "keywords": [
     "web components",

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

@@ -99,8 +99,8 @@ export default class ZnInlineEdit extends ZincElement implements ZincFormControl
   @property({ attribute: "textarea-rows", type: Number }) textareaRows: 1;
 
   /**
-   * Quick insertions offered by the slash menu of a `textarea` input. Accepts a JSON array of items, or the
-   * shorthand `Brand name={{BRAND_NAME}}, Support email={{SUPPORT_EMAIL}}`. Forwarded to the inner `zn-textarea`.
+   * Quick insertions offered by the slash menu of a `text` or `textarea` input. Accepts a JSON array of items, or
+   * the shorthand `Brand name={{BRAND_NAME}}, Support email={{SUPPORT_EMAIL}}`.
    */
   @property({
     attribute: 'slash-items',
@@ -482,6 +482,11 @@ export default class ZnInlineEdit extends ZincElement implements ZincFormControl
                 autocomplete=${ifDefined(this.autocomplete)}
                 required=${ifDefined(this.required)}
                 dir="${this.dir}"
+                slash-trigger="${this.slashTrigger}"
+                slash-heading="${this.slashHeading}"
+                slash-preset="${this.slashPreset}"
+                .slashItems="${this.slashItems}"
+                .slashItemsProvider="${this.slashItemsProvider}"
                 @zn-input="${this.handleInput}"
                 @zn-blur="${this.handleBlur}">
       </zn-input>`;

package/src/components/input/input.component.ts

@@ -1,15 +1,19 @@
 import {classMap} from "lit/directives/class-map.js";
 import {defaultValue} from "../../internal/default-value";
 import {FormControlController} from "../../internal/form";
+import {getSlashMenuPreset, parseSlashItems, type SlashMenuItem} from "../slash-menu/slash-menu-items";
 import {HasSlotController} from "../../internal/slot";
 import {html, unsafeCSS} from 'lit';
 import {ifDefined} from "lit/directives/if-defined.js";
 import {live} from "lit/directives/live.js";
 import {LocalizeController} from "../../utilities/localize";
 import {property, query, state} from 'lit/decorators.js';
+import {SlashMenuController} from "../slash-menu/slash-menu-controller";
 import {watch} from "../../internal/watch";
 import ZincElement from '../../internal/zinc-element';
 import ZnIcon from "../icon";
+import ZnSlashItem from "../slash-item";
+import ZnSlashMenu from "../slash-menu";
 import ZnTooltip from "../tooltip";
 import type {ZincFormControl} from '../../internal/zinc-element';
 
@@ -40,8 +44,20 @@ import styles from './input.scss';
  * @slot show-password-icon - An icon to use in lieu of the default show password icon.
  * @slot hide-password-icon - An icon to use in lieu of the default hide password icon.
  * @slot help-text - Text that describes how to use the input. Alternatively, you can use the `help-text` attribute.
+ * @slot slash-items - `<zn-slash-item>` elements describing the insertions offered by the slash menu. Items are
+ *  picked up wherever they sit inside the input, so this slot name is optional.
+ * @slot slash-menu - A `<zn-slash-menu>` to use instead of the built-in one, so its heading, sizing and styling can
+ *  be set in markup. Any `<zn-slash-item>` children of it become the menu's items.
+ *
+ * @dependency zn-slash-item
+ * @dependency zn-slash-menu
+ *
+ * @event zn-slash-select - Emitted when a slash menu item is chosen. Cancelable — call `preventDefault()` to
+ *  suppress the insertion and handle the item yourself.
+ * @event zn-slash-insert - Emitted after a slash menu item's value has been inserted.
  *
  * @csspart form-control - The form control that wraps the label, input, and help text.
+ * @csspart slash-menu - The slash menu shown at the caret.
  * @csspart form-control-label - The label's wrapper.
  * @csspart form-control-input - The input's wrapper.
  * @csspart form-control-help-text - The help text's wrapper.
@@ -62,6 +78,8 @@ export default class ZnInput extends ZincElement implements ZincFormControl {
   static styles = unsafeCSS(styles);
   static dependencies = {
     'zn-icon': ZnIcon,
+    'zn-slash-item': ZnSlashItem,
+    'zn-slash-menu': ZnSlashMenu,
     'zn-tooltip': ZnTooltip
   }
 
@@ -71,10 +89,24 @@ export default class ZnInput extends ZincElement implements ZincFormControl {
   private readonly hasSlotController = new HasSlotController(this, 'help-text', 'label', 'label-tooltip');
   private readonly localize = new LocalizeController(this);
 
+  private readonly slashController = new SlashMenuController(this, {
+    menu: () => this.mountSlashMenu(),
+    items: search => this.resolveSlashItems(search),
+    trigger: () => this.slashTrigger,
+    onSelect: (item, search) => !this.emit('zn-slash-select', {
+      detail: {item, query: search}
+    }).defaultPrevented,
+    onInsert: (item, value) => this.emit('zn-slash-insert', {detail: {item, value}})
+  });
+
   @query('.input__control') input: HTMLInputElement;
   @query('.input__color-picker') colorPicker: HTMLInputElement;
+  @query('zn-slash-menu') slashMenuElement: ZnSlashMenu | null;
 
   @state() private hasFocus = false;
+
+  /** Renders the slash menu only once it has been needed, keeping unused inputs cheap. */
+  @state() private hasSlashMenu = false;
   @state() private isUserTyping = false;
   @property() title = "" // make reactive pass through
 
@@ -224,6 +256,35 @@ export default class ZnInput extends ZincElement implements ZincFormControl {
    */
   @property() inputmode: 'none' | 'text' | 'decimal' | 'numeric' | 'tel' | 'search' | 'email' | 'url';
 
+  /**
+   * Quick insertions offered by the slash menu. Accepts a JSON array of items, or the shorthand
+   * `Brand name={{BRAND_NAME}}, Support email={{SUPPORT_EMAIL}}`. Can also be set as an array of
+   * `SlashMenuItem` objects in JavaScript.
+   */
+  @property({
+    attribute: 'slash-items',
+    converter: {
+      fromAttribute: (value: string) => parseSlashItems(value),
+      toAttribute: (value: SlashMenuItem[]) => JSON.stringify(value)
+    }
+  })
+  slashItems: SlashMenuItem[] = [];
+
+  /** Names of item sets registered with `registerSlashMenuPreset`, comma separated. */
+  @property({attribute: 'slash-preset'}) slashPreset = '';
+
+  /** The characters that open the slash menu. */
+  @property({attribute: 'slash-trigger'}) slashTrigger = '/';
+
+  /** The heading shown above the slash menu's items. */
+  @property({attribute: 'slash-heading'}) slashHeading = 'Insert';
+
+  /**
+   * Resolves additional items each time the menu opens, for lists that come from elsewhere (e.g. an
+   * API). Receives the current query and may return a promise. JavaScript only.
+   */
+  @property({attribute: false}) slashItemsProvider?: (query: string) => SlashMenuItem[] | Promise<SlashMenuItem[]>;
+
   /**
    * When enabled, pressing enter will always submit the surrounding form, even when the form uses
    * enter-navigation to move between fields.
@@ -565,6 +626,10 @@ export default class ZnInput extends ZincElement implements ZincFormControl {
   }
 
   private handleKeyDown(event: KeyboardEvent) {
+    // The slash menu claims its own keys; while it is open Escape closes it and Enter picks an item,
+    // rather than blurring the field or submitting the form
+    if (this.slashController.open) return;
+
     if (event.key === 'Escape') {
       this.input.blur();
       event.stopPropagation();
@@ -632,6 +697,78 @@ export default class ZnInput extends ZincElement implements ZincFormControl {
     if (this.type === 'range' && this.value === '') {
       this.value = this.input.value;
     }
+
+    this.slashController.attach(this.input);
+  }
+
+  /** The insertions the slash menu offers, gathered from every source, in the order they were declared. */
+  async resolveSlashItems(search = ''): Promise<SlashMenuItem[]> {
+    const items = [
+      ...getSlashMenuPreset(this.slashPreset),
+      ...this.slashItems,
+      ...this.slottedSlashItems()
+    ];
+
+    const provided = await this.slashItemsProvider?.(search);
+    return provided ? [...items, ...provided] : items;
+  }
+
+  /** Opens the slash menu at the caret, inserting the trigger if it isn't already there. */
+  async showSlashMenu() {
+    this.focus();
+
+    const caret = this.input.selectionStart ?? this.input.value.length;
+    const precedes = this.input.value.slice(caret - this.slashTrigger.length, caret);
+    if (precedes !== this.slashTrigger) {
+      this.setRangeText(this.slashTrigger, caret, caret, 'end');
+    }
+
+    await this.updateComplete;
+    this.slashController.requestOpen();
+  }
+
+  /** Closes the slash menu. */
+  hideSlashMenu() {
+    this.slashController.close();
+  }
+
+  private slottedSlashItems(): SlashMenuItem[] {
+    const elements = [...this.querySelectorAll<ZnSlashItem>('zn-slash-item')];
+
+    return elements.map(element => {
+      // Elements from a different zinc build may not have upgraded, so fall back to their markup
+      if (typeof element.toSlashMenuItem === 'function') return element.toSlashMenuItem();
+
+      const value = element.getAttribute('value') ?? (element.textContent ?? '').trim();
+      const order = element.getAttribute('order');
+      const caretOffset = element.getAttribute('caret-offset');
+
+      return {
+        label: element.getAttribute('label') ?? value,
+        value,
+        icon: element.getAttribute('icon') ?? undefined,
+        description: element.getAttribute('description') ?? undefined,
+        keywords: element.getAttribute('keywords') ?? undefined,
+        group: element.getAttribute('group') ?? undefined,
+        action: element.getAttribute('action') ?? undefined,
+        order: order === null ? undefined : Number(order),
+        caretOffset: caretOffset === null ? undefined : Number(caretOffset),
+        disabled: element.hasAttribute('disabled')
+      };
+    });
+  }
+
+  private async mountSlashMenu(): Promise<ZnSlashMenu | null> {
+    // A slotted menu is the author's own: it keeps its own heading, sizing and styling
+    const slotted = this.querySelector<ZnSlashMenu>('zn-slash-menu');
+    if (slotted) return slotted;
+
+    if (!this.hasSlashMenu) {
+      this.hasSlashMenu = true;
+      await this.updateComplete;
+    }
+
+    return this.slashMenuElement;
   }
 
   @watch('disabled', {waitUntilFirstUpdate: true})
@@ -958,6 +1095,12 @@ export default class ZnInput extends ZincElement implements ZincFormControl {
                 : ''}
             </span>
           </div>
+          ${this.hasSlashMenu
+            ? html`
+              <zn-slash-menu part="slash-menu" heading=${this.slashHeading}></zn-slash-menu>`
+            : ''}
+          <slot name="slash-menu"></slot>
+          <slot name="slash-items" hidden></slot>
         </div>
 
         <div

package/src/components/input/input.test.ts

@@ -1,7 +1,8 @@
 import '../../../dist/zn.min.js';
-import {expect, fixture, html} from '@open-wc/testing';
+import {expect, fixture, html, waitUntil} from '@open-wc/testing';
 import {clearFormStoreValues} from '../../utilities/form';
 import type ZnInput from './input.component';
+import type ZnSlashMenu from '../slash-menu/slash-menu.component';
 
 describe('<zn-input>', () => {
   it('should render a component', async () => {
@@ -217,4 +218,115 @@ describe('<zn-input>', () => {
       expect(contextNote(el)).to.equal('Custom');
     });
   });
+
+  describe('slash menu', () => {
+    function slashMenuOf(el: ZnInput) {
+      return el.shadowRoot!.querySelector<ZnSlashMenu>('zn-slash-menu');
+    }
+
+    /** Types `text` into the field the way a user would, leaving the caret at the end. */
+    function type(el: ZnInput, text: string) {
+      el.input.value = text;
+      el.input.setSelectionRange(text.length, text.length);
+      el.input.dispatchEvent(new InputEvent('input', {bubbles: true, composed: true}));
+    }
+
+    async function openSlashMenu(el: ZnInput, text = '/') {
+      await el.updateComplete;
+      el.focus();
+      type(el, text);
+      await waitUntil(() => slashMenuOf(el)?.open, 'the slash menu never opened');
+
+      return slashMenuOf(el)!;
+    }
+
+    it('stays closed when no items are configured', async () => {
+      const el = await fixture<ZnInput>(html`<zn-input></zn-input>`);
+      await el.updateComplete;
+
+      el.focus();
+      type(el, '/');
+      await el.updateComplete;
+      await el.updateComplete;
+
+      expect(slashMenuOf(el)?.open ?? false, 'nothing to insert, so nothing to show').to.be.false;
+    });
+
+    it('opens on the trigger with items from the slash-items attribute', async () => {
+      const el = await fixture<ZnInput>(html`
+        <zn-input slash-items="Brand name={{BRAND_NAME}}, Support email={{SUPPORT_EMAIL}}"></zn-input>`);
+      const menu = await openSlashMenu(el);
+
+      expect(menu.items.map(item => item.label)).to.deep.equal(['Brand name', 'Support email']);
+    });
+
+    it('collects items from slotted zn-slash-item elements', async () => {
+      const el = await fixture<ZnInput>(html`
+        <zn-input>
+          <zn-slash-item label="Brand name" value="{{BRAND_NAME}}"></zn-slash-item>
+        </zn-input>`);
+      const menu = await openSlashMenu(el);
+
+      expect(menu.items.map(item => item.label)).to.deep.equal(['Brand name']);
+    });
+
+    it('inserts the active item on Enter, replacing the trigger and query', async () => {
+      const el = await fixture<ZnInput>(html`
+        <zn-input slash-items="Brand name={{BRAND_NAME}}"></zn-input>`);
+      await openSlashMenu(el, 'Welcome to /bra');
+
+      el.input.dispatchEvent(new KeyboardEvent('keydown', {
+        key: 'Enter',
+        bubbles: true,
+        composed: true,
+        cancelable: true
+      }));
+      await el.updateComplete;
+
+      expect(el.value).to.equal('Welcome to {{BRAND_NAME}}');
+    });
+
+    it('does not submit the form when Enter chooses an item', async () => {
+      const form = await fixture<HTMLFormElement>(html`
+        <form>
+          <zn-input slash-items="Brand name={{BRAND_NAME}}"></zn-input>
+        </form>`);
+      const el = form.querySelector<ZnInput>('zn-input')!;
+
+      let submits = 0;
+      form.addEventListener('submit', event => {
+        event.preventDefault();
+        submits++;
+      });
+
+      await openSlashMenu(el);
+      el.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);
+    });
+
+    it('closes on Escape without blurring the field', async () => {
+      const el = await fixture<ZnInput>(html`
+        <zn-input slash-items="Brand name={{BRAND_NAME}}"></zn-input>`);
+      const menu = await openSlashMenu(el);
+
+      el.input.dispatchEvent(new KeyboardEvent('keydown', {
+        key: 'Escape',
+        bubbles: true,
+        composed: true,
+        cancelable: true
+      }));
+      await el.updateComplete;
+
+      expect(menu.open, 'Escape should close the menu').to.be.false;
+      expect(el.shadowRoot!.activeElement, 'the field should keep focus').to.equal(el.input);
+    });
+  });
 });