@varialkit/modal 0.1.1

package/docs.md

@@ -0,0 +1,78 @@
+# Modal
+
+Modal presents focused content or tasks in a layer above the page.
+Use it for critical decisions, forms, or previews that require user attention.
+
+## How to Use
+
+```tsx
+import { Modal } from "@solara/modal";
+
+export function Example() {
+  return (
+    <Modal isOpen onClose={() => {}}>
+      <Modal.Header onClose={() => {}}>
+        <Modal.Title>Invite teammates</Modal.Title>
+        <Modal.Subhead>Invite teammates</Modal.Subhead>
+      </Modal.Header>
+      <Modal.Content>Modal content goes here.</Modal.Content>
+      <Modal.Footer
+        primaryButton={{ label: "Send invites", onClick: () => {} }}
+        secondaryButton={{ label: "Cancel", onClick: () => {} }}
+      />
+    </Modal>
+  );
+}
+```
+
+## Best Practices
+
+- Keep titles short and action-oriented.
+- Reserve modals for critical, focused tasks.
+- Provide a clear dismissal path.
+
+## Props
+
+### Modal
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `isOpen` | `boolean` | _Required_ | Controls visibility. |
+| `onClose` | `() => void` | _Required_ | Close handler. |
+| `closeOnOverlayClick` | `boolean` | `true` | Close on overlay click. |
+| `closeOnEscape` | `boolean` | `true` | Close on Escape. |
+| `size` | `"sm" \| "md" \| "lg" \| "xl" \| "fullscreen"` | `"md"` | Modal width. |
+| `radius` | `"none" \| "sm" \| "md" \| "lg"` | `"md"` | Modal border-radius. |
+| `overlayClassName` | `string` | | Extra overlay class. |
+| `allowContentOverflow` | `boolean` | `false` | Allow content to overflow. |
+| `className` | `string` | | Custom class name. |
+
+### Modal.Header
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `showCloseButton` | `boolean` | `true` | Show close icon. |
+| `closeButtonAriaLabel` | `string` | `"Close modal"` | Close button aria label. |
+| `rightContent` | `ReactNode` | | Right-side header content. |
+| `transparent` | `boolean` | `false` | Overlay header style. |
+| `onClose` | `() => void` | _Required_ | Close handler. |
+
+### Modal.Title
+
+A `h2` element for the modal title. Should be used for short, attention-grabbing titles.
+
+### Modal.Subhead
+
+A `h3` element for the modal subhead. Use this to provide additional context or information that supports the main title. It appears directly below the `Modal.Title`.
+
+### Modal.Content
+
+The main content area of the modal. This is where the primary information or task-related components should be placed. It automatically handles vertical scrolling for oversized content.
+
+### Modal.Footer
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `primaryButton` | `ModalButtonProps` | | The primary action button, typically for confirming an action. |
+| `secondaryButton` | `ModalButtonProps` | | The secondary action button, often used for cancellation. |
+| `dangerButton` | `ModalButtonProps` | | A destructive action button, styled to indicate a potentially harmful action. |

package/examples/index.tsx

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

package/examples.tsx

