@ourroadmaps/web-sdk 0.3.0

package/README.md

@@ -0,0 +1,314 @@
+# @ourroadmaps/web-sdk
+
+Interactive overlay system and feedback widget for OurRoadmaps. Create guided walkthroughs, cursor animations, and annotations for prototypes and demos.
+
+## Quick Start
+
+### CDN (Recommended for Prototypes)
+
+```html
+<script src="https://unpkg.com/@ourroadmaps/web-sdk"></script>
+<script>
+  const { createOverlay } = OurRoadmaps;
+
+  const overlay = createOverlay();
+  overlay.play({
+    version: 1,
+    cursor: { name: 'Guide', color: '#6366f1' },
+    actions: [
+      { type: 'move', target: { selector: '#my-button' }, duration: 800 },
+      { type: 'click' },
+      { type: 'wait', duration: 1000 }
+    ]
+  });
+</script>
+```
+
+### npm
+
+```bash
+npm install @ourroadmaps/web-sdk
+```
+
+```javascript
+import { createOverlay } from '@ourroadmaps/web-sdk'
+
+const overlay = createOverlay()
+await overlay.play(script)
+```
+
+## Overlay System
+
+The overlay system provides cursor animations and annotations for creating guided walkthroughs.
+
+### Creating an Overlay
+
+```javascript
+const overlay = createOverlay({
+  cursor: {
+    name: 'Guide',      // Label shown next to cursor
+    color: '#6366f1',   // Cursor color
+    visible: true       // Initial visibility
+  },
+  annotations: {
+    color: '#ef4444',   // Default annotation color
+    strokeWidth: 3      // Default stroke width
+  },
+  zIndex: 9999          // Stack order
+})
+```
+
+### Script Format
+
+```javascript
+const script = {
+  version: 1,
+  cursor: { name: 'Guide', color: '#6366f1' },
+  annotations: { color: '#ef4444' },
+  actions: [
+    // Move cursor to element
+    { type: 'move', target: { selector: '#button' }, duration: 800 },
+
+    // Click at current position
+    { type: 'click' },
+
+    // Wait
+    { type: 'wait', duration: 2000 },
+
+    // Show annotations
+    {
+      type: 'showAnnotations',
+      annotations: [
+        { type: 'badge', target: { selector: '#step-1' }, number: 1 },
+        { type: 'label', target: { selector: '#step-1' }, text: 'Start here', position: 'right' }
+      ]
+    },
+
+    // Hide all annotations
+    { type: 'hideAnnotations' },
+
+    // Change cursor appearance
+    { type: 'setCursor', name: 'Done', color: '#22c55e' }
+  ]
+}
+```
+
+### Actions
+
+| Action | Description | Properties |
+|--------|-------------|------------|
+| `move` | Move cursor to target | `target`, `duration?` (default 600ms) |
+| `click` | Animate a click | `target?` (defaults to current position) |
+| `wait` | Pause playback | `duration` (ms) |
+| `showAnnotations` | Display annotations | `annotations[]` |
+| `hideAnnotations` | Remove annotations | `ids?` (specific IDs, or all if omitted) |
+| `setCursor` | Change cursor appearance | `visible?`, `name?`, `color?` |
+
+### Targeting
+
+Target elements using CSS selectors with optional anchor points:
+
+```javascript
+// Basic selector
+{ selector: '#my-element' }
+
+// With anchor point
+{ selector: '#my-element', anchor: 'top-right' }
+
+// With offset
+{ selector: '#my-element', anchor: 'center', offset: { x: 10, y: -5 } }
+
+// Fallback coordinates if element not found
+{ selector: '#my-element', fallback: { x: 100, y: 200 } }
+
+// Absolute coordinates
+{ x: 500, y: 300 }
+```
+
+Anchor options: `center`, `top`, `bottom`, `left`, `right`, `top-left`, `top-right`, `bottom-left`, `bottom-right`
+
+### Annotations
+
+#### Badge
+Numbered circle for step indicators:
+```javascript
+{ type: 'badge', target: { selector: '#step' }, number: 1, color: '#6366f1' }
+```
+
+#### Label
+Text callout with positioning:
+```javascript
+{
+  type: 'label',
+  target: { selector: '#element' },
+  text: 'Click here',
+  position: 'right',  // top, bottom, left, right, top-left, top-right, bottom-left, bottom-right
+  gap: 8              // Distance from target in pixels
+}
+```
+
+#### Box
+Highlight rectangle around element:
+```javascript
+{
+  type: 'box',
+  target: { selector: '#element' },
+  padding: 8,         // Extra space around element
+  dashed: true        // Dashed border style
+}
+```
+
+#### Circle
+Highlight ellipse around element:
+```javascript
+{ type: 'circle', target: { selector: '#element' }, padding: 12 }
+```
+
+#### Arrow
+Connecting line between two points:
+```javascript
+{
+  type: 'arrow',
+  from: { selector: '#start' },
+  to: { selector: '#end' }
+}
+```
+
+All annotations support:
+- `id` - Unique identifier for selective hiding
+- `color` - Override default color
+- `delay` - Milliseconds before appearing
+- `duration` - Auto-hide after milliseconds (0 = permanent)
+
+### Controller API
+
+```javascript
+const overlay = createOverlay()
+
+// Playback
+await overlay.play(script)    // Returns promise when complete
+overlay.stop()                // Stop playback
+overlay.isPlaying             // Current playback state
+overlay.currentActionIndex    // Current action (null if not playing)
+
+// Validation
+const result = overlay.validate(script)
+// { valid: boolean, errors: string[], warnings: string[] }
+
+// Events
+const unsubscribe = overlay.on('start', () => {})
+overlay.on('complete', () => {})
+overlay.on('stop', () => {})
+overlay.on('error', (error) => {})
+overlay.on('action', (action, index, phase) => {})
+
+// Direct cursor control
+overlay.cursor.moveTo({ selector: '#target' }, { duration: 500 })
+overlay.cursor.click()
+overlay.cursor.show()
+overlay.cursor.hide()
+overlay.cursor.setName('Helper')
+overlay.cursor.setColor('#22c55e')
+overlay.cursor.position   // { x, y } or null
+overlay.cursor.isVisible
+
+// Direct annotation control
+const id = overlay.annotations.badge({ selector: '#el' }, 1)
+overlay.annotations.label({ selector: '#el' }, 'Hello', { position: 'top' })
+overlay.annotations.box({ selector: '#el' })
+overlay.annotations.circle({ selector: '#el' })
+overlay.annotations.arrow({ selector: '#from' }, { selector: '#to' })
+overlay.annotations.hide(id)
+overlay.annotations.hideAll()
+overlay.annotations.activeIds  // Currently visible annotation IDs
+
+// Cleanup
+overlay.destroy()
+overlay.isDestroyed
+```
+
+### Error Handling
+
+```javascript
+overlay.on('error', (error) => {
+  console.log(error.code)     // ELEMENT_NOT_FOUND, ANIMATION_FAILED, etc.
+  console.log(error.message)  // Human-readable description
+  console.log(error.action)   // The action that failed
+  console.log(error.target)   // The target that couldn't be resolved
+})
+```
+
+Error codes:
+- `ELEMENT_NOT_FOUND` - CSS selector matched no elements
+- `ANIMATION_FAILED` - Animation couldn't complete
+- `SCROLL_FAILED` - Couldn't scroll element into view
+- `INVALID_SCRIPT` - Script failed validation
+- `INVALID_TARGET` - Target specification is malformed
+- `TIMEOUT` - Operation exceeded time limit
+
+## Feedback Widget
+
+The feedback widget displays a development-only feedback form.
+
+```javascript
+import { init, destroy } from '@ourroadmaps/web-sdk'
+
+// Initialize (only renders in development mode)
+init({ apiKey: 'your_api_key' })
+
+// Remove widget
+destroy()
+```
+
+The widget only renders when:
+- `NODE_ENV !== 'production'`
+- Running on `localhost` or `127.0.0.1`
+
+## Module Imports
+
+```javascript
+// Everything from main entry
+import { createOverlay, init, destroy } from '@ourroadmaps/web-sdk'
+
+// Just overlay
+import { createOverlay } from '@ourroadmaps/web-sdk/overlay'
+
+// Just feedback
+import { init, destroy } from '@ourroadmaps/web-sdk/feedback'
+```
+
+## CDN URLs
+
+```html
+<!-- Latest version (for prototypes) -->
+<script src="https://unpkg.com/@ourroadmaps/web-sdk"></script>
+
+<!-- Pinned version (for production) -->
+<script src="https://unpkg.com/@ourroadmaps/web-sdk@0.3.0"></script>
+
+<!-- Alternative: jsDelivr -->
+<script src="https://cdn.jsdelivr.net/npm/@ourroadmaps/web-sdk"></script>
+```
+
+The CDN build exposes `window.OurRoadmaps` with:
+- `createOverlay()` - Create overlay instance
+- `init()` - Initialize feedback widget
+- `destroy()` - Remove feedback widget
+
+## TypeScript
+
+Full type definitions included. Import types directly:
+
+```typescript
+import type {
+  OverlayScript,
+  OverlayController,
+  Action,
+  Annotation,
+  Target
+} from '@ourroadmaps/web-sdk'
+```
+
+## License
+
+Proprietary - OurRoadmaps

package/dist/chunk-4DE2IREA.cjs

@@ -0,0 +1,9 @@
+'use strict';
+
+var __defProp = Object.defineProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+
+exports.__publicField = __publicField;
+//# sourceMappingURL=chunk-4DE2IREA.cjs.map
+//# sourceMappingURL=chunk-4DE2IREA.cjs.map

package/dist/chunk-4DE2IREA.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"chunk-4DE2IREA.cjs"}