Co-authored-by: Steve Dudenhoeffer <[email protected]>
This commit was merged in pull request #63.
This commit is contained in:
@@ -0,0 +1,226 @@
|
||||
// Change history and undo (#49): zod-validated shapes for /gardens/:id/history
|
||||
// and /change-sets/:id/revert, plus the hooks the editor's History tab uses.
|
||||
//
|
||||
// A revert is a real write that can partly succeed, so its mutation is unusual:
|
||||
// a 409 is not a plain failure. It carries the change set that DID apply
|
||||
// alongside the entities it deliberately left alone, and the caller is expected
|
||||
// to report both.
|
||||
|
||||
import { useState } from 'react'
|
||||
import { useInfiniteQuery, useMutation, useQueryClient } from '@tanstack/react-query'
|
||||
import { z } from 'zod'
|
||||
import { ApiError, api, errorMessage } from './api'
|
||||
import { gardenFullKey } from './objects'
|
||||
|
||||
export const changeSourceSchema = z.enum(['ui', 'agent', 'api'])
|
||||
export type ChangeSource = z.infer<typeof changeSourceSchema>
|
||||
|
||||
export const changeCountSchema = z.object({
|
||||
entityType: z.enum(['garden', 'object', 'planting']),
|
||||
op: z.enum(['create', 'update', 'delete']),
|
||||
// COUNT(*) can only ever be a non-negative integer; constraining it means bad
|
||||
// data fails loudly rather than quietly hiding an Undo button (totalChanges
|
||||
// gates it) or rendering "1.5 beds changed".
|
||||
n: z.number().int().nonnegative(),
|
||||
})
|
||||
export type ChangeCount = z.infer<typeof changeCountSchema>
|
||||
|
||||
export const changeSetSchema = z.object({
|
||||
id: z.number(),
|
||||
gardenId: z.number(),
|
||||
actorId: z.number(),
|
||||
actorName: z.string().default(''),
|
||||
source: changeSourceSchema,
|
||||
summary: z.string(),
|
||||
agentRunId: z.string().optional(),
|
||||
// Set when this change set reverts another.
|
||||
revertsId: z.number().optional(),
|
||||
// Set when another change set reverted this one.
|
||||
revertedById: z.number().optional(),
|
||||
counts: z.array(changeCountSchema).default([]),
|
||||
createdAt: z.string(),
|
||||
})
|
||||
export type ChangeSet = z.infer<typeof changeSetSchema>
|
||||
|
||||
export const revertConflictSchema = z.object({
|
||||
entityType: z.enum(['garden', 'object', 'planting']),
|
||||
entityId: z.number(),
|
||||
reason: z.enum(['changed', 'missing', 'exists', 'unsupported']),
|
||||
name: z.string().optional(),
|
||||
})
|
||||
export type RevertConflict = z.infer<typeof revertConflictSchema>
|
||||
|
||||
const historyPageSchema = z.object({
|
||||
changeSets: z.array(changeSetSchema),
|
||||
hasMore: z.boolean(),
|
||||
})
|
||||
|
||||
const revertResultSchema = z.object({
|
||||
changeSet: changeSetSchema.nullable(),
|
||||
conflicts: z.array(revertConflictSchema).default([]),
|
||||
})
|
||||
export type RevertResult = z.infer<typeof revertResultSchema>
|
||||
|
||||
const PAGE_SIZE = 30
|
||||
|
||||
export function historyKey(gardenId: number) {
|
||||
return ['gardens', gardenId, 'history'] as const
|
||||
}
|
||||
|
||||
/** A garden's change sets, newest first, paged on demand. */
|
||||
export function useGardenHistory(gardenId: number, enabled = true) {
|
||||
return useInfiniteQuery({
|
||||
queryKey: historyKey(gardenId),
|
||||
enabled,
|
||||
initialPageParam: 0,
|
||||
queryFn: async ({ pageParam }) =>
|
||||
historyPageSchema.parse(
|
||||
await api.get(`/gardens/${gardenId}/history`, { params: { limit: PAGE_SIZE, offset: pageParam } }),
|
||||
),
|
||||
// Offset paging, not cursor: history is append-only at the FRONT, so a new
|
||||
// entry arriving mid-scroll shifts the window by one. That's a duplicate row
|
||||
// at worst, and the alternative (a cursor on created_at) buys little for a
|
||||
// list you scroll a page or two of.
|
||||
getNextPageParam: (last, pages) => (last.hasMore ? pages.length * PAGE_SIZE : undefined),
|
||||
})
|
||||
}
|
||||
|
||||
/** The conflicts carried by a 409 from a revert, or null if this isn't one. */
|
||||
export function revertConflicts(err: unknown): RevertResult | null {
|
||||
if (!(err instanceof ApiError) || err.status !== 409) return null
|
||||
const parsed = revertResultSchema.safeParse(err.body)
|
||||
return parsed.success ? parsed.data : null
|
||||
}
|
||||
|
||||
/**
|
||||
* Undo a change set. Invalidates the editor payload so the canvas redraws, and
|
||||
* the history list so the new entry (and the "reverted" mark on its target)
|
||||
* appear — on failure too, because a 409 means part of it applied.
|
||||
*/
|
||||
export function useRevertChangeSet(gardenId: number) {
|
||||
const qc = useQueryClient()
|
||||
const refresh = () => {
|
||||
void qc.invalidateQueries({ queryKey: gardenFullKey(gardenId) })
|
||||
void qc.invalidateQueries({ queryKey: historyKey(gardenId) })
|
||||
}
|
||||
return useMutation({
|
||||
mutationFn: async (changeSetId: number): Promise<RevertResult> =>
|
||||
revertResultSchema.parse(await api.post(`/change-sets/${changeSetId}/revert`, undefined)),
|
||||
onSuccess: refresh,
|
||||
onError: (err) => {
|
||||
if (revertConflicts(err)) refresh() // a partial revert still changed things
|
||||
},
|
||||
})
|
||||
}
|
||||
|
||||
/** How many rows a change set touched, for "3 changes" in the list. */
|
||||
export function totalChanges(cs: ChangeSet): number {
|
||||
return cs.counts.reduce((sum, c) => sum + c.n, 0)
|
||||
}
|
||||
|
||||
const ENTITY_NOUNS: Record<ChangeCount['entityType'], [string, string]> = {
|
||||
garden: ['garden setting', 'garden settings'],
|
||||
object: ['bed', 'beds'],
|
||||
planting: ['planting', 'plantings'],
|
||||
}
|
||||
|
||||
const OP_VERBS: Record<ChangeCount['op'], string> = {
|
||||
create: 'added',
|
||||
update: 'changed',
|
||||
delete: 'removed',
|
||||
}
|
||||
|
||||
/**
|
||||
* The change set's counts as a human phrase: "3 plantings added, 1 bed changed".
|
||||
* Returns '' when there's nothing to say, so callers can skip the line entirely
|
||||
* rather than render "0 changes".
|
||||
*/
|
||||
export function describeCounts(cs: ChangeSet): string {
|
||||
return cs.counts
|
||||
.filter((c) => c.n > 0)
|
||||
.map((c) => {
|
||||
const [one, many] = ENTITY_NOUNS[c.entityType]
|
||||
return `${c.n} ${c.n === 1 ? one : many} ${OP_VERBS[c.op]}`
|
||||
})
|
||||
.join(', ')
|
||||
}
|
||||
|
||||
/** What a revert left alone, phrased for the person who asked for the undo. */
|
||||
export function describeConflict(c: RevertConflict): string {
|
||||
const noun = c.name ? `“${c.name}”` : `that ${ENTITY_NOUNS[c.entityType][0]}`
|
||||
switch (c.reason) {
|
||||
case 'changed':
|
||||
return `${noun} was edited since, so it was left alone`
|
||||
case 'missing':
|
||||
return `${noun} no longer exists`
|
||||
case 'exists':
|
||||
return `${noun} exists again, so it wasn't restored over the top`
|
||||
case 'unsupported':
|
||||
return `${noun} can't be undone automatically`
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* The one undo implementation, shared by the history list and (per #49) the
|
||||
* agent turn's inline Undo in #57 — so an undo behaves identically wherever it
|
||||
* is offered, including how it explains a partial result.
|
||||
*
|
||||
* Outcomes are keyed by change set id, so a single instance serves a whole list.
|
||||
*/
|
||||
export function useUndo(gardenId: number) {
|
||||
const revert = useRevertChangeSet(gardenId)
|
||||
const [outcomes, setOutcomes] = useState<Record<number, UndoOutcome>>({})
|
||||
|
||||
const undo = (cs: ChangeSet) => {
|
||||
setOutcomes((prev) => ({ ...prev, [cs.id]: { tone: 'pending', message: 'Undoing…' } }))
|
||||
revert.mutate(cs.id, {
|
||||
onSuccess: (result) => {
|
||||
setOutcomes((prev) => ({ ...prev, [cs.id]: describeUndo(cs, result) }))
|
||||
},
|
||||
onError: (err) => {
|
||||
const result = revertConflicts(err)
|
||||
setOutcomes((prev) => ({
|
||||
...prev,
|
||||
[cs.id]: result
|
||||
? describeUndo(cs, result)
|
||||
: { tone: 'error', message: errorMessage(err, "That couldn't be undone.") },
|
||||
}))
|
||||
},
|
||||
})
|
||||
}
|
||||
|
||||
return {
|
||||
undo,
|
||||
// Per change set rather than a single global flag, so one row's pending
|
||||
// state can't disable the others.
|
||||
outcomeFor: (id: number): UndoOutcome | undefined => outcomes[id],
|
||||
}
|
||||
}
|
||||
|
||||
export interface UndoOutcome {
|
||||
tone: 'pending' | 'ok' | 'partial' | 'error'
|
||||
message: string
|
||||
}
|
||||
|
||||
/**
|
||||
* What actually happened, said in full. A revert can partly succeed, and "2 of 3
|
||||
* changes undone — “north bed” was edited since and was left alone" is the only
|
||||
* useful thing to report: a bare failure would be a lie about the two that did
|
||||
* apply, and a bare success would hide the one that didn't.
|
||||
*/
|
||||
export function describeUndo(target: ChangeSet, result: RevertResult): UndoOutcome {
|
||||
const skipped = result.conflicts.map(describeConflict).join('; ')
|
||||
const applied = result.changeSet ? totalChanges(result.changeSet) : 0
|
||||
if (result.conflicts.length === 0) {
|
||||
// The server answers 200 with a null change set when every revision was
|
||||
// already a no-op — reachable by undoing a creation whose object is gone.
|
||||
// Claiming "Undone." there would be reporting work that didn't happen.
|
||||
if (applied === 0) return { tone: 'ok', message: 'Nothing left to undo — this was already reversed.' }
|
||||
return { tone: 'ok', message: 'Undone.' }
|
||||
}
|
||||
if (applied === 0) {
|
||||
return { tone: 'error', message: `Nothing was undone — ${skipped}.` }
|
||||
}
|
||||
const total = totalChanges(target)
|
||||
return { tone: 'partial', message: `${applied} of ${total} changes undone — ${skipped}.` }
|
||||
}
|
||||
Reference in New Issue
Block a user