onboardme-sdk 0.0.1

package/src/components/checklist.ts

@@ -0,0 +1,295 @@
+/**
+ * checklist.ts — Week 3 Days 2, 3 & 4
+ *
+ * Renders the onboarding checklist panel into a Shadow DOM root and wires
+ * all interactivity: item click → mark complete, progress bar update,
+ * collapse/expand pill behaviour, and completionEvent auto-check.
+ */
+
+import type { FlowConfig, ChecklistItem } from '@onboardme/types';
+import type { Progress } from '../storage/progress-tracker.js';
+import { markStepComplete } from '../storage/progress-tracker.js';
+import { watchCompletionEvents } from '../storage/event-listener.js';
+import { CHECKLIST_CSS } from '../styles/checklist-css.js';
+import { pushEvent } from '../core/event-batcher.js';
+
+// ---------------------------------------------------------------------------
+// Per-shadow-root watcher cleanup
+// ---------------------------------------------------------------------------
+
+/**
+ * Stores the active unsubscribe function for each shadow root so that
+ * re-rendering cleans up the previous watcher before installing a new one.
+ */
+const _unsubscribers = new WeakMap<ShadowRoot, () => void>();
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function injectStyles(shadowRoot: ShadowRoot): void {
+  const style = shadowRoot.querySelector<HTMLStyleElement>('style[data-onboardme="styles"]');
+  if (style) {
+    if (!style.textContent?.includes('.om-checklist')) {
+      style.textContent = (style.textContent ?? '') + CHECKLIST_CSS;
+    }
+  }
+}
+
+function getChecklistItems(flow: FlowConfig): ChecklistItem[] {
+  const checklistStep = flow.steps.find((s) => s.type === 'checklist');
+  return checklistStep?.items ?? [];
+}
+
+function countRequired(items: ChecklistItem[]): number {
+  return items.filter((item) => item.required !== false).length;
+}
+
+function buildItemEl(item: ChecklistItem, isDone: boolean): HTMLLIElement {
+  const li = document.createElement('li');
+  const classes = ['om-checklist__item'];
+  if (isDone) classes.push('om-checklist__item--done');
+  if (item.required === false) classes.push('om-checklist__item--optional');
+  li.className = classes.join(' ');
+  li.dataset['itemId'] = item.id;
+
+  const check = document.createElement('span');
+  check.className = 'om-checklist__item-check';
+  check.setAttribute('aria-hidden', 'true');
+  check.textContent = isDone ? '✓' : '';
+
+  const label = document.createElement('span');
+  label.className = 'om-checklist__item-label';
+  label.textContent = item.label;
+
+  li.appendChild(check);
+  li.appendChild(label);
+
+  if (item.required === false) {
+    const badge = document.createElement('span');
+    badge.className = 'om-badge';
+    badge.textContent = 'Optional';
+    li.appendChild(badge);
+  }
+
+  return li;
+}
+
+/**
+ * Surgically updates the progress bar fill, progress label, and collapsed
+ * count without touching the item list.
+ */
+function updateProgressDisplay(
+  shadowRoot: ShadowRoot,
+  items: ChecklistItem[],
+  completedSteps: string[],
+): void {
+  const totalRequired = countRequired(items);
+  const completedRequired = items.filter(
+    (i) => i.required !== false && completedSteps.includes(i.id),
+  ).length;
+  const totalAll = items.length;
+  const completedAll = items.filter((i) => completedSteps.includes(i.id)).length;
+  const fillPct = totalRequired > 0 ? Math.round((completedRequired / totalRequired) * 100) : 0;
+
+  const fill = shadowRoot.querySelector<HTMLElement>('.om-checklist__progress-bar-fill');
+  if (fill) fill.style.width = `${fillPct}%`;
+
+  const label = shadowRoot.querySelector('[data-onboardme="progress-label"]');
+  if (label) label.textContent = `${completedAll} of ${totalAll} complete`;
+
+  const collapsedCount = shadowRoot.querySelector('[data-onboardme="collapsed-count"]');
+  if (collapsedCount) collapsedCount.textContent = `${completedAll} / ${totalAll}`;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Renders (or re-renders) the checklist panel into the provided Shadow DOM.
+ *
+ * - Finds the first step with type === 'checklist' in the flow
+ * - Sorts items by item.order (never array index)
+ * - Warns (console.warn) in debug mode when items.length > 7
+ * - Marks already-completed items from progress.completedSteps on first render
+ * - Replaces any existing panel so calling this twice does not duplicate it
+ * - Wires item click → markStepComplete → visual update (Day 3)
+ * - Wires collapse button and panel click for collapse/expand (Day 3)
+ *
+ * @param productId  Used by markStepComplete — pass empty string in tests that
+ *                   do not need persistence (keeps backwards compat).
+ * @param flowId     Same as above.
+ */
+export function renderChecklist(
+  flow: FlowConfig,
+  progress: Progress,
+  shadowRoot: ShadowRoot,
+  debug = false,
+  productId = '',
+  flowId = '',
+): void {
+  injectStyles(shadowRoot);
+
+  // Clean up previous completionEvent watcher before replacing the panel
+  _unsubscribers.get(shadowRoot)?.();
+  _unsubscribers.delete(shadowRoot);
+
+  const existing = shadowRoot.querySelector('[data-onboardme="checklist"]');
+  if (existing) shadowRoot.removeChild(existing);
+
+  const rawItems = getChecklistItems(flow);
+
+  if (debug && rawItems.length > 7) {
+    console.warn('[OnboardMe] Checklist has more than 7 items — consider splitting the flow.');
+  }
+
+  const items = [...rawItems].sort((a, b) => a.order - b.order);
+
+  const totalRequired = countRequired(items);
+  const completedRequired = items.filter(
+    (item) => item.required !== false && progress.completedSteps.includes(item.id),
+  ).length;
+  const totalAll = items.length;
+  const completedAll = items.filter((item) => progress.completedSteps.includes(item.id)).length;
+  const fillPct = totalRequired > 0 ? Math.round((completedRequired / totalRequired) * 100) : 0;
+
+  // ---- Mutable local snapshot of completedSteps ----------------------------
+  // Keeps click handlers in sync without re-reading localStorage on every click.
+  const mutableCompleted = [...progress.completedSteps];
+
+  // ---- Outer panel ---------------------------------------------------------
+  const panel = document.createElement('div');
+  panel.className = 'om-checklist';
+  panel.dataset['onboardme'] = 'checklist';
+
+  // ---- Header --------------------------------------------------------------
+  const header = document.createElement('div');
+  header.className = 'om-checklist__header';
+
+  const titleEl = document.createElement('span');
+  titleEl.className = 'om-checklist__title';
+  titleEl.textContent = 'Getting started';
+
+  // Shown only in collapsed state — holds "2 / 5"
+  const collapsedCountEl = document.createElement('span');
+  collapsedCountEl.className = 'om-checklist__collapsed-count';
+  collapsedCountEl.dataset['onboardme'] = 'collapsed-count';
+  collapsedCountEl.style.display = 'none';
+  collapsedCountEl.textContent = `${completedAll} / ${totalAll}`;
+
+  const collapseBtn = document.createElement('button');
+  collapseBtn.className = 'om-checklist__collapse-btn';
+  collapseBtn.type = 'button';
+  collapseBtn.dataset['onboardme'] = 'checklist-collapse';
+  collapseBtn.setAttribute('aria-label', 'Collapse checklist');
+  collapseBtn.textContent = '−';
+
+  header.appendChild(titleEl);
+  header.appendChild(collapsedCountEl);
+  header.appendChild(collapseBtn);
+
+  // ---- Progress area -------------------------------------------------------
+  const progressArea = document.createElement('div');
+  progressArea.className = 'om-checklist__progress';
+
+  const bar = document.createElement('div');
+  bar.className = 'om-checklist__progress-bar';
+
+  const fill = document.createElement('div');
+  fill.className = 'om-checklist__progress-bar-fill';
+  fill.style.width = `${fillPct}%`;
+  bar.appendChild(fill);
+
+  const progressLabel = document.createElement('span');
+  progressLabel.className = 'om-checklist__progress-label';
+  progressLabel.dataset['onboardme'] = 'progress-label';
+  progressLabel.textContent = `${completedAll} of ${totalAll} complete`;
+
+  progressArea.appendChild(bar);
+  progressArea.appendChild(progressLabel);
+
+  // ---- Items list ----------------------------------------------------------
+  const ul = document.createElement('ul');
+  ul.className = 'om-checklist__items';
+
+  for (const item of items) {
+    const isDone = progress.completedSteps.includes(item.id);
+    ul.appendChild(buildItemEl(item, isDone));
+  }
+
+  // ---- Assemble ------------------------------------------------------------
+  panel.appendChild(header);
+  panel.appendChild(progressArea);
+  panel.appendChild(ul);
+  shadowRoot.appendChild(panel);
+
+  // Emit step_viewed for the checklist step
+  const checklistStepId = flow.steps.find((s) => s.type === 'checklist')?.id ?? '';
+  if (checklistStepId && flowId) {
+    pushEvent('step_viewed', { flowId, stepId: checklistStepId });
+  }
+
+  // ---- Wire item click handlers --------------------------------------------
+  const itemEls = panel.querySelectorAll<HTMLLIElement>('.om-checklist__item');
+  for (const li of itemEls) {
+    li.addEventListener('click', () => {
+      const itemId = li.dataset['itemId'];
+      if (!itemId || mutableCompleted.includes(itemId)) return;
+
+      // Persist + emit event
+      if (productId && flowId) {
+        markStepComplete(productId, flowId, itemId);
+        pushEvent('checklist_item_done', { flowId, stepId: itemId });
+      }
+      mutableCompleted.push(itemId);
+
+      // Visual update — item
+      li.classList.add('om-checklist__item--done');
+      const checkEl = li.querySelector('.om-checklist__item-check');
+      if (checkEl) checkEl.textContent = '✓';
+
+      // Visual update — progress bar + label
+      updateProgressDisplay(shadowRoot, items, mutableCompleted);
+    });
+  }
+
+  // ---- Wire collapse / expand ----------------------------------------------
+  collapseBtn.addEventListener('click', (e) => {
+    e.stopPropagation(); // prevent the panel-level click from immediately re-expanding
+    panel.classList.add('om-checklist--collapsed');
+    titleEl.style.display = 'none';
+    collapsedCountEl.style.display = 'inline';
+  });
+
+  panel.addEventListener('click', () => {
+    if (!panel.classList.contains('om-checklist--collapsed')) return;
+    panel.classList.remove('om-checklist--collapsed');
+    titleEl.style.display = '';
+    collapsedCountEl.style.display = 'none';
+  });
+
+  // ---- Wire completionEvent auto-check (Day 4) -----------------------------
+  const unsubscribe = watchCompletionEvents(flow, (itemId) => {
+    if (mutableCompleted.includes(itemId)) return;
+
+    if (productId && flowId) {
+      markStepComplete(productId, flowId, itemId);
+      pushEvent('checklist_item_done', { flowId, stepId: itemId });
+    }
+    mutableCompleted.push(itemId);
+
+    // Visual update — item
+    const li = panel.querySelector<HTMLLIElement>(`[data-item-id="${itemId}"]`);
+    if (li) {
+      li.classList.add('om-checklist__item--done');
+      const checkEl = li.querySelector('.om-checklist__item-check');
+      if (checkEl) checkEl.textContent = '✓';
+    }
+
+    // Visual update — progress bar + label
+    updateProgressDisplay(shadowRoot, items, mutableCompleted);
+  });
+
+  _unsubscribers.set(shadowRoot, unsubscribe);
+}

package/src/components/modal-css.ts

@@ -0,0 +1,96 @@
+/**
+ * Modal CSS as an injectable string for the Shadow DOM.
+ * Source of truth: modal.css (kept alongside for readability/tooling).
+ */
+export const MODAL_CSS = `
+.om-overlay {
+  position: fixed;
+  inset: 0;
+  background: rgba(0, 0, 0, 0.45);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  z-index: 2147483647;
+}
+
+.om-modal {
+  background: #ffffff;
+  border-radius: 12px;
+  box-shadow: 0 20px 60px rgba(0, 0, 0, 0.2);
+  max-width: 480px;
+  width: calc(100% - 32px);
+  padding: 32px;
+  box-sizing: border-box;
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+  color: #111827;
+}
+
+.om-modal__title {
+  margin: 0 0 12px;
+  font-size: 20px;
+  font-weight: 700;
+  line-height: 1.3;
+  color: #111827;
+}
+
+.om-modal__body {
+  margin: 0 0 24px;
+  font-size: 15px;
+  line-height: 1.6;
+  color: #4b5563;
+}
+
+.om-modal__actions {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+  align-items: stretch;
+}
+
+.om-btn-primary {
+  display: block;
+  width: 100%;
+  padding: 12px 20px;
+  background: #4f46e5;
+  color: #ffffff;
+  font-size: 15px;
+  font-weight: 600;
+  border: none;
+  border-radius: 8px;
+  cursor: pointer;
+  text-align: center;
+  transition: background 0.15s ease;
+}
+
+.om-btn-primary:hover {
+  background: #4338ca;
+}
+
+.om-btn-primary:focus-visible {
+  outline: 3px solid #818cf8;
+  outline-offset: 2px;
+}
+
+.om-btn-skip {
+  display: block;
+  background: none;
+  border: none;
+  padding: 6px 0;
+  color: #6b7280;
+  font-size: 14px;
+  cursor: pointer;
+  text-align: center;
+  text-decoration: underline;
+  transition: color 0.15s ease;
+}
+
+.om-btn-skip:hover {
+  color: #374151;
+}
+
+.om-btn-skip:focus-visible {
+  outline: 2px solid #818cf8;
+  outline-offset: 2px;
+  border-radius: 4px;
+}
+`;

package/src/components/modal.ts

@@ -0,0 +1,171 @@
+import type { FlowStep } from '@onboardme/types';
+import { MODAL_CSS } from '../styles/modal-css.js';
+import { pushEvent } from '../core/event-batcher.js';
+
+// ---------------------------------------------------------------------------
+// Internal state
+// ---------------------------------------------------------------------------
+
+/**
+ * Maps each ShadowRoot to the keydown handler registered for it.
+ * Using a WeakMap ensures each shadow root instance has its own independent
+ * handler — no cross-instance interference.
+ */
+const _keyHandlers = new WeakMap<ShadowRoot, (e: KeyboardEvent) => void>();
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function sessionKey(productId: string): string {
+  return `onboardme_modal_shown_${productId}`;
+}
+
+// CSS is injected once into the shadow root's placeholder <style> element
+// (created by getShadowRoot() in Day 1).
+function injectStyles(shadowRoot: ShadowRoot): void {
+  const style = shadowRoot.querySelector<HTMLStyleElement>('style[data-onboardme="styles"]');
+  if (style && !style.textContent) {
+    style.textContent = MODAL_CSS;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Renders the welcome modal DOM structure into the provided Shadow DOM root.
+ *
+ * - Reads title/body from the FlowStep (plain text — no markdown yet)
+ * - Primary CTA defaults to "Get started" if step.primaryCta is absent
+ * - Skip link defaults to "Skip for now" if step.secondaryCta is absent
+ * - Skip link is hidden (not rendered) when step.dismissible === false
+ */
+export function renderModal(step: FlowStep, shadowRoot: ShadowRoot): void {
+  injectStyles(shadowRoot);
+
+  // Overlay — full-screen backdrop
+  const overlay = document.createElement('div');
+  overlay.className = 'om-overlay';
+  overlay.dataset['onboardme'] = 'overlay';
+
+  // Card
+  const modal = document.createElement('div');
+  modal.className = 'om-modal';
+  modal.setAttribute('role', 'dialog');
+  modal.setAttribute('aria-modal', 'true');
+  modal.setAttribute('aria-labelledby', 'om-modal-title');
+
+  // Title
+  const title = document.createElement('h2');
+  title.id = 'om-modal-title';
+  title.className = 'om-modal__title';
+  title.textContent = step.title;
+
+  // Body
+  const body = document.createElement('p');
+  body.className = 'om-modal__body';
+  body.textContent = step.body;
+
+  // Actions row
+  const actions = document.createElement('div');
+  actions.className = 'om-modal__actions';
+
+  // Primary CTA
+  const primaryCta = document.createElement('button');
+  primaryCta.className = 'om-btn-primary';
+  primaryCta.type = 'button';
+  primaryCta.textContent = step.primaryCta ?? 'Get started';
+  primaryCta.dataset['onboardme'] = 'primary-cta';
+
+  actions.appendChild(primaryCta);
+
+  // Skip link — hidden when dismissible is explicitly false
+  if (step.dismissible !== false) {
+    const skipBtn = document.createElement('button');
+    skipBtn.className = 'om-btn-skip';
+    skipBtn.type = 'button';
+    skipBtn.textContent = step.secondaryCta ?? 'Skip for now';
+    skipBtn.dataset['onboardme'] = 'skip-cta';
+    actions.appendChild(skipBtn);
+  }
+
+  modal.appendChild(title);
+  modal.appendChild(body);
+  modal.appendChild(actions);
+  overlay.appendChild(modal);
+  shadowRoot.appendChild(overlay);
+}
+
+/**
+ * Removes the modal overlay from the shadow root and cleans up the keyboard
+ * listener. Does NOT clear the session flag — modal cannot reappear within
+ * the same browser session.
+ */
+export function hideModal(shadowRoot: ShadowRoot): void {
+  const overlay = shadowRoot.querySelector('[data-onboardme="overlay"]');
+  if (overlay) {
+    shadowRoot.removeChild(overlay);
+  }
+
+  const keyHandler = _keyHandlers.get(shadowRoot);
+  if (keyHandler) {
+    document.removeEventListener('keydown', keyHandler);
+    _keyHandlers.delete(shadowRoot);
+  }
+}
+
+/**
+ * Shows the modal for a new user.
+ *
+ * Session guard: if the modal has already been shown in this browser session
+ * (sessionStorage flag set), returns immediately without rendering.
+ *
+ * On first show:
+ * - Sets the session flag so subsequent calls in the same tab are no-ops
+ * - Calls renderModal() to build the DOM
+ * - Wires Primary CTA and Skip button clicks to hideModal()
+ * - Adds a keydown listener for Escape → hideModal()
+ * - Moves focus to the primary CTA (accessibility)
+ */
+export function showModal(step: FlowStep, shadowRoot: ShadowRoot, productId: string, flowId: string): void {
+  // Session guard
+  if (sessionStorage.getItem(sessionKey(productId)) !== null) {
+    return;
+  }
+  sessionStorage.setItem(sessionKey(productId), '1');
+
+  // Enqueue flow lifecycle + step view events
+  pushEvent('flow_started', { flowId });
+  pushEvent('step_viewed', { flowId, stepId: step.id, stepIndex: 0 });
+
+  renderModal(step, shadowRoot);
+
+  // Wire Primary CTA → step_completed + hideModal
+  const primaryCta = shadowRoot.querySelector<HTMLButtonElement>('[data-onboardme="primary-cta"]');
+  primaryCta?.addEventListener('click', () => {
+    pushEvent('step_completed', { flowId, stepId: step.id });
+    hideModal(shadowRoot);
+  });
+
+  // Wire Skip → step_skipped + hideModal
+  const skipBtn = shadowRoot.querySelector<HTMLButtonElement>('[data-onboardme="skip-cta"]');
+  skipBtn?.addEventListener('click', () => {
+    pushEvent('step_skipped', { flowId, stepId: step.id });
+    hideModal(shadowRoot);
+  });
+
+  // Keyboard: Escape always closes, regardless of dismissible flag
+  const keyHandler = (e: KeyboardEvent) => {
+    if (e.key === 'Escape') {
+      pushEvent('step_skipped', { flowId, stepId: step.id });
+      hideModal(shadowRoot);
+    }
+  };
+  _keyHandlers.set(shadowRoot, keyHandler);
+  document.addEventListener('keydown', keyHandler);
+
+  // Move focus to primary CTA for accessibility
+  primaryCta?.focus();
+}

package/src/components/shadow-host.ts

@@ -0,0 +1,30 @@
+const ROOT_ID = 'onboardme-root';
+
+/**
+ * Returns the Shadow DOM root that all OnboardMe components mount into.
+ *
+ * On first call: creates <div id="onboardme-root">, attaches an open
+ * Shadow DOM, injects a placeholder <style> element, and appends to body.
+ *
+ * On subsequent calls: returns the existing shadow root without creating
+ * a duplicate element.
+ */
+export function getShadowRoot(): ShadowRoot {
+  const existing = document.getElementById(ROOT_ID);
+  if (existing?.shadowRoot) {
+    return existing.shadowRoot;
+  }
+
+  const host = document.createElement('div');
+  host.id = ROOT_ID;
+  document.body.appendChild(host);
+
+  const shadow = host.attachShadow({ mode: 'open' });
+
+  // Placeholder <style> — populated by component modules (Day 2+)
+  const style = document.createElement('style');
+  style.dataset['onboardme'] = 'styles';
+  shadow.appendChild(style);
+
+  return shadow;
+}

package/src/core/api-client.ts

@@ -0,0 +1,39 @@
+import type { OnboardingEvent } from '@onboardme/types';
+import { logger } from '../utils/logger.js';
+
+const TIMEOUT_MS = 10_000;
+
+/**
+ * Sends a batch of events to the configured endpoint.
+ * Never throws — always resolves to a boolean.
+ * Returns true on 2xx, false on any error (network, timeout, 4xx, 5xx).
+ * On failure the caller is responsible for retaining the queue.
+ */
+export async function postEvents(
+  endpoint: string,
+  events: OnboardingEvent[],
+): Promise<boolean> {
+  const controller = new AbortController();
+  const timerId = setTimeout(() => controller.abort(), TIMEOUT_MS);
+
+  try {
+    const res = await fetch(endpoint, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ events }),
+      signal: controller.signal,
+    });
+
+    if (!res.ok) {
+      logger.warn(`event flush failed — server responded ${res.status}`);
+      return false;
+    }
+
+    return true;
+  } catch (err) {
+    logger.warn(`event flush failed — ${(err as Error).message}`);
+    return false;
+  } finally {
+    clearTimeout(timerId);
+  }
+}