featuredrop 1.0.1 → 1.2.0

package/dist/testing.d.ts

@@ -0,0 +1,339 @@
+import { ReactNode, ReactElement } from 'react';
+
+type AdoptionEventType = "feature_seen" | "feature_clicked" | "feature_dismissed" | "tour_started" | "tour_completed" | "tour_skipped" | "checklist_task_completed" | "checklist_completed" | "survey_submitted" | "feedback_submitted" | "announcement_shown" | "cta_clicked";
+interface AdoptionEvent {
+    type: AdoptionEventType;
+    featureId?: string;
+    tourId?: string;
+    variant?: string;
+    timestamp: string;
+    sessionId?: string;
+    userId?: string;
+    metadata?: Record<string, unknown>;
+}
+type AdoptionEventInput = Omit<AdoptionEvent, "timestamp"> & {
+    timestamp?: string;
+};
+interface AnalyticsAdapter {
+    track: (event: AdoptionEvent) => void | Promise<void>;
+    trackBatch?: (events: AdoptionEvent[]) => void | Promise<void>;
+}
+interface AnalyticsCollectorOptions {
+    adapter: AnalyticsAdapter;
+    batchSize?: number;
+    flushInterval?: number;
+    sampleRate?: number;
+    enabled?: boolean;
+    sessionId?: string;
+    userId?: string;
+    now?: () => Date;
+    random?: () => number;
+}
+declare class AnalyticsCollector {
+    private adapter;
+    private queue;
+    private batchSize;
+    private flushInterval;
+    private sampleRate;
+    private enabled;
+    private now;
+    private random;
+    private sessionId?;
+    private userId?;
+    private timer;
+    private flushing;
+    constructor(options: AnalyticsCollectorOptions);
+    setEnabled(enabled: boolean): void;
+    setContext(context: {
+        sessionId?: string;
+        userId?: string;
+    }): void;
+    getQueueSize(): number;
+    track(event: AdoptionEventInput): void;
+    flush(): Promise<void>;
+    destroy(): Promise<void>;
+    private startTimer;
+}
+
+/** Entry type label — determines default icon/color in UI */
+type FeatureType = "feature" | "improvement" | "fix" | "breaking";
+/** Priority level for announcements */
+type FeaturePriority = "critical" | "normal" | "low";
+/** Call-to-action for a feature entry */
+interface FeatureCTA {
+    /** Button/link label */
+    label: string;
+    /** URL to navigate to */
+    url: string;
+}
+/** Variant-level overrides for A/B announcement testing */
+interface FeatureVariant {
+    /** Optional variant-specific label override */
+    label?: string;
+    /** Optional variant-specific description override */
+    description?: string;
+    /** Optional variant-specific image override */
+    image?: string;
+    /** Optional variant-specific CTA override */
+    cta?: FeatureCTA;
+    /** Optional variant-specific metadata overrides */
+    meta?: Record<string, unknown>;
+}
+/** Audience targeting rule — determines which user segments see a feature */
+interface AudienceRule {
+    /** Plans that should see this feature (e.g. ["pro", "enterprise"]) */
+    plan?: string[];
+    /** Roles that should see this feature (e.g. ["admin", "editor"]) */
+    role?: string[];
+    /** Regions that should see this feature (e.g. ["us", "eu"]) */
+    region?: string[];
+    /** Arbitrary key-value pairs for custom matching logic */
+    custom?: Record<string, unknown>;
+}
+/** User context for audience targeting */
+interface UserContext {
+    /** Current user's plan (e.g. "pro", "free") */
+    plan?: string;
+    /** Current user's role (e.g. "admin", "viewer") */
+    role?: string;
+    /** Current user's region (e.g. "us", "eu") */
+    region?: string;
+    /** Arbitrary traits for custom matching logic */
+    traits?: Record<string, unknown>;
+}
+/** Custom audience matcher function */
+type AudienceMatchFn = (audience: AudienceRule, userContext: UserContext) => boolean;
+/** Dependency gates for progressive feature discovery */
+interface FeatureDependencies {
+    /** Features the user must have seen before this one can surface */
+    seen?: string[];
+    /** Features the user must have clicked before this one can surface */
+    clicked?: string[];
+    /** Features the user must have dismissed before this one can surface */
+    dismissed?: string[];
+}
+/** Runtime context used by trigger evaluation */
+interface TriggerContext {
+    /** Current app route/path */
+    path?: string;
+    /** Named events observed in this session */
+    events?: ReadonlySet<string>;
+    /** Named milestone flags reached in this session */
+    milestones?: ReadonlySet<string>;
+    /** Usage counters keyed by event/pattern name */
+    usage?: Record<string, number>;
+    /** Session elapsed time in milliseconds */
+    elapsedMs?: number;
+    /** Scroll completion percentage (0-100) */
+    scrollPercent?: number;
+    /** Optional additional trigger context */
+    metadata?: Record<string, unknown>;
+}
+type FeatureTrigger = {
+    type: "page";
+    match: string | RegExp;
+} | {
+    type: "usage";
+    event: string;
+    minActions?: number;
+} | {
+    type: "time";
+    minSeconds: number;
+} | {
+    type: "milestone";
+    event: string;
+} | {
+    type: "frustration";
+    pattern: string;
+    threshold?: number;
+} | {
+    type: "scroll";
+    minPercent?: number;
+} | {
+    type: "custom";
+    evaluate: (context: TriggerContext) => boolean;
+};
+/** A single feature entry in the manifest */
+interface FeatureEntry {
+    /** Unique identifier for the feature */
+    id: string;
+    /** Human-readable label (e.g. "Decision Journal") */
+    label: string;
+    /** Optional longer description (supports markdown in UI components) */
+    description?: string;
+    /**
+     * Semantic version targeting.
+     * If provided as an object, requires `appVersion` to be supplied to the provider/helpers.
+     * - introduced: earliest app version that includes this feature
+     * - showNewUntil: stop showing "new" once appVersion reaches this
+     * - deprecatedAt: hide feature for app versions at or above this (optional safety)
+     * - showIn: range string, e.g. ">=2.5.0 <3.0.0"
+     */
+    version?: string | {
+        introduced?: string;
+        showNewUntil?: string;
+        deprecatedAt?: string;
+        showIn?: string;
+    };
+    /** ISO date when this feature was released */
+    releasedAt: string;
+    /** ISO date after which the "new" badge should stop showing */
+    showNewUntil: string;
+    /** Optional key to match navigation items (e.g. "/journal", "settings") */
+    sidebarKey?: string;
+    /** Optional grouping category (e.g. "ai", "billing", "core") */
+    category?: string;
+    /** Optional URL to link to (e.g. docs page, changelog entry) */
+    url?: string;
+    /** Entry type — determines default icon/color in UI components */
+    type?: FeatureType;
+    /** Priority level — critical entries get special treatment in UI */
+    priority?: FeaturePriority;
+    /** Optional image/screenshot URL */
+    image?: string;
+    /** Optional call-to-action button */
+    cta?: FeatureCTA;
+    /** ISO date — entry is hidden until this date (scheduled publishing) */
+    publishAt?: string;
+    /** Optional arbitrary metadata */
+    meta?: Record<string, unknown>;
+    /** A/B variants keyed by variant name (e.g. control, treatment_a) */
+    variants?: Record<string, FeatureVariant>;
+    /** Percentage split per variant (same order as variants object keys) */
+    variantSplit?: number[];
+    /** Audience targeting — if set, only matching users see this feature */
+    audience?: AudienceRule;
+    /** Dependency requirements (progressive disclosure sequencing) */
+    dependsOn?: FeatureDependencies;
+    /** Contextual trigger rule */
+    trigger?: FeatureTrigger;
+}
+/** The full feature manifest — an array of feature entries */
+type FeatureManifest = readonly FeatureEntry[];
+/**
+ * Storage adapter interface — implement for your persistence layer.
+ *
+ * The adapter bridges two data sources:
+ * - **Watermark**: a server-side timestamp ("features seen at")
+ * - **Dismissed IDs**: client-side per-feature dismissals
+ */
+interface StorageAdapter {
+    /** Get the user's "features seen at" watermark (ISO string or null) */
+    getWatermark(): string | null;
+    /** Get the set of individually dismissed feature IDs */
+    getDismissedIds(): ReadonlySet<string>;
+    /** Dismiss a single feature by ID */
+    dismiss(id: string): void;
+    /** Dismiss all features — sets watermark to `now` and clears dismissals */
+    dismissAll(now: Date): Promise<void>;
+}
+/** Analytics event callbacks — pipe to your analytics provider */
+interface AnalyticsCallbacks {
+    /** Fired when a feature badge becomes visible to the user */
+    onFeatureSeen?: (feature: FeatureEntry) => void;
+    /** Fired when a user dismisses a single feature */
+    onFeatureDismissed?: (feature: FeatureEntry) => void;
+    /** Fired when a user clicks a feature link or CTA */
+    onFeatureClicked?: (feature: FeatureEntry) => void;
+    /** Fired when the changelog widget is opened */
+    onWidgetOpened?: () => void;
+    /** Fired when the changelog widget is closed */
+    onWidgetClosed?: () => void;
+    /** Fired when all features are dismissed at once */
+    onAllDismissed?: () => void;
+}
+
+interface ThrottleOptions {
+    maxSimultaneousBadges?: number;
+    maxSimultaneousSpotlights?: number;
+    maxToastsPerSession?: number;
+    minTimeBetweenModals?: number;
+    minTimeBetweenTours?: number;
+    sessionCooldown?: number;
+    respectDoNotDisturb?: boolean;
+}
+
+interface FeatureDropTranslations {
+    newBadge: string;
+    whatsNewTitle: string;
+    markAllRead: string;
+    allCaughtUp: string;
+    close: string;
+    changelogTitle: string;
+    searchPlaceholder: string;
+    allCategories: string;
+    noUpdatesYet: string;
+    loadMore: string;
+    share: string;
+    skipToEntries: string;
+    stepOf: (current: number, total: number) => string;
+    back: string;
+    next: string;
+    skip: string;
+    finish: string;
+    gotIt: string;
+    announcement: string;
+    feedbackTitle: string;
+    feedbackTrigger: string;
+    feedbackSubmitted: string;
+    submit: string;
+    cancel: string;
+    askLater: string;
+}
+
+interface FeatureDropProviderProps {
+    /** The feature manifest — typically a frozen array of FeatureEntry objects */
+    manifest: FeatureManifest;
+    /** Storage adapter instance (e.g. LocalStorageAdapter, MemoryAdapter) */
+    storage: StorageAdapter;
+    /** Optional analytics callbacks — pipe to your analytics provider */
+    analytics?: AnalyticsCallbacks;
+    /** User context for audience targeting (plan, role, region, traits) */
+    userContext?: UserContext;
+    /** Custom audience matcher — overrides default AND/OR matching logic */
+    matchAudience?: AudienceMatchFn;
+    /** Current app version (semver) for version-pinned features */
+    appVersion?: string;
+    /** Announcement throttling and session cooldown controls */
+    throttle?: ThrottleOptions;
+    /** Stable identifier for A/B variant assignment (e.g. userId) */
+    variantKey?: string;
+    /** Optional adoption analytics collector */
+    collector?: AnalyticsCollector;
+    /** Locale code for built-in component translations (e.g. "en", "fr", "es") */
+    locale?: string;
+    /** Custom translation overrides for built-in component strings */
+    translations?: Partial<FeatureDropTranslations>;
+    children: ReactNode;
+}
+
+type MockFeatureInput = Partial<FeatureEntry> & {
+    id?: string;
+    label?: string;
+    releasedAt?: string;
+    showNewUntil?: string;
+    type?: FeatureType;
+};
+declare function createMockManifest(entries: MockFeatureInput[], now?: Date): FeatureManifest;
+interface MockStorage extends StorageAdapter {
+    setWatermark: (watermark: string | null) => void;
+    setDismissedIds: (ids: string[]) => void;
+    reset: () => void;
+}
+declare function createMockStorage(initial?: {
+    watermark?: string | null;
+    dismissedIds?: string[];
+}): MockStorage;
+declare function createTestProvider(props: Omit<FeatureDropProviderProps, "children">): ({ children }: {
+    children?: ReactNode;
+}) => ReactElement;
+declare function advanceTime(ms: number): void;
+declare function setMockTime(now: number | Date): void;
+type MockAnalyticsCollectorOptions = Omit<AnalyticsCollectorOptions, "adapter">;
+declare class MockAnalyticsCollector extends AnalyticsCollector {
+    readonly events: AdoptionEvent[];
+    constructor(options?: MockAnalyticsCollectorOptions);
+    clear(): void;
+}
+
+export { MockAnalyticsCollector, type MockAnalyticsCollectorOptions, type MockFeatureInput, type MockStorage, advanceTime, createMockManifest, createMockStorage, createTestProvider, setMockTime };