featuredrop 2.6.1 → 2.7.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "featuredrop",
-  "version": "2.6.1",
+  "version": "2.7.1",
   "description": "Lightweight feature discovery system. Show 'New' badges that auto-expire.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -195,6 +195,26 @@
         "types": "./dist/testing.d.cts",
         "default": "./dist/testing.cjs"
       }
+    },
+    "./react/hooks": {
+      "import": {
+        "types": "./dist/react-hooks.d.ts",
+        "default": "./dist/react-hooks.js"
+      },
+      "require": {
+        "types": "./dist/react-hooks.d.cts",
+        "default": "./dist/react-hooks.cjs"
+      }
+    },
+    "./tailwind": {
+      "import": {
+        "types": "./dist/tailwind.d.ts",
+        "default": "./dist/tailwind.js"
+      },
+      "require": {
+        "types": "./dist/tailwind.d.cts",
+        "default": "./dist/tailwind.cjs"
+      }
     }
   },
   "typesVersions": {
@@ -246,6 +266,12 @@
       ],
       "flags": [
         "./dist/flags.d.ts"
+      ],
+      "react/hooks": [
+        "./dist/react-hooks.d.ts"
+      ],
+      "tailwind": [
+        "./dist/tailwind.d.ts"
       ]
     }
   },
@@ -255,6 +281,11 @@
     "dist/**/*.d.ts",
     "dist/**/*.d.cts",
     "dist/**/*.map",
+    ".claude-plugin/**",
+    "skills/**",
+    "context7.json",
+    "src/ai/cursorrules.txt",
+    "src/ai/claude-skill.md",
     "README.md",
     "LICENSE"
   ],

