@arbidocs/blocks 0.5.106 → 0.5.107

package/dist/chunk-NFK2SEUD.js

@@ -0,0 +1,577 @@
+"use client";
+import { useHost } from './chunk-QG6MRLZG.js';
+import { createElement, useEffect, useSyncExternalStore } from 'react';
+import { MousePointerClick } from 'lucide-react';
+import { notify } from '@arbidocs/react/shell';
+import { cn } from '@arbidocs/react/ui';
+import { jsxs, jsx } from 'react/jsx-runtime';
+
+// src/tips/registry.ts
+var TIP_MAX_CHARS = 80;
+var TIP_CTA_LABEL_MAX_CHARS = 24;
+function createTipsRegistry(config) {
+  const { tips, everywhere, hiddenLabel = "Hidden (off)" } = config;
+  let content = config.content;
+  const listeners = /* @__PURE__ */ new Set();
+  const effective = (tip) => {
+    const o = content.overrides?.[tip.code];
+    if (!o) return { tip, hidden: false };
+    return {
+      tip: {
+        ...tip,
+        message: o.message ?? tip.message,
+        cta: o.cta === null ? void 0 : o.cta ?? tip.cta,
+        context: o.context ?? tip.context
+      },
+      hidden: o.hidden === true
+    };
+  };
+  const custom = () => content.custom ?? [];
+  const applies = (tipContext, context) => tipContext === context || tipContext === everywhere;
+  const placements = [
+    ...config.placements,
+    { value: "hidden", label: hiddenLabel }
+  ];
+  return {
+    select: (context, state) => {
+      const builtins = tips.map(effective).filter(
+        ({ tip, hidden }) => !hidden && applies(tip.context, context) && (!tip.when || tip.when(state))
+      ).map(({ tip }) => tip);
+      const authored = custom().filter((t) => t.hidden !== true && applies(t.context, context));
+      return [...builtins, ...authored].sort(
+        (a, b) => (b.priority ?? 0) - (a.priority ?? 0)
+      );
+    },
+    editorTips: () => [
+      ...tips.map((t) => {
+        const e = effective(t);
+        return { tip: e.tip, isCustom: false, isHidden: e.hidden };
+      }),
+      ...custom().map((t) => ({ tip: t, isCustom: true, isHidden: t.hidden === true }))
+    ],
+    getContent: () => content,
+    setContent: (next) => {
+      content = next;
+      listeners.forEach((listener) => listener());
+    },
+    subscribe: (listener) => {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    everywhere,
+    placements,
+    placementLabel: (p) => placements.find((o) => o.value === p)?.label ?? p
+  };
+}
+
+// src/guided/cursor.ts
+var GLIDE_MS = 580;
+var SCROLL_SETTLE_MS = 180;
+var DEFAULT_WAIT_MS = 1200;
+var PAINT_MS = 60;
+var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+var GuidedCursorController = class {
+  /** Glide duration (ms) — exported so the component's CSS transition matches. */
+  glideMs = GLIDE_MS;
+  snap = { visible: false, x: -100, y: -100 };
+  listeners = /* @__PURE__ */ new Set();
+  rippleListeners = /* @__PURE__ */ new Set();
+  // The user's real pointer, so a run begins where their eye already is (they
+  // just clicked "Show me"). Defaults to the lower-left, near the sidebar tips.
+  lastPointer = {
+    x: typeof window !== "undefined" ? 120 : 0,
+    y: typeof window !== "undefined" ? window.innerHeight - 60 : 0
+  };
+  constructor() {
+    if (typeof window !== "undefined") {
+      const track = (e) => {
+        this.lastPointer = { x: e.clientX, y: e.clientY };
+      };
+      window.addEventListener("pointermove", track, { passive: true });
+      window.addEventListener("pointerdown", track, { passive: true });
+    }
+  }
+  // external-store contract (useSyncExternalStore). getSnapshot returns a stable
+  // reference between changes, so React only re-renders on real moves.
+  subscribe = (cb) => {
+    this.listeners.add(cb);
+    return () => this.listeners.delete(cb);
+  };
+  getSnapshot = () => this.snap;
+  onRipple = (cb) => {
+    this.rippleListeners.add(cb);
+    return () => this.rippleListeners.delete(cb);
+  };
+  commit(next) {
+    this.snap = { ...this.snap, ...next };
+    this.listeners.forEach((l) => l());
+  }
+  prefersReducedMotion() {
+    return typeof window !== "undefined" && !!window.matchMedia?.("(prefers-reduced-motion: reduce)").matches;
+  }
+  show() {
+    if (this.snap.visible) return;
+    this.snap = { visible: true, x: this.lastPointer.x, y: this.lastPointer.y };
+    this.listeners.forEach((l) => l());
+  }
+  hide() {
+    if (this.snap.visible) this.commit({ visible: false });
+  }
+  moveTo(x, y) {
+    this.commit({ x, y });
+  }
+  /** Emit a click ripple at the cursor's current position. */
+  ripple() {
+    const { x, y } = this.snap;
+    this.rippleListeners.forEach((l) => l(x, y));
+  }
+  /** Resolve a selector to an element, briefly polling since the target may only
+   *  appear after a prior step navigates / opens a panel. */
+  async resolve(target, waitMs) {
+    if (typeof target !== "string") return target;
+    const deadline = Date.now() + waitMs;
+    let found = document.querySelector(target);
+    while (!found && Date.now() < deadline) {
+      await sleep(50);
+      found = document.querySelector(target);
+    }
+    return found;
+  }
+  /**
+   * Glide the cursor to the centre of `target` (a CSS selector or an element),
+   * scrolling it into view first. Resolves once the glide is done, so callers
+   * can `await` it before performing the action. Returns false if the target
+   * can't be found (after briefly waiting for it to appear).
+   */
+  async glideTo(target, opts) {
+    const el = await this.resolve(target, opts?.waitMs ?? DEFAULT_WAIT_MS);
+    if (!el) return false;
+    const reduced = this.prefersReducedMotion();
+    el.scrollIntoView({ block: "center", inline: "center", behavior: reduced ? "auto" : "smooth" });
+    await sleep(reduced ? 0 : SCROLL_SETTLE_MS);
+    const rect = el.getBoundingClientRect();
+    const x = rect.left + rect.width / 2;
+    const y = rect.top + rect.height / 2;
+    this.show();
+    if (!reduced) await sleep(PAINT_MS);
+    this.moveTo(x, y);
+    await sleep(reduced ? 0 : opts?.durationMs ?? GLIDE_MS);
+    return true;
+  }
+};
+var guidedCursor = new GuidedCursorController();
+var mounted = { consent: 0, cursor: 0 };
+function useMountedSurface(surface) {
+  useEffect(() => {
+    mounted[surface] += 1;
+    return () => {
+      mounted[surface] -= 1;
+    };
+  }, [surface]);
+}
+var isSurfaceMounted = (surface) => mounted[surface] > 0;
+var REMOTE_CONTROL_SURFACE = "data-remote-control-surface";
+var SENSITIVE_INPUT = "data-sensitive-input";
+
+// src/guided/runner.ts
+var guidedStepIcon = createElement(MousePointerClick, { className: "h-4 w-4" });
+var DEFAULT_PAUSE_MS = 900;
+var DWELL_MS = 280;
+var MAX_REMOTE_WAIT_MS = 5e3;
+var SECRET_AUTOCOMPLETE = /* @__PURE__ */ new Set(["current-password", "new-password", "one-time-code"]);
+var activeRun = null;
+var activeListeners = /* @__PURE__ */ new Set();
+var setActiveRun = (id) => {
+  if (activeRun === id) return;
+  activeRun = id;
+  activeListeners.forEach((listener) => listener());
+};
+var subscribeActive = (listener) => {
+  activeListeners.add(listener);
+  return () => {
+    activeListeners.delete(listener);
+  };
+};
+var getActiveRun = () => activeRun;
+var useActiveGuidedRun = () => useSyncExternalStore(subscribeActive, getActiveRun, getActiveRun);
+var runToken = 0;
+var sleep2 = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function clickElement(el) {
+  const rect = el.getBoundingClientRect();
+  const base = {
+    bubbles: true,
+    cancelable: true,
+    clientX: rect.left + rect.width / 2,
+    clientY: rect.top + rect.height / 2
+  };
+  const pointer = (type) => {
+    try {
+      return new PointerEvent(type, {
+        ...base,
+        pointerId: 1,
+        pointerType: "mouse",
+        isPrimary: true
+      });
+    } catch {
+      return new MouseEvent(type, base);
+    }
+  };
+  el.dispatchEvent(pointer("pointerdown"));
+  el.dispatchEvent(new MouseEvent("mousedown", base));
+  el.dispatchEvent(pointer("pointerup"));
+  el.dispatchEvent(new MouseEvent("mouseup", base));
+  el.dispatchEvent(new MouseEvent("click", base));
+  el.focus?.();
+}
+function isSensitiveField(el) {
+  if (el.hasAttribute(SENSITIVE_INPUT)) return true;
+  if (el instanceof HTMLInputElement && (el.type === "password" || el.type === "hidden"))
+    return true;
+  const tokens = (el.getAttribute("autocomplete") ?? "").toLowerCase().split(/\s+/);
+  return tokens.some((token) => SECRET_AUTOCOMPLETE.has(token));
+}
+function typeInto(el, value) {
+  if (!(el instanceof HTMLInputElement) && !(el instanceof HTMLTextAreaElement)) return;
+  if (isSensitiveField(el)) {
+    console.warn("[guided] Refusing to type into a password, secret or hidden field");
+    return;
+  }
+  el.focus();
+  const setter = Object.getOwnPropertyDescriptor(Object.getPrototypeOf(el), "value")?.set;
+  setter?.call(el, value);
+  el.dispatchEvent(new Event("input", { bubbles: true }));
+}
+var insideSurface = (el) => !!el.closest(`[${REMOTE_CONTROL_SURFACE}]`);
+function isOffLimits(el) {
+  if (insideSurface(el)) return true;
+  const label = el instanceof HTMLLabelElement ? el : el.closest("label");
+  const control = label?.control;
+  return !!label && (insideSurface(label) || !!control && insideSurface(control));
+}
+function isWatchable(el) {
+  const rect = el.getBoundingClientRect();
+  if (rect.width === 0 || rect.height === 0) return false;
+  return typeof el.checkVisibility === "function" ? el.checkVisibility() : true;
+}
+function performStep(step, el, remote) {
+  if (remote && isOffLimits(el)) {
+    console.warn("[guided] Refusing a remote step on an off-limits surface", step.target);
+    return;
+  }
+  if (remote && !isWatchable(el)) {
+    console.warn("[guided] Refusing a remote step on an element the user cannot see", step.target);
+    return;
+  }
+  if (step.do === "type") typeInto(el, step.value ?? "");
+  else clickElement(el);
+}
+function cancelGuidedRun() {
+  runToken += 1;
+  guidedCursor.hide();
+  setActiveRun(null);
+}
+async function runGuidedSteps(steps, id, { remote = false } = {}) {
+  if (steps.length === 0) return;
+  const bound = (ms) => remote && ms !== void 0 ? Math.min(ms, MAX_REMOTE_WAIT_MS) : ms;
+  const myToken = runToken += 1;
+  const superseded = () => runToken !== myToken;
+  setActiveRun(id);
+  for (const step of steps) {
+    if (superseded()) return;
+    if (step.note) notify.info(step.note, { icon: guidedStepIcon });
+    const landed = await guidedCursor.glideTo(step.target, { waitMs: bound(step.waitMs) });
+    if (superseded()) return;
+    if (landed) {
+      guidedCursor.ripple();
+      await sleep2(DWELL_MS);
+      if (superseded()) return;
+      const el = document.querySelector(step.target);
+      if (el) performStep(step, el, remote);
+    }
+    await sleep2(bound(step.pauseMs) ?? DEFAULT_PAUSE_MS);
+  }
+  if (superseded()) return;
+  guidedCursor.hide();
+  setActiveRun(null);
+}
+
+// src/guided/sequences.ts
+var KIT_SEQUENCES = {
+  "upload-a-document": {
+    id: "upload-a-document",
+    label: "Upload a document",
+    description: "Open Documents and start the uploader.",
+    steps: [
+      { target: '[data-testid="sidebar-documents-button"]', note: "Open Documents\u2026" },
+      {
+        target: '[data-testid="documents-upload-button"]',
+        note: "Start the uploader \u2014 drop files here."
+      }
+    ]
+  },
+  "invite-a-colleague": {
+    id: "invite-a-colleague",
+    label: "Invite a colleague",
+    description: "Open the account menu, then Contacts, then add a contact by email.",
+    steps: [
+      { target: '[data-testid="sidebar-user-profile"]', note: "Open your account menu\u2026" },
+      { target: '[data-testid="sidebar-contacts-button"]', note: "Open Contacts\u2026" },
+      { target: '[data-testid="dm-invite-chip"]', note: "Add a contact by email." }
+    ]
+  },
+  "open-plan-usage": {
+    id: "open-plan-usage",
+    label: "View plan & usage",
+    description: "Open the account menu, then Plan & Usage.",
+    steps: [
+      { target: '[data-testid="sidebar-user-profile"]', note: "Open your account menu\u2026" },
+      { target: '[data-testid="user-menu-projects"]', note: "Choose Plan & Usage." }
+    ]
+  }
+};
+var KIT_DEMOS = {
+  "upload-documents": "upload-a-document",
+  "open-invite-contacts": "invite-a-colleague",
+  // The panel opens from the account menu: Show me walks that path.
+  "open-projects": "open-plan-usage"
+};
+function createGuidedRuns(config = {}) {
+  const sequences = { ...KIT_SEQUENCES, ...config.sequences };
+  const demos = { ...KIT_DEMOS, ...config.demos };
+  const isSequenceId = (value) => Object.prototype.hasOwnProperty.call(sequences, value);
+  const runs = {
+    sequences,
+    demos,
+    cursorMark: config.cursorMark,
+    remoteControl: config.remoteControl === true,
+    options: Object.values(sequences).map((s) => ({
+      value: s.id,
+      label: s.label
+    })),
+    isSequenceId,
+    async run(input, options) {
+      if (typeof input !== "string") return runGuidedSteps(input, null, options);
+      if (!isSequenceId(input)) {
+        console.warn(`runSequence: "${input}" is not a known guided run`);
+        return;
+      }
+      return runGuidedSteps(sequences[input].steps, input, options);
+    },
+    // Through `runs.run`, the one way in, so whoever watches it sees a CTA's run too.
+    runCta(cta, runAction) {
+      if (cta.href) {
+        window.open(cta.href, "_blank", "noopener,noreferrer");
+        return;
+      }
+      if (cta.sequence) {
+        void runs.run(cta.sequence);
+        return;
+      }
+      if (!cta.action) return;
+      const demo = Object.prototype.hasOwnProperty.call(demos, cta.action) ? demos[cta.action] : void 0;
+      if (demo) void runs.run(demo);
+      else runAction(cta.action);
+    },
+    cancel: cancelGuidedRun
+  };
+  return runs;
+}
+
+// src/guided/useGuidedRuns.ts
+var KIT_RUNS = createGuidedRuns();
+function useGuidedRuns() {
+  return useHost().guided ?? KIT_RUNS;
+}
+function usageMeterState(used, allowance) {
+  if (allowance <= 0) return used > 0 ? "over" : "under";
+  const ratio = used / allowance;
+  return ratio >= 1 ? "over" : ratio >= 0.8 ? "near" : "under";
+}
+var STATE_TONE = {
+  under: "bg-primary",
+  near: "bg-yellow-500",
+  over: "bg-red-500"
+};
+var pctOf = (n, scale) => scale > 0 ? Math.max(0, Math.min(100, n / scale * 100)) : 0;
+var SWATCH = {
+  plan: "bg-muted-foreground/40",
+  topUps: "bg-primary/30",
+  autoRoom: "bg-muted"
+};
+var HATCH = {
+  backgroundImage: "repeating-linear-gradient(135deg, currentColor 0 1.5px, transparent 1.5px 5px)"
+};
+function AllowanceBar({ allowance, label }) {
+  const { used, plan } = allowance;
+  const topUps = Math.max(0, allowance.topUps ?? 0);
+  const room = Math.max(0, allowance.autoRoom ?? 0);
+  const total = plan + topUps;
+  const scale = Math.max(total + room, used, Number.EPSILON);
+  const state = usageMeterState(used, total);
+  const usedPct = total > 0 ? Math.round(used / total * 100) : used > 0 ? 100 : 0;
+  const markPlan = plan > 0 && plan < scale && (topUps > 0 || room > 0);
+  return /* @__PURE__ */ jsxs("div", { className: "relative h-2 overflow-hidden rounded-full bg-muted", "data-slot": "usage-meter-bar", children: [
+    topUps > 0 && /* @__PURE__ */ jsx(
+      "div",
+      {
+        className: cn("absolute inset-y-0", SWATCH.topUps),
+        style: { left: `${pctOf(plan, scale)}%`, width: `${pctOf(topUps, scale)}%` },
+        "data-slot": "usage-meter-topups"
+      }
+    ),
+    room > 0 && /* @__PURE__ */ jsx(
+      "div",
+      {
+        className: "absolute inset-y-0 text-muted-foreground/35",
+        style: { left: `${pctOf(total, scale)}%`, width: `${pctOf(room, scale)}%`, ...HATCH },
+        "data-slot": "usage-meter-auto-room"
+      }
+    ),
+    /* @__PURE__ */ jsx(
+      "div",
+      {
+        className: cn(
+          "absolute inset-y-0 left-0 rounded-full transition-[width]",
+          STATE_TONE[state]
+        ),
+        style: { width: `${pctOf(Math.min(used, scale), scale)}%` },
+        role: "progressbar",
+        "aria-valuenow": Math.min(usedPct, 100),
+        "aria-valuemin": 0,
+        "aria-valuemax": 100,
+        "aria-label": label,
+        "data-state": state
+      }
+    ),
+    markPlan && /* @__PURE__ */ jsx(
+      "div",
+      {
+        className: "absolute inset-y-0 w-0.5 -translate-x-1/2 bg-foreground/70",
+        style: { left: `${pctOf(plan, scale)}%` },
+        "aria-hidden": true,
+        "data-slot": "usage-meter-plan-mark"
+      }
+    ),
+    room > 0 && total > 0 && /* @__PURE__ */ jsx(
+      "div",
+      {
+        className: "absolute inset-y-0 w-px bg-foreground/40",
+        style: { left: `${pctOf(total, scale)}%` },
+        "aria-hidden": true
+      }
+    )
+  ] });
+}
+function UsageMeter({
+  icon: Icon,
+  label,
+  value,
+  pct = 0,
+  hint,
+  allowance,
+  legend,
+  details,
+  actions,
+  className,
+  testId
+}) {
+  const clamped = Math.max(0, Math.min(100, pct));
+  const tone = clamped >= 100 ? "bg-red-500" : clamped >= 50 ? "bg-yellow-500" : "bg-primary";
+  const state = allowance ? usageMeterState(allowance.used, allowance.plan + Math.max(0, allowance.topUps ?? 0)) : void 0;
+  const legendItems = legend ? [
+    ["plan", legend.plan],
+    ["topUps", legend.topUps],
+    ["autoRoom", legend.autoRoom]
+  ].filter(([, text]) => !!text) : [];
+  const meter = /* @__PURE__ */ jsxs("div", { className: "min-w-0 flex-1 space-y-1.5", children: [
+    /* @__PURE__ */ jsxs("div", { className: "flex min-w-0 items-center justify-between gap-3 text-sm", children: [
+      /* @__PURE__ */ jsxs(
+        "span",
+        {
+          className: cn(
+            "flex min-w-0 items-center gap-1.5",
+            allowance ? "font-medium text-foreground" : "text-muted-foreground"
+          ),
+          children: [
+            Icon && /* @__PURE__ */ jsx(Icon, { className: "size-3.5 shrink-0" }),
+            /* @__PURE__ */ jsxs("span", { className: "truncate", children: [
+              label,
+              hint ? ` (${hint})` : ""
+            ] })
+          ]
+        }
+      ),
+      /* @__PURE__ */ jsx(
+        "span",
+        {
+          className: "shrink-0 font-medium tabular-nums text-foreground",
+          "data-slot": "usage-meter-value",
+          children: value
+        }
+      )
+    ] }),
+    allowance ? /* @__PURE__ */ jsx(AllowanceBar, { allowance, label }) : /* @__PURE__ */ jsx("div", { className: "h-1.5 overflow-hidden rounded-full bg-muted", children: /* @__PURE__ */ jsx(
+      "div",
+      {
+        className: cn("h-full rounded-full transition-[width]", tone),
+        style: { width: `${clamped}%` },
+        role: "progressbar",
+        "aria-valuenow": clamped,
+        "aria-valuemin": 0,
+        "aria-valuemax": 100,
+        "aria-label": label
+      }
+    ) }),
+    legendItems.length > 0 && /* @__PURE__ */ jsx(
+      "ul",
+      {
+        className: "flex flex-wrap gap-x-4 gap-y-1 text-xs tabular-nums text-muted-foreground",
+        "data-slot": "usage-meter-legend",
+        children: legendItems.map(([key, text]) => /* @__PURE__ */ jsxs(
+          "li",
+          {
+            className: "flex items-center gap-1.5",
+            "data-slot": `usage-meter-legend-${key}`,
+            children: [
+              /* @__PURE__ */ jsx(
+                "span",
+                {
+                  className: cn(
+                    "inline-block size-2 rounded-sm",
+                    SWATCH[key],
+                    key === "autoRoom" && "text-muted-foreground/60"
+                  ),
+                  style: key === "autoRoom" ? HATCH : void 0,
+                  "aria-hidden": true
+                }
+              ),
+              text
+            ]
+          },
+          key
+        ))
+      }
+    ),
+    details && /* @__PURE__ */ jsx("div", { className: "space-y-1 text-xs text-muted-foreground", children: details })
+  ] });
+  if (!actions) {
+    return /* @__PURE__ */ jsx("div", { className: cn("space-y-1.5", className), "data-testid": testId, "data-state": state, children: meter });
+  }
+  return /* @__PURE__ */ jsx("div", { className: cn("@container", className), "data-testid": testId, "data-state": state, children: /* @__PURE__ */ jsxs("div", { className: "flex flex-col gap-3 @lg:flex-row @lg:items-start @lg:gap-6", children: [
+    meter,
+    /* @__PURE__ */ jsx(
+      "div",
+      {
+        className: "flex min-w-0 flex-wrap items-center gap-2 @lg:w-60 @lg:shrink-0 @lg:flex-col @lg:items-stretch",
+        "data-slot": "usage-meter-actions",
+        children: actions
+      }
+    )
+  ] }) });
+}
+
+export { KIT_DEMOS, KIT_SEQUENCES, REMOTE_CONTROL_SURFACE, TIP_CTA_LABEL_MAX_CHARS, TIP_MAX_CHARS, UsageMeter, cancelGuidedRun, createGuidedRuns, createTipsRegistry, guidedCursor, isSurfaceMounted, runGuidedSteps, usageMeterState, useActiveGuidedRun, useGuidedRuns, useMountedSurface };
+//# sourceMappingURL=chunk-NFK2SEUD.js.map
+//# sourceMappingURL=chunk-NFK2SEUD.js.map