{"$schema":"https://ui.shadcn.com/schema/registry-item.json","name":"dialog","type":"registry:ui","title":"Dialog","description":"A modal panel with a title, description, body and free-form footer — portals out, traps focus, and locks the page's scroll while open","categories":["overlays"],"registryDependencies":["https://fancy-ui.rama.app/r/internals.json","https://fancy-ui.rama.app/r/internals-dom.json","https://fancy-ui.rama.app/r/internals-motion.json","https://fancy-ui.rama.app/r/sound.json","https://fancy-ui.rama.app/r/utils.json"],"files":[{"path":"react/src/components/dialog/Dialog.tsx","content":"\"use client\";\n\nimport { forwardRef, useEffect, useRef, useState } from \"react\";\nimport type { ReactNode } from \"react\";\n\nimport { cn } from \"../../utils\";\nimport { useFancyId } from \"../../internals/use-id\";\nimport { useSoundCue } from \"../../sound/use-sound\";\nimport { DialogSurface } from \"./DialogSurface\";\n\nexport interface DialogProps {\n\t/** Whether the dialog is open. Controlled when given; the component keeps its own copy either way. */\n\topen?: boolean;\n\t/** Fires whenever `open` changes, from any trigger — the close button, Escape, an outside click, or the optional `trigger` node. */\n\tonOpenChange?: (open: boolean) => void;\n\t/** The heading. Omitted entirely (not just visually) when not given, so `aria-labelledby` never points at nothing. */\n\ttitle?: string;\n\t/** The copy under the title. Same omission rule as `title`. */\n\tdescription?: string;\n\t/** Whether Escape and an outside click close the dialog. The close button always works regardless — see the README. */\n\tdismissible?: boolean;\n\t/** Element to focus once the dialog opens. Defaults to the first focusable descendant — often the close button; pass a form field here for dialogs built around one. */\n\tinitialFocus?: HTMLElement | null;\n\t/** The dialog's body. */\n\tchildren?: ReactNode;\n\t/** The action row under the body. Free-form — callers build their own buttons. */\n\tfooter?: ReactNode;\n\t/** Optional trigger; renders in place and opens the dialog on activation. */\n\ttrigger?: ReactNode;\n\t/** Additional classes for the panel. */\n\tclassName?: string;\n\t/**\n\t * Plays the matching open/close cue through the sound controller. Off by\n\t * default; only audible once the user has enabled sound.\n\t */\n\tsound?: boolean;\n}\n\nexport const Dialog = forwardRef(function Dialog(\n\t{\n\t\topen: openProp,\n\t\tonOpenChange,\n\t\ttitle,\n\t\tdescription,\n\t\tdismissible = true,\n\t\tinitialFocus = null,\n\t\tchildren,\n\t\tfooter,\n\t\ttrigger,\n\t\tclassName,\n\t\tsound = false,\n\t},\n\tforwardedRef\n) {\n\t// The React shape of the source's `open = $bindable(false)`: an internal\n\t// copy seeded from the prop, re-synced during render whenever the CALLER\n\t// changes the prop, and free to move on its own in between. That is what\n\t// makes all three documented call shapes work off one implementation — a\n\t// caller driving `open` from its own state, a caller who passes only\n\t// `onOpenChange`, and a caller who passes neither and lets the trigger\n\t// run the whole thing.\n\t//\n\t// Re-synced in the render path, not an effect: an effect would paint one\n\t// frame of the stale value first, and the pattern React documents for\n\t// \"adjust state when a prop changes\" is exactly this — set state on the\n\t// component that owns it, during render, and let React restart the render\n\t// before committing anything.\n\tconst [open, setOpenState] = useState(openProp ?? false);\n\tconst [lastOpenProp, setLastOpenProp] = useState(openProp);\n\tif (lastOpenProp !== openProp) {\n\t\tsetLastOpenProp(openProp);\n\t\tsetOpenState(openProp ?? false);\n\t}\n\n\t// A no-op while `sound` is false, so the call sites below stay unguarded.\n\tconst playCue = useSoundCue(sound);\n\n\t// The only place `open` changes on this side of the wire — a plain\n\t// function, not an effect, so it never fights a caller's own controlled\n\t// write and never reads/writes `open` in the same pass.\n\tfunction setOpen(next: boolean) {\n\t\t// A dismiss that changes nothing fires nothing. Belt and braces beside\n\t\t// the dismiss layer's own `active` gate — `active` stops the listener,\n\t\t// this stops the callback — and it fixes a real defect on its own: a\n\t\t// second Escape during the close used to fire `onOpenChange(false)` a\n\t\t// second time.\n\t\t// The same guard is what keeps the cues honest: a redundant call — a\n\t\t// second Escape mid-exit, a dismiss that changes nothing — stays\n\t\t// silent rather than doubling up, and a dialog driven purely by the\n\t\t// `open` prop never reaches this function's open branch, so it opens\n\t\t// silently by design.\n\t\tif (open === next) return;\n\t\tsetOpenState(next);\n\t\tplayCue(next ? \"open\" : \"close\");\n\t\tonOpenChange?.(next);\n\t}\n\n\t// A plain ref, not state: nothing renders off it. It only has to exist by\n\t// the time `useDismissable`'s `exclude` callback runs, and both that and\n\t// `fallbackFocus` below are resolved at event time. Doubles as\n\t// `DialogSurface`'s `fallbackFocus` target — a real, findable place for\n\t// focus to land on close if whatever had focus when the dialog opened is\n\t// no longer in the document by the time it closes.\n\tconst triggerRef = useRef(null);\n\n\t// The wrapper only listens for the click bubbling up from whatever the\n\t// caller put inside `trigger` — it adds no interactive semantics of its\n\t// own, so the trigger's own content (expected to be a real button or\n\t// similar) is what carries keyboard activation. `exclude` on\n\t// `DialogSurface` below is what stops this same element from reading as\n\t// an \"outside\" pointerdown once the dialog is open, so clicking the\n\t// trigger again while open cannot immediately dismiss what it just — or\n\t// is about to — open.\n\tfunction openFromTrigger() {\n\t\tif (open) return;\n\t\tsetOpen(true);\n\t}\n\n\t// One seed, two suffixes — the same one-generator-per-instance pattern\n\t// FormField and RadioGroup use, safe during SSR. Undefined rather than a\n\t// generated id with nothing pointing at it while the title/description\n\t// they'd label are not rendered.\n\tconst uid = useFancyId();\n\tconst titleId = title ? `${uid}-title` : undefined;\n\tconst descriptionId = description ? `${uid}-description` : undefined;\n\n\t// The wrapper carries no semantics, so the disclosure state goes on what\n\t// the caller rendered inside it — the real button a keyboard or\n\t// screen-reader user lands on. Written imperatively because an arbitrary\n\t// `trigger` node cannot be handed props from here. `aria-controls` only\n\t// while the panel exists, so it never points at an id not in the document.\n\tconst panelId = `${uid}-panel`;\n\tuseEffect(() => {\n\t\tconst el = triggerRef.current?.firstElementChild;\n\t\tif (!el) return;\n\t\tel.setAttribute(\"aria-haspopup\", \"dialog\");\n\t\tel.setAttribute(\"aria-expanded\", String(open));\n\t\tif (open) el.setAttribute(\"aria-controls\", panelId);\n\t\telse el.removeAttribute(\"aria-controls\");\n\t\treturn () => {\n\t\t\tel.removeAttribute(\"aria-haspopup\");\n\t\t\tel.removeAttribute(\"aria-expanded\");\n\t\t\tel.removeAttribute(\"aria-controls\");\n\t\t};\n\t}, [open, panelId, trigger]);\n\n\tconst panelContent = (\n\t\t<>\n\t\t\t
\n\t\t\t\t{title ? (\n\t\t\t\t\t

\n\t\t\t\t\t\t{title}\n\t\t\t\t\t

\n\t\t\t\t) : null}\n\t\t\t\t{/*\n\t\t\t\t\tAlways rendered and always functional, independent of `dismissible`:\n\t\t\t\t\tthis is an explicit, deliberate activation — like clicking a Cancel\n\t\t\t\t\tbutton — not the accidental miss-click `dismissible` guards against,\n\t\t\t\t\tso a dialog that turns off Escape/outside-click to protect\n\t\t\t\t\tin-progress work still leaves one unambiguous way out.\n\t\t\t\t*/}\n\t\t\t\t setOpen(false)}\n\t\t\t\t\taria-label=\"Close\"\n\t\t\t\t>\n\t\t\t\t\t✕\n\t\t\t\t\n\t\t\t
\n\t\t\t{description ? (\n\t\t\t\t

\n\t\t\t\t\t{description}\n\t\t\t\t

\n\t\t\t) : null}\n\t\t\t{children}\n\t\t\t{footer ?
{footer}
: null}\n\t\t\n\t);\n\n\treturn (\n\t\t<>\n\t\t\t{trigger ? (\n\t\t\t\t/*\n\t\t\t\t\tThis wrapper adds no semantics of its own on purpose — it only\n\t\t\t\t\tlistens for the click bubbling up from whatever `trigger` renders,\n\t\t\t\t\twhich is expected to be a real interactive element (a Button,\n\t\t\t\t\ttypically) carrying its own keyboard activation. `display: contents`\n\t\t\t\t\tkeeps it out of layout entirely, so it never affects how the\n\t\t\t\t\ttrigger's own content positions itself.\n\t\t\t\t*/\n\t\t\t\t {\n\t\t\t\t\t\ttriggerRef.current = node;\n\t\t\t\t\t}}\n\t\t\t\t\tclassName=\"contents\"\n\t\t\t\t\tonClick={openFromTrigger}\n\t\t\t\t>\n\t\t\t\t\t{trigger}\n\t\t\t\t\n\t\t\t) : null}\n\t\t\t setOpen(false)}\n\t\t\t\tinitialFocus={initialFocus}\n\t\t\t\tfallbackFocus={() => triggerRef.current}\n\t\t\t\texclude={() => [triggerRef.current]}\n\t\t\t\tpanelClass={cn(className)}\n\t\t\t>\n\t\t\t\t{panelContent}\n\t\t\t\n\t\t\n\t);\n});\n\nDialog.displayName = \"Dialog\";\n","type":"registry:ui","target":"@ui/fancy/components/dialog/Dialog.tsx"},{"path":"react/src/components/dialog/DialogSurface.tsx","content":"\"use client\";\n\nimport { forwardRef } from \"react\";\n\nimport { cn } from \"../../utils\";\nimport { Portal } from \"../../internals/Portal\";\nimport { useDismissable } from \"../../internals/dismissable\";\nimport { useFocusTrap } from \"../../internals/focus-trap\";\nimport { useScrollLock } from \"../../internals/scroll-lock\";\nimport { useComposedRefs } from \"../../internals/dom/use-composed-refs\";\nimport { useElementRef } from \"../../internals/dom/use-element-ref\";\nimport { anchored } from \"../../internals/motion/anchored\";\nimport { DURATIONS } from \"../../internals/motion/tokens\";\nimport { usePresence } from \"../../internals/motion/presence\";\nimport type { DialogSurfaceProps } from \"./types\";\nimport \"./dialog-surface.css\";\n\nexport const DialogSurface = forwardRef(function DialogSurface(\n\t{\n\t\topen,\n\t\tid,\n\t\trole,\n\t\ttitleId,\n\t\tdescriptionId,\n\t\tescape,\n\t\toutsideClick,\n\t\tonDismiss,\n\t\tinitialFocus = null,\n\t\tfallbackFocus,\n\t\texclude,\n\t\tpanelClass,\n\t\tchildren,\n\t},\n\tforwardedRef\n) {\n\t// Convention C-1: the NODE, not a ref. The panel is created by\n\t// `presence.mounted`, so a `useRef` + `[]`-deps effect would still be\n\t// holding `null` when the trap's effect fires and the trap would never\n\t// arm — silently.\n\tconst [panel, setPanelNode] = useElementRef();\n\n\t// Returns the two functions the source hands out through `onActivate`:\n\t// the eager return, and the re-arm. Two module-level `let`s, two handler\n\t// functions and an `onActivate` closure collapse to this one line.\n\tconst trap = useFocusTrap(panel, { initialFocus, fallbackFocus });\n\n\tconst presence = usePresence(open, {\n\t\t// The two halves of the focus handshake, at the two moments the source\n\t\t// puts them: `onintrostart` → rearm, `onoutrostart` → returnFocusNow.\n\t\t//\n\t\t// `returnFocusNow` at the dismiss instant is the whole point: waiting\n\t\t// for the trap's own `destroy()` would leave a keyboard user on\n\t\t// `` for the length of the fade, because the panel is marked\n\t\t// `inert` the instant the exit starts.\n\t\t//\n\t\t// `rearm` is the other half. A dialog reopened DURING its exit\n\t\t// reverses instead of remounting, so the trap is never re-created:\n\t\t// without this the panel would come back `aria-modal` and interactive\n\t\t// with focus left on the trigger behind it, Tab walking the page\n\t\t// rather than the panel, and the eager return already spent for the\n\t\t// life of the instance.\n\t\tonEnterStart: () => trap.rearm(),\n\t\tonExitStart: () => trap.returnFocusNow(),\n\t});\n\n\t// Release timing, which is the only reason this is not keyed on `open`:\n\t// `presence.mounted` stays true for the whole exit, so the page stays\n\t// locked until the backdrop has actually finished fading instead of\n\t// unlocking the instant `open` flips and leaving the page scrollable\n\t// under a scrim still on screen.\n\t//\n\t// CONTRACT divergence, recorded in this folder's README: the internals\n\t// contract's worked example calls a bare `useScrollLock()` here. That is\n\t// only correct for a component whose own mounting scope IS the surface's,\n\t// and this one's is not — `Dialog` renders `DialogSurface`\n\t// unconditionally, exactly as the source does, so a bare call would lock\n\t// the page for every dialog on the page, open or not. `mounted` is the\n\t// mounting scope expressed as a boolean; it is emphatically not `open`.\n\tuseScrollLock(presence.mounted);\n\n\t// `active: open` — a plain boolean where the source needed `() => open`.\n\t// The layer stays ON the stack for its whole exit and stops being TOP of\n\t// it the instant `open` flips, so a second Escape during the fade falls\n\t// through to whatever is underneath.\n\tuseDismissable(panel, {\n\t\tonDismiss,\n\t\tescape,\n\t\toutsideClick,\n\t\texclude,\n\t\tactive: open,\n\t\tkeepFocus: true,\n\t});\n\n\t// Convention C-2: composed ABOVE any conditional. Calling this inside the\n\t// JSX branch below would be a conditional hook and would throw the first\n\t// time `mounted` flips.\n\tconst panelRef = useComposedRefs(\n\t\tsetPanelNode,\n\t\tforwardedRef,\n\t\tpresence.register(\"panel\", anchored, (entering) => ({\n\t\t\tentering,\n\t\t\tduration: DURATIONS.base,\n\t\t\texitDuration: DURATIONS.exit,\n\t\t}))\n\t);\n\n\t// The scrim fades on opacity alone (`scale: false`) — a full-viewport\n\t// fixed element has no business acquiring a compositing layer for a\n\t// transform it does not use. It shares the panel's clock exactly, so the\n\t// two leave together and the \"destroy the subtree when the LAST\n\t// transition finishes\" rule is a tie rather than a straggler.\n\tconst scrimRef = presence.register(\"scrim\", anchored, (entering) => ({\n\t\tentering,\n\t\tscale: false,\n\t\tduration: DURATIONS.base,\n\t\texitDuration: DURATIONS.exit,\n\t}));\n\n\t// CONTRACT divergence, recorded in this folder's README: the `Portal`\n\t// stays mounted and its CHILDREN are what `presence.mounted` gates,\n\t// rather than the whole component returning `null`. `usePortalTarget`\n\t// resolves its container in a layout effect, so a `Portal` that mounts in\n\t// the same commit as the surface renders nothing on that pass — and the\n\t// registered nodes therefore do not exist yet when `usePresence`'s own\n\t// layout effect looks for legs to start, which settles the group\n\t// immediately and skips the entrance outright. Hoisting the `Portal`\n\t// above the gate resolves the container once, at this component's mount,\n\t// so every later open attaches its nodes in the very commit\n\t// `usePresence` is waiting for.\n\treturn (\n\t\t\n\t\t\t{presence.mounted ? (\n\t\t\t\t<>\n\t\t\t\t\t\n\t\t\t\t\t{/*\n\t\t\t\t\t\tNo portal-before-focus-trap ordering ceremony here (divergence\n\t\t\t\t\t\tD-10): `createPortal` commits children into the container before\n\t\t\t\t\t\tany effect runs and refs populate before layout effects, so the\n\t\t\t\t\t\tnode the trap focuses is always connected. The silent-no-op\n\t\t\t\t\t\t`.focus()` hazard the source's comment block warns about cannot\n\t\t\t\t\t\trecur.\n\n\t\t\t\t\t\t`data-state` is an ordinary attribute (divergence D-2) carrying\n\t\t\t\t\t\t`surfaceState`'s TWO values — never `\"opening\"` (convention C-5).\n\t\t\t\t\t\t`inert` is not written by hand either: `usePresence` sets it on\n\t\t\t\t\t\tevery registered node for the whole exit, which is exactly what\n\t\t\t\t\t\ta closing modal wants.\n\t\t\t\t\t*/}\n\t\t\t\t\t\n\t\t\t\t\t\t{children}\n\t\t\t\t\t\n\t\t\t\t\n\t\t\t) : null}\n\t\t\n\t);\n});\n\nDialogSurface.displayName = \"DialogSurface\";\n","type":"registry:ui","target":"@ui/fancy/components/dialog/DialogSurface.tsx"},{"path":"react/src/components/dialog/dialog-surface.css","content":"/*\n * The `