featuredrop 2.6.1 → 2.7.1

package/dist/react-hooks.d.cts

@@ -0,0 +1,540 @@
+import { RefObject, ReactNode } from 'react';
+
+/** Entry type label — determines default icon/color in UI */
+type FeatureType = "feature" | "improvement" | "fix" | "breaking";
+/** Priority level for announcements */
+type FeaturePriority = "critical" | "normal" | "low";
+/** Motion preset for built-in component transitions */
+type FeatureDropAnimationPreset = "none" | "subtle" | "normal" | "playful";
+/** 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>;
+}
+/** 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 product scope (`"*"`, `"askverdict"`, etc.) for multi-product manifests */
+    product?: string;
+    /** Optional URL to link to (e.g. docs page, changelog entry) */
+    url?: string;
+    /** Optional feature flag key; requires a flag bridge to evaluate */
+    flagKey?: 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;
+}
+/** Display format hint from the engine */
+type DisplayFormat = "badge" | "toast" | "modal" | "banner" | "inline" | "spotlight";
+/** Interaction type tracked by the engine */
+type InteractionType = "seen" | "dismissed" | "clicked" | "completed" | "snoozed" | "hovered" | "expanded";
+/** Timing decision returned by the engine */
+interface TimingDecision {
+    /** Whether to show the announcement now */
+    show: boolean;
+    /** Reason for the decision */
+    reason: string;
+    /** Suggested delay in ms if not showing now */
+    delayMs?: number;
+    /** Confidence level (0-1) */
+    confidence: number;
+}
+/** Format recommendation from the engine */
+interface FormatRecommendation {
+    /** Recommended display format */
+    primary: DisplayFormat;
+    /** Fallback format if primary component isn't used */
+    fallback: DisplayFormat;
+    /** Reason for the recommendation */
+    reason: string;
+}
+/** Adoption score breakdown */
+interface AdoptionScore {
+    /** Overall score (0-100) */
+    score: number;
+    /** Letter grade */
+    grade: "A" | "B" | "C" | "D" | "F";
+    /** Score breakdown */
+    breakdown: {
+        /** % of features the user has explored */
+        featuresExplored: number;
+        /** Rate of dismissals (lower is better) */
+        dismissRate: number;
+        /** Rate of tour/checklist completion */
+        completionRate: number;
+        /** Whether engagement is rising, stable, or declining */
+        engagementTrend: "rising" | "stable" | "declining";
+    };
+    /** Actionable recommendations */
+    recommendations: string[];
+}
+/** Per-feature adoption status */
+interface FeatureAdoptionStatus {
+    featureId: string;
+    status: "unseen" | "seen" | "explored" | "adopted" | "dismissed";
+    firstSeen?: string;
+    lastInteraction?: string;
+    interactionCount: number;
+}
+/** Delivery context passed to the engine for timing decisions */
+interface DeliveryContext {
+    /** Current route/path */
+    currentPath: string;
+    /** Seconds since session start */
+    sessionAge: number;
+    /** Dismissals in last 5 minutes */
+    recentDismissals: number;
+    /** Feature priority */
+    featurePriority: FeaturePriority;
+}
+/**
+ * Plugin interface for the FeatureDrop engine.
+ *
+ * The open-source library defines this interface.
+ * The proprietary @featuredrop/engine implements it.
+ * Users can also build their own engine implementation.
+ *
+ * The free library works perfectly without any engine.
+ */
+interface FeatureDropEngine {
+    /** Decide whether to show a feature announcement now */
+    shouldShow(featureId: string, context: DeliveryContext): TimingDecision;
+    /** Recommend the best display format for a feature */
+    recommendFormat(featureId: string): FormatRecommendation;
+    /** Get the user's overall adoption score */
+    getAdoptionScore(): AdoptionScore;
+    /** Track a user interaction with a feature */
+    trackInteraction(featureId: string, type: InteractionType): void;
+    /** Get adoption status for a specific feature */
+    getFeatureAdoption(featureId: string): FeatureAdoptionStatus;
+    /** Initialize the engine (called by provider on mount) */
+    initialize?(): void;
+    /** Cleanup resources (called by provider on unmount) */
+    destroy?(): void;
+}
+
+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 FeatureEngagementMetrics {
+    seen: number;
+    clicked: number;
+    dismissed: number;
+}
+interface AdoptionMetrics {
+    getAdoptionRate: (featureId: string) => number;
+    getTourCompletionRate: (tourId: string) => number;
+    getChecklistCompletionRate: (checklistId: string) => number;
+    getFeatureEngagement: (featureId: string) => FeatureEngagementMetrics;
+    getVariantPerformance: (featureId: string) => Record<string, number>;
+}
+
+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;
+    newFeatureCount: (count: number) => 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 FeatureDropContextValue {
+    /** Full manifest provided to the provider */
+    manifest: FeatureEntry[] | readonly FeatureEntry[];
+    /** All currently "new" features */
+    newFeatures: FeatureEntry[];
+    /** New features currently queued by throttling rules */
+    queuedFeatures: FeatureEntry[];
+    /** Count of new features */
+    newCount: number;
+    /** Count before throttling (all pending new features) */
+    totalNewCount: number;
+    /** All new features sorted by priority then release date */
+    newFeaturesSorted: FeatureEntry[];
+    /** Check if a sidebar key has any new features */
+    isNew: (sidebarKey: string) => boolean;
+    /** Dismiss a single feature by ID */
+    dismiss: (id: string) => void;
+    /** Dismiss all features (marks all as seen) */
+    dismissAll: () => Promise<void>;
+    /** Get the feature entry for a sidebar key (if it's new) */
+    getFeature: (sidebarKey: string) => FeatureEntry | undefined;
+    /** Whether quiet mode (Do Not Disturb) is enabled */
+    quietMode: boolean;
+    /** Enable/disable quiet mode */
+    setQuietMode: (enabled: boolean) => void;
+    /** Mark a feature as seen for dependency-chain resolution */
+    markFeatureSeen: (featureId: string) => void;
+    /** Mark a feature as clicked for dependency-chain resolution */
+    markFeatureClicked: (featureId: string) => void;
+    /** Remaining toasts allowed in this session under throttle rules */
+    getRemainingToastSlots: () => number;
+    /** Mark toasts as shown in this session */
+    markToastsShown: (featureIds: string[]) => void;
+    /** Whether a modal can open right now under throttle rules */
+    canShowModal: (priority?: FeaturePriority) => boolean;
+    /** Record a modal display timestamp */
+    markModalShown: () => void;
+    /** Whether a tour can start right now under throttle rules */
+    canShowTour: () => boolean;
+    /** Record a tour start timestamp */
+    markTourShown: () => void;
+    /** Acquire/release spotlight slots under maxSimultaneousSpotlights */
+    acquireSpotlightSlot: (id: string, priority?: FeaturePriority) => boolean;
+    releaseSpotlightSlot: (id: string) => void;
+    /** Number of currently active spotlight slots */
+    activeSpotlightCount: number;
+    /** Emit an adoption analytics event (collector-backed when configured) */
+    trackAdoptionEvent: (event: AdoptionEventInput) => void;
+    /** Report a component/runtime error to provider-level monitoring hooks */
+    reportError: (error: unknown, context?: {
+        component?: string;
+        componentStack?: string;
+    }) => void;
+    /** Active locale code used by built-in UI strings */
+    locale: string;
+    /** Text direction derived from locale */
+    direction: "ltr" | "rtl";
+    /** Active motion preset for built-in component transitions */
+    animation: FeatureDropAnimationPreset;
+    /** Resolved translation strings for built-in React components */
+    translations: FeatureDropTranslations;
+    /** Track a named usage event for trigger rules */
+    trackUsageEvent: (event: string, delta?: number) => void;
+    /** Track a named trigger event for trigger rules */
+    trackTriggerEvent: (event: string) => void;
+    /** Mark a milestone for trigger rules */
+    trackMilestone: (event: string) => void;
+    /** Manually override current path for page trigger rules */
+    setTriggerPath: (path: string) => void;
+    /** Optional engine instance for AI-powered delivery intelligence */
+    engine: FeatureDropEngine | null;
+}
+
+/**
+ * Access the full feature discovery context.
+ *
+ * Returns: `{ newFeatures, newCount, isNew, dismiss, dismissAll, getFeature }`
+ *
+ * @throws Error if used outside of `<FeatureDropProvider>`
+ */
+declare function useFeatureDrop(): FeatureDropContextValue;
+
+interface UseNewFeatureResult {
+    /** Whether this sidebar key has a new feature */
+    isNew: boolean;
+    /** The feature entry, if new */
+    feature: FeatureEntry | undefined;
+    /** Dismiss the feature for this sidebar key */
+    dismiss: () => void;
+}
+/**
+ * Check if a single navigation item has a new feature.
+ *
+ * @param sidebarKey - The key to check (e.g. "/journal", "settings")
+ * @returns `{ isNew, feature, dismiss }`
+ */
+declare function useNewFeature(sidebarKey: string): UseNewFeatureResult;
+
+/**
+ * Get the count of currently new features.
+ *
+ * Useful for rendering a badge count on a "What's New" button.
+ *
+ * @returns The number of new features
+ */
+declare function useNewCount(): number;
+
+interface UseTabNotificationOptions {
+    /** Whether tab notifications are enabled. Default: true */
+    enabled?: boolean;
+    /** Template string. `{count}` is replaced with the number. Default: "({count}) {title}" */
+    template?: string;
+    /** Enable flashing/blinking pattern for attention. Default: false */
+    flash?: boolean;
+    /** Flash interval in ms. Default: 1500 */
+    flashInterval?: number;
+}
+/**
+ * Updates the browser tab title with the unread feature count.
+ *
+ * Shows "(3) My App" when there are new features, restores the original
+ * title when all features are read. Optional flash/blink pattern for attention.
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   useTabNotification();
+ *   return <div>...</div>;
+ * }
+ * ```
+ *
+ * @example With flash
+ * ```tsx
+ * useTabNotification({ flash: true, template: "[{count} new] {title}" });
+ * ```
+ */
+declare function useTabNotification(options?: UseTabNotificationOptions): void;
+
+declare function useAdoptionAnalytics(events: AdoptionEvent[]): AdoptionMetrics;
+
+interface TourStep {
+    id: string;
+    target: string | RefObject<HTMLElement | null>;
+    title: string;
+    content: string | ReactNode;
+    placement?: "top" | "bottom" | "left" | "right" | "auto";
+    action?: "click" | "input" | "custom";
+    advanceOn?: {
+        selector: string;
+        event: string;
+    };
+    highlightTarget?: boolean;
+    beforeStep?: () => Promise<void>;
+    afterStep?: () => Promise<void>;
+    skipable?: boolean;
+}
+
+interface TourSnapshot {
+    isActive: boolean;
+    currentStepIndex: number;
+    currentStep: TourStep | null;
+    totalSteps: number;
+}
+
+interface UseTourResult {
+    startTour: () => void;
+    nextStep: () => void;
+    prevStep: () => void;
+    skipTour: () => void;
+    closeTour: () => void;
+    currentStep: TourSnapshot["currentStep"];
+    currentStepIndex: number;
+    totalSteps: number;
+    isActive: boolean;
+}
+declare function useTour(id: string): UseTourResult;
+
+interface TourSequenceItem {
+    featureId: string;
+    tourId: string;
+}
+interface UseTourSequencerResult {
+    nextTourId: string | null;
+    nextFeatureId: string | null;
+    remainingTours: number;
+    startNextTour: () => boolean;
+}
+declare function useTourSequencer(sequence: TourSequenceItem[]): UseTourSequencerResult;
+
+interface UseChecklistResult {
+    completeTask: (taskId: string) => void;
+    resetChecklist: () => void;
+    dismissChecklist: () => void;
+    toggleCollapsed: () => void;
+    isComplete: boolean;
+    progress: {
+        completed: number;
+        total: number;
+        percent: number;
+    };
+    tasks: Array<{
+        id: string;
+        completed: boolean;
+    }>;
+    dismissed: boolean;
+    collapsed: boolean;
+}
+declare function useChecklist(id: string): UseChecklistResult;
+
+type SurveyType = "nps" | "csat" | "ces" | "custom";
+
+interface UseSurveyResult {
+    show: (options?: {
+        force?: boolean;
+    }) => boolean;
+    hide: () => void;
+    askLater: () => void;
+    isOpen: boolean;
+    submitted: boolean;
+    canShow: boolean;
+    type: SurveyType;
+}
+declare function useSurvey(id: string): UseSurveyResult;
+
+interface UseChangelogResult {
+    /** All features from the manifest (including non-new) */
+    features: readonly FeatureEntry[];
+    /** Only features that are currently "new" (unread) */
+    newFeatures: readonly FeatureEntry[];
+    /** Count of new/unread features */
+    newCount: number;
+    /** Sorted new features (critical first, then by date) */
+    newFeaturesSorted: readonly FeatureEntry[];
+    /** Dismiss a single feature by ID */
+    dismiss: (id: string) => void;
+    /** Dismiss all features at once */
+    dismissAll: () => void;
+    /** Check if a specific feature is new */
+    isNew: (sidebarKey: string) => boolean;
+    /** Mark all currently visible features as seen (advances watermark) */
+    markAllSeen: () => void;
+    /** Get features filtered by category */
+    getByCategory: (category: string) => readonly FeatureEntry[];
+}
+declare function useChangelog(): UseChangelogResult;
+
+export { type TourSequenceItem, type UseChangelogResult, type UseChecklistResult, type UseNewFeatureResult, type UseSurveyResult, type UseTabNotificationOptions, type UseTourResult, type UseTourSequencerResult, useAdoptionAnalytics, useChangelog, useChecklist, useFeatureDrop, useNewCount, useNewFeature, useSurvey, useTabNotification, useTour, useTourSequencer };