onboardme-sdk 0.0.1

package/src/__tests__/v2-positioner.test.ts

@@ -0,0 +1,115 @@
+import { describe, it, expect } from 'vitest'
+import { computeTooltipPosition, computeHighlightRect } from '../v2/positioner'
+
+const baseInput = {
+  targetRect:    { top: 100, left: 200, width: 80, height: 40 },
+  tooltipWidth:  120,
+  tooltipHeight: 60,
+  scrollX:       0,
+  scrollY:       0,
+  viewportWidth:  1280,
+  viewportHeight: 800,
+}
+
+describe('computeTooltipPosition — placement basics', () => {
+  it('places ABOVE the target on placement=top, horizontally centred', () => {
+    const r = computeTooltipPosition({ ...baseInput, placement: 'top' })
+    // top: 100 - 60 - 8 = 32
+    // left: 200 + 40 - 60 = 180
+    expect(r.top).toBe(32)
+    expect(r.left).toBe(180)
+  })
+
+  it('places BELOW the target on placement=bottom', () => {
+    const r = computeTooltipPosition({ ...baseInput, placement: 'bottom' })
+    // top: 100 + 40 + 8 = 148
+    expect(r.top).toBe(148)
+    expect(r.left).toBe(180)
+  })
+
+  it('places to the RIGHT on placement=right, vertically centred', () => {
+    const r = computeTooltipPosition({ ...baseInput, placement: 'right' })
+    // top: 100 + 20 - 30 = 90
+    // left: 200 + 80 + 8 = 288
+    expect(r.top).toBe(90)
+    expect(r.left).toBe(288)
+  })
+
+  it('places to the LEFT on placement=left', () => {
+    const r = computeTooltipPosition({ ...baseInput, placement: 'left' })
+    // left: 200 - 120 - 8 = 72
+    expect(r.left).toBe(72)
+    expect(r.top).toBe(90)
+  })
+
+  it('places centred in the viewport on placement=center', () => {
+    const r = computeTooltipPosition({ ...baseInput, placement: 'center' })
+    // top: 800/2 - 60/2 = 370
+    // left: 1280/2 - 120/2 = 580
+    expect(r.top).toBe(370)
+    expect(r.left).toBe(580)
+  })
+})
+
+describe('computeTooltipPosition — viewport clamping', () => {
+  it('clamps when target near top edge would push tooltip negative', () => {
+    const r = computeTooltipPosition({
+      ...baseInput,
+      targetRect: { top: 4, left: 200, width: 80, height: 20 },
+      placement: 'top',
+    })
+    // Without clamp: 4 - 60 - 8 = -64 → clamped to 8 (GAP)
+    expect(r.top).toBe(8)
+  })
+
+  it('clamps when tooltip would extend past right edge', () => {
+    const r = computeTooltipPosition({
+      ...baseInput,
+      targetRect: { top: 100, left: 1250, width: 20, height: 20 },
+      placement: 'right',
+    })
+    // Without clamp: 1250 + 20 + 8 = 1278; tooltip width 120 → ends at 1398 > vw
+    // Clamped: 1280 - 120 - 8 = 1152
+    expect(r.left).toBe(1152)
+  })
+
+  it('clamps when tooltip would extend past bottom edge', () => {
+    const r = computeTooltipPosition({
+      ...baseInput,
+      targetRect: { top: 750, left: 200, width: 80, height: 40 },
+      placement: 'bottom',
+    })
+    // Without clamp: 750 + 40 + 8 = 798; tooltip height 60 → ends at 858 > 800
+    // Clamped: 800 - 60 - 8 = 732
+    expect(r.top).toBe(732)
+  })
+})
+
+describe('computeTooltipPosition — page scroll', () => {
+  it('adds scroll offsets to the page-absolute coordinates', () => {
+    const r = computeTooltipPosition({
+      ...baseInput,
+      placement: 'bottom',
+      scrollX: 100,
+      scrollY: 200,
+    })
+    // top (viewport): 100 + 40 + 8 = 148
+    // left (viewport): 200 + 40 - 60 = 180
+    expect(r.top).toBe(148 + 200)
+    expect(r.left).toBe(180 + 100)
+  })
+})
+
+describe('computeHighlightRect', () => {
+  it('inflates by 4px on each side and adds scroll offset', () => {
+    const r = computeHighlightRect({
+      targetRect: { top: 100, left: 200, width: 80, height: 40 },
+      scrollX: 50,
+      scrollY: 25,
+    })
+    expect(r.top).toBe(100 - 4 + 25)
+    expect(r.left).toBe(200 - 4 + 50)
+    expect(r.width).toBe(80 + 8)
+    expect(r.height).toBe(40 + 8)
+  })
+})

