@raylang/elements 0.8.0 → 0.9.0

package/core/complete.js

@@ -0,0 +1,252 @@
+// Inline suggestions for a text field (ray-input, ray-textarea): while the
+// user types, `host.complete(text, caret)` says which part of the text a
+// suggestion would replace and with what ({ from, to, items }, or null);
+// a listbox opens under that part, in the top layer, and the chosen item
+// replaces it as an edit (undoable, an ordinary input event).
+//
+// The combobox pattern: the control gets aria-autocomplete, aria-expanded,
+// aria-controls and aria-activedescendant; the listbox lives in the same
+// shadow root, so the ids work. ArrowUp/Down move, Enter or Tab accept,
+// Escape closes, Ctrl+Space asks; the keys are taken before the control's
+// own (Enter submitting, Escape closing a dialog) only while the list is
+// open.
+
+import { css, uid } from "./core.js";
+import { TextLayer, syncHighlight } from "./textlayer.js";
+
+export const completeStyles = css`
+  .suggestions {
+    position: fixed;
+    inset: auto;
+    box-sizing: border-box;
+    min-width: 12rem;
+    max-width: min(28rem, calc(100vw - 16px));
+    max-height: 14rem;
+    margin: 0;
+    padding: var(--ray-space-1);
+    overflow-y: auto;
+    font-size: var(--ray-font-size-sm);
+    color: var(--ray-popover-foreground);
+    background: var(--ray-popover);
+    border: 1px solid var(--ray-border);
+    border-radius: var(--ray-radius-default);
+    box-shadow: var(--ray-shadow-md);
+  }
+  .suggestion {
+    display: flex;
+    align-items: baseline;
+    gap: var(--ray-space-3);
+    padding: var(--ray-space-1) var(--ray-space-2);
+    border-radius: var(--ray-radius-sm);
+    cursor: default;
+    white-space: nowrap;
+  }
+  .suggestion[aria-selected="true"] { color: var(--ray-accent-foreground); background: var(--ray-accent); }
+  .suggestion .s-label { flex: none; font-family: var(--ray-font-mono); }
+  .suggestion .s-detail { min-width: 0; overflow: hidden; text-overflow: ellipsis; color: var(--ray-muted-foreground); }
+  .suggestion .s-description { display: block; font-size: var(--ray-font-size-xs); color: var(--ray-muted-foreground); }
+`;
+
+/** The layer of a field, made once (shared with highlight). */
+export function layerOf(host) {
+  host._textLayer ??= new TextLayer(host.control);
+  return host._textLayer;
+}
+
+class Completer {
+  constructor(host) {
+    this.host = host;
+    const c = (this.control = host.control);
+    this.list = document.createElement("div");
+    this.list.className = "suggestions";
+    this.list.id = uid("suggestions");
+    this.list.setAttribute("part", "suggestions");
+    this.list.setAttribute("role", "listbox");
+    this.list.popover = "manual";
+    host.shadowRoot.append(this.list);
+    this.open = null; // { items, index, from, to }
+    this.asked = 0;
+    this.inserting = false;
+    c.setAttribute("aria-autocomplete", "list");
+    c.setAttribute("aria-expanded", "false");
+    c.setAttribute("aria-controls", this.list.id);
+    if (c.localName === "input") c.setAttribute("role", "combobox");
+    // Choosing with the pointer keeps the focus (and the caret) in the field.
+    this.list.addEventListener("pointerdown", (e) => e.preventDefault());
+    this.list.addEventListener("click", (e) => {
+      const option = e.target.closest(".suggestion");
+      if (option) this.accept(Number(option.dataset.index));
+    });
+    c.addEventListener("input", () => {
+      if (!this.inserting) this.ask();
+    });
+    c.addEventListener("click", () => this.open && this.ask());
+    c.addEventListener("blur", () => this.close());
+    // The caret moved along the text (on keyup it has landed): ask where it is now.
+    c.addEventListener("keyup", (e) => {
+      if (this.open && ["ArrowLeft", "ArrowRight", "Home", "End"].includes(e.key)) this.ask();
+    });
+    // Captured on the host: before the control's Enter and a dialog's Escape.
+    host.addEventListener("keydown", (e) => this.key(e), { capture: true });
+  }
+
+  /** Calls complete() for the text and caret now; shows or closes the list. */
+  async ask() {
+    const c = this.control;
+    const fn = this.host.complete;
+    if (typeof fn !== "function" || c.selectionStart !== c.selectionEnd || c.readOnly || c.disabled) {
+      this.close();
+      return;
+    }
+    const n = ++this.asked;
+    let result = null;
+    try {
+      result = await fn(c.value, c.selectionStart);
+    } catch (err) {
+      console.error("ray-elements: complete() threw", err);
+    }
+    // A later keystroke asked again, or the field lost the focus meanwhile.
+    if (n !== this.asked || this.host.shadowRoot.activeElement !== c) return;
+    const items = Array.isArray(result?.items) ? result.items.filter((i) => i && i.value !== undefined) : [];
+    if (!items.length) {
+      this.close();
+      return;
+    }
+    const length = c.value.length;
+    const from = Math.max(0, Math.min(length, Math.trunc(result.from ?? c.selectionStart)));
+    const to = Math.max(from, Math.min(length, Math.trunc(result.to ?? c.selectionStart)));
+    this.show(items, from, to);
+  }
+
+  show(items, from, to) {
+    this.list.setAttribute("aria-label", this.host.suggestionsLabel ?? "Suggestions");
+    this.list.replaceChildren(...items.map((item, i) => {
+      const option = document.createElement("div");
+      option.className = "suggestion";
+      option.id = `${this.list.id}-${i}`;
+      option.dataset.index = String(i);
+      option.setAttribute("role", "option");
+      option.setAttribute("part", "suggestion");
+      const label = document.createElement("span");
+      label.className = "s-label";
+      label.textContent = item.label ?? String(item.value);
+      option.append(label);
+      if (item.detail) {
+        const detail = document.createElement("span");
+        detail.className = "s-detail";
+        detail.textContent = item.detail;
+        option.append(detail);
+      }
+      if (item.description) {
+        const d = document.createElement("span");
+        d.className = "s-description";
+        d.textContent = item.description;
+        label.append(d);
+      }
+      return option;
+    }));
+    const keep = this.open ? this.open.items[this.open.index]?.value : undefined;
+    const index = Math.max(0, items.findIndex((i) => i.value === keep));
+    this.open = { items, index, from, to };
+    if (!this.list.matches(":popover-open")) this.list.showPopover();
+    this.control.setAttribute("aria-expanded", "true");
+    this.select(index);
+    this.place();
+  }
+
+  // Under the text it would replace; above it when there is no room below.
+  place() {
+    const at = layerOf(this.host);
+    // The layer's text as it is now (it is otherwise repainted on update).
+    syncHighlight(this.host);
+    const r = at.rectAt(this.open.from);
+    // A one-line field: below its box, not inside it; a textarea: below the line.
+    const box = at.multi ? r : this.control.parentElement.getBoundingClientRect();
+    const w = this.list.offsetWidth;
+    const h = this.list.offsetHeight;
+    const gap = 4;
+    const left = Math.max(8, Math.min(r.left, innerWidth - w - 8));
+    const below = box.bottom + gap;
+    const top = below + h <= innerHeight - 8 ? below : Math.max(8, box.top - gap - h);
+    this.list.style.left = `${left}px`;
+    this.list.style.top = `${top}px`;
+  }
+
+  select(index) {
+    this.open.index = index;
+    const options = [...this.list.children];
+    options.forEach((o, i) => o.setAttribute("aria-selected", String(i === index)));
+    const current = options[index];
+    if (!current) return;
+    this.control.setAttribute("aria-activedescendant", current.id);
+    const top = current.offsetTop;
+    if (top < this.list.scrollTop) this.list.scrollTop = top;
+    else if (top + current.offsetHeight > this.list.scrollTop + this.list.clientHeight) this.list.scrollTop = top + current.offsetHeight - this.list.clientHeight;
+  }
+
+  close() {
+    this.asked++;
+    if (!this.open) return;
+    this.open = null;
+    this.control.setAttribute("aria-expanded", "false");
+    this.control.removeAttribute("aria-activedescendant");
+    if (this.list.matches(":popover-open")) this.list.hidePopover();
+  }
+
+  /** Replaces from–to with the item's value, as an edit. */
+  accept(index) {
+    const { items, from, to } = this.open ?? {};
+    const item = items?.[index];
+    this.close();
+    if (!item) return;
+    const c = this.control;
+    const text = String(item.value);
+    c.focus();
+    c.setSelectionRange(from, to);
+    this.inserting = true;
+    try {
+      // execCommand edits the focused element and keeps undo; without the
+      // focus (a window in the background) it may do nothing: set it then.
+      const focused = this.host.shadowRoot.activeElement === c;
+      if (!focused || !document.execCommand("insertText", false, text) || c.value.slice(from, from + text.length) !== text) {
+        c.value = c.value.slice(0, from) + text + c.value.slice(to);
+        c.setSelectionRange(from + text.length, from + text.length);
+        c.dispatchEvent(new Event("input", { bubbles: true, composed: true }));
+      }
+    } finally {
+      this.inserting = false;
+    }
+    this.host.emit("ray-complete", { item, from, to });
+  }
+
+  key(e) {
+    if (e.composedPath()[0] !== this.control) return;
+    if (e.key === " " && e.ctrlKey) {
+      e.preventDefault();
+      this.ask();
+      return;
+    }
+    if (!this.open) return;
+    const n = this.open.items.length;
+    const take = () => {
+      e.preventDefault();
+      e.stopPropagation();
+    };
+    switch (e.key) {
+      case "ArrowDown": take(); this.select((this.open.index + 1) % n); break;
+      case "ArrowUp": take(); this.select((this.open.index - 1 + n) % n); break;
+      case "Enter":
+      case "Tab": take(); this.accept(this.open.index); break;
+      case "Escape": take(); this.close(); break;
+    }
+  }
+}
+
+/**
+ * Sets up inline suggestions on `host` (ray-input, ray-textarea) the first
+ * time it has a `complete` function; closes the list when it is removed.
+ */
+export function syncComplete(host) {
+  if (typeof host.complete === "function") host._completer ??= new Completer(host);
+  else host._completer?.close();
+}

