featuredrop 1.1.0 → 1.3.0

package/README.md

@@ -87,6 +87,14 @@ export const FEATURES = createManifest([
     priority: 'critical',
     cta: { label: 'Try it', url: '/journal' },
   },
+  {
+    id: 'scheduled-reports',
+    label: 'Scheduled Reports',
+    releasedAt: '2026-02-23T00:00:00Z',
+    showNewUntil: '2026-03-23T00:00:00Z',
+    dependsOn: { clicked: ['ai-journal'] }, // progressive rollout
+    trigger: { type: 'page', match: '/reports/*' }, // contextual trigger
+  },
 ])
 ```
 
@@ -101,6 +109,10 @@ const storage = new LocalStorageAdapter({
 })
 ```
 
+For offline-heavy apps, use `IndexedDBAdapter` to persist the same state with IndexedDB + local fallback.
+It also supports queued dismiss sync (`flushQueue`) + remote state reconciliation (`syncFromRemote`) for offline-first flows.
+For remote/state sync, `RemoteAdapter` now includes retry + circuit-breaker protection and a monitoring-friendly `isHealthy()` check.
+
 **3. Check what's new:**
 
 ```ts
@@ -112,6 +124,359 @@ hasNewFeature(FEATURES, '/journal', storage) // true/false
 
 Works with **any framework**. Zero React dependency for vanilla use.
 
+## Adoption Analytics
+
+Pipe structured adoption events to PostHog/Amplitude/Mixpanel/Segment or your own endpoint.
+
+```ts
+import { AnalyticsCollector, PostHogAdapter } from 'featuredrop'
+
+const collector = new AnalyticsCollector({
+  adapter: new PostHogAdapter(posthog),
+  batchSize: 20,
+  flushInterval: 10_000,
+  sampleRate: 1,
+})
+```
+
+```tsx
+<FeatureDropProvider
+  manifest={FEATURES}
+  storage={storage}
+  collector={collector}
+>
+  <App />
+</FeatureDropProvider>
+```
+
+## A/B Announcement Variants
+
+Run deterministic per-user announcement variants with weighted splits.
+
+```ts
+{
+  id: 'ai-journal',
+  label: 'AI Decision Journal',
+  variants: {
+    control: { description: 'Track decisions with AI-powered insights.' },
+    treatment: { description: 'Never second-guess decisions again.' },
+  },
+  variantSplit: [50, 50],
+}
+```
+
+```tsx
+<FeatureDropProvider
+  manifest={FEATURES}
+  storage={storage}
+  variantKey={user.id} // stable key for deterministic assignment
+>
+  <App />
+</FeatureDropProvider>
+```
+
+## Theme Engine
+
+Theme all featuredrop components with CSS variables (no CSS-in-JS runtime).
+
+```tsx
+import { ThemeProvider, ChangelogWidget } from 'featuredrop/react'
+
+<ThemeProvider theme="dark">
+  <ChangelogWidget />
+</ThemeProvider>
+```
+
+```tsx
+import { createTheme } from 'featuredrop'
+import { ThemeProvider, ChangelogPage } from 'featuredrop/react'
+
+const myTheme = createTheme({
+  colors: { primary: '#7c3aed' },
+  radii: { lg: '16px' },
+})
+
+<ThemeProvider theme={myTheme}>
+  <ChangelogPage />
+</ThemeProvider>
+```
+
+Presets: `light`, `dark`, `auto`, `minimal`, `vibrant`.
+You can also pass `theme` directly to `ChangelogWidget` and `ChangelogPage` for component-scoped overrides.
+
+## Internationalization
+
+Use built-in locale packs or supply partial overrides:
+
+```tsx
+<FeatureDropProvider
+  manifest={FEATURES}
+  storage={storage}
+  locale="fr"
+  translations={{
+    submit: 'Envoyer maintenant',
+  }}
+>
+  <App />
+</FeatureDropProvider>
+```
+
+Built-in locales: `en`, `es`, `fr`, `de`, `pt`, `zh-cn`, `ja`, `ko`, `ar`, `hi`.
+Locale helpers include locale-aware date formatting, pluralized count copy, and RTL direction support for Arabic.
+Use `formatRelativeTimeForLocale()` for localized "x days ago" labels, or set `dateFormat="relative"` on `ChangelogWidget` / `ChangelogPage`.
+
+## Animation Presets
+
+Choose built-in motion levels globally:
+
+```tsx
+<FeatureDropProvider manifest={FEATURES} storage={storage} animation="subtle">
+  <App />
+</FeatureDropProvider>
+```
+
+Available presets: `none`, `subtle`, `normal`, `playful`.  
+Reduced-motion users automatically receive `none`.
+Built-in `ChangelogWidget`, `AnnouncementModal`, and `Toast` include enter/exit animations, and `Tour`, `Survey`, `FeedbackWidget`, `Spotlight`, `SpotlightChain`, and `Hotspot` follow the same preset for enter/pulse motion.
+
+## Custom Renderer Protocol
+
+Need full UI control? Use a UI-agnostic renderer with state/actions/computed helpers:
+
+```ts
+import { createChangelogRenderer } from 'featuredrop'
+
+const renderer = createChangelogRenderer({ manifest: FEATURES, storage })
+renderer.subscribe((state) => console.log(state.newCount))
+renderer.actions.dismiss('ai-journal')
+```
+
+## Accessibility
+
+featuredrop components include keyboard navigation, focus trapping/return for dialogs, ARIA live regions, and reduced-motion support.
+
+Automated accessibility regression checks run in CI via `axe-core` + `vitest-axe` (`src/__tests__/accessibility-axe.test.tsx`).
+
+## Changelog-as-Code
+
+Manage announcements as markdown files in your repo and compile to a manifest:
+
+```bash
+npx featuredrop init --format markdown
+npx featuredrop add --label "AI Journal" --category ai --description "Track decisions with AI."
+npx featuredrop build --pattern "features/**/*.md" --out featuredrop.manifest.json
+npx featuredrop validate --pattern "features/**/*.md"
+npx featuredrop stats --pattern "features/**/*.md"
+npx featuredrop doctor --pattern "features/**/*.md"
+npx featuredrop generate-rss --pattern "features/**/*.md" --out featuredrop.rss.xml
+npx featuredrop generate-changelog --pattern "features/**/*.md" --out CHANGELOG.generated.md
+npx featuredrop migrate --from beamer --input beamer-export.json --out featuredrop.manifest.json
+npx featuredrop migrate --from headway --input headway-export.json --out featuredrop.manifest.json
+npx featuredrop migrate --from announcekit --input announcekit-export.json --out featuredrop.manifest.json
+npx featuredrop migrate --from canny --input canny-export.json --out featuredrop.manifest.json
+npx featuredrop migrate --from launchnotes --input launchnotes-export.json --out featuredrop.manifest.json
+```
+
+Example feature file:
+
+```md
+---
+id: ai-journal
+label: AI Journal
+type: feature
+category: ai
+releasedAt: 2026-02-15T00:00:00Z
+showNewUntil: 2026-03-15T00:00:00Z
+cta:
+  label: Try it now
+  url: /journal
+---
+Track decisions and outcomes with AI-powered insights.
+```
+
+## CMS Adapters
+
+Pull releases from your CMS and map them into `FeatureEntry[]`:
+
+```ts
+import { ContentfulAdapter, SanityAdapter, StrapiAdapter, NotionAdapter, MarkdownAdapter } from 'featuredrop'
+
+const contentful = new ContentfulAdapter({
+  spaceId: process.env.CONTENTFUL_SPACE!,
+  accessToken: process.env.CONTENTFUL_TOKEN!,
+  contentType: 'featureRelease',
+})
+
+const entries = await contentful.load()
+```
+
+Each adapter accepts optional `fieldMapping` overrides so you can map your content model fields without reshaping server responses.
+
+## Notification Bridges
+
+Use framework-agnostic bridge helpers to fan out release notifications:
+
+```ts
+import {
+  SlackBridge,
+  DiscordBridge,
+  EmailDigestGenerator,
+  WebhookBridge,
+  RSSFeedGenerator,
+} from 'featuredrop/bridges'
+
+await SlackBridge.notify(feature, { webhookUrl: process.env.SLACK_WEBHOOK! })
+await DiscordBridge.notify(feature, { webhookUrl: process.env.DISCORD_WEBHOOK! })
+await WebhookBridge.post(feature, { url: 'https://api.example.com/hooks/features' })
+
+const html = EmailDigestGenerator.generate(features, { title: 'Weekly updates' })
+const rss = RSSFeedGenerator.generate(features, { title: 'Product Updates' })
+```
+
+## CI Utilities
+
+Use `featuredrop/ci` for manifest diffing in pull-request checks:
+
+```ts
+import { diffManifest, generateChangelogDiff, validateManifestForCI } from 'featuredrop/ci'
+
+const diff = diffManifest(beforeManifest, afterManifest)
+const summary = generateChangelogDiff(diff, { includeFieldChanges: true })
+const validation = validateManifestForCI(afterManifest)
+```
+
+Run bundle budget checks after `pnpm build`:
+
+```bash
+pnpm size-check
+```
+
+## Feature Flag Bridges
+
+Gate announcement visibility behind flags via `feature.flagKey`:
+
+```ts
+import { createFlagBridge, LaunchDarklyBridge, PostHogBridge } from 'featuredrop/flags'
+
+const bridge = createFlagBridge({
+  isEnabled: (flagKey) => myFlagService.isOn(flagKey),
+})
+
+// Provider + feature entry
+<FeatureDropProvider manifest={FEATURES} storage={storage} flagBridge={bridge} />
+// { id: 'ai-journal', flagKey: 'ai-journal-enabled', ... }
+
+// Or vendor bridges
+const ld = new LaunchDarklyBridge(ldClient)
+const ph = new PostHogBridge(posthog)
+```
+
+## Multi-Product Support
+
+Scope visibility by product using `FeatureDropProvider` + `feature.product`:
+
+```tsx
+<FeatureDropProvider manifest={FEATURES} storage={storage} product="askverdict" />
+// feature.product can be "askverdict", "other-product", or "*" for shared entries
+```
+
+## Admin Components
+
+Use optional admin UI primitives via `featuredrop/admin`:
+
+```tsx
+import {
+  ManifestEditor,
+  ScheduleCalendar,
+  PreviewPanel,
+  AudienceBuilder,
+} from 'featuredrop/admin'
+
+<ManifestEditor features={features} onSave={saveManifest} />
+<ScheduleCalendar features={features} onSchedule={scheduleFeature} />
+<PreviewPanel feature={selectedFeature} components={['badge', 'changelog', 'toast']} />
+<AudienceBuilder segments={['free', 'pro']} roles={['admin', 'viewer']} onSave={saveAudience} />
+```
+
+## Resilience
+
+Built-in React exports are wrapped in internal error boundaries. If a featuredrop component throws, it unmounts itself (no host app crash) and optionally reports through provider `onError`.
+
+## Schema Validation
+
+Validate manifest JSON in CI or tooling pipelines.
+
+```ts
+import {
+  featureEntrySchema,
+  featureEntryJsonSchema,
+  validateManifest,
+} from 'featuredrop/schema'
+
+featureEntrySchema.parse({
+  id: 'ai-journal',
+  label: 'AI Journal',
+  releasedAt: '2026-02-15T00:00:00Z',
+  showNewUntil: '2026-03-15T00:00:00Z',
+})
+
+const result = validateManifest(data)
+if (!result.valid) {
+  throw new Error(result.errors.map((e) => `${e.path}: ${e.message}`).join("; "))
+}
+
+console.log(featureEntryJsonSchema.properties.id.type) // "string"
+```
+
+## Testing Utilities
+
+Use `featuredrop/testing` to speed up unit and component tests.
+
+```tsx
+import { render, screen } from '@testing-library/react'
+import { useNewCount } from 'featuredrop/react'
+import { createMockManifest, createMockStorage, createTestProvider } from 'featuredrop/testing'
+
+const manifest = createMockManifest([{ label: 'AI Journal', releasedAt: 'today', showNewUntil: '+14d' }])
+const storage = createMockStorage()
+const Wrapper = createTestProvider({ manifest, storage })
+
+function Count() {
+  return <span>{useNewCount()}</span>
+}
+
+render(<Count />, { wrapper: Wrapper })
+expect(screen.getByText('1')).toBeInTheDocument()
+```
+
+## Playground & Online Demos
+
+Use the lightweight component playground for quick UI iteration:
+
+```bash
+pnpm --dir examples/sandbox-react install
+pnpm playground
+pnpm playground:build
+```
+
+One-click editable demos:
+
+- React sandbox source: `examples/sandbox-react`
+- StackBlitz: https://stackblitz.com/github/GLINCKER/featuredrop/tree/main/examples/sandbox-react
+- CodeSandbox: https://codesandbox.io/p/sandbox/github/GLINCKER/featuredrop/tree/main/examples/sandbox-react
+
+## Docs Site (Nextra + Vercel)
+
+The repo now includes a docs app scaffold at `apps/docs` for a fast validation launch on Vercel.
+
+```bash
+pnpm docs:install
+pnpm docs:dev
+pnpm docs:build
+```
+
+The docs app is static-export ready, so it can also deploy on Cloudflare Pages or GitHub Pages.
+
 ## Components
 
 Everything you'd expect from Beamer or Headway — but free, self-hosted, and headless-first.
@@ -129,6 +494,9 @@ import { ChangelogWidget } from 'featuredrop/react'
 // Or modal / popover variant
 <ChangelogWidget variant="modal" title="Release Notes" />
 
+// Enable emoji reactions on entries
+<ChangelogWidget showReactions />
+
 // Fully headless
 <ChangelogWidget>
   {({ isOpen, toggle, features, count, dismissAll }) => (
@@ -177,6 +545,124 @@ import { Toast } from 'featuredrop/react'
 <Toast featureIds={["ai-journal"]} autoDismissMs={5000} />
 ```
 
