@ceed/ads 1.22.0 → 1.23.1

package/dist/components/feedback/Modal.md

@@ -41,15 +41,7 @@ The Modal component is a dialog overlay that appears on top of the main content,
 ## Usage
 
 ```tsx
-import {
-  Modal,
-  ModalDialog,
-  ModalClose,
-  DialogTitle,
-  DialogContent,
-  DialogActions,
-  Button,
-} from '@ceed/ads';
+import { Modal, ModalDialog, ModalClose, DialogTitle, DialogContent, DialogActions, Button } from '@ceed/ads';
 
 function MyComponent() {
   const [open, setOpen] = useState(false);
@@ -61,9 +53,7 @@ function MyComponent() {
         <ModalDialog>
           <ModalClose />
           <DialogTitle>Modal Title</DialogTitle>
-          <DialogContent>
-            Place your content here.
-          </DialogContent>
+          <DialogContent>Place your content here.</DialogContent>
           <DialogActions>
             <Button onClick={() => setOpen(false)}>Close</Button>
           </DialogActions>
@@ -74,6 +64,28 @@ function MyComponent() {
 }
 ```
 
+### ModalFrame Usage
+
+`ModalFrame` is a convenience component that combines `ModalDialog` + `ModalClose` + `DialogTitle` + `DialogContent` into a single composable unit.
+It provides a concise way to build modals with a title, close button, and content area.
+
+```tsx
+import { Modal, ModalFrame } from '@ceed/ads';
+
+function DetailModal({ open, onClose }) {
+  return (
+    <Modal open={open} onClose={onClose}>
+      <ModalFrame title="Detail" onClose={onClose}>
+        Content goes here.
+      </ModalFrame>
+    </Modal>
+  );
+}
+```
+
+> **Note**: Connect the same handler to both `Modal`'s `onClose` and `ModalFrame`'s `onClose`.
+> `Modal` handles backdrop click and ESC key, while `ModalFrame` handles the X button click.
+
 ## Examples
 
 ### Basic Modal
