@lerx/promise-modal 0.2.8 → 0.3.0

package/dist/providers/ConfigurationContext/useConfigurationContext.d.ts

@@ -1,7 +1,280 @@
+/**
+ * Hook that provides access to the complete modal configuration context.
+ *
+ * Returns all configuration including component overrides and options.
+ * This is the most comprehensive hook for accessing modal configuration,
+ * useful when you need multiple configuration values or custom components.
+ *
+ * @returns Complete configuration context with components and options
+ */
 export declare const useConfigurationContext: () => import("./ConfigurationContext").ConfigurationContextProps;
+/**
+ * Hook that provides only the modal options from configuration.
+ *
+ * Convenient when you only need access to options like duration, backdrop,
+ * and behavior settings without the component definitions.
+ *
+ * @returns Modal options object with all settings
+ *
+ * @example
+ * Basic usage:
+ * ```tsx
+ * function ModalBackdrop() {
+ *   const options = useConfigurationOptions();
+ *
+ *   return (
+ *     <div
+ *       className="modal-backdrop"
+ *       style={{
+ *         backgroundColor: options.backdrop,
+ *         transition: `opacity ${options.duration} ease`
+ *       }}
+ *       onClick={options.closeOnBackdropClick ? handleClose : undefined}
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * Conditional behavior based on options:
+ * ```tsx
+ * function ModalCloseButton({ onClose }) {
+ *   const { closeOnBackdropClick, manualDestroy } = useConfigurationOptions();
+ *   const [isClosing, setIsClosing] = useState(false);
+ *
+ *   const handleClick = () => {
+ *     if (manualDestroy) {
+ *       setIsClosing(true);
+ *       // Trigger close animation
+ *       setTimeout(onClose, 300);
+ *     } else {
+ *       onClose();
+ *     }
+ *   };
+ *
+ *   // Hide close button if backdrop click is disabled
+ *   if (!closeOnBackdropClick) return null;
+ *
+ *   return (
+ *     <button
+ *       onClick={handleClick}
+ *       className={isClosing ? 'closing' : ''}
+ *     >
+ *       ×
+ *     </button>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * Options-aware animations:
+ * ```tsx
+ * function AnimatedContent({ visible, children }) {
+ *   const options = useConfigurationOptions();
+ *   const contentRef = useRef<HTMLDivElement>(null);
+ *
+ *   useEffect(() => {
+ *     if (!contentRef.current) return;
+ *
+ *     const element = contentRef.current;
+ *     element.style.transition = `all ${options.duration} ease`;
+ *
+ *     if (visible) {
+ *       element.style.opacity = '1';
+ *       element.style.transform = 'scale(1)';
+ *     } else {
+ *       element.style.opacity = '0';
+ *       element.style.transform = 'scale(0.95)';
+ *     }
+ *   }, [visible, options.duration]);
+ *
+ *   return <div ref={contentRef}>{children}</div>;
+ * }
+ * ```
+ */
 export declare const useConfigurationOptions: () => Required<import("../..").ModalOptions>;
+/**
+ * Hook that provides modal animation duration in multiple formats.
+ *
+ * Returns both the original duration string and converted milliseconds,
+ * useful for JavaScript animations and timing calculations.
+ *
+ * @returns Object with duration string and milliseconds number
+ *
+ * @example
+ * Basic animation timing:
+ * ```tsx
+ * function TimedModal() {
+ *   const { duration, milliseconds } = useConfigurationDuration();
+ *   const [phase, setPhase] = useState<'entering' | 'visible' | 'leaving'>();
+ *
+ *   useEffect(() => {
+ *     if (phase === 'entering') {
+ *       const timer = setTimeout(() => setPhase('visible'), milliseconds);
+ *       return () => clearTimeout(timer);
+ *     }
+ *   }, [phase, milliseconds]);
+ *
+ *   return (
+ *     <div
+ *       className={`modal-${phase}`}
+ *       style={{ animationDuration: duration }}
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * Synchronized animations:
+ * ```tsx
+ * function ModalWithStaggeredElements({ items }) {
+ *   const { duration, milliseconds } = useConfigurationDuration();
+ *   const itemDelay = milliseconds / items.length;
+ *
+ *   return (
+ *     <div className="modal">
+ *       {items.map((item, index) => (
+ *         <div
+ *           key={item.id}
+ *           className="modal-item"
+ *           style={{
+ *             animationDuration: duration,
+ *             animationDelay: `${index * itemDelay}ms`
+ *           }}
+ *         >
+ *           {item.content}
+ *         </div>
+ *       ))}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * Progress indicators:
+ * ```tsx
+ * function ModalProgress({ onComplete }) {
+ *   const { milliseconds } = useConfigurationDuration();
+ *   const [progress, setProgress] = useState(0);
+ *
+ *   useEffect(() => {
+ *     const startTime = Date.now();
+ *     const interval = setInterval(() => {
+ *       const elapsed = Date.now() - startTime;
+ *       const percent = Math.min((elapsed / milliseconds) * 100, 100);
+ *       setProgress(percent);
+ *
+ *       if (percent >= 100) {
+ *         clearInterval(interval);
+ *         onComplete();
+ *       }
+ *     }, 16); // ~60fps
+ *
+ *     return () => clearInterval(interval);
+ *   }, [milliseconds, onComplete]);
+ *
+ *   return (
+ *     <div className="progress-bar">
+ *       <div
+ *         className="progress-fill"
+ *         style={{ width: `${progress}%` }}
+ *       />
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @remarks
+ * - Supports various duration formats: '300ms', '0.3s', '1s', etc.
+ * - Automatically converts to milliseconds for JavaScript timing
+ * - Useful for coordinating CSS and JS animations
+ */
 export declare const useConfigurationDuration: () => {
     duration: `${number}ms`;
     milliseconds: number;
 };