+### Product Tours
+
+Guided, multi-step onboarding with keyboard navigation and persistence.
+
+```tsx
+import { Tour, useTour } from 'featuredrop/react'
+
+<Tour id="onboarding" steps={steps} />
+const { startTour, nextStep, skipTour } = useTour('onboarding')
+```
+
+### Onboarding Checklist
+
+Task-based onboarding that can trigger tours, links, or callbacks.
+
+```tsx
+import { Checklist, useChecklist } from 'featuredrop/react'
+
+<Checklist id="getting-started" tasks={tasks} />
+const { completeTask, progress } = useChecklist('getting-started')
+```
+
+### Feedback Widget
+
+Collect lightweight in-app feedback with optional emoji and screenshots.
+
+```tsx
+import { FeedbackWidget } from 'featuredrop/react'
+
+<FeedbackWidget
+  featureId="ai-journal"
+  onSubmit={async (payload) => {
+    await fetch('/api/feedback', { method: 'POST', body: JSON.stringify(payload) })
+  }}
+  showEmoji
+  showScreenshot
+  rateLimit="1-per-feature"
+/>
+```
+
+### Survey (NPS / CSAT / CES / Custom)
+
+Run micro-surveys with trigger rules and imperative controls.
+
+```tsx
+import { Survey, useSurvey } from 'featuredrop/react'
+
+<Survey
+  id="nps-main"
+  type="nps"
+  prompt="How likely are you to recommend us?"
+  triggerRules={{ minDaysSinceSignup: 7, signupAt: user.createdAt }}
+  onSubmit={saveSurvey}
+/>
+
+const { show } = useSurvey('nps-main')
+```
+
+### Feature Request Voting
+
+Capture and rank product requests with local persistence and optional webhook sync.
+
+```tsx
+import { FeatureRequestButton, FeatureRequestForm } from 'featuredrop/react'
+
+<FeatureRequestButton featureId="dark-mode" requestTitle="Dark mode" />
+
+<FeatureRequestForm
+  categories={['UI', 'Performance', 'Integration', 'Other']}
+  onSubmit={async (request) => {
+    await fetch('/api/requests', { method: 'POST', body: JSON.stringify(request) })
+  }}
+/>
+```
+
+### Hotspots & Tooltips
+
+Persistent contextual hints attached to specific UI targets.
+
+```tsx
+import { Hotspot, TooltipGroup } from 'featuredrop/react'
+
+<TooltipGroup maxVisible={1}>
+  <Hotspot id="export-help" target="#export-btn" frequency="once">
+    Export supports CSV, PDF, and Excel.
+  </Hotspot>
+</TooltipGroup>
+```
+
+### Announcement Modal
+
+Priority-based modal announcements with optional slide carousel.
+
+```tsx
+import { AnnouncementModal } from 'featuredrop/react'
+
+<AnnouncementModal
+  feature={criticalFeature}
+  trigger="auto"
+  frequency="once"
+/>
+```
+
+### Spotlight Chain
+
+Lightweight chained spotlights for "here are 3 new things" flows.
+
+```tsx
+import { SpotlightChain } from 'featuredrop/react'
+
+<SpotlightChain
+  steps={[
+    { target: '#sidebar', content: 'New navigation' },
+    { target: '#search', content: 'Global search' },
+  ]}
+/>
+```
+
 ### NewBadge
 
 Headless badge component with variants. Zero CSS framework dependency.
