Form feedback pattern

const validation = useFormValidation();

// Register a field. Call on every render; the latest validator closure wins.
const name = validation.register(
  "clientName",
  (v) => (v.trim() ? null : "Enter a client name."),
);

// Spread onto the control and its wrapper:
<FormField label="Client name" required error={name.error}>
  <Input ref={name.ref} onBlur={name.onBlur} value={value} onChange={...} />
</FormField>

const rate = validation.register(
  "rateItem",
  (v) => (v ? null : "Select a rate item."),
  { getValue: () => selectedRateItemId ?? "" },
);

<FormField label="Rate item" required error={rate.error}>
  <SomePicker ref={rate.ref} onBlur={rate.onBlur} ... />
</FormField>

const save = async () => {
  const result = validation.validateAll();
  if (!result.valid) {
    notifyValidationErrors(result); // raises the "Can't save yet" error toast
    return;
  }
  // ... proceed with save
};

try {
  await onSave(payload);
} catch (err) {
  validation.setError("endDate", "End date must be after start date.");
}

<FormGrid>
  <FormField label="Category" span="medium" required>…</FormField>
  <FormField label="Unit" span="medium" required>…</FormField>
  <FormField label="Item name" span="full" required>…</FormField>
  <FormField label="Bulking %" span="short">…</FormField>
</FormGrid>

<FormField label="Depth" required error={depth.error} helper="Metres below surface.">
  <Input ref={depth.ref} onBlur={depth.onBlur} type="number" ... />
</FormField>

<SubmitButton isSaving={saving} disabled={!isDirty}>
  Save rate
</SubmitButton>

const formId = useId();

// Inside the dialog body:
<form id={formId} onSubmit={handleSubmit}>
  ...
</form>

// Inside the dialog footer:
<SubmitButton form={formId} isSaving={saving}>Save</SubmitButton>

notify.success({
  title: "Rate saved",
  message: "The excavator hourly rate now applies to new estimates.",
});

notify.error({
  title: "Could not save",
  message: "Check your connection and try again.",
});

notify.info({
  title: "Recalculating the estimate",
  message: "The totals will update when the calculation finishes.",
});

notify.success({
  title: "Assignment removed",
  message: "The crew booking has been cancelled.",
  action: {
    label: "Undo",
    onClick: () => restoreAssignment(id),
  },
});

import type { NotifyAction } from "@stralos-co-nz/ui";

notify.error({
  title: "Could not save",
  message: err.reason, // safe even when err.reason is ""
});

const result = validation.validateAll();
if (!result.valid) return notifyValidationErrors(result);

<Dialog
  open={isOpen}
  onClose={handleClose}
  title="Add rate item"
  size="md"
  actions={{ primary: { label: "Save item", form: "rate-item-form", loading: saving } }}
>
  <form id="rate-item-form" onSubmit={handleSubmit}>
    <FormGrid>…</FormGrid>
  </form>
</Dialog>

const isDirty = JSON.stringify(draft) !== pristine.current;

<Dialog
  open={isOpen}
  onClose={handleClose}
  title="Edit calculator"
  recordName={calculatorName}
  confirmOnDirtyClose
  isDirty={isDirty}
  footer={...}
>
  ...
</Dialog>

<DialogCancelButton />           // renders "Cancel"
<DialogCancelButton>Discard</DialogCancelButton>  // custom label

const { requestClose } = useDialogClose();
<Button onClick={requestClose}>Go back</Button>

import { openForeignLayers, useForeignLayerGate } from "@stralos-co-nz/ui";
import { useRemoteScope } from "@stralos-co-nz/ui";

function MyCustomOverlay({ open, onClose }: { open: boolean; onClose: () => void }) {
  const remoteKey = useRemoteScope();
  const admittedOpen = useForeignLayerGate(open, remoteKey);
  // use admittedOpen as the actual open state passed to the overlay
}

<ConfirmDialog
  open={confirmingDelete}
  title="Delete rate item?"
  message={`"${rateName}" will be removed from the library permanently.`}
  confirmLabel="Delete rate item"
  destructive
  onConfirm={handleDelete}
  onCancel={() => setConfirmingDelete(false)}
/>

// Simple usage — rotating phrases, no stage label
<ConstructionSpinner />

// With a known stage (multi-stage extraction)
<ConstructionSpinner
  stage="Reading the workbook"
  detail="rates.xlsx"
/>

// Stable — defined outside the component or memoised
const CUSTOM_PHRASES = ["Crunching the numbers", "Almost there"] as const;

<ConstructionSpinner phrases={CUSTOM_PHRASES} />

import { ModalError } from "./estimateShared";

const [saveError, setSaveError] = useState<string | null>(null);

const handleSubmit = async (e: React.FormEvent) => {
  e.preventDefault();
  setSaveError(null);

  const result = validation.validateAll();
  if (!result.valid) return notifyValidationErrors(result);

  try {
    await onSave(payload);
  } catch (err) {
    setSaveError(err instanceof Error ? err.message : "Could not save.");
  }
};

// Render inside the dialog body — always mounted, never conditional:
<ModalError message={saveError} />

function EditRateDialog({ rate, onSave, onClose }: Props) {
  const formId = useId();
  const validation = useFormValidation();
  const [name, setName] = useState(rate.name);
  const [saving, setSaving] = useState(false);
  const [saveError, setSaveError] = useState<string | null>(null);

  const pristine = useRef(JSON.stringify({ name }));
  const isDirty = JSON.stringify({ name }) !== pristine.current;

  const nameField = validation.register(
    "name",
    (v) => (v.trim() ? null : "Enter a rate name."),
  );

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    setSaveError(null);
    const result = validation.validateAll();
    if (!result.valid) return notifyValidationErrors(result);

    setSaving(true);
    try {
      await onSave({ name });
      notify.success({ title: "Rate saved", message: "Changes apply to new estimates." });
      onClose();
    } catch (err) {
      setSaveError(err instanceof Error ? err.message : "Could not save.");
    } finally {
      setSaving(false);
    }
  };

  return (
    <Dialog
      open
      onClose={onClose}
      title="Edit rate"
      confirmOnDirtyClose
      isDirty={isDirty}
      footer={
        <HStack justify="flex-end" width="100%">
          <DialogCancelButton />
          <SubmitButton form={formId} isSaving={saving}>Save rate</SubmitButton>
        </HStack>
      }
    >
      <form id={formId} onSubmit={handleSubmit}>
        <ModalError message={saveError} />
        <FormField label="Rate name" required error={nameField.error}>
          <Input
            ref={nameField.ref}
            onBlur={nameField.onBlur}
            value={name}
            onChange={(e) => setName(e.target.value)}
          />
        </FormField>
      </form>
    </Dialog>
  );
}