featuredrop 1.1.0 → 1.3.0

package/dist/angular.d.cts

@@ -0,0 +1,233 @@
+/** 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 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;
+}
+/** 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 SignalLike<T> {
+    (): T;
+    set: (value: T) => void;
+}
+type CreateSignalLikeFn = <T>(initial: T) => SignalLike<T>;
+interface AngularFeatureDropOptions {
+    manifest: FeatureManifest;
+    storage: StorageAdapter;
+    createSignal: CreateSignalLikeFn;
+    analytics?: AnalyticsCallbacks;
+    userContext?: UserContext;
+    matchAudience?: AudienceMatchFn;
+    appVersion?: string;
+}
+interface AngularFeatureDropService {
+    manifest: FeatureManifest;
+    newFeatures: SignalLike<FeatureEntry[]>;
+    newCount: () => number;
+    newFeaturesSorted: () => FeatureEntry[];
+    refresh: () => void;
+    dismiss: (id: string) => void;
+    dismissAll: () => Promise<void>;
+    isNew: (sidebarKey: string) => boolean;
+    getFeature: (sidebarKey: string) => FeatureEntry | undefined;
+}
+declare function createFeatureDropService(options: AngularFeatureDropOptions): AngularFeatureDropService;
+declare class FeatureDropService {
+    readonly manifest: FeatureManifest;
+    readonly newFeatures: SignalLike<FeatureEntry[]>;
+    private readonly service;
+    constructor(options: AngularFeatureDropOptions);
+    newCount(): number;
+    newFeaturesSorted(): FeatureEntry[];
+    refresh(): void;
+    dismiss(id: string): void;
+    dismissAll(): Promise<void>;
+    isNew(sidebarKey: string): boolean;
+    getFeature(sidebarKey: string): FeatureEntry | undefined;
+}
+
+export { type AngularFeatureDropOptions, type AngularFeatureDropService, type CreateSignalLikeFn, FeatureDropService, type SignalLike, createFeatureDropService };

package/dist/angular.d.ts

@@ -0,0 +1,233 @@
+/** 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 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;
+}
+/** 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 SignalLike<T> {
+    (): T;
+    set: (value: T) => void;
+}
+type CreateSignalLikeFn = <T>(initial: T) => SignalLike<T>;
+interface AngularFeatureDropOptions {
+    manifest: FeatureManifest;
+    storage: StorageAdapter;
+    createSignal: CreateSignalLikeFn;
+    analytics?: AnalyticsCallbacks;
+    userContext?: UserContext;
+    matchAudience?: AudienceMatchFn;
+    appVersion?: string;
+}
+interface AngularFeatureDropService {
+    manifest: FeatureManifest;
+    newFeatures: SignalLike<FeatureEntry[]>;
+    newCount: () => number;
+    newFeaturesSorted: () => FeatureEntry[];
+    refresh: () => void;
+    dismiss: (id: string) => void;
+    dismissAll: () => Promise<void>;
+    isNew: (sidebarKey: string) => boolean;
+    getFeature: (sidebarKey: string) => FeatureEntry | undefined;
+}
+declare function createFeatureDropService(options: AngularFeatureDropOptions): AngularFeatureDropService;
+declare class FeatureDropService {
+    readonly manifest: FeatureManifest;
+    readonly newFeatures: SignalLike<FeatureEntry[]>;
+    private readonly service;
+    constructor(options: AngularFeatureDropOptions);
+    newCount(): number;
+    newFeaturesSorted(): FeatureEntry[];
+    refresh(): void;
+    dismiss(id: string): void;
+    dismissAll(): Promise<void>;
+    isNew(sidebarKey: string): boolean;
+    getFeature(sidebarKey: string): FeatureEntry | undefined;
+}
+
+export { type AngularFeatureDropOptions, type AngularFeatureDropService, type CreateSignalLikeFn, FeatureDropService, type SignalLike, createFeatureDropService };