Build your personal knowledge base with Trilium Notes
TypeScript electronelectron-appknowledge-baseknowledge-graphknowledge-managementknowledge-management-graphlocal-firstnote-managmentnote-takernote-takingnotebooknotesnotes-apppersonal-knowledge-basepersonal-wikiscriptableself-hostedself-hostingwiki
import "./ScrollableLabel.css";
import clsx from "clsx";
import { type ComponentChildren, createRef, type RefObject, render } from "preact";
import { useCallback, useEffect, useRef } from "preact/hooks";
import { useScrollFade } from "./scroll_fade";
/** How fast a label reads itself out, in pixels a second: walking pace for the eye, not a marquee. */
const AUTO_SCROLL_SPEED = 30;
/** How far a pressed mouse moves along the label before it drags the line, in pixels. */
const DRAG_THRESHOLD = 4;
interface ScrollableLabelProps {
children?: ComponentChildren;
className?: string;
/**
* Walk the line to its end on its own, so what is cut off is read without being asked for. It
* stops at the end rather than looping or coming back, and the first sign of the reader taking
* over hands it to them for good: what they were reading must not slide out from under them.
*
* For a line that is shown rather than reached for, and where nothing is lost by it moving. Not
* for one the reader is picking a part out of.
*/
autoScroll?: boolean;
}
/**
* A single line of text too long for its box, which the reader swipes along rather than losing the end
* of. What is cut off fades out at whichever edge it continues past, so the line says that it goes on
* — the ellipsis of a label that can actually be read to the end.
*
* For where a name has to be given in full and there is no width to give it in: a phone, a narrow
* pane, a strip along the foot of a chart. A label that fits behaves as any other, showing no fade
* and taking no swipe.
*/
export default function ScrollableLabel({ children, className, autoScroll }: ScrollableLabelProps) {
const ref = useRef<HTMLDivElement>(null);
// The walk below starts over whenever the overflow changes, which is what walks a label whose
// words arrived after it did, a path waiting on its titles, without asking the caller to say so
// and without restarting on a render that changed nothing.
// `minOverflow` is dropped to a pixel: a line cut off by a character still has to read as cut
// off, and the walk below runs on any overflow at all.
const { className: fadeClass, overflow } = useScrollFade(ref, {
direction: "horizontal",
minOverflow: 1
});
useMouseDragScroll(ref);
// Set by the reader's own first scroll, and cleared only by a remount, which is what a new label
// is: a walk they interrupted must not start again while the same line is still on screen. A
// consumer whose label changes what it names keys it, so the new one arrives with a fresh walk.
const handedOver = useRef(false);
const handOver = useCallback(() => {
handedOver.current = true;
}, []);
useEffect(() => {
const element = ref.current;
// Handed over stays handed over: this effect runs again whenever the line's length changes,
// and a box resized under the reader — a rotation, a keyboard opening, a pane dragged — must
// not take the line back off them, which restarting from the beginning would.
if (!autoScroll || !element || handedOver.current || prefersReducedMotion()) {
return;
}
element.scrollLeft = 0;
// Read once rather than per frame: a right-to-left line travels towards negative offsets, so
// the same distance is applied with the sign its direction gives it.
const sign = getComputedStyle(element).direction === "rtl" ? -1 : 1;
let travelled = 0;
let previous: number | undefined;
let frame = 0;
// Advanced by elapsed time rather than by a step per frame, so the line reads at one pace
// whatever the display refreshes at, and a frame the browser skipped is made up for. Written
// out before it is asked for, so that the element read above stays narrowed inside it.
const step = (now: number) => {
// Tested here rather than only before asking for the next frame: the frame already in
// hand when the reader took over would otherwise move the line one last time, under them.
if (handedOver.current) {
return;
}
const total = element.scrollWidth - element.clientWidth;
if (previous !== undefined) {
travelled = Math.min(travelled + (now - previous) * AUTO_SCROLL_SPEED / 1000, total);
element.scrollLeft = sign * travelled;
}
previous = now;
// The end is where it stops: there is nothing further to read, and a line that came back
// to its start would be read as a new one arriving.
if (travelled < total) {
frame = requestAnimationFrame(step);
}
};
frame = requestAnimationFrame(step);
return () => cancelAnimationFrame(frame);
// Restarted when the line's length changes rather than when its markup does, so a label
// rendered again with the same words is left walking where it was.
}, [ autoScroll, overflow ]);
return (
<div
ref={ref}
className={clsx("scrollable-label", fadeClass, className)}
// The gesture rather than the scrolling it causes: a pointer going down on the label, or a
// wheel over it, says the reader has taken over before the line has moved an inch. Which
// is also why this is not read off the scroll events, where the walk's own scrolling and
// the reader's would have to be told apart by their arithmetic.
onPointerDown={autoScroll ? handOver : undefined}
onWheel={autoScroll ? handOver : undefined}
>{children}</div>
);
}
/**
* Moves the content of `element`, which Preact does not render, into a {@link ScrollableLabel}
* mounted inside it. Returns a function that unmounts the label and puts the content back.
*/
export function mountScrollableLabel(element: HTMLElement) {
// `render()` reuses or removes the children it finds in `element`.
const nodes = [ ...element.childNodes ];
element.replaceChildren();
const contentRef = createRef<HTMLSpanElement>();
render(<ScrollableLabel><span ref={contentRef} /></ScrollableLabel>, element);
const content = contentRef.current;
content?.append(...nodes);
return () => {
const current = content ? [ ...content.childNodes ] : nodes;
render(null, element);
element.replaceChildren(...current);
};
}
/**
* Scrolls the label in `ref` with a mouse dragged along it, as a swipe does on a touch screen.
* While the label overflows, a mouse press on it starts no native drag, such as that of a link, and
* no text selection, and the click that ends a drag is canceled.
*/
function useMouseDragScroll(ref: RefObject<HTMLElement | null>) {
useEffect(() => {
const element = ref.current;
if (!element) return;
let press: { pointerId: number; x: number; scrollLeft: number; isDragging: boolean }
| undefined;
let isClickCanceled = false;
// `user-select: none` on a pressed label keeps Firefox from starting a selection drag, whose
// autoscroll moves the label toward the pointer even when `selectstart` is canceled.
const setPress = (next: typeof press) => {
press = next;
element.toggleAttribute("data-pressed", !!next);
};
const onPointerDown = (event: PointerEvent) => {
isClickCanceled = false;
setPress(event.pointerType === "mouse" && event.button === 0
&& element.scrollWidth > element.clientWidth
? {
pointerId: event.pointerId,
x: event.clientX,
scrollLeft: element.scrollLeft,
isDragging: false
}
: undefined);
};
const onPointerMove = (event: PointerEvent) => {
if (event.pointerId !== press?.pointerId) return;
// Released away from the label before the drag captured the pointer.
if (!(event.buttons & 1)) {
setPress(undefined);
return;
}
const distance = event.clientX - press.x;
if (!press.isDragging && Math.abs(distance) >= DRAG_THRESHOLD) {
press.isDragging = true;
// Keeps the drag going once the pointer leaves the label.
element.setPointerCapture(event.pointerId);
}
if (press.isDragging) {
element.scrollLeft = press.scrollLeft - distance;
}
};
const onPointerUp = (event: PointerEvent) => {
if (event.pointerId !== press?.pointerId) return;
isClickCanceled = event.type === "pointerup" && press.isDragging;
setPress(undefined);
};
const preventWhilePressed = (event: Event) => {
if (press) {
event.preventDefault();
}
};
const cancelClick = (event: MouseEvent) => {
if (isClickCanceled) {
isClickCanceled = false;
event.preventDefault();
event.stopPropagation();
}
};
element.addEventListener("pointerdown", onPointerDown);
element.addEventListener("pointermove", onPointerMove);
element.addEventListener("pointerup", onPointerUp);
element.addEventListener("pointercancel", onPointerUp);
element.addEventListener("dragstart", preventWhilePressed);
element.addEventListener("click", cancelClick, true);
return () => {
element.removeEventListener("pointerdown", onPointerDown);
element.removeEventListener("pointermove", onPointerMove);
element.removeEventListener("pointerup", onPointerUp);
element.removeEventListener("pointercancel", onPointerUp);
element.removeEventListener("dragstart", preventWhilePressed);
element.removeEventListener("click", cancelClick, true);
element.removeAttribute("data-pressed");
};
}, [ ref ]);
}
/** A line that moves on its own is the thing this setting is there to ask for less of. */
function prefersReducedMotion() {
return window.matchMedia("(prefers-reduced-motion: reduce)").matches;
}