package/src/__tests__/v2-renderer.test.ts

@@ -0,0 +1,189 @@
+import { describe, it, expect, beforeEach } from 'vitest'
+import { renderV2Flow } from '../v2/renderer'
+import type { V2FlowConfig } from '../v2/types'
+
+function setupShadowRoot(): ShadowRoot {
+  document.body.innerHTML = ''
+  const host = document.createElement('div')
+  document.body.appendChild(host)
+  return host.attachShadow({ mode: 'open' })
+}
+
+function configWith(stepOverrides: Array<Partial<{
+  id: string
+  type: 'tooltip' | 'modal' | 'highlight'
+  title: string
+  description: string
+  selector: string
+  placement: 'top' | 'bottom' | 'left' | 'right' | 'center'
+  actionType: 'next' | 'skip' | 'complete'
+  actionLabel: string
+}>>): V2FlowConfig {
+  return {
+    steps: stepOverrides.map((o, i) => ({
+      id:          o.id          ?? `step-${i + 1}`,
+      title:       o.title       ?? `Step ${i + 1}`,
+      description: o.description ?? '',
+      type:        (o.type as 'tooltip' | 'modal' | 'highlight') ?? 'modal',
+      position: {
+        selector:  o.selector  ?? 'body',
+        placement: (o.placement as 'top'|'bottom'|'left'|'right'|'center') ?? 'center',
+      },
+      action: {
+        type:  (o.actionType as 'next' | 'skip' | 'complete') ?? (i === stepOverrides.length - 1 ? 'complete' : 'next'),
+        label: o.actionLabel ?? 'Next',
+      },
+    })),
+  }
+}
+
+beforeEach(() => {
+  document.body.innerHTML = ''
+})
+
+describe('renderV2Flow — first render', () => {
+  it('mounts a modal step with overlay and card', () => {
+    const root = setupShadowRoot()
+    const handle = renderV2Flow(
+      configWith([{ type: 'modal', title: 'Welcome', description: 'Get started' }]),
+      root,
+    )
+    expect(handle).not.toBeNull()
+    expect(root.querySelector('.om2-overlay')).not.toBeNull()
+    expect(root.querySelector('.om2-modal-card')).not.toBeNull()
+    expect(root.querySelector('.om2-title')?.textContent).toBe('Welcome')
+    expect(root.querySelector('.om2-description')?.textContent).toBe('Get started')
+  })
+
+  it('mounts a tooltip step (no overlay)', () => {
+    const root = setupShadowRoot()
+    document.body.innerHTML = '<button id="cta">Go</button>'
+    const handle = renderV2Flow(
+      configWith([{ type: 'tooltip', selector: '#cta', placement: 'bottom' }]),
+      root,
+    )
+    expect(handle).not.toBeNull()
+    expect(root.querySelector('.om2-tooltip')).not.toBeNull()
+    expect(root.querySelector('.om2-overlay')).toBeNull()
+  })
+
+  it('mounts a highlight step with both ring and tooltip', () => {
+    const root = setupShadowRoot()
+    document.body.innerHTML = '<button id="cta">Go</button>'
+    renderV2Flow(
+      configWith([{ type: 'highlight', selector: '#cta' }]),
+      root,
+    )
+    expect(root.querySelector('.om2-highlight')).not.toBeNull()
+    // Highlight steps still get an actionable card alongside the ring.
+    expect(root.querySelectorAll('.om2-tooltip, .om2-modal-card').length).toBeGreaterThanOrEqual(1)
+  })
+
+  it('falls back to centred card when tooltip selector misses', () => {
+    const root = setupShadowRoot()
+    document.body.innerHTML = '<div></div>'   // no #missing element
+    renderV2Flow(
+      configWith([{ type: 'tooltip', selector: '#missing' }]),
+      root,
+    )
+    // Tooltip card mounts even without a target.
+    const tooltip = root.querySelector('.om2-tooltip') as HTMLElement | null
+    expect(tooltip).not.toBeNull()
+  })
+
+  it('returns null and renders nothing when steps is empty', () => {
+    const root = setupShadowRoot()
+    const handle = renderV2Flow({ steps: [] }, root)
+    expect(handle).toBeNull()
+    expect(root.querySelector('.om2-tooltip')).toBeNull()
+  })
+
+  it('injects styles only once even when called multiple times', () => {
+    const root = setupShadowRoot()
+    renderV2Flow(configWith([{}]), root)
+    renderV2Flow(configWith([{}]), root)
+    const styles = root.querySelectorAll('style[data-onboardme-v2-styles]')
+    expect(styles.length).toBe(1)
+  })
+})
+
+describe('renderV2Flow — multi-step navigation', () => {
+  it('advances to the next step on Next click', () => {
+    const root = setupShadowRoot()
+    renderV2Flow(
+      configWith([
+        { title: 'First',  type: 'modal', actionType: 'next' },
+        { title: 'Second', type: 'modal', actionType: 'complete', actionLabel: 'Done' },
+      ]),
+      root,
+    )
+    expect(root.querySelector('.om2-title')?.textContent).toBe('First')
+
+    const primary = root.querySelector('.om2-btn-primary') as HTMLButtonElement
+    primary.click()
+
+    expect(root.querySelector('.om2-title')?.textContent).toBe('Second')
+  })
+
+  it('tears down all DOM when the last step is completed', () => {
+    const root = setupShadowRoot()
+    renderV2Flow(
+      configWith([{ type: 'modal', actionType: 'complete', actionLabel: 'Done' }]),
+      root,
+    )
+    expect(root.querySelector('.om2-modal-card')).not.toBeNull()
+
+    const primary = root.querySelector('.om2-btn-primary') as HTMLButtonElement
+    primary.click()
+
+    expect(root.querySelector('.om2-modal-card')).toBeNull()
+    expect(root.querySelector('.om2-overlay')).toBeNull()
+  })
+
+  it('skip button removes everything immediately, mid-flow', () => {
+    const root = setupShadowRoot()
+    renderV2Flow(
+      configWith([
+        { title: 'First',  type: 'modal' },
+        { title: 'Second', type: 'modal' },
+      ]),
+      root,
+    )
+    // Skip is rendered when more than one step remains AND not the last step.
+    const skipBtn = Array.from(root.querySelectorAll('.om2-btn-secondary')).find(
+      (b) => b.textContent === 'Skip',
+    ) as HTMLButtonElement | undefined
+    expect(skipBtn).toBeDefined()
+    skipBtn!.click()
+
+    expect(root.querySelector('.om2-modal-card')).toBeNull()
+  })
+
+  it('shows a step counter (n / total)', () => {
+    const root = setupShadowRoot()
+    renderV2Flow(configWith([{}, {}, {}]), root)
+    expect(root.querySelector('.om2-step-counter')?.textContent).toBe('1 / 3')
+  })
+
+  it('handle.destroy() removes everything', () => {
+    const root = setupShadowRoot()
+    const handle = renderV2Flow(configWith([{ type: 'modal' }]), root)
+    expect(handle).not.toBeNull()
+    handle!.destroy()
+    expect(root.querySelector('.om2-modal-card')).toBeNull()
+    // Calling destroy a second time is safe (no throw).
+    handle!.destroy()
+  })
+})
+
+describe('renderV2Flow — action labels', () => {
+  it('uses the configured action label on the primary button', () => {
+    const root = setupShadowRoot()
+    renderV2Flow(
+      configWith([{ type: 'modal', actionType: 'next', actionLabel: 'Got it' }]),
+      root,
+    )
+    const primary = root.querySelector('.om2-btn-primary') as HTMLButtonElement
+    expect(primary.textContent).toBe('Got it')
+  })
+})