package/core/scroll.js

@@ -1,6 +1,9 @@
 // Which element scrolls the page an element sits on, and the direction of
 // its scrolling: for the bars that hide while scrolling down and come back
-// on the way up (ray-app-bar, ray-bottom-nav).
+// on the way up (ray-app-bar, ray-bottom-nav); and rows that scroll sideways.
+
+import { css } from "./core.js";
+import { isRtl } from "./direction.js";
 
 /**
  * The scroller of `el`: `target` (an element or a selector) when given,
@@ -56,3 +59,84 @@ export function watchScroll(scroller, cb, { tolerance = 8 } = {}) {
     cancelAnimationFrame(frame);
   };
 }
+
+// --- a row that scrolls sideways (tab bars) -----------------------------------
+
+/**
+ * The look of a SideScroller's row (class "list"): the edge that hides items
+ * fades out, following the writing direction.
+ */
+export const sideScrollerStyles = css`
+  .list { --_fade-start: 0px; --_fade-end: 0px; --_fade-dir: to right; }
+  .list:dir(rtl) { --_fade-dir: to left; }
+  :host([data-overflow-start]) .list { --_fade-start: 2.5rem; }
+  :host([data-overflow-end]) .list { --_fade-end: 2.5rem; }
+  :host([data-overflow-start]) .list, :host([data-overflow-end]) .list {
+    -webkit-mask-image: linear-gradient(var(--_fade-dir), transparent, #000 var(--_fade-start), #000 calc(100% - var(--_fade-end)), transparent);
+    mask-image: linear-gradient(var(--_fade-dir), transparent, #000 var(--_fade-start), #000 calc(100% - var(--_fade-end)), transparent);
+  }
+`;
+
+/**
+ * A row of items that scrolls sideways (ray-tabs, ray-doc-tabs): it marks
+ * `host` with data-overflow-start / data-overflow-end (following the writing
+ * direction), turns a vertical wheel into a sideways scroll while the row
+ * can move (at its ends the page scrolls), and scrolls an item into view,
+ * moving the row only. `active()` false (a vertical tab list) turns it off;
+ * `onResize` runs when the row's size changes.
+ */
+export class SideScroller {
+  constructor(host, row, { active = () => true, onResize = () => {} } = {}) {
+    this.host = host;
+    this.row = row;
+    this.active = active;
+    row.addEventListener("scroll", () => this.update(), { passive: true });
+    row.addEventListener("wheel", (e) => this.#wheel(e), { passive: false });
+    this.ro = typeof ResizeObserver === "function" ? new ResizeObserver(() => onResize()) : null;
+  }
+
+  connect() {
+    this.ro?.observe(this.row);
+  }
+
+  disconnect() {
+    this.ro?.disconnect();
+  }
+
+  /** How far the row is scrolled from its start, and how much is left to its end. */
+  scrolled() {
+    // Right to left, scrollLeft runs from 0 to negative.
+    const start = Math.abs(this.row.scrollLeft);
+    return { start, end: this.row.scrollWidth - this.row.clientWidth - start };
+  }
+
+  /** Sets the host's overflow marks. */
+  update() {
+    const on = this.active();
+    const { start, end } = this.scrolled();
+    this.host.toggleAttribute("data-overflow-start", on && start > 1);
+    this.host.toggleAttribute("data-overflow-end", on && end > 1);
+  }
+
+  /** Scrolls the row to show `el`; false before layout (try again later). */
+  reveal(el) {
+    if (!el || !this.active()) return true;
+    const r = this.row.getBoundingClientRect();
+    const e = el.getBoundingClientRect();
+    if (!r.width) return false;
+    if (e.left < r.left) this.row.scrollLeft -= r.left - e.left;
+    else if (e.right > r.right) this.row.scrollLeft += e.right - r.right;
+    return true;
+  }
+
+  #wheel(e) {
+    if (!this.active() || e.ctrlKey || Math.abs(e.deltaY) <= Math.abs(e.deltaX)) return;
+    const forward = e.deltaY > 0;
+    const { start, end } = this.scrolled();
+    if (forward ? end <= 1 : start <= 1) return;
+    e.preventDefault();
+    const step = e.deltaMode === 1 ? e.deltaY * 16 : e.deltaY;
+    this.row.scrollLeft += isRtl(this.host) ? -step : step;
+    this.update();
+  }
+}

