@rebasepro/admin 0.16.0 → 0.16.1-canary.g0d7af95

package/src/collection_editor/useLiveSchemaEditing.tsx

@@ -0,0 +1,315 @@
+/**
+ * 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]);
+
+    /**
+     * Ask what the change would do, and ignore an answer that arrives late.
+     *
+     * Separate from `reviewChange` so it can be issued *again* without starting
+     * a new review: a plan that failed on a dropped connection should cost a
+     * click, not the whole wizard — the person has already filled in the form,
+     * and making them do it twice for a transient failure is the kind of thing
+     * that teaches people to distrust the preview.
+     */
+    const requestPlan = useCallback(async (change: ProposedCollectionChange) => {
+        // 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.
+        const token = ++reviewToken.current;
+        try {
+            const answer = await client.plan(change);
+            if (token === reviewToken.current) setPlan(answer);
+        } catch (err: unknown) {
+            if (token !== reviewToken.current) return;
+            setPlanError(
+                err instanceof LiveSchemaError || err instanceof Error
+                    ? err.message
+                    : String(err)
+            );
+        }
+    }, [client]);
+
+    const onRetry = useCallback(() => {
+        if (!pending) return;
+        setPlanError(undefined);
+        setPlan(undefined);
+        void requestPlan(pending.change);
+    }, [pending, requestPlan]);
+
+    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.
+            setPlan(undefined);
+            setPlanError(undefined);
+            setResult(undefined);
+            setApplyError(undefined);
+            setApplying(false);
+
+            void requestPlan(change);
+        });
+        // `client` is not listed: this no longer touches it directly, and
+        // `requestPlan` already carries that dependency.
+    }, [requestPlan]);
+
+    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}
+                    onRetry={planError ? onRetry : undefined}
+                    onSourceOnly={writeSourceOnly ? onSourceOnly : undefined}
+                    onClose={onClose}
+                    applyRefusedBecause={
+                        status && !status.canApply ? status.applyRefusedBecause : undefined
+                    }
+                    target={status && {
+                        repository: status.repository,
+                        branch: status.branch
+                    }}
+                />
+            </Suspense>
+        )
+        : null;
+
+    return { status, ready, reviewChange, dialog };
+}

package/src/collection_editor/useLocalCollectionsConfigController.tsx

@@ -5,6 +5,7 @@ import { getSubcollections } from "@rebasepro/common";
 import React, { useEffect, useMemo, useRef, useState } from "react";
 import type { AdminCollection } from "@rebasepro/admin-types";
 import { DEFAULT_API_PATH } from "@rebasepro/app";
+import { useLiveSchemaEditing } from "./useLiveSchemaEditing";
 
 /**
  * What the backend said about its schema editor, and how sure we are.
@@ -172,6 +173,47 @@ export function useLocalCollectionsConfigController(
         // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [editorUrl, forcedReadOnly, authKey]);
 
+    // ── Live schema editing ───────────────────────────────────────────
+    // The same edit, against a backend that can also change the database and
+    // commit the result. When it is available, a save is planned and shown
+    // before anything happens; when it is not, this is inert and writes go
+    // straight to the source-only editor exactly as before.
+    const liveSchema = useLiveSchemaEditing({
+        baseUrl: `${String(clientBaseUrl).replace(/\/$/, "")}${clientApiPath}/admin/schema`,
+        getAuthToken: resolveToken,
+        authKey,
+        // The fallback the dialog offers when a change cannot be applied —
+        // removing a property, most often, which the ensure path has no way to
+        // carry out. Writing the source and leaving the database alone is what
+        // the editor did before any of this existed.
+        writeSourceOnly: async ({ collectionId, collection }) => {
+            await request("/collection/save", { collectionId, collectionData: collection });
+        }
+    });
+
+    /**
+     * Perform a write, through the live editor when there is one.
+     *
+     * `sourceOnly` is the write this controller has always done. It stays the
+     * whole behaviour on a backend that cannot edit its schema — a bundle
+     * deployment, a non-Postgres driver, a version too old to be asked — so
+     * nothing about the editor depends on the feature being there.
+     */
+    const write = async (
+        collectionId: string,
+        collection: Record<string, unknown>,
+        sourceOnly: () => Promise<void>
+    ): Promise<void> => {
+        // `ready()`, not `status` — the rendered status is undefined for one
+        // round trip after mount, so reading it here would send a save issued
+        // in that window down the source-only path with no confirmation, while
+        // the same save a second later would open a dialog. One round trip is
+        // cheap; behaviour that depends on how fast somebody clicked is not.
+        const available = await liveSchema.ready();
+        if (!available.enabled) return sourceOnly();
+        await liveSchema.reviewChange({ collectionId, collection });
+    };
+
     const readOnly = forcedReadOnly
         ?? (availability.state === "known" ? !availability.enabled : buildModeGuess());
 