+/**
+ * Hook that provides the modal backdrop color configuration.
+ *
+ * Convenient accessor for backdrop styling, supporting any valid CSS color format.
+ *
+ * @returns Backdrop color string
+ *
+ * @example
+ * Basic backdrop:
+ * ```tsx
+ * function ModalOverlay({ visible }) {
+ *   const backdrop = useConfigurationBackdrop();
+ *
+ *   if (!visible) return null;
+ *
+ *   return (
+ *     <div
+ *       className="fixed inset-0"
+ *       style={{ backgroundColor: backdrop }}
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * Animated backdrop with opacity:
+ * ```tsx
+ * function AnimatedBackdrop({ visible }) {
+ *   const backdrop = useConfigurationBackdrop();
+ *   const [opacity, setOpacity] = useState(0);
+ *
+ *   // Parse backdrop color and apply custom opacity
+ *   const backdropWithOpacity = useMemo(() => {
+ *     if (backdrop.startsWith('rgba')) {
+ *       return backdrop.replace(/[\d.]+\)$/, `${opacity})`);
+ *     }
+ *     return `${backdrop}${Math.round(opacity * 255).toString(16).padStart(2, '0')}`;
+ *   }, [backdrop, opacity]);
+ *
+ *   useEffect(() => {
+ *     setOpacity(visible ? 1 : 0);
+ *   }, [visible]);
+ *
+ *   return (
+ *     <div
+ *       className="backdrop"
+ *       style={{
+ *         backgroundColor: backdropWithOpacity,
+ *         transition: 'opacity 300ms ease'
+ *       }}
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * Theme-aware backdrop:
+ * ```tsx
+ * function ThemedBackdrop() {
+ *   const backdrop = useConfigurationBackdrop();
+ *   const { theme } = useTheme();
+ *
+ *   const adjustedBackdrop = useMemo(() => {
+ *     if (theme === 'dark') {
+ *       // Make backdrop darker in dark mode
+ *       return backdrop.replace('0.5', '0.8');
+ *     }
+ *     return backdrop;
+ *   }, [backdrop, theme]);
+ *
+ *   return (
+ *     <div
+ *       className="modal-backdrop"
+ *       style={{ backgroundColor: adjustedBackdrop }}
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * @remarks
+ * - Supports all CSS color formats: hex, rgb, rgba, hsl, etc.
+ * - Default backdrop is typically semi-transparent black
+ * - Can be overridden at provider level or per-modal
+ */
 export declare const useConfigurationBackdrop: () => import("../../@aileron/declare").Color;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lerx/promise-modal",
-  "version": "0.2.8",
+  "version": "0.3.0",
   "description": "Universal React modal utility that can be used outside React components with promise-based results for alert, confirm, and prompt modals",
   "keywords": [
     "react",
@@ -51,23 +51,23 @@
     "build-storybook": "storybook build",
     "build:publish:npm": "yarn build && yarn publish:npm",
     "build:types": "tsc -p ./tsconfig.declarations.json && tsc-alias -p ./tsconfig.declarations.json",
-    "format": "prettier --write \"src/**/*.ts\" \"src/**/*.tsx\"",
+    "format": "prettier --write \"src/**/*.{ts,tsx}\"",
     "lint": "eslint \"src/**/*.{ts,tsx}\"",
     "make-dependency-graph": "npx depcruise src --config .dependency-cruiser.js --output-type dot > dependency-graph.dot && dot -Tpng dependency-graph.dot -o dependency-graph.png",
     "publish:npm": "yarn npm publish --access public",
     "size-limit": "size-limit",
     "start": "yarn build && yarn storybook",
     "storybook": "storybook dev -p 6006",
-    "storybook:upgrade": "npx storybook@latest upgrade",
+    "storybook:upgrade": "npx storybook@latest upgrade --yes",
     "test": "yarn build:chain && vitest",
     "version:major": "yarn version major",
     "version:minor": "yarn version minor",
     "version:patch": "yarn version patch"
   },
   "dependencies": {
-    "@winglet/common-utils": "^0.2.2",
-    "@winglet/react-utils": "^0.2.6",
-    "@winglet/style-utils": "^0.2.2"
+    "@winglet/common-utils": "^0.3.0",
+    "@winglet/react-utils": "^0.3.0",
+    "@winglet/style-utils": "^0.3.0"
   },
   "devDependencies": {
     "@chromatic-com/storybook": "^4.0.1",
@@ -78,8 +78,8 @@
     "@size-limit/preset-app": "^11.1.6",
     "@size-limit/preset-big-lib": "^11.1.6",
     "@size-limit/preset-small-lib": "^11.1.6",
-    "@storybook/addon-docs": "^9.0.14",
-    "@storybook/react-vite": "^9.0.14",
+    "@storybook/addon-docs": "^9.0.18",
+    "@storybook/react-vite": "^9.0.18",
     "@testing-library/dom": "^10.4.0",
     "@testing-library/jest-dom": "^6.6.3",
     "@testing-library/react": "^16.1.0",
@@ -90,7 +90,6 @@
     "antd": "^5.22.5",
     "dependency-cruiser": "^16.7.0",
     "jsdom": "^25.0.1",
-    "prettier": "^3.5.3",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "rollup": "^4.42.0",
@@ -98,7 +97,7 @@
     "rollup-plugin-peer-deps-external": "^2.2.4",
     "rollup-plugin-visualizer": "^5.12.0",
     "size-limit": "^11.2.0",
-    "storybook": "^9.0.14",
+    "storybook": "^9.0.18",
     "tsc-alias": "^1.8.16",
     "typescript": "^5.7.2",
     "vite": "^6.3.5",