@varialkit/drawer 0.1.0

package/docs.md

@@ -0,0 +1,78 @@
+# Drawer
+
+Drawer slides in from the side to show supporting tasks or context without leaving the page.
+Use it for secondary flows, filters, and detailed panels.
+
+## How to Use
+
+```tsx
+import { Drawer } from "@solara/drawer";
+
+export function Example() {
+  return (
+    <Drawer isOpen onClose={() => {}}>
+      <Drawer.Header onClose={() => {}}>
+        <Drawer.Title>Filters</Drawer.Title>
+      </Drawer.Header>
+      <Drawer.Content>Drawer content goes here.</Drawer.Content>
+      <Drawer.Footer
+        primaryButton={{ label: "Apply", onClick: () => {} }}
+        secondaryButton={{ label: "Reset", onClick: () => {} }}
+      />
+    </Drawer>
+  );
+}
+```
+
+## Best Practices
+
+- Keep drawers task-focused and easy to dismiss.
+- Use drawers for secondary workflows instead of primary actions.
+- Avoid stacking multiple drawers.
+- Use `sliding` when people need to resize the drawer from the exposed edge without shifting the main drawer surface.
+
+## Props
+
+### Drawer
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `isOpen` | `boolean` | _Required_ | Controls visibility. |
+| `onClose` | `() => void` | _Required_ | Close handler. |
+| `position` | `"left" \| "right"` | `"right"` | Drawer side. |
+| `overlay` | `boolean` | `true` | Show an overlay behind the drawer. |
+| `closeOnOverlayClick` | `boolean` | `true` | Close on overlay click. |
+| `closeOnEscape` | `boolean` | `true` | Close on Escape. |
+| `size` | `"sm" \| "md" \| "lg" \| "xl" \| string \| number` | `"md"` | Drawer width. Can be a preset size or a custom CSS value (e.g., "500px"). |
+| `sliding` | `boolean` | `false` | Enables a resize handle that sits just outside the drawer edge. Right drawers expose the handle on the left; left drawers expose it on the right. |
+| `minWidth` | `number \| \`${number}px\`` | `280` | Minimum width when `sliding` is enabled. |
+| `maxWidth` | `number \| \`${number}px\`` | `viewport width - 48px` | Maximum width when `sliding` is enabled. |
+| `overlayClassName` | `string` | | Extra overlay class. |
+| `allowContentOverflow` | `boolean` | `false` | Allow content to overflow. |
+| `floating` | `boolean` | `false` | Renders the drawer with a margin around it. |
+| `className` | `string` | | Custom class name. |
+
+### DrawerHeader
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `showCloseButton` | `boolean` | `true` | Show close icon. |
+| `closeButtonAriaLabel` | `string` | `"Close drawer"` | Close button aria label. |
+| `rightContent` | `ReactNode` | | Right-side header content. |
+| `subheader` | `ReactNode` | | Secondary header text. |
+| `bordered` | `boolean` | `true` | Show header divider. |
+| `onClose` | `() => void` | _Required_ | Close handler. |
+
+### DrawerContent
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `noPadding` | `boolean` | `false` | Remove default padding. |
+
+### DrawerFooter
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `primaryButton` | `FooterButtonProps` | | Primary action. |
+| `secondaryButton` | `FooterButtonProps` | | Secondary action. |
+| `dangerButton` | `FooterButtonProps` | | Destructive action. |

package/examples/index.tsx

@@ -0,0 +1 @@
+export { stories } from "../examples";

package/examples.tsx

