featuredrop 2.7.2 → 3.0.1

package/dist/preact.d.cts

@@ -826,6 +826,144 @@ interface UseSurveyResult {
 }
 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;
+
+interface UseSmartFeatureResult {
+    /** Whether the engine recommends showing this feature now */
+    show: boolean;
+    /** Recommended display format */
+    format: DisplayFormat;
+    /** Fallback format if primary component isn't available */
+    fallbackFormat: DisplayFormat;
+    /** The feature entry from the manifest */
+    feature: FeatureEntry | undefined;
+    /** Dismiss the feature (also tracks dismissal in engine) */
+    dismiss: () => void;
+    /** Engine's confidence in this timing decision (0-1) */
+    confidence: number;
+    /** Reason for the timing decision */
+    reason: string;
+}
+/**
+ * Engine-powered smart feature display hook.
+ *
+ * Combines the TimingOptimizer and FormatSelector to decide
+ * whether to show a feature and what format to use.
+ *
+ * Without an engine, gracefully degrades to always-show with badge format.
+ *
+ * @param featureId - The feature ID to check
+ * @returns `{ show, format, fallbackFormat, feature, dismiss, confidence, reason }`
+ *
+ * @example
+ * ```tsx
+ * function MyFeature() {
+ *   const { show, format, feature, dismiss } = useSmartFeature('dark-mode')
+ *
+ *   if (!show) return null
+ *
+ *   switch (format) {
+ *     case 'badge': return <NewBadge id="dark-mode" />
+ *     case 'toast': return <Toast feature={feature} onDismiss={dismiss} />
+ *     case 'modal': return <AnnouncementModal feature={feature} onDismiss={dismiss} />
+ *     default: return <NewBadge id="dark-mode" />
+ *   }
+ * }
+ * ```
+ */
+declare function useSmartFeature(featureId: string): UseSmartFeatureResult;
+
+type UseAdoptionScoreResult = AdoptionScore;
+/**
+ * Get the user's overall feature adoption score.
+ *
+ * Returns a 0-100 score with letter grade, breakdown, and recommendations.
+ * Useful for admin dashboards, debug panels, or gamification.
+ *
+ * Without an engine, returns a perfect score with no recommendations.
+ *
+ * @returns `{ score, grade, breakdown, recommendations }`
+ *
+ * @example
+ * ```tsx
+ * function AdoptionDashboard() {
+ *   const { score, grade, breakdown, recommendations } = useAdoptionScore()
+ *
+ *   return (
+ *     <div>
+ *       <h2>Adoption Score: {score}/100 ({grade})</h2>
+ *       <p>Features explored: {Math.round(breakdown.featuresExplored * 100)}%</p>
+ *       <p>Completion rate: {Math.round(breakdown.completionRate * 100)}%</p>
+ *       <ul>
+ *         {recommendations.map((r, i) => <li key={i}>{r}</li>)}
+ *       </ul>
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+declare function useAdoptionScore(): UseAdoptionScoreResult;
+
+interface UseBehaviorProfileResult {
+    /** Total sessions tracked */
+    sessionCount: number;
+    /** Dismiss rate (0-1) — fraction of announcements dismissed */
+    dismissRate: number;
+    /** Engagement rate (0-1) — fraction of announcements clicked/completed */
+    engagementRate: number;
+    /** User's preferred display format based on past behavior */
+    preferredFormat: DisplayFormat;
+    /** Whether an engine is available */
+    hasEngine: boolean;
+}
+/**
+ * Access the user's behavior profile for debug or admin views.
+ *
+ * Exposes aggregated behavior data from the AdoptionEngine's BehaviorTracker.
+ * Without an engine, returns default values.
+ *
+ * @returns `{ sessionCount, dismissRate, engagementRate, preferredFormat, hasEngine }`
+ *
+ * @example
+ * ```tsx
+ * function DebugPanel() {
+ *   const { sessionCount, dismissRate, engagementRate, preferredFormat, hasEngine } = useBehaviorProfile()
+ *
+ *   if (!hasEngine) return <p>No engine configured</p>
+ *
+ *   return (
+ *     <div>
+ *       <p>Sessions: {sessionCount}</p>
+ *       <p>Dismiss rate: {(dismissRate * 100).toFixed(0)}%</p>
+ *       <p>Engagement rate: {(engagementRate * 100).toFixed(0)}%</p>
+ *       <p>Preferred format: {preferredFormat}</p>
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+declare function useBehaviorProfile(): UseBehaviorProfileResult;
+
 interface NewBadgeRenderProps {
     /** Whether the feature is currently new */
     isNew: boolean;
