Skip to content

The open alternative to Salesforce, designed for AI.

Complete ColorSample and Loader APIs (#27381)

Raphaël Bosi865986a7b5bf
diff --git a/packages/twenty-docs/snippets/ui/generated/data-display/color-sample.mdx b/packages/twenty-docs/snippets/ui/generated/data-display/color-sample.mdx
index 0e82b28a33a..5ba2e3f01ac 100644
--- a/packages/twenty-docs/snippets/ui/generated/data-display/color-sample.mdx
+++ b/packages/twenty-docs/snippets/ui/generated/data-display/color-sample.mdx
@@ -11,8 +11,16 @@
* npx nx generate:ui twenty-docs
*/}
+<ParamField body="aria-hidden" type="Booleanish">
+ Mark decorative swatches as hidden from assistive technology.
+</ParamField>
+
+<ParamField body="aria-label" type="string">
+ Accessible name when the caller supplies role="img".
+</ParamField>
+
<ParamField body="className" type="string">
- CSS class applied to the swatch.
+ CSS class merged with the swatch class.
</ParamField>
<ParamField body="color" type="string">
@@ -23,6 +31,18 @@
Theme color used for the background and border. Required even when `color` overrides the background.
</ParamField>
-<ParamField body="variant" type="&quot;circle&quot; | &quot;default&quot; | &quot;pipeline&quot;">
- Swatch shape: `default`, `circle`, or `pipeline`. Omitting it uses the default shape.
+<ParamField body="ref" type="Ref&lt;HTMLDivElement&gt;">
+ Ref to the swatch div, or the element supplied through render.
+</ParamField>
+
+<ParamField body="render" type="ReactElement&lt;unknown, string | JSXElementConstructor&lt;any&gt;&gt; | ComponentRenderFn&lt;HTMLProps, {}&gt;">
+ Element or render callback composed through Base UI useRender.
+</ParamField>
+
+<ParamField body="style" type="CSSProperties">
+ Native styles merged with the swatch color defaults. Explicit styles win.
+</ParamField>
+
+<ParamField body="variant" type="&quot;circle&quot; | &quot;default&quot;">
+ Generic swatch shape: `default` or `circle`. Omitting it uses the default shape.
</ParamField>
diff --git a/packages/twenty-docs/snippets/ui/generated/feedback/loader.mdx b/packages/twenty-docs/snippets/ui/generated/feedback/loader.mdx
index e593c7f76b5..a7989cb35b3 100644
--- a/packages/twenty-docs/snippets/ui/generated/feedback/loader.mdx
+++ b/packages/twenty-docs/snippets/ui/generated/feedback/loader.mdx
@@ -11,6 +11,38 @@
* npx nx generate:ui twenty-docs
*/}
+<ParamField body="aria-hidden" type="Booleanish">
+ Hide a decorative loader when another element supplies loading feedback.
+</ParamField>
+
+<ParamField body="aria-label" type="string">
+ Accessible name for a labeled loader status.
+</ParamField>
+
+<ParamField body="aria-labelledby" type="string">
+ ID of text that names the loader status.
+</ParamField>
+
+<ParamField body="className" type="string">
+ CSS class merged with the loader container class.
+</ParamField>
+
<ParamField body="color" type="&quot;amber&quot; | &quot;blue&quot; | &quot;bronze&quot; | &quot;brown&quot; | &quot;crimson&quot; | &quot;cyan&quot; | &quot;gold&quot; | &quot;grass&quot; | &quot;gray&quot; | &quot;green&quot; | &quot;iris&quot; | &quot;jade&quot; | &quot;lime&quot; | &quot;mint&quot; | &quot;orange&quot; | &quot;pink&quot; | &quot;plum&quot; | &quot;purple&quot; | &quot;red&quot; | &quot;ruby&quot; | &quot;sky&quot; | &quot;tomato&quot; | &quot;turquoise&quot; | &quot;violet&quot; | &quot;yellow&quot;">
Theme color for the animated dot and border. When omitted, inherits the button color if available, otherwise the tertiary text color.
</ParamField>
+
+<ParamField body="ref" type="Ref&lt;HTMLDivElement&gt;">
+ Ref to the container div, or the element supplied through render.
+</ParamField>
+
+<ParamField body="render" type="ReactElement&lt;unknown, string | JSXElementConstructor&lt;any&gt;&gt; | ComponentRenderFn&lt;HTMLProps, {}&gt;">
+ Element or render callback composed through Base UI useRender.
+</ParamField>
+
+<ParamField body="role" type="AriaRole">
+ Supply status to expose loading feedback as a live region. No role is assigned by default.
+</ParamField>
+
+<ParamField body="style" type="CSSProperties">
+ Native styles merged with the loader color defaults. Explicit styles win.
+</ParamField>
diff --git a/packages/twenty-docs/ui/primitives/data-display/color-sample.mdx b/packages/twenty-docs/ui/primitives/data-display/color-sample.mdx
index e6d53f9011a..c4a0ed0df13 100644
--- a/packages/twenty-docs/ui/primitives/data-display/color-sample.mdx
+++ b/packages/twenty-docs/ui/primitives/data-display/color-sample.mdx
@@ -22,13 +22,18 @@ import { Text } from 'twenty-ui/primitives/typography';
export const PriorityColor = () => (
<Text style={{ display: 'flex', alignItems: 'center', gap: 8 }}>
- <ColorSample colorName="red" variant="circle" />
+ <ColorSample
+ colorName="red"
+ variant="circle"
+ render={<span />}
+ aria-hidden="true"
+ />
High priority
</Text>
);
```
-`colorName` selects a theme palette entry for the fill and border. `variant` accepts `default`, `circle`, or `pipeline`. Omitting it uses the default shape.
+`colorName` selects a theme palette entry for the fill and border. `variant` accepts `default` or `circle`. Omitting it uses the default shape.
## Custom colors
@@ -38,13 +43,22 @@ import { Text } from 'twenty-ui/primitives/typography';
export const BrandColor = () => (
<Text style={{ display: 'flex', alignItems: 'center', gap: 8 }}>
- <ColorSample colorName="blue" color="#2563eb" />
+ <ColorSample
+ colorName="blue"
+ color="#2563eb"
+ render={<span />}
+ aria-hidden="true"
+ />
Brand blue
</Text>
);
```
-A custom `color` overrides the fill; `colorName` remains required and still determines the border color. `className` styles the swatch. Other native attributes and click handlers are not forwarded. To offer selectable colors, compose the swatch inside a labeled [ListItem](/ui/primitives/navigation/list-item).
+A custom `color` overrides the fill; `colorName` remains required and still determines the border color. Native props, `className`, `style`, and `ref` target the swatch div. `render` accepts an element or callback through Base UI composition, for example a span inside text. Consumer styles override the default fill, border, or geometry. Decorative swatches use `aria-hidden="true"`; a standalone meaningful swatch uses `role="img"` with `aria-label` or `aria-labelledby`. To offer selectable colors, compose the swatch inside a labeled [ListItem](/ui/primitives/navigation/list-item).
+
+## Migration
+
+`ColorSampleProps` and `ColorSampleVariant` remain available from the data-display family. The unused `pipeline` variant is removed. Product-specific indicators belong in the application, using native styles or composition. Default and circle swatches keep their existing appearance.
## Props
diff --git a/packages/twenty-docs/ui/primitives/feedback/loader.mdx b/packages/twenty-docs/ui/primitives/feedback/loader.mdx
index 36f25f8d4af..aa6804b067a 100644
--- a/packages/twenty-docs/ui/primitives/feedback/loader.mdx
+++ b/packages/twenty-docs/ui/primitives/feedback/loader.mdx
@@ -23,18 +23,38 @@ import { Text } from 'twenty-ui/primitives/typography';
type SaveFeedbackProps = { isSaving: boolean };
export const SaveFeedback = ({ isSaving }: SaveFeedbackProps) => (
- <div role="status">
- {isSaving && (
- <div aria-hidden="true">
- <Loader color="blue" />
- </div>
- )}
- <Text>{isSaving ? 'Saving changes' : 'Changes saved'}</Text>
- </div>
+ <Text render={<div />} role="status" style={{ display: 'flex', gap: 8 }}>
+ {isSaving && <Loader color="blue" aria-hidden="true" render={<span />} />}
+ {isSaving ? 'Saving changes' : 'Changes saved'}
+ </Text>
);
```
-The application owns loading state. Keep the status wrapper mounted so text updates can be announced. The loader itself supplies no label or live region and accepts only `color`.
+Place visible status text beside the loader in a wrapper. The loader is a fixed-size visual indicator and does not accept children.
+
+The application owns loading state. Keep the status wrapper mounted so text updates can be announced. The loader assigns no label or live-region role by default. Use `aria-hidden="true"` when surrounding text or a button already supplies loading feedback.
+
+## Native composition and labeling
+
+Native props, `className`, `style`, and `ref` target the container div. `render` accepts an element or callback through Base UI composition. Styles override color defaults. `LoaderProps` is exported from the feedback family.
+
+For a standalone indicator, provide an explicit status role and accessible name. The animated dot remains decorative.
+
+```tsx
+import { Loader, type LoaderProps } from 'twenty-ui/primitives/feedback';
+
+const loadingProps: LoaderProps = {
+ role: 'status',
+ 'aria-label': 'Loading results',
+ color: 'blue',
+};
+
+export const LoadingResults = () => (
+ <Loader {...loadingProps} render={<span />} />
+);
+```
+
+Use `aria-labelledby` instead when visible text names the status. Keep a live-region owner mounted when it needs to announce changing text. The application owns when feedback appears and what it says.
## Color
diff --git a/packages/twenty-front-component-renderer/src/__stories__/TwentyUiGallery.stories.tsx b/packages/twenty-front-component-renderer/src/__stories__/TwentyUiGallery.stories.tsx
index 71a01de7fca..d6bedfec52f 100644
--- a/packages/twenty-front-component-renderer/src/__stories__/TwentyUiGallery.stories.tsx
+++ b/packages/twenty-front-component-renderer/src/__stories__/TwentyUiGallery.stories.tsx
@@ -60,6 +60,8 @@ import { sliderRangeTest } from '@/__stories__/twenty-ui-gallery/utils/sliderRan
import { sliderTest } from '@/__stories__/twenty-ui-gallery/utils/sliderTest';
import { toastTest } from '@/__stories__/twenty-ui-gallery/utils/toastTest';
import { avatarImageTest } from '@/__stories__/twenty-ui-gallery/utils/avatarImageTest';
+import { colorSampleTest } from '@/__stories__/twenty-ui-gallery/utils/colorSampleTest';
+import { loaderTest } from '@/__stories__/twenty-ui-gallery/utils/loaderTest';
const meta: Meta<typeof FrontComponentRenderer> = {
title: 'FrontComponent/Twenty UI Gallery',
@@ -76,23 +78,23 @@ export default meta;
export const DataDisplayReact: Story = createGalleryStory({
frontComponentBundleName: 'twenty-ui-data-display-gallery',
runtime: 'react',
- play: galleryRenderTest,
+ play: colorSampleTest,
});
export const DataDisplayPreact: Story = createGalleryStory({
frontComponentBundleName: 'twenty-ui-data-display-gallery',
runtime: 'preact',
- play: galleryRenderTest,
+ play: colorSampleTest,
});
export const FeedbackReact: Story = createGalleryStory({
frontComponentBundleName: 'twenty-ui-feedback-gallery',
runtime: 'react',
- play: galleryRenderTest,
+ play: loaderTest,
});
export const FeedbackPreact: Story = createGalleryStory({
frontComponentBundleName: 'twenty-ui-feedback-gallery',
runtime: 'preact',
- play: galleryRenderTest,
+ play: loaderTest,
});
export const ProgressReact: Story = createGalleryStory({
diff --git a/packages/twenty-front-component-renderer/src/__stories__/twenty-ui-gallery/twenty-ui-data-display-gallery.front-component.tsx b/packages/twenty-front-component-renderer/src/__stories__/twenty-ui-gallery/twenty-ui-data-display-gallery.front-component.tsx
index 3bdc25cb098..1c1afffc70f 100644
--- a/packages/twenty-front-component-renderer/src/__stories__/twenty-ui-gallery/twenty-ui-data-display-gallery.front-component.tsx
+++ b/packages/twenty-front-component-renderer/src/__stories__/twenty-ui-gallery/twenty-ui-data-display-gallery.front-component.tsx
@@ -14,6 +14,8 @@ import {
Status,
Tag,
} from 'twenty-ui/primitives/data-display';
+import { isDefined } from 'twenty-shared/utils';
+import 'twenty-ui/style.css';
import { ThemeProvider } from 'twenty-ui/theme';
import {
@@ -43,7 +45,36 @@ const DATA_DISPLAY_ENTRIES: GalleryEntry[] = [
},
{
name: 'ColorSample',
- node: <ColorSample colorName="blue" />,
+ node: (
+ <ColorSample
+ colorName="blue"
+ role="img"
+ aria-label="Brand blue"
+ className="custom-swatch"
+ style={{ width: 24 }}
+ render={<span data-composed="true" />}
+ ref={(element) => {
+ if (isDefined(element)) {
+ element.dataset.refTag = element.tagName;
+ }
+ }}
+ />
+ ),
+ },
+ {
+ name: 'DecorativeColorSample',
+ node: <ColorSample colorName="red" aria-hidden="true" />,
+ },
+ {
+ name: 'CircleColorSample',
+ node: (
+ <ColorSample
+ colorName="green"
+ variant="circle"
+ role="img"
+ aria-label="Green"
+ />
+ ),
},
{
name: 'CommandBlock',
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 26329762a5d..b84ad25222b 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
@@ -1,6 +1,9 @@
+import { createElement } from 'react';
import { defineFrontComponent } from 'twenty-sdk/define';
import { Callout, InlineBanner } from 'twenty-ui/components/feedback';
import { Banner, Loader, ProgressBar } from 'twenty-ui/primitives/feedback';
+import { isDefined } from 'twenty-shared/utils';
+import 'twenty-ui/style.css';
import { ThemeProvider } from 'twenty-ui/theme';
import {
@@ -39,7 +42,27 @@ const FEEDBACK_ENTRIES: GalleryEntry[] = [
},
{
name: 'Loader',
- node: <Loader color="blue" />,
+ node: (
+ <Loader
+ color="blue"
+ role="status"
+ aria-label="Loading results"
+ className="custom-loader"
+ style={{ borderColor: '#123456' }}
+ render={(props) =>
+ createElement('span', { ...props, 'data-composed': 'true' })
+ }
+ ref={(element) => {
+ if (isDefined(element)) {
+ element.dataset.refTag = element.tagName;
+ }
+ }}
+ />
+ ),
+ },
+ {
+ name: 'DecorativeLoader',
+ node: <Loader aria-hidden="true" />,
},
{
name: 'ProgressBar',
diff --git a/packages/twenty-front-component-renderer/src/__stories__/twenty-ui-gallery/utils/colorSampleTest.ts b/packages/twenty-front-component-renderer/src/__stories__/twenty-ui-gallery/utils/colorSampleTest.ts
new file mode 100644
index 00000000000..fa4d66bdd4d
--- /dev/null
+++ b/packages/twenty-front-component-renderer/src/__stories__/twenty-ui-gallery/utils/colorSampleTest.ts
@@ -0,0 +1,31 @@
+import { expect, waitFor, within } from 'storybook/test';
+
+import { type TwentyUiGalleryPlayFunction } from '@/__stories__/twenty-ui-gallery/types/TwentyUiGalleryPlayFunction';
+import { galleryRenderTest } from '@/__stories__/twenty-ui-gallery/utils/galleryRenderTests';
+
+export const colorSampleTest: TwentyUiGalleryPlayFunction = async (context) => {
+ await galleryRenderTest(context);
+ const canvas = within(context.canvasElement);
+ const swatch = canvas.getByRole('img', { name: 'Brand blue' });
+
+ await waitFor(() =>
+ expect(swatch).toHaveAttribute('data-ref-tag', 'HTML-SPAN'),
+ );
+ await expect(swatch).toHaveAttribute('data-composed', 'true');
+ await expect(swatch).toHaveClass('custom-swatch');
+ await expect(swatch).toHaveStyle({ width: '24px', height: '16px' });
+ await expect(canvas.getByRole('img', { name: 'Green' })).toHaveStyle({
+ width: '16px',
+ height: '16px',
+ borderRadius: '50%',
+ });
+ const decorativeSwatch = canvas
+ .getByTestId('gallery-item-DecorativeColorSample')
+ .querySelector('[aria-hidden="true"]');
+
+ await expect(decorativeSwatch).toHaveStyle({
+ width: '12px',
+ height: '16px',
+ borderWidth: '1px',
+ });
+};
diff --git a/packages/twenty-front-component-renderer/src/__stories__/twenty-ui-gallery/utils/loaderTest.ts b/packages/twenty-front-component-renderer/src/__stories__/twenty-ui-gallery/utils/loaderTest.ts
new file mode 100644
index 00000000000..5dfd780bfeb
--- /dev/null
+++ b/packages/twenty-front-component-renderer/src/__stories__/twenty-ui-gallery/utils/loaderTest.ts
@@ -0,0 +1,23 @@
+import { expect, waitFor, within } from 'storybook/test';
+
+import { type TwentyUiGalleryPlayFunction } from '@/__stories__/twenty-ui-gallery/types/TwentyUiGalleryPlayFunction';
+import { galleryRenderTest } from '@/__stories__/twenty-ui-gallery/utils/galleryRenderTests';
+
+export const loaderTest: TwentyUiGalleryPlayFunction = async (context) => {
+ await galleryRenderTest(context);
+ const canvas = within(context.canvasElement);
+ const loader = canvas.getByRole('status', { name: 'Loading results' });
+
+ await waitFor(() =>
+ expect(loader).toHaveAttribute('data-ref-tag', 'HTML-SPAN'),
+ );
+ await expect(loader).toHaveAttribute('data-composed', 'true');
+ await expect(loader).toHaveClass('custom-loader');
+ await expect(loader).toHaveStyle({ borderColor: 'rgb(18, 52, 86)' });
+ await expect(loader.firstElementChild).toHaveAttribute('aria-hidden', 'true');
+ const decorativeEntry = within(
+ canvas.getByTestId('gallery-item-DecorativeLoader'),
+ );
+
+ await expect(decorativeEntry.queryByRole('status')).not.toBeInTheDocument();
+};
diff --git a/packages/twenty-ui/docs/colorSamplePropDescriptions.ts b/packages/twenty-ui/docs/colorSamplePropDescriptions.ts
index 0a2a6ea7f97..9194dce79a1 100644
--- a/packages/twenty-ui/docs/colorSamplePropDescriptions.ts
+++ b/packages/twenty-ui/docs/colorSamplePropDescriptions.ts
@@ -1,6 +1,4 @@
-import { type ComponentProps } from 'react';
-
-import { type ColorSample } from '../src/primitives/data-display/ColorSample/ColorSample';
+import { type ColorSampleProps } from '../src/primitives/data-display/ColorSample/types/ColorSampleProps';
export const COLOR_SAMPLE_PROP_DESCRIPTIONS = {
colorName:
@@ -8,6 +6,13 @@ export const COLOR_SAMPLE_PROP_DESCRIPTIONS = {
color:
'CSS color that overrides the background; the border still uses `colorName`.',
variant:
- 'Swatch shape: `default`, `circle`, or `pipeline`. Omitting it uses the default shape.',
- className: 'CSS class applied to the swatch.',
-} satisfies Partial<Record<keyof ComponentProps<typeof ColorSample>, string>>;
+ 'Generic swatch shape: `default` or `circle`. Omitting it uses the default shape.',
+ className: 'CSS class merged with the swatch class.',
+ style:
+ 'Native styles merged with the swatch color defaults. Explicit styles win.',
+ ref: 'Ref to the swatch div, or the element supplied through render.',
+ render: 'Element or render callback composed through Base UI useRender.',
+ 'aria-hidden':
+ 'Mark decorative swatches as hidden from assistive technology.',
+ 'aria-label': 'Accessible name when the caller supplies role="img".',
+} satisfies Partial<Record<keyof ColorSampleProps, string>>;
diff --git a/packages/twenty-ui/docs/loaderPropDescriptions.ts b/packages/twenty-ui/docs/loaderPropDescriptions.ts
index 626e6c20faf..38fd2ec206a 100644
--- a/packages/twenty-ui/docs/loaderPropDescriptions.ts
+++ b/packages/twenty-ui/docs/loaderPropDescriptions.ts
@@ -1,8 +1,16 @@
-import { type ComponentProps } from 'react';
-
-import { type Loader } from '../src/primitives/feedback/Loader/Loader';
+import { type LoaderProps } from '../src/primitives/feedback/Loader/types/LoaderProps';
export const LOADER_PROP_DESCRIPTIONS = {
color:
'Theme color for the animated dot and border. When omitted, inherits the button color if available, otherwise the tertiary text color.',
-} satisfies Partial<Record<keyof ComponentProps<typeof Loader>, string>>;
+ className: 'CSS class merged with the loader container class.',
+ style:
+ 'Native styles merged with the loader color defaults. Explicit styles win.',
+ ref: 'Ref to the container div, or the element supplied through render.',
+ render: 'Element or render callback composed through Base UI useRender.',
+ role: 'Supply status to expose loading feedback as a live region. No role is assigned by default.',
+ 'aria-label': 'Accessible name for a labeled loader status.',
+ 'aria-labelledby': 'ID of text that names the loader status.',
+ 'aria-hidden':
+ 'Hide a decorative loader when another element supplies loading feedback.',
+} satisfies Partial<Record<keyof LoaderProps, string>>;
diff --git a/packages/twenty-ui/docs/public-exports.json b/packages/twenty-ui/docs/public-exports.json
index 5541c69fb3f..6bdfa7cf02b 100644
--- a/packages/twenty-ui/docs/public-exports.json
+++ b/packages/twenty-ui/docs/public-exports.json
@@ -722,8 +722,8 @@
"ChipProps": "primitives/data-display/Chip/types/ChipProps",
"ChipSize": "primitives/data-display/Chip/types/ChipSize",
"ChipVariant": "primitives/data-display/Chip/types/ChipVariant",
- "ColorSampleProps": "primitives/data-display/ColorSample/ColorSample",
- "ColorSampleVariant": "primitives/data-display/ColorSample/ColorSample",
+ "ColorSampleProps": "primitives/data-display/ColorSample/types/ColorSampleProps",
+ "ColorSampleVariant": "primitives/data-display/ColorSample/types/ColorSampleVariant",
"StatusProps": "primitives/data-display/Status/types/StatusProps",
"TagColor": "primitives/data-display/Tag/types/TagColor",
"TagProps": "primitives/data-display/Tag/types/TagProps"
@@ -740,6 +740,7 @@
"types": {
"BannerColor": "primitives/feedback/Banner/Banner",
"BannerVariant": "primitives/feedback/Banner/Banner",
+ "LoaderProps": "primitives/feedback/Loader/types/LoaderProps",
"ProgressBarProps": "primitives/feedback/ProgressBar/types/ProgressBarProps",
"ProgressRingProps": "primitives/feedback/ProgressRing/types/ProgressRingProps"
}
diff --git a/packages/twenty-ui/generated/components.docs.json b/packages/twenty-ui/generated/components.docs.json
index 7d506e8e650..c81113879fa 100644
--- a/packages/twenty-ui/generated/components.docs.json
+++ b/packages/twenty-ui/generated/components.docs.json
@@ -456,12 +456,26 @@
"entryPoint": "twenty-ui/primitives/data-display",
"slug": "data-display/color-sample",
"props": [
+ {
+ "name": "aria-hidden",
+ "type": "Booleanish",
+ "required": false,
+ "defaultValue": null,
+ "description": "Mark decorative swatches as hidden from assistive technology."
+ },
+ {
+ "name": "aria-label",
+ "type": "string",
+ "required": false,
+ "defaultValue": null,
+ "description": "Accessible name when the caller supplies role=\"img\"."
+ },
{
"name": "className",
"type": "string",
"required": false,
"defaultValue": null,
- "description": "CSS class applied to the swatch."
+ "description": "CSS class merged with the swatch class."
},
{
"name": "color",
@@ -477,12 +491,33 @@
"defaultValue": null,
"description": "Theme color used for the background and border. Required even when `color` overrides the background."
},
+ {
+ "name": "ref",
+ "type": "Ref<HTMLDivElement>",
+ "required": false,
+ "defaultValue": null,
+ "description": "Ref to the swatch div, or the element supplied through render."
+ },
+ {
+ "name": "render",
+ "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>",
+ "required": false,
+ "defaultValue": null,
+ "description": "Element or render callback composed through Base UI useRender."
+ },
+ {
+ "name": "style",
+ "type": "CSSProperties",
+ "required": false,
+ "defaultValue": null,
+ "description": "Native styles merged with the swatch color defaults. Explicit styles win."
+ },
{
"name": "variant",
- "type": "\"circle\" | \"default\" | \"pipeline\"",
+ "type": "\"circle\" | \"default\"",
"required": false,
"defaultValue": null,
- "description": "Swatch shape: `default`, `circle`, or `pipeline`. Omitting it uses the default shape."
+ "description": "Generic swatch shape: `default` or `circle`. Omitting it uses the default shape."
}
]
},
@@ -568,12 +603,68 @@
"entryPoint": "twenty-ui/primitives/feedback",
"slug": "feedback/loader",
"props": [
+ {
+ "name": "aria-hidden",
+ "type": "Booleanish",
+ "required": false,
+ "defaultValue": null,
+ "description": "Hide a decorative loader when another element supplies loading feedback."
+ },
+ {
+ "name": "aria-label",
+ "type": "string",
+ "required": false,
+ "defaultValue": null,
+ "description": "Accessible name for a labeled loader status."
+ },
+ {
+ "name": "aria-labelledby",
+ "type": "string",
+ "required": false,
+ "defaultValue": null,
+ "description": "ID of text that names the loader status."
+ },
+ {
+ "name": "className",
+ "type": "string",
+ "required": false,
+ "defaultValue": null,
+ "description": "CSS class merged with the loader container class."
+ },
{
"name": "color",
"type": "\"amber\" | \"blue\" | \"bronze\" | \"brown\" | \"crimson\" | \"cyan\" | \"gold\" | \"grass\" | \"gray\" | \"green\" | \"iris\" | \"jade\" | \"lime\" | \"mint\" | \"orange\" | \"pink\" | \"plum\" | \"purple\" | \"red\" | \"ruby\" | \"sky\" | \"tomato\" | \"turquoise\" | \"violet\" | \"yellow\"",
"required": false,
"defaultValue": null,
"description": "Theme color for the animated dot and border. When omitted, inherits the button color if available, otherwise the tertiary text color."
+ },
+ {
+ "name": "ref",
+ "type": "Ref<HTMLDivElement>",
+ "required": false,
+ "defaultValue": null,
+ "description": "Ref to the container div, or the element supplied through render."
+ },
+ {
+ "name": "render",
+ "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>",
+ "required": false,
+ "defaultValue": null,
+ "description": "Element or render callback composed through Base UI useRender."
+ },
+ {
+ "name": "role",
+ "type": "AriaRole",
+ "required": false,
+ "defaultValue": null,
+ "description": "Supply status to expose loading feedback as a live region. No role is assigned by default."
+ },
+ {
+ "name": "style",
+ "type": "CSSProperties",
+ "required": false,
+ "defaultValue": null,
+ "description": "Native styles merged with the loader color defaults. Explicit styles win."
}
]
},
diff --git a/packages/twenty-ui/src/primitives/data-display/ColorSample/ColorSample.module.scss b/packages/twenty-ui/src/primitives/data-display/ColorSample/ColorSample.module.scss
index 9fa0744ae13..10049080081 100644
--- a/packages/twenty-ui/src/primitives/data-display/ColorSample/ColorSample.module.scss
+++ b/packages/twenty-ui/src/primitives/data-display/ColorSample/ColorSample.module.scss
@@ -15,20 +15,3 @@
border-radius: 50%;
corner-shape: round;
}
-
-.pipeline {
- display: flex;
- align-items: center;
- justify-content: center;
- border: 0;
-
- &::after {
- display: block;
- width: var(--t-spacing-1);
- height: var(--t-spacing-1);
- border-radius: var(--t-border-radius-rounded);
- corner-shape: round;
- background-color: var(--color-sample-color);
- content: '';
- }
-}
diff --git a/packages/twenty-ui/src/primitives/data-display/ColorSample/ColorSample.module.scss.d.ts b/packages/twenty-ui/src/primitives/data-display/ColorSample/ColorSample.module.scss.d.ts
index 868ad8c17dd..6b198257097 100644
--- a/packages/twenty-ui/src/primitives/data-display/ColorSample/ColorSample.module.scss.d.ts
+++ b/packages/twenty-ui/src/primitives/data-display/ColorSample/ColorSample.module.scss.d.ts
@@ -1,6 +1,5 @@
declare const classNames: {
readonly root: 'root';
readonly circle: 'circle';
- readonly pipeline: 'pipeline';
};
export default classNames;
diff --git a/packages/twenty-ui/src/primitives/data-display/ColorSample/ColorSample.tsx b/packages/twenty-ui/src/primitives/data-display/ColorSample/ColorSample.tsx
index d384509b557..7465af88027 100644
--- a/packages/twenty-ui/src/primitives/data-display/ColorSample/ColorSample.tsx
+++ b/packages/twenty-ui/src/primitives/data-display/ColorSample/ColorSample.tsx
@@ -1,55 +1,39 @@
+import { useRender } from '@base-ui/react/use-render';
import { clsx } from 'clsx';
+import { type CSSProperties } from 'react';
-import { type ThemeColor, themeCssVariables } from '@ui/theme';
+import { themeCssVariables } from '@ui/theme';
-import { isDefined } from '@ui/utilities/utils/isDefined';
+import { type ColorSampleProps } from './types/ColorSampleProps';
import styles from './ColorSample.module.scss';
-export type ColorSampleVariant = 'circle' | 'default' | 'pipeline';
-
-type StyledColorSampleProps = {
- colorName: ThemeColor;
- color?: string;
- variant?: ColorSampleVariant;
-};
-
-export type ColorSampleProps = StyledColorSampleProps & {
- className?: string;
-};
-
-const getColor = (colorName: ThemeColor, color?: string) => {
- if (isDefined(color)) {
- return color;
- }
-
- return themeCssVariables.tag.background[colorName];
-};
-
-const getBorderColor = (colorName: ThemeColor) => {
- return themeCssVariables.tag.text[colorName];
-};
-
export const ColorSample = ({
colorName,
color,
variant,
className,
-}: ColorSampleProps) => {
- return (
- <div
- className={clsx(
+ style,
+ render,
+ ref,
+ ...props
+}: ColorSampleProps) =>
+ useRender({
+ defaultTagName: 'div',
+ render,
+ ref,
+ props: {
+ ...props,
+ className: clsx(
styles.root,
variant === 'circle' && styles.circle,
- variant === 'pipeline' && styles.pipeline,
className,
- )}
- style={
- {
- '--color-sample-color': getColor(colorName, color),
- '--color-sample-border-color': getBorderColor(colorName),
- } as React.CSSProperties
- }
- />
- );
-};
+ ),
+ style: {
+ '--color-sample-color':
+ color ?? themeCssVariables.tag.background[colorName],
+ '--color-sample-border-color': themeCssVariables.tag.text[colorName],
+ ...style,
+ } as CSSProperties,
+ },
+ });
diff --git a/packages/twenty-ui/src/primitives/data-display/ColorSample/__stories__/ColorSample.stories.tsx b/packages/twenty-ui/src/primitives/data-display/ColorSample/__stories__/ColorSample.stories.tsx
index bebda76d8a7..5512eb15aa3 100644
--- a/packages/twenty-ui/src/primitives/data-display/ColorSample/__stories__/ColorSample.stories.tsx
+++ b/packages/twenty-ui/src/primitives/data-display/ColorSample/__stories__/ColorSample.stories.tsx
@@ -1,8 +1,9 @@
import { type Meta, type StoryObj } from '@storybook/react-vite';
-
-import { ComponentDecorator } from '@ui/testing';
+import { expect } from 'storybook/test';
import { ColorSample } from '@ui/primitives/data-display/ColorSample/ColorSample';
+import { Text } from '@ui/primitives/typography';
+import { ComponentDecorator } from '@ui/testing';
const meta: Meta<typeof ColorSample> = {
title: 'UI/Data Display/ColorSample',
@@ -14,12 +15,48 @@ const meta: Meta<typeof ColorSample> = {
export default meta;
type Story = StoryObj<typeof ColorSample>;
-export const Default: Story = {};
-
-export const Pipeline: Story = {
- args: { variant: 'pipeline' },
+export const Default: Story = {
+ args: { 'aria-hidden': true },
};
export const Circle: Story = {
- args: { variant: 'circle' },
+ args: { variant: 'circle', role: 'img', 'aria-label': 'Green' },
+ play: async ({ canvas }) => {
+ await expect(canvas.getByRole('img', { name: 'Green' })).toHaveStyle({
+ width: '16px',
+ height: '16px',
+ borderRadius: '50%',
+ });
+ },
+};
+
+export const WithLabel: Story = {
+ render: (args) => (
+ <Text style={{ display: 'flex', alignItems: 'center', gap: 8 }}>
+ <ColorSample {...args} render={<span />} aria-hidden="true" />
+ High priority
+ </Text>
+ ),
+};
+
+export const CustomColor: Story = {
+ args: {
+ colorName: 'blue',
+ color: '#123456',
+ role: 'img',
+ 'aria-label': 'Brand blue',
+ style: { width: 24 },
+ render: <span />,
+ },
+ play: async ({ canvas }) => {
+ const swatch = canvas.getByRole('img', { name: 'Brand blue' });
+
+ await expect(swatch.tagName).toBe('SPAN');
+ await expect(swatch).toHaveStyle({
+ backgroundColor: 'rgb(18, 52, 86)',
+ width: '24px',
+ height: '16px',
+ borderWidth: '1px',
+ });
+ },
};
diff --git a/packages/twenty-ui/src/primitives/data-display/ColorSample/__tests__/ColorSample.test.tsx b/packages/twenty-ui/src/primitives/data-display/ColorSample/__tests__/ColorSample.test.tsx
new file mode 100644
index 00000000000..4a048db8834
--- /dev/null
+++ b/packages/twenty-ui/src/primitives/data-display/ColorSample/__tests__/ColorSample.test.tsx
@@ -0,0 +1,43 @@
+import { runComponentConformance } from '@test-utilities/conformance/runComponentConformance';
+import { render, screen } from '@testing-library/react';
+
+import { ColorSample } from '@ui/primitives/data-display';
+
+runComponentConformance({
+ name: 'ColorSample',
+ element: <ColorSample colorName="blue" />,
+ refInstanceOf: HTMLDivElement,
+ ownClassName: 'root',
+});
+
+it('exposes a named color only when the caller supplies image semantics', () => {
+ render(
+ <>
+ <ColorSample colorName="red" aria-hidden="true" />
+ <ColorSample colorName="blue" role="img" aria-label="Brand blue" />
+ </>,
+ );
+
+ expect(screen.getAllByRole('img')).toHaveLength(1);
+ expect(screen.getByRole('img', { name: 'Brand blue' })).toBeVisible();
+});
+
+it('preserves the palette border when a custom fill and native styles are supplied', () => {
+ render(
+ <ColorSample
+ colorName="blue"
+ color="#123456"
+ role="img"
+ aria-label="Custom blue"
+ style={{ width: 24 }}
+ />,
+ );
+
+ const swatch = screen.getByRole('img', { name: 'Custom blue' });
+
+ expect(swatch.style.getPropertyValue('--color-sample-color')).toBe('#123456');
+ expect(swatch.style.getPropertyValue('--color-sample-border-color')).toBe(
+ 'var(--t-tag-text-blue)',
+ );
+ expect(swatch).toHaveStyle({ width: '24px' });
+});
diff --git a/packages/twenty-ui/src/primitives/data-display/ColorSample/types/ColorSampleProps.ts b/packages/twenty-ui/src/primitives/data-display/ColorSample/types/ColorSampleProps.ts
new file mode 100644
index 00000000000..d3ac21cfaac
--- /dev/null
+++ b/packages/twenty-ui/src/primitives/data-display/ColorSample/types/ColorSampleProps.ts
@@ -0,0 +1,11 @@
+import { type useRender } from '@base-ui/react/use-render';
+
+import { type ThemeColor } from '@ui/theme';
+
+import { type ColorSampleVariant } from './ColorSampleVariant';
+
+export type ColorSampleProps = useRender.ComponentProps<'div'> & {
+ colorName: ThemeColor;
+ color?: string;
+ variant?: ColorSampleVariant;
+};
diff --git a/packages/twenty-ui/src/primitives/data-display/ColorSample/types/ColorSampleVariant.ts b/packages/twenty-ui/src/primitives/data-display/ColorSample/types/ColorSampleVariant.ts
new file mode 100644
index 00000000000..cb4c733b869
--- /dev/null
+++ b/packages/twenty-ui/src/primitives/data-display/ColorSample/types/ColorSampleVariant.ts
@@ -0,0 +1 @@
+export type ColorSampleVariant = 'circle' | 'default';
diff --git a/packages/twenty-ui/src/primitives/data-display/index.ts b/packages/twenty-ui/src/primitives/data-display/index.ts
index e423fe3fe9c..9da76565774 100644
--- a/packages/twenty-ui/src/primitives/data-display/index.ts
+++ b/packages/twenty-ui/src/primitives/data-display/index.ts
@@ -16,11 +16,9 @@ export { Chip } from './Chip/Chip';
export type { ChipProps } from './Chip/types/ChipProps';
export type { ChipSize } from './Chip/types/ChipSize';
export type { ChipVariant } from './Chip/types/ChipVariant';
-export type {
- ColorSampleVariant,
- ColorSampleProps,
-} from './ColorSample/ColorSample';
export { ColorSample } from './ColorSample/ColorSample';
+export type { ColorSampleProps } from './ColorSample/types/ColorSampleProps';
+export type { ColorSampleVariant } from './ColorSample/types/ColorSampleVariant';
export { Pill } from './Pill/Pill';
export { Status } from './Status/Status';
export type { StatusProps } from './Status/types/StatusProps';
diff --git a/packages/twenty-ui/src/primitives/feedback/Loader/Loader.tsx b/packages/twenty-ui/src/primitives/feedback/Loader/Loader.tsx
index 6d51e2758b7..e082651cc34 100644
--- a/packages/twenty-ui/src/primitives/feedback/Loader/Loader.tsx
+++ b/packages/twenty-ui/src/primitives/feedback/Loader/Loader.tsx
@@ -1,24 +1,35 @@
-import { type ThemeColor, themeCssVariables } from '@ui/theme';
+import { useRender } from '@base-ui/react/use-render';
+import { clsx } from 'clsx';
+import { type CSSProperties } from 'react';
-import styles from './Loader.module.scss';
+import { themeCssVariables } from '@ui/theme';
+import { isDefined } from '@ui/utilities/utils/isDefined';
+
+import { type LoaderProps } from './types/LoaderProps';
-type LoaderProps = {
- color?: ThemeColor;
-};
+import styles from './Loader.module.scss';
-export const Loader = ({ color }: LoaderProps) => {
- return (
- <div
- className={styles.container}
- style={
- color
- ? ({
- '--loader-color': themeCssVariables.tag.text[color],
- } as React.CSSProperties)
- : undefined
- }
- >
- <div className={styles.dot} />
- </div>
- );
-};
+export const Loader = ({
+ color,
+ className,
+ style,
+ render,
+ ref,
+ ...props
+}: LoaderProps) =>
+ useRender({
+ defaultTagName: 'div',
+ render,
+ ref,
+ props: {
+ ...props,
+ className: clsx(styles.container, className),
+ style: {
+ ...(isDefined(color) && {
+ '--loader-color': themeCssVariables.tag.text[color],
+ }),
+ ...style,
+ } as CSSProperties,
+ children: <span className={styles.dot} aria-hidden="true" />,
+ },
+ });
diff --git a/packages/twenty-ui/src/primitives/feedback/Loader/__stories__/Loader.stories.tsx b/packages/twenty-ui/src/primitives/feedback/Loader/__stories__/Loader.stories.tsx
index b09caceded2..181bae62f55 100644
--- a/packages/twenty-ui/src/primitives/feedback/Loader/__stories__/Loader.stories.tsx
+++ b/packages/twenty-ui/src/primitives/feedback/Loader/__stories__/Loader.stories.tsx
@@ -1,9 +1,10 @@
import { type Meta, type StoryObj } from '@storybook/react-vite';
-import { expect, waitFor } from 'storybook/test';
-
-import { ComponentDecorator } from '@ui/testing';
+import { type CSSProperties } from 'react';
+import { expect } from 'storybook/test';
import { Loader } from '@ui/primitives/feedback/Loader/Loader';
+import { Text } from '@ui/primitives/typography';
+import { ComponentDecorator } from '@ui/testing';
const meta: Meta<typeof Loader> = {
title: 'UI/Feedback/Loader',
@@ -18,83 +19,101 @@ type Story = StoryObj<typeof Loader>;
export const WithColor: Story = {
args: {
color: 'red',
+ role: 'status',
+ 'aria-label': 'Loading results',
},
- play: async ({ canvasElement }) => {
- await waitFor(() => {
- const element = canvasElement.querySelector(':first-child');
-
- expect(element).toBeVisible();
-
- return element;
- });
+ play: async ({ canvas }) => {
+ await expect(
+ canvas.getByRole('status', { name: 'Loading results' }),
+ ).toBeVisible();
},
};
export const WithColorDocumentation: Story = {
- args: WithColor.args,
+ render: () => (
+ <Text render={<div />} role="status" style={{ display: 'flex', gap: 8 }}>
+ <Loader
+ color="blue"
+ aria-hidden="true"
+ render={<span />}
+ data-testid="decorative-loader"
+ />
+ <Text>Saving changes</Text>
+ </Text>
+ ),
+};
+
+export const WithStatusText: Story = {
+ ...WithColorDocumentation,
+ play: async ({ canvas }) => {
+ const status = canvas.getByRole('status');
+ const label = canvas.getByText('Saving changes');
+ const loader = canvas.getByTestId('decorative-loader');
+
+ await expect(status).toHaveTextContent('Saving changes');
+ await expect(label).toBeVisible();
+ await expect(loader).toHaveStyle({ width: '24px', height: '12px' });
+ await expect(label.getBoundingClientRect().left).toBeGreaterThanOrEqual(
+ loader.getBoundingClientRect().right,
+ );
+ },
};
export const WithDefaultCssVariable: Story = {
decorators: [
(Story) => (
- // @ts-expect-error: Custom CSS variable for demonstration purposes
- <div style={{ '--tw-button-color': 'blue' }}>
+ <Text
+ render={<div />}
+ style={{ '--tw-button-color': 'blue' } as CSSProperties}
+ >
<Story />
- </div>
+ </Text>
),
],
- play: async ({ canvasElement }) => {
- await waitFor(() => {
- const element = canvasElement.querySelector(':first-child');
-
- expect(element).toBeVisible();
-
- return element;
+ args: { role: 'status', 'aria-label': 'Loading results' },
+ play: async ({ canvas }) => {
+ await expect(
+ canvas.getByRole('status', { name: 'Loading results' }),
+ ).toHaveStyle({
+ borderColor: 'rgb(0, 0, 255)',
});
},
};
export const WithDefaultColor: Story = {
- play: async ({ canvasElement }) => {
- await waitFor(() => {
- const element = canvasElement.querySelector(':first-child');
-
- expect(element).toBeVisible();
-
- return element;
- });
- },
+ args: { 'aria-hidden': true },
};
export const WithDifferentColors: Story = {
render: () => (
- <div id="container" style={{ display: 'flex', gap: '16px' }}>
- <Loader color="red" />
- <Loader color="blue" />
- <Loader color="yellow" />
- <Loader color="green" />
- </div>
+ <Text render={<div />} style={{ display: 'flex', gap: 16 }}>
+ <Loader color="red" aria-hidden="true" />
+ <Loader color="blue" aria-hidden="true" />
+ <Loader color="yellow" aria-hidden="true" />
+ <Loader color="green" aria-hidden="true" />
+ </Text>
),
- play: async ({ canvasElement }) => {
- const loaders = await waitFor(() => {
- const elements = canvasElement.querySelectorAll('#container > *');
-
- expect(elements).toHaveLength(4);
+};
- return elements;
- });
+export const Composition: Story = {
+ args: {
+ role: 'status',
+ 'aria-labelledby': 'loader-label',
+ render: (props) => <span {...props} />,
+ className: 'custom-loader',
+ style: { borderColor: '#123456' },
+ },
+ render: (args) => (
+ <Text render={<div />} style={{ display: 'flex', gap: 8 }}>
+ <Loader {...args} />
+ <Text id="loader-label">Loading results</Text>
+ </Text>
+ ),
+ play: async ({ canvas }) => {
+ const loader = canvas.getByRole('status', { name: 'Loading results' });
- expect(loaders[0]).toHaveStyle({
- borderColor: expect.stringContaining('red'),
- });
- expect(loaders[1]).toHaveStyle({
- borderColor: expect.stringContaining('blue'),
- });
- expect(loaders[2]).toHaveStyle({
- borderColor: expect.stringContaining('yellow'),
- });
- expect(loaders[3]).toHaveStyle({
- borderColor: expect.stringContaining('green'),
- });
+ await expect(loader.tagName).toBe('SPAN');
+ await expect(loader).toHaveClass('custom-loader');
+ await expect(loader).toHaveStyle({ borderColor: 'rgb(18, 52, 86)' });
},
};
diff --git a/packages/twenty-ui/src/primitives/feedback/Loader/__tests__/Loader.test.tsx b/packages/twenty-ui/src/primitives/feedback/Loader/__tests__/Loader.test.tsx
new file mode 100644
index 00000000000..85dfcc73aef
--- /dev/null
+++ b/packages/twenty-ui/src/primitives/feedback/Loader/__tests__/Loader.test.tsx
@@ -0,0 +1,30 @@
+import { runComponentConformance } from '@test-utilities/conformance/runComponentConformance';
+import { render, screen } from '@testing-library/react';
+
+import { Loader } from '@ui/primitives/feedback';
+
+runComponentConformance({
+ name: 'Loader',
+ element: <Loader color="blue" />,
+ refInstanceOf: HTMLDivElement,
+ ownClassName: 'container',
+});
+
+it('leaves announcements to the caller and hides a decorative loader', () => {
+ render(<Loader aria-hidden="true" data-testid="decorative-loader" />);
+
+ expect(screen.queryByRole('status')).not.toBeInTheDocument();
+ expect(screen.getByTestId('decorative-loader')).toHaveAttribute(
+ 'aria-hidden',
+ 'true',
+ );
+});
+
+it('supports a named live status with a decorative animated dot', () => {
+ render(<Loader role="status" aria-label="Saving changes" />);
+
+ const status = screen.getByRole('status', { name: 'Saving changes' });
+
+ expect(status).not.toHaveAttribute('aria-hidden');
+ expect(status.firstElementChild).toHaveAttribute('aria-hidden', 'true');
+});
diff --git a/packages/twenty-ui/src/primitives/feedback/Loader/types/LoaderProps.ts b/packages/twenty-ui/src/primitives/feedback/Loader/types/LoaderProps.ts
new file mode 100644
index 00000000000..feabeb92a73
--- /dev/null
+++ b/packages/twenty-ui/src/primitives/feedback/Loader/types/LoaderProps.ts
@@ -0,0 +1,10 @@
+import { type useRender } from '@base-ui/react/use-render';
+
+import { type ThemeColor } from '@ui/theme';
+
+export type LoaderProps = Omit<
+ useRender.ComponentProps<'div'>,
+ 'children' | 'color'
+> & {
+ color?: ThemeColor;
+};
diff --git a/packages/twenty-ui/src/primitives/feedback/index.ts b/packages/twenty-ui/src/primitives/feedback/index.ts
index 8ca76230945..f8bf28eaed8 100644
--- a/packages/twenty-ui/src/primitives/feedback/index.ts
+++ b/packages/twenty-ui/src/primitives/feedback/index.ts
@@ -10,6 +10,7 @@
export type { BannerColor, BannerVariant } from './Banner/Banner';
export { Banner } from './Banner/Banner';
export { Loader } from './Loader/Loader';
+export type { LoaderProps } from './Loader/types/LoaderProps';
export { ProgressBar } from './ProgressBar/ProgressBar';
export type { ProgressBarProps } from './ProgressBar/types/ProgressBarProps';
export { ProgressRing } from './ProgressRing/ProgressRing';