@royaloperahouse/chord 2.2.3-b-chord-development → 2.2.3-c-chord-development

package/dist/components/organisms/ModalWindow/ModalWindow.d.ts

@@ -1,4 +1,68 @@
 import { FunctionComponent } from 'react';
 import { ModalWindowProps } from '../../../types';
+/**
+ * A ModalWindow component, leveraging React Modal for rendering modals with enhanced accessibility
+ * and styling customization. This component is designed to be flexible for various use cases, with
+ * support for mobile responsiveness, custom z-indexes, and a close button.
+ *
+ * # Usage
+ * This component is intended to be used in React applications where modal functionality is required.
+ * It supports a range of props for customization, including isOpen, setIsOpen, children, appElementId,
+ * and accepts all additional props supported by React Modal for further configuration.
+ *
+ * ## Basic Example
+ * ```tsx
+ * import React, { useState } from 'react';
+ * import ModalWindow from './ModalWindow';
+ *
+ * const App = () => {
+ *   const [isOpen, setIsOpen] = useState(false);
+ *
+ *   const toggleModal = () => setIsOpen(!isOpen);
+ *
+ *   return (
+ *     <>
+ *       <button onClick={toggleModal}>Open Modal</button>
+ *       <ModalWindow
+ *         isOpen={isOpen}
+ *         setIsOpen={setIsOpen}
+ *         appElementId="root"
+ *       >
+ *         <div>Modal Content Here</div>
+ *       </ModalWindow>
+ *     </>
+ *   );
+ * }
+ * ```
+ *
+ * ## Advanced Usage
+ * You can further customize the modal by directly passing props supported by React Modal.
+ * This component adapts its z-index based on the device type (mobile or desktop) and allows for an
+ * accessible close functionality.
+ *
+ * ```tsx
+ * <ModalWindow
+ *   isOpen={isOpen}
+ *   setIsOpen={setIsOpen}
+ *   appElementId="root"
+ *   shouldCloseOnOverlayClick={true}
+ * >
+ *   <YourCustomComponent />
+ * </ModalWindow>
+ * ```
+ *
+ * # Props
+ * - `isOpen`: Boolean indicating if the modal is open.
+ * - `setIsOpen`: Function to set the open state of the modal.
+ * - `children`: Content to be displayed within the modal.
+ * - `appElementId`: ID of the app element to assist with accessibility.
+ * - All other props are passed directly to the underlying React Modal component, allowing for extensive customization.
+ *
+ * # Design and Accessibility
+ * This component automatically applies a `ScrollLock` when the modal is open to prevent background
+ * scrolling and sets appropriate z-index values to ensure the modal is layered correctly on the page.
+ * It also configures the modal for accessibility, including support for closing on ESC and setting
+ * `aria-modal` to true.
+ */
 declare const ModalWindow: FunctionComponent<ModalWindowProps>;
 export default ModalWindow;

package/dist/types/modalWindow.d.ts

@@ -1,8 +1,20 @@
-import React, { ReactElement } from 'react';
+import { ReactElement } from 'react';
 import Modal from 'react-modal';
 export interface ModalWindowProps extends Modal.Props {
+    /**
+     * Boolean indicating if the modal is open.
+     */
     isOpen: boolean;
-    setIsOpen: React.Dispatch<React.SetStateAction<boolean>>;
+    /**
+     * Function to set the open state of the modal.
+     */
+    setIsOpen: (isOpen: boolean) => void;
+    /**
+     * Content to be displayed within the modal.
+     */
     children: ReactElement;
+    /**
+     * ID of the app element to assist with accessibility.
+     */
     appElementId: string;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@royaloperahouse/chord",
-  "version": "2.2.3-b-chord-development",
+  "version": "2.2.3-c-chord-development",
   "author": "Royal Opera House",
   "license": "MIT",
   "main": "dist/index.js",