snapshot of https://github.com/twentyhq/twenty.git (main, 2026-09-17; blobs > 131072B omitted)

packages/twenty-docs/snippets/ui/generated/surfaces/alert-dialog.mdx

@@ -0,0 +1,244 @@
+{/*
+ * _____                    _
+ *|_   _|_      _____ _ __ | |_ _   _
+ *  | | \ \ /\ / / _ \ '_ \| __| | | | Auto-generated file
+ *  | |  \ V  V /  __/ | | | |_| |_| | DO NOT EDIT - changes will be overwritten
+ *  |_|   \_/\_/ \___|_| |_|\__|\__, | Generated by: npx nx generate:ui twenty-docs
+ *                              |___/
+ *
+ * This file is generated from the documentation data in packages/twenty-ui/generated.
+ * To update it, edit the component prop types or design tokens in twenty-ui and run:
+ *   npx nx generate:ui twenty-docs
+ */}
+
+### AlertDialog.Root
+
+<ParamField body="Root.actionsRef" type="RefObject&lt;DialogRootActions | null&gt;">
+  A ref to imperative actions.
+  - `unmount`: Manually unmounts the alert dialog.
+  Call this after any externally controlled closing animation finishes.
+  - `close`: Closes the alert dialog imperatively when called.
+</ParamField>
+
+<ParamField body="Root.children" type="ReactNode | PayloadChildRenderFunction&lt;Payload&gt;">
+  The content of the dialog.
+  This can be a regular React node or a render function that receives the `payload` of the active trigger.
+</ParamField>
+
+<ParamField body="Root.defaultOpen" type="boolean" default="false">
+  Whether the dialog is initially open.
+
+  To render a controlled dialog, use the `open` prop instead.
+</ParamField>
+
+<ParamField body="Root.defaultTriggerId" type="string | null">
+  ID of the trigger that the dialog is associated with.
+  This is useful in conjunction with the `defaultOpen` prop to create an initially open dialog.
+</ParamField>
+
+<ParamField body="Root.handle" type="AlertDialogHandle&lt;Payload&gt;">
+  A handle to associate the alert dialog with a trigger.
+  If specified, allows external triggers to control the alert dialog's open state.
+  Can be created with the AlertDialog.createHandle() method.
+</ParamField>
+
+<ParamField body="Root.onOpenChange" type="((open: boolean, eventDetails: AlertDialogRootChangeEventDetails) =&gt; void)">
+  Event handler called when the alert dialog is opened or closed.
+</ParamField>
+
+<ParamField body="Root.onOpenChangeComplete" type="((open: boolean) =&gt; void)">
+  Event handler called after any animations complete when the dialog is opened or closed.
+</ParamField>
+
+<ParamField body="Root.open" type="boolean">
+  Whether the dialog is currently open.
+</ParamField>
+
+<ParamField body="Root.triggerId" type="string | null">
+  ID of the trigger that the dialog is associated with.
+  This is useful in conjunction with the `open` prop to create a controlled dialog.
+  There's no need to specify this prop when the dialog is uncontrolled (that is, when the `open` prop is not set).
+</ParamField>
+
+### AlertDialog.Trigger
+
+<ParamField body="Trigger.className" type="string | ((state: DialogTriggerState) =&gt; string | undefined)">
+  CSS class applied to the element, or a function that
+  returns a class based on the component's state.
+</ParamField>
+
+<ParamField body="Trigger.handle" type="AlertDialogHandle&lt;Payload&gt;">
+  A handle to associate the trigger with an alert dialog.
+  Can be created with the AlertDialog.createHandle() method.
+</ParamField>
+
+<ParamField body="Trigger.id" type="string">
+  ID of the trigger. In addition to being forwarded to the rendered element,
+  it is also used to specify the active trigger for the dialog in controlled mode (with the DialogRoot `triggerId` prop).
+</ParamField>
+
+<ParamField body="Trigger.nativeButton" type="boolean" default="true">
+  Whether the component renders a native `<button>` element when replacing it
+  via the `render` prop.
+  Set to `false` if the rendered element is not a button (for example, `<div>`).
+</ParamField>
+
+<ParamField body="Trigger.payload" type="Payload">
+  A payload to pass to the dialog when it is opened.
+</ParamField>
+
+<ParamField body="Trigger.render" type="ReactElement&lt;unknown, string | JSXElementConstructor&lt;any&gt;&gt; | ComponentRenderFn&lt;HTMLProps, DialogTriggerState&gt;">
+  Allows you to replace the component's HTML element
+  with a different tag, or compose it with another component.
+
+  Accepts a `ReactElement` or a function that returns the element to render.
+</ParamField>
+
+<ParamField body="Trigger.style" type="CSSProperties | ((state: DialogTriggerState) =&gt; CSSProperties | undefined)">
+  Style applied to the element, or a function that
+  returns a style object based on the component's state.
+</ParamField>
+
+### AlertDialog.Popup
+
+<ParamField body="Popup.className" type="string | ((state: DialogPopupState) =&gt; string | undefined)">
+  CSS class applied to the element, or a function that
+  returns a class based on the component's state.
+</ParamField>
+
+<ParamField body="Popup.container" type="HTMLElement | ShadowRoot | RefObject&lt;HTMLElement | ShadowRoot | null&gt; | null">
+  Element the dialog is portaled into. Defaults to the theme's portal
+  container.
+</ParamField>
+
+<ParamField body="Popup.finalFocus" type="boolean | RefObject&lt;HTMLElement | null&gt; | ((closeType: InteractionType) =&gt; boolean | void | HTMLElement | null)">
+  Determines the element to focus when the dialog is closed.
+
+  - `false`: Do not move focus.
+  - `true`: Move focus based on the default behavior (trigger or previously focused element).
+  - `RefObject`: Move focus to the ref element.
+  - `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`).
+    Return an element to focus, `true` to use the default behavior, `null` to fall back to the default behavior, or `false`/`undefined` to do nothing.
+</ParamField>
+
+<ParamField body="Popup.initialFocus" type="boolean | RefObject&lt;HTMLElement | null&gt; | ((openType: InteractionType) =&gt; boolean | void | HTMLElement | null)">
+  Determines the element to focus when the dialog is opened.
+  By default, focus moves to the first tabbable element inside the popup, except when the dialog
+  is opened by touch — then the popup itself is focused to avoid opening the virtual keyboard.
+
+  - `false`: Do not move focus.
+  - `true`: Move focus based on the default behavior (first tabbable element or popup).
+  - `RefObject`: Move focus to the ref element.
+  - `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`).
+    Return an element to focus, `true` to use the default behavior, `null` to fall back to the default behavior, or `false`/`undefined` to do nothing.
+</ParamField>
+
+<ParamField body="Popup.keepMounted" type="boolean">
+  Keeps the dialog mounted in the DOM while it is closed.
+</ParamField>
+
+<ParamField body="Popup.render" type="ReactElement&lt;unknown, string | JSXElementConstructor&lt;any&gt;&gt; | ComponentRenderFn&lt;HTMLProps, DialogPopupState&gt;">
+  Allows you to replace the component's HTML element
+  with a different tag, or compose it with another component.
+
+  Accepts a `ReactElement` or a function that returns the element to render.
+</ParamField>
+
+<ParamField body="Popup.size" type="&quot;sm&quot; | &quot;md&quot; | &quot;lg&quot; | &quot;xl&quot; | &quot;fullscreen&quot;" default="md">
+  Width of the dialog, or `fullscreen` to fill the viewport.
+</ParamField>
+
+<ParamField body="Popup.style" type="CSSProperties | ((state: DialogPopupState) =&gt; CSSProperties | undefined)">
+  Style applied to the element, or a function that
+  returns a style object based on the component's state.
+</ParamField>
+
+### AlertDialog.Title
+
+<ParamField body="Title.className" type="string | ((state: DialogTitleState) =&gt; string | undefined)">
+  CSS class applied to the element, or a function that
+  returns a class based on the component's state.
+</ParamField>
+
+<ParamField body="Title.render" type="ReactElement&lt;unknown, string | JSXElementConstructor&lt;any&gt;&gt; | ComponentRenderFn&lt;HTMLProps, DialogTitleState&gt;">
+  Allows you to replace the component's HTML element
+  with a different tag, or compose it with another component.
+
+  Accepts a `ReactElement` or a function that returns the element to render.
+</ParamField>
+
+<ParamField body="Title.style" type="CSSProperties | ((state: DialogTitleState) =&gt; CSSProperties | undefined)">
+  Style applied to the element, or a function that
+  returns a style object based on the component's state.
+</ParamField>
+
+### AlertDialog.Description
+
+<ParamField body="Description.className" type="string | ((state: DialogDescriptionState) =&gt; string | undefined)">
+  CSS class applied to the element, or a function that
+  returns a class based on the component's state.
+</ParamField>
+
+<ParamField body="Description.render" type="ReactElement&lt;unknown, string | JSXElementConstructor&lt;any&gt;&gt; | ComponentRenderFn&lt;HTMLProps, DialogDescriptionState&gt;">
+  Allows you to replace the component's HTML element
+  with a different tag, or compose it with another component.
+
+  Accepts a `ReactElement` or a function that returns the element to render.
+</ParamField>
+
+<ParamField body="Description.style" type="CSSProperties | ((state: DialogDescriptionState) =&gt; CSSProperties | undefined)">
+  Style applied to the element, or a function that
+  returns a style object based on the component's state.
+</ParamField>
+
+### AlertDialog.Close
+
+<ParamField body="Close.className" type="string | ((state: DialogCloseState) =&gt; string | undefined)">
+  CSS class applied to the element, or a function that
+  returns a class based on the component's state.
+</ParamField>
+
+<ParamField body="Close.nativeButton" type="boolean" default="true">
+  Whether the component renders a native `<button>` element when replacing it
+  via the `render` prop.
+  Set to `false` if the rendered element is not a button (for example, `<div>`).
+</ParamField>
+
+<ParamField body="Close.render" type="ReactElement&lt;unknown, string | JSXElementConstructor&lt;any&gt;&gt; | ComponentRenderFn&lt;HTMLProps, DialogCloseState&gt;">
+  Allows you to replace the component's HTML element
+  with a different tag, or compose it with another component.
+
+  Accepts a `ReactElement` or a function that returns the element to render.
+</ParamField>
+
+<ParamField body="Close.style" type="CSSProperties | ((state: DialogCloseState) =&gt; CSSProperties | undefined)">
+  Style applied to the element, or a function that
+  returns a style object based on the component's state.
+</ParamField>
+
+### AlertDialog.Header
+
+<ParamField body="Header.render" type="ReactElement&lt;unknown, string | JSXElementConstructor&lt;any&gt;&gt; | ComponentRenderFn&lt;HTMLProps, {}&gt;">
+  Allows you to replace the component's HTML element
+  with a different tag, or compose it with another component.
+
+  Accepts a `ReactElement` or a function that returns the element to render.
+</ParamField>
+
+### AlertDialog.Body
+
+<ParamField body="Body.render" type="ReactElement&lt;unknown, string | JSXElementConstructor&lt;any&gt;&gt; | ComponentRenderFn&lt;HTMLProps, {}&gt;">
+  Allows you to replace the component's HTML element
+  with a different tag, or compose it with another component.
+
+  Accepts a `ReactElement` or a function that returns the element to render.
+</ParamField>
+
+### AlertDialog.Footer
+
+<ParamField body="Footer.render" type="ReactElement&lt;unknown, string | JSXElementConstructor&lt;any&gt;&gt; | ComponentRenderFn&lt;HTMLProps, {}&gt;">
+  Allows you to replace the component's HTML element
+  with a different tag, or compose it with another component.
+
+  Accepts a `ReactElement` or a function that returns the element to render.
+</ParamField>

