@ceed/cds 1.22.2 → 1.22.4

package/dist/components/feedback/CircularProgress.md

@@ -0,0 +1,257 @@
+# CircularProgress
+
+## Introduction
+
+The CircularProgress component displays a circular loading indicator. It is based on Joy UI's CircularProgress and supports both indeterminate (spinning) and determinate (progress percentage) modes. Use it to provide visual feedback during asynchronous operations like data fetching, file uploads, or form submissions.
+
+```tsx
+<CircularProgress />
+```
+
+| Field       | Description | Default |
+| ----------- | ----------- | ------- |
+| size        | —           | —       |
+| color       | —           | —       |
+| variant     | —           | —       |
+| value       | —           | —       |
+| determinate | —           | —       |
+| thickness   | —           | —       |
+
+## Usage
+
+```tsx
+import { CircularProgress } from '@ceed/cds';
+
+function MyComponent() {
+  return <CircularProgress />;
+}
+```
+
+## Sizes
+
+CircularProgress supports three sizes: `sm`, `md` (default), and `lg`.
+
+```tsx
+<>
+  <CircularProgress size="sm" />
+  <CircularProgress size="md" />
+  <CircularProgress size="lg" />
+</>
+```
+
+```tsx
+<CircularProgress size="sm" />
+<CircularProgress size="md" />
+<CircularProgress size="lg" />
+```
+
+## Colors
+
+Five semantic colors are available via the `color` prop. The default is `primary`.
+
+```tsx
+<>
+  <CircularProgress color="primary" />
+  <CircularProgress color="neutral" />
+  <CircularProgress color="danger" />
+  <CircularProgress color="success" />
+  <CircularProgress color="warning" />
+</>
+```
+
+```tsx
+<CircularProgress color="primary" />
+<CircularProgress color="neutral" />
+<CircularProgress color="danger" />
+<CircularProgress color="success" />
+<CircularProgress color="warning" />
+```
+
+## Variants
+
+Four visual variants are supported: `solid`, `soft` (default), `outlined`, and `plain`.
+
+```tsx
+<>
+  <CircularProgress variant="solid" />
+  <CircularProgress variant="soft" />
+  <CircularProgress variant="outlined" />
+  <CircularProgress variant="plain" />
+</>
+```
+
+```tsx
+<CircularProgress variant="solid" />
+<CircularProgress variant="soft" />
+<CircularProgress variant="outlined" />
+<CircularProgress variant="plain" />
+```
+
+## Determinate Mode
+
+Set `determinate` to `true` and provide a `value` (0–100) to display specific progress.
+
+```tsx
+<>
+  <CircularProgress determinate value={25} />
+  <CircularProgress determinate value={50} />
+  <CircularProgress determinate value={75} />
+  <CircularProgress determinate value={100} />
+</>
+```
+
+```tsx
+<CircularProgress determinate value={25} />
+<CircularProgress determinate value={50} />
+<CircularProgress determinate value={75} />
+<CircularProgress determinate value={100} />
+```
+
+## With Label
+
+Pass children to display a label inside the progress ring. This is useful for showing the current percentage.
+
+```tsx
+<CircularProgress determinate value={66}>
+  <Typography level="body-xs">66%</Typography>
+</CircularProgress>
+```
+
+```tsx
+<CircularProgress determinate value={66}>
+  <Typography level="body-xs">66%</Typography>
+</CircularProgress>
+```
+
+## In Button
+
+Use CircularProgress inside a Button to indicate a loading state.
+
+```tsx
+<>
+  <Button startDecorator={<CircularProgress variant="solid" size="sm" />}>
+    Loading…
+  </Button>
+  <Button disabled>
+    <CircularProgress variant="soft" size="sm" />
+  </Button>
+</>
+```
+
+```tsx
+<Button startDecorator={<CircularProgress variant="solid" size="sm" />}>
+  Loading…
+</Button>
+
+<Button disabled>
+  <CircularProgress variant="soft" size="sm" />
+</Button>
+```
+
+## Thickness
+
+Control the stroke thickness of the progress ring with the `thickness` prop.
+
+```tsx
+<>
+  <CircularProgress thickness={2} />
+  <CircularProgress thickness={4} />
+  <CircularProgress thickness={8} />
+</>
+```
+
+```tsx
+<CircularProgress thickness={2} />
+<CircularProgress thickness={4} />
+<CircularProgress thickness={8} />
+```
+
+## Common Use Cases
+
+### Data Fetching Indicator
+
+```tsx
+function DataLoader() {
+  const [loading, setLoading] = React.useState(true);
+  const [data, setData] = React.useState(null);
+
+  React.useEffect(() => {
+    fetchData().then((result) => {
+      setData(result);
+      setLoading(false);
+    });
+  }, []);
+
+  if (loading) {
+    return (
+      <Box sx={{ display: 'flex', justifyContent: 'center', py: 4 }}>
+        <CircularProgress />
+      </Box>
+    );
+  }
+
+  return <DataView data={data} />;
+}
+```
+
+### File Upload Progress
+
+```tsx
+function FileUpload({ progress }: { progress: number }) {
+  return (
+    <Stack direction="row" alignItems="center" spacing={2}>
+      <CircularProgress determinate value={progress} size="lg">
+        <Typography level="body-xs">{progress}%</Typography>
+      </CircularProgress>
+      <Typography level="body-md">Uploading file…</Typography>
+    </Stack>
+  );
+}
+```
+
+### Inline Loading Button
+
+```tsx
+function SubmitButton({ isSubmitting }: { isSubmitting: boolean }) {
+  return (
+    <Button
+      disabled={isSubmitting}
+      startDecorator={
+        isSubmitting ? <CircularProgress variant="solid" size="sm" /> : null
+      }
+    >
+      {isSubmitting ? 'Submitting…' : 'Submit'}
+    </Button>
+  );
+}
+```
+
+## Best Practices
+
+1. **Use indeterminate for unknown durations**: When you cannot estimate progress, use the default spinning mode. Switch to determinate only when you can track actual progress.
+
+```tsx
+// ✅ Unknown duration — indeterminate
+<CircularProgress />
+
+// ✅ Known progress — determinate
+<CircularProgress determinate value={uploadProgress} />
+
+// ❌ Don't use determinate with a static value for loading
+<CircularProgress determinate value={50} />
+```
+
+2. **Size appropriately**: Use `sm` for inline contexts (buttons, table cells), `md` for general use, and `lg` for prominent page-level loading states.
+
+3. **Match variant with context**: Use `solid` variant inside solid buttons, and `soft` (default) for standalone usage to maintain visual consistency.
+
+4. **Add descriptive text**: Always pair the indicator with text or an `aria-label` so users understand what is loading.
+
+5. **Avoid multiple spinners**: Show one loading indicator per distinct loading region. Multiple spinners on a page create visual clutter.
+
+## Accessibility
+
+- CircularProgress has `role="progressbar"` by default.
+- In determinate mode, `aria-valuenow`, `aria-valuemin`, and `aria-valuemax` are set automatically.
+- Add `aria-label` or nearby descriptive text to explain what is loading (e.g., `aria-label="Loading user data"`).
+- Ensure sufficient color contrast between the progress ring and its background, especially with the `plain` variant.

