@rebasepro/admin 0.16.0 → 0.16.1-canary.g2d1aec8

package/src/collection_editor/ui/collection_editor/SchemaChangeDialog.tsx

@@ -0,0 +1,368 @@
+/**
+ * What a schema change would do, before it does it.
+ *
+ * The dialog exists because a schema change has three possible verdicts and two
+ * of them are refusals. Without a preview, the only way to discover that a
+ * change is refused is to press a button on a live database and read what comes
+ * back — which is a fine way to learn and a poor way to work.
+ *
+ * ## What it shows, in the order somebody reads it
+ *
+ * The verdict first, in a sentence, because it decides whether the rest is
+ * worth reading. Then the changes, each with what it does and — when it is
+ * refused — what to do instead. Then the things that are easy to skip past and
+ * expensive to have skipped: constraints the change asks for that the database
+ * will not end up enforcing. The SQL and the file list come last, collapsed,
+ * for the reader who wants them; they are the evidence, not the summary.
+ *
+ * ## Why the button says "Commit and apply"
+ *
+ * Because that is the order, and the order is the feature. The commit lands
+ * first, so a failed apply leaves the repository ahead of the database — the
+ * ordinary state of every project between an edit and a deploy, which the next
+ * boot reconciles. A button labelled "Save" would be describing a different,
+ * worse thing.
+ */
+import React, { useState } from "react";
+import {
+    Alert,
+    Button,
+    Chip,
+    CircularProgress,
+    cls,
+    Dialog,
+    DialogActions,
+    DialogContent,
+    DialogTitle,
+    Typography
+} from "@rebasepro/ui";
+
+import type { LiveSchemaPlan, LiveSchemaResult, WithheldConstraint } from "../../liveSchemaClient";
+
+export interface SchemaChangeDialogProps {
+    open: boolean;
+    /** The collection being changed, for the title. */
+    collectionId: string;
+    /** `undefined` while the plan is still being fetched. */
+    plan?: LiveSchemaPlan;
+    /** Set when planning itself failed — a network error, a refusal, a 500. */
+    planError?: string;
+    /** Set once the change has been applied, which turns this into a receipt. */
+    result?: LiveSchemaResult;
+    applying: boolean;
+    /** Set when the apply threw rather than returning a result. */
+    applyError?: string;
+    onConfirm: () => void;
+    /**
+     * Write the collection source and leave the database alone.
+     *
+     * Offered only when the change is refused, and it is what keeps the editor
+     * usable while it is. Removing a property is the ordinary case: the ensure
+     * path has no `DROP COLUMN`, so a removal can never be applied — and
+     * refusing the whole save over it would mean a dev could no longer delete a
+     * field from a collection they are still designing.
+     *
+     * This is exactly what the editor did before live editing existed, so it is
+     * not a new hazard; the difference is that it now says what it leaves
+     * behind instead of reporting success.
+     */
+    onSourceOnly?: () => void;
+    onClose: () => void;
+    /**
+     * Why this caller may preview but not apply, when that is the case.
+     *
+     * A person signed in with an API key, most often. Shown next to a disabled
+     * button so the refusal arrives while they are deciding rather than after
+     * they have decided.
+     */
+    applyRefusedBecause?: string;
+}
+
+type Verdict = LiveSchemaPlan["verdict"];
+
+/** What the verdict means, in the words the reader needs rather than the enum's. */
+const VERDICT_COPY: Record<Verdict, { title: string; body: string; color: "info" | "warning" | "error" }> = {
+    safe: {
+        title: "Ready to apply",
+        body: "Every change here can be made against the running database.",
+        color: "info"
+    },
+    diverges: {
+        title: "This would leave the database out of step",
+        body: "The change can be written, but the database will not end up matching it. " +
+            "The details below say which part, and what would make it applicable.",
+        color: "warning"
+    },
+    "needs-migration": {
+        title: "This needs a migration",
+        body: "Some of this cannot be done to a running database at all — it drops or rewrites " +
+            "something, and that belongs in a migration somebody has read.",
+        color: "error"
+    }
+};
+
+const VERDICT_CHIP: Record<Verdict, { label: string; scheme: "greenLighter" | "orangeLighter" | "redLighter" }> = {
+    safe: { label: "safe", scheme: "greenLighter" },
+    diverges: { label: "diverges", scheme: "orangeLighter" },
+    "needs-migration": { label: "needs migration", scheme: "redLighter" }
+};
+
+const monospace = "font-mono text-xs leading-relaxed";
+const codeBlock = cls(
+    monospace,
+    "bg-surface-100 dark:bg-surface-800 rounded-md p-3 overflow-x-auto whitespace-pre"
+);
+
+/** A disclosure that starts closed. The evidence, for the reader who wants it. */
+function Details({ summary, count, children }: {
+    summary: string;
+    count: number;
+    children: React.ReactNode;
+}) {
+    const [open, setOpen] = useState(false);
+    if (count === 0) return null;
+    return (
+        <div>
+            <button
+                type="button"
+                onClick={() => setOpen(o => !o)}
+                className="flex items-center gap-2 text-sm text-text-secondary dark:text-text-secondary-dark hover:underline"
+            >
+                <span className={cls("transition-transform", open && "rotate-90")}>›</span>
+                {summary} ({count})
+            </button>
+            {open && <div className="mt-2">{children}</div>}
+        </div>
+    );
+}
+
+function WithheldConstraints({ constraints }: { constraints: WithheldConstraint[] }) {
+    if (constraints.length === 0) return null;
+    return (
+        <Alert color="warning">
+            <Typography variant="body2" className="font-medium mb-1">
+                {constraints.length === 1
+                    ? "One constraint will not be enforced"
+                    : `${constraints.length} constraints will not be enforced`}
+            </Typography>
+            <ul className="space-y-2">
+                {constraints.map(constraint => (
+                    <li key={constraint.target} className="text-sm">
+                        <code className="bg-surface-200 dark:bg-surface-700 px-1 rounded">
+                            {constraint.target}
+                        </code>
+                        <div className="mt-1">{constraint.reason}</div>
+                        <div className="mt-1 text-text-secondary dark:text-text-secondary-dark">
+                            {constraint.remedy}
+                        </div>
+                    </li>
+                ))}
+            </ul>
+        </Alert>
+    );
+}
+
+/** The receipt. Shown in place of the plan once the change has been applied. */
+function Applied({ result }: { result: LiveSchemaResult }) {
+    return (
+        <div className="flex flex-col gap-4">
+            <Alert color={result.applied ? "success" : "warning"}>
+                <Typography variant="body2">{result.summary}</Typography>
+            </Alert>
+
+            {!result.applied && result.applyError && (
+                // Deliberately not an error state. The commit landed, which is
+                // the durable half; the database is now behind the repository,
+                // which is where every project sits between an edit and a
+                // deploy, and boot reconciles it.
+                <Alert color="warning">
+                    <Typography variant="body2" className="font-medium mb-1">
+                        The database was not changed
+                    </Typography>
+                    <Typography variant="body2">{result.applyError}</Typography>
+                    <Typography variant="body2" className="mt-2">
+                        The commit is on <code>{result.committed.branch}</code> either way, so the
+                        change will be applied on the next boot.
+                    </Typography>
+                </Alert>
+            )}
+
+            <WithheldConstraints constraints={result.withheldConstraints ?? []}/>
+
+            <div>
+                <Typography variant="label" color="secondary">Committed</Typography>
+                <div className={cls(codeBlock, "mt-1")}>
+                    {result.committed.sha.slice(0, 9)} on {result.committed.branch}
+                    {"\n"}
+                    {result.committed.files.map(file => `  ${file}`).join("\n")}
+                </div>
+            </div>
+        </div>
+    );
+}
+
+export function SchemaChangeDialog({
+    open,
+    collectionId,
+    plan,
+    planError,
+    result,
+    applying,
+    applyError,
+    onConfirm,
+    onSourceOnly,
+    onClose,
+    applyRefusedBecause
+}: SchemaChangeDialogProps) {
+
+    const verdict = plan?.verdict;
+    const copy = verdict ? VERDICT_COPY[verdict] : undefined;
+
+    return (
+        <Dialog open={open} onOpenChange={value => { if (!value) onClose(); }} maxWidth="3xl">
+            <DialogTitle className="flex items-center gap-2">
+                {result ? "Schema change applied" : "Review schema change"}
+                <code className="text-sm font-normal text-text-secondary dark:text-text-secondary-dark">
+                    {collectionId}
+                </code>
+            </DialogTitle>
+
+            <DialogContent className="flex flex-col gap-4">
+                {planError && (
+                    <Alert color="error">
+                        <Typography variant="body2" className="font-medium mb-1">
+                            The change could not be planned
+                        </Typography>
+                        <Typography variant="body2">{planError}</Typography>
+                    </Alert>
+                )}
+
+                {!plan && !planError && !result && (
+                    <div className="flex items-center gap-3 py-6">
+                        <CircularProgress size="small"/>
+                        <Typography variant="body2" color="secondary">
+                            Working out what this change would do…
+                        </Typography>
+                    </div>
+                )}
+
+                {result && <Applied result={result}/>}
+
+                {plan && !result && copy && (
+                    <>
+                        <Alert color={copy.color}>
+                            <Typography variant="body2" className="font-medium mb-1">
+                                {copy.title}
+                            </Typography>
+                            <Typography variant="body2">{copy.body}</Typography>
+                        </Alert>
+
+                        {applyError && (
+                            <Alert color="error">
+                                <Typography variant="body2">{applyError}</Typography>
+                            </Alert>
+                        )}
+
+                        {plan.changes.length === 0 && (
+                            <Typography variant="body2" color="secondary">
+                                Nothing about the database changes. The collection source is still
+                                rewritten and committed.
+                            </Typography>
+                        )}
+
+                        {!plan.applicable && onSourceOnly && (
+                            <Typography variant="body2" color="secondary">
+                                You can still write the change to your collection source and leave
+                                the database as it is — the editor’s behaviour before this preview
+                                existed. The column stays, holding whatever is in it, and nothing
+                                serves it.
+                            </Typography>
+                        )}
+
+                        {plan.changes.length > 0 && (
+                            <ul className="flex flex-col gap-3">
+                                {plan.changes.map((change, index) => (
+                                    <li
+                                        key={`${change.collection}.${change.property ?? ""}.${index}`}
+                                        className="flex gap-3"
+                                    >
+                                        <Chip
+                                            size="smallest"
+                                            colorScheme={VERDICT_CHIP[change.verdict].scheme}
+                                            className="shrink-0 mt-0.5"
+                                        >
+                                            {VERDICT_CHIP[change.verdict].label}
+                                        </Chip>
+                                        <div className="min-w-0">
+                                            <Typography variant="body2">{change.detail}</Typography>
+                                            {change.remedy && (
+                                                <Typography
+                                                    variant="body2"
+                                                    color="secondary"
+                                                    className="mt-1"
+                                                >
+                                                    {change.remedy}
+                                                </Typography>
+                                            )}
+                                        </div>
+                                    </li>
+                                ))}
+                            </ul>
+                        )}
+
+                        <WithheldConstraints constraints={plan.withheldConstraints ?? []}/>
+
+                        {applyRefusedBecause && (
+                            <Alert color="info">
+                                <Typography variant="body2" className="font-medium mb-1">
+                                    You can preview this change, but not apply it
+                                </Typography>
+                                <Typography variant="body2">{applyRefusedBecause}</Typography>
+                            </Alert>
+                        )}
+
+                        <Details summary="SQL that will run" count={plan.statements.length}>
+                            <div className={codeBlock}>{plan.statements.join("\n")}</div>
+                        </Details>
+
+                        <Details summary="Files that will be committed" count={plan.files.length}>
+                            <div className={codeBlock}>{plan.files.join("\n")}</div>
+                        </Details>
+
+                        <Details summary="Commit message" count={plan.message ? 1 : 0}>
+                            <div className={codeBlock}>{plan.message}</div>
+                        </Details>
+                    </>
+                )}
+            </DialogContent>
+
+            <DialogActions>
+                <Button variant="text" onClick={onClose} disabled={applying}>
+                    {result ? "Close" : "Cancel"}
+                </Button>
+                {!result && plan && !plan.applicable && onSourceOnly && (
+                    <Button variant="outlined" onClick={onSourceOnly} disabled={applying}>
+                        Edit source only
+                    </Button>
+                )}
+                {!result && (
+                    <Button
+                        variant="filled"
+                        color="primary"
+                        onClick={onConfirm}
+                        // `applicable` is the server's word, not a
+                        // re-derivation from the verdicts on screen:
+                        // `applySchemaChange` re-checks it before it writes
+                        // anything, so a button that disagreed would only
+                        // produce the same refusal one click later. The same
+                        // goes for the permission — `/apply` checks it too, and
+                        // this only saves somebody the round trip.
+                        disabled={!plan?.applicable || applying || Boolean(applyRefusedBecause)}
+                    >
+                        {applying ? "Applying…" : "Commit and apply"}
+                    </Button>
+                )}
+            </DialogActions>
+        </Dialog>
+    );
+}