@@ -1271,6 +1409,35 @@ interface FeatureRequestFormProps {
     children?: (props: FeatureRequestFormRenderProps) => ReactNode;
 }
 
+interface SmartAnnouncementRenderProps {
+    /** Whether the engine recommends showing now */
+    show: boolean;
+    /** Recommended display format */
+    format: DisplayFormat;
+    /** Fallback format */
+    fallbackFormat: DisplayFormat;
+    /** The feature entry */
+    feature: FeatureEntry | undefined;
+    /** Dismiss callback (tracks in engine + provider) */
+    dismiss: () => void;
+    /** Engine confidence in the timing decision (0-1) */
+    confidence: number;
+    /** Reason for the decision */
+    reason: string;
+}
+interface SmartAnnouncementProps {
+    /** Feature ID to display */
+    id: string;
+    /** Override the engine's format recommendation */
+    format?: DisplayFormat;
+    /** Additional CSS class for the container */
+    className?: string;
+    /** Additional inline styles */
+    style?: CSSProperties;
+    /** Render prop for full customization */
+    children?: (props: SmartAnnouncementRenderProps) => ReactNode;
+}
+
 declare const NewBadge: react.ComponentType<NewBadgeProps>;
 
 declare const ChangelogWidget: react.ComponentType<ChangelogWidgetProps>;
@@ -1302,4 +1469,6 @@ declare const FeatureRequestButton: react.ComponentType<FeatureRequestButtonProp
 
 declare const FeatureRequestForm: react.ComponentType<FeatureRequestFormProps>;
 
-export { AnnouncementModal, type AnnouncementModalProps, type AnnouncementModalRenderProps, type AnnouncementSlide, Banner, type BannerProps, type BannerRenderProps, type BannerVariant, type ChangelogEntryRenderProps, ChangelogPage, type ChangelogPageProps, ChangelogWidget, type ChangelogWidgetProps, type ChangelogWidgetRenderProps, Checklist, type ChecklistProps, type ChecklistRenderProps, type ChecklistTask, FeatureDropContext, type FeatureDropContextValue, FeatureDropProvider, type FeatureDropProviderProps, FeatureRequestButton, type FeatureRequestButtonProps, type FeatureRequestButtonRenderProps, FeatureRequestForm, type FeatureRequestFormProps, type FeatureRequestFormRenderProps, type FeatureRequestPayload, type FeedbackEmoji, type FeedbackPayload, type FeedbackRateLimit, FeedbackWidget, type FeedbackWidgetProps, type FeedbackWidgetRenderProps, Hotspot, type HotspotProps, NewBadge, type NewBadgeProps, type NewBadgeRenderProps, type PaginationMode, Spotlight, SpotlightChain, type SpotlightChainProps, type SpotlightChainRenderProps, type SpotlightChainStep, type SpotlightProps, type SpotlightRenderProps, Survey, type SurveyPayload, type SurveyProps, type SurveyQuestion, type SurveyQuestionType, type SurveyRenderProps, type SurveyTriggerRules, type SurveyType, ThemeProvider, type ThemeProviderProps, Toast, type ToastProps, type ToastRenderProps, TooltipGroup, type TooltipGroupProps, Tour, type TourProps, type TourRenderProps, type TourSequenceItem, type TourStep, type UseChecklistResult, type UseNewFeatureResult, type UseSurveyResult, type UseTabNotificationOptions, type UseTourResult, type UseTourSequencerResult, useAdoptionAnalytics, useChecklist, useFeatureDrop, useNewCount, useNewFeature, useSurvey, useTabNotification, useTour, useTourSequencer };
+declare const SmartAnnouncement: react.ComponentType<SmartAnnouncementProps>;
+
+export { AnnouncementModal, type AnnouncementModalProps, type AnnouncementModalRenderProps, type AnnouncementSlide, Banner, type BannerProps, type BannerRenderProps, type BannerVariant, type ChangelogEntryRenderProps, ChangelogPage, type ChangelogPageProps, ChangelogWidget, type ChangelogWidgetProps, type ChangelogWidgetRenderProps, Checklist, type ChecklistProps, type ChecklistRenderProps, type ChecklistTask, FeatureDropContext, type FeatureDropContextValue, FeatureDropProvider, type FeatureDropProviderProps, FeatureRequestButton, type FeatureRequestButtonProps, type FeatureRequestButtonRenderProps, FeatureRequestForm, type FeatureRequestFormProps, type FeatureRequestFormRenderProps, type FeatureRequestPayload, type FeedbackEmoji, type FeedbackPayload, type FeedbackRateLimit, FeedbackWidget, type FeedbackWidgetProps, type FeedbackWidgetRenderProps, Hotspot, type HotspotProps, NewBadge, type NewBadgeProps, type NewBadgeRenderProps, type PaginationMode, SmartAnnouncement, type SmartAnnouncementProps, type SmartAnnouncementRenderProps, Spotlight, SpotlightChain, type SpotlightChainProps, type SpotlightChainRenderProps, type SpotlightChainStep, type SpotlightProps, type SpotlightRenderProps, Survey, type SurveyPayload, type SurveyProps, type SurveyQuestion, type SurveyQuestionType, type SurveyRenderProps, type SurveyTriggerRules, type SurveyType, ThemeProvider, type ThemeProviderProps, Toast, type ToastProps, type ToastRenderProps, TooltipGroup, type TooltipGroupProps, Tour, type TourProps, type TourRenderProps, type TourSequenceItem, type TourStep, type UseAdoptionScoreResult, type UseBehaviorProfileResult, type UseChangelogResult, type UseChecklistResult, type UseNewFeatureResult, type UseSmartFeatureResult, type UseSurveyResult, type UseTabNotificationOptions, type UseTourResult, type UseTourSequencerResult, useAdoptionAnalytics, useAdoptionScore, useBehaviorProfile, useChangelog, useChecklist, useFeatureDrop, useNewCount, useNewFeature, useSmartFeature, useSurvey, useTabNotification, useTour, useTourSequencer };