package/src/__tests__/v2-types.test.ts

@@ -0,0 +1,74 @@
+import { describe, it, expect } from 'vitest'
+import { isV2FlowConfig } from '../v2/types'
+
+const validV2Step = (overrides: Record<string, unknown> = {}) => ({
+  id: 'step-1',
+  title: 'T',
+  description: 'D',
+  type: 'modal',
+  position: { selector: 'body', placement: 'center' },
+  action: { type: 'next', label: 'Next' },
+  ...overrides,
+})
+
+describe('isV2FlowConfig', () => {
+  it('returns true for a valid v2 config', () => {
+    expect(isV2FlowConfig({ steps: [validV2Step()] })).toBe(true)
+  })
+
+  it('returns true for v2 with three step types', () => {
+    expect(isV2FlowConfig({
+      steps: [
+        validV2Step({ type: 'tooltip', position: { selector: '.x', placement: 'bottom' } }),
+        validV2Step({ id: 's2', type: 'highlight' }),
+        validV2Step({ id: 's3' }),
+      ],
+    })).toBe(true)
+  })
+
+  it('returns false for null / non-object', () => {
+    expect(isV2FlowConfig(null)).toBe(false)
+    expect(isV2FlowConfig(undefined)).toBe(false)
+    expect(isV2FlowConfig('x')).toBe(false)
+    expect(isV2FlowConfig(42)).toBe(false)
+  })
+
+  it('returns false when steps is missing or empty', () => {
+    expect(isV2FlowConfig({})).toBe(false)
+    expect(isV2FlowConfig({ steps: [] })).toBe(false)
+    expect(isV2FlowConfig({ steps: 'x' })).toBe(false)
+  })
+
+  it('returns false for legacy schema (body + primaryCta + targetSelector)', () => {
+    const legacy = {
+      steps: [{
+        id: 'step-1',
+        type: 'modal',
+        order: 0,
+        title: 'Welcome',
+        body: 'Get started',                  // ← legacy: body, not description
+        targetSelector: 'body',                // ← legacy: targetSelector, not position
+        primaryCta: 'Next',                    // ← legacy: primaryCta, not action
+      }],
+    }
+    expect(isV2FlowConfig(legacy)).toBe(false)
+  })
+
+  it('returns false when position is missing required fields', () => {
+    expect(isV2FlowConfig({
+      steps: [validV2Step({ position: { placement: 'center' } })],   // no selector
+    })).toBe(false)
+    expect(isV2FlowConfig({
+      steps: [validV2Step({ position: { selector: 'body' } })],      // no placement
+    })).toBe(false)
+  })
+
+  it('returns false when action is missing required fields', () => {
+    expect(isV2FlowConfig({
+      steps: [validV2Step({ action: { label: 'Go' } })],   // no type
+    })).toBe(false)
+    expect(isV2FlowConfig({
+      steps: [validV2Step({ action: { type: 'next' } })],  // no label
+    })).toBe(false)
+  })
+})

