rezi-modal-dialogs

name	rezi-modal-dialogs
description	Add modal dialogs and overlay UI with focus trapping. Use when implementing confirmations, alerts, or layered interfaces.
user-invocable	true
allowed-tools	Read, Glob, Grep, Edit, Write
argument-hint	[modal-type]
metadata	{"short-description":"Add modal dialogs"}

When to use

Use this skill when:

• Adding confirmation dialogs, alerts, or prompts
• Building layered/overlay UI
• Need focus trapping within a dialog

Source of truth

• packages/core/src/widgets/useModalStack.ts — useModalStack() hook
• packages/core/src/widgets/types.ts — ModalProps, LayersProps
• packages/core/src/widgets/ui.ts — ui.modal(), ui.layers()
• packages/core/src/ui/recipes.ts — recipe.modal() and recipe.surface() for design-system-consistent modal styling

Steps

Option A: useModalStack (recommended for multiple modals)

1. Use useModalStack() inside a defineWidget:

   const modals = useModalStack(ctx);
   
   // Push a modal
   modals.push("confirm", {
     title: "Confirm",
     content: body,
     onClose: () => modals.pop(),
   });
   
   // Include in view
   return ui.layers([mainContent, ...modals.render()]);
   

Option B: ui.modal (simple single modal)

1. Use ui.modal() directly with a state-controlled flag:

   return ui.layers([
     mainContent,
     ...(state.showModal
       ? [
           ui.modal({
             id: "confirm-modal",
             title: "Confirm",
             initialFocus: "confirm-ok",
             returnFocusTo: "open-confirm",
             onClose: () => app.update((s) => ({ ...s, showModal: false })),
             content: ui.text("Are you sure?"),
             actions: [
               ui.button({
                 id: "confirm-cancel",
                 label: "Cancel",
                 intent: "secondary",
                 onPress: () => app.update((s) => ({ ...s, showModal: false })),
               }),
               ui.button({
                 id: "confirm-ok",
                 label: "OK",
                 intent: "primary",
                 onPress: () => app.update((s) => ({ ...s, showModal: false })),
               }),
             ],
           }),
         ]
       : []),
   ]);
   

2. Overlay ordering note:

   • Modal, dropdown, and toast overlays share unified z-ordering through the LayerRegistry.
   • Prefer ui.layers([...]) as the common overlay composition root.

3. Dialog action intent note:

   • Use intent to communicate action semantics in modal/dialog button rows.
   • Recommended mapping: confirm/continue -> primary, cancel/back -> secondary, destructive -> danger, positive approval -> success, cautionary acknowledgment -> warning.

Verification

• Modal opens and closes correctly
• Focus traps within the modal (Tab doesn't escape)
• Focus returns to previous element on close