@grampro/kit 0.0.0-stage → 2.4.0

package/source/components/modal/README.md

@@ -0,0 +1,51 @@
+# Modal
+
+A modal and drawer for React 19 on the native `<dialog>` element, styled to match
+the rest of the library. No runtime dependencies besides React.
+
+The browser provides the top layer, the inert page behind, the focus trap and
+focus return. The component adds controlled state, dismiss rules, an
+`onBeforeClose` guard, sizes, drawers and enter/exit animation.
+
+## Setup
+
+```ts
+import { Modal } from "@/components/modal";
+import "@/components/modal/styles.css";
+```
+
+## Usage
+
+```tsx
+const [open, setOpen] = useState(false);
+
+<button onClick={() => setOpen(true)}>Edit</button>
+<Modal
+  open={open}
+  onOpenChange={setOpen}
+  title="Edit profile"
+  footer={({ close }) => <button onClick={close}>Done</button>}
+>
+  …
+</Modal>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `open` / `defaultOpen` / `onOpenChange` | `boolean` / `boolean` / `(open, reason?) => void` | — / `false` | Controlled or uncontrolled state. `reason`: `escape`, `backdrop`, `close-button`, `api`. |
+| `title`, `description`, `aria-label` | `ReactNode` / `string` | — | Header text; `aria-label` names an untitled modal. |
+| `children`, `footer` | `ReactNode \| ({ close }) => ReactNode` | — | Body and footer. |
+| `size` | `sm` \| `md` \| `lg` \| `xl` \| `full` | `md` | 400 / 520 / 720 / 960 px or the whole screen. |
+| `placement` | `center` \| `top` \| `left` \| `right` \| `bottom` | `center` | `left`, `right` and `bottom` are drawers. |
+| `closeButton`, `closeOnEscape`, `closeOnBackdrop` | `boolean` | `true` | Dismiss options. |
+| `onBeforeClose` | `(reason) => boolean \| Promise<boolean>` | — | Return `false` to stay open. |
+| `initialFocus` | `RefObject<HTMLElement>` | — | Otherwise `[data-autofocus]`, then the first focusable element. |
+| `keepMounted` | `boolean` | `false` | Keep the content's state while closed. |
+| `className`, `classNames`, `style`, `localeText`, `id`, `ref` | — | — | Slots: `root`, `header`, `title`, `description`, `close`, `body`, `footer`. `ref`: `open()`, `close()`, `getElement()`. |
+
+## Known limits
+
+- Exit animations need `transition-behavior: allow-discrete` (Chrome 117+, Safari 18+); elsewhere the modal closes instantly.
+- Page scrolling is locked with `:root:has(.md-root[open])`, which can shift content by the scrollbar's width.

package/source/components/modal/core/dismiss.ts

@@ -0,0 +1,29 @@
+import type { CloseGuard, CloseReason, DismissOptions, Rect } from "./types";
+
+/** Whether a close request is allowed before asking `onBeforeClose`. Code and the close button always are. */
+export function canDismiss(reason: CloseReason, options: DismissOptions = {}): boolean {
+  if (reason === "escape") return options.closeOnEscape ?? true;
+  if (reason === "backdrop") return options.closeOnBackdrop ?? true;
+  return true;
+}
+
+/**
+ * A native `<dialog>` reports clicks on its backdrop as clicks on itself, so a
+ * click counts as "on the backdrop" when it lands outside the dialog's box.
+ */
+export function isOutside(rect: Rect, x: number, y: number): boolean {
+  return x < rect.left || x > rect.right || y < rect.top || y > rect.bottom;
+}
+
+/**
+ * Runs `onBeforeClose`. Only an explicit `false` (or a promise of it) keeps the
+ * modal open; a guard that throws keeps it open too, so unsaved work isn't lost.
+ */
+export async function confirmClose(guard: CloseGuard | undefined, reason: CloseReason): Promise<boolean> {
+  if (!guard) return true;
+  try {
+    return (await guard(reason)) !== false;
+  } catch {
+    return false;
+  }
+}

package/source/components/modal/core/index.ts

@@ -0,0 +1,3 @@
+// Framework-free: the dismiss rules the Modal uses, so they can be tested and reused.
+export { canDismiss, confirmClose, isOutside } from "./dismiss";
+export type * from "./types";

package/source/components/modal/core/types.ts

@@ -0,0 +1,27 @@
+export type ModalSize = "sm" | "md" | "lg" | "xl" | "full";
+
+/** `center` and `top` are dialogs; `left`, `right` and `bottom` slide in as drawers. */
+export type ModalPlacement = "center" | "top" | "left" | "right" | "bottom";
+
+/** What asked the modal to close. */
+export type CloseReason = "escape" | "backdrop" | "close-button" | "api";
+
+export interface DismissOptions {
+  /** Default true. */
+  closeOnEscape?: boolean;
+  /** Default true. */
+  closeOnBackdrop?: boolean;
+}
+
+export interface Rect {
+  left: number;
+  top: number;
+  right: number;
+  bottom: number;
+}
+
+export type CloseGuard = (reason: CloseReason) => boolean | Promise<boolean>;
+
+export interface ModalLocaleText {
+  close: string;
+}

package/source/components/modal/index.ts

@@ -0,0 +1,5 @@
+export { Modal } from "./react/Modal";
+export type { ModalProps } from "./react/Modal";
+export { defaultModalText } from "./react/locale";
+export type { ModalHandle, ModalRenderProps, ModalSlot } from "./react/props";
+export * from "./core";

package/source/components/modal/passport.json

@@ -0,0 +1,289 @@
+{
+  "passportVersion": "1.0.0",
+  "identity": {
+    "component": "Modal",
+    "folder": "modal",
+    "exports": [
+      "Modal"
+    ]
+  },
+  "source": {
+    "libraryVersion": "2.4.0",
+    "files": [
+      "core/dismiss.ts",
+      "core/index.ts",
+      "core/types.ts",
+      "index.ts",
+      "react/Modal.tsx",
+      "react/icons.tsx",
+      "react/locale.ts",
+      "react/props.ts"
+    ],
+    "sourceHash": "sha256:910a347e2afc5b243068783ae93ebef3fa8595aa9dd4df3531aca3c754c84248"
+  },
+  "props": [
+    {
+      "name": "aria-label",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "derived",
+      "description": "Accessible name when there is no `title`.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "children",
+      "type": "other",
+      "typeText": "Renderable",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "className",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "classNames",
+      "type": "other",
+      "typeText": "Partial<Record<ModalSlot, string>> | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "closeButton",
+      "type": "boolean",
+      "typeText": "boolean | undefined",
+      "required": false,
+      "default": true,
+      "origin": "derived",
+      "description": "Show the × button. Default true.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "closeOnBackdrop",
+      "type": "boolean",
+      "typeText": "boolean | undefined",
+      "required": false,
+      "default": true,
+      "origin": "derived",
+      "description": "Default true.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "closeOnEscape",
+      "type": "boolean",
+      "typeText": "boolean | undefined",
+      "required": false,
+      "default": true,
+      "origin": "derived",
+      "description": "Default true.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "defaultOpen",
+      "type": "boolean",
+      "typeText": "boolean | undefined",
+      "required": false,
+      "default": false,
+      "origin": "derived"
+    },
+    {
+      "name": "description",
+      "type": "other",
+      "typeText": "ReactNode",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "footer",
+      "type": "other",
+      "typeText": "Renderable",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "id",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "initialFocus",
+      "type": "other",
+      "typeText": "RefObject<HTMLElement | null> | undefined",
+      "required": false,
+      "origin": "derived",
+      "description": "Focused on open. Otherwise the first `[data-autofocus]` element, then the first focusable one.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "keepMounted",
+      "type": "boolean",
+      "typeText": "boolean | undefined",
+      "required": false,
+      "default": false,
+      "origin": "derived",
+      "description": "Keep the content mounted while closed, preserving its state. Default false.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "localeText",
+      "type": "other",
+      "typeText": "Partial<ModalLocaleText> | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "onBeforeClose",
+      "type": "function",
+      "signature": "((reason: CloseReason) => boolean | Promise<boolean>) | undefined",
+      "required": false,
+      "origin": "derived",
+      "description": "Return `false` (or a promise of it) to keep the modal open, e.g. for unsaved changes.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "onOpenChange",
+      "type": "function",
+      "signature": "((open: boolean, reason?: CloseReason) => void) | undefined",
+      "required": false,
+      "origin": "derived",
+      "description": "`reason` says what closed it; it is undefined when opening.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "open",
+      "type": "boolean",
+      "typeText": "boolean | undefined",
+      "required": false,
+      "origin": "derived",
+      "description": "Controlled open state.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "placement",
+      "type": "enum",
+      "values": [
+        "bottom",
+        "center",
+        "left",
+        "right",
+        "top"
+      ],
+      "typeText": "ModalPlacement | undefined",
+      "required": false,
+      "default": "center",
+      "origin": "derived",
+      "description": "Default `center`.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "ref",
+      "type": "other",
+      "typeText": "Ref<ModalHandle> | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "size",
+      "type": "enum",
+      "values": [
+        "full",
+        "lg",
+        "md",
+        "sm",
+        "xl"
+      ],
+      "typeText": "ModalSize | undefined",
+      "required": false,
+      "default": "md",
+      "origin": "derived",
+      "description": "Width for dialogs; for drawers, the width (left/right) or height (bottom). Default `md`.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "style",
+      "type": "other",
+      "typeText": "CSSProperties | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "title",
+      "type": "other",
+      "typeText": "ReactNode",
+      "required": false,
+      "origin": "derived"
+    }
+  ],
+  "events": [
+    {
+      "name": "onBeforeClose",
+      "signature": "((reason: CloseReason) => boolean | Promise<boolean>) | undefined"
+    },
+    {
+      "name": "onOpenChange",
+      "signature": "((open: boolean, reason?: CloseReason) => void) | undefined"
+    }
+  ],
+  "slots": [
+    "root",
+    "header",
+    "title",
+    "description",
+    "close",
+    "body",
+    "footer"
+  ],
+  "states": [
+    {
+      "attr": "data-placement",
+      "values": [
+        "bottom",
+        "left",
+        "right",
+        "top"
+      ]
+    },
+    {
+      "attr": "data-size",
+      "values": [
+        "full",
+        "lg",
+        "sm",
+        "xl"
+      ]
+    },
+    {
+      "attr": "data-state"
+    },
+    {
+      "attr": "data-theme",
+      "values": [
+        "dark",
+        "light"
+      ]
+    }
+  ],
+  "accessibility": {
+    "supplied": [],
+    "required": []
+  },
+  "composition": {},
+  "operations": {},
+  "intentDomains": [],
+  "safeMutations": {},
+  "examples": [],
+  "coverage": {
+    "propsTotal": 22,
+    "propsDescribed": 11,
+    "describedPct": 50,
+    "authoredSections": [
+      "accessibility"
+    ]
+  }
+}

package/source/components/modal/react/Modal.tsx

@@ -0,0 +1,242 @@
+"use client";
+
+import {
+  useCallback,
+  useEffect,
+  useId,
+  useImperativeHandle,
+  useMemo,
+  useRef,
+  useState,
+  type CSSProperties,
+  type MouseEvent,
+  type ReactNode,
+  type Ref,
+  type RefObject,
+} from "react";
+import { useControllableState } from "../../shared/react/useControllableState";
+import { canDismiss, confirmClose, isOutside } from "../core/dismiss";
+import type {
+  CloseReason,
+  ModalLocaleText,
+  ModalPlacement,
+  ModalSize,
+} from "../core/types";
+import { XIcon } from "./icons";
+import { defaultModalText } from "./locale";
+import { cx, type ModalHandle, type ModalRenderProps, type ModalSlot } from "./props";
+
+/** Matches the CSS transition, so content stays mounted while the modal animates out. */
+const EXIT_DURATION = 200;
+
+type Renderable = ReactNode | ((props: ModalRenderProps) => ReactNode);
+
+export interface ModalProps {
+  /** Controlled open state. */
+  open?: boolean;
+  defaultOpen?: boolean;
+  /** `reason` says what closed it; it is undefined when opening. */
+  onOpenChange?(open: boolean, reason?: CloseReason): void;
+  title?: ReactNode;
+  description?: ReactNode;
+  /** Accessible name when there is no `title`. */
+  "aria-label"?: string;
+  children?: Renderable;
+  footer?: Renderable;
+  /** Width for dialogs; for drawers, the width (left/right) or height (bottom). Default `md`. */
+  size?: ModalSize;
+  /** Default `center`. */
+  placement?: ModalPlacement;
+  /** Show the × button. Default true. */
+  closeButton?: boolean;
+  /** Default true. */
+  closeOnEscape?: boolean;
+  /** Default true. */
+  closeOnBackdrop?: boolean;
+  /** Return `false` (or a promise of it) to keep the modal open, e.g. for unsaved changes. */
+  onBeforeClose?(reason: CloseReason): boolean | Promise<boolean>;
+  /** Focused on open. Otherwise the first `[data-autofocus]` element, then the first focusable one. */
+  initialFocus?: RefObject<HTMLElement | null>;
+  /** Keep the content mounted while closed, preserving its state. Default false. */
+  keepMounted?: boolean;
+  id?: string;
+  className?: string;
+  classNames?: Partial<Record<ModalSlot, string>>;
+  style?: CSSProperties;
+  localeText?: Partial<ModalLocaleText>;
+  ref?: Ref<ModalHandle>;
+}
+
+const outside = (event: MouseEvent<HTMLDialogElement>) =>
+  event.target === event.currentTarget &&
+  isOutside(event.currentTarget.getBoundingClientRect(), event.clientX, event.clientY);
+
+/**
+ * A modal built on the native `<dialog>` element. The browser provides the top
+ * layer, the inert background, the focus trap and focus return; the component
+ * adds controlled state, dismiss rules, drawers and animation.
+ */
+export function Modal(props: ModalProps) {
+  const {
+    ref,
+    open: openProp,
+    defaultOpen = false,
+    onOpenChange,
+    title,
+    description,
+    "aria-label": ariaLabel,
+    children,
+    footer,
+    size = "md",
+    placement = "center",
+    closeButton = true,
+    closeOnEscape = true,
+    closeOnBackdrop = true,
+    onBeforeClose,
+    initialFocus,
+    keepMounted = false,
+    id: idProp,
+    className,
+    classNames,
+    style,
+    localeText,
+  } = props;
+
+  const reactId = useId();
+  const id = idProp ?? reactId;
+  const text = useMemo(() => ({ ...defaultModalText, ...localeText }), [localeText]);
+  const dialogRef = useRef<HTMLDialogElement>(null);
+  const pressStartedOutside = useRef(false);
+
+  const [open, setOpenState] = useControllableState(openProp, defaultOpen);
+
+  // Keep the content mounted through the exit transition. Adjusting state while
+  // rendering avoids an extra render with the content already gone.
+  const [previousOpen, setPreviousOpen] = useState(open);
+  const [closing, setClosing] = useState(false);
+  if (previousOpen !== open) {
+    setPreviousOpen(open);
+    setClosing(!open);
+  }
+
+  useEffect(() => {
+    if (!closing) return;
+    const timer = setTimeout(() => setClosing(false), EXIT_DURATION);
+    return () => clearTimeout(timer);
+  }, [closing]);
+
+  const setOpen = useCallback(
+    (next: boolean, reason?: CloseReason) => {
+      setOpenState(next);
+      onOpenChange?.(next, reason);
+    },
+    [setOpenState, onOpenChange],
+  );
+
+  const requestClose = useCallback(
+    (reason: CloseReason) => {
+      if (!canDismiss(reason, { closeOnEscape, closeOnBackdrop })) return;
+      void confirmClose(onBeforeClose, reason).then((allowed) => {
+        if (allowed) setOpen(false, reason);
+      });
+    },
+    [closeOnEscape, closeOnBackdrop, onBeforeClose, setOpen],
+  );
+
+  useEffect(() => {
+    const dialog = dialogRef.current;
+    if (!dialog) return;
+    if (open && !dialog.open) {
+      dialog.showModal();
+      const target =
+        initialFocus?.current ?? dialog.querySelector<HTMLElement>("[data-autofocus]");
+      target?.focus();
+    } else if (!open && dialog.open) {
+      dialog.close();
+    }
+  }, [open, initialFocus]);
+
+  useImperativeHandle(
+    ref,
+    () => ({
+      open: () => setOpen(true),
+      close: () => requestClose("api"),
+      getElement: () => dialogRef.current,
+    }),
+    [setOpen, requestClose],
+  );
+
+  const renderProps: ModalRenderProps = { close: () => requestClose("api") };
+  const render = (node: Renderable) => (typeof node === "function" ? node(renderProps) : node);
+  const mounted = open || closing || keepMounted;
+
+  return (
+    <dialog
+      ref={dialogRef}
+      id={id}
+      className={cx("md-root", classNames?.root, className)}
+      style={style}
+      data-size={size}
+      data-placement={placement}
+      data-state={open ? "open" : "closed"}
+      aria-labelledby={title ? `${id}-title` : undefined}
+      aria-describedby={description ? `${id}-description` : undefined}
+      aria-label={title ? undefined : ariaLabel}
+      // Escape: keep the browser from closing it, and decide ourselves.
+      onCancel={(event) => {
+        event.preventDefault();
+        requestClose("escape");
+      }}
+      // Closed some other way, e.g. by a `<form method="dialog">` inside.
+      onClose={() => {
+        if (open) setOpen(false, "api");
+      }}
+      // A drag that starts inside and ends on the backdrop must not close it.
+      onPointerDown={(event) => {
+        pressStartedOutside.current = outside(event);
+      }}
+      onClick={(event) => {
+        if (pressStartedOutside.current && outside(event)) requestClose("backdrop");
+        pressStartedOutside.current = false;
+      }}
+    >
+      {mounted && (
+        <>
+          {(title || description || closeButton) && (
+            <header className={cx("md-header", classNames?.header)}>
+              <div className="md-heading">
+                {title && (
+                  <h2 id={`${id}-title`} className={cx("md-title", classNames?.title)}>
+                    {title}
+                  </h2>
+                )}
+                {description && (
+                  <p id={`${id}-description`} className={cx("md-description", classNames?.description)}>
+                    {description}
+                  </p>
+                )}
+              </div>
+              {closeButton && (
+                <button
+                  type="button"
+                  className={cx("md-close", classNames?.close)}
+                  aria-label={text.close}
+                  title={text.close}
+                  onClick={() => requestClose("close-button")}
+                >
+                  <XIcon />
+                </button>
+              )}
+            </header>
+          )}
+          {/* Focusable: the body scrolls, and a scroll area the keyboard can't
+              reach leaves its content unreadable without a mouse. */}
+          <div className={cx("md-body", classNames?.body)} tabIndex={0}>
+            {render(children)}
+          </div>
+          {footer && <footer className={cx("md-footer", classNames?.footer)}>{render(footer)}</footer>}
+        </>
+      )}
+    </dialog>
+  );
+}

package/source/components/modal/react/icons.tsx

@@ -0,0 +1 @@
+export { XIcon } from "../../shared/react/icons";

package/source/components/modal/react/locale.ts

@@ -0,0 +1,5 @@
+import type { ModalLocaleText } from "../core/types";
+
+export const defaultModalText: ModalLocaleText = {
+  close: "Close",
+};

package/source/components/modal/react/props.ts

@@ -0,0 +1,17 @@
+export type ModalSlot = "root" | "header" | "title" | "description" | "close" | "body" | "footer";
+
+export interface ModalHandle {
+  open(): void;
+  /** Asks to close; `onBeforeClose` still gets a say. */
+  close(): void;
+  getElement(): HTMLDialogElement | null;
+}
+
+/** Passed to `children` and `footer` when they are functions. */
+export interface ModalRenderProps {
+  /** Closes through `onBeforeClose`, like the close button. */
+  close(): void;
+}
+
+// Shared with every other component, so class handling cannot drift.
+export { cx } from "../../shared/core/cx";