@ceed/ads 1.23.3 → 1.23.5

package/dist/components/data-display/Typography.md

@@ -33,20 +33,110 @@ function MyComponent() {
 
 ## Typography Levels
 
+### Overview
+
+Typography levels are divided into three groups: **Headings**, **Titles**, and **Body**. The default level is `body-md`.
+
+- **Headings** (`h1`–`h4`): Used for page and section headings. Uses the display font family (Inter).
+- **Titles** (`title-lg`, `title-md`, `title-sm`): Used for UI labels, card titles, and emphasized text. Uses the body font family (Inter).
+- **Body** (`body-lg`, `body-md`, `body-sm`, `body-xs`): Used for readable content and descriptions. Uses the body font family (Inter).
+
+```tsx
+<>
+  <Stack direction="row" spacing={2}>
+    <Typography level="h1">h1</Typography>
+    <Typography {...args} level="h1" />
+  </Stack>
+  <Stack direction="row" spacing={2}>
+    <Typography level="h2">h2</Typography>
+    <Typography {...args} level="h2" />
+  </Stack>
+  <Stack direction="row" spacing={2}>
+    <Typography level="h3">h3</Typography>
+    <Typography {...args} level="h3" />
+  </Stack>
+  <Stack direction="row" spacing={2}>
+    <Typography level="h4">h4</Typography>
+    <Typography {...args} level="h4" />
+  </Stack>
+  <Stack direction="row" spacing={2}>
+    <Typography level="title-lg">title-lg</Typography>
+    <Typography {...args} level="title-lg" />
+  </Stack>
+  <Stack direction="row" spacing={2}>
+    <Typography level="title-md">title-md</Typography>
+    <Typography {...args} level="title-md" />
+  </Stack>
+  <Stack direction="row" spacing={2}>
+    <Typography level="title-sm">title-sm</Typography>
+    <Typography {...args} level="title-sm" />
+  </Stack>
+  <Stack direction="row" spacing={2}>
+    <Typography level="body-lg">body-lg</Typography>
+    <Typography {...args} level="body-lg" />
+  </Stack>
+  <Stack direction="row" spacing={2}>
+    <Typography level="body-md">body-md</Typography>
+    <Typography {...args} level="body-md" />
+  </Stack>
+  <Stack direction="row" spacing={2}>
+    <Typography level="body-sm">body-sm</Typography>
+    <Typography {...args} level="body-sm" />
+  </Stack>
+  <Stack direction="row" spacing={2}>
+    <Typography level="body-xs">body-xs</Typography>
+    <Typography {...args} level="body-xs" />
+  </Stack>
+</>
+```
+
+### Style Reference
+
+| Level    | Font Family     | Font Size       | Font Weight    | Line Height | Letter Spacing | Default Color  | HTML Tag |
+| -------- | --------------- | --------------- | -------------- | ----------- | -------------- | -------------- | -------- |
+| h1       | display (Inter) | 2.25rem (36px)  | 700 (Bold)     | 1.333       | -0.025em       | text.primary   | `<h1>`   |
+| h2       | display (Inter) | 1.875rem (30px) | 700 (Bold)     | 1.333       | -0.025em       | text.primary   | `<h2>`   |
+| h3       | display (Inter) | 1.5rem (24px)   | 600 (SemiBold) | 1.333       | -0.025em       | text.primary   | `<h3>`   |
+| h4       | display (Inter) | 1.25rem (20px)  | 600 (SemiBold) | 1.5         | -0.025em       | text.primary   | `<h4>`   |
+| title-lg | body (Inter)    | 1.125rem (18px) | 600 (SemiBold) | 1.333       | -              | text.primary   | `<p>`    |
+| title-md | body (Inter)    | 1rem (16px)     | 500 (Medium)   | 1.5         | -              | text.primary   | `<p>`    |
+| title-sm | body (Inter)    | 0.875rem (14px) | 500 (Medium)   | 1.429       | -              | text.primary   | `<p>`    |
+| body-lg  | body (Inter)    | 1.125rem (18px) | inherit        | 1.5         | -              | text.secondary | `<p>`    |
+| body-md  | body (Inter)    | 1rem (16px)     | inherit        | 1.5         | -              | text.secondary | `<p>`    |
+| body-sm  | body (Inter)    | 0.875rem (14px) | inherit        | 1.5         | -              | text.tertiary  | `<p>`    |
+| body-xs  | body (Inter)    | 0.75rem (12px)  | 500 (Medium)   | 1.5         | -              | text.tertiary  | `<span>` |
+
 ### Headings
 
-Levels for headings. Use them to clearly define page structure.
+Heading levels define page structure and hierarchy. They use the display font family with heavier weights for visual prominence.
+
+```tsx
+<>
+  <Typography level="h1">h1 - Main page heading</Typography>
+  <Typography level="h2">h2 - Section heading</Typography>
+  <Typography level="h3">h3 - Subsection heading</Typography>
+  <Typography level="h4">h4 - Detail heading</Typography>
+</>
+```
 
 ```tsx
 <Typography level="h1">H1 - Main page heading</Typography>
 <Typography level="h2">H2 - Section heading</Typography>
 <Typography level="h3">H3 - Subsection heading</Typography>
-<Typography level="h4">H4 - Detailed heading</Typography>
+<Typography level="h4">H4 - Detail heading</Typography>
 ```
 
 ### Titles
 
-Used for important titles or emphasized text.
+Title levels are used for UI labels, card titles, and other emphasized text that is not a document heading.
+
+```tsx
+<>
+  <Typography level="title-lg">title-lg - Large title</Typography>
+  <Typography level="title-md">title-md - Medium title</Typography>
+  <Typography level="title-sm">title-sm - Small title</Typography>
+</>
+```
 
 ```tsx
 <Typography level="title-lg">Large Title</Typography>
@@ -56,7 +146,16 @@ Used for important titles or emphasized text.
 
 ### Body Text
 
-Levels for body text. Use these for most readable content.
+Body levels are used for readable content and descriptions. The default level `body-md` is suitable for most body text. Use `body-xs` sparingly for auxiliary information like timestamps or counters.
+
+```tsx
+<>
+  <Typography level="body-lg">body-lg - Large body text</Typography>
+  <Typography level="body-md">body-md - Regular body text</Typography>
+  <Typography level="body-sm">body-sm - Small body text</Typography>
+  <Typography level="body-xs">body-xs - Extra small text</Typography>
+</>
+```
 
 ```tsx
 <Typography level="body-lg">Large body text</Typography>
@@ -65,6 +164,194 @@ Levels for body text. Use these for most readable content.
 <Typography level="body-xs">Extra small text</Typography>
 ```
 
+## Design Token Reference
+
+### Font Size Scale
+
+| Token | Value           |
+| ----- | --------------- |
+| xs    | 0.75rem (12px)  |
+| sm    | 0.875rem (14px) |
+| md    | 1rem (16px)     |
+| lg    | 1.125rem (18px) |
+| xl    | 1.25rem (20px)  |
+| xl2   | 1.5rem (24px)   |
+| xl3   | 1.875rem (30px) |
+| xl4   | 2.25rem (36px)  |
+
+### Font Weight Scale
+
+| Token | Value          |
+| ----- | -------------- |
+| sm    | 300 (Light)    |
+| md    | 500 (Medium)   |
+| lg    | 600 (SemiBold) |
+| xl    | 700 (Bold)     |
+
+### Line Height Scale
+
+| Token | Value |
+| ----- | ----- |
+| xs    | 1.333 |
+| sm    | 1.429 |
+| md    | 1.5   |
+| lg    | 1.556 |
+| xl    | 1.667 |
+
+### Font Families
+
+- **body**: `"Inter"`, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif
+- **display**: `"Inter"`, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif
+- **code**: `"Source Code Pro"`, ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace
+
+## Colors
+
+Typography supports five semantic colors via the `color` prop. Use `textColor` to apply any palette color directly.
+
+```tsx
+<>
+  <Typography color="primary">Primary color</Typography>
+  <Typography color="neutral">Neutral color</Typography>
+  <Typography color="danger">Danger color</Typography>
+  <Typography color="success">Success color</Typography>
+  <Typography color="warning">Warning color</Typography>
+</>
+```
+
+```tsx
+<Typography color="primary">Primary color</Typography>
+<Typography color="neutral">Neutral color</Typography>
+<Typography color="danger">Danger color</Typography>
+<Typography color="success">Success color</Typography>
+<Typography color="warning">Warning color</Typography>
+
+{/* Use textColor for specific palette values */}
+<Typography textColor="neutral.600">Custom palette color</Typography>
+```
+
+## Component Prop
+
+Use the `component` prop to render Typography as a different HTML element or React component. Each level has a default HTML tag mapping shown below.
+
+```tsx
+<>
+  <Typography level="h1" component="h2">
+    h1 style rendered as h2 tag
+  </Typography>
+  <Typography level="body-md" component="span">
+    body-md rendered as span
+  </Typography>
+  <Typography level="title-md" component="label">
+    title-md rendered as label
+  </Typography>
+</>
+```
+
+```tsx
+<Typography level="h1" component="h2">
+  h1 style rendered as an h2 tag
+</Typography>
+
+<Typography level="body-md" component="span">
+  Inline text
+</Typography>
+
+<Typography level="title-md" component="label">
+  Rendered as a label element
+</Typography>
+```
+
+**Default HTML tag mapping:**
+
+| Level    | Default HTML Tag |
+| -------- | ---------------- |
+| h1       | `<h1>`           |
+| h2       | `<h2>`           |
+| h3       | `<h3>`           |
+| h4       | `<h4>`           |
+| title-lg | `<p>`            |
+| title-md | `<p>`            |
+| title-sm | `<p>`            |
+| body-lg  | `<p>`            |
+| body-md  | `<p>`            |
+| body-sm  | `<p>`            |
+| body-xs  | `<span>`         |
+
+## Decorators
+
+Use `startDecorator` and `endDecorator` to add icons or other elements before or after the text.
+
+```tsx
+<>
+  <Typography startDecorator={<InfoOutlined />}>
+    Text with start decorator
+  </Typography>
+  <Typography endDecorator={<ArrowForward />}>
+    Text with end decorator
+  </Typography>
+  <Typography startDecorator={<InfoOutlined />} endDecorator={<ArrowForward />}>
+    Text with both decorators
+  </Typography>
+</>
+```
+
+```tsx
+import InfoOutlined from '@mui/icons-material/InfoOutlined';
+import ArrowForward from '@mui/icons-material/ArrowForward';
+
+<Typography startDecorator={<InfoOutlined />}>
+  Text with start decorator
+</Typography>
+
+<Typography endDecorator={<ArrowForward />}>
+  Text with end decorator
+</Typography>
+
+<Typography startDecorator={<InfoOutlined />} endDecorator={<ArrowForward />}>
+  Text with both decorators
+</Typography>
+```
+
+## Text Overflow (noWrap)
+
+Use the `noWrap` prop to truncate overflowing text with an ellipsis. Pair it with a `maxWidth` to constrain the text width.
+
+```tsx
+<Typography noWrap sx={{
+  maxWidth: 200
+}}>
+This is a long text that will be truncated with an ellipsis when it
+exceeds the maximum width of the container.
+</Typography>
+```
+
+```tsx
+<Typography noWrap sx={{ maxWidth: 200 }}>
+  This is a long text that will be truncated with an ellipsis when it exceeds
+  the maximum width.
+</Typography>
+```
+
+## Responsive Typography
+
+You can pass a responsive object to the `level` prop, or use `sx` to set responsive font sizes.
+
+```tsx
+{/* Responsive level */}
+<Typography level={{ xs: 'h3', sm: 'h2', md: 'h1' }}>
+  Responsive Heading
+</Typography>
+
+{/* Responsive font size via sx */}
+<Typography
+  sx={{
+    fontSize: { xs: '1rem', sm: '1.25rem', md: '1.5rem' },
+  }}
+>
+  Responsive text
+</Typography>
+```
+
 ## Common Use Cases
 
 ### Page Structure
@@ -197,7 +484,7 @@ function ArticlePage() {
         level="body-md"
         sx={{
           textDecoration: item.completed ? 'line-through' : 'none',
-          color: item.completed ? 'neutral.500' : 'text.primary'
+          color: item.completed ? 'neutral.500' : 'text.primary',
         }}
       >
         {item.text}
@@ -210,56 +497,9 @@ function ArticlePage() {
 </Stack>
 ```
 
-## Colors
-
-Typography supports various colors:
-
-```tsx
-<Stack spacing={1}>
-  <Typography color="primary">Primary color</Typography>
-  <Typography color="neutral">Neutral color</Typography>
-  <Typography color="danger">Danger color</Typography>
-  <Typography color="success">Success color</Typography>
-  <Typography color="warning">Warning color</Typography>
-</Stack>
-```
-
-## Component Prop
-
-You can render it as a different HTML element or React component:
-
-```tsx
-<Typography level="h1" component="h2">
-  h1 style rendered as an h2 tag
-</Typography>
-
-<Typography level="body-md" component="span">
-  Inline text
-</Typography>
-
-<Typography level="title-md" component={Link} href="/page">
-  Rendered as a Link component
-</Typography>
-```
-
-## Responsive Typography
-
-You can use responsive levels:
-
-```tsx
-<Typography
-  level={{ xs: 'h3', sm: 'h2', md: 'h1' }}
-  sx={{
-    fontSize: { xs: '1.5rem', sm: '2rem', md: '2.5rem' }
-  }}
->
-  Responsive Heading
-</Typography>
-```
-
 ## Best Practices
 
-1. **Semantic Structure**: Use heading levels in order to create a clear document structure.
+1. **Semantic Structure**: Use heading levels in order (`h1` → `h2` → `h3`) to create a clear document hierarchy.
 
 ```tsx
 // ✅ Correct order
@@ -267,22 +507,31 @@ You can use responsive levels:
 <Typography level="h2">Section heading</Typography>
 <Typography level="h3">Subsection</Typography>
 
-// ❌ Incorrect order
+// ❌ Incorrect order — skipping h2
 <Typography level="h1">Main heading</Typography>
 <Typography level="h3">Section heading</Typography>
 ```
 
-2. **Consistency**: Use the same level for text serving the same purpose.
+2. **Consistency**: Use the same level for text serving the same purpose across the application.
 
 3. **Readability**: Provide proper line spacing and paragraph separation for body text.
 
 4. **Color Contrast**: Maintain sufficient color contrast to ensure accessibility.
 
-## Accessibility
+5. **Level Selection Guide**:
+   - **Headings** (`h1`–`h4`): Use for document structure and section titles.
+   - **Titles** (`title-lg/md/sm`): Use for UI labels, card headers, and emphasized text.
+   - **Body** (`body-lg/md/sm/xs`): Use for content, descriptions, and supporting text.
 
-- Use appropriate semantic HTML tags
-- Support screen readers
-- Ensure keyboard navigation (when used as a link or button)
-- Maintain sufficient color contrast
+6. **Avoid inline style overrides**: Prefer the `level` prop over `sx` for font sizing. Use `level` for consistent design tokens.
+
+7. **Use `textColor` for custom colors**: When the five semantic colors are insufficient, use `textColor` to apply any palette value directly.
+
+8. **Use `body-xs` sparingly**: Reserve `body-xs` (12px) for auxiliary information such as timestamps, counters, and footnotes — not for primary content.
+
+## Accessibility
 
-Typography plays a key role in effectively conveying information and creating visual hierarchy in user interfaces. By choosing appropriate levels and styles, you can create content that is easy to read and accessible.
+- Use sequential heading levels (`h1` → `h2` → `h3`). Do not skip levels.
+- Use the `component` prop to separate visual style from semantic meaning (e.g., `level="h1" component="h2"` when you need h1 styling but h2 semantics).
+- Avoid using `body-xs` (12px) for essential content — the small size may be difficult to read.
+- Maintain sufficient color contrast ratios (WCAG AA: 4.5:1 for normal text, 3:1 for large text).

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