@lynx-js/web-elements 0.12.8 → 0.12.10

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # @lynx-js/web-elements
 
+## 0.12.10
+
+### Patch Changes
+
+- Update markdown-it to ^15.0.1. ([#3749](https://github.com/lynx-family/lynx-stack/pull/3749))
+
+- Add an optional `scroll-view` mouse-drag plugin for touchscreen-like scrolling ([#3594](https://github.com/lynx-family/lynx-stack/pull/3594))
+  on desktop browsers. Enable it by importing
+  `@lynx-js/web-core/plugins/scroll-view-mouse-drag` or
+  `@lynx-js/web-elements/plugins/scroll-view-mouse-drag` before registering the
+  web elements.
+- Support the `bindselectionchange` event on `text` and `inline-text` in Lynx for Web. ([#3741](https://github.com/lynx-family/lynx-stack/pull/3741))
+
+## 0.12.9
+
+### Patch Changes
+
+- Clamp the `setFoldExpanded` offset of `<x-foldview-ng>` to the scrollable length. ([#3290](https://github.com/lynx-family/lynx-stack/pull/3290))
+
+  `setFoldExpanded` called the native `scrollTo`, bypassing the clamping done by the
+  `scrollTop` setter. A page collapsing its header with a deliberately large offset
+  (e.g. `offset: '99999px'`) scrolled past the end, which does not happen on native.
+- Give `<x-foldview-header-ng>` a `width: 100%`. ([#3290](https://github.com/lynx-family/lynx-stack/pull/3290))
+
+  The element is laid out with `position: absolute` but had no width, so it shrank to
+  fit its content instead of filling the foldview.
+
 ## 0.12.8
 
 ### Patch Changes

package/README.md

@@ -37,6 +37,20 @@ document.body.innerHTML = `
 `;
 ```
 
+### Mouse-drag scrolling
+
+To make `<scroll-view>` respond to mouse dragging like a touchscreen, load
+the optional plugin before registering the elements:
+
+```javascript
+import '@lynx-js/web-elements/plugins/scroll-view-mouse-drag';
+import '@lynx-js/web-elements/all';
+import '@lynx-js/web-elements/index.css';
+```
+
+The plugin only changes `<scroll-view>` and leaves native touch scrolling
+unchanged.
+
 ## Document
 
 See our website for more information.

package/dist/elements/ScrollView/ScrollViewMouseDrag.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/elements/ScrollView/ScrollViewMouseDrag.js

@@ -0,0 +1,315 @@
+// Copyright 2026 The Lynx Authors. All rights reserved.
+// Licensed under the Apache License Version 2.0 that can be found in the
+// LICENSE file in the root directory of this source tree.
+import { boostedQueueMicrotask } from '../../element-reactive/index.js';
+const dragStartThreshold = 5;
+const userScrollableOverflowValues = new Set(['auto', 'overlay', 'scroll']);
+const blockingOverscrollBehaviorValues = new Set(['contain', 'none']);
+function getScrollableAxes(dom, style) {
+    if (dom.getAttribute('enable-scroll') === 'false') {
+        return { x: false, y: false };
+    }
+    return {
+        x: userScrollableOverflowValues.has(style.overflowX)
+            && dom.scrollWidth - dom.clientWidth > 1,
+        y: userScrollableOverflowValues.has(style.overflowY)
+            && dom.scrollHeight - dom.clientHeight > 1,
+    };
+}
+function findScrollChain(event) {
+    let owner;
+    let ownerAxes;
+    const x = [];
+    const y = [];
+    for (const target of event.composedPath()) {
+        if (!(target instanceof HTMLElement) || target.localName !== 'scroll-view') {
+            continue;
+        }
+        const style = getComputedStyle(target);
+        const axes = getScrollableAxes(target, style);
+        if (!axes.x && !axes.y) {
+            continue;
+        }
+        if (!owner) {
+            owner = target;
+            ownerAxes = axes;
+        }
+        if (axes.x) {
+            x.push({
+                allowsChaining: !blockingOverscrollBehaviorValues.has(style.overscrollBehaviorX),
+                dom: target,
+                start: target.scrollLeft,
+            });
+        }
+        if (axes.y) {
+            y.push({
+                allowsChaining: !blockingOverscrollBehaviorValues.has(style.overscrollBehaviorY),
+                dom: target,
+                start: target.scrollTop,
+            });
+        }
+    }
+    return owner && ownerAxes ? { owner, ownerAxes, x, y } : undefined;
+}
+function selectDragAxes(chain, deltaX, deltaY) {
+    const absoluteX = Math.abs(deltaX);
+    const absoluteY = Math.abs(deltaY);
+    if (Math.hypot(deltaX, deltaY) <= dragStartThreshold) {
+        return undefined;
+    }
+    const hasX = chain.x.length > 0;
+    const hasY = chain.y.length > 0;
+    if (chain.ownerAxes.x && chain.ownerAxes.y) {
+        return { x: hasX, y: hasY };
+    }
+    if (hasX && hasY) {
+        if (absoluteX === absoluteY) {
+            return chain.ownerAxes.x
+                ? { x: true, y: false }
+                : { x: false, y: true };
+        }
+        return absoluteX > absoluteY
+            ? { x: true, y: false }
+            : { x: false, y: true };
+    }
+    if (hasX && absoluteX >= absoluteY) {
+        return { x: true, y: false };
+    }
+    if (hasY && absoluteY >= absoluteX) {
+        return { x: false, y: true };
+    }
+    return undefined;
+}
+function applyScrollDelta(candidates, delta, axis) {
+    let remaining = delta;
+    for (const candidate of candidates) {
+        const next = candidate.start + remaining;
+        if (axis === 'x') {
+            candidate.dom.scrollTo({
+                behavior: 'instant',
+                left: next,
+                top: candidate.dom.scrollTop,
+            });
+            remaining -= candidate.dom.scrollLeft - candidate.start;
+        }
+        else {
+            candidate.dom.scrollTo({
+                behavior: 'instant',
+                left: candidate.dom.scrollLeft,
+                top: next,
+            });
+            remaining -= candidate.dom.scrollTop - candidate.start;
+        }
+        if (!candidate.allowsChaining) {
+            return;
+        }
+    }
+}
+/**
+ * Makes a scroll-view follow mouse dragging in the same direction as touch
+ * scrolling. Pointer events from touchscreens are left to the browser.
+ */
+class ScrollViewMouseDrag {
+    static observedAttributes = [];
+    #dom;
+    #connected = false;
+    #dragState;
+    #clickSuppression;
+    constructor(dom) {
+        this.#dom = dom;
+    }
+    #handlePointerDown = (event) => {
+        if (event.pointerType !== 'mouse'
+            || !event.isPrimary
+            || event.button !== 0
+            || this.#dragState) {
+            return;
+        }
+        const chain = findScrollChain(event);
+        if (!chain || chain.owner !== this.#dom) {
+            return;
+        }
+        const document = this.#dom.ownerDocument;
+        this.#dragState = {
+            chain,
+            document,
+            dragging: false,
+            pendingDeltaX: 0,
+            pendingDeltaY: 0,
+            pointerId: event.pointerId,
+            scrollUpdateQueued: false,
+            startClientX: event.clientX,
+            startClientY: event.clientY,
+        };
+        this.#trackPotentialClick(document);
+        document.addEventListener('pointermove', this.#handlePointerMove, {
+            capture: true,
+            passive: false,
+        });
+        document.addEventListener('pointerup', this.#handlePointerUp, true);
+        document.addEventListener('pointercancel', this.#handlePointerCancel, true);
+        document.defaultView?.addEventListener('blur', this.#handlePointerCancel);
+    };
+    #handlePointerMove = (event) => {
+        const state = this.#dragState;
+        if (!state || event.pointerId !== state.pointerId) {
+            return;
+        }
+        if ((event.buttons & 1) === 0) {
+            this.#stopDragging(false);
+            return;
+        }
+        const deltaX = event.clientX - state.startClientX;
+        const deltaY = event.clientY - state.startClientY;
+        if (!state.dragging) {
+            const activeAxes = selectDragAxes(state.chain, deltaX, deltaY);
+            if (!activeAxes) {
+                return;
+            }
+            state.activeAxes = activeAxes;
+            state.dragging = true;
+            state.previousUserSelect = this.#dom.style.userSelect;
+            this.#dom.style.userSelect = 'none';
+            state.document.getSelection()?.removeAllRanges();
+            this.#dom.setPointerCapture(event.pointerId);
+        }
+        if (event.cancelable) {
+            event.preventDefault();
+        }
+        state.pendingDeltaX = -deltaX;
+        state.pendingDeltaY = -deltaY;
+        if (!state.scrollUpdateQueued) {
+            state.scrollUpdateQueued = true;
+            boostedQueueMicrotask(() => this.#flushScrollUpdate(state));
+        }
+    };
+    #flushScrollUpdate(state) {
+        if (!state.scrollUpdateQueued) {
+            return;
+        }
+        state.scrollUpdateQueued = false;
+        if (state.activeAxes?.x) {
+            applyScrollDelta(state.chain.x, state.pendingDeltaX, 'x');
+        }
+        if (state.activeAxes?.y) {
+            applyScrollDelta(state.chain.y, state.pendingDeltaY, 'y');
+        }
+    }
+    #handlePointerUp = (event) => {
+        if (event.pointerId !== this.#dragState?.pointerId) {
+            return;
+        }
+        this.#stopDragging(this.#dragState.dragging);
+    };
+    #handlePointerCancel = (event) => {
+        if (event instanceof PointerEvent
+            && event.pointerId !== this.#dragState?.pointerId) {
+            return;
+        }
+        this.#stopDragging(false);
+    };
+    #handleDragStart = (event) => {
+        if (this.#dragState) {
+            event.preventDefault();
+        }
+    };
+    #handleClick = (event) => {
+        if (!this.#clickSuppression?.suppress
+            || !event.composedPath().includes(this.#dom)) {
+            return;
+        }
+        this.#clearClickSuppression();
+        event.preventDefault();
+        event.stopImmediatePropagation();
+    };
+    #stopDragging(suppressClick) {
+        const state = this.#dragState;
+        if (!state) {
+            return;
+        }
+        const { document } = state;
+        this.#flushScrollUpdate(state);
+        document.removeEventListener('pointermove', this.#handlePointerMove, true);
+        document.removeEventListener('pointerup', this.#handlePointerUp, true);
+        document.removeEventListener('pointercancel', this.#handlePointerCancel, true);
+        document.defaultView?.removeEventListener('blur', this.#handlePointerCancel);
+        if (this.#dom.hasPointerCapture(state.pointerId)) {
+            this.#dom.releasePointerCapture(state.pointerId);
+        }
+        if (state.dragging && this.#dom.style.userSelect === 'none') {
+            this.#dom.style.userSelect = state.previousUserSelect ?? '';
+        }
+        this.#dragState = undefined;
+        if (suppressClick) {
+            const clickSuppression = this.#clickSuppression;
+            if (clickSuppression) {
+                clickSuppression.suppress = true;
+                clearTimeout(clickSuppression.timer);
+                clickSuppression.timer = setTimeout(this.#clearClickSuppression, 0);
+            }
+        }
+        else {
+            this.#clearClickSuppression();
+        }
+    }
+    #trackPotentialClick(document) {
+        this.#clearClickSuppression();
+        const target = document.defaultView ?? document;
+        this.#clickSuppression = { suppress: false, target };
+        target.addEventListener('click', this.#handleClick, true);
+    }
+    #clearClickSuppression = () => {
+        const clickSuppression = this.#clickSuppression;
+        if (!clickSuppression) {
+            return;
+        }
+        clickSuppression.target.removeEventListener('click', this.#handleClick, true);
+        clearTimeout(clickSuppression.timer);
+        this.#clickSuppression = undefined;
+    };
+    connectedCallback() {
+        if (this.#connected) {
+            return;
+        }
+        this.#connected = true;
+        this.#dom.addEventListener('pointerdown', this.#handlePointerDown, true);
+        this.#dom.addEventListener('dragstart', this.#handleDragStart, true);
+    }
+    dispose() {
+        this.#connected = false;
+        this.#dom.removeEventListener('pointerdown', this.#handlePointerDown, true);
+        this.#dom.removeEventListener('dragstart', this.#handleDragStart, true);
+        this.#stopDragging(false);
+        this.#clearClickSuppression();
+    }
+}
+const scrollViewTagName = 'scroll-view';
+const registeredClasses = new WeakSet();
+function registerMouseDragPlugin(elementClass) {
+    if (registeredClasses.has(elementClass)) {
+        return;
+    }
+    const componentClass = elementClass;
+    if (!componentClass.registerPlugin) {
+        return;
+    }
+    componentClass.registerPlugin(ScrollViewMouseDrag);
+    registeredClasses.add(elementClass);
+}
+if (typeof customElements !== 'undefined') {
+    const registeredScrollView = customElements.get(scrollViewTagName);
+    if (registeredScrollView) {
+        registerMouseDragPlugin(registeredScrollView);
+    }
+    else {
+        const define = Reflect.get(customElements, 'define');
+        customElements.define = function (name, elementClass, options) {
+            if (name === scrollViewTagName) {
+                registerMouseDragPlugin(elementClass);
+            }
+            Reflect.apply(define, this, [name, elementClass, options]);
+        };
+        void customElements.whenDefined(scrollViewTagName).then(registerMouseDragPlugin);
+    }
+}
+//# sourceMappingURL=ScrollViewMouseDrag.js.map

package/dist/elements/XFoldViewNg/XFoldviewNg.js

@@ -70,8 +70,10 @@ let XFoldviewNg = (() => {
         setFoldExpanded(params) {
             const { offset, smooth = true } = params;
             const offsetValue = parseFloat(offset);
+            // `scrollTo` is the native method and does not go through the `scrollTop`
+            // setter above, so the offset has to be clamped here as well.
             this.scrollTo({
-                top: offsetValue,
+                top: Math.min(Math.max(offsetValue, 0), this[scrollableLength]),
                 behavior: smooth ? 'smooth' : 'instant',
             });
         }

package/dist/elements/XText/InlineText.d.ts

@@ -1,5 +1,5 @@
 /**
- * @deprecated you can use x-text instead in x-text.
+ * @deprecated Use x-text instead of inline-text.
  */
 export declare class InlineText extends HTMLElement {
 }

package/dist/elements/XText/InlineText.js

@@ -5,11 +5,12 @@ import { __esDecorate, __runInitializers } from "tslib";
 // LICENSE file in the root directory of this source tree.
 */
 import { Component } from '../../element-reactive/index.js';
+import { XTextSelectionEvents } from './XTextSelectionEvents.js';
 /**
- * @deprecated you can use x-text instead in x-text.
+ * @deprecated Use x-text instead of inline-text.
  */
 let InlineText = (() => {
-    let _classDecorators = [Component('inline-text', [])];
+    let _classDecorators = [Component('inline-text', [XTextSelectionEvents])];
     let _classDescriptor;
     let _classExtraInitializers = [];
     let _classThis;

package/dist/elements/XText/XText.js

@@ -10,8 +10,14 @@ import { ScrollIntoView } from '../ScrollView/ScrollIntoView.js';
 import { RawTextAttributes } from './RawText.js';
 import { CommonEventsAndMethods, layoutChangeTarget, } from '../common/CommonEventsAndMethods.js';
 import { templateXText } from '../htmlTemplates.js';
+import { XTextSelectionEvents } from './XTextSelectionEvents.js';
 let XText = (() => {
-    let _classDecorators = [Component('x-text', [CommonEventsAndMethods, XTextTruncation, RawTextAttributes], templateXText)];
+    let _classDecorators = [Component('x-text', [
+            CommonEventsAndMethods,
+            XTextSelectionEvents,
+            XTextTruncation,
+            RawTextAttributes,
+        ], templateXText)];
     let _classDescriptor;
     let _classExtraInitializers = [];
     let _classThis;

package/dist/elements/XText/XTextSelectionEvents.d.ts

@@ -0,0 +1,9 @@
+import { type AttributeReactiveClass } from '../../element-reactive/index.js';
+export declare class XTextSelectionEvents implements InstanceType<AttributeReactiveClass<typeof HTMLElement>> {
+    #private;
+    static observedAttributes: never[];
+    constructor(dom: HTMLElement);
+    connectedCallback(): void;
+    dispose(): void;
+    _handleEnableSelectionChangeEvent(status: boolean): void;
+}

package/dist/elements/XText/XTextSelectionEvents.js

@@ -0,0 +1,134 @@
+import { __esDecorate, __runInitializers } from "tslib";
+/*
+// Copyright 2026 The Lynx Authors. All rights reserved.
+// Licensed under the Apache License Version 2.0 that can be found in the
+// LICENSE file in the root directory of this source tree.
+*/
+import { registerEventEnableStatusChangeHandler, } from '../../element-reactive/index.js';
+import { commonComponentEventSetting } from '../common/commonEventInitConfiguration.js';
+const emptySelection = () => ({
+    start: -1,
+    end: -1,
+    direction: 'forward',
+});
+/**
+ * Converts a selection boundary to an offset in the target's text. Using the
+ * range text length provides one offset space across nested text nodes.
+ */
+const getTextOffset = (root, node, offset) => {
+    if (!node || !root.contains(node))
+        return null;
+    const range = root.ownerDocument.createRange();
+    range.selectNodeContents(root);
+    try {
+        range.setEnd(node, offset);
+    }
+    catch {
+        return null;
+    }
+    return range.toString().length;
+};
+/**
+ * Returns offsets relative to the target text. A -1 offset means the selection
+ * is collapsed, unavailable, or outside the target.
+ */
+const getSelectionDetail = (dom) => {
+    const selection = dom.ownerDocument.getSelection();
+    if (!selection || selection.rangeCount === 0) {
+        return emptySelection();
+    }
+    const anchor = getTextOffset(dom, selection.anchorNode, selection.anchorOffset);
+    const focus = getTextOffset(dom, selection.focusNode, selection.focusOffset);
+    if (anchor !== null && focus !== null && anchor !== focus) {
+        return {
+            start: Math.min(anchor, focus),
+            end: Math.max(anchor, focus),
+            direction: anchor < focus ? 'forward' : 'backward',
+        };
+    }
+    // WebKit retargets selection endpoints outside a shadow tree. Ask for the
+    // composed range to recover the actual text nodes in that case.
+    const shadowRoots = [];
+    let root = dom.getRootNode();
+    while (root instanceof ShadowRoot) {
+        shadowRoots.push(root);
+        root = root.host.getRootNode();
+    }
+    const [range] = selection.getComposedRanges?.({ shadowRoots }) ?? [];
+    const start = range
+        ? getTextOffset(dom, range.startContainer, range.startOffset)
+        : null;
+    const end = range
+        ? getTextOffset(dom, range.endContainer, range.endOffset)
+        : null;
+    if (start === null || end === null || start === end)
+        return emptySelection();
+    return {
+        start,
+        end,
+        direction: selection.direction === 'backward' ? 'backward' : 'forward',
+    };
+};
+let XTextSelectionEvents = (() => {
+    let _instanceExtraInitializers = [];
+    let __handleEnableSelectionChangeEvent_decorators;
+    return class XTextSelectionEvents {
+        static {
+            const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(null) : void 0;
+            __handleEnableSelectionChangeEvent_decorators = [registerEventEnableStatusChangeHandler('selectionchange')];
+            __esDecorate(this, null, __handleEnableSelectionChangeEvent_decorators, { kind: "method", name: "_handleEnableSelectionChangeEvent", static: false, private: false, access: { has: obj => "_handleEnableSelectionChangeEvent" in obj, get: obj => obj._handleEnableSelectionChangeEvent }, metadata: _metadata }, null, _instanceExtraInitializers);
+            if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
+        }
+        static observedAttributes = [];
+        #dom = __runInitializers(this, _instanceExtraInitializers);
+        #enabled = false;
+        #connected = false;
+        #attachedDocument;
+        #lastSelectionSignature;
+        constructor(dom) {
+            this.#dom = dom;
+        }
+        connectedCallback() {
+            this.#connected = true;
+            this.#updateSelectionChangeListener();
+        }
+        dispose() {
+            this.#connected = false;
+            this.#updateSelectionChangeListener();
+        }
+        _handleEnableSelectionChangeEvent(status) {
+            this.#enabled = status;
+            if (!status)
+                this.#lastSelectionSignature = undefined;
+            this.#updateSelectionChangeListener();
+        }
+        #updateSelectionChangeListener() {
+            const document = this.#dom.ownerDocument;
+            const shouldAttach = this.#enabled && this.#connected;
+            if (shouldAttach && this.#attachedDocument === document)
+                return;
+            if (!shouldAttach && !this.#attachedDocument)
+                return;
+            this.#attachedDocument?.removeEventListener('selectionchange', this.#handleSelectionChange);
+            if (shouldAttach) {
+                document.addEventListener('selectionchange', this.#handleSelectionChange);
+            }
+            this.#attachedDocument = shouldAttach ? document : undefined;
+        }
+        #handleSelectionChange = () => {
+            const detail = getSelectionDetail(this.#dom);
+            const signature = `${detail.start}:${detail.end}:${detail.direction}`;
+            if (signature === this.#lastSelectionSignature
+                || (detail.start === -1 && this.#lastSelectionSignature === undefined)) {
+                return;
+            }
+            this.#lastSelectionSignature = signature;
+            this.#dom.dispatchEvent(new CustomEvent('selectionchange', {
+                ...commonComponentEventSetting,
+                detail,
+            }));
+        };
+    };
+})();
+export { XTextSelectionEvents };
+//# sourceMappingURL=XTextSelectionEvents.js.map

package/dist/elements/XText/index.d.ts

@@ -14,6 +14,7 @@ export { RawText } from './RawText.js';
  *
  * Events:
  * - `layout`: Fired when text layout happens (if enabled). Detail provides line info.
+ * - `selectionchange`: Fired when the text selection changes. Detail provides start, end, and direction.
  *
  * CSS Variables:
  * - `--lynx-text-bg-color`: Inherited background color for nested text elements.

package/dist/elements/XText/index.js

@@ -17,6 +17,7 @@ export { RawText } from './RawText.js';
  *
  * Events:
  * - `layout`: Fired when text layout happens (if enabled). Detail provides line info.
+ * - `selectionchange`: Fired when the text selection changes. Detail provides start, end, and direction.
  *
  * CSS Variables:
  * - `--lynx-text-bg-color`: Inherited background color for nested text elements.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lynx-js/web-elements",
-  "version": "0.12.8",
+  "version": "0.12.10",
   "private": false,
   "repository": {
     "type": "git",
@@ -34,6 +34,11 @@
       "types": "./dist/elements/ScrollView/index.d.ts",
       "default": "./dist/elements/ScrollView/index.js"
     },
+    "./plugins/scroll-view-mouse-drag": {
+      "@lynx-js/source-field": "./src/elements/ScrollView/ScrollViewMouseDrag.ts",
+      "types": "./dist/elements/ScrollView/ScrollViewMouseDrag.d.ts",
+      "default": "./dist/elements/ScrollView/ScrollViewMouseDrag.js"
+    },
     "./XAudioTT": {
       "@lynx-js/source-field": "./src/elements/XAudioTT/index.ts",
       "types": "./dist/elements/XAudioTT/index.d.ts",
@@ -135,11 +140,11 @@
   ],
   "dependencies": {
     "dompurify": "^3.4.13",
-    "markdown-it": "^15.0.0"
+    "markdown-it": "^15.0.1"
   },
   "devDependencies": {
     "@playwright/test": "^1.61.1",
-    "@rsbuild/core": "2.1.10",
+    "@rsbuild/core": "2.2.3",
     "@rsbuild/plugin-source-build": "1.0.6",
     "@types/markdown-it": "^14.1.2",
     "@types/node": "^24.13.3",

package/src/elements/XFoldViewNg/x-foldview-ng.css

@@ -59,6 +59,8 @@ x-foldview-header-ng {
   order: 2;
   flex: 0 0 auto;
   position: absolute;
+  /* an out-of-flow box shrinks to fit its content without an explicit width */
+  width: 100%;
 }
 
 x-foldview-ng[header-over-slot] > x-foldview-slot-ng,