entity-react-modals 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 bazil
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,327 @@
+# entity-react-modals
+
+Zero-dependency React modal library with spring physics animations powered by the Web Animations API.
+
+- No animation libraries required — uses native WAAPI
+- Compound component API for flexible composition
+- 5 built-in spring presets + custom spring configs
+- Controlled and uncontrolled modes
+- Portal-rendered, accessible, and tree-shakable
+
+## Install
+
+```bash
+npm install entity-react-modals
+```
+
+## Quick Start
+
+```tsx
+import {
+  Modal,
+  ModalTrigger,
+  ModalContent,
+  ModalHeader,
+  ModalBody,
+  ModalFooter,
+  ModalClose,
+} from 'entity-react-modals';
+import 'entity-react-modals/styles.css';
+
+function App() {
+  return (
+    <Modal>
+      <ModalTrigger>
+        <button>Open Modal</button>
+      </ModalTrigger>
+      <ModalContent>
+        <ModalHeader>
+          <h2>Hello</h2>
+          <ModalClose />
+        </ModalHeader>
+        <ModalBody>
+          <p>This modal uses spring physics for smooth animations.</p>
+        </ModalBody>
+        <ModalFooter>
+          <ModalClose>Cancel</ModalClose>
+          <button>Confirm</button>
+        </ModalFooter>
+      </ModalContent>
+    </Modal>
+  );
+}
+```
+
+## Components
+
+| Component | Purpose |
+|---|---|
+| `Modal` | Root provider. Manages open/close state and passes config to children via context. |
+| `ModalTrigger` | Wraps an element to open the modal on click. Clones child and injects `onClick`. |
+| `ModalContent` | The dialog panel. Renders via portal to `document.body`. Handles animations, backdrop, escape, click-outside. |
+| `ModalHeader` | Layout wrapper for the header section. |
+| `ModalBody` | Layout wrapper for the body content. |
+| `ModalFooter` | Layout wrapper for the footer actions. |
+| `ModalClose` | Button that closes the modal. Defaults to `×` character. |
+
+## Props
+
+### Modal
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | — | Must contain `ModalContent` and optionally `ModalTrigger`. |
+| `open` | `boolean` | — | Controlled open state. |
+| `defaultOpen` | `boolean` | `false` | Initial open state for uncontrolled mode. |
+| `onOpenChange` | `(open: boolean) => void` | — | Called when open state changes. |
+| `spring` | `SpringPreset \| SpringConfig` | `'default'` | Spring animation config. |
+| `backdropColor` | `string` | `'rgba(0,0,0,0.6)'` | Backdrop background color. |
+| `backdropBlur` | `number` | `4` | Backdrop blur radius in px. |
+| `size` | `'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | Panel max-width preset. |
+| `animationDuration` | `number` | — | Override computed spring duration in ms. |
+
+### ModalContent
+
+Props set on `ModalContent` override those set on `Modal` for that specific content panel.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | — | Modal panel content. |
+| `size` | `'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | Panel max-width. |
+| `closeOnBackdropClick` | `boolean` | `true` | Close when clicking the backdrop. |
+| `closeOnEscape` | `boolean` | `true` | Close on Escape key press. |
+| `backdropColor` | `string` | — | Override backdrop color. |
+| `backdropBlur` | `number` | — | Override backdrop blur. |
+| `spring` | `SpringPreset \| SpringConfig` | — | Override spring config. |
+| `animationDuration` | `number` | — | Override animation duration. |
+
+### ModalClose
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | `'×'` | Button content. |
+| `className` | `string` | — | Additional CSS class. |
+
+### ModalHeader, ModalBody, ModalFooter
+
+| Prop | Type | Description |
+|---|---|---|
+| `children` | `ReactNode` | Section content. |
+| `className` | `string` | Additional CSS class. |
+
+## Sizes
+
+| Size | Max Width |
+|---|---|
+| `sm` | 400px |
+| `md` | 560px |
+| `lg` | 720px |
+| `xl` | 900px |
+
+```tsx
+<ModalContent size="lg">...</ModalContent>
+```
+
+## Spring Presets
+
+| Preset | Stiffness | Damping | Mass | Feel |
+|---|---|---|---|---|
+| `default` | 100 | 10 | 1 | Moderate bounce, balanced |
+| `gentle` | 100 | 20 | 1 | Critically damped, no overshoot |
+| `wobbly` | 200 | 10 | 1 | Playful, lots of bounce |
+| `stiff` | 400 | 30 | 1 | Snappy, quick settle |
+| `slow` | 50 | 20 | 1 | Heavy, deliberate |
+
+```tsx
+<ModalContent spring="wobbly">...</ModalContent>
+```
+
+## Custom Spring Config
+
+Pass a `SpringConfig` object to fine-tune the animation:
+
+```tsx
+<ModalContent spring={{ stiffness: 300, damping: 15, mass: 0.8 }}>
+  ...
+</ModalContent>
+```
+
+| Parameter | Description |
+|---|---|
+| `stiffness` | Spring stiffness. Higher = faster response. |
+| `damping` | Damping force. Higher = less oscillation. |
+| `mass` | Mass of the animated object. Lower = lighter feel. |
+
+Spring config can also be set on the `Modal` root and it applies to all content panels:
+
+```tsx
+<Modal spring={{ stiffness: 300, damping: 15, mass: 0.8 }}>
+  <ModalTrigger>...</ModalTrigger>
+  <ModalContent>...</ModalContent>
+</Modal>
+```
+
+## Controlled Mode
+
+Manage open/close state externally with `useState`:
+
+```tsx
+function ControlledModal() {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <>
+      <button onClick={() => setOpen(true)}>Open</button>
+      <Modal open={open} onOpenChange={setOpen}>
+        <ModalContent>
+          <ModalHeader>
+            <h2>Controlled</h2>
+            <ModalClose />
+          </ModalHeader>
+          <ModalBody>
+            <p>State is managed by the parent.</p>
+            <p>Status: {open ? 'Open' : 'Closed'}</p>
+          </ModalBody>
+          <ModalFooter>
+            <button onClick={() => setOpen(false)}>Close</button>
+          </ModalFooter>
+        </ModalContent>
+      </Modal>
+    </>
+  );
+}
+```
+
+## Uncontrolled Mode
+
+Use `defaultOpen` for simple cases where you don't need external state:
+
+```tsx
+<Modal defaultOpen={false}>
+  <ModalTrigger>
+    <button>Open</button>
+  </ModalTrigger>
+  <ModalContent>
+    <ModalHeader>
+      <h2>Uncontrolled</h2>
+      <ModalClose />
+    </ModalHeader>
+    <ModalBody>
+      <p>Managed internally.</p>
+    </ModalBody>
+  </ModalContent>
+</Modal>
+```
+
+## Backdrop Customization
+
+Customize the backdrop color and blur intensity:
+
+```tsx
+{/* Dark backdrop with heavy blur */}
+<ModalContent backdropColor="rgba(0, 0, 0, 0.8)" backdropBlur={20}>
+  ...
+</ModalContent>
+
+{/* Colored backdrop */}
+<ModalContent backdropColor="rgba(99, 102, 241, 0.4)" backdropBlur={8}>
+  ...
+</ModalContent>
+```
+
+## Disabling Close Behaviors
+
+```tsx
+{/* Disable close on backdrop click */}
+<ModalContent closeOnBackdropClick={false}>
+  ...
+</ModalContent>
+
+{/* Disable close on Escape key */}
+<ModalContent closeOnEscape={false}>
+  ...
+</ModalContent>
+```
+
+## Multiple Modals
+
+Each `Modal` provider is independent. Nest multiple modals freely:
+
+```tsx
+function App() {
+  return (
+    <>
+      <Modal>
+        <ModalTrigger><button>First</button></ModalTrigger>
+        <ModalContent>
+          <ModalHeader><h2>First Modal</h2><ModalClose /></ModalHeader>
+          <ModalBody>Content</ModalBody>
+        </ModalContent>
+      </Modal>
+
+      <Modal>
+        <ModalTrigger><button>Second</button></ModalTrigger>
+        <ModalContent size="lg" spring="gentle">
+          <ModalHeader><h2>Second Modal</h2><ModalClose /></ModalHeader>
+          <ModalBody>Different size and spring</ModalBody>
+        </ModalContent>
+      </Modal>
+    </>
+  );
+}
+```
+
+## CSS Custom Properties
+
+Override these in your CSS to theme the modals globally:
+
+```css
+:root {
+  --rm-backdrop-bg: rgba(0, 0, 0, 0.6);
+  --rm-panel-bg: #ffffff;
+  --rm-panel-radius: 12px;
+  --rm-panel-shadow: 0 20px 60px rgba(0, 0, 0, 0.15);
+  --rm-close-color: #3b82f6;
+  --rm-close-hover: #2563eb;
+  --rm-header-border: #e2e8f0;
+  --rm-footer-border: #e2e8f0;
+}
+```
+
+## Accessibility
+
+- `role="dialog"` and `aria-modal="true"` on the panel
+- `aria-label="Close"` on the close button
+- Focus trapped within the modal via backdrop click and escape handling
+- Respects `prefers-reduced-motion: reduce` — animations are skipped entirely
+
+## TypeScript
+
+All component props and spring types are fully typed and exported:
+
+```tsx
+import type {
+  ModalProps,
+  ModalContentProps,
+  ModalTriggerProps,
+  ModalCloseProps,
+  ModalHeaderProps,
+  ModalBodyProps,
+  ModalFooterProps,
+  SpringConfig,
+  SpringPreset,
+} from 'entity-react-modals';
+```
+
+## Tree Shaking
+
+The package uses the `exports` field with conditional ESM/CJS builds and marks CSS as the only side effect. Bundlers will tree-shake unused components automatically.
+
+```tsx
+// Only imports what you use
+import { Modal, ModalContent } from 'entity-react-modals';
+```
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,353 @@
+'use strict';
+
+var react = require('react');
+var jsxRuntime = require('react/jsx-runtime');
+var reactDom = require('react-dom');
+
+// src/Modal.tsx
+var ModalContext = react.createContext(null);
+function useModalContext() {
+  const ctx = react.useContext(ModalContext);
+  if (!ctx) throw new Error("Modal compound components must be used within <Modal>");
+  return ctx;
+}
+function Modal({
+  children,
+  open: controlledOpen,
+  defaultOpen = false,
+  onOpenChange,
+  spring,
+  backdropColor,
+  backdropBlur,
+  size,
+  animationDuration
+}) {
+  const [internalOpen, setInternalOpen] = react.useState(defaultOpen);
+  const isControlled = controlledOpen !== void 0;
+  const open = isControlled ? controlledOpen : internalOpen;
+  const onClose = react.useCallback(() => {
+    if (isControlled) {
+      onOpenChange?.(false);
+    } else {
+      setInternalOpen(false);
+      onOpenChange?.(false);
+    }
+  }, [isControlled, onOpenChange]);
+  const onOpen = react.useCallback(() => {
+    if (isControlled) {
+      onOpenChange?.(true);
+    } else {
+      setInternalOpen(true);
+      onOpenChange?.(true);
+    }
+  }, [isControlled, onOpenChange]);
+  const value = {
+    open,
+    onClose,
+    onOpen,
+    spring,
+    backdropColor,
+    backdropBlur,
+    size,
+    animationDuration
+  };
+  return /* @__PURE__ */ jsxRuntime.jsx(ModalContext.Provider, { value, children });
+}
+function ModalTrigger({ children }) {
+  const { onOpen } = useModalContext();
+  if (!react.isValidElement(children)) {
+    return /* @__PURE__ */ jsxRuntime.jsx("button", { onClick: onOpen, children });
+  }
+  return react.cloneElement(children, {
+    onClick: (e) => {
+      onOpen();
+      const existing = children.props.onClick;
+      if (typeof existing === "function") existing(e);
+    }
+  });
+}
+
+// src/spring.ts
+var PRESETS = {
+  default: { stiffness: 100, damping: 10, mass: 1 },
+  gentle: { stiffness: 100, damping: 20, mass: 1 },
+  wobbly: { stiffness: 200, damping: 10, mass: 1 },
+  stiff: { stiffness: 400, damping: 30, mass: 1 },
+  slow: { stiffness: 50, damping: 20, mass: 1 }
+};
+var VELOCITY_THRESHOLD = 1e-3;
+var DISPLACEMENT_THRESHOLD = 1e-3;
+var MAX_SIMULATION_STEPS = 1200;
+var FIXED_DT = 1 / 120;
+function resolveSpringConfig(input) {
+  if (!input) return PRESETS.default;
+  if (typeof input === "string") return PRESETS[input] ?? PRESETS.default;
+  return { ...PRESETS.default, ...input };
+}
+function isAtRest(value, velocity, target) {
+  return Math.abs(velocity) < VELOCITY_THRESHOLD && Math.abs(value - target) < DISPLACEMENT_THRESHOLD;
+}
+function generateSpringKeyframes(from, to, config, options) {
+  const { stiffness, damping, mass } = config;
+  const maxSteps = options?.maxDuration ? Math.min(MAX_SIMULATION_STEPS, Math.ceil(options.maxDuration / 1e3 / FIXED_DT)) : MAX_SIMULATION_STEPS;
+  let value = from;
+  let velocity = 0;
+  const positions = [from];
+  let steps = 0;
+  while (steps < maxSteps) {
+    if (isAtRest(value, velocity, to)) {
+      positions.push(to);
+      break;
+    }
+    const displacement = value - to;
+    const springForce = -stiffness * displacement;
+    const dampingForce = -damping * velocity;
+    const acceleration = (springForce + dampingForce) / mass;
+    velocity += acceleration * FIXED_DT;
+    value += velocity * FIXED_DT;
+    positions.push(value);
+    steps++;
+  }
+  if (steps >= maxSteps) {
+    positions.push(to);
+  }
+  const duration = steps * FIXED_DT * 1e3;
+  return { keyframes: positions, duration };
+}
+function springToWAAPIKeyframes(fromValue, toValue, property, config, options) {
+  const { keyframes: positions, duration } = generateSpringKeyframes(fromValue, toValue, config, options);
+  const waapiKeyframes = positions.map((pos, i) => {
+    const offset = i / (positions.length - 1);
+    if (property === "opacity") {
+      return { opacity: String(pos), offset };
+    }
+    const scale = 0.95 + 0.05 * pos;
+    return {
+      transform: `scale(${scale})`,
+      opacity: String(pos),
+      offset
+    };
+  });
+  return { keyframes: waapiKeyframes, duration };
+}
+
+// src/animate.ts
+function prefersReducedMotion() {
+  return window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+}
+var EXIT_MAX_DURATION = 400;
+function animateIn(backdropEl, panelEl, config) {
+  if (prefersReducedMotion()) {
+    backdropEl.style.opacity = "1";
+    panelEl.style.opacity = "1";
+    panelEl.style.transform = "scale(1)";
+    return [];
+  }
+  const springConfig = resolveSpringConfig(config?.spring);
+  const { keyframes: backdropKF, duration: backdropDur } = springToWAAPIKeyframes(0, 1, "opacity", {
+    ...springConfig,
+    stiffness: springConfig.stiffness * 0.8
+  });
+  const { keyframes: panelKF, duration: panelDur } = springToWAAPIKeyframes(0, 1, "transform", springConfig);
+  const backdropAnim = backdropEl.animate(backdropKF, {
+    duration: backdropDur,
+    easing: "linear",
+    fill: "forwards"
+  });
+  const panelAnim = panelEl.animate(panelKF, {
+    duration: panelDur,
+    easing: "linear",
+    fill: "forwards"
+  });
+  return [backdropAnim, panelAnim];
+}
+function animateOut(backdropEl, panelEl, config) {
+  if (prefersReducedMotion()) {
+    return Promise.resolve();
+  }
+  const springConfig = resolveSpringConfig(config?.spring);
+  const exitConfig = {
+    stiffness: springConfig.stiffness * 2,
+    damping: springConfig.damping * 1.5,
+    mass: springConfig.mass
+  };
+  const { keyframes: backdropKF, duration: backdropDur } = springToWAAPIKeyframes(1, 0, "opacity", {
+    ...exitConfig,
+    stiffness: exitConfig.stiffness * 0.8
+  }, { maxDuration: EXIT_MAX_DURATION });
+  const { keyframes: panelKF, duration: panelDur } = springToWAAPIKeyframes(1, 0, "transform", exitConfig, {
+    maxDuration: EXIT_MAX_DURATION
+  });
+  const backdropAnim = backdropEl.animate(backdropKF, {
+    duration: backdropDur,
+    easing: "linear",
+    fill: "forwards"
+  });
+  const panelAnim = panelEl.animate(panelKF, {
+    duration: panelDur,
+    easing: "linear",
+    fill: "forwards"
+  });
+  return Promise.all([backdropAnim.finished, panelAnim.finished]).then(() => {
+  });
+}
+function useEscapeKey(enabled, onEscape) {
+  react.useEffect(() => {
+    if (!enabled) return;
+    function handleKeyDown(e) {
+      if (e.key === "Escape") onEscape();
+    }
+    document.addEventListener("keydown", handleKeyDown);
+    return () => document.removeEventListener("keydown", handleKeyDown);
+  }, [enabled, onEscape]);
+}
+function useClickOutside(enabled, onClick) {
+  const panelRef = react.useRef(null);
+  const handleClick = react.useCallback(
+    (e) => {
+      if (!enabled || !panelRef.current) return;
+      if (!panelRef.current.contains(e.target)) {
+        onClick();
+      }
+    },
+    [enabled, onClick]
+  );
+  react.useEffect(() => {
+    if (!enabled) return;
+    document.addEventListener("mousedown", handleClick);
+    return () => document.removeEventListener("mousedown", handleClick);
+  }, [enabled, handleClick]);
+  return panelRef;
+}
+var SIZE_MAP = {
+  sm: "400px",
+  md: "560px",
+  lg: "720px",
+  xl: "900px"
+};
+var SAFETY_UNMOUNT_MS = 600;
+function ModalContent({
+  children,
+  size: sizeProp,
+  closeOnBackdropClick = true,
+  closeOnEscape = true,
+  backdropColor,
+  backdropBlur,
+  spring,
+  animationDuration
+}) {
+  const ctx = useModalContext();
+  const size = sizeProp ?? ctx.size ?? "md";
+  const resolvedBackdropColor = backdropColor ?? ctx.backdropColor ?? "rgba(0, 0, 0, 0.6)";
+  const resolvedBackdropBlur = backdropBlur ?? ctx.backdropBlur ?? 4;
+  const resolvedSpring = spring ?? ctx.spring;
+  const [render, setRender] = react.useState(ctx.open);
+  const backdropRef = react.useRef(null);
+  const panelRef = react.useRef(null);
+  const animatingRef = react.useRef(false);
+  const prevOpen = react.useRef(ctx.open);
+  const safetyTimerRef = react.useRef(null);
+  const clearSafetyTimer = react.useCallback(() => {
+    if (safetyTimerRef.current !== null) {
+      clearTimeout(safetyTimerRef.current);
+      safetyTimerRef.current = null;
+    }
+  }, []);
+  const handleClose = react.useCallback(() => {
+    if (animatingRef.current) return;
+    ctx.onClose();
+  }, [ctx]);
+  useEscapeKey(closeOnEscape && ctx.open, handleClose);
+  const clickOutsideRef = useClickOutside(closeOnBackdropClick && ctx.open, handleClose);
+  react.useEffect(() => {
+    if (ctx.open && !prevOpen.current) {
+      clearSafetyTimer();
+      setRender(true);
+      animatingRef.current = true;
+      requestAnimationFrame(() => {
+        requestAnimationFrame(() => {
+          if (backdropRef.current && panelRef.current) {
+            animateIn(backdropRef.current, panelRef.current, {
+              spring: resolvedSpring});
+            setTimeout(() => {
+              animatingRef.current = false;
+            }, 500);
+          }
+        });
+      });
+    } else if (!ctx.open && prevOpen.current) {
+      animatingRef.current = true;
+      if (backdropRef.current) {
+        backdropRef.current.style.pointerEvents = "none";
+      }
+      const unmount = () => {
+        clearSafetyTimer();
+        setRender(false);
+        animatingRef.current = false;
+      };
+      safetyTimerRef.current = setTimeout(unmount, SAFETY_UNMOUNT_MS);
+      if (backdropRef.current && panelRef.current) {
+        animateOut(backdropRef.current, panelRef.current, {
+          spring: resolvedSpring}).then(unmount);
+      } else {
+        unmount();
+      }
+    }
+    prevOpen.current = ctx.open;
+    return clearSafetyTimer;
+  }, [ctx.open, resolvedSpring, animationDuration, clearSafetyTimer]);
+  if (!render) return null;
+  const setRefs = (el) => {
+    clickOutsideRef.current = el;
+    panelRef.current = el;
+  };
+  return reactDom.createPortal(
+    /* @__PURE__ */ jsxRuntime.jsx(
+      "div",
+      {
+        className: "rm-backdrop",
+        ref: backdropRef,
+        style: {
+          background: resolvedBackdropColor,
+          backdropFilter: `blur(${resolvedBackdropBlur}px)`,
+          WebkitBackdropFilter: `blur(${resolvedBackdropBlur}px)`
+        },
+        children: /* @__PURE__ */ jsxRuntime.jsx(
+          "div",
+          {
+            ref: setRefs,
+            className: `rm-panel rm-panel--${size}`,
+            role: "dialog",
+            "aria-modal": "true",
+            style: { maxWidth: SIZE_MAP[size] },
+            children
+          }
+        )
+      }
+    ),
+    document.body
+  );
+}
+function ModalClose({ children = "\xD7", className }) {
+  const { onClose } = useModalContext();
+  return /* @__PURE__ */ jsxRuntime.jsx("button", { className: `rm-close ${className ?? ""}`, onClick: onClose, "aria-label": "Close", children });
+}
+function ModalHeader({ children, className }) {
+  return /* @__PURE__ */ jsxRuntime.jsx("div", { className: `rm-header ${className ?? ""}`, children });
+}
+function ModalBody({ children, className }) {
+  return /* @__PURE__ */ jsxRuntime.jsx("div", { className: `rm-body ${className ?? ""}`, children });
+}
+function ModalFooter({ children, className }) {
+  return /* @__PURE__ */ jsxRuntime.jsx("div", { className: `rm-footer ${className ?? ""}`, children });
+}
+
+exports.Modal = Modal;
+exports.ModalBody = ModalBody;
+exports.ModalClose = ModalClose;
+exports.ModalContent = ModalContent;
+exports.ModalFooter = ModalFooter;
+exports.ModalHeader = ModalHeader;
+exports.ModalTrigger = ModalTrigger;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map