@diabolic/pointy 1.1.0 → 1.2.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
@@ -64,11 +65,67 @@ pointy.show();
 {
   target: '#element',           // CSS selector or HTMLElement
   content: 'Message',           // String, HTML, array, or React element
-  direction: 'up',              // 'up', 'down', or null (auto)
+  direction: 'up-left',         // Direction preset or null (auto)
   duration: 3000                // Step-specific autoplay duration (ms)
 }
 ```
 
+### 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; margin: 4px 0;">
+    <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 and flexible multi-line text layout!</span>
+  </div>
+` }
+
+// Multiple messages (auto-cycles)
+{ target: '#el', content: ['First message', 'Second message', 'Third message'] }
+
+// React/JSX element (if using React)
+{ target: '#el', content: <MyCustomComponent /> }
+```
+
+### Direction Presets
+
+Control the pointer and bubble direction manually:
+
+| Direction | Description |
+|-----------|-------------|
+| `null` | Auto (default) - automatically adjusts based on viewport |
+| `'up'` | Pointer points up, bubble below target |
+| `'down'` | Pointer points down, bubble above target |
+| `'left'` | Bubble on left side of target |
+| `'right'` | Bubble on right side of target |
+| `'up-left'` | Pointer up, bubble on left |
+| `'up-right'` | Pointer up, bubble on right |
+| `'down-left'` | Pointer down, bubble on left |
+| `'down-right'` | Pointer down, bubble on right |
+
+```javascript
+// In steps
+{ target: '#el', content: 'Hello', direction: 'down-right' }
+
+// Runtime
+pointy.setDirection('up-left');           // Both axes
+pointy.setHorizontalDirection('right');   // Only horizontal
+pointy.setVerticalDirection('down');      // Only vertical
+pointy.setDirection(null);                // Reset to auto
+
+// pointTo with direction
+pointy.pointTo('#element', 'Message', 'down-left');
+```
+
 ### Animation
 
 | Option | Type | Default | Description |
@@ -100,6 +157,15 @@ pointy.show();
 | `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 |
@@ -192,6 +258,12 @@ pointy.setOffset(30, 20);
 pointy.setInitialPosition('top-left');
 pointy.setInitialPositionOffset(50);
 pointy.setZIndex(10000);
+pointy.setStayInViewport(true, { x: 50, y: 80 }); // Auto-flip with custom thresholds
+
+// Direction
+pointy.setDirection('up-left');           // Set both directions
+pointy.setHorizontalDirection('right');   // Only horizontal (left/right/null)
+pointy.setVerticalDirection('down');      // Only vertical (up/down/null)
 
 // Tracking
 pointy.setTracking(true);
@@ -211,6 +283,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
@@ -297,6 +373,15 @@ pointy.on('all', (data) => {
 | `moveComplete` | `{ index, step, target }` |
 | `introAnimationStart` | `{ duration, initialPosition }` |
 | `introAnimationEnd` | `{ initialPosition }` |
+| `flipHorizontal` | `{ from: 'left'\|'right', to: 'left'\|'right' }` |
+| `flipVertical` | `{ from: 'up'\|'down', to: 'up'\|'down' }` |
+
+#### Direction
+| Event | Data |
+|-------|------|
+| `directionChange` | `{ from: { horizontal, vertical }, to: { horizontal, vertical } }` |
+| `horizontalDirectionChange` | `{ from, to }` |
+| `verticalDirectionChange` | `{ from, to }` |
 
 #### Content
 | Event | Data |
@@ -339,9 +424,27 @@ pointy.on('all', (data) => {
 | `autoplayNext` | `{ fromIndex, duration?, afterMessages? }` |
 | `autoplayComplete` | `{ totalSteps }` |
 | `autoHide` | `{ delay, source }` |
+| `autoplayChange` | `{ from, to }` |
+| `autoplayWaitForMessagesChange` | `{ from, to }` |
+
+#### Viewport
+| Event | 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
 
@@ -349,9 +452,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);
 }
 ```
 
@@ -436,6 +546,26 @@ 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');
+```
+
 ### 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,