@posthog/browser-common 0.9.4 → 0.9.6

package/dist/surveys-config.js

@@ -0,0 +1,68 @@
+"use strict";
+var __webpack_require__ = {};
+(()=>{
+    __webpack_require__.d = (exports1, getters, values)=>{
+        var define = (defs, kind)=>{
+            for(var key in defs)if (__webpack_require__.o(defs, key) && !__webpack_require__.o(exports1, key)) Object.defineProperty(exports1, key, {
+                enumerable: true,
+                [kind]: defs[key]
+            });
+        };
+        define(getters, "get");
+        define(values, "value");
+    };
+})();
+(()=>{
+    __webpack_require__.o = (obj, prop)=>Object.prototype.hasOwnProperty.call(obj, prop);
+})();
+(()=>{
+    __webpack_require__.r = (exports1)=>{
+        if ("u" > typeof Symbol && Symbol.toStringTag) Object.defineProperty(exports1, Symbol.toStringTag, {
+            value: 'Module'
+        });
+        Object.defineProperty(exports1, '__esModule', {
+            value: true
+        });
+    };
+})();
+var __webpack_exports__ = {};
+__webpack_require__.r(__webpack_exports__);
+const SURVEYS = '$surveys';
+const SURVEYS_LOADED_AT = '$surveys_loaded_at';
+const SURVEYS_CACHE_TTL_MS = 300000;
+const SURVEYS_REFRESH_BACKOFF_MS = SURVEYS_CACHE_TTL_MS;
+const LOAD_EXT_NOT_FOUND = 'PostHog loadExternalDependency extension not found.';
+const SURVEYS_ACTIVATED = '$surveys_activated';
+const SURVEYS_ACTIVATED_SESSION = '$surveys_activated_session';
+const SURVEYS_ACTIVATED_TIMESTAMPS = '$surveys_activated_timestamps';
+__webpack_require__.d(__webpack_exports__, {}, {
+    LOAD_EXT_NOT_FOUND: LOAD_EXT_NOT_FOUND,
+    SURVEYS: SURVEYS,
+    SURVEYS_ACTIVATED: SURVEYS_ACTIVATED,
+    SURVEYS_ACTIVATED_SESSION: SURVEYS_ACTIVATED_SESSION,
+    SURVEYS_ACTIVATED_TIMESTAMPS: SURVEYS_ACTIVATED_TIMESTAMPS,
+    SURVEYS_CACHE_TTL_MS: SURVEYS_CACHE_TTL_MS,
+    SURVEYS_LOADED_AT: SURVEYS_LOADED_AT,
+    SURVEYS_REFRESH_BACKOFF_MS: SURVEYS_REFRESH_BACKOFF_MS
+});
+exports.LOAD_EXT_NOT_FOUND = __webpack_exports__.LOAD_EXT_NOT_FOUND;
+exports.SURVEYS = __webpack_exports__.SURVEYS;
+exports.SURVEYS_ACTIVATED = __webpack_exports__.SURVEYS_ACTIVATED;
+exports.SURVEYS_ACTIVATED_SESSION = __webpack_exports__.SURVEYS_ACTIVATED_SESSION;
+exports.SURVEYS_ACTIVATED_TIMESTAMPS = __webpack_exports__.SURVEYS_ACTIVATED_TIMESTAMPS;
+exports.SURVEYS_CACHE_TTL_MS = __webpack_exports__.SURVEYS_CACHE_TTL_MS;
+exports.SURVEYS_LOADED_AT = __webpack_exports__.SURVEYS_LOADED_AT;
+exports.SURVEYS_REFRESH_BACKOFF_MS = __webpack_exports__.SURVEYS_REFRESH_BACKOFF_MS;
+for(var __rspack_i in __webpack_exports__)if (-1 === [
+    "LOAD_EXT_NOT_FOUND",
+    "SURVEYS",
+    "SURVEYS_ACTIVATED",
+    "SURVEYS_ACTIVATED_SESSION",
+    "SURVEYS_ACTIVATED_TIMESTAMPS",
+    "SURVEYS_CACHE_TTL_MS",
+    "SURVEYS_LOADED_AT",
+    "SURVEYS_REFRESH_BACKOFF_MS"
+].indexOf(__rspack_i)) exports[__rspack_i] = __webpack_exports__[__rspack_i];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});

package/dist/surveys-config.mjs