@@ -211,7 +697,27 @@ npm install featuredrop react    # react is an optional peer dep
 ```tsx
 import { FeatureDropProvider } from 'featuredrop/react'
 
-<FeatureDropProvider manifest={FEATURES} storage={storage}>
+<FeatureDropProvider manifest={FEATURES} storage={storage} appVersion="2.5.1">
+  <App />
+</FeatureDropProvider>
+```
+
+**Throttling + quiet mode:**
+
+```tsx
+<FeatureDropProvider
+  manifest={FEATURES}
+  storage={storage}
+  throttle={{
+    maxSimultaneousBadges: 3,
+    maxSimultaneousSpotlights: 1,
+    maxToastsPerSession: 3,
+    minTimeBetweenModals: 30000,
+    minTimeBetweenTours: 86400000,
+    sessionCooldown: 5000,
+    respectDoNotDisturb: true,
+  }}
+>
   <App />
 </FeatureDropProvider>
 ```
@@ -248,11 +754,28 @@ import { ChangelogWidget } from 'featuredrop/react'
 | `useNewFeature(key)` | Single nav item: `{ isNew, feature, dismiss }` |
 | `useNewCount()` | Just the badge count |
 | `useTabNotification()` | Updates browser tab title with count |
+| `useTour(id)` | Imperative tour controls and current step snapshot |
+| `useTourSequencer(sequence)` | Ordered multi-tour orchestration by feature readiness |
+| `useChecklist(id)` | Imperative checklist controls + progress |
+| `useSurvey(id)` | Imperative survey controls (`show`, `hide`, `askLater`) + state |
 | `<NewBadge />` | Headless badge: `pill`, `dot`, or `count` variant |
