@ceed/cds 1.24.1-next.3 → 1.25.0

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

@@ -43,9 +43,7 @@ function ConfirmationDialog({ open, onClose, onConfirm }) {
             <Button variant="plain" color="neutral" onClick={onClose}>
               Cancel
             </Button>
-            <Button onClick={onConfirm}>
-              Confirm
-            </Button>
+            <Button onClick={onConfirm}>Confirm</Button>
           </>
         }
       >
@@ -94,6 +92,61 @@ Dialog Content
 </DialogFrame>
 ```
 
+### Standalone Usage
+
+DialogFrame can be used without a Modal wrapper for embedding dialog-style layouts directly within a page.
+
+> ⚠️ **Important** ⚠️
+>
+> 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
+}}>
+<DialogFrame {...args} title="Standalone Dialog" actions={<>
+  <Button variant="plain" color="neutral">
+    Cancel
+  </Button>
+  <Button variant="plain">Confirm</Button>
+</>}>
+DialogFrame used without Modal. The parent container must provide explicit width and height.
+</DialogFrame>
+</Box>
+```
+
+```tsx
+import { DialogFrame, Button, Box } from '@ceed/cds';
+
+// Standalone usage requires explicit container dimensions
+function EmbeddedDialog() {
+  return (
+    <Box sx={{ position: 'relative', width: 480, height: 300 }}>
+      <DialogFrame
+        title="Settings"
+        actions={
+          <>
+            <Button variant="plain" color="neutral">
+              Cancel
+            </Button>
+            <Button>Save</Button>
+          </>
+        }
+      >
+        This dialog is embedded directly in the page layout.
+      </DialogFrame>
+    </Box>
+  );
+}
+```
+
 ## When to Use
 
 ### ✅ Good Use Cases
@@ -177,21 +230,11 @@ function QuickAddDialog({ open, onClose, onSubmit }) {
         <Stack gap={2}>
           <FormControl>
             <FormLabel>Name</FormLabel>
-            <Input
-              value={name}
-              onChange={(e) => setName(e.target.value)}
-              placeholder="Enter name"
-              autoFocus
-            />
+            <Input value={name} onChange={(e) => setName(e.target.value)} placeholder="Enter name" autoFocus />
           </FormControl>
           <FormControl>
             <FormLabel>Email</FormLabel>
-            <Input
-              type="email"
-              value={email}
-              onChange={(e) => setEmail(e.target.value)}
-              placeholder="Enter email"
-            />
+            <Input type="email" value={email} onChange={(e) => setEmail(e.target.value)} placeholder="Enter email" />
           </FormControl>
         </Stack>
       </DialogFrame>
@@ -216,15 +259,11 @@ function UnsavedChangesDialog({ open, onClose, onDiscard, onSave }) {
             <Button variant="outlined" color="danger" onClick={onDiscard}>
               Discard
             </Button>
-            <Button onClick={onSave}>
-              Save Changes
-            </Button>
+            <Button onClick={onSave}>Save Changes</Button>
           </>
         }
       >
-        <Typography>
-          You have unsaved changes. Would you like to save them before leaving?
-        </Typography>
+        <Typography>You have unsaved changes. Would you like to save them before leaving?</Typography>
       </DialogFrame>
     </Modal>
   );
