featuredrop 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,131 @@
+/** 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 */
+    description?: 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 URL to link to (e.g. docs page, changelog entry) */
+    url?: string;
+    /** Optional version string when this feature shipped */
+    version?: string;
+    /** Optional arbitrary metadata */
+    meta?: Record<string, unknown>;
+}
+/** 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>;
+}
+
+/**
+ * Check if a single feature should show as "new".
+ *
+ * A feature is "new" when ALL of these are true:
+ * 1. Current time is before `showNewUntil`
+ * 2. Feature was released after the watermark (or no watermark exists)
+ * 3. Feature has not been individually dismissed
+ */
+declare function isNew(feature: FeatureEntry, watermark: string | null, dismissedIds: ReadonlySet<string>, now?: Date): boolean;
+/**
+ * Get all features that are currently "new" for this user.
+ */
+declare function getNewFeatures(manifest: FeatureManifest, storage: StorageAdapter, now?: Date): FeatureEntry[];
+/**
+ * Get the count of new features.
+ */
+declare function getNewFeatureCount(manifest: FeatureManifest, storage: StorageAdapter, now?: Date): number;
+/**
+ * Check if a specific sidebar key has a new feature.
+ */
+declare function hasNewFeature(manifest: FeatureManifest, sidebarKey: string, storage: StorageAdapter, now?: Date): boolean;
+
+/**
+ * Create a frozen feature manifest from an array of entries.
+ * Ensures the manifest is immutable at runtime.
+ */
+declare function createManifest(entries: FeatureEntry[]): FeatureManifest;
+/**
+ * Find a feature by its ID in the manifest.
+ * Returns `undefined` if not found.
+ */
+declare function getFeatureById(manifest: FeatureManifest, id: string): FeatureEntry | undefined;
+/**
+ * Get all new features in a specific category.
+ */
+declare function getNewFeaturesByCategory(manifest: FeatureManifest, category: string, storage: StorageAdapter, now?: Date): FeatureEntry[];
+
+interface LocalStorageAdapterOptions {
+    /** Key prefix for localStorage entries. Default: "featuredrop" */
+    prefix?: string;
+    /** Server-side watermark (ISO string). Typically from user profile. */
+    watermark?: string | null;
+    /** Callback when dismissAll is called. Use for server-side watermark updates. */
+    onDismissAll?: (now: Date) => Promise<void>;
+}
+/**
+ * localStorage-based storage adapter.
+ *
+ * Architecture:
+ * - **Watermark** comes from the server (passed at construction time)
+ * - **Per-feature dismissals** are stored in localStorage (zero server writes)
+ * - **dismissAll()** optionally calls a server callback, then clears localStorage
+ *
+ * Gracefully handles SSR environments where `window`/`localStorage` is unavailable.
+ */
+declare class LocalStorageAdapter implements StorageAdapter {
+    private readonly prefix;
+    private readonly watermarkValue;
+    private readonly onDismissAllCallback?;
+    private readonly dismissedKey;
+    constructor(options?: LocalStorageAdapterOptions);
+    getWatermark(): string | null;
+    getDismissedIds(): ReadonlySet<string>;
+    dismiss(id: string): void;
+    dismissAll(now: Date): Promise<void>;
+}
+
+/**
+ * In-memory storage adapter.
+ *
+ * Useful for:
+ * - Testing (no side effects)
+ * - Server-side rendering (no `window`/`localStorage`)
+ * - Environments without persistent storage
+ */
+declare class MemoryAdapter implements StorageAdapter {
+    private watermark;
+    private dismissed;
+    constructor(options?: {
+        watermark?: string | null;
+    });
+    getWatermark(): string | null;
+    getDismissedIds(): ReadonlySet<string>;
+    dismiss(id: string): void;
+    dismissAll(now: Date): Promise<void>;
+}
+
+export { type FeatureEntry, type FeatureManifest, LocalStorageAdapter, type LocalStorageAdapterOptions, MemoryAdapter, type StorageAdapter, createManifest, getFeatureById, getNewFeatureCount, getNewFeatures, getNewFeaturesByCategory, hasNewFeature, isNew };

package/dist/index.js

