@raylang/elements 0.11.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/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",

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.11.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.

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.11.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>`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raylang/elements",
-  "version": "0.11.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"],

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. */