@@ -0,0 +1,407 @@
+import React from "react";
+import { Drawer } from "./src/Drawer";
+import type { DrawerProps } from "./src/Drawer.types";
+import { Button } from "@solara/button";
+
+type DrawerStoryProps = DrawerProps & {
+  noPadding?: boolean;
+  showSubheader?: boolean;
+  showRightContent?: boolean;
+  floating?: boolean;
+};
+
+const DrawerPlayground = (props: DrawerStoryProps) => {
+  const isControlled = typeof props.isOpen === "boolean";
+  const [open, setOpen] = React.useState(props.isOpen ?? false);
+
+  React.useEffect(() => {
+    if (isControlled) {
+      setOpen(props.isOpen as boolean);
+    }
+  }, [isControlled, props.isOpen]);
+
+  return (
+    <div style={{ display: "flex", flexDirection: "column", gap: "1rem" }}>
+      <Button label="Open drawer" onClick={() => setOpen(true)} />
+      <Drawer
+        isOpen={open}
+        onClose={() => setOpen(false)}
+        position={props.position}
+        overlay={props.overlay}
+        closeOnOverlayClick={props.closeOnOverlayClick}
+        closeOnEscape={props.closeOnEscape}
+        size={props.size}
+        sliding={props.sliding}
+        minWidth={props.minWidth}
+        maxWidth={props.maxWidth}
+        allowContentOverflow={props.allowContentOverflow}
+        floating={props.floating}
+      >
+        <Drawer.Header
+          onClose={() => setOpen(false)}
+          subheader={
+            props.showSubheader ? (
+              <span style={{ fontSize: "0.75rem", color: "var(--color-text-secondary)" }}>
+                Updated just now
+              </span>
+            ) : undefined
+          }
+          rightContent={
+            props.showRightContent ? (
+              <span style={{ fontSize: "0.75rem", color: "var(--color-text-secondary)" }}>
+                3 filters
+              </span>
+            ) : null
+          }
+        >
+          <Drawer.Title>Filters</Drawer.Title>
+        </Drawer.Header>
+        <Drawer.Content noPadding={props.noPadding}>
+          <div style={{ display: "grid", gap: "0.75rem" }}>
+            <p style={{ margin: 0 }}>
+              Add filters, secondary tasks, or contextual notes without leaving the current page.
+            </p>
+            <ul style={{ margin: 0, paddingLeft: "1.25rem" }}>
+              <li>Status: Active</li>
+              <li>Owner: Design</li>
+              <li>Last updated: 2 days ago</li>
+            </ul>
+          </div>
+        </Drawer.Content>
+        <Drawer.Footer
+          primaryButton={{ label: "Apply", onClick: () => setOpen(false) }}
+          secondaryButton={{ label: "Reset", onClick: () => setOpen(false) }}
+        />
+      </Drawer>
+    </div>
+  );
+};
+
+const DrawerSlidingStory = () => {
+  const [open, setOpen] = React.useState(false);
+  return (
+    <div style={{ display: "flex", flexDirection: "column", gap: "1rem" }}>
+      <Button label="Open sliding drawer" onClick={() => setOpen(true)} />
+      <Drawer
+        isOpen={open}
+        onClose={() => setOpen(false)}
+        position="right"
+        size="lg"
+        sliding
+        minWidth={320}
+        maxWidth={720}
+      >
+        <Drawer.Header onClose={() => setOpen(false)}>
+          <Drawer.Title>Resizable drawer</Drawer.Title>
+        </Drawer.Header>
+        <Drawer.Content>
+          <p style={{ marginTop: 0 }}>
+            Drag the handle that sits outside the drawer edge to resize it without moving the main content area.
+          </p>
+          <p style={{ marginBottom: 0 }}>
+            On right drawers the handle appears on the left edge. On left drawers it appears on the right edge.
+          </p>
+        </Drawer.Content>
+      </Drawer>
+    </div>
+  );
+};
+
+const DrawerHeaderStory = () => {
+  const [open, setOpen] = React.useState(false);
+  return (
+    <div style={{ display: "flex", flexDirection: "column", gap: "1rem" }}>
+      <Button label="Open drawer" onClick={() => setOpen(true)} />
+      <Drawer isOpen={open} onClose={() => setOpen(false)} overlay closeOnOverlayClick closeOnEscape>
+        <Drawer.Header
+          onClose={() => setOpen(false)}
+          subheader={<span style={{ fontSize: "0.75rem" }}>Header-only</span>}
+          rightContent={<span style={{ fontSize: "0.75rem" }}>3 filters</span>}
+        >
+          <Drawer.Title>Header example</Drawer.Title>
+        </Drawer.Header>
+      </Drawer>
+    </div>
+  );
+};
+
+const DrawerFooterStory = () => {
+  const [open, setOpen] = React.useState(false);
+  return (
+    <div style={{ display: "flex", flexDirection: "column", gap: "1rem" }}>
+      <Button label="Open drawer" onClick={() => setOpen(true)} />
+      <Drawer isOpen={open} onClose={() => setOpen(false)} overlay closeOnOverlayClick closeOnEscape>
+        <Drawer.Footer
+          primaryButton={{ label: "Apply", onClick: () => setOpen(false) }}
+          secondaryButton={{ label: "Cancel", onClick: () => setOpen(false) }}
+        />
+      </Drawer>
+    </div>
+  );
+};
+
+const DrawerNoOverlayStory = () => {
+  const [open, setOpen] = React.useState(false);
+  return (
+    <div style={{ display: "flex", flexDirection: "column", gap: "1rem" }}>
+      <Button label="Open drawer (no overlay)" onClick={() => setOpen(true)} />
+      <Drawer isOpen={open} onClose={() => setOpen(false)} overlay={false}>
+        <Drawer.Header onClose={() => setOpen(false)}>
+          <Drawer.Title>Drawer without overlay</Drawer.Title>
+        </Drawer.Header>
+        <Drawer.Content>
+          <p>This drawer does not have an overlay.</p>
+        </Drawer.Content>
+      </Drawer>
+    </div>
+  );
+};
+
+const DrawerFloatingStory = () => {
+  const [open, setOpen] = React.useState(false);
+  return (
+    <div style={{ display: "flex", flexDirection: "column", gap: "1rem" }}>
+      <Button label="Open floating drawer" onClick={() => setOpen(true)} />
+      <Drawer isOpen={open} onClose={() => setOpen(false)} floating>
+        <Drawer.Header onClose={() => setOpen(false)}>
+          <Drawer.Title>Floating Drawer</Drawer.Title>
+        </Drawer.Header>
+        <Drawer.Content>
+          <p>This drawer has a margin around it.</p>
+        </Drawer.Content>
+      </Drawer>
+    </div>
+  );
+};
+
+const DrawerCustomWidthStory = () => {
+  const [open, setOpen] = React.useState(false);
+  return (
+    <div style={{ display: "flex", flexDirection: "column", gap: "1rem" }}>
+      <Button label="Open drawer (custom width)" onClick={() => setOpen(true)} />
+      <Drawer isOpen={open} onClose={() => setOpen(false)} size="500px">
+        <Drawer.Header onClose={() => setOpen(false)}>
+          <Drawer.Title>Drawer with custom width</Drawer.Title>
+        </Drawer.Header>
+        <Drawer.Content>
+          <p>This drawer has a custom width of 500px.</p>
+        </Drawer.Content>
+      </Drawer>
+    </div>
+  );
+};
+
+export const stories = {
+  playground: {
+    title: "Playground",
+    description: "Adjust the Drawer props to explore behavior.",
+    render: (props: DrawerStoryProps) => <DrawerPlayground {...props} />,
+    controls: [
+      { name: "size", type: "select", options: ["sm", "md", "lg", "xl"] },
+      { name: "position", type: "select", options: ["left", "right"] },
+      { name: "floating", type: "boolean" },
+      { name: "sliding", type: "boolean" },
+      { name: "minWidth", type: "text" },
+      { name: "maxWidth", type: "text" },
+      { name: "overlay", type: "boolean" },
+      { name: "closeOnOverlayClick", type: "boolean" },
+      { name: "closeOnEscape", type: "boolean" },
+      { name: "allowContentOverflow", type: "boolean" },
+      { name: "noPadding", type: "boolean" },
+      { name: "showSubheader", type: "boolean" },
+      { name: "showRightContent", type: "boolean" },
+      { name: "isOpen", type: "boolean" },
+    ],
+    initialProps: {
+      size: "md",
+      position: "right",
+      floating: false,
+      sliding: false,
+      minWidth: 280,
+      maxWidth: 960,
+      overlay: true,
+      closeOnOverlayClick: true,
+      closeOnEscape: true,
+      allowContentOverflow: false,
+      noPadding: false,
+      showSubheader: true,
+      showRightContent: true,
+      isOpen: false,
+    },
+  },
+  sliding: {
+    title: "Sliding",
+    description: "Resizable drawer with an external drag handle anchored to the exposed edge.",
+    showProps: false,
+    render: () => <DrawerSlidingStory />,
+    code: `import React from "react";
+import { Button } from "@solara/button";
+import { Drawer } from "@solara/drawer";
+
+export function Example() {
+  const [open, setOpen] = React.useState(false);
+
+  return (
+    <div style={{ display: "flex", flexDirection: "column", gap: "1rem" }}>
+      <Button label="Open sliding drawer" onClick={() => setOpen(true)} />
+      <Drawer
+        isOpen={open}
+        onClose={() => setOpen(false)}
+        position="right"
+        size="lg"
+        sliding
+        minWidth={320}
+        maxWidth={720}
+      >
+        <Drawer.Header onClose={() => setOpen(false)}>
+          <Drawer.Title>Resizable drawer</Drawer.Title>
+        </Drawer.Header>
+        <Drawer.Content>
+          <p>Drag the outside handle to resize the drawer.</p>
+        </Drawer.Content>
+      </Drawer>
+    </div>
+  );
+}
+`,
+  },
+  header: {
+    title: "Header",
+    description: "Header-only configuration with subheader and right content.",
+    showProps: false,
+    render: () => <DrawerHeaderStory />,
+    code: `import React from "react";
+import { Button } from "@solara/button";
+import { Drawer } from "@solara/drawer";
+
+export function Example() {
+  const [open, setOpen] = React.useState(false);
+
+  return (
+    <div style={{ display: "flex", flexDirection: "column", gap: "1rem" }}>
+      <Button label="Open drawer" onClick={() => setOpen(true)} />
+      <Drawer isOpen={open} onClose={() => setOpen(false)} overlay closeOnOverlayClick closeOnEscape>
+        <Drawer.Header
+          onClose={() => setOpen(false)}
+          subheader={<span style={{ fontSize: "0.75rem" }}>Header-only</span>}
+          rightContent={<span style={{ fontSize: "0.75rem" }}>3 filters</span>}
+        >
+          <Drawer.Title>Header example</Drawer.Title>
+        </Drawer.Header>
+      </Drawer>
+    </div>
+  );
+}
+`,
+  },
+  footer: {
+    title: "Footer",
+    description: "Footer-only configuration with primary/secondary actions.",
+    showProps: false,
+    render: () => <DrawerFooterStory />,
+    code: `import React from "react";
+import { Button } from "@solara/button";
+import { Drawer } from "@solara/drawer";
+
+export function Example() {
+  const [open, setOpen] = React.useState(false);
+
+  return (
+    <div style={{ display: "flex", flexDirection: "column", gap: "1rem" }}>
+      <Button label="Open drawer" onClick={() => setOpen(true)} />
+      <Drawer isOpen={open} onClose={() => setOpen(false)} overlay closeOnOverlayClick closeOnEscape>
+        <Drawer.Footer
+          primaryButton={{ label: "Apply", onClick: () => setOpen(false) }}
+          secondaryButton={{ label: "Cancel", onClick: () => setOpen(false) }}
+        />
+      </Drawer>
+    </div>
+  );
+}
+`,
+  },
+  noOverlay: {
+    title: "No Overlay",
+    description: "Drawer without a background overlay.",
+    showProps: false,
+    render: () => <DrawerNoOverlayStory />,
+    code: `import React from "react";
+import { Button } from "@solara/button";
+import { Drawer } from "@solara/drawer";
+
+export function Example() {
+  const [open, setOpen] = React.useState(false);
+
+  return (
+    <div style={{ display: "flex", flexDirection: "column", gap: "1rem" }}>
+      <Button label="Open drawer (no overlay)" onClick={() => setOpen(true)} />
+      <Drawer isOpen={open} onClose={() => setOpen(false)} overlay={false}>
+        <Drawer.Header onClose={() => setOpen(false)}>
+          <Drawer.Title>Drawer without overlay</Drawer.Title>
+        </Drawer.Header>
+        <Drawer.Content>
+          <p>This drawer does not have an overlay.</p>
+        </Drawer.Content>
+      </Drawer>
+    </div>
+  );
+}
+`,
+  },
+  floating: {
+    title: "Floating",
+    description: "Drawer with a margin around it.",
+    showProps: false,
+    render: () => <DrawerFloatingStory />,
+    code: `import React from "react";
+import { Button } from "@solara/button";
+import { Drawer } from "@solara/drawer";
+
+export function Example() {
+  const [open, setOpen] = React.useState(false);
+
+  return (
+    <div style={{ display: "flex", flexDirection: "column", gap: "1rem" }}>
+      <Button label="Open floating drawer" onClick={() => setOpen(true)} />
+      <Drawer isOpen={open} onClose={() => setOpen(false)} floating>
+        <Drawer.Header onClose={() => setOpen(false)}>
+          <Drawer.Title>Floating Drawer</Drawer.Title>
+        </Drawer.Header>
+        <Drawer.Content>
+          <p>This drawer has a margin around it.</p>
+        </Drawer.Content>
+      </Drawer>
+    </div>
+  );
+}
+`,
+  },
+  customWidth: {
+    title: "Custom Width",
+    description: "Drawer with a custom width.",
+    showProps: false,
+    render: () => <DrawerCustomWidthStory />,
+    code: `import React from "react";
+import { Button } from "@solara/button";
+import { Drawer } from "@solara/drawer";
+
+export function Example() {
+  const [open, setOpen] = React.useState(false);
+
+  return (
+    <div style={{ display: "flex", flexDirection: "column", gap: "1rem" }}>
+      <Button label="Open drawer (custom width)" onClick={() => setOpen(true)} />
+      <Drawer isOpen={open} onClose={() => setOpen(false)} size="500px">
+        <Drawer.Header onClose={() => setOpen(false)}>
+          <Drawer.Title>Drawer with custom width</Drawer.Title>
+        </Drawer.Header>
+        <Drawer.Content>
+          <p>This drawer has a custom width of 500px.</p>
+        </Drawer.Content>
+      </Drawer>
+    </div>
+  );
+}
+`,
+  },
+};

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@varialkit/drawer",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./examples": "./examples/index.tsx"
+  },
+  "dependencies": {
+    "@varialkit/button": "0.1.0"
+  },
+  "files": [
+    "src",
+    "docs.md",
+    "examples",
+    "examples.tsx"
+  ],
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "19.0.10",
+    "react": "19.0.0",
+    "react-dom": "19.0.0"
+  }
+}

