Let a dialog choose where initial focus lands

[woksin]

Summary

A destructive dialog could not stop its OK button taking focus on open without discarding the footer's behavior.

Added

• initialFocus on Dialog, forwarded by CommandDialog, choosing where focus lands when the dialog opens: DialogInitialFocus.Confirm (the default, unchanged), Cancel, or Content. Cancel degrades to Content where no dismissing button exists.

Fixed

• A dialog with a custom footer or buttons={null} left focus on document.body, outside the modal. BusyIndicatorDialog shipped in that state; focus now moves to the dialog's title.

[woksin]

Reviewer context, kept out of the body so it stays out of the release notes.

The trigger was a one-keystroke destruction path found in a consuming application: a native <button> fires click on keydown, and autoFocus put a freshly mounted dialog's OK under the same held key, collapsing a two-step confirmation into one act. The asymmetry is what makes it a framework concern rather than an application mistake — a dialog with a mandatory input is protected for free by its validity gate, while a destructive dialog that asks for nothing is armed. The framework protected the dialog that asks for something and armed the one that asks for nothing.

Replacing the footer was not a usable workaround: typeof buttons === 'number' also flips closable, no-ops onHide, severs CommandDialog's handleConfirm so the command never executes, and — a fourth behavior the report missed — kills Escape, since PrimeReact derives isCloseOnEscape from closable. That coupling is left in place deliberately: a blanket fix would put a close button on BusyIndicatorDialog, which must not be dismissible. It is documented and pinned with characterization specs, and needs its own design pass.

initialFocus is an enum rather than a boolean because false cannot say where focus goes, and the implicit answer is document.body — a modal with focus outside itself. Content focuses the dialog title with tabIndex={-1}, the WAI-ARIA APG pattern; the title is PrimeReact's aria-labelledby target, so screen readers announce what the dialog is.

The default is unchanged and byte-identical, argued rather than assumed: the framework cannot know which dialogs are destructive.

Verification: 30 new tests (suite 188 → 218), 14 mutations, all red. Specs render into jsdom with the real PrimeReact Dialog. yarn ci, npx tsc -b and build-storybook all exit 0. Honest gap: jsdom does not synthesize click from Enter keydown, so the harness does it explicitly — the invariant is right but one step removed from the browser's own key handling.

Also flagged, not fixed: ConfirmationDialog cannot express the choice (its request type and hook use positional args, an Arc-side API decision), and a single-step StepperCommandDialog still arms submit on mount.