@leavepulse/ui 0.56.0 → 0.58.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-D7m9ZxNk.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/MenuTitle.vue.js

@@ -1,4 +1,4 @@
-import { _ as _sfc_main } from "../chunks/MenuTitle-J3ZDYjpV.js";
+import { _ as _sfc_main } from "../chunks/MenuTitle-DQP6hc2N.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-DCHOjr6e.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/useHintSystem.d.ts

@@ -0,0 +1,195 @@
+import { type ComputedRef } from "vue";
+import type { HintNote } from "../components/LpHintLayer.vue";
+import type { TourContext, TourStep } from "../components/LpTour.vue";
+export interface HintFeature {
+    page: string;
+    title: string;
+    text: string;
+    order?: number;
+    keys?: string;
+    try?: boolean;
+    side?: TourStep["side"];
+    /** Bump to announce a changed feature again: it reads as new to everyone. */
+    rev?: number;
+    /** Keeps its dot until explained, even after "not now". */
+    required?: boolean;
+    /**
+     * Rendered only in some states (data-dependent, behind a filter). Its first
+     * appearance is not news, so it is never marked new for merely showing up;
+     * a `rev` bump still announces it.
+     */
+    conditional?: boolean;
+    /** When the `v-hint` id is not the element to light (a column header, an opened menu). */
+    target?: () => Element | null;
+    enter?: (context: TourContext) => void | Promise<void>;
+}
+export interface HintPage {
+    title: string;
+    /**
+     * A localStorage key prefix that proves the user worked on this page before
+     * the system existed (a remembered table layout). Such a page is treated as
+     * known on first sight: no tour offer, no dots for what was always there.
+     */
+    known?: string;
+}
+export interface HintNews {
+    id: string;
+    date: string;
+    page: string;
+    text: string;
+    feature?: string;
+}
+export interface HintNudge {
+    id: string;
+    feature: string;
+    text: string;
+}
+export type HintLevel = "seen" | "explained" | "used";
+export interface HintRecord {
+    state: HintLevel;
+    dismissed: boolean;
+    count: number;
+    assigned?: boolean;
+    updatedAt: string;
+}
+export interface HintDelta {
+    key: string;
+    state?: HintLevel;
+    dismissed?: boolean;
+    add?: number;
+}
+export interface HintStorage {
+    load(): Promise<Record<string, HintRecord>> | Record<string, HintRecord>;
+    save(deltas: HintDelta[]): Promise<void> | void;
+    /** Last chance on page hide (sendBeacon); falls back to `save`. */
+    saveOnLeave?(deltas: HintDelta[]): void;
+}
+export interface HintTiming {
+    settle: number;
+    offerAgain: number;
+    offersMax: number;
+    freshLimit: number;
+    nudgeAgain: number;
+    flush: number;
+}
+export interface HintSystemOptions {
+    features: Record<string, HintFeature>;
+    pages?: Record<string, HintPage>;
+    news?: HintNews[];
+    storage?: HintStorage;
+    /** The current page id, read reactively (map your route to it). */
+    page: () => string;
+    sessionKey?: string;
+    timing?: Partial<HintTiming>;
+}
+export type HintOffer = {
+    kind: "tour" | "assigned";
+    page: string;
+} | {
+    kind: "news";
+    page: string;
+    items: HintNews[];
+} | {
+    kind: "nudge";
+    page: string;
+    nudge: HintNudge;
+};
+/** Records in localStorage: for anonymous sessions and apps without a server. */
+export declare function localHintStorage(key?: string): HintStorage;
+/** Record keys, for apps that read or assign records directly (a "who knows what" view). */
+export declare const hintKey: {
+    feature: (id: string, rev?: number) => string;
+    page: (page: string) => string;
+    news: (id: string) => string;
+    nudge: (id: string) => string;
+};
+export interface HintSummary {
+    tour: "done" | "assigned" | "declined" | "offered" | "never";
+    offers: number;
+    known: number;
+    total: number;
+    /** Titles of `required` features this person has not been shown. */
+    missing: string[];
+}
+/** What one person knows of a page, from their records: for a manager's view. */
+export declare function hintSummary(records: Map<string, Pick<HintRecord, "state" | "dismissed" | "count" | "assigned">>, features: Record<string, HintFeature>, page: string): HintSummary;
+export declare function createHintSystem(options: HintSystemOptions): {
+    state: {
+        records: Map<string, {
+            state: HintLevel;
+            dismissed: boolean;
+            count: number;
+            assigned?: boolean | undefined;
+            updatedAt: string;
+        }> & Omit<Map<string, HintRecord>, keyof Map<any, any>>;
+        loaded: boolean;
+        page: string;
+        tour: {
+            open: boolean;
+            step: number;
+            steps: {
+                target?: (string | Element | (() => Element | null)) | undefined;
+                title: string;
+                text?: string | undefined;
+                keys?: string | undefined;
+                side?: "top" | "right" | "bottom" | "left" | undefined;
+                try?: boolean | undefined;
+                perform?: (() => void | Promise<void>) | undefined;
+                enter?: ((context: TourContext) => void | Promise<void>) | undefined;
+            }[];
+            ids: string[];
+            page: string;
+        };
+        offer: {
+            kind: "tour" | "assigned";
+            page: string;
+        } | {
+            kind: "news";
+            page: string;
+            items: {
+                id: string;
+                date: string;
+                page: string;
+                text: string;
+                feature?: string | undefined;
+            }[];
+        } | {
+            kind: "nudge";
+            page: string;
+            nudge: {
+                id: string;
+                feature: string;
+                text: string;
+            };
+        } | null;
+        candidate: {
+            id: string;
+            feature: string;
+            text: string;
+            page: string;
+        } | null;
+        settledAt: number;
+        intent: boolean;
+    };
+    fresh: ComputedRef<string[]>;
+    notes: ComputedRef<Record<string, HintNote>>;
+    start: () => void;
+    stop: () => void;
+    hasTour: (page?: string) => boolean;
+    startTour: (page?: string, only?: string[]) => void;
+    load(): Promise<void>;
+    /** Ask for a nudge; it shows when the budget and the page allow. */
+    nudge(n: HintNudge): void;
+    /** The user navigated on purpose (palette, notification): do not interrupt this arrival. */
+    markIntent(): void;
+    unreadNews: (page?: string) => HintNews[];
+    readNews: (page: string) => void;
+    pageTitle: (page: string) => string;
+    readFresh(id: string): void;
+    tourShown(index: number): void;
+    tourEnded(finished: boolean): void;
+    answer(choice: "show" | "later" | "never"): void;
+};
+export type HintSystem = ReturnType<typeof createHintSystem>;
+export declare function provideHintSystem(system: HintSystem): void;
+export declare function useHintSystem(): HintSystem | null;