@diabolic/pointy 1.1.1 → 1.3.0

package/README.md

@@ -13,7 +13,8 @@ A lightweight, dependency-free JavaScript library for creating animated tooltips
 - 📝 **Multi-step Tours** - Create guided product tours with multiple steps
 - 💬 **Multi-message Steps** - Each step can have multiple messages that auto-cycle
 - 🎬 **Autoplay Mode** - Automatically advance through steps
-- 🎨 **Customizable Styling** - CSS variables, custom class names, and SVG support
+- 🎨 **Customizable Styling** - CSS variables, custom class names, SVG support, and color theming
+- 🎨 **Color Theming** - Customize pointer, bubble background, and text colors
 - 📍 **Target Tracking** - Follows target elements in real-time
 - ⚛️ **React Compatible** - Supports JSX/React elements as content
 - 🔗 **Event System** - Comprehensive events with group listeners
@@ -69,6 +70,47 @@ pointy.show();
 }
 ```
 
+### Content Types
+
+Pointy supports multiple content formats:
+
+```javascript
+// Plain text
+{ target: '#el', content: 'Simple message' }
+
+// HTML string with custom layout
+{ target: '#el', content: `
+  <div style="display: flex; gap: 10px; align-items: flex-start; max-width: 260px;">
+    <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+      <circle cx="12" cy="12" r="10"/>
+      <path d="M12 16v-4M12 8h.01"/>
+    </svg>
+    <span style="line-height: 1.4;">Custom tooltip with icon!</span>
+  </div>
+` }
+
+// Multiple messages (auto-cycles with messageInterval)
+{ target: '#el', content: ['First message', 'Second message', 'Third message'] }
+
+// React/JSX element (requires React & ReactDOM)
+{ target: '#el', content: (
+  <div style={{ display: 'flex', gap: '10px', alignItems: 'flex-start' }}>
+    <svg width={20} height={20} viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth={2}>
+      <circle cx={12} cy={12} r={10} />
+      <path d="M12 16v-4" />
+    </svg>
+    <span>React element with SVG!</span>
+  </div>
+) }
+
+// Array of React elements
+{ target: '#el', content: [
+  <span>First React message</span>,
+  <strong>Second React message</strong>,
+  <em>Third React message</em>
+] }
+```
+
 ### Direction Presets
 
 Control the pointer and bubble direction manually:
@@ -96,7 +138,7 @@ pointy.setVerticalDirection('down');      // Only vertical
 pointy.setDirection(null);                // Reset to auto
 
 // pointTo with direction
-pointy.pointTo('#element', 'Message', 'down-left');
+pointy.pointTo('#element', 'Message', { direction: 'down-left' });
 ```
 
 ### Animation
@@ -130,6 +172,15 @@ pointy.pointTo('#element', 'Message', 'down-left');
 | `autoplayWaitForMessages` | `boolean` | `true` | Wait for all messages |
 | `messageInterval` | `number\|null` | `null` | Message auto-cycle interval (ms) |
 
+### Styling
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `pointerColor` | `string` | `null` | Pointer/cursor color (CSS color) |
+| `bubbleBackgroundColor` | `string` | `null` | Bubble background color (CSS color) |
+| `bubbleTextColor` | `string` | `null` | Bubble text color (CSS color) |
+| `bubbleMaxWidth` | `string` | `'min(400px, 90vw)'` | Maximum bubble width (CSS value) |
+
 ### Completion
 
 | Option | Type | Default | Description |
@@ -180,10 +231,34 @@ pointy.goToMessage(index);
 
 ### Point to Custom Target
 
+Temporarily point to any element without changing the current step:
+
 ```javascript
+// Basic usage
 pointy.pointTo('#element');
 pointy.pointTo('#element', 'Custom message');
-pointy.pointTo('#element', 'Message', 'down');
+
+// With options
+pointy.pointTo('#element', 'Message', {
+  direction: 'down',      // 'up', 'down', 'left', 'right', 'up-left', etc.
+  autoplay: true,         // Auto-cycle through messages (if array)
+  interval: 2000,         // Message cycle interval in ms
+  cycle: true             // Loop messages (true) or stop at last (false)
+});
+
+// Array of messages with autoplay
+pointy.pointTo('#element', [
+  'First tip',
+  'Second tip', 
+  'Third tip'
+], { autoplay: true, interval: 2500 });
+
+// Stop at last message (no loop)
+pointy.pointTo('#element', ['Step 1', 'Step 2', 'Done!'], {
+  autoplay: true,
+  interval: 2000,
+  cycle: false  // Stops at 'Done!'
+});
 ```
 
 ### Autoplay Control
