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

package/dist/ArticleBody.d.ts

@@ -0,0 +1,27 @@
+import type { AllHTMLAttributes, JSX, ReactNode } from "react";
+export type ArticleBodyElement = keyof JSX.IntrinsicElements;
+export interface ArticleBodyProps extends Omit<AllHTMLAttributes<HTMLElement>, "id" | "as" | "children" | "contentEditable" | "dangerouslySetInnerHTML"> {
+    /** The body field's id, e.g. `blog.hello-world.body`. */
+    id: string;
+    /** Element to render. Defaults to `div`; use the element the article already had. */
+    as?: ArticleBodyElement | undefined;
+    /** DOM `id` attribute, since `id` is taken by the field id. */
+    htmlId?: string | undefined;
+    /** The article as the site renders it. Untouched in both modes. */
+    children?: ReactNode | undefined;
+}
+/**
+ * Marks the rendered article body as editable.
+ *
+ * In normal mode this is exactly the element the site already had, with the
+ * site's own rendered Markdown or MDX inside it: no wrapper, no attributes,
+ * no editor code path. In edit mode the same element gains an outline and a
+ * button that opens the source editor for the body.
+ *
+ * A body is not a sentence, so it deliberately does not become
+ * contentEditable the way `EditableText` does. Editing raw Markdown or MDX
+ * in place — next to JSX, imports and fenced code the renderer has already
+ * consumed — would be a different document from the one the reader sees.
+ * The panel edits the source; the page keeps rendering the article.
+ */
+export declare function ArticleBody(props: ArticleBodyProps): JSX.Element;

package/dist/ArticleBody.js

@@ -0,0 +1,50 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { splitDocumentFieldId } from "@getrefino/core";
+import { createElement, useCallback, useSyncExternalStore } from "react";
+import { useCopyContext } from "./context.js";
+/**
+ * Marks the rendered article body as editable.
+ *
+ * In normal mode this is exactly the element the site already had, with the
+ * site's own rendered Markdown or MDX inside it: no wrapper, no attributes,
+ * no editor code path. In edit mode the same element gains an outline and a
+ * button that opens the source editor for the body.
+ *
+ * A body is not a sentence, so it deliberately does not become
+ * contentEditable the way `EditableText` does. Editing raw Markdown or MDX
+ * in place — next to JSX, imports and fenced code the renderer has already
+ * consumed — would be a different document from the one the reader sees.
+ * The panel edits the source; the page keeps rendering the article.
+ */
+export function ArticleBody(props) {
+    const { id, as = "div", htmlId, children, ...rest } = props;
+    const context = useCopyContext();
+    const store = context?.store ?? null;
+    const subscribe = store ? store.subscribe : noopSubscribe;
+    const editing = useSyncExternalStore(subscribe, () => store?.getState().editing ?? false, () => false);
+    if (!store || !editing) {
+        return createElement(as, { ...rest, id: htmlId }, children);
+    }
+    return (_jsx(EditableArticleBody, { id: id, as: as, htmlId: htmlId, rest: rest, store: store, children: children }));
+}
+function noopSubscribe() {
+    return () => { };
+}
+function EditableArticleBody({ id, as, htmlId, rest, store, children }) {
+    const documentId = useSyncExternalStore(store.subscribe, () => splitDocumentFieldId(store.getState().documentIds, id)?.documentId ?? null, () => null);
+    const dirty = useSyncExternalStore(store.subscribe, () => store.isDirty(id), () => false);
+    const open = useCallback(() => {
+        if (documentId)
+            store.openPanel({ kind: "body", documentId });
+    }, [documentId, store]);
+    if (!documentId) {
+        return createElement(as, { ...rest, id: htmlId }, children);
+    }
+    return createElement(as, {
+        ...rest,
+        id: htmlId,
+        "data-refino-body": id,
+        "data-refino-state": dirty ? "dirty" : "idle",
+    }, _jsx("button", { type: "button", className: "refino-body__edit", onClick: open, children: dirty ? "Edit article body — unsaved" : "Edit article body" }), children);
+}

package/dist/ArticlePanel.d.ts

@@ -0,0 +1,7 @@
+import type { JSX } from "react";
+/**
+ * The two editing surfaces that are not the rendered page: the article's
+ * metadata, and the article's source body. Rendered once by the provider,
+ * over the page, and only while edit mode is on.
+ */
+export declare function ArticlePanel(): JSX.Element | null;

package/dist/ArticlePanel.js

