@ceed/ads 1.25.1-next.3 → 1.26.0

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,166 @@ 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** meet the following requirements:
+>
+> - `position: 'relative'` — ModalFrame uses absolute positioning internally
+> - Explicit `width` and `height` — `height` must be an absolute value (e.g., `300`, `'400px'`), not a relative value like `%` or `auto`
+>
+> 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={{
+  position: 'relative',
+  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 +499,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 +575,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 +603,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 +634,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 +718,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 +767,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 +799,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 +876,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.

package/dist/components/feedback/Skeleton.md

@@ -0,0 +1,280 @@
+# Skeleton
+
+## Introduction
+
+The Skeleton component provides placeholder previews of content before data is loaded. It is based on Joy UI's Skeleton and helps reduce perceived loading time by showing an approximation of the page layout. Skeletons improve the user experience by preventing layout shifts and giving users a visual cue that content is on its way.
+
+```tsx
+<Skeleton
+  variant="rectangular"
+  width={200}
+  height={24}
+/>
+```
+
+| Field                        | Description | Default |
+| ---------------------------- | ----------- | ------- |
+| Controls resolved at runtime | —           | —       |
+
+## Usage
+
+```tsx
+import { Skeleton } from '@ceed/ads';
+
+function MyComponent() {
+  return <Skeleton variant="rectangular" width={200} height={24} />;
+}
+```
+
+## Variants
+
+Skeleton supports three variants: `rectangular`, `circular`, and `text`.
+
+- **rectangular**: Block-shaped placeholder for images, cards, and content areas.
+- **circular**: Round placeholder for avatars and icons.
+- **text**: Matches the height and spacing of text content at a given `level`.
+
+```tsx
+<>
+  <Skeleton variant="rectangular" width={200} height={24} />
+  <Skeleton variant="circular" width={48} height={48} />
+  <Skeleton variant="text" width={200} />
+</>
+```
+
+```tsx
+<Skeleton variant="rectangular" width={200} height={24} />
+<Skeleton variant="circular" width={48} height={48} />
+<Skeleton variant="text" width={200} />
+```
+
+## Animations
+
+Skeleton supports `wave` (default) and `pulse` animations. Set `animation={false}` to disable animation entirely.
+
+```tsx
+<Stack gap={3}>
+  <Box>
+    <Typography level="body-sm" sx={{
+      mb: 1
+    }}>
+    Wave (default)
+  </Typography>
+  <Skeleton animation="wave" variant="rectangular" width={200} height={24} />
+</Box>
+<Box>
+  <Typography level="body-sm" sx={{
+    mb: 1
+  }}>
+  Pulse
+</Typography>
+<Skeleton animation="pulse" variant="rectangular" width={200} height={24} />
+</Box>
+<Box>
+  <Typography level="body-sm" sx={{
+    mb: 1
+  }}>
+  No animation (false)
+</Typography>
+<Skeleton animation={false} variant="rectangular" width={200} height={24} />
+</Box>
+</Stack>
+```
+
+```tsx
+<Skeleton animation="wave" variant="rectangular" width={200} height={24} />
+<Skeleton animation="pulse" variant="rectangular" width={200} height={24} />
+<Skeleton animation={false} variant="rectangular" width={200} height={24} />
+```
+
+## Text Skeleton
+
+Use `variant="text"` with the `level` prop to match Typography sizing. This is useful for creating text content placeholders that accurately reflect the final layout.
+
+```tsx
+<Stack gap={1} sx={{
+  width: 300
+}}>
+<Skeleton variant="text" level="h3" />
+<Skeleton variant="text" level="body-md" />
+<Skeleton variant="text" level="body-md" />
+<Skeleton variant="text" level="body-md" width="80%" />
+</Stack>
+```
+
+```tsx
+<Skeleton variant="text" level="h3" />
+<Skeleton variant="text" level="body-md" />
+<Skeleton variant="text" level="body-md" />
+<Skeleton variant="text" level="body-md" width="80%" />
+```
+
+## Card Skeleton
+
+Compose multiple Skeleton elements to create placeholder layouts for complex components like cards.
+
+```tsx
+<Box sx={{
+  width: 300,
+  p: 2,
+  border: '1px solid',
+  borderColor: 'divider',
+  borderRadius: 'sm'
+}}>
+<Skeleton variant="rectangular" width="100%" height={140} sx={{
+  borderRadius: 'sm',
+  mb: 2
+}} />
+<Skeleton variant="text" level="title-md" sx={{
+  mb: 1
+}} />
+<Skeleton variant="text" level="body-sm" />
+<Skeleton variant="text" level="body-sm" width="60%" />
+<Stack direction="row" gap={1} sx={{
+  mt: 2
+}}>
+<Skeleton variant="rectangular" width={80} height={32} sx={{
+  borderRadius: 'sm'
+}} />
+<Skeleton variant="rectangular" width={80} height={32} sx={{
+  borderRadius: 'sm'
+}} />
+</Stack>
+</Box>
+```
+
+## Data Loading List
+
+Combine circular and text skeletons to represent list items during loading.
+
+```tsx
+<Stack gap={2} sx={{
+  width: 400
+}}>
+{[1, 2, 3].map(i => <Stack key={i} direction="row" gap={2} alignItems="center">
+<Skeleton variant="circular" width={40} height={40} />
+<Box sx={{
+  flex: 1
+}}>
+<Skeleton variant="text" level="title-sm" width="60%" />
+<Skeleton variant="text" level="body-xs" width="40%" />
+</Box>
+</Stack>)}
+</Stack>
+```
+
+## Inline Wrapping
+
+Wrap existing content with Skeleton to overlay it while loading. Set the `loading` prop to control visibility.
+
+```tsx
+<Typography level="body-md">
+  <Skeleton loading>
+    This text will be hidden behind a skeleton while loading.
+  </Skeleton>
+</Typography>
+```
+
+```tsx
+<Typography level="body-md">
+  <Skeleton loading>
+    This text will be hidden behind a skeleton while loading.
+  </Skeleton>
+</Typography>
+```
+
+## Common Use Cases
+
+### Page Content Loading
+
+```tsx
+function PageSkeleton() {
+  return (
+    <Stack gap={3}>
+      <Skeleton variant="text" level="h1" width="50%" />
+      <Skeleton variant="text" level="body-md" />
+      <Skeleton variant="text" level="body-md" />
+      <Skeleton variant="text" level="body-md" width="75%" />
+
+      <Skeleton variant="rectangular" width="100%" height={200} sx={{ borderRadius: 'sm' }} />
+
+      <Skeleton variant="text" level="body-md" />
+      <Skeleton variant="text" level="body-md" />
+    </Stack>
+  );
+}
+```
+
+### User List Loading
+
+```tsx
+function UserListSkeleton({ count = 5 }: { count?: number }) {
+  return (
+    <Stack gap={2}>
+      {Array.from({ length: count }).map((_, i) => (
+        <Stack key={i} direction="row" gap={2} alignItems="center">
+          <Skeleton variant="circular" width={40} height={40} />
+          <Box sx={{ flex: 1 }}>
+            <Skeleton variant="text" level="title-sm" width="40%" />
+            <Skeleton variant="text" level="body-xs" width="25%" />
+          </Box>
+        </Stack>
+      ))}
+    </Stack>
+  );
+}
+```
+
+### Conditional Rendering
+
+```tsx
+function UserProfile({ loading, user }: { loading: boolean; user?: User }) {
+  return (
+    <Stack direction="row" gap={2} alignItems="center">
+      {loading ? (
+        <Skeleton variant="circular" width={48} height={48} />
+      ) : (
+        <Avatar src={user?.avatar} />
+      )}
+      <Box>
+        <Typography level="title-md">
+          <Skeleton loading={loading}>{user?.name || 'Placeholder Name'}</Skeleton>
+        </Typography>
+        <Typography level="body-sm">
+          <Skeleton loading={loading}>{user?.email || 'email@example.com'}</Skeleton>
+        </Typography>
+      </Box>
+    </Stack>
+  );
+}
+```
+
+## Best Practices
+
+1. **Match the final layout**: Skeleton placeholders should closely approximate the size and position of the real content to prevent layout shifts.
+
+```tsx
+// ✅ Matches the actual content structure
+<Stack gap={1}>
+  <Skeleton variant="text" level="title-md" width="60%" />
+  <Skeleton variant="text" level="body-sm" />
+</Stack>
+
+// ❌ Generic rectangle that doesn't match
+<Skeleton variant="rectangular" width={300} height={100} />
+```
+
+2. **Use `variant="text"` with `level`**: When replacing Typography, use the text variant with the matching level to get accurate line heights.
+
+3. **Avoid over-skeletonizing**: Only skeleton the main content areas. Don't add skeletons for static elements like navigation or headers that are always present.
+
+4. **Use consistent animation**: Keep the same animation type (`wave` or `pulse`) across the entire application for a cohesive loading experience.
+
+5. **Set appropriate widths**: Vary skeleton widths (e.g., 60%, 80%, 100%) to mimic natural text line lengths rather than using uniform widths.
+
+## Accessibility
+
+- Skeleton elements are purely decorative. Screen readers should focus on the loading state announcement, not individual skeleton elements.
+- Use `aria-busy="true"` on the container element while content is loading.
+- Provide an `aria-label` or visually hidden text that describes the loading state (e.g., "Loading user profile").
+- Ensure the animation respects `prefers-reduced-motion` — Joy UI handles this automatically.

package/dist/components/feedback/llms.txt

@@ -3,8 +3,10 @@
 ## Documentation
 
 - [Alert](./Alert.md)
+- [CircularProgress](./CircularProgress.md)
 - [DialogFrame](./Dialog.md)
 - [Modal](./Modal.md)
+- [Skeleton](./Skeleton.md)
 
 ## Parent