Notices and refused edits

Refused edits

An edit that cannot happen returns an EditRefusal. Its closed kind identifies the reason, and an optional subject names the value or type involved. undefined means the edit succeeded.

Built-in Creator fields show refusals beside the control with an alert role. A custom control that calls a design-surface method should handle the returned value at the same interaction point.

Creator notices

Notices describe a successful automatic action that could otherwise be confusing: pasted names were renumbered, incompatible properties were dropped during a type conversion, or deleting a container also removed its children.

They arrive through surface.onNotice. The default assembly renders the latest one in a persistent polite live region; composed Creators can use CreatorNotices or useLatestNotice.

Handle feedback in custom UI

import {
  CreatorNotices,
  useCreatorText,
} from '@kajay/creator-react';
import { refusalMessageKey } from '@kajay/creator-core';

// Include this once in a composed Creator. SurveyCreator already does.
<CreatorNotices surface={workspace.surface} />

function RenameButton({ surface, question, nextName }) {
  const text = useCreatorText();

  function rename(): void {
    const refusal = surface.setProperty(question, 'name', nextName);
    if (refusal !== undefined) {
      announce(text(refusalMessageKey(refusal.kind), refusal.subject ?? ''));
    }
  }

  return <button onClick={rename}>Rename</button>;
}

When to use each

• A refusal answers the control that attempted an edit which did not happen.
• A notice announces something Kajay did automatically and successfully.
• Save failure is separate state owned by the save controller.
• Definition parse problems belong to the JSON editor and runtime diagnostics.