@@ -0,0 +1,123 @@
+// src/core.ts
+function isNew(feature, watermark, dismissedIds, now = /* @__PURE__ */ new Date()) {
+  if (dismissedIds.has(feature.id)) return false;
+  const nowMs = now.getTime();
+  const showUntilMs = new Date(feature.showNewUntil).getTime();
+  if (nowMs >= showUntilMs) return false;
+  if (watermark) {
+    const watermarkMs = new Date(watermark).getTime();
+    const releasedMs = new Date(feature.releasedAt).getTime();
+    if (releasedMs <= watermarkMs) return false;
+  }
+  return true;
+}
+function getNewFeatures(manifest, storage, now = /* @__PURE__ */ new Date()) {
+  const watermark = storage.getWatermark();
+  const dismissedIds = storage.getDismissedIds();
+  return manifest.filter((f) => isNew(f, watermark, dismissedIds, now));
+}
+function getNewFeatureCount(manifest, storage, now = /* @__PURE__ */ new Date()) {
+  return getNewFeatures(manifest, storage, now).length;
+}
+function hasNewFeature(manifest, sidebarKey, storage, now = /* @__PURE__ */ new Date()) {
+  const watermark = storage.getWatermark();
+  const dismissedIds = storage.getDismissedIds();
+  return manifest.some(
+    (f) => f.sidebarKey === sidebarKey && isNew(f, watermark, dismissedIds, now)
+  );
+}
+
+// src/helpers.ts
+function createManifest(entries) {
+  return Object.freeze([...entries]);
+}
+function getFeatureById(manifest, id) {
+  return manifest.find((f) => f.id === id);
+}
+function getNewFeaturesByCategory(manifest, category, storage, now = /* @__PURE__ */ new Date()) {
+  const watermark = storage.getWatermark();
+  const dismissedIds = storage.getDismissedIds();
+  return manifest.filter(
+    (f) => f.category === category && isNew(f, watermark, dismissedIds, now)
+  );
+}
+
+// src/adapters/local-storage.ts
+var DISMISSED_SUFFIX = ":dismissed";
+var LocalStorageAdapter = class {
+  prefix;
+  watermarkValue;
+  onDismissAllCallback;
+  dismissedKey;
+  constructor(options = {}) {
+    this.prefix = options.prefix ?? "featuredrop";
+    this.watermarkValue = options.watermark ?? null;
+    this.onDismissAllCallback = options.onDismissAll;
+    this.dismissedKey = `${this.prefix}${DISMISSED_SUFFIX}`;
+  }
+  getWatermark() {
+    return this.watermarkValue;
+  }
+  getDismissedIds() {
+    try {
+      if (typeof window === "undefined") return /* @__PURE__ */ new Set();
+      const raw = localStorage.getItem(this.dismissedKey);
+      if (!raw) return /* @__PURE__ */ new Set();
+      const parsed = JSON.parse(raw);
+      if (Array.isArray(parsed)) return new Set(parsed);
+      return /* @__PURE__ */ new Set();
+    } catch {
+      return /* @__PURE__ */ new Set();
+    }
+  }
+  dismiss(id) {
+    try {
+      if (typeof window === "undefined") return;
+      const raw = localStorage.getItem(this.dismissedKey);
+      const existing = raw ? JSON.parse(raw) : [];
+      if (!existing.includes(id)) {
+        existing.push(id);
+        localStorage.setItem(this.dismissedKey, JSON.stringify(existing));
+      }
+    } catch {
+    }
+  }
+  async dismissAll(now) {
+    try {
+      if (typeof window !== "undefined") {
+        localStorage.removeItem(this.dismissedKey);
+      }
+    } catch {
+    }
+    if (this.onDismissAllCallback) {
+      await this.onDismissAllCallback(now);
+    }
+  }
+};
+
+// src/adapters/memory.ts
+var MemoryAdapter = class {
+  watermark;
+  dismissed;
+  constructor(options = {}) {
+    this.watermark = options.watermark ?? null;
+    this.dismissed = /* @__PURE__ */ new Set();
+  }
+  getWatermark() {
+    return this.watermark;
+  }
+  getDismissedIds() {
+    return this.dismissed;
+  }
+  dismiss(id) {
+    this.dismissed.add(id);
+  }
+  async dismissAll(now) {
+    this.watermark = now.toISOString();
+    this.dismissed.clear();
+  }
+};
+
+export { LocalStorageAdapter, MemoryAdapter, createManifest, getFeatureById, getNewFeatureCount, getNewFeatures, getNewFeaturesByCategory, hasNewFeature, isNew };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core.ts","../src/helpers.ts","../src/adapters/local-storage.ts","../src/adapters/memory.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import type { FeatureEntry, FeatureManifest, StorageAdapter } from \"./types\";\n\n/**\n * Check if a single feature should show as \"new\".\n *\n * A feature is \"new\" when ALL of these are true:\n * 1. Current time is before `showNewUntil`\n * 2. Feature was released after the watermark (or no watermark exists)\n * 3. Feature has not been individually dismissed\n */\nexport function isNew(\n  feature: FeatureEntry,\n  watermark: string | null,\n  dismissedIds: ReadonlySet<string>,\n  now: Date = new Date(),\n): boolean {\n  // Already dismissed by the user on this device\n  if (dismissedIds.has(feature.id)) return false;\n\n  const nowMs = now.getTime();\n  const showUntilMs = new Date(feature.showNewUntil).getTime();\n\n  // Past the display window\n  if (nowMs >= showUntilMs) return false;\n\n  // If there's a watermark, feature must have been released after it\n  if (watermark) {\n    const watermarkMs = new Date(watermark).getTime();\n    const releasedMs = new Date(feature.releasedAt).getTime();\n    if (releasedMs <= watermarkMs) return false;\n  }\n\n  return true;\n}\n\n/**\n * Get all features that are currently \"new\" for this user.\n */\nexport function getNewFeatures(\n  manifest: FeatureManifest,\n  storage: StorageAdapter,\n  now: Date = new Date(),\n): FeatureEntry[] {\n  const watermark = storage.getWatermark();\n  const dismissedIds = storage.getDismissedIds();\n  return manifest.filter((f) => isNew(f, watermark, dismissedIds, now));\n}\n\n/**\n * Get the count of new features.\n */\nexport function getNewFeatureCount(\n  manifest: FeatureManifest,\n  storage: StorageAdapter,\n  now: Date = new Date(),\n): number {\n  return getNewFeatures(manifest, storage, now).length;\n}\n\n/**\n * Check if a specific sidebar key has a new feature.\n */\nexport function hasNewFeature(\n  manifest: FeatureManifest,\n  sidebarKey: string,\n  storage: StorageAdapter,\n  now: Date = new Date(),\n): boolean {\n  const watermark = storage.getWatermark();\n  const dismissedIds = storage.getDismissedIds();\n  return manifest.some(\n    (f) => f.sidebarKey === sidebarKey && isNew(f, watermark, dismissedIds, now),\n  );\n}\n","import type { FeatureEntry, FeatureManifest, StorageAdapter } from \"./types\";\nimport { isNew } from \"./core\";\n\n/**\n * Create a frozen feature manifest from an array of entries.\n * Ensures the manifest is immutable at runtime.\n */\nexport function createManifest(\n  entries: FeatureEntry[],\n): FeatureManifest {\n  return Object.freeze([...entries]);\n}\n\n/**\n * Find a feature by its ID in the manifest.\n * Returns `undefined` if not found.\n */\nexport function getFeatureById(\n  manifest: FeatureManifest,\n  id: string,\n): FeatureEntry | undefined {\n  return manifest.find((f) => f.id === id);\n}\n\n/**\n * Get all new features in a specific category.\n */\nexport function getNewFeaturesByCategory(\n  manifest: FeatureManifest,\n  category: string,\n  storage: StorageAdapter,\n  now: Date = new Date(),\n): FeatureEntry[] {\n  const watermark = storage.getWatermark();\n  const dismissedIds = storage.getDismissedIds();\n  return manifest.filter(\n    (f) => f.category === category && isNew(f, watermark, dismissedIds, now),\n  );\n}\n","import type { StorageAdapter } from \"../types\";\n\nexport interface LocalStorageAdapterOptions {\n  /** Key prefix for localStorage entries. Default: \"featuredrop\" */\n  prefix?: string;\n  /** Server-side watermark (ISO string). Typically from user profile. */\n  watermark?: string | null;\n  /** Callback when dismissAll is called. Use for server-side watermark updates. */\n  onDismissAll?: (now: Date) => Promise<void>;\n}\n\nconst DISMISSED_SUFFIX = \":dismissed\";\n\n/**\n * localStorage-based storage adapter.\n *\n * Architecture:\n * - **Watermark** comes from the server (passed at construction time)\n * - **Per-feature dismissals** are stored in localStorage (zero server writes)\n * - **dismissAll()** optionally calls a server callback, then clears localStorage\n *\n * Gracefully handles SSR environments where `window`/`localStorage` is unavailable.\n */\nexport class LocalStorageAdapter implements StorageAdapter {\n  private readonly prefix: string;\n  private readonly watermarkValue: string | null;\n  private readonly onDismissAllCallback?: (now: Date) => Promise<void>;\n  private readonly dismissedKey: string;\n\n  constructor(options: LocalStorageAdapterOptions = {}) {\n    this.prefix = options.prefix ?? \"featuredrop\";\n    this.watermarkValue = options.watermark ?? null;\n    this.onDismissAllCallback = options.onDismissAll;\n    this.dismissedKey = `${this.prefix}${DISMISSED_SUFFIX}`;\n  }\n\n  getWatermark(): string | null {\n    return this.watermarkValue;\n  }\n\n  getDismissedIds(): ReadonlySet<string> {\n    try {\n      if (typeof window === \"undefined\") return new Set();\n      const raw = localStorage.getItem(this.dismissedKey);\n      if (!raw) return new Set();\n      const parsed: unknown = JSON.parse(raw);\n      if (Array.isArray(parsed)) return new Set(parsed as string[]);\n      return new Set();\n    } catch {\n      return new Set();\n    }\n  }\n\n  dismiss(id: string): void {\n    try {\n      if (typeof window === \"undefined\") return;\n      const raw = localStorage.getItem(this.dismissedKey);\n      const existing: string[] = raw ? (JSON.parse(raw) as string[]) : [];\n      if (!existing.includes(id)) {\n        existing.push(id);\n        localStorage.setItem(this.dismissedKey, JSON.stringify(existing));\n      }\n    } catch {\n      // localStorage unavailable — silent fail\n    }\n  }\n\n  async dismissAll(now: Date): Promise<void> {\n    try {\n      if (typeof window !== \"undefined\") {\n        localStorage.removeItem(this.dismissedKey);\n      }\n    } catch {\n      // localStorage unavailable — silent fail\n    }\n\n    if (this.onDismissAllCallback) {\n      await this.onDismissAllCallback(now);\n    }\n  }\n}\n","import type { StorageAdapter } from \"../types\";\n\n/**\n * In-memory storage adapter.\n *\n * Useful for:\n * - Testing (no side effects)\n * - Server-side rendering (no `window`/`localStorage`)\n * - Environments without persistent storage\n */\nexport class MemoryAdapter implements StorageAdapter {\n  private watermark: string | null;\n  private dismissed: Set<string>;\n\n  constructor(options: { watermark?: string | null } = {}) {\n    this.watermark = options.watermark ?? null;\n    this.dismissed = new Set();\n  }\n\n  getWatermark(): string | null {\n    return this.watermark;\n  }\n\n  getDismissedIds(): ReadonlySet<string> {\n    return this.dismissed;\n  }\n\n  dismiss(id: string): void {\n    this.dismissed.add(id);\n  }\n\n  async dismissAll(now: Date): Promise<void> {\n    this.watermark = now.toISOString();\n    this.dismissed.clear();\n  }\n}\n"]}

