@getrefino/react 0.1.0-rc.4 → 0.1.0-rc.6

package/dist/updates.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Updating the site's Refino integration from the editor.
+ *
+ * The editor knows nothing about where updates come from. A host that can
+ * update itself passes an `IntegrationUpdateSource` (Refino-hosted sites get
+ * one generated for them) whose two methods resolve with whatever JSON the
+ * update service answered. Everything is validated here, in the package,
+ * rather than in the generated transport, so the generated code can stay a
+ * thin pipe that rarely needs to change, and an answer this version does not
+ * understand reads as "nothing to offer" rather than as an error.
+ */
+export type UpdateUrgency = "optional" | "recommended" | "required";
+export type IntegrationUpdateStatus = {
+    readonly state: "current";
+} | {
+    readonly state: "available";
+    /** The version the update installs. */
+    readonly version: string;
+    readonly urgency: UpdateUrgency;
+    /** Plain-language highlights of the release, possibly none. */
+    readonly summary: readonly string[];
+    /** False when the update needs a developer; `message` then says so in plain words. */
+    readonly automatic: boolean;
+    readonly message: string | null;
+};
+export type IntegrationUpdateResult = {
+    readonly ok: true;
+    readonly version: string;
+} | {
+    readonly ok: false;
+    readonly code: string;
+    readonly message: string;
+    /**
+     * Whether the repository was left exactly as it was. False only when
+     * the request's outcome is unknown (the connection dropped while it
+     * ran), never after a refusal.
+     */
+    readonly unchanged: boolean;
+};
+export interface IntegrationUpdateSource {
+    /** Resolve with the update service's JSON body for "is there an update?". */
+    check(): Promise<unknown>;
+    /** Resolve with the update service's JSON body for "install `version` now". */
+    apply(version: string): Promise<unknown>;
+}
+/** `{ ok: true, update: {...} }` → a status. Anything unexpected is "current": no noise. */
+export declare function readUpdateStatus(body: unknown): IntegrationUpdateStatus;
+/** `{ ok: true, result: { status: "updated", version } }` or `{ ok: false, error }` → a result. */
+export declare function readUpdateResult(body: unknown, requested: string): IntegrationUpdateResult;

package/dist/updates.js

@@ -0,0 +1,52 @@
+/**
+ * Updating the site's Refino integration from the editor.
+ *
+ * The editor knows nothing about where updates come from. A host that can
+ * update itself passes an `IntegrationUpdateSource` (Refino-hosted sites get
+ * one generated for them) whose two methods resolve with whatever JSON the
+ * update service answered. Everything is validated here, in the package,
+ * rather than in the generated transport, so the generated code can stay a
+ * thin pipe that rarely needs to change, and an answer this version does not
+ * understand reads as "nothing to offer" rather than as an error.
+ */
+const CURRENT = { state: "current" };
+const VERSION = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+const MAX_TEXT = 300;
+function record(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value) ? value : null;
+}
+function text(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value.trim().slice(0, MAX_TEXT) : null;
+}
+/** `{ ok: true, update: {...} }` → a status. Anything unexpected is "current": no noise. */
+export function readUpdateStatus(body) {
+    const update = record(record(body)?.ok === true ? record(body).update : null);
+    if (!update || update.state !== "available")
+        return CURRENT;
+    const version = typeof update.version === "string" && VERSION.test(update.version) ? update.version : null;
+    if (!version)
+        return CURRENT;
+    const urgency = update.urgency === "recommended" || update.urgency === "required" ? update.urgency : "optional";
+    const summary = Array.isArray(update.summary) ? update.summary.map(text).filter((line) => line !== null).slice(0, 5) : [];
+    const automatic = update.automatic === true;
+    return { state: "available", version, urgency, summary, automatic, message: automatic ? null : text(update.message) };
+}
+const GENERIC_FAILURE = "Refino could not update this site.";
+const UNKNOWN_OUTCOME = "Refino could not confirm whether the update finished.";
+/** `{ ok: true, result: { status: "updated", version } }` or `{ ok: false, error }` → a result. */
+export function readUpdateResult(body, requested) {
+    const value = record(body);
+    const result = record(value?.ok === true ? value.result : null);
+    if (result && (result.status === "updated" || result.status === "current")) {
+        const version = typeof result.version === "string" && VERSION.test(result.version) ? result.version : requested;
+        return { ok: true, version };
+    }
+    const error = record(value?.error);
+    const code = typeof error?.code === "string" ? error.code : "UNEXPECTED";
+    // "Nothing was changed" is only ever said when the service says so. A
+    // dropped connection, a proxy error page or an answer this version cannot
+    // read leaves the outcome unknown, and the owner is told exactly that.
+    const unchanged = error?.repositoryUnchanged === true;
+    const message = text(error?.message) ?? (unchanged ? GENERIC_FAILURE : UNKNOWN_OUTCOME);
+    return { ok: false, code, message, unchanged };
+}

package/dist/useCopyEditor.d.ts

@@ -1,11 +1,18 @@
 import type { ContentId } from "@getrefino/core";
-import type { CopyEditorState } from "./store.js";
+import type { ArticleState, CopyEditorState, EditorPanel } from "./store.js";
+import type { IntegrationUpdateSource } from "./updates.js";
 export interface CopyEditor {
     readonly state: CopyEditorState;
     readonly dirtyIds: readonly ContentId[];
     readonly isDirty: boolean;
     /** Login page to offer when the endpoint reports the session ended. */
     readonly signInHref: string;
+    /** The provider's update source, if the host offers integration updates. */
+    readonly updates: IntegrationUpdateSource | undefined;
+    /** Articles on this page, in the order the host declared them. Empty on a page without one. */
+    readonly articles: readonly ArticleState[];
+    openPanel(panel: EditorPanel): void;
+    closePanel(): void;
     save(): Promise<void>;
     revertValue(id: ContentId): void;
     revertAll(): void;

package/dist/useCopyEditor.js

@@ -7,9 +7,10 @@ import { useCopyEditorState, useCopyStoreOrThrow } from "./context.js";
  * the default toolbar does not fit the host site.
  */
 export function useCopyEditor() {
-    const { store, onExit, signInHref } = useCopyStoreOrThrow();
+    const { store, onExit, signInHref, updates } = useCopyStoreOrThrow();
     const state = useCopyEditorState(store);
     const dirtyIds = useMemo(() => getDirtyIds(state.draft), [state.draft]);
+    const articles = useMemo(() => state.documentIds.map((id) => state.documents[id]).filter((article) => article !== undefined), [state.documentIds, state.documents]);
     const exit = useCallback(async () => {
         const count = getDirtyIds(store.getState().draft).length;
         if (count > 0 && typeof window !== "undefined") {
@@ -24,11 +25,15 @@ export function useCopyEditor() {
         dirtyIds,
         isDirty: dirtyIds.length > 0,
         signInHref,
+        updates,
+        articles,
+        openPanel: store.openPanel,
+        closePanel: store.closePanel,
         save: store.save,
         revertValue: store.revertValue,
         revertAll: store.revertAll,
         reloadLatest: store.reloadLatest,
         dismissError: store.dismissError,
         exit,
-    }), [state, dirtyIds, store, exit, signInHref]);
+    }), [state, dirtyIds, store, exit, signInHref, updates, articles]);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getrefino/react",
-  "version": "0.1.0-rc.4",
+  "version": "0.1.0-rc.6",
   "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.4"
+    "@getrefino/core": "0.1.0-rc.6"
   },
   "peerDependencies": {
     "react": "^18.2.0 || ^19.0.0",