@@ -237,14 +276,7 @@ function UnsavedChangesDialog({ open, onClose, onDiscard, onSave }) {
 function InfoDialog({ open, onClose, title, message }) {
   return (
     <Modal open={open} onClose={onClose}>
-      <DialogFrame
-        title={title}
-        actions={
-          <Button onClick={onClose}>
-            Got it
-          </Button>
-        }
-      >
+      <DialogFrame title={title} actions={<Button onClick={onClose}>Got it</Button>}>
         <Typography>{message}</Typography>
       </DialogFrame>
     </Modal>
@@ -301,18 +333,8 @@ function ProcessingDialog({ open, status, onClose }) {
   return (
     <Modal open={open} onClose={isProcessing ? undefined : onClose}>
       <DialogFrame
-        title={
-          isProcessing ? 'Processing...' :
-          isSuccess ? 'Success!' :
-          'Error'
-        }
-        actions={
-          !isProcessing && (
-            <Button onClick={onClose}>
-              {isSuccess ? 'Done' : 'Try Again'}
-            </Button>
-          )
-        }
+        title={isProcessing ? 'Processing...' : isSuccess ? 'Success!' : 'Error'}
+        actions={!isProcessing && <Button onClick={onClose}>{isSuccess ? 'Done' : 'Try Again'}</Button>}
       >
         <Box sx={{ textAlign: 'center', py: 2 }}>
           {isProcessing && <CircularProgress />}
@@ -457,9 +479,7 @@ DialogFrame should be wrapped in Modal for proper behavior:
 // Fullscreen for complex content or mobile
 <Modal open={open} onClose={onClose}>
   <DialogFrame fullscreen title="Edit Profile">
-    <Box sx={{ p: 2 }}>
-      {/* Large form or content */}
-    </Box>
+    <Box sx={{ p: 2 }}>{/* Large form or content */}</Box>
   </DialogFrame>
 </Modal>
 ```
@@ -500,9 +520,7 @@ DialogFrame inherits accessibility features from Modal:
 
 ```tsx
 // Title provides context
-<DialogFrame title="Confirm Deletion">
-  {/* Content is read after title */}
-</DialogFrame>
+<DialogFrame title="Confirm Deletion">{/* Content is read after title */}</DialogFrame>
 ```
 
 ## Best Practices
@@ -530,9 +548,7 @@ DialogFrame inherits accessibility features from Modal:
 ```tsx
 // ✅ Good: Brief, scannable content
 <DialogFrame title="Delete Project">
-  <Typography>
-    This will permanently delete the project and all its data.
-  </Typography>
+  <Typography>This will permanently delete the project and all its data.</Typography>
 </DialogFrame>
 ```
 
@@ -560,7 +576,7 @@ DialogFrame inherits accessibility features from Modal:
 // ❌ Bad: Dialog for simple feedback
 <DialogFrame title="Success">
   <Typography>Item saved!</Typography>
-</DialogFrame>
+</DialogFrame>;
 
 // ✅ Good: Use Toast
 showToast({ message: 'Item saved!' });
@@ -570,9 +586,7 @@ showToast({ message: 'Item saved!' });
 
 ```tsx
 // ❌ Bad: Complex form in dialog
-<DialogFrame title="Create Account">
-  {/* 20+ form fields */}
-</DialogFrame>
+<DialogFrame title="Create Account">{/* 20+ form fields */}</DialogFrame>
 ```
 
 3. **Don't use vague button labels**: Be specific about actions
@@ -599,9 +613,7 @@ For dialogs with heavy content:
 function HeavyDialog({ open, onClose }) {
   return (
     <Modal open={open} onClose={onClose}>
-      <DialogFrame title="Data Preview">
-        {open && <HeavyDataComponent />}
-      </DialogFrame>
+      <DialogFrame title="Data Preview">{open && <HeavyDataComponent />}</DialogFrame>
     </Modal>
   );
 }
@@ -625,11 +637,13 @@ const handleCancel = useCallback(() => {
 Unmount dialog completely when not needed:
 
 ```tsx
-{open && (
-  <Modal open={open} onClose={onClose}>
-    <DialogFrame>...</DialogFrame>
-  </Modal>
-)}
+{
+  open && (
+    <Modal open={open} onClose={onClose}>
+      <DialogFrame>...</DialogFrame>
+    </Modal>
+  );
+}
 ```
 
 DialogFrame provides a consistent structure for dialog content. Combine it with Modal for proper overlay behavior, keep content concise and actionable, and always provide clear options for users to proceed or cancel.