canopycms 0.11.1 → 0.12.1

package/dist/editor/conflict-choices.js

@@ -0,0 +1,108 @@
+/**
+ * What a choice on a conflict card does to the open entry's form value (conflict-cards.ts builds
+ * the cards). Pure. A choice is an unsaved edit: the save that writes it sends the conflict's key in
+ * `resolvedConflicts` (api/content.ts), which is what resolves it.
+ */
+import { holdsAs, setChangeBack, valueAtChange, withValueAt } from './undo-change.js';
+/** The change-shaped handle `undo-change.ts` places a value by. */
+export const placeOf = (field) => ({
+    key: field.key,
+    dataPath: field.dataPath,
+    path: [],
+    kind: 'changed',
+    ...(field.item && { item: true }),
+});
+/** Whether a choice says everything its conflict needs. */
+export const isDecided = (field, choice) => !!choice &&
+    (choice.how !== 'regions' ||
+        (!!field.text && field.text.regions.every((_, i) => choice.regions[i] !== undefined)));
+const linesOf = (text, count) => count === 0 || (count === undefined && text === '') ? [] : text.split('\n');
+/** A region's lines under `choice`; undecided, they are yours, as the merge left them. */
+const regionLines = (region, choice) => {
+    const yours = linesOf(region.branch, region.lines);
+    // Counted, as the branch's are: joined, one blank line reads as none.
+    const latest = linesOf(region.base, region.baseLines);
+    if (choice === 'latest')
+        return latest;
+    if (choice === 'both')
+        return [...latest, ...yours];
+    return yours;
+};
+/**
+ * The text the merge left with each region as `regions` chooses it. A region's lines sit where the
+ * merge put yours (`TextConflictRegion.line`), so regions are placed from the last up.
+ * @internal Exported for tests.
+ */
+export function textWithChoices(text, regions) {
+    const endBreak = text.merged.endsWith('\n');
+    const body = endBreak ? text.merged.slice(0, -1) : text.merged;
+    const lines = body === '' && !endBreak ? [] : body.split('\n');
+    for (let i = text.regions.length - 1; i >= 0; i--) {
+        const region = text.regions[i];
+        lines.splice(region.line, region.lines, ...regionLines(region, regions[i]));
+    }
+    const joined = lines.join('\n');
+    return endBreak ? `${joined}\n` : joined;
+}
+/** What the form would hold at the conflict's place under `choice`, given your saved value. */
+const expectedUnder = (field, choice, saved) => {
+    if (!choice || choice.how === 'yours')
+        return { from: saved };
+    if (choice.how === 'latest')
+        return field.latest ? { from: field.latest } : undefined;
+    if (choice.how === 'regions' && field.text)
+        return { text: textWithChoices(field.text, choice.regions) };
+    return undefined;
+};
+/**
+ * Whether the form still holds the conflict's place as the last choice (or, before any, your saved
+ * value) left it. False once it was edited by hand: a choice would then replace that edit.
+ */
+export function holdsChoice(current, saved, field, choice, bodyField) {
+    const expected = expectedUnder(field, choice, saved);
+    // A place with no path, such as where the entry is, holds nothing the form could edit.
+    if (!expected || field.dataPath.length === 0)
+        return true;
+    if ('text' in expected)
+        return valueAtChange(current, field, bodyField) === expected.text;
+    // An item on the way that the form no longer has holds nothing, though an empty value would
+    // compare equal to the nothing found there.
+    const from = expected.from;
+    const itemGone = field.dataPath.some((segment, i) => 'item' in segment &&
+        valueAtChange(from, { dataPath: field.dataPath.slice(0, i + 1) }, bodyField) !== undefined &&
+        valueAtChange(current, { dataPath: field.dataPath.slice(0, i + 1) }, bodyField) === undefined);
+    if (itemGone)
+        return false;
+    // Long text checks the merged text, which your saved value holds until a region is chosen.
+    if (field.text && (!choice || choice.how === 'yours')) {
+        return valueAtChange(current, field, bodyField) === valueAtChange(saved, field, bodyField);
+    }
+    return holdsAs(current, expected.from, placeOf(field), bodyField);
+}
+/**
+ * `current` with the conflict's place as `source` has it: a list item `source` lacks taken out, or
+ * one `current` lacks put in where `source` has it, through `undo-change.ts`; anything else, an item
+ * both hold included, replaced where it is, by key. Undefined when it can't be placed.
+ */
+const placeFrom = (current, source, field, bodyField) => {
+    const place = placeOf(field);
+    const wanted = valueAtChange(source, place, bodyField);
+    if (wanted === undefined ||
+        (field.item && valueAtChange(current, place, bodyField) === undefined))
+        return setChangeBack(current, source, place, bodyField);
+    return withValueAt(current, place, structuredClone(wanted), bodyField);
+};
+/**
+ * `current` with the latest version at the conflict's place; undefined when it can't be placed, as
+ * where the latest version couldn't be read or doesn't hold the items on the place's path
+ * ({@link FieldConflict.latestPlaceable}).
+ */
+export const withLatest = (current, field, bodyField) => field.latest && field.latestPlaceable
+    ? placeFrom(current, field.latest, field, bodyField)
+    : undefined;
+/** `current` with your saved value back at the conflict's place, as before any choice. */
+export const withYours = (current, saved, field, bodyField) => placeFrom(current, saved, field, bodyField);
+/** `current` with long text as `regions` chooses it. */
+export const withRegions = (current, field, regions, bodyField) => field.text
+    ? withValueAt(current, field, textWithChoices(field.text, regions), bodyField)
+    : undefined;

