Skip to content

The open alternative to Salesforce, designed for AI.

Add multiline ListItem rows (#28572)

Raphaël Bosic898c2490a69
diff --git a/packages/twenty-docs/snippets/ui/generated/components/navigation/dropdown.mdx b/packages/twenty-docs/snippets/ui/generated/components/navigation/dropdown.mdx
index d6868e12f17..e20bef72969 100644
--- a/packages/twenty-docs/snippets/ui/generated/components/navigation/dropdown.mdx
+++ b/packages/twenty-docs/snippets/ui/generated/components/navigation/dropdown.mdx
@@ -196,9 +196,8 @@
Supporting text, placed according to `descriptionPlacement`.
</ParamField>
-<ParamField body="ActionItem.descriptionPlacement" type="&quot;end&quot; | &quot;inline&quot;">
- Where the description renders: inline after the content or at the end of
- the row.
+<ParamField body="ActionItem.descriptionPlacement" type="&quot;below&quot; | &quot;end&quot; | &quot;inline&quot;">
+ Places supporting content inline after the label, at the end, or below it with wrapping. Inline is the default.
</ParamField>
<ParamField body="ActionItem.endIcon" type="ReactNode">
@@ -270,9 +269,8 @@
Supporting text, placed according to `descriptionPlacement`.
</ParamField>
-<ParamField body="OptionItem.descriptionPlacement" type="&quot;end&quot; | &quot;inline&quot;">
- Where the description renders: inline after the content or at the end of
- the row.
+<ParamField body="OptionItem.descriptionPlacement" type="&quot;below&quot; | &quot;end&quot; | &quot;inline&quot;">
+ Places supporting content inline after the label, at the end, or below it with wrapping. Inline is the default.
</ParamField>
<ParamField body="OptionItem.endIcon" type="ReactNode">
@@ -472,9 +470,8 @@
Supporting text, placed according to `descriptionPlacement`.
</ParamField>
-<ParamField body="Back.descriptionPlacement" type="&quot;end&quot; | &quot;inline&quot;">
- Where the description renders: inline after the content or at the end of
- the row.
+<ParamField body="Back.descriptionPlacement" type="&quot;below&quot; | &quot;end&quot; | &quot;inline&quot;">
+ Places supporting content inline after the label, at the end, or below it with wrapping. Inline is the default.
</ParamField>
<ParamField body="Back.endIcon" type="ReactNode">
@@ -564,9 +561,8 @@
Supporting text, placed according to `descriptionPlacement`.
</ParamField>
-<ParamField body="SubmenuTrigger.descriptionPlacement" type="&quot;end&quot; | &quot;inline&quot;">
- Where the description renders: inline after the content or at the end of
- the row.
+<ParamField body="SubmenuTrigger.descriptionPlacement" type="&quot;below&quot; | &quot;end&quot; | &quot;inline&quot;">
+ Places supporting content inline after the label, at the end, or below it with wrapping. Inline is the default.
</ParamField>
<ParamField body="SubmenuTrigger.endIcon" type="ReactNode">
diff --git a/packages/twenty-docs/snippets/ui/generated/components/navigation/list-item-button.mdx b/packages/twenty-docs/snippets/ui/generated/components/navigation/list-item-button.mdx
index 5de43bd3394..6235e9adb7e 100644
--- a/packages/twenty-docs/snippets/ui/generated/components/navigation/list-item-button.mdx
+++ b/packages/twenty-docs/snippets/ui/generated/components/navigation/list-item-button.mdx
@@ -11,6 +11,10 @@
* npx nx generate:ui twenty-docs
*/}
+<ParamField body="active" type="boolean">
+ Marks the open or current item independently of selection and focus. The caller supplies accessible state.
+</ParamField>
+
<ParamField body="color" type="&quot;danger&quot; | &quot;neutral&quot;">
Color of the text and icons. `danger` marks a destructive action.
</ParamField>
@@ -19,9 +23,8 @@
Supporting text, placed according to `descriptionPlacement`.
</ParamField>
-<ParamField body="descriptionPlacement" type="&quot;end&quot; | &quot;inline&quot;">
- Where the description renders: inline after the content or at the end of
- the row.
+<ParamField body="descriptionPlacement" type="&quot;below&quot; | &quot;end&quot; | &quot;inline&quot;">
+ Places supporting content inline after the label, at the end, or below it with wrapping. Inline is the default.
</ParamField>
<ParamField body="disabled" type="boolean" default="false">
@@ -57,6 +60,10 @@
Applies selected styling and a decorative indicator. The caller supplies selection state and accessible semantics.
</ParamField>
+<ParamField body="selectionAppearance" type="&quot;accent&quot; | &quot;default&quot;">
+ Selection styling independent of description placement. `default` preserves indicator-based styling; `accent` fills selected rows with the accent background.
+</ParamField>
+
<ParamField body="shortcut" type="ShortcutDefinition">
Displays decorative shortcut hints. The caller registers the shortcuts.
</ParamField>
diff --git a/packages/twenty-docs/snippets/ui/generated/input/autocomplete.mdx b/packages/twenty-docs/snippets/ui/generated/input/autocomplete.mdx
index 81a5411397e..c99a8f2c990 100644
--- a/packages/twenty-docs/snippets/ui/generated/input/autocomplete.mdx
+++ b/packages/twenty-docs/snippets/ui/generated/input/autocomplete.mdx
@@ -628,8 +628,7 @@
</ParamField>
<ParamField body="Item.descriptionPlacement" type="&quot;end&quot; | &quot;inline&quot;" default="inline">
- Where the description renders: inline after the content or at the end of
- the row.
+ Where the description renders: inline after the content or at the end of the row.
</ParamField>
<ParamField body="Item.disabled" type="boolean" default="false">
diff --git a/packages/twenty-docs/snippets/ui/generated/navigation/list-item.mdx b/packages/twenty-docs/snippets/ui/generated/navigation/list-item.mdx
index a07cd8dc687..29d051c60e2 100644
--- a/packages/twenty-docs/snippets/ui/generated/navigation/list-item.mdx
+++ b/packages/twenty-docs/snippets/ui/generated/navigation/list-item.mdx
@@ -19,6 +19,10 @@
When trailing actions are visible: on hover and focus, or always.
</ParamField>
+<ParamField body="active" type="boolean" default="false">
+ Marks the open or current item independently of selection and focus. Does not add accessible state or activate the item.
+</ParamField>
+
<ParamField body="color" type="&quot;danger&quot; | &quot;neutral&quot;" default="neutral">
Color of the text and icons. `danger` marks a destructive action.
</ParamField>
@@ -27,9 +31,8 @@
Supporting text, placed according to `descriptionPlacement`.
</ParamField>
-<ParamField body="descriptionPlacement" type="&quot;end&quot; | &quot;inline&quot;" default="inline">
- Where the description renders: inline after the content or at the end of
- the row.
+<ParamField body="descriptionPlacement" type="&quot;below&quot; | &quot;end&quot; | &quot;inline&quot;" default="inline">
+ Places supporting content inline after the label, at the end, or below it with wrapping. Inline is the default.
</ParamField>
<ParamField body="disabled" type="boolean" default="false">
@@ -65,6 +68,10 @@
Applies selected styling and the configured decorative indicator. Selection state and accessible semantics belong to the owner.
</ParamField>
+<ParamField body="selectionAppearance" type="&quot;accent&quot; | &quot;default&quot;" default="default">
+ Selection styling independent of description placement. `default` preserves indicator-based styling; `accent` fills selected rows with the accent background.
+</ParamField>
+
<ParamField body="shortcut" type="ShortcutDefinition">
Keyboard shortcut keys displayed at the end of the row. Registering the
shortcut is up to the application.
diff --git a/packages/twenty-docs/ui/components/navigation/list-item-button.mdx b/packages/twenty-docs/ui/components/navigation/list-item-button.mdx
index 48014a894b3..edbe4605c76 100644
--- a/packages/twenty-docs/ui/components/navigation/list-item-button.mdx
+++ b/packages/twenty-docs/ui/components/navigation/list-item-button.mdx
@@ -73,7 +73,7 @@ Set `focusableWhenDisabled` to keep a disabled button focusable. It uses `aria-d
## Selection and visual slots
-Your application owns selection. Pair `selected` with the appropriate accessible state, such as `aria-pressed` for a toggle button. `focused` highlights the row without moving DOM focus. Indicators and shortcut hints are decorative; your application registers shortcuts and handles navigation.
+Your application owns the independent `active`, `selected`, and `focused` states. Use `active` for the open or current row. Pair `selected` with the appropriate accessible state, such as `aria-pressed` for a toggle button. `focused` highlights the row without moving DOM focus. Indicators and shortcut hints are decorative; your application registers shortcuts and handles navigation.
```tsx
import { useState } from 'react';
@@ -103,9 +103,43 @@ export const ShowArchivedToggle = () => {
Use `startIcon`, `endIcon`, `description`, and `descriptionPlacement` for supporting content. `color="danger"` marks a destructive action. `shortcutJoinLabel` controls the text between sequential shortcuts, and `hasSubmenu` displays a submenu indicator.
+## Multiline supporting content
+
+Set `descriptionPlacement="below"` to wrap supporting text beneath the label. The label retains its truncation behavior. Pass [Text](/ui/primitives/typography/text) with `truncate` or `lineClamp` as `description` when you need a shorter preview. The `inline` and `end` placements keep their existing appearance.
+
+```tsx
+import { ListItemButton } from 'twenty-ui/components/navigation';
+import { Avatar } from 'twenty-ui/primitives/data-display';
+
+type PlanningActionProps = {
+ active?: boolean;
+ disabled?: boolean;
+ onOpen: () => void;
+};
+
+export const PlanningAction = ({
+ active = false,
+ disabled = false,
+ onOpen,
+}: PlanningActionProps) => (
+ <ListItemButton
+ active={active}
+ disabled={disabled}
+ descriptionPlacement="below"
+ description="Review the proposed timeline and confirm the next steps with the team."
+ startIcon={<Avatar name="Alex Morgan" size="md" imageProps={{ alt: '' }} />}
+ onClick={onOpen}
+ >
+ Quarterly planning
+ </ListItemButton>
+);
+```
+
+`active` applies the current-row background. Set `selectionAppearance="accent"` for an accent fill on selected rows with any description placement; the default preserves the existing indicator-based selection styling. `focused` applies the shared highlighted background; the focus-visible outline follows actual keyboard focus. These props do not add accessible state or move focus. Native button activation and disabled behavior remain unchanged.
+
## Independent controls
-Keep independent buttons beside `ListItemButton` so each retains its own focus and activation. The component has no `actions` slot. Use a passive `ListItem` with `actions` when the row itself does not act.
+Keep independent buttons and checkboxes beside `ListItemButton` so each retains its own focus and activation. Do not nest them in its content or icon slots. The component has no `actions` slot. Use a `ListItem` with its default `div` root for [a row with independent controls](/ui/primitives/navigation/list-item#independent-controls), and supply disabled behavior and event propagation on each control.
```tsx
import { ListItemButton } from 'twenty-ui/components/navigation';
diff --git a/packages/twenty-docs/ui/primitives/navigation/list-item.mdx b/packages/twenty-docs/ui/primitives/navigation/list-item.mdx
index f97bf541385..5b91c333d66 100644
--- a/packages/twenty-docs/ui/primitives/navigation/list-item.mdx
+++ b/packages/twenty-docs/ui/primitives/navigation/list-item.mdx
@@ -39,16 +39,109 @@ ListItem
└── endIcon
```
-| Slot | Requirement | Purpose |
-| ------------------------------------- | -------------------------------- | ------------------------------------------------------------------------------- |
-| `children` | Required for a visible row label | Supplies the main text. |
-| `startIcon`, `endIcon` | Optional | Add supporting icons at either end of the row content. |
-| `description` | Optional | Adds supporting text inline or at the end, according to `descriptionPlacement`. |
-| `actions` | Optional | Adds trailing content, such as a separately focusable action. |
-| `indicator`, `shortcut`, `hasSubmenu` | Optional | Configure built-in selection marks, shortcut hints, and the submenu indicator. |
+| Slot | Requirement | Purpose |
+| ------------------------------------- | -------------------------------- | ------------------------------------------------------------------------------ |
+| `children` | Required for a visible row label | Supplies the main text. |
+| `startIcon`, `endIcon` | Optional | Add icons, avatars, metadata, or independent controls at either end. |
+| `description` | Optional | Adds supporting content inline, below the label, or at the end. |
+| `actions` | Optional | Adds trailing content, such as a separately focusable action. |
+| `indicator`, `shortcut`, `hasSubmenu` | Optional | Configure built-in selection marks, shortcut hints, and the submenu indicator. |
The row supplies layout. `render` accepts an element or a callback that receives native props and visual state. Spread those props onto the actual root when using a callback. Native attributes, event handlers, `className`, `style`, and `ref` reach that root. For a row with independent action buttons, keep the row itself non-interactive so those buttons remain separate controls.
+## Multiline rows
+
+Set `descriptionPlacement="below"` to place supporting content beneath the label. The title keeps its existing truncation behavior, and supporting content wraps with the available width. The default `inline` placement and the `end` placement retain their existing appearance.
+
+<StoryEmbed
+ storyId="ui-navigation-listitem-multiline--display"
+ title="Multiline ListItem example"
+ height={150}
+/>
+
+```tsx
+import { Avatar } from 'twenty-ui/primitives/data-display';
+import { ListItem } from 'twenty-ui/primitives/navigation';
+import { Text } from 'twenty-ui/primitives/typography';
+
+export const PlanningRow = () => (
+ <ListItem
+ descriptionPlacement="below"
+ startIcon={<Avatar name="Alex Morgan" size="md" imageProps={{ alt: '' }} />}
+ description="Review the proposed timeline and confirm the next steps with the team."
+ endIcon={
+ <Text render={<span />} size="sm" color="secondary">
+ 09:48
+ </Text>
+ }
+ >
+ Quarterly planning
+ </ListItem>
+);
+```
+
+For shorter previews, pass a [Text](/ui/primitives/typography/text) component with `truncate` or `lineClamp` as `description`. Custom content controls its own layout and accessible labels.
+
+### Independent visual states
+
+All visual state belongs to the caller. `active` identifies the open or current row without selecting it. `selected` represents selection, and `focused` represents a keyboard navigation highlight without moving DOM focus. `active` applies the current-row background. Set `selectionAppearance="accent"` for an accent fill on selected rows, independently of description placement. The default appearance preserves the existing indicator-based selection styling. `focused` applies the shared highlighted background, including when an owner uses it for pointer highlighting. The focus-visible outline follows actual keyboard focus on the root or its controls.
+
+These props do not add accessible states. Supply `aria-current`, `aria-selected`, or a control's `checked` state on the appropriate semantic owner. Actual keyboard focus also retains the native focus-visible outline.
+
+### Independent controls
+
+Keep the default `div` root when a row contains a real checkbox or independent action buttons. Use `startIcon` for the checkbox and `actions` for buttons. The decorative `indicator` is unnecessary when a real checkbox already displays selection.
+
+```tsx
+import { useState } from 'react';
+import { Button, Checkbox } from 'twenty-ui/primitives/input';
+import { ListItem } from 'twenty-ui/primitives/navigation';
+
+type SelectablePlanningRowProps = {
+ active?: boolean;
+ disabled?: boolean;
+ onOpen: () => void;
+};
+
+export const SelectablePlanningRow = ({
+ active = false,
+ disabled = false,
+ onOpen,
+}: SelectablePlanningRowProps) => {
+ const [selected, setSelected] = useState(false);
+
+ return (
+ <ListItem
+ active={active}
+ selected={selected}
+ selectionAppearance="accent"
+ disabled={disabled}
+ descriptionPlacement="below"
+ description="Review the proposed timeline and confirm the next steps with the team."
+ startIcon={
+ <Checkbox
+ aria-label="Select quarterly planning"
+ checked={selected}
+ onCheckedChange={setSelected}
+ disabled={disabled}
+ />
+ }
+ actions={
+ <Button variant="ghost" size="sm" onClick={onOpen} disabled={disabled}>
+ Open
+ </Button>
+ }
+ >
+ Quarterly planning
+ </ListItem>
+ );
+};
+```
+
+Selection and opening are separate interactions. The application owns event propagation and any row activation or keyboard policy. `ListItem.disabled` changes appearance only; pass `disabled` to each real control to prevent its activation.
+
+The existing action visibility behavior applies to multiline rows: `actionsVisibility="hover"` reveals actions on hover or focus within the row and keeps them visible on touch devices. Set it to `always` for persistent actions, including while a caller-owned popup is open. At row widths of 480px or less, multiline actions move to their own line and wrap as needed.
+
## Action row
Use [ListItemButton](/ui/components/navigation/list-item-button) to pair row styling with native button interaction. Pass `disabled` once to control both appearance and activation.
@@ -196,7 +289,7 @@ export const ShowArchivedToggle = () => {
};
```
-`selected`, `focused`, and `disabled` control row styling. They do not register actions, move DOM focus, add accessible roles or states, or suppress events. The `check` and `checkbox` indicators are decorative; use a real [Checkbox](/ui/primitives/input/checkbox) for a form control. Set `aria-pressed`, `aria-selected`, or other state semantics on the owner that needs them.
+`active`, `selected`, `focused`, and `disabled` independently control row styling. They do not register actions, move DOM focus, add accessible roles or states, or suppress events. The `check` and `checkbox` indicators are decorative; use a real [Checkbox](/ui/primitives/input/checkbox) for a form control. Set `aria-pressed`, `aria-selected`, or other state semantics on the owner that needs them.
## Picker rows
@@ -291,7 +384,7 @@ The checkbox indicator is not a form control and does not submit a value. Use [C
## Slots
-Use `startIcon` and `endIcon` for icons, `description` for supporting text, `actions` for trailing content, and `hasSubmenu` for a submenu indicator. `descriptionPlacement` accepts `inline` or `end`. `color="danger"` styles a destructive action. Avoid nesting interactive controls inside a row rendered as a button.
+Use `startIcon` and `endIcon` for icons or caller-owned content, `description` for supporting text, `actions` for trailing content, and `hasSubmenu` for a submenu indicator. `descriptionPlacement` accepts `inline`, `end`, or `below`. `color="danger"` styles a destructive action. Avoid nesting interactive controls inside a row rendered as a button.
```tsx
import { Button } from 'twenty-ui/primitives/input';
diff --git a/packages/twenty-ui/docs/components.ts b/packages/twenty-ui/docs/components.ts
index 4aee198cfa4..4fbafa97ad5 100644
--- a/packages/twenty-ui/docs/components.ts
+++ b/packages/twenty-ui/docs/components.ts
@@ -499,6 +499,10 @@ export const DOCUMENTED_COMPONENTS = [
},
},
partPropDescriptions: {
+ Item: {
+ descriptionPlacement:
+ 'Where the description renders: inline after the content or at the end of the row.',
+ },
Root: {
items:
'Flat items or groups with an items array. Preserves the upstream item type; nullish entries are not supported.',
@@ -568,6 +572,12 @@ export const DOCUMENTED_COMPONENTS = [
slug: 'navigation/list-item',
propDescriptions: {
ref: 'Ref to the actual DOM root, including a composed native button or link.',
+ selectionAppearance:
+ 'Selection styling independent of description placement. `default` preserves indicator-based styling; `accent` fills selected rows with the accent background.',
+ active:
+ 'Marks the open or current item independently of selection and focus. Does not add accessible state or activate the item.',
+ descriptionPlacement:
+ 'Places supporting content inline after the label, at the end, or below it with wrapping. Inline is the default.',
selected:
'Applies selected styling and the configured decorative indicator. Selection state and accessible semantics belong to the owner.',
focused:
@@ -884,6 +894,12 @@ export const DOCUMENTED_COMPONENTS = [
disabled: 'Disables activation and applies the matching row appearance.',
focusableWhenDisabled:
'Keeps a disabled button focusable with aria-disabled while preventing activation.',
+ selectionAppearance:
+ 'Selection styling independent of description placement. `default` preserves indicator-based styling; `accent` fills selected rows with the accent background.',
+ active:
+ 'Marks the open or current item independently of selection and focus. The caller supplies accessible state.',
+ descriptionPlacement:
+ 'Places supporting content inline after the label, at the end, or below it with wrapping. Inline is the default.',
selected:
'Applies selected styling and a decorative indicator. The caller supplies selection state and accessible semantics.',
focused: 'Highlights the row without moving DOM focus.',
diff --git a/packages/twenty-ui/docs/dropdownPartPropDescriptions.ts b/packages/twenty-ui/docs/dropdownPartPropDescriptions.ts
index 7bc2a83110a..bd3c5f29f16 100644
--- a/packages/twenty-ui/docs/dropdownPartPropDescriptions.ts
+++ b/packages/twenty-ui/docs/dropdownPartPropDescriptions.ts
@@ -28,6 +28,8 @@ const DROPDOWN_ROOT_PROP_DESCRIPTIONS = {
} satisfies Partial<Record<keyof DropdownRootProps, string>>;
const DROPDOWN_ITEM_PROP_DESCRIPTIONS = {
+ descriptionPlacement:
+ 'Places supporting content inline after the label, at the end, or below it with wrapping. Inline is the default.',
actions:
'Trailing controls rendered beside the primary row control. Only supported in picker and panel pages, since a menu may only contain menu items. Secondary actions activate independently of the row.',
actionsVisibility:
diff --git a/packages/twenty-ui/generated/components.docs.json b/packages/twenty-ui/generated/components.docs.json
index a2d4d323daa..8df2f497288 100644
--- a/packages/twenty-ui/generated/components.docs.json
+++ b/packages/twenty-ui/generated/components.docs.json
@@ -5991,7 +5991,7 @@
"type": "\"end\" | \"inline\"",
"required": false,
"defaultValue": "inline",
- "description": "Where the description renders: inline after the content or at the end of\nthe row."
+ "description": "Where the description renders: inline after the content or at the end of the row."
},
{
"name": "disabled",
@@ -7804,6 +7804,13 @@
"defaultValue": "hover",
"description": "When trailing actions are visible: on hover and focus, or always."
},
+ {
+ "name": "active",
+ "type": "boolean",
+ "required": false,
+ "defaultValue": "false",
+ "description": "Marks the open or current item independently of selection and focus. Does not add accessible state or activate the item."
+ },
{
"name": "color",
"type": "\"danger\" | \"neutral\"",
@@ -7820,10 +7827,10 @@
},
{
"name": "descriptionPlacement",
- "type": "\"end\" | \"inline\"",
+ "type": "\"below\" | \"end\" | \"inline\"",
"required": false,
"defaultValue": "inline",
- "description": "Where the description renders: inline after the content or at the end of\nthe row."
+ "description": "Places supporting content inline after the label, at the end, or below it with wrapping. Inline is the default."
},
{
"name": "disabled",
@@ -7881,6 +7888,13 @@
"defaultValue": "false",
"description": "Applies selected styling and the configured decorative indicator. Selection state and accessible semantics belong to the owner."
},
+ {
+ "name": "selectionAppearance",
+ "type": "\"accent\" | \"default\"",
+ "required": false,
+ "defaultValue": "default",
+ "description": "Selection styling independent of description placement. `default` preserves indicator-based styling; `accent` fills selected rows with the accent background."
+ },
{
"name": "shortcut",
"type": "ShortcutDefinition",
@@ -12334,10 +12348,10 @@
},
{
"name": "descriptionPlacement",
- "type": "\"end\" | \"inline\"",
+ "type": "\"below\" | \"end\" | \"inline\"",
"required": false,
"defaultValue": null,
- "description": "Where the description renders: inline after the content or at the end of\nthe row."
+ "description": "Places supporting content inline after the label, at the end, or below it with wrapping. Inline is the default."
},
{
"name": "endIcon",
@@ -12458,10 +12472,10 @@
},
{
"name": "descriptionPlacement",
- "type": "\"end\" | \"inline\"",
+ "type": "\"below\" | \"end\" | \"inline\"",
"required": false,
"defaultValue": null,
- "description": "Where the description renders: inline after the content or at the end of\nthe row."
+ "description": "Places supporting content inline after the label, at the end, or below it with wrapping. Inline is the default."
},
{
"name": "endIcon",
@@ -12780,10 +12794,10 @@
},
{
"name": "descriptionPlacement",
- "type": "\"end\" | \"inline\"",
+ "type": "\"below\" | \"end\" | \"inline\"",
"required": false,
"defaultValue": null,
- "description": "Where the description renders: inline after the content or at the end of\nthe row."
+ "description": "Places supporting content inline after the label, at the end, or below it with wrapping. Inline is the default."
},
{
"name": "endIcon",
@@ -12937,10 +12951,10 @@
},
{
"name": "descriptionPlacement",
- "type": "\"end\" | \"inline\"",
+ "type": "\"below\" | \"end\" | \"inline\"",
"required": false,
"defaultValue": null,
- "description": "Where the description renders: inline after the content or at the end of\nthe row."
+ "description": "Places supporting content inline after the label, at the end, or below it with wrapping. Inline is the default."
},
{
"name": "endIcon",
@@ -13570,6 +13584,13 @@
"entryPoint": "twenty-ui/components/navigation",
"slug": "components/navigation/list-item-button",
"props": [
+ {
+ "name": "active",
+ "type": "boolean",
+ "required": false,
+ "defaultValue": null,
+ "description": "Marks the open or current item independently of selection and focus. The caller supplies accessible state."
+ },
{
"name": "color",
"type": "\"danger\" | \"neutral\"",
@@ -13586,10 +13607,10 @@
},
{
"name": "descriptionPlacement",
- "type": "\"end\" | \"inline\"",
+ "type": "\"below\" | \"end\" | \"inline\"",
"required": false,
"defaultValue": null,
- "description": "Where the description renders: inline after the content or at the end of\nthe row."
+ "description": "Places supporting content inline after the label, at the end, or below it with wrapping. Inline is the default."
},
{
"name": "disabled",
@@ -13647,6 +13668,13 @@
"defaultValue": null,
"description": "Applies selected styling and a decorative indicator. The caller supplies selection state and accessible semantics."
},
+ {
+ "name": "selectionAppearance",
+ "type": "\"accent\" | \"default\"",
+ "required": false,
+ "defaultValue": null,
+ "description": "Selection styling independent of description placement. `default` preserves indicator-based styling; `accent` fills selected rows with the accent background."
+ },
{
"name": "shortcut",
"type": "ShortcutDefinition",
diff --git a/packages/twenty-ui/src/components/navigation/ListItemButton/ListItemButton.tsx b/packages/twenty-ui/src/components/navigation/ListItemButton/ListItemButton.tsx
index a2852755441..134689c6b76 100644
--- a/packages/twenty-ui/src/components/navigation/ListItemButton/ListItemButton.tsx
+++ b/packages/twenty-ui/src/components/navigation/ListItemButton/ListItemButton.tsx
@@ -7,6 +7,8 @@ import { type ListItemButtonProps } from './types/ListItemButtonProps';
export const ListItemButton = ({
color,
selected,
+ selectionAppearance,
+ active,
focused,
indicator,
startIcon,
@@ -24,6 +26,8 @@ export const ListItemButton = ({
<ListItem
color={color}
selected={selected}
+ selectionAppearance={selectionAppearance}
+ active={active}
focused={focused}
indicator={indicator}
startIcon={startIcon}
diff --git a/packages/twenty-ui/src/components/navigation/ListItemButton/__stories__/ListItemButton.stories.tsx b/packages/twenty-ui/src/components/navigation/ListItemButton/__stories__/ListItemButton.stories.tsx
index a8b60b34020..d5311633852 100644
--- a/packages/twenty-ui/src/components/navigation/ListItemButton/__stories__/ListItemButton.stories.tsx
+++ b/packages/twenty-ui/src/components/navigation/ListItemButton/__stories__/ListItemButton.stories.tsx
@@ -59,3 +59,12 @@ export const IndependentAction: Story = {
</div>
),
};
+
+export const Multiline: Story = {
+ args: {
+ children: 'Duplicate document',
+ description: 'Create a copy with the same settings.',
+ descriptionPlacement: 'below',
+ active: true,
+ },
+};
diff --git a/packages/twenty-ui/src/components/navigation/ListItemButton/__tests__/ListItemButton.test.tsx b/packages/twenty-ui/src/components/navigation/ListItemButton/__tests__/ListItemButton.test.tsx
index 7b12b7fa9ae..01d18bdc484 100644
--- a/packages/twenty-ui/src/components/navigation/ListItemButton/__tests__/ListItemButton.test.tsx
+++ b/packages/twenty-ui/src/components/navigation/ListItemButton/__tests__/ListItemButton.test.tsx
@@ -5,6 +5,33 @@ import { createRef } from 'react';
import { ListItemButton } from '../ListItemButton';
describe('ListItemButton', () => {
+ it('forwards multiline visual state without leaking props to the native button', () => {
+ render(
+ <ListItemButton
+ active
+ selected
+ selectionAppearance="accent"
+ focused
+ descriptionPlacement="below"
+ description="Supporting content"
+ >
+ Document
+ </ListItemButton>,
+ );
+
+ const button = screen.getByRole('button');
+
+ expect(button).toHaveAttribute('data-active');
+ expect(button).toHaveAttribute('data-selected');
+ expect(button).toHaveAttribute('data-selection-appearance', 'accent');
+ expect(button).not.toHaveAttribute('selectionAppearance');
+ expect(button).toHaveAttribute('data-highlighted');
+ expect(button).toHaveAttribute('data-description-placement', 'below');
+ expect(button).not.toHaveAttribute('active');
+ expect(button).not.toHaveAttribute('aria-pressed');
+ expect(button).toHaveTextContent('Supporting content');
+ });
+
it('activates with pointer, Enter and Space without submitting its form', async () => {
const user = userEvent.setup();
const onClick = vi.fn();
diff --git a/packages/twenty-ui/src/components/navigation/ListItemButton/types/ListItemButtonProps.ts b/packages/twenty-ui/src/components/navigation/ListItemButton/types/ListItemButtonProps.ts
index 4801ea3c9cb..3028f53596c 100644
--- a/packages/twenty-ui/src/components/navigation/ListItemButton/types/ListItemButtonProps.ts
+++ b/packages/twenty-ui/src/components/navigation/ListItemButton/types/ListItemButtonProps.ts
@@ -12,6 +12,8 @@ export type ListItemButtonProps = Omit<
ListItemProps,
| 'color'
| 'selected'
+ | 'selectionAppearance'
+ | 'active'
| 'focused'
| 'indicator'
| 'startIcon'
diff --git a/packages/twenty-ui/src/primitives/input/Autocomplete/__tests__/Autocomplete.test.tsx b/packages/twenty-ui/src/primitives/input/Autocomplete/__tests__/Autocomplete.test.tsx
index c661c482185..c636f261325 100644
--- a/packages/twenty-ui/src/primitives/input/Autocomplete/__tests__/Autocomplete.test.tsx
+++ b/packages/twenty-ui/src/primitives/input/Autocomplete/__tests__/Autocomplete.test.tsx
@@ -8,6 +8,7 @@ import listItemStyles from '@ui/primitives/navigation/ListItem/ListItem.module.s
import { Autocomplete } from '@ui/primitives/input';
import styles from '../Autocomplete.module.scss';
import { type AutocompleteInputProps } from '../types/AutocompleteInputProps';
+import { type AutocompleteItemProps } from '../types/AutocompleteItemProps';
const RootWrapper = ({ children }: { children: ReactNode }) => (
<Autocomplete.Root>{children}</Autocomplete.Root>
@@ -143,3 +144,9 @@ it('accepts size only on an Autocomplete.Input without render', () => {
size: 'sm';
}>().not.toExtend<AutocompleteInputProps>();
});
+
+it('keeps autocomplete descriptions limited to their supported placements', () => {
+ expectTypeOf<AutocompleteItemProps['descriptionPlacement']>().toEqualTypeOf<
+ 'inline' | 'end' | undefined
+ >();
+});
diff --git a/packages/twenty-ui/src/primitives/input/Autocomplete/types/AutocompleteItemProps.ts b/packages/twenty-ui/src/primitives/input/Autocomplete/types/AutocompleteItemProps.ts
index 66f309efe4b..1ff6081bbef 100644
--- a/packages/twenty-ui/src/primitives/input/Autocomplete/types/AutocompleteItemProps.ts
+++ b/packages/twenty-ui/src/primitives/input/Autocomplete/types/AutocompleteItemProps.ts
@@ -3,7 +3,9 @@ import { type Autocomplete as AutocompletePrimitive } from '@base-ui/react/autoc
import { type ListItemProps } from '@ui/primitives/navigation/ListItem/types/ListItemProps';
export type AutocompleteItemProps = AutocompletePrimitive.Item.Props &
- Pick<
- ListItemProps,
- 'startIcon' | 'endIcon' | 'description' | 'descriptionPlacement'
- >;
+ Pick<ListItemProps, 'startIcon' | 'endIcon' | 'description'> & {
+ descriptionPlacement?: Exclude<
+ ListItemProps['descriptionPlacement'],
+ 'below'
+ >;
+ };
diff --git a/packages/twenty-ui/src/primitives/navigation/ListItem/ListItem.module.scss b/packages/twenty-ui/src/primitives/navigation/ListItem/ListItem.module.scss
index 6131e503765..287e5e65b93 100644
--- a/packages/twenty-ui/src/primitives/navigation/ListItem/ListItem.module.scss
+++ b/packages/twenty-ui/src/primitives/navigation/ListItem/ListItem.module.scss
@@ -35,11 +35,17 @@
}
}
+ &[data-active],
&[data-highlighted],
&[data-selected][data-indicator='none'] {
--tw-list-item-background: var(--t-background-transparent-light);
}
+ &[data-selected][data-selection-appearance='accent'] {
+ --tw-list-item-background: var(--t-accent-tertiary);
+ --tw-list-item-hover-background: var(--t-accent-tertiary);
+ }
+
&[data-color='danger'] {
--tw-list-item-color: var(--t-font-color-danger);
--tw-list-item-hover-background: var(--t-background-transparent-danger);
@@ -158,3 +164,39 @@
transform: scaleX(-1);
}
}
+
+.root[data-description-placement='below'] {
+ align-items: flex-start;
+ container-type: inline-size;
+ flex-wrap: wrap;
+ padding-block: var(--t-spacing-2);
+
+ .label {
+ align-items: stretch;
+ flex-direction: column;
+ overflow: visible;
+ }
+
+ .text {
+ min-inline-size: 0;
+ overflow: visible;
+ }
+
+ .description {
+ overflow: visible;
+ overflow-wrap: anywhere;
+ white-space: normal;
+ }
+
+ .actions {
+ flex-wrap: wrap;
+ max-inline-size: 50%;
+ }
+}
+
+@container (max-width: 480px) {
+ .root[data-description-placement='below'] > .actions {
+ flex-basis: 100%;
+ max-inline-size: 100%;
+ }
+}
diff --git a/packages/twenty-ui/src/primitives/navigation/ListItem/ListItem.tsx b/packages/twenty-ui/src/primitives/navigation/ListItem/ListItem.tsx
index f5353e6b994..ba6954f67c6 100644
--- a/packages/twenty-ui/src/primitives/navigation/ListItem/ListItem.tsx
+++ b/packages/twenty-ui/src/primitives/navigation/ListItem/ListItem.tsx
@@ -15,6 +15,8 @@ import { type ListItemProps } from './types/ListItemProps';
export const ListItem = ({
color = 'neutral',
selected = false,
+ selectionAppearance = 'default',
+ active = false,
focused = false,
disabled = false,
indicator = 'none',
@@ -34,14 +36,26 @@ export const ListItem = ({
...props
}: ListItemProps) => {
const hasDescription = isRenderableSlot(description);
+ const actionSlot = isRenderableSlot(actions) ? (
+ <span className={styles.actions}>{actions}</span>
+ ) : null;
return useRender({
render,
ref,
- state: { color, indicator, selected, highlighted: focused, disabled },
+ state: {
+ color,
+ indicator,
+ selected,
+ active,
+ highlighted: focused,
+ disabled,
+ },
props: {
...props,
'data-actions-visibility': actionsVisibility,
+ 'data-description-placement': descriptionPlacement,
+ 'data-selection-appearance': selectionAppearance,
className: clsx(styles.root, className),
children: (
<>
@@ -59,9 +73,12 @@ export const ListItem = ({
children
)}
</span>
- {hasDescription && descriptionPlacement === 'inline' && (
+ {hasDescription && descriptionPlacement !== 'end' && (
<span
- className={clsx(styles.description, styles.inlineDescription)}
+ className={clsx(
+ styles.description,
+ descriptionPlacement === 'inline' && styles.inlineDescription,
+ )}
>
{description}
</span>
@@ -72,9 +89,7 @@ export const ListItem = ({
{description}
</span>
)}
- {isRenderableSlot(actions) && (
- <span className={styles.actions}>{actions}</span>
- )}
+ {descriptionPlacement !== 'below' && actionSlot}
{isDefined(shortcut) && (
<Shortcut
className={styles.hotkeys}
@@ -91,6 +106,7 @@ export const ListItem = ({
{hasSubmenu && (
<IconChevronRight className={styles.submenuIcon} aria-hidden />
)}
+ {descriptionPlacement === 'below' && actionSlot}
</>
),
},
diff --git a/packages/twenty-ui/src/primitives/navigation/ListItem/__stories__/ListItemMultiline.stories.tsx b/packages/twenty-ui/src/primitives/navigation/ListItem/__stories__/ListItemMultiline.stories.tsx
new file mode 100644
index 00000000000..ca93a08edd9
--- /dev/null
+++ b/packages/twenty-ui/src/primitives/navigation/ListItem/__stories__/ListItemMultiline.stories.tsx
@@ -0,0 +1,326 @@
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import { expect, fn, userEvent, waitFor, within } from 'storybook/test';
+
+import { Avatar } from '@ui/primitives/data-display/Avatar/Avatar';
+import { Button } from '@ui/primitives/input/Button/Button';
+import { Text } from '@ui/primitives/typography/Text/Text';
+import {
+ A11Y_DEFER_COLOR_CONTRAST,
+ CatalogDecorator,
+ ComponentDecorator,
+ type CatalogStory,
+} from '@ui/testing';
+
+import { ListItem } from '../ListItem';
+import { type ListItemProps } from '../types/ListItemProps';
+import { ListItemMultilineExample } from './ListItemMultilineExample';
+
+const meta: Meta<typeof ListItem> = {
+ title: 'UI/Navigation/ListItem/Multiline',
+ component: ListItem,
+ parameters: { container: { width: 560 } },
+ args: {
+ children: 'Quarterly planning',
+ description:
+ 'Review the proposed timeline and confirm the next steps with the team.',
+ descriptionPlacement: 'below',
+ startIcon: <Avatar name="Alex Morgan" size="md" imageProps={{ alt: '' }} />,
+ endIcon: (
+ <Text render={<span />} size="sm" color="secondary">
+ 09:48
+ </Text>
+ ),
+ },
+};
+
+export default meta;
+type Story = StoryObj<typeof ListItem>;
+
+export const Display: Story = { decorators: [ComponentDecorator] };
+
+export const Narrow: Story = {
+ decorators: [ComponentDecorator],
+ parameters: { container: { width: 240 } },
+ args: {
+ children: 'A quarterly planning document with a long title',
+ description: '[email protected]',
+ actions: (
+ <Button size="sm" variant="ghost">
+ Review document
+ </Button>
+ ),
+ actionsVisibility: 'always',
+ },
+};
+
+export const NarrowControlInteractions: Story = {
+ ...Narrow,
+ tags: ['!autodocs'],
+ args: {
+ ...Narrow.args,
+ endIcon: (
+ <Button size="sm" variant="ghost">
+ Details
+ </Button>
+ ),
+ },
+ play: async ({ canvasElement }) => {
+ const canvas = within(canvasElement);
+ const details = canvas.getByRole('button', { name: 'Details' });
+ const review = canvas.getByRole('button', { name: 'Review document' });
+ const description = canvas.getByText(
+ );
+ const row = details.closest<HTMLElement>('[data-description-placement]');
+
+ await userEvent.tab();
+ await expect(details).toHaveFocus();
+ await userEvent.tab();
+ await expect(review).toHaveFocus();
+ await expect(review.getBoundingClientRect().top).toBeGreaterThanOrEqual(
+ description.getBoundingClientRect().bottom,
+ );
+ await expect(row?.scrollWidth).toBe(row?.clientWidth);
+ },
+};
+
+export const TruncatedDescription: Story = {
+ decorators: [ComponentDecorator],
+ parameters: { container: { width: 240 } },
+ args: {
+ description: (
+ <Text render={<span />} style={{ display: 'block' }} truncate>
+ Review the proposed timeline and confirm the next steps with the team.
+ </Text>
+ ),
+ },
+};
+
+export const IndependentControls: Story = {
+ decorators: [ComponentDecorator],
+ render: () => <ListItemMultilineExample />,
+};
+
+export const IndependentControlInteractions: StoryObj<
+ typeof ListItemMultilineExample
+> = {
+ tags: ['!autodocs'],
+ decorators: [ComponentDecorator],
+ args: { onOpen: fn(), onArchive: fn() },
+ render: (args) => (
+ <ListItemMultilineExample onOpen={args.onOpen} onArchive={args.onArchive} />
+ ),
+ play: async ({ canvasElement, args }) => {
+ const canvas = within(canvasElement);
+ const row = canvas.getByRole('group', { name: 'Planning document' });
+ const checkbox = canvas.getByRole('checkbox', {
+ name: 'Select planning document',
+ });
+ const open = canvas.getByRole('button', { name: 'Quarterly planning' });
+ const archive = canvas.getByRole('button', { name: 'Archive' });
+
+ await userEvent.tab();
+ await expect(checkbox).toHaveFocus();
+ await userEvent.keyboard(' ');
+ await expect(checkbox).toBeChecked();
+ await expect(row).toHaveAttribute('data-selected');
+ await expect(row).not.toHaveAttribute('data-active');
+ await expect(args.onOpen).not.toHaveBeenCalled();
+ await expect(args.onArchive).not.toHaveBeenCalled();
+
+ await userEvent.tab();
+ await expect(open).toHaveFocus();
+ await userEvent.keyboard('{Enter}');
+ await expect(row).toHaveAttribute('data-active');
+ await expect(checkbox).toBeChecked();
+ await expect(args.onOpen).toHaveBeenCalledTimes(1);
+
+ await userEvent.tab();
+ await expect(archive).toHaveFocus();
+ await waitFor(() =>
+ expect(archive.parentElement).toHaveStyle({ opacity: '1' }),
+ );
+ await userEvent.keyboard(' ');
+ await expect(open).toHaveAttribute('aria-pressed', 'true');
+ await expect(args.onArchive).toHaveBeenCalledTimes(1);
+ await expect(args.onOpen).toHaveBeenCalledTimes(1);
+ await expect(checkbox).toBeChecked();
+
+ await userEvent.click(checkbox);
+ await expect(row).not.toHaveAttribute('data-selected');
+ await expect(row).toHaveAttribute('data-active');
+ await expect(checkbox).not.toBeChecked();
+ },
+};
+
+export const HighlightedWithoutKeyboardFocus: Story = {
+ tags: ['!autodocs'],
+ decorators: [ComponentDecorator],
+ args: { focused: true, render: <button type="button" /> },
+ play: async ({ canvasElement }) => {
+ const item = within(canvasElement).getByRole('button');
+
+ await userEvent.hover(item);
+ await expect(item).toHaveAttribute('data-highlighted');
+ await expect(item).not.toHaveFocus();
+ await expect(item).toHaveStyle({ outlineStyle: 'none' });
+
+ await userEvent.tab();
+ await expect(item).toHaveFocus();
+ await expect(item).toHaveStyle({ outlineStyle: 'solid' });
+ },
+};
+
+export const DisabledControls: Story = {
+ decorators: [ComponentDecorator],
+ render: () => <ListItemMultilineExample disabled />,
+};
+
+export const DisabledControlInteractions: Story = {
+ ...DisabledControls,
+ tags: ['!autodocs'],
+ play: async ({ canvasElement }) => {
+ const canvas = within(canvasElement);
+ const checkbox = canvas.getByRole('checkbox');
+ const open = canvas.getByRole('button', { name: 'Quarterly planning' });
+ const archive = canvas.getByRole('button', { name: 'Archive' });
+
+ await expect(checkbox).toHaveAttribute('aria-disabled', 'true');
+ await expect(open).toBeDisabled();
+ await expect(archive).toBeDisabled();
+ await userEvent.click(open);
+ await userEvent.click(checkbox);
+ await expect(open).toHaveAttribute('aria-pressed', 'false');
+ await expect(checkbox).not.toBeChecked();
+ },
+};
+
+type MultilineState =
+ | 'default'
+ | 'active'
+ | 'selected'
+ | 'focused'
+ | 'combined'
+ | 'disabled';
+
+const MULTILINE_STATE_PROPS: Record<MultilineState, Partial<ListItemProps>> = {
+ default: {},
+ active: { active: true },
+ selected: { selected: true },
+ focused: { focused: true },
+ combined: { active: true, selected: true, focused: true },
+ disabled: { disabled: true },
+};
+
+export const VisualRegression: CatalogStory<Story, typeof ListItem> = {
+ tags: ['!autodocs'],
+ decorators: [CatalogDecorator],
+ args: {
+ indicator: 'checkbox',
+ startIcon: undefined,
+ selectionAppearance: 'accent',
+ },
+ parameters: {
+ a11y: A11Y_DEFER_COLOR_CONTRAST,
+ catalog: {
+ dimensions: [
+ { name: '', values: [''], props: () => ({}) },
+ {
+ name: 'state',
+ values: [
+ 'default',
+ 'active',
+ 'selected',
+ 'focused',
+ 'combined',
+ 'disabled',
+ ] satisfies MultilineState[],
+ props: (state: MultilineState) => MULTILINE_STATE_PROPS[state],
+ },
+ ],
+ options: { elementContainer: { style: { width: 320 } } },
+ },
+ },
+};
+
+export const VisualRegressionDark: CatalogStory<Story, typeof ListItem> = {
+ ...VisualRegression,
+ globals: { colorScheme: 'dark' },
+};
+
+export const SelectionAppearance: CatalogStory<Story, typeof ListItem> = {
+ decorators: [CatalogDecorator],
+ args: {
+ selected: true,
+ indicator: 'checkbox',
+ startIcon: undefined,
+ description: 'Team planning',
+ },
+ parameters: {
+ a11y: A11Y_DEFER_COLOR_CONTRAST,
+ catalog: {
+ dimensions: [
+ {
+ name: 'selection appearance',
+ values: ['default', 'accent'] satisfies NonNullable<
+ ListItemProps['selectionAppearance']
+ >[],
+ props: (
+ selectionAppearance: ListItemProps['selectionAppearance'],
+ ) => ({ selectionAppearance }),
+ },
+ {
+ name: 'description placement',
+ values: ['inline', 'end', 'below'] satisfies NonNullable<
+ ListItemProps['descriptionPlacement']
+ >[],
+ props: (
+ descriptionPlacement: ListItemProps['descriptionPlacement'],
+ ) => ({ descriptionPlacement }),
+ },
+ ],
+ options: { elementContainer: { style: { width: 320 } } },
+ },
+ },
+};
+
+export const SelectionAppearanceInteractions: CatalogStory<
+ Story,
+ typeof ListItem
+> = {
+ ...SelectionAppearance,
+ tags: ['!autodocs'],
+ render: (args) => (
+ <ListItem
+ role="group"
+ aria-label={`${args.descriptionPlacement} ${args.selectionAppearance}`}
+ selected
+ selectionAppearance={args.selectionAppearance}
+ descriptionPlacement={args.descriptionPlacement}
+ description="Supporting content"
+ indicator="checkbox"
+ >
+ Quarterly planning
+ </ListItem>
+ ),
+ play: async ({ canvasElement }) => {
+ const canvas = within(canvasElement);
+ const accentBackground = getComputedStyle(
+ canvas.getByRole('group', { name: 'inline accent' }),
+ ).backgroundColor;
+ const defaultBackground = getComputedStyle(
+ canvas.getByRole('group', { name: 'inline default' }),
+ ).backgroundColor;
+
+ await expect(accentBackground).not.toBe(defaultBackground);
+
+ for (const placement of ['inline', 'end', 'below']) {
+ await expect(
+ canvas.getByRole('group', { name: `${placement} accent` }),
+ ).toHaveStyle({ backgroundColor: accentBackground });
+ await expect(
+ canvas.getByRole('group', { name: `${placement} default` }),
+ ).toHaveStyle({ backgroundColor: defaultBackground });
+ }
+ },
+};
diff --git a/packages/twenty-ui/src/primitives/navigation/ListItem/__stories__/ListItemMultilineExample.tsx b/packages/twenty-ui/src/primitives/navigation/ListItem/__stories__/ListItemMultilineExample.tsx
new file mode 100644
index 00000000000..0fe29c7e738
--- /dev/null
+++ b/packages/twenty-ui/src/primitives/navigation/ListItem/__stories__/ListItemMultilineExample.tsx
@@ -0,0 +1,72 @@
+import { useState } from 'react';
+
+import { Button } from '@ui/primitives/input/Button/Button';
+import { Checkbox } from '@ui/primitives/input/Checkbox/Checkbox';
+import { Text } from '@ui/primitives/typography/Text/Text';
+
+import { ListItem } from '../ListItem';
+
+type ListItemMultilineExampleProps = {
+ disabled?: boolean;
+ onOpen?: () => void;
+ onArchive?: () => void;
+};
+
+export const ListItemMultilineExample = ({
+ disabled = false,
+ onOpen,
+ onArchive,
+}: ListItemMultilineExampleProps) => {
+ const [active, setActive] = useState(false);
+ const [selected, setSelected] = useState(false);
+
+ return (
+ <ListItem
+ role="group"
+ aria-label="Planning document"
+ aria-disabled={disabled || undefined}
+ active={active}
+ selected={selected}
+ selectionAppearance="accent"
+ disabled={disabled}
+ descriptionPlacement="below"
+ description="Review the proposed timeline and confirm the next steps with the team."
+ startIcon={
+ <Checkbox
+ aria-label="Select planning document"
+ checked={selected}
+ onCheckedChange={setSelected}
+ disabled={disabled}
+ />
+ }
+ endIcon={
+ <Text render={<span />} size="sm">
+ 09:48
+ </Text>
+ }
+ actions={
+ <Button
+ variant="ghost"
+ size="sm"
+ disabled={disabled}
+ onClick={onArchive}
+ >
+ Archive
+ </Button>
+ }
+ >
+ <Button
+ variant="ghost"
+ size="sm"
+ aria-pressed={active}
+ disabled={disabled}
+ onClick={() => {
+ setActive(!active);
+ onOpen?.();
+ }}
+ >
+ Quarterly planning
+ </Button>
+ </ListItem>
+ );
+};
diff --git a/packages/twenty-ui/src/primitives/navigation/ListItem/__tests__/ListItem.test.tsx b/packages/twenty-ui/src/primitives/navigation/ListItem/__tests__/ListItem.test.tsx
index c2dd85964c0..76ed6f1d610 100644
--- a/packages/twenty-ui/src/primitives/navigation/ListItem/__tests__/ListItem.test.tsx
+++ b/packages/twenty-ui/src/primitives/navigation/ListItem/__tests__/ListItem.test.tsx
@@ -231,3 +231,40 @@ describe('ListItem content', () => {
expect(screen.getByTestId('custom-label')).toBeInTheDocument();
});
});
+
+describe('ListItem multiline contract', () => {
+ it('keeps active, selection, and focus state independent of semantics', () => {
+ const ref = createRef<HTMLDivElement>();
+
+ const { rerender } = render(
+ <ListItem
+ ref={ref}
+ active
+ descriptionPlacement="below"
+ description="Supporting content"
+ >
+ Document
+ </ListItem>,
+ );
+
+ expect(ref.current).toHaveAttribute('data-active');
+ expect(ref.current).not.toHaveAttribute('data-selected');
+ expect(ref.current).not.toHaveAttribute('data-highlighted');
+ expect(ref.current).not.toHaveAttribute('aria-current');
+ expect(ref.current).not.toHaveAttribute('active');
+ expect(ref.current).toHaveAttribute('data-description-placement', 'below');
+ expect(screen.getByText('Supporting content')).toBeInTheDocument();
+
+ rerender(
+ <ListItem ref={ref} selected focused indicator="checkbox">
+ Document
+ </ListItem>,
+ );
+
+ expect(ref.current).not.toHaveAttribute('data-active');
+ expect(ref.current).toHaveAttribute('data-selected');
+ expect(ref.current).toHaveAttribute('data-highlighted');
+ expect(ref.current).toHaveAttribute('data-description-placement', 'inline');
+ expect(screen.queryByRole('checkbox')).not.toBeInTheDocument();
+ });
+});
diff --git a/packages/twenty-ui/src/primitives/navigation/ListItem/types/ListItemDescriptionPlacement.ts b/packages/twenty-ui/src/primitives/navigation/ListItem/types/ListItemDescriptionPlacement.ts
index 4bf7a3e5b21..14d0e5614a2 100644
--- a/packages/twenty-ui/src/primitives/navigation/ListItem/types/ListItemDescriptionPlacement.ts
+++ b/packages/twenty-ui/src/primitives/navigation/ListItem/types/ListItemDescriptionPlacement.ts
@@ -1 +1 @@
-export type ListItemDescriptionPlacement = 'inline' | 'end';
+export type ListItemDescriptionPlacement = 'inline' | 'end' | 'below';
diff --git a/packages/twenty-ui/src/primitives/navigation/ListItem/types/ListItemProps.ts b/packages/twenty-ui/src/primitives/navigation/ListItem/types/ListItemProps.ts
index cefbdef5c68..3989856549d 100644
--- a/packages/twenty-ui/src/primitives/navigation/ListItem/types/ListItemProps.ts
+++ b/packages/twenty-ui/src/primitives/navigation/ListItem/types/ListItemProps.ts
@@ -20,6 +20,8 @@ export type ListItemProps = Omit<
* `indicator` is set.
*/
selected?: boolean;
+ active?: boolean;
+ selectionAppearance?: 'default' | 'accent';
/** Applies the highlighted style, for example to the focused item of a list. */
focused?: boolean;
disabled?: boolean;
diff --git a/packages/twenty-ui/src/primitives/navigation/ListItem/types/ListItemState.ts b/packages/twenty-ui/src/primitives/navigation/ListItem/types/ListItemState.ts
index 726aa01f1a5..38b84189cc9 100644
--- a/packages/twenty-ui/src/primitives/navigation/ListItem/types/ListItemState.ts
+++ b/packages/twenty-ui/src/primitives/navigation/ListItem/types/ListItemState.ts
@@ -5,6 +5,7 @@ export type ListItemState = {
color: ListItemColor;
indicator: ListItemIndicator;
selected: boolean;
+ active: boolean;
highlighted: boolean;
disabled: boolean;
};