entity-react-modals 1.0.0 → 1.1.0

package/README.md

@@ -1,10 +1,17 @@
 # entity-react-modals
 
+[![npm version](https://img.shields.io/npm/v/entity-react-modals.svg)](https://www.npmjs.com/package/entity-react-modals)
+[![npm downloads](https://img.shields.io/npm/dm/entity-react-modals.svg)](https://www.npmjs.com/package/entity-react-modals)
+[![license](https://img.shields.io/npm/l/entity-react-modals.svg)](https://github.com/BazilSuhail/npm-react-modals/blob/main/LICENSE)
+[![bundle size](https://img.shields.io/bundlephobia/minzip/entity-react-modals)](https://bundlephobia.com/package/entity-react-modals)
+[![typescript](https://img.shields.io/badge/typescript-ready-blue.svg)](https://www.typescriptlang.org/)
+
 Zero-dependency React modal library with spring physics animations powered by the Web Animations API.
 
-- No animation libraries required — uses native WAAPI
+- **7 animation variants** — scale, slide, fade, none
+- **5 spring presets** — default, gentle, wobbly, stiff, slow
+- Zero-config — styles auto-injected, no CSS import needed
 - Compound component API for flexible composition
-- 5 built-in spring presets + custom spring configs
 - Controlled and uncontrolled modes
 - Portal-rendered, accessible, and tree-shakable
 
@@ -26,7 +33,6 @@ import {
   ModalFooter,
   ModalClose,
 } from 'entity-react-modals';
-import 'entity-react-modals/styles.css';
 
 function App() {
   return (
@@ -74,7 +80,8 @@ function App() {
 | `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. |
+| `animation` | `AnimationVariant` | `'scale'` | Animation variant. |
+| `spring` | `SpringPreset \| SpringConfig` | `'default'` | Spring physics 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. |
@@ -87,7 +94,9 @@ Props set on `ModalContent` override those set on `Modal` for that specific cont
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `children` | `ReactNode` | — | Modal panel content. |
+| `className` | `string` | — | Additional CSS class on the panel. |
 | `size` | `'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | Panel max-width. |
+| `animation` | `AnimationVariant` | `'scale'` | Animation variant. |
 | `closeOnBackdropClick` | `boolean` | `true` | Close when clicking the backdrop. |
 | `closeOnEscape` | `boolean` | `true` | Close on Escape key press. |
 | `backdropColor` | `string` | — | Override backdrop color. |
@@ -109,6 +118,184 @@ Props set on `ModalContent` override those set on `Modal` for that specific cont
 | `children` | `ReactNode` | Section content. |
 | `className` | `string` | Additional CSS class. |
 
+## Animation Variants
+
+| Variant | Effect |
+|---|---|
+| `scale` | Scale from 0.95 to 1 (default) |
+| `slide-bottom` | Slide up from below |
+| `slide-top` | Slide down from above |
+| `slide-left` | Slide in from left |
+| `slide-right` | Slide in from right |
+| `fade` | Opacity only, no transform |
+| `none` | Instant, no animation |
+
+```tsx
+// Set on Modal (applies to all content)
+<Modal animation="slide-bottom">...</Modal>
+
+// Set on ModalContent (overrides Modal)
+<ModalContent animation="slide-left" spring="gentle">...</ModalContent>
+
+// Disable animation entirely
+<ModalContent animation="none">...</ModalContent>
+```
+
+### Real-World Example: Notification Toast
+
+```tsx
+<Modal>
+  <ModalTrigger>
+    <button>Show Notification</button>
+  </ModalTrigger>
+  <ModalContent size="sm" animation="slide-bottom" spring="stiff"
+    backdropColor="rgba(0, 0, 0, 0.3)" backdropBlur={4}>
+    <div style={{ padding: '24px', textAlign: 'center' }}>
+      <h3>Success!</h3>
+      <p>Your changes have been saved.</p>
+      <ModalClose>Done</ModalClose>
+    </div>
+  </ModalContent>
+</Modal>
+```
+
+### Real-World Example: Settings Panel
+
+```tsx
+<Modal>
+  <ModalTrigger>
+    <button>Settings</button>
+  </ModalTrigger>
+  <ModalContent size="lg" animation="slide-left" spring="default"
+    backdropColor="rgba(0, 0, 0, 0.4)" backdropBlur={8}>
+    <ModalHeader>
+      <h2>Settings</h2>
+      <ModalClose />
+    </ModalHeader>
+    <ModalBody>
+      {/* Toggle sections, forms, danger zones */}
+    </ModalBody>
+  </ModalContent>
+</Modal>
+```
+
+### Real-World Example: Command Palette
+
+```tsx
+<Modal>
+  <ModalTrigger>
+    <button>Search</button>
+  </ModalTrigger>
+  <ModalContent size="md" animation="scale" spring="stiff"
+    backdropColor="rgba(0, 0, 0, 0.6)" backdropBlur={8}>
+    <div style={{ padding: '12px' }}>
+      <input type="text" placeholder="Search commands..." autoFocus />
+      {/* Command list */}
+    </div>
+  </ModalContent>
+</Modal>
+```
+
+### Real-World Example: Payment Form
+
+```tsx
+<Modal>
+  <ModalTrigger>
+    <button>Upgrade to Pro</button>
+  </ModalTrigger>
+  <ModalContent size="md" spring="gentle"
+    backdropColor="rgba(0, 0, 0, 0.5)" backdropBlur={6}>
+    <ModalHeader>
+      <h2>Upgrade to Pro</h2>
+      <ModalClose />
+    </ModalHeader>
+    <ModalBody>
+      <p>$49 / one time</p>
+      {/* Card form */}
+    </ModalBody>
+    <ModalFooter>
+      <ModalClose>Cancel</ModalClose>
+      <button>Pay $49</button>
+    </ModalFooter>
+  </ModalContent>
+</Modal>
+```
+
+### Real-World Example: Image Viewer
+
+```tsx
+<Modal>
+  <ModalTrigger>
+    <button>View Image</button>
+  </ModalTrigger>
+  <ModalContent size="xl" animation="scale" spring="gentle"
+    backdropColor="rgba(0, 0, 0, 0.85)" backdropBlur={12}>
+    <ModalClose />
+    {/* Full-width image content */}
+  </ModalContent>
+</Modal>
+```
+
+### Real-World Example: Destructive Alert
+
+```tsx
+<Modal>
+  <ModalTrigger>
+    <button>Delete Account</button>
+  </ModalTrigger>
+  <ModalContent size="sm" animation="slide-top" spring="stiff"
+    backdropColor="rgba(0, 0, 0, 0.6)" backdropBlur={4}>
+    <div style={{ padding: '24px', textAlign: 'center' }}>
+      <h3>Are you sure?</h3>
+      <p>This action cannot be undone.</p>
+      <ModalClose>Cancel</ModalClose>
+      <button style={{ background: '#ef4444', color: 'white' }}>
+        Yes, delete everything
+      </button>
+    </div>
+  </ModalContent>
+</Modal>
+```
+
+### Real-World Example: Login Form
+
+```tsx
+<Modal>
+  <ModalTrigger>
+    <button>Sign in</button>
+  </ModalTrigger>
+  <ModalContent size="sm" animation="slide-bottom" spring="gentle"
+    backdropColor="rgba(16, 185, 129, 0.15)" backdropBlur={12}>
+    <div style={{ padding: '24px' }}>
+      <h3>Welcome back</h3>
+      <input type="email" placeholder="you@example.com" />
+      <input type="password" placeholder="Password" />
+      <button>Sign in</button>
+    </div>
+  </ModalContent>
+</Modal>
+```
+
+### Real-World Example: Pricing Cards
+
+```tsx
+<Modal>
+  <ModalTrigger>
+    <button>View Pricing</button>
+  </ModalTrigger>
+  <ModalContent size="lg" animation="slide-right" spring="wobbly"
+    backdropColor="rgba(0, 0, 0, 0.5)" backdropBlur={8}>
+    <ModalHeader>
+      <h2>Choose your plan</h2>
+      <ModalClose />
+    </ModalHeader>
+    <ModalBody>
+      {/* Three-column pricing cards */}
+    </ModalBody>
+  </ModalContent>
+</Modal>
+```
+
 ## Sizes
 
 | Size | Max Width |
@@ -152,15 +339,6 @@ Pass a `SpringConfig` object to fine-tune the animation:
 | `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`:
@@ -261,9 +439,9 @@ function App() {
 
       <Modal>
         <ModalTrigger><button>Second</button></ModalTrigger>
-        <ModalContent size="lg" spring="gentle">
+        <ModalContent size="lg" animation="slide-left" spring="gentle">
           <ModalHeader><h2>Second Modal</h2><ModalClose /></ModalHeader>
-          <ModalBody>Different size and spring</ModalBody>
+          <ModalBody>Different size, animation, and spring</ModalBody>
         </ModalContent>
       </Modal>
     </>
@@ -310,12 +488,13 @@ import type {
   ModalFooterProps,
   SpringConfig,
   SpringPreset,
+  AnimationVariant,
 } 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.
+The package uses the `exports` field with conditional ESM/CJS builds and `sideEffects: false`. Styles are auto-injected on first import. Bundlers will tree-shake unused components automatically.
 
 ```tsx
 // Only imports what you use

package/dist/index.cjs

@@ -4,7 +4,124 @@ var react = require('react');
 var jsxRuntime = require('react/jsx-runtime');
 var reactDom = require('react-dom');
 
-// src/Modal.tsx
+// src/inject.ts
+var INJECTED = "__ERM_INJECTED__";
+function injectStyles(css) {
+  if (typeof document === "undefined") return;
+  if (window[INJECTED]) return;
+  window[INJECTED] = true;
+  const style = document.createElement("style");
+  style.textContent = css;
+  document.head.appendChild(style);
+}
+
+// src/styles.ts
+var styles = `
+: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;
+}
+
+.rm-backdrop {
+  position: fixed;
+  inset: 0;
+  z-index: 9998;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 20px;
+  opacity: 0;
+}
+
+.rm-panel {
+  position: relative;
+  z-index: 9999;
+  background: var(--rm-panel-bg);
+  border-radius: var(--rm-panel-radius);
+  box-shadow: var(--rm-panel-shadow);
+  width: 100%;
+  max-height: calc(100vh - 40px);
+  opacity: 0;
+  transform: scale(0.95);
+  display: flex;
+  flex-direction: column;
+}
+
+.rm-panel--sm { max-width: 400px; }
+.rm-panel--md { max-width: 560px; }
+.rm-panel--lg { max-width: 720px; }
+.rm-panel--xl { max-width: 900px; }
+
+.rm-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 16px 20px;
+  border-bottom: 1px solid var(--rm-header-border);
+  flex-shrink: 0;
+}
+
+.rm-header h2,
+.rm-header h3 {
+  margin: 0;
+  font-size: 1.125rem;
+  font-weight: 600;
+  color: #1e293b;
+}
+
+.rm-body {
+  padding: 20px;
+  overflow-y: auto;
+  flex: 1;
+  min-height: 0;
+}
+
+.rm-footer {
+  display: flex;
+  align-items: center;
+  justify-content: flex-end;
+  gap: 8px;
+  padding: 16px 20px;
+  border-top: 1px solid var(--rm-footer-border);
+  flex-shrink: 0;
+}
+
+.rm-close {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 28px;
+  height: 28px;
+  padding: 0;
+  border: none;
+  border-radius: 6px;
+  background: transparent;
+  color: var(--rm-close-color);
+  font-size: 1.25rem;
+  line-height: 1;
+  cursor: pointer;
+  transition: background-color 0.15s ease, color 0.15s ease;
+}
+
+.rm-close:hover {
+  background: rgba(59, 130, 246, 0.1);
+  color: var(--rm-close-hover);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .rm-backdrop,
+  .rm-panel {
+    transition: none !important;
+    animation: none !important;
+  }
+}
+`;
 var ModalContext = react.createContext(null);
 function useModalContext() {
   const ctx = react.useContext(ModalContext);
@@ -17,6 +134,7 @@ function Modal({
   defaultOpen = false,
   onOpenChange,
   spring,
+  animation,
   backdropColor,
   backdropBlur,
   size,
@@ -46,6 +164,7 @@ function Modal({
     onClose,
     onOpen,
     spring,
+    animation,
     backdropColor,
     backdropBlur,
     size,
@@ -114,21 +233,58 @@ function generateSpringKeyframes(from, to, config, options) {
   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) => {
+function buildTransformKeyframes(positions, variant) {
+  return positions.map((pos, i) => {
     const offset = i / (positions.length - 1);
-    if (property === "opacity") {
-      return { opacity: String(pos), offset };
+    switch (variant) {
+      case "fade":
+        return { opacity: String(pos), offset };
+      case "scale":
+        return {
+          transform: `scale(${0.95 + 0.05 * pos})`,
+          opacity: String(pos),
+          offset
+        };
+      case "slide-bottom":
+        return {
+          transform: `translateY(${(1 - pos) * 100}%)`,
+          opacity: String(pos),
+          offset
+        };
+      case "slide-top":
+        return {
+          transform: `translateY(${(pos - 1) * 100}%)`,
+          opacity: String(pos),
+          offset
+        };
+      case "slide-left":
+        return {
+          transform: `translateX(${(pos - 1) * 100}%)`,
+          opacity: String(pos),
+          offset
+        };
+      case "slide-right":
+        return {
+          transform: `translateX(${(1 - pos) * 100}%)`,
+          opacity: String(pos),
+          offset
+        };
+      default:
+        return { opacity: String(pos), offset };
     }
-    const scale = 0.95 + 0.05 * pos;
-    return {
-      transform: `scale(${scale})`,
-      opacity: String(pos),
-      offset
-    };
   });
-  return { keyframes: waapiKeyframes, duration };
+}
+function springToWAAPIKeyframes(fromValue, toValue, property, config, options) {
+  const { keyframes: positions, duration } = generateSpringKeyframes(fromValue, toValue, config, options);
+  if (property === "opacity") {
+    const keyframes = positions.map((pos, i) => ({
+      opacity: String(pos),
+      offset: i / (positions.length - 1)
+    }));
+    return { keyframes, duration };
+  }
+  const variant = options?.variant ?? "scale";
+  return { keyframes: buildTransformKeyframes(positions, variant), duration };
 }
 
 // src/animate.ts
@@ -137,10 +293,11 @@ function prefersReducedMotion() {
 }
 var EXIT_MAX_DURATION = 400;
 function animateIn(backdropEl, panelEl, config) {
-  if (prefersReducedMotion()) {
+  const variant = config?.animation ?? "scale";
+  if (prefersReducedMotion() || variant === "none") {
     backdropEl.style.opacity = "1";
     panelEl.style.opacity = "1";
-    panelEl.style.transform = "scale(1)";
+    panelEl.style.transform = "none";
     return [];
   }
   const springConfig = resolveSpringConfig(config?.spring);
@@ -148,7 +305,7 @@ function animateIn(backdropEl, panelEl, config) {
     ...springConfig,
     stiffness: springConfig.stiffness * 0.8
   });
-  const { keyframes: panelKF, duration: panelDur } = springToWAAPIKeyframes(0, 1, "transform", springConfig);
+  const { keyframes: panelKF, duration: panelDur } = springToWAAPIKeyframes(0, 1, "transform", springConfig, { variant });
   const backdropAnim = backdropEl.animate(backdropKF, {
     duration: backdropDur,
     easing: "linear",
@@ -162,7 +319,8 @@ function animateIn(backdropEl, panelEl, config) {
   return [backdropAnim, panelAnim];
 }
 function animateOut(backdropEl, panelEl, config) {
-  if (prefersReducedMotion()) {
+  const variant = config?.animation ?? "scale";
+  if (prefersReducedMotion() || variant === "none") {
     return Promise.resolve();
   }
   const springConfig = resolveSpringConfig(config?.spring);
@@ -176,7 +334,8 @@ function animateOut(backdropEl, panelEl, config) {
     stiffness: exitConfig.stiffness * 0.8
   }, { maxDuration: EXIT_MAX_DURATION });
   const { keyframes: panelKF, duration: panelDur } = springToWAAPIKeyframes(1, 0, "transform", exitConfig, {
-    maxDuration: EXIT_MAX_DURATION
+    maxDuration: EXIT_MAX_DURATION,
+    variant
   });
   const backdropAnim = backdropEl.animate(backdropKF, {
     duration: backdropDur,
@@ -219,16 +378,12 @@ function useClickOutside(enabled, onClick) {
   }, [enabled, handleClick]);
   return panelRef;
 }
-var SIZE_MAP = {
-  sm: "400px",
-  md: "560px",
-  lg: "720px",
-  xl: "900px"
-};
 var SAFETY_UNMOUNT_MS = 600;
 function ModalContent({
   children,
+  className,
   size: sizeProp,
+  animation: animationProp,
   closeOnBackdropClick = true,
   closeOnEscape = true,
   backdropColor,
@@ -238,6 +393,7 @@ function ModalContent({
 }) {
   const ctx = useModalContext();
   const size = sizeProp ?? ctx.size ?? "md";
+  const resolvedAnimation = animationProp ?? ctx.animation ?? "scale";
   const resolvedBackdropColor = backdropColor ?? ctx.backdropColor ?? "rgba(0, 0, 0, 0.6)";
   const resolvedBackdropBlur = backdropBlur ?? ctx.backdropBlur ?? 4;
   const resolvedSpring = spring ?? ctx.spring;
@@ -268,7 +424,8 @@ function ModalContent({
         requestAnimationFrame(() => {
           if (backdropRef.current && panelRef.current) {
             animateIn(backdropRef.current, panelRef.current, {
-              spring: resolvedSpring});
+              spring: resolvedSpring,
+              animation: resolvedAnimation});
             setTimeout(() => {
               animatingRef.current = false;
             }, 500);
@@ -288,14 +445,15 @@ function ModalContent({
       safetyTimerRef.current = setTimeout(unmount, SAFETY_UNMOUNT_MS);
       if (backdropRef.current && panelRef.current) {
         animateOut(backdropRef.current, panelRef.current, {
-          spring: resolvedSpring}).then(unmount);
+          spring: resolvedSpring,
+          animation: resolvedAnimation}).then(unmount);
       } else {
         unmount();
       }
     }
     prevOpen.current = ctx.open;
     return clearSafetyTimer;
-  }, [ctx.open, resolvedSpring, animationDuration, clearSafetyTimer]);
+  }, [ctx.open, resolvedSpring, resolvedAnimation, animationDuration, clearSafetyTimer]);
   if (!render) return null;
   const setRefs = (el) => {
     clickOutsideRef.current = el;
@@ -316,10 +474,9 @@ function ModalContent({
           "div",
           {
             ref: setRefs,
-            className: `rm-panel rm-panel--${size}`,
+            className: `rm-panel rm-panel--${size}${className ? ` ${className}` : ""}`,
             role: "dialog",
             "aria-modal": "true",
-            style: { maxWidth: SIZE_MAP[size] },
             children
           }
         )
@@ -342,6 +499,9 @@ function ModalFooter({ children, className }) {
   return /* @__PURE__ */ jsxRuntime.jsx("div", { className: `rm-footer ${className ?? ""}`, children });
 }
 
+// src/index.ts
+injectStyles(styles);
+
 exports.Modal = Modal;
 exports.ModalBody = ModalBody;
 exports.ModalClose = ModalClose;