@leavepulse/ui 0.55.0 → 0.57.0

package/dist/components/LpTour.vue.d.ts

@@ -0,0 +1,98 @@
+export interface TourContext {
+    /** Undo something when this step is left, in either direction (close the menu it opened). */
+    onLeave(cleanup: () => void): void;
+    /** Undo something when the tour ends, for what several steps share (a dialog they all live in). */
+    onEnd(cleanup: () => void): void;
+}
+export interface TourStep {
+    /**
+     * What to point at: a `v-hint` id, a CSS selector, an element or a getter.
+     * Left out, the step is a centred card with nothing highlighted (an intro).
+     * A target that never appears is skipped, so a step for a control the user
+     * cannot see costs nothing.
+     */
+    target?: string | Element | (() => Element | null);
+    title: string;
+    text?: string;
+    /** A shortcut for the same action, shown as keycaps ("Ctrl+K"). */
+    keys?: string;
+    side?: "top" | "right" | "bottom" | "left";
+    /**
+     * Ask the user to press the highlighted control themselves; the tour moves
+     * on when they do. Doing it beats reading about it.
+     */
+    try?: boolean;
+    /** With `try`, a "do it for me" button runs this instead. */
+    perform?: () => void | Promise<void>;
+    /** Runs before the step shows: open the dialog or tab its target lives in. */
+    enter?: (context: TourContext) => void | Promise<void>;
+}
+declare const _default: typeof __VLS_export;
+export default _default;
+declare const __VLS_export: __VLS_WithSlots<import("vue").DefineComponent<{
+    steps: TourStep[];
+    /** Room around the target inside the lit hole, px. */
+    padding?: number;
+    labels?: Partial<{
+        next: string;
+        back: string;
+        done: string;
+        close: string;
+        progress: string;
+        perform: string;
+        tryIt: string;
+    }>;
+} & {
+    open?: boolean;
+    step?: number;
+}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    "update:open": (value: boolean) => any;
+    "update:step": (value: number) => any;
+} & {
+    dismiss: (index: number) => any;
+    finish: () => any;
+}, string, import("vue").PublicProps, Readonly<{
+    steps: TourStep[];
+    /** Room around the target inside the lit hole, px. */
+    padding?: number;
+    labels?: Partial<{
+        next: string;
+        back: string;
+        done: string;
+        close: string;
+        progress: string;
+        perform: string;
+        tryIt: string;
+    }>;
+} & {
+    open?: boolean;
+    step?: number;
+}> & Readonly<{
+    "onUpdate:open"?: ((value: boolean) => any) | undefined;
+    onDismiss?: ((index: number) => any) | undefined;
+    "onUpdate:step"?: ((value: number) => any) | undefined;
+    onFinish?: (() => any) | undefined;
+}>, {
+    padding: number;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>, {
+    card?: (props: {
+        step: TourStep | undefined;
+        index: number;
+        next: () => void;
+        back: () => void;
+        dismiss: () => void;
+    }) => any;
+} & {
+    card?: (props: {
+        step: TourStep | undefined;
+        index: number;
+        next: () => void;
+        back: () => void;
+        dismiss: () => void;
+    }) => any;
+}>;
+type __VLS_WithSlots<T, S> = T & {
+    new (): {
+        $slots: S;
+    };
+};

package/dist/components/LpTour.vue.js

@@ -0,0 +1,4 @@
+import { _ as _sfc_main } from "../chunks/LpTour-C1TC2GyY.js";
+export {
+  _sfc_main as default
+};

package/dist/components/LpUptimeBar.vue.js

@@ -1,4 +1,4 @@
-import { _ as _sfc_main } from "../chunks/LpUptimeBar-ugcv25xj.js";
+import { _ as _sfc_main } from "../chunks/LpUptimeBar-B4ltCfno.js";
 export {
   _sfc_main as default
 };

package/dist/components/TourCard.vue.d.ts

@@ -0,0 +1,28 @@
+import type { TourStep } from "./LpTour.vue";
+type __VLS_Props = {
+    step: TourStep | undefined;
+    index: number;
+    last: boolean;
+    progress: string;
+    labels: {
+        next: string;
+        back: string;
+        done: string;
+        close: string;
+        perform: string;
+        tryIt: string;
+    };
+};
+declare const __VLS_export: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {} & {
+    next: () => any;
+    dismiss: () => any;
+    back: () => any;
+    perform: () => any;
+}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{
+    onNext?: (() => any) | undefined;
+    onDismiss?: (() => any) | undefined;
+    onBack?: (() => any) | undefined;
+    onPerform?: (() => any) | undefined;
+}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;

package/dist/components/TourCard.vue.js

@@ -0,0 +1,4 @@
+import { _ as _sfc_main } from "../chunks/TourCard-BQS3ztqj.js";
+export {
+  _sfc_main as default
+};

package/dist/components/tour.d.ts

@@ -0,0 +1,21 @@
+import type { Box } from "../composables/spatialNav";
+type Size = {
+    width: number;
+    height: number;
+};
+/** The hole around a target: padded, then clipped to the viewport so a tall
+ * target never pushes the dim panels off-screen. */
+export declare function holeOf(target: Box, padding: number, viewport: Size): Box;
+/** The four dim panels around a hole: top, bottom, left, right. */
+export declare function panelsAround(hole: Box, viewport: Size): Box[];
+/**
+ * Open the context menu of an element as a right-click would, at its centre.
+ * Lets a tour step show a row's menu without the user hunting for it; the menu
+ * itself is whatever the app already wires to that element.
+ *
+ * Returns the way to close it again: a press outside the menu, which every
+ * dismissable layer honours. Not Escape — that key also closes whatever is on
+ * top, a tour included, and would end the walk instead of the menu.
+ */
+export declare function openContextMenu(el: Element): () => void;
+export {};

package/dist/components/tour.js

@@ -0,0 +1,38 @@
+function holeOf(target, padding, viewport) {
+  const x = Math.max(0, target.x - padding);
+  const y = Math.max(0, target.y - padding);
+  const right = Math.min(viewport.width, target.x + target.width + padding);
+  const bottom = Math.min(viewport.height, target.y + target.height + padding);
+  return { x, y, width: Math.max(0, right - x), height: Math.max(0, bottom - y) };
+}
+function panelsAround(hole, viewport) {
+  const bottom = hole.y + hole.height;
+  return [
+    { x: 0, y: 0, width: viewport.width, height: hole.y },
+    { x: 0, y: bottom, width: viewport.width, height: Math.max(0, viewport.height - bottom) },
+    { x: 0, y: hole.y, width: hole.x, height: hole.height },
+    { x: hole.x + hole.width, y: hole.y, width: Math.max(0, viewport.width - hole.x - hole.width), height: hole.height }
+  ];
+}
+function openContextMenu(el) {
+  const box = el.getBoundingClientRect();
+  el.dispatchEvent(
+    new MouseEvent("contextmenu", {
+      bubbles: true,
+      cancelable: true,
+      button: 2,
+      clientX: box.left + box.width / 2,
+      clientY: box.top + box.height / 2
+    })
+  );
+  return () => {
+    const outside = { bubbles: true, cancelable: true, clientX: 0, clientY: 0 };
+    document.body.dispatchEvent(new PointerEvent("pointerdown", outside));
+    document.body.dispatchEvent(new PointerEvent("pointerup", outside));
+  };
+}
+export {
+  holeOf,
+  openContextMenu,
+  panelsAround
+};

package/dist/composables/scroll.d.ts

@@ -0,0 +1,17 @@
+export interface ScrollParentOptions {
+    /** Which overflow counts: vertical (default), horizontal, or either. */
+    axis?: "y" | "x" | "both";
+    /** Start the search at the element itself rather than its parent. */
+    self?: boolean;
+}
+/** The nearest ancestor that scrolls along `axis` and has something to scroll, or null. */
+export declare function scrollParent(el: Element | null | undefined, { axis, self }?: ScrollParentOptions): HTMLElement | null;
+export interface ScrollToElementOptions {
+    /** `nearest` scrolls only when the element is out of view. */
+    block?: "nearest" | "center" | "start";
+    behavior?: ScrollBehavior;
+    /** Room kept between the element and the scroller's edge. */
+    margin?: number;
+}
+/** Scroll the nearest scroller, and only it, so that `el` is in view. */
+export declare function scrollToElement(el: Element | null | undefined, { block, behavior, margin }?: ScrollToElementOptions): void;

package/dist/composables/scroll.js

@@ -0,0 +1,29 @@
+const SCROLLS = /(auto|scroll|overlay)/;
+function scrollParent(el, { axis = "y", self = false } = {}) {
+  for (let node = self ? el : el?.parentElement; node; node = node.parentElement) {
+    if (node === document.body || node === document.documentElement) return null;
+    const style = getComputedStyle(node);
+    const y = axis !== "x" && SCROLLS.test(style.overflowY) && node.scrollHeight > node.clientHeight;
+    const x = axis !== "y" && SCROLLS.test(style.overflowX) && node.scrollWidth > node.clientWidth;
+    if (y || x) return node;
+  }
+  return null;
+}
+function scrollToElement(el, { block = "nearest", behavior = "auto", margin = 0 } = {}) {
+  if (!el) return;
+  const box = scrollParent(el) ?? document.scrollingElement;
+  if (!box) return;
+  const outer = box === document.scrollingElement ? new DOMRect(0, 0, window.innerWidth, window.innerHeight) : box.getBoundingClientRect();
+  const inner = el.getBoundingClientRect();
+  const top = inner.top - outer.top + box.scrollTop;
+  let target = box.scrollTop;
+  if (block === "start") target = top - margin;
+  else if (block === "center") target = top - (box.clientHeight - inner.height) / 2;
+  else if (inner.top < outer.top + margin) target = top - margin;
+  else if (inner.bottom > outer.bottom - margin) target = top - box.clientHeight + inner.height + margin;
+  if (target !== box.scrollTop) box.scrollTo({ top: target, behavior });
+}
+export {
+  scrollParent,
+  scrollToElement
+};

package/dist/composables/useGamepadNav.js

@@ -1,5 +1,6 @@
 import { ref, onMounted, onBeforeUnmount, toValue } from "vue";
 import { focusableIn, nextInDirection } from "./spatialNav.js";
+import { scrollParent } from "./scroll.js";
 const BUTTON = { a: 0, b: 1, lb: 4, rb: 5, start: 9, up: 12, down: 13, left: 14, right: 15 };
 const STICK_THRESHOLD = 0.55;
 const REPEAT_DELAY_MS = 380;
@@ -76,13 +77,7 @@ function useGamepadNav(options = {}) {
     }
   }
   function scrollBy(dx, dy) {
-    let element = document.activeElement;
-    while (element && element !== document.body) {
-      const style = getComputedStyle(element);
-      if (/(auto|scroll)/.test(style.overflowY + style.overflowX) && element.scrollHeight > element.clientHeight) break;
-      element = element.parentElement;
-    }
-    (element && element !== document.body ? element : document.scrollingElement)?.scrollBy(dx, dy);
+    (scrollParent(document.activeElement, { axis: "both", self: true }) ?? document.scrollingElement)?.scrollBy(dx, dy);
   }
   function poll(now) {
     frame = requestAnimationFrame(poll);

package/dist/composables/useHints.d.ts

@@ -0,0 +1,18 @@
+import { type Directive } from "vue";
+export type HintEvent = "seen" | "used" | "hover";
+type Listener = (id: string, el: HTMLElement) => void;
+/** `v-hint="'page.feature'"` on the element that represents a feature. */
+export declare const vHint: Directive<HTMLElement, string | null | undefined>;
+export declare const hints: {
+    /** Ids of everything hinted that is in the DOM now. Reactive. */
+    ids(): string[];
+    /** Whether an element with this id is in the DOM. Reactive. */
+    present(id: string): boolean;
+    /** The first connected element with this id that has a box, or null. */
+    element(id: string): HTMLElement | null;
+    /** Subscribe to a signal; returns the unsubscribe. */
+    on(event: HintEvent, listener: Listener): () => void;
+    /** Report use that is not a click on the element. */
+    use(id: string): void;
+};
+export {};

package/dist/composables/useHints.js

@@ -0,0 +1,120 @@
+import { shallowReactive } from "vue";
+const SEEN_MS = 800;
+const SEEN_RATIO = 0.5;
+const mounted = shallowReactive(/* @__PURE__ */ new Map());
+const listeners = { seen: /* @__PURE__ */ new Set(), used: /* @__PURE__ */ new Set(), hover: /* @__PURE__ */ new Set() };
+const idOf = /* @__PURE__ */ new WeakMap();
+const timers = /* @__PURE__ */ new WeakMap();
+const seenOnce = /* @__PURE__ */ new WeakSet();
+function emit(event, id, el) {
+  for (const listener of listeners[event]) listener(id, el);
+}
+let observer = null;
+function watchSight(el) {
+  if (typeof IntersectionObserver === "undefined") {
+    seenOnce.add(el);
+    emit("seen", idOf.get(el), el);
+    return;
+  }
+  observer ??= new IntersectionObserver(
+    (entries) => {
+      for (const entry of entries) {
+        const target = entry.target;
+        const id = idOf.get(target);
+        if (!id || seenOnce.has(target)) continue;
+        clearTimeout(timers.get(target));
+        if (entry.intersectionRatio >= SEEN_RATIO) {
+          timers.set(
+            target,
+            setTimeout(() => {
+              seenOnce.add(target);
+              observer?.unobserve(target);
+              emit("seen", id, target);
+            }, SEEN_MS)
+          );
+        }
+      }
+    },
+    { threshold: [0, SEEN_RATIO] }
+  );
+  observer.observe(el);
+}
+function onClick(event) {
+  const el = event.currentTarget;
+  const id = idOf.get(el);
+  if (id) emit("used", id, el);
+}
+function onHover(event) {
+  const el = event.currentTarget;
+  const id = idOf.get(el);
+  if (id) emit("hover", id, el);
+}
+function attach(el, id) {
+  idOf.set(el, id);
+  el.dataset.hint = id;
+  const set = mounted.get(id) ?? /* @__PURE__ */ new Set();
+  set.add(el);
+  mounted.set(id, new Set(set));
+  el.addEventListener("click", onClick, { capture: true });
+  el.addEventListener("pointerenter", onHover);
+  el.addEventListener("focusin", onHover);
+  watchSight(el);
+}
+function detach(el) {
+  const id = idOf.get(el);
+  if (!id) return;
+  clearTimeout(timers.get(el));
+  observer?.unobserve(el);
+  el.removeEventListener("click", onClick, { capture: true });
+  el.removeEventListener("pointerenter", onHover);
+  el.removeEventListener("focusin", onHover);
+  const set = new Set(mounted.get(id));
+  set.delete(el);
+  if (set.size) mounted.set(id, set);
+  else mounted.delete(id);
+  idOf.delete(el);
+}
+const vHint = {
+  mounted(el, binding) {
+    if (binding.value) attach(el, binding.value);
+  },
+  updated(el, binding) {
+    if (binding.value === idOf.get(el)) return;
+    detach(el);
+    if (binding.value) attach(el, binding.value);
+  },
+  beforeUnmount(el) {
+    detach(el);
+  }
+};
+const hints = {
+  /** Ids of everything hinted that is in the DOM now. Reactive. */
+  ids() {
+    return [...mounted.keys()];
+  },
+  /** Whether an element with this id is in the DOM. Reactive. */
+  present(id) {
+    return mounted.has(id);
+  },
+  /** The first connected element with this id that has a box, or null. */
+  element(id) {
+    for (const el of mounted.get(id) ?? []) {
+      if (el.isConnected && el.getClientRects().length) return el;
+    }
+    return null;
+  },
+  /** Subscribe to a signal; returns the unsubscribe. */
+  on(event, listener) {
+    listeners[event].add(listener);
+    return () => listeners[event].delete(listener);
+  },
+  /** Report use that is not a click on the element. */
+  use(id) {
+    const el = hints.element(id);
+    for (const listener of listeners.used) listener(id, el ?? document.body);
+  }
+};
+export {
+  hints,
+  vHint
+};

package/dist/composables/useMediaQuery.d.ts

@@ -0,0 +1,2 @@
+import { type Ref } from "vue";
+export declare function useMediaQuery(query: string): Ref<boolean>;

package/dist/composables/useMediaQuery.js

@@ -0,0 +1,18 @@
+import { ref, onMounted, onBeforeUnmount } from "vue";
+function useMediaQuery(query) {
+  const matches = ref(false);
+  let list;
+  const update = () => {
+    matches.value = !!list?.matches;
+  };
+  onMounted(() => {
+    list = window.matchMedia?.(query);
+    update();
+    list?.addEventListener("change", update);
+  });
+  onBeforeUnmount(() => list?.removeEventListener("change", update));
+  return matches;
+}
+export {
+  useMediaQuery
+};

package/dist/composables/usePaintSelect.js

@@ -1,16 +1,10 @@
 import { ref, toValue, onMounted, onBeforeUnmount, readonly } from "vue";
 import { useHotkeys } from "./useHotkeys.js";
+import { scrollParent } from "./scroll.js";
 const HOLD_MS = 320;
 const SLOP_PX = 8;
 const EDGE_PX = 40;
 const SCROLL_STEP = 14;
-function scrollParent(el) {
-  for (let node = el?.parentElement; node; node = node.parentElement) {
-    const { overflowY } = getComputedStyle(node);
-    if ((overflowY === "auto" || overflowY === "scroll") && node.scrollHeight > node.clientHeight) return node;
-  }
-  return null;
-}
 function usePaintSelect(options) {
   const resolve = options.resolve ?? ((raw) => raw);
   let stroke = null;

package/dist/index.d.ts

@@ -157,6 +157,11 @@ export { default as LpThemeSwitcher } from "./components/LpThemeSwitcher.vue";
 export { default as LpTilt } from "./components/LpTilt.vue";
 export { default as LpToaster } from "./components/LpToaster.vue";
 export { default as LpTooltip } from "./components/LpTooltip.vue";
+export { default as LpTour } from "./components/LpTour.vue";
+export type { TourContext, TourStep } from "./components/LpTour.vue";
+export { holeOf, openContextMenu, panelsAround } from "./components/tour";
+export { default as LpHintLayer } from "./components/LpHintLayer.vue";
+export type { HintNote } from "./components/LpHintLayer.vue";
 export { default as LpTooltipProvider } from "./components/LpTooltipProvider.vue";
 export { default as LpTopologyCanvas } from "./components/LpTopologyCanvas.vue";
 export type { CanvasViewport, EdgeCategory, EdgeObserved, TopologyEdge, TopologyLane, TopologyNode, } from "./components/LpTopologyCanvas.vue";
@@ -205,6 +210,11 @@ export type { FieldContext, FieldControlState } from "./composables/useField";
 export type { UseInputFilterOptions } from "./composables/useInputFilter";
 export { easeOut, easeTravel, easingToken, prefersReducedMotion } from "./composables/easing";
 export { useReveal } from "./composables/useReveal";
+export { hints, vHint } from "./composables/useHints";
+export type { HintEvent } from "./composables/useHints";
+export { scrollParent, scrollToElement } from "./composables/scroll";
+export type { ScrollParentOptions, ScrollToElementOptions } from "./composables/scroll";
+export { useMediaQuery } from "./composables/useMediaQuery";
 export type { UseReveal, UseRevealOptions } from "./composables/useReveal";
 export { useAsyncTask } from "./composables/useAsyncTask";
 export { useRovingFocus } from "./composables/useRovingFocus";