Skip to content

The open alternative to Salesforce, designed for AI.

Unify Progress semantics and move onboarding motion (#27831)

Raphaël Bosi76db836a237e
diff --git a/packages/twenty-docs/docs.json b/packages/twenty-docs/docs.json
index 423a32da2c8..42707171742 100644
--- a/packages/twenty-docs/docs.json
+++ b/packages/twenty-docs/docs.json
@@ -557,6 +557,7 @@
"pages": [
"ui/primitives/feedback/banner",
"ui/primitives/feedback/loader",
+ "ui/primitives/feedback/progress",
"ui/primitives/feedback/progress-bar",
"ui/primitives/feedback/progress-ring",
"ui/primitives/feedback/skeleton"
diff --git a/packages/twenty-docs/navigation/base-structure.json b/packages/twenty-docs/navigation/base-structure.json
index e3e18183254..5f6b2773f64 100644
--- a/packages/twenty-docs/navigation/base-structure.json
+++ b/packages/twenty-docs/navigation/base-structure.json
@@ -569,6 +569,7 @@
"pages": [
"ui/primitives/feedback/banner",
"ui/primitives/feedback/loader",
+ "ui/primitives/feedback/progress",
"ui/primitives/feedback/progress-bar",
"ui/primitives/feedback/progress-ring",
"ui/primitives/feedback/skeleton"
diff --git a/packages/twenty-docs/scripts/ui/__tests__/public-component-exports.spec.ts b/packages/twenty-docs/scripts/ui/__tests__/public-component-exports.spec.ts
index 7360e673a6a..86b4734a71d 100644
--- a/packages/twenty-docs/scripts/ui/__tests__/public-component-exports.spec.ts
+++ b/packages/twenty-docs/scripts/ui/__tests__/public-component-exports.spec.ts
@@ -69,6 +69,28 @@ describe('public component documentation coverage', () => {
).toEqual(['Action', 'Menu']);
});
+ it('finds a preserved upstream component namespace through public re-exports', () => {
+ const { checker, getEntryPoint } = createFixtureProgram({
+ 'upstream-parts.d.ts': `
+ export declare const Root: (props: { value: number | null }) => null;
+ export declare const Indicator: () => null;
+ export type Status = 'progressing' | 'complete' | 'indeterminate';
+ `,
+ 'upstream.d.ts': "export * as Progress from './upstream-parts';",
+ 'Progress.tsx': "export { Progress } from './upstream';",
+ 'index.ts': "export { Progress } from './Progress';",
+ });
+
+ expect(
+ getPublicComponentExports({
+ checker,
+ entryPoints: [
+ getEntryPoint('twenty-ui/primitives/feedback', 'index.ts'),
+ ],
+ }).map(({ name }) => name),
+ ).toEqual(['Progress']);
+ });
+
it('keeps every entry point exporting a component whatever their order', () => {
const { checker, getEntryPoint } = createFixtureProgram({
'IconCheck.tsx': 'export const IconCheck = () => null;',
diff --git a/packages/twenty-docs/snippets/ui/generated/components/data-display/metric-row.mdx b/packages/twenty-docs/snippets/ui/generated/components/data-display/metric-row.mdx
index 33e44921ac8..243f02e2729 100644
--- a/packages/twenty-docs/snippets/ui/generated/components/data-display/metric-row.mdx
+++ b/packages/twenty-docs/snippets/ui/generated/components/data-display/metric-row.mdx
@@ -28,7 +28,7 @@
</ParamField>
<ParamField body="progressValueText" type="string">
- Accessible value text for the progress ring. Overrides the string value fallback; supply it when formatted content needs more context than a percentage.
+ Accessible value text for the progress ring. Nonempty text overrides the string value fallback; an empty string uses the ring percentage. Supply it when formatted content needs more context than a percentage.
</ParamField>
<ParamField body="render" type="ReactElement&lt;unknown, string | JSXElementConstructor&lt;any&gt;&gt; | ComponentRenderFn&lt;HTMLProps, {}&gt;">
@@ -44,5 +44,5 @@
</ParamField>
<ParamField body="value" type="ReactNode" required>
- Preformatted value displayed at the end of the row. String values also supply the progress ring accessible value text.
+ Preformatted value displayed at the end of the row. Nonempty string values also supply the progress ring accessible value text.
</ParamField>
diff --git a/packages/twenty-docs/snippets/ui/generated/feedback/progress-bar.mdx b/packages/twenty-docs/snippets/ui/generated/feedback/progress-bar.mdx
index bfbf86bb004..a22af14ef78 100644
--- a/packages/twenty-docs/snippets/ui/generated/feedback/progress-bar.mdx
+++ b/packages/twenty-docs/snippets/ui/generated/feedback/progress-bar.mdx
@@ -11,8 +11,16 @@
* npx nx generate:ui twenty-docs
*/}
-<ParamField body="ariaLabel" type="string">
- Accessible name describing the operation being measured.
+<ParamField body="aria-label" type="string">
+ Accessible name identifying the measured operation.
+</ParamField>
+
+<ParamField body="aria-labelledby" type="string">
+ ID of the visible label that names the operation.
+</ParamField>
+
+<ParamField body="aria-valuetext" type="string">
+ Human-readable progress value overriding the default formatted value.
</ParamField>
<ParamField body="backgroundColor" type="string" default="none">
@@ -23,38 +31,58 @@
CSS color of the filled bar. Defaults to the primary text color.
</ParamField>
-<ParamField body="className" type="string">
- CSS class applied to the progress root.
+<ParamField body="children" type="ReactNode">
+ Additional Progress parts or supporting content inside the root.
</ParamField>
-<ParamField body="onGrowInComplete" type="(() =&gt; void)">
- Called when the grow-in animation ends.
+<ParamField body="className" type="string | ((state: ProgressRootState) =&gt; string | undefined)">
+ Class applied to the progress root, or a callback receiving its status.
</ParamField>
-<ParamField body="size" type="&quot;md&quot; | &quot;sm&quot;" default="md">
- Bar height: `sm` (6px) or `md` (8px).
+<ParamField body="format" type="NumberFormatOptions">
+ Intl.NumberFormat options for the clamped numeric value. The default displays the normalized percentage.
</ParamField>
-<ParamField body="value" type="number" required>
- Current progress from 0 to 100.
+<ParamField body="getAriaValueText" type="((formattedValue: string, value: number | null) =&gt; string)">
+ Receives the formatted value and raw value, including null, and returns an accessible value description.
</ParamField>
-<ParamField body="withBorderRadius" type="boolean" default="false">
- Rounds the track and indicator corners.
+<ParamField body="locale" type="LocalesArgument">
+ Locale or locale list used to format the value. Defaults to the runtime locale.
</ParamField>
-<ParamField body="withGlint" type="boolean" default="false">
- Sweeps a highlight across the filled bar each time the value changes.
+<ParamField body="max" type="number" default="100">
+ Inclusive maximum. Defaults to 100.
</ParamField>
-<ParamField body="withGrowIn" type="boolean" default="false">
- Grows the bar in from zero width when it mounts.
+<ParamField body="min" type="number" default="0">
+ Inclusive minimum. Defaults to 0.
</ParamField>
-<ParamField body="withMinimumFillWidth" type="boolean" default="true">
- Keeps a small visible fill for any value above zero.
+<ParamField body="ref" type="Ref&lt;HTMLDivElement&gt;">
+ Ref to the root div, or the element composed through render.
+</ParamField>
+
+<ParamField body="render" type="ReactElement&lt;unknown, string | JSXElementConstructor&lt;any&gt;&gt; | ComponentRenderFn&lt;HTMLProps, ProgressRootState&gt;">
+ Composes the root with an element or render callback. Forward the supplied props and ref to retain progress semantics.
+</ParamField>
+
+<ParamField body="size" type="&quot;md&quot; | &quot;sm&quot;" default="md">
+ Bar height: sm (6px) or md (8px).
+</ParamField>
+
+<ParamField body="style" type="CSSProperties | ((state: ProgressRootState) =&gt; CSSProperties | undefined)">
+ Inline styles applied to the progress root, or a callback receiving its status.
+</ParamField>
+
+<ParamField body="value" type="number | null" required>
+ Controlled value in the min/max range. Use null for indeterminate progress.
</ParamField>
-<ParamField body="withSpringFill" type="boolean" default="false">
- Animates value changes with a spring that slightly overshoots the target.
+<ParamField body="withBorderRadius" type="boolean" default="false">
+ Rounds the track and indicator corners.
+</ParamField>
+
+<ParamField body="withMinimumFillWidth" type="boolean" default="true">
+ Applies a cosmetic minimum of up to 12px, capped at half the track width, only above the minimum and below completion.
</ParamField>
diff --git a/packages/twenty-docs/snippets/ui/generated/feedback/progress-ring.mdx b/packages/twenty-docs/snippets/ui/generated/feedback/progress-ring.mdx
index 08fc7c29617..65945fd309a 100644
--- a/packages/twenty-docs/snippets/ui/generated/feedback/progress-ring.mdx
+++ b/packages/twenty-docs/snippets/ui/generated/feedback/progress-ring.mdx
@@ -16,11 +16,11 @@
</ParamField>
<ParamField body="aria-labelledby" type="string">
- ID of the visible label that names the measured operation.
+ ID of the visible label that names the operation.
</ParamField>
<ParamField body="aria-valuetext" type="string">
- Human-readable progress value when a percentage alone is insufficient.
+ Human-readable progress value overriding the default formatted value.
</ParamField>
<ParamField body="barColor" type="string">
@@ -28,25 +28,49 @@
</ParamField>
<ParamField body="children" type="ReactNode">
- Optional preformatted value displayed before the ring.
+ Optional preformatted value or Progress parts displayed before the ring.
</ParamField>
-<ParamField body="className" type="string">
- CSS class applied to the progress root.
+<ParamField body="className" type="string | ((state: ProgressRootState) =&gt; string | undefined)">
+ Class applied to the progress root, or a callback receiving its status.
</ParamField>
-<ParamField body="render" type="ReactElement&lt;unknown, string | JSXElementConstructor&lt;any&gt;&gt; | ComponentRenderFn&lt;HTMLProps, {}&gt;">
- Replaces the root element while preserving progress semantics.
+<ParamField body="format" type="NumberFormatOptions">
+ Intl.NumberFormat options for the clamped numeric value. The default displays the normalized percentage.
+</ParamField>
+
+<ParamField body="getAriaValueText" type="((formattedValue: string, value: number | null) =&gt; string)">
+ Receives the formatted value and raw value, including null, and returns an accessible value description.
+</ParamField>
+
+<ParamField body="locale" type="LocalesArgument">
+ Locale or locale list used to format the value. Defaults to the runtime locale.
+</ParamField>
+
+<ParamField body="max" type="number" default="100">
+ Inclusive maximum. Defaults to 100.
+</ParamField>
+
+<ParamField body="min" type="number" default="0">
+ Inclusive minimum. Defaults to 0.
+</ParamField>
+
+<ParamField body="ref" type="Ref&lt;HTMLDivElement&gt;">
+ Ref to the root div, or the element composed through render.
+</ParamField>
+
+<ParamField body="render" type="ReactElement&lt;unknown, string | JSXElementConstructor&lt;any&gt;&gt; | ComponentRenderFn&lt;HTMLProps, ProgressRootState&gt;">
+ Composes the root with an element or render callback. Forward the supplied props and ref to retain progress semantics.
</ParamField>
<ParamField body="size" type="&quot;md&quot; | &quot;sm&quot;" default="md">
Ring diameter: sm (14px) or md (16px). Defaults to md.
</ParamField>
-<ParamField body="style" type="CSSProperties">
- Inline styles applied to the progress root.
+<ParamField body="style" type="CSSProperties | ((state: ProgressRootState) =&gt; CSSProperties | undefined)">
+ Inline styles applied to the progress root, or a callback receiving its status.
</ParamField>
-<ParamField body="value" type="number" required>
- Controlled progress from 0 to 100. Out-of-range values are bounded and NaN renders as zero.
+<ParamField body="value" type="number | null" required>
+ Controlled value in the min/max range. Use null for indeterminate progress.
</ParamField>
diff --git a/packages/twenty-docs/snippets/ui/generated/feedback/progress.mdx b/packages/twenty-docs/snippets/ui/generated/feedback/progress.mdx
new file mode 100644
index 00000000000..36d01a100c8
--- /dev/null
+++ b/packages/twenty-docs/snippets/ui/generated/feedback/progress.mdx
@@ -0,0 +1,154 @@
+{/*
+ * _____ _
+ *|_ _|_ _____ _ __ | |_ _ _
+ * | | \ \ /\ / / _ \ '_ \| __| | | | Auto-generated file
+ * | | \ V V / __/ | | | |_| |_| | DO NOT EDIT - changes will be overwritten
+ * |_| \_/\_/ \___|_| |_|\__|\__, | Generated by: npx nx generate:ui twenty-docs
+ * |___/
+ *
+ * This file is generated from the documentation data in packages/twenty-ui/generated.
+ * To update it, edit the component prop types or design tokens in twenty-ui and run:
+ * npx nx generate:ui twenty-docs
+ */}
+
+### Progress.Root
+
+<ParamField body="Root.aria-label" type="string">
+ Accessible name identifying the measured operation.
+</ParamField>
+
+<ParamField body="Root.aria-labelledby" type="string">
+ ID of the visible label that names the operation.
+</ParamField>
+
+<ParamField body="Root.aria-valuetext" type="string">
+ Human-readable progress value overriding the default formatted value.
+</ParamField>
+
+<ParamField body="Root.children" type="ReactNode">
+ Composed Progress parts and supporting content.
+</ParamField>
+
+<ParamField body="Root.className" type="string | ((state: ProgressRootState) =&gt; string | undefined)">
+ Class applied to this part, or a callback receiving its progress status.
+</ParamField>
+
+<ParamField body="Root.format" type="NumberFormatOptions">
+ Intl.NumberFormat options for the clamped numeric value. The default displays the normalized percentage.
+</ParamField>
+
+<ParamField body="Root.getAriaValueText" type="((formattedValue: string, value: number | null) =&gt; string)">
+ Receives the formatted value and raw value, including null, and returns an accessible value description.
+</ParamField>
+
+<ParamField body="Root.locale" type="LocalesArgument">
+ Locale or locale list used to format the value. Defaults to the runtime locale.
+</ParamField>
+
+<ParamField body="Root.max" type="number" default="100">
+ Inclusive maximum. Defaults to 100.
+</ParamField>
+
+<ParamField body="Root.min" type="number" default="0">
+ Inclusive minimum. Defaults to 0.
+</ParamField>
+
+<ParamField body="Root.ref" type="Ref&lt;HTMLDivElement&gt;">
+ Ref to the root div, or the element composed through Root.render.
+</ParamField>
+
+<ParamField body="Root.render" type="ReactElement&lt;unknown, string | JSXElementConstructor&lt;any&gt;&gt; | ComponentRenderFn&lt;HTMLProps, ProgressRootState&gt;">
+ Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element.
+</ParamField>
+
+<ParamField body="Root.style" type="CSSProperties | ((state: ProgressRootState) =&gt; CSSProperties | undefined)">
+ Inline styles applied to this part, or a callback receiving its progress status.
+</ParamField>
+
+<ParamField body="Root.value" type="number | null" required>
+ Controlled value in the min/max range. Use null for indeterminate progress.
+</ParamField>
+
+### Progress.Track
+
+<ParamField body="Track.children" type="ReactNode">
+ The indicator and optional supporting content.
+</ParamField>
+
+<ParamField body="Track.className" type="string | ((state: ProgressTrackState) =&gt; string | undefined)">
+ Class applied to this part, or a callback receiving its progress status.
+</ParamField>
+
+<ParamField body="Track.ref" type="Ref&lt;HTMLDivElement&gt;">
+ Ref to the track div, or the element composed through Track.render.
+</ParamField>
+
+<ParamField body="Track.render" type="ReactElement&lt;unknown, string | JSXElementConstructor&lt;any&gt;&gt; | ComponentRenderFn&lt;HTMLProps, ProgressTrackState&gt;">
+ Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element.
+</ParamField>
+
+<ParamField body="Track.style" type="CSSProperties | ((state: ProgressTrackState) =&gt; CSSProperties | undefined)">
+ Inline styles applied to this part, or a callback receiving its progress status.
+</ParamField>
+
+### Progress.Indicator
+
+<ParamField body="Indicator.className" type="string | ((state: ProgressIndicatorState) =&gt; string | undefined)">
+ Class applied to this part, or a callback receiving its progress status.
+</ParamField>
+
+<ParamField body="Indicator.ref" type="Ref&lt;HTMLDivElement&gt;">
+ Ref to the indicator div, or the element composed through Indicator.render.
+</ParamField>
+
+<ParamField body="Indicator.render" type="ReactElement&lt;unknown, string | JSXElementConstructor&lt;any&gt;&gt; | ComponentRenderFn&lt;HTMLProps, ProgressIndicatorState&gt;">
+ Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element.
+</ParamField>
+
+<ParamField body="Indicator.style" type="CSSProperties | ((state: ProgressIndicatorState) =&gt; CSSProperties | undefined)">
+ Inline styles applied to this part, or a callback receiving its progress status.
+</ParamField>
+
+### Progress.Value
+
+<ParamField body="Value.children" type="((formattedValue: string | null, value: number | null) =&gt; ReactNode) | null">
+ Optional callback receiving the formatted value and raw value. Indeterminate progress passes indeterminate as formatted text. Without a callback, indeterminate progress displays no content.
+</ParamField>
+
+<ParamField body="Value.className" type="string | ((state: ProgressValueState) =&gt; string | undefined)">
+ Class applied to this part, or a callback receiving its progress status.
+</ParamField>
+
+<ParamField body="Value.ref" type="Ref&lt;HTMLSpanElement&gt;">
+ Ref to the value span, or the element composed through Value.render.
+</ParamField>
+
+<ParamField body="Value.render" type="ReactElement&lt;unknown, string | JSXElementConstructor&lt;any&gt;&gt; | ComponentRenderFn&lt;HTMLProps, ProgressValueState&gt;">
+ Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element.
+</ParamField>
+
+<ParamField body="Value.style" type="CSSProperties | ((state: ProgressValueState) =&gt; CSSProperties | undefined)">
+ Inline styles applied to this part, or a callback receiving its progress status.
+</ParamField>
+
+### Progress.Label
+
+<ParamField body="Label.children" type="ReactNode">
+ Visible text that supplies the accessible name of the root.
+</ParamField>
+
+<ParamField body="Label.className" type="string | ((state: ProgressLabelState) =&gt; string | undefined)">
+ Class applied to this part, or a callback receiving its progress status.
+</ParamField>
+
+<ParamField body="Label.ref" type="Ref&lt;HTMLSpanElement&gt;">
+ Ref to the label span, or the element composed through Label.render.
+</ParamField>
+
+<ParamField body="Label.render" type="ReactElement&lt;unknown, string | JSXElementConstructor&lt;any&gt;&gt; | ComponentRenderFn&lt;HTMLProps, ProgressLabelState&gt;">
+ Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element.
+</ParamField>
+
+<ParamField body="Label.style" type="CSSProperties | ((state: ProgressLabelState) =&gt; CSSProperties | undefined)">
+ Inline styles applied to this part, or a callback receiving its progress status.
+</ParamField>
diff --git a/packages/twenty-docs/ui/components/data-display/metric-row.mdx b/packages/twenty-docs/ui/components/data-display/metric-row.mdx
index e3e019f7e41..80ecbeeea33 100644
--- a/packages/twenty-docs/ui/components/data-display/metric-row.mdx
+++ b/packages/twenty-docs/ui/components/data-display/metric-row.mdx
@@ -49,7 +49,7 @@ export const CompletedMetric = () => (
## Composition and accessibility
-Label content accepts nodes. Its accessible text names the progress ring through `aria-labelledby`, including nested text. Provide a meaningful visible label. A string value is also exposed as its accessible value text. For formatted value content, supply `progressValueText` when a percentage does not describe the metric fully. This text overrides the string value fallback. Without it, other content keeps the ring's percentage value text. The optional `startIcon` node is decorative. The caller controls its dimensions and stroke.
+Label content accepts nodes. Its accessible text names the progress ring through `aria-labelledby`, including nested text. Provide a meaningful visible label. A nonempty string value is also exposed as its accessible value text. For formatted value content, supply `progressValueText` when a percentage does not describe the metric fully. This text overrides the string value fallback. Without it, other content keeps the ring's percentage value text. An empty `progressValueText` also uses the percentage, including when `value` is a string. The optional `startIcon` node is decorative. The caller controls its dimensions and stroke.
```tsx
import { MetricRow } from 'twenty-ui/components/data-display';
diff --git a/packages/twenty-docs/ui/primitives/feedback/progress-bar.mdx b/packages/twenty-docs/ui/primitives/feedback/progress-bar.mdx
index c4ffe125baf..8d5511d2d0e 100644
--- a/packages/twenty-docs/ui/primitives/feedback/progress-bar.mdx
+++ b/packages/twenty-docs/ui/primitives/feedback/progress-bar.mdx
@@ -1,13 +1,12 @@
---
title: ProgressBar
-description: Show measured progress with a horizontal bar.
+description: Show measured or indeterminate progress with a horizontal bar.
---
import { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';
-
import ProgressBarReference from '/snippets/ui/generated/feedback/progress-bar.mdx';
-`ProgressBar` displays a value from 0 to 100 and exposes progressbar semantics. Give it an `ariaLabel` that identifies the operation, and show a text status when users need the numeric value.
+`ProgressBar` supplies a horizontal appearance for [Progress](/ui/primitives/feedback/progress). It preserves the complete root contract, including native attributes, refs, render composition, formatting, custom ranges, and indeterminate progress. Give it an `aria-label` that identifies the operation.
<StoryEmbed
storyId="ui-feedback-progressbar-progressbar--default"
@@ -20,29 +19,47 @@ import ProgressBarReference from '/snippets/ui/generated/feedback/progress-bar.m
import { ProgressBar } from 'twenty-ui/primitives/feedback';
import { Text } from 'twenty-ui/primitives/typography';
-type ImportProgressProps = { percentage: number };
+type ImportProgressProps = { importedRecords: number | null };
-export const ImportProgress = ({ percentage }: ImportProgressProps) => (
+export const ImportProgress = ({ importedRecords }: ImportProgressProps) => (
<>
- <Text>Importing records: {percentage}%</Text>
+ <Text>Importing records: {importedRecords ?? 'preparing'}</Text>
<ProgressBar
- value={percentage}
- ariaLabel="Importing records"
+ value={importedRecords}
+ max={1000}
+ aria-label="Importing records"
withBorderRadius
/>
</>
);
```
-## State ownership
+## State ownership and ranges
+
+`value` is required and controlled by the application. There is no `defaultValue` mode. The component does not start a request or advance progress by itself. Pass `null` when progress is unknown. Non-finite values also remain indeterminate.
+
+`min` defaults to `0`, and `max` defaults to `100`. Finite values are clamped to the range for the semantic value and normalized fill. A value of `70` in the range `20` to `120` fills half the bar and reports `50%`, while `aria-valuenow` stays `70`.
+
+<StoryEmbed
+ storyId="ui-feedback-progressbar-progressbar--custom-range"
+ title="A nonzero minimum and custom maximum"
+/>
-`value` is required and controlled by the application. There is no `defaultValue` mode. The component does not start a request or advance numeric progress by itself. Use [Loader](/ui/primitives/feedback/loader) when progress is unknown.
+Use `aria-valuetext`, `getAriaValueText`, `locale`, and `format` as described in [Progress](/ui/primitives/feedback/progress). Use composed Progress parts when labels and values need their own visible layout.
Use [Toast](/ui/components/feedback/toast) for notifications with a dismiss countdown and hover pause.
-## Appearance
+## Appearance and composition
+
+`size` selects a 6px or 8px track. `barColor` and `backgroundColor` accept CSS colors, including theme variables. `withBorderRadius` rounds the track and indicator. `withMinimumFillWidth` keeps a small cosmetic fill only between the minimum and completion. This minimum is at most 12px and half the track width, so a narrow track still distinguishes incomplete progress from completion. It does not fill an empty bar or change semantic values.
+
+Native attributes, `className`, `style`, and `ref` target the root. `className` and `style` can receive the progress state. `render` can replace the root while preserving its semantics. Indeterminate progress has its own appearance without reporting a numeric percentage. Reduced-motion preferences disable fill transitions and indeterminate motion.
+
+Compose [Progress parts](/ui/primitives/feedback/progress) for custom layouts or feature animation. Feature timing, grow-in, glints, springs, and completion callbacks belong to the application composition.
+
+## Migration
-`barColor` and `backgroundColor` accept CSS colors, including theme variables. `withBorderRadius` rounds the track and indicator. `className` styles the root; other native attributes are not forwarded.
+Replace `ariaLabel` with native `aria-label`. The `withGrowIn`, `withGlint`, `withSpringFill`, and `onGrowInComplete` props are removed. Implement their appearance, timing, and completion callbacks in an application composition using [Progress parts](/ui/primitives/feedback/progress). Native `onAnimationEnd` remains available on the root.
## Props
diff --git a/packages/twenty-docs/ui/primitives/feedback/progress-ring.mdx b/packages/twenty-docs/ui/primitives/feedback/progress-ring.mdx
index 15949660153..7d4b05cc311 100644
--- a/packages/twenty-docs/ui/primitives/feedback/progress-ring.mdx
+++ b/packages/twenty-docs/ui/primitives/feedback/progress-ring.mdx
@@ -1,12 +1,12 @@
---
title: ProgressRing
-description: Show a known progress value in a compact circular indicator.
+description: Show measured or indeterminate progress in a compact circular indicator.
---
import { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';
import ProgressRingReference from '/snippets/ui/generated/feedback/progress-ring.mdx';
-`ProgressRing` shows a controlled percentage with accessible progressbar semantics. It can display a preformatted value beside the ring.
+`ProgressRing` supplies a circular appearance for [Progress](/ui/primitives/feedback/progress). It shares the root's custom range, null, formatting, labeling, native prop, ref, and render contract. Optional children display a preformatted value beside the ring.
<StoryEmbed
storyId="ui-feedback-progressring-progressring--default"
@@ -16,14 +16,15 @@ import ProgressRingReference from '/snippets/ui/generated/feedback/progress-ring
## Usage
-Supply a value from 0 to 100 and an accessible name. Use `aria-valuetext` when a formatted value explains progress more clearly than a percentage.
+Supply the raw controlled value and an accessible name. Use `aria-valuetext` when a formatted value explains progress more clearly than a percentage.
```tsx
import { ProgressRing } from 'twenty-ui/primitives/feedback';
export const ImportProgress = () => (
<ProgressRing
- value={60}
+ value={600}
+ max={1000}
aria-label="Importing records"
aria-valuetext="600 of 1,000 records"
>
@@ -32,19 +33,29 @@ export const ImportProgress = () => (
);
```
-Use `aria-labelledby` to associate the ring with an existing visible label. The optional children display a value; they do not provide the ring's accessible name.
+Use `aria-labelledby` to associate the ring with an existing visible label, or compose `Progress.Label` as a child. Preformatted children do not automatically provide the ring's accessible name.
-## Controlled progress
+## Controlled progress and ranges
-The application calculates `value` and formats the displayed text. The ring does not fetch data, advance progress, or calculate quotas. Values outside 0 to 100 are bounded to that range, including infinite values. `NaN` renders as zero. Displayed children stay unchanged.
+The application calculates `value` and formats display content. The ring does not fetch data, advance progress, or calculate quotas. `min` defaults to `0`, and `max` defaults to `100`. Finite values are clamped to the range for semantic values and arc geometry. The arc fills by the normalized percentage, including when the minimum is nonzero.
-Use [Loader](/ui/primitives/feedback/loader) for indeterminate loading, [ProgressBar](/ui/primitives/feedback/progress-bar) for horizontal progress, or [MetricRow](/ui/components/data-display/metric-row) for a label and aligned value.
+<StoryEmbed
+ storyId="ui-feedback-progressring-progressring--custom-range"
+ title="Circular progress in a custom range"
+ height={140}
+/>
+
+Pass `value={null}` for indeterminate progress. The ring omits `aria-valuenow` and displays an indeterminate arc. Non-finite values also remain indeterminate; they do not become zero or completion. Display content stays controlled by the application.
+
+Use `locale`, `format`, and `getAriaValueText` as described in [Progress](/ui/primitives/feedback/progress). Compose `Progress.Value` to display the root's formatted value.
+
+Use [ProgressBar](/ui/primitives/feedback/progress-bar) for horizontal progress or [MetricRow](/ui/components/data-display/metric-row) for a label and aligned value.
-## Appearance and motion
+## Appearance and composition
-`size="md"` renders a 16px ring; `size="sm"` renders a 14px ring. Both use a 2px stroke and fill clockwise from the top. `barColor` accepts CSS colors, including theme variables.
+`size="md"` renders a 16px ring; `size="sm"` renders a 14px ring. Both use a 2px stroke and fill clockwise from the top. `barColor` accepts CSS colors, including theme variables. The SVG is decorative and hidden from accessibility APIs.
-Value changes animate for 300ms. The transition is disabled when the user prefers reduced motion. Native attributes, `className`, `style`, and `ref` target the outer progress element. `render` can replace that element while retaining the progress semantics.
+Value changes animate for 300ms. Reduced-motion preferences disable the transition and indeterminate rotation. Native attributes, `className`, `style`, and `ref` target the outer progress element. `className` and `style` can receive the progress state. `render` can replace the root while retaining its semantics.
## Props
diff --git a/packages/twenty-docs/ui/primitives/feedback/progress.mdx b/packages/twenty-docs/ui/primitives/feedback/progress.mdx
new file mode 100644
index 00000000000..05a31354548
--- /dev/null
+++ b/packages/twenty-docs/ui/primitives/feedback/progress.mdx
@@ -0,0 +1,97 @@
+---
+title: Progress
+description: Compose accessible progress with shared range, labeling, and value semantics.
+---
+
+import { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';
+import ProgressReference from '/snippets/ui/generated/feedback/progress.mdx';
+
+`Progress` exposes the installed Base UI parts: `Root`, `Track`, `Indicator`, `Label`, and `Value`. Import them from `twenty-ui/primitives/feedback`. Use [ProgressBar](/ui/primitives/feedback/progress-bar) or [ProgressRing](/ui/primitives/feedback/progress-ring) for a convenient appearance with the same semantic contract.
+
+<StoryEmbed
+ storyId="ui-feedback-progress--default"
+ title="Composed progress example"
+ height={180}
+/>
+
+## Compose progress
+
+`Root` owns the controlled value and accessible progressbar semantics. `Label` supplies its accessible name. `Value` displays the formatted value. `Track` and `Indicator` describe the visual fill; the indicator width comes from the root's normalized range. The parts do not impose an appearance.
+
+```tsx
+import { Progress } from 'twenty-ui/primitives/feedback';
+
+export const ImportProgress = () => (
+ <Progress.Root value={70} min={20} max={120} style={{ width: 240 }}>
+ <Progress.Label>Importing records</Progress.Label>
+ <Progress.Value />
+ <Progress.Track
+ style={{ height: 8, background: 'var(--t-background-tertiary)' }}
+ >
+ <Progress.Indicator
+ style={{ background: 'var(--t-font-color-primary)' }}
+ />
+ </Progress.Track>
+ </Progress.Root>
+);
+```
+
+This range displays `50%` while `aria-valuenow` is `70`, `aria-valuemin` is `20`, and `aria-valuemax` is `120`. The application owns requests, timing, and progress updates. There is no `defaultValue` or automatic advancement.
+
+## Values, ranges, and indeterminate progress
+
+`min` defaults to `0`, and `max` defaults to `100`. Supply finite bounds with `min < max`. Finite values outside the range are clamped for the semantic value, formatted value, and visual fill. Completion occurs at the maximum. Changing the range recalculates the percentage without changing the raw value supplied by the application.
+
+Pass `value={null}` when the amount of progress is unknown. The root then has indeterminate status, omits `aria-valuenow`, and uses `indeterminate progress` as its default accessible value text. Non-finite values also remain indeterminate; they are not converted to zero. The raw `Indicator` has no computed percentage width in that state, so the composition chooses its indeterminate appearance.
+
+```tsx
+import { ProgressBar } from 'twenty-ui/primitives/feedback';
+
+export const PendingImport = () => (
+ <ProgressBar value={null} aria-label="Preparing the import" />
+);
+```
+
+## Labels and formatting
+
+Compose `Progress.Label` inside `Root`, or set native `aria-label` or `aria-labelledby`. Use `aria-valuetext` for a human-readable alternative when a percentage is insufficient.
+
+The default formatter displays the normalized percentage. `locale` and `format` retain the installed `Intl.NumberFormat` contract; an explicit `format` formats the clamped numeric value. `getAriaValueText(formattedValue, value)` receives that formatted text and the raw application value, including `null`. It changes the accessible value text without changing the fill.
+
+```tsx
+import { Progress } from 'twenty-ui/primitives/feedback';
+
+export const RecordCount = () => (
+ <Progress.Root
+ value={600}
+ max={1000}
+ format={{ style: 'decimal' }}
+ getAriaValueText={(formattedValue) => `${formattedValue} of 1,000 records`}
+ >
+ <Progress.Label>Importing records</Progress.Label>
+ <Progress.Value>
+ {(formattedValue) => `${formattedValue} / 1,000`}
+ </Progress.Value>
+ </Progress.Root>
+);
+```
+
+`Progress.Value` receives both the formatted value and raw value through its optional child callback. For indeterminate progress, the callback receives `indeterminate` as formatted text; without a callback, the value part displays no content. Display content does not automatically become the accessible name or accessible value text.
+
+## Native props, refs, and composition
+
+| Part | Default DOM and ref target |
+| ----------- | -------------------------------------- |
+| `Root` | Outer `div` with progressbar semantics |
+| `Track` | Track `div` |
+| `Indicator` | Fill `div` |
+| `Label` | Label `span` |
+| `Value` | Value `span` |
+
+Every part preserves native props, refs, and the installed `render` composition contract. Forward the supplied props and ref when replacing an element. `className`, `style`, and `render` callbacks receive the public state with `status`: `progressing`, `complete`, or `indeterminate`. State attributes make the same status available to styles.
+
+The entry point exports `ProgressStatus` and the `Props` and `State` types for every part, including `ProgressRootProps`, `ProgressRootState`, `ProgressIndicatorProps`, and `ProgressIndicatorState`. Each part forwards native event handlers. Applications own feature choreography and completion callbacks.
+
+## Props
+
+<ProgressReference />
diff --git a/packages/twenty-docs/ui/primitives/overview.mdx b/packages/twenty-docs/ui/primitives/overview.mdx
index 1b79b579d83..af343c0f698 100644
--- a/packages/twenty-docs/ui/primitives/overview.mdx
+++ b/packages/twenty-docs/ui/primitives/overview.mdx
@@ -92,13 +92,13 @@ Use a native button for button-like parts. On parts that expose `nativeButton`,
Each page includes usage examples, interaction guidance, and a generated API reference.
-| Family | Primitives |
-| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Accessibility | [VisuallyHidden](/ui/primitives/accessibility/visually-hidden) |
-| Data display | [Avatar](/ui/primitives/data-display/avatar), [Chip](/ui/primitives/data-display/chip), [ColorSample](/ui/primitives/data-display/color-sample), [Badge](/ui/primitives/data-display/badge), [Status](/ui/primitives/data-display/status), [Tag](/ui/primitives/data-display/tag) |
-| Feedback | [Banner](/ui/primitives/feedback/banner), [Loader](/ui/primitives/feedback/loader), [ProgressBar](/ui/primitives/feedback/progress-bar), [ProgressRing](/ui/primitives/feedback/progress-ring) |
+| Family | Primitives |
+| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Accessibility | [VisuallyHidden](/ui/primitives/accessibility/visually-hidden) |
+| Data display | [Avatar](/ui/primitives/data-display/avatar), [Chip](/ui/primitives/data-display/chip), [ColorSample](/ui/primitives/data-display/color-sample), [Badge](/ui/primitives/data-display/badge), [Status](/ui/primitives/data-display/status), [Tag](/ui/primitives/data-display/tag) |
+| Feedback | [Banner](/ui/primitives/feedback/banner), [Loader](/ui/primitives/feedback/loader), [Progress](/ui/primitives/feedback/progress), [ProgressBar](/ui/primitives/feedback/progress-bar), [ProgressRing](/ui/primitives/feedback/progress-ring) |
| Forms | [Button](/ui/primitives/input/button), [ButtonGroup](/ui/primitives/input/button-group), [Checkbox](/ui/primitives/input/checkbox), [Field](/ui/primitives/input/field), [Input](/ui/primitives/input/input), [InputGroup](/ui/primitives/input/input-group), [Radio](/ui/primitives/input/radio), [RadioGroup](/ui/primitives/input/radio-group), [Select](/ui/primitives/input/select), [Slider](/ui/primitives/input/slider), [Switch](/ui/primitives/input/switch), [Textarea](/ui/primitives/input/textarea) |
-| Layout | [Collapsible](/ui/primitives/layout/collapsible), [Separator](/ui/primitives/layout/separator), [ResizeHandle](/ui/primitives/layout/resize-handle), [DirectionProvider](/ui/primitives/layout/direction-provider) |
-| Navigation | [ListItem](/ui/primitives/navigation/list-item), [Tabs](/ui/primitives/navigation/tabs) |
-| Surfaces | [AlertDialog](/ui/primitives/surfaces/alert-dialog), [Card](/ui/primitives/surfaces/card), [Dialog](/ui/primitives/surfaces/dialog), [Popover](/ui/primitives/surfaces/popover), [Tooltip](/ui/primitives/surfaces/tooltip) |
-| Typography | [Heading](/ui/primitives/typography/heading), [OverflowingTextWithTooltip](/ui/primitives/typography/overflowing-text-with-tooltip), [Text](/ui/primitives/typography/text) |
+| Layout | [Collapsible](/ui/primitives/layout/collapsible), [Separator](/ui/primitives/layout/separator), [ResizeHandle](/ui/primitives/layout/resize-handle), [DirectionProvider](/ui/primitives/layout/direction-provider) |
+| Navigation | [ListItem](/ui/primitives/navigation/list-item), [Tabs](/ui/primitives/navigation/tabs) |
+| Surfaces | [AlertDialog](/ui/primitives/surfaces/alert-dialog), [Card](/ui/primitives/surfaces/card), [Dialog](/ui/primitives/surfaces/dialog), [Popover](/ui/primitives/surfaces/popover), [Tooltip](/ui/primitives/surfaces/tooltip) |
+| Typography | [Heading](/ui/primitives/typography/heading), [OverflowingTextWithTooltip](/ui/primitives/typography/overflowing-text-with-tooltip), [Text](/ui/primitives/typography/text) |
diff --git a/packages/twenty-front-component-renderer/src/__stories__/twenty-ui-gallery/README.md b/packages/twenty-front-component-renderer/src/__stories__/twenty-ui-gallery/README.md
index 0abfbba7d37..7422b2ad61c 100644
--- a/packages/twenty-front-component-renderer/src/__stories__/twenty-ui-gallery/README.md
+++ b/packages/twenty-front-component-renderer/src/__stories__/twenty-ui-gallery/README.md
@@ -31,6 +31,8 @@ AvatarGroup checks derived counts, partially loaded totals, custom overflow and
Badge checks ordinary node content, compact sizes, colors and circle shape. Its React and Preact fixtures keep count clamping and zero visibility in the caller, and verify native span attributes, refs and pointer handlers plus explicit button and link render composition with keyboard activation.
+Progress composes Root, Track, Indicator, Label and Value alongside the ProgressBar and ProgressRing presets. The shared React and Preact fixture covers native names, attributes, refs, render composition and pointer handlers, nonzero minima, changing ranges and values, clamped boundaries, indeterminate progress and agreement between bar fill and ring geometry. The fixture also checks zero and complete fill and a minimum fill that stays below the full width of a narrow track. SVG bindings currently omit the `focusable` attribute; these cases verify `aria-hidden` and that keyboard Tab skips the decorative SVG.
+
Scenarios share their checks between runtimes where behavior matches. The story
file contains the metadata and named entries; `utils/` holds the story factory,
shared assertions, render checks, interaction checks, and known-failure
@@ -66,6 +68,7 @@ effect within the interaction timeout.
| `twenty-ui-overflowing-list` | OverflowingList |
| `twenty-ui-phone-country-picker` | PhoneCountryPicker |
| `twenty-ui-currency-picker` | CurrencyPicker |
+| `twenty-ui-progress` | Progress parts, ProgressBar, ProgressRing and MetricRow (native composition, range normalization, indeterminate values and geometry) |
| `twenty-ui-popover` | Popover |
| `twenty-ui-card-composition` | Card (native parts and refs, render composition, display semantics, button/link ownership and nested controls) |
| `twenty-ui-dialog` | SDK `openCommandConfirmationModal` confirmation request |
diff --git a/packages/twenty-front-component-renderer/src/__stories__/twenty-ui-gallery/twenty-ui-feedback-gallery.front-component.tsx b/packages/twenty-front-component-renderer/src/__stories__/twenty-ui-gallery/twenty-ui-feedback-gallery.front-component.tsx
index cd65b45232b..4d0de2211c0 100644
--- a/packages/twenty-front-component-renderer/src/__stories__/twenty-ui-gallery/twenty-ui-feedback-gallery.front-component.tsx
+++ b/packages/twenty-front-component-renderer/src/__stories__/twenty-ui-gallery/twenty-ui-feedback-gallery.front-component.tsx
@@ -88,7 +88,7 @@ const FEEDBACK_ENTRIES: GalleryEntry[] = [
},
{
name: 'ProgressBar',
- node: <ProgressBar value={50} ariaLabel="Progress" />,
+ node: <ProgressBar value={50} aria-label="Progress" />,
},
{
name: 'Skeleton',
diff --git a/packages/twenty-front-component-renderer/src/__stories__/twenty-ui-gallery/twenty-ui-progress.front-component.tsx b/packages/twenty-front-component-renderer/src/__stories__/twenty-ui-gallery/twenty-ui-progress.front-component.tsx
index 9efa91ccfb3..17c12189621 100644
--- a/packages/twenty-front-component-renderer/src/__stories__/twenty-ui-gallery/twenty-ui-progress.front-component.tsx
+++ b/packages/twenty-front-component-renderer/src/__stories__/twenty-ui-gallery/twenty-ui-progress.front-component.tsx
@@ -1,37 +1,132 @@
-import { useState } from 'react';
+import { createElement, useState } from 'react';
import { defineFrontComponent } from 'twenty-sdk/define';
+import { isDefined } from 'twenty-shared/utils';
import { MetricRow } from 'twenty-ui/components/data-display';
import { IconDatabase } from 'twenty-ui/icon';
-import { ProgressRing } from 'twenty-ui/primitives/feedback';
+import {
+ Progress,
+ ProgressBar,
+ ProgressRing,
+} from 'twenty-ui/primitives/feedback';
import { Button } from 'twenty-ui/primitives/input';
import { Text } from 'twenty-ui/primitives/typography';
import { TwentyUiGalleryCard } from '@/__stories__/shared/front-components/twenty-ui-gallery-card';
const ProgressExample = () => {
- const [progress, setProgress] = useState(25);
+ const [progress, setProgress] = useState<number | null>(25);
+ const [range, setRange] = useState({ min: 10, max: 70 });
+ const [pointerEntries, setPointerEntries] = useState(0);
+
+ const recordProgressRef = (element: HTMLElement | null) => {
+ if (isDefined(element)) {
+ element.dataset.refTag = element.tagName;
+ }
+ };
return (
- <TwentyUiGalleryCard title="Determinate progress">
+ <TwentyUiGalleryCard title="Progress parts, ranges and native roots">
+ <ProgressBar
+ min={range.min}
+ max={range.max}
+ value={progress}
+ aria-label="Import bar"
+ id="import-bar"
+ title="Import bar title"
+ lang="fr"
+ className="custom-progress-bar"
+ style={{ marginTop: 7, width: 200 }}
+ render={<section data-composed="bar" />}
+ ref={recordProgressRef}
+ onMouseEnter={() => setPointerEntries((entries) => entries + 1)}
+ />
<ProgressRing
+ min={range.min}
+ max={range.max}
value={progress}
- aria-label="Importing records"
- aria-valuetext={`${progress} of 100 records`}
+ aria-label="Import ring"
+ id="import-ring"
+ title="Import ring title"
+ lang="fr"
+ className="custom-progress-ring"
+ style={{ marginTop: 9 }}
+ render={(props, state) =>
+ createElement('article', {
+ ...props,
+ 'data-composed': 'ring',
+ 'data-render-status': state.status,
+ })
+ }
+ ref={recordProgressRef}
>
- {progress} / 100
+ {isDefined(progress) ? `${progress} records` : 'Waiting for records'}
</ProgressRing>
+ <Progress.Root
+ min={range.min}
+ max={range.max}
+ value={progress}
+ render={<section data-composed="parts" />}
+ ref={recordProgressRef}
+ >
+ <Progress.Label
+ id="progress-records-label"
+ render={<strong />}
+ ref={recordProgressRef}
+ >
+ Composed records
+ </Progress.Label>
+ <Progress.Track
+ aria-label="Composed track"
+ style={{ width: 200, height: 8 }}
+ render={<div data-composed="track" />}
+ ref={recordProgressRef}
+ >
+ <Progress.Indicator
+ aria-label="Composed indicator"
+ style={{ backgroundColor: 'rgb(20, 80, 120)' }}
+ render={(props, state) =>
+ createElement('div', {
+ ...props,
+ 'data-render-status': state.status,
+ })
+ }
+ ref={recordProgressRef}
+ />
+ </Progress.Track>
+ <Progress.Value
+ aria-label="Composed value"
+ render={<output />}
+ ref={recordProgressRef}
+ >
+ {(formattedValue, value) =>
+ isDefined(value) ? `${formattedValue} of records` : 'Waiting'
+ }
+ </Progress.Value>
+ </Progress.Root>
+ <ProgressBar
+ value={1}
+ aria-label="Compact progress"
+ style={{ width: 8 }}
+ />
<MetricRow
startIcon={<IconDatabase size={14} />}
- value={<Text render={<bdi />}>{progress} / 100 GB</Text>}
- progress={progress}
- progressValueText={`${progress} of 100 gigabytes used`}
+ value={<Text render={<bdi />}>25 / 100 GB</Text>}
+ progress={25}
+ progressValueText="25 of 100 gigabytes used"
>
<Text render={<strong />}>Storage</Text>
</MetricRow>
<MetricRow value={0}>Completed imports</MetricRow>
<ProgressRing value={-10} size="sm" aria-label="Empty progress" />
<ProgressRing value={120} size="sm" aria-label="Complete progress" />
- <Button onClick={() => setProgress(75)}>Advance progress</Button>
+ <Button onClick={() => setProgress(55)}>Advance progress</Button>
+ <Button onClick={() => setRange({ min: 30, max: 130 })}>
+ Change progress range
+ </Button>
+ <Button onClick={() => setProgress(null)}>Wait for records</Button>
+ <Button onClick={() => setProgress(150)}>Complete import</Button>
+ <Button onClick={() => setProgress(30)}>Reset import</Button>
+ <output aria-label="Progress pointer entries">{pointerEntries}</output>
</TwentyUiGalleryCard>
);
};
@@ -40,6 +135,6 @@ export default defineFrontComponent({
universalIdentifier: 'bdc37e74-31d3-4a94-9805-03bd38f40ddf',
name: 'twenty-ui-progress',
description:
- 'Controlled progress, formatted metric values and accessible names in the sandbox',
+ 'Progress composition, normalized ranges and native props in the sandbox',
component: ProgressExample,
});
diff --git a/packages/twenty-front-component-renderer/src/__stories__/twenty-ui-gallery/utils/calloutTest.ts b/packages/twenty-front-component-renderer/src/__stories__/twenty-ui-gallery/utils/calloutTest.ts
index f070db1f2aa..eb6ddc3593e 100644
--- a/packages/twenty-front-component-renderer/src/__stories__/twenty-ui-gallery/utils/calloutTest.ts
+++ b/packages/twenty-front-component-renderer/src/__stories__/twenty-ui-gallery/utils/calloutTest.ts
@@ -7,6 +7,11 @@ import { bannerTest } from '@/__stories__/twenty-ui-gallery/utils/bannerTest';
export const calloutTest: TwentyUiGalleryPlayFunction = async (context) => {
await bannerTest(context);
const canvas = within(context.canvasElement);
+ const progress = canvas.getByRole('progressbar', { name: 'Progress' });
+ expect(progress).toHaveAttribute('aria-valuenow', '50');
+ expect(progress).toHaveAttribute('aria-valuemin', '0');
+ expect(progress).toHaveAttribute('aria-valuemax', '100');
+ expect(progress).toHaveAttribute('aria-valuetext', '50%');
const callout = canvas.getByRole('region', { name: 'Import notice' });
await waitFor(() =>
expect(callout).toHaveAttribute('data-ref-tag', 'HTML-SECTION'),
diff --git a/packages/twenty-front-component-renderer/src/__stories__/twenty-ui-gallery/utils/progressTest.ts b/packages/twenty-front-component-renderer/src/__stories__/twenty-ui-gallery/utils/progressTest.ts
index 8e1e26cf78c..8c3f2bf1a11 100644
--- a/packages/twenty-front-component-renderer/src/__stories__/twenty-ui-gallery/utils/progressTest.ts
+++ b/packages/twenty-front-component-renderer/src/__stories__/twenty-ui-gallery/utils/progressTest.ts
@@ -1,34 +1,164 @@
import { expect, userEvent, waitFor, within } from 'storybook/test';
+import { isDefined } from 'twenty-shared/utils';
import { errorHandler } from '@/__stories__/shared/test-utils/createFrontComponentStoryMeta';
import { expectFrontComponentMounted } from '@/__stories__/shared/test-utils/matchers/expectFrontComponentMounted';
import { type TwentyUiGalleryPlayFunction } from '@/__stories__/twenty-ui-gallery/types/TwentyUiGalleryPlayFunction';
+const expectRingGeometry = ({
+ ring,
+ fraction,
+}: {
+ ring: HTMLElement;
+ fraction: number;
+}) => {
+ const circle = ring.querySelector('circle:last-child');
+ if (!isDefined(circle)) {
+ throw new Error('Progress ring indicator is missing');
+ }
+
+ const circumference = Number(circle.getAttribute('stroke-dasharray'));
+ const offset = Number(circle.getAttribute('stroke-dashoffset'));
+ expect(circumference).toBeGreaterThan(0);
+ expect(offset / circumference).toBeCloseTo(1 - fraction, 5);
+};
+
+const expectProgressGeometry = ({
+ bar,
+ ring,
+ indicator,
+ fraction,
+}: {
+ bar: HTMLElement;
+ ring: HTMLElement;
+ indicator: HTMLElement;
+ fraction: number;
+}) => {
+ const barIndicator = bar.querySelector<HTMLElement>('div > div');
+ if (!isDefined(barIndicator)) {
+ throw new Error('Progress bar indicator is missing');
+ }
+
+ expect(indicator.style.width).toBe(`${fraction * 100}%`);
+ expect(barIndicator.style.width).toBe(`${fraction * 100}%`);
+ expectRingGeometry({ ring, fraction });
+};
+
+const expectProgressValues = ({
+ roots,
+ value,
+ min,
+ max,
+ valueText,
+}: {
+ roots: HTMLElement[];
+ value: number;
+ min: number;
+ max: number;
+ valueText: string;
+}) => {
+ for (const root of roots) {
+ expect(root).toHaveAttribute('aria-valuenow', String(value));
+ expect(root).toHaveAttribute('aria-valuemin', String(min));
+ expect(root).toHaveAttribute('aria-valuemax', String(max));
+ expect(root).toHaveAttribute('aria-valuetext', valueText);
+ }
+};
+
export const progressTest: TwentyUiGalleryPlayFunction = async ({
canvasElement,
}) => {
const canvas = within(canvasElement);
await expectFrontComponentMounted(canvas);
- const importProgress = canvas.getByRole('progressbar', {
- name: 'Importing records',
+ const bar = canvas.getByRole('progressbar', { name: 'Import bar' });
+ const ring = canvas.getByRole('progressbar', { name: 'Import ring' });
+ const composed = await canvas.findByRole('progressbar', {
+ name: 'Composed records',
});
- const storageProgress = canvas.getByRole('progressbar', {
- name: 'Storage',
+ const indicator = canvas.getByLabelText('Composed indicator');
+ const track = canvas.getByLabelText('Composed track');
+ const value = canvas.getByLabelText('Composed value');
+ const label = canvas.getByText('Composed records');
+ const roots = [bar, ring, composed];
+
+ expectProgressValues({
+ roots,
+ value: 25,
+ min: 10,
+ max: 70,
+ valueText: '25%',
});
+ expectProgressGeometry({ bar, ring, indicator, fraction: 0.25 });
+ expect(value).toHaveTextContent('25% of records');
+ expect(value).toHaveAttribute('aria-hidden', 'true');
+ expect(composed).toHaveAttribute('aria-labelledby', label.id);
+ expect(composed).toHaveAttribute('data-composed', 'parts');
+ expect(track).toHaveAttribute('data-composed', 'track');
+ expect(indicator).toHaveAttribute('data-render-status', 'progressing');
+ expect(ring).toHaveAttribute('data-render-status', 'progressing');
+
+ expect(bar.tagName).toBe('SECTION');
+ expect(bar).toHaveAttribute('id', 'import-bar');
+ expect(bar).toHaveAttribute('title', 'Import bar title');
+ expect(bar).toHaveAttribute('lang', 'fr');
+ expect(bar).toHaveClass('custom-progress-bar');
+ expect(bar).toHaveStyle({ marginTop: '7px' });
+ expect(ring.tagName).toBe('ARTICLE');
+ expect(ring).toHaveAttribute('id', 'import-ring');
+ expect(ring).toHaveAttribute('title', 'Import ring title');
+ expect(ring).toHaveAttribute('lang', 'fr');
+ expect(ring).toHaveClass('custom-progress-ring');
+ expect(ring).toHaveStyle({ marginTop: '9px' });
+ const decorativeSvg = ring.querySelector('svg');
+ if (!isDefined(decorativeSvg)) {
+ throw new Error('Decorative progress SVG is missing');
+ }
+
+ expect(decorativeSvg).toHaveAttribute('aria-hidden', 'true');
+ expect(decorativeSvg.tabIndex).toBe(-1);
- expect(importProgress).toHaveAttribute('aria-valuenow', '25');
- expect(importProgress).toHaveAttribute('aria-valuemin', '0');
- expect(importProgress).toHaveAttribute('aria-valuemax', '100');
- expect(importProgress).toHaveAttribute('aria-valuetext', '25 of 100 records');
- expect(storageProgress).toHaveAttribute('aria-valuenow', '25');
- expect(storageProgress).toHaveAttribute(
- 'aria-valuetext',
- '25 of 100 gigabytes used',
+ await waitFor(() => {
+ expect(bar).toHaveAttribute('data-ref-tag', 'HTML-SECTION');
+ expect(ring).toHaveAttribute('data-ref-tag', 'HTML-ARTICLE');
+ expect(composed).toHaveAttribute('data-ref-tag', 'HTML-SECTION');
+ expect(track).toHaveAttribute('data-ref-tag', 'HTML-DIV');
+ expect(indicator).toHaveAttribute('data-ref-tag', 'HTML-DIV');
+ expect(label).toHaveAttribute('data-ref-tag', 'HTML-STRONG');
+ expect(value).toHaveAttribute('data-ref-tag', 'HTML-OUTPUT');
+ });
+ await userEvent.tab();
+ expect(
+ canvas.getByRole('button', { name: 'Advance progress' }),
+ ).toHaveFocus();
+ expect(decorativeSvg).not.toHaveFocus();
+ await userEvent.hover(bar);
+ await waitFor(() =>
+ expect(canvas.getByLabelText('Progress pointer entries')).toHaveTextContent(
+ '1',
+ ),
);
+
+ const compact = canvas.getByRole('progressbar', { name: 'Compact progress' });
+ const compactIndicator = compact.firstElementChild?.firstElementChild;
+ if (!isDefined(compactIndicator)) {
+ throw new Error('Compact bar indicator is missing');
+ }
+
+ expect(compact).toHaveAttribute('aria-valuenow', '1');
+ await waitFor(() => {
+ expect(compactIndicator.getBoundingClientRect().width).toBe(4);
+ expect(compactIndicator.getBoundingClientRect().width).toBeLessThan(
+ compact.getBoundingClientRect().width,
+ );
+ });
+
+ const storage = canvas.getByRole('progressbar', { name: 'Storage' });
+ expect(storage).toHaveAttribute('aria-valuenow', '25');
+ expect(storage).toHaveAttribute('aria-valuetext', '25 of 100 gigabytes used');
expect(canvas.getByText('25 / 100 GB')).toBeVisible();
expect(canvas.getByText('0')).toBeVisible();
- expect(canvas.getAllByRole('progressbar')).toHaveLength(4);
+ expect(canvas.getAllByRole('progressbar')).toHaveLength(7);
expect(
canvas.getByRole('progressbar', { name: 'Empty progress' }),
).toHaveAttribute('aria-valuenow', '0');
@@ -39,19 +169,108 @@ export const progressTest: TwentyUiGalleryPlayFunction = async ({
await userEvent.click(
canvas.getByRole('button', { name: 'Advance progress' }),
);
+ await waitFor(() => {
+ expectProgressValues({
+ roots,
+ value: 55,
+ min: 10,
+ max: 70,
+ valueText: '75%',
+ });
+ expectProgressGeometry({ bar, ring, indicator, fraction: 0.75 });
+ expect(value).toHaveTextContent('75% of records');
+ expect(within(ring).getByText('55 records')).toBeVisible();
+ });
+ await userEvent.click(
+ canvas.getByRole('button', { name: 'Change progress range' }),
+ );
await waitFor(() => {
- expect(importProgress).toHaveAttribute('aria-valuenow', '75');
- expect(importProgress).toHaveAttribute(
- 'aria-valuetext',
- '75 of 100 records',
+ expectProgressValues({
+ roots,
+ value: 55,
+ min: 30,
+ max: 130,
+ valueText: '25%',
+ });
+ expectProgressGeometry({ bar, ring, indicator, fraction: 0.25 });
+ expect(value).toHaveTextContent('25% of records');
+ });
+
+ await userEvent.click(
+ canvas.getByRole('button', { name: 'Wait for records' }),
+ );
+ await waitFor(() => {
+ for (const root of roots) {
+ expect(root).not.toHaveAttribute('aria-valuenow');
+ expect(root).toHaveAttribute('aria-valuetext', 'indeterminate progress');
+ expect(root).toHaveAttribute('data-indeterminate');
+ }
+ expect(indicator).toHaveAttribute('data-render-status', 'indeterminate');
+ expect(indicator.style.width).toBe('');
+ expectRingGeometry({ ring, fraction: 0.25 });
+ const ringIndicator = ring.querySelector('[data-indeterminate]');
+ if (!isDefined(ringIndicator)) {
+ throw new Error('Indeterminate ring indicator is missing');
+ }
+ expect(getComputedStyle(ringIndicator).animationName).not.toBe('none');
+ expect(bar.querySelector('div > div')).not.toHaveAttribute(
+ 'data-minimum-fill',
+ );
+ expect(ring).toHaveAttribute('data-render-status', 'indeterminate');
+ expect(value).toHaveTextContent('Waiting');
+ expect(within(ring).getByText('Waiting for records')).toBeVisible();
+ });
+
+ await userEvent.click(
+ canvas.getByRole('button', { name: 'Complete import' }),
+ );
+ await waitFor(() => {
+ expectProgressValues({
+ roots,
+ value: 130,
+ min: 30,
+ max: 130,
+ valueText: '100%',
+ });
+ for (const root of roots) {
+ expect(root).toHaveAttribute('data-complete');
+ expect(root).not.toHaveAttribute('data-indeterminate');
+ }
+ expectProgressGeometry({ bar, ring, indicator, fraction: 1 });
+ const barIndicator = bar.querySelector('div > div');
+ if (!isDefined(barIndicator)) {
+ throw new Error('Complete bar indicator is missing');
+ }
+ expect(barIndicator).not.toHaveAttribute('data-minimum-fill');
+ expect(barIndicator.getBoundingClientRect().width).toBeCloseTo(
+ bar.getBoundingClientRect().width,
+ 1,
);
- expect(storageProgress).toHaveAttribute('aria-valuenow', '75');
- expect(storageProgress).toHaveAttribute(
- 'aria-valuetext',
- '75 of 100 gigabytes used',
+ expect(value).toHaveTextContent('100% of records');
+ });
+
+ await userEvent.click(canvas.getByRole('button', { name: 'Reset import' }));
+ await waitFor(() => {
+ expectProgressValues({
+ roots,
+ value: 30,
+ min: 30,
+ max: 130,
+ valueText: '0%',
+ });
+ expectProgressGeometry({ bar, ring, indicator, fraction: 0 });
+ const barIndicator = bar.querySelector('div > div');
+ if (!isDefined(barIndicator)) {
+ throw new Error('Empty bar indicator is missing');
+ }
+ expect(barIndicator).not.toHaveAttribute('data-minimum-fill');
+ expect(barIndicator.getBoundingClientRect().width).toBe(0);
+ expect(ring.querySelector('circle:last-child')).toHaveAttribute(
+ 'stroke-linecap',
+ 'butt',
);
- expect(canvas.getByText('75 / 100 GB')).toBeVisible();
+ expect(value).toHaveTextContent('0% of records');
});
expect(errorHandler).not.toHaveBeenCalled();
};
diff --git a/packages/twenty-front/src/modules/onboarding/components/free-credits/OnboardingFreeCreditsProgress.tsx b/packages/twenty-front/src/modules/onboarding/components/free-credits/OnboardingFreeCreditsProgress.tsx
index 654d28b5658..b8eacdaefe5 100644
--- a/packages/twenty-front/src/modules/onboarding/components/free-credits/OnboardingFreeCreditsProgress.tsx
+++ b/packages/twenty-front/src/modules/onboarding/components/free-credits/OnboardingFreeCreditsProgress.tsx
@@ -1,4 +1,5 @@
import { OnboardingFreeCreditsAnimatedCount } from '@/onboarding/components/free-credits/OnboardingFreeCreditsAnimatedCount';
+import { OnboardingFreeCreditsProgressBar } from '@/onboarding/components/free-credits/OnboardingFreeCreditsProgressBar';
import { StyledOnboardingFreeCreditsCount } from '@/onboarding/components/free-credits/StyledOnboardingFreeCreditsCount';
import { StyledOnboardingFreeCreditsLabel } from '@/onboarding/components/free-credits/StyledOnboardingFreeCreditsLabel';
import { StyledOnboardingFreeCreditsText } from '@/onboarding/components/free-credits/StyledOnboardingFreeCreditsText';
@@ -6,7 +7,6 @@ import { styled } from '@linaria/react';
import { plural } from '@lingui/core/macro';
import { useLingui } from '@lingui/react/macro';
import { VisuallyHidden } from 'twenty-ui/primitives/accessibility';
-import { ProgressBar } from 'twenty-ui/primitives/feedback';
import { themeCssVariables } from 'twenty-ui/theme';
import { useIsMobile } from 'twenty-ui/utilities';
@@ -44,18 +44,13 @@ export const OnboardingFreeCreditsProgress = ({
return (
<>
<StyledProgressBarContainer>
- <ProgressBar
- value={Math.min(100, (displayedCredits / goalCredits) * 100)}
- size="sm"
- ariaLabel={t`Free credits earned`}
- backgroundColor={themeCssVariables.background.transparent.medium}
- barColor={themeCssVariables.color.green9}
- withBorderRadius
- withGrowIn={!hasTrackGrown}
- withGlint={hasTrackGrown && hasNewlyEarnedCredits}
- withSpringFill
- withMinimumFillWidth={false}
- onGrowInComplete={onTrackGrown}
+ <OnboardingFreeCreditsProgressBar
+ value={displayedCredits}
+ max={goalCredits}
+ aria-label={t`Free credits earned`}
+ hasTrackGrown={hasTrackGrown}
+ hasNewlyEarnedCredits={hasNewlyEarnedCredits}
+ onTrackGrown={onTrackGrown}
/>
</StyledProgressBarContainer>
<StyledOnboardingFreeCreditsText>
diff --git a/packages/twenty-front/src/modules/onboarding/components/free-credits/OnboardingFreeCreditsProgressBar.tsx b/packages/twenty-front/src/modules/onboarding/components/free-credits/OnboardingFreeCreditsProgressBar.tsx
new file mode 100644
index 00000000000..a30973fef5d
--- /dev/null
+++ b/packages/twenty-front/src/modules/onboarding/components/free-credits/OnboardingFreeCreditsProgressBar.tsx
@@ -0,0 +1,152 @@
+import { OnboardingFreeCreditsProgressBarReducedMotionEffect } from '@/onboarding/components/free-credits/OnboardingFreeCreditsProgressBarReducedMotionEffect';
+import { styled } from '@linaria/react';
+import {
+ Progress,
+ type ProgressRootProps,
+} from 'twenty-ui/primitives/feedback';
+import { themeCssVariables } from 'twenty-ui/theme';
+
+const StyledProgressBar = styled.div`
+ background-color: ${themeCssVariables.background.transparent.medium};
+ border-radius: ${themeCssVariables.border.radius.pill};
+ corner-shape: round;
+ height: ${themeCssVariables.spacing['1.5']};
+ overflow: hidden;
+ position: relative;
+ width: 100%;
+
+ &[data-grow-in] {
+ animation: onboardingFreeCreditsProgressBarGrow
+ calc(${themeCssVariables.animation.duration.normal} * 1s)
+ cubic-bezier(0.2, 0, 0, 1);
+ }
+
+ @keyframes onboardingFreeCreditsProgressBarGrow {
+ from {
+ width: 0;
+ }
+ }
+
+ @media (prefers-reduced-motion: reduce) {
+ &[data-grow-in] {
+ animation: none;
+ }
+ }
+`;
+
+const StyledTrack = styled.div`
+ height: 100%;
+ position: relative;
+ width: 100%;
+`;
+
+const StyledIndicator = styled.div`
+ background-color: ${themeCssVariables.color.green9};
+ border-radius: ${themeCssVariables.border.radius.pill};
+ corner-shape: round;
+ height: 100%;
+ overflow: hidden;
+ position: relative;
+ transition: width calc(${themeCssVariables.animation.duration.normal} * 2s)
+ linear(
+ 0,
+ 0.092,
+ 0.285,
+ 0.496,
+ 0.681,
+ 0.823,
+ 0.922,
+ 0.982,
+ 1.015,
+ 1.028,
+ 1.03,
+ 1.026,
+ 1.02,
+ 1.014,
+ 1.008,
+ 1.004,
+ 1.002,
+ 1,
+ 0.999,
+ 0.999,
+ 1
+ );
+
+ @media (prefers-reduced-motion: reduce) {
+ transition: none;
+ }
+`;
+
+const StyledGlint = styled.span`
+ animation: onboardingFreeCreditsProgressBarGlint
+ calc(${themeCssVariables.animation.duration.normal} * 3s)
+ cubic-bezier(0.2, 0, 0, 1) forwards;
+ backdrop-filter: brightness(1.6);
+ inset: 0;
+ mask-image: linear-gradient(90deg, transparent, black, transparent);
+ position: absolute;
+ transform: translateX(-100%);
+
+ @keyframes onboardingFreeCreditsProgressBarGlint {
+ from {
+ transform: translateX(-100%);
+ }
+
+ to {
+ transform: translateX(100%);
+ }
+ }
+
+ @media (prefers-reduced-motion: reduce) {
+ display: none;
+ }
+`;
+
+type OnboardingFreeCreditsProgressBarProps = Pick<
+ ProgressRootProps,
+ 'value' | 'max' | 'aria-label'
+> & {
+ hasNewlyEarnedCredits: boolean;
+ hasTrackGrown: boolean;
+ onTrackGrown: () => void;
+};
+
+export const OnboardingFreeCreditsProgressBar = ({
+ value,
+ max,
+ 'aria-label': ariaLabel,
+ hasNewlyEarnedCredits,
+ hasTrackGrown,
+ onTrackGrown,
+}: OnboardingFreeCreditsProgressBarProps) => {
+ return (
+ <>
+ <Progress.Root
+ value={value}
+ max={max}
+ aria-label={ariaLabel}
+ data-grow-in={!hasTrackGrown || undefined}
+ onAnimationEnd={({ target, currentTarget }) => {
+ if (hasTrackGrown || target !== currentTarget) {
+ return;
+ }
+
+ onTrackGrown();
+ }}
+ render={<StyledProgressBar />}
+ >
+ <Progress.Track render={<StyledTrack />}>
+ <Progress.Indicator render={<StyledIndicator />}>
+ {hasTrackGrown && hasNewlyEarnedCredits && (
+ <StyledGlint key={`${max}:${value}`} aria-hidden />
+ )}
+ </Progress.Indicator>
+ </Progress.Track>
+ </Progress.Root>
+ <OnboardingFreeCreditsProgressBarReducedMotionEffect
+ hasTrackGrown={hasTrackGrown}
+ onTrackGrown={onTrackGrown}
+ />
+ </>
+ );
+};
diff --git a/packages/twenty-front/src/modules/onboarding/components/free-credits/OnboardingFreeCreditsProgressBarReducedMotionEffect.tsx b/packages/twenty-front/src/modules/onboarding/components/free-credits/OnboardingFreeCreditsProgressBarReducedMotionEffect.tsx
new file mode 100644
index 00000000000..7eea977e8a2
--- /dev/null
+++ b/packages/twenty-front/src/modules/onboarding/components/free-credits/OnboardingFreeCreditsProgressBarReducedMotionEffect.tsx
@@ -0,0 +1,26 @@
+import { useEffect } from 'react';
+import { useMediaQuery } from 'twenty-ui/utilities';
+
+const REDUCED_MOTION_QUERY = '(prefers-reduced-motion: reduce)';
+
+type OnboardingFreeCreditsProgressBarReducedMotionEffectProps = {
+ hasTrackGrown: boolean;
+ onTrackGrown: () => void;
+};
+
+export const OnboardingFreeCreditsProgressBarReducedMotionEffect = ({
+ hasTrackGrown,
+ onTrackGrown,
+}: OnboardingFreeCreditsProgressBarReducedMotionEffectProps) => {
+ const shouldReduceMotion = useMediaQuery(REDUCED_MOTION_QUERY);
+
+ useEffect(() => {
+ if (hasTrackGrown || !shouldReduceMotion) {
+ return;
+ }
+
+ onTrackGrown();
+ }, [hasTrackGrown, onTrackGrown, shouldReduceMotion]);
+
+ return null;
+};
diff --git a/packages/twenty-front/src/modules/onboarding/components/free-credits/__stories__/OnboardingFreeCreditsProgressBar.stories.tsx b/packages/twenty-front/src/modules/onboarding/components/free-credits/__stories__/OnboardingFreeCreditsProgressBar.stories.tsx
new file mode 100644
index 00000000000..6670cb2c402
--- /dev/null
+++ b/packages/twenty-front/src/modules/onboarding/components/free-credits/__stories__/OnboardingFreeCreditsProgressBar.stories.tsx
@@ -0,0 +1,213 @@
+import { OnboardingFreeCreditsProgressGrowthExample } from '@/onboarding/components/free-credits/__stories__/OnboardingFreeCreditsProgressGrowthExample';
+import { OnboardingFreeCreditsProgressBar } from '@/onboarding/components/free-credits/OnboardingFreeCreditsProgressBar';
+import { styled } from '@linaria/react';
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import { expect, userEvent, waitFor, within } from 'storybook/test';
+import { useState } from 'react';
+import { Button } from 'twenty-ui/primitives/input';
+import { themeCssVariables } from 'twenty-ui/theme';
+import { isDefined } from 'twenty-shared/utils';
+
+const TRACK_GROWTH_EVENT_NAME = 'animationend';
+const REDUCED_MOTION_CHANGE_EVENT_NAME = 'change';
+const REDUCED_MOTION_QUERY = '(prefers-reduced-motion: reduce)';
+
+const mockReducedMotionPreference = (matches: boolean) => {
+ const originalMatchMedia = window.matchMedia;
+ const reducedMotionMedia = Object.assign(new EventTarget(), {
+ matches,
+ media: REDUCED_MOTION_QUERY,
+ onchange: null,
+ addListener: () => {},
+ removeListener: () => {},
+ });
+
+ window.matchMedia = (query) =>
+ query === REDUCED_MOTION_QUERY
+ ? reducedMotionMedia
+ : originalMatchMedia(query);
+
+ return {
+ enableReducedMotion: () => {
+ reducedMotionMedia.matches = true;
+ reducedMotionMedia.dispatchEvent(
+ new MediaQueryListEvent(REDUCED_MOTION_CHANGE_EVENT_NAME, {
+ matches: true,
+ media: REDUCED_MOTION_QUERY,
+ }),
+ );
+ },
+ restore: () => {
+ window.matchMedia = originalMatchMedia;
+ },
+ };
+};
+
+const StyledContainer = styled.div`
+ display: flex;
+ flex-direction: column;
+ gap: ${themeCssVariables.spacing[4]};
+ width: 240px;
+`;
+
+const StyledPausedGrowth = styled.div`
+ [data-grow-in] {
+ animation-duration: calc(
+ ${themeCssVariables.animation.duration.normal} * 1s
+ ) !important;
+ animation-play-state: paused;
+ }
+`;
+
+const OnboardingProgressExample = () => {
+ const [hasTrackGrown, setHasTrackGrown] = useState(false);
+ const [earnedCredits, setEarnedCredits] = useState(60);
+ const [goalCredits, setGoalCredits] = useState(100);
+
+ return (
+ <StyledContainer>
+ <OnboardingFreeCreditsProgressBar
+ value={hasTrackGrown ? earnedCredits : 20}
+ max={goalCredits}
+ aria-label="Free credits earned"
+ hasTrackGrown={hasTrackGrown}
+ hasNewlyEarnedCredits
+ onTrackGrown={() => setHasTrackGrown(true)}
+ />
+ <Button onClick={() => setEarnedCredits((credits) => credits + 20)}>
+ Earn 20 credits
+ </Button>
+ <Button onClick={() => setGoalCredits(200)}>
+ Set goal to 200 credits
+ </Button>
+ </StyledContainer>
+ );
+};
+
+const meta: Meta<typeof OnboardingFreeCreditsProgressBar> = {
+ title: 'Modules/Onboarding/FreeCredits/ProgressBar',
+ component: OnboardingFreeCreditsProgressBar,
+};
+
+export default meta;
+
+type Story = StoryObj<typeof OnboardingFreeCreditsProgressBar>;
+
+export const Choreography: Story = {
+ render: () => <OnboardingProgressExample />,
+};
+
+export const Updates: Story = {
+ render: () => <OnboardingProgressExample />,
+ play: async ({ canvasElement }) => {
+ const canvas = within(canvasElement);
+ const progressBar = canvas.getByRole('progressbar', {
+ name: 'Free credits earned',
+ });
+
+ await waitFor(() =>
+ expect(progressBar).toHaveAttribute('aria-valuenow', '60'),
+ );
+ await expect(progressBar).not.toHaveAttribute('data-grow-in');
+ await userEvent.click(
+ canvas.getByRole('button', { name: 'Earn 20 credits' }),
+ );
+ await expect(progressBar).toHaveAttribute('aria-valuenow', '80');
+ await userEvent.click(
+ canvas.getByRole('button', { name: 'Set goal to 200 credits' }),
+ );
+ await expect(progressBar).toHaveAttribute('aria-valuemax', '200');
+ await expect(progressBar).toHaveAttribute('aria-valuetext', '40%');
+ },
+};
+
+export const GrowthCompletion: Story = {
+ render: () => (
+ <StyledPausedGrowth>
+ <OnboardingFreeCreditsProgressGrowthExample />
+ </StyledPausedGrowth>
+ ),
+ play: async ({ canvasElement }) => {
+ const canvas = within(canvasElement);
+
+ await userEvent.click(canvas.getByRole('button', { name: 'Start growth' }));
+ const progressBar = canvas.getByRole('progressbar', {
+ name: 'Free credits earned',
+ });
+ const track = progressBar.firstElementChild;
+ const [growthAnimation] = progressBar.getAnimations();
+
+ await expect(track).not.toBeNull();
+ await expect(growthAnimation).toBeDefined();
+
+ if (!isDefined(track) || !isDefined(growthAnimation)) {
+ throw new Error('The progress track and growth animation must exist');
+ }
+
+ track.dispatchEvent(
+ new AnimationEvent(TRACK_GROWTH_EVENT_NAME, { bubbles: true }),
+ );
+ await expect(progressBar).toHaveAttribute('aria-valuenow', '20');
+ await expect(progressBar).toHaveAttribute('data-grow-in');
+ growthAnimation.play();
+ await waitFor(() =>
+ expect(progressBar).toHaveAttribute('aria-valuenow', '60'),
+ );
+ await expect(progressBar).not.toHaveAttribute('data-grow-in');
+ },
+};
+
+export const ReducedMotionCompletion: Story = {
+ render: () => <OnboardingFreeCreditsProgressGrowthExample />,
+ play: async ({ canvasElement }) => {
+ const canvas = within(canvasElement);
+ const reducedMotion = mockReducedMotionPreference(true);
+
+ try {
+ await userEvent.click(
+ canvas.getByRole('button', { name: 'Start growth' }),
+ );
+ const progressBar = canvas.getByRole('progressbar', {
+ name: 'Free credits earned',
+ });
+
+ await waitFor(() =>
+ expect(progressBar).toHaveAttribute('aria-valuenow', '60'),
+ );
+ await expect(progressBar).not.toHaveAttribute('data-grow-in');
+ } finally {
+ reducedMotion.restore();
+ }
+ },
+};
+
+export const ReducedMotionChange: Story = {
+ render: () => (
+ <StyledPausedGrowth>
+ <OnboardingFreeCreditsProgressGrowthExample />
+ </StyledPausedGrowth>
+ ),
+ play: async ({ canvasElement }) => {
+ const canvas = within(canvasElement);
+ const reducedMotion = mockReducedMotionPreference(false);
+
+ try {
+ await userEvent.click(
+ canvas.getByRole('button', { name: 'Start growth' }),
+ );
+ const progressBar = canvas.getByRole('progressbar', {
+ name: 'Free credits earned',
+ });
+
+ await expect(progressBar).toHaveAttribute('aria-valuenow', '20');
+ await expect(progressBar).toHaveAttribute('data-grow-in');
+ reducedMotion.enableReducedMotion();
+ await waitFor(() =>
+ expect(progressBar).toHaveAttribute('aria-valuenow', '60'),
+ );
+ await expect(progressBar).not.toHaveAttribute('data-grow-in');
+ } finally {
+ reducedMotion.restore();
+ }
+ },
+};
diff --git a/packages/twenty-front/src/modules/onboarding/components/free-credits/__stories__/OnboardingFreeCreditsProgressGrowthExample.tsx b/packages/twenty-front/src/modules/onboarding/components/free-credits/__stories__/OnboardingFreeCreditsProgressGrowthExample.tsx
new file mode 100644
index 00000000000..85f3cf2c29d
--- /dev/null
+++ b/packages/twenty-front/src/modules/onboarding/components/free-credits/__stories__/OnboardingFreeCreditsProgressGrowthExample.tsx
@@ -0,0 +1,38 @@
+import { OnboardingFreeCreditsProgressBar } from '@/onboarding/components/free-credits/OnboardingFreeCreditsProgressBar';
+import { styled } from '@linaria/react';
+import { useState } from 'react';
+import { Button } from 'twenty-ui/primitives/input';
+import { themeCssVariables } from 'twenty-ui/theme';
+
+const StyledContainer = styled.div`
+ display: flex;
+ flex-direction: column;
+ gap: ${themeCssVariables.spacing[4]};
+ width: 240px;
+`;
+
+export const OnboardingFreeCreditsProgressGrowthExample = () => {
+ const [hasStartedGrowth, setHasStartedGrowth] = useState(false);
+ const [hasTrackGrown, setHasTrackGrown] = useState(false);
+
+ return (
+ <StyledContainer>
+ {hasStartedGrowth && (
+ <OnboardingFreeCreditsProgressBar
+ value={hasTrackGrown ? 60 : 20}
+ max={100}
+ aria-label="Free credits earned"
+ hasTrackGrown={hasTrackGrown}
+ hasNewlyEarnedCredits
+ onTrackGrown={() => setHasTrackGrown(true)}
+ />
+ )}
+ <Button
+ disabled={hasStartedGrowth}
+ onClick={() => setHasStartedGrowth(true)}
+ >
+ Start growth
+ </Button>
+ </StyledContainer>
+ );
+};
diff --git a/packages/twenty-front/src/modules/settings/billing/components/SettingsBillingCreditsSection.tsx b/packages/twenty-front/src/modules/settings/billing/components/SettingsBillingCreditsSection.tsx
index 3dea0ed8ed9..284dd659c70 100644
--- a/packages/twenty-front/src/modules/settings/billing/components/SettingsBillingCreditsSection.tsx
+++ b/packages/twenty-front/src/modules/settings/billing/components/SettingsBillingCreditsSection.tsx
@@ -39,8 +39,6 @@ import {
} from '~/generated-metadata/graphql';
import { openUrlInNewTab } from '~/utils/openUrlInNewTab';
-const MIN_VISIBLE_EMPTY_CREDIT_PROGRESS_PERCENTAGE = 4;
-
const StyledSettingsBillingCardBody = styled.div`
display: flex;
flex-direction: column;
@@ -183,10 +181,6 @@ export const SettingsBillingCreditsSection = ({
100,
Math.max(0, remainingCreditsPercentage),
);
- const isCreditsEmpty = clampedRemainingCreditsPercentage === 0;
- const displayedProgressBarValue = isCreditsEmpty
- ? MIN_VISIBLE_EMPTY_CREDIT_PROGRESS_PERCENTAGE
- : clampedRemainingCreditsPercentage;
// rolloverCredits sums every active grant, not just the rolled-over ones
const extraCredits = rolloverCredits;
@@ -259,13 +253,10 @@ export const SettingsBillingCreditsSection = ({
</StyledSettingsBillingCardHeader>
<StyledCreditsCardBody>
<ProgressBar
- value={displayedProgressBarValue}
+ value={clampedRemainingCreditsPercentage}
+ aria-label={t`Remaining credits`}
backgroundColor={themeCssVariables.background.tertiary}
- barColor={
- isCreditsEmpty
- ? themeCssVariables.color.red9
- : themeCssVariables.color.green9
- }
+ barColor={themeCssVariables.color.green9}
withBorderRadius
/>
<StyledCreditsFooter>
diff --git a/packages/twenty-shared/src/constants/DocumentationPaths.ts b/packages/twenty-shared/src/constants/DocumentationPaths.ts
index efd015b1566..c8881897e9e 100644
--- a/packages/twenty-shared/src/constants/DocumentationPaths.ts
+++ b/packages/twenty-shared/src/constants/DocumentationPaths.ts
@@ -185,6 +185,7 @@ export const DOCUMENTATION_PATHS = {
UI_PRIMITIVES_DATA_DISPLAY_TAG: '/ui/primitives/data-display/tag',
UI_PRIMITIVES_FEEDBACK_BANNER: '/ui/primitives/feedback/banner',
UI_PRIMITIVES_FEEDBACK_LOADER: '/ui/primitives/feedback/loader',
+ UI_PRIMITIVES_FEEDBACK_PROGRESS: '/ui/primitives/feedback/progress',
UI_PRIMITIVES_FEEDBACK_PROGRESS_BAR: '/ui/primitives/feedback/progress-bar',
UI_PRIMITIVES_FEEDBACK_PROGRESS_RING: '/ui/primitives/feedback/progress-ring',
UI_PRIMITIVES_FEEDBACK_SKELETON: '/ui/primitives/feedback/skeleton',
diff --git a/packages/twenty-ui/docs/components.ts b/packages/twenty-ui/docs/components.ts
index 3b5f1380b29..badd0b6c4bb 100644
--- a/packages/twenty-ui/docs/components.ts
+++ b/packages/twenty-ui/docs/components.ts
@@ -8,6 +8,7 @@ import { COUNTRY_SELECT_PROP_DESCRIPTIONS } from './countrySelectPropDescription
import { CURRENCY_PICKER_PART_PROP_DESCRIPTIONS } from './currencyPickerPartPropDescriptions';
import { OVERFLOWING_LIST_PROP_DESCRIPTIONS } from './overflowingListPropDescriptions';
import { METRIC_ROW_PROP_DESCRIPTIONS } from './metricRowPropDescriptions';
+import { PROGRESS_PART_PROP_DESCRIPTIONS } from './progressPartPropDescriptions';
import { PROGRESS_RING_PROP_DESCRIPTIONS } from './progressRingPropDescriptions';
import { AVATAR_GROUP_PROP_DESCRIPTIONS } from './avatarGroupPropDescriptions';
import { COMMAND_BLOCK_PROP_DESCRIPTIONS } from './commandBlockPropDescriptions';
@@ -184,6 +185,14 @@ export const DOCUMENTED_COMPONENTS = [
slug: 'feedback/skeleton',
propDescriptions: SKELETON_PROP_DESCRIPTIONS,
},
+ {
+ name: 'Progress',
+ source: 'primitives/feedback/Progress/Progress.tsx',
+ entryPoint: 'twenty-ui/primitives/feedback',
+ slug: 'feedback/progress',
+ parts: ['Root', 'Track', 'Indicator', 'Label', 'Value'],
+ partPropDescriptions: PROGRESS_PART_PROP_DESCRIPTIONS,
+ },
{
name: 'ProgressBar',
source: 'primitives/feedback/ProgressBar/ProgressBar.tsx',
diff --git a/packages/twenty-ui/docs/metricRowPropDescriptions.ts b/packages/twenty-ui/docs/metricRowPropDescriptions.ts
index 4a847799943..bca01237a7c 100644
--- a/packages/twenty-ui/docs/metricRowPropDescriptions.ts
+++ b/packages/twenty-ui/docs/metricRowPropDescriptions.ts
@@ -8,12 +8,12 @@ export const METRIC_ROW_PROP_DESCRIPTIONS = {
startIcon:
'Decorative node content before the label. The caller controls icon geometry.',
value:
- 'Preformatted value displayed at the end of the row. String values also supply the progress ring accessible value text.',
+ 'Preformatted value displayed at the end of the row. Nonempty string values also supply the progress ring accessible value text.',
progress:
'Optional controlled progress from 0 to 100. Omitting it displays the value without a ring.',
progressColor: 'CSS color of the filled arc when progress is provided.',
progressValueText:
- 'Accessible value text for the progress ring. Overrides the string value fallback; supply it when formatted content needs more context than a percentage.',
+ 'Accessible value text for the progress ring. Nonempty text overrides the string value fallback; an empty string uses the ring percentage. Supply it when formatted content needs more context than a percentage.',
className: 'CSS class applied to the row root.',
style: 'Inline styles applied to the row root.',
render: 'Replaces the row root element while preserving its contents.',
diff --git a/packages/twenty-ui/docs/module-ownership.json b/packages/twenty-ui/docs/module-ownership.json
index b75d74f8fde..ea220c4a10f 100644
--- a/packages/twenty-ui/docs/module-ownership.json
+++ b/packages/twenty-ui/docs/module-ownership.json
@@ -24,6 +24,7 @@
"NumberField",
"OverflowingTextWithTooltip",
"Popover",
+ "Progress",
"ProgressBar",
"ProgressRing",
"Radio",
diff --git a/packages/twenty-ui/docs/progressBarPropDescriptions.ts b/packages/twenty-ui/docs/progressBarPropDescriptions.ts
index 97ad1fcaeb5..112d72fd840 100644
--- a/packages/twenty-ui/docs/progressBarPropDescriptions.ts
+++ b/packages/twenty-ui/docs/progressBarPropDescriptions.ts
@@ -3,18 +3,32 @@ import { type ComponentProps } from 'react';
import { type ProgressBar } from '../src/primitives/feedback/ProgressBar/ProgressBar';
export const PROGRESS_BAR_PROP_DESCRIPTIONS = {
- value: 'Current progress from 0 to 100.',
- size: 'Bar height: `sm` (6px) or `md` (8px).',
- className: 'CSS class applied to the progress root.',
+ value:
+ 'Controlled value in the min/max range. Use null for indeterminate progress.',
+ min: 'Inclusive minimum. Defaults to 0.',
+ max: 'Inclusive maximum. Defaults to 100.',
+ size: 'Bar height: sm (6px) or md (8px).',
barColor: 'CSS color of the filled bar. Defaults to the primary text color.',
backgroundColor: 'CSS background color of the track.',
withBorderRadius: 'Rounds the track and indicator corners.',
- withGrowIn: 'Grows the bar in from zero width when it mounts.',
- withGlint:
- 'Sweeps a highlight across the filled bar each time the value changes.',
- withSpringFill:
- 'Animates value changes with a spring that slightly overshoots the target.',
- withMinimumFillWidth: 'Keeps a small visible fill for any value above zero.',
- ariaLabel: 'Accessible name describing the operation being measured.',
- onGrowInComplete: 'Called when the grow-in animation ends.',
+ withMinimumFillWidth:
+ 'Applies a cosmetic minimum of up to 12px, capped at half the track width, only above the minimum and below completion.',
+ children: 'Additional Progress parts or supporting content inside the root.',
+ 'aria-label': 'Accessible name identifying the measured operation.',
+ 'aria-labelledby': 'ID of the visible label that names the operation.',
+ 'aria-valuetext':
+ 'Human-readable progress value overriding the default formatted value.',
+ format:
+ 'Intl.NumberFormat options for the clamped numeric value. The default displays the normalized percentage.',
+ locale:
+ 'Locale or locale list used to format the value. Defaults to the runtime locale.',
+ getAriaValueText:
+ 'Receives the formatted value and raw value, including null, and returns an accessible value description.',
+ className:
+ 'Class applied to the progress root, or a callback receiving its status.',
+ style:
+ 'Inline styles applied to the progress root, or a callback receiving its status.',
+ ref: 'Ref to the root div, or the element composed through render.',
+ render:
+ 'Composes the root with an element or render callback. Forward the supplied props and ref to retain progress semantics.',
} satisfies Partial<Record<keyof ComponentProps<typeof ProgressBar>, string>>;
diff --git a/packages/twenty-ui/docs/progressPartPropDescriptions.ts b/packages/twenty-ui/docs/progressPartPropDescriptions.ts
new file mode 100644
index 00000000000..7e15d5acd72
--- /dev/null
+++ b/packages/twenty-ui/docs/progressPartPropDescriptions.ts
@@ -0,0 +1,64 @@
+import { type ComponentProps } from 'react';
+
+import { type Progress } from '../src/primitives/feedback/Progress/Progress';
+
+const PROGRESS_COMMON_PROP_DESCRIPTIONS = {
+ className:
+ 'Class applied to this part, or a callback receiving its progress status.',
+ style:
+ 'Inline styles applied to this part, or a callback receiving its progress status.',
+ render:
+ 'Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element.',
+};
+
+export const PROGRESS_PART_PROP_DESCRIPTIONS = {
+ Root: {
+ ...PROGRESS_COMMON_PROP_DESCRIPTIONS,
+ value:
+ 'Controlled value in the min/max range. Use null for indeterminate progress.',
+ min: 'Inclusive minimum. Defaults to 0.',
+ max: 'Inclusive maximum. Defaults to 100.',
+ format:
+ 'Intl.NumberFormat options for the clamped numeric value. The default displays the normalized percentage.',
+ locale:
+ 'Locale or locale list used to format the value. Defaults to the runtime locale.',
+ getAriaValueText:
+ 'Receives the formatted value and raw value, including null, and returns an accessible value description.',
+ children: 'Composed Progress parts and supporting content.',
+ 'aria-label': 'Accessible name identifying the measured operation.',
+ 'aria-labelledby': 'ID of the visible label that names the operation.',
+ 'aria-valuetext':
+ 'Human-readable progress value overriding the default formatted value.',
+ ref: 'Ref to the root div, or the element composed through Root.render.',
+ } satisfies Partial<
+ Record<keyof ComponentProps<typeof Progress.Root>, string>
+ >,
+ Track: {
+ ...PROGRESS_COMMON_PROP_DESCRIPTIONS,
+ children: 'The indicator and optional supporting content.',
+ ref: 'Ref to the track div, or the element composed through Track.render.',
+ } satisfies Partial<
+ Record<keyof ComponentProps<typeof Progress.Track>, string>
+ >,
+ Indicator: {
+ ...PROGRESS_COMMON_PROP_DESCRIPTIONS,
+ ref: 'Ref to the indicator div, or the element composed through Indicator.render.',
+ } satisfies Partial<
+ Record<keyof ComponentProps<typeof Progress.Indicator>, string>
+ >,
+ Label: {
+ ...PROGRESS_COMMON_PROP_DESCRIPTIONS,
+ children: 'Visible text that supplies the accessible name of the root.',
+ ref: 'Ref to the label span, or the element composed through Label.render.',
+ } satisfies Partial<
+ Record<keyof ComponentProps<typeof Progress.Label>, string>
+ >,
+ Value: {
+ ...PROGRESS_COMMON_PROP_DESCRIPTIONS,
+ children:
+ 'Optional callback receiving the formatted value and raw value. Indeterminate progress passes indeterminate as formatted text. Without a callback, indeterminate progress displays no content.',
+ ref: 'Ref to the value span, or the element composed through Value.render.',
+ } satisfies Partial<
+ Record<keyof ComponentProps<typeof Progress.Value>, string>
+ >,
+};
diff --git a/packages/twenty-ui/docs/progressRingPropDescriptions.ts b/packages/twenty-ui/docs/progressRingPropDescriptions.ts
index 8fa997dbf18..1b335725a69 100644
--- a/packages/twenty-ui/docs/progressRingPropDescriptions.ts
+++ b/packages/twenty-ui/docs/progressRingPropDescriptions.ts
@@ -4,16 +4,28 @@ import { type ProgressRing } from '../src/primitives/feedback/ProgressRing/Progr
export const PROGRESS_RING_PROP_DESCRIPTIONS = {
value:
- 'Controlled progress from 0 to 100. Out-of-range values are bounded and NaN renders as zero.',
+ 'Controlled value in the min/max range. Use null for indeterminate progress.',
+ min: 'Inclusive minimum. Defaults to 0.',
+ max: 'Inclusive maximum. Defaults to 100.',
size: 'Ring diameter: sm (14px) or md (16px). Defaults to md.',
barColor: 'CSS color of the filled arc. Defaults to the blue theme color.',
- children: 'Optional preformatted value displayed before the ring.',
+ children:
+ 'Optional preformatted value or Progress parts displayed before the ring.',
'aria-label': 'Accessible name identifying the measured operation.',
- 'aria-labelledby':
- 'ID of the visible label that names the measured operation.',
+ 'aria-labelledby': 'ID of the visible label that names the operation.',
'aria-valuetext':
- 'Human-readable progress value when a percentage alone is insufficient.',
- className: 'CSS class applied to the progress root.',
- style: 'Inline styles applied to the progress root.',
- render: 'Replaces the root element while preserving progress semantics.',
+ 'Human-readable progress value overriding the default formatted value.',
+ format:
+ 'Intl.NumberFormat options for the clamped numeric value. The default displays the normalized percentage.',
+ locale:
+ 'Locale or locale list used to format the value. Defaults to the runtime locale.',
+ getAriaValueText:
+ 'Receives the formatted value and raw value, including null, and returns an accessible value description.',
+ className:
+ 'Class applied to the progress root, or a callback receiving its status.',
+ style:
+ 'Inline styles applied to the progress root, or a callback receiving its status.',
+ ref: 'Ref to the root div, or the element composed through render.',
+ render:
+ 'Composes the root with an element or render callback. Forward the supplied props and ref to retain progress semantics.',
} satisfies Partial<Record<keyof ComponentProps<typeof ProgressRing>, string>>;
diff --git a/packages/twenty-ui/docs/public-exports.json b/packages/twenty-ui/docs/public-exports.json
index 08c8b522dc9..74dcce8ec8e 100644
--- a/packages/twenty-ui/docs/public-exports.json
+++ b/packages/twenty-ui/docs/public-exports.json
@@ -765,6 +765,7 @@
"values": {
"Banner": "primitives/feedback/Banner/Banner",
"Loader": "primitives/feedback/Loader/Loader",
+ "Progress": "primitives/feedback/Progress/Progress",
"ProgressBar": "primitives/feedback/ProgressBar/ProgressBar",
"ProgressRing": "primitives/feedback/ProgressRing/ProgressRing",
"Skeleton": "primitives/feedback/Skeleton/Skeleton",
@@ -779,7 +780,18 @@
"BannerVariant": "primitives/feedback/Banner/types/BannerVariant",
"LoaderProps": "primitives/feedback/Loader/types/LoaderProps",
"ProgressBarProps": "primitives/feedback/ProgressBar/types/ProgressBarProps",
+ "ProgressIndicatorProps": "primitives/feedback/Progress/types/ProgressIndicatorProps",
+ "ProgressIndicatorState": "primitives/feedback/Progress/types/ProgressIndicatorState",
+ "ProgressLabelProps": "primitives/feedback/Progress/types/ProgressLabelProps",
+ "ProgressLabelState": "primitives/feedback/Progress/types/ProgressLabelState",
"ProgressRingProps": "primitives/feedback/ProgressRing/types/ProgressRingProps",
+ "ProgressRootProps": "primitives/feedback/Progress/types/ProgressRootProps",
+ "ProgressRootState": "primitives/feedback/Progress/types/ProgressRootState",
+ "ProgressStatus": "primitives/feedback/Progress/types/ProgressStatus",
+ "ProgressTrackProps": "primitives/feedback/Progress/types/ProgressTrackProps",
+ "ProgressTrackState": "primitives/feedback/Progress/types/ProgressTrackState",
+ "ProgressValueProps": "primitives/feedback/Progress/types/ProgressValueProps",
+ "ProgressValueState": "primitives/feedback/Progress/types/ProgressValueState",
"SkeletonProps": "primitives/feedback/Skeleton/types/SkeletonProps"
}
},
diff --git a/packages/twenty-ui/generated/components.docs.json b/packages/twenty-ui/generated/components.docs.json
index 9e1c047e619..e1e3dcec574 100644
--- a/packages/twenty-ui/generated/components.docs.json
+++ b/packages/twenty-ui/generated/components.docs.json
@@ -258,14 +258,14 @@
"type": "string",
"required": false,
"defaultValue": null,
- "description": "ID of the visible label that names the measured operation."
+ "description": "ID of the visible label that names the operation."
},
{
"name": "aria-valuetext",
"type": "string",
"required": false,
"defaultValue": null,
- "description": "Human-readable progress value when a percentage alone is insufficient."
+ "description": "Human-readable progress value overriding the default formatted value."
},
{
"name": "barColor",
@@ -279,21 +279,63 @@
"type": "ReactNode",
"required": false,
"defaultValue": null,
- "description": "Optional preformatted value displayed before the ring."
+ "description": "Optional preformatted value or Progress parts displayed before the ring."
},
{
"name": "className",
- "type": "string",
+ "type": "string | ((state: ProgressRootState) => string | undefined)",
+ "required": false,
+ "defaultValue": null,
+ "description": "Class applied to the progress root, or a callback receiving its status."
+ },
+ {
+ "name": "format",
+ "type": "NumberFormatOptions",
"required": false,
"defaultValue": null,
- "description": "CSS class applied to the progress root."
+ "description": "Intl.NumberFormat options for the clamped numeric value. The default displays the normalized percentage."
+ },
+ {
+ "name": "getAriaValueText",
+ "type": "((formattedValue: string, value: number | null) => string)",
+ "required": false,
+ "defaultValue": null,
+ "description": "Receives the formatted value and raw value, including null, and returns an accessible value description."
+ },
+ {
+ "name": "locale",
+ "type": "LocalesArgument",
+ "required": false,
+ "defaultValue": null,
+ "description": "Locale or locale list used to format the value. Defaults to the runtime locale."
+ },
+ {
+ "name": "max",
+ "type": "number",
+ "required": false,
+ "defaultValue": "100",
+ "description": "Inclusive maximum. Defaults to 100."
+ },
+ {
+ "name": "min",
+ "type": "number",
+ "required": false,
+ "defaultValue": "0",
+ "description": "Inclusive minimum. Defaults to 0."
+ },
+ {
+ "name": "ref",
+ "type": "Ref<HTMLDivElement>",
+ "required": false,
+ "defaultValue": null,
+ "description": "Ref to the root div, or the element composed through render."
},
{
"name": "render",
- "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>",
+ "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ProgressRootState>",
"required": false,
"defaultValue": null,
- "description": "Replaces the root element while preserving progress semantics."
+ "description": "Composes the root with an element or render callback. Forward the supplied props and ref to retain progress semantics."
},
{
"name": "size",
@@ -304,17 +346,17 @@
},
{
"name": "style",
- "type": "CSSProperties",
+ "type": "CSSProperties | ((state: ProgressRootState) => CSSProperties | undefined)",
"required": false,
"defaultValue": null,
- "description": "Inline styles applied to the progress root."
+ "description": "Inline styles applied to the progress root, or a callback receiving its status."
},
{
"name": "value",
- "type": "number",
+ "type": "number | null",
"required": true,
"defaultValue": null,
- "description": "Controlled progress from 0 to 100. Out-of-range values are bounded and NaN renders as zero."
+ "description": "Controlled value in the min/max range. Use null for indeterminate progress."
}
]
},
@@ -356,7 +398,7 @@
"type": "string",
"required": false,
"defaultValue": null,
- "description": "Accessible value text for the progress ring. Overrides the string value fallback; supply it when formatted content needs more context than a percentage."
+ "description": "Accessible value text for the progress ring. Nonempty text overrides the string value fallback; an empty string uses the ring percentage. Supply it when formatted content needs more context than a percentage."
},
{
"name": "render",
@@ -384,7 +426,7 @@
"type": "ReactNode",
"required": true,
"defaultValue": null,
- "description": "Preformatted value displayed at the end of the row. String values also supply the progress ring accessible value text."
+ "description": "Preformatted value displayed at the end of the row. Nonempty string values also supply the progress ring accessible value text."
}
]
},
@@ -913,17 +955,295 @@
}
]
},
+ {
+ "name": "Progress",
+ "entryPoint": "twenty-ui/primitives/feedback",
+ "slug": "feedback/progress",
+ "props": [],
+ "parts": [
+ {
+ "name": "Root",
+ "props": [
+ {
+ "name": "aria-label",
+ "type": "string",
+ "required": false,
+ "defaultValue": null,
+ "description": "Accessible name identifying the measured operation."
+ },
+ {
+ "name": "aria-labelledby",
+ "type": "string",
+ "required": false,
+ "defaultValue": null,
+ "description": "ID of the visible label that names the operation."
+ },
+ {
+ "name": "aria-valuetext",
+ "type": "string",
+ "required": false,
+ "defaultValue": null,
+ "description": "Human-readable progress value overriding the default formatted value."
+ },
+ {
+ "name": "children",
+ "type": "ReactNode",
+ "required": false,
+ "defaultValue": null,
+ "description": "Composed Progress parts and supporting content."
+ },
+ {
+ "name": "className",
+ "type": "string | ((state: ProgressRootState) => string | undefined)",
+ "required": false,
+ "defaultValue": null,
+ "description": "Class applied to this part, or a callback receiving its progress status."
+ },
+ {
+ "name": "format",
+ "type": "NumberFormatOptions",
+ "required": false,
+ "defaultValue": null,
+ "description": "Intl.NumberFormat options for the clamped numeric value. The default displays the normalized percentage."
+ },
+ {
+ "name": "getAriaValueText",
+ "type": "((formattedValue: string, value: number | null) => string)",
+ "required": false,
+ "defaultValue": null,
+ "description": "Receives the formatted value and raw value, including null, and returns an accessible value description."
+ },
+ {
+ "name": "locale",
+ "type": "LocalesArgument",
+ "required": false,
+ "defaultValue": null,
+ "description": "Locale or locale list used to format the value. Defaults to the runtime locale."
+ },
+ {
+ "name": "max",
+ "type": "number",
+ "required": false,
+ "defaultValue": "100",
+ "description": "Inclusive maximum. Defaults to 100."
+ },
+ {
+ "name": "min",
+ "type": "number",
+ "required": false,
+ "defaultValue": "0",
+ "description": "Inclusive minimum. Defaults to 0."
+ },
+ {
+ "name": "ref",
+ "type": "Ref<HTMLDivElement>",
+ "required": false,
+ "defaultValue": null,
+ "description": "Ref to the root div, or the element composed through Root.render."
+ },
+ {
+ "name": "render",
+ "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ProgressRootState>",
+ "required": false,
+ "defaultValue": null,
+ "description": "Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element."
+ },
+ {
+ "name": "style",
+ "type": "CSSProperties | ((state: ProgressRootState) => CSSProperties | undefined)",
+ "required": false,
+ "defaultValue": null,
+ "description": "Inline styles applied to this part, or a callback receiving its progress status."
+ },
+ {
+ "name": "value",
+ "type": "number | null",
+ "required": true,
+ "defaultValue": null,
+ "description": "Controlled value in the min/max range. Use null for indeterminate progress."
+ }
+ ]
+ },
+ {
+ "name": "Track",
+ "props": [
+ {
+ "name": "children",
+ "type": "ReactNode",
+ "required": false,
+ "defaultValue": null,
+ "description": "The indicator and optional supporting content."
+ },
+ {
+ "name": "className",
+ "type": "string | ((state: ProgressTrackState) => string | undefined)",
+ "required": false,
+ "defaultValue": null,
+ "description": "Class applied to this part, or a callback receiving its progress status."
+ },
+ {
+ "name": "ref",
+ "type": "Ref<HTMLDivElement>",
+ "required": false,
+ "defaultValue": null,
+ "description": "Ref to the track div, or the element composed through Track.render."
+ },
+ {
+ "name": "render",
+ "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ProgressTrackState>",
+ "required": false,
+ "defaultValue": null,
+ "description": "Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element."
+ },
+ {
+ "name": "style",
+ "type": "CSSProperties | ((state: ProgressTrackState) => CSSProperties | undefined)",
+ "required": false,
+ "defaultValue": null,
+ "description": "Inline styles applied to this part, or a callback receiving its progress status."
+ }
+ ]
+ },
+ {
+ "name": "Indicator",
+ "props": [
+ {
+ "name": "className",
+ "type": "string | ((state: ProgressIndicatorState) => string | undefined)",
+ "required": false,
+ "defaultValue": null,
+ "description": "Class applied to this part, or a callback receiving its progress status."
+ },
+ {
+ "name": "ref",
+ "type": "Ref<HTMLDivElement>",
+ "required": false,
+ "defaultValue": null,
+ "description": "Ref to the indicator div, or the element composed through Indicator.render."
+ },
+ {
+ "name": "render",
+ "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ProgressIndicatorState>",
+ "required": false,
+ "defaultValue": null,
+ "description": "Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element."
+ },
+ {
+ "name": "style",
+ "type": "CSSProperties | ((state: ProgressIndicatorState) => CSSProperties | undefined)",
+ "required": false,
+ "defaultValue": null,
+ "description": "Inline styles applied to this part, or a callback receiving its progress status."
+ }
+ ]
+ },
+ {
+ "name": "Value",
+ "props": [
+ {
+ "name": "children",
+ "type": "((formattedValue: string | null, value: number | null) => ReactNode) | null",
+ "required": false,
+ "defaultValue": null,
+ "description": "Optional callback receiving the formatted value and raw value. Indeterminate progress passes indeterminate as formatted text. Without a callback, indeterminate progress displays no content."
+ },
+ {
+ "name": "className",
+ "type": "string | ((state: ProgressValueState) => string | undefined)",
+ "required": false,
+ "defaultValue": null,
+ "description": "Class applied to this part, or a callback receiving its progress status."
+ },
+ {
+ "name": "ref",
+ "type": "Ref<HTMLSpanElement>",
+ "required": false,
+ "defaultValue": null,
+ "description": "Ref to the value span, or the element composed through Value.render."
+ },
+ {
+ "name": "render",
+ "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ProgressValueState>",
+ "required": false,
+ "defaultValue": null,
+ "description": "Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element."
+ },
+ {
+ "name": "style",
+ "type": "CSSProperties | ((state: ProgressValueState) => CSSProperties | undefined)",
+ "required": false,
+ "defaultValue": null,
+ "description": "Inline styles applied to this part, or a callback receiving its progress status."
+ }
+ ]
+ },
+ {
+ "name": "Label",
+ "props": [
+ {
+ "name": "children",
+ "type": "ReactNode",
+ "required": false,
+ "defaultValue": null,
+ "description": "Visible text that supplies the accessible name of the root."
+ },
+ {
+ "name": "className",
+ "type": "string | ((state: ProgressLabelState) => string | undefined)",
+ "required": false,
+ "defaultValue": null,
+ "description": "Class applied to this part, or a callback receiving its progress status."
+ },
+ {
+ "name": "ref",
+ "type": "Ref<HTMLSpanElement>",
+ "required": false,
+ "defaultValue": null,
+ "description": "Ref to the label span, or the element composed through Label.render."
+ },
+ {
+ "name": "render",
+ "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ProgressLabelState>",
+ "required": false,
+ "defaultValue": null,
+ "description": "Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element."
+ },
+ {
+ "name": "style",
+ "type": "CSSProperties | ((state: ProgressLabelState) => CSSProperties | undefined)",
+ "required": false,
+ "defaultValue": null,
+ "description": "Inline styles applied to this part, or a callback receiving its progress status."
+ }
+ ]
+ }
+ ]
+ },
{
"name": "ProgressBar",
"entryPoint": "twenty-ui/primitives/feedback",
"slug": "feedback/progress-bar",
"props": [
{
- "name": "ariaLabel",
+ "name": "aria-label",
+ "type": "string",
+ "required": false,
+ "defaultValue": null,
+ "description": "Accessible name identifying the measured operation."
+ },
+ {
+ "name": "aria-labelledby",
+ "type": "string",
+ "required": false,
+ "defaultValue": null,
+ "description": "ID of the visible label that names the operation."
+ },
+ {
+ "name": "aria-valuetext",
"type": "string",
"required": false,
"defaultValue": null,
- "description": "Accessible name describing the operation being measured."
+ "description": "Human-readable progress value overriding the default formatted value."
},
{
"name": "backgroundColor",
@@ -939,68 +1259,103 @@
"defaultValue": null,
"description": "CSS color of the filled bar. Defaults to the primary text color."
},
+ {
+ "name": "children",
+ "type": "ReactNode",
+ "required": false,
+ "defaultValue": null,
+ "description": "Additional Progress parts or supporting content inside the root."
+ },
{
"name": "className",
- "type": "string",
+ "type": "string | ((state: ProgressRootState) => string | undefined)",
"required": false,
"defaultValue": null,
- "description": "CSS class applied to the progress root."
+ "description": "Class applied to the progress root, or a callback receiving its status."
},
{
- "name": "onGrowInComplete",
- "type": "(() => void)",
+ "name": "format",
+ "type": "NumberFormatOptions",
"required": false,
"defaultValue": null,
- "description": "Called when the grow-in animation ends."
+ "description": "Intl.NumberFormat options for the clamped numeric value. The default displays the normalized percentage."
},
{
- "name": "size",
- "type": "\"md\" | \"sm\"",
+ "name": "getAriaValueText",
+ "type": "((formattedValue: string, value: number | null) => string)",
"required": false,
- "defaultValue": "md",
- "description": "Bar height: `sm` (6px) or `md` (8px)."
+ "defaultValue": null,
+ "description": "Receives the formatted value and raw value, including null, and returns an accessible value description."
},
{
- "name": "value",
+ "name": "locale",
+ "type": "LocalesArgument",
+ "required": false,
+ "defaultValue": null,
+ "description": "Locale or locale list used to format the value. Defaults to the runtime locale."
+ },
+ {
+ "name": "max",
"type": "number",
- "required": true,
+ "required": false,
+ "defaultValue": "100",
+ "description": "Inclusive maximum. Defaults to 100."
+ },
+ {
+ "name": "min",
+ "type": "number",
+ "required": false,
+ "defaultValue": "0",
+ "description": "Inclusive minimum. Defaults to 0."
+ },
+ {
+ "name": "ref",
+ "type": "Ref<HTMLDivElement>",
+ "required": false,
"defaultValue": null,
- "description": "Current progress from 0 to 100."
+ "description": "Ref to the root div, or the element composed through render."
},
{
- "name": "withBorderRadius",
- "type": "boolean",
+ "name": "render",
+ "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, ProgressRootState>",
"required": false,
- "defaultValue": "false",
- "description": "Rounds the track and indicator corners."
+ "defaultValue": null,
+ "description": "Composes the root with an element or render callback. Forward the supplied props and ref to retain progress semantics."
},
{
- "name": "withGlint",
- "type": "boolean",
+ "name": "size",
+ "type": "\"md\" | \"sm\"",
"required": false,
- "defaultValue": "false",
- "description": "Sweeps a highlight across the filled bar each time the value changes."
+ "defaultValue": "md",
+ "description": "Bar height: sm (6px) or md (8px)."
},
{
- "name": "withGrowIn",
- "type": "boolean",
+ "name": "style",
+ "type": "CSSProperties | ((state: ProgressRootState) => CSSProperties | undefined)",
"required": false,
- "defaultValue": "false",
- "description": "Grows the bar in from zero width when it mounts."
+ "defaultValue": null,
+ "description": "Inline styles applied to the progress root, or a callback receiving its status."
},
{
- "name": "withMinimumFillWidth",
+ "name": "value",
+ "type": "number | null",
+ "required": true,
+ "defaultValue": null,
+ "description": "Controlled value in the min/max range. Use null for indeterminate progress."
+ },
+ {
+ "name": "withBorderRadius",
"type": "boolean",
"required": false,
- "defaultValue": "true",
- "description": "Keeps a small visible fill for any value above zero."
+ "defaultValue": "false",
+ "description": "Rounds the track and indicator corners."
},
{
- "name": "withSpringFill",
+ "name": "withMinimumFillWidth",
"type": "boolean",
"required": false,
- "defaultValue": "false",
- "description": "Animates value changes with a spring that slightly overshoots the target."
+ "defaultValue": "true",
+ "description": "Applies a cosmetic minimum of up to 12px, capped at half the track width, only above the minimum and below completion."
}
]
},
diff --git a/packages/twenty-ui/scripts/generateDocsData.ts b/packages/twenty-ui/scripts/generateDocsData.ts
index fc142f33480..7c853f21e0a 100644
--- a/packages/twenty-ui/scripts/generateDocsData.ts
+++ b/packages/twenty-ui/scripts/generateDocsData.ts
@@ -222,12 +222,16 @@ const components: ComponentDocumentation[] = DOCUMENTED_COMPONENTS.map(
(component) => {
const source = program.getSourceFile(resolve(sourceRoot, component.source));
const moduleSymbol = source && checker.getSymbolAtLocation(source);
- const symbol =
+ let symbol =
moduleSymbol &&
checker
.getExportsOfModule(moduleSymbol)
.find((candidate) => candidate.name === component.name);
+ if (isDefined(symbol) && (symbol.flags & ts.SymbolFlags.Alias) !== 0) {
+ symbol = checker.getAliasedSymbol(symbol);
+ }
+
if (!symbol?.valueDeclaration) {
throw new Error(`Could not find the export for ${component.name}`);
}
@@ -278,17 +282,23 @@ const components: ComponentDocumentation[] = DOCUMENTED_COMPONENTS.map(
const parts = componentParts.map((part) => {
const declaration = part.valueDeclaration;
- if (!declaration || !ts.isPropertyAssignment(declaration)) {
+ const isNamespaceExport = (part.flags & ts.SymbolFlags.Alias) !== 0;
+ const isObjectPart =
+ isDefined(declaration) && ts.isPropertyAssignment(declaration);
+
+ if (!isObjectPart && !isNamespaceExport) {
throw new Error(`Could not resolve ${component.name}.${part.name}`);
}
- let partSymbol = checker.getSymbolAtLocation(declaration.initializer);
+ let partSymbol = isObjectPart
+ ? checker.getSymbolAtLocation(declaration.initializer)
+ : part;
if (!partSymbol) {
throw new Error(`Could not find ${component.name}.${part.name}`);
}
- if (partSymbol.flags & ts.SymbolFlags.Alias) {
+ if ((partSymbol.flags & ts.SymbolFlags.Alias) !== 0) {
partSymbol = checker.getAliasedSymbol(partSymbol);
}
diff --git a/packages/twenty-ui/src/components/data-display/MetricRow/MetricRow.tsx b/packages/twenty-ui/src/components/data-display/MetricRow/MetricRow.tsx
index 387a85dc15d..b56a9d276bc 100644
--- a/packages/twenty-ui/src/components/data-display/MetricRow/MetricRow.tsx
+++ b/packages/twenty-ui/src/components/data-display/MetricRow/MetricRow.tsx
@@ -1,5 +1,5 @@
import { useRender } from '@base-ui/react/use-render';
-import { isString } from '@sniptt/guards';
+import { isNonEmptyString } from '@sniptt/guards';
import { clsx } from 'clsx';
import { useId } from 'react';
@@ -22,6 +22,7 @@ export const MetricRow = ({
...props
}: MetricRowProps) => {
const labelId = useId();
+ const accessibleValueText = progressValueText ?? value;
return useRender({
render,
@@ -45,9 +46,9 @@ export const MetricRow = ({
size="sm"
barColor={progressColor}
aria-labelledby={labelId}
- aria-valuetext={
- progressValueText ?? (isString(value) ? value : undefined)
- }
+ {...(isNonEmptyString(accessibleValueText)
+ ? { 'aria-valuetext': accessibleValueText }
+ : {})}
>
{value}
</ProgressRing>
diff --git a/packages/twenty-ui/src/primitives/feedback/Progress/Progress.tsx b/packages/twenty-ui/src/primitives/feedback/Progress/Progress.tsx
new file mode 100644
index 00000000000..b2fca83e37d
--- /dev/null
+++ b/packages/twenty-ui/src/primitives/feedback/Progress/Progress.tsx
@@ -0,0 +1 @@
+export { Progress } from '@base-ui/react/progress';
diff --git a/packages/twenty-ui/src/primitives/feedback/Progress/__stories__/Progress.stories.tsx b/packages/twenty-ui/src/primitives/feedback/Progress/__stories__/Progress.stories.tsx
new file mode 100644
index 00000000000..3b23ef88558
--- /dev/null
+++ b/packages/twenty-ui/src/primitives/feedback/Progress/__stories__/Progress.stories.tsx
@@ -0,0 +1,93 @@
+import { isNull } from '@sniptt/guards';
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import { useState } from 'react';
+import { expect, userEvent, within } from 'storybook/test';
+
+import { Progress } from '@ui/primitives/feedback/Progress/Progress';
+import { Button } from '@ui/primitives/input/Button/Button';
+import { Text } from '@ui/primitives/typography/Text/Text';
+import { ComponentDecorator } from '@ui/testing/decorators/ComponentDecorator';
+
+const meta = {
+ title: 'UI/Feedback/Progress',
+ component: Progress.Root,
+ decorators: [ComponentDecorator],
+ args: { value: 70, min: 20, max: 120 },
+ parameters: { container: { width: 240 } },
+ render: (args) => (
+ <Progress.Root {...args} style={{ width: '100%' }}>
+ <Progress.Label render={<Text />}>Importing records</Progress.Label>
+ <Progress.Value render={<Text />} />
+ <Progress.Track
+ style={{ height: 8, background: 'var(--t-background-tertiary)' }}
+ >
+ <Progress.Indicator
+ style={{ background: 'var(--t-font-color-primary)' }}
+ />
+ </Progress.Track>
+ </Progress.Root>
+ ),
+} satisfies Meta<typeof Progress.Root>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};
+
+export const LabelAndValue: Story = {
+ play: async ({ canvasElement }) => {
+ const canvas = within(canvasElement);
+ const progress = canvas.getByRole('progressbar', {
+ name: 'Importing records',
+ });
+
+ await expect(progress).toHaveAttribute('aria-valuenow', '70');
+ await expect(progress).toHaveAttribute('aria-valuemin', '20');
+ await expect(progress).toHaveAttribute('aria-valuemax', '120');
+ await expect(progress).toHaveAttribute('aria-valuetext', '50%');
+ await expect(canvas.getByText('50%')).toBeVisible();
+ },
+};
+
+const ControlledProgress = () => {
+ const [value, setValue] = useState<number | null>(null);
+
+ return (
+ <>
+ <Progress.Root value={value} max={1000} format={{ style: 'decimal' }}>
+ <Progress.Label>Importing records</Progress.Label>
+ <Progress.Value>
+ {(formattedValue) =>
+ isNull(value) ? 'Preparing import' : formattedValue
+ }
+ </Progress.Value>
+ </Progress.Root>
+ <Button onClick={() => setValue(600)}>Report records</Button>
+ <Button onClick={() => setValue(1000)}>Complete import</Button>
+ </>
+ );
+};
+
+export const Controlled: Story = {
+ render: () => <ControlledProgress />,
+ play: async ({ canvasElement }) => {
+ const canvas = within(canvasElement);
+ const progress = canvas.getByRole('progressbar', {
+ name: 'Importing records',
+ });
+
+ await expect(progress).not.toHaveAttribute('aria-valuenow');
+ await expect(canvas.getByText('Preparing import')).toBeVisible();
+ await userEvent.click(
+ canvas.getByRole('button', { name: 'Report records' }),
+ );
+ await expect(progress).toHaveAttribute('aria-valuenow', '600');
+ await expect(canvas.getByText('600')).toBeVisible();
+ await userEvent.click(
+ canvas.getByRole('button', { name: 'Complete import' }),
+ );
+ await expect(progress).toHaveAttribute('aria-valuenow', '1000');
+ await expect(progress).toHaveAttribute('data-complete');
+ },
+};
diff --git a/packages/twenty-ui/src/primitives/feedback/Progress/__tests__/Progress.reduced-motion.test.tsx b/packages/twenty-ui/src/primitives/feedback/Progress/__tests__/Progress.reduced-motion.test.tsx
new file mode 100644
index 00000000000..a4e98560ce7
--- /dev/null
+++ b/packages/twenty-ui/src/primitives/feedback/Progress/__tests__/Progress.reduced-motion.test.tsx
@@ -0,0 +1,54 @@
+import { cleanup, render, screen } from '@testing-library/react';
+import { afterEach, expect, it } from 'vitest';
+
+import { ProgressBar, ProgressRing } from '@ui/primitives/feedback';
+import { ThemeProvider } from '@ui/theme';
+import '@ui/theme/theme-light.css';
+import { isDefined } from '@ui/utilities/utils/isDefined';
+
+afterEach(cleanup);
+
+it.each([
+ {
+ name: 'bar',
+ component: (
+ <ProgressBar value={null} aria-label="Bar" style={{ width: 200 }} />
+ ),
+ indicatorWidth: 50,
+ indicatorSelector: ':scope > div > div',
+ },
+ {
+ name: 'ring',
+ component: <ProgressRing value={null} aria-label="Ring" />,
+ indicatorWidth: 16,
+ indicatorSelector: ':scope > div',
+ },
+])(
+ 'keeps the indeterminate $name visible without movement when reduced motion is preferred',
+ ({ component, indicatorWidth, indicatorSelector }) => {
+ render(<ThemeProvider colorScheme="light">{component}</ThemeProvider>);
+
+ expect(window.matchMedia('(prefers-reduced-motion: reduce)').matches).toBe(
+ true,
+ );
+ const progress = screen.getByRole('progressbar');
+ const indicator = progress.querySelector<HTMLElement>(indicatorSelector);
+ if (!isDefined(indicator)) {
+ throw new Error('Indeterminate progress indicator is missing');
+ }
+
+ expect(
+ getComputedStyle(progress)
+ .getPropertyValue('--t-animation-duration-normal')
+ .trim(),
+ ).toBe('0.3');
+ expect(indicator.getBoundingClientRect().width).toBe(indicatorWidth);
+ expect(indicator.getBoundingClientRect().height).toBeGreaterThan(0);
+ expect(progress).not.toHaveAttribute('aria-valuenow');
+ expect(getComputedStyle(indicator).animationName).toBe('none');
+ expect(progress.getAnimations({ subtree: true })).toHaveLength(0);
+ for (const element of [indicator, ...progress.querySelectorAll('circle')]) {
+ expect(getComputedStyle(element).transitionDuration).toBe('0s');
+ }
+ },
+);
diff --git a/packages/twenty-ui/src/primitives/feedback/Progress/__tests__/Progress.test.tsx b/packages/twenty-ui/src/primitives/feedback/Progress/__tests__/Progress.test.tsx
new file mode 100644
index 00000000000..bb8e72ea9af
--- /dev/null
+++ b/packages/twenty-ui/src/primitives/feedback/Progress/__tests__/Progress.test.tsx
@@ -0,0 +1,266 @@
+import { type Progress as BaseProgress } from '@base-ui/react/progress';
+import { render, screen } from '@testing-library/react';
+import { createRef } from 'react';
+import { describe, expect, expectTypeOf, it, vi } from 'vitest';
+
+import {
+ Progress,
+ ProgressBar,
+ ProgressRing,
+ type ProgressRootProps,
+} from '@ui/primitives/feedback';
+
+const getRingPercentage = (root: HTMLElement) => {
+ const circle = root.querySelector('circle:last-child');
+ const circumference = Number(circle?.getAttribute('stroke-dasharray'));
+ const offset = Number(circle?.getAttribute('stroke-dashoffset'));
+
+ return 100 * (1 - offset / circumference);
+};
+
+const getBarIndicator = (root: HTMLElement) =>
+ root.firstElementChild?.firstElementChild;
+
+describe('Progress public contract', () => {
+ it('preserves the installed namespace and native callback types', () => {
+ expectTypeOf<typeof Progress>().toEqualTypeOf<typeof BaseProgress>();
+ expectTypeOf<Progress.Status>().toEqualTypeOf<BaseProgress.Status>();
+ expectTypeOf<ProgressRootProps>().toEqualTypeOf<BaseProgress.Root.Props>();
+
+ const onClick: NonNullable<ProgressRootProps['onClick']> = (event) => {
+ expectTypeOf(event.preventBaseUIHandler).toEqualTypeOf<() => void>();
+ };
+
+ expect(onClick).toBeTypeOf('function');
+ });
+
+ it('composes labeled parts with value formatting and refs', () => {
+ const rootRef = createRef<HTMLDivElement>();
+ const labelRef = createRef<HTMLSpanElement>();
+ const valueRef = createRef<HTMLSpanElement>();
+ const trackRef = createRef<HTMLDivElement>();
+ const indicatorRef = createRef<HTMLDivElement>();
+
+ render(
+ <Progress.Root value={25} min={10} max={70} ref={rootRef}>
+ <Progress.Label ref={labelRef}>Files imported</Progress.Label>
+ <Progress.Value ref={valueRef} />
+ <Progress.Track ref={trackRef}>
+ <Progress.Indicator ref={indicatorRef} />
+ </Progress.Track>
+ </Progress.Root>,
+ );
+
+ const progress = screen.getByRole('progressbar', {
+ name: 'Files imported',
+ });
+ expect(rootRef.current).toBe(progress);
+ expect(labelRef.current).toBe(screen.getByText('Files imported'));
+ expect(valueRef.current).toBe(screen.getByText('25%'));
+ expect(trackRef.current).toContainElement(indicatorRef.current);
+ expect(indicatorRef.current).toHaveStyle({ width: '25%' });
+ });
+
+ it('keeps the raw value available in value children and accessible formatting', () => {
+ const getAriaValueText = vi.fn(
+ (formattedValue: string) => `${formattedValue} files`,
+ );
+
+ render(
+ <ProgressBar
+ value={90}
+ min={10}
+ max={70}
+ format={{ maximumFractionDigits: 0 }}
+ locale="en-US"
+ getAriaValueText={getAriaValueText}
+ >
+ <Progress.Label>Files imported</Progress.Label>
+ <Progress.Value>
+ {(formattedValue, value) => `${formattedValue} of ${value}`}
+ </Progress.Value>
+ </ProgressBar>,
+ );
+
+ expect(
+ screen.getByRole('progressbar', { name: 'Files imported' }),
+ ).toHaveAttribute('aria-valuetext', '70 files');
+ expect(screen.getByText('70 of 90')).toBeInTheDocument();
+ expect(getAriaValueText).toHaveBeenCalledWith('70', 90);
+ });
+
+ it('preserves upstream indeterminate value content and custom display', () => {
+ const valueContent = vi.fn(() => 'Preparing import');
+ render(
+ <Progress.Root value={null} aria-label="Import">
+ <Progress.Value>{valueContent}</Progress.Value>
+ </Progress.Root>,
+ );
+
+ expect(valueContent).toHaveBeenCalledWith('indeterminate', null);
+ expect(screen.getByText('Preparing import')).toHaveAttribute(
+ 'aria-hidden',
+ 'true',
+ );
+ expect(screen.getByRole('progressbar', { name: 'Import' })).toHaveAttribute(
+ 'aria-valuetext',
+ 'indeterminate progress',
+ );
+ });
+
+ it('preserves explicit aria-valuetext and aria-labelledby on both presets', () => {
+ render(
+ <>
+ <span id="progress-name">Import status</span>
+ <ProgressBar
+ value={25}
+ aria-labelledby="progress-name"
+ aria-valuetext="One file remaining"
+ />
+ <ProgressRing
+ value={25}
+ aria-labelledby="progress-name"
+ aria-valuetext="One file remaining"
+ />
+ </>,
+ );
+
+ for (const progress of screen.getAllByRole('progressbar', {
+ name: 'Import status',
+ })) {
+ expect(progress).toHaveAttribute('aria-valuetext', 'One file remaining');
+ }
+ });
+});
+
+describe('Progress preset agreement', () => {
+ it.each([
+ {
+ value: 10,
+ min: 10,
+ max: 70,
+ percentage: 0,
+ normalizedValue: 10,
+ status: 'progressing',
+ },
+ {
+ value: 25,
+ min: 10,
+ max: 70,
+ percentage: 25,
+ normalizedValue: 25,
+ status: 'progressing',
+ },
+ {
+ value: 90,
+ min: 10,
+ max: 70,
+ percentage: 100,
+ normalizedValue: 70,
+ status: 'complete',
+ },
+ {
+ value: -90,
+ min: 10,
+ max: 70,
+ percentage: 0,
+ normalizedValue: 10,
+ status: 'progressing',
+ },
+ {
+ value: -20,
+ min: -40,
+ max: 40,
+ percentage: 25,
+ normalizedValue: -20,
+ status: 'progressing',
+ },
+ {
+ value: 10,
+ min: 10,
+ max: 10,
+ percentage: 0,
+ normalizedValue: 10,
+ status: 'complete',
+ },
+ ])(
+ 'shares geometry, semantic values and status for $value in $min to $max',
+ ({ value, min, max, percentage, normalizedValue, status }) => {
+ render(
+ <>
+ <ProgressBar value={value} min={min} max={max} aria-label="Bar" />
+ <ProgressRing value={value} min={min} max={max} aria-label="Ring" />
+ </>,
+ );
+
+ const bar = screen.getByRole('progressbar', { name: 'Bar' });
+ const ring = screen.getByRole('progressbar', { name: 'Ring' });
+ for (const progress of [bar, ring]) {
+ expect(progress).toHaveAttribute('aria-valuemin', String(min));
+ expect(progress).toHaveAttribute('aria-valuemax', String(max));
+ expect(progress).toHaveAttribute(
+ 'aria-valuenow',
+ String(normalizedValue),
+ );
+ expect(progress).toHaveAttribute('aria-valuetext', `${percentage}%`);
+ expect(progress).toHaveAttribute(`data-${status}`);
+ }
+ expect(getBarIndicator(bar)).toHaveStyle({ width: `${percentage}%` });
+ expect(getRingPercentage(ring)).toBeCloseTo(percentage);
+ expect(getBarIndicator(bar)?.hasAttribute('data-minimum-fill')).toBe(
+ percentage > 0 && percentage < 100,
+ );
+ if (percentage === 0) {
+ expect(ring.querySelector('circle:last-child')).toHaveAttribute(
+ 'stroke-linecap',
+ 'butt',
+ );
+ }
+ },
+ );
+
+ it.each([
+ null,
+ Number.NaN,
+ Number.POSITIVE_INFINITY,
+ Number.NEGATIVE_INFINITY,
+ ])('preserves upstream indeterminate semantics for %s', (value) => {
+ render(
+ <>
+ <ProgressBar value={value} min={10} max={70} aria-label="Bar" />
+ <ProgressRing value={value} min={10} max={70} aria-label="Ring" />
+ </>,
+ );
+
+ const bar = screen.getByRole('progressbar', { name: 'Bar' });
+ const ring = screen.getByRole('progressbar', { name: 'Ring' });
+ for (const progress of [bar, ring]) {
+ expect(progress).not.toHaveAttribute('aria-valuenow');
+ expect(progress).toHaveAttribute('data-indeterminate');
+ expect(progress).toHaveAttribute(
+ 'aria-valuetext',
+ 'indeterminate progress',
+ );
+ }
+ expect(getBarIndicator(bar)).not.toHaveAttribute('data-minimum-fill');
+ expect(getBarIndicator(bar)).not.toHaveStyle({ width: '0%' });
+ expect(getRingPercentage(ring)).toBeCloseTo(25);
+ expect(ring.querySelector('svg')).toHaveAttribute('aria-hidden', 'true');
+ expect(ring.querySelector('svg')).toHaveAttribute('focusable', 'false');
+ });
+
+ it('can disable minimum fill without changing the semantic value', () => {
+ render(
+ <ProgressBar
+ value={11}
+ min={10}
+ max={70}
+ withMinimumFillWidth={false}
+ aria-label="Files"
+ />,
+ );
+ const progress = screen.getByRole('progressbar', { name: 'Files' });
+ expect(progress).toHaveAttribute('aria-valuenow', '11');
+ expect(getBarIndicator(progress)).not.toHaveAttribute('data-minimum-fill');
+ });
+});
diff --git a/packages/twenty-ui/src/primitives/feedback/Progress/internal/getProgressIndicatorPercentage.ts b/packages/twenty-ui/src/primitives/feedback/Progress/internal/getProgressIndicatorPercentage.ts
new file mode 100644
index 00000000000..f9df94070fa
--- /dev/null
+++ b/packages/twenty-ui/src/primitives/feedback/Progress/internal/getProgressIndicatorPercentage.ts
@@ -0,0 +1,13 @@
+import { isString } from '@sniptt/guards';
+import { type CSSProperties } from 'react';
+
+type GetProgressIndicatorPercentageParams = {
+ width: CSSProperties['width'];
+ fallbackPercentage: number;
+};
+
+export const getProgressIndicatorPercentage = ({
+ width,
+ fallbackPercentage,
+}: GetProgressIndicatorPercentageParams) =>
+ isString(width) ? Number.parseFloat(width) : fallbackPercentage;
diff --git a/packages/twenty-ui/src/primitives/feedback/Progress/types/ProgressIndicatorProps.ts b/packages/twenty-ui/src/primitives/feedback/Progress/types/ProgressIndicatorProps.ts
new file mode 100644
index 00000000000..20a79b9d0c2
--- /dev/null
+++ b/packages/twenty-ui/src/primitives/feedback/Progress/types/ProgressIndicatorProps.ts
@@ -0,0 +1,3 @@
+import { type Progress } from '@base-ui/react/progress';
+
+export type ProgressIndicatorProps = Progress.Indicator.Props;
diff --git a/packages/twenty-ui/src/primitives/feedback/Progress/types/ProgressIndicatorState.ts b/packages/twenty-ui/src/primitives/feedback/Progress/types/ProgressIndicatorState.ts
new file mode 100644
index 00000000000..84a2e13f19f
--- /dev/null
+++ b/packages/twenty-ui/src/primitives/feedback/Progress/types/ProgressIndicatorState.ts
@@ -0,0 +1,3 @@
+import { type Progress } from '@base-ui/react/progress';
+
+export type ProgressIndicatorState = Progress.Indicator.State;
diff --git a/packages/twenty-ui/src/primitives/feedback/Progress/types/ProgressLabelProps.ts b/packages/twenty-ui/src/primitives/feedback/Progress/types/ProgressLabelProps.ts
new file mode 100644
index 00000000000..d55bb082b03
--- /dev/null
+++ b/packages/twenty-ui/src/primitives/feedback/Progress/types/ProgressLabelProps.ts
@@ -0,0 +1,3 @@
+import { type Progress } from '@base-ui/react/progress';
+
+export type ProgressLabelProps = Progress.Label.Props;
diff --git a/packages/twenty-ui/src/primitives/feedback/Progress/types/ProgressLabelState.ts b/packages/twenty-ui/src/primitives/feedback/Progress/types/ProgressLabelState.ts
new file mode 100644
index 00000000000..b59e5f7e529
--- /dev/null
+++ b/packages/twenty-ui/src/primitives/feedback/Progress/types/ProgressLabelState.ts
@@ -0,0 +1,3 @@
+import { type Progress } from '@base-ui/react/progress';
+
+export type ProgressLabelState = Progress.Label.State;
diff --git a/packages/twenty-ui/src/primitives/feedback/Progress/types/ProgressRootProps.ts b/packages/twenty-ui/src/primitives/feedback/Progress/types/ProgressRootProps.ts
new file mode 100644
index 00000000000..734fb7d1376
--- /dev/null
+++ b/packages/twenty-ui/src/primitives/feedback/Progress/types/ProgressRootProps.ts
@@ -0,0 +1,3 @@
+import { type Progress } from '@base-ui/react/progress';
+
+export type ProgressRootProps = Progress.Root.Props;
diff --git a/packages/twenty-ui/src/primitives/feedback/Progress/types/ProgressRootState.ts b/packages/twenty-ui/src/primitives/feedback/Progress/types/ProgressRootState.ts
new file mode 100644
index 00000000000..7fa33058b8a
--- /dev/null
+++ b/packages/twenty-ui/src/primitives/feedback/Progress/types/ProgressRootState.ts
@@ -0,0 +1,3 @@
+import { type Progress } from '@base-ui/react/progress';
+
+export type ProgressRootState = Progress.Root.State;
diff --git a/packages/twenty-ui/src/primitives/feedback/Progress/types/ProgressStatus.ts b/packages/twenty-ui/src/primitives/feedback/Progress/types/ProgressStatus.ts
new file mode 100644
index 00000000000..8f104c55fd6
--- /dev/null
+++ b/packages/twenty-ui/src/primitives/feedback/Progress/types/ProgressStatus.ts
@@ -0,0 +1,3 @@
+import { type Progress } from '@base-ui/react/progress';
+
+export type ProgressStatus = Progress.Status;
diff --git a/packages/twenty-ui/src/primitives/feedback/Progress/types/ProgressTrackProps.ts b/packages/twenty-ui/src/primitives/feedback/Progress/types/ProgressTrackProps.ts
new file mode 100644
index 00000000000..08e8df5030e
--- /dev/null
+++ b/packages/twenty-ui/src/primitives/feedback/Progress/types/ProgressTrackProps.ts
@@ -0,0 +1,3 @@
+import { type Progress } from '@base-ui/react/progress';
+
+export type ProgressTrackProps = Progress.Track.Props;
diff --git a/packages/twenty-ui/src/primitives/feedback/Progress/types/ProgressTrackState.ts b/packages/twenty-ui/src/primitives/feedback/Progress/types/ProgressTrackState.ts
new file mode 100644
index 00000000000..5a98be0bdac
--- /dev/null
+++ b/packages/twenty-ui/src/primitives/feedback/Progress/types/ProgressTrackState.ts
@@ -0,0 +1,3 @@
+import { type Progress } from '@base-ui/react/progress';
+
+export type ProgressTrackState = Progress.Track.State;
diff --git a/packages/twenty-ui/src/primitives/feedback/Progress/types/ProgressValueProps.ts b/packages/twenty-ui/src/primitives/feedback/Progress/types/ProgressValueProps.ts
new file mode 100644
index 00000000000..774af8775fb
--- /dev/null
+++ b/packages/twenty-ui/src/primitives/feedback/Progress/types/ProgressValueProps.ts
@@ -0,0 +1,3 @@
+import { type Progress } from '@base-ui/react/progress';
+
+export type ProgressValueProps = Progress.Value.Props;
diff --git a/packages/twenty-ui/src/primitives/feedback/Progress/types/ProgressValueState.ts b/packages/twenty-ui/src/primitives/feedback/Progress/types/ProgressValueState.ts
new file mode 100644
index 00000000000..43c275cce76
--- /dev/null
+++ b/packages/twenty-ui/src/primitives/feedback/Progress/types/ProgressValueState.ts
@@ -0,0 +1,3 @@
+import { type Progress } from '@base-ui/react/progress';
+
+export type ProgressValueState = Progress.Value.State;
diff --git a/packages/twenty-ui/src/primitives/feedback/ProgressBar/ProgressBar.module.scss b/packages/twenty-ui/src/primitives/feedback/ProgressBar/ProgressBar.module.scss
index 774211d7824..b5c148089cd 100644
--- a/packages/twenty-ui/src/primitives/feedback/ProgressBar/ProgressBar.module.scss
+++ b/packages/twenty-ui/src/primitives/feedback/ProgressBar/ProgressBar.module.scss
@@ -14,10 +14,6 @@
border-radius: var(--t-border-radius-pill);
corner-shape: round;
}
-
- &[data-grow-in] {
- animation: progressBarGrowIn duration(normal) cubic-bezier(0.2, 0, 0, 1);
- }
}
.track {
@@ -39,74 +35,33 @@
corner-shape: round;
}
- &[data-spring-fill] {
- transition: width calc(#{duration(normal)} * 2)
- linear(
- 0,
- 0.092,
- 0.285,
- 0.496,
- 0.681,
- 0.823,
- 0.922,
- 0.982,
- 1.015,
- 1.028,
- 1.03,
- 1.026,
- 1.02,
- 1.014,
- 1.008,
- 1.004,
- 1.002,
- 1,
- 0.999,
- 0.999,
- 1
- );
+ &[data-minimum-fill] {
+ min-width: min(12px, 50%);
}
- &[data-nonzero] {
- min-width: 12px;
+ &[data-indeterminate] {
+ animation: progressBarIndeterminate calc(#{duration(normal)} * 5)
+ ease-in-out infinite;
+ width: 25%;
}
}
-.glint {
- animation: progressBarGlint calc(#{duration(normal)} * 3)
- cubic-bezier(0.2, 0, 0, 1) forwards;
- backdrop-filter: brightness(1.6);
- inset: 0;
- mask-image: linear-gradient(90deg, transparent, black, transparent);
- position: absolute;
- transform: translateX(-100%);
-}
-
-@keyframes progressBarGrowIn {
- from {
- width: 0;
- }
-}
-
-@keyframes progressBarGlint {
+@keyframes progressBarIndeterminate {
from {
transform: translateX(-100%);
}
to {
- transform: translateX(100%);
+ transform: translateX(400%);
}
}
@media (prefers-reduced-motion: reduce) {
- .bar[data-grow-in] {
- animation-duration: 0s;
- }
-
- .indicator[data-spring-fill] {
+ .indicator {
transition: none;
- }
- .glint {
- display: none;
+ &[data-indeterminate] {
+ animation: none;
+ }
}
}
diff --git a/packages/twenty-ui/src/primitives/feedback/ProgressBar/ProgressBar.module.scss.d.ts b/packages/twenty-ui/src/primitives/feedback/ProgressBar/ProgressBar.module.scss.d.ts
index 261a16c7b3d..27476d00cba 100644
--- a/packages/twenty-ui/src/primitives/feedback/ProgressBar/ProgressBar.module.scss.d.ts
+++ b/packages/twenty-ui/src/primitives/feedback/ProgressBar/ProgressBar.module.scss.d.ts
@@ -2,6 +2,5 @@ declare const classNames: {
readonly bar: 'bar';
readonly track: 'track';
readonly indicator: 'indicator';
- readonly glint: 'glint';
};
export default classNames;
diff --git a/packages/twenty-ui/src/primitives/feedback/ProgressBar/ProgressBar.tsx b/packages/twenty-ui/src/primitives/feedback/ProgressBar/ProgressBar.tsx
index 34050d003f6..02687f256ab 100644
--- a/packages/twenty-ui/src/primitives/feedback/ProgressBar/ProgressBar.tsx
+++ b/packages/twenty-ui/src/primitives/feedback/ProgressBar/ProgressBar.tsx
@@ -1,57 +1,61 @@
-import { Progress } from '@base-ui/react/progress';
-import { isNonEmptyString } from '@sniptt/guards';
-import { clsx } from 'clsx';
+import { isFunction, isNonEmptyString } from '@sniptt/guards';
import { type CSSProperties } from 'react';
+import { mergeClassNames } from '@ui/utilities/internal/mergeClassNames';
+
+import { getProgressIndicatorPercentage } from '../Progress/internal/getProgressIndicatorPercentage';
+import { Progress } from '../Progress/Progress';
+
import styles from './ProgressBar.module.scss';
import { type ProgressBarProps } from './types/ProgressBarProps';
export const ProgressBar = ({
- value,
size = 'md',
className,
+ style,
+ children,
barColor,
backgroundColor = 'none',
withBorderRadius = false,
- withGrowIn = false,
- withGlint = false,
- withSpringFill = false,
withMinimumFillWidth = true,
- ariaLabel,
- onGrowInComplete,
-}: ProgressBarProps) => {
- return (
- <Progress.Root
- className={clsx(styles.bar, className)}
- data-size={size}
- data-with-border-radius={withBorderRadius || undefined}
- data-grow-in={withGrowIn || undefined}
- aria-label={ariaLabel}
- value={value}
- onAnimationEnd={(event) => {
- if (withGrowIn && event.target === event.currentTarget) {
- onGrowInComplete?.();
- }
- }}
- style={
- {
- '--progress-bar-background-color': backgroundColor,
- ...(isNonEmptyString(barColor)
- ? { '--progress-bar-color': barColor }
- : {}),
- } as CSSProperties
- }
- >
- <Progress.Track className={styles.track}>
- <Progress.Indicator
- className={styles.indicator}
- data-with-border-radius={withBorderRadius || undefined}
- data-spring-fill={withSpringFill || undefined}
- data-nonzero={(withMinimumFillWidth && value > 0) || undefined}
- >
- {withGlint && <span key={value} className={styles.glint} />}
- </Progress.Indicator>
- </Progress.Track>
- </Progress.Root>
- );
-};
+ ...props
+}: ProgressBarProps) => (
+ <Progress.Root
+ {...props}
+ className={mergeClassNames(styles.bar, className)}
+ data-size={size}
+ data-with-border-radius={withBorderRadius || undefined}
+ style={(state) =>
+ ({
+ '--progress-bar-background-color': backgroundColor,
+ ...(isNonEmptyString(barColor)
+ ? { '--progress-bar-color': barColor }
+ : {}),
+ ...(isFunction(style) ? style(state) : style),
+ }) as CSSProperties
+ }
+ >
+ <Progress.Track className={styles.track}>
+ <Progress.Indicator
+ className={styles.indicator}
+ data-with-border-radius={withBorderRadius || undefined}
+ render={(indicatorProps) => {
+ const percentage = getProgressIndicatorPercentage({
+ width: indicatorProps.style?.width,
+ fallbackPercentage: 0,
+ });
+ const hasMinimumFill =
+ withMinimumFillWidth && percentage > 0 && percentage < 100;
+
+ return (
+ <div
+ {...indicatorProps}
+ data-minimum-fill={hasMinimumFill || undefined}
+ />
+ );
+ }}
+ />
+ </Progress.Track>
+ {children}
+ </Progress.Root>
+);
diff --git a/packages/twenty-ui/src/primitives/feedback/ProgressBar/__stories__/ProgressBar.stories.tsx b/packages/twenty-ui/src/primitives/feedback/ProgressBar/__stories__/ProgressBar.stories.tsx
index 01707ed102b..35b0ccde560 100644
--- a/packages/twenty-ui/src/primitives/feedback/ProgressBar/__stories__/ProgressBar.stories.tsx
+++ b/packages/twenty-ui/src/primitives/feedback/ProgressBar/__stories__/ProgressBar.stories.tsx
@@ -2,14 +2,16 @@ import { type Meta, type StoryObj } from '@storybook/react-vite';
import { useState } from 'react';
import { expect, userEvent, within } from 'storybook/test';
-import { ComponentDecorator } from '@ui/testing/decorators/ComponentDecorator';
+import { type Progress, ProgressRing } from '@ui/primitives/feedback';
import { ProgressBar } from '@ui/primitives/feedback/ProgressBar/ProgressBar';
import { Button } from '@ui/primitives/input/Button/Button';
+import { ComponentDecorator } from '@ui/testing/decorators/ComponentDecorator';
const meta: Meta<typeof ProgressBar> = {
title: 'UI/Feedback/ProgressBar/ProgressBar',
component: ProgressBar,
decorators: [ComponentDecorator],
+ args: { value: 75, 'aria-label': 'Import progress' },
argTypes: {
className: { control: false },
value: { control: { type: 'range', min: 0, max: 100, step: 1 } },
@@ -20,71 +22,62 @@ export default meta;
type Story = StoryObj<typeof ProgressBar>;
-export const Default: Story = {
- args: {
- value: 75,
- ariaLabel: 'Progress',
- },
-};
+export const Default: Story = {};
export const Small: Story = {
- args: {
- value: 50,
- ariaLabel: 'Progress',
- size: 'sm',
- withBorderRadius: true,
- },
+ args: { value: 50, size: 'sm', withBorderRadius: true },
play: async ({ canvasElement }) => {
- const progressBar = await within(canvasElement).findByRole('progressbar', {
- name: 'Progress',
+ const progress = within(canvasElement).getByRole('progressbar', {
+ name: 'Import progress',
});
- expect(progressBar).toHaveAttribute('aria-valuenow', '50');
- await expect(progressBar).toHaveStyle({ height: '6px' });
+ await expect(progress).toHaveAttribute('aria-valuenow', '50');
+ await expect(progress).toHaveStyle({ height: '6px' });
},
};
-export const GrowInWithGlint: Story = {
- args: {
- value: 60,
- ariaLabel: 'Progress',
- withBorderRadius: true,
- withGrowIn: true,
- withGlint: true,
- },
- play: async ({ canvasElement }) => {
- const progressBar = await within(canvasElement).findByRole('progressbar', {
- name: 'Progress',
- });
-
- expect(progressBar).toHaveAttribute('aria-valuenow', '60');
- },
+export const CustomRange: Story = {
+ args: { value: 70, min: 20, max: 120, withBorderRadius: true },
};
-export const SpringFill: Story = {
- args: {
- value: 40,
- ariaLabel: 'Progress',
- withBorderRadius: true,
- withSpringFill: true,
- },
- play: async ({ canvasElement }) => {
- const progressBar = await within(canvasElement).findByRole('progressbar', {
- name: 'Progress',
- });
+export const Indeterminate: Story = {
+ args: { value: null, withBorderRadius: true },
+};
- expect(progressBar).toHaveAttribute('aria-valuenow', '40');
- },
+export const WithMinimumFill: Story = {
+ args: { value: 1, withMinimumFillWidth: true, withBorderRadius: true },
};
const ControlledProgressBar = () => {
- const [value, setValue] = useState(0);
+ const [value, setValue] = useState<number | null>(20);
+ const [maximum, setMaximum] = useState(120);
+ const appearance = (state: Progress.Root.State) => ({
+ opacity: state.status === 'complete' ? 0.5 : 1,
+ });
+ const className = (state: Progress.Root.State) => state.status;
return (
<>
- <ProgressBar value={value} ariaLabel="Import progress" />
- <Button onClick={() => setValue(50)}>Report progress</Button>
- <Button onClick={() => setValue(100)}>Complete import</Button>
+ <ProgressBar
+ value={value}
+ min={20}
+ max={maximum}
+ aria-label="Import progress"
+ className={className}
+ style={appearance}
+ />
+ <ProgressRing
+ value={value}
+ min={20}
+ max={maximum}
+ aria-label="Import progress ring"
+ className={className}
+ style={appearance}
+ />
+ <Button onClick={() => setValue(70)}>Report progress</Button>
+ <Button onClick={() => setMaximum(220)}>Extend import</Button>
+ <Button onClick={() => setValue(null)}>Await progress</Button>
+ <Button onClick={() => setValue(maximum)}>Complete import</Button>
</>
);
};
@@ -97,14 +90,76 @@ export const Controlled: Story = {
name: 'Import progress',
});
- expect(progress).toHaveAttribute('aria-valuenow', '0');
+ const ring = canvas.getByRole('progressbar', {
+ name: 'Import progress ring',
+ });
+ const expectSharedProgress = async (percentage: number) => {
+ const indicator =
+ progress.querySelector<HTMLElement>(':scope > div > div');
+ const circle = ring.querySelector('circle:last-child');
+ const circumference = Number(circle?.getAttribute('stroke-dasharray'));
+ const offset = Number(circle?.getAttribute('stroke-dashoffset'));
+
+ await expect(indicator?.style.width).toBe(`${percentage}%`);
+ await expect(100 * (1 - offset / circumference)).toBeCloseTo(percentage);
+ };
+
+ await expect(progress).toHaveAttribute('aria-valuenow', '20');
+ await expect(progress).toHaveAttribute('aria-valuemin', '20');
+ await expect(progress).toHaveAttribute('aria-valuemax', '120');
+ await expect(progress).toHaveAttribute('aria-valuetext', '0%');
+ await expectSharedProgress(0);
await userEvent.click(
canvas.getByRole('button', { name: 'Report progress' }),
);
- expect(progress).toHaveAttribute('aria-valuenow', '50');
+ await expect(progress).toHaveAttribute('aria-valuenow', '70');
+ await expect(progress).toHaveAttribute('aria-valuetext', '50%');
+ await expectSharedProgress(50);
+ await userEvent.click(
+ canvas.getByRole('button', { name: 'Extend import' }),
+ );
+ await expect(progress).toHaveAttribute('aria-valuemax', '220');
+ await expect(progress).toHaveAttribute('aria-valuetext', '25%');
+ await expectSharedProgress(25);
+ await userEvent.click(
+ canvas.getByRole('button', { name: 'Await progress' }),
+ );
+ await expect(progress).not.toHaveAttribute('aria-valuenow');
+ await expect(progress).toHaveAttribute('data-indeterminate');
+ await expect(ring).toHaveClass('indeterminate');
+ await expect(ring).not.toHaveAttribute('aria-valuenow');
await userEvent.click(
canvas.getByRole('button', { name: 'Complete import' }),
);
- expect(progress).toHaveAttribute('aria-valuenow', '100');
+ await expect(progress).toHaveAttribute('aria-valuenow', '220');
+ await expect(progress).toHaveAttribute('data-complete');
+ await expect(ring).toHaveAttribute('aria-valuenow', '220');
+ await expectSharedProgress(100);
+ for (const preset of [progress, ring]) {
+ await expect(preset).toHaveClass('complete');
+ await expect(preset).toHaveStyle({ opacity: '0.5' });
+ }
+ await expect(
+ canvas.getByRole('progressbar', { name: 'Import progress' }),
+ ).toBe(progress);
+ await expect(
+ canvas.getByRole('progressbar', { name: 'Import progress ring' }),
+ ).toBe(ring);
+ },
+};
+
+export const CompactMinimumFill: Story = {
+ args: { value: 1, style: { width: 8 }, withMinimumFillWidth: true },
+ play: async ({ canvasElement }) => {
+ const progress = within(canvasElement).getByRole('progressbar', {
+ name: 'Import progress',
+ });
+ const indicator = progress.firstElementChild?.firstElementChild;
+
+ await expect(progress).toHaveAttribute('aria-valuenow', '1');
+ await expect(indicator?.getBoundingClientRect().width).toBe(4);
+ await expect(indicator?.getBoundingClientRect().width).toBeLessThan(
+ progress.getBoundingClientRect().width,
+ );
},
};
diff --git a/packages/twenty-ui/src/primitives/feedback/ProgressBar/__tests__/ProgressBar.test.tsx b/packages/twenty-ui/src/primitives/feedback/ProgressBar/__tests__/ProgressBar.test.tsx
new file mode 100644
index 00000000000..1a306056954
--- /dev/null
+++ b/packages/twenty-ui/src/primitives/feedback/ProgressBar/__tests__/ProgressBar.test.tsx
@@ -0,0 +1,9 @@
+import { runComponentConformance } from '@test-utilities/conformance/runComponentConformance';
+
+import { ProgressBar } from '@ui/primitives/feedback';
+
+runComponentConformance({
+ name: 'ProgressBar',
+ element: <ProgressBar value={42} aria-label="Import progress" />,
+ refInstanceOf: HTMLDivElement,
+});
diff --git a/packages/twenty-ui/src/primitives/feedback/ProgressBar/types/ProgressBarProps.ts b/packages/twenty-ui/src/primitives/feedback/ProgressBar/types/ProgressBarProps.ts
index 615b60f63bb..20b6f7007ac 100644
--- a/packages/twenty-ui/src/primitives/feedback/ProgressBar/types/ProgressBarProps.ts
+++ b/packages/twenty-ui/src/primitives/feedback/ProgressBar/types/ProgressBarProps.ts
@@ -1,14 +1,9 @@
-export type ProgressBarProps = {
- value: number;
+import { type ProgressRootProps } from '../../Progress/types/ProgressRootProps';
+
+export type ProgressBarProps = ProgressRootProps & {
size?: 'sm' | 'md';
- className?: string;
barColor?: string;
backgroundColor?: string;
withBorderRadius?: boolean;
- withGrowIn?: boolean;
- withGlint?: boolean;
- withSpringFill?: boolean;
withMinimumFillWidth?: boolean;
- ariaLabel?: string;
- onGrowInComplete?: () => void;
};
diff --git a/packages/twenty-ui/src/primitives/feedback/ProgressRing/ProgressRing.module.scss b/packages/twenty-ui/src/primitives/feedback/ProgressRing/ProgressRing.module.scss
index 90d7bbf1f8a..adc2bbb79a7 100644
--- a/packages/twenty-ui/src/primitives/feedback/ProgressRing/ProgressRing.module.scss
+++ b/packages/twenty-ui/src/primitives/feedback/ProgressRing/ProgressRing.module.scss
@@ -9,8 +9,14 @@
}
.ring {
+ display: inline-flex;
flex-shrink: 0;
transform: rotate(-90deg);
+
+ &[data-indeterminate] {
+ animation: progressRingIndeterminate calc(#{duration(normal)} * 5) linear
+ infinite;
+ }
}
.track {
@@ -28,7 +34,17 @@
transition: stroke-dashoffset duration(normal) ease;
}
+@keyframes progressRingIndeterminate {
+ to {
+ transform: rotate(270deg);
+ }
+}
+
@media (prefers-reduced-motion: reduce) {
+ .ring[data-indeterminate] {
+ animation: none;
+ }
+
.indicator {
transition: none;
}
diff --git a/packages/twenty-ui/src/primitives/feedback/ProgressRing/ProgressRing.tsx b/packages/twenty-ui/src/primitives/feedback/ProgressRing/ProgressRing.tsx
index 07deea176df..2dc2f7f1a84 100644
--- a/packages/twenty-ui/src/primitives/feedback/ProgressRing/ProgressRing.tsx
+++ b/packages/twenty-ui/src/primitives/feedback/ProgressRing/ProgressRing.tsx
@@ -1,80 +1,35 @@
-import { Progress } from '@base-ui/react/progress';
-import { clamp } from '@base-ui/utils/clamp';
-import { isNonEmptyString } from '@sniptt/guards';
-import { clsx } from 'clsx';
+import { isFunction, isNonEmptyString } from '@sniptt/guards';
import { type CSSProperties } from 'react';
-import { isRenderableSlot } from '@ui/utilities/internal/isRenderableSlot';
-import { isDefined } from '@ui/utilities/utils/isDefined';
+import { mergeClassNames } from '@ui/utilities/internal/mergeClassNames';
+
+import { Progress } from '../Progress/Progress';
import styles from './ProgressRing.module.scss';
+import { ProgressRingIndicator } from './internal/ProgressRingIndicator';
import { type ProgressRingProps } from './types/ProgressRingProps';
-const RING_SIZE = { sm: 14, md: 16 };
-const STROKE_WIDTH = 2;
-
export const ProgressRing = ({
- value,
size = 'md',
barColor,
children,
className,
style,
- 'aria-valuetext': ariaValueText,
...props
-}: ProgressRingProps) => {
- const clampedValue = clamp(value, 0, 100);
- const boundedValue = Number.isNaN(clampedValue) ? 0 : clampedValue;
- const diameter = RING_SIZE[size];
- const radius = (diameter - STROKE_WIDTH) / 2;
- const circumference = 2 * Math.PI * radius;
-
- return (
- <Progress.Root
- {...props}
- value={boundedValue}
- min={0}
- max={100}
- getAriaValueText={(formattedValue) =>
- isNonEmptyString(ariaValueText) ? ariaValueText : formattedValue
- }
- className={clsx(styles.root, className)}
- style={
- {
- ...(isDefined(barColor) ? { '--progress-ring-color': barColor } : {}),
- ...style,
- } as CSSProperties
- }
- >
- {isRenderableSlot(children) && <span>{children}</span>}
- <svg
- className={styles.ring}
- width={diameter}
- height={diameter}
- viewBox={`0 0 ${diameter} ${diameter}`}
- aria-hidden="true"
- focusable="false"
- >
- <circle
- className={styles.track}
- cx={diameter / 2}
- cy={diameter / 2}
- r={radius}
- strokeWidth={STROKE_WIDTH}
- />
- <circle
- className={styles.indicator}
- cx={diameter / 2}
- cy={diameter / 2}
- r={radius}
- strokeWidth={STROKE_WIDTH}
- strokeDasharray={circumference}
- strokeDashoffset={
- circumference - (boundedValue / 100) * circumference
- }
- strokeLinecap="round"
- />
- </svg>
- </Progress.Root>
- );
-};
+}: ProgressRingProps) => (
+ <Progress.Root
+ {...props}
+ className={mergeClassNames(styles.root, className)}
+ style={(state) =>
+ ({
+ ...(isNonEmptyString(barColor)
+ ? { '--progress-ring-color': barColor }
+ : {}),
+ ...(isFunction(style) ? style(state) : style),
+ }) as CSSProperties
+ }
+ >
+ {children}
+ <ProgressRingIndicator size={size} />
+ </Progress.Root>
+);
diff --git a/packages/twenty-ui/src/primitives/feedback/ProgressRing/__stories__/ProgressRing.stories.tsx b/packages/twenty-ui/src/primitives/feedback/ProgressRing/__stories__/ProgressRing.stories.tsx
index 94793c8d308..22f21c7f33c 100644
--- a/packages/twenty-ui/src/primitives/feedback/ProgressRing/__stories__/ProgressRing.stories.tsx
+++ b/packages/twenty-ui/src/primitives/feedback/ProgressRing/__stories__/ProgressRing.stories.tsx
@@ -53,13 +53,6 @@ export const WithValue: Story = {
const BOUNDARY_VALUES = [
{ label: 'Below zero', value: -10, expected: 0 },
{ label: 'Above one hundred', value: 120, expected: 100 },
- { label: 'Invalid value', value: Number.NaN, expected: 0 },
- { label: 'Negative infinity', value: Number.NEGATIVE_INFINITY, expected: 0 },
- {
- label: 'Positive infinity',
- value: Number.POSITIVE_INFINITY,
- expected: 100,
- },
{ label: 'Fractional progress', value: 42.5, expected: 42.5 },
];
@@ -87,6 +80,45 @@ export const BoundedValues: Story = {
},
};
+export const CustomRange: Story = {
+ args: { value: 70, min: 20, max: 120 },
+};
+
+export const Indeterminate: Story = {
+ args: { value: null },
+};
+
+const INDETERMINATE_VALUES = [
+ { label: 'Unknown progress', value: null },
+ { label: 'Invalid progress', value: Number.NaN },
+ { label: 'Negative infinity', value: Number.NEGATIVE_INFINITY },
+ { label: 'Positive infinity', value: Number.POSITIVE_INFINITY },
+];
+
+export const IndeterminateValues: Story = {
+ render: () => (
+ <>
+ {INDETERMINATE_VALUES.map(({ label, value }) => (
+ <ProgressRing key={label} aria-label={label} value={value} />
+ ))}
+ </>
+ ),
+ play: async ({ canvasElement }) => {
+ const canvas = within(canvasElement);
+
+ for (const { label } of INDETERMINATE_VALUES) {
+ const progress = canvas.getByRole('progressbar', { name: label });
+
+ await expect(progress).not.toHaveAttribute('aria-valuenow');
+ await expect(progress).toHaveAttribute('data-indeterminate');
+ await expect(progress).toHaveAttribute(
+ 'aria-valuetext',
+ 'indeterminate progress',
+ );
+ }
+ },
+};
+
const ControlledProgressRing = () => {
const [value, setValue] = useState(0);
diff --git a/packages/twenty-ui/src/primitives/feedback/ProgressRing/internal/ProgressRingIndicator.tsx b/packages/twenty-ui/src/primitives/feedback/ProgressRing/internal/ProgressRingIndicator.tsx
new file mode 100644
index 00000000000..b287668f225
--- /dev/null
+++ b/packages/twenty-ui/src/primitives/feedback/ProgressRing/internal/ProgressRingIndicator.tsx
@@ -0,0 +1,66 @@
+import { getProgressIndicatorPercentage } from '../../Progress/internal/getProgressIndicatorPercentage';
+import { Progress } from '../../Progress/Progress';
+import styles from '../ProgressRing.module.scss';
+import { type ProgressRingProps } from '../types/ProgressRingProps';
+
+const RING_SIZE = { sm: 14, md: 16 };
+const STROKE_WIDTH = 2;
+const INDETERMINATE_PERCENTAGE = 25;
+
+export const ProgressRingIndicator = ({
+ size,
+}: Required<Pick<ProgressRingProps, 'size'>>) => {
+ const diameter = RING_SIZE[size];
+ const radius = (diameter - STROKE_WIDTH) / 2;
+ const circumference = 2 * Math.PI * radius;
+
+ return (
+ <Progress.Indicator
+ className={styles.ring}
+ aria-hidden="true"
+ render={(indicatorProps) => {
+ const percentage = getProgressIndicatorPercentage({
+ width: indicatorProps.style?.width,
+ fallbackPercentage: INDETERMINATE_PERCENTAGE,
+ });
+
+ return (
+ <div
+ {...indicatorProps}
+ style={{
+ ...indicatorProps.style,
+ width: diameter,
+ height: diameter,
+ }}
+ >
+ <svg
+ width={diameter}
+ height={diameter}
+ viewBox={`0 0 ${diameter} ${diameter}`}
+ aria-hidden="true"
+ focusable="false"
+ >
+ <circle
+ className={styles.track}
+ cx={diameter / 2}
+ cy={diameter / 2}
+ r={radius}
+ strokeWidth={STROKE_WIDTH}
+ />
+ <circle
+ className={styles.indicator}
+ cx={diameter / 2}
+ cy={diameter / 2}
+ r={radius}
+ strokeWidth={STROKE_WIDTH}
+ strokeDasharray={circumference}
+ strokeDashoffset={circumference * (1 - percentage / 100)}
+ strokeLinecap={percentage === 0 ? 'butt' : 'round'}
+ />
+ </svg>
+ </div>
+ );
+ }}
+ />
+ );
+};
diff --git a/packages/twenty-ui/src/primitives/feedback/ProgressRing/types/ProgressRingProps.ts b/packages/twenty-ui/src/primitives/feedback/ProgressRing/types/ProgressRingProps.ts
index 77026650544..b27ee870e34 100644
--- a/packages/twenty-ui/src/primitives/feedback/ProgressRing/types/ProgressRingProps.ts
+++ b/packages/twenty-ui/src/primitives/feedback/ProgressRing/types/ProgressRingProps.ts
@@ -1,7 +1,6 @@
-import { type useRender } from '@base-ui/react/use-render';
+import { type ProgressRootProps } from '../../Progress/types/ProgressRootProps';
-export type ProgressRingProps = useRender.ComponentProps<'div'> & {
- value: number;
+export type ProgressRingProps = ProgressRootProps & {
size?: 'sm' | 'md';
barColor?: string;
};
diff --git a/packages/twenty-ui/src/primitives/feedback/index.ts b/packages/twenty-ui/src/primitives/feedback/index.ts
index 493901a8548..b238a10bff8 100644
--- a/packages/twenty-ui/src/primitives/feedback/index.ts
+++ b/packages/twenty-ui/src/primitives/feedback/index.ts
@@ -16,6 +16,18 @@ export type { BannerStatus } from './Banner/types/BannerStatus';
export type { BannerVariant } from './Banner/types/BannerVariant';
export { Loader } from './Loader/Loader';
export type { LoaderProps } from './Loader/types/LoaderProps';
+export { Progress } from './Progress/Progress';
+export type { ProgressIndicatorProps } from './Progress/types/ProgressIndicatorProps';
+export type { ProgressIndicatorState } from './Progress/types/ProgressIndicatorState';
+export type { ProgressLabelProps } from './Progress/types/ProgressLabelProps';
+export type { ProgressLabelState } from './Progress/types/ProgressLabelState';
+export type { ProgressRootProps } from './Progress/types/ProgressRootProps';
+export type { ProgressRootState } from './Progress/types/ProgressRootState';
+export type { ProgressStatus } from './Progress/types/ProgressStatus';
+export type { ProgressTrackProps } from './Progress/types/ProgressTrackProps';
+export type { ProgressTrackState } from './Progress/types/ProgressTrackState';
+export type { ProgressValueProps } from './Progress/types/ProgressValueProps';
+export type { ProgressValueState } from './Progress/types/ProgressValueState';
export { ProgressBar } from './ProgressBar/ProgressBar';
export type { ProgressBarProps } from './ProgressBar/types/ProgressBarProps';
export { ProgressRing } from './ProgressRing/ProgressRing';