package/dist/editor/conflict-notice.d.ts

@@ -0,0 +1,25 @@
+/**
+ * What the editor says about a branch's open conflicts outside "Show changes": the open entry's
+ * notice, Submit's reason, the bar's badge and the "Get latest changes" toast. A count is of the
+ * choices left (`MergeConflictsData.openCount`): one per field, and one per entry-level conflict
+ * (`openConflictCount`, merge-conflicts.ts). No copy names a
+ * branch: an author may not know the branch theirs was cut from.
+ */
+import type { MergeConflictListItem } from '../api/merge-conflicts.js';
+/** The notice above an entry's form while it has conflicts; the list item when it is loaded. */
+export declare function entryConflictNotice(item: MergeConflictListItem | undefined): string;
+/** Why Submit for review waits while choices are open. */
+export declare const conflictsSubmitReason: (count: number) => string;
+/** The bar's "Needs action" detail while choices are open. */
+export declare const conflictsHoldMessage: (count: number) => string;
+/**
+ * The "Get latest changes" toast when the merge left choices; undefined: not yet counted. None
+ * left is a plain success, which base-update-wait.ts says instead.
+ */
+export declare const latestChangesConflictsMessage: (count: number | undefined) => string;
+/** The bar's "Needs action" detail while the branch's record of conflicts is held. */
+export declare const conflictRecordHeldMessage = "This branch's record of conflicts was damaged and set aside, so it's on hold: it can't be submitted or approved until an admin releases the hold.";
+/** The same, to an admin, who has the way out beside it. */
+export declare const conflictRecordHeldAdminMessage = "This branch's record of conflicts was damaged and set aside, so it's on hold: it can't be submitted or approved. Use \"Release hold\" to let it go on.";
+/** What "Release hold" gives up, in its confirm. */
+export declare const releaseHoldConsequences = "Releasing lets this branch be submitted and approved again. The list of fields that needed a choice is lost for good: each field keeps the value it has now, and no one will be asked to choose. Check the branch's changes first.";

package/dist/editor/conflict-notice.js