package/dist/preact.d.ts

@@ -826,6 +826,144 @@ interface UseSurveyResult {
 }
 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;
+
+interface UseSmartFeatureResult {
+    /** Whether the engine recommends showing this feature now */
+    show: boolean;
+    /** Recommended display format */
+    format: DisplayFormat;
+    /** Fallback format if primary component isn't available */
+    fallbackFormat: DisplayFormat;
+    /** The feature entry from the manifest */
+    feature: FeatureEntry | undefined;
+    /** Dismiss the feature (also tracks dismissal in engine) */
+    dismiss: () => void;
+    /** Engine's confidence in this timing decision (0-1) */
+    confidence: number;
+    /** Reason for the timing decision */
+    reason: string;
+}
+/**
+ * Engine-powered smart feature display hook.
+ *
+ * Combines the TimingOptimizer and FormatSelector to decide
+ * whether to show a feature and what format to use.
+ *
+ * Without an engine, gracefully degrades to always-show with badge format.
+ *
+ * @param featureId - The feature ID to check
+ * @returns `{ show, format, fallbackFormat, feature, dismiss, confidence, reason }`
+ *
+ * @example
+ * ```tsx
+ * function MyFeature() {
+ *   const { show, format, feature, dismiss } = useSmartFeature('dark-mode')
+ *
+ *   if (!show) return null
+ *
+ *   switch (format) {
+ *     case 'badge': return <NewBadge id="dark-mode" />
+ *     case 'toast': return <Toast feature={feature} onDismiss={dismiss} />
+ *     case 'modal': return <AnnouncementModal feature={feature} onDismiss={dismiss} />
+ *     default: return <NewBadge id="dark-mode" />
+ *   }
+ * }
+ * ```
+ */
+declare function useSmartFeature(featureId: string): UseSmartFeatureResult;
+
+type UseAdoptionScoreResult = AdoptionScore;
+/**
+ * Get the user's overall feature adoption score.
+ *
+ * Returns a 0-100 score with letter grade, breakdown, and recommendations.
+ * Useful for admin dashboards, debug panels, or gamification.
+ *
+ * Without an engine, returns a perfect score with no recommendations.
+ *
+ * @returns `{ score, grade, breakdown, recommendations }`
+ *
+ * @example
+ * ```tsx
+ * function AdoptionDashboard() {
+ *   const { score, grade, breakdown, recommendations } = useAdoptionScore()
+ *
+ *   return (
+ *     <div>
+ *       <h2>Adoption Score: {score}/100 ({grade})</h2>
+ *       <p>Features explored: {Math.round(breakdown.featuresExplored * 100)}%</p>
+ *       <p>Completion rate: {Math.round(breakdown.completionRate * 100)}%</p>
+ *       <ul>
+ *         {recommendations.map((r, i) => <li key={i}>{r}</li>)}
+ *       </ul>
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+declare function useAdoptionScore(): UseAdoptionScoreResult;
+
+interface UseBehaviorProfileResult {
+    /** Total sessions tracked */
+    sessionCount: number;
+    /** Dismiss rate (0-1) — fraction of announcements dismissed */
+    dismissRate: number;
+    /** Engagement rate (0-1) — fraction of announcements clicked/completed */
+    engagementRate: number;
+    /** User's preferred display format based on past behavior */
+    preferredFormat: DisplayFormat;
+    /** Whether an engine is available */
+    hasEngine: boolean;
+}
+/**
+ * Access the user's behavior profile for debug or admin views.
+ *
+ * Exposes aggregated behavior data from the AdoptionEngine's BehaviorTracker.
+ * Without an engine, returns default values.
+ *
+ * @returns `{ sessionCount, dismissRate, engagementRate, preferredFormat, hasEngine }`
+ *
+ * @example
+ * ```tsx
+ * function DebugPanel() {
+ *   const { sessionCount, dismissRate, engagementRate, preferredFormat, hasEngine } = useBehaviorProfile()
+ *
+ *   if (!hasEngine) return <p>No engine configured</p>
+ *
+ *   return (
+ *     <div>
+ *       <p>Sessions: {sessionCount}</p>
+ *       <p>Dismiss rate: {(dismissRate * 100).toFixed(0)}%</p>
+ *       <p>Engagement rate: {(engagementRate * 100).toFixed(0)}%</p>
+ *       <p>Preferred format: {preferredFormat}</p>
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+declare function useBehaviorProfile(): UseBehaviorProfileResult;
+
 interface NewBadgeRenderProps {
     /** Whether the feature is currently new */
     isNew: boolean;
