@trackunit/react-modal 1.14.27 → 1.14.29

package/index.cjs.js

@@ -505,31 +505,39 @@ const useModalStack = (isOpen) => {
 /** Scale factor per modal depth level (5% smaller per level back) */
 const SCALE_FACTOR_PER_LEVEL = 0.05;
 /**
- * - Modals are used to present critical information or request user input needed to complete a user's workflow.
- * - Modals interrupt a user's workflow by design.
- * - The modal component provides a foundation for creating dialogs, lightboxes, etc.
- * - Modals should always be used with the `useModal` hook.
+ * Modal presents critical information or requests user input in an overlay dialog that interrupts the current workflow.
+ * It renders inside a Portal with a backdrop overlay, focus trapping, and proper accessibility roles.
+ * Modals must always be used together with the `useModal` hook, which manages open/close state and Floating UI integration.
  *
- * @example
- * ```tsx
- * const parentComponent = () => {
- *  const modal = useModal();
+ * Compose the modal body with `ModalHeader`, `ModalBody`, and `ModalFooter` for consistent structure.
  *
- *  return (
- *   <ChildComponent {...modal} />
- *  );
- * };
+ * ### When to use
+ * Use Modal for confirmations, forms, or critical information that requires user attention before proceeding.
+ *
+ * ### When not to use
+ * Do not use Modal for non-blocking notifications — use `Notice` or `Alert`.
+ * Do not use Modal for simple tooltips or contextual info — use `Popover`.
  *
- * const ChildComponent = ({...modalProps}: UseModalReturnValue) => {
- *  return (* <Modal {...modalProps}>
- *      <ModalHeader onClickClose={modalProps.close} heading="My Modal" />
- *      <ModalBody>
- *        <p>This is a modal</p>
- *      </ModalBody>
- *      <ModalFooter onCancel={modalProps.close} primaryLabel="Cancel" />
- *    </Modal> *);
+ * @example Modal with header, body, and footer
+ * ```tsx
+ * import { Modal, ModalHeader, ModalBody, ModalFooter, useModal } from "@trackunit/react-modal";
+ *
+ * const ConfirmDialog = () => {
+ *   const modal = useModal();
+ *   return (
+ *     <>
+ *       <button onClick={modal.open}>Open</button>
+ *       <Modal {...modal} size="medium">
+ *         <ModalHeader onClickClose={modal.close} heading="Confirm Action" />
+ *         <ModalBody>Are you sure you want to proceed?</ModalBody>
+ *         <ModalFooter onCancel={modal.close} primaryLabel="Confirm" />
+ *       </Modal>
+ *     </>
+ *   );
  * };
  * ```
+ * @param {ModalProps} props - The props for the Modal component
+ * @returns {ReactElement} Modal component
  */
 const Modal = ({ children, isOpen, role = "dialog", "data-testid": dataTestId, className, size, floatingUi, ref, restoreFocus = true, }) => {
     // For dialogs/modals, Floating UI recommends not using floatingStyles since the modal

package/index.esm.js

@@ -503,31 +503,39 @@ const useModalStack = (isOpen) => {
 /** Scale factor per modal depth level (5% smaller per level back) */
 const SCALE_FACTOR_PER_LEVEL = 0.05;
 /**
- * - Modals are used to present critical information or request user input needed to complete a user's workflow.
- * - Modals interrupt a user's workflow by design.
- * - The modal component provides a foundation for creating dialogs, lightboxes, etc.
- * - Modals should always be used with the `useModal` hook.
+ * Modal presents critical information or requests user input in an overlay dialog that interrupts the current workflow.
+ * It renders inside a Portal with a backdrop overlay, focus trapping, and proper accessibility roles.
+ * Modals must always be used together with the `useModal` hook, which manages open/close state and Floating UI integration.
  *
- * @example
- * ```tsx
- * const parentComponent = () => {
- *  const modal = useModal();
+ * Compose the modal body with `ModalHeader`, `ModalBody`, and `ModalFooter` for consistent structure.
  *
- *  return (
- *   <ChildComponent {...modal} />
- *  );
- * };
+ * ### When to use
+ * Use Modal for confirmations, forms, or critical information that requires user attention before proceeding.
+ *
+ * ### When not to use
+ * Do not use Modal for non-blocking notifications — use `Notice` or `Alert`.
+ * Do not use Modal for simple tooltips or contextual info — use `Popover`.
  *
- * const ChildComponent = ({...modalProps}: UseModalReturnValue) => {
- *  return (* <Modal {...modalProps}>
- *      <ModalHeader onClickClose={modalProps.close} heading="My Modal" />
- *      <ModalBody>
- *        <p>This is a modal</p>
- *      </ModalBody>
- *      <ModalFooter onCancel={modalProps.close} primaryLabel="Cancel" />
- *    </Modal> *);
+ * @example Modal with header, body, and footer
+ * ```tsx
+ * import { Modal, ModalHeader, ModalBody, ModalFooter, useModal } from "@trackunit/react-modal";
+ *
+ * const ConfirmDialog = () => {
+ *   const modal = useModal();
+ *   return (
+ *     <>
+ *       <button onClick={modal.open}>Open</button>
+ *       <Modal {...modal} size="medium">
+ *         <ModalHeader onClickClose={modal.close} heading="Confirm Action" />
+ *         <ModalBody>Are you sure you want to proceed?</ModalBody>
+ *         <ModalFooter onCancel={modal.close} primaryLabel="Confirm" />
+ *       </Modal>
+ *     </>
+ *   );
  * };
  * ```
+ * @param {ModalProps} props - The props for the Modal component
+ * @returns {ReactElement} Modal component
  */
 const Modal = ({ children, isOpen, role = "dialog", "data-testid": dataTestId, className, size, floatingUi, ref, restoreFocus = true, }) => {
     // For dialogs/modals, Floating UI recommends not using floatingStyles since the modal

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trackunit/react-modal",
-  "version": "1.14.27",
+  "version": "1.14.29",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "engines": {
@@ -8,7 +8,7 @@
   },
   "dependencies": {
     "@floating-ui/react": "^0.26.25",
-    "@trackunit/react-components": "1.17.22",
+    "@trackunit/react-components": "1.17.24",
     "react": "19.0.0",
     "@trackunit/css-class-variance-utilities": "1.11.43",
     "@trackunit/shared-utils": "1.13.43",

package/src/modal/Modal.d.ts

@@ -26,31 +26,39 @@ export type ModalProps = PropsWithChildren<UseModalReturnValue & {
     restoreFocus?: boolean;
 }>;
 /**
- * - Modals are used to present critical information or request user input needed to complete a user's workflow.
- * - Modals interrupt a user's workflow by design.
- * - The modal component provides a foundation for creating dialogs, lightboxes, etc.
- * - Modals should always be used with the `useModal` hook.
+ * Modal presents critical information or requests user input in an overlay dialog that interrupts the current workflow.
+ * It renders inside a Portal with a backdrop overlay, focus trapping, and proper accessibility roles.
+ * Modals must always be used together with the `useModal` hook, which manages open/close state and Floating UI integration.
  *
- * @example
- * ```tsx
- * const parentComponent = () => {
- *  const modal = useModal();
+ * Compose the modal body with `ModalHeader`, `ModalBody`, and `ModalFooter` for consistent structure.
  *
- *  return (
- *   <ChildComponent {...modal} />
- *  );
- * };
+ * ### When to use
+ * Use Modal for confirmations, forms, or critical information that requires user attention before proceeding.
+ *
+ * ### When not to use
+ * Do not use Modal for non-blocking notifications — use `Notice` or `Alert`.
+ * Do not use Modal for simple tooltips or contextual info — use `Popover`.
+ *
+ * @example Modal with header, body, and footer
+ * ```tsx
+ * import { Modal, ModalHeader, ModalBody, ModalFooter, useModal } from "@trackunit/react-modal";
  *
- * const ChildComponent = ({...modalProps}: UseModalReturnValue) => {
- *  return (* <Modal {...modalProps}>
- *      <ModalHeader onClickClose={modalProps.close} heading="My Modal" />
- *      <ModalBody>
- *        <p>This is a modal</p>
- *      </ModalBody>
- *      <ModalFooter onCancel={modalProps.close} primaryLabel="Cancel" />
- *    </Modal> *);
+ * const ConfirmDialog = () => {
+ *   const modal = useModal();
+ *   return (
+ *     <>
+ *       <button onClick={modal.open}>Open</button>
+ *       <Modal {...modal} size="medium">
+ *         <ModalHeader onClickClose={modal.close} heading="Confirm Action" />
+ *         <ModalBody>Are you sure you want to proceed?</ModalBody>
+ *         <ModalFooter onCancel={modal.close} primaryLabel="Confirm" />
+ *       </Modal>
+ *     </>
+ *   );
  * };
  * ```
+ * @param {ModalProps} props - The props for the Modal component
+ * @returns {ReactElement} Modal component
  */
 export declare const Modal: {
     ({ children, isOpen, role, "data-testid": dataTestId, className, size, floatingUi, ref, restoreFocus, }: ModalProps): ReactElement;