package/src/Drawer.scss

@@ -0,0 +1,334 @@
+@keyframes solara-drawer-fade-in {
+  from {
+    opacity: 0;
+  }
+
+  to {
+    opacity: 1;
+  }
+}
+
+@keyframes solara-drawer-slide-in-right {
+  from {
+    transform: translateX(32px);
+  }
+
+  to {
+    transform: translateX(0);
+  }
+}
+
+@keyframes solara-drawer-slide-in-left {
+  from {
+    transform: translateX(-32px);
+  }
+
+  to {
+    transform: translateX(0);
+  }
+}
+
+.solara-drawer__overlay {
+  position: fixed;
+  inset: 0;
+  background-color: rgba(var(--overlay-backdrop-rgb), var(--overlay-backdrop-opacity));
+  z-index: 3000;
+  backdrop-filter: blur(var(--overlay-backdrop-blur));
+  animation: solara-drawer-fade-in 0.2s ease-out;
+
+  @media (prefers-reduced-motion: reduce) {
+    animation: none;
+  }
+}
+
+.solara-drawer {
+  position: fixed;
+  top: 0;
+  bottom: 0;
+  width: 100%;
+  max-width: 28rem;
+  --drawer-surface-color: var(--color-surface-100);
+  --drawer-surface-color-rgb: var(--color-surface-100-rgb);
+  --surface-border-color: var(--color-divider-secondary);
+  --surface-border-color-rgb: var(--color-divider-secondary-rgb);
+  --surface-opacity: 1;
+  --surface-blur: 0px;
+  --surface-shadow: var(--shadow-md);
+  --drawer-resize-grip-color: color-mix(in srgb, var(--color-text-secondary) 78%, var(--color-divider-primary));
+  --drawer-resize-grip-hover-color: color-mix(in srgb, var(--color-text-primary) 72%, var(--color-divider-primary));
+  --drawer-resize-grip-ring: color-mix(in srgb, var(--color-surface-0) 92%, var(--color-divider-primary));
+  background-color: rgba(var(--drawer-surface-color-rgb), var(--surface-opacity));
+  border-left: 1px solid var(--surface-border-color);
+  border-right: 1px solid var(--surface-border-color);
+  box-shadow: var(--surface-shadow);
+  backdrop-filter: blur(var(--surface-blur));
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+  animation: solara-drawer-slide-in-right 0.24s ease-out;
+
+  @media (prefers-reduced-motion: reduce) {
+    animation: none;
+  }
+}
+
+.solara-drawer--left {
+  left: 0;
+  border-left: none;
+  animation-name: solara-drawer-slide-in-left;
+}
+
+.solara-drawer--right {
+  right: 0;
+  border-right: none;
+}
+
+.solara-drawer--overflow {
+  overflow: visible;
+}
+
+.solara-drawer--sliding {
+  overflow: visible;
+}
+
+.solara-drawer--size-sm {
+  max-width: 20rem;
+}
+
+.solara-drawer--size-md {
+  max-width: 28rem;
+}
+
+.solara-drawer--size-lg {
+  max-width: 36rem;
+}
+
+.solara-drawer--size-xl {
+  max-width: 48rem;
+}
+
+@media (max-width: 640px) {
+  .solara-drawer {
+    max-width: calc(100vw - 1rem);
+  }
+}
+
+.solara-drawer--floating {
+  top: 1rem;
+  bottom: 1rem;
+  border-radius: var(--radius-lg);
+
+  &.solara-drawer--left {
+    left: 1rem;
+  }
+
+  &.solara-drawer--right {
+    right: 1rem;
+  }
+}
+
+.solara-drawer__resize-handle {
+  position: absolute;
+  top: 0;
+  bottom: 0;
+  width: 20px;
+  padding: 0;
+  border: none;
+  background: transparent;
+  cursor: ew-resize;
+  touch-action: none;
+  z-index: 2;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+
+  &:focus-visible {
+    outline: none;
+  }
+}
+
+.solara-drawer__resize-grip {
+  display: block;
+  width: 6px;
+  height: 60px;
+  border-radius: 9999px;
+  background-color: var(--drawer-resize-grip-color);
+  box-shadow: 0 0 0 1px var(--drawer-resize-grip-ring);
+  transition: background-color 0.2s ease, transform 0.2s ease;
+}
+
+.solara-drawer__resize-handle:hover .solara-drawer__resize-grip,
+.solara-drawer__resize-handle:focus-visible .solara-drawer__resize-grip,
+.solara-drawer__resize-handle:active .solara-drawer__resize-grip {
+  background-color: var(--drawer-resize-grip-hover-color);
+  transform: scaleX(1.08);
+}
+
+.solara-drawer__resize-handle--left {
+  left: -18px;
+}
+
+.solara-drawer__resize-handle--right {
+  right: -18px;
+}
+
+.solara-drawer--floating .solara-drawer__resize-handle {
+  top: calc(var(--space-4) * -1);
+  bottom: calc(var(--space-4) * -1);
+}
+
+.solara-drawer__header {
+  padding: calc(var(--space-4) * var(--spacing-multiplier)) calc(var(--space-5) * var(--spacing-multiplier));
+  display: flex;
+  align-items: flex-start;
+  justify-content: space-between;
+  gap: calc(var(--space-3) * var(--spacing-multiplier));
+}
+
+.solara-drawer__header--bordered {
+  border-bottom: 1px solid var(--surface-border-color);
+}
+
+.solara-drawer__header-content {
+  flex: 1;
+  min-width: 0;
+}
+
+.solara-drawer__header-actions {
+  display: flex;
+  align-items: center;
+  gap: calc(var(--space-2) * var(--spacing-multiplier));
+}
+
+.solara-drawer__title {
+  margin: 0;
+  font-size: var(--font-size-h5-scaled);
+  line-height: var(--line-height-body-scaled);
+  font-weight: 600;
+  color: var(--color-text-primary);
+}
+
+.solara-drawer__subheader {
+  margin-top: calc(var(--space-1) * var(--spacing-multiplier));
+  color: var(--color-text-secondary);
+  font-size: var(--font-size-caption-scaled);
+  line-height: var(--line-height-caption-scaled);
+}
+
+.solara-drawer__close {
+  color: var(--color-text-secondary);
+  transition: color 0.2s ease, background-color 0.2s ease;
+  border-radius: 9999px;
+  width: 32px;
+  height: 32px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: none;
+  border: none;
+  cursor: pointer;
+  padding: 0;
+}
+
+.solara-drawer__close:hover,
+.solara-drawer__close:focus-visible {
+  color: var(--color-text-primary);
+  background-color: var(--color-surface-200);
+  outline: none;
+}
+
+.solara-drawer__content {
+  padding: calc(var(--space-4) * var(--spacing-multiplier)) calc(var(--space-5) * var(--spacing-multiplier));
+  overflow-y: auto;
+  overflow-x: visible;
+  flex: 1;
+  color: var(--color-text-secondary);
+}
+
+.solara-drawer__content--overflow {
+  overflow: visible;
+}
+
+.solara-drawer__content--no-padding {
+  padding: 0;
+}
+
+.solara-drawer__footer {
+  padding: calc(var(--space-4) * var(--spacing-multiplier)) calc(var(--space-5) * var(--spacing-multiplier));
+  border-top: 1px solid var(--surface-border-color);
+  background-color: rgba(var(--drawer-surface-color-rgb), var(--surface-opacity));
+}
+
+:root[data-surface-default="translucent"] .solara-drawer,
+:root[data-surface-drawer="translucent"] .solara-drawer,
+.solara-drawer[data-surface-style="translucent"] {
+  --surface-opacity: var(--opacity-translucent-medium);
+  --surface-blur: 0px;
+  --drawer-surface-color-rgb: var(--surface-translucent-tint-rgb);
+}
+
+:root[data-surface-default="glass"] .solara-drawer,
+:root[data-surface-drawer="glass"] .solara-drawer,
+.solara-drawer[data-surface-style="glass"] {
+  --surface-opacity: var(--opacity-translucent-heavy);
+  --surface-blur: var(--blur-medium);
+  --surface-border-color: rgba(var(--surface-border-color-rgb), var(--surface-border-alpha-glass));
+  --drawer-surface-color-rgb: var(--surface-translucent-tint-rgb);
+}
+
+.solara-drawer[data-surface-style="solid"] {
+  --surface-opacity: 1;
+  --surface-blur: 0px;
+  --surface-border-color: var(--color-divider-secondary);
+}
+
+:root[data-surface-drawer="solid"] .solara-drawer {
+  --surface-opacity: 1;
+  --surface-blur: 0px;
+  --surface-border-color: var(--color-divider-secondary);
+}
+
+:root[data-surface-default="translucent"] .solara-drawer__footer,
+:root[data-surface-drawer="translucent"] .solara-drawer__footer,
+.solara-drawer[data-surface-style="translucent"] .solara-drawer__footer,
+:root[data-surface-default="glass"] .solara-drawer__footer,
+:root[data-surface-drawer="glass"] .solara-drawer__footer,
+.solara-drawer[data-surface-style="glass"] .solara-drawer__footer {
+  background-color: transparent;
+}
+
+:root[data-surface-default="translucent"] .solara-drawer,
+:root[data-surface-drawer="translucent"] .solara-drawer,
+.solara-drawer[data-surface-style="translucent"],
+:root[data-surface-default="glass"] .solara-drawer,
+:root[data-surface-drawer="glass"] .solara-drawer,
+.solara-drawer[data-surface-style="glass"] {
+  overflow: hidden;
+}
+
+:root[data-surface-default="translucent"] .solara-drawer--sliding,
+:root[data-surface-drawer="translucent"] .solara-drawer--sliding,
+.solara-drawer--sliding[data-surface-style="translucent"],
+:root[data-surface-default="glass"] .solara-drawer--sliding,
+:root[data-surface-drawer="glass"] .solara-drawer--sliding,
+.solara-drawer--sliding[data-surface-style="glass"] {
+  overflow: visible;
+}
+
+.solara-drawer__footer-actions {
+  display: flex;
+  justify-content: flex-end;
+  gap: calc(var(--space-3) * var(--spacing-multiplier));
+  flex-wrap: wrap;
+}
+
+@media (max-width: 640px) {
+  .solara-drawer__footer-actions {
+    flex-direction: column;
+    width: 100%;
+  }
+
+  .solara-drawer__footer-actions>* {
+    width: 100%;
+  }
+}

