@docentjs/dom 0.2.1 → 0.3.1

package/dist/index.d.cts

@@ -114,7 +114,12 @@ export declare class DomRenderer implements Renderer {
   private isSheet;
   /** In sheet mode, scroll once so the target is not hidden behind the sheet. */
   private keepClearOfSheet;
-  /** Run after a smooth scroll settles (scrollend, or a short fallback), or right away. */
+  /**
+   * Run once a smooth scroll has settled, or right away for instant scrolls.
+   * Settled means the target stopped moving for two frames' worth of samples,
+   * not a fixed delay: smooth scrolls take longer on slow or busy devices.
+   * `scrollend` finishes early where supported; a cap keeps it bounded.
+   */
   private afterScroll;
   private template;
   private buildDefault;
@@ -145,8 +150,11 @@ interface CreateTourOptions extends Omit<ControllerOptions, 'tour' | 'renderer'>
  */
 export declare class DomTourController extends TourController {
   private readonly cleanups;
+  private readonly followRoutes;
   constructor(tour: Tour, options?: CreateTourOptions);
+  start(at?: number | string): Promise<void>;
   destroy(): Promise<void>;
+  private listenToRoutes;
 }
 /** Create a browser-ready tour. Call `.start()` or `.resume()` on the result. */
 export declare function createTour(tour: Tour, options?: CreateTourOptions): DomTourController;

package/dist/index.d.ts

@@ -114,7 +114,12 @@ export declare class DomRenderer implements Renderer {
   private isSheet;
   /** In sheet mode, scroll once so the target is not hidden behind the sheet. */
   private keepClearOfSheet;
-  /** Run after a smooth scroll settles (scrollend, or a short fallback), or right away. */
+  /**
+   * Run once a smooth scroll has settled, or right away for instant scrolls.
+   * Settled means the target stopped moving for two frames' worth of samples,
+   * not a fixed delay: smooth scrolls take longer on slow or busy devices.
+   * `scrollend` finishes early where supported; a cap keeps it bounded.
+   */
   private afterScroll;
   private template;
   private buildDefault;
@@ -145,8 +150,11 @@ interface CreateTourOptions extends Omit<ControllerOptions, 'tour' | 'renderer'>
  */
 export declare class DomTourController extends TourController {
   private readonly cleanups;
+  private readonly followRoutes;
   constructor(tour: Tour, options?: CreateTourOptions);
+  start(at?: number | string): Promise<void>;
   destroy(): Promise<void>;
+  private listenToRoutes;
 }
 /** Create a browser-ready tour. Call `.start()` or `.resume()` on the result. */
 export declare function createTour(tour: Tour, options?: CreateTourOptions): DomTourController;

package/dist/index.js

@@ -480,7 +480,9 @@ const STYLES = `
   --docent-width: 320px;
   --docent-overlay: #000;
   --docent-overlay-opacity: 0.55;
-  --docent-duration: 250ms;
+  --docent-duration: 220ms;
+  /* Fast start, gentle stop: movement begins the moment you click. */
+  --docent-easing: cubic-bezier(0.2, 0.8, 0.2, 1);
   position: fixed;
   inset: 0;
   z-index: var(--docent-z, 2147483000);
@@ -504,7 +506,7 @@ const STYLES = `
   background: var(--docent-overlay);
   opacity: var(--docent-overlay-opacity);
   pointer-events: auto;
-  transition: clip-path var(--docent-duration) ease;
+  transition: clip-path var(--docent-duration) var(--docent-easing);
 }
 .blocker {
   position: absolute;
@@ -524,9 +526,12 @@ const STYLES = `
   padding: 16px;
   pointer-events: auto;
   outline: none;
-  transition: transform var(--docent-duration) ease, opacity var(--docent-duration) ease;
+  transition: transform var(--docent-duration) var(--docent-easing), opacity var(--docent-duration) var(--docent-easing);
 }
 .popover[data-entering] { opacity: 0; transition: none; }
+/* Between steps the popover slides; only its content cross-fades, briefly. */
+.popover[data-moving] > * { animation: docent-swap 160ms ease-out; }
+@keyframes docent-swap { from { opacity: 0; } to { opacity: 1; } }
 .popover.headless {
   width: auto;
   max-width: none;
@@ -598,6 +603,7 @@ const STYLES = `
 .button:focus-visible, .close:focus-visible { outline: 2px solid var(--docent-accent); outline-offset: 2px; }
 @media (prefers-reduced-motion: reduce) {
   .overlay, .popover { transition: none; }
+  .popover[data-moving] > * { animation: none; }
 }
 `;
 //#endregion
@@ -754,6 +760,7 @@ var DomRenderer = class {
 	show(ctx) {
 		const firstStep = !this.host;
 		const host = this.mount();
+		const from = this.popover?.style.transform || null;
 		this.teardownStep();
 		this.ctx = ctx;
 		this.target = ctx.step.target === void 0 ? null : resolveTarget(ctx.step.target, this.doc);
@@ -761,12 +768,15 @@ var DomRenderer = class {
 		applyTheme(host, mergeThemes(this.options.theme, template?.theme, ctx.tour.options?.theme));
 		this.setTemplateCss(template?.css);
 		const initialFocus = this.options.headless ? this.buildHeadless(ctx, host, this.options.headless) : this.buildDefault(ctx, host, template);
-		this.popover?.setAttribute("data-entering", "");
+		if (this.popover && from) {
+			this.popover.style.transform = from;
+			this.popover.setAttribute("data-moving", "");
+		} else this.popover?.setAttribute("data-entering", "");
 		if (this.target) {
 			const smooth = this.scrollIntoView(this.target, ctx.step);
 			if (this.options.avoidOcclusion !== false) {
 				const target = this.target;
-				this.afterScroll(smooth, () => {
+				this.afterScroll(smooth, target, () => {
 					if (this.target === target && uncover(target, host, this.viewport())) this.update();
 				});
 			}
@@ -909,28 +919,41 @@ var DomRenderer = class {
 			behavior: "auto"
 		});
 	}
-	/** Run after a smooth scroll settles (scrollend, or a short fallback), or right away. */
-	afterScroll(smooth, fn) {
+	/**
+	* Run once a smooth scroll has settled, or right away for instant scrolls.
+	* Settled means the target stopped moving for two frames' worth of samples,
+	* not a fixed delay: smooth scrolls take longer on slow or busy devices.
+	* `scrollend` finishes early where supported; a cap keeps it bounded.
+	*/
+	afterScroll(smooth, target, fn) {
 		const win = this.doc.defaultView;
 		if (!smooth || !win) {
 			fn();
 			return;
 		}
 		let done = false;
-		const finish = () => {
-			if (done) return;
+		let lastTop = NaN;
+		let stableSamples = 0;
+		const stop = () => {
 			done = true;
 			win.removeEventListener("scrollend", finish);
-			clearTimeout(timer);
+			clearInterval(poll);
+			clearTimeout(cap);
+		};
+		const finish = () => {
+			if (done) return;
+			stop();
 			fn();
 		};
-		const timer = setTimeout(finish, 600);
+		const poll = setInterval(() => {
+			const top = target.getBoundingClientRect().top;
+			stableSamples = Math.abs(top - lastTop) < .5 ? stableSamples + 1 : 0;
+			lastTop = top;
+			if (stableSamples >= 2) finish();
+		}, 80);
+		const cap = setTimeout(finish, 3e3);
 		win.addEventListener("scrollend", finish, { once: true });
-		this.cleanups.push(() => {
-			done = true;
-			win.removeEventListener("scrollend", finish);
-			clearTimeout(timer);
-		});
+		this.cleanups.push(stop);
 	}
 	template(ctx) {
 		const name = ctx.tour.options?.template ?? this.options.template;
@@ -1095,6 +1118,9 @@ var DomRenderer = class {
 	}
 	onKeydown(e, ctx) {
 		const options = ctx.tour.options ?? {};
+		const path = typeof e.composedPath === "function" ? e.composedPath() : [];
+		const origin = path[0] ?? e.target;
+		if (path.some((n) => n instanceof Element && n.hasAttribute("data-docent-ignore-keys"))) return;
 		if (e.key === "Escape" && options.allowClose !== false) {
 			e.preventDefault();
 			ctx.actions.skip();
@@ -1105,7 +1131,7 @@ var DomRenderer = class {
 			return;
 		}
 		if (options.keyboard === false) return;
-		if (e.target instanceof HTMLElement && /^(INPUT|TEXTAREA|SELECT)$/.test(e.target.tagName)) return;
+		if (origin instanceof HTMLElement && (/^(INPUT|TEXTAREA|SELECT)$/.test(origin.tagName) || origin.isContentEditable)) return;
 		if (e.key === "ArrowRight" && ctx.step.buttons?.next !== false) {
 			e.preventDefault();
 			ctx.actions.next();
@@ -1200,6 +1226,7 @@ function createLocalStorage(storage) {
 */
 var DomTourController = class extends TourController {
 	cleanups = [];
+	followRoutes;
 	constructor(tour, options = {}) {
 		const { renderer: rendererOptions, followRoutes, ...rest } = options;
 		const renderer = new DomRenderer(rendererOptions);
@@ -1209,24 +1236,30 @@ var DomTourController = class extends TourController {
 			renderer,
 			storage: rest.storage ?? createLocalStorage()
 		});
-		if (followRoutes !== false && typeof window !== "undefined") {
-			const onChange = () => void this.routeChanged();
-			for (const type of ["popstate", "hashchange"]) {
-				window.addEventListener(type, onChange);
-				this.cleanups.push(() => window.removeEventListener(type, onChange));
-			}
-			const nav = window.navigation;
-			if (nav) {
-				nav.addEventListener("navigatesuccess", onChange);
-				this.cleanups.push(() => nav.removeEventListener("navigatesuccess", onChange));
-			}
-		}
+		this.followRoutes = followRoutes !== false;
+	}
+	async start(at) {
+		this.listenToRoutes();
+		return super.start(at);
 	}
 	async destroy() {
 		for (const c of this.cleanups) c();
 		this.cleanups.length = 0;
 		await super.destroy();
 	}
+	listenToRoutes() {
+		if (!this.followRoutes || this.cleanups.length > 0 || typeof window === "undefined") return;
+		const onChange = () => void this.routeChanged();
+		for (const type of ["popstate", "hashchange"]) {
+			window.addEventListener(type, onChange);
+			this.cleanups.push(() => window.removeEventListener(type, onChange));
+		}
+		const nav = window.navigation;
+		if (nav) {
+			nav.addEventListener("navigatesuccess", onChange);
+			this.cleanups.push(() => nav.removeEventListener("navigatesuccess", onChange));
+		}
+	}
 };
 /** Create a browser-ready tour. Call `.start()` or `.resume()` on the result. */
 function createTour(tour, options) {