@@ -0,0 +1,194 @@
+import React from "react";
+import { Modal } from "./src/Modal";
+import type { ModalProps } from "./src/Modal.types";
+import { Button } from "@solara/button";
+
+type ModalStoryProps = ModalProps & {
+  headerTransparent?: boolean;
+  showRightContent?: boolean;
+  radius?: "none" | "sm" | "md" | "lg";
+};
+
+const ModalPlayground = (props: ModalStoryProps) => {
+  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 modal" onClick={() => setOpen(true)} />
+      <Modal
+        isOpen={open}
+        onClose={() => setOpen(false)}
+        closeOnOverlayClick={props.closeOnOverlayClick}
+        closeOnEscape={props.closeOnEscape}
+        size={props.size}
+        radius={props.radius}
+        allowContentOverflow={props.allowContentOverflow}
+      >
+        <Modal.Header
+          onClose={() => setOpen(false)}
+          transparent={props.headerTransparent}
+          rightContent={
+            props.showRightContent ? (
+              <span style={{ fontSize: "0.75rem", color: "var(--color-text-secondary)" }}>
+                Updated today
+              </span>
+            ) : null
+          }
+        >
+          <Modal.Title>Invite teammates</Modal.Title>
+          <Modal.Subhead>This is a subhead.</Modal.Subhead>
+        </Modal.Header>
+        <Modal.Content>
+          <p style={{ marginTop: 0 }}>
+            Collect email addresses and assign a role. Invitees will receive a link to join the
+            project.
+          </p>
+          <ul style={{ marginBottom: 0 }}>
+            <li>Owner: full access</li>
+            <li>Editor: can update content</li>
+            <li>Viewer: read-only access</li>
+          </ul>
+        </Modal.Content>
+        <Modal.Footer
+          primaryButton={{
+            label: "Send invites",
+            onClick: () => setOpen(false),
+          }}
+          secondaryButton={{
+            label: "Cancel",
+            onClick: () => setOpen(false),
+          }}
+        />
+      </Modal>
+    </div>
+  );
+};
+
+const ModalHeaderStory = () => {
+  const [open, setOpen] = React.useState(false);
+  return (
+    <div style={{ display: "flex", flexDirection: "column", gap: "1rem" }}>
+      <Button label="Open modal" onClick={() => setOpen(true)} />
+      <Modal isOpen={open} onClose={() => setOpen(false)} closeOnOverlayClick closeOnEscape>
+        <Modal.Header
+          onClose={() => setOpen(false)}
+          rightContent={
+            <span style={{ fontSize: "0.75rem", color: "var(--color-text-secondary)" }}>
+              Header only
+            </span>
+          }
+        >
+          <Modal.Title>Header example</Modal.Title>
+        </Modal.Header>
+      </Modal>
+    </div>
+  );
+};
+
+const ModalFooterStory = () => {
+  const [open, setOpen] = React.useState(false);
+  return (
+    <div style={{ display: "flex", flexDirection: "column", gap: "1rem" }}>
+      <Button label="Open modal" onClick={() => setOpen(true)} />
+      <Modal isOpen={open} onClose={() => setOpen(false)} closeOnOverlayClick closeOnEscape>
+        <Modal.Footer
+          primaryButton={{ label: "Confirm", onClick: () => setOpen(false) }}
+          secondaryButton={{ label: "Cancel", onClick: () => setOpen(false) }}
+        />
+      </Modal>
+    </div>
+  );
+};
+
+export const stories = {
+  playground: {
+    title: "Playground",
+    description: "Adjust the Modal props to explore behavior.",
+    render: (props: ModalStoryProps) => <ModalPlayground {...props} />,
+    controls: [
+      { name: "size", type: "select", options: ["sm", "md", "lg", "xl", "fullscreen"] },
+      { name: "radius", type: "select", options: ["none", "sm", "md", "lg"] },
+      { name: "closeOnOverlayClick", type: "boolean" },
+      { name: "closeOnEscape", type: "boolean" },
+      { name: "allowContentOverflow", type: "boolean" },
+      { name: "headerTransparent", type: "boolean" },
+      { name: "showRightContent", type: "boolean" },
+      { name: "isOpen", type: "boolean" },
+    ],
+    initialProps: {
+      size: "md",
+      radius: "md",
+      closeOnOverlayClick: true,
+      closeOnEscape: true,
+      allowContentOverflow: false,
+      headerTransparent: false,
+      showRightContent: true,
+      isOpen: false,
+    },
+  },
+  header: {
+    title: "Header",
+    description: "Header-only configuration with close and right content.",
+    showProps: false,
+    render: () => <ModalHeaderStory />,
+    code: `import React from "react";
+import { Button } from "@solara/button";
+import { Modal } from "@solara/modal";
+
+export function Example() {
+  const [open, setOpen] = React.useState(false);
+
+  return (
+    <div style={{ display: "flex", flexDirection: "column", gap: "1rem" }}>
+      <Button label="Open modal" onClick={() => setOpen(true)} />
+      <Modal isOpen={open} onClose={() => setOpen(false)} closeOnOverlayClick closeOnEscape>
+        <Modal.Header
+          onClose={() => setOpen(false)}
+          rightContent={
+            <span style={{ fontSize: "0.75rem", color: "var(--color-text-secondary)" }}>
+              Header only
+            </span>
+          }
+        >
+          <Modal.Title>Header example</Modal.Title>
+        </Modal.Header>
+      </Modal>
+    </div>
+  );
+}
+`,
+  },
+  footer: {
+    title: "Footer",
+    description: "Footer-only configuration with primary/secondary actions.",
+    showProps: false,
+    render: () => <ModalFooterStory />,
+    code: `import React from "react";
+import { Button } from "@solara/button";
+import { Modal } from "@solara/modal";
+
+export function Example() {
+  const [open, setOpen] = React.useState(false);
+
+  return (
+    <div style={{ display: "flex", flexDirection: "column", gap: "1rem" }}>
+      <Button label="Open modal" onClick={() => setOpen(true)} />
+      <Modal isOpen={open} onClose={() => setOpen(false)} closeOnOverlayClick closeOnEscape>
+        <Modal.Footer
+          primaryButton={{ label: "Confirm", onClick: () => setOpen(false) }}
+          secondaryButton={{ label: "Cancel", onClick: () => setOpen(false) }}
+        />
+      </Modal>
+    </div>
+  );
+}
+`,
+  },
+};

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@varialkit/modal",
+  "version": "0.1.1",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./examples": "./examples/index.tsx"
+  },
+  "dependencies": {
+    "@varialkit/button": "0.1.1"
+  },
+  "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/Modal.scss

