@fpkit/acss 0.5.4 → 0.5.6

package/src/components/dialog/dialog-modal.tsx

@@ -0,0 +1,111 @@
+// Dialog.tsx
+import React from "react";
+import Dialog from "./dialog";
+import Button from "#components/buttons/button.jsx";
+
+/**
+ * Additional props for the DialogModal component, extending the props of the Dialog component.
+ *
+ * @property {string} [className] - Optional className for the dialog content wrapper.
+ * @property {string} [btnLabel] - Label for the button that opens the dialog.
+ * @property {() => void} [btnOnClick] - Callback function to be called when the button is clicked.
+ * @property {"sm" | "md" | "lg"} [btnSize] - Size of the button that opens the dialog.
+ */
+interface DialogModalProps extends React.ComponentProps<typeof Dialog> {
+  /** Optional className for the dialog content wrapper */
+  className?: string;
+  btnLabel?: string;
+  btnOnClick?: () => void;
+  btnSize?: "sm" | "md" | "lg";
+  btnProps?: React.ComponentProps<typeof Button>;
+}
+
+/**
+ * A modal dialog component that provides an accessible overlay with an optional trigger button.
+ * Extends the base Dialog component with additional button control functionality.
+ *
+ * @component
+ * @param {Object} props - Component props
+ * @param {boolean} [props.isAlertDialog] - Whether this is an alert dialog requiring user action
+ * @param {() => void} [props.onClose] - Callback when dialog is closed
+ * @param {string} [props.dialogTitle] - Title displayed in dialog header
+ * @param {string} [props.dialogLabel] - Accessible label for the dialog
+ * @param {string} [props.btnLabel="Open Dialog"] - Text label for the trigger button
+ * @param {"sm" | "md" | "lg"} [props.btnSize="md"] - Size of the trigger button
+ * @param {() => void} [props.btnOnClick] - Callback when trigger button is clicked
+ * @param {React.ReactNode} props.children - Content to display inside the dialog
+ * @param {() => void} [props.onConfirm] - Callback when confirm button is clicked (for alert dialogs)
+ * @param {string} [props.confirmLabel="Confirm"] - Text for the confirm button
+ * @param {string} [props.cancelLabel="Cancel"] - Text for the cancel button
+ * @param {string} [props.className] - Additional CSS class for the dialog wrapper
+ * @param {React.ComponentProps<typeof Button>} [props.btnProps] - Additional props for the trigger button
+ * @returns {JSX.Element} A dialog component with a trigger button
+ *
+ * @example
+ * ```jsx
+ * <DialogModal
+ *   dialogTitle="Confirm Action"
+ *   btnLabel="Open Modal"
+ *   btnSize="lg"
+ *   onClose={() => console.log('Dialog closed')}
+ * >
+ *   <p>Dialog content goes here</p>
+ * </DialogModal>
+ * ```
+ */
+
+export const DialogModal: React.FC<DialogModalProps> = ({
+  isAlertDialog,
+  onClose,
+  dialogTitle,
+  dialogLabel,
+  btnLabel = "Open Dialog",
+  btnSize = "sm",
+  btnOnClick,
+  children,
+  onConfirm,
+  confirmLabel = "Confirm",
+  cancelLabel = "Cancel",
+  className,
+  btnProps,
+}) => {
+  const [isOpen, setIsOpen] = React.useState(false);
+
+  const handleClose = () => {
+    setIsOpen(false);
+    onClose?.();
+  };
+  const handleButtonClick = () => {
+    setIsOpen(true);
+    btnOnClick?.();
+  };
+
+  const dialogBtnProps = {
+    type: "button" as "button" | "submit" | "reset",
+    onClick: handleButtonClick,
+    "data-btn": btnSize,
+    ...btnProps,
+  };
+
+  return (
+    <>
+      <Button {...dialogBtnProps}>{btnLabel}</Button>
+      <Dialog
+        showDialog={isOpen}
+        dialogTitle={dialogTitle}
+        onClose={handleClose}
+        title={dialogTitle}
+        dialogLabel={dialogLabel}
+        className={className}
+        isAlertDialog={isAlertDialog}
+        onConfirm={onConfirm}
+        confirmLabel={confirmLabel}
+        cancelLabel={cancelLabel}
+      >
+        {children}
+      </Dialog>
+    </>
+  );
+};
+export default DialogModal;
+DialogModal.displayName = "Dialog Modal";