package/src/collection_editor/useLiveSchemaEditing.tsx

@@ -0,0 +1,285 @@
+/**
+ * The plan-then-confirm flow, as a hook.
+ *
+ * Owns three things that belong together and nothing else: whether the backend
+ * can edit its schema, the plan for the change somebody is making, and the
+ * dialog they confirm it in. The config controller calls `reviewChange` and
+ * awaits it; everything about *how* the confirmation happens stays here.
+ *
+ * ## Why `reviewChange` returns a promise that can reject
+ *
+ * Because the editor needs to know. A save that was cancelled must not leave
+ * the form thinking it succeeded — the collection on screen would then differ
+ * from the one on disk, and the next save would be computed from the wrong
+ * `before`. Rejecting with {@link SchemaChangeCancelled} is how "the person
+ * said no" reaches the caller as an outcome rather than as silence.
+ */
+import React, { Suspense, useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { lazyChunk } from "@rebasepro/ui";
+
+import {
+    createLiveSchemaClient,
+    LiveSchemaError,
+    SchemaChangeCancelled,
+    type LiveSchemaClient,
+    type LiveSchemaPlan,
+    type LiveSchemaResult,
+    type LiveSchemaStatus,
+    type ProposedCollectionChange
+} from "./liveSchemaClient";
+
+// Re-exported so the hook stays the one import a caller needs.
+export { SchemaChangeCancelled, isSchemaChangeCancelled } from "./liveSchemaClient";
+
+/**
+ * Loaded when a change is actually being reviewed, not before.
+ *
+ * This hook is reached from the collections config controller, which is
+ * constructed on every admin boot — so a static import would put the dialog and
+ * the `@rebasepro/ui` surface it draws on into the **eager** bundle: everything
+ * a browser downloads before the login screen paints. It cost 14 kB there, for
+ * a dialog most sessions never open. The bundle budget caught it.
+ */
+const SchemaChangeDialog = lazyChunk(() =>
+    import("./ui/collection_editor/SchemaChangeDialog")
+        .then(m => ({ default: m.SchemaChangeDialog }))
+);
+
+export interface UseLiveSchemaEditingOptions {
+    /** Base for the routes, e.g. `https://api.example.com/api/admin/schema`. */
+    baseUrl: string;
+    getAuthToken?: () => Promise<string | null> | string | null;
+    /**
+     * Identity of the signed-in user.
+     *
+     * Only used to re-ask: whether this backend will accept a schema change
+     * depends on who is asking, and the answer to an anonymous probe does not
+     * survive a sign-in.
+     */
+    authKey?: string | null;
+    /**
+     * Write the collection source and leave the database alone — what the
+     * editor did before this existed. Offered in the dialog when a change is
+     * refused, so a dev can still delete a field from a collection they are
+     * designing. Omit it and the fallback is not offered.
+     */
+    writeSourceOnly?: (change: ProposedCollectionChange) => Promise<void>;
+    /** Swappable for the tests, which have no server. */
+    client?: LiveSchemaClient;
+}
+
+interface PendingChange {
+    change: ProposedCollectionChange;
+    resolve: () => void;
+    reject: (err: Error) => void;
+}
+
+export interface LiveSchemaEditing {
+    /** `undefined` until the backend has answered. For rendering. */
+    status?: LiveSchemaStatus;
+    /**
+     * The same answer, for deciding.
+     *
+     * `status` is undefined for one round trip after mount, and a caller that
+     * read it to choose a code path would take the "not available" branch for
+     * that window — so a save issued quickly after a page load would silently
+     * skip the confirmation and write source only, while the same save a second
+     * later would not. Timing-dependent behaviour with no visible difference is
+     * the worst shape this could have.
+     *
+     * Resolves once, cached; never rejects, because every way of failing to get
+     * an answer means the same thing to whoever is deciding.
+     */
+    ready: () => Promise<LiveSchemaStatus>;
+    /**
+     * Plan the change, show it, and settle when the person has decided.
+     *
+     * Resolves once the change has been applied — or written source-only, if
+     * they chose that. Rejects with {@link SchemaChangeCancelled} if they
+     * closed the dialog, and with the underlying error if planning or applying
+     * failed in a way they did not choose.
+     */
+    reviewChange: (change: ProposedCollectionChange) => Promise<void>;
+    /** Render this once, high enough that a dialog over the editor is not clipped. */
+    dialog: React.ReactNode;
+}
+
+export function useLiveSchemaEditing(options: UseLiveSchemaEditingOptions): LiveSchemaEditing {
+    const { baseUrl, authKey, writeSourceOnly } = options;
+
+    const optionsRef = useRef(options);
+    optionsRef.current = options;
+
+    const client = useMemo(
+        () => options.client ?? createLiveSchemaClient({
+            baseUrl,
+            getAuthToken: () => optionsRef.current.getAuthToken?.() ?? null
+        }),
+        // `client` is either supplied once by a test or built from the URL. The
+        // token getter is read through the ref so a new closure on every render
+        // does not rebuild the client underneath an in-flight request.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+        [baseUrl, options.client]
+    );
+
+    const [status, setStatus] = useState<LiveSchemaStatus | undefined>();
+    const [pending, setPending] = useState<PendingChange | undefined>();
+    const [plan, setPlan] = useState<LiveSchemaPlan | undefined>();
+    const [planError, setPlanError] = useState<string | undefined>();
+    const [result, setResult] = useState<LiveSchemaResult | undefined>();
+    const [applying, setApplying] = useState(false);
+    const [applyError, setApplyError] = useState<string | undefined>();
+
+    // The in-flight probe, so `ready()` can await the same one the effect
+    // started rather than issuing a second. Keyed by client+authKey the same way
+    // the effect is: a sign-in changes the answer, so it has to be re-asked.
+    // `undefined` passed explicitly: React 19's `useRef` takes no zero-argument
+    // overload, and omitting it is an error rather than a default.
+    const probe = useRef<{ key: unknown[]; promise: Promise<LiveSchemaStatus> } | undefined>(undefined);
+
+    /** Which review a plan response belongs to. See `reviewChange`. */
+    const reviewToken = useRef(0);
+
+    const ready = useCallback((): Promise<LiveSchemaStatus> => {
+        const key = [client, authKey];
+        const current = probe.current;
+        if (!current || current.key[0] !== key[0] || current.key[1] !== key[1]) {
+            probe.current = { key, promise: client.status() };
+        }
+        return probe.current!.promise;
+    }, [client, authKey]);
+
+    useEffect(() => {
+        let cancelled = false;
+        void ready().then(answer => {
+            if (!cancelled) setStatus(answer);
+        });
+        return () => { cancelled = true; };
+    }, [ready]);
+
+    const clear = useCallback(() => {
+        setPending(undefined);
+        setPlan(undefined);
+        setPlanError(undefined);
+        setResult(undefined);
+        setApplyError(undefined);
+        setApplying(false);
+    }, []);
+
+    const reviewChange = useCallback((change: ProposedCollectionChange) => {
+        return new Promise<void>((resolve, reject) => {
+            // A second review while one is open — a double-clicked save —
+            // replaces the pending one, and the one it replaces has to be
+            // settled. `setPending` used to overwrite `resolve`/`reject` with
+            // nobody left holding them, so the first caller's promise never
+            // settled at all and the editor's save simply never returned.
+            setPending(previous => {
+                previous?.reject(new SchemaChangeCancelled());
+                return { change, resolve, reject };
+            });
+
+            // Identifies the review a response belongs to. A plan that arrives
+            // after its review was replaced must not be shown: the dialog would
+            // describe the *previous* change while the reader believes it
+            // describes this one, and the SQL on screen would be for something
+            // they are not confirming.
+            const token = ++reviewToken.current;
+            setPlan(undefined);
+            setPlanError(undefined);
+            setResult(undefined);
+            setApplyError(undefined);
+            setApplying(false);
+
+            void client.plan(change).then(
+                answer => { if (token === reviewToken.current) setPlan(answer); },
+                (err: unknown) => {
+                    if (token !== reviewToken.current) return;
+                    setPlanError(
+                        err instanceof LiveSchemaError || err instanceof Error
+                            ? err.message
+                            : String(err)
+                    );
+                }
+            );
+        });
+    }, [client]);
+
+    const onConfirm = useCallback(() => {
+        if (!pending) return;
+        setApplying(true);
+        setApplyError(undefined);
+        void client.apply(pending.change).then(
+            answer => {
+                setResult(answer);
+                setApplying(false);
+                // Resolved here, not on close. The change has happened, and the
+                // dialog is now a receipt somebody may read for as long as they
+                // like — holding the caller open until they close it would
+                // leave the editor mid-save for no reason.
+                pending.resolve();
+                setPending(undefined);
+            },
+            (err: unknown) => {
+                setApplying(false);
+                setApplyError(err instanceof Error ? err.message : String(err));
+            }
+        );
+    }, [client, pending]);
+
+    const onSourceOnly = useCallback(() => {
+        if (!pending || !writeSourceOnly) return;
+        setApplying(true);
+        setApplyError(undefined);
+        const settle = pending;
+        void writeSourceOnly(settle.change).then(
+            () => { clear(); settle.resolve(); },
+            (err: unknown) => {
+                setApplying(false);
+                setApplyError(err instanceof Error ? err.message : String(err));
+            }
+        );
+    }, [pending, writeSourceOnly, clear]);
+
+    const onClose = useCallback(() => {
+        // Escape and the backdrop reach this too, and the Cancel *button* is the
+        // only one of the three that was disabled while applying. Closing
+        // mid-apply rejected the caller as cancelled while the commit and the
+        // DDL carried on — reporting that nothing happened while something did,
+        // which is the exact failure this whole feature exists to end.
+        if (applying) return;
+
+        const settle = pending;
+        clear();
+        // A dialog showing a result has already resolved; closing it is not a
+        // cancellation of anything.
+        if (settle && !result) settle.reject(new SchemaChangeCancelled());
+    }, [applying, pending, result, clear]);
+
+    // Not even a Suspense boundary until there is something to review — the
+    // chunk is fetched by the first `reviewChange`, and an admin session that
+    // never edits a collection never pays for it.
+    const open = Boolean(pending) || Boolean(result);
+    const dialog = open
+        ? (
+            <Suspense fallback={null}>
+                <SchemaChangeDialog
+                    open={open}
+                    collectionId={pending?.change.collectionId ?? ""}
+                    plan={plan}
+                    planError={planError}
+                    result={result}
+                    applying={applying}
+                    applyError={applyError}
+                    onConfirm={onConfirm}
+                    onSourceOnly={writeSourceOnly ? onSourceOnly : undefined}
+                    onClose={onClose}
+                    applyRefusedBecause={
+                        status && !status.canApply ? status.applyRefusedBecause : undefined
+                    }
+                />
+            </Suspense>
+        )
+        : null;
+
+    return { status, ready, reviewChange, dialog };
+}