@@ -0,0 +1,284 @@
+@keyframes solara-modal-fade-in {
+  from {
+    opacity: 0;
+  }
+
+  to {
+    opacity: 1;
+  }
+}
+
+@keyframes solara-modal-slide-in {
+  from {
+    opacity: 0;
+    transform: translateY(14px) scale(0.98);
+  }
+
+  to {
+    opacity: 1;
+    transform: translateY(0) scale(1);
+  }
+}
+
+.solara-modal__overlay {
+  position: fixed;
+  inset: 0;
+  background-color: rgba(var(--overlay-backdrop-rgb), var(--overlay-backdrop-opacity));
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: calc(var(--space-4) * var(--spacing-multiplier));
+  z-index: 3000;
+  backdrop-filter: blur(var(--overlay-backdrop-blur));
+  animation: solara-modal-fade-in 0.2s ease-out;
+
+  @media (prefers-reduced-motion: reduce) {
+    animation: none;
+  }
+
+  // Remove padding when the modal is in fullscreen mode.
+  &--fullscreen {
+    padding: 0;
+  }
+}
+
+.solara-modal {
+  --modal-surface-color: var(--color-surface-100);
+  --modal-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);
+  background-color: rgba(var(--modal-surface-color-rgb), var(--surface-opacity));
+  border: 1px solid var(--surface-border-color);
+  box-shadow: var(--surface-shadow);
+  backdrop-filter: blur(var(--surface-blur));
+  --modal-border-radius: calc(var(--radius-4) * var(--radius-multiplier));
+  border-radius: var(--modal-border-radius);
+  width: 100%;
+  // Default width is smaller now.
+  max-width: 60vw;
+  max-height: calc(100vh - 2rem);
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+  animation: solara-modal-slide-in 0.24s ease-out;
+
+  @media (prefers-reduced-motion: reduce) {
+    animation: none;
+  }
+}
+
+.solara-modal--overflow {
+  overflow: visible;
+}
+
+.solara-modal--size-sm {
+  max-width: 28rem;
+}
+
+.solara-modal--size-md {
+  max-width: 36rem;
+}
+
+.solara-modal--size-lg {
+  max-width: 48rem;
+}
+
+.solara-modal--size-xl {
+  max-width: 64rem;
+}
+
+// Fullscreen variant fills the entire viewport.
+.solara-modal--size-fullscreen {
+  width: 100vw;
+  max-width: 100vw;
+  height: 100vh;
+  max-height: 100vh;
+  border-radius: 0;
+}
+
+.solara-modal--radius-none {
+  --modal-border-radius: 0;
+}
+
+.solara-modal--radius-sm {
+  --modal-border-radius: calc(var(--radius-2) * var(--radius-multiplier));
+}
+
+.solara-modal--radius-md {
+  --modal-border-radius: calc(var(--radius-4) * var(--radius-multiplier));
+}
+
+.solara-modal--radius-lg {
+  --modal-border-radius: calc(var(--radius-8) * var(--radius-multiplier));
+}
+
+@media (max-width: 640px) {
+  .solara-modal {
+    max-width: calc(100vw - 1rem);
+    max-height: calc(100vh - 1rem);
+  }
+}
+
+.solara-modal__header {
+  padding: calc(var(--space-4) * var(--spacing-multiplier)) calc(var(--space-5) * var(--spacing-multiplier));
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  border-bottom: 1px solid var(--surface-border-color);
+  gap: calc(var(--space-3) * var(--spacing-multiplier));
+  min-height: 60px;
+  border-top-left-radius: var(--modal-border-radius);
+  border-top-right-radius: var(--modal-border-radius);
+}
+
+.solara-modal__header--transparent {
+  background: transparent;
+  border-bottom: none;
+  position: absolute;
+  top: 0;
+  left: 0;
+  right: 0;
+  z-index: 5;
+}
+
+.solara-modal__header-content {
+  flex: 1;
+  min-width: 0;
+  // Vertically center the title and subhead.
+  display: flex;
+  flex-direction: column;
+  justify-content: center;
+}
+
+.solara-modal__header-actions {
+  display: flex;
+  align-items: center;
+  gap: calc(var(--space-2) * var(--spacing-multiplier));
+}
+
+.solara-modal__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);
+}
+
+// Subhead provides additional context to the title.
+.solara-modal__subhead {
+  margin: 0;
+  font-size: var(--font-size-sm-scaled);
+  line-height: var(--line-height-body-scaled);
+  font-weight: 400;
+  color: var(--color-text-secondary);
+}
+
+.solara-modal__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-modal__close:hover,
+.solara-modal__close:focus-visible {
+  color: var(--color-text-primary);
+  background-color: var(--color-surface-200);
+  outline: none;
+}
+
+.solara-modal__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-modal__content--overflow {
+  overflow: visible;
+}
+
+.solara-modal__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(--modal-surface-color-rgb), var(--surface-opacity));
+  border-bottom-left-radius: var(--modal-border-radius);
+  border-bottom-right-radius: var(--modal-border-radius);
+}
+
+:root[data-surface-default="translucent"] .solara-modal,
+:root[data-surface-modal="translucent"] .solara-modal,
+.solara-modal[data-surface-style="translucent"] {
+  --surface-opacity: var(--opacity-translucent-medium);
+  --surface-blur: 0px;
+  --modal-surface-color-rgb: var(--surface-translucent-tint-rgb);
+}
+
+:root[data-surface-default="glass"] .solara-modal,
+:root[data-surface-modal="glass"] .solara-modal,
+.solara-modal[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));
+  --modal-surface-color-rgb: var(--surface-translucent-tint-rgb);
+}
+
+.solara-modal[data-surface-style="solid"] {
+  --surface-opacity: 1;
+  --surface-blur: 0px;
+  --surface-border-color: var(--color-divider-secondary);
+}
+
+:root[data-surface-modal="solid"] .solara-modal {
+  --surface-opacity: 1;
+  --surface-blur: 0px;
+  --surface-border-color: var(--color-divider-secondary);
+}
+
+:root[data-surface-default="translucent"] .solara-modal__footer,
+:root[data-surface-modal="translucent"] .solara-modal__footer,
+.solara-modal[data-surface-style="translucent"] .solara-modal__footer,
+:root[data-surface-default="glass"] .solara-modal__footer,
+:root[data-surface-modal="glass"] .solara-modal__footer,
+.solara-modal[data-surface-style="glass"] .solara-modal__footer {
+  background-color: transparent;
+}
+
+:root[data-surface-default="translucent"] .solara-modal,
+:root[data-surface-modal="translucent"] .solara-modal,
+.solara-modal[data-surface-style="translucent"],
+:root[data-surface-default="glass"] .solara-modal,
+:root[data-surface-modal="glass"] .solara-modal,
+.solara-modal[data-surface-style="glass"] {
+  overflow: hidden;
+}
+
+.solara-modal__footer-actions {
+  display: flex;
+  justify-content: flex-end;
+  gap: calc(var(--space-3) * var(--spacing-multiplier));
+  flex-wrap: wrap;
+}
+
+@media (max-width: 640px) {
+  .solara-modal__footer-actions {
+    flex-direction: column;
+    width: 100%;
+  }
+
+  .solara-modal__footer-actions>* {
+    width: 100%;
+  }
+}