package/src/components/dialog/dialog.scss

@@ -0,0 +1,76 @@
+:root {
+  --dialog-min-w: max(20rem, 80%);
+  --dialog-gap: 0.625rem;
+  --dialog-border-color: lightgray;
+  --dialog-border-width: thin;
+  --dialog-border-style: solid;
+  --dialog-border-radius: var(--border-radius);
+  --dialog-padding: 1.5rem;
+  --dialog-padding-inline: 1rem;
+  --dialog-close-color: gray;
+  --dialog-button-bg: transparent;
+  --dialog-button-border: transparent thin solid;
+  --dialog-button-hover-bg: whitesmoke;
+  --dialog-display: flex;
+  --dialog-flex-direction: column;
+}
+
+dialog {
+  width: var(--dialog-min-w);
+  min-width: var(--min-w);
+  gap: var(--dialog-gap);
+  border: var(--dialog-border-color) var(--dialog-border-width) solid;
+  border-radius: var(--dialog-border-radius);
+  padding: var(--dialog-padding);
+  padding-block-start: calc(var(--dialog-padding) - 0rem);
+
+  &[open] {
+    display: var(--dialog-display);
+    flex-direction: var(--dialog-flex-direction);
+    gap: var(--dialog-gap);
+  }
+  section {
+    width: 100%;
+    display: flex;
+    justify-content: start;
+    gap: var(--dialog-gap);
+    flex-direction: var(--dialog-flex-direction);
+    margin-block-start: 0;
+    --sect-y: 0;
+  }
+}
+
+.dialog-header {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  width: 100%;
+  min-width: 100%;
+  h3 {
+    margin-block-start: 0;
+    margin-block-end: 0;
+  }
+  .dialog-close {
+    margin-block-end: 0;
+  }
+  button[type="button"] {
+    background-color: var(--dialog-button-bg);
+    border: var(--dialog-button-border);
+    cursor: pointer;
+    &:hover,
+    &:focus {
+      border-color: var(--dialog-close-color);
+      background-color: var(--dialog-button-hover-bg);
+    }
+  }
+}
+
+.alert-dialog-actions,
+.dialog-footer {
+  display: flex;
+  flex-direction: row;
+  flex-wrap: wrap;
+  justify-content: var(--dialog-footer-justify, flex-end);
+  gap: var(--dialog-gap);
+  width: 100%;
+}

package/src/components/dialog/dialog.stories.tsx

@@ -0,0 +1,116 @@
+import { StoryObj, Meta, StoryFn } from "@storybook/react";
+import { within, expect, userEvent } from "@storybook/test";
+
+import Dialog from "./dialog";
+import React from "react";
+
+const content =
+  "This is a dialog component used to display modal dialogs. It can be used to show important information or prompt the user for input.";
+
+const buttonDecorator = [
+  (Story: StoryFn) => {
+    const [isOpen, setIsOpen] = React.useState(false);
+    return (
+      <div>
+        <button onClick={() => setIsOpen(true)}>Open Dialog</button>
+        <Story
+          args={{
+            showDialog: isOpen,
+            onClose: () => setIsOpen(false),
+            dialogTitle: "Dialog Button",
+            children: content,
+          }}
+        />
+        <section>{content}</section>
+      </div>
+    );
+  },
+];
+
+const meta: Meta<typeof Dialog> = {
+  title: "FP.REACT Components/Dialog/Dialogs",
+  component: Dialog,
+  tags: ["alpha"],
+  parameters: {
+    docs: {
+      description: {
+        component: "Dialog component for displaying modal dialogs.",
+      },
+    },
+  },
+  args: {
+    children: content,
+  },
+  decorators: [
+    (Story) => {
+      return (
+        <div
+          style={{
+            display: "flex",
+            justifyContent: "center",
+            alignItems: "center",
+            width: "500px",
+            marginInline: "20px",
+            marginBlockStart: "5rem",
+          }}
+        >
+          <Story />
+        </div>
+      );
+    },
+  ],
+} as Story;
+
+export default meta;
+type Story = StoryObj<typeof Dialog>;
+
+export const BasicDialog: Story = {
+  args: {
+    isAlertDialog: false,
+    showDialog: true,
+    dialogTitle: "Basic Dialog",
+  },
+} as Story;
+
+/**
+ * Show the dialog by default
+ * set the showDialog prop to true
+ */
+export const NonModalDialog: Story = {
+  args: {
+    showDialog: true,
+    isAlertDialog: true,
+    dialogTitle: "Non Modal Dialog",
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(canvas.getByRole("alertdialog")).toBeInTheDocument();
+  },
+} as Story;
+
+export const DialogWithButton: Story = {
+  decorators: buttonDecorator,
+} as Story;
+
+export const DialogInteractions: Story = {
+  args: {
+    isAlertDialog: false,
+    showDialog: true,
+    dialogTitle: "Dialog Interactions",
+  },
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    const dialog = canvas.getByRole("dialog");
+    const closeButton = canvas.getByRole("button", { name: /close dialog/i });
+
+    await step("Modal is rendered", async () => {
+      await expect(dialog).toBeInTheDocument();
+      await expect(closeButton).toBeInTheDocument();
+    });
+
+    await step("Close modal", async () => {
+      await userEvent.click(closeButton, { delay: 1000 });
+      // await expect(dialog).not.toBeInTheDocument();
+    });
+  },
+} as Story;