@@ -292,6 +304,162 @@ Modals can be stacked on top of each other when necessary.
 </>
 ```
 
+### ModalFrame
+
+ModalFrame is a convenience component that automatically provides a title, close button, and content area.
+
+#### ModalFrame Playground
+
+```tsx
+<>
+  <Button onClick={() => setOpen(true)}>Open ModalFrame</Button>
+  <Modal open={open} onClose={() => setOpen(false)}>
+    <ModalFrame title="ModalFrame Title" onClose={() => setOpen(false)}>
+      <Typography>
+        ModalFrame automatically composes ModalDialog, ModalClose, DialogTitle, and DialogContent. You only need
+        to provide a title, onClose handler, and children.
+      </Typography>
+    </ModalFrame>
+  </Modal>
+</>
+```
+
+#### titleStartDecorator
+
+Display an icon or decorative element before the title.
+
+```tsx
+<>
+  <Button onClick={() => setOpen(true)}>With Decorator</Button>
+  <Modal open={open} onClose={() => setOpen(false)}>
+    <ModalFrame title="Details" titleStartDecorator={<InfoOutlinedIcon />} onClose={() => setOpen(false)}>
+      <Typography>
+        Use the <code>titleStartDecorator</code> prop to display an icon or element before the title.
+      </Typography>
+    </ModalFrame>
+  </Modal>
+</>
+```
+
+#### Form Content
+
+An inline form pattern where the submit button lives inside the content area.
+
+```tsx
+<>
+  <Button onClick={() => setOpen(true)}>Form in ModalFrame</Button>
+  <Modal open={open} onClose={() => setOpen(false)}>
+    <ModalFrame title="Create Project" onClose={() => setOpen(false)}>
+      <form onSubmit={(event: React.FormEvent<HTMLFormElement>) => {
+        event.preventDefault();
+        setOpen(false);
+      }}>
+      <Stack spacing={2}>
+        <FormControl>
+          <FormLabel>Name</FormLabel>
+          <Input required />
+        </FormControl>
+        <FormControl>
+          <FormLabel>Description</FormLabel>
+          <Input required />
+        </FormControl>
+        <Button type="submit">Submit</Button>
+      </Stack>
+    </form>
+  </ModalFrame>
+</Modal>
+</>
+```
+
+#### Sizes
+
+Compare sm / md / lg sizes side by side.
+
+```tsx
+<Stack direction="row" spacing={2}>
+  <Button size="sm" onClick={() => setOpenSm(true)}>
+    Small
+  </Button>
+  <Button size="md" onClick={() => setOpenMd(true)}>
+    Medium
+  </Button>
+  <Button size="lg" onClick={() => setOpenLg(true)}>
+    Large
+  </Button>
+  <Modal open={openSm} onClose={() => setOpenSm(false)}>
+    <ModalFrame title="Small ModalFrame" size="sm" onClose={() => setOpenSm(false)}>
+      <Typography>This is a small ModalFrame.</Typography>
+    </ModalFrame>
+  </Modal>
+  <Modal open={openMd} onClose={() => setOpenMd(false)}>
+    <ModalFrame title="Medium ModalFrame" size="md" onClose={() => setOpenMd(false)}>
+      <Typography>This is a medium ModalFrame.</Typography>
+    </ModalFrame>
+  </Modal>
+  <Modal open={openLg} onClose={() => setOpenLg(false)}>
+    <ModalFrame title="Large ModalFrame" size="lg" onClose={() => setOpenLg(false)}>
+      <Typography>This is a large ModalFrame.</Typography>
+    </ModalFrame>
+  </Modal>
+</Stack>
+```
+
+#### Custom Content
+
+A layout example suited for displaying detailed information.
+
+```tsx
+<>
+  <Button onClick={() => setOpen(true)}>Custom Content</Button>
+  <Modal open={open} onClose={() => setOpen(false)}>
+    <ModalFrame title="Order Details" onClose={() => setOpen(false)}>
+      <Stack spacing={2}>
+        <Box>
+          <Typography level="title-sm">Order ID</Typography>
+          <Typography level="body-sm">ORD-2024-00123</Typography>
+        </Box>
+        <Divider />
+        <Box>
+          <Typography level="title-sm">Customer</Typography>
+          <Typography level="body-sm">John Doe</Typography>
+        </Box>
+        <Divider />
+        <Box>
+          <Typography level="title-sm">Status</Typography>
+          <Typography level="body-sm" color="success">
+            Completed
+          </Typography>
+        </Box>
+      </Stack>
+    </ModalFrame>
+  </Modal>
+</>
+```
+
+#### Standalone
+
+ModalFrame can be used without a Modal wrapper for embedding dialog-style layouts directly within a page.
+
+> ⚠️ **Important** ⚠️
+>
+> When using ModalFrame without Modal, the parent container **must** provide explicit `width` and `height` values.
+> ModalFrame inherits its dimensions from `ModalDialog`, which normally receives sizing from the Modal overlay.
+> Without these constraints, the component will not render with correct dimensions.
+
+```tsx
+<Box sx={{
+  width: 480,
+  height: 300
+}}>
+<ModalFrame title="Standalone ModalFrame" onClose={() => console.log('close')}>
+  <Typography>
+    ModalFrame used without Modal. The parent container must provide
+    explicit width and height.
+  </Typography>
+</ModalFrame>
+</Box>
+```
+
 ## When to Use
 
 ### ✅ Good Use Cases
@@ -327,8 +495,7 @@ function DeleteConfirmation({ item, onDelete, onCancel }) {
         </DialogTitle>
         <Divider />
         <DialogContent>
-          This action cannot be undone. All data associated with this item
-          will be permanently removed.
+          This action cannot be undone. All data associated with this item will be permanently removed.
         </DialogContent>
         <DialogActions>
           <Button variant="solid" color="danger" onClick={onDelete}>
@@ -404,8 +571,7 @@ function TermsModal({ open, onAccept, onDecline }) {
         <DialogTitle>Terms of Service</DialogTitle>
         <DialogContent>
           <Typography level="body-sm">
-            Please read and accept the following terms and conditions before
-            proceeding...
+            Please read and accept the following terms and conditions before proceeding...
           </Typography>
           {/* Terms content */}
         </DialogContent>
@@ -433,11 +599,7 @@ function ImagePreviewModal({ image, open, onClose }) {
     <Modal open={open} onClose={onClose}>
       <ModalDialog layout="center" sx={{ p: 0, overflow: 'hidden' }}>
         <ModalClose sx={{ top: 8, right: 8, zIndex: 1 }} />
-        <img
-          src={image.src}
-          alt={image.alt}
-          style={{ maxWidth: '90vw', maxHeight: '90vh', objectFit: 'contain' }}
-        />
+        <img src={image.src} alt={image.alt} style={{ maxWidth: '90vw', maxHeight: '90vh', objectFit: 'contain' }} />
       </ModalDialog>
     </Modal>
   );
@@ -468,22 +630,69 @@ function LoadingModal({ open, message }) {
 Modal uses a composition pattern with multiple sub-components:
 
 ```tsx
-<Modal>                    {/* Overlay and backdrop */}
-  <ModalDialog>            {/* Dialog container */}
-    <ModalClose />         {/* Close button (optional) */}
-    <DialogTitle>          {/* Header */}
+<Modal>
+  {/* Overlay and backdrop */}
+  <ModalDialog>
+    {/* Dialog container */}
+    <ModalClose /> {/* Close button (optional) */}
+    <DialogTitle>
+      {/* Header */}
       Title
     </DialogTitle>
-    <DialogContent>        {/* Body */}
+    <DialogContent>
+      {/* Body */}
       Content goes here
     </DialogContent>
