@trackunit/react-modal 1.6.61 → 1.7.1

package/index.cjs.js

@@ -108,14 +108,33 @@ const ModalBackdrop = ({ children, onClick }) => {
  * - 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.
  *
- * - Modals should be used with the `useModal` hook.
- * - const modal = useModal();
- * - <Modal {...modal} />
+ * @example
+ * ```tsx
+ * const parentComponent = () => {
+ *  const modal = useModal();
+ *
+ *  return (
+ *   <ChildComponent {...modal} />
+ *  );
+ * };
+ *
+ * const childComponent = ({...modalProps}: UseModalReturnValue) => {
+ *  return (
+ *    <Modal {...modalProps}>
+ *      <CardHeader onClose={modalProps.close} heading="My Modal" />
+ *      <CardBody>
+ *        <p>This is a modal</p>
+ *      </CardBody>
+ *    </Modal>
+ *  );
+ * };
+ * ```
  */
-const Modal = ({ children, isOpen, role, dataTestId, className, containerClassName, onBackdropClick, floatingUi, ref, }) => {
+const Modal = ({ children, isOpen, role = "dialog", dataTestId, className, containerClassName, onBackdropClick, floatingUi, ref, }) => {
     const { rootElement, refs, floatingStyles, context, getFloatingProps } = floatingUi;
-    return (jsxRuntime.jsx(reactComponents.Portal, { root: rootElement, children: isOpen ? (jsxRuntime.jsx(react$1.FloatingFocusManager, { context: context, children: jsxRuntime.jsx("div", { ref: refs.setFloating, style: { ...floatingStyles, zIndex: uiDesignTokens.zIndex.overlay }, ...getFloatingProps(), children: jsxRuntime.jsx(ModalBackdrop, { onClick: onBackdropClick, children: jsxRuntime.jsx("div", { className: cvaModalContainer({ className: containerClassName }), ref: ref, role: role, children: jsxRuntime.jsx(reactComponents.Card, { className: cvaModalCard({ className }), dataTestId: dataTestId, children: children }) }) }) }) })) : null }));
+    return (jsxRuntime.jsx(reactComponents.Portal, { root: rootElement, children: isOpen ? (jsxRuntime.jsx(react$1.FloatingFocusManager, { context: context, children: jsxRuntime.jsx("div", { ref: refs.setFloating, style: { ...floatingStyles, zIndex: uiDesignTokens.zIndex.overlay }, ...getFloatingProps(), children: jsxRuntime.jsx(ModalBackdrop, { onClick: onBackdropClick, children: jsxRuntime.jsx("div", { "aria-modal": true, className: cvaModalContainer({ className: containerClassName }), ref: ref, role: role, children: jsxRuntime.jsx(reactComponents.Card, { className: cvaModalCard({ className }), dataTestId: dataTestId, children: children }) }) }) }) })) : null }));
 };
 Modal.displayName = "Modal";
 

package/index.esm.js

@@ -106,14 +106,33 @@ const ModalBackdrop = ({ children, onClick }) => {
  * - 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.
  *
- * - Modals should be used with the `useModal` hook.
- * - const modal = useModal();
- * - <Modal {...modal} />
+ * @example
+ * ```tsx
+ * const parentComponent = () => {
+ *  const modal = useModal();
+ *
+ *  return (
+ *   <ChildComponent {...modal} />
+ *  );
+ * };
+ *
+ * const childComponent = ({...modalProps}: UseModalReturnValue) => {
+ *  return (
+ *    <Modal {...modalProps}>
+ *      <CardHeader onClose={modalProps.close} heading="My Modal" />
+ *      <CardBody>
+ *        <p>This is a modal</p>
+ *      </CardBody>
+ *    </Modal>
+ *  );
+ * };
+ * ```
  */
-const Modal = ({ children, isOpen, role, dataTestId, className, containerClassName, onBackdropClick, floatingUi, ref, }) => {
+const Modal = ({ children, isOpen, role = "dialog", dataTestId, className, containerClassName, onBackdropClick, floatingUi, ref, }) => {
     const { rootElement, refs, floatingStyles, context, getFloatingProps } = floatingUi;
-    return (jsx(Portal, { root: rootElement, children: isOpen ? (jsx(FloatingFocusManager, { context: context, children: jsx("div", { ref: refs.setFloating, style: { ...floatingStyles, zIndex: zIndex.overlay }, ...getFloatingProps(), children: jsx(ModalBackdrop, { onClick: onBackdropClick, children: jsx("div", { className: cvaModalContainer({ className: containerClassName }), ref: ref, role: role, children: jsx(Card, { className: cvaModalCard({ className }), dataTestId: dataTestId, children: children }) }) }) }) })) : null }));
+    return (jsx(Portal, { root: rootElement, children: isOpen ? (jsx(FloatingFocusManager, { context: context, children: jsx("div", { ref: refs.setFloating, style: { ...floatingStyles, zIndex: zIndex.overlay }, ...getFloatingProps(), children: jsx(ModalBackdrop, { onClick: onBackdropClick, children: jsx("div", { "aria-modal": true, className: cvaModalContainer({ className: containerClassName }), ref: ref, role: role, children: jsx(Card, { className: cvaModalCard({ className }), dataTestId: dataTestId, children: children }) }) }) }) })) : null }));
 };
 Modal.displayName = "Modal";
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trackunit/react-modal",
-  "version": "1.6.61",
+  "version": "1.7.1",
   "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.8.15",
-    "@trackunit/react-core-hooks": "1.6.46",
-    "@trackunit/css-class-variance-utilities": "1.6.43",
-    "@trackunit/i18n-library-translation": "1.6.47",
-    "@trackunit/react-test-setup": "1.3.43",
+    "@trackunit/react-components": "1.8.18",
+    "@trackunit/react-core-hooks": "1.6.48",
+    "@trackunit/css-class-variance-utilities": "1.6.45",
+    "@trackunit/i18n-library-translation": "1.6.49",
+    "@trackunit/react-test-setup": "1.3.45",
     "@floating-ui/react": "^0.26.25",
     "@floating-ui/react-dom": "2.1.2",
-    "@trackunit/ui-design-tokens": "1.6.45"
+    "@trackunit/ui-design-tokens": "1.6.47"
   },
   "module": "./index.esm.js",
   "main": "./index.cjs.js",

package/src/modal/Modal.d.ts

@@ -1,19 +1,50 @@
-import { PropsWithChildren } from "react";
+import { AriaRole, PropsWithChildren } from "react";
 import { BaseUseModalActionArgs, UseModalReturnValue } from "./useModal";
 export type ModalProps<TOnCloseFnArgs extends BaseUseModalActionArgs = [], TOnOpenFnArgs extends BaseUseModalActionArgs = []> = {
-    role?: string;
+    /**
+     * The aria role for the modal.
+     */
+    role?: AriaRole;
+    /**
+     * The classes for the modal.
+     */
     className?: string;
+    /**
+     * The classes for the container of the modal.
+     */
     containerClassName?: string;
+    /**
+     * The test ID applied to the modal.
+     */
     dataTestId?: string;
 } & PropsWithChildren<UseModalReturnValue<TOnCloseFnArgs, TOnOpenFnArgs>>;
 /**
  * - 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.
  *
- * - Modals should be used with the `useModal` hook.
- * - const modal = useModal();
- * - <Modal {...modal} />
+ * @example
+ * ```tsx
+ * const parentComponent = () => {
+ *  const modal = useModal();
+ *
+ *  return (
+ *   <ChildComponent {...modal} />
+ *  );
+ * };
+ *
+ * const childComponent = ({...modalProps}: UseModalReturnValue) => {
+ *  return (
+ *    <Modal {...modalProps}>
+ *      <CardHeader onClose={modalProps.close} heading="My Modal" />
+ *      <CardBody>
+ *        <p>This is a modal</p>
+ *      </CardBody>
+ *    </Modal>
+ *  );
+ * };
+ * ```
  */
 export declare const Modal: {
     <TOnCloseFnArgs extends BaseUseModalActionArgs = [], TOnOpenFnArgs extends BaseUseModalActionArgs = []>({ children, isOpen, role, dataTestId, className, containerClassName, onBackdropClick, floatingUi, ref, }: ModalProps<TOnCloseFnArgs, TOnOpenFnArgs>): import("react/jsx-runtime").JSX.Element;

package/src/modal/Modal.stories.d.ts

@@ -1,15 +1,15 @@
 import { Meta, StoryObj } from "@storybook/react-webpack5";
 import { Modal } from "./Modal";
+import { UseModalReturnValue } from "./useModal";
 type Story = StoryObj<typeof Modal>;
 declare const meta: Meta<typeof Modal>;
 export default meta;
 export declare const packageName: () => import("react/jsx-runtime").JSX.Element;
-export declare const OverviewTemplate: () => import("react/jsx-runtime").JSX.Element;
+export declare const OverviewTemplate: ({ ...modalProps }: UseModalReturnValue) => import("react/jsx-runtime").JSX.Element;
 export declare const Default: Story;
 export declare const IncorrectUsageErrorModal: (closeOnOutsideClick: true) => import("react/jsx-runtime").JSX.Element;
 export declare const CorrectUsagePrimaryAction: (closeOnOutsideClick: true) => import("react/jsx-runtime").JSX.Element;
 export declare const IncorrectUsageLongText: (closeOnOutsideClick: true) => import("react/jsx-runtime").JSX.Element;
 export declare const CorrectUsageImportantAction: (closeOnOutsideClick: true) => import("react/jsx-runtime").JSX.Element;
-export declare const IncorrectAccessibility: (closeOnOutsideClick: false) => import("react/jsx-runtime").JSX.Element;
 export declare const CorrectAccessibility: (closeOnOutsideClick: true) => import("react/jsx-runtime").JSX.Element;
 export declare const CorrectStateManagement: () => import("react/jsx-runtime").JSX.Element;

package/src/modal/useModal.d.ts

@@ -24,13 +24,37 @@ type FloatingUiProps = {
     getFloatingProps: UseInteractionsReturn["getFloatingProps"];
 };
 export type UseModalReturnValue<TOnCloseFnArgs extends BaseUseModalActionArgs = [], TOnOpenFnArgs extends BaseUseModalActionArgs = []> = {
+    /**
+     * The ref for the modal.
+     */
     ref: Ref<HTMLDivElement>;
+    /**
+     * Whether the modal is open.
+     */
     isOpen: boolean;
+    /**
+     * Whether the modal should close when the user clicks outside of the modal.
+     */
     closeOnOutsideClick: boolean;
+    /**
+     * The callback function to call when the user clicks outside of the modal.
+     */
     onBackdropClick: () => void;
+    /**
+     * A function to call for opening the modal.
+     */
     open: OnOpenFn<TOnOpenFnArgs>;
+    /**
+     * A function to call for toggling the modal visibility.
+     */
     toggle: (...args: TOnOpenFnArgs | TOnCloseFnArgs) => void;
+    /**
+     * A function to call for closing the modal.
+     */
     close: OnCloseFn<TOnCloseFnArgs>;
+    /**
+     * The floating UI properties for the modal.
+     */
     floatingUi: FloatingUiProps;
 };
 /**