@manta-eu/react 0.11.0 → 0.13.0

package/src/components/plan-limits/PlanLimitsDialog.tsx

@@ -0,0 +1,331 @@
+import { humanCount } from "@manta-eu/lib/humanize";
+import { isPresent } from "@manta-eu/lib/present";
+import { format, isValid, parse } from "date-fns";
+import { useEffect, useId, useMemo, useState } from "react";
+import { match } from "ts-pattern";
+import {
+  buildPlanLimitChanges,
+  buildPlanLimitsModel,
+  type PlanLimitChange,
+  type PlanLimitLock,
+  type PlanLimitRow,
+  type PlanLimitRule,
+  type PlanLimitRuleModel,
+  planLimitControlLabel,
+  planLimitsCanSave,
+  planLimitSentences,
+  sliderRangeFor,
+} from "./plan-limits-model";
+import { messageOf, type PlanLimitsSaveResult } from "./plan-limits-save";
+import { Banner } from "#components/banner/index";
+import { Button } from "#components/button/index";
+import { Input, InputDate } from "#components/input/index";
+import { Loader } from "#components/loader/index";
+import {
+  Dialog,
+  DialogBody,
+  DialogClose,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from "#components/modal/index";
+import { Slider } from "#components/slider/index";
+import { RuleNarrativeSegments } from "#ldo-ui";
+import { ruleValueInputDescriptors } from "#routes/rules/components/rule-value-input";
+import { getRuleDisplayName } from "#routes/rules/components/rules.utils";
+
+export type PlanLimitsDialogProps = {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  rules: readonly PlanLimitRule[];
+  onSave: (changes: readonly PlanLimitChange[]) => Promise<PlanLimitsSaveResult>;
+  isLoading?: boolean;
+  isSaving?: boolean;
+  error?: string | null;
+  /** Rules the dialog does not show, when the plan has more than the page read. */
+  omittedRules?: number;
+};
+
+export const planLimitsDialogTitle = "This plan's limits";
+export const planLimitsDialogDescription =
+  "The numbers and dates this plan's rules use. Saving updates the recommended changes now; Manta acts on them at the plan's next run.";
+export const planLimitsEmptyText = "This plan's rules carry no value to edit.";
+export const planLimitsNothingEditableText = "None of these rules can be edited here. Each one says why.";
+export const planLimitLockNotes: Record<PlanLimitLock, string> = {
+  manta: "Manta maintains this rule, so it can't be edited here.",
+  staged: "This rule has a change staged on its rule page. Commit or clear it there first.",
+};
+
+const numberFormat = new Intl.NumberFormat("en-US", { maximumFractionDigits: 4 });
+/** A rule's date literal is a plain ISO day. */
+const ruleDateFormat = "yyyy-MM-dd";
+
+function dateOf(value: string): Date | undefined {
+  const date = parse(value, ruleDateFormat, new Date());
+  return isValid(date) ? date : undefined;
+}
+
+export function PlanLimitsDialog(props: PlanLimitsDialogProps) {
+  const { open, onOpenChange, rules, onSave, isLoading = false, isSaving = false, error, omittedRules = 0 } = props;
+  const [values, setValues] = useState<Record<string, string>>({});
+  const [saveError, setSaveError] = useState<string>();
+  const [submitting, setSubmitting] = useState(false);
+
+  const model = useMemo(() => buildPlanLimitsModel(rules), [rules]);
+  const build = useMemo(() => buildPlanLimitChanges(model, values), [model, values]);
+
+  useEffect(() => {
+    setValues({});
+    setSaveError(undefined);
+  }, [open]);
+
+  const hasEditableRows = isPresent(model.editableRows);
+  const notShown = omittedRules + model.unparsable.length;
+  const busy = isSaving || submitting;
+  const canSave = planLimitsCanSave(build) && !busy;
+  const changedRuleIris = new Set(build.changes.map((change) => change.ruleIri));
+  const changedValues = model.editableRows.filter(
+    (row) => changedRuleIris.has(row.ruleIri) && values[row.id] !== undefined && values[row.id] !== row.edit.value,
+  ).length;
+
+  async function handleSave() {
+    if (!canSave) return;
+    setSaveError(undefined);
+    setSubmitting(true);
+    try {
+      const result = await onSave(build.changes);
+      if (result.ok) onOpenChange(false);
+      else setSaveError(result.error);
+    } catch (err: unknown) {
+      setSaveError(messageOf(err, "The limits could not be saved"));
+    } finally {
+      setSubmitting(false);
+    }
+  }
+
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent size="lg" fullScreenOnMobile>
+        <DialogHeader>
+          <DialogTitle text={planLimitsDialogTitle} />
+          <DialogDescription>{planLimitsDialogDescription}</DialogDescription>
+        </DialogHeader>
+        <DialogBody className="flex flex-col gap-7">
+          {isLoading && (
+            <div className="flex items-center gap-2 typography-small text-muted-foreground">
+              <Loader className="size-4" />
+              Loading the plan's rules...
+            </div>
+          )}
+          {!isLoading && isPresent(error) && <Banner label={error} />}
+          {!isLoading && !isPresent(error) && !isPresent(model.rows) && (
+            <p className="typography-small text-muted-foreground">{planLimitsEmptyText}</p>
+          )}
+          {!isLoading && isPresent(model.rows) && !hasEditableRows && (
+            <p className="typography-small text-muted-foreground">{planLimitsNothingEditableText}</p>
+          )}
+          {model.rules.map((rule) => (
+            <PlanLimitRuleView
+              key={rule.ruleIri}
+              rule={rule}
+              values={values}
+              fieldErrors={build.fieldErrors}
+              ruleError={build.ruleErrors[rule.ruleIri]}
+              disabled={busy}
+              onChange={(row, value) => setValues((current) => ({ ...current, [row.id]: value }))}
+            />
+          ))}
+          {(hasEditableRows || notShown > 0) && (
+            <dl className="grid grid-cols-[1fr_auto] gap-x-6 gap-y-2 rounded-lg-v4 bg-muted/40 px-4 py-3 typography-small">
+              {hasEditableRows && (
+                <>
+                  <dt className="text-muted-foreground">Values changed</dt>
+                  <dd className="text-right text-default-foreground">{changedValues}</dd>
+                  <dt className="text-muted-foreground">Rules updated on save</dt>
+                  <dd className="text-right text-default-foreground">{build.changes.length}</dd>
+                  <dt className="text-muted-foreground">Recommended changes</dt>
+                  <dd className="text-right text-default-foreground">update on save</dd>
+                  <dt className="text-muted-foreground">Manta acts on them</dt>
+                  <dd className="text-right text-default-foreground">at the plan's next run</dd>
+                </>
+              )}
+              {omittedRules > 0 && (
+                <>
+                  <dt className="text-muted-foreground">Not shown, on the plan's rule pages</dt>
+                  <dd className="text-right text-default-foreground">{humanCount(omittedRules, "rule")}</dd>
+                </>
+              )}
+              {isPresent(model.unparsable) && (
+                <>
+                  <dt className="text-muted-foreground">Not shown, could not be read</dt>
+                  <dd className="text-right text-default-foreground">{humanCount(model.unparsable.length, "rule")}</dd>
+                </>
+              )}
+            </dl>
+          )}
+          {isPresent(saveError) && <Banner label={saveError} />}
+        </DialogBody>
+        <DialogFooter>
+          <DialogClose asChild>
+            <Button variant="tertiary" label="Cancel" disabled={busy} />
+          </DialogClose>
+          <Button label={busy ? "Saving..." : "Save limits"} disabled={!canSave} onClick={() => void handleSave()} />
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  );
+}
+
+type PlanLimitRuleViewProps = {
+  rule: PlanLimitRuleModel;
+  values: Readonly<Record<string, string>>;
+  fieldErrors: Readonly<Record<string, string>>;
+  ruleError: string | undefined;
+  disabled: boolean;
+  onChange: (row: PlanLimitRow, value: string) => void;
+};
+
+/** One rule's limits: each sentence once with its values live, a control per value under it, the rule named once. */
+function PlanLimitRuleView(props: PlanLimitRuleViewProps) {
+  const { rule, values, fieldErrors, ruleError, disabled, onChange } = props;
+  const editable = !rule.lock;
+  const ruleName = getRuleDisplayName(rule.ruleIri);
+  const valueOf = (row: PlanLimitRow) => values[row.id] ?? row.edit.value;
+  const figureOf = (row: PlanLimitRow) => {
+    const value = valueOf(row);
+    const numeric = Number(value);
+    return row.edit.kind === "number" && Number.isFinite(numeric) ? numberFormat.format(numeric) : value;
+  };
+
+  return (
+    <section aria-label={ruleName} className="flex flex-col gap-3">
+      {planLimitSentences(rule.rows).map((sentence) => {
+        const live = sentence.segments.map((segment) => {
+          const row = sentence.rows.find(
+            (candidate) => segment.kind === "value" && segment.edit?.id === candidate.edit.id,
+          );
+          return row ? { ...segment, text: figureOf(row) } : segment;
+        });
+        return (
+          <div key={sentence.rows[0]?.id} className="flex flex-col gap-3">
+            <p className="typography-small-medium leading-6 text-default-foreground">
+              <RuleNarrativeSegments variant="narrative" segments={live} />
+            </p>
+            {editable &&
+              sentence.rows.map((row) => (
+                <PlanLimitControl
+                  key={row.id}
+                  row={row}
+                  label={planLimitControlLabel(row)}
+                  value={valueOf(row)}
+                  fieldError={fieldErrors[row.id]}
+                  disabled={disabled}
+                  onChange={(value) => onChange(row, value)}
+                />
+              ))}
+          </div>
+        );
+      })}
+      <p className="typography-caption text-muted-foreground">
+        From the rule {ruleName}.{rule.lock && ` ${planLimitLockNotes[rule.lock]}`}
+      </p>
+      {isPresent(ruleError) && <p className="typography-caption text-error-foreground">{ruleError}</p>}
+    </section>
+  );
+}
+
+type PlanLimitControlProps = {
+  row: PlanLimitRow;
+  label: string;
+  value: string;
+  fieldError: string | undefined;
+  disabled: boolean;
+  onChange: (value: string) => void;
+};
+
+/** The control for one value: a slider with a field for a number, a date field for a date. */
+function PlanLimitControl(props: PlanLimitControlProps) {
+  const { row, label, value, fieldError, disabled, onChange } = props;
+  const inputId = useId();
+  const descriptor = ruleValueInputDescriptors[row.edit.kind];
+  const [typed, setTyped] = useState(row.edit.value);
+  const range = sliderRangeFor(row.edit.value, typed);
+  const numeric = Number(value);
+
+  const fallbackInput = (
+    <Input
+      id={inputId}
+      containerClassName="w-56"
+      className="w-full"
+      type={descriptor.type}
+      step={descriptor.step}
+      inputMode={descriptor.inputMode}
+      value={descriptor.toInputValue(value)}
+      error={fieldError}
+      helperText={descriptor.helperText}
+      disabled={disabled}
+      onChange={(event) => onChange(descriptor.fromInputValue(event.target.value))}
+    />
+  );
+
+  return (
+    <div className="grid items-center gap-3 md:grid-cols-[7rem_minmax(0,1fr)]">
+      <label htmlFor={inputId} className="typography-small text-muted-foreground">
+        {label}
+      </label>
+      {match(row.edit.kind)
+        .with("number", () =>
+          range ? (
+            <div className="flex items-center gap-4">
+              <Slider
+                className="min-w-0 flex-1"
+                min={range.min}
+                max={range.max}
+                step={range.step}
+                value={[Number.isFinite(numeric) ? numeric : range.min]}
+                disabled={disabled}
+                onValueChange={([next]) => onChange(String(next))}
+                thumbProps={[{ "aria-label": label }]}
+              />
+              <Input
+                id={inputId}
+                containerClassName="w-28 shrink-0"
+                className="w-full"
+                type="number"
+                step="any"
+                inputMode="decimal"
+                value={value}
+                error={fieldError}
+                disabled={disabled}
+                onChange={(event) => {
+                  setTyped(event.target.value);
+                  onChange(event.target.value);
+                }}
+              />
+            </div>
+          ) : (
+            fallbackInput
+          ),
+        )
+        .with("date", () => (
+          <div className="flex flex-col gap-1">
+            <InputDate
+              id={inputId}
+              className="w-44"
+              aria-invalid={fieldError ? true : undefined}
+              selected={dateOf(value)}
+              allowPast
+              closeOnSelect
+              disabled={disabled}
+              onChange={(date) => onChange(format(date, ruleDateFormat))}
+            />
+            {isPresent(fieldError) && <p className="typography-caption text-error-foreground">{fieldError}</p>}
+          </div>
+        ))
+        .with("dateTime", () => fallbackInput)
+        .exhaustive()}
+    </div>
+  );
+}