@@ -247,6 +322,10 @@ pointy.setHideOnCompleteDelay(500);
 
 // Styling
 pointy.setPointerSvg('<svg>...</svg>');
+pointy.setPointerColor('#ff6600');           // Pointer color
+pointy.setBubbleBackgroundColor('#1a1a2e');  // Bubble background
+pointy.setBubbleTextColor('#ffffff');        // Bubble text
+pointy.setBubbleMaxWidth('300px');           // Max bubble width
 ```
 
 ## Easing Presets
@@ -353,11 +432,11 @@ pointy.on('all', (data) => {
 #### Message Cycle
 | Event | Data |
 |-------|------|
-| `messageCycleStart` | `{ interval, totalMessages }` |
+| `messageCycleStart` | `{ interval, totalMessages, cycle }` |
 | `messageCycleStop` | `{ currentIndex }` |
 | `messageCyclePause` | `{ currentIndex }` |
 | `messageCycleResume` | `{ currentIndex }` |
-| `messageCycleComplete` | `{ stepIndex, totalMessages }` |
+| `messageCycleComplete` | `{ stepIndex?, totalMessages }` |
 
 #### Pointing
 | Event | Data |
@@ -393,7 +472,18 @@ pointy.on('all', (data) => {
 | `stayInViewportChange` | `{ from: { enabled, x, y }, to: { enabled, x, y } }` |
 
 #### Config
-All setter methods emit `*Change` events with `{ from, to }` data.
+All setter methods emit `*Change` events with `{ from, to }` data:
+
+| Event | Description |
+|-------|-------------|
+| `pointerColorChange` | Pointer color changed |
+| `bubbleBackgroundColorChange` | Bubble background color changed |
+| `bubbleTextColorChange` | Bubble text color changed |
+| `bubbleMaxWidthChange` | Bubble max width changed |
+| `easingChange` | Easing preset changed |
+| `animationDurationChange` | Animation duration changed |
+| `floatingAnimationChange` | Floating animation toggled |
+| ... | (and more for all setters) |
 
 ## CSS Customization
 
@@ -401,9 +491,16 @@ All setter methods emit `*Change` events with `{ from, to }` data.
 
 ```css
 .pointy-container {
+  /* Animation */
   --pointy-duration: 1000ms;
   --pointy-easing: cubic-bezier(0, 0.55, 0.45, 1);
   --pointy-bubble-fade: 500ms;
+  
+  /* Colors */
+  --pointy-pointer-color: #0a1551;
+  --pointy-bubble-bg: #0a1551;
+  --pointy-bubble-color: white;
+  --pointy-bubble-max-width: min(400px, 90vw);
 }
 ```
 
@@ -488,6 +585,62 @@ const tour = new Pointy({
 tour.show();
 ```
 
