@alexgorbatchev/shadcn 0.0.19 → 0.0.20

package/llms/components/overlays/Drawer.md

@@ -0,0 +1,597 @@
+# Drawer
+
+Story: @alexgorbatchev/shadcn/components/overlays/Drawer
+Source: src/components/stories/overlays/Drawer.stories.tsx
+
+[Full source and local helpers](https://github.com/alexgorbatchev/shadcn/blob/main/src/components/stories/overlays/Drawer.stories.tsx)
+
+## Public imports
+
+```tsx
+import { Button, DensityProvider, DirectionProvider, Drawer, DrawerClose, DrawerContent, DrawerDescription, DrawerFooter, DrawerHeader, DrawerTitle, DrawerTrigger } from "@alexgorbatchev/shadcn";
+```
+
+## Supporting imports
+
+```tsx
+import type { ComponentProps } from "react";
+import { useState } from "react";
+```
+
+## Default component
+
+```tsx
+Drawer
+```
+
+## Story controls
+
+```tsx
+{
+    swipeDirection: { control: "select", options: ["down", "up", "left", "right"] },
+    showSwipeHandle: { control: "boolean" },
+    modal: { control: "select", options: [true, false, "trap-focus"] },
+}
+```
+
+## 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.
+
+### Default
+
+```tsx
+{
+    render: (args) => (<Drawer {...args}>
+      <DrawerTrigger render={<Button variant="outline"/>}>Open details</DrawerTrigger>
+      <DrawerContent>
+        <DrawerHeader>
+          <DrawerTitle>Project details</DrawerTitle>
+          <DrawerDescription>Review the project before continuing.</DrawerDescription>
+        </DrawerHeader>
+        <div className="p-panel">Three tasks are ready.</div>
+        <DrawerFooter>
+          <DrawerClose render={<Button />}>Done</DrawerClose>
+        </DrawerFooter>
+      </DrawerContent>
+    </Drawer>)
+}
+```
+
+### Open
+
+```tsx
+{
+    render: (args) => (<Drawer {...args}>
+      <DrawerTrigger render={<Button variant="outline"/>}>Open details</DrawerTrigger>
+      <DrawerContent>
+        <DrawerHeader>
+          <DrawerTitle>Project details</DrawerTitle>
+          <DrawerDescription>Review the project before continuing.</DrawerDescription>
+        </DrawerHeader>
+        <div className="p-panel">Three tasks are ready.</div>
+        <DrawerFooter>
+          <DrawerClose render={<Button />}>Done</DrawerClose>
+        </DrawerFooter>
+      </DrawerContent>
+    </Drawer>)
+}
+```
+
+### Up
+
+```tsx
+{
+    render: (args) => (<Drawer {...args}>
+      <DrawerTrigger render={<Button variant="outline"/>}>Open details</DrawerTrigger>
+      <DrawerContent>
+        <DrawerHeader>
+          <DrawerTitle>Project details</DrawerTitle>
+          <DrawerDescription>Review the project before continuing.</DrawerDescription>
+        </DrawerHeader>
+        <div className="p-panel">Three tasks are ready.</div>
+        <DrawerFooter>
+          <DrawerClose render={<Button />}>Done</DrawerClose>
+        </DrawerFooter>
+      </DrawerContent>
+    </Drawer>),
+    args: { swipeDirection: "up", showSwipeHandle: true }
+}
+```
+
+### Left
+
+```tsx
+{
+    render: (args) => (<Drawer {...args}>
+      <DrawerTrigger render={<Button variant="outline"/>}>Open details</DrawerTrigger>
+      <DrawerContent>
+        <DrawerHeader>
+          <DrawerTitle>Project details</DrawerTitle>
+          <DrawerDescription>Review the project before continuing.</DrawerDescription>
+        </DrawerHeader>
+        <div className="p-panel">Three tasks are ready.</div>
+        <DrawerFooter>
+          <DrawerClose render={<Button />}>Done</DrawerClose>
+        </DrawerFooter>
+      </DrawerContent>
+    </Drawer>),
+    args: { swipeDirection: "left", showSwipeHandle: true }
+}
+```
+
+### Right
+
+```tsx
+{
+    render: (args) => (<Drawer {...args}>
+      <DrawerTrigger render={<Button variant="outline"/>}>Open details</DrawerTrigger>
+      <DrawerContent>
+        <DrawerHeader>
+          <DrawerTitle>Project details</DrawerTitle>
+          <DrawerDescription>Review the project before continuing.</DrawerDescription>
+        </DrawerHeader>
+        <div className="p-panel">Three tasks are ready.</div>
+        <DrawerFooter>
+          <DrawerClose render={<Button />}>Done</DrawerClose>
+        </DrawerFooter>
+      </DrawerContent>
+    </Drawer>),
+    args: { swipeDirection: "right", modal: false }
+}
+```
+
+### SnapPoints
+
+```tsx
+{
+    render: (args) => (<Drawer {...args}>
+      <DrawerTrigger render={<Button variant="outline"/>}>Open details</DrawerTrigger>
+      <DrawerContent>
+        <DrawerHeader>
+          <DrawerTitle>Project details</DrawerTitle>
+          <DrawerDescription>Review the project before continuing.</DrawerDescription>
+        </DrawerHeader>
+        <div className="p-panel">Three tasks are ready.</div>
+        <DrawerFooter>
+          <DrawerClose render={<Button />}>Done</DrawerClose>
+        </DrawerFooter>
+      </DrawerContent>
+    </Drawer>),
+    args: { snapPoints: [0.5, 1], defaultSnapPoint: 0.5, showSwipeHandle: true }
+}
+```
+
+### FocusTrap
+
+```tsx
+{
+    render: (args) => (<Drawer {...args}>
+      <DrawerTrigger render={<Button variant="outline"/>}>Open details</DrawerTrigger>
+      <DrawerContent>
+        <DrawerHeader>
+          <DrawerTitle>Project details</DrawerTitle>
+          <DrawerDescription>Review the project before continuing.</DrawerDescription>
+        </DrawerHeader>
+        <div className="p-panel">Three tasks are ready.</div>
+        <DrawerFooter>
+          <DrawerClose render={<Button />}>Done</DrawerClose>
+        </DrawerFooter>
+      </DrawerContent>
+    </Drawer>),
+    args: { modal: "trap-focus" }
+}
+```
+
+### Nested
+
+```tsx
+{
+    render: (args) => (<DensityProvider density="compact">
+      <Drawer {...args} showSwipeHandle>
+        <DrawerTrigger render={<Button />}>Open parent</DrawerTrigger>
+        <DrawerContent>
+          <DrawerHeader>
+            <DrawerTitle>Parent drawer</DrawerTitle>
+            <DrawerDescription>Choose a task.</DrawerDescription>
+          </DrawerHeader>
+          <div className="p-panel">
+            <Drawer showSwipeHandle>
+              <DrawerTrigger render={<Button />}>Open child</DrawerTrigger>
+              <DrawerContent className={nestedClassName}>
+                <DrawerHeader>
+                  <DrawerTitle>Child drawer</DrawerTitle>
+                  <DrawerDescription>Review this task.</DrawerDescription>
+                </DrawerHeader>
+                <DrawerFooter>
+                  <DrawerClose render={<Button />}>Close child</DrawerClose>
+                </DrawerFooter>
+              </DrawerContent>
+            </Drawer>
+          </div>
+          <DrawerFooter>
+            <DrawerClose render={<Button />}>Close parent</DrawerClose>
+          </DrawerFooter>
+        </DrawerContent>
+      </Drawer>
+    </DensityProvider>)
+}
+```
+
+### Scrollable
+
+```tsx
+{
+    render: () => (<Drawer>
+      <DrawerTrigger render={<Button />}>Open activity</DrawerTrigger>
+      <DrawerContent>
+        <DrawerHeader>
+          <DrawerTitle>Project activity</DrawerTitle>
+          <DrawerDescription>Review the complete activity log.</DrawerDescription>
+        </DrawerHeader>
+        <div role="region" aria-label="Activity log" tabIndex={0} className="flex-1 overflow-y-auto p-panel">
+          {Array.from({ length: 50 }, (_, index) => (<p key={index} className="py-4">
+              Activity {index + 1}: Project update recorded.
+            </p>))}
+        </div>
+        <DrawerFooter>
+          <DrawerClose render={<Button />}>Finish review</DrawerClose>
+        </DrawerFooter>
+      </DrawerContent>
+    </Drawer>)
+}
+```
+
+### RightToLeft
+
+```tsx
+{
+    render: (args) => (<Drawer {...args}>
+      <DrawerTrigger render={<Button variant="outline"/>}>Open details</DrawerTrigger>
+      <DrawerContent>
+        <DrawerHeader>
+          <DrawerTitle>Project details</DrawerTitle>
+          <DrawerDescription>Review the project before continuing.</DrawerDescription>
+        </DrawerHeader>
+        <div className="p-panel">Three tasks are ready.</div>
+        <DrawerFooter>
+          <DrawerClose render={<Button />}>Done</DrawerClose>
+        </DrawerFooter>
+      </DrawerContent>
+    </Drawer>),
+    decorators: [
+        (Story) => (<DirectionProvider direction="rtl">
+        <div dir="rtl">
+          <Story />
+        </div>
+      </DirectionProvider>),
+    ],
+    args: { swipeDirection: "right", showSwipeHandle: true }
+}
+```
+
+### Payload
+
+```tsx
+{
+    render: () => (<Drawer<string>>
+      {({ payload }) => (<>
+          <DrawerTrigger<string> payload="Alpha" render={<Button />}>
+            Review Alpha
+          </DrawerTrigger>
+          <DrawerTrigger<string> payload="Beta" render={<Button />}>
+            Review Beta
+          </DrawerTrigger>
+          <DrawerContent>
+            <DrawerHeader>
+              <DrawerTitle>Review {payload?.toUpperCase()}</DrawerTitle>
+            </DrawerHeader>
+            <DrawerFooter>
+              <DrawerClose render={<Button />}>Done</DrawerClose>
+            </DrawerFooter>
+          </DrawerContent>
+        </>)}
+    </Drawer>)
+}
+```
+
+### RightToLeftScrollable
+
+```tsx
+{
+    render: () => (<Drawer>
+      <DrawerTrigger render={<Button />}>Open activity</DrawerTrigger>
+      <DrawerContent>
+        <DrawerHeader>
+          <DrawerTitle>Project activity</DrawerTitle>
+          <DrawerDescription>Review the complete activity log.</DrawerDescription>
+        </DrawerHeader>
+        <div role="region" aria-label="Activity log" tabIndex={0} className="flex-1 overflow-y-auto p-panel">
+          {Array.from({ length: 50 }, (_, index) => (<p key={index} className="py-4">
+              Activity {index + 1}: Project update recorded.
+            </p>))}
+        </div>
+        <DrawerFooter>
+          <DrawerClose render={<Button />}>Finish review</DrawerClose>
+        </DrawerFooter>
+      </DrawerContent>
+    </Drawer>),
+    decorators: RightToLeft.decorators
+}
+```
+
+### RightToLeftUp
+
+```tsx
+{
+    render: (args) => (<Drawer {...args}>
+      <DrawerTrigger render={<Button variant="outline"/>}>Open details</DrawerTrigger>
+      <DrawerContent>
+        <DrawerHeader>
+          <DrawerTitle>Project details</DrawerTitle>
+          <DrawerDescription>Review the project before continuing.</DrawerDescription>
+        </DrawerHeader>
+        <div className="p-panel">Three tasks are ready.</div>
+        <DrawerFooter>
+          <DrawerClose render={<Button />}>Done</DrawerClose>
+        </DrawerFooter>
+      </DrawerContent>
+    </Drawer>),
+    args: { swipeDirection: "up", showSwipeHandle: true },
+    decorators: RightToLeft.decorators
+}
+```
+
+### RightToLeftLeft
+
+```tsx
+{
+    render: (args) => (<Drawer {...args}>
+      <DrawerTrigger render={<Button variant="outline"/>}>Open details</DrawerTrigger>
+      <DrawerContent>
+        <DrawerHeader>
+          <DrawerTitle>Project details</DrawerTitle>
+          <DrawerDescription>Review the project before continuing.</DrawerDescription>
+        </DrawerHeader>
+        <div className="p-panel">Three tasks are ready.</div>
+        <DrawerFooter>
+          <DrawerClose render={<Button />}>Done</DrawerClose>
+        </DrawerFooter>
+      </DrawerContent>
+    </Drawer>),
+    args: { swipeDirection: "left", showSwipeHandle: true },
+    decorators: RightToLeft.decorators
+}
+```
+
+### SwipeHandle
+
+```tsx
+{
+    render: (args) => (<Drawer {...args}>
+      <DrawerTrigger render={<Button variant="outline"/>}>Open details</DrawerTrigger>
+      <DrawerContent>
+        <DrawerHeader>
+          <DrawerTitle>Project details</DrawerTitle>
+          <DrawerDescription>Review the project before continuing.</DrawerDescription>
+        </DrawerHeader>
+        <div className="p-panel">Three tasks are ready.</div>
+        <DrawerFooter>
+          <DrawerClose render={<Button />}>Done</DrawerClose>
+        </DrawerFooter>
+      </DrawerContent>
+    </Drawer>),
+    args: { showSwipeHandle: true }
+}
+```
+
+### NonModal
+
+```tsx
+{
+    args: { modal: false },
+    render: function Render(args) {
+        const [count, setCount] = useState(0);
+        return (<div className="flex flex-col items-start gap-4">
+        <Button onClick={() => setCount(count + 1)}>Outside counter</Button>
+        <output aria-label="Outside count">{count}</output>
+        <Drawer {...args} disablePointerDismissal swipeDirection="right">
+          <DrawerTrigger render={<Button />}>Open persistent drawer</DrawerTrigger>
+          <DrawerContent>
+            <DrawerHeader>
+              <DrawerTitle>Persistent drawer</DrawerTitle>
+              <DrawerDescription>The page remains interactive.</DrawerDescription>
+            </DrawerHeader>
+            <DrawerFooter>
+              <DrawerClose render={<Button />}>Done</DrawerClose>
+            </DrawerFooter>
+          </DrawerContent>
+        </Drawer>
+      </div>);
+    }
+}
+```
+
+### RightToLeftNonModal
+
+```tsx
+{
+    args: { modal: false },
+    render: function Render(args) {
+        const [count, setCount] = useState(0);
+        return (<div className="flex flex-col items-start gap-4">
+        <Button onClick={() => setCount(count + 1)}>Outside counter</Button>
+        <output aria-label="Outside count">{count}</output>
+        <Drawer {...args} disablePointerDismissal swipeDirection="right">
+          <DrawerTrigger render={<Button />}>Open persistent drawer</DrawerTrigger>
+          <DrawerContent>
+            <DrawerHeader>
+              <DrawerTitle>Persistent drawer</DrawerTitle>
+              <DrawerDescription>The page remains interactive.</DrawerDescription>
+            </DrawerHeader>
+            <DrawerFooter>
+              <DrawerClose render={<Button />}>Done</DrawerClose>
+            </DrawerFooter>
+          </DrawerContent>
+        </Drawer>
+      </div>);
+    },
+    decorators: RightToLeft.decorators
+}
+```
+
+### TrappedFocus
+
+```tsx
+{
+    args: { modal: "trap-focus" },
+    render: function Render(args) {
+        const [count, setCount] = useState(0);
+        return (<div className="flex flex-col items-start gap-4">
+        <Button onClick={() => setCount(count + 1)}>Outside counter</Button>
+        <output aria-label="Outside count">{count}</output>
+        <Drawer {...args} disablePointerDismissal swipeDirection="right">
+          <DrawerTrigger render={<Button />}>Open persistent drawer</DrawerTrigger>
+          <DrawerContent>
+            <DrawerHeader>
+              <DrawerTitle>Persistent drawer</DrawerTitle>
+              <DrawerDescription>The page remains interactive.</DrawerDescription>
+            </DrawerHeader>
+            <DrawerFooter>
+              <DrawerClose render={<Button />}>Done</DrawerClose>
+            </DrawerFooter>
+          </DrawerContent>
+        </Drawer>
+      </div>);
+    }
+}
+```
+
+### ControlledSnapPoints
+
+```tsx
+{
+    render: function Render() {
+        const [point, setPoint] = useState<ComponentProps<typeof Drawer>["snapPoint"]>(0.5);
+        return (<Drawer snapPoints={[0.5, 1]} snapPoint={point} onSnapPointChange={setPoint} showSwipeHandle>
+        <DrawerTrigger render={<Button />}>Open snap controls</DrawerTrigger>
+        <DrawerContent>
+          <DrawerHeader>
+            <DrawerTitle>Snap controls</DrawerTitle>
+            <DrawerDescription>Choose a compact or expanded view.</DrawerDescription>
+          </DrawerHeader>
+          <div className="flex flex-1 flex-col gap-4 p-panel">
+            <Button onClick={() => setPoint(1)}>Expand drawer</Button>
+            <Button onClick={() => setPoint(0.5)}>Compact drawer</Button>
+            <output aria-label="Active snap point">{point}</output>
+          </div>
+          <DrawerFooter>
+            <DrawerClose render={<Button />}>Done</DrawerClose>
+          </DrawerFooter>
+        </DrawerContent>
+      </Drawer>);
+    }
+}
+```
+
+### RightToLeftControlledSnapPoints
+
+```tsx
+{
+    render: function Render() {
+        const [point, setPoint] = useState<ComponentProps<typeof Drawer>["snapPoint"]>(0.5);
+        return (<Drawer snapPoints={[0.5, 1]} snapPoint={point} onSnapPointChange={setPoint} showSwipeHandle>
+        <DrawerTrigger render={<Button />}>Open snap controls</DrawerTrigger>
+        <DrawerContent>
+          <DrawerHeader>
+            <DrawerTitle>Snap controls</DrawerTitle>
+            <DrawerDescription>Choose a compact or expanded view.</DrawerDescription>
+          </DrawerHeader>
+          <div className="flex flex-1 flex-col gap-4 p-panel">
+            <Button onClick={() => setPoint(1)}>Expand drawer</Button>
+            <Button onClick={() => setPoint(0.5)}>Compact drawer</Button>
+            <output aria-label="Active snap point">{point}</output>
+          </div>
+          <DrawerFooter>
+            <DrawerClose render={<Button />}>Done</DrawerClose>
+          </DrawerFooter>
+        </DrawerContent>
+      </Drawer>);
+    },
+    decorators: RightToLeft.decorators
+}
+```
+
+### Responsive
+
+```tsx
+{
+    render: () => <ResponsiveDrawerExample />
+}
+```
+
+### RightToLeftResponsive
+
+```tsx
+{
+    render: () => <ResponsiveDrawerExample />,
+    decorators: RightToLeft.decorators
+}
+```
+
+### CustomHeight
+
+```tsx
+{
+    render: (args) => (<Drawer {...args}>
+      <DrawerTrigger render={<Button />}>Open half-height drawer</DrawerTrigger>
+      <DrawerContent className="h-[50vh]">
+        <DrawerHeader>
+          <DrawerTitle>Half-height drawer</DrawerTitle>
+          <DrawerDescription>A custom viewport-relative height.</DrawerDescription>
+        </DrawerHeader>
+        <DrawerFooter>
+          <DrawerClose render={<Button />}>Done</DrawerClose>
+        </DrawerFooter>
+      </DrawerContent>
+    </Drawer>)
+}
+```
+
+### CustomWidth
+
+```tsx
+{
+    render: (args) => (<Drawer {...args} swipeDirection="right">
+      <DrawerTrigger render={<Button />}>Open custom-width drawer</DrawerTrigger>
+      <DrawerContent className="w-80">
+        <DrawerHeader>
+          <DrawerTitle>Custom-width drawer</DrawerTitle>
+          <DrawerDescription>A custom side-panel width.</DrawerDescription>
+        </DrawerHeader>
+        <DrawerFooter>
+          <DrawerClose render={<Button />}>Done</DrawerClose>
+        </DrawerFooter>
+      </DrawerContent>
+    </Drawer>)
+}
+```
+
+### Inset
+
+```tsx
+{
+    render: (args) => (<Drawer {...args}>
+      <DrawerTrigger render={<Button />}>Open floating drawer</DrawerTrigger>
+      <DrawerContent className="[--drawer-inset:1rem]">
+        <DrawerHeader>
+          <DrawerTitle>Floating drawer</DrawerTitle>
+          <DrawerDescription>Inset from the viewport edges.</DrawerDescription>
+        </DrawerHeader>
+        <DrawerFooter>
+          <DrawerClose render={<Button />}>Done</DrawerClose>
+        </DrawerFooter>
+      </DrawerContent>
+    </Drawer>)
+}
+```