package/src/components/plan-limits/index.tsx

@@ -0,0 +1,3 @@
+export type { PlanLimitChange, PlanLimitLock, PlanLimitRule } from "./plan-limits-model";
+export type { PlanLimitsSaveResult, PlanLimitsSaveStep } from "./plan-limits-save";
+export { PlanLimitsDialog, type PlanLimitsDialogProps } from "./PlanLimitsDialog";

package/src/components/plan-limits/plan-limits-client.ts

@@ -0,0 +1,71 @@
+import {
+  type GQLActionPlanRulesQuery,
+  type GQLClearStagedRulesMutation,
+  type GQLClearStagedRulesMutationVariables,
+  type GQLCommitStagedRulesMutation,
+  type GQLCommitStagedRulesMutationVariables,
+  GQLRuleOperation,
+  GQLRuleOwner,
+  type GQLStageRuleOperationMutation,
+  type GQLStageRuleOperationMutationVariables,
+  type GQLValidateStagedRulesMutation,
+  type GQLValidateStagedRulesMutationVariables,
+} from "@manta-eu/client";
+import { extractPlanName } from "@manta-eu/client/shared/agent-mode";
+import type { PlanLimitRule } from "./plan-limits-model";
+import type { PlanLimitsSaveClient } from "./plan-limits-save";
+
+export type PlanRuleRow = GQLActionPlanRulesQuery["rules"]["rules"][number];
+
+/** A rule with no owner is not Manta's, so it can be edited like a user's. */
+export function planLimitRuleOf(rule: PlanRuleRow): PlanLimitRule {
+  return {
+    ruleIri: rule.ruleIri,
+    ruleText: rule.committedRule ?? rule.stagedRule ?? "",
+    ownedByManta: rule.ownedBy?.type === GQLRuleOwner.Manta,
+    hasStagedChange: rule.isStaged,
+  };
+}
+
+export type PlanLimitsMutations = {
+  stage: (variables: GQLStageRuleOperationMutationVariables) => Promise<GQLStageRuleOperationMutation>;
+  validate: (variables: GQLValidateStagedRulesMutationVariables) => Promise<GQLValidateStagedRulesMutation>;
+  commit: (variables: GQLCommitStagedRulesMutationVariables) => Promise<GQLCommitStagedRulesMutation>;
+  clear: (variables: GQLClearStagedRulesMutationVariables) => Promise<GQLClearStagedRulesMutation>;
+};
+
+/** Reads the rule mutations' answers into what the save chain needs. */
+export function planLimitsSaveClient(
+  mutations: PlanLimitsMutations,
+  planGraphIri: string | undefined,
+): PlanLimitsSaveClient {
+  return {
+    stage: async (change) => {
+      const response = await mutations.stage({
+        input: {
+          humanIntent: `Edit the limits of ${planGraphIri ? extractPlanName(planGraphIri) : "the plan"}`,
+          operation: GQLRuleOperation.Change,
+          ruleIri: change.ruleIri,
+          newRule: change.ruleText,
+        },
+      });
+      return { success: response.stageRuleOperation.success, error: response.stageRuleOperation.error };
+    },
+    validate: async (ruleIris) => {
+      const response = await mutations.validate({ ruleIris });
+      const validation = response.validateStagedRules;
+      const errors = [
+        ...(validation.syntaxErrors ?? []),
+        ...(validation.isStratifiable ? [] : ["The changed rules cannot be stratified."]),
+        ...(validation.error ? [validation.error] : []),
+      ];
+      return { isValid: validation.isValid && validation.isStratifiable, errors };
+    },
+    commit: async (ruleIris) => {
+      const response = await mutations.commit({ dryRun: false, ruleIris });
+      const commit = response.commitStagedRules;
+      return { success: commit.success, rulesUpdated: commit.rulesUpdated, error: commit.error };
+    },
+    clear: (ruleIris) => mutations.clear({ ruleIris }),
+  };
+}