package/skills/featuredrop-setup/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: featuredrop-setup
+description: >
+  Configure FeatureDrop product adoption toolkit in any project. Use when adding
+  changelogs, feature badges, onboarding tours, checklists, hotspots, feedback
+  widgets, or surveys to an application.
+---
+
+# FeatureDrop — Product Adoption Toolkit
+
+Open-source, zero-dependency library for in-app feature discovery. < 3 kB core.
+
+## Setup Pattern
+
+1. `npm install featuredrop`
+2. Create a JSON manifest: `[{ id, label, description, releasedAt, showNewUntil? }]`
+3. Wrap root: `<FeatureDropProvider manifest={features} storage={new LocalStorageAdapter()}>`
+4. Add components or use headless hooks.
+
+## Imports (ALWAYS use subpath imports)
+
+```ts
+// Core (no React, no UI)
+import { isNew, getNewFeatures, createManifest, LocalStorageAdapter } from 'featuredrop'
+
+// React components (ready-made UI)
+import { NewBadge, ChangelogWidget, Tour, Checklist, Banner, Toast } from 'featuredrop/react'
+
+// Headless hooks (data + actions, no JSX — for custom design systems / shadcn)
+import { useChangelog, useNewFeature, useNewCount, useTour, useChecklist } from 'featuredrop/react/hooks'
+
+// Storage adapters
+import { PostgresAdapter, RedisAdapter, IndexedDBAdapter, HybridAdapter } from 'featuredrop/adapters'
+
+// Validation
+import { validateManifest } from 'featuredrop/schema'
+
+// Testing helpers
+import { createMockManifest, createMockStorage, TestProvider } from 'featuredrop/testing'
+
+// Tailwind plugin
+import { featureDropPlugin } from 'featuredrop/tailwind'
+```
+
+## Hooks (prefer these for custom UI / shadcn projects)
+
+| Hook | Returns |
+|------|---------|
+| `useNewFeature(id)` | `{ isNew, feature, dismiss }` |
+| `useNewCount()` | `number` — unread badge count |
+| `useChangelog()` | `{ features, newFeatures, newCount, dismiss, dismissAll, markAllSeen, getByCategory }` |
+| `useTour(id)` | `{ currentStep, stepIndex, totalSteps, isActive, start, next, prev, skip, complete, goTo }` |
+| `useChecklist(id)` | `{ tasks, completedCount, totalCount, progress, isComplete, completeTask, resetTask }` |
+| `useSurvey(id)` | `{ isVisible, questions, submit, askLater, dismiss }` |
+| `useFeatureDrop()` | Full provider context (features, count, dismiss, throttle controls, engine) |
+| `useTabNotification()` | Browser tab title: `"(3) My App"` |
+
+## Components (ready-made UI)
+
+NewBadge, ChangelogWidget, ChangelogPage, Tour, Checklist, Spotlight, SpotlightChain,
+Hotspot, TooltipGroup, Banner, Toast, AnnouncementModal, Survey, FeedbackWidget,
+FeatureRequestButton, FeatureRequestForm
+
+## Feature Manifest Format
+
+```ts
+{
+  id: string              // unique identifier
+  label: string           // display title
+  description: string     // what changed
+  releasedAt: string      // ISO date
+  showNewUntil?: string   // ISO date — auto-expire badge
+  category?: string       // group: "ui", "api", "billing"
+  type?: string           // "feature" | "improvement" | "fix" | "deprecation"
+  priority?: string       // "low" | "medium" | "high" | "critical"
+  cta?: { label: string; url: string }
+  audience?: Record<string, string[]>  // user segmentation
+}
+```
+
+## Storage Adapters
+
+Default: `LocalStorageAdapter` (browser). Server: `PostgresAdapter`, `RedisAdapter`.
+Offline: `IndexedDBAdapter`. Hybrid: `HybridAdapter` (local + remote sync).
+Custom: implement `{ getWatermark, setWatermark, getDismissedIds, addDismissedId }`.
+
+## Provider Props
+
+```tsx
+<FeatureDropProvider
+  manifest={features}             // required
+  storage={adapter}               // required
+  analytics={{ onFeatureSeen, onFeatureDismissed, onFeatureClicked }}
+  userContext={{ plan, role, region }}  // for audience targeting
+  appVersion="2.1.0"             // semver gating
+  throttle={{ maxToastsPerSession: 3, modalCooldownMs: 120_000 }}
+  locale="en"                    // i18n (en/es/fr/de/pt/zh-cn/ja/ko/ar/hi)
+  animation="normal"             // "none" | "subtle" | "normal" | "playful"
+  engine={engineInstance}         // optional: FeatureDropEngine for smart delivery
+/>
+```
+
+## Tailwind Integration
+
+```ts
+// tailwind.config.ts
+import { featureDropPlugin } from 'featuredrop/tailwind'
+
+export default {
+  plugins: [featureDropPlugin({ prefix: 'fd' })],
+}
+// Adds: fd-badge, fd-badge-dot, fd-badge-count, fd-animate-pulse, fd-animate-fade-in
+// CSS vars: --fd-new, --fd-changelog-bg, --fd-tour-bg (auto dark mode)
+```
+
+## Rules
+
+- Always use subpath imports (`featuredrop/react`, not just `featuredrop`)
+- Prefer hooks from `featuredrop/react/hooks` when the project uses shadcn, Radix, or custom design system
+- Features auto-expire via `showNewUntil` — don't build manual expiry logic
+- Zero production dependencies — don't add external deps
+- TypeScript strict mode — no `any` types
+- All components support headless mode via render props
+- Core < 3 kB, React ~12 kB, fully tree-shakeable

package/src/ai/claude-skill.md