package/dist/react.cjs

@@ -0,0 +1,197 @@
+"use client";
+'use strict';
+
+var react = require('react');
+var jsxRuntime = require('react/jsx-runtime');
+
+// src/react/provider.tsx
+
+// src/core.ts
+function isNew(feature, watermark, dismissedIds, now = /* @__PURE__ */ new Date()) {
+  if (dismissedIds.has(feature.id)) return false;
+  const nowMs = now.getTime();
+  const showUntilMs = new Date(feature.showNewUntil).getTime();
+  if (nowMs >= showUntilMs) return false;
+  if (watermark) {
+    const watermarkMs = new Date(watermark).getTime();
+    const releasedMs = new Date(feature.releasedAt).getTime();
+    if (releasedMs <= watermarkMs) return false;
+  }
+  return true;
+}
+function getNewFeatures(manifest, storage, now = /* @__PURE__ */ new Date()) {
+  const watermark = storage.getWatermark();
+  const dismissedIds = storage.getDismissedIds();
+  return manifest.filter((f) => isNew(f, watermark, dismissedIds, now));
+}
+function hasNewFeature(manifest, sidebarKey, storage, now = /* @__PURE__ */ new Date()) {
+  const watermark = storage.getWatermark();
+  const dismissedIds = storage.getDismissedIds();
+  return manifest.some(
+    (f) => f.sidebarKey === sidebarKey && isNew(f, watermark, dismissedIds, now)
+  );
+}
+var FeatureDropContext = react.createContext(
+  null
+);
+function FeatureDropProvider({
+  manifest,
+  storage,
+  children
+}) {
+  const [newFeatures, setNewFeatures] = react.useState(
+    () => getNewFeatures(manifest, storage)
+  );
+  const recompute = react.useCallback(() => {
+    setNewFeatures(getNewFeatures(manifest, storage));
+  }, [manifest, storage]);
+  const dismiss = react.useCallback(
+    (id) => {
+      storage.dismiss(id);
+      recompute();
+    },
+    [storage, recompute]
+  );
+  const dismissAll = react.useCallback(async () => {
+    await storage.dismissAll(/* @__PURE__ */ new Date());
+    setNewFeatures([]);
+  }, [storage]);
+  const isNewFn = react.useCallback(
+    (sidebarKey) => hasNewFeature(manifest, sidebarKey, storage),
+    [manifest, storage]
+  );
+  const getFeature = react.useCallback(
+    (sidebarKey) => newFeatures.find((f) => f.sidebarKey === sidebarKey),
+    [newFeatures]
+  );
+  const value = react.useMemo(
+    () => ({
+      newFeatures,
+      newCount: newFeatures.length,
+      isNew: isNewFn,
+      dismiss,
+      dismissAll,
+      getFeature
+    }),
+    [newFeatures, isNewFn, dismiss, dismissAll, getFeature]
+  );
+  return /* @__PURE__ */ jsxRuntime.jsx(FeatureDropContext.Provider, { value, children });
+}
+function useFeatureDrop() {
+  const context = react.useContext(FeatureDropContext);
+  if (!context) {
+    throw new Error(
+      "useFeatureDrop must be used within a <FeatureDropProvider>"
+    );
+  }
+  return context;
+}
+
+// src/react/hooks/use-new-feature.ts
+function useNewFeature(sidebarKey) {
+  const { isNew: isNew2, getFeature, dismiss } = useFeatureDrop();
+  const feature = getFeature(sidebarKey);
+  const isNewValue = isNew2(sidebarKey);
+  return {
+    isNew: isNewValue,
+    feature,
+    dismiss: () => {
+      if (feature) {
+        dismiss(feature.id);
+      }
+    }
+  };
+}
+
+// src/react/hooks/use-new-count.ts
+function useNewCount() {
+  const { newCount } = useFeatureDrop();
+  return newCount;
+}
+var baseStyles = {
+  display: "inline-flex",
+  alignItems: "center",
+  justifyContent: "center",
+  fontFamily: "inherit"
+};
+var pillStyles = {
+  ...baseStyles,
+  padding: "2px 6px",
+  borderRadius: "9999px",
+  fontSize: "var(--featuredrop-font-size, 10px)",
+  fontWeight: 700,
+  textTransform: "uppercase",
+  letterSpacing: "0.05em",
+  lineHeight: 1,
+  color: "var(--featuredrop-color, #b45309)",
+  backgroundColor: "var(--featuredrop-bg, rgba(245, 158, 11, 0.15))"
+};
+var dotStyles = {
+  ...baseStyles,
+  width: "var(--featuredrop-dot-size, 8px)",
+  height: "var(--featuredrop-dot-size, 8px)",
+  borderRadius: "9999px",
+  backgroundColor: "var(--featuredrop-color, #f59e0b)",
+  boxShadow: "0 0 6px var(--featuredrop-glow, rgba(245, 158, 11, 0.6))",
+  animation: "featuredrop-pulse 2s ease-in-out infinite"
+};
+var countStyles = {
+  ...baseStyles,
+  minWidth: "var(--featuredrop-count-size, 18px)",
+  height: "var(--featuredrop-count-size, 18px)",
+  padding: "0 4px",
+  borderRadius: "9999px",
+  fontSize: "var(--featuredrop-font-size, 11px)",
+  fontWeight: 700,
+  lineHeight: 1,
+  color: "var(--featuredrop-count-color, white)",
+  backgroundColor: "var(--featuredrop-count-bg, #f59e0b)"
+};
+function NewBadge({
+  variant = "pill",
+  show = true,
+  count,
+  label = "New",
+  onDismiss,
+  dismissOnClick = false,
+  className,
+  style,
+  children
+}) {
+  if (children) {
+    return /* @__PURE__ */ jsxRuntime.jsx(jsxRuntime.Fragment, { children: children({ isNew: show }) });
+  }
+  if (!show) return null;
+  const handleClick = dismissOnClick && onDismiss ? onDismiss : void 0;
+  const variantStyles = variant === "dot" ? dotStyles : variant === "count" ? countStyles : pillStyles;
+  const content = variant === "dot" ? null : variant === "count" ? count ?? 0 : label;
+  const ariaLabel = variant === "count" ? `${count ?? 0} new features` : "New feature";
+  return /* @__PURE__ */ jsxRuntime.jsx(
+    "span",
+    {
+      "data-featuredrop": variant,
+      className,
+      style: { ...variantStyles, ...style },
+      onClick: handleClick,
+      role: dismissOnClick ? "button" : void 0,
+      tabIndex: dismissOnClick ? 0 : void 0,
+      onKeyDown: dismissOnClick && onDismiss ? (e) => {
+        if (e.key === "Enter" || e.key === " ") {
+          e.preventDefault();
+          onDismiss();
+        }
+      } : void 0,
+      "aria-label": ariaLabel,
+      children: content
+    }
+  );
+}
+
+exports.FeatureDropContext = FeatureDropContext;
+exports.FeatureDropProvider = FeatureDropProvider;
+exports.NewBadge = NewBadge;
+exports.useFeatureDrop = useFeatureDrop;
+exports.useNewCount = useNewCount;
+exports.useNewFeature = useNewFeature;
+//# sourceMappingURL=react.cjs.map
+//# sourceMappingURL=react.cjs.map

