featuredrop 1.0.1 → 1.1.0

package/dist/react.d.ts

@@ -1,14 +1,25 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as react from 'react';
-import { ReactNode, CSSProperties } from 'react';
+import { ReactNode, CSSProperties, RefObject } 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";
+/** Call-to-action for a feature entry */
+interface FeatureCTA {
+    /** Button/link label */
+    label: string;
+    /** URL to navigate to */
+    url: string;
+}
 /** 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 */
+    /** Optional longer description (supports markdown in UI components) */
     description?: string;
     /** ISO date when this feature was released */
     releasedAt: string;
@@ -22,6 +33,16 @@ interface FeatureEntry {
     url?: string;
     /** Optional version string when this feature shipped */
     version?: 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>;
 }
@@ -44,27 +65,46 @@ interface StorageAdapter {
     /** 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 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;
     children: ReactNode;
 }
 /**
  * Provides feature discovery state to the component tree.
  *
  * Wrap your app (or a subtree) with this provider to enable
- * `useFeatureDrop`, `useNewFeature`, and `useNewCount` hooks.
+ * `useFeatureDrop`, `useNewFeature`, `useNewCount`, and other hooks.
  */
-declare function FeatureDropProvider({ manifest, storage, children, }: FeatureDropProviderProps): react_jsx_runtime.JSX.Element;
+declare function FeatureDropProvider({ manifest, storage, analytics, children, }: FeatureDropProviderProps): react_jsx_runtime.JSX.Element;
 
 interface FeatureDropContextValue {
     /** All currently "new" features */
     newFeatures: FeatureEntry[];
     /** Count of new features */
     newCount: 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 */
@@ -110,6 +150,37 @@ declare function useNewFeature(sidebarKey: string): UseNewFeatureResult;
  */
 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;
+
 interface NewBadgeRenderProps {
     /** Whether the feature is currently new */
     isNew: boolean;
@@ -151,4 +222,252 @@ interface NewBadgeProps {
  */
 declare function NewBadge({ variant, show, count, label, onDismiss, dismissOnClick, className, style, children, }: NewBadgeProps): react_jsx_runtime.JSX.Element | null;
 
-export { FeatureDropContext, type FeatureDropContextValue, FeatureDropProvider, type FeatureDropProviderProps, NewBadge, type NewBadgeProps, type NewBadgeRenderProps, type UseNewFeatureResult, useFeatureDrop, useNewCount, useNewFeature };
+interface ChangelogEntryRenderProps {
+    feature: FeatureEntry;
+    dismiss: () => void;
+}
+interface ChangelogWidgetRenderProps {
+    /** Whether the widget is currently open */
+    isOpen: boolean;
+    /** Open the widget */
+    open: () => void;
+    /** Close the widget */
+    close: () => void;
+    /** Toggle open/close */
+    toggle: () => void;
+    /** Current new feature count */
+    count: number;
+    /** Sorted features to display */
+    features: FeatureEntry[];
+    /** Dismiss a single feature */
+    dismiss: (id: string) => void;
+    /** Dismiss all features */
+    dismissAll: () => Promise<void>;
+}
+interface ChangelogWidgetProps {
+    /** Display variant */
+    variant?: "panel" | "modal" | "popover";
+    /** Title shown in the widget header. Default: "What's New" */
+    title?: string;
+    /** Text for the trigger button. Default: "What's New" */
+    triggerLabel?: string;
+    /** Show trigger badge count. Default: true */
+    showCount?: boolean;
+    /** Text for the "mark all as read" button. Default: "Mark all as read" */
+    markAllLabel?: string;
+    /** Whether to show the mark-all button. Default: true */
+    showMarkAll?: boolean;
+    /** Text shown when no new features exist. Default: "You're all caught up!" */
+    emptyLabel?: string;
+    /** Max height for the feed area. Default: "400px" */
+    maxHeight?: string;
+    /** Analytics callbacks */
+    analytics?: AnalyticsCallbacks;
+    /** Additional CSS class for the container */
+    className?: string;
+    /** Additional inline styles for the container */
+    style?: CSSProperties;
+    /** Render prop for full customization — receives widget state */
+    children?: (props: ChangelogWidgetRenderProps) => ReactNode;
+    /** Custom render for each entry — receives feature + dismiss callback */
+    renderEntry?: (props: ChangelogEntryRenderProps) => ReactNode;
+    /** Custom render for the trigger button */
+    renderTrigger?: (props: {
+        count: number;
+        onClick: () => void;
+    }) => ReactNode;
+}
+/**
+ * Changelog widget — the #1 feature for feature discovery tools.
+ *
+ * Renders a trigger button with an unread count badge and a
+ * slide-out panel, modal, or popover with the changelog feed.
+ *
+ * Styled via CSS custom properties — zero framework dependency.
+ * Use `children` render prop for full headless control.
+ *
+ * @example
+ * ```tsx
+ * <ChangelogWidget variant="panel" />
+ * ```
+ *
+ * @example Headless mode
+ * ```tsx
+ * <ChangelogWidget>
+ *   {({ isOpen, toggle, features, count }) => (
+ *     <MyCustomUI ... />
+ *   )}
+ * </ChangelogWidget>
+ * ```
+ */
+declare function ChangelogWidget({ variant, title, triggerLabel, showCount, markAllLabel, showMarkAll, emptyLabel, maxHeight, analytics, className, style, children, renderEntry, renderTrigger, }: ChangelogWidgetProps): react_jsx_runtime.JSX.Element;
+
+interface SpotlightRenderProps {
+    /** The feature being spotlighted */
+    feature: FeatureEntry | undefined;
+    /** Whether the spotlight is active */
+    isActive: boolean;
+    /** Whether the tooltip is visible */
+    isTooltipOpen: boolean;
+    /** Show the tooltip */
+    openTooltip: () => void;
+    /** Hide the tooltip */
+    closeTooltip: () => void;
+    /** Dismiss this spotlight permanently */
+    dismiss: () => void;
+}
+interface SpotlightProps {
+    /** The feature ID to spotlight */
+    featureId: string;
+    /** Ref to the target DOM element — beacon will be positioned over it */
+    targetRef?: RefObject<HTMLElement | null>;
+    /** CSS selector for the target element (alternative to targetRef) */
+    targetSelector?: string;
+    /** Tooltip placement relative to target */
+    placement?: "top" | "bottom" | "left" | "right";
+    /** Beacon size in pixels. Default: 12 */
+    beaconSize?: number;
+    /** Auto-dismiss after the tooltip is seen */
+    autoDismiss?: boolean;
+    /** Delay before auto-dismiss in ms. Default: 5000 */
+    autoDismissDelay?: number;
+    /** Analytics callbacks */
+    analytics?: AnalyticsCallbacks;
+    /** Additional CSS class */
+    className?: string;
+    /** Custom tooltip content */
+    tooltipContent?: ReactNode;
+    /** Render prop for full customization */
+    children?: (props: SpotlightRenderProps) => ReactNode;
+}
+/**
+ * Pulsing beacon that attaches to any DOM element to highlight a new feature.
+ *
+ * Clicking the beacon reveals a tooltip with feature info.
+ * After dismissal, the beacon disappears permanently for this user.
+ *
+ * @example
+ * ```tsx
+ * const ref = useRef<HTMLButtonElement>(null);
+ * <button ref={ref}>Analytics</button>
+ * <Spotlight featureId="analytics-v2" targetRef={ref} />
+ * ```
+ *
+ * @example With CSS selector
+ * ```tsx
+ * <Spotlight featureId="analytics-v2" targetSelector="#analytics-btn" />
+ * ```
+ */
+declare function Spotlight({ featureId, targetRef, targetSelector, placement, beaconSize, autoDismiss, autoDismissDelay, analytics, className, tooltipContent, children, }: SpotlightProps): react_jsx_runtime.JSX.Element | null;
+
+type BannerVariant = "info" | "success" | "warning" | "announcement";
+interface BannerRenderProps {
+    /** The feature being announced */
+    feature: FeatureEntry | undefined;
+    /** Whether the banner is active */
+    isActive: boolean;
+    /** Whether the banner has been dismissed this session */
+    isDismissed: boolean;
+    /** Dismiss the banner permanently */
+    dismiss: () => void;
+}
+interface BannerProps {
+    /** Feature ID to display as a banner */
+    featureId: string;
+    /** Banner visual variant. Default: "announcement" */
+    variant?: BannerVariant;
+    /** Whether the banner is dismissible. Default: true */
+    dismissible?: boolean;
+    /** Position mode. Default: "sticky" */
+    position?: "sticky" | "inline" | "fixed";
+    /** Analytics callbacks */
+    analytics?: AnalyticsCallbacks;
+    /** Additional CSS class */
+    className?: string;
+    /** Additional inline styles */
+    style?: CSSProperties;
+    /** Render prop for full customization */
+    children?: (props: BannerRenderProps) => ReactNode;
+}
+/**
+ * Announcement banner for major feature launches or important notices.
+ *
+ * Shows at the top of the page (sticky/fixed) or inline in content.
+ * Auto-expires using the same `showNewUntil` logic as badges.
+ * Styled via CSS custom properties for each variant.
+ *
+ * @example
+ * ```tsx
+ * <Banner featureId="v2-launch" variant="announcement" />
+ * ```
+ *
+ * @example Headless
+ * ```tsx
+ * <Banner featureId="v2-launch">
+ *   {({ feature, dismiss }) => (
+ *     <div>New: {feature?.label} <button onClick={dismiss}>x</button></div>
+ *   )}
+ * </Banner>
+ * ```
+ */
+declare function Banner({ featureId, variant, dismissible, position, analytics, className, style, children, }: BannerProps): react_jsx_runtime.JSX.Element | null;
+
+interface ToastRenderProps {
+    /** Features currently showing as toasts */
+    toasts: FeatureEntry[];
+    /** Dismiss a specific toast */
+    dismiss: (id: string) => void;
+    /** Dismiss all toasts */
+    dismissAll: () => void;
+}
+interface ToastProps {
+    /** Feature IDs to show as toasts. If omitted, shows all new features. */
+    featureIds?: string[];
+    /** Max number of visible toasts at once. Default: 3 */
+    maxVisible?: number;
+    /** Auto-dismiss delay in ms. Default: 8000. Set to 0 to disable. */
+    autoDismissMs?: number;
+    /** Position on screen. Default: "bottom-right" */
+    position?: "top-right" | "top-left" | "bottom-right" | "bottom-left" | "top-center" | "bottom-center";
+    /** Analytics callbacks */
+    analytics?: AnalyticsCallbacks;
+    /** Additional CSS class for the container */
+    className?: string;
+    /** Additional inline styles for the container */
+    style?: CSSProperties;
+    /** Render prop for full customization */
+    children?: (props: ToastRenderProps) => ReactNode;
+    /** Custom render for each toast */
+    renderToast?: (props: {
+        feature: FeatureEntry;
+        dismiss: () => void;
+    }) => ReactNode;
+}
+/**
+ * Toast notification component for feature announcements.
+ *
+ * Shows brief popups for new features. Auto-dismisses after a timeout.
+ * Stacks multiple toasts with configurable max visible count.
+ *
+ * @example
+ * ```tsx
+ * <Toast position="bottom-right" maxVisible={3} />
+ * ```
+ *
+ * @example Specific features
+ * ```tsx
+ * <Toast featureIds={["ai-journal", "analytics-v2"]} />
+ * ```
+ *
+ * @example Headless
+ * ```tsx
+ * <Toast>
+ *   {({ toasts, dismiss }) => toasts.map(t => (
+ *     <div key={t.id}>{t.label} <button onClick={() => dismiss(t.id)}>x</button></div>
+ *   ))}
+ * </Toast>
+ * ```
+ */
+declare function Toast({ featureIds, maxVisible, autoDismissMs, position, analytics, className, style, children, renderToast, }: ToastProps): react_jsx_runtime.JSX.Element | null;
+
+export { Banner, type BannerProps, type BannerRenderProps, type BannerVariant, type ChangelogEntryRenderProps, ChangelogWidget, type ChangelogWidgetProps, type ChangelogWidgetRenderProps, FeatureDropContext, type FeatureDropContextValue, FeatureDropProvider, type FeatureDropProviderProps, NewBadge, type NewBadgeProps, type NewBadgeRenderProps, Spotlight, type SpotlightProps, type SpotlightRenderProps, Toast, type ToastProps, type ToastRenderProps, type UseNewFeatureResult, type UseTabNotificationOptions, useFeatureDrop, useNewCount, useNewFeature, useTabNotification };