package/src/components/dialog/dialog.tsx

@@ -0,0 +1,128 @@
+import React, { useRef, useEffect, CSSProperties } from "react";
+import UI from "#components/ui";
+import DialogHeader from "#components/dialog/views/dialog-header";
+import DialogFooter from "#components/dialog/views/dialog-footer";
+import { useDialogClickHandler } from "#hooks/useDialogClickHandler.js";
+
+/**
+ * Defines the props for the Dialog component.
+ *
+ * @property {boolean} [showDialog] - Determines whether the dialog should be shown.
+ * @property {boolean} [isAlertDialog] - Determines whether the dialog should be displayed as an alert dialog.
+ * @property {() => void} [onClose] - A callback function to be called when the dialog is closed.
+ * @property {string} dialogTitle - The title of the dialog.
+ * @property {string} [dialogLabel] - An optional label for the dialog.
+ * @property {React.ReactNode} children - The content to be displayed inside the dialog.
+ * @property {() => void | Promise<void>} [onConfirm] - A callback function to be called when the user confirms the dialog.
+ * @property {string} [confirmLabel] - The label for the confirm button.
+ * @property {string} [cancelLabel] - The label for the cancel button.
+ * @property {string} [className] - An optional CSS class name to be applied to the dialog.
+ * @property {CSSProperties} [styles] - Optional inline styles to be applied to the dialog.
+ */
+type DialogModalProps = React.ComponentProps<typeof UI> &
+  React.ComponentProps<"dialog"> & {
+    dialogTitle: string;
+    dialogLabel?: string;
+    children: React.ReactNode;
+    showDialog?: boolean;
+    isAlertDialog?: boolean;
+    onClose?: () => void;
+    onConfirm?: () => void | Promise<void>;
+    confirmLabel?: string;
+    cancelLabel?: string;
+    className?: string;
+    hideFooter?: boolean;
+    styles?: CSSProperties;
+  };
+
+/**
+ * Renders a dialog modal component with customizable content and behavior.
+ *
+ * @param showDialog - Determines whether the dialog should be shown.
+ * @param isAlertDialog - Determines whether the dialog should be displayed as an alert dialog.
+ * @param onClose - A callback function to be called when the dialog is closed.
+ * @param dialogTitle - The title of the dialog.
+ * @param dialogLabel - An optional label for the dialog.
+ * @param children - The content to be displayed inside the dialog.
+ * @param onConfirm - A callback function to be called when the user confirms the dialog.
+ * @param confirmLabel - The label for the confirm button.
+ * @param cancelLabel - The label for the cancel button.
+ * @param className - An optional CSS class name to be applied to the dialog.
+ * @param styles - Optional inline styles to be applied to the dialog.
+ */
+export const Dialog: React.FC<DialogModalProps> = ({
+  showDialog,
+  isAlertDialog,
+  onClose,
+  dialogTitle,
+  dialogLabel,
+  children,
+  onConfirm,
+  confirmLabel = "Confirm",
+  cancelLabel = "Cancel",
+  className = "",
+  hideFooter,
+  styles,
+}) => {
+  const dialogRef = useRef<HTMLDialogElement>(null);
+  const [isOpen, setIsOpen] = React.useState(showDialog);
+
+  useEffect(() => {
+    setIsOpen(showDialog);
+  }, [showDialog]);
+
+  useEffect(() => {
+    const dialog = dialogRef.current;
+    if (!dialog) return;
+
+    if (isOpen) {
+      if (isAlertDialog) {
+        dialog.show();
+      } else {
+        dialog.showModal();
+      }
+    } else {
+      dialog.close();
+    }
+  }, [isOpen, isAlertDialog]);
+
+  const handleClose = () => {
+    if (onClose) onClose();
+    setIsOpen(false);
+  };
+
+  const handleClickOutside = useDialogClickHandler(dialogRef, handleClose);
+
+  return (
+    <UI
+      as="dialog"
+      role={isAlertDialog ? "alertdialog" : "dialog"}
+      ref={dialogRef}
+      onClose={handleClose}
+      onClick={handleClickOutside}
+      aria-modal={isOpen ? "true" : undefined}
+      className={`${"dialog-modal"} ${className}`}
+      aria-label={dialogLabel}
+      style={styles}
+    >
+      <DialogHeader dialogTitle={dialogTitle} onClick={handleClose} />
+
+      <UI
+        as="section"
+        className={`dialog-content ${className}`}
+        onClick={(e: React.MouseEvent) => e.stopPropagation()}
+      >
+        {children}
+        {!hideFooter && (
+          <DialogFooter
+            onClose={handleClose}
+            onConfirm={onConfirm}
+            confirmLabel={confirmLabel}
+            cancelLabel={cancelLabel}
+          />
+        )}
+      </UI>
+    </UI>
+  );
+};
+export default React.memo(Dialog);