package/dist/components/feedback/Dialog.md

@@ -98,12 +98,16 @@ DialogFrame can be used without a Modal wrapper for embedding dialog-style layou
 
 > ⚠️ **Important** ⚠️
 >
-> When using DialogFrame without Modal, the parent container **must** provide explicit `width` and `height` values.
-> DialogFrame inherits its dimensions from `ModalDialog`, which normally receives sizing from the Modal overlay.
-> Without these constraints, the component will not render with correct dimensions.
+> When using DialogFrame without Modal, the parent container **must** meet the following requirements:
+>
+> - `position: 'relative'` — DialogFrame 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`
+>
+> DialogFrame 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
 }}>
@@ -124,7 +128,7 @@ import { DialogFrame, Button, Box } from '@ceed/cds';
 // Standalone usage requires explicit container dimensions
 function EmbeddedDialog() {
   return (
-    <Box sx={{ width: 480, height: 300 }}>
+    <Box sx={{ position: 'relative', width: 480, height: 300 }}>
       <DialogFrame
         title="Settings"
         actions={

package/dist/components/feedback/Modal.md

@@ -442,12 +442,16 @@ ModalFrame can be used without a Modal wrapper for embedding dialog-style layout
 
 > ⚠️ **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.
+> 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
 }}>

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/cds';
+
+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