packages/twenty-docs/snippets/ui/generated/surfaces/dialog.mdx

@@ -0,0 +1,43 @@
+{/*
+ * _____                    _
+ *|_   _|_      _____ _ __ | |_ _   _
+ *  | | \ \ /\ / / _ \ '_ \| __| | | | Auto-generated file
+ *  | |  \ V  V /  __/ | | | |_| |_| | DO NOT EDIT - changes will be overwritten
+ *  |_|   \_/\_/ \___|_| |_|\__|\__, | Generated by: npx nx generate:ui twenty-docs
+ *                              |___/
+ *
+ * This file is generated from the documentation data in packages/twenty-ui/generated.
+ * To update it, edit the component prop types or design tokens in twenty-ui and run:
+ *   npx nx generate:ui twenty-docs
+ */}
+
+### Dialog.Title
+
+<ParamField body="Title.className" type="string | ((state: DialogTitleState) =&gt; string | undefined)">
+  CSS class applied to the element, or a function that
+  returns a class based on the component's state.
+</ParamField>
+
+<ParamField body="Title.color" type="&quot;primary&quot; | &quot;secondary&quot; | &quot;tertiary&quot;" default="primary">
+  Theme font color. Defaults to `primary`.
+</ParamField>
+
+<ParamField body="Title.level" type="5 | 1 | 2 | 3 | 4 | 6" default="2">
+  Semantic heading level, from `h1` through `h6`. Does not change the visual size. Defaults to `2`.
+</ParamField>
+
+<ParamField body="Title.render" type="ReactElement&lt;unknown, string | JSXElementConstructor&lt;any&gt;&gt; | ComponentRenderFn&lt;HTMLProps, DialogTitleState&gt;">
+  Allows you to replace the component's HTML element
+  with a different tag, or compose it with another component.
+
+  Accepts a `ReactElement` or a function that returns the element to render.
+</ParamField>
+
+<ParamField body="Title.size" type="&quot;sm&quot; | &quot;md&quot; | &quot;lg&quot; | &quot;xs&quot;" default="lg">
+  Visual font size, independent of the heading level. Defaults to `lg`.
+</ParamField>
+
+<ParamField body="Title.style" type="CSSProperties | ((state: DialogTitleState) =&gt; CSSProperties | undefined)">
+  Style applied to the element, or a function that
+  returns a style object based on the component's state.
+</ParamField>

packages/twenty-docs/snippets/ui/generated/surfaces/menu.mdx

