@raylang/elements 0.10.0 → 0.12.0

package/components/input/input.js

@@ -73,6 +73,11 @@ export class RayInput extends FieldControl {
     syncComplete(this);
   }
 
+  /** The highlight range under a point of the viewport, or null. */
+  highlightAt(x, y) {
+    return this._textLayer?.rangeAt(x, y) ?? null;
+  }
+
   /** Runs `highlight` again (what it marks changed, not the text). */
   refreshHighlight() {
     syncHighlight(this);

package/components/menu/menu.js

@@ -142,6 +142,13 @@ export class RayMenu extends Floating {
     return this.context && this._point ? this._point : super.anchorRect();
   }
 
+  // A context menu's trigger is the area it serves: a press there, outside
+  // the panel, closes it like a system context menu (a right click reopens
+  // it at the new point).
+  triggerDismisses() {
+    return Boolean(this.context);
+  }
+
   toggled(open) {
     if (open) {
       this._focus(this._focusOnOpen ?? "first");

package/components/pulse/pulse.js

@@ -0,0 +1,140 @@
+// <ray-pulse>: an indeterminate wait indicator softer than ray-spinner: up to
+// five circles, concentric or in a row, breathing or expanding from a point.
+// Four presets (variant); count, shape, fade and direction override them.
+
+import { RayElement, css, define } from "../../core/core.js";
+import { applyColor, srOnlyStyles } from "../../core/styles.js";
+
+export const MAX_COUNT = 5;
+
+/**
+ * The presets. `scale` is where a cycle starts (1 = the circle's full size),
+ * `stagger` how much of the cycle separates one circle's phase from the next
+ * (1 = spread evenly), `core` a static dot in the middle, `row` dots side by
+ * side instead of concentric.
+ */
+export const PRESETS = {
+  cluster: { count: 3, shape: "filled", fade: "none", direction: "alternate", scale: 0.7, stagger: 1 },
+  breathe: { count: 2, shape: "filled", fade: "none", direction: "alternate", scale: 0.6, stagger: 0 },
+  ripple: { count: 2, shape: "ring", fade: "out", direction: "normal", scale: 0.3, stagger: 1, core: true },
+  dots: { count: 3, shape: "filled", fade: "out", direction: "alternate", scale: 0.6, stagger: 1, row: true },
+};
+
+const styles = css`
+  :host {
+    display: inline-flex;
+    vertical-align: middle;
+    --_pulse: 2.25rem;
+    --_cycle: var(--ray-pulse-cycle, 1.6s);
+    --_floor: var(--ray-pulse-floor, 0.2);
+  }
+  :host([size="xs"]) { --_pulse: 1.125rem; }
+  :host([size="sm"]) { --_pulse: 1.375rem; }
+  :host([size="lg"]) { --_pulse: 2.75rem; }
+  :host([size="xl"]) { --_pulse: 3.625rem; }
+  .pulse {
+    display: inline-grid;
+    place-items: center;
+    width: var(--_pulse);
+    height: var(--_pulse);
+    color: var(--_filled);
+  }
+  .pulse.row {
+    display: inline-flex;
+    align-items: center;
+    gap: calc(var(--_pulse) * 0.16);
+    width: auto;
+  }
+  .dot {
+    grid-area: 1 / 1;
+    display: block;
+    flex: none;
+    width: var(--_w);
+    height: var(--_w);
+    border-radius: 50%;
+    background: currentColor;
+    opacity: var(--_o, 1);
+    animation: ray-pulse var(--_cycle) var(--_ease) infinite var(--_direction);
+    /* Negative: every circle is already mid-cycle on the first frame. */
+    animation-delay: calc(-1 * var(--_i) * var(--_cycle) * var(--_stagger) / var(--_n));
+  }
+  .ring > .dot { background: transparent; border: max(1.5px, calc(var(--_pulse) / 18)) solid currentColor; }
+  /* Concentric filled circles: the larger, the fainter (else they merge into one). */
+  .gradient > .dot { --_o: calc(1 - (1 - var(--_floor)) * var(--_i) / var(--_last)); }
+  .core { --_w: 28%; animation: none; opacity: 1; background: currentColor; border: 0; }
+  @keyframes ray-pulse {
+    from { transform: scale(var(--_scale)); opacity: var(--_o, 1); }
+    to { transform: scale(1); opacity: calc(var(--_o, 1) * var(--_fade-end)); }
+  }
+  @media (prefers-reduced-motion: reduce) {
+    .dot { animation-duration: calc(var(--_cycle) * 2) !important; }
+  }
+`;
+
+const clampCount = (n) => Math.max(1, Math.min(MAX_COUNT, Math.floor(n)));
+
+export class RayPulse extends RayElement {
+  static properties = {
+    variant: { type: String, reflect: true, default: "cluster" },
+    count: { type: Number, reflect: true },
+    shape: { type: String, reflect: true },
+    fade: { type: String, reflect: true },
+    direction: { type: String, reflect: true },
+    color: { type: String, reflect: true },
+    size: { type: String, reflect: true, default: "md" },
+    label: { type: String, default: "Loading" },
+  };
+  static styles = [srOnlyStyles, styles];
+  static template = `<span class="pulse" part="pulse" aria-hidden="true"></span><span class="sr-only"></span>`;
+
+  connectedCallback() {
+    super.connectedCallback();
+    if (!this.hasAttribute("role")) this.setAttribute("role", "status");
+  }
+
+  update() {
+    const preset = PRESETS[this.variant] ?? PRESETS.cluster;
+    const n = this.count > 0 ? clampCount(this.count) : preset.count;
+    const shape = this.shape === "ring" || this.shape === "filled" ? this.shape : preset.shape;
+    // `fade` alone (an empty attribute) means out; "none" switches a preset's off.
+    const fade = this.fade == null ? preset.fade : this.fade === "none" ? "none" : "out";
+    const direction = this.direction === "normal" || this.direction === "alternate" ? this.direction : preset.direction;
+    const box = this.$(".pulse");
+    applyColor(box, this.color);
+    box.classList.toggle("row", !!preset.row);
+    box.classList.toggle("ring", shape === "ring");
+    box.classList.toggle("gradient", shape === "filled" && !preset.row);
+    const s = box.style;
+    s.setProperty("--_n", String(n));
+    s.setProperty("--_last", String(Math.max(1, n - 1)));
+    s.setProperty("--_scale", `var(--ray-pulse-scale, ${preset.scale})`);
+    s.setProperty("--_stagger", `var(--ray-pulse-stagger, ${preset.stagger})`);
+    s.setProperty("--_direction", direction);
+    s.setProperty("--_fade-end", fade === "out" ? "0" : "1");
+    s.setProperty("--_ease", direction === "normal" ? "cubic-bezier(0, 0.4, 0.5, 1)" : "ease-in-out");
+    const key = `${n}:${preset.row ? "row" : "ring"}:${preset.core ? "core" : ""}`;
+    if (box.dataset.key !== key) {
+      box.dataset.key = key;
+      const dots = [];
+      // Largest first, so the smaller ones paint on top of it.
+      for (let i = n - 1; i >= 0; i--) {
+        const dot = document.createElement("i");
+        dot.className = "dot";
+        dot.setAttribute("part", "dot");
+        dot.style.setProperty("--_i", String(i));
+        dot.style.setProperty("--_w", preset.row ? "calc(var(--_pulse) * 0.28)" : `${Math.round(((i + 1) / n) * 100)}%`);
+        dots.push(dot);
+      }
+      if (preset.core) {
+        const core = document.createElement("i");
+        core.className = "dot core";
+        core.setAttribute("part", "dot core");
+        dots.push(core);
+      }
+      box.replaceChildren(...dots);
+    }
+    this.$(".sr-only").textContent = this.label;
+  }
+}
+
+define("ray-pulse", RayPulse);

package/components/textarea/textarea.js

@@ -77,6 +77,11 @@ export class RayTextarea extends FieldControl {
     syncComplete(this);
   }
 
+  /** The highlight range under a point of the viewport, or null. */
+  highlightAt(x, y) {
+    return this._textLayer?.rangeAt(x, y) ?? null;
+  }
+
   /** Runs `highlight` again (what it marks changed, not the text). */
   refreshHighlight() {
     syncHighlight(this);

package/core/floating.js

@@ -35,6 +35,7 @@ export class Floating extends RayElement {
     open: { type: Boolean, reflect: true },
     placement: { type: String, reflect: true, default: "bottom" },
     offset: { type: Number, default: 8 },
+    anchor: { attribute: false },
   };
   /** popover attribute of the panel ("manual": closing is handled here). */
   static popoverMode = "manual";
@@ -102,8 +103,15 @@ export class Floating extends RayElement {
   /** Subclasses attach their trigger listeners here. */
   wireTrigger(_trigger) {}
 
-  /** The rectangle the panel is placed against (default: the trigger). */
+  /**
+   * The rectangle the panel is placed against: `anchor` when set (an element,
+   * a DOMRect or a function returning one: a text range, the pointer), else
+   * the trigger.
+   */
   anchorRect() {
+    const a = typeof this.anchor === "function" ? this.anchor() : this.anchor;
+    if (a instanceof Element) return a.getBoundingClientRect();
+    if (a && typeof a.left === "number") return a;
     return (this.trigger ?? this).getBoundingClientRect();
   }
 
@@ -132,7 +140,20 @@ export class Floating extends RayElement {
   _dismissable() {
     const ctor = /** @type {typeof Floating} */ (this.constructor);
     if (this.#undismiss || !ctor.lightDismiss || ctor.popoverMode !== "manual") return;
-    this.#undismiss = dismissable({ panel: this.panel, owner: this, trigger: this.trigger, close: () => { this.open = false; } });
+    // When the trigger dismisses, so does the rest of the host's light DOM
+    // (the area is a child of the host): only the panel is inside then.
+    const area = this.triggerDismisses();
+    this.#undismiss = dismissable({ panel: this.panel, owner: area ? this.panel : this, trigger: area ? null : this.trigger, close: () => { this.open = false; } });
+  }
+
+  /**
+   * Whether a press on the trigger counts as outside and closes the panel.
+   * Default false: a button that toggles the panel handles its own click
+   * (closing it there too would reopen it). A context menu's trigger is the
+   * whole area it serves, so there it is true.
+   */
+  triggerDismisses() {
+    return false;
   }
 
   /** The keyframes the panel leaves with (subclasses may change them). */
@@ -166,6 +187,15 @@ export class Floating extends RayElement {
 
   _onToggle(e) {
     const opening = e.newState === "open";
+    // `toggle` is a task: `open` may have changed again since the state it
+    // reports. An open that a later `open = false` is already animating out,
+    // or a close that a later `open = true` re-showed, must not win over
+    // that newer value; only the pair of events is still emitted.
+    const stale = opening ? !this.open && Boolean(this.#exit) : Boolean(this.open) && this.panel.matches(":popover-open");
+    if (stale) {
+      this.emit(opening ? "ray-open" : "ray-close");
+      return;
+    }
     if (this.popupKind()) this.#trigger?.setAttribute("aria-expanded", String(opening));
     if (opening) {
       this.reposition();

package/core/textlayer.js

@@ -176,10 +176,18 @@ export class TextLayer {
 
   /** The range under a point of the viewport, or null. */
   rangeAt(x, y) {
+    return this.hitAt(x, y)?.range ?? null;
+  }
+
+  /**
+   * The range under a point of the viewport and the box of the line of it
+   * the point is on (a range may wrap), or null.
+   */
+  hitAt(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];
+        if (x >= r.left && x <= r.right && y >= r.top && y <= r.bottom) return { range: this.ranges[i], rect: r };
       }
     }
     return null;
@@ -189,7 +197,9 @@ export class TextLayer {
 /**
  * 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.
+ * set. A range's `title` becomes the field's tooltip under the pointer, and
+ * `ray-highlight-hover` fires when the range under it changes (null leaving
+ * one), with its box, so an app can show its own popover over a range.
  */
 export function syncHighlight(host) {
   const fn = typeof host.highlight === "function" ? host.highlight : null;
@@ -197,10 +207,18 @@ export function syncHighlight(host) {
   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 ?? "";
+    let over = null;
+    const hover = (x, y) => {
+      const hit = host._textLayer.hitAt(x, y);
+      const title = hit?.range.title ?? "";
       if (host.control.title !== title) host.control.title = title;
-    });
+      const range = hit?.range ?? null;
+      if (range === over) return;
+      over = range;
+      host.emit("ray-highlight-hover", { range, rect: hit?.rect ?? null });
+    };
+    host.control.addEventListener("pointermove", (e) => hover(e.clientX, e.clientY));
+    host.control.addEventListener("pointerleave", () => hover(-1, -1));
   }
   let ranges = [];
   if (fn) {

package/custom-elements.json

@@ -4746,6 +4746,11 @@
               "name": "select",
               "description": "Selects the text."
             },
+            {
+              "kind": "method",
+              "name": "highlightAt",
+              "description": "The highlight range under a point of the viewport (clientX, clientY), or null."
+            },
             {
               "kind": "method",
               "name": "refreshHighlight",
@@ -4760,6 +4765,13 @@
               },
               "description": "A suggestion was accepted (the text already has it)."
             },
+            {
+              "name": "ray-highlight-hover",
+              "type": {
+                "text": "CustomEvent<{ range: HighlightRange | null; rect: DOMRect | null }>"
+              },
+              "description": "The highlight range under the pointer changed: the range and the box of the line of it the pointer is on, or null on leaving a range. Anchor a ray-popover to rect (its anchor property) to show more than the title."
+            },
             {
               "name": "input",
               "type": {
@@ -5301,6 +5313,13 @@
               },
               "description": "A suggestion was accepted (the text already has it)."
             },
+            {
+              "name": "ray-highlight-hover",
+              "type": {
+                "text": "CustomEvent<{ range: HighlightRange | null; rect: DOMRect | null }>"
+              },
+              "description": "The highlight range under the pointer changed: the range and the box of the line of it the pointer is on, or null on leaving a range. Anchor a ray-popover to rect (its anchor property) to show more than the title."
+            },
             {
               "name": "input",
               "type": {
@@ -6301,6 +6320,13 @@
               },
               "description": "A suggestion was accepted (the text already has it)."
             },
+            {
+              "name": "ray-highlight-hover",
+              "type": {
+                "text": "CustomEvent<{ range: HighlightRange | null; rect: DOMRect | null }>"
+              },
+              "description": "The highlight range under the pointer changed: the range and the box of the line of it the pointer is on, or null on leaving a range. Anchor a ray-popover to rect (its anchor property) to show more than the title."
+            },
             {
               "name": "input",
               "type": {
@@ -6765,6 +6791,13 @@
               },
               "description": "A suggestion was accepted (the text already has it)."
             },
+            {
+              "name": "ray-highlight-hover",
+              "type": {
+                "text": "CustomEvent<{ range: HighlightRange | null; rect: DOMRect | null }>"
+              },
+              "description": "The highlight range under the pointer changed: the range and the box of the line of it the pointer is on, or null on leaving a range. Anchor a ray-popover to rect (its anchor property) to show more than the title."
+            },
             {
               "name": "input",
               "type": {
@@ -9540,6 +9573,11 @@
               "attribute": "radius",
               "reflects": true
             },
+            {
+              "kind": "method",
+              "name": "highlightAt",
+              "description": "The highlight range under a point of the viewport (clientX, clientY), or null."
+            },
             {
               "kind": "method",
               "name": "refreshHighlight",
@@ -9554,6 +9592,13 @@
               },
               "description": "A suggestion was accepted (the text already has it)."
             },
+            {
+              "name": "ray-highlight-hover",
+              "type": {
+                "text": "CustomEvent<{ range: HighlightRange | null; rect: DOMRect | null }>"
+              },
+              "description": "The highlight range under the pointer changed: the range and the box of the line of it the pointer is on, or null on leaving a range. Anchor a ray-popover to rect (its anchor property) to show more than the title."
+            },
             {
               "name": "input",
               "type": {
@@ -13496,6 +13541,14 @@
               "attribute": "native",
               "reflects": true
             },
+            {
+              "kind": "field",
+              "name": "anchor",
+              "type": {
+                "text": "Element | DOMRect | (() => DOMRect) | null"
+              },
+              "description": "What the panel is placed against instead of the trigger: an element, a DOMRect or a function returning one (a text range, the pointer; read again on every reposition). The trigger still opens it."
+            },
             {
               "kind": "field",
               "name": "offset",
@@ -13571,7 +13624,7 @@
           "slots": [
             {
               "name": "trigger",
-              "description": "The button that opens it, or the area for a context menu."
+              "description": "The button that opens it, or the area for a context menu (a press on the area outside the open menu closes it; a right click reopens it at the new point)."
             },
             {
               "name": "",
@@ -13940,6 +13993,14 @@
               "reflects": false,
               "default": "8"
             },
+            {
+              "kind": "field",
+              "name": "anchor",
+              "type": {
+                "text": "Element | DOMRect | (() => DOMRect) | null"
+              },
+              "description": "What the panel is placed against instead of the trigger: an element, a DOMRect or a function returning one (a text range, the pointer; read again on every reposition). The trigger still opens it."
+            },
             {
               "kind": "field",
               "name": "width",
@@ -18463,6 +18524,206 @@
         }
       ]
     },
+    {
+      "kind": "javascript-module",
+      "path": "components/pulse/pulse.js",
+      "declarations": [
+        {
+          "kind": "class",
+          "name": "RayPulse",
+          "tagName": "ray-pulse",
+          "customElement": true,
+          "description": "Four presets (variant), each a bundle of count, shape, fade and direction, which override it one by one. The rest is tuned with custom properties on the element: --ray-pulse-cycle (one cycle, default 1.6s; doubled with reduced motion), --ray-pulse-floor (opacity of the largest of concentric filled circles, 0 to 1, default 0.2), --ray-pulse-scale (where a cycle starts, 1 = full size; default per variant) and --ray-pulse-stagger (how much of the cycle separates the phases of the circles, 0 together to 1 spread evenly; default per variant).",
+          "superclass": {
+            "name": "RayElement"
+          },
+          "attributes": [
+            {
+              "name": "variant",
+              "type": {
+                "text": "\"cluster\" | \"breathe\" | \"ripple\" | \"dots\""
+              },
+              "description": "The figure: cluster (three concentric circles breathing out of phase), breathe (one dot over a halo), ripple (rings expanding from a dot) or dots (three in a row, in sequence).",
+              "fieldName": "variant",
+              "default": "cluster"
+            },
+            {
+              "name": "count",
+              "type": {
+                "text": "number"
+              },
+              "description": "Number of circles, 1 to 5 (more are clamped). Default: the variant's.",
+              "fieldName": "count"
+            },
+            {
+              "name": "shape",
+              "type": {
+                "text": "\"filled\" | \"ring\""
+              },
+              "description": "Filled discs (concentric ones fade with size, see --ray-pulse-floor) or outlined rings. Default: the variant's.",
+              "fieldName": "shape"
+            },
+            {
+              "name": "fade",
+              "type": {
+                "text": "\"out\" | \"none\""
+              },
+              "description": "Whether a cycle ends transparent; the bare attribute means out. Default: the variant's (ripple and dots fade).",
+              "fieldName": "fade"
+            },
+            {
+              "name": "direction",
+              "type": {
+                "text": "\"alternate\" | \"normal\""
+              },
+              "description": "alternate goes there and back; normal goes one way and restarts (with fade: the ripple). Default: the variant's.",
+              "fieldName": "direction"
+            },
+            {
+              "name": "color",
+              "type": {
+                "text": "string"
+              },
+              "description": "A palette color or any CSS color. Default: the primary color.",
+              "fieldName": "color"
+            },
+            {
+              "name": "size",
+              "type": {
+                "text": "\"xs\" | \"sm\" | \"md\" | \"lg\" | \"xl\""
+              },
+              "description": "Height of the figure (the dots variant is wider).",
+              "fieldName": "size",
+              "default": "md"
+            },
+            {
+              "name": "label",
+              "type": {
+                "text": "string"
+              },
+              "description": "Text read by screen readers.",
+              "fieldName": "label",
+              "default": "Loading"
+            }
+          ],
+          "members": [
+            {
+              "kind": "field",
+              "name": "variant",
+              "type": {
+                "text": "\"cluster\" | \"breathe\" | \"ripple\" | \"dots\""
+              },
+              "description": "The figure: cluster (three concentric circles breathing out of phase), breathe (one dot over a halo), ripple (rings expanding from a dot) or dots (three in a row, in sequence).",
+              "attribute": "variant",
+              "reflects": true,
+              "default": "cluster"
+            },
+            {
+              "kind": "field",
+              "name": "count",
+              "type": {
+                "text": "number"
+              },
+              "description": "Number of circles, 1 to 5 (more are clamped). Default: the variant's.",
+              "attribute": "count",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "shape",
+              "type": {
+                "text": "\"filled\" | \"ring\""
+              },
+              "description": "Filled discs (concentric ones fade with size, see --ray-pulse-floor) or outlined rings. Default: the variant's.",
+              "attribute": "shape",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "fade",
+              "type": {
+                "text": "\"out\" | \"none\""
+              },
+              "description": "Whether a cycle ends transparent; the bare attribute means out. Default: the variant's (ripple and dots fade).",
+              "attribute": "fade",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "direction",
+              "type": {
+                "text": "\"alternate\" | \"normal\""
+              },
+              "description": "alternate goes there and back; normal goes one way and restarts (with fade: the ripple). Default: the variant's.",
+              "attribute": "direction",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "color",
+              "type": {
+                "text": "string"
+              },
+              "description": "A palette color or any CSS color. Default: the primary color.",
+              "attribute": "color",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "size",
+              "type": {
+                "text": "\"xs\" | \"sm\" | \"md\" | \"lg\" | \"xl\""
+              },
+              "description": "Height of the figure (the dots variant is wider).",
+              "attribute": "size",
+              "reflects": true,
+              "default": "md"
+            },
+            {
+              "kind": "field",
+              "name": "label",
+              "type": {
+                "text": "string"
+              },
+              "description": "Text read by screen readers.",
+              "attribute": "label",
+              "reflects": false,
+              "default": "Loading"
+            }
+          ],
+          "events": [],
+          "slots": [],
+          "cssParts": [
+            {
+              "name": "pulse",
+              "description": "The box holding the circles."
+            },
+            {
+              "name": "dot",
+              "description": "Each circle (the static center of ripple is also part core)."
+            }
+          ]
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "RayPulse",
+          "declaration": {
+            "name": "RayPulse",
+            "module": "components/pulse/pulse.js"
+          }
+        },
+        {
+          "kind": "custom-element-definition",
+          "name": "ray-pulse",
+          "declaration": {
+            "name": "RayPulse",
+            "module": "components/pulse/pulse.js"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "components/ring-progress/ring-progress.js",

package/index.js

@@ -58,6 +58,7 @@ export { RayAlert } from "./components/alert/alert.js";
 export { RayEmptyState } from "./components/empty-state/empty-state.js";
 export { RayNotification, RayToaster, notify, updateNotification, hideNotification, clearNotifications, statusIcon } from "./components/notification/notification.js";
 export { RayProgress } from "./components/progress/progress.js";
+export { RayPulse } from "./components/pulse/pulse.js";
 export { RayRingProgress } from "./components/ring-progress/ring-progress.js";
 export { RaySkeleton } from "./components/skeleton/skeleton.js";
 export { RaySpinner } from "./components/spinner/spinner.js";

package/llms-full.txt

@@ -1,6 +1,6 @@
 # ray-elements
 
-> Web components (custom elements, Shadow DOM, no dependencies) for any web app: plain HTML, React, Vue or a raylang app. npm: `@raylang/elements`, `@raylang/react`, `@raylang/vue`; raylang: the `elements` package. This file describes version 0.10.0.
+> Web components (custom elements, Shadow DOM, no dependencies) for any web app: plain HTML, React, Vue or a raylang app. npm: `@raylang/elements`, `@raylang/react`, `@raylang/vue`; raylang: the `elements` package. This file describes version 0.12.0.
 
 ray-elements is a design system of standard web components (custom elements
 with Shadow DOM, no dependencies): `<ray-button>`, `<ray-input>`,
@@ -918,6 +918,7 @@ Attributes (forwarded to the inner element):
 Events:
 
 - `ray-complete` (detail `{ item: CompletionItem; from: number; to: number }`): A suggestion was accepted (the text already has it).
+- `ray-highlight-hover` (detail `{ range: HighlightRange | null; rect: DOMRect | null }`): The highlight range under the pointer changed: the range and the box of the line of it the pointer is on, or null on leaving a range. Anchor a ray-popover to rect (its anchor property) to show more than the title.
 - `input`: On every edit (value already updated).
 - `change`: When an edit is committed (blur, Enter).
 
@@ -944,6 +945,7 @@ Parts (`::part()`):
 Methods and properties:
 
 - `select(): void`: Selects the text.
+- `highlightAt(x: number, y: number): HighlightRange | null`: The highlight range under a point of the viewport (clientX, clientY), or null.
 - `refreshHighlight(): void`: Runs highlight again, when what it marks changed but the text did not.
 
 Vue `v-model`: `value` (updated on input).
@@ -1480,6 +1482,7 @@ Attributes (forwarded to the inner element):
 Events:
 
 - `ray-complete` (detail `{ item: CompletionItem; from: number; to: number }`): A suggestion was accepted (the text already has it).
+- `ray-highlight-hover` (detail `{ range: HighlightRange | null; rect: DOMRect | null }`): The highlight range under the pointer changed: the range and the box of the line of it the pointer is on, or null on leaving a range. Anchor a ray-popover to rect (its anchor property) to show more than the title.
 - `input`: On every edit.
 - `change`: When an edit is committed.
 
@@ -1497,6 +1500,7 @@ Parts (`::part()`):
 
 Methods and properties:
 
+- `highlightAt(x: number, y: number): HighlightRange | null`: The highlight range under a point of the viewport (clientX, clientY), or null.
 - `refreshHighlight(): void`: Runs highlight again, when what it marks changed but the text did not.
 
 Vue `v-model`: `value` (updated on input).
@@ -2191,6 +2195,7 @@ Properties:
 - `context`: boolean, reflects. Opens on right click (contextmenu) over the trigger area, at the pointer.
 - `keepOpen` (attribute `keep-open`): boolean, reflects. Choosing an item does not close the menu.
 - `native`: boolean, reflects. With a native host (ray-elements/core/raylang.js in a std/ui window), opens as the system's context menu at the pointer: items and dividers, same ray-select.
+- `anchor` (property only): `Element | DOMRect | (() => DOMRect) | null`. What the panel is placed against instead of the trigger: an element, a DOMRect or a function returning one (a text range, the pointer; read again on every reposition). The trigger still opens it.
 
 Also the properties of Floating: `offset`.
 
@@ -2203,7 +2208,7 @@ Events:
 
 Slots:
 
-- `trigger`: The button that opens it, or the area for a context menu.
+- `trigger`: The button that opens it, or the area for a context menu (a press on the area outside the open menu closes it; a right click reopens it at the new point).
 - (default): ray-menu-item, ray-menu-label and ray-menu-divider elements.
 
 Parts (`::part()`):
@@ -2294,6 +2299,7 @@ Properties:
 - `open`: boolean, reflects. Shown.
 - `placement`: `bottom` | `bottom-start` | `bottom-end` | `top` | `top-start` | `top-end` | `left` | `left-start` | `left-end` | `right` | `right-start` | `right-end`, default `bottom`, reflects. Preferred side and alignment: top/bottom/left/right are sides of the screen; on top and bottom, -start/-end follow the writing direction (right to left, "bottom-start" lines up the right edges).
 - `offset`: number, default `8`. Gap to the trigger in px.
+- `anchor` (property only): `Element | DOMRect | (() => DOMRect) | null`. What the panel is placed against instead of the trigger: an element, a DOMRect or a function returning one (a text range, the pointer; read again on every reposition). The trigger still opens it.
 - `width`: string. Panel width (px number or CSS length). Default: its content.
 - `matchWidth` (attribute `match-width`): boolean. At least as wide as the trigger.
 - `padding`: `0` | `xs` | `sm` | `md` | `lg`, default `md`, reflects. Panel padding.
@@ -3007,6 +3013,32 @@ Parts (`::part()`):
 - `bar`: The filled bar.
 - `value`: The percentage beside the bar (show-value on xs, sm, md).
 
+### Pulse
+
+An indeterminate wait indicator softer than the spinner: circles that breathe or ripple, announced as a status.
+
+Import: `import "@raylang/elements/pulse";` · Category: Feedback
+
+#### `<ray-pulse>` (RayPulse, extends RayElement)
+
+Four presets (variant), each a bundle of count, shape, fade and direction, which override it one by one. The rest is tuned with custom properties on the element: --ray-pulse-cycle (one cycle, default 1.6s; doubled with reduced motion), --ray-pulse-floor (opacity of the largest of concentric filled circles, 0 to 1, default 0.2), --ray-pulse-scale (where a cycle starts, 1 = full size; default per variant) and --ray-pulse-stagger (how much of the cycle separates the phases of the circles, 0 together to 1 spread evenly; default per variant).
+
+Properties:
+
+- `variant`: `cluster` | `breathe` | `ripple` | `dots`, default `cluster`, reflects. The figure: cluster (three concentric circles breathing out of phase), breathe (one dot over a halo), ripple (rings expanding from a dot) or dots (three in a row, in sequence).
+- `count`: number, reflects. Number of circles, 1 to 5 (more are clamped). Default: the variant's.
+- `shape`: `filled` | `ring`, reflects. Filled discs (concentric ones fade with size, see --ray-pulse-floor) or outlined rings. Default: the variant's.
+- `fade`: `out` | `none`, reflects. Whether a cycle ends transparent; the bare attribute means out. Default: the variant's (ripple and dots fade).
+- `direction`: `alternate` | `normal`, reflects. alternate goes there and back; normal goes one way and restarts (with fade: the ripple). Default: the variant's.
+- `color`: string, reflects. A palette color or any CSS color. Default: the primary color.
+- `size`: `xs` | `sm` | `md` | `lg` | `xl`, default `md`, reflects. Height of the figure (the dots variant is wider).
+- `label`: string, default `Loading`. Text read by screen readers.
+
+Parts (`::part()`):
+
+- `pulse`: The box holding the circles.
+- `dot`: Each circle (the static center of ripple is also part core).
+
 ### Ring progress
 
 Progress as a ring (Mantine's RingProgress), with content in the middle: a countdown, a goal, an upload. Announced as a progressbar.

package/llms.txt

@@ -1,6 +1,6 @@
 # ray-elements
 
-> Web components (custom elements, Shadow DOM, no dependencies) for any web app: plain HTML, React, Vue or a raylang app. npm: `@raylang/elements`, `@raylang/react`, `@raylang/vue`; raylang: the `elements` package. This file describes version 0.10.0.
+> Web components (custom elements, Shadow DOM, no dependencies) for any web app: plain HTML, React, Vue or a raylang app. npm: `@raylang/elements`, `@raylang/react`, `@raylang/vue`; raylang: the `elements` package. This file describes version 0.12.0.
 
 ray-elements is a design system of standard web components (custom elements
 with Shadow DOM, no dependencies): `<ray-button>`, `<ray-input>`,
@@ -337,6 +337,7 @@ Members whose name starts with `_` are internal.
 - [Empty state](https://elements.raylang.dev/components/empty-state.md): `<ray-empty-state>` (Feedback). What a list, table or pane shows when it is empty: icon, title, text and the action that fills it.
 - [Notification](https://elements.raylang.dev/components/notification.md): `<ray-notification>`, `<ray-toaster>` (Feedback). Toasts: notify(), updateNotification(), hideNotification(), clearNotifications(); shown in a ray-toaster (a polite live region in the top layer).
 - [Progress](https://elements.raylang.dev/components/progress.md): `<ray-progress>` (Feedback). A determinate or (without value) indeterminate progress bar, announced as a progressbar.
+- [Pulse](https://elements.raylang.dev/components/pulse.md): `<ray-pulse>` (Feedback). An indeterminate wait indicator softer than the spinner: circles that breathe or ripple, announced as a status.
 - [Ring progress](https://elements.raylang.dev/components/ring-progress.md): `<ray-ring-progress>` (Feedback). Progress as a ring (Mantine's RingProgress), with content in the middle: a countdown, a goal, an upload.
 - [Skeleton](https://elements.raylang.dev/components/skeleton.md): `<ray-skeleton>` (Feedback). A placeholder while content loads: a shimmering block, a circle or text lines; with loaded it shows its content.
 - [Spinner](https://elements.raylang.dev/components/spinner.md): `<ray-spinner>` (Feedback). An indeterminate loading indicator, announced as a status.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raylang/elements",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "Web components for any app, with raylang extras (shadcn/ui + Mantine inspired)",
   "license": "Apache-2.0",
   "keywords": ["web-components", "custom-elements", "design-system", "ui", "raylang"],
@@ -252,6 +252,10 @@
       "types": "./ray-elements.d.ts",
       "default": "./components/progress/progress.js"
     },
+    "./pulse": {
+      "types": "./ray-elements.d.ts",
+      "default": "./components/pulse/pulse.js"
+    },
     "./ring-progress": {
       "types": "./ray-elements.d.ts",
       "default": "./components/ring-progress/ring-progress.js"

package/ray-elements.d.ts

@@ -855,6 +855,8 @@ export declare class RayInput extends FieldControl {
   suggestionsLabel: string;
   /** Selects the text. */
   select(): void;
+  /** The highlight range under a point of the viewport (clientX, clientY), or null. */
+  highlightAt(x: number, y: number): HighlightRange | null;
   /** Runs highlight again, when what it marks changed but the text did not. */
   refreshHighlight(): void;
   addEventListener<K extends keyof RayInputEventMap>(type: K, listener: (this: RayInput, ev: RayInputEventMap[K]) => unknown, options?: boolean | AddEventListenerOptions): void;
@@ -865,6 +867,8 @@ export declare class RayInput extends FieldControl {
 export interface RayInputEventMap extends HTMLElementEventMap {
   /** A suggestion was accepted (the text already has it). */
   "ray-complete": CustomEvent<{ item: CompletionItem; from: number; to: number }>;
+  /** The highlight range under the pointer changed: the range and the box of the line of it the pointer is on, or null on leaving a range. Anchor a ray-popover to rect (its anchor property) to show more than the title. */
+  "ray-highlight-hover": CustomEvent<{ range: HighlightRange | null; rect: DOMRect | null }>;
 }
 
 // --- Mode input (mode-input)
@@ -900,6 +904,8 @@ export interface RayModeInputEventMap extends HTMLElementEventMap {
   "ray-mode-change": CustomEvent<{ mode: string; previous: string | null; option: ModeOption }>;
   /** A suggestion was accepted (the text already has it). */
   "ray-complete": CustomEvent<{ item: CompletionItem; from: number; to: number }>;
+  /** The highlight range under the pointer changed: the range and the box of the line of it the pointer is on, or null on leaving a range. Anchor a ray-popover to rect (its anchor property) to show more than the title. */
+  "ray-highlight-hover": CustomEvent<{ range: HighlightRange | null; rect: DOMRect | null }>;
 }
 
 // --- Number input (number-input)
@@ -960,6 +966,8 @@ export interface RayPasswordInputEventMap extends HTMLElementEventMap {
   "ray-visibility-change": CustomEvent<{ visible: boolean }>;
   /** A suggestion was accepted (the text already has it). */
   "ray-complete": CustomEvent<{ item: CompletionItem; from: number; to: number }>;
+  /** The highlight range under the pointer changed: the range and the box of the line of it the pointer is on, or null on leaving a range. Anchor a ray-popover to rect (its anchor property) to show more than the title. */
+  "ray-highlight-hover": CustomEvent<{ range: HighlightRange | null; rect: DOMRect | null }>;
 }
 
 // --- Path input (path-input)
@@ -991,6 +999,8 @@ export interface RayPathInputEventMap extends HTMLElementEventMap {
   "ray-error": CustomEvent<{ error: Error }>;
   /** A suggestion was accepted (the text already has it). */
   "ray-complete": CustomEvent<{ item: CompletionItem; from: number; to: number }>;
+  /** The highlight range under the pointer changed: the range and the box of the line of it the pointer is on, or null on leaving a range. Anchor a ray-popover to rect (its anchor property) to show more than the title. */
+  "ray-highlight-hover": CustomEvent<{ range: HighlightRange | null; rect: DOMRect | null }>;
 }
 
 // --- Radio group (radio)
@@ -1250,6 +1260,8 @@ export declare class RayTextarea extends FieldControl {
   complete: ((text: string, caret: number) => CompletionResult | null | Promise<CompletionResult | null>) | null;
   /** Accessible name of the suggestion list. */
   suggestionsLabel: string;
+  /** The highlight range under a point of the viewport (clientX, clientY), or null. */
+  highlightAt(x: number, y: number): HighlightRange | null;
   /** Runs highlight again, when what it marks changed but the text did not. */
   refreshHighlight(): void;
   addEventListener<K extends keyof RayTextareaEventMap>(type: K, listener: (this: RayTextarea, ev: RayTextareaEventMap[K]) => unknown, options?: boolean | AddEventListenerOptions): void;
@@ -1260,6 +1272,8 @@ export declare class RayTextarea extends FieldControl {
 export interface RayTextareaEventMap extends HTMLElementEventMap {
   /** A suggestion was accepted (the text already has it). */
   "ray-complete": CustomEvent<{ item: CompletionItem; from: number; to: number }>;
+  /** The highlight range under the pointer changed: the range and the box of the line of it the pointer is on, or null on leaving a range. Anchor a ray-popover to rect (its anchor property) to show more than the title. */
+  "ray-highlight-hover": CustomEvent<{ range: HighlightRange | null; rect: DOMRect | null }>;
 }
 
 // --- Bottom nav (bottom-nav)
@@ -1747,6 +1761,8 @@ export declare class RayMenu extends Floating {
   keepOpen: boolean | undefined;
   /** With a native host (ray-elements/core/raylang.js in a std/ui window), opens as the system's context menu at the pointer: items and dividers, same ray-select. */
   native: boolean | undefined;
+  /** What the panel is placed against instead of the trigger: an element, a DOMRect or a function returning one (a text range, the pointer; read again on every reposition). The trigger still opens it. */
+  anchor: Element | DOMRect | (() => DOMRect) | null;
   /** Opens the items as the system's context menu (needs a native host); resolves to the chosen item, or null. */
   popupNative(): Promise<RayMenuItem | null>;
   /** Opens it. */
@@ -1807,6 +1823,8 @@ export declare class RayPopover extends Floating {
   placement: "bottom" | "bottom-start" | "bottom-end" | "top" | "top-start" | "top-end" | "left" | "left-start" | "left-end" | "right" | "right-start" | "right-end";
   /** Gap to the trigger in px. */
   offset: number;
+  /** What the panel is placed against instead of the trigger: an element, a DOMRect or a function returning one (a text range, the pointer; read again on every reposition). The trigger still opens it. */
+  anchor: Element | DOMRect | (() => DOMRect) | null;
   /** Panel width (px number or CSS length). Default: its content. */
   width: string | undefined;
   /** At least as wide as the trigger. */
@@ -2367,6 +2385,27 @@ export declare class RayProgress extends RayElement {
   label: string | undefined;
 }
 
+// --- Pulse (pulse)
+/** <ray-pulse> Four presets (variant), each a bundle of count, shape, fade and direction, which override it one by one. The rest is tuned with custom properties on the element: --ray-pulse-cycle (one cycle, default 1.6s; doubled with reduced motion), --ray-pulse-floor (opacity of the largest of concentric filled circles, 0 to 1, default 0.2), --ray-pulse-scale (where a cycle starts, 1 = full size; default per variant) and --ray-pulse-stagger (how much of the cycle separates the phases of the circles, 0 together to 1 spread evenly; default per variant). */
+export declare class RayPulse extends RayElement {
+  /** The figure: cluster (three concentric circles breathing out of phase), breathe (one dot over a halo), ripple (rings expanding from a dot) or dots (three in a row, in sequence). */
+  variant: "cluster" | "breathe" | "ripple" | "dots";
+  /** Number of circles, 1 to 5 (more are clamped). Default: the variant's. */
+  count: number | undefined;
+  /** Filled discs (concentric ones fade with size, see --ray-pulse-floor) or outlined rings. Default: the variant's. */
+  shape: "filled" | "ring" | undefined;
+  /** Whether a cycle ends transparent; the bare attribute means out. Default: the variant's (ripple and dots fade). */
+  fade: "out" | "none" | undefined;
+  /** alternate goes there and back; normal goes one way and restarts (with fade: the ripple). Default: the variant's. */
+  direction: "alternate" | "normal" | undefined;
+  /** A palette color or any CSS color. Default: the primary color. */
+  color: string | undefined;
+  /** Height of the figure (the dots variant is wider). */
+  size: "xs" | "sm" | "md" | "lg" | "xl";
+  /** Text read by screen readers. */
+  label: string;
+}
+
 // --- Ring progress (ring-progress)
 /** <ray-ring-progress> The arc starts at 12 o'clock and runs clockwise; a countdown is a value that goes down. Without value it spins (indeterminate). The middle holds the default slot (a clock), or the percentage with show-value. */
 export declare class RayRingProgress extends RayElement {
@@ -2764,6 +2803,7 @@ declare global {
     "ray-notification": RayNotification;
     "ray-toaster": RayToaster;
     "ray-progress": RayProgress;
+    "ray-pulse": RayPulse;
     "ray-ring-progress": RayRingProgress;
     "ray-skeleton": RaySkeleton;
     "ray-spinner": RaySpinner;

package/vscode.html-custom-data.json

@@ -6645,6 +6645,99 @@
         }
       ]
     },
+    {
+      "name": "ray-pulse",
+      "description": "Four presets (variant), each a bundle of count, shape, fade and direction, which override it one by one. The rest is tuned with custom properties on the element: --ray-pulse-cycle (one cycle, default 1.6s; doubled with reduced motion), --ray-pulse-floor (opacity of the largest of concentric filled circles, 0 to 1, default 0.2), --ray-pulse-scale (where a cycle starts, 1 = full size; default per variant) and --ray-pulse-stagger (how much of the cycle separates the phases of the circles, 0 together to 1 spread evenly; default per variant).",
+      "attributes": [
+        {
+          "name": "variant",
+          "description": "The figure: cluster (three concentric circles breathing out of phase), breathe (one dot over a halo), ripple (rings expanding from a dot) or dots (three in a row, in sequence).",
+          "values": [
+            {
+              "name": "cluster"
+            },
+            {
+              "name": "breathe"
+            },
+            {
+              "name": "ripple"
+            },
+            {
+              "name": "dots"
+            }
+          ]
+        },
+        {
+          "name": "count",
+          "description": "Number of circles, 1 to 5 (more are clamped). Default: the variant's."
+        },
+        {
+          "name": "shape",
+          "description": "Filled discs (concentric ones fade with size, see --ray-pulse-floor) or outlined rings. Default: the variant's.",
+          "values": [
+            {
+              "name": "filled"
+            },
+            {
+              "name": "ring"
+            }
+          ]
+        },
+        {
+          "name": "fade",
+          "description": "Whether a cycle ends transparent; the bare attribute means out. Default: the variant's (ripple and dots fade).",
+          "values": [
+            {
+              "name": "out"
+            },
+            {
+              "name": "none"
+            }
+          ]
+        },
+        {
+          "name": "direction",
+          "description": "alternate goes there and back; normal goes one way and restarts (with fade: the ripple). Default: the variant's.",
+          "values": [
+            {
+              "name": "alternate"
+            },
+            {
+              "name": "normal"
+            }
+          ]
+        },
+        {
+          "name": "color",
+          "description": "A palette color or any CSS color. Default: the primary color."
+        },
+        {
+          "name": "size",
+          "description": "Height of the figure (the dots variant is wider).",
+          "values": [
+            {
+              "name": "xs"
+            },
+            {
+              "name": "sm"
+            },
+            {
+              "name": "md"
+            },
+            {
+              "name": "lg"
+            },
+            {
+              "name": "xl"
+            }
+          ]
+        },
+        {
+          "name": "label",
+          "description": "Text read by screen readers."
+        }
+      ]
+    },
     {
       "name": "ray-ring-progress",
       "description": "The arc starts at 12 o'clock and runs clockwise; a countdown is a value that goes down. Without value it spins (indeterminate). The middle holds the default slot (a clock), or the percentage with show-value.",