@rebasepro/cms 0.17.3 → 0.18.0

package/src/collection_editor/useJsonCollectionsConfigController.tsx

@@ -1,297 +0,0 @@
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
-import type { EngineProperties, Property } from "@rebasepro/types";
-import type { NavigationGroupMapping, AdminCollection } from "@rebasepro/cms-types";
-import type {
-    CollectionsConfigController,
-    SaveCollectionParams,
-    UpdateCollectionParams,
-    DeleteCollectionParams,
-    SavePropertyParams,
-    DeletePropertyParams,
-    UpdatePropertiesOrderParams,
-    UpdateKanbanColumnsOrderParams,
-} from "./types/config_controller";
-import type { JsonCollectionStore, SerializableCollectionConfig } from "./serializable_types";
-import { toSerializableCollectionConfig, toSerializableProperty, fromSerializableCollectionConfigs } from "./serializable_utils";
-
-export interface UseJsonCollectionsConfigControllerOptions {
-    /**
-     * The store adapter for persisting/loading collections.
-     */
-    store: JsonCollectionStore;
-
-    /**
-     * If true, the configuration cannot be modified.
-     */
-    readOnly?: boolean;
-
-    /**
-     * If true, collections will be loaded from the store on mount.
-     * Defaults to true.
-     */
-    autoLoad?: boolean;
-}
-
-/**
- * A `CollectionsConfigController` implementation that persists collection
- * configurations as JSON via a pluggable `JsonCollectionStore` adapter.
- *
- * Use this when you want to store collection schemas in a database, API,
- * localStorage, or any other JSON-compatible backend — as opposed to the
- * default code-based persistence.
- *
- * @example
- * ```tsx
- * const store: JsonCollectionStore = {
- *     load: async () => { const res = await fetch('/api/schemas'); return res.json(); },
- *     save: async (slug, data) => { await fetch(`/api/schemas/${slug}`, { method: 'PUT', body: JSON.stringify(data) }); },
- *     delete: async (slug) => { await fetch(`/api/schemas/${slug}`, { method: 'DELETE' }); },
- * };
- *
- * const configController = useJsonCollectionsConfigController({ store });
- * ```
- */
-export function useJsonCollectionsConfigController({
-    store,
-    readOnly = false,
-    autoLoad = true,
-}: UseJsonCollectionsConfigControllerOptions): CollectionsConfigController {
-    const [collections, setCollections] = useState<AdminCollection[]>([]);
-    const [loading, setLoading] = useState(autoLoad);
-    const [navigationEntries, setNavigationEntries] = useState<NavigationGroupMapping[]>([]);
-
-    // Keep store ref stable to avoid stale closures in callbacks
-    const storeRef = useRef(store);
-    storeRef.current = store;
-
-    /**
-     * The current collections, readable outside a state updater.
-     *
-     * Three mutators used to compute their new value inside
-     * `setCollections(prev => …)` and persist from in there, which cost them
-     * both halves of a save: the promise they returned resolved before the
-     * store had answered, so a failed write reached the caller as a success,
-     * and a `setState` updater must be pure — under `StrictMode` React invokes
-     * it twice, so every one of those saves wrote to the store twice in
-     * development. Reading `prev` from a ref lets them do what
-     * `updatePropertiesOrder` already did: compute, set, then await.
-     */
-    const collectionsRef = useRef<AdminCollection[]>([]);
-    const applyCollections = useCallback((next: AdminCollection[]) => {
-        collectionsRef.current = next;
-        setCollections(next);
-    }, []);
-
-    // ── Load on mount ─────────────────────────────────────────────────
-    useEffect(() => {
-        if (!autoLoad) return;
-        let cancelled = false;
-
-        (async () => {
-            try {
-                const [serialized, navEntries] = await Promise.all([
-                    storeRef.current.load(),
-                    storeRef.current.loadNavigationEntries?.() ?? Promise.resolve([]),
-                ]);
-                if (cancelled) return;
-                // Deserialized as a set: a relation's target is a slug, and a slug only
-                // resolves against the other collections it arrived with.
-                applyCollections(fromSerializableCollectionConfigs(serialized));
-                setNavigationEntries(navEntries);
-            } catch (e) {
-                console.error("useJsonCollectionsConfigController: failed to load collections", e);
-            } finally {
-                if (!cancelled) setLoading(false);
-            }
-        })();
-
-        return () => { cancelled = true; };
-        // `applyCollections` is `useCallback(…, [])`, so naming it here cannot
-        // re-run the mount effect — it is listed because a stable identity is a
-        // fact about today's code, not a reason to leave a dependency out.
-    }, [autoLoad, applyCollections]);
-
-    // ── Helpers ────────────────────────────────────────────────────────
-
-    /**
-     * Update local state and persist a collection to the store.
-     */
-    const persistCollection = useCallback(async (collection: AdminCollection) => {
-        const serializable = toSerializableCollectionConfig(collection);
-        await storeRef.current.save(collection.slug, serializable);
-    }, []);
-
-    /**
-     * Find collection by id (slug).
-     */
-    const getCollection = useCallback((id: string): AdminCollection => {
-        const found = collections.find(c => c.slug === id);
-        if (found) return found;
-        throw new Error(`Collection "${id}" not found`);
-    }, [collections]);
-
-    // ── CRUD operations ───────────────────────────────────────────────
-
-    const saveCollection = useCallback(async <M extends Record<string, unknown>>(
-        { id, collectionData }: SaveCollectionParams<M>
-    ) => {
-        const collection = collectionData as AdminCollection;
-        await persistCollection(collection);
-        const prev = collectionsRef.current;
-        const idx = prev.findIndex(c => c.slug === id);
-        if (idx >= 0) {
-            const next = [...prev];
-            next[idx] = collection;
-            applyCollections(next);
-        } else {
-            applyCollections([...prev, collection]);
-        }
-    }, [persistCollection, applyCollections]);
-
-    const updateCollection = useCallback(async <M extends Record<string, unknown>>(
-        { id, collectionData, previousId }: UpdateCollectionParams<M>
-    ) => {
-        const prev = collectionsRef.current;
-        const lookupId = previousId ?? id;
-        const idx = prev.findIndex(c => c.slug === lookupId);
-        if (idx < 0) return;
-
-        const merged = { ...prev[idx], ...collectionData } as AdminCollection;
-        const next = [...prev];
-        next[idx] = merged;
-        applyCollections(next);
-
-        await persistCollection(merged);
-
-        // If the slug changed, clean up the old entry in the store. After the
-        // save, not beside it: dropping the old key first and then failing to
-        // write the new one loses the collection outright.
-        if (previousId && previousId !== id) {
-            await storeRef.current.delete(previousId);
-        }
-    }, [persistCollection, applyCollections]);
-
-    const deleteCollection = useCallback(async ({ id }: DeleteCollectionParams) => {
-        await storeRef.current.delete(id);
-        applyCollections(collectionsRef.current.filter(c => c.slug !== id));
-    }, [applyCollections]);
-
-    const saveProperty = useCallback(async ({
-        path,
-        propertyKey,
-        property,
-        newPropertiesOrder,
-    }: SavePropertyParams) => {
-        const prev = collectionsRef.current;
-        const idx = prev.findIndex(c => c.slug === path);
-        if (idx < 0) return;
-
-        const collection = { ...prev[idx] };
-        collection.properties = {
-            ...collection.properties,
-            [propertyKey]: property,
-        } as EngineProperties;
-        if (newPropertiesOrder) {
-            collection.propertiesOrder = newPropertiesOrder as typeof collection.propertiesOrder;
-        }
-
-        const next = [...prev];
-        next[idx] = collection as AdminCollection;
-        applyCollections(next);
-
-        await persistCollection(next[idx]);
-    }, [persistCollection, applyCollections]);
-
-    const deleteProperty = useCallback(async ({
-        path,
-        propertyKey,
-        newPropertiesOrder,
-    }: DeletePropertyParams) => {
-        const prev = collectionsRef.current;
-        const idx = prev.findIndex(c => c.slug === path);
-        if (idx < 0) return;
-
-        const collection = { ...prev[idx] };
-        const { [propertyKey]: _removed, ...remaining } = collection.properties;
-        collection.properties = remaining;
-        if (newPropertiesOrder) {
-            collection.propertiesOrder = newPropertiesOrder as typeof collection.propertiesOrder;
-        }
-
-        const next = [...prev];
-        next[idx] = collection as AdminCollection;
-        applyCollections(next);
-
-        await persistCollection(next[idx]);
-    }, [persistCollection, applyCollections]);
-
-    const updatePropertiesOrder = useCallback(async ({
-        collection,
-        newPropertiesOrder,
-    }: UpdatePropertiesOrderParams) => {
-        const updated = {
-            ...collection,
-            propertiesOrder: newPropertiesOrder,
-        } as AdminCollection;
-
-        const prev = collectionsRef.current;
-        const idx = prev.findIndex(c => c.slug === collection.slug);
-        if (idx >= 0) {
-            const next = [...prev];
-            next[idx] = updated;
-            applyCollections(next);
-        }
-
-        await persistCollection(updated);
-    }, [persistCollection, applyCollections]);
-
-    const updateKanbanColumnsOrder = useCallback(async ({
-        collection,
-        kanbanColumnProperty,
-        newColumnsOrder,
-    }: UpdateKanbanColumnsOrderParams) => {
-        // Kanban column order is stored in the enum order of the column property.
-        // For JSON persistence, we store it as-is — the view layer reads enum order.
-        // This is a no-op for now; the kanban order is determined by the enum
-        // definition on the property itself.
-    }, []);
-
-    const saveNavigationEntriesHandler = useCallback(async (entries: NavigationGroupMapping[]) => {
-        setNavigationEntries(entries);
-        if (storeRef.current.saveNavigationEntries) {
-            await storeRef.current.saveNavigationEntries(entries);
-        }
-    }, []);
-
-    // ── Return controller ─────────────────────────────────────────────
-    return useMemo<CollectionsConfigController>(() => ({
-        loading,
-        readOnly,
-        readOnlyReason: readOnly ? "Configuration is read-only." : undefined,
-        collections,
-        getCollection,
-        saveCollection,
-        updateCollection,
-        deleteCollection,
-        saveProperty,
-        deleteProperty,
-        updatePropertiesOrder,
-        updateKanbanColumnsOrder,
-        navigationEntries,
-        saveNavigationEntries: saveNavigationEntriesHandler,
-    }), [
-        loading,
-        readOnly,
-        collections,
-        getCollection,
-        saveCollection,
-        updateCollection,
-        deleteCollection,
-        saveProperty,
-        deleteProperty,
-        updatePropertiesOrder,
-        updateKanbanColumnsOrder,
-        navigationEntries,
-        saveNavigationEntriesHandler,
-    ]);
-}

package/src/collection_editor/useLiveSchemaEditing.tsx

@@ -1,315 +0,0 @@
-/**
- * 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 };
-}