@@ -0,0 +1,674 @@
+{/*
+ * _____                    _
+ *|_   _|_      _____ _ __ | |_ _   _
+ *  | | \ \ /\ / / _ \ '_ \| __| | | | Auto-generated file
+ *  | |  \ V  V /  __/ | | | |_| |_| | DO NOT EDIT - changes will be overwritten
+ *  |_|   \_/\_/ \___|_| |_|\__|\__, | Generated by: npx nx generate:ui twenty-docs
+ *                              |___/
+ *
+ * This file is generated from the documentation data in packages/twenty-ui/generated.
+ * To update it, edit the component prop types or design tokens in twenty-ui and run:
+ *   npx nx generate:ui twenty-docs
+ */}
+
+### Menu.Root
+
+<ParamField body="Root.actionsRef" type="RefObject&lt;MenuRootActions | null&gt;">
+  A ref to imperative actions.
+  - `unmount`: Manually unmounts the menu.
+    Call this after any externally controlled closing animation finishes.
+  - `close`: When specified, the menu can be closed imperatively.
+</ParamField>
+
+<ParamField body="Root.children" type="ReactNode | PayloadChildRenderFunction&lt;Payload&gt;">
+  The content of the menu.
+  This can be a regular React node or a render function that receives the `payload` of the active trigger.
+</ParamField>
+
+<ParamField body="Root.closeParentOnEsc" type="boolean" default="false">
+  When in a submenu, determines whether pressing the Escape key
+  closes the entire menu, or only the current child menu.
+</ParamField>
+
+<ParamField body="Root.defaultOpen" type="boolean" default="false">
+  Whether the menu is initially open.
+
+  To render a controlled menu, use the `open` prop instead.
+</ParamField>
+
+<ParamField body="Root.defaultTriggerId" type="string | null">
+  ID of the trigger that the menu is associated with.
+  This is useful in conjunction with the `defaultOpen` prop to create an initially open menu.
+</ParamField>
+
+<ParamField body="Root.disabled" type="boolean" default="false">
+  Whether the component should ignore user interaction.
+</ParamField>
+
+<ParamField body="Root.handle" type="MenuHandle&lt;Payload&gt;">
+  A handle to associate the menu with a trigger.
+  If specified, allows external triggers to control the menu's open state.
+</ParamField>
+
+<ParamField body="Root.highlightItemOnHover" type="boolean" default="true">
+  Whether moving the pointer over items should highlight them.
+  Disabling this prop allows CSS `:hover` to be differentiated from the `:focus` (`data-highlighted`) state.
+</ParamField>
+
+<ParamField body="Root.loopFocus" type="boolean" default="true">
+  Whether to loop keyboard focus back to the first item
+  when the end of the list is reached while using the arrow keys.
+</ParamField>
+
+<ParamField body="Root.modal" type="boolean" default="true">
+  Determines if the menu enters a modal state when open.
+  - `true`: user interaction is limited to the menu: document page scroll is locked and pointer interactions on outside elements are disabled.
+  - `false`: user interaction with the rest of the document is allowed.
+
+  On touch devices, a `true` modal blocks outside taps but leaves the page scrollable unless the popup spans nearly the full viewport width, matching native iOS behavior.
+
+  Nested menus ignore this prop, and menus opened by hover are never modal.
+</ParamField>
+
+<ParamField body="Root.onOpenChange" type="((open: boolean, eventDetails: MenuRootChangeEventDetails) =&gt; void)">
+  Event handler called when the menu is opened or closed.
+</ParamField>
+
+<ParamField body="Root.onOpenChangeComplete" type="((open: boolean) =&gt; void)">
+  Event handler called after any animations complete when the menu is opened or closed.
+</ParamField>
+
+<ParamField body="Root.open" type="boolean">
+  Whether the menu is currently open.
+</ParamField>
+
+<ParamField body="Root.orientation" type="&quot;horizontal&quot; | &quot;vertical&quot;" default="vertical">
+  The visual orientation of the menu.
+  Controls whether roving focus uses up/down or left/right arrow keys.
+</ParamField>
+
+<ParamField body="Root.triggerId" type="string | null">
+  ID of the trigger that the menu is associated with.
+  This is useful in conjunction with the `open` prop to create a controlled menu.
+  There's no need to specify this prop when the menu is uncontrolled (that is, when the `open` prop is not set).
+</ParamField>
+
+### Menu.Trigger
+
+<ParamField body="Trigger.className" type="string | ((state: MenuTriggerState) =&gt; string | undefined)">
+  CSS class applied to the element, or a function that
+  returns a class based on the component's state.
+</ParamField>
+
+<ParamField body="Trigger.closeDelay" type="number" default="0">
+  How long to wait before closing the menu that was opened on hover.
+  Specified in milliseconds.
+
+  Requires the `openOnHover` prop.
+</ParamField>
+
+<ParamField body="Trigger.delay" type="number" default="100">
+  How long to wait before the menu may be opened on hover. Specified in milliseconds.
+
+  Requires the `openOnHover` prop.
+</ParamField>
+
+<ParamField body="Trigger.disabled" type="boolean" default="false">
+  Whether the component should ignore user interaction.
+</ParamField>
+
+<ParamField body="Trigger.handle" type="MenuHandle&lt;Payload&gt;">
+  A handle to associate the trigger with a menu.
+</ParamField>
+
+<ParamField body="Trigger.nativeButton" type="boolean" default="true">
+  Whether the component renders a native `<button>` element when replacing it
+  via the `render` prop.
+  Set to `false` if the rendered element is not a button (for example, `<div>`).
+</ParamField>
+
+<ParamField body="Trigger.openOnHover" type="boolean">
+  Whether the menu should also open when the trigger is hovered.
+</ParamField>
+
+<ParamField body="Trigger.payload" type="Payload">
+  A payload to pass to the menu when it is opened.
+</ParamField>
+
+<ParamField body="Trigger.render" type="ReactElement&lt;unknown, string | JSXElementConstructor&lt;any&gt;&gt; | ComponentRenderFn&lt;HTMLProps, MenuTriggerState&gt;">
+  Allows you to replace the component's HTML element
+  with a different tag, or compose it with another component.
+
+  Accepts a `ReactElement` or a function that returns the element to render.
+</ParamField>
+
+<ParamField body="Trigger.style" type="CSSProperties | ((state: MenuTriggerState) =&gt; CSSProperties | undefined)">
+  Style applied to the element, or a function that
+  returns a style object based on the component's state.
+</ParamField>
+
+### Menu.Popup
+
+<ParamField body="Popup.align" type="&quot;center&quot; | &quot;start&quot; | &quot;end&quot;">
+  Alignment of the popup along the anchor. Defaults to `start`.
+</ParamField>
+
+<ParamField body="Popup.alignOffset" type="number">
+  Offset in pixels along the alignment axis. Defaults to `0` for a menu and
+  `-4` for a submenu.
+</ParamField>
+
+<ParamField body="Popup.anchor" type="Element | VirtualElement | RefObject&lt;Element | null&gt; | (() =&gt; Element | VirtualElement | null) | null">
+  Element or position the popup is anchored to. Defaults to the trigger.
+</ParamField>
+
+<ParamField body="Popup.className" type="string | ((state: MenuPopupState) =&gt; string | undefined)">
+  CSS class applied to the element, or a function that
+  returns a class based on the component's state.
+</ParamField>
+
+<ParamField body="Popup.container" type="HTMLElement | ShadowRoot | RefObject&lt;HTMLElement | ShadowRoot | null&gt; | null">
+  Element the popup is portaled into. Defaults to the theme's portal
+  container.
+</ParamField>
+
+<ParamField body="Popup.finalFocus" type="boolean | RefObject&lt;HTMLElement | null&gt; | ((closeType: InteractionType) =&gt; boolean | void | HTMLElement | null)">
+  Determines the element to focus when the menu is closed.
+
+  - `false`: Do not move focus.
+  - `true`: Move focus based on the default behavior (trigger or previously focused element).
+  - `RefObject`: Move focus to the ref element.
+  - `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`).
+    Return an element to focus, `true` to use the default behavior, or `false`/`undefined` to do nothing.
+</ParamField>
+
+<ParamField body="Popup.keepMounted" type="boolean">
+  Keeps the popup mounted in the DOM while the menu is closed.
+</ParamField>
+
+<ParamField body="Popup.render" type="ReactElement&lt;unknown, string | JSXElementConstructor&lt;any&gt;&gt; | ComponentRenderFn&lt;HTMLProps, MenuPopupState&gt;">
+  Allows you to replace the component's HTML element
+  with a different tag, or compose it with another component.
+
+  Accepts a `ReactElement` or a function that returns the element to render.
+</ParamField>
+
+<ParamField body="Popup.side" type="&quot;top&quot; | &quot;right&quot; | &quot;bottom&quot; | &quot;left&quot; | &quot;inline-end&quot; | &quot;inline-start&quot;">
+  Side of the anchor the popup is placed on. Defaults to `bottom` for a menu
+  and `inline-end` for a submenu.
+</ParamField>
+
+<ParamField body="Popup.sideOffset" type="number">
+  Distance in pixels between the anchor and the popup. Defaults to `8` for a
+  menu and `0` for a submenu.
+</ParamField>
+
+<ParamField body="Popup.style" type="CSSProperties | ((state: MenuPopupState) =&gt; CSSProperties | undefined)">
+  Style applied to the element, or a function that
+  returns a style object based on the component's state.
+</ParamField>
+
+### Menu.Item
+
+<ParamField body="Item.className" type="string | ((state: MenuItemState) =&gt; string | undefined)">
+  CSS class applied to the element, or a function that
+  returns a class based on the component's state.
+</ParamField>
+
+<ParamField body="Item.closeOnClick" type="boolean" default="true">
+  Whether to close the menu when the item is clicked.
+</ParamField>
+
+<ParamField body="Item.color" type="&quot;neutral&quot; | &quot;danger&quot;">
+  Color of the text and icons. `danger` marks a destructive action.
+</ParamField>
+
+<ParamField body="Item.description" type="ReactNode">
+  Supporting text, placed according to `descriptionPlacement`.
+</ParamField>
+
+<ParamField body="Item.descriptionPlacement" type="&quot;inline&quot; | &quot;end&quot;">
+  Where the description renders: inline after the content or at the end of
+  the row.
+</ParamField>
+
+<ParamField body="Item.disabled" type="boolean" default="false">
+  Whether the component should ignore user interaction.
+</ParamField>
+
+<ParamField body="Item.endIcon" type="ReactNode">
+  Icon rendered after the content.
+</ParamField>
+
+<ParamField body="Item.hotkeys" type="string[]">
+  Keyboard shortcut keys displayed at the end of the row. Registering the
+  shortcut is up to the application.
+</ParamField>
+
+<ParamField body="Item.label" type="string">
+  Overrides the text label to use when the item is matched during keyboard text navigation.
+</ParamField>
+
+<ParamField body="Item.nativeButton" type="boolean" default="false">
+  Whether the component renders a native `<button>` element when replacing it
+  via the `render` prop.
+  Set to `true` if the rendered element is a native button.
+</ParamField>
+
+<ParamField body="Item.onClick" type="((event: BaseUIEvent&lt;MouseEvent&lt;HTMLDivElement, MouseEvent&gt;&gt;) =&gt; void)">
+  The click handler for the menu item.
+</ParamField>
+
+<ParamField body="Item.render" type="ReactElement&lt;unknown, string | JSXElementConstructor&lt;any&gt;&gt; | ComponentRenderFn&lt;HTMLProps, MenuItemState&gt;">
+  Allows you to replace the component's HTML element
+  with a different tag, or compose it with another component.
+
+  Accepts a `ReactElement` or a function that returns the element to render.
+</ParamField>
+
+<ParamField body="Item.startIcon" type="ReactNode">
+  Icon rendered before the content.
+</ParamField>
+
+<ParamField body="Item.style" type="CSSProperties | ((state: MenuItemState) =&gt; CSSProperties | undefined)">
+  Style applied to the element, or a function that
+  returns a style object based on the component's state.
+</ParamField>
+
+### Menu.CheckboxItem
+
+<ParamField body="CheckboxItem.checked" type="boolean">
+  Whether the checkbox item is currently ticked.
+
+  To render an uncontrolled checkbox item, use the `defaultChecked` prop instead.
+</ParamField>
+
+<ParamField body="CheckboxItem.className" type="string | ((state: MenuCheckboxItemState) =&gt; string | undefined)">
+  CSS class applied to the element, or a function that
+  returns a class based on the component's state.
+</ParamField>
+
+<ParamField body="CheckboxItem.closeOnClick" type="boolean" default="false">
+  Whether to close the menu when the item is clicked.
+</ParamField>
+
+<ParamField body="CheckboxItem.color" type="&quot;neutral&quot; | &quot;danger&quot;">
+  Color of the text and icons. `danger` marks a destructive action.
+</ParamField>
+
+<ParamField body="CheckboxItem.defaultChecked" type="boolean" default="false">
+  Whether the checkbox item is initially ticked.
+
+  To render a controlled checkbox item, use the `checked` prop instead.
+</ParamField>
+
+<ParamField body="CheckboxItem.description" type="ReactNode">
+  Supporting text, placed according to `descriptionPlacement`.
+</ParamField>
+
+<ParamField body="CheckboxItem.descriptionPlacement" type="&quot;inline&quot; | &quot;end&quot;">
+  Where the description renders: inline after the content or at the end of
+  the row.
+</ParamField>
+
+<ParamField body="CheckboxItem.disabled" type="boolean" default="false">
+  Whether the component should ignore user interaction.
+</ParamField>
+
+<ParamField body="CheckboxItem.endIcon" type="ReactNode">
+  Icon rendered after the content.
+</ParamField>
+
+<ParamField body="CheckboxItem.hotkeys" type="string[]">
+  Keyboard shortcut keys displayed at the end of the row. Registering the
+  shortcut is up to the application.
+</ParamField>
+
+<ParamField body="CheckboxItem.label" type="string">
+  Overrides the text label to use when the item is matched during keyboard text navigation.
+</ParamField>
+
+<ParamField body="CheckboxItem.nativeButton" type="boolean" default="false">
+  Whether the component renders a native `<button>` element when replacing it
+  via the `render` prop.
+  Set to `true` if the rendered element is a native button.
+</ParamField>
+
+<ParamField body="CheckboxItem.onCheckedChange" type="((checked: boolean, eventDetails: MenuRootChangeEventDetails) =&gt; void)">
+  Event handler called when the checkbox item is ticked or unticked.
+</ParamField>
+
+<ParamField body="CheckboxItem.onClick" type="((event: BaseUIEvent&lt;MouseEvent&lt;HTMLDivElement, MouseEvent&gt;&gt;) =&gt; void)">
+  The click handler for the menu item.
+</ParamField>
+
+<ParamField body="CheckboxItem.render" type="ReactElement&lt;unknown, string | JSXElementConstructor&lt;any&gt;&gt; | ComponentRenderFn&lt;HTMLProps, MenuCheckboxItemState&gt;">
+  Allows you to replace the component's HTML element
+  with a different tag, or compose it with another component.
+
+  Accepts a `ReactElement` or a function that returns the element to render.
+</ParamField>
+
+<ParamField body="CheckboxItem.startIcon" type="ReactNode">
+  Icon rendered before the content.
+</ParamField>
+
+<ParamField body="CheckboxItem.style" type="CSSProperties | ((state: MenuCheckboxItemState) =&gt; CSSProperties | undefined)">
+  Style applied to the element, or a function that
+  returns a style object based on the component's state.
+</ParamField>
+
+### Menu.RadioGroup
+
+<ParamField body="RadioGroup.children" type="ReactNode">
+  The content of the component.
+</ParamField>
+
+<ParamField body="RadioGroup.className" type="string | ((state: MenuRadioGroupState) =&gt; string | undefined)">
+  CSS class applied to the element, or a function that
+  returns a class based on the component's state.
+</ParamField>
+
+<ParamField body="RadioGroup.defaultValue" type="any">
+  The uncontrolled value of the radio item that should be initially selected.
+
+  To render a controlled radio group, use the `value` prop instead.
+</ParamField>
+
+<ParamField body="RadioGroup.disabled" type="boolean" default="false">
+  Whether the component should ignore user interaction.
+</ParamField>
+
+<ParamField body="RadioGroup.onValueChange" type="((value: any, eventDetails: MenuRootChangeEventDetails) =&gt; void)">
+  Function called when the selected value changes.
+</ParamField>
+
+<ParamField body="RadioGroup.render" type="ReactElement&lt;unknown, string | JSXElementConstructor&lt;any&gt;&gt; | ComponentRenderFn&lt;HTMLProps, MenuRadioGroupState&gt;">
+  Allows you to replace the component's HTML element
+  with a different tag, or compose it with another component.
+
+  Accepts a `ReactElement` or a function that returns the element to render.
+</ParamField>
+
+<ParamField body="RadioGroup.style" type="CSSProperties | ((state: MenuRadioGroupState) =&gt; CSSProperties | undefined)">
+  Style applied to the element, or a function that
+  returns a style object based on the component's state.
+</ParamField>
+
+<ParamField body="RadioGroup.value" type="any">
+  The controlled value of the radio item that should be currently selected.
+
+  To render an uncontrolled radio group, use the `defaultValue` prop instead.
+</ParamField>
+
+### Menu.RadioItem
+
+<ParamField body="RadioItem.className" type="string | ((state: MenuRadioItemState) =&gt; string | undefined)">
+  CSS class applied to the element, or a function that
+  returns a class based on the component's state.
+</ParamField>
+
+<ParamField body="RadioItem.closeOnClick" type="boolean" default="false">
+  Whether to close the menu when the item is clicked.
+</ParamField>
+
+<ParamField body="RadioItem.color" type="&quot;neutral&quot; | &quot;danger&quot;">
+  Color of the text and icons. `danger` marks a destructive action.
+</ParamField>
+
+<ParamField body="RadioItem.description" type="ReactNode">
+  Supporting text, placed according to `descriptionPlacement`.
+</ParamField>
+
+<ParamField body="RadioItem.descriptionPlacement" type="&quot;inline&quot; | &quot;end&quot;">
+  Where the description renders: inline after the content or at the end of
+  the row.
+</ParamField>
+
+<ParamField body="RadioItem.disabled" type="boolean" default="false">
+  Whether the component should ignore user interaction.
+</ParamField>
+
+<ParamField body="RadioItem.endIcon" type="ReactNode">
+  Icon rendered after the content.
+</ParamField>
+
+<ParamField body="RadioItem.hotkeys" type="string[]">
+  Keyboard shortcut keys displayed at the end of the row. Registering the
+  shortcut is up to the application.
+</ParamField>
+
+<ParamField body="RadioItem.label" type="string">
+  Overrides the text label to use when the item is matched during keyboard text navigation.
+</ParamField>
+
+<ParamField body="RadioItem.nativeButton" type="boolean" default="false">
+  Whether the component renders a native `<button>` element when replacing it
+  via the `render` prop.
+  Set to `true` if the rendered element is a native button.
+</ParamField>
+
+<ParamField body="RadioItem.onClick" type="((event: BaseUIEvent&lt;MouseEvent&lt;HTMLDivElement, MouseEvent&gt;&gt;) =&gt; void)">
+  The click handler for the menu item.
+</ParamField>
+
+<ParamField body="RadioItem.render" type="ReactElement&lt;unknown, string | JSXElementConstructor&lt;any&gt;&gt; | ComponentRenderFn&lt;HTMLProps, MenuRadioItemState&gt;">
+  Allows you to replace the component's HTML element
+  with a different tag, or compose it with another component.
+
+  Accepts a `ReactElement` or a function that returns the element to render.
+</ParamField>
+
+<ParamField body="RadioItem.startIcon" type="ReactNode">
+  Icon rendered before the content.
+</ParamField>
+
+<ParamField body="RadioItem.style" type="CSSProperties | ((state: MenuRadioItemState) =&gt; CSSProperties | undefined)">
+  Style applied to the element, or a function that
+  returns a style object based on the component's state.
+</ParamField>
+
+<ParamField body="RadioItem.value" type="any" required>
+  Value of the radio item.
+  This is the value that will be set in the MenuRadioGroup when the item is selected.
+</ParamField>
+
+### Menu.Group
+
+<ParamField body="Group.children" type="ReactNode">
+  The content of the component.
+</ParamField>
+
+<ParamField body="Group.className" type="string | ((state: MenuGroupState) =&gt; string | undefined)">
+  CSS class applied to the element, or a function that
+  returns a class based on the component's state.
+</ParamField>
+
+<ParamField body="Group.render" type="ReactElement&lt;unknown, string | JSXElementConstructor&lt;any&gt;&gt; | ComponentRenderFn&lt;HTMLProps, MenuGroupState&gt;">
+  Allows you to replace the component's HTML element
+  with a different tag, or compose it with another component.
+
+  Accepts a `ReactElement` or a function that returns the element to render.
+</ParamField>
+
+<ParamField body="Group.style" type="CSSProperties | ((state: MenuGroupState) =&gt; CSSProperties | undefined)">
+  Style applied to the element, or a function that
+  returns a style object based on the component's state.
+</ParamField>
+
+### Menu.GroupLabel
+
+<ParamField body="GroupLabel.className" type="string | ((state: MenuGroupLabelState) =&gt; string | undefined)">
+  CSS class applied to the element, or a function that
+  returns a class based on the component's state.
+</ParamField>
+
+<ParamField body="GroupLabel.render" type="ReactElement&lt;unknown, string | JSXElementConstructor&lt;any&gt;&gt; | ComponentRenderFn&lt;HTMLProps, MenuGroupLabelState&gt;">
+  Allows you to replace the component's HTML element
+  with a different tag, or compose it with another component.
+
+  Accepts a `ReactElement` or a function that returns the element to render.
+</ParamField>
+
+<ParamField body="GroupLabel.style" type="CSSProperties | ((state: MenuGroupLabelState) =&gt; CSSProperties | undefined)">
+  Style applied to the element, or a function that
+  returns a style object based on the component's state.
+</ParamField>
+
+### Menu.Separator
+
+<ParamField body="Separator.className" type="string | ((state: SeparatorState) =&gt; string | undefined)">
+  CSS class applied to the element, or a function that
+  returns a class based on the component's state.
+</ParamField>
+
+<ParamField body="Separator.orientation" type="&quot;horizontal&quot; | &quot;vertical&quot;" default="horizontal">
+  The orientation of the separator.
+</ParamField>
+
+<ParamField body="Separator.render" type="ReactElement&lt;unknown, string | JSXElementConstructor&lt;any&gt;&gt; | ComponentRenderFn&lt;HTMLProps, SeparatorState&gt;">
+  Allows you to replace the component's HTML element
+  with a different tag, or compose it with another component.
+
+  Accepts a `ReactElement` or a function that returns the element to render.
+</ParamField>
+
+<ParamField body="Separator.style" type="CSSProperties | ((state: SeparatorState) =&gt; CSSProperties | undefined)">
+  Style applied to the element, or a function that
+  returns a style object based on the component's state.
+</ParamField>
+
+### Menu.SubmenuRoot
+
+<ParamField body="SubmenuRoot.actionsRef" type="RefObject&lt;MenuRootActions | null&gt;">
+  A ref to imperative actions.
+  - `unmount`: Manually unmounts the menu.
+    Call this after any externally controlled closing animation finishes.
+  - `close`: When specified, the menu can be closed imperatively.
+</ParamField>
+
+<ParamField body="SubmenuRoot.children" type="ReactNode">
+  The content of the submenu.
+</ParamField>
+
+<ParamField body="SubmenuRoot.closeParentOnEsc" type="boolean" default="false">
+  When in a submenu, determines whether pressing the Escape key
+  closes the entire menu, or only the current child menu.
+</ParamField>
+
+<ParamField body="SubmenuRoot.defaultOpen" type="boolean" default="false">
+  Whether the menu is initially open.
+
+  To render a controlled menu, use the `open` prop instead.
+</ParamField>
+
+<ParamField body="SubmenuRoot.disabled" type="boolean" default="false">
+  Whether the component should ignore user interaction.
+</ParamField>
+
+<ParamField body="SubmenuRoot.highlightItemOnHover" type="boolean" default="true">
+  Whether moving the pointer over items should highlight them.
+  Disabling this prop allows CSS `:hover` to be differentiated from the `:focus` (`data-highlighted`) state.
+</ParamField>
+
+<ParamField body="SubmenuRoot.loopFocus" type="boolean" default="true">
+  Whether to loop keyboard focus back to the first item
+  when the end of the list is reached while using the arrow keys.
+</ParamField>
+
+<ParamField body="SubmenuRoot.onOpenChange" type="((open: boolean, eventDetails: MenuRootChangeEventDetails) =&gt; void)">
+  Event handler called when the menu is opened or closed.
+</ParamField>
+
+<ParamField body="SubmenuRoot.onOpenChangeComplete" type="((open: boolean) =&gt; void)">
+  Event handler called after any animations complete when the menu is opened or closed.
+</ParamField>
+
+<ParamField body="SubmenuRoot.open" type="boolean">
+  Whether the menu is currently open.
+</ParamField>
+
+<ParamField body="SubmenuRoot.orientation" type="&quot;horizontal&quot; | &quot;vertical&quot;" default="vertical">
+  The visual orientation of the menu.
+  Controls whether roving focus uses up/down or left/right arrow keys.
+</ParamField>
+
+### Menu.SubmenuTrigger
+
+<ParamField body="SubmenuTrigger.className" type="string | ((state: MenuSubmenuTriggerState) =&gt; string | undefined)">
+  CSS class applied to the element, or a function that
+  returns a class based on the component's state.
+</ParamField>
+
+<ParamField body="SubmenuTrigger.closeDelay" type="number" default="0">
+  How long to wait before closing the menu that was opened on hover.
+  Specified in milliseconds.
+
+  Requires the `openOnHover` prop.
+</ParamField>
+
+<ParamField body="SubmenuTrigger.color" type="&quot;neutral&quot; | &quot;danger&quot;">
+  Color of the text and icons. `danger` marks a destructive action.
+</ParamField>
+
+<ParamField body="SubmenuTrigger.delay" type="number" default="100">
+  How long to wait before the menu may be opened on hover. Specified in milliseconds.
+
+  Requires the `openOnHover` prop.
+</ParamField>
+
+<ParamField body="SubmenuTrigger.description" type="ReactNode">
+  Supporting text, placed according to `descriptionPlacement`.
+</ParamField>
+
+<ParamField body="SubmenuTrigger.descriptionPlacement" type="&quot;inline&quot; | &quot;end&quot;">
+  Where the description renders: inline after the content or at the end of
+  the row.
+</ParamField>
+
+<ParamField body="SubmenuTrigger.disabled" type="boolean" default="false">
+  Whether the component should ignore user interaction.
+</ParamField>
+
+<ParamField body="SubmenuTrigger.endIcon" type="ReactNode">
+  Icon rendered after the content.
+</ParamField>
+
+<ParamField body="SubmenuTrigger.hotkeys" type="string[]">
+  Keyboard shortcut keys displayed at the end of the row. Registering the
+  shortcut is up to the application.
+</ParamField>
+
+<ParamField body="SubmenuTrigger.label" type="string">
+  Overrides the text label to use when the item is matched during keyboard text navigation.
+</ParamField>
+
+<ParamField body="SubmenuTrigger.nativeButton" type="boolean" default="false">
+  Whether the component renders a native `<button>` element when replacing it
+  via the `render` prop.
+  Set to `true` if the rendered element is a native button.
+</ParamField>
+
+<ParamField body="SubmenuTrigger.onClick" type="((event: BaseUIEvent&lt;MouseEvent&lt;HTMLDivElement, MouseEvent&gt;&gt;) =&gt; void)">
+
+</ParamField>
+
+<ParamField body="SubmenuTrigger.openOnHover" type="boolean" default="true">
+  Whether the menu should also open when the trigger is hovered.
+</ParamField>
+
+<ParamField body="SubmenuTrigger.render" type="ReactElement&lt;unknown, string | JSXElementConstructor&lt;any&gt;&gt; | ComponentRenderFn&lt;HTMLProps, MenuSubmenuTriggerState&gt;">
+  Allows you to replace the component's HTML element
+  with a different tag, or compose it with another component.
+
+  Accepts a `ReactElement` or a function that returns the element to render.
+</ParamField>
+
+<ParamField body="SubmenuTrigger.startIcon" type="ReactNode">
+  Icon rendered before the content.
+</ParamField>
+
+<ParamField body="SubmenuTrigger.style" type="CSSProperties | ((state: MenuSubmenuTriggerState) =&gt; CSSProperties | undefined)">
+  Style applied to the element, or a function that
+  returns a style object based on the component's state.
+</ParamField>