package/src/Modal.tsx

@@ -0,0 +1,293 @@
+"use client";
+
+import React, { createContext, forwardRef, useEffect, useMemo, useRef } from "react";
+import { createPortal } from "react-dom";
+import { Button } from "@solara/button";
+import type {
+  ModalButtonProps,
+  ModalContentProps,
+  ModalFooterProps,
+  ModalHeaderProps,
+  ModalProps,
+  ModalRadius,
+  ModalTitleProps,
+  ModalSubheadProps,
+} from "./Modal.types";
+import "./Modal.scss";
+
+const classNames = (...classes: Array<string | undefined | false | null>) =>
+  classes.filter(Boolean).join(" ");
+
+const ModalContext = 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 ModalHeader = forwardRef<HTMLDivElement, ModalHeaderProps>(
+  (
+    {
+      className,
+      children,
+      showCloseButton = true,
+      closeButtonAriaLabel = "Close modal",
+      rightContent,
+      transparent = false,
+      onClose,
+      ...props
+    },
+    ref
+  ) => (
+    <div
+      className={classNames(
+        "solara-modal__header",
+        transparent ? "solara-modal__header--transparent" : undefined,
+        className
+      )}
+      ref={ref}
+      {...props}
+    >
+      <div className="solara-modal__header-content">{children}</div>
+      <div className="solara-modal__header-actions">
+        {rightContent}
+        {showCloseButton ? (
+          <button
+            type="button"
+            onClick={onClose}
+            aria-label={closeButtonAriaLabel}
+            className="solara-modal__close"
+          >
+            <CloseIcon />
+          </button>
+        ) : null}
+      </div>
+    </div>
+  )
+);
+
+const ModalTitle = forwardRef<HTMLHeadingElement, ModalTitleProps>(
+  ({ className, ...props }, ref) => (
+    <h2 className={classNames("solara-modal__title", className)} ref={ref} {...props} />
+  )
+);
+
+/**
+ * A subhead for the modal, rendered as an `h3` element.
+ * This should be used for providing additional context to the modal's title.
+ */
+const ModalSubhead = forwardRef<HTMLHeadingElement, ModalSubheadProps>(
+  ({ className, ...props }, ref) => (
+    <h3
+      className={classNames("solara-modal__subhead", className)}
+      ref={ref}
+      {...props}
+    />
+  )
+);
+
+const ModalContent = forwardRef<HTMLDivElement, ModalContentProps>(
+  ({ className, ...props }, ref) => {
+    const { allowContentOverflow } = React.useContext(ModalContext);
+
+    return (
+      <div
+        className={classNames(
+          "solara-modal__content",
+          allowContentOverflow ? "solara-modal__content--overflow" : undefined,
+          className
+        )}
+        ref={ref}
+        {...props}
+      />
+    );
+  }
+);
+
+const ModalFooter = forwardRef<HTMLDivElement, ModalFooterProps>(
+  ({ className, primaryButton, secondaryButton, dangerButton, ...props }, ref) => {
+    const renderButton = (button: ModalButtonProps, 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-modal__footer", className)} ref={ref} {...props}>
+        <div className="solara-modal__footer-actions">
+          {secondaryButton ? renderButton(secondaryButton, "secondary") : null}
+          {dangerButton ? renderButton(dangerButton, "danger") : null}
+          {primaryButton ? renderButton(primaryButton, "primary") : null}
+        </div>
+      </div>
+    );
+  }
+);
+
+const ModalComponent = forwardRef<HTMLDivElement, ModalProps>(
+  (
+    {
+      isOpen,
+      onClose,
+      children,
+      closeOnOverlayClick = true,
+      closeOnEscape = true,
+      size = "md",
+      radius = "md",
+      className,
+      overlayClassName,
+      allowContentOverflow = false,
+      surfaceStyle,
+      style,
+      ...props
+    },
+    ref
+  ) => {
+    const modalRef = useRef<HTMLDivElement>(null);
+    React.useImperativeHandle(ref, () => modalRef.current as HTMLDivElement);
+
+    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]);
+
+    const contextValue = useMemo(
+      () => ({
+        allowContentOverflow,
+      }),
+      [allowContentOverflow]
+    );
+
+    if (!isOpen) return null;
+
+    // Surface styling is controlled via data attributes so theme defaults remain centralized.
+    const surfaceAttributes: Record<string, string | undefined> = {};
+    const surfaceStyleVars: React.CSSProperties = {};
+
+    if (surfaceStyle) {
+      if (typeof surfaceStyle === "string") {
+        surfaceAttributes["data-surface-style"] = surfaceStyle;
+      } else {
+        surfaceAttributes["data-surface-style"] = "custom";
+        if (surfaceStyle.opacity !== undefined) {
+          (surfaceStyleVars as any)["--surface-opacity"] =
+            surfaceStyle.opacity.toString();
+        }
+        if (surfaceStyle.blur !== undefined) {
+          (surfaceStyleVars as any)["--surface-blur"] = `${surfaceStyle.blur}px`;
+        }
+        if (surfaceStyle.borderColor !== undefined) {
+          (surfaceStyleVars as any)["--surface-border-color"] = surfaceStyle.borderColor;
+        }
+        if (surfaceStyle.shadow !== undefined) {
+          (surfaceStyleVars as any)["--surface-shadow"] = surfaceStyle.shadow;
+        }
+      }
+    }
+
+    return createPortal(
+      <div
+        className={classNames(
+          "solara-modal__overlay",
+          // When the modal is fullscreen, we apply a specific class to the overlay
+          // to remove the padding and allow the modal to fill the entire viewport.
+          size === "fullscreen" ? "solara-modal__overlay--fullscreen" : undefined,
+          overlayClassName
+        )}
+        onClick={closeOnOverlayClick ? onClose : undefined}
+      >
+        <div
+          ref={modalRef}
+          className={classNames(
+            "solara-modal",
+            `solara-modal--size-${size}`,
+            `solara-modal--radius-${radius}`,
+            allowContentOverflow ? "solara-modal--overflow" : undefined,
+            className
+          )}
+          style={{ ...surfaceStyleVars, ...style }}
+          role="dialog"
+          aria-modal="true"
+          onClick={(event) => event.stopPropagation()}
+          {...surfaceAttributes}
+          {...props}
+        >
+          <ModalContext.Provider value={contextValue}>{children}</ModalContext.Provider>
+        </div>
+      </div>,
+      document.body
+    );
+  }
+);
+
+ModalComponent.displayName = "Modal";
+ModalHeader.displayName = "Modal.Header";
+ModalTitle.displayName = "Modal.Title";
+ModalSubhead.displayName = "Modal.Subhead";
+ModalContent.displayName = "Modal.Content";
+ModalFooter.displayName = "Modal.Footer";
+
+interface ModalCompoundComponent
+  extends React.ForwardRefExoticComponent<ModalProps & React.RefAttributes<HTMLDivElement>> {
+  Header: typeof ModalHeader;
+  Title: typeof ModalTitle;
+  Subhead: typeof ModalSubhead;
+  Content: typeof ModalContent;
+  Footer: typeof ModalFooter;
+}
+
+const Modal = Object.assign(ModalComponent, {
+  Header: ModalHeader,
+  Title: ModalTitle,
+  Subhead: ModalSubhead,
+  Content: ModalContent,
+  Footer: ModalFooter,
+});
+
+export { Modal, ModalHeader, ModalTitle, ModalSubhead, ModalContent, ModalFooter };
+export type {
+  ModalProps,
+  ModalHeaderProps,
+  ModalTitleProps,
+  ModalSubheadProps,
+  ModalContentProps,
+  ModalFooterProps,
+  ModalButtonProps,
+};
+
+export default Modal as ModalCompoundComponent;