package/core/textlayer.js

@@ -0,0 +1,214 @@
+// A layer behind a text control (the <input> of ray-input, the <textarea>
+// of ray-textarea) with the same text laid out the same way, transparent,
+// to paint ranges of it: `highlight` tints tokens such as {{variables}},
+// and the position of any character can be measured (to place suggestions
+// under the caret). The control keeps its own text, caret, selection and
+// IME; the layer only paints behind it.
+
+import { css } from "./core.js";
+
+/** The layer's look, for the component's styles. */
+export const textLayerStyles = css`
+  .control { position: relative; }
+  .text-layer {
+    position: absolute;
+    box-sizing: border-box;
+    display: flex;
+    align-items: center;
+    overflow: hidden;
+    color: transparent;
+    pointer-events: none;
+  }
+  .text-layer > div { flex: none; white-space: pre; }
+  .text-layer.multi { display: block; }
+  .text-layer.multi > div { white-space: pre-wrap; overflow-wrap: break-word; }
+  .text-layer mark {
+    --_tint: color-mix(in srgb, var(--ray-primary) 18%, transparent);
+    color: transparent;
+    background: var(--_tint);
+    border-radius: 3px;
+    box-shadow: 0 0 0 1.5px var(--_tint);
+  }
+  .text-layer mark[data-kind="error"] {
+    --_tint: color-mix(in srgb, var(--ray-destructive) 16%, transparent);
+    text-decoration: underline wavy var(--ray-destructive);
+    text-decoration-skip-ink: none;
+    text-underline-offset: 3px;
+  }
+`;
+
+// Copied from the control so the layer's text falls on the same pixels.
+const LAYOUT = [
+  "fontFamily", "fontSize", "fontWeight", "fontStyle", "fontStretch", "fontFeatureSettings", "fontVariantLigatures",
+  "letterSpacing", "wordSpacing", "lineHeight", "textTransform", "textIndent", "tabSize", "direction",
+  "paddingTop", "paddingRight", "paddingBottom", "paddingLeft",
+];
+
+/**
+ * The ranges a highlight function gives, checked and sorted: within the
+ * text, not overlapping (an overlapping one is dropped), start < end.
+ * @param {Array<{start: number, end: number, kind?: string, title?: string}> | null | undefined} ranges
+ * @param {number} length
+ */
+export function cleanRanges(ranges, length) {
+  const out = [];
+  const sorted = (Array.isArray(ranges) ? ranges : [])
+    .filter((r) => r && Number.isFinite(r.start) && Number.isFinite(r.end))
+    .map((r) => ({ ...r, start: Math.max(0, Math.trunc(r.start)), end: Math.min(length, Math.trunc(r.end)) }))
+    .filter((r) => r.start < r.end)
+    .sort((a, b) => a.start - b.start || b.end - a.end);
+  let at = 0;
+  for (const r of sorted) {
+    if (r.start < at) continue;
+    out.push(r);
+    at = r.end;
+  }
+  return out;
+}
+
+export class TextLayer {
+  /** @param {HTMLInputElement | HTMLTextAreaElement} control */
+  constructor(control) {
+    this.control = control;
+    this.multi = control.localName === "textarea";
+    this.el = document.createElement("div");
+    this.el.className = "text-layer" + (this.multi ? " multi" : "");
+    this.el.setAttribute("part", "text-layer");
+    this.el.setAttribute("aria-hidden", "true");
+    this.text = document.createElement("div");
+    this.el.append(this.text);
+    control.before(this.el);
+    this.ranges = [];
+    this._shown = null;
+    control.addEventListener("scroll", () => this.scroll(), { passive: true });
+    // A one-line input scrolls with the caret without a scroll event: follow
+    // it while focused.
+    let following = 0;
+    const follow = () => {
+      this.scroll();
+      following = requestAnimationFrame(follow);
+    };
+    control.addEventListener("focus", () => {
+      if (!this.multi && !following) following = requestAnimationFrame(follow);
+    });
+    control.addEventListener("blur", () => {
+      cancelAnimationFrame(following);
+      following = 0;
+      this.scroll();
+    });
+    // Placed on the next frame: moving the layer inside the observer's
+    // callback would loop it.
+    if (typeof ResizeObserver === "function") new ResizeObserver(() => requestAnimationFrame(() => this.place())).observe(control);
+  }
+
+  /** Lays out the control's text with `ranges` marked. */
+  paint(ranges) {
+    const value = this.control.value;
+    this.ranges = cleanRanges(ranges, value.length);
+    const key = value + "\u0000" + JSON.stringify(this.ranges.map((r) => [r.start, r.end, r.kind ?? ""]));
+    if (this._shown !== key) {
+      this._shown = key;
+      const nodes = [];
+      let at = 0;
+      for (const r of this.ranges) {
+        if (r.start > at) nodes.push(value.slice(at, r.start));
+        const mark = document.createElement("mark");
+        mark.textContent = value.slice(r.start, r.end);
+        const kind = String(r.kind ?? "").replace(/[^a-z0-9-]/gi, "");
+        mark.setAttribute("part", kind ? `highlight highlight-${kind}` : "highlight");
+        if (kind) mark.dataset.kind = kind;
+        nodes.push(mark);
+        at = r.end;
+      }
+      if (at < value.length) nodes.push(value.slice(at));
+      // A trailing newline takes a line in a textarea but not in a <div>.
+      if (this.multi && value.endsWith("\n")) nodes.push(" ");
+      this.text.replaceChildren(...nodes);
+    }
+    this.place();
+    this.scroll();
+  }
+
+  place() {
+    const c = this.control;
+    const cs = getComputedStyle(c);
+    for (const k of LAYOUT) this.el.style[k] = cs[k];
+    // offsetLeft is measured from the left, whatever the direction.
+    this.el.style.left = `${c.offsetLeft}px`;
+    this.el.style.top = `${c.offsetTop}px`;
+    // clientWidth leaves out a scrollbar: the text wraps at the same width.
+    this.el.style.width = `${this.multi ? c.clientWidth : c.offsetWidth}px`;
+    this.el.style.height = `${this.multi ? c.clientHeight : c.offsetHeight}px`;
+  }
+
+  scroll() {
+    const c = this.control;
+    this.text.style.transform = this.multi ? `translateY(${-c.scrollTop}px)` : `translateX(${-c.scrollLeft}px)`;
+  }
+
+  /** The viewport rectangle of the character at `offset` (the end of the text: its last one's end). */
+  rectAt(offset) {
+    const walker = document.createTreeWalker(this.text, NodeFilter.SHOW_TEXT);
+    let left = Math.max(0, offset);
+    let last = null;
+    for (let n = walker.nextNode(); n; n = walker.nextNode()) {
+      last = n;
+      if (left < n.length) {
+        const range = document.createRange();
+        range.setStart(n, left);
+        range.setEnd(n, left + 1);
+        const r = range.getBoundingClientRect();
+        if (r.width || r.height) return r;
+        break;
+      }
+      left -= n.length;
+    }
+    if (last && last.length) {
+      const range = document.createRange();
+      range.setStart(last, last.length - 1);
+      range.setEnd(last, last.length);
+      const r = range.getBoundingClientRect();
+      if (r.width || r.height) return new DOMRect(r.right, r.top, 0, r.height);
+    }
+    const c = this.control.getBoundingClientRect();
+    return new DOMRect(c.left, c.top, 0, c.height);
+  }
+
+  /** The range under a point of the viewport, or null. */
+  rangeAt(x, y) {
+    const marks = [...this.text.querySelectorAll("mark")];
+    for (let i = 0; i < marks.length; i++) {
+      for (const r of marks[i].getClientRects()) {
+        if (x >= r.left && x <= r.right && y >= r.top && y <= r.bottom) return this.ranges[i];
+      }
+    }
+    return null;
+  }
+}
+
+/**
+ * Paints `host.highlight(text)` behind `host.control` (ray-input,
+ * ray-textarea): the layer is made the first time a highlight function is
+ * set. A range's `title` becomes the field's tooltip under the pointer.
+ */
+export function syncHighlight(host) {
+  const fn = typeof host.highlight === "function" ? host.highlight : null;
+  if (!fn && !host._textLayer) return;
+  host._textLayer ??= new TextLayer(host.control);
+  if (!host._highlightTitles) {
+    host._highlightTitles = true;
+    host.control.addEventListener("pointermove", (e) => {
+      const title = host._textLayer.rangeAt(e.clientX, e.clientY)?.title ?? "";
+      if (host.control.title !== title) host.control.title = title;
+    });
+  }
+  let ranges = [];
+  if (fn) {
+    try {
+      ranges = fn(host.control.value);
+    } catch (err) {
+      console.error("ray-elements: highlight() threw", err);
+    }
+  }
+  host._textLayer.paint(ranges);
+}