feedtack 1.0.1 → 1.2.0

package/README.md

@@ -80,49 +80,12 @@ The `FeedtackAdapter` interface has five methods. Here are copy-paste implementa
 
 ### Disk / JSON files (Node.js)
 
-Git-trackable feedback — each submission becomes a JSON file in `.feedback/`.
+Git-trackable feedback — each submission becomes a JSON file in `.feedback/`. `DiskAdapter` ships with the package and also implements `ContentAdapter` + `ContentEditAdapter`.
 
 ```ts
-import type { FeedtackAdapter, FeedbackItem, FeedtackPayload } from 'feedtack'
-import { readdir, readFile, writeFile, mkdir } from 'node:fs/promises'
-import { join } from 'node:path'
+import { DiskAdapter } from 'feedtack/node'
 
-const DIR = '.feedback'
-
-class DiskAdapter implements FeedtackAdapter {
-  async submit(payload: FeedtackPayload) {
-    await mkdir(DIR, { recursive: true })
-    const item: FeedbackItem = { payload, replies: [], resolutions: [], archives: [] }
-    await writeFile(join(DIR, `${payload.id}.json`), JSON.stringify(item, null, 2))
-  }
-
-  async reply(feedbackId: string, reply: Omit<FeedbackItem['replies'][0], 'id' | 'feedbackId'>) {
-    const item = await this.read(feedbackId)
-    item.replies.push({ ...reply, id: crypto.randomUUID(), feedbackId })
-    await this.write(feedbackId, item)
-  }
-
-  async resolve(feedbackId: string, resolution: Omit<FeedbackItem['resolutions'][0], 'feedbackId'>) {
-    const item = await this.read(feedbackId)
-    item.resolutions.push({ ...resolution, feedbackId })
-    await this.write(feedbackId, item)
-  }
-
-  async archive(feedbackId: string, userId: string) {
-    const item = await this.read(feedbackId)
-    item.archives.push({ feedbackId, archivedBy: { id: userId, name: '', role: '' }, timestamp: new Date().toISOString() })
-    await this.write(feedbackId, item)
-  }
-
-  async loadFeedback() {
-    await mkdir(DIR, { recursive: true })
-    const files = (await readdir(DIR)).filter((f) => f.endsWith('.json'))
-    return Promise.all(files.map(async (f) => JSON.parse(await readFile(join(DIR, f), 'utf-8')) as FeedbackItem))
-  }
-
-  private async read(id: string) { return JSON.parse(await readFile(join(DIR, `${id}.json`), 'utf-8')) as FeedbackItem }
-  private async write(id: string, item: FeedbackItem) { await writeFile(join(DIR, `${id}.json`), JSON.stringify(item, null, 2)) }
-}
+const adapter = new DiskAdapter({ directory: '.feedback' }) // default: '.feedback'
 ```
 
 ### Supabase
