ui-sniper 3.0.9 → 3.1.0

package/dist/index.d.mts

@@ -1,6 +1,34 @@
 import * as react from 'react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 
+interface PIIRedactionConfig {
+    /**
+     * Whether PII redaction is enabled.
+     * When using the boolean shorthand `redactPII={true}`, all defaults apply.
+     */
+    enabled: boolean;
+    /**
+     * Additional CSS selectors whose matched elements will be visually blurred.
+     * Built-in selectors are always included when `enabled` is true:
+     *   `.patient-data`, `[data-pii]`, `[data-phi]`, `[data-sensitive]`
+     */
+    selectors?: string[];
+    /**
+     * Enable regex-based pattern scanning on text nodes.
+     * Matches: email addresses, phone numbers, US SSNs, credit card numbers.
+     * Matched text nodes are wrapped in a blur span during capture.
+     * Default: true
+     */
+    patterns?: boolean;
+    /**
+     * Also redact matched text from annotation string fields
+     * (comment, selectedText, nearbyText, fullPath).
+     * Replaced with `[REDACTED]` in markdown output.
+     * Default: true
+     */
+    redactOutput?: boolean;
+}
+
 type Annotation = {
     id: string;
     x: number;
@@ -81,6 +109,19 @@ type ThreadMessage = {
     content: string;
     timestamp: number;
 };
+/** Fired by the `onTelemetry` callback on key user actions. */
+type TelemetryEvent = {
+    /** What triggered the telemetry event */
+    trigger: "copy" | "submit" | "annotate" | "clear";
+    /** All annotations at the time of the event */
+    annotations: Annotation[];
+    /** The markdown output string (populated for copy/submit) */
+    output?: string;
+    /** Unix timestamp (ms) */
+    timestamp: number;
+    /** Current page URL */
+    pageUrl: string;
+};
 
 type DemoAnnotation = {
     selector: string;
@@ -115,10 +156,108 @@ type PageFeedbackToolbarCSSProps = {
     webhookUrl?: string;
     /** Custom class name applied to the toolbar container. Use to adjust positioning or z-index. */
     className?: string;
+    /**
+     * When true, hides the default floating trigger button/badge.
+     * Use with `useUISniper()` hook to build your own custom trigger UI.
+     * @example
+     * ```tsx
+     * <UISniper headless />
+     * // Anywhere in your tree:
+     * const { open } = useUISniper();
+     * ```
+     */
+    headless?: boolean;
+    /** Fired when the toolbar is activated (expanded). */
+    onActivate?: () => void;
+    /** Fired when the toolbar is deactivated (collapsed). */
+    onDeactivate?: () => void;
+    /**
+     * Called on key user actions (copy, submit, annotate, clear).
+     * Provides a structured event payload so you can capture telemetry
+     * without monkey-patching globals.
+     */
+    onTelemetry?: (event: TelemetryEvent) => void;
+    /**
+     * When true, failed webhook requests are queued in localStorage and
+     * automatically retried when the browser comes back online.
+     * Default: false
+     */
+    offlineQueue?: boolean;
+    /**
+     * localStorage key for the offline queue.
+     * Default: "ui-sniper-offline-queue"
+     */
+    offlineQueueKey?: string;
+    /**
+     * Enable PII/PHI redaction before screenshots are captured and in
+     * annotation text output.
+     *
+     * Pass `true` for defaults (blurs `.patient-data`, `[data-pii]`,
+     * `[data-phi]`, and pattern-matches emails/phones/SSNs).
+     * Or pass a `PIIRedactionConfig` object for fine-grained control.
+     *
+     * @example
+     * ```tsx
+     * <UISniper redactPII />
+     * <UISniper redactPII={{ selectors: ['.mrn', '.dob'], patterns: true }} />
+     * ```
+     */
+    redactPII?: boolean | PIIRedactionConfig;
+    /**
+     * Suppresses UI Sniper's own `[UI Sniper]`-prefixed console warnings
+     * in development mode. Also adds `suppressHydrationWarning` to the
+     * portal wrapper to silence Next.js hydration mismatch noise.
+     * Has no effect in production.
+     */
+    suppressDevWarnings?: boolean;
 };
 /** Alias for PageFeedbackToolbarCSSProps */
 type UISniperProps = PageFeedbackToolbarCSSProps;
-declare function PageFeedbackToolbarCSS({ demoAnnotations, demoDelay, enableDemoMode, onAnnotationAdd, onAnnotationDelete, onAnnotationUpdate, onAnnotationsClear, onCopy, onSubmit, copyToClipboard, endpoint, sessionId: initialSessionId, onSessionCreated, webhookUrl, className: userClassName, }?: PageFeedbackToolbarCSSProps): react.ReactPortal | null;
+declare function PageFeedbackToolbarCSS({ demoAnnotations, demoDelay, enableDemoMode, onAnnotationAdd, onAnnotationDelete, onAnnotationUpdate, onAnnotationsClear, onCopy, onSubmit, copyToClipboard, endpoint, sessionId: initialSessionId, onSessionCreated, webhookUrl, className: userClassName, headless, onActivate, onDeactivate, onTelemetry, offlineQueue, offlineQueueKey, redactPII, suppressDevWarnings, }?: PageFeedbackToolbarCSSProps): react.ReactPortal | null;
+
+interface UISniperContextValue {
+    /** Whether the toolbar is currently expanded/active */
+    isActive: boolean;
+    /** Open (activate) the toolbar */
+    open: () => void;
+    /** Close (deactivate) the toolbar */
+    close: () => void;
+    /** Toggle toolbar open/closed */
+    toggle: () => void;
+}
+declare const UISniperContext: react.Context<UISniperContextValue>;
+/**
+ * Access UISniper's programmatic API.
+ *
+ * Must be rendered inside the same React tree that contains a `<UISniper />`
+ * component. Combine with `headless` prop on `<UISniper />` to hide the
+ * default floating button and use your own custom trigger.
+ *
+ * @example
+ * ```tsx
+ * // In your layout (e.g. app/layout.tsx):
+ * <UISniper headless />
+ *
+ * // In any child component:
+ * const { open, isActive } = useUISniper();
+ * return <button onClick={open}>Give Feedback</button>;
+ * ```
+ */
+declare function useUISniper(): UISniperContextValue;
+
+interface ReviewPanelProps {
+    /** Annotations to review */
+    annotations: Annotation[];
+    /** Called when the panel should close */
+    onClose: () => void;
+    /** Called when user clicks "Jump to" on an annotation */
+    onJumpTo?: (annotation: Annotation) => void;
+    /** Called when user deletes an annotation from the panel */
+    onDelete?: (annotation: Annotation) => void;
+    /** Whether the panel is in dark or light mode */
+    isDarkMode?: boolean;
+}
+declare function ReviewPanel({ annotations, onClose, onJumpTo, onDelete, }: ReviewPanelProps): react_jsx_runtime.JSX.Element;
 
 interface AnnotationPopupCSSProps {
     /** Element name to display in header */
@@ -326,4 +465,4 @@ declare function getStorageKey(pathname: string): string;
 declare function loadAnnotations<T = Annotation>(pathname: string): T[];
 declare function saveAnnotations<T = Annotation>(pathname: string, annotations: T[]): void;
 
-export { AnimatedBunny, type Annotation, AnnotationPopupCSS, type AnnotationPopupCSSHandle, type AnnotationPopupCSSProps, type DemoAnnotation, IconChatEllipsis, IconCheck, IconCheckSmall, IconCheckSmallAnimated, IconCheckmark, IconCheckmarkCircle, IconCheckmarkLarge, IconChevronLeft, IconChevronRight, IconClose, IconCopyAlt, IconCopyAnimated, IconEdit, IconEye, IconEyeAlt, IconEyeAnimated, IconEyeClosed, IconEyeMinus, IconGear, IconHelp, IconLayout, IconListSparkle, IconMoon, IconPause, IconPauseAlt, IconPausePlayAnimated, IconPlayAlt, IconPlus, IconSendAnimated, IconSendArrow, IconSun, IconTarget, IconTrash, IconTrashAlt, IconXmark, IconXmarkLarge, PageFeedbackToolbarCSS, PageFeedbackToolbarCSS as UISniper, type UISniperProps, closestCrossingShadow, getElementClasses, getElementPath, getNearbyText, getShadowHost, getStorageKey, identifyAnimationElement, identifyElement, isInShadowDOM, loadAnnotations, saveAnnotations };
+export { AnimatedBunny, type Annotation, AnnotationPopupCSS, type AnnotationPopupCSSHandle, type AnnotationPopupCSSProps, type DemoAnnotation, IconChatEllipsis, IconCheck, IconCheckSmall, IconCheckSmallAnimated, IconCheckmark, IconCheckmarkCircle, IconCheckmarkLarge, IconChevronLeft, IconChevronRight, IconClose, IconCopyAlt, IconCopyAnimated, IconEdit, IconEye, IconEyeAlt, IconEyeAnimated, IconEyeClosed, IconEyeMinus, IconGear, IconHelp, IconLayout, IconListSparkle, IconMoon, IconPause, IconPauseAlt, IconPausePlayAnimated, IconPlayAlt, IconPlus, IconSendAnimated, IconSendArrow, IconSun, IconTarget, IconTrash, IconTrashAlt, IconXmark, IconXmarkLarge, type PIIRedactionConfig, PageFeedbackToolbarCSS, ReviewPanel, type ReviewPanelProps, type TelemetryEvent, PageFeedbackToolbarCSS as UISniper, UISniperContext, type UISniperContextValue, type UISniperProps, closestCrossingShadow, getElementClasses, getElementPath, getNearbyText, getShadowHost, getStorageKey, identifyAnimationElement, identifyElement, isInShadowDOM, loadAnnotations, saveAnnotations, useUISniper };

package/dist/index.d.ts

@@ -1,6 +1,34 @@
 import * as react from 'react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 
+interface PIIRedactionConfig {
+    /**
+     * Whether PII redaction is enabled.
+     * When using the boolean shorthand `redactPII={true}`, all defaults apply.
+     */
+    enabled: boolean;
+    /**
+     * Additional CSS selectors whose matched elements will be visually blurred.
+     * Built-in selectors are always included when `enabled` is true:
+     *   `.patient-data`, `[data-pii]`, `[data-phi]`, `[data-sensitive]`
+     */
+    selectors?: string[];
+    /**
+     * Enable regex-based pattern scanning on text nodes.
+     * Matches: email addresses, phone numbers, US SSNs, credit card numbers.
+     * Matched text nodes are wrapped in a blur span during capture.
+     * Default: true
+     */
+    patterns?: boolean;
+    /**
+     * Also redact matched text from annotation string fields
+     * (comment, selectedText, nearbyText, fullPath).
+     * Replaced with `[REDACTED]` in markdown output.
+     * Default: true
+     */
+    redactOutput?: boolean;
+}
+
 type Annotation = {
     id: string;
     x: number;
@@ -81,6 +109,19 @@ type ThreadMessage = {
     content: string;
     timestamp: number;
 };
+/** Fired by the `onTelemetry` callback on key user actions. */
+type TelemetryEvent = {
+    /** What triggered the telemetry event */
+    trigger: "copy" | "submit" | "annotate" | "clear";
+    /** All annotations at the time of the event */
+    annotations: Annotation[];
+    /** The markdown output string (populated for copy/submit) */
+    output?: string;
+    /** Unix timestamp (ms) */
+    timestamp: number;
+    /** Current page URL */
+    pageUrl: string;
+};
 
 type DemoAnnotation = {
     selector: string;
@@ -115,10 +156,108 @@ type PageFeedbackToolbarCSSProps = {
     webhookUrl?: string;
     /** Custom class name applied to the toolbar container. Use to adjust positioning or z-index. */
     className?: string;
+    /**
+     * When true, hides the default floating trigger button/badge.
+     * Use with `useUISniper()` hook to build your own custom trigger UI.
+     * @example
+     * ```tsx
+     * <UISniper headless />
+     * // Anywhere in your tree:
+     * const { open } = useUISniper();
+     * ```
+     */
+    headless?: boolean;
+    /** Fired when the toolbar is activated (expanded). */
+    onActivate?: () => void;
+    /** Fired when the toolbar is deactivated (collapsed). */
+    onDeactivate?: () => void;
+    /**
+     * Called on key user actions (copy, submit, annotate, clear).
+     * Provides a structured event payload so you can capture telemetry
+     * without monkey-patching globals.
+     */
+    onTelemetry?: (event: TelemetryEvent) => void;
+    /**
+     * When true, failed webhook requests are queued in localStorage and
+     * automatically retried when the browser comes back online.
+     * Default: false
+     */
+    offlineQueue?: boolean;
+    /**
+     * localStorage key for the offline queue.
+     * Default: "ui-sniper-offline-queue"
+     */
+    offlineQueueKey?: string;
+    /**
+     * Enable PII/PHI redaction before screenshots are captured and in
+     * annotation text output.
+     *
+     * Pass `true` for defaults (blurs `.patient-data`, `[data-pii]`,
+     * `[data-phi]`, and pattern-matches emails/phones/SSNs).
+     * Or pass a `PIIRedactionConfig` object for fine-grained control.
+     *
+     * @example
+     * ```tsx
+     * <UISniper redactPII />
+     * <UISniper redactPII={{ selectors: ['.mrn', '.dob'], patterns: true }} />
+     * ```
+     */
+    redactPII?: boolean | PIIRedactionConfig;
+    /**
+     * Suppresses UI Sniper's own `[UI Sniper]`-prefixed console warnings
+     * in development mode. Also adds `suppressHydrationWarning` to the
+     * portal wrapper to silence Next.js hydration mismatch noise.
+     * Has no effect in production.
+     */
+    suppressDevWarnings?: boolean;
 };
 /** Alias for PageFeedbackToolbarCSSProps */
 type UISniperProps = PageFeedbackToolbarCSSProps;
-declare function PageFeedbackToolbarCSS({ demoAnnotations, demoDelay, enableDemoMode, onAnnotationAdd, onAnnotationDelete, onAnnotationUpdate, onAnnotationsClear, onCopy, onSubmit, copyToClipboard, endpoint, sessionId: initialSessionId, onSessionCreated, webhookUrl, className: userClassName, }?: PageFeedbackToolbarCSSProps): react.ReactPortal | null;
+declare function PageFeedbackToolbarCSS({ demoAnnotations, demoDelay, enableDemoMode, onAnnotationAdd, onAnnotationDelete, onAnnotationUpdate, onAnnotationsClear, onCopy, onSubmit, copyToClipboard, endpoint, sessionId: initialSessionId, onSessionCreated, webhookUrl, className: userClassName, headless, onActivate, onDeactivate, onTelemetry, offlineQueue, offlineQueueKey, redactPII, suppressDevWarnings, }?: PageFeedbackToolbarCSSProps): react.ReactPortal | null;
+
+interface UISniperContextValue {
+    /** Whether the toolbar is currently expanded/active */
+    isActive: boolean;
+    /** Open (activate) the toolbar */
+    open: () => void;
+    /** Close (deactivate) the toolbar */
+    close: () => void;
+    /** Toggle toolbar open/closed */
+    toggle: () => void;
+}
+declare const UISniperContext: react.Context<UISniperContextValue>;
+/**
+ * Access UISniper's programmatic API.
+ *
+ * Must be rendered inside the same React tree that contains a `<UISniper />`
+ * component. Combine with `headless` prop on `<UISniper />` to hide the
+ * default floating button and use your own custom trigger.
+ *
+ * @example
+ * ```tsx
+ * // In your layout (e.g. app/layout.tsx):
+ * <UISniper headless />
+ *
+ * // In any child component:
+ * const { open, isActive } = useUISniper();
+ * return <button onClick={open}>Give Feedback</button>;
+ * ```
+ */
+declare function useUISniper(): UISniperContextValue;
+
+interface ReviewPanelProps {
+    /** Annotations to review */
+    annotations: Annotation[];
+    /** Called when the panel should close */
+    onClose: () => void;
+    /** Called when user clicks "Jump to" on an annotation */
+    onJumpTo?: (annotation: Annotation) => void;
+    /** Called when user deletes an annotation from the panel */
+    onDelete?: (annotation: Annotation) => void;
+    /** Whether the panel is in dark or light mode */
+    isDarkMode?: boolean;
+}
+declare function ReviewPanel({ annotations, onClose, onJumpTo, onDelete, }: ReviewPanelProps): react_jsx_runtime.JSX.Element;
 
 interface AnnotationPopupCSSProps {
     /** Element name to display in header */
@@ -326,4 +465,4 @@ declare function getStorageKey(pathname: string): string;
 declare function loadAnnotations<T = Annotation>(pathname: string): T[];
 declare function saveAnnotations<T = Annotation>(pathname: string, annotations: T[]): void;
 
-export { AnimatedBunny, type Annotation, AnnotationPopupCSS, type AnnotationPopupCSSHandle, type AnnotationPopupCSSProps, type DemoAnnotation, IconChatEllipsis, IconCheck, IconCheckSmall, IconCheckSmallAnimated, IconCheckmark, IconCheckmarkCircle, IconCheckmarkLarge, IconChevronLeft, IconChevronRight, IconClose, IconCopyAlt, IconCopyAnimated, IconEdit, IconEye, IconEyeAlt, IconEyeAnimated, IconEyeClosed, IconEyeMinus, IconGear, IconHelp, IconLayout, IconListSparkle, IconMoon, IconPause, IconPauseAlt, IconPausePlayAnimated, IconPlayAlt, IconPlus, IconSendAnimated, IconSendArrow, IconSun, IconTarget, IconTrash, IconTrashAlt, IconXmark, IconXmarkLarge, PageFeedbackToolbarCSS, PageFeedbackToolbarCSS as UISniper, type UISniperProps, closestCrossingShadow, getElementClasses, getElementPath, getNearbyText, getShadowHost, getStorageKey, identifyAnimationElement, identifyElement, isInShadowDOM, loadAnnotations, saveAnnotations };
+export { AnimatedBunny, type Annotation, AnnotationPopupCSS, type AnnotationPopupCSSHandle, type AnnotationPopupCSSProps, type DemoAnnotation, IconChatEllipsis, IconCheck, IconCheckSmall, IconCheckSmallAnimated, IconCheckmark, IconCheckmarkCircle, IconCheckmarkLarge, IconChevronLeft, IconChevronRight, IconClose, IconCopyAlt, IconCopyAnimated, IconEdit, IconEye, IconEyeAlt, IconEyeAnimated, IconEyeClosed, IconEyeMinus, IconGear, IconHelp, IconLayout, IconListSparkle, IconMoon, IconPause, IconPauseAlt, IconPausePlayAnimated, IconPlayAlt, IconPlus, IconSendAnimated, IconSendArrow, IconSun, IconTarget, IconTrash, IconTrashAlt, IconXmark, IconXmarkLarge, type PIIRedactionConfig, PageFeedbackToolbarCSS, ReviewPanel, type ReviewPanelProps, type TelemetryEvent, PageFeedbackToolbarCSS as UISniper, UISniperContext, type UISniperContextValue, type UISniperProps, closestCrossingShadow, getElementClasses, getElementPath, getNearbyText, getShadowHost, getStorageKey, identifyAnimationElement, identifyElement, isInShadowDOM, loadAnnotations, saveAnnotations, useUISniper };