package/src/components/plan-limits/plan-limits-model.ts

@@ -0,0 +1,180 @@
+import { isPresent } from "@manta-eu/lib/present";
+import {
+  buildRuleSetupModel,
+  type EditableRuleValue,
+  type NarrativeSegment,
+  parseDatalogRuleCached,
+  type RuleSetupModel,
+} from "#ldo-ui";
+import { buildUpdatedRuleText } from "#routes/rules/components/rule-value-edit";
+
+export type PlanLimitRule = {
+  ruleIri: string;
+  ruleText: string;
+  /** A rule Manta maintains; editing it would make it the user's and stop Manta's updates, so it stays read-only. */
+  ownedByManta: boolean;
+  /** A rule with an uncommitted change staged elsewhere; saving here would commit that change too. */
+  hasStagedChange: boolean;
+};
+
+export type PlanLimitLock = "manta" | "staged";
+
+export function planLimitLock(rule: PlanLimitRule): PlanLimitLock | null {
+  if (rule.hasStagedChange) return "staged";
+  if (rule.ownedByManta) return "manta";
+  return null;
+}
+
+export type PlanLimitRow = {
+  /** Unique across the plan: a rule's edit ids repeat between rules. */
+  id: string;
+  ruleIri: string;
+  edit: EditableRuleValue;
+  segments: readonly NarrativeSegment[];
+};
+
+export type PlanLimitRuleModel = PlanLimitRule & {
+  lock: PlanLimitLock | null;
+  model: RuleSetupModel;
+  rows: PlanLimitRow[];
+};
+
+export type PlanLimitsModel = {
+  rules: PlanLimitRuleModel[];
+  rows: PlanLimitRow[];
+  editableRows: PlanLimitRow[];
+  unparsable: { ruleIri: string; error: string }[];
+};
+
+export type PlanLimitChange = { ruleIri: string; ruleText: string };
+
+export type PlanLimitsBuild = {
+  changed: boolean;
+  changes: PlanLimitChange[];
+  fieldErrors: Readonly<Record<string, string>>;
+  ruleErrors: Readonly<Record<string, string>>;
+};
+
+export function planLimitRowId(ruleIri: string, editId: string): string {
+  return `${ruleIri}#${editId}`;
+}
+
+export function buildPlanLimitsModel(rules: readonly PlanLimitRule[]): PlanLimitsModel {
+  const unparsable: PlanLimitsModel["unparsable"] = [];
+  const ruleModels = rules.flatMap((rule): PlanLimitRuleModel[] => {
+    if (!isPresent(rule.ruleText)) return [];
+    const { ast, error } = parseDatalogRuleCached(rule.ruleText);
+    if (!ast) {
+      unparsable.push({ ruleIri: rule.ruleIri, error: error ?? "Could not parse rule" });
+      return [];
+    }
+    const model = buildRuleSetupModel(ast);
+    const rows = model.editableValues.map(({ edit, segments }) => ({
+      id: planLimitRowId(rule.ruleIri, edit.id),
+      ruleIri: rule.ruleIri,
+      edit,
+      segments,
+    }));
+    return isPresent(rows) ? [{ ...rule, lock: planLimitLock(rule), model, rows }] : [];
+  });
+  return {
+    rules: ruleModels,
+    rows: ruleModels.flatMap((rule) => rule.rows),
+    editableRows: ruleModels.flatMap((rule) => (rule.lock ? [] : rule.rows)),
+    unparsable,
+  };
+}
+
+export function buildPlanLimitChanges(
+  model: PlanLimitsModel,
+  values: Readonly<Record<string, string>>,
+): PlanLimitsBuild {
+  const changes: PlanLimitChange[] = [];
+  const fieldErrors: Record<string, string> = {};
+  const ruleErrors: Record<string, string> = {};
+
+  for (const rule of model.rules) {
+    if (rule.lock) continue;
+    const ruleValues: Record<string, string> = {};
+    for (const row of rule.rows) {
+      const value = values[row.id];
+      if (value !== undefined) ruleValues[row.edit.id] = value;
+    }
+    const result = buildUpdatedRuleText(rule.model, ruleValues);
+    for (const [editId, message] of Object.entries(result.fieldErrors)) {
+      fieldErrors[planLimitRowId(rule.ruleIri, editId)] = message;
+    }
+    if (result.error) ruleErrors[rule.ruleIri] = result.error;
+    if (result.changed && !result.error && !isPresent(Object.keys(result.fieldErrors))) {
+      changes.push({ ruleIri: rule.ruleIri, ruleText: result.ruleText });
+    }
+  }
+
+  return { changed: isPresent(changes), changes, fieldErrors, ruleErrors };
+}
+
+/** A build can be saved only when something changed and no value and no rule carries an error. */
+export function planLimitsCanSave(build: PlanLimitsBuild): boolean {
+  return build.changed && !isPresent(Object.keys(build.fieldErrors)) && !isPresent(Object.keys(build.ruleErrors));
+}
+
+export type SliderRange = { min: number; max: number; step: number };
+
+/** Rounds up to 1, 2 or 5 times a power of ten, so a slider ends on a round figure. */
+export function niceCeiling(value: number): number {
+  if (value <= 0) return 0;
+  const magnitude = 10 ** Math.floor(Math.log10(value));
+  const leading = value / magnitude;
+  const nice = leading <= 1 ? 1 : leading <= 2 ? 2 : leading <= 5 ? 5 : 10;
+  return nice * magnitude;
+}
+
+/** A slider's bounds around a rule's number: 0 to a round figure past twice the rule's or the typed value. */
+export function sliderRangeFor(ruleValue: string, currentValue: string = ruleValue): SliderRange | null {
+  const original = Number(ruleValue);
+  const current = Number(currentValue);
+  if (!Number.isFinite(original)) return null;
+  const decimals = Math.min(4, (ruleValue.split(".")[1] ?? "").length);
+  const step = decimals === 0 ? 1 : 10 ** -decimals;
+  const base = original === 0 ? 10 : niceCeiling(Math.abs(original) * 2);
+  const typed = Number.isFinite(current) ? Math.abs(current) : 0;
+  const max = typed > base ? niceCeiling(typed * 2) : base;
+  const min = original < 0 || current < 0 ? -max : 0;
+  return { min, max, step };
+}
+
+export type PlanLimitSentence = {
+  /** The narrative row's segments, shared by every value it holds. */
+  segments: readonly NarrativeSegment[];
+  rows: PlanLimitRow[];
+};
+
+/** A rule's values grouped by sentence: `buildRuleSetupModel` gives every value of a row one `editContext` array. */
+export function planLimitSentences(rows: readonly PlanLimitRow[]): PlanLimitSentence[] {
+  const sentences: PlanLimitSentence[] = [];
+  for (const row of rows) {
+    const sentence = sentences.find((candidate) => candidate.segments === row.segments);
+    if (sentence) sentence.rows.push(row);
+    else sentences.push({ segments: row.segments, rows: [row] });
+  }
+  return sentences;
+}
+
+/** The words right before a value in its sentence ("at least", "at most"), to name its control. */
+export function planLimitControlLabel(row: PlanLimitRow): string {
+  const index = row.segments.findIndex((segment) => segment.kind === "value" && segment.edit?.id === row.edit.id);
+  const words: string[] = [];
+  for (let cursor = index - 1; cursor >= 0; cursor--) {
+    const segment = row.segments[cursor];
+    if (segment?.kind !== "text") break;
+    words.unshift(segment.text);
+  }
+  const label = words
+    .join("")
+    .trim()
+    .replace(/^(and|or|,)\s+/i, "")
+    .replace(/^is\s+/i, "")
+    .replace(/[,:]$/, "")
+    .trim();
+  return label || "Value";
+}

