Edit Lifecycle — Type Catalog and Hook Reference

Type definitions and hook API for the Edit Lifecycle framework. See Edit Lifecycle for the pattern overview and state machine.

Type Catalog

PlantUML diagram

FieldError

A single validation error on a specific field.

Property	Type	Required	Description
`field`	`string`	Yes	Dot-path to the field (e.g., `"postalCode"`, `"address.city"`)
`message`	`string`	Yes	Human-readable error message
`code`	`string`	No	Machine-readable code for testing and i18n
`severity`	`'error' \| 'warning'`	No	`'error'` blocks confirm; `'warning'` shows but allows. Default: `'error'`

ValidationResult

Result of validating a value.

Property	Type	Description
`valid`	`boolean`	`true` if no errors (warnings are allowed)
`errors`	`FieldError[]`	List of field-level errors and warnings

Validator<T>

A function that validates a value and returns a result: (value: T) => ValidationResult.

Convention: each editable component exports its validator as a named function alongside the component (e.g., validateAddress).

EditPhase

Union of the four lifecycle phases: 'idle' | 'editing' | 'confirming' | 'error'.

EditLifecycleCallbacks<T>

Callbacks for the edit lifecycle, all optional:

Callback	Signature	When called
`onChange`	`(value: T, validation: ValidationResult) => void`	Every draft change
`onConfirm`	`(value: T) => void`	User confirms and intrinsic validation passes
`onCancel`	`() => void`	User cancels the edit

EditableComponentProps<T>

Standard props for any editable component. Extends EditLifecycleCallbacks<T>.

Property	Type	Required	Description
`initialValue`	`T`	Yes	Starting value from parent or data provider
`contextErrors`	`FieldError[]`	No	Errors injected by the parent
`disabled`	`boolean`	No	Disables editing (parent saving, sibling editing)

useDraft<T> Hook

The core hook that implements the state machine. Each editable component calls useDraft to manage its local draft.

Options

interface UseDraftOptions<T> {
  initialValue: T;
  validate: Validator<T>;
  contextErrors?: FieldError[];
  onChange?: (value: T, validation: ValidationResult) => void;
  onConfirm?: (value: T) => void;
  onCancel?: () => void;
  isEqual?: (a: T, b: T) => boolean;
}

Option	Description
`initialValue`	Resets the draft when this value changes
`validate`	Intrinsic validator, called on every draft change
`contextErrors`	Parent-injected errors, merged into `allErrors`
`onChange`	Forwarded lifecycle callback
`onConfirm`	Forwarded lifecycle callback
`onCancel`	Forwarded lifecycle callback
`isEqual`	Custom equality for `initialValue` change detection. Default: `Object.is` (reference equality)

Return Value

interface DraftState<T> {
  value: T;
  intrinsicValidation: ValidationResult;
  allErrors: FieldError[];
  dirty: boolean;
  isValid: boolean;
  phase: EditPhase;

  update: (updater: T | ((prev: T) => T)) => void;
  updateField: (path: string, value: unknown) => void;
  confirm: () => void;
  cancel: () => void;
  reset: () => void;
  errorsFor: (field: string) => FieldError[];
}

Member	Description
`value`	Current draft value
`intrinsicValidation`	Latest result from the `validate` function
`allErrors`	Intrinsic errors + `contextErrors`, for display
`dirty`	`true` when draft differs from `initialValue`
`isValid`	`true` when no blocking errors (intrinsic + contextual)
`phase`	Current lifecycle phase
`update(updater)`	Replace draft; accepts value or updater function
`updateField(path, value)`	Update a single field by dot-path
`confirm()`	Confirm if valid (calls `onConfirm`); else enter error phase
`cancel()`	Reset to `initialValue` and call `onCancel`
`reset()`	Reset to `initialValue` without calling `onCancel`
`errorsFor(field)`	Filter `allErrors` by field prefix

Key Behaviors

Initial value reset. The draft resets when initialValue changes. By default this uses reference equality (Object.is). Callers must memoize initialValue to prevent unwanted resets. Provide isEqual for structural comparison when needed.

Validation on every change. update() and updateField() run the validate function synchronously and call onChange with the result.

Error merging. allErrors is the union of intrinsic validation errors and contextErrors. isValid is false when any error has severity: 'error' (or no severity). Warnings do not block confirm.

Prefix-based error filtering. errorsFor('address') matches 'address', 'address.city', 'address.postalCode' but not 'addressLine2'. This enables automatic error routing in nested hierarchies.

Usage Example — Leaf Component

function AddressEditor(props: EditableComponentProps<Address>) {
  const draft = useDraft({
    initialValue: props.initialValue,
    validate: validateAddress,
    contextErrors: props.contextErrors,
    onChange: props.onChange,
    onConfirm: props.onConfirm,
    onCancel: props.onCancel,
  });

  return (
    <div>
      <input
        value={draft.value.street}
        onChange={(e) => draft.updateField('street', e.target.value)}
      />
      {draft.errorsFor('street').map((e) => (
        <span key={e.message}>{e.message}</span>
      ))}
      <button onClick={draft.confirm} disabled={!draft.isValid}>
        Save
      </button>
      <button onClick={draft.cancel}>Cancel</button>
    </div>
  );
}

Import Paths

// Types only (no React dependency)
import type {
  FieldError,
  ValidationResult,
  Validator,
  EditPhase,
  EditLifecycleCallbacks,
  EditableComponentProps,
} from '@arda-cards/design-system/types/canary';

// Hook + types (requires React)
import { useDraft, setNestedField } from '@arda-cards/design-system/canary';
import type { UseDraftOptions, DraftState } from '@arda-cards/design-system/canary';