-    <DialogActions>        {/* Footer */}
+    <DialogActions>
+      {/* Footer */}
       <Button>Action</Button>
     </DialogActions>
   </ModalDialog>
 </Modal>
 ```
 
+## Component Roles
+
+| Component         | Role                                                            | When to Use                                                      |
+| ----------------- | --------------------------------------------------------------- | ---------------------------------------------------------------- |
+| **Modal**         | Overlay backdrop, open/close state management                   | Always required as the outermost wrapper                         |
+| **ModalDialog**   | Dialog container (variant/size/layout)                          | When you need direct control over layout                         |
+| **ModalClose**    | Close (X) button in the top-right corner                        | When users should be able to close via a button                  |
+| **ModalOverflow** | Scrollable area                                                 | When content exceeds the viewport                                |
+| **ModalFrame**    | Combines ModalDialog + ModalClose + DialogTitle + DialogContent | When you only need a title + close + content (no action buttons) |
+| **DialogTitle**   | Header area (styled padding)                                    | When composing manually                                          |
+| **DialogContent** | Body area (styled padding)                                      | When composing manually                                          |
+| **DialogActions** | Footer action button area                                       | When confirm/cancel buttons are needed                           |
+
+## Choosing the Right Component
+
+### ModalFrame vs DialogFrame
+
+|                    | ModalFrame                                      | DialogFrame                             |
+| ------------------ | ----------------------------------------------- | --------------------------------------- |
+| Close (X) button   | Built-in                                        | None                                    |
+| Title decorator    | `titleStartDecorator`                           | None                                    |
+| Action button area | None                                            | `actions` prop (required)               |
+| Fullscreen         | `layout="fullscreen"`                           | `fullscreen` prop                       |
+| Best for           | Information display, detail views, inline forms | Confirm/cancel dialogs, decision-making |
+
+### Use ModalFrame when
+
+- You need an informational modal with a close button (detail views, previews)
+- The form's submit button lives inside the content area
+- You need an icon next to the title
+
+### Use DialogFrame when
+
+- Explicit action buttons (confirm/cancel) must be pinned to the bottom
+- User decisions are required (delete confirmation, save confirmation)
+- Only explicit choices should be allowed without a close (X) button
+
+### Use manual composition when
+
+- You need a custom layout that doesn't fit the ModalFrame/DialogFrame pattern
+- You want to use both ModalClose and DialogActions together
+
 ## Props and Customization
 
 ### Modal Props
@@ -505,6 +714,17 @@ Modal uses a composition pattern with multiple sub-components:
 | `size`    | `'sm' \| 'md' \| 'lg'`                                         | `'md'`       | Dialog size  |
 | `layout`  | `'center' \| 'fullscreen'`                                     | `'center'`   | Layout mode  |
 
+### ModalFrame Props
+
+| Prop                  | Type         | Default | Description                                |
+| --------------------- | ------------ | ------- | ------------------------------------------ |
+| `title`               | `ReactNode`  | -       | Title displayed in the header              |
+| `children`            | `ReactNode`  | -       | Body content                               |
+| `titleStartDecorator` | `ReactNode`  | -       | Icon or element displayed before the title |
+| `onClose`             | `() => void` | -       | Callback when the close button is clicked  |
+
+ModalFrame accepts all ModalDialog props (`variant`, `color`, `size`, `layout`, `sx`, etc.).
+
 ### Custom Styling
 
 ```tsx
@@ -543,17 +763,10 @@ Modal components include comprehensive accessibility features:
 - `aria-describedby` connects to DialogContent
 
 ```tsx
-<Modal
-  open={open}
-  onClose={onClose}
-  aria-labelledby="modal-title"
-  aria-describedby="modal-description"
->
+<Modal open={open} onClose={onClose} aria-labelledby="modal-title" aria-describedby="modal-description">
   <ModalDialog>
     <DialogTitle id="modal-title">Accessible Title</DialogTitle>
-    <DialogContent id="modal-description">
-      This content is read by screen readers.
-    </DialogContent>
+    <DialogContent id="modal-description">This content is read by screen readers.</DialogContent>
   </ModalDialog>
 </Modal>
 ```
@@ -582,7 +795,9 @@ Modal components include comprehensive accessibility features:
 ```tsx
 // ✅ Good: Clear action buttons
 <DialogActions>
-  <Button variant="solid" color="danger">Delete</Button>
+  <Button variant="solid" color="danger">
+    Delete
+  </Button>
   <Button variant="plain">Cancel</Button>
 </DialogActions>
 ```
@@ -657,15 +872,11 @@ Use `keepMounted` only when the modal needs to preserve state between openings:
 Memoize modal content when it depends on complex data:
 
 ```tsx
-const modalContent = useMemo(() => (
-  <ComplexContent data={data} />
-), [data]);
+const modalContent = useMemo(() => <ComplexContent data={data} />, [data]);
 
 <Modal open={open} onClose={onClose}>
-  <ModalDialog>
-    {modalContent}
-  </ModalDialog>
-</Modal>
+  <ModalDialog>{modalContent}</ModalDialog>
+</Modal>;
 ```
 
 Modal is a powerful component for focused user interactions. Use it thoughtfully to maintain a smooth user experience while capturing important decisions and inputs.