Initial Commit

packages/ui/react/react-ui/src/components/drawer/drawer.variants.md

@@ -0,0 +1,64 @@
+# Drawer Variants (cva config)
+
+## Purpose
+
+`drawerOverlayVariants`, `drawerContentVariants`, `drawerHandleVariants`, `drawerHeaderVariants`, `drawerFooterVariants`, `drawerTitleVariants`, and `drawerDescriptionVariants` are the cva configurations powering every `<Drawer>` slot. They are split from `drawer.tsx` into their own module so an ejected source copy under `npx shadcn@latest add @suaveplan/drawer` keeps the cva configurations in a dedicated file. Theme overrides flow through `useThemedVariants("Drawer<Slot>")`.
+
+All slots are layout-only — the chassis cva does not parameterise the drawer's behaviour (vaul handles snap-points / direction / background-scale at the runtime level), only its visual recipe.
+
+## Features
+
+- Overlay: `fixed inset-0 bg-black/80` matching Sheet/Dialog visual language.
+- Content: `fixed inset-x-0 bottom-0` anchored to the bottom of the viewport with rounded top, border, and bg-background fill.
+- Handle: small `bg-muted` pill rendered above the panel content as a drag affordance.
+- Header / footer / title / description: layout-only utilities matching the shadcn upstream `drawer` recipe.
+- NEVER carries a numeric `z-index` (vaul/Radix Portal handle stacking).
+
+## Usage: Basic Example
+
+```ts
+import { drawerContentVariants, drawerTitleVariants } from "@suaveplan/react-ui";
+
+const contentClassName = drawerContentVariants();
+const titleClassName = drawerTitleVariants();
+```
+
+## Usage: Advanced Example
+
+```ts
+import { drawerContentVariants, cn } from "@suaveplan/react-ui";
+
+export function CustomBottomSheet() {
+    return (
+        <div
+            role="dialog"
+            aria-modal="true"
+            className={cn(
+                drawerContentVariants(),
+                "border-t-2 border-primary"
+            )}
+        >
+            …
+        </div>
+    );
+}
+```
+
+## API Reference
+
+Every cva resolver returns a single class string suitable for use inside `cn(...)` chains. None take arguments — the drawer slots are not parameterised by design.
+
+- `drawerOverlayVariants(): string`
+- `drawerContentVariants(): string`
+- `drawerHandleVariants(): string`
+- `drawerHeaderVariants(): string`
+- `drawerFooterVariants(): string`
+- `drawerTitleVariants(): string`
+- `drawerDescriptionVariants(): string`
+
+## Implementation Notes
+
+- Per the shadcn skill rule, the cva NEVER assigns a numeric `z-index`. Vaul wraps Radix's `<Portal>` to host the content above all page content via DOM placement.
+- The chassis paints the drawer's visual recipe; vaul provides the slide animation, snap-point physics, and swipe-down-dismiss gesture at runtime.
+- The handle slot uses `mx-auto` so it stays centred regardless of the drawer's width — RTL-safe by construction.
+- Padding (`p-4`) on header / footer is applied at the slot level so consumers can override per-instance via `cn(...)` without touching the cva.