@@ -0,0 +1,39 @@
+/**
+ * What the editor says about a branch's open conflicts outside "Show changes": the open entry's
+ * notice, Submit's reason, the bar's badge and the "Get latest changes" toast. A count is of the
+ * choices left (`MergeConflictsData.openCount`): one per field, and one per entry-level conflict
+ * (`openConflictCount`, merge-conflicts.ts). No copy names a
+ * branch: an author may not know the branch theirs was cut from.
+ */
+/** "1 field needs", "2 fields need". */
+const fieldsNeed = (count) => count === 1 ? '1 field needs' : `${count} fields need`;
+const CHOOSE = 'Choose what to keep in "Show changes".';
+/** The notice above an entry's form while it has conflicts; the list item when it is loaded. */
+export function entryConflictNotice(item) {
+    switch (item?.kind) {
+        case 'deleted-on-base':
+            return `This entry was deleted in the latest version, but you changed it. ${CHOOSE}`;
+        case 'unreadable':
+        case 'deleted-on-branch':
+            return `This entry was changed by you and by someone else. ${CHOOSE}`;
+        case 'fields':
+            return `${item.fieldCount === 1 ? '1 field was' : `${item.fieldCount} fields were`} changed by you and by someone else. ${CHOOSE}`;
+        default:
+            return `Some fields were changed by you and by someone else. ${CHOOSE}`;
+    }
+}
+/** Why Submit for review waits while choices are open. */
+export const conflictsSubmitReason = (count) => `${fieldsNeed(count)} your choice before this branch can be submitted. Choose what to keep in "Show changes" on each flagged entry.`;
+/** The bar's "Needs action" detail while choices are open. */
+export const conflictsHoldMessage = (count) => `${fieldsNeed(count)} your choice: changed by you and by someone else. Choose what to keep in "Show changes" on each flagged entry, then submit.`;
+/**
+ * The "Get latest changes" toast when the merge left choices; undefined: not yet counted. None
+ * left is a plain success, which base-update-wait.ts says instead.
+ */
+export const latestChangesConflictsMessage = (count) => `Latest changes added. ${count === undefined ? 'Some fields need' : fieldsNeed(count)} your choice.`;
+/** The bar's "Needs action" detail while the branch's record of conflicts is held. */
+export const conflictRecordHeldMessage = "This branch's record of conflicts was damaged and set aside, so it's on hold: it can't be submitted or approved until an admin releases the hold.";
+/** The same, to an admin, who has the way out beside it. */
+export const conflictRecordHeldAdminMessage = "This branch's record of conflicts was damaged and set aside, so it's on hold: it can't be submitted or approved. Use \"Release hold\" to let it go on.";
+/** What "Release hold" gives up, in its confirm. */
+export const releaseHoldConsequences = "Releasing lets this branch be submitted and approved again. The list of fields that needed a choice is lost for good: each field keeps the value it has now, and no one will be asked to choose. Check the branch's changes first.";

package/dist/editor/copy.d.ts