+### Custom Theming
+
+```javascript
+const tour = new Pointy({
+  steps: [
+    { target: '#feature', content: 'Check out this feature!' }
+  ],
+  pointerColor: '#ff6600',
+  bubbleBackgroundColor: '#1a1a2e',
+  bubbleTextColor: '#ffffff',
+  bubbleMaxWidth: '300px'
+});
+
+tour.show();
+
+// Or change colors at runtime
+tour.setPointerColor('#00ff88');
+tour.setBubbleBackgroundColor('#2d2d44');
+```
+
+### React/JSX Content
+
+```jsx
+// With React loaded via CDN or bundler
+const tour = new Pointy({
+  steps: [{
+    target: '#feature',
+    content: (
+      <div style={{ display: 'flex', gap: '10px', alignItems: 'flex-start' }}>
+        <svg 
+          width={20} height={20} viewBox="0 0 24 24"
+          fill="none" stroke="currentColor" strokeWidth={2}
+          strokeLinecap="round" strokeLinejoin="round"
+        >
+          <path d="M12 22c5.523 0 10-4.477 10-10S17.523 2 12 2 2 6.477 2 12s4.477 10 10 10z" />
+          <path d="M12 16v-4" />
+          <path d="M12 8h.01" />
+        </svg>
+        <span>React element with info icon!</span>
+      </div>
+    )
+  }]
+});
+
+tour.show();
+
+// Or with pointTo and autoplay
+const messages = [
+  <span>First tip</span>,
+  <strong>Important tip!</strong>,
+  <em>Final tip</em>
+];
+
+tour.pointTo('#element', messages, { autoplay: true, interval: 2000 });
+```
+
 ### Autoplay Tour
 
 ```javascript

package/dist/pointy.d.ts

@@ -7,6 +7,31 @@ declare module '@diabolic/pointy' {
   export = Pointy;
 }
 
+/**
+ * Direction presets for pointer positioning
+ */
+type PointyDirection = 'up' | 'down' | 'left' | 'right' | 'up-left' | 'up-right' | 'down-left' | 'down-right' | null;
+
+/**
+ * Horizontal direction
+ */
+type PointyHorizontalDirection = 'left' | 'right' | null;
+
+/**
+ * Vertical direction
+ */
+type PointyVerticalDirection = 'up' | 'down' | null;
+
+/**
+ * Viewport threshold configuration
+ */
+interface PointyViewportThresholds {
+  /** Horizontal margin from viewport edge to trigger flip (default: 40) */
+  x?: number;
+  /** Vertical margin from viewport edge to trigger flip (default: 60) */
+  y?: number;
+}
+
 /**
  * Step configuration for tour steps
  */
@@ -15,8 +40,8 @@ interface PointyStep {
   target: string | HTMLElement;
   /** Content to display - can be string, HTML, array of messages, or React element */
   content: string | string[] | React.ReactNode | React.ReactNode[];
-  /** Pointer direction: 'up', 'down', or null for auto */
-  direction?: 'up' | 'down' | null;
+  /** Pointer direction: 'up', 'down', 'left', 'right', 'up-left', 'up-right', 'down-left', 'down-right', or null for auto */
+  direction?: PointyDirection;
   /** Step-specific autoplay duration in ms (overrides global autoplay) */
   duration?: number;
 }
@@ -110,6 +135,10 @@ interface PointyOptions {
   /** Enable floating/bobbing animation (default: true) */
   floatingAnimation?: boolean;
 
+  // Viewport
+  /** Auto-flip bubble to stay within viewport (default: true). Can be boolean or threshold config */
+  stayInViewport?: boolean | PointyViewportThresholds;
+
   // Position
   /** Horizontal offset from target in px (default: 20) */
   offsetX?: number;
@@ -159,6 +188,14 @@ interface PointyOptions {
   cssVarPrefix?: string;
   /** Custom SVG markup for pointer or React element */
   pointerSvg?: string | React.ReactNode;
+  /** Custom bubble background color (CSS color value) */
+  bubbleBackgroundColor?: string;
+  /** Custom bubble text color (CSS color value) */
+  bubbleTextColor?: string;
+  /** Maximum width for bubble (CSS width value, default: 'min(400px, 90vw)') */
+  bubbleMaxWidth?: string;
+  /** Custom pointer/cursor color (CSS color value) */
+  pointerColor?: string;
 
   // Callbacks
   /** Called when step changes */
@@ -247,10 +284,34 @@ interface PointyMessageCycleEventData extends PointyEventData {
 interface PointyPointingEventData extends PointyEventData {
   target?: HTMLElement;
   content?: string | string[];
-  direction?: 'up' | 'down' | null;
+  direction?: PointyDirection;
   fromTarget?: HTMLElement;
 }
 
+/**
+ * Flip event data (when bubble flips due to viewport bounds)
+ */
+interface PointyFlipEventData extends PointyEventData {
+  from: 'left' | 'right' | 'up' | 'down';
+  to: 'left' | 'right' | 'up' | 'down';
+}
+
+/**
+ * Direction change event data
+ */
+interface PointyDirectionChangeEventData extends PointyEventData {
+  from: { horizontal: PointyHorizontalDirection; vertical: PointyVerticalDirection };
+  to: { horizontal: PointyHorizontalDirection; vertical: PointyVerticalDirection };
+}
+
+/**
+ * Viewport change event data
+ */
+interface PointyViewportChangeEventData extends PointyEventData {
+  from: { enabled: boolean; x: number; y: number };
+  to: { enabled: boolean; x: number; y: number };
+}
+
 /**
  * Tracking event data
  */
@@ -291,15 +352,17 @@ type PointyEventCallback<T = PointyEventData> = (data: T) => void;
  */
 type PointyLifecycleEvent = 'beforeShow' | 'show' | 'beforeHide' | 'hide' | 'destroy' | 'beforeRestart' | 'restart' | 'beforeReset' | 'reset';
 type PointyNavigationEvent = 'beforeStepChange' | 'stepChange' | 'next' | 'prev' | 'complete';
-type PointyAnimationEvent = 'animationStart' | 'animationEnd' | 'move' | 'moveComplete' | 'introAnimationStart' | 'introAnimationEnd';
+type PointyAnimationEvent = 'animationStart' | 'animationEnd' | 'move' | 'moveComplete' | 'introAnimationStart' | 'introAnimationEnd' | 'flipHorizontal' | 'flipVertical';
+type PointyDirectionEvent = 'directionChange' | 'horizontalDirectionChange' | 'verticalDirectionChange';
+type PointyViewportEvent = 'stayInViewportChange';
 type PointyContentEvent = 'contentSet' | 'messagesSet' | 'messageChange';
 type PointyMessageCycleEvent = 'messageCycleStart' | 'messageCycleStop' | 'messageCyclePause' | 'messageCycleResume' | 'messageCycleComplete';
 type PointyPointingEvent = 'beforePointTo' | 'pointTo' | 'pointToComplete';
 type PointyTrackingEvent = 'track' | 'targetChange' | 'trackingChange' | 'trackingFpsChange';
 type PointyAutoplayEvent = 'autoplayStart' | 'autoplayStop' | 'autoplayPause' | 'autoplayResume' | 'autoplayNext' | 'autoplayComplete' | 'autoHide' | 'autoplayChange' | 'autoplayWaitForMessagesChange';
-type PointyConfigEvent = 'easingChange' | 'animationDurationChange' | 'introFadeDurationChange' | 'bubbleFadeDurationChange' | 'messageIntervalChange' | 'messageTransitionDurationChange' | 'offsetChange' | 'resetOnCompleteChange' | 'hideOnCompleteChange' | 'hideOnCompleteDelayChange' | 'floatingAnimationChange' | 'initialPositionChange' | 'initialPositionOffsetChange' | 'pointerSvgChange';
+type PointyConfigEvent = 'easingChange' | 'animationDurationChange' | 'introFadeDurationChange' | 'bubbleFadeDurationChange' | 'bubbleBackgroundColorChange' | 'bubbleTextColorChange' | 'bubbleMaxWidthChange' | 'pointerColorChange' | 'messageIntervalChange' | 'messageTransitionDurationChange' | 'offsetChange' | 'resetOnCompleteChange' | 'hideOnCompleteChange' | 'hideOnCompleteDelayChange' | 'floatingAnimationChange' | 'initialPositionChange' | 'initialPositionOffsetChange' | 'pointerSvgChange' | 'zIndexChange';
 
-type PointyEvent = PointyLifecycleEvent | PointyNavigationEvent | PointyAnimationEvent | PointyContentEvent | PointyMessageCycleEvent | PointyPointingEvent | PointyTrackingEvent | PointyAutoplayEvent | PointyConfigEvent;
+type PointyEvent = PointyLifecycleEvent | PointyNavigationEvent | PointyAnimationEvent | PointyDirectionEvent | PointyViewportEvent | PointyContentEvent | PointyMessageCycleEvent | PointyPointingEvent | PointyTrackingEvent | PointyAutoplayEvent | PointyConfigEvent;
 
 /**
  * Event group names
@@ -313,6 +376,8 @@ interface PointyEventGroups {
   lifecycle: PointyLifecycleEvent[];
   navigation: PointyNavigationEvent[];
   animation: PointyAnimationEvent[];
+  direction: PointyDirectionEvent[];
+  viewport: PointyViewportEvent[];
   content: PointyContentEvent[];
   messageCycle: PointyMessageCycleEvent[];
   pointing: PointyPointingEvent[];
@@ -474,6 +539,22 @@ declare class Pointy {
   messageInterval: number | null;
   /** Current pointer SVG or React element */
   pointerSvg: string | React.ReactNode;
+  /** Custom bubble background color */
+  bubbleBackgroundColor: string | null;
+  /** Custom bubble text color */
+  bubbleTextColor: string | null;
+  /** Maximum width for bubble (default: min(400px, 90vw)) */
+  bubbleMaxWidth: string | null;
+  /** Custom pointer/cursor color */
+  pointerColor: string | null;
+
+  // Viewport properties
+  /** Whether to auto-flip bubble to stay in viewport */
+  stayInViewport: boolean;
+  /** Horizontal viewport threshold */
+  viewportThresholdX: number;
+  /** Vertical viewport threshold */
+  viewportThresholdY: number;
 
   // State properties (readonly)
   /** Whether pointer is currently visible */
@@ -486,8 +567,12 @@ declare class Pointy {
   readonly currentMessages: (string | React.ReactNode)[];
   /** Whether pointer is pointing up */
   readonly isPointingUp: boolean;
-  /** Manual direction override */
-  readonly manualDirection: 'up' | 'down' | null;
+  /** Whether pointer is on left side of target */
+  readonly isPointingLeft: boolean;
+  /** Manual horizontal direction override */
+  readonly manualHorizontalDirection: PointyHorizontalDirection;
+  /** Manual vertical direction override */
+  readonly manualVerticalDirection: PointyVerticalDirection;
 
   // Callbacks
   /** Step change callback */
@@ -532,9 +617,9 @@ declare class Pointy {
    * Point to any element without changing current step
    * @param target - Target element or CSS selector
    * @param content - Optional content to display
-   * @param direction - Optional direction: 'up', 'down', or null for auto
+   * @param direction - Optional direction: 'up', 'down', 'left', 'right', 'up-left', 'up-right', 'down-left', 'down-right', or null for auto
    */
-  pointTo(target: string | HTMLElement, content?: string | string[], direction?: 'up' | 'down' | null): void;
+  pointTo(target: string | HTMLElement, content?: string | string[], direction?: PointyDirection): void;
 
   // Content methods
   /**
@@ -650,6 +735,26 @@ declare class Pointy {
    * @param duration - Duration in milliseconds
    */
   setBubbleFadeDuration(duration: number): void;
+  /**
+   * Set the bubble background color
+   * @param color - CSS color value (hex, rgb, etc.) or null to reset
+   */
+  setBubbleBackgroundColor(color: string | null): void;
+  /**
+   * Set the bubble text color
+   * @param color - CSS color value (hex, rgb, etc.) or null to reset
+   */
+  setBubbleTextColor(color: string | null): void;
+  /**
+   * Set the bubble max width
+   * @param width - CSS width value (e.g., '90vw', '300px') or null to reset
+   */
+  setBubbleMaxWidth(width: string | null): void;
+  /**
+   * Set the pointer/cursor color
+   * @param color - CSS color value (hex, rgb, etc.) or null to reset
+   */
+  setPointerColor(color: string | null): void;
   /**
    * Set the message transition duration
    * @param duration - Duration in milliseconds
@@ -727,6 +832,32 @@ declare class Pointy {
    * @param svg - SVG markup string or React element
    */
   setPointerSvg(svg: string | React.ReactNode): void;
+  /**
+   * Set the z-index of the container
+   * @param zIndex - CSS z-index value
+   */
+  setZIndex(zIndex: number): void;
+  /**
+   * Set stayInViewport enabled/disabled with optional thresholds
+   * @param enabled - Whether stayInViewport is enabled
+   * @param thresholds - Optional threshold values { x?: number, y?: number }
+   */
+  setStayInViewport(enabled: boolean, thresholds?: PointyViewportThresholds): void;
+  /**
+   * Set the pointer direction manually (both horizontal and vertical)
+   * @param direction - Direction: 'up', 'down', 'left', 'right', 'up-left', 'up-right', 'down-left', 'down-right', or null for auto
+   */
+  setDirection(direction: PointyDirection): void;
+  /**
+   * Set only the horizontal direction
+   * @param direction - 'left', 'right', or null for auto
+   */
+  setHorizontalDirection(direction: PointyHorizontalDirection): void;
+  /**
+   * Set only the vertical direction
+   * @param direction - 'up', 'down', or null for auto
+   */
+  setVerticalDirection(direction: PointyVerticalDirection): void;
 
   // Getter methods
   /** Get current pointer SVG or React element */
@@ -825,6 +956,10 @@ export {
   PointyClassSuffixes,
   PointyInitialPosition,
   PointyEasing,
+  PointyDirection,
+  PointyHorizontalDirection,
+  PointyVerticalDirection,
+  PointyViewportThresholds,
   PointyEvent,
   PointyEventGroup,
   PointyEventGroups,
@@ -836,6 +971,11 @@ export {
   PointyNavigationEventData,
   PointyAnimationEvent,
   PointyAnimationEventData,
+  PointyDirectionEvent,
+  PointyDirectionChangeEventData,
+  PointyViewportEvent,
+  PointyViewportChangeEventData,
+  PointyFlipEventData,
   PointyContentEvent,
   PointyContentEventData,
   PointyMessageCycleEvent,