@@ -0,0 +1,109 @@
+# FeatureDrop — Setup & Configuration Skill
+
+## What it is
+Open-source product adoption toolkit. Changelogs, badges, tours, checklists, feedback.
+Zero dependencies. < 3 kB core. MIT licensed.
+
+## Quick Setup
+1. `npm install featuredrop`
+2. Create features.json manifest
+3. Wrap root in `<FeatureDropProvider manifest={features} storage={new LocalStorageAdapter()}>`
+4. Drop components or use hooks
+
+## Imports (ALWAYS use subpath imports)
+```
+featuredrop                — core functions (isNew, getNewFeatures, createManifest)
+featuredrop/react          — components + hooks (NewBadge, ChangelogWidget, Tour, Checklist)
+featuredrop/react/hooks    — headless hooks only (useChangelog, useTour, useChecklist, useNewFeature)
+featuredrop/adapters       — storage (PostgresAdapter, RedisAdapter, IndexedDBAdapter, etc.)
+featuredrop/schema         — Zod validation (featureEntrySchema, validateManifest)
+featuredrop/testing        — test helpers (createMockManifest, createMockStorage, createTestProvider)
+featuredrop/tailwind       — Tailwind plugin (featureDropPlugin)
+```
+
+## Hooks Reference (prefer these for custom UI)
+```
+useNewFeature(sidebarKey)  → { isNew, feature, dismiss }
+useNewCount()              → number
+useChangelog()             → { features, newFeatures, newCount, dismiss, dismissAll, markAllSeen, getByCategory }
+useTour(id)                → { currentStep, stepIndex, totalSteps, isActive, start, next, prev, skip, complete }
+useChecklist(id)           → { tasks, progress, isComplete, completeTask, resetChecklist }
+useSurvey(id)              → { isOpen, show, hide, askLater, submitted, canShow }
+useFeatureDrop()           → full provider context (low-level)
+```
+
+## Components (ready-made UI with headless render prop mode)
+NewBadge, ChangelogWidget, ChangelogPage, Tour, Checklist, Spotlight, SpotlightChain,
+Hotspot, TooltipGroup, Banner, Toast, AnnouncementModal, Survey, FeedbackWidget,
+FeatureRequestButton, FeatureRequestForm
+
+## Manifest Format
+```json
+{
+  "id": "dark-mode",
+  "label": "Dark Mode",
+  "description": "Toggle between light and dark themes.",
+  "releasedAt": "2026-02-20",
+  "showNewUntil": "2026-04-20",
+  "category": "ui",
+  "priority": "normal",
+  "type": "feature"
+}
+```
+
+## Storage Adapters
+- LocalStorageAdapter (browser default, zero-config)
+- MemoryAdapter (testing, SSR)
+- IndexedDBAdapter (offline-first PWAs)
+- PostgresAdapter, RedisAdapter, MySQLAdapter, MongoAdapter, SQLiteAdapter (server)
+- SupabaseAdapter (Supabase with optional realtime)
+- RemoteAdapter (HTTP API with retry + circuit breaker)
+- HybridAdapter (local + remote with batched sync)
+
+## Provider Props
+```tsx
+<FeatureDropProvider
+  manifest={features}           // required: FeatureEntry[]
+  storage={adapter}             // required: StorageAdapter
+  userContext={{ plan, role }}   // optional: audience targeting
+  analytics={{ onFeatureSeen }} // optional: event callbacks
+  locale="en"                   // optional: i18n
+  animation="normal"            // optional: "none" | "subtle" | "normal" | "playful"
+  throttle={{ sessionCooldown: 5000 }} // optional: rate limiting
+/>
+```
+
+## Common Patterns
+
+### Using with shadcn/ui
+```tsx
+import { useChangelog } from 'featuredrop/react/hooks'
+import { Sheet, SheetContent, SheetTrigger } from '@/components/ui/sheet'
+import { Badge } from '@/components/ui/badge'
+
+function MyChangelog() {
+  const { newFeatures, newCount, dismiss, markAllSeen } = useChangelog()
+  return (
+    <Sheet onOpenChange={() => markAllSeen()}>
+      <SheetTrigger>
+        What's New {newCount > 0 && <Badge>{newCount}</Badge>}
+      </SheetTrigger>
+      <SheetContent>
+        {newFeatures.map(f => (
+          <div key={f.id} onClick={() => dismiss(f.id)}>
+            <h3>{f.label}</h3>
+            <p>{f.description}</p>
+          </div>
+        ))}
+      </SheetContent>
+    </Sheet>
+  )
+}
+```
+
+## Rules
+- Always use subpath imports (never bare 'featuredrop' for React code)
+- Prefer hooks over components when user has a custom design system
+- Features auto-expire via showNewUntil — don't build manual expiry logic
+- Zero production dependencies must be maintained
+- TypeScript strict — no any types

package/src/ai/cursorrules.txt

@@ -0,0 +1,13 @@
+When working with FeatureDrop:
+- FeatureDrop is a product adoption library (changelogs, badges, tours, checklists, feedback)
+- ALWAYS import from subpaths: 'featuredrop/react', 'featuredrop/react/hooks', 'featuredrop/adapters'
+- For custom UI: use hooks from 'featuredrop/react/hooks' (useChangelog, useTour, useChecklist)
+- For ready-made UI: use components from 'featuredrop/react' (NewBadge, ChangelogWidget, Tour)
+- Features are defined in JSON: { id, label, description, releasedAt, showNewUntil? }
+- Wrap app in <FeatureDropProvider manifest={features} storage={new LocalStorageAdapter()}>
+- Storage default: LocalStorageAdapter. Server: PostgresAdapter, RedisAdapter from 'featuredrop/adapters'
+- Core < 3 kB, React ~12 kB, zero production deps, fully tree-shakable
+- All components support headless mode via render props
+- For shadcn projects: use hooks from 'featuredrop/react/hooks' + shadcn primitives
+- TypeScript strict mode, no 'any' types
+- Zero production dependencies — do not add external deps