@@ -179,24 +221,42 @@ export function useLocalCollectionsConfigController(
         ? availability.reason
         : "Collections can only be edited against a backend running the schema editor, which is off in production.";
 
+    const findCollection = (id: string): AdminCollection | undefined =>
+        parsedCollections.find(c => (c as AdminCollection & { id?: string }).id === id || c.slug === id);
+
+    /**
+     * The whole collection as it should end up.
+     *
+     * Live editing computes the proposed state by replacing one collection in
+     * the set, so it needs all of it: handed a patch, it would read every
+     * property the patch does not mention as a removal and refuse the change.
+     * A collection this does not recognise is a new one, and the patch is the
+     * whole of it.
+     */
+    const wholeCollection = (id: string, patch: Record<string, unknown>): Record<string, unknown> => {
+        const current = findCollection(id) as Record<string, unknown> | undefined;
+        return current ? { ...current, ...patch } : patch;
+    };
+
     return useMemo(() => ({
         loading: false,
         readOnly,
         readOnlyReason,
         collections: parsedCollections,
+        dialog: liveSchema.dialog,
         getCollection: (id: string) => {
-            const found = parsedCollections.find(c => (c as AdminCollection & { id?: string }).id === id || c.slug === id);
+            const found = findCollection(id);
             if (found) return found;
             throw Error(`Collection ${id} not found in local mode`);
         },
 
         saveCollection: async ({ id, collectionData }: SaveCollectionParams) => {
-            await request("/collection/save", { collectionId: id,
-collectionData });
+            await write(id, collectionData as unknown as Record<string, unknown>, () =>
+                request("/collection/save", { collectionId: id, collectionData }));
         },
         updateCollection: async ({ id, collectionData }: UpdateCollectionParams) => {
-            await request("/collection/save", { collectionId: id,
-collectionData });
+            await write(id, wholeCollection(id, collectionData as Record<string, unknown>), () =>
+                request("/collection/save", { collectionId: id, collectionData }));
         },
         deleteCollection: async ({ id }: DeleteCollectionParams) => {
             await request("/collection/delete", { collectionId: id });
@@ -207,14 +267,30 @@ collectionData });
         // mention — `securityRules` first, which then falls back to the
         // directory default and widens who can read the collection.
         saveProperty: async ({ path, propertyKey, property, newPropertiesOrder }: SavePropertyParams) => {
-            await request("/property/save", { collectionId: path,
+            // Assembled into the whole collection before it is planned. This is
+            // the write that most often *is* a schema change — adding a field
+            // to a collection is adding a column — and the one whose payload
+            // says least about it on its own.
+            const current = findCollection(path) as Record<string, unknown> | undefined;
+            const properties = {
+                ...(current?.properties as Record<string, unknown> | undefined ?? {}),
+                [propertyKey]: property
+            };
+            const proposed = wholeCollection(path, {
+                properties,
+                ...(newPropertiesOrder ? { propertiesOrder: newPropertiesOrder } : {})
+            });
+
+            await write(path, proposed, async () => {
+                await request("/property/save", { collectionId: path,
 propertyKey,
 propertyConfig: property });
-            if (newPropertiesOrder) {
-                await request("/collection/save", { collectionId: path,
+                if (newPropertiesOrder) {
+                    await request("/collection/save", { collectionId: path,
 collectionData: { propertiesOrder: newPropertiesOrder },
 partial: true });
-            }
+                }
+            });
         },
         deleteProperty: async ({ path, propertyKey, newPropertiesOrder }: DeletePropertyParams) => {
             await request("/property/delete", { collectionId: path,
@@ -238,5 +314,28 @@ partial: true });
 
         navigationEntries: [],
         saveNavigationEntries: async () => { }
-    }), [clientOrUrl, parsedCollections, readOnly, readOnlyReason, options?.getAuthToken]);
+        // `liveSchema.dialog` and `liveSchema.status` both change as the flow
+        // runs — a plan arrives, a dialog opens — and a controller memoised
+        // without them would keep handing back a closed dialog and a stale
+        // answer about whether the backend can edit its schema at all.
+        //
+        // `write`, `request`, `findCollection` and `wholeCollection` are
+        // rebuilt on every render, so listing them would defeat the memo
+        // entirely. Each is already covered *transitively* by what is listed:
+        // `request` closes over `editorUrl` and a ref, and `editorUrl` derives
+        // from `clientOrUrl`; `findCollection` and `wholeCollection` close over
+        // `parsedCollections`; `write` closes over `liveSchema.status` and
+        // `liveSchema.reviewChange`, and the latter is a `useCallback` keyed on
+        // a client built from `clientOrUrl`. Every input that can change is in
+        // the array under the name it actually varies with.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }), [
+        clientOrUrl,
+        parsedCollections,
+        readOnly,
+        readOnlyReason,
+        options?.getAuthToken,
+        liveSchema.dialog,
+        liveSchema.status
+    ]);
 }

package/src/components/DrawerNavigationGroup.tsx

@@ -27,15 +27,6 @@ export interface DrawerNavigationGroupProps {
      * Whether the drawer is in open (expanded) state
      */
     drawerOpen: boolean;
-    /**
-     * @deprecated No longer read. Entry tooltips are uncontrolled — they follow the
-     * pointer and focus, and are suppressed wherever the label is already visible.
-     */
-    tooltipsOpen?: boolean;
-    /**
-     * @deprecated No longer read. See {@link tooltipsOpen}.
-     */
-    adminMenuOpen?: boolean;
     /**
      * Optional actions to render in the group header (e.g., "Add collection" button)
      */

package/src/components/DrawerNavigationItem.tsx

@@ -10,11 +10,7 @@ import { cls, Tooltip } from "@rebasepro/ui";
 export type DrawerNavigationItemProps = {
     icon: React.ReactElement,
     name: string,
-    /** @deprecated No longer read: the tooltip is uncontrolled. */
-    tooltipsOpen?: boolean,
     drawerOpen: boolean,
-    /** @deprecated No longer read: the tooltip is uncontrolled. */
-    adminMenuOpen?: boolean,
     url: string,
     onClick?: () => void,
     /**

package/src/components/RelationSelector.tsx

@@ -68,8 +68,6 @@ export interface RelationSelectorProps {
     size?: "small" | "medium" | "large";
     useChips?: boolean;
     disabled?: boolean;
-    error?: boolean; // kept for backwards compatibility (could be used for styling later)
-    padding?: boolean; // legacy prop
     invisible?: boolean;
 
     relation: Relation;

package/src/data_import/utils/data.ts

@@ -2,7 +2,7 @@ import { getPropertyInPath } from "../../util";
 import { Entity, EntityReference, CollectionRegistryController, Properties, Property, Vector } from "@rebasepro/types";
 import { AuthController, AdminCollection } from "@rebasepro/admin-types";
 import { isPropertyBuilder } from "@rebasepro/common";
-import { unflattenObject } from "./file_to_json";
+import { unflattenObject } from "./transforms";
 import { getIn } from "@rebasepro/forms";
 import { inferTypeFromValue } from "@rebasepro/inference";
 import { isPrototypePollutingKey, mergeDeep } from "@rebasepro/utils";

package/src/data_import/utils/file_to_json.ts

@@ -3,9 +3,6 @@ import { mapJsonParse, unflattenObject } from "./transforms";
 import { parseCsvToObjects } from "./csv";
 import { isPrototypePollutingKey } from "@rebasepro/utils";
 
-// Re-export for backwards compat (tests import from this file)
-export { unflattenObject } from "./transforms";
-
 type ConversionResult = {
     data: object[];
     propertiesOrder: string[]

package/src/index.ts

@@ -112,6 +112,12 @@ export * from "./data_export";
 
 // Collection editor — moved from @rebasepro/studio (admin-dependent visual schema editor)
 export * from "./collection_editor";
+export * from "./collection_editor/liveSchemaClient";
+export * from "./collection_editor/useLiveSchemaEditing";
+// `SchemaChangeDialog` is deliberately absent, like `CollectionEditorDialog`
+// and `PropertyFormDialog` beside it: re-exporting it from the barrel puts it
+// back in the eager bundle and undoes the `lazyChunk` in `useLiveSchemaEditing`.
+// Import it by path if you need the component itself.
 
 
 export { CreationResultDialog } from "./components/admin/CreationResultDialog";

package/src/util/previews.ts

@@ -1,5 +1,5 @@
 import type { Property } from "@rebasepro/types";
-import type { PropertyConfig, AdminCollection } from "@rebasepro/admin-types";
+import type { AdminCollection } from "@rebasepro/admin-types";
 import { getTitlePropertyKey, getTitlePropertyKeyForValues } from "@rebasepro/app";
 import { isPropertyBuilder } from "@rebasepro/common";
 
@@ -21,7 +21,9 @@ export { getEntityPreviewKeys } from "@rebasepro/app";
  * called. Identifiers are excluded from the property *schema* — primary keys,
  * foreign keys, UUID columns — not from the key name.
  */
-export function getEntityTitlePropertyKey<M extends Record<string, unknown>>(collection: AdminCollection<M>, propertyConfigs: Record<string, PropertyConfig>): string | undefined {
+export function getEntityTitlePropertyKey<M extends Record<string, unknown>>(
+    collection: AdminCollection<M>
+): string | undefined {
     return getTitlePropertyKey(collection);
 }