@@ -0,0 +1,93 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { BODY_FIELD_ID, META_FIELD_PREFIX, documentFieldId } from "@getrefino/core";
+import { useCallback, useEffect, useRef, useSyncExternalStore } from "react";
+import { useCopyEditorState, useCopyStoreOrThrow } from "./context.js";
+const LABELS = {
+    title: "Title",
+    subtitle: "Subtitle",
+    excerpt: "Excerpt",
+    description: "Description",
+    seoTitle: "SEO title",
+    seoDescription: "SEO description",
+    author: "Author",
+    date: "Date",
+    ctaLabel: "CTA label",
+    ctaText: "CTA text",
+};
+/** Fields that are usually a sentence or two rather than a line. */
+const MULTILINE = new Set(["excerpt", "description", "seoDescription"]);
+function fieldName(field) {
+    return field.id.startsWith(META_FIELD_PREFIX) ? field.id.slice(META_FIELD_PREFIX.length) : field.id;
+}
+function labelFor(field) {
+    const name = fieldName(field);
+    return LABELS[name] ?? name.replace(/([a-z])([A-Z])/g, "$1 $2").replace(/^./, (char) => char.toUpperCase());
+}
+/**
+ * The two editing surfaces that are not the rendered page: the article's
+ * metadata, and the article's source body. Rendered once by the provider,
+ * over the page, and only while edit mode is on.
+ */
+export function ArticlePanel() {
+    const { store } = useCopyStoreOrThrow();
+    const state = useCopyEditorState(store);
+    const panel = state.panel;
+    const article = panel ? state.documents[panel.documentId] : undefined;
+    const close = useCallback(() => store.closePanel(), [store]);
+    useEffect(() => {
+        if (!panel || typeof window === "undefined")
+            return;
+        const onKeyDown = (event) => {
+            if (event.key === "Escape") {
+                event.stopPropagation();
+                store.closePanel();
+            }
+        };
+        window.addEventListener("keydown", onKeyDown, true);
+        return () => window.removeEventListener("keydown", onKeyDown, true);
+    }, [panel, store]);
+    if (!panel || !article)
+        return null;
+    const heading = panel.kind === "body" ? "Article body" : "Article metadata";
+    return (_jsxs("div", { className: "refino-panel", role: "dialog", "aria-modal": "false", "aria-label": heading, children: [_jsxs("div", { className: "refino-panel__head", children: [_jsxs("div", { children: [_jsx("strong", { className: "refino-panel__title", children: heading }), article.path && (_jsx("span", { className: "refino-panel__path", title: article.path, children: article.path }))] }), _jsx("button", { type: "button", className: "refino-panel__close", onClick: close, children: "Done" })] }), panel.kind === "body" ? _jsx(BodyEditor, { article: article }) : _jsx(MetadataEditor, { article: article })] }));
+}
+/** One field of the draft, subscribed to on its own so typing re-renders one input. */
+function useField(id) {
+    const { store } = useCopyStoreOrThrow();
+    const value = useSyncExternalStore(store.subscribe, () => store.getValue(id) ?? "", () => store.getValue(id) ?? "");
+    const dirty = useSyncExternalStore(store.subscribe, () => store.isDirty(id), () => false);
+    return { value, dirty };
+}
+function BodyEditor({ article }) {
+    const { store } = useCopyStoreOrThrow();
+    const id = documentFieldId(article.documentId, BODY_FIELD_ID);
+    const { value, dirty } = useField(id);
+    const field = article.fields.find((candidate) => candidate.id === BODY_FIELD_ID);
+    const textarea = useRef(null);
+    useEffect(() => {
+        textarea.current?.focus();
+    }, []);
+    if (field && !field.editable) {
+        return (_jsx("div", { className: "refino-panel__body", children: _jsxs("p", { className: "refino-panel__notice", role: "alert", children: ["Refino cannot edit this article\u2019s body: ", field.reason, ". Nothing has been changed."] }) }));
+    }
+    return (_jsxs("div", { className: "refino-panel__body", children: [_jsxs("p", { className: "refino-panel__hint", children: ["This is the article\u2019s ", article.sourceType === "mdx" ? "MDX" : "Markdown", " source, exactly as it is in", " ", article.path ?? "the repository", ". Components, imports, expressions and code fences are saved back unchanged; edit the prose around them."] }), _jsx("textarea", { ref: textarea, className: "refino-panel__source", spellCheck: false, value: value, "aria-label": "Article source", onChange: (event) => store.setValue(id, event.target.value) }), _jsxs("div", { className: "refino-panel__actions", children: [_jsx("span", { className: "refino-panel__state", children: dirty ? "This body has unsaved changes" : "This body is unchanged" }), _jsx("button", { type: "button", className: "refino-toolbar__button", onClick: () => store.revertValue(id), disabled: !dirty, children: "Revert body" })] })] }));
+}
+function MetadataEditor({ article }) {
+    const { store } = useCopyStoreOrThrow();
+    const fields = article.fields.filter((field) => field.id !== BODY_FIELD_ID);
+    if (fields.length === 0) {
+        return (_jsx("div", { className: "refino-panel__body", children: _jsxs("p", { className: "refino-panel__notice", children: ["Refino found no metadata it recognizes in this article\u2019s frontmatter. Map the fields you want in the ", _jsx("code", { children: "content" }), " block of ", _jsx("code", { children: "refino.config.json" }), "."] }) }));
+    }
+    return (_jsxs("div", { className: "refino-panel__body", children: [_jsx("div", { className: "refino-panel__fields", children: fields.map((field) => (_jsx(MetadataField, { article: article, field: field }, field.id))) }), _jsxs("div", { className: "refino-panel__actions", children: [_jsx("span", { className: "refino-panel__state", children: "Every other frontmatter key in this file is left exactly as it is." }), _jsx("button", { type: "button", className: "refino-toolbar__button", onClick: () => {
+                            for (const field of fields)
+                                store.revertValue(documentFieldId(article.documentId, field.id));
+                        }, children: "Revert metadata" })] })] }));
+}
+function MetadataField({ article, field }) {
+    const { store } = useCopyStoreOrThrow();
+    const id = documentFieldId(article.documentId, field.id);
+    const { value, dirty } = useField(id);
+    const name = fieldName(field);
+    return (_jsxs("label", { className: "refino-panel__field", "data-refino-state": dirty ? "dirty" : "idle", children: [_jsxs("span", { className: "refino-panel__label", children: [labelFor(field), field.key && _jsx("code", { className: "refino-panel__key", children: field.key })] }), MULTILINE.has(name) ? (_jsx("textarea", { className: "refino-panel__input refino-panel__input--multiline", value: value, disabled: !field.editable, onChange: (event) => store.setValue(id, event.target.value) })) : (_jsx("input", { type: "text", className: "refino-panel__input", value: value, disabled: !field.editable, onChange: (event) => store.setValue(id, event.target.value) })), !field.editable && _jsxs("span", { className: "refino-panel__reason", children: ["Read-only: ", field.reason, "."] })] }));
+}