package/src/components/dialog/hooks/useClickOutside.ts

@@ -0,0 +1,33 @@
+// hooks/useClickOutside.ts
+import { RefObject } from "react";
+
+/**
+ * Hook that handles click outside detection for any HTML element
+ * @param ref Reference to the element to detect clicks outside of
+ * @param handler Function to call when a click outside is detected
+ * @returns Click event handler function
+ */
+const useClickOutside = (
+  ref: RefObject<HTMLElement>,
+  handler: () => void
+): ((e: React.MouseEvent<HTMLElement>) => void) => {
+  return (e: React.MouseEvent<HTMLElement>) => {
+    const dimensions = ref.current?.getBoundingClientRect();
+
+    if (!dimensions) {
+      return;
+    }
+
+    const isClickOutside =
+      e.clientY < dimensions.top ||
+      e.clientY > dimensions.bottom ||
+      e.clientX < dimensions.left ||
+      e.clientX > dimensions.right;
+
+    if (isClickOutside) {
+      handler();
+    }
+  };
+};
+
+export default useClickOutside;

package/src/components/dialog/views/README.mdx

@@ -0,0 +1,182 @@
+import { Meta } from "@storybook/blocks";
+
+<Meta title="FP.REACT Views/DialogHeader/Readme" />
+
+# Dialog
+
+## Summary
+
+A reusable dialog/modal component that includes a header, content area, and
+footer. The component provides customizable title, confirm, and cancel
+functionality.
+
+## Features
+
+- Customizable title, confirm, and cancel functionality
+- Built-in close button with icon
+- Fully accessible
+- Memoized for performance optimization
+
+## Props
+
+The `Dialog` component accepts the following props:
+
+- `isOpen: boolean`: Controls the visibility of the dialog
+- `onClose: () => void`: Callback function triggered when the dialog is closed
+- `title: string`: The title text to display in the header
+- `children: React.ReactNode`: The content to display inside the dialog
+- `onConfirm?: () => void | Promise<void>`: Optional callback function triggered
+  when the confirm button is clicked
+- `confirmLabel?: string`: Optional label text for the confirm button
+- `cancelLabel?: string`: Optional label text for the cancel button
+- `className?: string`: Optional className for the dialog content wrapper
+
+## Technical Details
+
+- Uses React.memo for performance optimization
+- Integrates with the UI component system
+- Implements accessible heading structure using the Heading component
+- Uses Icon.Remove for the close button visual
+- Includes data attributes for styling customization
+
+## Usage Example
+
+### Basic Usage
+
+```tsx
+import { Dialog } from "./dialog";
+
+function BasicDialog() {
+  const [isOpen, setIsOpen] = useState(false);
+
+  return (
+    <>
+      <button onClick={() => setIsOpen(true)}>Open Dialog</button>
+      <Dialog
+        isOpen={isOpen}
+        onClose={() => setIsOpen(false)}
+        title="Dialog Title"
+        confirmLabel="Confirm"
+        cancelLabel="Cancel"
+      >
+        <div>Dialog content here...</div>
+      </Dialog>
+    </>
+  );
+}
+```
+
+# DialogHeader
+
+## Summary
+
+A reusable header component specifically designed for dialog/modal interfaces.
+The component provides a clean, accessible header with a title and close button
+functionality.
+
+## Features
+
+- Clean, minimal header design
+- Built-in close button with icon
+- Customizable title using the Heading component
+- Memoized for performance optimization
+- Fully accessible
+
+## Props
+
+The `DialogHeader` component accepts the following props:
+
+- `dialogTitle: string`: The title text to display in the header
+- `onClick: () => void`: Callback function triggered when the close button is
+  clicked
+
+## Technical Details
+
+- Uses React.memo for performance optimization
+- Integrates with the UI component system
+- Implements accessible heading structure using the Heading component
+- Uses Icon.Remove for the close button visual
+- Includes data attributes for styling customization
+
+## Usage Example
+
+### Basic Usage
+
+```tsx
+import { DialogHeader } from "./dialog-header";
+
+function BasicDialog() {
+  return (
+    <DialogHeader
+      dialogTitle="Settings"
+      onClose={() => console.log("Dialog closed")}
+    />
+  );
+}
+
+// Example within a Dialog component
+import { Dialog } from "./dialog";
+import { DialogHeader } from "./dialog-header";
+
+function SettingsDialog() {
+  const [isOpen, setIsOpen] = useState(false);
+
+  return (
+    <Dialog isOpen={isOpen}>
+      <DialogHeader
+        dialogTitle="Application Settings"
+        onClose={() => setIsOpen(false)}
+      />
+      <div>Dialog content here...</div>
+    </Dialog>
+  );
+}
+```
+
+# DialogFooter
+
+## Summary
+
+A reusable footer component specifically designed for dialog/modal interfaces.
+The component provides customizable confirm and cancel buttons.
+
+## Features
+
+- Customizable confirm and cancel buttons
+- Optional confirm button handler
+- Fully accessible
+
+## Props
+
+The `DialogFooter` component accepts the following props:
+
+- `onClose: () => void`: Callback function triggered when the cancel button is
+  clicked
+- `onConfirm?: () => void | Promise<void>`: Optional callback function triggered
+  when the confirm button is clicked
+- `confirmLabel: string`: Label text for the confirm button
+- `cancelLabel: string`: Label text for the cancel button
+
+## Technical Details
+
+- Integrates with the UI component system
+- Includes data attributes for styling customization
+
+## Usage Example
+
+### Basic Usage
+
+```tsx
+import { DialogFooter } from "./dialog-footer";
+
+function BasicDialogFooter() {
+  return (
+    <DialogFooter
+      onClose={() => console.log("Dialog closed")}
+      onConfirm={() => console.log("Dialog confirmed")}
+      confirmLabel="Confirm"
+      cancelLabel="Cancel"
+    />
+  );
+}
+```

package/src/components/dialog/views/dialog-footer.tsx

@@ -0,0 +1,45 @@
+import React from "react";
+import UI from "#components/ui";
+import Button from "#components/buttons/button";
+
+type DialogFooterProps = {
+  onClose: () => void;
+  onConfirm?: () => void | Promise<void>;
+  confirmLabel: string;
+  cancelLabel: string;
+};
+
+const DialogFooter: React.FC<DialogFooterProps> = ({
+  onClose,
+  onConfirm,
+  confirmLabel,
+  cancelLabel,
+}) => {
+  return (
+    <UI as="section" className="dialog-footer">
+      {cancelLabel && (
+        <Button
+          type="button"
+          onClick={onClose}
+          className="dialog-button button-secondary"
+          data-btn="sm"
+        >
+          {cancelLabel}
+        </Button>
+      )}
+
+      {onConfirm && (
+        <Button
+          type="button"
+          onClick={onConfirm}
+          className="dialog-button button-primary"
+          data-btn="sm"
+        >
+          {confirmLabel}
+        </Button>
+      )}
+    </UI>
+  );
+};
+
+export default DialogFooter;