package/src/components/plan-limits/plan-limits-save.ts

@@ -0,0 +1,68 @@
+import { parseError } from "@manta-eu/client/shared/error-utils";
+import { humanList } from "@manta-eu/lib/humanize";
+import { isPresent } from "@manta-eu/lib/present";
+import type { PlanLimitChange } from "./plan-limits-model";
+
+export type PlanLimitsSaveStep = "stage" | "validate" | "commit";
+
+export type PlanLimitsSaveClient = {
+  stage: (change: PlanLimitChange) => Promise<{ success: boolean; error?: string | null }>;
+  validate: (ruleIris: string[]) => Promise<{ isValid: boolean; errors: string[] }>;
+  commit: (ruleIris: string[]) => Promise<{ success: boolean; rulesUpdated: number; error?: string | null }>;
+  clear: (ruleIris: string[]) => Promise<unknown>;
+};
+
+export type PlanLimitsSaveResult =
+  | { ok: true; rulesUpdated: number }
+  | { ok: false; step: PlanLimitsSaveStep; error: string };
+
+/** Stages every change, validates and commits them together; a failure clears what was staged, or says it could not. */
+export async function savePlanLimits(
+  client: PlanLimitsSaveClient,
+  changes: readonly PlanLimitChange[],
+): Promise<PlanLimitsSaveResult> {
+  const ruleIris = changes.map((change) => change.ruleIri);
+  const staged: string[] = [];
+
+  const rollback = async (step: PlanLimitsSaveStep, error: string): Promise<PlanLimitsSaveResult> => {
+    if (!isPresent(staged)) return { ok: false, step, error };
+    const cleared = await client.clear(staged).then(
+      () => null,
+      (err: unknown) => messageOf(err),
+    );
+    if (cleared === null) return { ok: false, step, error };
+    return {
+      ok: false,
+      step,
+      error: `${error.replace(/\.$/, "")}. The staged changes could not be cleared (${cleared}); clear them on the rule pages.`,
+    };
+  };
+
+  for (const change of changes) {
+    const result = await client.stage(change).catch((err: unknown) => ({ success: false, error: messageOf(err) }));
+    if (!result.success) return rollback("stage", result.error ?? `Could not stage ${change.ruleIri}`);
+    staged.push(change.ruleIri);
+  }
+
+  const validation = await client
+    .validate(ruleIris)
+    .catch((err: unknown) => ({ isValid: false, errors: [messageOf(err)] }));
+  if (!validation.isValid)
+    return rollback(
+      "validate",
+      isPresent(validation.errors) ? humanList(validation.errors) : "The rules did not validate",
+    );
+
+  const commit = await client
+    .commit(ruleIris)
+    .catch((err: unknown) => ({ success: false, rulesUpdated: 0, error: messageOf(err) }));
+  if (!commit.success) return rollback("commit", commit.error ?? "Could not commit the rules");
+
+  return { ok: true, rulesUpdated: commit.rulesUpdated };
+}
+
+/** The text to show for a thrown error: its description when it has one, else its message. */
+export function messageOf(err: unknown, fallback = "Something went wrong"): string {
+  const info = parseError(err, fallback);
+  return info.description ?? info.message;
+}