@leavepulse/ui 0.56.0 → 0.58.0

package/dist/composables/useHintSystem.js

@@ -0,0 +1,334 @@
+import { provide, reactive, computed, inject, watch } from "vue";
+import { anyModalOpen } from "../components/modalDepth.js";
+import { hints } from "./useHints.js";
+const RANK = { seen: 0, explained: 1, used: 2 };
+const DAY = 24 * 3600 * 1e3;
+const DEFAULT_TIMING = {
+  settle: 2500,
+  offerAgain: 3 * DAY,
+  offersMax: 2,
+  freshLimit: 3,
+  nudgeAgain: 7 * DAY,
+  flush: 2e3
+};
+function localHintStorage(key = "lp-hints") {
+  const read = () => {
+    try {
+      return JSON.parse(localStorage.getItem(key) || "{}");
+    } catch {
+      return {};
+    }
+  };
+  return {
+    load: read,
+    save(deltas) {
+      const all = read();
+      for (const d of deltas) all[d.key] = merge(all[d.key], d);
+      try {
+        localStorage.setItem(key, JSON.stringify(all));
+      } catch {
+        return;
+      }
+    }
+  };
+}
+function merge(record, delta) {
+  const base = record ?? { state: "seen", dismissed: false, count: 0, updatedAt: "" };
+  return {
+    ...base,
+    state: delta.state && RANK[delta.state] > RANK[base.state] ? delta.state : base.state,
+    dismissed: delta.dismissed ?? base.dismissed,
+    count: base.count + (delta.add ?? 0),
+    updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+const hintKey = {
+  feature: (id, rev = 1) => `f:${id}:${rev}`,
+  page: (page) => `t:${page}`,
+  news: (id) => `c:${id}`,
+  nudge: (id) => `n:${id}`
+};
+function hintSummary(records, features, page) {
+  const own = Object.entries(features).filter(([, f]) => f.page === page);
+  const knows = (id, f) => RANK[records.get(hintKey.feature(id, f.rev))?.state ?? "seen"] >= RANK.explained;
+  const tour = records.get(hintKey.page(page));
+  return {
+    tour: tour && RANK[tour.state] >= RANK.explained ? "done" : tour?.assigned ? "assigned" : tour?.dismissed ? "declined" : tour ? "offered" : "never",
+    offers: tour?.count ?? 0,
+    known: own.filter(([id, f]) => knows(id, f)).length,
+    total: own.length,
+    missing: own.filter(([id, f]) => f.required && !knows(id, f)).map(([, f]) => f.title)
+  };
+}
+function typing() {
+  const el = document.activeElement;
+  return el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement || el instanceof HTMLElement && el.isContentEditable;
+}
+function createHintSystem(options) {
+  const timing = { ...DEFAULT_TIMING, ...options.timing };
+  const features = options.features;
+  const pages = options.pages ?? {};
+  const news = options.news ?? [];
+  const storage = options.storage ?? localHintStorage();
+  const sessionKey = options.sessionKey ?? "lp-hints:interrupted";
+  const state = reactive({
+    records: /* @__PURE__ */ new Map(),
+    loaded: false,
+    page: "",
+    tour: { open: false, step: 0, steps: [], ids: [], page: "" },
+    offer: null,
+    candidate: null,
+    settledAt: 0,
+    intent: false
+  });
+  const pending = /* @__PURE__ */ new Map();
+  let flushTimer;
+  const featureKey = (id) => hintKey.feature(id, features[id]?.rev);
+  const pageKey = hintKey.page;
+  const newsKey = hintKey.news;
+  const nudgeKey = hintKey.nudge;
+  function interrupted() {
+    try {
+      return sessionStorage.getItem(sessionKey) === "1";
+    } catch {
+      return false;
+    }
+  }
+  function spend() {
+    try {
+      sessionStorage.setItem(sessionKey, "1");
+    } catch {
+      return;
+    }
+  }
+  async function flush() {
+    clearTimeout(flushTimer);
+    flushTimer = void 0;
+    if (!pending.size) return;
+    const deltas = [...pending.values()];
+    pending.clear();
+    try {
+      await storage.save(deltas);
+    } catch {
+      for (const d of deltas) if (!pending.has(d.key)) pending.set(d.key, d);
+    }
+  }
+  function flushOnLeave() {
+    if (!pending.size) return;
+    const deltas = [...pending.values()];
+    pending.clear();
+    if (storage.saveOnLeave) storage.saveOnLeave(deltas);
+    else void storage.save(deltas);
+  }
+  function record(key, delta) {
+    state.records.set(key, merge(state.records.get(key), delta));
+    const queued = pending.get(key);
+    pending.set(key, {
+      key,
+      state: delta.state ?? queued?.state,
+      dismissed: delta.dismissed ?? queued?.dismissed,
+      add: (queued?.add ?? 0) + (delta.add ?? 0)
+    });
+    flushTimer ??= setTimeout(() => void flush(), timing.flush);
+  }
+  const present = (page) => Object.keys(features).filter((id) => features[id].page === page && hints.present(id));
+  function knownBefore(page) {
+    const marker = pages[page]?.known;
+    if (!marker) return false;
+    try {
+      return Object.keys(localStorage).some((key) => key.startsWith(marker));
+    } catch {
+      return false;
+    }
+  }
+  function baseline(page) {
+    for (const id of present(page)) if (!state.records.has(featureKey(id))) record(featureKey(id), { state: "seen" });
+  }
+  const fresh = computed(() => {
+    const page = state.page;
+    if (!page || !state.loaded || state.tour.open || !state.records.has(pageKey(page))) return [];
+    return present(page).filter((id) => {
+      const f = features[id];
+      const rec = state.records.get(featureKey(id));
+      if (!rec) return !f.conditional || (f.rev ?? 1) > 1;
+      return !!f.required && RANK[rec.state] < RANK.explained && !rec.dismissed;
+    }).sort((a, b) => Number(!!features[b].required) - Number(!!features[a].required) || (features[a].order ?? 0) - (features[b].order ?? 0)).slice(0, timing.freshLimit);
+  });
+  const notes = computed(
+    () => Object.fromEntries(Object.entries(features).map(([id, f]) => [id, { title: f.title, text: f.text }]))
+  );
+  const hasTour = (page = state.page) => Object.values(features).some((f) => f.page === page);
+  function startTour(page = state.page, only) {
+    const entries = Object.entries(features).filter(([id, f]) => f.page === page && (!only || only.includes(id))).sort(([, a], [, b]) => (a.order ?? 0) - (b.order ?? 0));
+    if (!entries.length) return;
+    state.offer = null;
+    Object.assign(state.tour, {
+      open: true,
+      step: 0,
+      page,
+      ids: entries.map(([id]) => id),
+      steps: entries.map(([id, f]) => ({
+        target: f.target ?? id,
+        title: f.title,
+        text: f.text,
+        keys: f.keys,
+        try: f.try,
+        side: f.side,
+        enter: f.enter
+      }))
+    });
+  }
+  const unread = (page) => news.filter((n) => (!page || n.page === page) && !state.records.has(newsKey(n.id)) && (!page || !n.feature || hints.present(n.feature)));
+  function readNews(page) {
+    for (const n of unread(page)) record(newsKey(n.id), { state: "explained" });
+  }
+  function considerOffer() {
+    const page = state.page;
+    const ready = state.loaded && !state.tour.open && !state.offer && !anyModalOpen() && !typing() && Date.now() - state.settledAt > timing.settle;
+    if (!page || !ready) return;
+    const rec = state.records.get(pageKey(page));
+    if (rec?.assigned && RANK[rec.state] < RANK.explained && hasTour(page)) {
+      state.offer = { kind: "assigned", page };
+      return;
+    }
+    if (state.intent || interrupted()) return;
+    if (!rec && knownBefore(page)) {
+      record(pageKey(page), { state: "seen" });
+      baseline(page);
+    } else if (!rec || !rec.dismissed && RANK[rec.state] < RANK.explained && rec.count < timing.offersMax && Date.now() - Date.parse(rec.updatedAt || "0") > timing.offerAgain) {
+      if (!hasTour(page)) return;
+      spend();
+      if (!rec) {
+        record(pageKey(page), { state: "seen" });
+        baseline(page);
+        readNews(page);
+      }
+      state.offer = { kind: "tour", page };
+      return;
+    }
+    const items = unread(page);
+    if (items.length) {
+      spend();
+      state.offer = { kind: "news", page, items: items.slice(0, 3) };
+      return;
+    }
+    const n = state.candidate;
+    if (!n || n.page !== page) return;
+    const seen = state.records.get(nudgeKey(n.id));
+    if (seen?.dismissed || state.records.get(featureKey(n.feature))?.state === "used" || !hints.present(n.feature)) return;
+    if (seen && Date.now() - Date.parse(seen.updatedAt) < timing.nudgeAgain) return;
+    state.candidate = null;
+    spend();
+    record(nudgeKey(n.id), { add: 1 });
+    state.offer = { kind: "nudge", page, nudge: n };
+  }
+  let stops = [];
+  function start() {
+    if (stops.length) return;
+    const stopPage = watch(
+      options.page,
+      (page) => {
+        state.page = page;
+        state.settledAt = Date.now();
+        if (state.offer && state.offer.page !== page) state.offer = null;
+        if (state.candidate && state.candidate.page !== page) state.candidate = null;
+        setTimeout(() => state.intent = false, timing.settle * 2);
+      },
+      { immediate: true }
+    );
+    const poll = setInterval(() => {
+      try {
+        considerOffer();
+      } catch (error) {
+        console.warn("[hints] disabled after an error:", error);
+        stop();
+      }
+    }, 1e3);
+    window.addEventListener("pagehide", flushOnLeave);
+    stops = [
+      stopPage,
+      hints.on("used", (id) => {
+        if (features[id]) record(featureKey(id), { state: "used", add: 1 });
+      }),
+      () => clearInterval(poll),
+      () => window.removeEventListener("pagehide", flushOnLeave)
+    ];
+  }
+  function stop() {
+    for (const s of stops.splice(0)) s();
+    flushOnLeave();
+  }
+  return {
+    state,
+    fresh,
+    notes,
+    start,
+    stop,
+    hasTour,
+    startTour,
+    async load() {
+      state.records.clear();
+      try {
+        for (const [key, rec] of Object.entries(await storage.load())) state.records.set(key, rec);
+        state.loaded = true;
+      } catch {
+        state.loaded = false;
+      }
+    },
+    /** Ask for a nudge; it shows when the budget and the page allow. */
+    nudge(n) {
+      state.candidate = { ...n, page: state.page };
+    },
+    /** The user navigated on purpose (palette, notification): do not interrupt this arrival. */
+    markIntent() {
+      state.intent = true;
+    },
+    unreadNews: (page) => unread(page),
+    readNews,
+    pageTitle: (page) => pages[page]?.title ?? page,
+    readFresh(id) {
+      record(featureKey(id), { state: "explained" });
+    },
+    tourShown(index) {
+      const id = state.tour.ids[index];
+      if (id) record(featureKey(id), { state: "explained" });
+    },
+    tourEnded(finished) {
+      record(pageKey(state.tour.page), finished ? { state: "explained" } : { add: 1 });
+      baseline(state.tour.page);
+    },
+    answer(choice) {
+      const offer = state.offer;
+      state.offer = null;
+      if (!offer) return;
+      if (offer.kind === "news") {
+        const ids = offer.items.map((n) => n.feature).filter((id) => !!id);
+        readNews(offer.page);
+        if (choice === "show" && ids.length) startTour(offer.page, ids);
+      } else if (offer.kind === "nudge") {
+        if (choice === "show") startTour(features[offer.nudge.feature].page, [offer.nudge.feature]);
+        else record(nudgeKey(offer.nudge.id), { dismissed: true });
+      } else if (choice === "show") {
+        startTour(offer.page);
+      } else {
+        record(pageKey(offer.page), { add: 1, dismissed: choice === "never" });
+        baseline(offer.page);
+      }
+    }
+  };
+}
+const HINT_SYSTEM = /* @__PURE__ */ Symbol.for("lp-hint-system");
+function provideHintSystem(system) {
+  provide(HINT_SYSTEM, system);
+}
+function useHintSystem() {
+  return inject(HINT_SYSTEM, null);
+}
+export {
+  createHintSystem,
+  hintKey,
+  hintSummary,
+  localHintStorage,
+  provideHintSystem,
+  useHintSystem
+};

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/icons-all.js

@@ -1,3 +1,3 @@
 import lucide from "@iconify-json/lucide/icons.json";
-import { a as registerIconCollection } from "./chunks/icons-CkA0njzm.js";
+import { a as registerIconCollection } from "./chunks/icons-QqBscG5I.js";
 registerIconCollection(lucide);

package/dist/index.d.ts

@@ -157,6 +157,14 @@ 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 { default as LpHints } from "./components/LpHints.vue";
+export { createHintSystem, hintKey, hintSummary, localHintStorage, provideHintSystem, useHintSystem } from "./composables/useHintSystem";
+export type { HintDelta, HintFeature, HintLevel, HintNews, HintNudge, HintOffer, HintPage, HintRecord, HintStorage, HintSummary, HintSystem, HintSystemOptions, HintTiming, } from "./composables/useHintSystem";
+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 +213,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";