From 8f441a1b87bb2077a8db9c88f5a2bd4f5b0b969b Mon Sep 17 00:00:00 2001 From: Souradip Pal Date: Wed, 2 Apr 2025 07:04:00 +0000 Subject: [PATCH] Enhanced modal guidance documentation while maintaining consistency Signed-off-by: Souradip Pal --- .../Projects/Sistent/components/modal/code.js | 374 +++++++++++++++--- .../Sistent/components/modal/guidance.js | 165 ++++++-- .../Sistent/components/modal/index.js | 8 +- .../Projects/Sistent/sistent.style.js | 32 ++ 4 files changed, 475 insertions(+), 104 deletions(-) diff --git a/src/sections/Projects/Sistent/components/modal/code.js b/src/sections/Projects/Sistent/components/modal/code.js index 174e1c8b7e5d..df0471779d7a 100644 --- a/src/sections/Projects/Sistent/components/modal/code.js +++ b/src/sections/Projects/Sistent/components/modal/code.js @@ -19,7 +19,7 @@ import { useLocation } from "@reach/router"; import { navigate } from "gatsby"; import { useStyledDarkMode } from "../../../../../theme/app/useStyledDarkMode"; import { CodeBlock } from "../button/code-block"; -import { ActionBox } from "../../sistent.style"; +import { ActionBox, DocsTable, TableHead, TableBody } from "../../sistent.style"; const CustomInput = ({ label, text, style }) => ( @@ -36,48 +36,85 @@ const CustomInput = ({ label, text, style }) => ( ); +const importExample = `// Import the necessary components +import { + Button, + Modal, + ModalBody, + ModalFooter, + ModalButtonSecondary, + ModalButtonPrimary, + ModalButtonDanger +} from "@layer5/sistent"; + +// State to control modal visibility +const [isOpen, setIsOpen] = useState(false); + +// Handlers for opening/closing modal +const handleOpen = () => setIsOpen(true); +const handleClose = () => setIsOpen(false);`; + const codes = [ - ` - - -
- This action is irreversible! Are you sure you want to delete this team? -
- - - - Cancel - - - Delete - - - `, - ` - - - - - - - - - Cancel - - - Save - - - `, + ` + + + +
+ This action is irreversible! Are you sure you want to delete this team? +
+ + + + + Cancel + + + Delete + + + +`, + ` + + + + + + + + + + + Cancel + + + Save + + + +`, ]; const ModalCode = () => { @@ -123,7 +160,7 @@ const ModalCode = () => { onClick={() => navigate("/projects/sistent/components/modal")} title="Overview" /> - {/* { navigate("/projects/sistent/components/modal/guidance") } title="Guidance" - /> */} + /> navigate("/projects/sistent/identity/color/code")} + onClick={() => navigate("/projects/sistent/components/modal/code")} title="Code" />

- Buttons communicate actions to users and they can be placed at - several places throughout the user interface. + Modals provide a focused way to capture user attention for important + actions or information. They temporarily disable the main interface + until the user responds to the modal dialog.

- + + +

Getting Started

+ +

+ To use the Modal component in your application, start by importing the necessary components + and setting up the state to control the modal's visibility. +

+
+ +
+ + +

Modal Props

+ +
+
+ + + + Prop + Type + Default + Description + + + + + open + boolean + false + Controls the visibility of the modal + + + closeModal + function + required + Callback function triggered when the modal is closed + + + title + string + "" + Text displayed in the modal header + + + children + node + required + Content to be rendered inside the modal + + + disableBackdropClick + boolean + false + If true, clicking the backdrop will not close the modal + + + +
+
+ + +

ModalBody Props

+ +
+
+ + + + Prop + Type + Default + Description + + + + + children + node + required + Content to display in the modal body + + + sx + object + { } + Custom styles to apply to the modal body + + + +
+
+ + +

ModalFooter Props

+ +
+
+ + + + Prop + Type + Default + Description + + + + + variant + string + "outlined" + Footer style variant. Options: "outlined", "filled" + + + children + node + required + Content to display in the footer, typically action buttons + + + sx + object + { } + Custom styles to apply to the footer + + + +
+
+ + +

Modal Button Components

+ +
+
+ + + + Component + Description + + + + + ModalButtonPrimary + Primary action button, typically used for confirming actions + + + ModalButtonSecondary + Secondary action button, typically used for cancellation + + + ModalButtonDanger + Danger action button, used for destructive actions like delete + + + +
+
+ +

Confirmation Modal

 +

+ A confirmation modal is used to verify a user's action before proceeding, + especially for destructive or irreversible operations. +

- @@ -180,21 +391,24 @@ const ModalCode = () => {
-

Action Modal

+

Action Modal

- Action modals help users carry out specific tasks. These would - naturally involve more steps than just confirming or rejecting an - action. They may include forms, links, and feature specific - elements that ensure that users complete crucial tasks along their - given flow. They will usually have an icon at the top left corner - of the modal to signify what the purpose of this modal is in - relation to the given flow as well as help users familiarize with - said custom icons for easy identification across our solutions - however, this might not be applicable in all cases. + Action modals help users carry out specific tasks that require form input or + more complex interactions. These modals typically include form fields, dropdown menus, + or other interactive elements.

- + {
+ + +

Custom Styling

+ +

+ You can customize the appearance of your modals by using the sx prop or style prop on various components. + Here's an example of a custom styled modal: +

+
+ + + + This modal has custom styling applied to it. + + + + + + Cancel + + + Confirm + + + +`} /> +
@@ -228,4 +480,4 @@ const ModalCode = () => { ); }; -export default ModalCode; +export default ModalCode; \ No newline at end of file diff --git a/src/sections/Projects/Sistent/components/modal/guidance.js b/src/sections/Projects/Sistent/components/modal/guidance.js index fdb7e0bf197c..e262da32283a 100644 --- a/src/sections/Projects/Sistent/components/modal/guidance.js +++ b/src/sections/Projects/Sistent/components/modal/guidance.js @@ -1,53 +1,140 @@ import React from "react"; -import { SistentLayout } from "../../sistent-layout"; -import TabButton from "../../../../../reusecore/Button"; import { navigate } from "gatsby"; import { useLocation } from "@reach/router"; +import TabButton from "../../../../../reusecore/Button"; +import { SistentLayout } from "../../sistent-layout"; +import { useStyledDarkMode } from "../../../../../theme/app/useStyledDarkMode"; const ModalGuidance = () => { const location = useLocation(); + const { isDark } = useStyledDarkMode(); + return ( -
+
+ +

Modal

+

- A button is an interactive element that triggers a specific action, - takes users where they need to go, and points out what happens next in a - given flow. + A modal is a container that appears in front of the main content on a + page, providing important information or an actionable piece of + content for users to execute.

-
-
- navigate("/projects/sistent/components/modal")} - title="Overview" - /> - {/* - navigate("/projects/sistent/components/modal/guidance") - } - title="Guidance" - /> */} - navigate("/projects/sistent/identity/color/code")} - title="Code" - /> +
+ navigate("/projects/sistent/components/modal")} + title="Overview" + /> + + navigate("/projects/sistent/components/modal/guidance") + } + title="Guidance" + /> + navigate("/projects/sistent/components/modal/code")} + title="Code" + /> +
+
+

+ Modals provide a focused way to capture user attention for important + actions or information. They temporarily disable the main interface + until the user interacts with the modal. +

+ + +

When to Use Modals

+ +

+ Use modals strategically to avoid disrupting the user experience: +

+
    +
  • Use for important actions requiring immediate attention
    • +
  • Use for confirmations before critical actions
    • +
  • Use for collecting focused input
    • +
  • Avoid using for non-critical information that could be displayed inline
    • +
  • Avoid using for complex multi-step processes
    • +
  • Avoid multiple or nested modals
    • +
+ + +

Content Guidelines

+ +

+ Keep modal content focused and clear: +

+
    +
  • Use clear titles that describe what the modal is for
    • +
  • Keep content brief and directly related to the action
    • +
  • Use specific button labels (e.g., "Save" instead of "OK")
    • +
  • For confirmations, clearly state what will happen
    • +
  • Highlight the most important information
    • +
+ + +

Accessibility

+ +

+ Make modals accessible to all users: +

+
    +
  • Focus should move to the first interactive element when modal opens
    • +
  • Trap focus within the modal until it's closed
    • +
  • Return focus to the triggering element when modal closes
    • +
  • Support keyboard navigation including ESC key to close
    • +
  • Ensure good color contrast for all text
    • +
  • Use proper ARIA attributes (aria-modal, aria-labelledby, aria-describedby)
    • +
+ + +

Design Guidelines

+ +

+ Follow these design best practices: +

+
    +
  • Center the modal in the viewport
    • +
  • Use a semi-transparent overlay to focus attention on the modal
    • +
  • Include a clear close button (usually in the top-right corner)
    • +
  • For long content, make the modal body scrollable while keeping headers and footers fixed
    • +
  • Use consistent spacing and padding
    • +
  • Apply subtle animations for opening and closing
    • +
+ + +

Behavior

+ +

+ Ensure intuitive modal behavior: +

+
    +
  • Block interaction with the page behind the modal
    • +
  • Provide multiple ways to dismiss (close button, cancel button, ESC key, clicking overlay)
    • +
  • Validate form inputs before submission
    • +
  • Show confirmation for destructive actions
    • +
  • Display loading indicators for operations that take time
    • +
+
); }; -export default ModalGuidance; + +export default ModalGuidance; \ No newline at end of file diff --git a/src/sections/Projects/Sistent/components/modal/index.js b/src/sections/Projects/Sistent/components/modal/index.js index dd7b698b98b2..22af300c7af1 100644 --- a/src/sections/Projects/Sistent/components/modal/index.js +++ b/src/sections/Projects/Sistent/components/modal/index.js @@ -33,10 +33,10 @@ const SistentModal = () => { onClick={() => navigate("/projects/sistent/components/modal")} title="Overview" /> - {/* { navigate("/projects/sistent/components/modal/guidance") } title="Guidance" - /> */} + /> { ); }; -export default SistentModal; +export default SistentModal; \ No newline at end of file diff --git a/src/sections/Projects/Sistent/sistent.style.js b/src/sections/Projects/Sistent/sistent.style.js index c694d60eed33..e317d543a9e7 100644 --- a/src/sections/Projects/Sistent/sistent.style.js +++ b/src/sections/Projects/Sistent/sistent.style.js @@ -8,6 +8,28 @@ export const ActionBox = styled(Box)(() => ({ gap: "1rem" })); +// New styled components for documentation tables +export const DocsTable = styled.table` + width: 100%; + border-collapse: collapse; + margin-bottom: 20px; +`; + +export const TableHead = styled.thead` + th { + text-align: left; + padding: 8px 12px; + border-bottom: 2px solid #ddd; + } +`; + +export const TableBody = styled.tbody` + td { + padding: 8px 12px; + border-bottom: 1px solid #ddd; + } +`; + const SistentWrapper = styled.div` position: relative; .content > a:first-of-type > h2:first-of-type { @@ -628,6 +650,16 @@ const SistentWrapper = styled.div` padding-top: 1rem; } + /* Guidance list styling */ + .guidance-list { + padding-left: 30px; + } + + .guidance-list-item { + margin-bottom: 8px; + color: ${(props) => props.theme.text}; + } + .image-container { margin-top: 0.5rem; margin-bottom: 0.5rem;