-| `<ChangelogWidget />` | Full changelog feed with trigger button |
+| `<ChangelogWidget />` | Full changelog feed with trigger button + optional reactions |
+| `<ChangelogPage />` | Full-page changelog with filters/search/pagination |
 | `<Spotlight />` | Pulsing beacon attached to DOM elements |
 | `<Banner />` | Announcement banner with variants |
 | `<Toast />` | Stackable toast notifications |
+| `<Tour />` | Multi-step guided product tour |
+| `<Checklist />` | Onboarding task checklist |
+| `<FeedbackWidget />` | In-app feedback form with category/emoji/screenshot support |
+| `<Survey />` | NPS/CSAT/CES/custom survey engine with trigger rules |
+| `<FeatureRequestButton />` | Per-feature voting button with persisted vote guard |
+| `<FeatureRequestForm />` | Request capture form + sortable request list |
+| `<Hotspot />` / `<TooltipGroup />` | Contextual tooltips with visibility caps |
+| `<AnnouncementModal />` | Priority/frequency-gated modal announcements |
+| `<SpotlightChain />` | Lightweight chained spotlight walkthrough |
+
+`useFeatureDrop()` also exposes queue/throttle controls: `queuedFeatures`, `totalNewCount`, `quietMode`, `setQuietMode`, `markFeatureSeen`, `markFeatureClicked`, toast-slot helpers, modal/tour pacing checks, and spotlight slot controls.
+It also exposes trigger runtime helpers: `trackUsageEvent`, `trackTriggerEvent`, `trackMilestone`, and `setTriggerPath`.
 
 **Analytics integration:**
 