package/dist/RefinoArticle.d.ts

@@ -0,0 +1,37 @@
+import type { FieldId } from "@getrefino/core";
+import type { JSX } from "react";
+export interface RefinoArticleProps {
+    /**
+     * The article's id, e.g. `blog.hello-world`. Produced by
+     * `documentIdForPath` in `@getrefino/core/documents` from the source path
+     * the page already knows. A path is never sent to the server.
+     */
+    documentId: string;
+    /**
+     * The field values this page rendered the article with, e.g.
+     * `{ "meta.title": post.title, body: post.body }`. Edit mode shows these
+     * until the canonical version has loaded, and keeps them for fields
+     * Refino can read but not write.
+     */
+    fields: Readonly<Record<FieldId, string>>;
+}
+/**
+ * Declares that this page renders an article, so the editor can load it,
+ * hold a draft of it and save it.
+ *
+ * It renders nothing. Put it in the article page, wherever is convenient —
+ * the provider usually lives in the root layout, which cannot know which
+ * article a route is showing, and this is how the page tells it.
+ *
+ * Registration happens on mount, which is after the server rendered the
+ * page, so give each `EditableText` for an article field the page's own
+ * value as its child:
+ *
+ * ```tsx
+ * <EditableText id={`${documentId}.meta.title`} as="h1">{fields["meta.title"]}</EditableText>
+ * ```
+ *
+ * The server-rendered HTML is then already correct, and the editor replaces
+ * it with the canonical value once it has loaded. Both are the same file.
+ */
+export declare function RefinoArticle({ documentId, fields }: RefinoArticleProps): JSX.Element | null;

package/dist/RefinoArticle.js

