@alexgorbatchev/shadcn 0.0.19 → 0.0.21

package/llms/components/overlays/Dialog.md

@@ -0,0 +1,559 @@
+# Dialog
+
+Story: @alexgorbatchev/shadcn/components/overlays/Dialog
+Source: src/components/stories/overlays/Dialog.stories.tsx
+
+[Full source and local helpers](https://github.com/alexgorbatchev/shadcn/blob/main/src/components/stories/overlays/Dialog.stories.tsx)
+
+## Public imports
+
+```tsx
+import { Dialog, DialogTrigger, DialogContent, DialogHeader, DialogTitle, DialogDescription, DialogFooter, DialogClose, DialogPortal, DialogOverlay, Button, Field, FieldLabel, FieldGroup, Input, DensityProvider, DirectionProvider, ScrollArea } from "@alexgorbatchev/shadcn";
+```
+
+## Supporting imports
+
+```tsx
+import { useId, useRef, useState } from "react";
+import type { ComponentProps, ReactElement } from "react";
+import { Dialog as DialogPrimitive } from "@base-ui/react/dialog";
+import type { DialogRootChangeEventDetails } from "@base-ui/react/dialog";
+```
+
+## Default component
+
+```tsx
+Dialog
+```
+
+## Default args
+
+```tsx
+{ onOpenChange: fn(), onOpenChangeComplete: fn() }
+```
+
+## Default render
+
+```tsx
+function Render(args) {
+    const storyId = useId();
+    return (<Dialog {...args}>
+        <DialogTrigger render={<Button variant="outline"/>}>Edit profile</DialogTrigger>
+        <DialogContent>
+          <DialogHeader>
+            <DialogTitle>Edit profile</DialogTitle>
+            <DialogDescription>Update your display name.</DialogDescription>
+          </DialogHeader>
+          <Field>
+            <FieldLabel htmlFor={storyId}>Name</FieldLabel>
+            <Input id={storyId} defaultValue="Alex Gorbatchev"/>
+          </Field>
+          <DialogFooter>
+            <DialogClose render={<Button variant="outline"/>}>Cancel</DialogClose>
+            <DialogClose render={<Button />}>Save changes</DialogClose>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>);
+}
+```
+
+## Examples
+
+Storybook CSF excerpts. Default args and render apply unless overridden. Local helpers, fixtures, decorators, and providers may be required; these are reference excerpts, not standalone consumer modules. Interaction tests are omitted.
+
+### Fullscreen
+
+```tsx
+{
+    render: (args) => (<Dialog {...args}>
+      <DialogTrigger render={<Button />}>Expand diagram</DialogTrigger>
+      <DialogContent size="fullscreen">
+        <DialogTitle>Diagram canvas</DialogTitle>
+        <DialogDescription>Explore the diagram in the full viewport.</DialogDescription>
+      </DialogContent>
+    </Dialog>)
+}
+```
+
+### Default
+
+```tsx
+{}
+```
+
+### WideForm
+
+```tsx
+{
+    render: (args) => (<Dialog {...args}>
+      <DialogTrigger render={<Button />}>Edit metadata</DialogTrigger>
+      <DialogContent size="wide">
+        <DialogHeader>
+          <DialogTitle>Metadata</DialogTitle>
+          <DialogDescription>Two fields share a row.</DialogDescription>
+        </DialogHeader>
+        <FieldGroup columns={2}>
+          <Field>
+            <FieldLabel htmlFor="wide-title">Title</FieldLabel>
+            <Input id="wide-title"/>
+          </Field>
+          <Field>
+            <FieldLabel htmlFor="wide-artist">Artist</FieldLabel>
+            <Input id="wide-artist"/>
+          </Field>
+        </FieldGroup>
+      </DialogContent>
+    </Dialog>)
+}
+```
+
+### TallContent
+
+```tsx
+{
+    render: (args) => (<Dialog {...args}>
+      <DialogTrigger render={<Button />}>Review fields</DialogTrigger>
+      <DialogContent size="wide">
+        <DialogHeader>
+          <DialogTitle>Review fields</DialogTitle>
+          <DialogDescription>More fields than fit in the viewport.</DialogDescription>
+        </DialogHeader>
+        <form className="flex min-h-0 flex-col gap-panel" onSubmit={(event) => event.preventDefault()}>
+          <ScrollArea className="min-h-0">
+            <FieldGroup>
+              {Array.from({ length: 40 }, (_, index) => (<Field key={index}>
+                  <FieldLabel htmlFor={`tall-field-${index}`}>Field {index + 1}</FieldLabel>
+                  <Input id={`tall-field-${index}`}/>
+                </Field>))}
+            </FieldGroup>
+          </ScrollArea>
+          <DialogFooter>
+            <DialogClose render={<Button variant="outline"/>}>Cancel</DialogClose>
+            <Button type="submit">Apply</Button>
+          </DialogFooter>
+        </form>
+      </DialogContent>
+    </Dialog>)
+}
+```
+
+### Open
+
+```tsx
+{
+    args: { defaultOpen: true }
+}
+```
+
+### NonModal
+
+```tsx
+{
+    args: { modal: false },
+    render: (args) => (<>
+      <Button>Outside action</Button>
+      <Dialog {...args}>
+        <DialogTrigger render={<Button />}>Open nonmodal</DialogTrigger>
+        <DialogContent>
+          <DialogTitle>Nonmodal profile</DialogTitle>
+          <DialogDescription>Outside controls remain available.</DialogDescription>
+          <Input aria-label="Name"/>
+        </DialogContent>
+      </Dialog>
+    </>)
+}
+```
+
+### KeyboardFocusTrap
+
+```tsx
+{}
+```
+
+### DisabledTrigger
+
+```tsx
+{
+    render: (args) => (<Dialog {...args}>
+      <DialogTrigger disabled render={<Button />}>
+        Unavailable editor
+      </DialogTrigger>
+      <DialogContent>
+        <DialogTitle>Unavailable profile</DialogTitle>
+      </DialogContent>
+    </Dialog>)
+}
+```
+
+### CancelledOpening
+
+```tsx
+{
+    args: { onOpenChange: fn((_open: boolean, details: DialogRootChangeEventDetails) => details.cancel()) }
+}
+```
+
+### CancelledClosing
+
+```tsx
+{
+    args: {
+        onOpenChange: fn((open: boolean, details: DialogRootChangeEventDetails) => {
+            if (!open)
+                details.cancel();
+        }),
+    }
+}
+```
+
+### Controlled
+
+```tsx
+{
+    render: function Render() {
+        const [isOpen, setIsOpen] = useState(false);
+        return (<>
+        <Button onClick={() => setIsOpen(true)}>Show controlled editor</Button>
+        <Dialog open={isOpen} onOpenChange={setIsOpen}>
+          <DialogContent showCloseButton={false}>
+            <DialogTitle>Controlled profile</DialogTitle>
+            <DialogFooter showCloseButton/>
+          </DialogContent>
+        </Dialog>
+        <output aria-label="Dialog state">{String(isOpen)}</output>
+      </>);
+    }
+}
+```
+
+### OutsideDismissal
+
+```tsx
+{
+    render: (args) => (<Dialog {...args}>
+      <DialogTrigger render={<Button />}>Open dismissible editor</DialogTrigger>
+      <DialogContent showCloseButton={false}>
+        <DialogTitle>Dismissible profile</DialogTitle>
+        <DialogClose render={<Button />}>Done</DialogClose>
+      </DialogContent>
+    </Dialog>)
+}
+```
+
+### PreventOutsideDismissal
+
+```tsx
+{
+    args: { disablePointerDismissal: true }
+}
+```
+
+### NativeCallbacks
+
+```tsx
+{
+    render: (args) => (<Dialog {...args}>
+      <DialogTrigger className={(state) => (state.open ? "w-64" : "w-48")}>Callback editor</DialogTrigger>
+      <DialogContent className={(state) => (state.open ? "w-64" : "w-48")}>
+        <DialogTitle className={() => "h-12"}>Callback profile</DialogTitle>
+        <DialogDescription className={() => "h-10"}>Callback description</DialogDescription>
+        <DialogClose className={(state) => (state.disabled ? "h-12" : "h-8")}>Done</DialogClose>
+      </DialogContent>
+    </Dialog>)
+}
+```
+
+### OverlayCallback
+
+```tsx
+{
+    render: (args) => (<Dialog {...args}>
+      <DialogTrigger render={<Button />}>Open backdrop example</DialogTrigger>
+      <DialogPortal>
+        <DialogOverlay data-testid="Dialog--overlay" className={(state) => (state.open ? "opacity-50" : "opacity-0")}/>
+        <DialogPrimitive.Popup className="fixed top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2 bg-popover p-panel">
+          <DialogTitle>Backdrop example</DialogTitle>
+          <DialogClose render={<Button />}>Done</DialogClose>
+        </DialogPrimitive.Popup>
+      </DialogPortal>
+    </Dialog>)
+}
+```
+
+### CompactPortal
+
+```tsx
+{
+    render: (args) => (<DensityProvider density="compact">
+      <Dialog {...args}>
+        <DialogTrigger render={<Button />}>Open compact editor</DialogTrigger>
+        <DialogContent showCloseButton={false}>
+          <DialogTitle>Compact profile</DialogTitle>
+          <DialogDescription>Compact portal content.</DialogDescription>
+          <DialogFooter showCloseButton/>
+        </DialogContent>
+      </Dialog>
+    </DensityProvider>)
+}
+```
+
+### RTL
+
+```tsx
+{
+    render: (args) => (<DirectionProvider direction="rtl">
+      <section dir="rtl">
+        <Dialog {...args}>
+          <DialogTrigger render={<Button />}>Open RTL editor</DialogTrigger>
+          <DialogContent>
+            <DialogTitle>RTL profile</DialogTitle>
+            <DialogDescription>Direction follows the portal.</DialogDescription>
+          </DialogContent>
+        </Dialog>
+      </section>
+    </DirectionProvider>)
+}
+```
+
+### CustomFocusAndNativeRender
+
+```tsx
+{
+    render: function Render(args) {
+        const inputRef = useRef<HTMLInputElement>(null);
+        const finalRef = useRef<HTMLButtonElement>(null);
+        const popupRef = useRef<HTMLDivElement>(null);
+        return (<>
+        <Button ref={finalRef}>Return target</Button>
+        <Dialog {...args}>
+          <DialogTrigger render={<button type="button"/>}>Custom focus editor</DialogTrigger>
+          <DialogContent render={<section />} ref={popupRef} initialFocus={inputRef} finalFocus={finalRef}>
+            <DialogTitle>Custom focus profile</DialogTitle>
+            <Input ref={inputRef} aria-label="Preferred field"/>
+            <DialogClose render={<Button />}>Done</DialogClose>
+            <Button onClick={() => popupRef.current?.focus()}>Focus surface</Button>
+          </DialogContent>
+        </Dialog>
+      </>);
+    }
+}
+```
+
+### FooterCloseOnly
+
+```tsx
+{
+    render: (args) => (<Dialog {...args}>
+      <DialogTrigger render={<Button />}>Open footer example</DialogTrigger>
+      <DialogContent showCloseButton={false}>
+        <DialogTitle>Footer example</DialogTitle>
+        <DialogFooter showCloseButton/>
+      </DialogContent>
+    </Dialog>)
+}
+```
+
+### Nested
+
+```tsx
+{
+    render: (args) => (<Dialog {...args}>
+      <DialogTrigger render={<Button />}>Open parent</DialogTrigger>
+      <DialogContent>
+        <DialogTitle>Parent editor</DialogTitle>
+        <Dialog>
+          <DialogTrigger render={<Button />}>Open child</DialogTrigger>
+          <DialogContent>
+            <DialogTitle>Child editor</DialogTitle>
+            <DialogClose render={<Button />}>Finish child</DialogClose>
+          </DialogContent>
+        </Dialog>
+      </DialogContent>
+    </Dialog>)
+}
+```
+
+### Payload
+
+```tsx
+{
+    render: () => (<Dialog<string>>
+      {({ payload }) => (<>
+          <DialogTrigger<string> payload="Alex">Edit Alex</DialogTrigger>
+          <DialogTrigger<string> payload="Blair">Edit Blair</DialogTrigger>
+          <DialogContent>
+            <DialogTitle>Edit {payload}</DialogTitle>
+            <DialogClose render={<Button />}>Done</DialogClose>
+          </DialogContent>
+        </>)}
+    </Dialog>)
+}
+```
+
+### FocusTrapWithoutScrollLock
+
+```tsx
+{
+    render: function Render(args) {
+        const [count, setCount] = useState(0);
+        return (<>
+        <Button onClick={() => setCount(count + 1)}>Outside counter</Button>
+        <output aria-label="Outside count">{count}</output>
+        <Dialog {...args} modal="trap-focus" disablePointerDismissal>
+          <DialogTrigger render={<Button />}>Open focus trap</DialogTrigger>
+          <DialogContent>
+            <DialogTitle>Focus trap</DialogTitle>
+            <Input aria-label="Trapped field"/>
+          </DialogContent>
+        </Dialog>
+      </>);
+    }
+}
+```
+
+### ImperativeClosing
+
+```tsx
+{
+    render: function Render(args) {
+        const actionsRef = useRef<DialogPrimitive.Root.Actions>(null);
+        return (<Dialog {...args} actionsRef={actionsRef}>
+        <DialogTrigger render={<Button />}>Open imperative editor</DialogTrigger>
+        <DialogContent>
+          <DialogTitle>Imperative editor</DialogTitle>
+          <Button onClick={() => actionsRef.current?.close()}>Finish imperatively</Button>
+        </DialogContent>
+      </Dialog>);
+    }
+}
+```
+
+### NativeForm
+
+```tsx
+{
+    render: function Render() {
+        const [isOpen, setIsOpen] = useState(false), [saved, setSaved] = useState("");
+        const id = useId();
+        return (<>
+        <Dialog open={isOpen} onOpenChange={setIsOpen}>
+          <DialogTrigger render={<Button />}>Open profile form</DialogTrigger>
+          <DialogContent>
+            <DialogTitle>Profile form</DialogTitle>
+            <form aria-label="Profile form" onSubmit={(event) => {
+                event.preventDefault();
+                setSaved(String(new FormData(event.currentTarget).get("name")));
+                setIsOpen(false);
+            }}>
+              <Field>
+                <FieldLabel htmlFor={id}>Name</FieldLabel>
+                <Input id={id} name="name" required defaultValue="Alex"/>
+              </Field>
+              <Button type="reset">Reset name</Button>
+              <Button type="submit">Save profile</Button>
+            </form>
+          </DialogContent>
+        </Dialog>
+        <output aria-label="Saved name">{saved}</output>
+      </>);
+    }
+}
+```
+
+### DetachedTriggers
+
+```tsx
+{
+    render: function Render() {
+        const [handle] = useState(() => DialogPrimitive.createHandle<string>());
+        return (<>
+        <DialogTrigger handle={handle} payload="Alex" render={<Button />}>
+          Detached Alex
+        </DialogTrigger>
+        <DialogTrigger handle={handle} payload="Blair" render={<Button />}>
+          Detached Blair
+        </DialogTrigger>
+        <Dialog handle={handle}>
+          {({ payload }) => (<DialogContent>
+              <DialogTitle>Detached {payload}</DialogTitle>
+              <DialogClose render={<Button />}>Done</DialogClose>
+            </DialogContent>)}
+        </Dialog>
+      </>);
+    }
+}
+```
+
+### StickyFooter
+
+```tsx
+{
+    render: (args) => <ScrollableDialogExample {...args} hasFooter/>
+}
+```
+
+### RTLStickyFooter
+
+```tsx
+{
+    render: (args) => <ScrollableDialogExample {...args} hasFooter direction="rtl"/>
+}
+```
+
+### ScrollableContent
+
+```tsx
+{
+    render: (args) => <ScrollableDialogExample {...args}/>
+}
+```
+
+### RTLScrollableContent
+
+```tsx
+{
+    render: (args) => <ScrollableDialogExample {...args} direction="rtl"/>
+}
+```
+
+### CustomCloseButton
+
+```tsx
+{
+    render: function Render(args) {
+        const id = useId();
+        return (<Dialog {...args}>
+        <DialogTrigger render={<Button />}>Share project</DialogTrigger>
+        <DialogContent showCloseButton={false}>
+          <DialogHeader>
+            <DialogTitle>Share link</DialogTitle>
+            <DialogDescription>Anyone with this link can view the project.</DialogDescription>
+          </DialogHeader>
+          <Field>
+            <FieldLabel htmlFor={id}>Project link</FieldLabel>
+            <Input id={id} readOnly defaultValue="https://example.com/project"/>
+          </Field>
+          <DialogFooter>
+            <DialogClose render={<Button variant="outline"/>}>Done sharing</DialogClose>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>);
+    }
+}
+```
+
+### NoCloseButton
+
+```tsx
+{
+    render: (args) => (<Dialog {...args}>
+      <DialogTrigger render={<Button />}>Read information</DialogTrigger>
+      <DialogContent showCloseButton={false}>
+        <DialogHeader>
+          <DialogTitle>Information</DialogTitle>
+          <DialogDescription>Press Escape to return.</DialogDescription>
+        </DialogHeader>
+      </DialogContent>
+    </Dialog>)
+}
+```