@@ -9,6 +9,7 @@ export declare const EDITOR_ACTIONS: {
     readonly refreshFromServer: "Refresh from server";
     readonly submitForReview: "Submit for review";
     readonly withdrawFromReview: "Withdraw from review";
+    readonly getLatestChanges: "Get latest changes";
     readonly approve: "Approve";
     readonly review: "Review";
     readonly requestChanges: "Request changes";
@@ -22,7 +23,24 @@ export declare const EDITOR_ACTIONS: {
     readonly changeUrl: "Change URL";
     readonly changeSlug: "Change slug";
     readonly showChanges: "Show changes";
+    readonly undoChange: "Undo change";
+    readonly redoChange: "Redo change";
+    readonly undoAllChanges: "Undo all changes";
+    readonly redoAllChanges: "Redo all changes";
+    readonly restoreEntry: "Restore entry";
+    readonly deleteEntry: "Delete entry";
+    readonly useLatestVersion: "Use latest version";
+    readonly keepYourVersion: "Keep your version";
+    readonly useBoth: "Use both";
+    readonly markResolved: "Mark resolved";
+    readonly releaseHold: "Release hold";
+    readonly removeIt: "Remove it";
+    readonly keepIt: "Keep it";
+    readonly keepItDeleted: "Keep it deleted";
+    readonly chooseAgain: "Choose again";
 };
+/** Withdraw's confirm on a branch that conflicts with its base, which then gets the latest changes. */
+export declare const WITHDRAW_AND_GET_LATEST = "Withdraw and get latest changes";
 /**
  * Why a list at its `maxItems` adds nothing more, as a disabled Add's Tooltip or an input's hint.
  * `one` and `many` name what the list holds.
@@ -35,6 +53,8 @@ export declare const rewrittenSubmitReason: (isAdmin: boolean) => string;
  * says how to finish the submit, where it can be retried at all.
  */
 export declare const UNFINISHED_SUBMIT_APPROVE_REASON = "The last submit didn't finish, so this branch can't be approved yet. Use \"Request changes\" to send it back to its editor.";
+/** Why an entry's form, and every control that would change the entry, can't act for this user. */
+export declare const NO_EDIT_ACCESS_REASON = "You don't have edit access to this entry. Ask a CanopyCMS admin to grant it.";
 /** Why only an admin may delete a branch that may hold commits nothing else has. */
 export declare const DELETE_NEEDS_ADMIN_REASON = "This branch may hold changes that are missing from GitHub. Ask an admin to check it before deleting it.";
 /** Why Approve and Request changes can't act: the pull request they act on is gone. */

package/dist/editor/copy.js

@@ -9,6 +9,7 @@ export const EDITOR_ACTIONS = {
     refreshFromServer: 'Refresh from server',
     submitForReview: 'Submit for review',
     withdrawFromReview: 'Withdraw from review',
+    getLatestChanges: 'Get latest changes',
     approve: 'Approve',
     review: 'Review',
     requestChanges: 'Request changes',
@@ -22,7 +23,24 @@ export const EDITOR_ACTIONS = {
     changeUrl: 'Change URL',
     changeSlug: 'Change slug',
     showChanges: 'Show changes',
+    undoChange: 'Undo change',
+    redoChange: 'Redo change',
+    undoAllChanges: 'Undo all changes',
+    redoAllChanges: 'Redo all changes',
+    restoreEntry: 'Restore entry',
+    deleteEntry: 'Delete entry',
+    useLatestVersion: 'Use latest version',
+    keepYourVersion: 'Keep your version',
+    useBoth: 'Use both',
+    markResolved: 'Mark resolved',
+    releaseHold: 'Release hold',
+    removeIt: 'Remove it',
+    keepIt: 'Keep it',
+    keepItDeleted: 'Keep it deleted',
+    chooseAgain: 'Choose again',
 };
+/** Withdraw's confirm on a branch that conflicts with its base, which then gets the latest changes. */
+export const WITHDRAW_AND_GET_LATEST = 'Withdraw and get latest changes';
 /**
  * Why a list at its `maxItems` adds nothing more, as a disabled Add's Tooltip or an input's hint.
  * `one` and `many` name what the list holds.
@@ -37,6 +55,8 @@ export const rewrittenSubmitReason = (isAdmin) => isAdmin
  * says how to finish the submit, where it can be retried at all.
  */
 export const UNFINISHED_SUBMIT_APPROVE_REASON = 'The last submit didn\'t finish, so this branch can\'t be approved yet. Use "Request changes" to send it back to its editor.';
+/** Why an entry's form, and every control that would change the entry, can't act for this user. */
+export const NO_EDIT_ACCESS_REASON = "You don't have edit access to this entry. Ask a CanopyCMS admin to grant it.";
 /** Why only an admin may delete a branch that may hold commits nothing else has. */
 export const DELETE_NEEDS_ADMIN_REASON = 'This branch may hold changes that are missing from GitHub. Ask an admin to check it before deleting it.';
 /** Why Approve and Request changes can't act: the pull request they act on is gone. */

package/dist/editor/entry-diff.d.ts

@@ -99,9 +99,22 @@ export type DisplayValue = {
     kind: 'raw';
     text: string;
 };
+/**
+ * One step into a form value: a record's member, a list item by its item key, or a block item's
+ * data, which is its `value` record or, in the inline `_type` shape, the item itself.
+ */
+export type DataPathSegment = {
+    field: string;
+} | {
+    item: string;
+} | {
+    blockData: true;
+};
 export interface EntryChange {
     /** Stable among one diff's changes: its data path, list items named by key. */
     key: string;
+    /** Where the change is in the form value; absent for the entry type, which no field holds. */
+    dataPath?: DataPathSegment[];
     /** Human labels from the entry down to the change: "Page sections › Hero › Heading". */
     path: string[];
     kind: 'added' | 'removed' | 'changed' | 'moved';
@@ -127,6 +140,8 @@ export interface EntryDiffInput {
     after: EntryChangeSide | null;
     /** A referenced entry's title, from the entries the editor has listed. */
     referenceTitle?: (id: string) => string | undefined;
+    /** False when only which changes there are matters: no text is diffed for its marks. */
+    marks?: boolean;
 }
 /**
  * The difference between two texts. Short single-line text is diffed by word; anything else by
@@ -136,8 +151,9 @@ export interface EntryDiffInput {
  * text's spacing, so one side read back from its parts would not be the text it was.
  * Undefined once `deadline` (a `Date.now()`) passes: no line diff starts after it. A short word
  * diff runs until the later `wordDeadline`.
- * @internal Exported for tests.
  */
 export declare function textDiff(before: string, after: string, long?: boolean, deadline?: number, wordDeadline?: number): TextDiff | undefined;
+/** `value` of `field` as the drawer shows it whole, for a value a conflict compares whole. */
+export declare function displayWhole(field: FieldConfig | undefined, value: unknown, referenceTitle?: (id: string) => string | undefined): DisplayValue;
 /** The entry's changes between `before` and `after`, in schema order. */
-export declare function computeEntryDiff({ fields, before, after, referenceTitle, }: EntryDiffInput): EntryDiff;
+export declare function computeEntryDiff({ fields, before, after, referenceTitle, marks, }: EntryDiffInput): EntryDiff;

package/dist/editor/entry-diff.js

@@ -5,8 +5,8 @@
  * so a reordered item reads as moved, not as one removed and one added.
  */
 import { diffLines, diffWordsWithSpace } from 'diff';
-import equal from 'fast-deep-equal';
 import { ITEM_KEY } from '../item-keys.js';
+import { isEmptyValue as isEmpty, normalizedValue as normalized, sameValue, } from '../merge/value-equality.js';
 import { findBodyFieldName } from '../utils/body-field.js';
 import { isCalendarDay, localMidnight } from '../utils/calendar-day.js';
 import { flattenGroupFields } from '../utils/flatten-group-fields.js';
@@ -40,33 +40,18 @@ const formValue = (fields, side) => {
         return side.data;
     return { ...side.data, [side.bodyFieldName ?? findBodyFieldName(fields)]: side.body };
 };
-const isEmpty = (value) => value === undefined ||
-    value === null ||
-    value === '' ||
-    (Array.isArray(value) && value.length === 0) ||
-    (isPlainRecord(value) && Object.keys(value).every((k) => k === ITEM_KEY || isEmpty(value[k])));
-/** `value` without item keys and empty members, so equal content compares equal. */
-const normalized = (value) => {
-    if (Array.isArray(value))
-        return value.map(normalized);
-    if (!isPlainRecord(value))
-        return value;
-    const out = {};
-    for (const [k, v] of Object.entries(value)) {
-        if (k !== ITEM_KEY && !isEmpty(v))
-            out[k] = normalized(v);
-    }
-    return out;
-};
-const sameValue = (a, b) => (isEmpty(a) && isEmpty(b)) || equal(normalized(a), normalized(b));
-const at = (parent, label, key) => ({
+const at = (parent, label, key, segment) => ({
     path: [...parent.path, label],
     key: parent.key ? `${parent.key}.${key}` : key,
+    ...(parent.segments && segment && { segments: [...parent.segments, segment] }),
 });
+/** `where`'s data path as a change carries it. */
+const dataPathOf = (where) => where.segments ? { dataPath: where.segments } : {};
 /** A member the schema doesn't name, under an "Other fields" crumb. */
 const otherAt = (parent, name) => ({
     path: [...parent.path, OTHER_FIELDS_LABEL, humanizeName(name)],
     key: `${parent.key}?${name}`,
+    ...(parent.segments && { segments: [...parent.segments, { field: name }] }),
 });
 /** The file name of an image `src`, its query and fragment dropped. */
 const fileName = (src) => {
@@ -245,7 +230,7 @@ class Walker {
         const flat = flattenGroupFields(fields);
         const known = new Set(flat.map((f) => f.name));
         for (const field of flat) {
-            this.field(field, before?.[field.name], after?.[field.name], at(where, schemaLabel(field), field.name));
+            this.field(field, before?.[field.name], after?.[field.name], at(where, schemaLabel(field), field.name, { field: field.name }));
         }
         const others = new Set([...Object.keys(before ?? {}), ...Object.keys(after ?? {})]);
         for (const name of others) {
@@ -287,7 +272,7 @@ class Walker {
         if (sameValue(before, after) || sameInstant(field, before, after))
             return;
         const kind = isEmpty(before) ? 'added' : isEmpty(after) ? 'removed' : 'changed';
-        const change = { key: where.key, path: where.path, kind };
+        const change = { key: where.key, ...dataPathOf(where), path: where.path, kind };
         if (kind !== 'added')
             change.before = this.display(field, before);
         if (kind !== 'removed')
@@ -337,13 +322,15 @@ class Walker {
         const a = isPlainRecord(after) ? resolveBlockItem(field, after) : undefined;
         const sameTemplate = isPlainRecord(before) && isPlainRecord(after) && before.template === after.template;
         if (b && a && sameTemplate) {
-            this.fields(a.fields, b.data, a.data, where);
+            const data = where.segments && { segments: [...where.segments, { blockData: true }] };
+            this.fields(a.fields, b.data, a.data, { ...where, ...data });
             return;
         }
         if (sameValue(before, after))
             return;
         this.changes.push({
             key: where.key,
+            ...dataPathOf(where),
             path: where.path,
             kind: 'changed',
             before: this.blockRecord(field, before),
@@ -373,10 +360,11 @@ class Walker {
             const from = bIndex.get(key);
             // A matched item is named as it was at the base, so a change to its title doesn't rename
             // the path to it.
-            const itemAt = at(where, from === undefined ? item.heading(value, index) : item.heading(bItems[from], from), key);
+            const itemAt = at(where, from === undefined ? item.heading(value, index) : item.heading(bItems[from], from), key, { item: key });
             if (from === undefined) {
                 this.changes.push({
                     key: itemAt.key,
+                    ...dataPathOf(itemAt),
                     path: itemAt.path,
                     kind: 'added',
                     item: true,
@@ -387,6 +375,7 @@ class Walker {
             if (!stayed.has(key)) {
                 this.changes.push({
                     key: `${itemAt.key}#moved`,
+                    ...dataPathOf(itemAt),
                     path: itemAt.path,
                     kind: 'moved',
                     item: true,
@@ -400,9 +389,10 @@ class Walker {
             const key = bKeys[index];
             if (aSet.has(key))
                 return;
-            const itemAt = at(where, item.heading(value, index), key);
+            const itemAt = at(where, item.heading(value, index), key, { item: key });
             this.changes.push({
                 key: itemAt.key,
+                ...dataPathOf(itemAt),
                 path: itemAt.path,
                 kind: 'removed',
                 item: true,
@@ -496,7 +486,6 @@ const splitLines = (value) => {
  * text's spacing, so one side read back from its parts would not be the text it was.
  * Undefined once `deadline` (a `Date.now()`) passes: no line diff starts after it. A short word
  * diff runs until the later `wordDeadline`.
- * @internal Exported for tests.
  */
 export function textDiff(before, after, long = false, deadline = Date.now() + DIFF_TIMEOUT_MS, wordDeadline = Date.now() + SHORT_DIFF_TIMEOUT_MS) {
     // jsdiff restarts its clock on each call, so each is given only what is left of the budget.
@@ -584,12 +573,17 @@ const withContext = (lines) => {
     }
     return out;
 };
+/** `value` of `field` as the drawer shows it whole, for a value a conflict compares whole. */
+export function displayWhole(field, value, referenceTitle) {
+    return new Walker(referenceTitle, 0, 0).display(field, value);
+}
 /** The entry's changes between `before` and `after`, in schema order. */
-export function computeEntryDiff({ fields, before, after, referenceTitle, }) {
-    // One budget for the whole entry: see DIFF_TIMEOUT_MS and SHORT_DIFF_TIMEOUT_MS.
-    const started = Date.now();
-    const walker = new Walker(referenceTitle, started + DIFF_TIMEOUT_MS, started + SHORT_DIFF_TIMEOUT_MS);
-    const root = { path: [], key: '' };
+export function computeEntryDiff({ fields, before, after, referenceTitle, marks = true, }) {
+    // One budget for the whole entry: see DIFF_TIMEOUT_MS and SHORT_DIFF_TIMEOUT_MS. Without
+    // marks, both deadlines have passed before the walk starts.
+    const started = marks ? Date.now() : 0;
+    const walker = new Walker(referenceTitle, started + (marks ? DIFF_TIMEOUT_MS : 0), started + (marks ? SHORT_DIFF_TIMEOUT_MS : 0));
+    const root = { path: [], key: '', segments: [] };
     if (before && after && before.entryType !== after.entryType) {
         walker.value(undefined, humanizeName(before.entryType), humanizeName(after.entryType), at(root, 'Entry type', '$entryType'));
     }

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

@@ -0,0 +1,36 @@
+import type { BranchListItem } from '../../api/branch.js';
+import type { OperatingMode } from '../../operating-mode/types.js';
+import { type BaseUpdateWait } from '../base-update-wait.js';
+export interface UseBaseUpdateOptions {
+    /** The open branch. */
+    branch: BranchListItem | undefined;
+    operatingMode: OperatingMode;
+    /** The user may take the branch's workflow actions, which asking for the latest changes is. */
+    permitted: boolean;
+    /** Entries with unsaved changes on the branch; asking waits until they are saved. */
+    unsavedCount: number;
+    /** Re-read the branch's entries and the open one, keeping drafts: the worker rewrote them. */
+    onUpdated: () => void;
+    /** Opens the branch's conflicts, offered by the toast of a merge that left some. */
+    onShowConflicts?: () => void;
+}
+export interface UseBaseUpdateReturn {
+    /** "Get latest changes" applies here: a worker answers, the branch is editing, the user may ask. */
+    available: boolean;
+    /** The open branch's wait; `waiting` makes its form read-only. */
+    wait: BaseUpdateWait;
+    /** The open branch's request itself is in flight. */
+    requesting: boolean;
+    /** Why it can't be asked now; undefined when it can. */
+    blockedReason?: string;
+    /** Asks for the open branch, unless unsaved changes hold it. */
+    request: () => Promise<void>;
+}
+/**
+ * "Get latest changes" for the open branch: asks, then re-reads the branch list while the branch
+ * waits, and reports the worker's answer in a toast once it lands. Only a wait this tab saw end
+ * reports, so a reload onto an answered request stays quiet. The wait is timed by the server's
+ * clock (server-clock.ts), and a request this tab made counts even when a listing fetched before
+ * it lands after it.
+ */
+export declare function useBaseUpdate(options: UseBaseUpdateOptions): UseBaseUpdateReturn;