@@ -1271,6 +1409,35 @@ interface FeatureRequestFormProps {
     children?: (props: FeatureRequestFormRenderProps) => ReactNode;
 }
 
+interface SmartAnnouncementRenderProps {
+    /** Whether the engine recommends showing now */
+    show: boolean;
+    /** Recommended display format */
+    format: DisplayFormat;
+    /** Fallback format */
+    fallbackFormat: DisplayFormat;
+    /** The feature entry */
+    feature: FeatureEntry | undefined;
+    /** Dismiss callback (tracks in engine + provider) */
+    dismiss: () => void;
+    /** Engine confidence in the timing decision (0-1) */
+    confidence: number;
+    /** Reason for the decision */
+    reason: string;
+}
+interface SmartAnnouncementProps {
+    /** Feature ID to display */
+    id: string;
+    /** Override the engine's format recommendation */
+    format?: DisplayFormat;
+    /** Additional CSS class for the container */
+    className?: string;
+    /** Additional inline styles */
+    style?: CSSProperties;
+    /** Render prop for full customization */
+    children?: (props: SmartAnnouncementRenderProps) => ReactNode;
+}
+
 declare const NewBadge: react.ComponentType<NewBadgeProps>;
 
 declare const ChangelogWidget: react.ComponentType<ChangelogWidgetProps>;
@@ -1302,4 +1469,6 @@ declare const FeatureRequestButton: react.ComponentType<FeatureRequestButtonProp
 
 declare const FeatureRequestForm: react.ComponentType<FeatureRequestFormProps>;
 