package/src/Drawer.tsx

@@ -0,0 +1,450 @@
+"use client";
+
+import React, { createContext, forwardRef, useEffect, useMemo, useRef, useState } from "react";
+import { createPortal } from "react-dom";
+import { Button } from "@solara/button";
+import type {
+  DrawerContentProps,
+  DrawerFooterProps,
+  DrawerHeaderProps,
+  DrawerProps,
+  DrawerTitleProps,
+  FooterButtonProps,
+  DrawerSize,
+  DrawerSide,
+  DrawerResizeConstraint,
+} from "./Drawer.types";
+import "./Drawer.scss";
+
+const classNames = (...classes: Array<string | undefined | false | null>) =>
+  classes.filter(Boolean).join(" ");
+
+const PRESET_DRAWER_WIDTHS: Record<DrawerSize, number> = {
+  sm: 320,
+  md: 448,
+  lg: 576,
+  xl: 768,
+};
+
+const DEFAULT_MIN_WIDTH = 280;
+const DEFAULT_MAX_WIDTH_OFFSET = 48;
+
+const parseResizeConstraint = (value: DrawerResizeConstraint | undefined) => {
+  if (typeof value === "number") return value;
+  if (typeof value === "string") {
+    const parsed = Number.parseFloat(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+  }
+  return undefined;
+};
+
+const getInitialDrawerWidth = (size: DrawerProps["size"]) => {
+  if (typeof size === "number") return size;
+  if (typeof size === "string") {
+    if (size in PRESET_DRAWER_WIDTHS) {
+      return PRESET_DRAWER_WIDTHS[size as DrawerSize];
+    }
+
+    const parsed = Number.parseFloat(size);
+    return Number.isFinite(parsed) ? parsed : undefined;
+  }
+
+  return PRESET_DRAWER_WIDTHS.md;
+};
+
+const clampDrawerWidth = (width: number, minWidth: number, maxWidth: number) =>
+  Math.min(Math.max(width, minWidth), maxWidth);
+
+const DrawerContext = createContext<{ allowContentOverflow?: boolean }>({});
+
+const CloseIcon = () => (
+  <svg viewBox="0 0 20 20" width="16" height="16" aria-hidden="true">
+    <path
+      d="M5 5l10 10M15 5L5 15"
+      stroke="currentColor"
+      strokeWidth="1.6"
+      strokeLinecap="round"
+    />
+  </svg>
+);
+
+const DrawerHeader = forwardRef<HTMLDivElement, DrawerHeaderProps>(
+  (
+    {
+      className,
+      children,
+      showCloseButton = true,
+      closeButtonAriaLabel = "Close drawer",
+      rightContent,
+      subheader,
+      bordered = true,
+      onClose,
+      ...props
+    },
+    ref
+  ) => (
+    <div
+      className={classNames(
+        "solara-drawer__header",
+        bordered ? "solara-drawer__header--bordered" : undefined,
+        className
+      )}
+      ref={ref}
+      {...props}
+    >
+      <div className="solara-drawer__header-content">
+        {children}
+        {subheader ? <div className="solara-drawer__subheader">{subheader}</div> : null}
+      </div>
+      <div className="solara-drawer__header-actions">
+        {rightContent}
+        {showCloseButton ? (
+          <button
+            type="button"
+            onClick={onClose}
+            aria-label={closeButtonAriaLabel}
+            className="solara-drawer__close"
+          >
+            <CloseIcon />
+          </button>
+        ) : null}
+      </div>
+    </div>
+  )
+);
+
+const DrawerTitle = forwardRef<HTMLHeadingElement, DrawerTitleProps>(
+  ({ className, ...props }, ref) => (
+    <h2 className={classNames("solara-drawer__title", className)} ref={ref} {...props} />
+  )
+);
+
+const DrawerContent = forwardRef<HTMLDivElement, DrawerContentProps>(
+  ({ className, noPadding, ...props }, ref) => {
+    const { allowContentOverflow } = React.useContext(DrawerContext);
+    return (
+      <div
+        className={classNames(
+          "solara-drawer__content",
+          allowContentOverflow ? "solara-drawer__content--overflow" : undefined,
+          noPadding ? "solara-drawer__content--no-padding" : undefined,
+          className
+        )}
+        ref={ref}
+        {...props}
+      />
+    );
+  }
+);
+
+const DrawerFooter = forwardRef<HTMLDivElement, DrawerFooterProps>(
+  ({ className, primaryButton, secondaryButton, dangerButton, ...props }, ref) => {
+    const renderButton = (button: FooterButtonProps, kind: "primary" | "secondary" | "danger") => {
+      const variant = kind === "primary" ? "primary" : "default";
+      const destructive = kind === "danger";
+      const isLoading = Boolean(button.loading);
+      const label = isLoading && button.loadingText ? button.loadingText : button.label;
+      const style = button.fullWidth ? { width: "100%" } : undefined;
+
+      return (
+        <Button
+          key={button.label}
+          type="button"
+          variant={variant}
+          destructive={destructive}
+          radius={button.radius}
+          onClick={button.onClick}
+          disabled={button.disabled || isLoading}
+          style={style}
+          label={label}
+        />
+      );
+    };
+
+    return (
+      <div className={classNames("solara-drawer__footer", className)} ref={ref} {...props}>
+        <div className="solara-drawer__footer-actions">
+          {secondaryButton ? renderButton(secondaryButton, "secondary") : null}
+          {dangerButton ? renderButton(dangerButton, "danger") : null}
+          {primaryButton ? renderButton(primaryButton, "primary") : null}
+        </div>
+      </div>
+    );
+  }
+);
+
+const DrawerComponent = forwardRef<HTMLDivElement, DrawerProps>(
+  (
+    {
+      isOpen,
+      onClose,
+      children,
+      position = "right",
+      overlay = true,
+      closeOnOverlayClick = true,
+      closeOnOutsideClick = true,
+      closeOnEscape = true,
+      size = "md",
+      sliding = false,
+      minWidth,
+      maxWidth,
+      className,
+      overlayClassName,
+      allowContentOverflow = false,
+      floating = false,
+      surfaceStyle,
+      style,
+      ...props
+    },
+    ref
+  ) => {
+    const drawerRef = useRef<HTMLDivElement>(null);
+    const dragStateRef = useRef<{ pointerId: number; rafId: number | null } | null>(null);
+    const [drawerWidth, setDrawerWidth] = useState<number | undefined>(() => getInitialDrawerWidth(size));
+    React.useImperativeHandle(ref, () => drawerRef.current as HTMLDivElement);
+
+    useEffect(() => {
+      if (!sliding) return;
+      setDrawerWidth(getInitialDrawerWidth(size));
+    }, [size, sliding]);
+
+    useEffect(() => {
+      if (!isOpen) return;
+      const originalOverflow = document.body.style.overflow;
+      document.body.style.overflow = "hidden";
+      return () => {
+        document.body.style.overflow = originalOverflow;
+      };
+    }, [isOpen]);
+
+    useEffect(() => {
+      if (!isOpen || !closeOnEscape) return;
+      const handleEscape = (event: KeyboardEvent) => {
+        if (event.key === "Escape") onClose();
+      };
+      document.addEventListener("keydown", handleEscape);
+      return () => document.removeEventListener("keydown", handleEscape);
+    }, [isOpen, closeOnEscape, onClose]);
+
+    useEffect(() => {
+      if (!isOpen || !closeOnOutsideClick) return;
+
+      const handleClickOutside = (event: MouseEvent) => {
+        if (drawerRef.current && !drawerRef.current.contains(event.target as Node)) {
+          onClose();
+        }
+      };
+
+      document.addEventListener("mousedown", handleClickOutside);
+      return () => document.removeEventListener("mousedown", handleClickOutside);
+    }, [isOpen, closeOnOutsideClick, onClose]);
+
+    const contextValue = useMemo(
+      () => ({
+        allowContentOverflow,
+      }),
+      [allowContentOverflow]
+    );
+
+    useEffect(() => {
+      return () => {
+        const dragState = dragStateRef.current;
+        if (dragState?.rafId !== null && dragState?.rafId !== undefined) {
+          window.cancelAnimationFrame(dragState.rafId);
+        }
+      };
+    }, []);
+
+    if (!isOpen) return null;
+
+    const isPresetSize = ["sm", "md", "lg", "xl"].includes(size as string);
+    const resolvedMinWidth = parseResizeConstraint(minWidth) ?? DEFAULT_MIN_WIDTH;
+    const viewportMaxWidth = typeof window === "undefined" ? Number.POSITIVE_INFINITY : window.innerWidth - DEFAULT_MAX_WIDTH_OFFSET;
+    const resolvedMaxWidth = parseResizeConstraint(maxWidth) ?? viewportMaxWidth;
+    const normalizedMaxWidth = Math.max(resolvedMinWidth, resolvedMaxWidth);
+
+    const drawerClasses = classNames(
+      "solara-drawer",
+      `solara-drawer--${position}`,
+      isPresetSize ? `solara-drawer--size-${size}` : undefined,
+      allowContentOverflow ? "solara-drawer--overflow" : undefined,
+      floating ? "solara-drawer--floating" : undefined,
+      sliding ? "solara-drawer--sliding" : undefined,
+      className
+    );
+
+    // Surface treatment stays theme-driven via data attributes and CSS variables.
+    const surfaceAttributes: Record<string, string | undefined> = {};
+    const surfaceStyleVars: React.CSSProperties & Record<string, string | undefined> = {};
+
+    if (surfaceStyle) {
+      if (typeof surfaceStyle === "string") {
+        surfaceAttributes["data-surface-style"] = surfaceStyle;
+      } else {
+        surfaceAttributes["data-surface-style"] = "custom";
+        if (surfaceStyle.opacity !== undefined) {
+          surfaceStyleVars["--surface-opacity"] = surfaceStyle.opacity.toString();
+        }
+        if (surfaceStyle.blur !== undefined) {
+          surfaceStyleVars["--surface-blur"] = `${surfaceStyle.blur}px`;
+        }
+        if (surfaceStyle.borderColor !== undefined) {
+          surfaceStyleVars["--surface-border-color"] = surfaceStyle.borderColor;
+        }
+        if (surfaceStyle.shadow !== undefined) {
+          surfaceStyleVars["--surface-shadow"] = surfaceStyle.shadow;
+        }
+      }
+    }
+
+    const resolvedWidth = sliding
+      ? clampDrawerWidth(drawerWidth ?? getInitialDrawerWidth(size) ?? PRESET_DRAWER_WIDTHS.md, resolvedMinWidth, normalizedMaxWidth)
+      : undefined;
+
+    const drawerStyle: React.CSSProperties = {
+      ...(!sliding && !isPresetSize ? { width: size } : {}),
+      ...(sliding ? { width: resolvedWidth, maxWidth: normalizedMaxWidth, minWidth: resolvedMinWidth } : {}),
+    };
+
+    // Dragging measures from the viewport edge the drawer is anchored to.
+    const updateWidthFromPointer = (clientX: number) => {
+      const nextWidth = position === "right" ? window.innerWidth - clientX : clientX;
+      setDrawerWidth(clampDrawerWidth(nextWidth, resolvedMinWidth, normalizedMaxWidth));
+    };
+
+    const handleResizePointerDown = (event: React.PointerEvent<HTMLButtonElement>) => {
+      if (!sliding) return;
+
+      event.preventDefault();
+      event.stopPropagation();
+
+      const target = event.currentTarget;
+      target.setPointerCapture(event.pointerId);
+
+      dragStateRef.current = { pointerId: event.pointerId, rafId: null };
+
+      // Use one animation frame per pointer tick burst to keep resize responsive without over-rendering.
+      const handlePointerMove = (moveEvent: PointerEvent) => {
+        if (!dragStateRef.current || moveEvent.pointerId !== dragStateRef.current.pointerId) return;
+
+        if (dragStateRef.current.rafId !== null) {
+          window.cancelAnimationFrame(dragStateRef.current.rafId);
+        }
+
+        dragStateRef.current.rafId = window.requestAnimationFrame(() => {
+          updateWidthFromPointer(moveEvent.clientX);
+          if (dragStateRef.current) {
+            dragStateRef.current.rafId = null;
+          }
+        });
+      };
+
+      const cleanupPointerSession = (pointerId: number) => {
+        const dragState = dragStateRef.current;
+        if (dragState?.rafId !== null && dragState?.rafId !== undefined) {
+          window.cancelAnimationFrame(dragState.rafId);
+        }
+
+        dragStateRef.current = null;
+        target.releasePointerCapture(pointerId);
+        window.removeEventListener("pointermove", handlePointerMove);
+        window.removeEventListener("pointerup", handlePointerUp);
+        window.removeEventListener("pointercancel", handlePointerCancel);
+      };
+
+      const handlePointerUp = (upEvent: PointerEvent) => {
+        if (upEvent.pointerId !== event.pointerId) return;
+        cleanupPointerSession(upEvent.pointerId);
+      };
+
+      const handlePointerCancel = (cancelEvent: PointerEvent) => {
+        if (cancelEvent.pointerId !== event.pointerId) return;
+        cleanupPointerSession(cancelEvent.pointerId);
+      };
+
+      window.addEventListener("pointermove", handlePointerMove);
+      window.addEventListener("pointerup", handlePointerUp);
+      window.addEventListener("pointercancel", handlePointerCancel);
+    };
+
+    const content = (
+      <div
+        ref={drawerRef}
+        className={drawerClasses}
+        style={{ ...drawerStyle, ...surfaceStyleVars, ...style }}
+        role="dialog"
+        aria-modal={overlay ? "true" : undefined}
+        onClick={(event) => event.stopPropagation()}
+        {...surfaceAttributes}
+        {...props}
+      >
+        {sliding ? (
+          <button
+            type="button"
+            aria-label={`Resize ${position} drawer`}
+            className={classNames(
+              "solara-drawer__resize-handle",
+              position === "right"
+                ? "solara-drawer__resize-handle--left"
+                : "solara-drawer__resize-handle--right"
+            )}
+            onPointerDown={handleResizePointerDown}
+            onClick={(event) => event.stopPropagation()}
+          >
+            <span aria-hidden="true" className="solara-drawer__resize-grip" />
+          </button>
+        ) : null}
+        <DrawerContext.Provider value={contextValue}>{children}</DrawerContext.Provider>
+      </div>
+    );
+
+    if (!overlay) {
+      return createPortal(content, document.body);
+    }
+
+    return createPortal(
+      <div
+        className={classNames("solara-drawer__overlay", overlayClassName)}
+        onClick={closeOnOverlayClick ? onClose : undefined}
+      >
+        {content}
+      </div>,
+      document.body
+    );
+  }
+);
+
+DrawerComponent.displayName = "Drawer";
+DrawerHeader.displayName = "Drawer.Header";
+DrawerTitle.displayName = "Drawer.Title";
+DrawerContent.displayName = "Drawer.Content";
+DrawerFooter.displayName = "Drawer.Footer";
+
+interface DrawerCompoundComponent
+  extends React.ForwardRefExoticComponent<DrawerProps & React.RefAttributes<HTMLDivElement>> {
+  Header: typeof DrawerHeader;
+  Title: typeof DrawerTitle;
+  Content: typeof DrawerContent;
+  Footer: typeof DrawerFooter;
+}
+
+const Drawer = Object.assign(DrawerComponent, {
+  Header: DrawerHeader,
+  Title: DrawerTitle,
+  Content: DrawerContent,
+  Footer: DrawerFooter,
+});
+
+export { Drawer, DrawerHeader, DrawerTitle, DrawerContent, DrawerFooter };
+export type {
+  DrawerProps,
+  DrawerHeaderProps,
+  DrawerTitleProps,
+  DrawerContentProps,
+  DrawerFooterProps,
+  DrawerSize,
+  DrawerSide,
+  FooterButtonProps,
+};
+
+export default Drawer as DrawerCompoundComponent;

package/src/Drawer.types.ts

@@ -0,0 +1,69 @@
+import type React from "react";
+
+export type DrawerSize = "sm" | "md" | "lg" | "xl";
+export type DrawerSide = "left" | "right";
+
+export type DrawerResizeConstraint = number | `${number}px`;
+
+export type DrawerSurfaceStyle =
+  | "solid"
+  | "translucent"
+  | "glass"
+  | {
+      opacity?: number;
+      blur?: number;
+      borderColor?: string;
+      shadow?: string;
+    };
+
+export interface FooterButtonProps {
+  label: string;
+  variant?: "primary" | "secondary" | "danger";
+  onClick: (event?: React.MouseEvent<HTMLButtonElement>) => void;
+  disabled?: boolean;
+  loading?: boolean;
+  loadingText?: string;
+  fullWidth?: boolean;
+  radius?: "default" | "none" | "full";
+}
+
+export interface DrawerHeaderProps extends React.HTMLAttributes<HTMLDivElement> {
+  showCloseButton?: boolean;
+  closeButtonAriaLabel?: string;
+  rightContent?: React.ReactNode;
+  subheader?: React.ReactNode;
+  bordered?: boolean;
+  onClose: () => void;
+}
+
+export interface DrawerTitleProps extends React.HTMLAttributes<HTMLHeadingElement> { }
+
+export interface DrawerContentProps extends React.HTMLAttributes<HTMLDivElement> {
+  noPadding?: boolean;
+}
+
+export interface DrawerFooterProps extends React.HTMLAttributes<HTMLDivElement> {
+  primaryButton?: FooterButtonProps;
+  secondaryButton?: FooterButtonProps;
+  dangerButton?: FooterButtonProps;
+}
+
+export interface DrawerProps extends React.HTMLAttributes<HTMLDivElement> {
+  isOpen: boolean;
+  onClose: () => void;
+  position?: DrawerSide;
+  overlay?: boolean;
+  closeOnOverlayClick?: boolean;
+  closeOnEscape?: boolean;
+  size?: DrawerSize | (string & {}) | number;
+  sliding?: boolean;
+  minWidth?: DrawerResizeConstraint;
+  maxWidth?: DrawerResizeConstraint;
+  overlayClassName?: string;
+  allowContentOverflow?: boolean;
+  children?: React.ReactNode;
+  floating?: boolean;
+  closeOnOutsideClick?: boolean;
+  /** Controls surface material treatment without changing layout tokens. */
+  surfaceStyle?: DrawerSurfaceStyle;
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+export { Drawer } from "./Drawer";
+export type {
+  DrawerProps,
+  DrawerHeaderProps,
+  DrawerTitleProps,
+  DrawerContentProps,
+  DrawerFooterProps,
+  DrawerSize,
+  DrawerSide,
+  FooterButtonProps,
+} from "./Drawer.types";