packages/twenty-docs/snippets/ui/generated/surfaces/popover.mdx

@@ -0,0 +1,268 @@
+{/*
+ * _____                    _
+ *|_   _|_      _____ _ __ | |_ _   _
+ *  | | \ \ /\ / / _ \ '_ \| __| | | | Auto-generated file
+ *  | |  \ V  V /  __/ | | | |_| |_| | DO NOT EDIT - changes will be overwritten
+ *  |_|   \_/\_/ \___|_| |_|\__|\__, | Generated by: npx nx generate:ui twenty-docs
+ *                              |___/
+ *
+ * This file is generated from the documentation data in packages/twenty-ui/generated.
+ * To update it, edit the component prop types or design tokens in twenty-ui and run:
+ *   npx nx generate:ui twenty-docs
+ */}
+
+### Popover.Root
+
+<ParamField body="Root.actionsRef" type="RefObject&lt;PopoverRootActions | null&gt;">
+  A ref to imperative actions.
+  - `unmount`: Manually unmounts the popover.
+  Call this after any externally controlled closing animation finishes.
+  - `close`: Closes the popover imperatively when called.
+</ParamField>
+
+<ParamField body="Root.children" type="ReactNode | PayloadChildRenderFunction&lt;Payload&gt;">
+  The content of the popover.
+  This can be a regular React node or a render function that receives the `payload` of the active trigger.
+</ParamField>
+
+<ParamField body="Root.defaultOpen" type="boolean" default="false">
+  Whether the popover is initially open.
+
+  To render a controlled popover, use the `open` prop instead.
+</ParamField>
+
+<ParamField body="Root.defaultTriggerId" type="string | null">
+  ID of the trigger that the popover is associated with.
+  This is useful in conjunction with the `defaultOpen` prop to create an initially open popover.
+</ParamField>
+
+<ParamField body="Root.handle" type="PopoverHandle&lt;Payload&gt;">
+  A handle to associate the popover with a trigger.
+  If specified, allows external triggers to control the popover's open state.
+</ParamField>
+
+<ParamField body="Root.modal" type="boolean | &quot;trap-focus&quot;" default="false">
+  Determines if the popover enters a modal state when open.
+  - `true`: user interaction is limited to the popover: document page scroll is locked, and pointer interactions on outside elements are disabled.
+  - `false`: user interaction with the rest of the document is allowed.
+  - `'trap-focus'`: focus is trapped inside the popover, but document page scroll is not locked and pointer interactions outside of it remain enabled.
+
+  On touch devices, a `true` modal blocks outside taps but leaves the page scrollable unless the popup spans nearly the full viewport width, matching native iOS behavior.
+
+  When `modal` is `true`, focus trapping is enabled only if `<Popover.Close>` is rendered
+  inside `<Popover.Popup>`. It can be visually hidden with your own CSS if needed, such as
+  Tailwind's `sr-only` utility.
+
+  When `modal` is `'trap-focus'`, render `<Popover.Close>` inside `<Popover.Popup>` so touch
+  screen readers can escape the popup.
+</ParamField>
+
+<ParamField body="Root.onOpenChange" type="((open: boolean, eventDetails: PopoverRootChangeEventDetails) =&gt; void)">
+  Event handler called when the popover is opened or closed.
+</ParamField>
+
+<ParamField body="Root.onOpenChangeComplete" type="((open: boolean) =&gt; void)">
+  Event handler called after any animations complete when the popover is opened or closed.
+</ParamField>
+
+<ParamField body="Root.open" type="boolean">
+  Whether the popover is currently open.
+</ParamField>
+
+<ParamField body="Root.triggerId" type="string | null">
+  ID of the trigger that the popover is associated with.
+  This is useful in conjunction with the `open` prop to create a controlled popover.
+  There's no need to specify this prop when the popover is uncontrolled (that is, when the `open` prop is not set).
+</ParamField>
+
+### Popover.Trigger
+
+<ParamField body="Trigger.className" type="string | ((state: PopoverTriggerState) =&gt; string | undefined)">
+  CSS class applied to the element, or a function that
+  returns a class based on the component's state.
+</ParamField>
+
+<ParamField body="Trigger.closeDelay" type="number" default="0">
+  How long to wait before closing the popover that was opened on hover.
+  Specified in milliseconds.
+
+  Requires the `openOnHover` prop.
+</ParamField>
+
+<ParamField body="Trigger.delay" type="number" default="300">
+  How long to wait before the popover may be opened on hover. Specified in milliseconds.
+
+  Requires the `openOnHover` prop.
+</ParamField>
+
+<ParamField body="Trigger.handle" type="PopoverHandle&lt;Payload&gt;">
+  A handle to associate the trigger with a popover.
+</ParamField>
+
+<ParamField body="Trigger.id" type="string">
+  ID of the trigger. In addition to being forwarded to the rendered element,
+  it is also used to specify the active trigger for the popover in controlled mode (with the PopoverRoot `triggerId` prop).
+</ParamField>
+
+<ParamField body="Trigger.nativeButton" type="boolean" default="true">
+  Whether the component renders a native `<button>` element when replacing it
+  via the `render` prop.
+  Set to `false` if the rendered element is not a button (e.g. `<div>`).
+</ParamField>
+
+<ParamField body="Trigger.openOnHover" type="boolean" default="false">
+  Whether the popover should also open when the trigger is hovered.
+</ParamField>
+
+<ParamField body="Trigger.payload" type="Payload">
+  A payload to pass to the popover when it is opened.
+</ParamField>
+
+<ParamField body="Trigger.render" type="ReactElement&lt;unknown, string | JSXElementConstructor&lt;any&gt;&gt; | ComponentRenderFn&lt;HTMLProps, PopoverTriggerState&gt;">
+  Allows you to replace the component's HTML element
+  with a different tag, or compose it with another component.
+
+  Accepts a `ReactElement` or a function that returns the element to render.
+</ParamField>
+
+<ParamField body="Trigger.style" type="CSSProperties | ((state: PopoverTriggerState) =&gt; CSSProperties | undefined)">
+  Style applied to the element, or a function that
+  returns a style object based on the component's state.
+</ParamField>
+
+### Popover.Popup
+
+<ParamField body="Popup.align" type="&quot;center&quot; | &quot;start&quot; | &quot;end&quot;" default="center">
+  Alignment of the popup along the anchor.
+</ParamField>
+
+<ParamField body="Popup.alignOffset" type="number">
+  Offset in pixels along the alignment axis.
+</ParamField>
+
+<ParamField body="Popup.anchor" type="Element | VirtualElement | RefObject&lt;Element | null&gt; | (() =&gt; Element | VirtualElement | null) | null">
+  Element or position the popup is anchored to. Defaults to the trigger.
+</ParamField>
+
+<ParamField body="Popup.arrow" type="boolean" default="false">
+  Shows an arrow pointing at the anchor.
+</ParamField>
+
+<ParamField body="Popup.className" type="string | ((state: PopoverPopupState) =&gt; string | undefined)">
+  CSS class applied to the element, or a function that
+  returns a class based on the component's state.
+</ParamField>
+
+<ParamField body="Popup.container" type="HTMLElement | ShadowRoot | RefObject&lt;HTMLElement | ShadowRoot | null&gt; | null">
+  Element the popup is portaled into. Defaults to the theme's portal
+  container.
+</ParamField>
+
+<ParamField body="Popup.finalFocus" type="boolean | RefObject&lt;HTMLElement | null&gt; | ((closeType: InteractionType) =&gt; boolean | void | HTMLElement | null)">
+  Determines the element to focus when the popover is closed.
+
+  - `false`: Do not move focus.
+  - `true`: Move focus based on the default behavior (trigger or previously focused element).
+  - `RefObject`: Move focus to the ref element.
+  - `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`).
+    Return an element to focus, `true` to use the default behavior, `null` to fall back to the default behavior, or `false`/`undefined` to do nothing.
+</ParamField>
+
+<ParamField body="Popup.initialFocus" type="boolean | RefObject&lt;HTMLElement | null&gt; | ((openType: InteractionType) =&gt; boolean | void | HTMLElement | null)">
+  Determines the element to focus when the popover is opened.
+  By default, focus moves to the first tabbable element inside the popup, except when the popover
+  is opened by touch — then the popup itself is focused to avoid opening the virtual keyboard.
+
+  - `false`: Do not move focus.
+  - `true`: Move focus based on the default behavior (first tabbable element or popup).
+  - `RefObject`: Move focus to the ref element.
+  - `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`).
+    Return an element to focus, `true` to use the default behavior, `null` to fall back to the default behavior, or `false`/`undefined` to do nothing.
+</ParamField>
+
+<ParamField body="Popup.keepMounted" type="boolean">
+  Keeps the popup mounted in the DOM while the popover is closed.
+</ParamField>
+
+<ParamField body="Popup.render" type="ReactElement&lt;unknown, string | JSXElementConstructor&lt;any&gt;&gt; | ComponentRenderFn&lt;HTMLProps, PopoverPopupState&gt;">
+  Allows you to replace the component's HTML element
+  with a different tag, or compose it with another component.
+
+  Accepts a `ReactElement` or a function that returns the element to render.
+</ParamField>
+
+<ParamField body="Popup.side" type="&quot;top&quot; | &quot;right&quot; | &quot;bottom&quot; | &quot;left&quot; | &quot;inline-end&quot; | &quot;inline-start&quot;" default="bottom">
+  Side of the anchor the popup is placed on.
+</ParamField>
+
+<ParamField body="Popup.sideOffset" type="number" default="8">
+  Distance in pixels between the anchor and the popup.
+</ParamField>
+
+<ParamField body="Popup.style" type="CSSProperties | ((state: PopoverPopupState) =&gt; CSSProperties | undefined)">
+  Style applied to the element, or a function that
+  returns a style object based on the component's state.
+</ParamField>
+
+### Popover.Title
+
+<ParamField body="Title.className" type="string | ((state: PopoverTitleState) =&gt; string | undefined)">
+  CSS class applied to the element, or a function that
+  returns a class based on the component's state.
+</ParamField>
+
+<ParamField body="Title.render" type="ReactElement&lt;unknown, string | JSXElementConstructor&lt;any&gt;&gt; | ComponentRenderFn&lt;HTMLProps, PopoverTitleState&gt;">
+  Allows you to replace the component's HTML element
+  with a different tag, or compose it with another component.
+
+  Accepts a `ReactElement` or a function that returns the element to render.
+</ParamField>
+
+<ParamField body="Title.style" type="CSSProperties | ((state: PopoverTitleState) =&gt; CSSProperties | undefined)">
+  Style applied to the element, or a function that
+  returns a style object based on the component's state.
+</ParamField>
+
+### Popover.Description
+
+<ParamField body="Description.className" type="string | ((state: PopoverDescriptionState) =&gt; string | undefined)">
+  CSS class applied to the element, or a function that
+  returns a class based on the component's state.
+</ParamField>
+
+<ParamField body="Description.render" type="ReactElement&lt;unknown, string | JSXElementConstructor&lt;any&gt;&gt; | ComponentRenderFn&lt;HTMLProps, PopoverDescriptionState&gt;">
+  Allows you to replace the component's HTML element
+  with a different tag, or compose it with another component.
+
+  Accepts a `ReactElement` or a function that returns the element to render.
+</ParamField>
+
+<ParamField body="Description.style" type="CSSProperties | ((state: PopoverDescriptionState) =&gt; CSSProperties | undefined)">
+  Style applied to the element, or a function that
+  returns a style object based on the component's state.
+</ParamField>
+
+### Popover.Close
+
+<ParamField body="Close.className" type="string | ((state: PopoverCloseState) =&gt; string | undefined)">
+  CSS class applied to the element, or a function that
+  returns a class based on the component's state.
+</ParamField>
+
+<ParamField body="Close.nativeButton" type="boolean" default="true">
+  Whether the component renders a native `<button>` element when replacing it
+  via the `render` prop.
+  Set to `false` if the rendered element is not a button (for example, `<div>`).
+</ParamField>
+
+<ParamField body="Close.render" type="ReactElement&lt;unknown, string | JSXElementConstructor&lt;any&gt;&gt; | ComponentRenderFn&lt;HTMLProps, PopoverCloseState&gt;">
+  Allows you to replace the component's HTML element
+  with a different tag, or compose it with another component.
+
+  Accepts a `ReactElement` or a function that returns the element to render.
+</ParamField>
+
+<ParamField body="Close.style" type="CSSProperties | ((state: PopoverCloseState) =&gt; CSSProperties | undefined)">
+  Style applied to the element, or a function that
+  returns a style object based on the component's state.
+</ParamField>