-export { AnnouncementModal, type AnnouncementModalProps, type AnnouncementModalRenderProps, type AnnouncementSlide, Banner, type BannerProps, type BannerRenderProps, type BannerVariant, type ChangelogEntryRenderProps, ChangelogPage, type ChangelogPageProps, ChangelogWidget, type ChangelogWidgetProps, type ChangelogWidgetRenderProps, Checklist, type ChecklistProps, type ChecklistRenderProps, type ChecklistTask, FeatureDropContext, type FeatureDropContextValue, FeatureDropProvider, type FeatureDropProviderProps, FeatureRequestButton, type FeatureRequestButtonProps, type FeatureRequestButtonRenderProps, FeatureRequestForm, type FeatureRequestFormProps, type FeatureRequestFormRenderProps, type FeatureRequestPayload, type FeedbackEmoji, type FeedbackPayload, type FeedbackRateLimit, FeedbackWidget, type FeedbackWidgetProps, type FeedbackWidgetRenderProps, Hotspot, type HotspotProps, NewBadge, type NewBadgeProps, type NewBadgeRenderProps, type PaginationMode, Spotlight, SpotlightChain, type SpotlightChainProps, type SpotlightChainRenderProps, type SpotlightChainStep, type SpotlightProps, type SpotlightRenderProps, Survey, type SurveyPayload, type SurveyProps, type SurveyQuestion, type SurveyQuestionType, type SurveyRenderProps, type SurveyTriggerRules, type SurveyType, ThemeProvider, type ThemeProviderProps, Toast, type ToastProps, type ToastRenderProps, TooltipGroup, type TooltipGroupProps, Tour, type TourProps, type TourRenderProps, type TourSequenceItem, type TourStep, type UseChecklistResult, type UseNewFeatureResult, type UseSurveyResult, type UseTabNotificationOptions, type UseTourResult, type UseTourSequencerResult, useAdoptionAnalytics, useChecklist, useFeatureDrop, useNewCount, useNewFeature, useSurvey, useTabNotification, useTour, useTourSequencer };
+declare const SmartAnnouncement: react.ComponentType<SmartAnnouncementProps>;
+
+export { AnnouncementModal, type AnnouncementModalProps, type AnnouncementModalRenderProps, type AnnouncementSlide, Banner, type BannerProps, type BannerRenderProps, type BannerVariant, type ChangelogEntryRenderProps, ChangelogPage, type ChangelogPageProps, ChangelogWidget, type ChangelogWidgetProps, type ChangelogWidgetRenderProps, Checklist, type ChecklistProps, type ChecklistRenderProps, type ChecklistTask, FeatureDropContext, type FeatureDropContextValue, FeatureDropProvider, type FeatureDropProviderProps, FeatureRequestButton, type FeatureRequestButtonProps, type FeatureRequestButtonRenderProps, FeatureRequestForm, type FeatureRequestFormProps, type FeatureRequestFormRenderProps, type FeatureRequestPayload, type FeedbackEmoji, type FeedbackPayload, type FeedbackRateLimit, FeedbackWidget, type FeedbackWidgetProps, type FeedbackWidgetRenderProps, Hotspot, type HotspotProps, NewBadge, type NewBadgeProps, type NewBadgeRenderProps, type PaginationMode, SmartAnnouncement, type SmartAnnouncementProps, type SmartAnnouncementRenderProps, Spotlight, SpotlightChain, type SpotlightChainProps, type SpotlightChainRenderProps, type SpotlightChainStep, type SpotlightProps, type SpotlightRenderProps, Survey, type SurveyPayload, type SurveyProps, type SurveyQuestion, type SurveyQuestionType, type SurveyRenderProps, type SurveyTriggerRules, type SurveyType, ThemeProvider, type ThemeProviderProps, Toast, type ToastProps, type ToastRenderProps, TooltipGroup, type TooltipGroupProps, Tour, type TourProps, type TourRenderProps, type TourSequenceItem, type TourStep, type UseAdoptionScoreResult, type UseBehaviorProfileResult, type UseChangelogResult, type UseChecklistResult, type UseNewFeatureResult, type UseSmartFeatureResult, type UseSurveyResult, type UseTabNotificationOptions, type UseTourResult, type UseTourSequencerResult, useAdoptionAnalytics, useAdoptionScore, useBehaviorProfile, useChangelog, useChecklist, useFeatureDrop, useNewCount, useNewFeature, useSmartFeature, useSurvey, useTabNotification, useTour, useTourSequencer };