canopycms 0.7.0 → 0.8.0

package/dist/editor/hooks/useBranchActions.d.ts

@@ -1,7 +1,10 @@
 import type { BranchListItem } from '../../api/branch.js';
+import { type CreateRefusal } from './create-branch-request.js';
 import type { UnsavedSummary } from './useDraftManager.js';
 export interface UseBranchActionsOptions {
     branchName: string;
+    /** What the dialogs call the open branch, when it is not `branchName`. */
+    branchLabel?: string;
     setBranchName: (name: string) => void;
     /** From useDraftManager's `resolveUnsaved`: what a branch-level action would leave behind. */
     getUnsaved: () => Promise<UnsavedSummary>;
@@ -9,18 +12,32 @@ export interface UseBranchActionsOptions {
     /** Receives the branch the server just created, so it can be shown before any listing includes it. */
     onBranchCreated: (branch: BranchListItem) => void;
     onBranchSwitch?: (branch: string) => void;
+    /** What `?branch=` carries for a branch (its short name); defaults to the name as given. */
+    urlBranchName?: (branch: string) => string;
+    /**
+     * Whether `next`, the name a card or history entry gives, opens `branchName`, so a change to it
+     * is no switch; defaults to equality.
+     */
+    sameBranch?: (next: string, branchName: string) => boolean;
     /** The current user; a create the server never answered adopts only a listed branch they made. */
     userId?: string;
 }
 export interface UseBranchActionsReturn {
-    handleBranchChange: (branch: string | null) => Promise<void>;
+    /**
+     * `push: false` for a switch a Back or Forward makes, which arrived at its history entry already;
+     * it rejects instead once its `superseded()` holds.
+     */
+    handleBranchChange: (branch: string | null, options?: {
+        push?: boolean;
+        superseded?: () => boolean;
+    }) => Promise<void>;
     /** True when nothing is unsaved or the user accepted the warning. Run before any in-flight UI. */
     confirmCreate: () => Promise<boolean>;
     handleCreateBranch: (branch: {
         name: string;
         title?: string;
         description?: string;
-    }) => Promise<boolean>;
+    }) => Promise<boolean | CreateRefusal>;
     /** True while the unsaved-changes confirm is on screen. */
     confirmOpen: boolean;
 }

package/dist/editor/hooks/useBranchActions.js

@@ -5,7 +5,9 @@ import { notifications } from '@mantine/notifications';
 import { Text } from '@mantine/core';
 import { useApiClient } from '../context/index.js';
 import { requestBranchCreate } from './create-branch-request.js';
+import { displayBranchName } from '../branch-names.js';
 import { writeEditorUrl } from './editor-history.js';