packages/twenty-docs/snippets/ui/generated/surfaces/tooltip.mdx

@@ -0,0 +1,416 @@
+{/*
+ * _____                    _
+ *|_   _|_      _____ _ __ | |_ _   _
+ *  | | \ \ /\ / / _ \ '_ \| __| | | | Auto-generated file
+ *  | |  \ V  V /  __/ | | | |_| |_| | DO NOT EDIT - changes will be overwritten
+ *  |_|   \_/\_/ \___|_| |_|\__|\__, | Generated by: npx nx generate:ui twenty-docs
+ *                              |___/
+ *
+ * This file is generated from the documentation data in packages/twenty-ui/generated.
+ * To update it, edit the component prop types or design tokens in twenty-ui and run:
+ *   npx nx generate:ui twenty-docs
+ */}
+
+<ParamField body="actionsRef" type="RefObject&lt;TooltipRootActions | null&gt;">
+  A ref to imperative actions.
+  - `unmount`: Unmounts the tooltip popup.
+  - `close`: Closes the tooltip imperatively when called.
+</ParamField>
+
+<ParamField body="align" type="&quot;center&quot; | &quot;start&quot; | &quot;end&quot;">
+  Alignment relative to the trigger. Defaults to center.
+</ParamField>
+
+<ParamField body="alignOffset" type="number | OffsetFunction" default="0">
+  Offset along the alignment axis in pixels.
+</ParamField>
+
+<ParamField body="anchor" type="Element | VirtualElement | RefObject&lt;Element | null&gt; | (() =&gt; Element | VirtualElement | null) | null">
+  An explicit positioning anchor for the popup.
+</ParamField>
+
+<ParamField body="arrow" type="boolean">
+  Displays an arrow pointing to the trigger. Defaults to false.
+</ParamField>
+
+<ParamField body="children" type="ReactElement&lt;unknown, string | JSXElementConstructor&lt;any&gt;&gt;" required>
+  A single trigger element. Custom components must forward their ref, native attributes, and event handlers.
+</ParamField>
+
+<ParamField body="className" type="string | ((state: TooltipPopupState) =&gt; string | undefined)">
+  Additional CSS class for the popup.
+</ParamField>
+
+<ParamField body="closeDelay" type="number" default="0">
+  Delay in milliseconds before closing after hover ends. Defaults to 0.
+</ParamField>
+
+<ParamField body="closeOnClick" type="boolean" default="true">
+  Whether the tooltip should close when this trigger is clicked.
+</ParamField>
+
+<ParamField body="collisionAvoidance" type="CollisionAvoidance">
+  Determines how to handle collisions when positioning the popup.
+
+  `side` controls overflow on the preferred placement axis (`top`/`bottom` or `left`/`right`):
+  - `'flip'`: keep the requested side when it fits; otherwise try the opposite side
+    (`top` and `bottom`, or `left` and `right`).
+  - `'shift'`: never change side; keep the requested side and move the popup within
+    the clipping boundary so it stays visible.
+  - `'none'`: do not correct side-axis overflow.
+
+  `align` controls overflow on the alignment axis (`start`/`center`/`end`):
+  - `'flip'`: keep side, but swap `start` and `end` when the requested alignment overflows.
+  - `'shift'`: keep side and requested alignment, then nudge the popup along the
+    alignment axis to fit.
+  - `'none'`: do not correct alignment-axis overflow.
+
+  `fallbackAxisSide` controls fallback behavior on the perpendicular axis when the
+  preferred axis cannot fit:
+  - `'start'`: allow perpendicular fallback and try the logical start side first
+    (`top` before `bottom`, or `left` before `right` in LTR).
+  - `'end'`: allow perpendicular fallback and try the logical end side first
+    (`bottom` before `top`, or `right` before `left` in LTR).
+  - `'none'`: do not fallback to the perpendicular axis.
+
+  When `side` is `'shift'`, explicitly setting `align` only supports `'shift'` or `'none'`.
+  If `align` is omitted, it defaults to `'flip'`.
+</ParamField>
+
+<ParamField body="collisionBoundary" type="Boundary" default="clipping-ancestors">
+  An element or a rectangle that delimits the area that the popup is confined to.
+</ParamField>
+
+<ParamField body="collisionPadding" type="Padding" default="5">
+  Additional space to maintain from the edge of the collision boundary.
+</ParamField>
+
+<ParamField body="container" type="HTMLElement | ShadowRoot | RefObject&lt;HTMLElement | ShadowRoot | null&gt; | null">
+  Portal destination. Defaults to the current theme container.
+</ParamField>
+
+<ParamField body="content" type="ReactNode" required>
+  Supplementary content displayed in the tooltip.
+</ParamField>
+
+<ParamField body="defaultOpen" type="boolean" default="false">
+  Initial visibility when the tooltip manages its own state.
+</ParamField>
+
+<ParamField body="defaultTriggerId" type="string | null">
+  ID of the trigger that the tooltip is associated with.
+  This is useful in conjunction with the `defaultOpen` prop to create an initially open tooltip.
+</ParamField>
+
+<ParamField body="delay" type="number" default="600">
+  Delay in milliseconds before opening on hover. Defaults to 600.
+</ParamField>
+
+<ParamField body="disableAnchorTracking" type="boolean" default="false">
+  Whether to disable the popup from tracking any layout shift of its positioning anchor.
+</ParamField>
+
+<ParamField body="disabled" type="boolean" default="false">
+  Prevents the tooltip from opening.
+</ParamField>
+
+<ParamField body="disableHoverablePopup" type="boolean" default="false">
+  Prevents hovering over the popup from keeping it open.
+</ParamField>
+
+<ParamField body="keepMounted" type="boolean">
+  Keeps the popup mounted while closed.
+</ParamField>
+
+<ParamField body="maxWidth" type="MaxWidth&lt;string | number&gt;">
+  Maximum popup width. Defaults to 300 pixels.
+</ParamField>
+
+<ParamField body="onOpenChange" type="((open: boolean, eventDetails: TooltipRootChangeEventDetails) =&gt; void)">
+  Called when an interaction requests a visibility change.
+</ParamField>
+
+<ParamField body="onOpenChangeComplete" type="((open: boolean) =&gt; void)">
+  Event handler called after any animations complete when the tooltip is opened or closed.
+</ParamField>
+
+<ParamField body="open" type="boolean">
+  Controlled visibility of the tooltip.
+</ParamField>
+
+<ParamField body="positionMethod" type="&quot;absolute&quot; | &quot;fixed&quot;" default="absolute">
+  CSS positioning method for the popup.
+</ParamField>
+
+<ParamField body="render" type="ReactElement&lt;unknown, string | JSXElementConstructor&lt;any&gt;&gt; | ComponentRenderFn&lt;HTMLProps, TooltipPopupState&gt;">
+  Allows you to replace the component's HTML element
+  with a different tag, or compose it with another component.
+
+  Accepts a `ReactElement` or a function that returns the element to render.
+</ParamField>
+
+<ParamField body="side" type="&quot;top&quot; | &quot;right&quot; | &quot;bottom&quot; | &quot;left&quot;">
+  Preferred side of the trigger. Defaults to top and may change to avoid collisions.
+</ParamField>
+
+<ParamField body="sideOffset" type="number | OffsetFunction" default="10">
+  Distance from the trigger in pixels. Defaults to 10.
+</ParamField>
+
+<ParamField body="sticky" type="boolean" default="false">
+  Whether to maintain the popup in the viewport after
+  the anchor element was scrolled out of view.
+</ParamField>
+
+<ParamField body="style" type="CSSProperties | ((state: TooltipPopupState) =&gt; CSSProperties | undefined)">
+  Inline styles for the popup.
+</ParamField>
+
+<ParamField body="trackCursorAxis" type="&quot;none&quot; | &quot;both&quot; | &quot;x&quot; | &quot;y&quot;" default="none">
+  Determines which axis the tooltip should track the cursor on.
+</ParamField>
+
+<ParamField body="triggerId" type="string | null">
+  ID of the trigger that the tooltip is associated with.
+  This is useful in conjunction with the `open` prop to create a controlled tooltip.
+  There's no need to specify this prop when the tooltip is uncontrolled (that is, when the `open` prop is not set).
+</ParamField>
+
+### Tooltip.Root
+
+<ParamField body="Root.actionsRef" type="RefObject&lt;TooltipRootActions | null&gt;">
+  A ref to imperative actions.
+  - `unmount`: Unmounts the tooltip popup.
+  - `close`: Closes the tooltip imperatively when called.
+</ParamField>
+
+<ParamField body="Root.children" type="ReactNode | PayloadChildRenderFunction&lt;Payload&gt;">
+  The content of the tooltip.
+  This can be a regular React node or a render function that receives the `payload` of the active trigger.
+</ParamField>
+
+<ParamField body="Root.defaultOpen" type="boolean" default="false">
+  Whether the tooltip is initially open.
+
+  To render a controlled tooltip, use the `open` prop instead.
+</ParamField>
+
+<ParamField body="Root.defaultTriggerId" type="string | null">
+  ID of the trigger that the tooltip is associated with.
+  This is useful in conjunction with the `defaultOpen` prop to create an initially open tooltip.
+</ParamField>
+
+<ParamField body="Root.disabled" type="boolean" default="false">
+  Whether the tooltip is disabled.
+</ParamField>
+
+<ParamField body="Root.disableHoverablePopup" type="boolean" default="false">
+  Whether the tooltip contents can be hovered without closing the tooltip.
+</ParamField>
+
+<ParamField body="Root.handle" type="TooltipHandle&lt;Payload&gt;">
+  A handle to associate the tooltip with a trigger.
+  If specified, allows external triggers to control the tooltip's open state.
+  Can be created with the Tooltip.createHandle() method.
+</ParamField>
+
+<ParamField body="Root.onOpenChange" type="((open: boolean, eventDetails: TooltipRootChangeEventDetails) =&gt; void)">
+  Event handler called when the tooltip is opened or closed.
+</ParamField>
+
+<ParamField body="Root.onOpenChangeComplete" type="((open: boolean) =&gt; void)">
+  Event handler called after any animations complete when the tooltip is opened or closed.
+</ParamField>
+
+<ParamField body="Root.open" type="boolean">
+  Whether the tooltip is currently open.
+</ParamField>
+
+<ParamField body="Root.trackCursorAxis" type="&quot;none&quot; | &quot;both&quot; | &quot;x&quot; | &quot;y&quot;" default="none">
+  Determines which axis the tooltip should track the cursor on.
+</ParamField>
+
+<ParamField body="Root.triggerId" type="string | null">
+  ID of the trigger that the tooltip is associated with.
+  This is useful in conjunction with the `open` prop to create a controlled tooltip.
+  There's no need to specify this prop when the tooltip is uncontrolled (that is, when the `open` prop is not set).
+</ParamField>
+
+### Tooltip.Trigger
+
+<ParamField body="Trigger.className" type="string | ((state: TooltipTriggerState) =&gt; string | undefined)">
+  CSS class applied to the element, or a function that
+  returns a class based on the component's state.
+</ParamField>
+
+<ParamField body="Trigger.closeDelay" type="number" default="0">
+  How long to wait before closing the tooltip. Specified in milliseconds.
+</ParamField>
+
+<ParamField body="Trigger.closeOnClick" type="boolean" default="true">
+  Whether the tooltip should close when this trigger is clicked.
+</ParamField>
+
+<ParamField body="Trigger.delay" type="number" default="600">
+  How long to wait before opening the tooltip on hover. Specified in milliseconds.
+</ParamField>
+
+<ParamField body="Trigger.disabled" type="boolean" default="false">
+  If `true`, the tooltip will not open when interacting with this trigger.
+  Note that this doesn't apply the `disabled` attribute to the trigger element.
+  If you want to disable the trigger element itself, you can pass the `disabled` prop to the trigger element via the `render` prop.
+</ParamField>
+
+<ParamField body="Trigger.handle" type="TooltipHandle&lt;Payload&gt;">
+  A handle to associate the trigger with a tooltip.
+</ParamField>
+
+<ParamField body="Trigger.payload" type="Payload">
+  A payload to pass to the tooltip when it is opened.
+</ParamField>
+
+<ParamField body="Trigger.render" type="ReactElement&lt;unknown, string | JSXElementConstructor&lt;any&gt;&gt; | ComponentRenderFn&lt;HTMLProps, TooltipTriggerState&gt;">
+  Allows you to replace the component's HTML element
+  with a different tag, or compose it with another component.
+
+  Accepts a `ReactElement` or a function that returns the element to render.
+</ParamField>
+
+<ParamField body="Trigger.style" type="CSSProperties | ((state: TooltipTriggerState) =&gt; CSSProperties | undefined)">
+  Style applied to the element, or a function that
+  returns a style object based on the component's state.
+</ParamField>
+
+### Tooltip.Popup
+
+<ParamField body="Popup.align" type="&quot;center&quot; | &quot;start&quot; | &quot;end&quot;" default="center">
+  Alignment relative to the trigger. Defaults to center.
+</ParamField>
+
+<ParamField body="Popup.alignOffset" type="number | OffsetFunction" default="0">
+  Offset along the alignment axis in pixels.
+</ParamField>
+
+<ParamField body="Popup.anchor" type="Element | VirtualElement | RefObject&lt;Element | null&gt; | (() =&gt; Element | VirtualElement | null) | null">
+  An explicit positioning anchor for the popup.
+</ParamField>
+
+<ParamField body="Popup.arrow" type="boolean" default="false">
+  Displays an arrow pointing to the trigger. Defaults to false.
+</ParamField>
+
+<ParamField body="Popup.className" type="string | ((state: TooltipPopupState) =&gt; string | undefined)">
+  Additional CSS class for the popup.
+</ParamField>
+
+<ParamField body="Popup.collisionAvoidance" type="CollisionAvoidance">
+  Determines how to handle collisions when positioning the popup.
+
+  `side` controls overflow on the preferred placement axis (`top`/`bottom` or `left`/`right`):
+  - `'flip'`: keep the requested side when it fits; otherwise try the opposite side
+    (`top` and `bottom`, or `left` and `right`).
+  - `'shift'`: never change side; keep the requested side and move the popup within
+    the clipping boundary so it stays visible.
+  - `'none'`: do not correct side-axis overflow.
+
+  `align` controls overflow on the alignment axis (`start`/`center`/`end`):
+  - `'flip'`: keep side, but swap `start` and `end` when the requested alignment overflows.
+  - `'shift'`: keep side and requested alignment, then nudge the popup along the
+    alignment axis to fit.
+  - `'none'`: do not correct alignment-axis overflow.
+
+  `fallbackAxisSide` controls fallback behavior on the perpendicular axis when the
+  preferred axis cannot fit:
+  - `'start'`: allow perpendicular fallback and try the logical start side first
+    (`top` before `bottom`, or `left` before `right` in LTR).
+  - `'end'`: allow perpendicular fallback and try the logical end side first
+    (`bottom` before `top`, or `right` before `left` in LTR).
+  - `'none'`: do not fallback to the perpendicular axis.
+
+  When `side` is `'shift'`, explicitly setting `align` only supports `'shift'` or `'none'`.
+  If `align` is omitted, it defaults to `'flip'`.
+</ParamField>
+
+<ParamField body="Popup.collisionBoundary" type="Boundary" default="clipping-ancestors">
+  An element or a rectangle that delimits the area that the popup is confined to.
+</ParamField>
+
+<ParamField body="Popup.collisionPadding" type="Padding" default="5">
+  Additional space to maintain from the edge of the collision boundary.
+</ParamField>
+
+<ParamField body="Popup.container" type="HTMLElement | ShadowRoot | RefObject&lt;HTMLElement | ShadowRoot | null&gt; | null">
+  Portal destination. Defaults to the current theme container.
+</ParamField>
+
+<ParamField body="Popup.disableAnchorTracking" type="boolean" default="false">
+  Whether to disable the popup from tracking any layout shift of its positioning anchor.
+</ParamField>
+
+<ParamField body="Popup.keepMounted" type="boolean">
+  Keeps the popup mounted while closed.
+</ParamField>
+
+<ParamField body="Popup.maxWidth" type="MaxWidth&lt;string | number&gt;" default="300px">
+  Maximum popup width. Defaults to 300 pixels.
+</ParamField>
+
+<ParamField body="Popup.positionMethod" type="&quot;absolute&quot; | &quot;fixed&quot;" default="absolute">
+  CSS positioning method for the popup.
+</ParamField>
+
+<ParamField body="Popup.render" type="ReactElement&lt;unknown, string | JSXElementConstructor&lt;any&gt;&gt; | ComponentRenderFn&lt;HTMLProps, TooltipPopupState&gt;">
+  Allows you to replace the component's HTML element
+  with a different tag, or compose it with another component.
+
+  Accepts a `ReactElement` or a function that returns the element to render.
+</ParamField>
+
+<ParamField body="Popup.side" type="&quot;top&quot; | &quot;right&quot; | &quot;bottom&quot; | &quot;left&quot;" default="top">
+  Preferred side of the trigger. Defaults to top and may change to avoid collisions.
+</ParamField>
+
+<ParamField body="Popup.sideOffset" type="number | OffsetFunction" default="10">
+  Distance from the trigger in pixels. Defaults to 10.
+</ParamField>
+
+<ParamField body="Popup.sticky" type="boolean" default="false">
+  Whether to maintain the popup in the viewport after
+  the anchor element was scrolled out of view.
+</ParamField>
+
+<ParamField body="Popup.style" type="CSSProperties | ((state: TooltipPopupState) =&gt; CSSProperties | undefined)">
+  Inline styles for the popup.
+</ParamField>
+
+### Tooltip.Content
+
+<ParamField body="Content.description" type="ReactNode">
+  Secondary explanation beneath the primary text.
+</ParamField>
+
+<ParamField body="Content.render" type="ReactElement&lt;unknown, string | JSXElementConstructor&lt;any&gt;&gt; | ComponentRenderFn&lt;HTMLProps, {}&gt;">
+  Allows you to replace the component's HTML element
+  with a different tag, or compose it with another component.
+
+  Accepts a `ReactElement` or a function that returns the element to render.
+</ParamField>
+
+<ParamField body="Content.startIcon" type="ReactNode">
+  An icon displayed before the text.
+</ParamField>
+
+### Tooltip.Provider
+
+<ParamField body="Provider.closeDelay" type="number">
+  How long to wait before closing a tooltip. Specified in milliseconds.
+</ParamField>
+
+<ParamField body="Provider.delay" type="number">
+  How long to wait before opening the tooltip on hover. Specified in milliseconds.
+</ParamField>
+
+<ParamField body="Provider.timeout" type="number" default="400">
+  Another tooltip will open instantly if the previous tooltip
+  is closed within this timeout. Specified in milliseconds.
+</ParamField>