@trackunit/react-modal 1.11.18 → 1.11.19

package/index.cjs.js

@@ -308,8 +308,36 @@ const cvaModalBodyContainer = cssClassVarianceUtilities.cvaMerge([
 /**
  * Modal body container.
  *
- * Renders children inside a scrollable flex container.
+ * Renders children inside a scrollable flex container. Use this component to wrap
+ * the main content of a modal, which automatically handles overflow scrolling.
  *
+ * @example Modal body with form content
+ * ```tsx
+ * import { Modal, ModalHeader, ModalBody, ModalFooter, useModal } from "@trackunit/react-modal";
+ * import { TextField } from "@trackunit/react-form-components";
+ *
+ * const EditAssetModal = () => {
+ *   const modal = useModal();
+ *
+ *   return (
+ *     <Modal {...modal} size="medium">
+ *       <ModalHeader heading="Edit Asset" onClose={modal.close} />
+ *       <ModalBody>
+ *         <div className="flex flex-col gap-4">
+ *           <TextField label="Asset Name" name="name" />
+ *           <TextField label="Serial Number" name="serial" />
+ *         </div>
+ *       </ModalBody>
+ *       <ModalFooter
+ *         cancelLabel="Cancel"
+ *         onCancel={modal.close}
+ *         primaryLabel="Save"
+ *         primaryAction={() => console.log("Save")}
+ *       />
+ *     </Modal>
+ *   );
+ * };
+ * ```
  * @param {ModalBodyProps} props Component props.
  * @param {ReactNode | null} props.children Content to render inside the modal body.
  * @param {string} [props."data-testid"] Optional test id for the container.
@@ -338,6 +366,55 @@ function isCustom(props) {
 /**
  * Modal footer with action buttons.
  *
+ * Provides a consistent footer layout with cancel, secondary, and primary action buttons.
+ * Supports loading states and automatic button disabling during async operations.
+ *
+ * @example Standard modal footer with actions
+ * ```tsx
+ * import { Modal, ModalHeader, ModalBody, ModalFooter, useModal } from "@trackunit/react-modal";
+ *
+ * const ConfirmModal = () => {
+ *   const modal = useModal();
+ *   const [isLoading, setIsLoading] = useState(false);
+ *
+ *   return (
+ *     <Modal {...modal} size="small">
+ *       <ModalHeader heading="Confirm Delete" onClose={modal.close} />
+ *       <ModalBody>Are you sure you want to delete this asset?</ModalBody>
+ *       <ModalFooter
+ *         cancelLabel="Cancel"
+ *         onCancel={modal.close}
+ *         primaryLabel="Delete"
+ *         primaryVariant="primary-danger"
+ *         primaryLoading={isLoading}
+ *         primaryAction={() => {
+ *           setIsLoading(true);
+ *           // handle delete
+ *         }}
+ *       />
+ *     </Modal>
+ *   );
+ * };
+ * ```
+ * @example Custom footer with children
+ * ```tsx
+ * import { Modal, ModalFooter, useModal } from "@trackunit/react-modal";
+ * import { Button } from "@trackunit/react-components";
+ *
+ * const CustomFooterModal = () => {
+ *   const modal = useModal();
+ *
+ *   return (
+ *     <Modal {...modal} size="medium">
+ *       <ModalFooter>
+ *         <Button variant="ghost-neutral" onClick={modal.close}>Skip</Button>
+ *         <Button variant="secondary">Save Draft</Button>
+ *         <Button variant="primary">Publish</Button>
+ *       </ModalFooter>
+ *     </Modal>
+ *   );
+ * };
+ * ```
  * @param props Component props.
  * @param props.cancelLabel Text for the Cancel button.
  * @param props.onCancel Optional handler invoked when the Cancel button is clicked (alias to onClose, if provided).
@@ -369,6 +446,46 @@ const cvaIconContainer = cssClassVarianceUtilities.cvaMerge(["flex", "place-item
  * Modal header section.
  * Displays a main heading, optional subheading, and a close button.
  *
+ * Use inside a Modal component to provide consistent header styling with a title, subtitle, and close button.
+ *
+ * @example Basic modal header
+ * ```tsx
+ * import { Modal, ModalHeader, ModalBody, useModal } from "@trackunit/react-modal";
+ *
+ * const MyModal = () => {
+ *   const modal = useModal();
+ *
+ *   return (
+ *     <Modal {...modal} size="medium">
+ *       <ModalHeader
+ *         heading="Confirm Action"
+ *         subHeading="Please review the details below"
+ *         onClose={modal.close}
+ *       />
+ *       <ModalBody>Modal content here</ModalBody>
+ *     </Modal>
+ *   );
+ * };
+ * ```
+ * @example Modal header with accessories
+ * ```tsx
+ * import { Modal, ModalHeader, useModal } from "@trackunit/react-modal";
+ * import { Tag } from "@trackunit/react-components";
+ *
+ * const StatusModal = () => {
+ *   const modal = useModal();
+ *
+ *   return (
+ *     <Modal {...modal} size="medium">
+ *       <ModalHeader
+ *         heading="Asset Details"
+ *         onClose={modal.close}
+ *         accessories={<Tag color="success">Active</Tag>}
+ *       />
+ *     </Modal>
+ *   );
+ * };
+ * ```
  * @param {ModalHeaderProps} props Component props.
  * @param {string} [props.heading] Main heading text.
  * @param {string} [props.subHeading] Optional subheading content.

package/index.esm.js

@@ -1,6 +1,6 @@
 import { jsx, jsxs } from 'react/jsx-runtime';
 import { registerTranslations } from '@trackunit/i18n-library-translation';
-import { FloatingFocusManager, useFloating, autoUpdate, shift, useDismiss, useInteractions } from '@floating-ui/react';
+import { FloatingFocusManager, useFloating, shift, autoUpdate, useDismiss, useInteractions } from '@floating-ui/react';
 import { Portal, Card, Button, Heading, Text, IconButton, Icon, useScrollBlock } from '@trackunit/react-components';
 import { zIndex } from '@trackunit/ui-design-tokens';
 import { useRef, useLayoutEffect, forwardRef, useState, useContext, useEffect, useCallback, useMemo } from 'react';
@@ -306,8 +306,36 @@ const cvaModalBodyContainer = cvaMerge([
 /**
  * Modal body container.
  *
- * Renders children inside a scrollable flex container.
+ * Renders children inside a scrollable flex container. Use this component to wrap
+ * the main content of a modal, which automatically handles overflow scrolling.
  *
+ * @example Modal body with form content
+ * ```tsx
+ * import { Modal, ModalHeader, ModalBody, ModalFooter, useModal } from "@trackunit/react-modal";
+ * import { TextField } from "@trackunit/react-form-components";
+ *
+ * const EditAssetModal = () => {
+ *   const modal = useModal();
+ *
+ *   return (
+ *     <Modal {...modal} size="medium">
+ *       <ModalHeader heading="Edit Asset" onClose={modal.close} />
+ *       <ModalBody>
+ *         <div className="flex flex-col gap-4">
+ *           <TextField label="Asset Name" name="name" />
+ *           <TextField label="Serial Number" name="serial" />
+ *         </div>
+ *       </ModalBody>
+ *       <ModalFooter
+ *         cancelLabel="Cancel"
+ *         onCancel={modal.close}
+ *         primaryLabel="Save"
+ *         primaryAction={() => console.log("Save")}
+ *       />
+ *     </Modal>
+ *   );
+ * };
+ * ```
  * @param {ModalBodyProps} props Component props.
  * @param {ReactNode | null} props.children Content to render inside the modal body.
  * @param {string} [props."data-testid"] Optional test id for the container.
@@ -336,6 +364,55 @@ function isCustom(props) {
 /**
  * Modal footer with action buttons.
  *
+ * Provides a consistent footer layout with cancel, secondary, and primary action buttons.
+ * Supports loading states and automatic button disabling during async operations.
+ *
+ * @example Standard modal footer with actions
+ * ```tsx
+ * import { Modal, ModalHeader, ModalBody, ModalFooter, useModal } from "@trackunit/react-modal";
+ *
+ * const ConfirmModal = () => {
+ *   const modal = useModal();
+ *   const [isLoading, setIsLoading] = useState(false);
+ *
+ *   return (
+ *     <Modal {...modal} size="small">
+ *       <ModalHeader heading="Confirm Delete" onClose={modal.close} />
+ *       <ModalBody>Are you sure you want to delete this asset?</ModalBody>
+ *       <ModalFooter
+ *         cancelLabel="Cancel"
+ *         onCancel={modal.close}
+ *         primaryLabel="Delete"
+ *         primaryVariant="primary-danger"
+ *         primaryLoading={isLoading}
+ *         primaryAction={() => {
+ *           setIsLoading(true);
+ *           // handle delete
+ *         }}
+ *       />
+ *     </Modal>
+ *   );
+ * };
+ * ```
+ * @example Custom footer with children
+ * ```tsx
+ * import { Modal, ModalFooter, useModal } from "@trackunit/react-modal";
+ * import { Button } from "@trackunit/react-components";
+ *
+ * const CustomFooterModal = () => {
+ *   const modal = useModal();
+ *
+ *   return (
+ *     <Modal {...modal} size="medium">
+ *       <ModalFooter>
+ *         <Button variant="ghost-neutral" onClick={modal.close}>Skip</Button>
+ *         <Button variant="secondary">Save Draft</Button>
+ *         <Button variant="primary">Publish</Button>
+ *       </ModalFooter>
+ *     </Modal>
+ *   );
+ * };
+ * ```
  * @param props Component props.
  * @param props.cancelLabel Text for the Cancel button.
  * @param props.onCancel Optional handler invoked when the Cancel button is clicked (alias to onClose, if provided).
@@ -367,6 +444,46 @@ const cvaIconContainer = cvaMerge(["flex", "place-items-center"]);
  * Modal header section.
  * Displays a main heading, optional subheading, and a close button.
  *
+ * Use inside a Modal component to provide consistent header styling with a title, subtitle, and close button.
+ *
+ * @example Basic modal header
+ * ```tsx
+ * import { Modal, ModalHeader, ModalBody, useModal } from "@trackunit/react-modal";
+ *
+ * const MyModal = () => {
+ *   const modal = useModal();
+ *
+ *   return (
+ *     <Modal {...modal} size="medium">
+ *       <ModalHeader
+ *         heading="Confirm Action"
+ *         subHeading="Please review the details below"
+ *         onClose={modal.close}
+ *       />
+ *       <ModalBody>Modal content here</ModalBody>
+ *     </Modal>
+ *   );
+ * };
+ * ```
+ * @example Modal header with accessories
+ * ```tsx
+ * import { Modal, ModalHeader, useModal } from "@trackunit/react-modal";
+ * import { Tag } from "@trackunit/react-components";
+ *
+ * const StatusModal = () => {
+ *   const modal = useModal();
+ *
+ *   return (
+ *     <Modal {...modal} size="medium">
+ *       <ModalHeader
+ *         heading="Asset Details"
+ *         onClose={modal.close}
+ *         accessories={<Tag color="success">Active</Tag>}
+ *       />
+ *     </Modal>
+ *   );
+ * };
+ * ```
  * @param {ModalHeaderProps} props Component props.
  * @param {string} [props.heading] Main heading text.
  * @param {string} [props.subHeading] Optional subheading content.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trackunit/react-modal",
-  "version": "1.11.18",
+  "version": "1.11.19",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "engines": {
@@ -8,14 +8,14 @@
   },
   "dependencies": {
     "react": "19.0.0",
-    "@trackunit/react-components": "1.14.18",
-    "@trackunit/css-class-variance-utilities": "1.10.15",
-    "@trackunit/i18n-library-translation": "1.10.15",
+    "@trackunit/react-components": "1.14.19",
+    "@trackunit/css-class-variance-utilities": "1.10.16",
+    "@trackunit/i18n-library-translation": "1.10.16",
     "@floating-ui/react": "^0.26.25",
     "@floating-ui/react-dom": "2.1.2",
-    "@trackunit/ui-design-tokens": "1.10.15",
-    "@trackunit/react-core-contexts-api": "1.11.15",
-    "@trackunit/shared-utils": "1.12.15"
+    "@trackunit/ui-design-tokens": "1.10.16",
+    "@trackunit/react-core-contexts-api": "1.11.16",
+    "@trackunit/shared-utils": "1.12.16"
   },
   "module": "./index.esm.js",
   "main": "./index.cjs.js",

package/src/modal/ModalBody/ModalBody.d.ts

@@ -15,8 +15,36 @@ export interface ModalBodyProps extends CommonProps {
 /**
  * Modal body container.
  *
- * Renders children inside a scrollable flex container.
+ * Renders children inside a scrollable flex container. Use this component to wrap
+ * the main content of a modal, which automatically handles overflow scrolling.
  *
+ * @example Modal body with form content
+ * ```tsx
+ * import { Modal, ModalHeader, ModalBody, ModalFooter, useModal } from "@trackunit/react-modal";
+ * import { TextField } from "@trackunit/react-form-components";
+ *
+ * const EditAssetModal = () => {
+ *   const modal = useModal();
+ *
+ *   return (
+ *     <Modal {...modal} size="medium">
+ *       <ModalHeader heading="Edit Asset" onClose={modal.close} />
+ *       <ModalBody>
+ *         <div className="flex flex-col gap-4">
+ *           <TextField label="Asset Name" name="name" />
+ *           <TextField label="Serial Number" name="serial" />
+ *         </div>
+ *       </ModalBody>
+ *       <ModalFooter
+ *         cancelLabel="Cancel"
+ *         onCancel={modal.close}
+ *         primaryLabel="Save"
+ *         primaryAction={() => console.log("Save")}
+ *       />
+ *     </Modal>
+ *   );
+ * };
+ * ```
  * @param {ModalBodyProps} props Component props.
  * @param {ReactNode | null} props.children Content to render inside the modal body.
  * @param {string} [props."data-testid"] Optional test id for the container.

package/src/modal/ModalFooter/ModalFooter.d.ts

@@ -89,6 +89,55 @@ export type ModalFooterProps = ModalFooterBuiltInProps | ModalFooterCustomProps;
 /**
  * Modal footer with action buttons.
  *
+ * Provides a consistent footer layout with cancel, secondary, and primary action buttons.
+ * Supports loading states and automatic button disabling during async operations.
+ *
+ * @example Standard modal footer with actions
+ * ```tsx
+ * import { Modal, ModalHeader, ModalBody, ModalFooter, useModal } from "@trackunit/react-modal";
+ *
+ * const ConfirmModal = () => {
+ *   const modal = useModal();
+ *   const [isLoading, setIsLoading] = useState(false);
+ *
+ *   return (
+ *     <Modal {...modal} size="small">
+ *       <ModalHeader heading="Confirm Delete" onClose={modal.close} />
+ *       <ModalBody>Are you sure you want to delete this asset?</ModalBody>
+ *       <ModalFooter
+ *         cancelLabel="Cancel"
+ *         onCancel={modal.close}
+ *         primaryLabel="Delete"
+ *         primaryVariant="primary-danger"
+ *         primaryLoading={isLoading}
+ *         primaryAction={() => {
+ *           setIsLoading(true);
+ *           // handle delete
+ *         }}
+ *       />
+ *     </Modal>
+ *   );
+ * };
+ * ```
+ * @example Custom footer with children
+ * ```tsx
+ * import { Modal, ModalFooter, useModal } from "@trackunit/react-modal";
+ * import { Button } from "@trackunit/react-components";
+ *
+ * const CustomFooterModal = () => {
+ *   const modal = useModal();
+ *
+ *   return (
+ *     <Modal {...modal} size="medium">
+ *       <ModalFooter>
+ *         <Button variant="ghost-neutral" onClick={modal.close}>Skip</Button>
+ *         <Button variant="secondary">Save Draft</Button>
+ *         <Button variant="primary">Publish</Button>
+ *       </ModalFooter>
+ *     </Modal>
+ *   );
+ * };
+ * ```
  * @param props Component props.
  * @param props.cancelLabel Text for the Cancel button.
  * @param props.onCancel Optional handler invoked when the Cancel button is clicked (alias to onClose, if provided).

package/src/modal/ModalHeader/ModalHeader.d.ts

@@ -31,6 +31,46 @@ export interface ModalHeaderProps extends CommonProps {
  * Modal header section.
  * Displays a main heading, optional subheading, and a close button.
  *
+ * Use inside a Modal component to provide consistent header styling with a title, subtitle, and close button.
+ *
+ * @example Basic modal header
+ * ```tsx
+ * import { Modal, ModalHeader, ModalBody, useModal } from "@trackunit/react-modal";
+ *
+ * const MyModal = () => {
+ *   const modal = useModal();
+ *
+ *   return (
+ *     <Modal {...modal} size="medium">
+ *       <ModalHeader
+ *         heading="Confirm Action"
+ *         subHeading="Please review the details below"
+ *         onClose={modal.close}
+ *       />
+ *       <ModalBody>Modal content here</ModalBody>
+ *     </Modal>
+ *   );
+ * };
+ * ```
+ * @example Modal header with accessories
+ * ```tsx
+ * import { Modal, ModalHeader, useModal } from "@trackunit/react-modal";
+ * import { Tag } from "@trackunit/react-components";
+ *
+ * const StatusModal = () => {
+ *   const modal = useModal();
+ *
+ *   return (
+ *     <Modal {...modal} size="medium">
+ *       <ModalHeader
+ *         heading="Asset Details"
+ *         onClose={modal.close}
+ *         accessories={<Tag color="success">Active</Tag>}
+ *       />
+ *     </Modal>
+ *   );
+ * };
+ * ```
  * @param {ModalHeaderProps} props Component props.
  * @param {string} [props.heading] Main heading text.
  * @param {string} [props.subHeading] Optional subheading content.