package/src/__tests__/week2-day1.test.ts

@@ -0,0 +1,62 @@
+import { beforeEach, describe, expect, it } from 'vitest';
+import { getShadowRoot } from '../components/shadow-host.js';
+
+describe('Week 2 Day 1 — Shadow DOM container (shadow-host.ts)', () => {
+  beforeEach(() => {
+    // Reset DOM between tests
+    document.body.innerHTML = '';
+  });
+
+  it('appends #onboardme-root to document.body', () => {
+    getShadowRoot();
+    expect(document.getElementById('onboardme-root')).not.toBeNull();
+  });
+
+  it('attaches an open Shadow DOM to #onboardme-root', () => {
+    const shadow = getShadowRoot();
+    expect(shadow).toBeInstanceOf(ShadowRoot);
+    expect(shadow.mode).toBe('open');
+  });
+
+  it('injects a <style> placeholder inside the shadow root', () => {
+    const shadow = getShadowRoot();
+    const style = shadow.querySelector('style');
+    expect(style).not.toBeNull();
+    expect(style?.dataset['onboardme']).toBe('styles');
+  });
+
+  it('returns the same shadow root on repeated calls (no duplicate host)', () => {
+    const first = getShadowRoot();
+    const second = getShadowRoot();
+    expect(first).toBe(second);
+    expect(document.querySelectorAll('#onboardme-root').length).toBe(1);
+  });
+
+  it('does not create a second #onboardme-root if called multiple times', () => {
+    getShadowRoot();
+    getShadowRoot();
+    getShadowRoot();
+    expect(document.querySelectorAll('#onboardme-root').length).toBe(1);
+  });
+
+  it('shadow root is isolated — a style added to body does not appear inside shadow root', () => {
+    const shadow = getShadowRoot();
+    // Add a style to the host document body (outside shadow)
+    const hostStyle = document.createElement('style');
+    hostStyle.textContent = '.host-class { color: red; }';
+    document.head.appendChild(hostStyle);
+
+    // The shadow root should only contain the placeholder style, not the host one
+    const shadowStyles = shadow.querySelectorAll('style');
+    const hasHostStyle = Array.from(shadowStyles).some(
+      (s) => s.textContent === '.host-class { color: red; }',
+    );
+    expect(hasHostStyle).toBe(false);
+  });
+
+  it('host element is a direct child of document.body', () => {
+    getShadowRoot();
+    const host = document.getElementById('onboardme-root');
+    expect(host?.parentElement).toBe(document.body);
+  });
+});