@@ -0,0 +1,9 @@
+const SURVEYS = '$surveys';
+const SURVEYS_LOADED_AT = '$surveys_loaded_at';
+const SURVEYS_CACHE_TTL_MS = 300000;
+const SURVEYS_REFRESH_BACKOFF_MS = SURVEYS_CACHE_TTL_MS;
+const LOAD_EXT_NOT_FOUND = 'PostHog loadExternalDependency extension not found.';
+const SURVEYS_ACTIVATED = '$surveys_activated';
+const SURVEYS_ACTIVATED_SESSION = '$surveys_activated_session';
+const SURVEYS_ACTIVATED_TIMESTAMPS = '$surveys_activated_timestamps';
+export { LOAD_EXT_NOT_FOUND, SURVEYS, SURVEYS_ACTIVATED, SURVEYS_ACTIVATED_SESSION, SURVEYS_ACTIVATED_TIMESTAMPS, SURVEYS_CACHE_TTL_MS, SURVEYS_LOADED_AT, SURVEYS_REFRESH_BACKOFF_MS };

package/dist/surveys-renderer.d.ts

@@ -0,0 +1,248 @@
+import { type JSX, type RefObject } from 'preact';
+import type { SurveyRenderContext } from './survey-render-context';
+import type { DisplaySurveyPopoverOptions, Survey, SurveyCallback, SurveyWithTypeAndAppearance } from './types/surveys';
+import type { Properties } from '@posthog/types';
+import { getNextSurveyStep } from './surveys/survey-branching';
+export { getNextSurveyStep };
+/**
+ * `previewPageIndex` sentinel for the intro screen — the leading mirror of the confirmation
+ * page's `survey.questions.length` sentinel. Also serves as a capability marker for the main
+ * app: bundles without this export cannot render the intro screen preview.
+ */
+export declare const INTRO_SCREEN_PREVIEW_INDEX = -1;
+export declare class SurveyManager {
+    private _host;
+    private _surveyInFocus;
+    private _surveyTimeouts;
+    private _widgetSelectorListeners;
+    private _renderedTabWidgets;
+    private _renderedTargets;
+    private _prefillHandledSurveys;
+    private _automaticDisplayDispose?;
+    private _disposed;
+    private _currentLanguage;
+    private _surveyIsRendered;
+    private _languageChangeListener;
+    private _unsubscribeFeatureFlags;
+    private _surveyPopupProps;
+    private _displayOptions;
+    private _loggedFeatureFlagsDisabledWarning;
+    constructor(posthog: SurveyRenderContext);
+    private _onLanguageChange;
+    private _applyDisplayOverrides;
+    handlePageUnload: () => void;
+    private _clearSurveyTimeout;
+    /**
+     * cancel a "pending" survey, i.e. one that is waiting to be displayed in
+     * the _surveyTimeouts queue
+     */
+    cancelSurvey(surveyId: string): void;
+    startAutomaticDisplay(): void;
+    clearInMemoryInProgressSurveyState(): void;
+    dispose(): void;
+    /**
+     * `resumeDelayFromActivation` is internal to the display loop: a survey armed by an
+     * event/action trigger resumes its popup delay from when the trigger fired, so navigating
+     * mid-delay does not restart the countdown. An explicit `displaySurvey()` call carries its own
+     * `ignoreDelay` option instead, so it must always honor the full configured delay.
+     */
+    handlePopoverSurvey: (surveyParam: Survey, options?: DisplaySurveyPopoverOptions, { resumeDelayFromActivation }?: {
+        resumeDelayFromActivation?: boolean | undefined;
+    }) => void;
+    private _handleWidget;
+    private _detachWidgetSelectorListener;
+    private _removeWidgetSelectorListener;
+    private _removeTabWidget;
+    private _isWidgetSurveyOpen;
+    private _manageWidgetSelectorListener;
+    /**
+     * Sorts surveys by their appearance delay in ascending order. If a survey does not have an appearance delay,
+     * it is considered to have a delay of 0.
+     * @param surveys
+     * @returns The surveys sorted by their appearance delay
+     */
+    private _sortSurveysByAppearanceDelay;
+    renderPopover: (survey: Survey) => void;
+    renderSurvey: (survey: Survey, selector: Element, properties?: Properties) => void;
+    private _translateSurveyForRendering;
+    private _handleUrlPrefill;
+    /**
+     * On load, capture a response for prefilled questions only when:
+     * 1) the survey is complete, OR
+     * 2) partial responses are enabled AND the skipped questions were set to auto-submit.
+     */
+    private _autoSubmitPrefilledResponses;
+    /**
+     * process prefilled responses for non-hosted surveys
+     *
+     * @returns boolean, true if the survey is completed
+     */
+    private _handleInitialResponses;
+    private _processPrefillData;
+    private _isSurveyFeatureFlagEnabled;
+    private _warnIfFeatureFlagsDisabled;
+    private _isSurveyConditionMatched;
+    private _internalFlagCheckSatisfied;
+    checkSurveyEligibility(survey: Survey): {
+        eligible: boolean;
+        reason?: string | undefined;
+    };
+    /**
+     * PostHog's capture state, as an eligibility result. This is a prerequisite for any survey the
+     * SDK renders itself, not one of the survey's display conditions: without it a person types an
+     * answer, sees the confirmation, and `capture()` drops the `survey sent` event. So
+     * `displaySurvey`'s `ignoreConditions` must not bypass it. `is_capturing()` is the same gate
+     * `capture()` uses, so cookieless `on_reject` stays eligible.
+     *
+     * Deliberately kept out of `checkSurveyEligibility`: that also backs the public
+     * `getActiveMatchingSurveys`, which custom integrations use to discover API surveys they
+     * render themselves and record through their own backend (see `markSurveyAsSeen`). PostHog's
+     * capture state says nothing about whether such a response can be recorded, so discovery
+     * stays capture-independent.
+     */
+    checkSurveyCaptureEligibility(): {
+        eligible: boolean;
+        reason?: string | undefined;
+    };
+    /**
+     * Eligibility for a survey the SDK renders and captures the response for itself: everything
+     * `checkSurveyEligibility` checks, plus PostHog's capture state.
+     */
+    checkSurveyDisplayEligibility(survey: Survey): {
+        eligible: boolean;
+        reason?: string | undefined;
+    };
+    /**
+     * Renderability = display eligibility (running, type, flags, wait period, already-seen,
+     * capturing) plus the survey's event/action activation trigger. Used by the programmatic
+     * `canRenderSurvey` / `canRenderSurveyAsync` checks so they match the display loop.
+     *
+     * The trigger is intentionally kept out of `checkSurveyDisplayEligibility`: that method is
+     * also used by the explicit `displaySurvey` path, and the trigger state only lives in memory
+     * (a reload clears it, server-side events never set it). Gating eligibility on it would
+     * make explicit `displaySurvey('id')` calls silently show nothing.
+     */
+    checkSurveyRenderability(survey: Survey): {
+        eligible: boolean;
+        reason?: string | undefined;
+    };
+    /**
+     * Surveys can be activated by events or actions. This method checks if the survey has events and actions,
+     * and if so, it checks if the survey has been activated.
+     * @param survey
+     */
+    private _hasActionOrEventTriggeredSurvey;
+    private _checkFlags;
+    /**
+     * The full predicate for "should this survey display right now": eligibility (running,
+     * type, linked/targeting/internal flags, wait period, already-seen) plus the URL/device/
+     * selector conditions, the event/action trigger, and any feature-flag dependencies.
+     *
+     * Shared by the display loop and re-checked when a popover's delay timer fires, so a
+     * survey that became ineligible *during* the delay (e.g. an identify() reloaded flags and
+     * the internal targeting flag is now false) is not shown. Note this is purely an AND gate:
+     * adding it can only ever suppress a display, never cause an extra one.
+     *
+     * PostHog's capture state is not part of this: it also backs the public
+     * `getActiveMatchingSurveys` discovery result, so the paths where the SDK renders the survey
+     * itself apply that gate separately — see `checkSurveyDisplayEligibility`.
+     */
+    private _shouldDisplaySurvey;
+    getActiveMatchingSurveys: (callback: SurveyCallback, forceReload?: boolean) => void;
+    callSurveysAndEvaluateDisplayLogic: (forceReload?: boolean) => void;
+    private _addSurveyToFocus;
+    private _removeSurveyFromDom;
+    private _removeSurveyFromFocus;
+    getTestAPI(): {
+        addSurveyToFocus: (survey: Pick<Survey, 'id'>) => void;
+        removeSurveyFromFocus: (survey: SurveyWithTypeAndAppearance) => void;
+        surveyInFocus: string | null;
+        surveyTimeouts: Map<string, number>;
+        handleWidget: (survey: Survey) => void;
+        handlePopoverSurvey: (surveyParam: Survey, options?: DisplaySurveyPopoverOptions, { resumeDelayFromActivation }?: {
+            resumeDelayFromActivation?: boolean | undefined;
+        }) => void;
+        manageWidgetSelectorListener: (survey: Survey, selector: string) => void;
+        sortSurveysByAppearanceDelay: (surveys: Survey[]) => Survey[];
+        checkFlags: (survey: Survey) => boolean;
+        isSurveyFeatureFlagEnabled: (flagKey: string | null, flagVariant?: string | undefined) => boolean;
+        onLanguageChange: () => void;
+        currentLanguage: string | null;
+        surveyIsRendered: boolean;
+    };
+}
+export declare const renderSurveysPreview: ({ survey, parentElement, previewPageIndex, forceDisableHtml, onPreviewSubmit, onPreviewBack, posthog, positionStyles, }: {
+    survey: Survey;
+    parentElement: HTMLElement;
+    previewPageIndex: number;
+    forceDisableHtml?: boolean | undefined;
+    onPreviewSubmit?: ((res: string | string[] | number | null) => void) | undefined;
+    onPreviewBack?: (() => void) | undefined;
+    posthog?: SurveyRenderContext | undefined;
+    positionStyles?: JSX.CSSProperties | undefined;
+}) => void;
+export declare const renderFeedbackWidgetPreview: ({ survey, root, forceDisableHtml, posthog, }: {
+    survey: Survey;
+    root: HTMLElement;
+    forceDisableHtml?: boolean | undefined;
+    posthog?: SurveyRenderContext | undefined;
+}) => void;
+export declare function generateSurveys(posthog: SurveyRenderContext, isSurveysEnabled: boolean | undefined): SurveyManager | undefined;
+type UseHideSurveyOnURLChangeProps = {
+    survey: Pick<Survey, 'id' | 'conditions' | 'type' | 'appearance'>;
+    removeSurveyFromFocus?: ((survey: SurveyWithTypeAndAppearance) => void) | undefined;
+    setSurveyVisible: (visible: boolean) => void;
+    isPreviewMode?: boolean | undefined;
+    posthog?: SurveyRenderContext | undefined;
+};
+/**
+ * This hook handles URL-based survey visibility after the initial mount.
+ * The initial URL check is handled by the `getActiveMatchingSurveys` method in  the `PostHogSurveys` class,
+ * which ensures the URL matches before displaying a survey for the first time.
+ * That is the method that is called every second to see if there's a matching survey.
+ *
+ * This separation of concerns means:
+ * 1. Initial URL matching is done by `getActiveMatchingSurveys` before displaying the survey
+ * 2. Subsequent URL changes are handled here to hide the survey as the user navigates
+ */
+export declare function useHideSurveyOnURLChange({ survey, removeSurveyFromFocus, setSurveyVisible, isPreviewMode, posthog, }: UseHideSurveyOnURLChangeProps): void;
+export declare function usePopupVisibility(survey: Survey, posthog: SurveyRenderContext | undefined, millisecondDelay: number, isPreviewMode: boolean, removeSurveyFromFocus: (survey: SurveyWithTypeAndAppearance) => void, isPopup: boolean, surveyContainerRef?: RefObject<HTMLDivElement>, skipShownEvent?: boolean, surveyLanguage?: string | null): {
+    isPopupVisible: boolean;
+    isSurveySent: boolean;
+    setIsPopupVisible: import("preact/hooks").Dispatch<import("preact/hooks").StateUpdater<boolean>>;
+    hidePopupWithAnimation: () => void;
+};
+interface SurveyPopupProps {
+    survey: Survey;
+    forceDisableHtml?: boolean | undefined;
+    posthog?: SurveyRenderContext | undefined;
+    style?: JSX.CSSProperties | undefined;
+    previewPageIndex?: number | undefined;
+    removeSurveyFromFocus?: ((survey: SurveyWithTypeAndAppearance) => void) | undefined;
+    isPopup?: boolean | undefined;
+    onPreviewSubmit?: ((res: string | string[] | number | null) => void) | undefined;
+    onPreviewBack?: (() => void) | undefined;
+    onPopupSurveyDismissed?: (() => void) | undefined;
+    onCloseConfirmationMessage?: (() => void) | undefined;
+    /** Additional properties to include in all survey events */
+    properties?: Properties | undefined;
+    /** if true, survey popup will only render if there is a thank-you message */
+    isSurveyCompleted?: boolean | undefined;
+    /** When true, `survey shown` events will not be emitted automatically */
+    skipShownEvent?: boolean | undefined;
+    /** The language that was applied to the survey. */
+    surveyLanguage?: (string | null) | undefined;
+}
+export declare function SurveyPopup({ survey, forceDisableHtml, posthog, style, previewPageIndex, removeSurveyFromFocus, isPopup, onPreviewSubmit, onPreviewBack, onPopupSurveyDismissed, onCloseConfirmationMessage, properties, isSurveyCompleted, skipShownEvent, surveyLanguage, }: SurveyPopupProps): JSX.Element | null;
+export declare function Questions({ survey, forceDisableHtml, posthog, }: {
+    survey: Survey;
+    forceDisableHtml: boolean;
+    posthog?: SurveyRenderContext | undefined;
+}): JSX.Element | null;
+export declare function FeedbackWidget({ survey, forceDisableHtml, posthog, readOnly, surveyLanguage, }: {
+    survey: Survey;
+    forceDisableHtml?: boolean | undefined;
+    posthog?: SurveyRenderContext | undefined;
+    readOnly?: boolean | undefined;
+    surveyLanguage?: (string | null) | undefined;
+}): JSX.Element | null;