package/dist/react.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core.ts","../src/react/context.ts","../src/react/provider.tsx","../src/react/hooks/use-feature-drop.ts","../src/react/hooks/use-new-feature.ts","../src/react/hooks/use-new-count.ts","../src/react/components/new-badge.tsx"],"names":["createContext","useState","useCallback","useMemo","jsx","useContext","isNew","Fragment"],"mappings":";;;;;;;;AAUO,SAAS,MACd,OAAA,EACA,SAAA,EACA,cACA,GAAA,mBAAY,IAAI,MAAK,EACZ;AAET,EAAA,IAAI,YAAA,CAAa,GAAA,CAAI,OAAA,CAAQ,EAAE,GAAG,OAAO,KAAA;AAEzC,EAAA,MAAM,KAAA,GAAQ,IAAI,OAAA,EAAQ;AAC1B,EAAA,MAAM,cAAc,IAAI,IAAA,CAAK,OAAA,CAAQ,YAAY,EAAE,OAAA,EAAQ;AAG3D,EAAA,IAAI,KAAA,IAAS,aAAa,OAAO,KAAA;AAGjC,EAAA,IAAI,SAAA,EAAW;AACb,IAAA,MAAM,WAAA,GAAc,IAAI,IAAA,CAAK,SAAS,EAAE,OAAA,EAAQ;AAChD,IAAA,MAAM,aAAa,IAAI,IAAA,CAAK,OAAA,CAAQ,UAAU,EAAE,OAAA,EAAQ;AACxD,IAAA,IAAI,UAAA,IAAc,aAAa,OAAO,KAAA;AAAA,EACxC;AAEA,EAAA,OAAO,IAAA;AACT;AAKO,SAAS,eACd,QAAA,EACA,OAAA,EACA,GAAA,mBAAY,IAAI,MAAK,EACL;AAChB,EAAA,MAAM,SAAA,GAAY,QAAQ,YAAA,EAAa;AACvC,EAAA,MAAM,YAAA,GAAe,QAAQ,eAAA,EAAgB;AAC7C,EAAA,OAAO,QAAA,CAAS,OAAO,CAAC,CAAA,KAAM,MAAM,CAAA,EAAG,SAAA,EAAW,YAAA,EAAc,GAAG,CAAC,CAAA;AACtE;AAgBO,SAAS,cACd,QAAA,EACA,UAAA,EACA,SACA,GAAA,mBAAY,IAAI,MAAK,EACZ;AACT,EAAA,MAAM,SAAA,GAAY,QAAQ,YAAA,EAAa;AACvC,EAAA,MAAM,YAAA,GAAe,QAAQ,eAAA,EAAgB;AAC7C,EAAA,OAAO,QAAA,CAAS,IAAA;AAAA,IACd,CAAC,MAAM,CAAA,CAAE,UAAA,KAAe,cAAc,KAAA,CAAM,CAAA,EAAG,SAAA,EAAW,YAAA,EAAc,GAAG;AAAA,GAC7E;AACF;ACvDO,IAAM,kBAAA,GAAqBA,mBAAA;AAAA,EAChC;AACF;ACDO,SAAS,mBAAA,CAAoB;AAAA,EAClC,QAAA;AAAA,EACA,OAAA;AAAA,EACA;AACF,CAAA,EAA6B;AAC3B,EAAA,MAAM,CAAC,WAAA,EAAa,cAAc,CAAA,GAAIC,cAAA;AAAA,IAAS,MAC7C,cAAA,CAAe,QAAA,EAAU,OAAO;AAAA,GAClC;AAEA,EAAA,MAAM,SAAA,GAAYC,kBAAY,MAAM;AAClC,IAAA,cAAA,CAAe,cAAA,CAAe,QAAA,EAAU,OAAO,CAAC,CAAA;AAAA,EAClD,CAAA,EAAG,CAAC,QAAA,EAAU,OAAO,CAAC,CAAA;AAEtB,EAAA,MAAM,OAAA,GAAUA,iBAAA;AAAA,IACd,CAAC,EAAA,KAAe;AACd,MAAA,OAAA,CAAQ,QAAQ,EAAE,CAAA;AAClB,MAAA,SAAA,EAAU;AAAA,IACZ,CAAA;AAAA,IACA,CAAC,SAAS,SAAS;AAAA,GACrB;AAEA,EAAA,MAAM,UAAA,GAAaA,kBAAY,YAAY;AACzC,IAAA,MAAM,OAAA,CAAQ,UAAA,iBAAW,IAAI,IAAA,EAAM,CAAA;AACnC,IAAA,cAAA,CAAe,EAAE,CAAA;AAAA,EACnB,CAAA,EAAG,CAAC,OAAO,CAAC,CAAA;AAEZ,EAAA,MAAM,OAAA,GAAUA,iBAAA;AAAA,IACd,CAAC,UAAA,KAAuB,aAAA,CAAc,QAAA,EAAU,YAAY,OAAO,CAAA;AAAA,IACnE,CAAC,UAAU,OAAO;AAAA,GACpB;AAEA,EAAA,MAAM,UAAA,GAAaA,iBAAA;AAAA,IACjB,CAAC,eACC,WAAA,CAAY,IAAA,CAAK,CAAC,CAAA,KAAM,CAAA,CAAE,eAAe,UAAU,CAAA;AAAA,IACrD,CAAC,WAAW;AAAA,GACd;AAEA,EAAA,MAAM,KAAA,GAAQC,aAAA;AAAA,IACZ,OAAO;AAAA,MACL,WAAA;AAAA,MACA,UAAU,WAAA,CAAY,MAAA;AAAA,MACtB,KAAA,EAAO,OAAA;AAAA,MACP,OAAA;AAAA,MACA,UAAA;AAAA,MACA;AAAA,KACF,CAAA;AAAA,IACA,CAAC,WAAA,EAAa,OAAA,EAAS,OAAA,EAAS,YAAY,UAAU;AAAA,GACxD;AAEA,EAAA,uBACEC,cAAA,CAAC,kBAAA,CAAmB,QAAA,EAAnB,EAA4B,OAC1B,QAAA,EACH,CAAA;AAEJ;AC9DO,SAAS,cAAA,GAA0C;AACxD,EAAA,MAAM,OAAA,GAAUC,iBAAW,kBAAkB,CAAA;AAC7C,EAAA,IAAI,CAAC,OAAA,EAAS;AACZ,IAAA,MAAM,IAAI,KAAA;AAAA,MACR;AAAA,KACF;AAAA,EACF;AACA,EAAA,OAAO,OAAA;AACT;;;ACDO,SAAS,cAAc,UAAA,EAAyC;AACrE,EAAA,MAAM,EAAE,KAAA,EAAAC,MAAAA,EAAO,UAAA,EAAY,OAAA,KAAY,cAAA,EAAe;AAEtD,EAAA,MAAM,OAAA,GAAU,WAAW,UAAU,CAAA;AACrC,EAAA,MAAM,UAAA,GAAaA,OAAM,UAAU,CAAA;AAEnC,EAAA,OAAO;AAAA,IACL,KAAA,EAAO,UAAA;AAAA,IACP,OAAA;AAAA,IACA,SAAS,MAAM;AACb,MAAA,IAAI,OAAA,EAAS;AACX,QAAA,OAAA,CAAQ,QAAQ,EAAE,CAAA;AAAA,MACpB;AAAA,IACF;AAAA,GACF;AACF;;;ACxBO,SAAS,WAAA,GAAsB;AACpC,EAAA,MAAM,EAAE,QAAA,EAAS,GAAI,cAAA,EAAe;AACpC,EAAA,OAAO,QAAA;AACT;ACgBA,IAAM,UAAA,GAA4B;AAAA,EAChC,OAAA,EAAS,aAAA;AAAA,EACT,UAAA,EAAY,QAAA;AAAA,EACZ,cAAA,EAAgB,QAAA;AAAA,EAChB,UAAA,EAAY;AACd,CAAA;AAEA,IAAM,UAAA,GAA4B;AAAA,EAChC,GAAG,UAAA;AAAA,EACH,OAAA,EAAS,SAAA;AAAA,EACT,YAAA,EAAc,QAAA;AAAA,EACd,QAAA,EAAU,oCAAA;AAAA,EACV,UAAA,EAAY,GAAA;AAAA,EACZ,aAAA,EAAe,WAAA;AAAA,EACf,aAAA,EAAe,QAAA;AAAA,EACf,UAAA,EAAY,CAAA;AAAA,EACZ,KAAA,EAAO,mCAAA;AAAA,EACP,eAAA,EAAiB;AACnB,CAAA;AAEA,IAAM,SAAA,GAA2B;AAAA,EAC/B,GAAG,UAAA;AAAA,EACH,KAAA,EAAO,kCAAA;AAAA,EACP,MAAA,EAAQ,kCAAA;AAAA,EACR,YAAA,EAAc,QAAA;AAAA,EACd,eAAA,EAAiB,mCAAA;AAAA,EACjB,SAAA,EAAW,0DAAA;AAAA,EACX,SAAA,EAAW;AACb,CAAA;AAEA,IAAM,WAAA,GAA6B;AAAA,EACjC,GAAG,UAAA;AAAA,EACH,QAAA,EAAU,qCAAA;AAAA,EACV,MAAA,EAAQ,qCAAA;AAAA,EACR,OAAA,EAAS,OAAA;AAAA,EACT,YAAA,EAAc,QAAA;AAAA,EACd,QAAA,EAAU,oCAAA;AAAA,EACV,UAAA,EAAY,GAAA;AAAA,EACZ,UAAA,EAAY,CAAA;AAAA,EACZ,KAAA,EAAO,uCAAA;AAAA,EACP,eAAA,EAAiB;AACnB,CAAA;AAiBO,SAAS,QAAA,CAAS;AAAA,EACvB,OAAA,GAAU,MAAA;AAAA,EACV,IAAA,GAAO,IAAA;AAAA,EACP,KAAA;AAAA,EACA,KAAA,GAAQ,KAAA;AAAA,EACR,SAAA;AAAA,EACA,cAAA,GAAiB,KAAA;AAAA,EACjB,SAAA;AAAA,EACA,KAAA;AAAA,EACA;AACF,CAAA,EAAkB;AAEhB,EAAA,IAAI,QAAA,EAAU;AACZ,IAAA,uBAAOF,eAAAG,mBAAA,EAAA,EAAG,QAAA,EAAA,QAAA,CAAS,EAAE,KAAA,EAAO,IAAA,EAAM,CAAA,EAAE,CAAA;AAAA,EACtC;AAEA,EAAA,IAAI,CAAC,MAAM,OAAO,IAAA;AAElB,EAAA,MAAM,WAAA,GAAc,cAAA,IAAkB,SAAA,GAAY,SAAA,GAAY,MAAA;AAE9D,EAAA,MAAM,gBACJ,OAAA,KAAY,KAAA,GACR,SAAA,GACA,OAAA,KAAY,UACV,WAAA,GACA,UAAA;AAER,EAAA,MAAM,UACJ,OAAA,KAAY,KAAA,GACR,OACA,OAAA,KAAY,OAAA,GACT,SAAS,CAAA,GACV,KAAA;AAER,EAAA,MAAM,YACJ,OAAA,KAAY,OAAA,GACR,CAAA,EAAG,KAAA,IAAS,CAAC,CAAA,aAAA,CAAA,GACb,aAAA;AAEN,EAAA,uBACEH,cAAAA;AAAA,IAAC,MAAA;AAAA,IAAA;AAAA,MACC,kBAAA,EAAkB,OAAA;AAAA,MAClB,SAAA;AAAA,MACA,KAAA,EAAO,EAAE,GAAG,aAAA,EAAe,GAAG,KAAA,EAAM;AAAA,MACpC,OAAA,EAAS,WAAA;AAAA,MACT,IAAA,EAAM,iBAAiB,QAAA,GAAW,MAAA;AAAA,MAClC,QAAA,EAAU,iBAAiB,CAAA,GAAI,MAAA;AAAA,MAC/B,SAAA,EACE,cAAA,IAAkB,SAAA,GACd,CAAC,CAAA,KAAM;AACL,QAAA,IAAI,CAAA,CAAE,GAAA,KAAQ,OAAA,IAAW,CAAA,CAAE,QAAQ,GAAA,EAAK;AACtC,UAAA,CAAA,CAAE,cAAA,EAAe;AACjB,UAAA,SAAA,EAAU;AAAA,QACZ;AAAA,MACF,CAAA,GACA,MAAA;AAAA,MAEN,YAAA,EAAY,SAAA;AAAA,MAEX,QAAA,EAAA;AAAA;AAAA,GACH;AAEJ","file":"react.cjs","sourcesContent":["import type { FeatureEntry, FeatureManifest, StorageAdapter } from \"./types\";\n\n/**\n * Check if a single feature should show as \"new\".\n *\n * A feature is \"new\" when ALL of these are true:\n * 1. Current time is before `showNewUntil`\n * 2. Feature was released after the watermark (or no watermark exists)\n * 3. Feature has not been individually dismissed\n */\nexport function isNew(\n  feature: FeatureEntry,\n  watermark: string | null,\n  dismissedIds: ReadonlySet<string>,\n  now: Date = new Date(),\n): boolean {\n  // Already dismissed by the user on this device\n  if (dismissedIds.has(feature.id)) return false;\n\n  const nowMs = now.getTime();\n  const showUntilMs = new Date(feature.showNewUntil).getTime();\n\n  // Past the display window\n  if (nowMs >= showUntilMs) return false;\n\n  // If there's a watermark, feature must have been released after it\n  if (watermark) {\n    const watermarkMs = new Date(watermark).getTime();\n    const releasedMs = new Date(feature.releasedAt).getTime();\n    if (releasedMs <= watermarkMs) return false;\n  }\n\n  return true;\n}\n\n/**\n * Get all features that are currently \"new\" for this user.\n */\nexport function getNewFeatures(\n  manifest: FeatureManifest,\n  storage: StorageAdapter,\n  now: Date = new Date(),\n): FeatureEntry[] {\n  const watermark = storage.getWatermark();\n  const dismissedIds = storage.getDismissedIds();\n  return manifest.filter((f) => isNew(f, watermark, dismissedIds, now));\n}\n\n/**\n * Get the count of new features.\n */\nexport function getNewFeatureCount(\n  manifest: FeatureManifest,\n  storage: StorageAdapter,\n  now: Date = new Date(),\n): number {\n  return getNewFeatures(manifest, storage, now).length;\n}\n\n/**\n * Check if a specific sidebar key has a new feature.\n */\nexport function hasNewFeature(\n  manifest: FeatureManifest,\n  sidebarKey: string,\n  storage: StorageAdapter,\n  now: Date = new Date(),\n): boolean {\n  const watermark = storage.getWatermark();\n  const dismissedIds = storage.getDismissedIds();\n  return manifest.some(\n    (f) => f.sidebarKey === sidebarKey && isNew(f, watermark, dismissedIds, now),\n  );\n}\n","import { createContext } from \"react\";\nimport type { FeatureEntry } from \"../types\";\n\nexport interface FeatureDropContextValue {\n  /** All currently \"new\" features */\n  newFeatures: FeatureEntry[];\n  /** Count of new features */\n  newCount: number;\n  /** Check if a sidebar key has any new features */\n  isNew: (sidebarKey: string) => boolean;\n  /** Dismiss a single feature by ID */\n  dismiss: (id: string) => void;\n  /** Dismiss all features (marks all as seen) */\n  dismissAll: () => Promise<void>;\n  /** Get the feature entry for a sidebar key (if it's new) */\n  getFeature: (sidebarKey: string) => FeatureEntry | undefined;\n}\n\nexport const FeatureDropContext = createContext<FeatureDropContextValue | null>(\n  null,\n);\n","import { useState, useCallback, useMemo, type ReactNode } from \"react\";\nimport type { FeatureManifest, StorageAdapter } from \"../types\";\nimport { getNewFeatures, hasNewFeature } from \"../core\";\nimport { FeatureDropContext } from \"./context\";\n\nexport interface FeatureDropProviderProps {\n  /** The feature manifest — typically a frozen array of FeatureEntry objects */\n  manifest: FeatureManifest;\n  /** Storage adapter instance (e.g. LocalStorageAdapter, MemoryAdapter) */\n  storage: StorageAdapter;\n  children: ReactNode;\n}\n\n/**\n * Provides feature discovery state to the component tree.\n *\n * Wrap your app (or a subtree) with this provider to enable\n * `useFeatureDrop`, `useNewFeature`, and `useNewCount` hooks.\n */\nexport function FeatureDropProvider({\n  manifest,\n  storage,\n  children,\n}: FeatureDropProviderProps) {\n  const [newFeatures, setNewFeatures] = useState(() =>\n    getNewFeatures(manifest, storage),\n  );\n\n  const recompute = useCallback(() => {\n    setNewFeatures(getNewFeatures(manifest, storage));\n  }, [manifest, storage]);\n\n  const dismiss = useCallback(\n    (id: string) => {\n      storage.dismiss(id);\n      recompute();\n    },\n    [storage, recompute],\n  );\n\n  const dismissAll = useCallback(async () => {\n    await storage.dismissAll(new Date());\n    setNewFeatures([]);\n  }, [storage]);\n\n  const isNewFn = useCallback(\n    (sidebarKey: string) => hasNewFeature(manifest, sidebarKey, storage),\n    [manifest, storage],\n  );\n\n  const getFeature = useCallback(\n    (sidebarKey: string) =>\n      newFeatures.find((f) => f.sidebarKey === sidebarKey),\n    [newFeatures],\n  );\n\n  const value = useMemo(\n    () => ({\n      newFeatures,\n      newCount: newFeatures.length,\n      isNew: isNewFn,\n      dismiss,\n      dismissAll,\n      getFeature,\n    }),\n    [newFeatures, isNewFn, dismiss, dismissAll, getFeature],\n  );\n\n  return (\n    <FeatureDropContext.Provider value={value}>\n      {children}\n    </FeatureDropContext.Provider>\n  );\n}\n","import { useContext } from \"react\";\nimport { FeatureDropContext } from \"../context\";\nimport type { FeatureDropContextValue } from \"../context\";\n\n/**\n * Access the full feature discovery context.\n *\n * Returns: `{ newFeatures, newCount, isNew, dismiss, dismissAll, getFeature }`\n *\n * @throws Error if used outside of `<FeatureDropProvider>`\n */\nexport function useFeatureDrop(): FeatureDropContextValue {\n  const context = useContext(FeatureDropContext);\n  if (!context) {\n    throw new Error(\n      \"useFeatureDrop must be used within a <FeatureDropProvider>\",\n    );\n  }\n  return context;\n}\n","import { useFeatureDrop } from \"./use-feature-drop\";\nimport type { FeatureEntry } from \"../../types\";\n\nexport interface UseNewFeatureResult {\n  /** Whether this sidebar key has a new feature */\n  isNew: boolean;\n  /** The feature entry, if new */\n  feature: FeatureEntry | undefined;\n  /** Dismiss the feature for this sidebar key */\n  dismiss: () => void;\n}\n\n/**\n * Check if a single navigation item has a new feature.\n *\n * @param sidebarKey - The key to check (e.g. \"/journal\", \"settings\")\n * @returns `{ isNew, feature, dismiss }`\n */\nexport function useNewFeature(sidebarKey: string): UseNewFeatureResult {\n  const { isNew, getFeature, dismiss } = useFeatureDrop();\n\n  const feature = getFeature(sidebarKey);\n  const isNewValue = isNew(sidebarKey);\n\n  return {\n    isNew: isNewValue,\n    feature,\n    dismiss: () => {\n      if (feature) {\n        dismiss(feature.id);\n      }\n    },\n  };\n}\n","import { useFeatureDrop } from \"./use-feature-drop\";\n\n/**\n * Get the count of currently new features.\n *\n * Useful for rendering a badge count on a \"What's New\" button.\n *\n * @returns The number of new features\n */\nexport function useNewCount(): number {\n  const { newCount } = useFeatureDrop();\n  return newCount;\n}\n","import type { ReactNode, CSSProperties } from \"react\";\n\nexport interface NewBadgeRenderProps {\n  /** Whether the feature is currently new */\n  isNew: boolean;\n}\n\nexport interface NewBadgeProps {\n  /** Display variant */\n  variant?: \"pill\" | \"dot\" | \"count\";\n  /** Whether to show the badge (typically from `useNewFeature().isNew`) */\n  show?: boolean;\n  /** Count to display when variant is \"count\" */\n  count?: number;\n  /** Text label for the pill variant. Default: \"New\" */\n  label?: string;\n  /** Dismiss callback. If set with `dismissOnClick`, clicking dismisses. */\n  onDismiss?: () => void;\n  /** Whether clicking the badge should trigger onDismiss */\n  dismissOnClick?: boolean;\n  /** Additional CSS class */\n  className?: string;\n  /** Additional inline styles (merged with defaults) */\n  style?: CSSProperties;\n  /** Render prop for full customization */\n  children?: (props: NewBadgeRenderProps) => ReactNode;\n}\n\nconst baseStyles: CSSProperties = {\n  display: \"inline-flex\",\n  alignItems: \"center\",\n  justifyContent: \"center\",\n  fontFamily: \"inherit\",\n};\n\nconst pillStyles: CSSProperties = {\n  ...baseStyles,\n  padding: \"2px 6px\",\n  borderRadius: \"9999px\",\n  fontSize: \"var(--featuredrop-font-size, 10px)\",\n  fontWeight: 700,\n  textTransform: \"uppercase\" as const,\n  letterSpacing: \"0.05em\",\n  lineHeight: 1,\n  color: \"var(--featuredrop-color, #b45309)\",\n  backgroundColor: \"var(--featuredrop-bg, rgba(245, 158, 11, 0.15))\",\n};\n\nconst dotStyles: CSSProperties = {\n  ...baseStyles,\n  width: \"var(--featuredrop-dot-size, 8px)\",\n  height: \"var(--featuredrop-dot-size, 8px)\",\n  borderRadius: \"9999px\",\n  backgroundColor: \"var(--featuredrop-color, #f59e0b)\",\n  boxShadow: \"0 0 6px var(--featuredrop-glow, rgba(245, 158, 11, 0.6))\",\n  animation: \"featuredrop-pulse 2s ease-in-out infinite\",\n};\n\nconst countStyles: CSSProperties = {\n  ...baseStyles,\n  minWidth: \"var(--featuredrop-count-size, 18px)\",\n  height: \"var(--featuredrop-count-size, 18px)\",\n  padding: \"0 4px\",\n  borderRadius: \"9999px\",\n  fontSize: \"var(--featuredrop-font-size, 11px)\",\n  fontWeight: 700,\n  lineHeight: 1,\n  color: \"var(--featuredrop-count-color, white)\",\n  backgroundColor: \"var(--featuredrop-count-bg, #f59e0b)\",\n};\n\n/**\n * Headless \"New\" badge component.\n *\n * Styled via CSS custom properties — zero CSS framework dependency:\n * - `--featuredrop-color` — text/dot color\n * - `--featuredrop-bg` — pill background\n * - `--featuredrop-font-size` — font size\n * - `--featuredrop-dot-size` — dot diameter\n * - `--featuredrop-glow` — dot glow color\n * - `--featuredrop-count-size` — count badge size\n * - `--featuredrop-count-color` — count text color\n * - `--featuredrop-count-bg` — count background\n *\n * Use `data-featuredrop` attribute for CSS selector styling.\n */\nexport function NewBadge({\n  variant = \"pill\",\n  show = true,\n  count,\n  label = \"New\",\n  onDismiss,\n  dismissOnClick = false,\n  className,\n  style,\n  children,\n}: NewBadgeProps) {\n  // Render prop mode\n  if (children) {\n    return <>{children({ isNew: show })}</>;\n  }\n\n  if (!show) return null;\n\n  const handleClick = dismissOnClick && onDismiss ? onDismiss : undefined;\n\n  const variantStyles =\n    variant === \"dot\"\n      ? dotStyles\n      : variant === \"count\"\n        ? countStyles\n        : pillStyles;\n\n  const content =\n    variant === \"dot\"\n      ? null\n      : variant === \"count\"\n        ? (count ?? 0)\n        : label;\n\n  const ariaLabel =\n    variant === \"count\"\n      ? `${count ?? 0} new features`\n      : \"New feature\";\n\n  return (\n    <span\n      data-featuredrop={variant}\n      className={className}\n      style={{ ...variantStyles, ...style }}\n      onClick={handleClick}\n      role={dismissOnClick ? \"button\" : undefined}\n      tabIndex={dismissOnClick ? 0 : undefined}\n      onKeyDown={\n        dismissOnClick && onDismiss\n          ? (e) => {\n              if (e.key === \"Enter\" || e.key === \" \") {\n                e.preventDefault();\n                onDismiss();\n              }\n            }\n          : undefined\n      }\n      aria-label={ariaLabel}\n    >\n      {content}\n    </span>\n  );\n}\n"]}