package/src/Modal.types.ts

@@ -0,0 +1,78 @@
+import type React from "react";
+
+export type ModalSize = "sm" | "md" | "lg" | "xl" | "fullscreen";
+
+export interface ModalButtonProps {
+  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 ModalHeaderProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** Whether to show the close button. */
+  showCloseButton?: boolean;
+  /** Aria label for the close button. */
+  closeButtonAriaLabel?: string;
+  /** Content to be rendered on the right side of the header. */
+  rightContent?: React.ReactNode;
+  /** Renders the header as a transparent overlay above content. */
+  transparent?: boolean;
+  /** Called when the close button is pressed. */
+  onClose: () => void;
+}
+
+export interface ModalTitleProps extends React.HTMLAttributes<HTMLHeadingElement> { }
+
+export interface ModalSubheadProps extends React.HTMLAttributes<HTMLHeadingElement> { }
+
+export interface ModalContentProps extends React.HTMLAttributes<HTMLDivElement> { }
+
+export interface ModalFooterProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** Primary button configuration. */
+  primaryButton?: ModalButtonProps;
+  /** Secondary button configuration. */
+  secondaryButton?: ModalButtonProps;
+  /** Danger button configuration. */
+  dangerButton?: ModalButtonProps;
+}
+
+export type ModalRadius = "none" | "sm" | "md" | "lg";
+
+export type ModalSurfaceStyle =
+  | "solid"
+  | "translucent"
+  | "glass"
+  | {
+      opacity?: number;
+      blur?: number;
+      borderColor?: string;
+      shadow?: string;
+    };
+
+export interface ModalProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** Whether the modal is open. */
+  isOpen: boolean;
+  /** Callback when modal is requested to close. */
+  onClose: () => void;
+  /** Whether to close the modal when clicking outside. */
+  closeOnOverlayClick?: boolean;
+  /** Whether to close the modal when pressing escape. */
+  closeOnEscape?: boolean;
+  /** Size of the modal. */
+  size?: ModalSize;
+  /** Radius of the modal */
+  radius?: ModalRadius;
+  /** Controls surface material treatment without changing layout tokens. */
+  surfaceStyle?: ModalSurfaceStyle;
+  /** Custom class name for the modal overlay. */
+  overlayClassName?: string;
+  /** Whether to allow content overflow (useful for dropdowns). */
+  allowContentOverflow?: boolean;
+  /** Modal children content. */
+  children?: React.ReactNode;
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+export { Modal } from "./Modal";
+export type {
+  ModalProps,
+  ModalHeaderProps,
+  ModalTitleProps,
+  ModalContentProps,
+  ModalFooterProps,
+  ModalButtonProps,
+  ModalSize,
+} from "./Modal.types";