package/src/__tests__/week2-day2.test.ts

@@ -0,0 +1,128 @@
+import { beforeEach, describe, expect, it } from 'vitest';
+import { getShadowRoot } from '../components/shadow-host.js';
+import { renderModal } from '../components/modal.js';
+import type { FlowStep } from '@onboardme/types';
+
+// Minimal valid FlowStep for testing
+function makeStep(overrides: Partial<FlowStep> = {}): FlowStep {
+  return {
+    id: 'step-1',
+    type: 'modal',
+    order: 1,
+    title: 'Welcome to Acme',
+    body: 'Let us show you around.',
+    trigger: { type: 'page_load' },
+    dismissible: true,
+    ...overrides,
+  };
+}
+
+describe('Week 2 Day 2 — Modal HTML structure (modal.ts)', () => {
+  let shadow: ShadowRoot;
+
+  beforeEach(() => {
+    document.body.innerHTML = '';
+    shadow = getShadowRoot();
+  });
+
+  // --- DOM structure ---
+
+  it('renders an overlay element inside the shadow root', () => {
+    renderModal(makeStep(), shadow);
+    expect(shadow.querySelector('[data-onboardme="overlay"]')).not.toBeNull();
+  });
+
+  it('overlay has class om-overlay', () => {
+    renderModal(makeStep(), shadow);
+    expect(shadow.querySelector('.om-overlay')).not.toBeNull();
+  });
+
+  it('renders a modal card with class om-modal inside the overlay', () => {
+    renderModal(makeStep(), shadow);
+    const overlay = shadow.querySelector('.om-overlay');
+    expect(overlay?.querySelector('.om-modal')).not.toBeNull();
+  });
+
+  it('modal has role="dialog" and aria-modal="true"', () => {
+    renderModal(makeStep(), shadow);
+    const modal = shadow.querySelector('.om-modal');
+    expect(modal?.getAttribute('role')).toBe('dialog');
+    expect(modal?.getAttribute('aria-modal')).toBe('true');
+  });
+
+  // --- Content ---
+
+  it('renders step.title as the modal heading text', () => {
+    renderModal(makeStep({ title: 'Hello World' }), shadow);
+    expect(shadow.querySelector('.om-modal__title')?.textContent).toBe('Hello World');
+  });
+
+  it('renders step.body as the modal body text', () => {
+    renderModal(makeStep({ body: 'This is the body.' }), shadow);
+    expect(shadow.querySelector('.om-modal__body')?.textContent).toBe('This is the body.');
+  });
+
+  // --- CTA defaults ---
+
+  it('uses "Get started" as primary CTA when step.primaryCta is absent', () => {
+    renderModal(makeStep(), shadow);
+    const btn = shadow.querySelector<HTMLButtonElement>('[data-onboardme="primary-cta"]');
+    expect(btn?.textContent).toBe('Get started');
+  });
+
+  it('uses step.primaryCta when provided', () => {
+    renderModal(makeStep({ primaryCta: 'Start tour' }), shadow);
+    const btn = shadow.querySelector('[data-onboardme="primary-cta"]');
+    expect(btn?.textContent).toBe('Start tour');
+  });
+
+  it('uses "Skip for now" as skip label when step.secondaryCta is absent', () => {
+    renderModal(makeStep(), shadow);
+    const btn = shadow.querySelector('[data-onboardme="skip-cta"]');
+    expect(btn?.textContent).toBe('Skip for now');
+  });
+
+  it('uses step.secondaryCta when provided', () => {
+    renderModal(makeStep({ secondaryCta: 'Maybe later' }), shadow);
+    const btn = shadow.querySelector('[data-onboardme="skip-cta"]');
+    expect(btn?.textContent).toBe('Maybe later');
+  });
+
+  // --- Dismissible flag ---
+
+  it('renders the skip button when dismissible is true', () => {
+    renderModal(makeStep({ dismissible: true }), shadow);
+    expect(shadow.querySelector('[data-onboardme="skip-cta"]')).not.toBeNull();
+  });
+
+  it('hides the skip button when dismissible is false', () => {
+    renderModal(makeStep({ dismissible: false }), shadow);
+    expect(shadow.querySelector('[data-onboardme="skip-cta"]')).toBeNull();
+  });
+
+  it('renders the skip button when dismissible is omitted (default true)', () => {
+    const step = makeStep();
+    delete (step as Partial<FlowStep>).dismissible;
+    renderModal(step, shadow);
+    expect(shadow.querySelector('[data-onboardme="skip-cta"]')).not.toBeNull();
+  });
+
+  // --- CSS injection ---
+
+  it('populates the placeholder <style> element with modal CSS', () => {
+    renderModal(makeStep(), shadow);
+    const style = shadow.querySelector<HTMLStyleElement>('style[data-onboardme="styles"]');
+    expect(style?.textContent).toBeTruthy();
+    expect(style?.textContent).toContain('.om-overlay');
+    expect(style?.textContent).toContain('.om-modal');
+  });
+
+  it('does not inject styles into the host document head', () => {
+    renderModal(makeStep(), shadow);
+    const hostStyles = document.head.querySelectorAll('style');
+    const leaked = Array.from(hostStyles).some(
+      (s) => s.textContent?.includes('.om-overlay'),
+    );
+    expect(leaked).toBe(false);
+  });
+});