@@ -260,6 +783,7 @@ import { ChangelogWidget } from 'featuredrop/react'
 <FeatureDropProvider
   manifest={FEATURES}
   storage={storage}
+  appVersion="2.5.1" // optional semver for version-pinned features
   analytics={{
     onFeatureSeen: (f) => posthog.capture('feature_seen', { id: f.id }),
     onFeatureDismissed: (f) => posthog.capture('feature_dismissed', { id: f.id }),
@@ -311,7 +835,12 @@ Read the full [Architecture doc](docs/ARCHITECTURE.md) for cross-device sync flo
 | **Price** | **Free** | $59-399/mo | $49-249/mo | $79-299/mo | $79+ |
 | Auto-expiring badges | Yes | - | - | - | - |
 | Changelog widget | Yes | Yes | Yes | Yes | Yes |
+| Product tours | Yes | - | - | - | - |
+| Onboarding checklists | Yes | - | - | - | - |
 | Spotlight/beacon | Yes | - | - | - | - |
+| Hotspot tooltips | Yes | - | - | - | - |
+| Announcement modal | Yes | - | - | - | - |
+| Spotlight chaining | Yes | - | - | - | - |
 | Toast notifications | Yes | - | - | - | - |
 | Announcement banner | Yes | - | - | - | - |
 | Tab title notification | Yes | - | - | - | - |
@@ -334,20 +863,34 @@ Read the full [Architecture doc](docs/ARCHITECTURE.md) for cross-device sync flo
 |-----------|--------|--------|
 | React / Next.js | Stable | `featuredrop/react` |
 | Vanilla JS | Stable | `featuredrop` |
-| Vue 3 | Planned | `featuredrop/vue` |
-| Svelte 5 | Planned | `featuredrop/svelte` |
+| SolidJS | Preview | `featuredrop/solid` |
+| Preact (compat) | Preview | `featuredrop/preact` |
+| Web Components | Preview | `featuredrop/web-components` |
+| Angular | Preview | `featuredrop/angular` |
+| Vue 3 | Preview | `featuredrop/vue` |
+| Svelte 5 | Preview (store bindings) | `featuredrop/svelte` |
 
 ## Documentation
 
+- [Docs App Source](apps/docs/) — Next.js + Nextra site scaffold (`/`, `/docs`, `/playground`)
+- [Docs Site Guide](docs/DOCS_SITE.md) — Local commands and Vercel deployment setup
 - [API Reference](docs/API.md) — All functions, adapters, hooks, components
+- [Recipes](docs/RECIPES.md) — Copy-paste integration patterns (sidebar badge, tours, migration, A/B tests)
 - [Architecture](docs/ARCHITECTURE.md) — Three-check algorithm, cross-device sync, custom adapters
 - [Next.js Example](examples/nextjs/) — Full App Router integration
 - [Vanilla Example](examples/vanilla/) — Plain HTML, zero build step
+- [React Sandbox](examples/sandbox-react/) — Interactive local/online playground
 
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, commit conventions, and how releases work.
 
+## Security
+
+- Report vulnerabilities privately via [SECURITY.md](SECURITY.md).
+- CI includes CodeQL static analysis on pull requests and `main`.
+- `pnpm security-check` scans runtime source for unsafe execution/rendering patterns.
+
 ## License
 
 MIT &copy; [Glincker](https://glincker.com)