featuredrop 1.2.0 → 1.3.0

package/dist/preact.d.ts

@@ -1,11 +1,13 @@
-import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as react from 'react';
 import { ReactNode, CSSProperties, RefObject } from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
 
 /** 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 */
@@ -50,6 +52,10 @@ interface UserContext {
 }
 /** Custom audience matcher function */
 type AudienceMatchFn = (audience: AudienceRule, userContext: UserContext) => boolean;
+/** Feature flag resolver interface for gating announcement visibility */
+interface FeatureFlagBridge {
+    isEnabled: (flagKey: string, userContext?: UserContext) => boolean;
+}
 /** Dependency gates for progressive feature discovery */
 interface FeatureDependencies {
     /** Features the user must have seen before this one can surface */
@@ -130,8 +136,12 @@ interface FeatureEntry {
     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 */
@@ -280,6 +290,7 @@ interface FeatureDropTranslations {
     loadMore: string;
     share: string;
     skipToEntries: string;
+    newFeatureCount: (count: number) => string;
     stepOf: (current: number, total: number) => string;
     back: string;
     next: string;
@@ -302,20 +313,31 @@ interface FeatureDropProviderProps {
     storage: StorageAdapter;
     /** Optional analytics callbacks — pipe to your analytics provider */
     analytics?: AnalyticsCallbacks;
+    /** Optional error callback for monitoring caught component errors */
+    onError?: (error: unknown, context?: {
+        component?: string;
+        componentStack?: string;
+    }) => void;
     /** 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;
+    /** Current product scope for multi-product manifests */
+    product?: 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;
+    /** Feature flag bridge for evaluating `feature.flagKey` visibility */
+    flagBridge?: FeatureFlagBridge;
     /** Locale code for built-in component translations (e.g. "en", "fr", "es") */
     locale?: string;
+    /** Animation preset for built-in component transitions */
+    animation?: FeatureDropAnimationPreset;
     /** Custom translation overrides for built-in component strings */
     translations?: Partial<FeatureDropTranslations>;
     children: ReactNode;
@@ -326,7 +348,7 @@ interface FeatureDropProviderProps {
  * Wrap your app (or a subtree) with this provider to enable
  * `useFeatureDrop`, `useNewFeature`, `useNewCount`, and other hooks.
  */
-declare function FeatureDropProvider({ manifest, storage, analytics, userContext, matchAudience: matchAudienceFn, appVersion, throttle, variantKey, collector, locale, translations: translationOverrides, children, }: FeatureDropProviderProps): react_jsx_runtime.JSX.Element;
+declare function FeatureDropProvider({ manifest, storage, analytics, onError, userContext, matchAudience: matchAudienceFn, appVersion, product, throttle, variantKey, collector, flagBridge, locale, animation, translations: translationOverrides, children, }: FeatureDropProviderProps): react_jsx_runtime.JSX.Element;
 
 interface FeatureDropTheme {
     colors: {
@@ -440,8 +462,17 @@ interface FeatureDropContextValue {
     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 */
@@ -564,7 +595,6 @@ interface TourProps {
     persistence?: boolean;
     children?: (props: TourRenderProps) => ReactNode;
 }
-declare function Tour({ id, steps, onComplete, onSkip, onTourStarted, onTourCompleted, onTourSkipped, onStepViewed, overlay, showProgress, keyboard, persistence, children, }: TourProps): react_jsx_runtime.JSX.Element | null;
 
 interface TourSnapshot {
     isActive: boolean;
@@ -690,7 +720,6 @@ interface SurveyProps {
     style?: CSSProperties;
     children?: (props: SurveyRenderProps) => ReactNode;
 }
-declare function Survey({ id, type, prompt, featureId, questions, trigger, triggerRules, defaultOpen, showAskLater, submitLabel, askLaterLabel, closeLabel, title, metadata, onSubmit, onAskLater, onDismiss, className, style, children, }: SurveyProps): react_jsx_runtime.JSX.Element | null;
 
 interface UseSurveyResult {
     show: (options?: {
@@ -729,22 +758,6 @@ interface NewBadgeProps {
     /** Render prop for full customization */
     children?: (props: NewBadgeRenderProps) => ReactNode;
 }
-/**
- * Headless "New" badge component.
- *
- * Styled via CSS custom properties — zero CSS framework dependency:
- * - `--featuredrop-color` — text/dot color
- * - `--featuredrop-bg` — pill background
- * - `--featuredrop-font-size` — font size
- * - `--featuredrop-dot-size` — dot diameter
- * - `--featuredrop-glow` — dot glow color
- * - `--featuredrop-count-size` — count badge size
- * - `--featuredrop-count-color` — count text color
- * - `--featuredrop-count-bg` — count background
- *
- * Use `data-featuredrop` attribute for CSS selector styling.
- */
-declare function NewBadge({ variant, show, count, label, onDismiss, dismissOnClick, className, style, children, }: NewBadgeProps): react_jsx_runtime.JSX.Element | null;
 
 type ReactionCounts = Record<string, number>;
 
@@ -792,6 +805,8 @@ interface ChangelogWidgetProps {
     emptyLabel?: string;
     /** Max height for the feed area. Default: "400px" */
     maxHeight?: string;
+    /** Date display mode for entry metadata. Default: "absolute" */
+    dateFormat?: "absolute" | "relative";
     /** Analytics callbacks */
     analytics?: AnalyticsCallbacks;
     /** Additional CSS class for the container */
@@ -816,30 +831,6 @@ interface ChangelogWidgetProps {
     /** Callback fired when a reaction is persisted */
     onReaction?: (feature: FeatureEntry, reaction: string, counts: ReactionCounts) => void;
 }
-/**
- * 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, theme, children, renderEntry, renderTrigger, showReactions, reactions, onReaction, }: ChangelogWidgetProps): react_jsx_runtime.JSX.Element;
 
 interface SpotlightRenderProps {
     /** The feature being spotlighted */
@@ -879,25 +870,6 @@ interface SpotlightProps {
     /** 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 {
@@ -928,28 +900,6 @@ interface BannerProps {
     /** 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 */
@@ -982,32 +932,6 @@ interface ToastProps {
         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;
 
 type PaginationMode = "infinite-scroll" | "load-more" | "numbered";
 interface ChangelogPageProps {
@@ -1019,6 +943,7 @@ interface ChangelogPageProps {
     emptyState?: ReactNode;
     renderEntry?: (entry: FeatureEntry, index: number) => ReactNode;
     formatDate?: (date: string) => string;
+    dateFormat?: "absolute" | "relative";
     basePath?: string;
     manifest?: FeatureManifest;
     className?: string;
@@ -1028,7 +953,6 @@ interface ChangelogPageProps {
     reactions?: string[];
     onReaction?: (entry: FeatureEntry, reaction: string, counts: ReactionCounts) => void;
 }
-declare function ChangelogPage({ pageSize, pagination, showFilters, showSearch, categories, emptyState, renderEntry, formatDate, basePath, manifest: manifestProp, className, style, theme, showReactions, reactions, onReaction, }: ChangelogPageProps): react_jsx_runtime.JSX.Element;
 
 interface ChecklistTask {
     id: string;
@@ -1069,7 +993,6 @@ interface ChecklistProps {
     actionHandlers?: Record<string, () => void>;
     children?: (props: ChecklistRenderProps) => ReactNode;
 }
-declare function Checklist({ id, tasks, position, collapsible, showProgress, onComplete, dismissible, actionHandlers, children, }: ChecklistProps): react_jsx_runtime.JSX.Element | null;
 
 interface HotspotProps {
     id: string;
@@ -1082,8 +1005,6 @@ interface TooltipGroupProps {
     maxVisible?: number;
     children: ReactNode;
 }
-declare function TooltipGroup({ maxVisible, children }: TooltipGroupProps): react_jsx_runtime.JSX.Element;
-declare function Hotspot({ id, target, type, frequency, children, }: HotspotProps): react_jsx_runtime.JSX.Element | null;
 
 type FeedbackEmoji = "thumbs-up" | "thumbs-down" | "heart" | "thinking" | "fire";
 interface FeedbackPayload {
@@ -1130,7 +1051,6 @@ interface FeedbackWidgetProps {
     style?: CSSProperties;
     children?: (props: FeedbackWidgetRenderProps) => ReactNode;
 }
-declare function FeedbackWidget({ featureId, onSubmit, showScreenshot, showEmoji, rateLimit, categories, metadata, screenshotCapture, triggerLabel, title, className, style, children, }: FeedbackWidgetProps): react_jsx_runtime.JSX.Element;
 
 interface AnnouncementSlide {
     id?: string;
@@ -1170,7 +1090,6 @@ interface AnnouncementModalProps {
     style?: CSSProperties;
     children?: (props: AnnouncementModalRenderProps) => ReactNode;
 }
-declare function AnnouncementModal({ id, featureId, feature, trigger, defaultOpen, slides, frequency, dismissible, mobileBreakpoint, onOpen, onDismiss, onPrimaryCtaClick, onSecondaryCtaClick, className, style, children, }: AnnouncementModalProps): react_jsx_runtime.JSX.Element | null;
 
 interface SpotlightChainStep {
     id?: string;
@@ -1198,7 +1117,6 @@ interface SpotlightChainProps {
     onSkip?: (step: SpotlightChainStep | null, index: number) => void;
     children?: (props: SpotlightChainRenderProps) => ReactNode;
 }
-declare function SpotlightChain({ steps, startOnMount, autoAdvance, autoAdvanceMs, onComplete, onStepViewed, onSkip, children, }: SpotlightChainProps): react_jsx_runtime.JSX.Element | null;
 
 interface FeatureRequestRecord {
     id: string;
@@ -1231,7 +1149,6 @@ interface FeatureRequestButtonProps {
     style?: CSSProperties;
     children?: (props: FeatureRequestButtonRenderProps) => ReactNode;
 }
-declare function FeatureRequestButton({ featureId, requestId, requestTitle, label, onVote, className, style, children, }: FeatureRequestButtonProps): react_jsx_runtime.JSX.Element;
 
 interface FeatureRequestPayload extends FeatureRequestRecord {
     metadata?: Record<string, unknown>;
@@ -1261,6 +1178,36 @@ interface FeatureRequestFormProps {
     style?: CSSProperties;
     children?: (props: FeatureRequestFormRenderProps) => ReactNode;
 }
-declare function FeatureRequestForm({ onSubmit, onWebhook, categories, defaultSort, metadata, className, style, children, }: FeatureRequestFormProps): react_jsx_runtime.JSX.Element;
+
+declare const NewBadge: react.ComponentType<NewBadgeProps>;
+
+declare const ChangelogWidget: react.ComponentType<ChangelogWidgetProps>;
+
+declare const Spotlight: react.ComponentType<SpotlightProps>;
+
+declare const Banner: react.ComponentType<BannerProps>;
+
+declare const Toast: react.ComponentType<ToastProps>;
+
+declare const ChangelogPage: react.ComponentType<ChangelogPageProps>;
+
+declare const Tour: react.ComponentType<TourProps>;
+
+declare const Checklist: react.ComponentType<ChecklistProps>;
+
+declare const Hotspot: react.ComponentType<HotspotProps>;
+declare const TooltipGroup: react.ComponentType<TooltipGroupProps>;
+
+declare const FeedbackWidget: react.ComponentType<FeedbackWidgetProps>;
+
+declare const AnnouncementModal: react.ComponentType<AnnouncementModalProps>;
+
+declare const SpotlightChain: react.ComponentType<SpotlightChainProps>;
+
+declare const Survey: react.ComponentType<SurveyProps>;
+
+declare const FeatureRequestButton: react.ComponentType<FeatureRequestButtonProps>;
+
+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 };