@atlaskit/editor-common/dist/types-ts4.5/experiences/Experience.d.ts

A package that contains common classes and components for editor and renderer

import type { DispatchAnalyticsEvent } from '../analytics';
import type { ExperienceCheck } from './ExperienceCheck';
import type { CustomExperienceMetadata, ExperienceId } from './types';
type ExperienceOptions = {
    /**
     * An optional sub identifier to further classify the specific experience action taken
     *
     * e.g. 'bold' 'bullet' 'insert-table'
     */
    action?: string;
    /**
     * An optional sub identifier to further classify the specific experience action subject
     *
     * e.g. 'selection-toolbar' 'quick-insert'
     */
    actionSubjectId?: string;
    /**
     * Checks used to control experience transition to various states.
     * Once the experience is in progress, these checks can automatically trigger
     * state transitions (e.g., timeout check to trigger failure).
     */
    checks?: ExperienceCheck[];
    /**
     * Function to dispatch analytics events for experience tracking.
     * Required for tracking experienceMeasured and experienceSampled events.
     */
    dispatchAnalyticsEvent: DispatchAnalyticsEvent;
    /**
     * Optional global metadata to attach to all analytics events for this experience.
     *
     * Can be overridden by metadata provided in individual start/abort/fail/success calls.
     */
    metadata?: CustomExperienceMetadata;
    /**
     * Sample rate for experienceSampled events.
     * Determines how frequently we should track events for the experience based on
     * expected volume. Value should be between 0 and 1.
     *
     * @default DEFAULT_EXPERIENCE_SAMPLE_RATE (0.001 = 1 in 1000)
     *
     * Newly defined experiences should use the default unless they have data
     * to justify a different rate. Measurements should be gathered after initial
     * instrumentation, then the sample rate can be tuned up to a safe threshold.
     */
    sampleRate?: number;
};
type ExperienceStartOptions = {
    forceRestart?: boolean;
    metadata?: CustomExperienceMetadata;
    method?: string;
};
type ExperienceEndOptions = {
    metadata?: CustomExperienceMetadata;
    reason?: string;
};
export declare class Experience {
    private readonly id;
    private readonly actionSubjectId;
    private readonly dispatchAnalyticsEvent;
    private readonly sampleRate;
    private readonly globalMetadata;
    private readonly check;
    private currentState;
    /**
     * Set of experience states that have been seen in the current session.
     *
     * Used to determine if experienceStatusFirstSeen flag should be set in events.
     */
    private statesSeen;
    /**
     * Indicates whether sampled tracking is enabled for this current experience session.
     *
     * Set to true | false upon transitioning to 'started' state.
     * When true, on subsequent transitions we fire experienceSampled events.
     * Ensures that every tracked start has corresponding abort/fail/success tracked.
     */
    private isSampledTrackingEnabled;
    /**
     * Timestamp (in milliseconds) when the experience transitioned to 'started' state.
     *
     * Used to calculate experience duration. Set via Date.now() when experience starts.
     */
    private startTimeMs;
    /**
     * Metadata provided at experience start time to merge into subsequent events.
     *
     * Used to retain experienceStartMethod and other start-specific metadata.
     */
    private startMetadata;
    /**
     * Creates a new Experience instance for tracking user experiences.
     *
     * @param id - Unique identifier for the experience e.g. 'toolbarOpen' 'menuAction'
     * @param options - Configuration options for the experience
     * @param options.checks - Experience checks to monitor for completion
     * @param options.dispatchAnalyticsEvent - Function to dispatch analytics events
     * @param options.sampleRate - Sample rate for experienceSampled events
     * @param options.metadata - Global metadata to attach to all events
     * @param options.action - Optional sub identifier for the specific experience action e.g. 'bold' 'insertTable'
     * @param options.actionSubjectId - Optional sub identifier for the experience action subject e.g. 'selectionToolbar' 'quickInsert'
     */
    constructor(id: ExperienceId, options: ExperienceOptions);
    private startCheck;
    private stopCheck;
    private getEndStateMetadata;
    /**
     * Transitions to a new experience state and tracks analytics events.
     *
     * Upon transition to each state, two events are tracked:
     * - experienceMeasured: tracked on every successful transition, used for data analysis
     * - experienceSampled: tracked only on 1 out of every N transitions based on sample rate
     *
     * @param toState - The target state to transition to
     * @param metadata - Optional metadata to attach to the analytics events
     * @returns true if transition was successful, false if invalid transition
     */
    private transitionTo;
    /**
     * Tracks analytics events for a state transition.
     *
     * Fires both experienceMeasured (always) and experienceSampled (sampled) events.
     *
     * @param toState - The state that was transitioned to
     * @param metadata - Metadata to include in the event, including firstInSession flag
     */
    private trackTransition;
    /**
     * Starts tracking the experience and all checks which monitor for completion.
     *
     * Metadata from options will be merged with metadata provided in subsequent events.
     *
     * @param options - Configuration for starting the experience
     * @param options.metadata - Optional custom metadata attached to all subsequent events for this started experience
     * @param options.forceRestart - If true and experience already in progress will abort and restart
     * @param options.method - Optional method for experience start, e.g., how the experience was initiated
     */
    start(options?: ExperienceStartOptions): boolean;
    /**
     * Marks the experience as successful and stops any ongoing checks.
     *
     * @param options - Configuration for the success event
     * @param options.metadata - Optional custom metadata attached to the success event
     * @param options.reason - Optional reason for success
     * @returns false if transition to success state was not valid
     */
    success(options?: ExperienceEndOptions): boolean;
    /**
     * Aborts the experience and stops any ongoing checks.
     *
     * Use this when a started experience terminates early due to user action or context change
     * (e.g., component unmount, navigation). This is neither success nor failure.
     *
     * @param options - Configuration for the abort event
     * @param options.metadata - Optional custom metadata attached to the abort event
     * @param options.reason - Optional reason for abort
     *
     * @example
     * // Abort on component unmount
     * useEffect(() => {
     *   return () => experience.abort({ reason: 'unmount', metadata: { someKey: 'someValue' } });
     * }, []);
     *
     * @returns false if transition to aborted state was not valid
     */
    abort(options?: ExperienceEndOptions): boolean;
    /**
     * Manually marks the experience as failed and stops any ongoing checks.
     *
     * Use this for actual failures in the experience flow (e.g., timeout, error conditions).
     *
     * @param options - Configuration for the failure event
     * @param options.metadata - Optional custom metadata attached to the failure event
     * @param options.reason - Optional reason for failure
     * @returns false if transition to failed state was not valid
     */
    failure(options?: ExperienceEndOptions): boolean;
}
export {};