@getrefino/react 0.1.0-rc.1 → 0.1.0-rc.3

package/dist/RefinoProvider.d.ts

@@ -1,6 +1,7 @@
 import type { CopyContent } from "@getrefino/core";
 import type { JSX, ReactNode } from "react";
 import type { CopyRequestHeaders } from "./store.js";
+import type { EditorEventSink } from "./telemetry.js";
 export interface RefinoProviderProps {
     /** The canonical copy, usually `import copy from "./content/copy.json"`. */
     content: CopyContent;
@@ -23,6 +24,14 @@ export interface RefinoProviderProps {
     signInHref?: string | undefined;
     /** Called when the user presses Exit (after confirming unsaved changes). */
     onExit?: (() => void | Promise<void>) | undefined;
+    /**
+     * Optional sink for the editor's four semantic events (`editor_opened`,
+     * `edit_started`, `edit_saved`, `edit_reverted`). No SDK is loaded and no
+     * request is made unless a site provides one, and the events carry counts
+     * and enums only — never copy, ids or page content. Refino-connected
+     * sites get a sink that posts to Refino; everyone else gets silence.
+     */
+    onEvent?: EditorEventSink | undefined;
     /** Render the built-in toolbar in edit mode. Set false to use `useCopyEditor` with custom UI. */
     toolbar?: boolean | undefined;
     children?: ReactNode | undefined;

package/dist/RefinoProvider.js

@@ -1,7 +1,7 @@
 "use client";
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import { getDirtyIds } from "@getrefino/core";
-import { useEffect, useMemo, useState } from "react";
+import { useEffect, useMemo, useRef, useState } from "react";
 import { CopyContext } from "./context.js";
 import { createCopyStore } from "./store.js";
 import { EDITOR_STYLES } from "./styles.js";
@@ -13,8 +13,13 @@ import { CopyEditorToolbar } from "./Toolbar.js";
  * the toolbar and editor styles.
  */
 export function RefinoProvider(props) {
-    const { content, editing = false, endpoint = "/api/copy", headers, signInHref = "/edit", onExit, toolbar = true, children } = props;
-    const [store] = useState(() => createCopyStore({ content, editing, endpoint, headers }));
+    const { content, editing = false, endpoint = "/api/copy", headers, signInHref = "/edit", onExit, onEvent, toolbar = true, children } = props;
+    // Created once. The sink is read through the ref below, so a host that
+    // passes a new closure on every render neither recreates the store nor
+    // replays a lifecycle event.
+    const sinkRef = useRef(onEvent);
+    sinkRef.current = onEvent;
+    const [store] = useState(() => createCopyStore({ content, editing, endpoint, headers, onEvent: (event) => sinkRef.current?.(event) }));
     useEffect(() => {
         store.setEditing(editing);
     }, [editing, store]);

package/dist/index.d.ts

@@ -7,4 +7,5 @@ export { useCopyEditor } from "./useCopyEditor.js";
 export type { CopyEditor } from "./useCopyEditor.js";
 export { createCopyStore } from "./store.js";
 export type { CopyEditorState, CopyRequestHeaders, CopyStore, CopyStoreOptions, EditorError, EditorStatus, LastSave, RebaseInfo, } from "./store.js";
+export type { EditorEvent, EditorEventName, EditorEventProperties, EditorEventSink } from "./telemetry.js";
 export { EDITOR_STYLES } from "./styles.js";

package/dist/store.d.ts

@@ -1,4 +1,5 @@
 import type { ContentId, ContentSnapshot, CopyContent, DraftState } from "@getrefino/core";
+import type { EditorEventSink } from "./telemetry.js";
 export type EditorStatus = "idle" | "loading" | "saving" | "saved" | "error" | "conflict";
 export interface EditorError {
     readonly code: string;
@@ -44,6 +45,12 @@ export interface CopyStoreOptions {
      */
     readonly headers?: CopyRequestHeaders | undefined;
     readonly fetch?: typeof fetch;
+    /**
+     * Optional sink for the editor's four semantic events. Called only on real
+     * state transitions — never on a render, a keystroke, a poll or a retry —
+     * and never with copy, ids or anything read from the page.
+     */
+    readonly onEvent?: EditorEventSink | undefined;
 }
 export interface CopyStore {
     getState(): CopyEditorState;

package/dist/store.js

@@ -2,6 +2,36 @@ import { createDraft, getDirtyIds, getDraftValue, hasCopy, isDraftValueDirty, re
 export function createCopyStore(options) {
     const doFetch = options.fetch ?? ((...args) => globalThis.fetch(...args));
     const listeners = new Set();
+    /**
+     * Whether this editing session has already been reported as opened.
+     *
+     * An **editor session** starts when edit mode turns on and the canonical
+     * copy has loaded, and ends when edit mode turns off. Edit mode is a
+     * product state — decided by the host's server check, or in Refino-hosted
+     * mode by whether a valid editor token is stored — so a session is a fact
+     * about the product, never about React.
+     *
+     * That is why the flag is keyed to `editing` and not to the store's
+     * lifetime: within one session, a re-render, a StrictMode double effect,
+     * a retried `load()` or a `reloadLatest()` after a conflict must not
+     * report a second opening, while genuinely leaving edit mode and coming
+     * back must.
+     */
+    let openedReported = false;
+    function report(event) {
+        const sink = options.onEvent;
+        if (!sink)
+            return;
+        try {
+            sink(event);
+        }
+        catch {
+            // Telemetry must never break editing.
+        }
+    }
+    function dirtyCount(draft) {
+        return Object.keys(draft.changes).length;
+    }
     let state = {
         editing: options.editing,
         draft: createDraft(options.content),
@@ -89,19 +119,29 @@ export function createCopyStore(options) {
             const draft = setDraftValue(state.draft, id, value);
             if (draft === state.draft)
                 return;
+            // The transition from a clean draft to a dirty one, not every
+            // keystroke: typing a word produces one event, not twenty.
+            const started = dirtyCount(state.draft) === 0 && dirtyCount(draft) > 0;
             update({
                 draft,
                 status: state.status === "saved" || state.status === "error" ? "idle" : state.status,
                 error: state.status === "error" ? null : state.error,
             });
+            if (started)
+                report({ name: "edit_started", properties: {} });
         },
         revertValue(id) {
             const draft = revertDraftValue(state.draft, id);
-            if (draft !== state.draft)
-                update({ draft });
+            if (draft === state.draft)
+                return;
+            update({ draft });
+            report({ name: "edit_reverted", properties: { scope: "one" } });
         },
         revertAll() {
+            const had = dirtyCount(state.draft) > 0;
             update({ draft: revertAllDraft(state.draft), rebase: null });
+            if (had)
+                report({ name: "edit_reverted", properties: { scope: "all" } });
         },
         setActive(id) {
             if (state.activeId !== id)
@@ -113,8 +153,13 @@ export function createCopyStore(options) {
             update({ draft: createDraft(content) });
         },
         setEditing(editing) {
-            if (state.editing !== editing)
-                update({ editing });
+            if (state.editing === editing)
+                return;
+            // Leaving edit mode ends the session. The next one is a new session and
+            // reports its own opening, whether or not the provider ever unmounted.
+            if (!editing)
+                openedReported = false;
+            update({ editing });
         },
         async load() {
             update({ status: "loading", error: null });
@@ -122,6 +167,11 @@ export function createCopyStore(options) {
             if (body.ok && "snapshot" in body) {
                 applySnapshot(body.snapshot, getDirtyIds(state.draft).length > 0);
                 update({ status: "idle" });
+                // The editor is open once the canonical copy is actually in hand.
+                if (state.editing && !openedReported) {
+                    openedReported = true;
+                    report({ name: "editor_opened", properties: {} });
+                }
             }
             else if (!body.ok) {
                 update({ status: "error", error: body.error });
@@ -138,7 +188,8 @@ export function createCopyStore(options) {
                 return;
             }
             const changes = state.draft.changes;
-            if (Object.keys(changes).length === 0) {
+            const changedCount = Object.keys(changes).length;
+            if (changedCount === 0) {
                 update({ status: "saved", lastSave: { at: Date.now(), status: "unchanged" }, error: null });
                 return;
             }
@@ -155,6 +206,11 @@ export function createCopyStore(options) {
                     ? { at: Date.now(), status: result.status, commitUrl: result.commit.url }
                     : { at: Date.now(), status: result.status };
                 update({ status: "saved", lastSave });
+                // Only a save that produced a commit. An unchanged re-save wrote
+                // nothing, so it is not an edit.
+                if (result.status === "saved") {
+                    report({ name: "edit_saved", properties: { changed_count: changedCount } });
+                }
                 return;
             }
             if (!body.ok && body.error.code === "CONFLICT") {

package/dist/telemetry.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The editor's semantic event sink.
+ *
+ * `@getrefino/react` ships to customers' own websites, so it knows nothing
+ * about any analytics vendor and loads no SDK. It reports four facts about
+ * the editor's own state machine and hands them to whatever function the
+ * host passed in; a site that passes nothing sends nothing.
+ *
+ * What it reports is deliberately tiny and deliberately content-free: a
+ * count and an enum, never a copy id, never a draft value, never the
+ * canonical text, never anything read out of the customer's page. The
+ * properties an event may carry are listed here, in types, for exactly
+ * that reason.
+ */
+export type EditorEventName = 
+/** Edit mode is on and the canonical copy has loaded. Once per editor session. */
+"editor_opened"
+/** The draft went from clean to dirty. Once per run of changes, not once per keystroke. */
+ | "edit_started"
+/** A save succeeded. Hosts that persist through Refino leave this to the server. */
+ | "edit_saved"
+/** A draft change was thrown away. */
+ | "edit_reverted";
+export interface EditorEventProperties {
+    editor_opened: Record<string, never>;
+    edit_started: Record<string, never>;
+    /** How many ids were in the save. A count, never the ids. */
+    edit_saved: {
+        readonly changed_count: number;
+    };
+    edit_reverted: {
+        readonly scope: "one" | "all";
+    };
+}
+export type EditorEvent = {
+    [E in EditorEventName]: {
+        readonly name: E;
+        readonly properties: EditorEventProperties[E];
+    };
+}[EditorEventName];
+/**
+ * Called once per editor state transition. It must not throw — the store
+ * calls it inside a guard anyway, so a sink that does is simply ignored —
+ * and it must not block: treat it as fire and forget.
+ */
+export type EditorEventSink = (event: EditorEvent) => void;

package/dist/telemetry.js

@@ -0,0 +1,15 @@
+/**
+ * The editor's semantic event sink.
+ *
+ * `@getrefino/react` ships to customers' own websites, so it knows nothing
+ * about any analytics vendor and loads no SDK. It reports four facts about
+ * the editor's own state machine and hands them to whatever function the
+ * host passed in; a site that passes nothing sends nothing.
+ *
+ * What it reports is deliberately tiny and deliberately content-free: a
+ * count and an enum, never a copy id, never a draft value, never the
+ * canonical text, never anything read out of the customer's page. The
+ * properties an event may carry are listed here, in types, for exactly
+ * that reason.
+ */
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getrefino/react",
-  "version": "0.1.0-rc.1",
+  "version": "0.1.0-rc.3",
   "description": "React components for Refino: edit a website's existing copy in place on the rendered page and commit it to the repository. Click text. Edit text. Save.",
   "keywords": [
     "refino",
@@ -37,7 +37,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@getrefino/core": "0.1.0-rc.1"
+    "@getrefino/core": "0.1.0-rc.3"
   },
   "peerDependencies": {
     "react": "^18.2.0 || ^19.0.0",