@@ -0,0 +1,43 @@
+"use client";
+import { useEffect, useMemo } from "react";
+import { useCopyContext } from "./context.js";
+/**
+ * Declares that this page renders an article, so the editor can load it,
+ * hold a draft of it and save it.
+ *
+ * It renders nothing. Put it in the article page, wherever is convenient —
+ * the provider usually lives in the root layout, which cannot know which
+ * article a route is showing, and this is how the page tells it.
+ *
+ * Registration happens on mount, which is after the server rendered the
+ * page, so give each `EditableText` for an article field the page's own
+ * value as its child:
+ *
+ * ```tsx
+ * <EditableText id={`${documentId}.meta.title`} as="h1">{fields["meta.title"]}</EditableText>
+ * ```
+ *
+ * The server-rendered HTML is then already correct, and the editor replaces
+ * it with the canonical value once it has loaded. Both are the same file.
+ */
+export function RefinoArticle({ documentId, fields }) {
+    const context = useCopyContext();
+    const store = context?.store ?? null;
+    // Registration is by value: a client-side navigation to another article
+    // re-registers, and a re-render with the same values does nothing.
+    const signature = useMemo(() => JSON.stringify([
+        documentId,
+        Object.keys(fields)
+            .sort()
+            .map((key) => [key, fields[key]]),
+    ]), [documentId, fields]);
+    useEffect(() => {
+        if (!store)
+            return;
+        store.addDocument({ documentId, fields });
+        return () => store.removeDocument(documentId);
+        // `signature` stands in for `fields`, which is a fresh object every render.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [store, documentId, signature]);
+    return null;
+}

package/dist/RefinoProvider.d.ts

@@ -2,6 +2,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";
+import type { IntegrationUpdateSource } from "./updates.js";
 export interface RefinoProviderProps {
     /** The canonical copy, usually `import copy from "./content/copy.json"`. */
     content: CopyContent;
@@ -32,6 +33,13 @@ export interface RefinoProviderProps {
      * sites get a sink that posts to Refino; everyone else gets silence.
      */
     onEvent?: EditorEventSink | undefined;
+    /**
+     * Lets the toolbar offer updates to the site's Refino integration. Asked
+     * once per editing session; nothing in the repository changes unless the
+     * owner presses "Update Refino". Refino-connected sites get this from
+     * their generated client; everyone else leaves it out and sees nothing.
+     */
+    updates?: IntegrationUpdateSource | 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,8 +1,9 @@
 "use client";
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import { getDirtyIds } from "@getrefino/core";
-import { useEffect, useMemo, useRef, useState } from "react";
+import { useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
 import { CopyContext } from "./context.js";
+import { ArticlePanel } from "./ArticlePanel.js";
 import { createCopyStore } from "./store.js";
 import { EDITOR_STYLES } from "./styles.js";
 import { CopyEditorToolbar } from "./Toolbar.js";
@@ -13,7 +14,7 @@ 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, onEvent, toolbar = true, children } = props;
+    const { content, editing = false, endpoint = "/api/copy", headers, signInHref = "/edit", onExit, onEvent, updates, 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.
@@ -26,11 +27,27 @@ export function RefinoProvider(props) {
     useEffect(() => {
         store.setBaseContent(content);
     }, [content, store]);
+    /**
+     * Load the canonical copy once per editing session, and again when the
+     * articles on the page change (a client-side navigation to another post).
+     *
+     * Articles register from `<RefinoArticle>`, whose effect runs before this
+     * one on mount, so the first request already names them and the page is
+     * loaded in one round trip rather than two.
+     */
+    const documentKey = useSyncExternalStore(store.subscribe, () => store.getState().documentIds.join(","), () => "");
+    const loadedKey = useRef(null);
     useEffect(() => {
-        if (!editing)
+        if (!editing) {
+            loadedKey.current = null;
             return;
+        }
+        const key = store.getState().documentIds.join(",");
+        if (loadedKey.current === key)
+            return;
+        loadedKey.current = key;
         void store.load();
-    }, [editing, store]);
+    }, [editing, store, documentKey]);
     useEffect(() => {
         if (!editing || typeof window === "undefined")
             return;
@@ -53,6 +70,6 @@ export function RefinoProvider(props) {
             window.removeEventListener("keydown", onKeyDown);
         };
     }, [editing, store]);
-    const value = useMemo(() => ({ store, onExit, signInHref }), [store, onExit, signInHref]);
-    return (_jsxs(CopyContext.Provider, { value: value, children: [children, editing && (_jsxs(_Fragment, { children: [_jsx("style", { "data-refino-styles": "", children: EDITOR_STYLES }), toolbar && _jsx(CopyEditorToolbar, {})] }))] }));
+    const value = useMemo(() => ({ store, onExit, signInHref, updates }), [store, onExit, signInHref, updates]);
+    return (_jsxs(CopyContext.Provider, { value: value, children: [children, editing && (_jsxs(_Fragment, { children: [_jsx("style", { "data-refino-styles": "", children: EDITOR_STYLES }), _jsx(ArticlePanel, {}), toolbar && _jsx(CopyEditorToolbar, {})] }))] }));
 }

package/dist/Toolbar.js

@@ -1,7 +1,8 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-import { useCallback } from "react";
+import { useCallback, useRef } from "react";
 import { INSTRUCTIONS_ID } from "./dom.js";
+import { UpdateButton, UpdatePanel, useIntegrationUpdate } from "./UpdateNotice.js";
 import { useCopyEditor } from "./useCopyEditor.js";
 function plural(count, word) {
     return `${count} ${word}${count === 1 ? "" : "s"}`;
@@ -14,10 +15,15 @@ function plural(count, word) {
  */
 export function CopyEditorToolbar() {
     const editor = useCopyEditor();
-    const { state, dirtyIds } = editor;
+    const { state, dirtyIds, articles } = editor;
+    // V1 edits the article the page is showing. A page with several is
+    // supported by the model; the toolbar simply offers the first.
+    const article = articles[0];
     const dirtyCount = dirtyIds.length;
     const activeDirty = state.activeId !== null && dirtyIds.includes(state.activeId);
     const busy = state.status === "saving" || state.status === "loading";
+    const update = useIntegrationUpdate(editor.updates, state.loaded);
+    const updateButtonRef = useRef(null);
     const onRevertSelected = useCallback(() => {
         if (state.activeId)
             editor.revertValue(state.activeId);
@@ -50,5 +56,7 @@ export function CopyEditorToolbar() {
             statusText = dirtyCount > 0 ? `${plural(dirtyCount, "unsaved change")}` : "No changes";
             dotClass = dirtyCount > 0 ? "dirty" : "";
     }
-    return (_jsxs("div", { className: "refino-toolbar", role: "region", "aria-label": "Copy editor", children: [_jsx("p", { id: INSTRUCTIONS_ID, className: "refino-sr-only", children: "Editable text. Type to change it. Press Enter to finish or Escape to cancel this edit." }), state.status === "conflict" && (_jsxs("div", { className: "refino-toolbar__notice refino-toolbar__notice--conflict", role: "alert", children: [_jsx("p", { children: "The copy file changed in the repository while you were editing (an AI agent or developer probably pushed). Your edits were not saved and nothing was overwritten." }), _jsxs("p", { children: ["Reload the latest copy and your ", plural(dirtyCount, "unsaved edit"), " will be reapplied on top of it for you to review and save again."] })] })), state.status === "error" && state.error && (_jsxs("div", { className: "refino-toolbar__notice refino-toolbar__notice--error", role: "alert", children: [_jsx("p", { children: state.error.message }), _jsxs("p", { children: [_jsx("code", { children: state.error.code }), state.error.code === "UNAUTHORIZED" && (_jsxs(_Fragment, { children: [" ", _jsx("a", { className: "refino-toolbar__link", href: editor.signInHref, children: "Sign in again" })] }))] })] })), state.rebase && (_jsxs("div", { className: "refino-toolbar__notice", role: "status", children: [state.rebase.overlapping.length > 0 && (_jsxs("p", { children: ["Both you and the repository changed:", " ", state.rebase.overlapping.map((id, index) => (_jsxs("span", { children: [index > 0 ? ", " : "", _jsx("code", { children: id })] }, id))), ". Your wording is shown; review before saving."] })), state.rebase.dropped.length > 0 && (_jsxs("p", { children: ["Dropped edits for fields that no longer exist:", " ", state.rebase.dropped.map((id, index) => (_jsxs("span", { children: [index > 0 ? ", " : "", _jsx("code", { children: id })] }, id))), "."] }))] })), _jsxs("div", { className: "refino-toolbar__bar", role: "toolbar", "aria-label": "Copy editor controls", children: [_jsxs("span", { className: "refino-toolbar__status", "aria-live": "polite", children: [_jsx("span", { className: `refino-toolbar__dot${dotClass ? ` refino-toolbar__dot--${dotClass}` : ""}` }), statusText, state.status === "saved" && state.lastSave?.commitUrl && (_jsxs(_Fragment, { children: [" ", _jsx("a", { className: "refino-toolbar__link", href: state.lastSave.commitUrl, target: "_blank", rel: "noreferrer", children: "view commit" })] }))] }), state.activeId && (_jsx("span", { className: "refino-toolbar__key", title: state.activeId, children: state.activeId })), state.status === "conflict" ? (_jsx("button", { type: "button", className: "refino-toolbar__button refino-toolbar__button--primary", onClick: () => void editor.reloadLatest(), children: "Reload latest" })) : (_jsxs(_Fragment, { children: [_jsx("button", { type: "button", className: "refino-toolbar__button", onMouseDown: (event) => event.preventDefault(), onClick: onRevertSelected, disabled: !activeDirty || busy, title: "Revert the selected text to its saved value", children: "Revert" }), _jsx("button", { type: "button", className: "refino-toolbar__button", onClick: editor.revertAll, disabled: dirtyCount === 0 || busy, title: "Discard all unsaved changes", children: "Revert all" }), _jsx("button", { type: "button", className: "refino-toolbar__button refino-toolbar__button--primary", onClick: () => void editor.save(), disabled: dirtyCount === 0 || busy || !state.loaded, title: "Save all changes (Ctrl/Cmd+S)", children: state.status === "saving" ? "Saving…" : "Save" })] })), _jsx("button", { type: "button", className: "refino-toolbar__button", onClick: () => void editor.exit(), disabled: busy, children: "Exit" })] })] }));
+    return (_jsxs("div", { className: "refino-toolbar", role: "region", "aria-label": "Copy editor", children: [_jsx("p", { id: INSTRUCTIONS_ID, className: "refino-sr-only", children: "Editable text. Type to change it. Press Enter to finish or Escape to cancel this edit." }), _jsx(UpdatePanel, { control: update, saving: state.status === "saving", buttonRef: updateButtonRef }), state.status === "conflict" && (_jsxs("div", { className: "refino-toolbar__notice refino-toolbar__notice--conflict", role: "alert", children: [_jsx("p", { children: "The copy file changed in the repository while you were editing (an AI agent or developer probably pushed). Your edits were not saved and nothing was overwritten." }), _jsxs("p", { children: ["Reload the latest copy and your ", plural(dirtyCount, "unsaved edit"), " will be reapplied on top of it for you to review and save again."] })] })), state.status === "error" && state.error && (_jsxs("div", { className: "refino-toolbar__notice refino-toolbar__notice--error", role: "alert", children: [_jsx("p", { children: state.error.message }), _jsxs("p", { children: [_jsx("code", { children: state.error.code }), state.error.code === "UNAUTHORIZED" && (_jsxs(_Fragment, { children: [" ", _jsx("a", { className: "refino-toolbar__link", href: editor.signInHref, children: "Sign in again" })] }))] })] })), state.rebase && (_jsxs("div", { className: "refino-toolbar__notice", role: "status", children: [state.rebase.overlapping.length > 0 && (_jsxs("p", { children: ["Both you and the repository changed:", " ", state.rebase.overlapping.map((id, index) => (_jsxs("span", { children: [index > 0 ? ", " : "", _jsx("code", { children: id })] }, id))), ". Your wording is shown; review before saving."] })), state.rebase.dropped.length > 0 && (_jsxs("p", { children: ["Dropped edits for fields that no longer exist:", " ", state.rebase.dropped.map((id, index) => (_jsxs("span", { children: [index > 0 ? ", " : "", _jsx("code", { children: id })] }, id))), "."] }))] })), _jsxs("div", { className: "refino-toolbar__bar", role: "toolbar", "aria-label": "Copy editor controls", children: [_jsxs("span", { className: "refino-toolbar__status", "aria-live": "polite", children: [_jsx("span", { className: `refino-toolbar__dot${dotClass ? ` refino-toolbar__dot--${dotClass}` : ""}` }), statusText, state.status === "saved" && state.lastSave?.commitUrl && (_jsxs(_Fragment, { children: [" ", _jsx("a", { className: "refino-toolbar__link", href: state.lastSave.commitUrl, target: "_blank", rel: "noreferrer", children: "view commit" })] }))] }), article && state.status !== "conflict" && (_jsx("button", { type: "button", className: "refino-toolbar__button", onClick: () => state.panel?.kind === "metadata"
+                            ? editor.closePanel()
+                            : editor.openPanel({ kind: "metadata", documentId: article.documentId }), "aria-pressed": state.panel?.kind === "metadata", title: "Edit this article's title, excerpt, SEO fields and dates", children: "Article metadata" })), state.activeId && (_jsx("span", { className: "refino-toolbar__key", title: state.activeId, children: state.activeId })), state.status === "conflict" ? (_jsx("button", { type: "button", className: "refino-toolbar__button refino-toolbar__button--primary", onClick: () => void editor.reloadLatest(), children: "Reload latest" })) : (_jsxs(_Fragment, { children: [_jsx("button", { type: "button", className: "refino-toolbar__button", onMouseDown: (event) => event.preventDefault(), onClick: onRevertSelected, disabled: !activeDirty || busy, title: "Revert the selected text to its saved value", children: "Revert" }), _jsx("button", { type: "button", className: "refino-toolbar__button", onClick: editor.revertAll, disabled: dirtyCount === 0 || busy, title: "Discard all unsaved changes", children: "Revert all" }), _jsx("button", { type: "button", className: "refino-toolbar__button refino-toolbar__button--primary", onClick: () => void editor.save(), disabled: dirtyCount === 0 || busy || !state.loaded, title: "Save all changes (Ctrl/Cmd+S)", children: state.status === "saving" ? "Saving…" : "Save" })] })), _jsx(UpdateButton, { control: update, buttonRef: updateButtonRef }), _jsx("button", { type: "button", className: "refino-toolbar__button", onClick: () => void editor.exit(), disabled: busy, children: "Exit" })] })] }));
 }

package/dist/UpdateNotice.d.ts

@@ -0,0 +1,51 @@
+import type { JSX, RefObject } from "react";
+import type { IntegrationUpdateResult, IntegrationUpdateSource, IntegrationUpdateStatus } from "./updates.js";
+type Available = Extract<IntegrationUpdateStatus, {
+    state: "available";
+}>;
+export type UpdatePhase = {
+    readonly kind: "hidden";
+} | {
+    readonly kind: "available";
+    readonly update: Available;
+} | {
+    readonly kind: "updating";
+    readonly update: Available;
+} | {
+    readonly kind: "updated";
+    readonly version: string;
+} | {
+    readonly kind: "failed";
+    readonly update: Available;
+    readonly result: Extract<IntegrationUpdateResult, {
+        ok: false;
+    }>;
+};
+export interface IntegrationUpdateControl {
+    readonly phase: UpdatePhase;
+    readonly open: boolean;
+    setOpen(open: boolean): void;
+    /** Install the offered version. The only path to a repository change, and only ever from a click. */
+    apply(): Promise<void>;
+    /** Close the panel after a success or failure; a success also retires the toolbar control. */
+    close(): void;
+}
+/**
+ * Asks once per editing session, after the copy has loaded, whether the
+ * site's integration has an update, and runs the update when (and only
+ * when) the owner asks for it. No polling, no retries, no background work.
+ */
+export declare function useIntegrationUpdate(source: IntegrationUpdateSource | undefined, ready: boolean): IntegrationUpdateControl;
+/** The toolbar control: absent unless there is something to offer. */
+export declare function UpdateButton({ control, buttonRef }: {
+    control: IntegrationUpdateControl;
+    buttonRef: RefObject<HTMLButtonElement | null>;
+}): JSX.Element | null;
+/** The compact panel above the toolbar. */
+export declare function UpdatePanel({ control, saving, buttonRef, }: {
+    control: IntegrationUpdateControl;
+    /** A save is in flight; an update now would race it for the branch. */
+    saving: boolean;
+    buttonRef: RefObject<HTMLButtonElement | null>;
+}): JSX.Element | null;
+export {};

package/dist/UpdateNotice.js

@@ -0,0 +1,136 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useCallback, useEffect, useId, useRef, useState } from "react";
+import { readUpdateResult, readUpdateStatus } from "./updates.js";
+/**
+ * Asks once per editing session, after the copy has loaded, whether the
+ * site's integration has an update, and runs the update when (and only
+ * when) the owner asks for it. No polling, no retries, no background work.
+ */
+export function useIntegrationUpdate(source, ready) {
+    const [phase, setPhase] = useState({ kind: "hidden" });
+    const [open, setOpen] = useState(false);
+    const asked = useRef(false);
+    useEffect(() => {
+        if (!source || !ready || asked.current)
+            return;
+        asked.current = true;
+        // Whatever goes wrong while asking, the answer is "nothing to show".
+        void Promise.resolve()
+            .then(() => source.check())
+            .then(readUpdateStatus, () => ({ state: "current" }))
+            .then((status) => {
+            if (status.state === "available")
+                setPhase({ kind: "available", update: status });
+        });
+    }, [source, ready]);
+    const apply = useCallback(async () => {
+        if (!source || (phase.kind !== "available" && phase.kind !== "failed"))
+            return;
+        const update = phase.update;
+        if (!update.automatic)
+            return;
+        setPhase({ kind: "updating", update });
+        let result;
+        try {
+            result = readUpdateResult(await source.apply(update.version), update.version);
+        }
+        catch {
+            result = readUpdateResult(null, update.version);
+        }
+        setPhase(result.ok ? { kind: "updated", version: result.version } : { kind: "failed", update, result });
+    }, [phase, source]);
+    const close = useCallback(() => {
+        setOpen(false);
+        if (phase.kind === "updated")
+            setPhase({ kind: "hidden" });
+        else if (phase.kind === "failed")
+            setPhase({ kind: "available", update: phase.update });
+    }, [phase]);
+    return { phase, open, setOpen, apply, close };
+}
+function title(update) {
+    switch (update.urgency) {
+        case "required":
+            return "Refino update required";
+        case "recommended":
+            return "Refino update recommended";
+        default:
+            return "Refino update available";
+    }
+}
+function triggerLabel(phase) {
+    switch (phase.kind) {
+        case "available":
+        case "failed":
+            return phase.update.urgency === "required" ? "Update required" : phase.update.urgency === "recommended" ? "Update recommended" : "Update available";
+        case "updating":
+            return "Updating…";
+        case "updated":
+            return "Updated";
+        default:
+            return null;
+    }
+}
+/** The toolbar control: absent unless there is something to offer. */
+export function UpdateButton({ control, buttonRef }) {
+    const label = triggerLabel(control.phase);
+    if (!label)
+        return null;
+    return (_jsxs("button", { ref: buttonRef, type: "button", className: "refino-toolbar__button refino-toolbar__button--update", "aria-haspopup": "dialog", "aria-expanded": control.open, onClick: () => control.setOpen(!control.open), children: [_jsx("span", { className: "refino-toolbar__dot refino-toolbar__dot--update", "aria-hidden": "true" }), label] }));
+}
+/** The compact panel above the toolbar. */
+export function UpdatePanel({ control, saving, buttonRef, }) {
+    const { phase, open } = control;
+    const titleId = useId();
+    const focusRef = useRef(null);
+    const visible = open && phase.kind !== "hidden";
+    const dismiss = useCallback(() => {
+        if (phase.kind === "updating")
+            return;
+        control.close();
+        buttonRef.current?.focus();
+    }, [buttonRef, control, phase.kind]);
+    useEffect(() => {
+        if (visible)
+            focusRef.current?.focus();
+    }, [visible, phase.kind]);
+    if (!visible)
+        return null;
+    const onKeyDown = (event) => {
+        if (event.key === "Escape") {
+            event.stopPropagation();
+            dismiss();
+        }
+    };
+    let heading;
+    let body;
+    let actions;
+    switch (phase.kind) {
+        case "available": {
+            const { update } = phase;
+            heading = title(update);
+            body = (_jsxs(_Fragment, { children: [_jsxs("p", { children: ["Version ", update.version, " is available."] }), update.summary.length > 0 && (_jsx("ul", { className: "refino-update__summary", children: update.summary.map((line) => (_jsx("li", { children: line }, line))) })), update.automatic ? (_jsx("p", { className: "refino-update__note", children: "Your site redeploys with the update as usual. Your text and unsaved edits are not affected." })) : (_jsx("p", { className: "refino-update__note", children: update.message ?? "This update needs to be installed by whoever maintains your site's code." }))] }));
+            actions = update.automatic ? (_jsxs(_Fragment, { children: [_jsx("button", { ref: focusRef, type: "button", className: "refino-toolbar__button", onClick: dismiss, children: "Not now" }), _jsx("button", { type: "button", className: "refino-toolbar__button refino-toolbar__button--primary", onClick: () => void control.apply(), disabled: saving, title: saving ? "Wait for the save to finish" : undefined, children: "Update Refino" })] })) : (_jsx("button", { ref: focusRef, type: "button", className: "refino-toolbar__button", onClick: dismiss, children: "Close" }));
+            break;
+        }
+        case "updating":
+            heading = "Updating Refino…";
+            body = _jsx("p", { children: "This usually takes a few seconds. Keep this page open." });
+            actions = _jsx(_Fragment, {});
+            break;
+        case "updated":
+            heading = `Refino updated to ${phase.version}`;
+            body = _jsx("p", { children: "Your site is redeploying with the update, which can take a few minutes. You can keep editing in the meantime." });
+            actions = (_jsx("button", { ref: focusRef, type: "button", className: "refino-toolbar__button refino-toolbar__button--primary", onClick: dismiss, children: "Done" }));
+            break;
+        case "failed": {
+            const { result } = phase;
+            heading = result.unchanged ? "Refino was not updated" : "Update status unknown";
+            body = (_jsxs(_Fragment, { children: [_jsx("p", { children: result.message }), _jsx("p", { className: "refino-update__note", children: result.unchanged ? "Nothing on your site was changed." : "Reload this page in a minute to see whether the update went through." })] }));
+            actions = (_jsxs(_Fragment, { children: [_jsx("button", { ref: focusRef, type: "button", className: "refino-toolbar__button", onClick: dismiss, children: "Close" }), result.unchanged && (_jsx("button", { type: "button", className: "refino-toolbar__button refino-toolbar__button--primary", onClick: () => void control.apply(), disabled: saving, children: "Try again" }))] }));
+            break;
+        }
+    }
+    return (_jsxs("div", { className: "refino-toolbar__notice refino-update", role: "dialog", "aria-labelledby": titleId, onKeyDown: onKeyDown, children: [_jsx("p", { id: titleId, className: "refino-update__title", "aria-live": "polite", children: heading }), body, phase.kind !== "updating" && _jsx("div", { className: "refino-update__actions", children: actions })] }));
+}

package/dist/context.d.ts

@@ -1,9 +1,12 @@
 import type { CopyEditorState, CopyStore } from "./store.js";
+import type { IntegrationUpdateSource } from "./updates.js";
 export interface CopyContextValue {
     readonly store: CopyStore;
     readonly onExit: (() => void | Promise<void>) | undefined;
     /** Where to send the owner when the session has ended. */
     readonly signInHref: string;
+    /** Where the toolbar asks about, and installs, updates to the site's Refino integration. */
+    readonly updates: IntegrationUpdateSource | undefined;
 }
 export declare const CopyContext: import("react").Context<CopyContextValue | null>;
 export declare function useCopyContext(): CopyContextValue | null;

package/dist/index.d.ts

@@ -5,7 +5,13 @@ export type { EditableTextElement, EditableTextProps } from "./EditableText.js";
 export { CopyEditorToolbar } from "./Toolbar.js";
 export { useCopyEditor } from "./useCopyEditor.js";
 export type { CopyEditor } from "./useCopyEditor.js";
+export { ArticleBody } from "./ArticleBody.js";
+export type { ArticleBodyElement, ArticleBodyProps } from "./ArticleBody.js";
+export { RefinoArticle } from "./RefinoArticle.js";
+export type { RefinoArticleProps } from "./RefinoArticle.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 type { ArticleDocument, ArticleState, CopyEditorState, EditorPanel, CopyRequestHeaders, CopyStore, CopyStoreOptions, EditorError, EditorStatus, LastSave, RebaseInfo, } from "./store.js";
+export type { EditorEvent, EditorEventName, EditorEventProperties, EditorEventSink, EditorSurface, } from "./telemetry.js";
+export { readUpdateResult, readUpdateStatus } from "./updates.js";
+export type { IntegrationUpdateResult, IntegrationUpdateSource, IntegrationUpdateStatus, UpdateUrgency } from "./updates.js";
 export { EDITOR_STYLES } from "./styles.js";

package/dist/index.js

@@ -2,5 +2,8 @@ export { RefinoProvider } from "./RefinoProvider.js";
 export { EditableText } from "./EditableText.js";
 export { CopyEditorToolbar } from "./Toolbar.js";
 export { useCopyEditor } from "./useCopyEditor.js";
+export { ArticleBody } from "./ArticleBody.js";
+export { RefinoArticle } from "./RefinoArticle.js";
 export { createCopyStore } from "./store.js";
+export { readUpdateResult, readUpdateStatus } from "./updates.js";
 export { EDITOR_STYLES } from "./styles.js";