@eventop/sdk 1.0.2 → 1.0.4

package/dist/index.cjs

@@ -0,0 +1,473 @@
+'use strict';
+
+var react = require('react');
+
+/**
+ * Root context — holds the global feature registry.
+ * Set by EventopAIProvider at the root of the app.
+ */
+const EventopRegistryContext = /*#__PURE__*/react.createContext(null);
+
+/**
+ * Feature scope context — set by EventopTarget.
+ * Tells any EventopStep inside the tree which feature it belongs to,
+ * so you can nest EventopStep inside a EventopTarget without repeating
+ * the feature id. Also supports explicit feature="id" on EventopStep
+ * for steps that live outside their parent EventopTarget in the tree.
+ */
+const EventopFeatureScopeContext = /*#__PURE__*/react.createContext(null);
+function useRegistry() {
+  const ctx = react.useContext(EventopRegistryContext);
+  if (!ctx) throw new Error('[EventopAI] Must be used inside <EventopAIProvider>.');
+  return ctx;
+}
+function useFeatureScope() {
+  return react.useContext(EventopFeatureScopeContext); // null is fine — steps can declare feature explicitly
+}
+
+/**
+ * FeatureRegistry
+ *
+ * The live map of everything currently mounted in the React tree.
+ *
+ * Features   — registered by ShepherdTarget
+ * Flow steps — registered by ShepherdStep, attached to a feature by id
+ *
+ * Both features and steps can live anywhere in the component tree.
+ * They don't need to be co-located. A ShepherdStep just needs to know
+ * which feature id it belongs to.
+ *
+ * Nested steps:
+ *   Steps can themselves have children steps (sub-steps) by passing
+ *   a parentStep prop to ShepherdStep. This lets you model flows like:
+ *
+ *   Feature: "Create styled text"
+ *     Step 0: Click Add Text
+ *     Step 1: Type your content          ← parentStep: 0
+ *       Step 1.0: Select the text        ← parentStep: 1, index: 0
+ *       Step 1.1: Open font picker       ← parentStep: 1, index: 1
+ *       Step 1.2: Choose a font          ← parentStep: 1, index: 2
+ *     Step 2: Click Done
+ *
+ *   In practice most flows are flat (index 0, 1, 2, 3...) but the
+ *   registry supports nested depth for complex interactions.
+ */
+function createFeatureRegistry() {
+  // Map<featureId, featureData>
+  const features = new Map();
+  // Map<featureId, Map<stepKey, stepData>>
+  // stepKey is either a number (flat) or "parentIndex.childIndex" (nested)
+  const flowSteps = new Map();
+  const listeners = new Set();
+  function notify() {
+    listeners.forEach(fn => fn());
+  }
+
+  // ── Feature registration ─────────────────────────────────────────────────
+
+  function registerFeature(feature) {
+    features.set(feature.id, {
+      ...feature,
+      _registeredAt: Date.now()
+    });
+    notify();
+  }
+  function unregisterFeature(id) {
+    features.delete(id);
+    flowSteps.delete(id);
+    notify();
+  }
+
+  // ── Step registration ────────────────────────────────────────────────────
+
+  /**
+   * Register a flow step.
+   *
+   * @param {string} featureId      - Parent feature id
+   * @param {number} index          - Position in the flat flow (0, 1, 2…)
+   * @param {number|null} parentStep - If set, this is a sub-step of parentStep
+   * @param {object} stepData       - { selector, waitFor, advanceOn, ... }
+   */
+  function registerStep(featureId, index, parentStep, stepData) {
+    if (!flowSteps.has(featureId)) {
+      flowSteps.set(featureId, new Map());
+    }
+    const key = parentStep != null ? `${parentStep}.${index}` : String(index);
+    flowSteps.get(featureId).set(key, {
+      ...stepData,
+      index,
+      parentStep: parentStep ?? null,
+      key
+    });
+    notify();
+  }
+  function unregisterStep(featureId, index, parentStep) {
+    const map = flowSteps.get(featureId);
+    if (!map) return;
+    const key = parentStep != null ? `${parentStep}.${index}` : String(index);
+    map.delete(key);
+    if (map.size === 0) flowSteps.delete(featureId);
+    notify();
+  }
+
+  // ── Snapshot ─────────────────────────────────────────────────────────────
+
+  /**
+   * Build the flat flow array the SDK core expects.
+   *
+   * For nested steps we inline sub-steps after their parent step,
+   * in index order. This means a flow like:
+   *
+   *   Step 0 (flat)
+   *   Step 1 (flat)
+   *     Step 1.0 (sub-step of 1)
+   *     Step 1.1 (sub-step of 1)
+   *   Step 2 (flat)
+   *
+   * becomes the SDK flow: [step0, step1, step1.0, step1.1, step2]
+   *
+   * The AI writes titles/text for the parent feature.
+   * Sub-steps inherit the parent step's text with a "(N/M)" suffix added
+   * by the SDK's expandFlowSteps() function.
+   */
+  function buildFlow(featureId) {
+    const map = flowSteps.get(featureId);
+    if (!map || map.size === 0) return null;
+    const allSteps = Array.from(map.values());
+
+    // Separate top-level and nested steps
+    const topLevel = allSteps.filter(s => s.parentStep == null).sort((a, b) => a.index - b.index);
+    const result = [];
+    topLevel.forEach(step => {
+      result.push(step);
+      // Inline any sub-steps after the parent
+      const children = allSteps.filter(s => s.parentStep === step.index).sort((a, b) => a.index - b.index);
+      result.push(...children);
+    });
+    return result.length > 0 ? result : null;
+  }
+
+  /**
+   * Returns the live feature array in the format the SDK core expects.
+   * screen.check() is automatic — mounted = available.
+   */
+  function snapshot() {
+    return Array.from(features.values()).map(feature => {
+      const flow = buildFlow(feature.id);
+      return {
+        id: feature.id,
+        name: feature.name,
+        description: feature.description,
+        selector: feature.selector,
+        advanceOn: feature.advanceOn || null,
+        waitFor: feature.waitFor || null,
+        ...(flow ? {
+          flow
+        } : {}),
+        screen: {
+          id: feature.id,
+          check: () => features.has(feature.id),
+          navigate: feature.navigate || null,
+          waitFor: feature.navigateWaitFor || feature.selector || null
+        }
+      };
+    });
+  }
+  return {
+    registerFeature,
+    unregisterFeature,
+    registerStep,
+    unregisterStep,
+    snapshot,
+    isRegistered: id => features.has(id),
+    subscribe: fn => {
+      listeners.add(fn);
+      return () => listeners.delete(fn);
+    }
+  };
+}
+
+/**
+ * EventopProvider
+ *
+ * Drop this once at the root of your app.
+ * Every EventopTarget and EventopStep anywhere in the tree will
+ * register with this provider automatically.
+ *
+ * @example
+ * <EventopProvider
+ *   provider={myServerFetcher}
+ *   appName="PixelCraft"
+ *   assistantName="Pixel AI"
+ *   suggestions={['Add a shadow', 'Export design']}
+ *   theme={{ mode: 'dark', tokens: { accent: '#6366f1' } }}
+ *   position={{ corner: 'bottom-right' }}
+ * >
+ *   <App />
+ * </EventopProvider>
+ */
+function EventopProvider({
+  children,
+  provider,
+  appName,
+  assistantName,
+  suggestions,
+  theme,
+  position
+}) {
+  if (!provider) throw new Error('[Eventop] <EventopProvider> requires a provider prop.');
+  if (!appName) throw new Error('[Eventop] <EventopProvider> requires an appName prop.');
+  const registry = react.useRef(createFeatureRegistry()).current;
+  const sdkReady = react.useRef(false);
+  const syncToSDK = react.useCallback(() => {
+    if (!sdkReady.current || !window.Eventop) return;
+    window.Eventop._updateConfig?.({
+      features: registry.snapshot()
+    });
+  }, [registry]);
+  react.useEffect(() => {
+    function boot() {
+      window.Eventop.init({
+        provider,
+        config: {
+          appName,
+          assistantName,
+          suggestions,
+          theme,
+          position,
+          features: registry.snapshot(),
+          _providerName: 'custom'
+        }
+      });
+      sdkReady.current = true;
+      syncToSDK();
+    }
+    boot();
+    const unsub = registry.subscribe(syncToSDK);
+    return () => {
+      unsub();
+      window.Eventop?.cancelTour();
+    };
+  }, []);
+  const ctx = {
+    registerFeature: registry.registerFeature,
+    unregisterFeature: registry.unregisterFeature,
+    registerStep: registry.registerStep,
+    unregisterStep: registry.unregisterStep,
+    isRegistered: registry.isRegistered
+  };
+  return /*#__PURE__*/React.createElement(EventopRegistryContext.Provider, {
+    value: ctx
+  }, children);
+}
+
+/**
+ * EventopTarget
+ *
+ * Wraps any component and registers it as an Eventop feature at the call site.
+ * The wrapped component does not need to know about Eventop.
+ */
+function EventopTarget({
+  children,
+  id,
+  name,
+  description,
+  navigate,
+  navigateWaitFor,
+  advanceOn,
+  waitFor,
+  ...rest
+}) {
+  const registry = useRegistry();
+  const ref = react.useRef(null);
+  const dataAttr = `data-evtp-${id}`;
+  const selector = `[${dataAttr}]`;
+  react.useEffect(() => {
+    if (!id || !name) {
+      console.warn('[Eventop] <EventopTarget> requires id and name props.');
+      return;
+    }
+    registry.registerFeature({
+      id,
+      name,
+      description,
+      selector,
+      navigate,
+      navigateWaitFor,
+      waitFor,
+      advanceOn: advanceOn ? {
+        selector,
+        ...advanceOn
+      } : null
+    });
+    return () => registry.unregisterFeature(id);
+  }, [id, name, description]);
+  const child = react.Children.only(children);
+  let wrapped;
+  try {
+    wrapped = /*#__PURE__*/react.cloneElement(child, {
+      [dataAttr]: '',
+      ref: node => {
+        ref.current = node;
+        const originalRef = child.ref;
+        if (typeof originalRef === 'function') originalRef(node);else if (originalRef && 'current' in originalRef) originalRef.current = node;
+      }
+    });
+  } catch {
+    wrapped = /*#__PURE__*/React.createElement("span", {
+      [dataAttr]: '',
+      ref: ref,
+      style: {
+        display: 'contents'
+      }
+    }, child);
+  }
+  return /*#__PURE__*/React.createElement(EventopFeatureScopeContext.Provider, {
+    value: id
+  }, wrapped);
+}
+
+/**
+ * EventopStep
+ *
+ * Registers one step in a multi-step flow. Can live anywhere in the tree.
+ * Steps self-assemble into order via the `index` prop.
+ */
+function EventopStep({
+  children,
+  feature,
+  index,
+  parentStep,
+  waitFor,
+  advanceOn
+}) {
+  const registry = useRegistry();
+  const featureScope = useFeatureScope();
+  const featureId = feature || featureScope;
+  const ref = react.useRef(null);
+  if (!featureId) {
+    console.warn('[Eventop] <EventopStep> needs either a feature prop or an <EventopTarget> ancestor.');
+  }
+  if (index == null) {
+    console.warn('[Eventop] <EventopStep> requires an index prop.');
+  }
+  const dataAttr = `data-evtp-step-${featureId}-${parentStep != null ? `${parentStep}-` : ''}${index}`;
+  const selector = `[${dataAttr}]`;
+  react.useEffect(() => {
+    if (!featureId || index == null) return;
+    registry.registerStep(featureId, index, parentStep ?? null, {
+      selector,
+      waitFor: waitFor || null,
+      advanceOn: advanceOn ? {
+        selector,
+        ...advanceOn
+      } : null
+    });
+    return () => registry.unregisterStep(featureId, index, parentStep ?? null);
+  }, [featureId, index, parentStep]);
+  const child = react.Children.only(children);
+  let wrapped;
+  try {
+    wrapped = /*#__PURE__*/react.cloneElement(child, {
+      [dataAttr]: '',
+      ref: node => {
+        ref.current = node;
+        const originalRef = child.ref;
+        if (typeof originalRef === 'function') originalRef(node);else if (originalRef && 'current' in originalRef) originalRef.current = node;
+      }
+    });
+  } catch {
+    wrapped = /*#__PURE__*/React.createElement("span", {
+      [dataAttr]: '',
+      ref: ref,
+      style: {
+        display: 'contents'
+      }
+    }, child);
+  }
+  return wrapped;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+//  useEventopAI
+//
+//  Access the SDK programmatic API from inside any component.
+//  Use for stepComplete(), stepFail(), open(), close() etc.
+//
+//  @example
+//  function CheckoutForm() {
+//    const { stepComplete, stepFail } = useEventopAI();
+//
+//    async function handleNext() {
+//      const ok = await validateEmail(email);
+//      if (ok) stepComplete();
+//      else stepFail('Please enter a valid email address.');
+//    }
+//  }
+// ═══════════════════════════════════════════════════════════════════════════
+
+function useEventop() {
+  const sdk = () => window.Eventop;
+  return {
+    open: () => sdk()?.open(),
+    close: () => sdk()?.close(),
+    cancelTour: () => sdk()?.cancelTour(),
+    resumeTour: () => sdk()?.resumeTour(),
+    isActive: () => sdk()?.isActive() ?? false,
+    isPaused: () => sdk()?.isPaused() ?? false,
+    stepComplete: () => sdk()?.stepComplete(),
+    stepFail: msg => sdk()?.stepFail(msg),
+    runTour: steps => sdk()?.runTour(steps)
+  };
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+//  useEventopTour
+//
+//  Reactively tracks tour state so you can render your own UI.
+//  Polls at 300ms — lightweight enough for a status indicator.
+//
+//  @example
+//  function TourBar() {
+//    const { isActive, isPaused, resume, cancel } = useEventopTour();
+//    if (!isActive && !isPaused) return null;
+//    return (
+//      <div>
+//        {isPaused && <button onClick={resume}>Resume tour</button>}
+//        <button onClick={cancel}>End</button>
+//      </div>
+//    );
+//  }
+// ═══════════════════════════════════════════════════════════════════════════
+
+function useEventopTour() {
+  const [state, setState] = react.useState({
+    isActive: false,
+    isPaused: false
+  });
+  react.useEffect(() => {
+    const id = setInterval(() => {
+      const sdk = window.Eventop;
+      if (!sdk) return;
+      const next = {
+        isActive: sdk.isActive(),
+        isPaused: sdk.isPaused()
+      };
+      setState(prev => prev.isActive !== next.isActive || prev.isPaused !== next.isPaused ? next : prev);
+    }, 300);
+    return () => clearInterval(id);
+  }, []);
+  return {
+    ...state,
+    resume: react.useCallback(() => window.Eventop?.resumeTour(), []),
+    cancel: react.useCallback(() => window.Eventop?.cancelTour(), []),
+    open: react.useCallback(() => window.Eventop?.open(), []),
+    close: react.useCallback(() => window.Eventop?.close(), [])
+  };
+}
+
+exports.EventopProvider = EventopProvider;
+exports.EventopStep = EventopStep;
+exports.EventopTarget = EventopTarget;
+exports.useEventop = useEventop;
+exports.useEventopTour = useEventopTour;