+import { parseCreatedBranchName } from '../../paths/validation.js';
 const MAX_LISTED_LABELS = 5;
 /** 'Unsaved changes in: "A", "B".' */
 export const describeUnsaved = ({ labels }) => {
@@ -24,13 +26,13 @@ export const describeUnsaved = ({ labels }) => {
 export function useBranchActions(options) {
     const apiClient = useApiClient();
     const [confirmOpen, setConfirmOpen] = useState(false);
-    const performBranchSwitch = (next) => {
+    const performBranchSwitch = (next, urlName, push = true) => {
         options.setBranchName(next);
-        // Its own history entry; a Back onto another branch already shows this URL, so writes nothing.
+        // Its own history entry, unless a Back or Forward made it: that entry's URL is replaced.
         if (typeof window !== 'undefined') {
             const url = new URL(window.location.href);
-            url.searchParams.set('branch', next);
-            writeEditorUrl(url.toString(), true);
+            url.searchParams.set('branch', urlName ?? options.urlBranchName?.(next) ?? next);
+            writeEditorUrl(url.toString(), push);
         }
         options.onBranchSwitch?.(next);
     };
@@ -49,7 +51,7 @@ export function useBranchActions(options) {
             openConfirm({
                 title: 'Unsaved Changes',
                 // Drafts are stored per branch, so leaving does not lose them.
-                children: (_jsxs(Text, { size: "sm", children: [describeUnsaved(unsaved), " Your drafts stay on \u201C", options.branchName, "\u201D and come back when you return. ", question] })),
+                children: (_jsxs(Text, { size: "sm", children: [describeUnsaved(unsaved), " Your drafts stay on \u201C", options.branchLabel ?? options.branchName, "\u201D and come back when you return. ", question] })),
                 labels: { confirm: 'Continue Anyway', cancel: 'Cancel' },
                 confirmProps: { color: 'red' },
                 onCancel: () => settle(false),
@@ -60,16 +62,21 @@ export function useBranchActions(options) {
             });
         });
     };
-    const handleBranchChange = async (next) => {
-        if (!next || next === options.branchName)
+    const handleBranchChange = async (next, change = {}) => {
+        if (!next || (options.sameBranch?.(next, options.branchName) ?? next === options.branchName))
             return;
         const confirmed = await confirmIfDirty('Switch branches anyway?');
         if (!confirmed)
             throw new Error('User cancelled branch switch');
-        performBranchSwitch(next);
+        if (change.superseded?.())
+            throw new Error('A later history move superseded the branch switch');
+        performBranchSwitch(next, undefined, change.push ?? true);
     };
     const confirmCreate = () => confirmIfDirty('Create the new branch anyway?');
-    /** Resolves true when the branch was created and switched to, false when it was not. */
+    /**
+     * Resolves true when the branch was created and switched to, false when it was not and a toast
+     * says why, or a {@link CreateRefusal} when the name cannot be created.
+     */
     const handleCreateBranch = async (branch) => {
         try {
             const outcome = await requestBranchCreate(apiClient, {
@@ -78,22 +85,24 @@ export function useBranchActions(options) {
                 description: branch.description,
             }, options.userId);
             if (outcome.kind === 'failed') {
+                if (outcome.refused)
+                    return { refusal: outcome.message };
                 throw new Error(outcome.message);
             }
             const created = outcome.branch;
             if (created)
                 options.onBranchCreated(created);
-            // The server sanitizes the branch name (e.g. "feature/x" -> "feature-x")
-            // before persisting it. Adopt the canonical name from the response so
-            // the client doesn't end up stuck on a name the server never saved.
-            const createdName = created?.name ?? branch.name;
-            notifications.show({
-                message: createdName === branch.name
-                    ? `Branch "${createdName}" created`
-                    : `Branch "${createdName}" created (renamed from "${branch.name}")`,
-                color: 'green',
-            });
-            performBranchSwitch(createdName);
+            // The server adds the namespace, which the editor is never told; its short name resolves too.
+            const typed = parseCreatedBranchName(branch.name);
+            const createdName = created?.name ?? (typed.ok ? typed.shortName : branch.name);
+            const createdLabel = created
+                ? displayBranchName(created)
+                : typed.ok
+                    ? typed.shortName
+                    : branch.name;
+            notifications.show({ message: `Branch “${createdLabel}” created`, color: 'green' });
+            // A listing may not hold it yet, so its own short name stands in for the lookup.
+            performBranchSwitch(createdName, created?.shortName);
             // Not awaited: a listing can lag the create, and the switch must not wait
             // on it. loadBranches reports its own failures and never rejects.
             void options.onReloadBranches();

package/dist/editor/hooks/useBranchChangesData.d.ts

@@ -0,0 +1,57 @@
+import type { ApiClient } from '../context/index.js';
+import type { BranchChangesData } from '../../api/branch-changes.js';
+import type { BranchEntryChangeData } from '../../api/branch-entry-changes.js';
+/** An entry's change on the branch, and where a move started. */
+export interface EntryChangeTarget {
+    logicalPath: string;
+    /** A moved entry's path at the base. */
+    from?: string;
+    /** The entry's content id, so a slug another entry reuses isn't read as this one. */
+    id?: string;
+}
+/**
+ * Why a branch's changes could not be loaded: the branch moved under the read (a 409, nothing
+ * lost; `message` is the server's) or anything else.
+ */
+export type BranchChangesError = {
+    kind: 'syncing';
+    message?: string;
+} | {
+    kind: 'failed';
+    message: string;
+};
+/**
+ * Why an entry's change could not be loaded: as the list's, or a refusal no retry passes: too
+ * large to compare (413), on neither side (404), or a side that doesn't parse (422).
+ */
+type EntryChangeError = BranchChangesError | {
+    kind: 'tooLarge';
+    message: string;
+} | {
+    kind: 'notFound';
+    message: string;
+} | {
+    kind: 'unreadable';
+    message: string;
+};
+interface ChangesState<T, E> {
+    data: T | undefined;
+    error: E | undefined;
+    isLoading: boolean;
+    isValidating: boolean;
+    /**
+     * Starts a fresh fetch through SWR's revalidating `mutate()`, never coalesced with one in
+     * flight; SWR keeps whichever fetch started last (hooks/README.md).
+     */
+    reload: () => Promise<void>;
+}
+export type BranchChangesState = ChangesState<BranchChangesData, BranchChangesError>;
+/**
+ * The branch's changes. `reload` also revalidates every entry change of the branch that is
+ * shown, so one save refreshes the list and an open "Show changes" alike.
+ */
+export declare function useBranchChangesData(apiClient: Pick<ApiClient, 'changes'>, branch: string, enabled: boolean): BranchChangesState;
+export type EntryChangeState = ChangesState<BranchEntryChangeData, EntryChangeError>;
+/** One entry's change on the branch, fetched while `target` is set (the drawer is open). */
+export declare function useEntryChangeData(apiClient: Pick<ApiClient, 'changes'>, branch: string, target: EntryChangeTarget | undefined): EntryChangeState;
+export {};

package/dist/editor/hooks/useBranchChangesData.js

@@ -0,0 +1,134 @@
+'use client';
+/**
+ * SWR-backed reads of what a branch changes against its base: the list (GET /:branch/changes)
+ * for the Content panel's Changed filter, and one entry's two sides (GET
+ * /:branch/changes/...entryPath) for its "Show changes" drawer. Keyed per branch like
+ * useCommentsData.ts; a null key fetches nothing.
+ */
+import { useCallback, useRef } from 'react';
+import useSWR, { useSWRConfig } from 'swr';
+const KEY_PREFIX = 'canopy:changes:';
+/** Cache key for a branch's changes against its base. */
+const branchChangesKey = (branch) => `${KEY_PREFIX}${branch}`;
+/**
+ * Cache key for one entry's change. Under its branch's list key and a `:`, which no branch name
+ * holds, so a reload of the list finds every entry key of its branch by prefix.
+ */
+const entryChangeKey = (branch, target) => `${KEY_PREFIX}${branch}:${target.logicalPath}${target.from ? `?from=${target.from}` : ''}${target.id ? `#${target.id}` : ''}`;
+class ChangesLoadError extends Error {
+    constructor(reason) {
+        super(`Couldn't load the branch's changes (${reason.kind})`);
+        this.reason = reason;
+    }
+}
+async function fetchBranchChanges(apiClient, branch) {
+    const result = await apiClient.changes.list({ branch });
+    // A body no CanopyCMS handler wrote, such as a proxy's, is a failure, not an empty list.
+    if (result.ok && Array.isArray(result.data?.entries) && Array.isArray(result.data.collections)) {
+        return result.data;
+    }
+    throw new ChangesLoadError(result.status === 409
+        ? { kind: 'syncing', ...(result.error && { message: result.error }) }
+        : { kind: 'failed', message: result.error ?? `HTTP ${result.status}` });
+}
+async function fetchEntryChange(apiClient, branch, target) {
+    const result = await apiClient.changes.entry({
+        branch,
+        entryPath: target.logicalPath,
+        ...(target.from && { from: target.from }),
+        ...(target.id && { id: target.id }),
+    });
+    if (result.ok && result.data && 'before' in result.data && 'after' in result.data) {
+        return result.data;
+    }
+    const message = result.error ?? `HTTP ${result.status}`;
+    throw new ChangesLoadError(result.status === 409
+        ? { kind: 'syncing', ...(result.error && { message: result.error }) }
+        : result.status === 413
+            ? { kind: 'tooLarge', message }
+            : result.status === 404
+                ? { kind: 'notFound', message }
+                : result.status === 422
+                    ? { kind: 'unreadable', message }
+                    : { kind: 'failed', message });
+}
+const toError = (err) => err instanceof ChangesLoadError
+    ? err.reason
+    : { kind: 'failed', message: err instanceof Error ? err.message : String(err) };
+/**
+ * `fetch` as an SWR fetcher that never lets an overtaken fetch's error show. SWR 2.4 drops an
+ * overtaken fetch's result but still shows its error, so per key it counts the fetches started,
+ * and one overtaken resolves with the last answer instead of throwing, which SWR then drops: a
+ * newer fetch holds the key, or has finished.
+ */
+function useOvertakenGuard(fetch) {
+    const startsRef = useRef(new Map());
+    const answersRef = useRef(new Map());
+    return async (key) => {
+        const started = (startsRef.current.get(key) ?? 0) + 1;
+        startsRef.current.set(key, started);
+        try {
+            const data = await fetch(key);
+            answersRef.current.set(key, data);
+            return data;
+        }
+        catch (err) {
+            if ((startsRef.current.get(key) ?? 0) > started)
+                return answersRef.current.get(key);
+            throw err;
+        }
+    };
+}
+/**
+ * The branch's changes. `reload` also revalidates every entry change of the branch that is
+ * shown, so one save refreshes the list and an open "Show changes" alike.
+ */
+export function useBranchChangesData(apiClient, branch, enabled) {
+    const key = branch && enabled ? branchChangesKey(branch) : null;
+    const fetcher = useOvertakenGuard((cacheKey) => 
+    // The branch is read from the key the fetch was started for, never from the render.
+    fetchBranchChanges(apiClient, cacheKey.slice(KEY_PREFIX.length)));
+    const swr = useSWR(key, fetcher);
+    const { mutate } = swr;
+    const { mutate: mutateKeys } = useSWRConfig();
+    const reload = useCallback(async () => {
+        const entryPrefix = `${branchChangesKey(branch)}:`;
+        await Promise.all([
+            mutate(),
+            mutateKeys((k) => typeof k === 'string' && k.startsWith(entryPrefix)),
+        ]);
+    }, [mutate, mutateKeys, branch]);
+    return {
+        data: swr.data,
+        error: key && swr.error !== undefined ? toError(swr.error) : undefined,
+        isLoading: swr.isLoading,
+        isValidating: swr.isValidating,
+        reload,
+    };
+}
+/** One entry's change on the branch, fetched while `target` is set (the drawer is open). */
+export function useEntryChangeData(apiClient, branch, target) {
+    const key = branch && target ? entryChangeKey(branch, target) : null;
+    // What each key fetches, recorded as it is rendered, so a fetch reads its own key's target.
+    const targetsRef = useRef(new Map());
+    if (key && target)
+        targetsRef.current.set(key, { branch, target });
+    const fetcher = useOvertakenGuard((cacheKey) => {
+        const keyed = targetsRef.current.get(cacheKey);
+        if (!keyed)
+            throw new Error(`No entry change is keyed ${cacheKey}`);
+        return fetchEntryChange(apiClient, keyed.branch, keyed.target);
+    });
+    const swr = useSWR(key, fetcher);
+    const { mutate } = swr;
+    const reload = useCallback(async () => {
+        await mutate();
+    }, [mutate]);
+    return {
+        data: swr.data,
+        error: key && swr.error !== undefined ? toError(swr.error) : undefined,
+        isLoading: swr.isLoading,
+        isValidating: swr.isValidating,
+        reload,
+    };
+}

package/dist/editor/hooks/useBranchManager.d.ts

@@ -27,6 +27,7 @@ export declare function withdrawPullRequestBullet(pr: BranchPullRequest): string
 export declare const CREATED_BRANCH_GRACE_MS = 120000;
 interface BranchSummary {
     name: string;
+    shortName?: string;
     status: string;
     createdBy?: string;
     updatedAt?: string;
@@ -85,11 +86,26 @@ export interface UseBranchManagerOptions {
     onChangesRequested?: (branchName: string) => void;
 }
 export interface UseBranchManagerReturn {
+    /**
+     * The listed full name of the open branch, which keys everything stored or fetched per branch.
+     * Until a listing resolves the name it arrived by, that name as given.
+     */
     branchName: string;
+    /** Opens the branch `name` names, a URL value or card address, resolved once a listing holds it. */
     setBranchName: (name: string) => void;
     branches: BranchListItem[];
     branchSummaries: BranchSummary[];
     currentBranch: BranchListItem | undefined;
+    /** What the open branch's own actions hand `handleSubmit` and the rest (`branchAddress`). */
+    currentAddress: string;
+    /** The listed branch `name`, a URL value or card address, opens. */
+    listedBranch: (name: string) => BranchListItem | undefined;
+    /** The full name of the listed branch `name` opens, else `name` sanitized. */
+    listedName: (name: string) => string;
+    /** Whether `name`, a URL value or card address, opens `branch`, a `branchName` this gave. */
+    namesBranch: (name: string, branch: string) => boolean;
+    /** What `?branch=` carries for the branch `name`, a full name or its exact form, names, else `name`. */
+    urlBranchName: (name: string) => string;
     /** The listing failed and nothing earlier stands in for it. */
     branchesLoadFailed: boolean;
     /** A listing has arrived, so a branch missing from it is not still loading. */