package/dist/react.d.cts

@@ -0,0 +1,154 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react from 'react';
+import { ReactNode, CSSProperties } from 'react';
+
+/** 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 */
+    description?: 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 URL to link to (e.g. docs page, changelog entry) */
+    url?: string;
+    /** Optional version string when this feature shipped */
+    version?: string;
+    /** Optional arbitrary metadata */
+    meta?: Record<string, unknown>;
+}
+/** 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>;
+}
+
+interface FeatureDropProviderProps {
+    /** The feature manifest — typically a frozen array of FeatureEntry objects */
+    manifest: FeatureManifest;
+    /** Storage adapter instance (e.g. LocalStorageAdapter, MemoryAdapter) */
+    storage: StorageAdapter;
+    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.
+ */
+declare function FeatureDropProvider({ manifest, storage, children, }: FeatureDropProviderProps): react_jsx_runtime.JSX.Element;
+
+interface FeatureDropContextValue {
+    /** All currently "new" features */
+    newFeatures: FeatureEntry[];
+    /** Count of new features */
+    newCount: number;
+    /** 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;
+}
+declare const FeatureDropContext: react.Context<FeatureDropContextValue | 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 NewBadgeRenderProps {
+    /** Whether the feature is currently new */
+    isNew: boolean;
+}
+interface NewBadgeProps {
+    /** Display variant */
+    variant?: "pill" | "dot" | "count";
+    /** Whether to show the badge (typically from `useNewFeature().isNew`) */
+    show?: boolean;
+    /** Count to display when variant is "count" */
+    count?: number;
+    /** Text label for the pill variant. Default: "New" */
+    label?: string;
+    /** Dismiss callback. If set with `dismissOnClick`, clicking dismisses. */
+    onDismiss?: () => void;
+    /** Whether clicking the badge should trigger onDismiss */
+    dismissOnClick?: boolean;
+    /** Additional CSS class */
+    className?: string;
+    /** Additional inline styles (merged with defaults) */
+    style?: CSSProperties;
+    /** 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;
+
+export { FeatureDropContext, type FeatureDropContextValue, FeatureDropProvider, type FeatureDropProviderProps, NewBadge, type NewBadgeProps, type NewBadgeRenderProps, type UseNewFeatureResult, useFeatureDrop, useNewCount, useNewFeature };