Skip to content

The open alternative to Salesforce, designed for AI.

Preserve native Breadcrumb links (#27636)

Raphaël Bosi4f7e2bef825a
diff --git a/packages/twenty-docs/snippets/ui/generated/navigation/breadcrumb.mdx b/packages/twenty-docs/snippets/ui/generated/navigation/breadcrumb.mdx
index 4f46444bcf6..5f64e852b6e 100644
--- a/packages/twenty-docs/snippets/ui/generated/navigation/breadcrumb.mdx
+++ b/packages/twenty-docs/snippets/ui/generated/navigation/breadcrumb.mdx
@@ -11,10 +11,26 @@
* npx nx generate:ui twenty-docs
*/}
+<ParamField body="aria-label" type="string">
+ Accessible navigation name. Defaults to Breadcrumb; supply a localized name or use aria-labelledby.
+</ParamField>
+
+<ParamField body="className" type="string">
+ Class merged onto the root navigation element.
+</ParamField>
+
<ParamField body="links" type="BreadcrumbItem[]" required>
- Ordered trail items. Each item accepts `children`, `href`, `render`, and `title`. The final item represents the current page.
+ Ordered trail items with native anchor attributes, event handlers, ref, children and element or callback render composition. Items with href default to anchors; other items default to text. The final item defaults to aria-current="page". An explicit aria-current value is preserved, including false.
+</ParamField>
+
+<ParamField body="ref" type="Ref&lt;HTMLElement&gt;">
+ Ref to the root nav, or the DOM element supplied through render.
</ParamField>
<ParamField body="render" type="ReactElement&lt;unknown, string | JSXElementConstructor&lt;any&gt;&gt; | ComponentRenderFn&lt;HTMLProps, {}&gt;">
Caller-supplied root element or renderer. Preserve the navigation landmark and forward the supplied props and ref.
</ParamField>
+
+<ParamField body="style" type="CSSProperties">
+ Inline styles applied to the root navigation element.
+</ParamField>
diff --git a/packages/twenty-docs/ui/primitives/navigation/breadcrumb.mdx b/packages/twenty-docs/ui/primitives/navigation/breadcrumb.mdx
index b085028c1b9..938147f4f13 100644
--- a/packages/twenty-docs/ui/primitives/navigation/breadcrumb.mdx
+++ b/packages/twenty-docs/ui/primitives/navigation/breadcrumb.mdx
@@ -7,7 +7,7 @@ import { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';
import BreadcrumbReference from '/snippets/ui/generated/navigation/breadcrumb.mdx';
-`Breadcrumb` renders an ordered navigation trail. It owns separators, current-page semantics, link focus styles, and truncation of the current item's label.
+`Breadcrumb` renders an ordered navigation trail. It includes decorative separators, link focus styles, and truncation of the final item's label. Items preserve native anchor behavior and support custom routing through `render`.
<StoryEmbed
storyId="primitives-navigation-breadcrumb--default"
@@ -17,7 +17,7 @@ import BreadcrumbReference from '/snippets/ui/generated/navigation/breadcrumb.md
## Usage
-Pass items in ancestor-to-current order. The navigation landmark defaults to the accessible name `Breadcrumb`; use `aria-label` to localize it or distinguish multiple trails. The final item receives `aria-current="page"`, whether it has a destination or displays plain text.
+Pass items in ancestor-to-current order. The navigation landmark defaults to the accessible name `Breadcrumb`; use `aria-label` to localize it or distinguish multiple trails. The final item defaults to `aria-current="page"`, whether it has a destination or displays plain text.
```tsx
import { Breadcrumb } from 'twenty-ui/primitives/navigation';
@@ -34,17 +34,65 @@ export const CompanyBreadcrumb = () => (
);
```
-Items with `href` use native links. Items without a destination are text. Separators are decorative and hidden from assistive technology. Links follow the browser's normal Tab and Enter behavior.
+Items with `href` use native anchors. Items without a destination default to text. The `/` separators are decorative, hidden from assistive technology, and outside the links' accessible names. Links follow the browser's normal Tab and Enter behavior, including modifier clicks and opening in a new tab.
+
+## Native item props
+
+Each item accepts native anchor attributes, event handlers, `className`, `style`, and `ref`. For example, pass `target` and `rel` for a new tab, `download` for a file, or `referrerPolicy` to control the request. The item's ref reaches the rendered DOM element.
+
+```tsx
+import { Breadcrumb } from 'twenty-ui/primitives/navigation';
+
+export const ReferenceBreadcrumb = () => (
+ <Breadcrumb
+ aria-label="Reference location"
+ links={[
+ {
+ children: 'Documentation',
+ href: 'https://docs.twenty.com',
+ target: '_blank',
+ rel: 'noopener noreferrer',
+ referrerPolicy: 'no-referrer',
+ },
+ { children: 'Companies' },
+ ]}
+ />
+);
+```
+
+## Current page
+
+An explicit `aria-current` value on an item takes precedence over its position. Use `aria-current="page"` on another item and `aria-current={false}` on the final item when the current page is earlier in the trail. Other native current-item values, such as `step`, are also preserved. Ensure only the intended item is current.
+
+```tsx
+import { Breadcrumb } from 'twenty-ui/primitives/navigation';
+
+export const CompanyContextBreadcrumb = () => (
+ <Breadcrumb
+ links={[
+ { children: 'Home', href: '/' },
+ {
+ children: 'Companies',
+ href: '/companies',
+ 'aria-current': 'page',
+ },
+ { children: 'Acme', 'aria-current': false },
+ ]}
+ />
+);
+```
## Router links
-Use an item's `render` prop to supply your router's link component, alongside `href`. The rendered link must forward the supplied props and ref to its anchor. See [custom components](/ui/primitives/overview#custom-components) for composition requirements.
+Use an item's `render` prop to supply your router's link component, alongside `href`. Pass router-specific destinations, state, and history options directly to that component. `render` accepts either an element or a function receiving the supplied props, including native anchor attributes and its ref.
+
+The rendered link must forward the supplied props and ref to its anchor. Preserve native link behavior when handling navigation, including modifier clicks and new tabs. See [custom components](/ui/primitives/overview#custom-components) for composition requirements.
The application chooses destinations and decides when to show a mobile back action. `Breadcrumb` does not infer routes or collapse ancestors into a menu.
## Long labels
-The current item shrinks and truncates with an ellipsis when the container has limited space. Ancestor items retain their width. Plain string labels become the native browser tooltip automatically. Use `title` to override that text or provide a tooltip for rich content.
+The final item shrinks and truncates with an ellipsis when the container has limited space. Ancestor items retain their width. Plain string labels become the native browser tooltip automatically. Use `title` to override that text or provide a tooltip for rich content. Set `title=""` to suppress the automatic tooltip.
<StoryEmbed
storyId="primitives-navigation-breadcrumb--truncation"
@@ -72,8 +120,41 @@ The trail follows the surrounding text direction. Set `dir="rtl"` on `Breadcrumb
height={160}
/>
-## Props
+## Root customization
+
+Native navigation attributes, including accessible names, `className`, `style`, and event handlers, reach the root landmark. The root ref reaches its `nav` element. Root `render` also accepts an element or function; keep the navigation landmark and forward its supplied props and ref.
+
+```tsx
+import { useRef } from 'react';
+import { Breadcrumb } from 'twenty-ui/primitives/navigation';
+
+export const HeaderBreadcrumb = () => {
+ const navigationRef = useRef<HTMLElement>(null);
+ const companiesRef = useRef<HTMLAnchorElement>(null);
+
+ return (
+ <Breadcrumb
+ aria-label="Company location"
+ ref={navigationRef}
+ render={<nav data-location="header" />}
+ links={[
+ {
+ children: 'Companies',
+ href: '/companies',
+ ref: companiesRef,
+ render: (props) => (
+ <a {...props} data-route={props.href}>
+ {props.children}
+ </a>
+ ),
+ },
+ { children: 'Acme' },
+ ]}
+ />
+ );
+};
+```
-Native navigation attributes, including accessible names, `className`, `style`, and event handlers, reach the root landmark.
+## Props
<BreadcrumbReference />
diff --git a/packages/twenty-front-component-renderer/src/__stories__/twenty-ui-gallery/twenty-ui-breadcrumb.front-component.tsx b/packages/twenty-front-component-renderer/src/__stories__/twenty-ui-gallery/twenty-ui-breadcrumb.front-component.tsx
index e94cfc1f759..06a8c31db74 100644
--- a/packages/twenty-front-component-renderer/src/__stories__/twenty-ui-gallery/twenty-ui-breadcrumb.front-component.tsx
+++ b/packages/twenty-front-component-renderer/src/__stories__/twenty-ui-gallery/twenty-ui-breadcrumb.front-component.tsx
@@ -1,5 +1,6 @@
-import { useState } from 'react';
+import { createElement, useState } from 'react';
import { defineFrontComponent } from 'twenty-sdk/define';
+import { isDefined } from 'twenty-shared/utils';
import { Breadcrumb } from 'twenty-ui/primitives/navigation';
import { Text } from 'twenty-ui/primitives/typography';
@@ -8,14 +9,41 @@ import { TwentyUiGalleryCard } from '@/__stories__/shared/front-components/twent
const BreadcrumbExample = () => {
const [activations, setActivations] = useState(0);
const [composedActivations, setComposedActivations] = useState(0);
+ const [nativeActivations, setNativeActivations] = useState(0);
+ const [nativeTarget, setNativeTarget] = useState('');
return (
<TwentyUiGalleryCard title="Breadcrumb">
<Breadcrumb
aria-label="Account breadcrumb"
onClick={() => setActivations((count) => count + 1)}
+ render={<nav data-composed-root="true" />}
+ ref={(element) => {
+ if (isDefined(element)) element.dataset.refTag = element.tagName;
+ }}
links={[
- { children: 'Objects', href: '/objects' },
+ {
+ children: 'Objects',
+ href: '/objects',
+ target: '_self',
+ rel: 'nofollow',
+ download: 'objects.csv',
+ hrefLang: 'en',
+ referrerPolicy: 'no-referrer',
+ id: 'objects-link',
+ className: 'native-breadcrumb-link',
+ tabIndex: 0,
+ title: 'All objects',
+ onClick: (event) => {
+ setNativeActivations((count) => count + 1);
+ setNativeTarget(
+ `${event.currentTarget.tagName}:${event.currentTarget.getAttribute('href')}`,
+ );
+ },
+ ref: (element) => {
+ if (isDefined(element)) element.dataset.refTag = element.tagName;
+ },
+ },
{
children: 'Account',
href: '/objects/account',
@@ -25,6 +53,24 @@ const BreadcrumbExample = () => {
},
]}
/>
+ <Breadcrumb
+ aria-label="Explicit current breadcrumb"
+ links={[
+ {
+ children: 'Workspace',
+ href: '/workspace',
+ 'aria-current': 'location',
+ render: (props) =>
+ createElement('a', { ...props, 'data-composed-route': 'true' }),
+ },
+ {
+ children: 'Following',
+ href: '/following',
+ 'aria-current': false,
+ title: '',
+ },
+ ]}
+ />
<Breadcrumb
aria-label="Truncated breadcrumb"
style={{ width: 220 }}
@@ -36,7 +82,8 @@ const BreadcrumbExample = () => {
]}
/>
<Text role="status">
- Activations: {activations}; Composed activations: {composedActivations}
+ Activations: {activations}; Composed activations: {composedActivations};
+ Native activations: {nativeActivations}; Native target: {nativeTarget}
</Text>
</TwentyUiGalleryCard>
);
@@ -45,6 +92,7 @@ const BreadcrumbExample = () => {
export default defineFrontComponent({
universalIdentifier: 'e5e0d2b9-5227-4376-bc92-364cb55a9f72',
name: 'twenty-ui-breadcrumb',
- description: 'Breadcrumb links, current items, and truncation in the sandbox',
+ description:
+ 'Breadcrumb native links, current items, and composition in the sandbox',
component: BreadcrumbExample,
});
diff --git a/packages/twenty-front-component-renderer/src/__stories__/twenty-ui-gallery/utils/breadcrumbTest.ts b/packages/twenty-front-component-renderer/src/__stories__/twenty-ui-gallery/utils/breadcrumbTest.ts
index 68347203e12..8382174bbb8 100644
--- a/packages/twenty-front-component-renderer/src/__stories__/twenty-ui-gallery/utils/breadcrumbTest.ts
+++ b/packages/twenty-front-component-renderer/src/__stories__/twenty-ui-gallery/utils/breadcrumbTest.ts
@@ -17,10 +17,26 @@ export const breadcrumbTest: TwentyUiGalleryPlayFunction = async ({
const objects = trail.getByRole('link', { name: 'Objects' });
const account = trail.getByRole('link', { name: 'Account', current: 'page' });
+ await waitFor(() =>
+ expect(navigation).toHaveAttribute('data-ref-tag', 'HTML-NAV'),
+ );
+ await expect(navigation).toHaveAttribute('data-composed-root', 'true');
await expect(trail.getByRole('list').tagName).toBe('OL');
await expect(trail.getAllByRole('listitem')).toHaveLength(2);
await expect(trail.getByText('/')).toHaveAttribute('aria-hidden', 'true');
+ await waitFor(() =>
+ expect(objects).toHaveAttribute('data-ref-tag', 'HTML-A'),
+ );
await expect(objects).toHaveAttribute('href', '/objects');
+ await expect(objects).toHaveAttribute('target', '_self');
+ await expect(objects).toHaveAttribute('rel', 'nofollow');
+ await expect(objects).toHaveAttribute('download', 'objects.csv');
+ await expect(objects).toHaveAttribute('hreflang', 'en');
+ await expect(objects).toHaveAttribute('referrerpolicy', 'no-referrer');
+ await expect(objects).toHaveAttribute('id', 'objects-link');
+ await expect(objects).toHaveClass('native-breadcrumb-link');
+ await expect(objects).toHaveAttribute('tabindex', '0');
+ await expect(objects).toHaveAttribute('title', 'All objects');
await expect(objects).not.toHaveAttribute('aria-current');
await expect(account).toHaveAttribute('href', '/objects/account');
await expect(account.tagName).toBe('A');
@@ -33,13 +49,13 @@ export const breadcrumbTest: TwentyUiGalleryPlayFunction = async ({
await expect(objects).toHaveFocus();
await waitFor(() =>
expect(canvas.getByRole('status')).toHaveTextContent(
- 'Activations: 1; Composed activations: 0',
+ 'Activations: 1; Composed activations: 0; Native activations: 1; Native target: HTML-A:/objects',
),
);
await userEvent.keyboard('{Enter}');
await waitFor(() =>
expect(canvas.getByRole('status')).toHaveTextContent(
- 'Activations: 2; Composed activations: 0',
+ 'Activations: 2; Composed activations: 0; Native activations: 2; Native target: HTML-A:/objects',
),
);
await userEvent.tab();
@@ -47,13 +63,30 @@ export const breadcrumbTest: TwentyUiGalleryPlayFunction = async ({
await userEvent.keyboard('{Enter}');
await waitFor(() =>
expect(canvas.getByRole('status')).toHaveTextContent(
- 'Activations: 3; Composed activations: 1',
+ 'Activations: 3; Composed activations: 1; Native activations: 2; Native target: HTML-A:/objects',
),
);
} finally {
navigation.removeEventListener('click', preventNavigation);
}
+ const explicitTrail = within(
+ canvas.getByRole('navigation', { name: 'Explicit current breadcrumb' }),
+ );
+ const workspace = explicitTrail.getByRole('link', {
+ name: 'Workspace',
+ current: 'location',
+ });
+ const following = explicitTrail.getByRole('link', {
+ name: 'Following',
+ current: false,
+ });
+
+ await expect(workspace).toHaveAttribute('href', '/workspace');
+ await expect(workspace).toHaveAttribute('data-composed-route', 'true');
+ await expect(following).toHaveAttribute('aria-current', 'false');
+ await expect(following).toHaveAttribute('title', '');
+
const truncatedNavigation = canvas.getByRole('navigation', {
name: 'Truncated breadcrumb',
});
diff --git a/packages/twenty-front-component-renderer/src/constants/AllowedHtmlElements.ts b/packages/twenty-front-component-renderer/src/constants/AllowedHtmlElements.ts
index 39fab48cad4..60d2dbaa569 100644
--- a/packages/twenty-front-component-renderer/src/constants/AllowedHtmlElements.ts
+++ b/packages/twenty-front-component-renderer/src/constants/AllowedHtmlElements.ts
@@ -39,6 +39,9 @@ export const ALLOWED_HTML_ELEMENTS: AllowedHtmlElement[] = [
href: { type: 'string', optional: true },
target: { type: 'string', optional: true },
rel: { type: 'string', optional: true },
+ download: { type: 'string', optional: true },
+ hrefLang: { type: 'string', optional: true },
+ referrerPolicy: { type: 'string', optional: true },
},
},
{
diff --git a/packages/twenty-front-component-renderer/src/remote/generated/remote-elements.ts b/packages/twenty-front-component-renderer/src/remote/generated/remote-elements.ts
index 4adcef93245..1e1079885f4 100644
--- a/packages/twenty-front-component-renderer/src/remote/generated/remote-elements.ts
+++ b/packages/twenty-front-component-renderer/src/remote/generated/remote-elements.ts
@@ -393,6 +393,9 @@ export type HtmlAProperties = HtmlCommonProperties & {
href?: string;
target?: string;
rel?: string;
+ download?: string;
+ hrefLang?: string;
+ referrerPolicy?: string;
};
export const HtmlAElement = createRemoteElement<
@@ -406,6 +409,9 @@ export const HtmlAElement = createRemoteElement<
href: { type: String },
target: { type: String },
rel: { type: String },
+ download: { type: String },
+ hrefLang: { type: String },
+ referrerPolicy: { type: String },
},
events: {
...HTML_COMMON_EVENTS_CONFIG,
diff --git a/packages/twenty-ui/docs/breadcrumbPropDescriptions.ts b/packages/twenty-ui/docs/breadcrumbPropDescriptions.ts
index 4486c2de07e..b8910bbaf36 100644
--- a/packages/twenty-ui/docs/breadcrumbPropDescriptions.ts
+++ b/packages/twenty-ui/docs/breadcrumbPropDescriptions.ts
@@ -4,7 +4,12 @@ import { type Breadcrumb } from '../src/primitives/navigation/Breadcrumb/Breadcr
export const BREADCRUMB_PROP_DESCRIPTIONS = {
links:
- 'Ordered trail items. Each item accepts `children`, `href`, `render`, and `title`. The final item represents the current page.',
+ 'Ordered trail items with native anchor attributes, event handlers, ref, children and element or callback render composition. Items with href default to anchors; other items default to text. The final item defaults to aria-current="page". An explicit aria-current value is preserved, including false.',
+ 'aria-label':
+ 'Accessible navigation name. Defaults to Breadcrumb; supply a localized name or use aria-labelledby.',
+ className: 'Class merged onto the root navigation element.',
+ style: 'Inline styles applied to the root navigation element.',
+ ref: 'Ref to the root nav, or the DOM element supplied through render.',
render:
'Caller-supplied root element or renderer. Preserve the navigation landmark and forward the supplied props and ref.',
} satisfies Partial<Record<keyof ComponentProps<typeof Breadcrumb>, string>>;
diff --git a/packages/twenty-ui/generated/components.docs.json b/packages/twenty-ui/generated/components.docs.json
index 2534d9101d7..9a777a1a343 100644
--- a/packages/twenty-ui/generated/components.docs.json
+++ b/packages/twenty-ui/generated/components.docs.json
@@ -4723,12 +4723,33 @@
"entryPoint": "twenty-ui/primitives/navigation",
"slug": "navigation/breadcrumb",
"props": [
+ {
+ "name": "aria-label",
+ "type": "string",
+ "required": false,
+ "defaultValue": null,
+ "description": "Accessible navigation name. Defaults to Breadcrumb; supply a localized name or use aria-labelledby."
+ },
+ {
+ "name": "className",
+ "type": "string",
+ "required": false,
+ "defaultValue": null,
+ "description": "Class merged onto the root navigation element."
+ },
{
"name": "links",
"type": "BreadcrumbItem[]",
"required": true,
"defaultValue": null,
- "description": "Ordered trail items. Each item accepts `children`, `href`, `render`, and `title`. The final item represents the current page."
+ "description": "Ordered trail items with native anchor attributes, event handlers, ref, children and element or callback render composition. Items with href default to anchors; other items default to text. The final item defaults to aria-current=\"page\". An explicit aria-current value is preserved, including false."
+ },
+ {
+ "name": "ref",
+ "type": "Ref<HTMLElement>",
+ "required": false,
+ "defaultValue": null,
+ "description": "Ref to the root nav, or the DOM element supplied through render."
},
{
"name": "render",
@@ -4736,6 +4757,13 @@
"required": false,
"defaultValue": null,
"description": "Caller-supplied root element or renderer. Preserve the navigation landmark and forward the supplied props and ref."
+ },
+ {
+ "name": "style",
+ "type": "CSSProperties",
+ "required": false,
+ "defaultValue": null,
+ "description": "Inline styles applied to the root navigation element."
}
]
},
diff --git a/packages/twenty-ui/src/primitives/navigation/Breadcrumb/__stories__/Breadcrumb.interactions.stories.tsx b/packages/twenty-ui/src/primitives/navigation/Breadcrumb/__stories__/Breadcrumb.interactions.stories.tsx
new file mode 100644
index 00000000000..83ef92052a5
--- /dev/null
+++ b/packages/twenty-ui/src/primitives/navigation/Breadcrumb/__stories__/Breadcrumb.interactions.stories.tsx
@@ -0,0 +1,196 @@
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import { type MouseEvent } from 'react';
+import { expect, fn, userEvent, within } from 'storybook/test';
+
+import { A11Y_DEFER_COLOR_CONTRAST, ComponentDecorator } from '@ui/testing';
+
+import { Breadcrumb } from '../Breadcrumb';
+
+const LONG_CURRENT_LABEL =
+ 'A company name that needs more room than the page header';
+
+const meta: Meta<typeof Breadcrumb> = {
+ title: 'Primitives/Navigation/Breadcrumb/Interactions',
+ component: Breadcrumb,
+ decorators: [ComponentDecorator],
+ parameters: {
+ container: { width: 350 },
+ a11y: A11Y_DEFER_COLOR_CONTRAST,
+ },
+ args: {
+ links: [
+ { children: 'Objects', href: '/objects' },
+ { children: 'Companies', href: '/companies' },
+ { children: 'New' },
+ ],
+ },
+};
+
+export default meta;
+type Story = StoryObj<typeof Breadcrumb>;
+
+export const Semantics: Story = {
+ play: async ({ canvasElement }) => {
+ const canvas = within(canvasElement);
+ const navigation = canvas.getByRole('navigation', { name: 'Breadcrumb' });
+
+ await expect(within(navigation).getAllByRole('listitem')).toHaveLength(3);
+ await expect(within(navigation).getAllByRole('link')).toHaveLength(2);
+ await expect(canvas.getByText('New')).toHaveAttribute(
+ 'aria-current',
+ 'page',
+ );
+ await expect(
+ canvas.getByRole('link', { name: 'Objects' }),
+ ).not.toHaveAttribute('aria-current');
+
+ for (const separator of canvas.getAllByText('/')) {
+ await expect(separator).toHaveAttribute('aria-hidden', 'true');
+ }
+ },
+};
+
+export const LinkActivation: Story = {
+ args: {
+ onClick: fn((event: MouseEvent<HTMLElement>) => event.preventDefault()),
+ links: [
+ { children: 'Objects', href: '/objects' },
+ {
+ children: 'Companies',
+ href: '/companies',
+ render: (
+ <a href="/companies" data-composed="true">
+ Companies
+ </a>
+ ),
+ },
+ ],
+ },
+ play: async ({ canvasElement, args }) => {
+ const canvas = within(canvasElement);
+ const objects = canvas.getByRole('link', { name: 'Objects' });
+ const companies = canvas.getByRole('link', { name: 'Companies' });
+
+ await userEvent.tab();
+ await expect(objects).toHaveFocus();
+ await expect(getComputedStyle(objects).outlineStyle).toBe('solid');
+ await expect(getComputedStyle(objects).outlineOffset).toBe('-2px');
+ await userEvent.keyboard('{Enter}');
+ await expect(args.onClick).toHaveBeenCalledTimes(1);
+ await userEvent.tab();
+ await expect(companies).toHaveFocus();
+ await expect(companies).toHaveAttribute('href', '/companies');
+ await expect(companies).toHaveAttribute('data-composed', 'true');
+ await expect(companies).toHaveAttribute('aria-current', 'page');
+ await userEvent.keyboard('{Enter}');
+ await expect(args.onClick).toHaveBeenCalledTimes(2);
+ await userEvent.click(objects);
+ await expect(args.onClick).toHaveBeenCalledTimes(3);
+ },
+};
+
+export const TruncationBehavior: Story = {
+ args: {
+ links: [
+ { children: 'Objects', href: '/objects' },
+ { children: 'Companies', href: '/companies' },
+ { children: LONG_CURRENT_LABEL },
+ ],
+ },
+ play: async ({ canvasElement }) => {
+ const canvas = within(canvasElement);
+ const current = canvas.getByText(LONG_CURRENT_LABEL);
+ const objects = canvas.getByRole('link', { name: 'Objects' });
+ const companies = canvas.getByRole('link', { name: 'Companies' });
+
+ await expect(current.scrollWidth).toBeGreaterThan(current.clientWidth);
+ await expect(getComputedStyle(current).textOverflow).toBe('ellipsis');
+ await expect(current).toHaveAttribute('title', LONG_CURRENT_LABEL);
+ await expect(objects.scrollWidth).toBe(objects.clientWidth);
+ await expect(companies.scrollWidth).toBe(companies.clientWidth);
+ await expect(current.getBoundingClientRect().right).toBeLessThanOrEqual(
+ canvas.getByRole('navigation').getBoundingClientRect().right + 1,
+ );
+ },
+};
+
+export const SingleItem: Story = {
+ args: { links: [{ children: 'Settings' }] },
+ play: async ({ canvasElement }) => {
+ const canvas = within(canvasElement);
+
+ await expect(canvas.getByText('Settings')).toHaveAttribute(
+ 'aria-current',
+ 'page',
+ );
+ await expect(canvas.queryByRole('link')).not.toBeInTheDocument();
+ await expect(canvas.queryByText('/')).not.toBeInTheDocument();
+ },
+};
+
+export const Empty: Story = {
+ args: { links: [] },
+ play: async ({ canvasElement }) => {
+ const canvas = within(canvasElement);
+
+ await expect(canvas.getByRole('list')).toBeEmptyDOMElement();
+ await expect(canvas.queryByRole('link')).not.toBeInTheDocument();
+ },
+};
+
+export const NativeIntegration: Story = {
+ args: {
+ 'aria-label': 'Record path',
+ ref: fn(),
+ render: <nav data-composed-root="true" />,
+ links: [
+ {
+ children: 'Workspace',
+ href: '#workspace',
+ target: '_blank',
+ rel: 'noopener noreferrer',
+ download: 'workspace.csv',
+ referrerPolicy: 'no-referrer',
+ 'aria-current': 'location',
+ title: '',
+ ref: fn(),
+ onClick: fn((event: MouseEvent<HTMLAnchorElement>) =>
+ event.preventDefault(),
+ ),
+ render: (props) => (
+ <a {...props} data-composed-link="true">
+ {props.children}
+ </a>
+ ),
+ },
+ { children: 'Companies', href: '#companies', 'aria-current': false },
+ ],
+ },
+ play: async ({ canvasElement, args }) => {
+ const canvas = within(canvasElement);
+ const navigation = canvas.getByRole('navigation', { name: 'Record path' });
+ const workspace = canvas.getByRole('link', { name: 'Workspace' });
+ const companies = canvas.getByRole('link', { name: 'Companies' });
+
+ await expect(navigation).toHaveAttribute('data-composed-root', 'true');
+ await expect(args.ref).toHaveBeenCalledWith(navigation);
+ await expect(workspace).toHaveAttribute('href', '#workspace');
+ await expect(workspace).toHaveAttribute('target', '_blank');
+ await expect(workspace).toHaveAttribute('rel', 'noopener noreferrer');
+ await expect(workspace).toHaveAttribute('download', 'workspace.csv');
+ await expect(workspace).toHaveAttribute('referrerpolicy', 'no-referrer');
+ await expect(workspace).toHaveAttribute('title', '');
+ await expect(workspace).toHaveAttribute('aria-current', 'location');
+ await expect(workspace).toHaveAttribute('data-composed-link', 'true');
+ await expect(args.links[0]?.ref).toHaveBeenCalledWith(workspace);
+ await expect(companies).toHaveAttribute('aria-current', 'false');
+ await userEvent.tab();
+ await expect(workspace).toHaveFocus();
+ await userEvent.keyboard('{Enter}');
+ await expect(args.links[0]?.onClick).toHaveBeenCalledTimes(1);
+ await userEvent.keyboard('{Control>}');
+ await userEvent.click(workspace);
+ await userEvent.keyboard('{/Control}');
+ await expect(args.links[0]?.onClick).toHaveBeenCalledTimes(2);
+ },
+};
diff --git a/packages/twenty-ui/src/primitives/navigation/Breadcrumb/__stories__/Breadcrumb.stories.tsx b/packages/twenty-ui/src/primitives/navigation/Breadcrumb/__stories__/Breadcrumb.stories.tsx
index be15162f73f..50a9db1ea0d 100644
--- a/packages/twenty-ui/src/primitives/navigation/Breadcrumb/__stories__/Breadcrumb.stories.tsx
+++ b/packages/twenty-ui/src/primitives/navigation/Breadcrumb/__stories__/Breadcrumb.stories.tsx
@@ -1,6 +1,4 @@
import { type Meta, type StoryObj } from '@storybook/react-vite';
-import { type MouseEvent } from 'react';
-import { expect, fn, userEvent, within } from 'storybook/test';
import { Text } from '@ui/primitives/typography/Text/Text';
import { A11Y_DEFER_COLOR_CONTRAST, ComponentDecorator } from '@ui/testing';
@@ -67,106 +65,32 @@ export const Rtl: Story = { args: { dir: 'rtl' } };
export const Dark: Story = { globals: { colorScheme: 'dark' } };
-export const Semantics: Story = {
- play: async ({ canvasElement }) => {
- const canvas = within(canvasElement);
- const navigation = canvas.getByRole('navigation', { name: 'Breadcrumb' });
-
- await expect(within(navigation).getAllByRole('listitem')).toHaveLength(3);
- await expect(within(navigation).getAllByRole('link')).toHaveLength(2);
- await expect(canvas.getByText('New')).toHaveAttribute(
- 'aria-current',
- 'page',
- );
- await expect(
- canvas.getByRole('link', { name: 'Objects' }),
- ).not.toHaveAttribute('aria-current');
-
- for (const separator of canvas.getAllByText('/')) {
- await expect(separator).toHaveAttribute('aria-hidden', 'true');
- }
- },
+export const SingleItem: Story = {
+ args: { links: [{ children: 'Settings' }] },
};
-export const LinkActivation: Story = {
+export const Empty: Story = { args: { links: [] } };
+
+export const NativeLinks: Story = {
args: {
- ...LinkedCurrentItem.args,
- onClick: fn((event: MouseEvent<HTMLElement>) => event.preventDefault()),
links: [
- { children: 'Objects', href: '/objects' },
{
- children: 'Companies',
- href: '/companies',
- render: (
- <a href="/companies" data-composed="true">
- Companies
- </a>
- ),
+ children: 'Workspace',
+ href: '#workspace',
+ target: '_blank',
+ rel: 'noopener noreferrer',
+ referrerPolicy: 'no-referrer',
},
+ { children: 'Companies', href: '#companies', title: '' },
],
},
- play: async ({ canvasElement, args }) => {
- const canvas = within(canvasElement);
- const objects = canvas.getByRole('link', { name: 'Objects' });
- const companies = canvas.getByRole('link', { name: 'Companies' });
-
- await userEvent.tab();
- await expect(objects).toHaveFocus();
- await expect(getComputedStyle(objects).outlineStyle).toBe('solid');
- await expect(getComputedStyle(objects).outlineOffset).toBe('-2px');
- await userEvent.keyboard('{Enter}');
- await expect(args.onClick).toHaveBeenCalledTimes(1);
- await userEvent.tab();
- await expect(companies).toHaveFocus();
- await expect(companies).toHaveAttribute('href', '/companies');
- await expect(companies).toHaveAttribute('data-composed', 'true');
- await expect(companies).toHaveAttribute('aria-current', 'page');
- await userEvent.keyboard('{Enter}');
- await expect(args.onClick).toHaveBeenCalledTimes(2);
- await userEvent.click(objects);
- await expect(args.onClick).toHaveBeenCalledTimes(3);
- },
};
-export const TruncationBehavior: Story = {
- ...Truncation,
- play: async ({ canvasElement }) => {
- const canvas = within(canvasElement);
- const current = canvas.getByText(LONG_CURRENT_LABEL);
- const objects = canvas.getByRole('link', { name: 'Objects' });
- const companies = canvas.getByRole('link', { name: 'Companies' });
-
- await expect(current.scrollWidth).toBeGreaterThan(current.clientWidth);
- await expect(getComputedStyle(current).textOverflow).toBe('ellipsis');
- await expect(current).toHaveAttribute('title', LONG_CURRENT_LABEL);
- await expect(objects.scrollWidth).toBe(objects.clientWidth);
- await expect(companies.scrollWidth).toBe(companies.clientWidth);
- await expect(current.getBoundingClientRect().right).toBeLessThanOrEqual(
- canvas.getByRole('navigation').getBoundingClientRect().right + 1,
- );
- },
-};
-
-export const SingleItem: Story = {
- args: { links: [{ children: 'Settings' }] },
- play: async ({ canvasElement }) => {
- const canvas = within(canvasElement);
-
- await expect(canvas.getByText('Settings')).toHaveAttribute(
- 'aria-current',
- 'page',
- );
- await expect(canvas.queryByRole('link')).not.toBeInTheDocument();
- await expect(canvas.queryByText('/')).not.toBeInTheDocument();
- },
-};
-
-export const Empty: Story = {
- args: { links: [] },
- play: async ({ canvasElement }) => {
- const canvas = within(canvasElement);
-
- await expect(canvas.getByRole('list')).toBeEmptyDOMElement();
- await expect(canvas.queryByRole('link')).not.toBeInTheDocument();
+export const ExplicitCurrentItem: Story = {
+ args: {
+ links: [
+ { children: 'Workspace', href: '#workspace', 'aria-current': 'page' },
+ { children: 'Company', href: '#company', 'aria-current': false },
+ ],
},
};
diff --git a/packages/twenty-ui/src/primitives/navigation/Breadcrumb/__tests__/Breadcrumb.test.tsx b/packages/twenty-ui/src/primitives/navigation/Breadcrumb/__tests__/Breadcrumb.test.tsx
index df288be84b8..942ad5a3ccb 100644
--- a/packages/twenty-ui/src/primitives/navigation/Breadcrumb/__tests__/Breadcrumb.test.tsx
+++ b/packages/twenty-ui/src/primitives/navigation/Breadcrumb/__tests__/Breadcrumb.test.tsx
@@ -1,3 +1,8 @@
+import { render, screen, within } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { createRef, type ComponentPropsWithRef, type MouseEvent } from 'react';
+import { describe, expect, it, vi } from 'vitest';
+
import { runComponentConformance } from '@test-utilities/conformance/runComponentConformance';
import { Breadcrumb } from '../Breadcrumb';
@@ -9,3 +14,226 @@ runComponentConformance({
ownClassName: styles.root,
refInstanceOf: HTMLElement,
});
+
+const RoutingLink = ({
+ to,
+ children,
+ ...props
+}: ComponentPropsWithRef<'a'> & { to: string }) => (
+ <a {...props} href={to}>
+ {children}
+ </a>
+);
+
+describe('Breadcrumb items', () => {
+ it('preserves native anchor attributes, styling and cancellable events', async () => {
+ const user = userEvent.setup();
+ const onClick = vi.fn();
+ const onFocus = vi.fn();
+ const item = {
+ children: 'Export',
+ href: '#export',
+ target: '_blank',
+ rel: 'noopener noreferrer',
+ download: 'records.csv',
+ hrefLang: 'en',
+ referrerPolicy: 'no-referrer' as const,
+ 'data-destination': 'export',
+ className: 'consumer-link',
+ style: { marginLeft: '7px' },
+ onFocus,
+ onClick: (event: MouseEvent<HTMLAnchorElement>) => {
+ onClick(event.currentTarget, event.defaultPrevented);
+ event.preventDefault();
+ },
+ };
+
+ render(<Breadcrumb links={[item]} />);
+
+ const link = screen.getByRole('link', { name: 'Export' });
+
+ expect(link).toHaveAttribute('href', '#export');
+ expect(link).toHaveAttribute('target', '_blank');
+ expect(link).toHaveAttribute('rel', 'noopener noreferrer');
+ expect(link).toHaveAttribute('download', 'records.csv');
+ expect(link).toHaveAttribute('hreflang', 'en');
+ expect(link).toHaveAttribute('referrerpolicy', 'no-referrer');
+ expect(link).toHaveAttribute('data-destination', 'export');
+ expect(link).toHaveClass(styles.content, 'consumer-link');
+ expect(link).toHaveStyle({ marginLeft: '7px' });
+
+ await user.tab();
+ expect(link).toHaveFocus();
+ expect(onFocus).toHaveBeenCalledOnce();
+ await user.keyboard('{Enter}');
+ expect(onClick).toHaveBeenCalledExactlyOnceWith(link, false);
+ });
+
+ it('keeps default current-page and decorative separator semantics', () => {
+ render(
+ <Breadcrumb
+ aria-label="Record path"
+ links={[
+ { children: 'Workspace', href: '/workspace' },
+ { children: 'Company' },
+ ]}
+ />,
+ );
+
+ const navigation = screen.getByRole('navigation', { name: 'Record path' });
+
+ expect(within(navigation).getAllByRole('listitem')).toHaveLength(2);
+ expect(within(navigation).getByRole('link')).not.toHaveAttribute(
+ 'aria-current',
+ );
+ expect(within(navigation).getByText('Company')).toHaveAttribute(
+ 'aria-current',
+ 'page',
+ );
+ expect(within(navigation).getByText('/')).toHaveAttribute(
+ 'aria-hidden',
+ 'true',
+ );
+ });
+
+ it('respects explicit current-page attributes and linked current items', () => {
+ const { rerender } = render(
+ <Breadcrumb
+ links={[
+ { children: 'Workspace', href: '#workspace', 'aria-current': 'page' },
+ { children: 'Company', href: '#company', 'aria-current': false },
+ ]}
+ />,
+ );
+
+ expect(screen.getByRole('link', { name: 'Workspace' })).toHaveAttribute(
+ 'aria-current',
+ 'page',
+ );
+ expect(screen.getByRole('link', { name: 'Company' })).toHaveAttribute(
+ 'aria-current',
+ 'false',
+ );
+
+ rerender(
+ <Breadcrumb
+ links={[
+ { children: 'Workspace', href: '#workspace' },
+ { children: 'Company', href: '#company', 'aria-current': 'location' },
+ ]}
+ />,
+ );
+ expect(screen.getByRole('link', { name: 'Company' })).toHaveAttribute(
+ 'aria-current',
+ 'location',
+ );
+ });
+
+ it('merges routing element props, handlers and DOM refs', async () => {
+ const user = userEvent.setup();
+ const itemRef = createRef<HTMLAnchorElement>();
+ const routingRef = createRef<HTMLAnchorElement>();
+ const onItemClick = vi.fn();
+ const onRoutingClick = vi.fn();
+ const { unmount } = render(
+ <Breadcrumb
+ links={[
+ {
+ children: 'Companies',
+ href: '#companies',
+ ref: itemRef,
+ onClick: onItemClick,
+ className: 'item-link',
+ render: (
+ <RoutingLink
+ to="#companies"
+ ref={routingRef}
+ className="router-link"
+ data-router="true"
+ onClick={onRoutingClick}
+ />
+ ),
+ },
+ ]}
+ />,
+ );
+
+ const link = screen.getByRole('link', { name: 'Companies' });
+
+ expect(link).toHaveAttribute('href', '#companies');
+ expect(link).toHaveAttribute('data-router', 'true');
+ expect(link).toHaveClass(styles.content, 'item-link', 'router-link');
+ expect(itemRef.current).toBe(link);
+ expect(routingRef.current).toBe(link);
+ await user.click(link);
+ expect(onItemClick).toHaveBeenCalledOnce();
+ expect(onRoutingClick).toHaveBeenCalledOnce();
+
+ unmount();
+ expect(itemRef.current).toBeNull();
+ expect(routingRef.current).toBeNull();
+ });
+
+ it('passes native props and cleanup refs through a routing render function', () => {
+ const cleanup = vi.fn();
+ const ref = vi.fn(() => cleanup);
+ const { unmount } = render(
+ <Breadcrumb
+ links={[
+ {
+ children: 'Settings',
+ href: '#settings',
+ target: '_blank',
+ ref,
+ render: ({ href, ...props }) => (
+ <RoutingLink {...props} to={href ?? '#fallback'} />
+ ),
+ },
+ ]}
+ />,
+ );
+
+ const link = screen.getByRole('link', { name: 'Settings' });
+
+ expect(link).toHaveAttribute('href', '#settings');
+ expect(link).toHaveAttribute('target', '_blank');
+ expect(link).toHaveAttribute('aria-current', 'page');
+ expect(ref).toHaveBeenCalledWith(link);
+ expect(cleanup).not.toHaveBeenCalled();
+ unmount();
+ expect(cleanup).toHaveBeenCalledOnce();
+ });
+
+ it('exposes the actual DOM ref for a static current item', () => {
+ const ref = createRef<HTMLSpanElement>();
+ const { unmount } = render(
+ <Breadcrumb links={[{ children: 'Company', ref }]} />,
+ );
+
+ expect(ref.current).toBe(screen.getByText('Company'));
+ expect(ref.current).toBeInstanceOf(HTMLSpanElement);
+ unmount();
+ expect(ref.current).toBeNull();
+ });
+
+ it('preserves caller-owned nodes and meaningful title overrides', () => {
+ render(
+ <Breadcrumb
+ links={[
+ { children: 'Workspace', href: '#workspace', title: '' },
+ { children: <strong>Company</strong>, title: 'Company record' },
+ ]}
+ />,
+ );
+
+ expect(screen.getByRole('link', { name: 'Workspace' })).toHaveAttribute(
+ 'title',
+ '',
+ );
+ expect(screen.getByText('Company').tagName).toBe('STRONG');
+ expect(screen.getByText('Company').parentElement).toHaveAttribute(
+ 'title',
+ 'Company record',
+ );
+ });
+});
diff --git a/packages/twenty-ui/src/primitives/navigation/Breadcrumb/internal/BreadcrumbItemContent.tsx b/packages/twenty-ui/src/primitives/navigation/Breadcrumb/internal/BreadcrumbItemContent.tsx
index e991cb5984e..e536dabccf3 100644
--- a/packages/twenty-ui/src/primitives/navigation/Breadcrumb/internal/BreadcrumbItemContent.tsx
+++ b/packages/twenty-ui/src/primitives/navigation/Breadcrumb/internal/BreadcrumbItemContent.tsx
@@ -1,5 +1,6 @@
import { useRender } from '@base-ui/react/use-render';
import { isString } from '@sniptt/guards';
+import { clsx } from 'clsx';
import { isDefined } from '@ui/utilities/utils/isDefined';
@@ -16,17 +17,23 @@ export const BreadcrumbItemContent = ({
render,
title,
current,
+ className,
+ ref,
+ 'aria-current': ariaCurrent = current ? 'page' : undefined,
+ ...props
}: BreadcrumbItemContentProps) => {
return useRender({
defaultTagName: isDefined(href) ? 'a' : 'span',
render,
+ ref,
props: {
+ ...props,
children,
href,
title: title ?? (isString(children) ? children : undefined),
- 'aria-current': current ? 'page' : undefined,
+ 'aria-current': ariaCurrent,
'data-linked': isDefined(href) || undefined,
- className: styles.content,
+ className: clsx(styles.content, className),
},
});
};
diff --git a/packages/twenty-ui/src/primitives/navigation/Breadcrumb/types/BreadcrumbItem.ts b/packages/twenty-ui/src/primitives/navigation/Breadcrumb/types/BreadcrumbItem.ts
index 81df00b8a4a..66173db9092 100644
--- a/packages/twenty-ui/src/primitives/navigation/Breadcrumb/types/BreadcrumbItem.ts
+++ b/packages/twenty-ui/src/primitives/navigation/Breadcrumb/types/BreadcrumbItem.ts
@@ -1,6 +1,13 @@
import { type useRender } from '@base-ui/react/use-render';
+import { type Ref } from 'react';
-export type BreadcrumbItem = Pick<
- useRender.ComponentProps<'a'>,
- 'children' | 'href' | 'render' | 'title'
->;
+export type BreadcrumbItem = Omit<
+ useRender.ComponentProps<
+ 'a',
+ Record<string, never>,
+ useRender.ElementProps<'a'>
+ >,
+ 'ref'
+> & {
+ ref?: Ref<HTMLAnchorElement | HTMLSpanElement>;
+};