@@ -243,6 +206,51 @@ function MyButton() {
 }
 ```
 
+## Content approval (opt-in)
+
+Feedtack can also track whether copywriting fields on a page have been reviewed and approved. Annotate elements with `data-feedtack-field`, use an adapter that implements `ContentAdapter` (`DiskAdapter` and `WebhookAdapter` both do), and call the hook:
+
+```tsx
+<h1 data-feedtack-field="hero.heading">Welcome to Acme</h1>
+<p data-feedtack-field="hero.subheading">The best tools for your team.</p>
+```
+
+```tsx
+import { useContentApproval } from 'feedtack/react'
+
+const { fields, approve, checkDeploy } = useContentApproval(adapter, currentUser.id)
+
+// Gate deploys on all fields being approved
+const result = await checkDeploy()
+// => { approved: false, pending: ['hero.subheading'] }
+```
+
+Approvals are hash-based — if the content changes, the approval goes stale automatically. See the [Content Approval docs](site-docs/content/docs/concepts/content-approval.mdx) for the full API.
+
+## Content editing (opt-in)
+
+For teams that want to edit content inline, `useContentEdit` builds on top of content approval. It hydrates the DOM with stored values, makes annotated fields `contenteditable`, and auto-saves on blur. The adapter must implement `ContentEditAdapter` (`DiskAdapter` and `WebhookAdapter` both do).
+
+```tsx
+import { useContentEdit, ContentEditToolbar } from 'feedtack/react'
+
+function AdminLayout({ adapter, children }) {
+  const edit = useContentEdit(adapter, currentUser.id)
+
+  return (
+    <>
+      {children}
+      {edit.active && <ContentEditToolbar {...edit.toolbarProps} />}
+      <button onClick={edit.active ? edit.deactivate : edit.activate}>
+        {edit.active ? 'Exit edit mode' : 'Edit content'}
+      </button>
+    </>
+  )
+}
+```
+
+The toolbar shows approve/revert actions per field, a session changes panel, and a deploy gate. See the [Content Editing docs](site-docs/content/docs/concepts/content-editing.mdx) for details.
+
 ## What feedtack does NOT do
 
 - LLM triage or routing (downstream concern — feedtack emits, others act)
@@ -251,6 +259,7 @@ function MyButton() {
 
 ## ICEBOX
 
+- Vanilla JS content editing (no React dependency)
 - Script tag CDN distribution
 - Next.js plugin
 - `allowedCaptures` config for scoping DOM access

package/dist/{theme-BdqpMipn.d.ts → adapter-Cn59URIG.d.ts}

@@ -132,7 +132,74 @@ interface FeedtackFilter {
     userId?: string;
     scope?: FeedtackScope;
 }
+/** Recorded approval for a content field — keyed by dot-path (e.g. "hero.heading") */
+interface FieldApproval {
+    /** 12-char truncated SHA-256 of the approved content */
+    hash: string;
+    /** User IDs who have approved this field */
+    by: string[];
+    /** ISO 8601 UTC timestamp of most recent approval */
+    at: string;
+}
+/** Combined field identity, approval record, and staleness flag */
+interface FieldApprovalState {
+    /** Dot-path field identifier (value of data-feedtack-field attribute) */
+    fieldPath: string;
+    /** Null when the field has never been approved */
+    approval: FieldApproval | null;
+    /** True when the current content hash differs from the stored approval hash */
+    stale: boolean;
+}
+interface FieldFilter {
+    pathname?: string;
+    fieldPath?: string;
+}
+/** A single field edit recorded in the current editing session */
+interface FieldChange {
+    fieldPath: string;
+    /** Value at session start (pre-first-edit for this field) */
+    from: string;
+    /** Most recent saved value */
+    to: string;
+    /** Unix ms timestamp of most recent save */
+    savedAt: number;
+}
+/** Info about the currently focused content field — used by the edit toolbar */
+interface FocusedFieldInfo {
+    element: HTMLElement;
+    fieldPath: string;
+}
 
+/**
+ * Optional extension interface for adapters that support content field approvals.
+ * Implement alongside FeedtackAdapter — adapters that omit this continue to work unchanged.
+ */
+interface ContentAdapter {
+    /** Record approval for a field at its current hash */
+    approve(fieldPath: string, approval: FieldApproval): Promise<void>;
+    /** Remove approval for a field by a specific user */
+    revokeApproval(fieldPath: string, userId: string): Promise<void>;
+    /** Load approval states, optionally filtered */
+    loadApprovals(filter?: FieldFilter): Promise<FieldApprovalState[]>;
+}
+/**
+ * Optional extension of ContentAdapter for adapters that support inline content editing.
+ * saveField MUST atomically persist the new value AND clear the stored approval.
+ */
+interface ContentEditAdapter extends ContentAdapter {
+    /** Fetch all stored field values for DOM hydration — keyed by dot-path */
+    loadFields(): Promise<Record<string, string>>;
+    /** Persist a field edit. MUST clear the stored approval for the field. */
+    saveField(fieldPath: string, value: string): Promise<void>;
+}
+/** Returns true if the adapter implements ContentEditAdapter */
+declare function isContentEditAdapter(adapter: unknown): adapter is ContentEditAdapter;
+/** Warn in dev mode when an edit method is called on a non-ContentEditAdapter */
+declare function warnIfNotContentEditAdapter(adapter: unknown, method: string): void;
+/** Returns true if the adapter implements ContentAdapter */
+declare function isContentAdapter(adapter: unknown): adapter is ContentAdapter;
+/** Warn in dev mode when a ContentAdapter method is called on a non-ContentAdapter */
+declare function warnIfNotContentAdapter(adapter: unknown, method: string): void;
 /** Plugin contract — implement this interface to create a custom feedtack backend */
 interface FeedtackAdapter {
     /** Submit new feedback payload */
@@ -147,25 +214,4 @@ interface FeedtackAdapter {
     loadFeedback(filter?: FeedtackFilter): Promise<FeedbackItem[]>;
 }
 
-interface FeedtackTheme {
-    /** Accent color — pin button active state, focus rings, selected states */
-    primary?: string;
-    /** Panel and picker background */
-    background?: string;
-    /** Input and card surface background */
-    surface?: string;
-    /** Primary text color */
-    text?: string;
-    /** Secondary/placeholder text color */
-    textMuted?: string;
-    /** Panel and input border color */
-    border?: string;
-    /** Border radius applied to panels and inputs */
-    radius?: string;
-    /** Notification badge color */
-    badge?: string;
-}
-/** Maps FeedtackTheme fields to CSS custom properties on #feedtack-root */
-declare function themeToCSS(theme: FeedtackTheme): Record<string, string>;
-
-export { type AncestorNode as A, type FeedtackAdapter as F, SCHEMA_VERSION as S, type FeedtackPayload as a, type FeedtackReply as b, type FeedtackResolution as c, type FeedtackFilter as d, type FeedbackItem as e, type FeedtackDeviceMeta as f, type FeedtackPageMeta as g, type FeedtackViewportMeta as h, type FeedtackPinTarget as i, type FeedtackArchive as j, type FeedtackBoundingRect as k, type FeedtackPin as l, type FeedtackScope as m, type FeedtackSentiment as n, type FeedtackTheme as o, type FeedtackUser as p, themeToCSS as t };
+export { type AncestorNode as A, type ContentAdapter as C, type FeedtackAdapter as F, SCHEMA_VERSION as S, type FeedtackPayload as a, type FeedtackReply as b, type FeedtackResolution as c, type FeedtackFilter as d, type FeedbackItem as e, type ContentEditAdapter as f, type FieldFilter as g, type FieldApprovalState as h, type FieldApproval as i, type FeedtackDeviceMeta as j, type FeedtackPageMeta as k, type FeedtackViewportMeta as l, type FeedtackPinTarget as m, type FeedtackArchive as n, type FeedtackBoundingRect as o, type FeedtackPin as p, type FeedtackScope as q, type FeedtackSentiment as r, type FeedtackUser as s, type FieldChange as t, type FocusedFieldInfo as u, isContentAdapter as v, isContentEditAdapter as w, warnIfNotContentAdapter as x, warnIfNotContentEditAdapter as y };