+ Click me
+
+ );
+
+ const element = result.getByRole('button');
+ const a11yRunner = createA11yTestRunner(result, {
+ keyboardNavigation: true,
+ screenReader: true,
+ focusManagement: true,
+ });
+
+ const testResults = await a11yRunner.runAllTests(element);
+ console.log('A11y test results:', testResults);
+ },
+};
+
+/**
+ * Example: Testing performance
+ */
+export const performanceExample = {
+ HeavyComponent: ({ items = [] }: { items?: any[] }) =>
+ React.createElement('div', {},
+ items.map((item, index) =>
+ React.createElement('div', { key: index }, `Item ${index}: ${item}`)
+ )
+ ),
+
+ async testRenderPerformance() {
+ const largeDataSet = Array.from({ length: 1000 }, (_, i) => `Data ${i}`);
+
+ await testComponentPerformance({
+ Component: this.HeavyComponent,
+ props: { items: largeDataSet },
+ thresholds: {
+ maxRenderTime: 200, // Allow more time for heavy component
+ maxUpdateTime: 100,
+ maxMemoryUsage: 20,
+ },
+ });
+ },
+};
diff --git a/packages/test/src/examples/real-component-tests.ts b/packages/test/src/examples/real-component-tests.ts
new file mode 100644
index 00000000..0aa77a82
--- /dev/null
+++ b/packages/test/src/examples/real-component-tests.ts
@@ -0,0 +1,272 @@
+/**
+ * Real-world examples of testing Flippo headless components
+ * These examples show how to test actual patterns used in your component library
+ */
+
+import * as React from 'react';
+import { vi, describe, it } from 'vitest';
+
+import {
+ createRenderer,
+ createHeadlessTestUtils,
+ testCompoundPatterns,
+ testAriaRelationships,
+ createA11yTestRunner,
+ testComponentPerformance,
+} from '../index';
+
+/**
+ * Example: Testing Avatar component with image loading states
+ */
+export function testAvatarComponent() {
+ describe('Avatar Component', () => {
+ const { render } = createRenderer();
+
+ it('should handle image loading states', async () => {
+ const onImageLoad = vi.fn();
+ const onImageError = vi.fn();
+
+ const result = render(
+ {/* Mock Avatar.Root */}
+ 
+
+ );
+
+ const utils = createHeadlessTestUtils(result);
+ const img = result.getByRole('img');
+
+ // Test successful image load
+ await utils.testEventHandler({
+ element: img,
+ event: 'load',
+ handler: onImageLoad,
+ });
+
+ // Test accessibility
+ utils.testAccessibilityAttributes(img, {
+ 'alt': 'Test Avatar',
+ 'aria-hidden': null, // Should not have aria-hidden
+ });
+ });
+
+ it('should meet performance requirements', async () => {
+ const MockAvatar = ({ src, alt }: any) =>
+ React.createElement('img', { src, alt, role: 'img' });
+
+ await testComponentPerformance({
+ Component: MockAvatar,
+ props: {
+ src: 'test-image.jpg',
+ alt: 'Performance test avatar',
+ },
+ thresholds: {
+ maxRenderTime: 20, // Very fast for simple image
+ maxUpdateTime: 10,
+ },
+ });
+ });
+ });
+}
+
+/**
+ * Example: Testing Dialog compound component
+ */
+export function testDialogComponent() {
+ describe('Dialog Component', () => {
+ const dialogTester = testCompoundPatterns().dialog;
+
+ it('should handle compound structure correctly', async () => {
+ const MockDialog = {
+ Root: ({ children }: any) => React.createElement('div', { 'data-dialog-root': true }, children),
+ Trigger: ({ children, ...props }: any) => React.createElement('button', { ...props }, children),
+ Portal: ({ children }: any) => React.createElement('div', { 'data-portal': true }, children),
+ Popup: ({ children, ...props }: any) => React.createElement('div', { role: 'dialog', ...props }, children),
+ };
+
+ const ui = (
+
+ Fallback
{/* Mock Avatar.Fallback */}
+
+
+
+
+
+ );
+
+ const utils = createHeadlessTestUtils(result);
+ const dialog = result.getByRole('dialog');
+
+ // Test escape key closes dialog
+ await utils.testKeyboardNavigation({
+ trigger: dialog,
+ key: 'Escape',
+ expectFocus: false,
+ });
+ });
+ });
+}
+
+/**
+ * Example: Testing Menu component with complex interactions
+ */
+export function testMenuComponent() {
+ describe('Menu Component', () => {
+ it('should handle arrow key navigation', async () => {
+ const { render } = createRenderer();
+
+ const result = render(
+
+
+ );
+
+ const utils = createHeadlessTestUtils(result);
+ const firstItem = result.getByTestId('item-1');
+ const secondItem = result.getByTestId('item-2');
+
+ // Test arrow down navigation
+ await utils.testKeyboardNavigation({
+ trigger: firstItem,
+ expectedTarget: secondItem,
+ key: 'ArrowDown',
+ });
+ });
+
+ it('should pass accessibility audit', async () => {
+ const { render } = createRenderer();
+
+ const result = render(
+ Item 1
+ Item 2
+ Item 3
+
+
+
+
+ );
+
+ const menu = result.getByRole('menu');
+ const a11yRunner = createA11yTestRunner(result, {
+ keyboardNavigation: true,
+ screenReader: true,
+ });
+
+ const results = await a11yRunner.runAllTests(menu);
+ expect(results.every(r => r.passed)).toBe(true);
+ });
+ });
+}
+
+/**
+ * Example: Testing form components
+ */
+export function testFormComponents() {
+ describe('Form Components', () => {
+ it('should handle field validation', async () => {
+ const { render } = createRenderer();
+ const onInvalid = vi.fn();
+
+ const result = render(
+
+ );
+
+ const utils = createHeadlessTestUtils(result);
+ const emailInput = result.getByTestId('email-input');
+
+ // Test validation
+ await utils.testEventHandler({
+ element: emailInput,
+ event: 'invalid',
+ handler: onInvalid,
+ });
+
+ // Test ARIA relationships
+ await testAriaRelationships({
+ renderResult: result,
+ relationships: [
+ {
+ source: 'email-input',
+ target: 'email-error',
+ attribute: 'aria-describedby',
+ },
+ ],
+ });
+ });
+ });
+}
+
+/**
+ * Example: Testing components with floating UI
+ */
+export function testFloatingComponents() {
+ describe('Floating Components', () => {
+ it('should position popover correctly', async () => {
+ const { render } = createRenderer();
+
+ const result = render(
+
+
+
+ );
+
+ const popup = result.getByTestId('popup');
+
+ // Custom matcher для проверки позиционирования
+ expect(popup).toBeProperlyPositioned({
+ top: 100,
+ left: 50,
+ });
+ });
+ });
+}
diff --git a/packages/test/src/examples/tooltip-integration.test.ts b/packages/test/src/examples/tooltip-integration.test.ts
new file mode 100644
index 00000000..f34ca932
--- /dev/null
+++ b/packages/test/src/examples/tooltip-integration.test.ts
@@ -0,0 +1,195 @@
+/**
+ * Example integration test showing how to use @flippo/internal-test-utils
+ * with actual Tooltip component from the headless components package
+ */
+
+import { describe, it, vi, beforeEach, afterEach } from 'vitest';
+import {
+ createRenderer,
+ createHeadlessTestUtils,
+ testAriaRelationships,
+ createA11yTestRunner,
+ testCommonEventPatterns,
+ expect,
+} from '../index';
+
+// This would normally be imported from your actual component package:
+// import { Tooltip } from '@flippo-ui/headless-components/tooltip';
+
+/**
+ * Mock Tooltip components for demonstration
+ * In real usage, you would import these from your component library
+ */
+const MockTooltip = {
+ Provider: ({ children }: any) =>
+ Popup content
+
+ {children}
,
+ Root: ({ children, onOpenChange }: any) => (
+
+ {children}
+
+ ),
+ Trigger: ({ children, ...props }: any) => (
+
+ ),
+ Portal: ({ children }: any) => (
+ {children}
+ ),
+ Positioner: ({ children }: any) => (
+ {children}
+ ),
+ Popup: ({ children, ...props }: any) => (
+
+ {children}
+
+ ),
+};
+
+describe('Tooltip Integration Test', () => {
+ const { render } = createRenderer();
+
+ beforeEach(() => {
+ vi.useFakeTimers();
+ });
+
+ afterEach(() => {
+ vi.useRealTimers();
+ });
+
+ it('should render and show/hide on hover', async () => {
+ const onOpenChange = vi.fn();
+
+ const result = render(
+ ` element.
+ *
+ * Documentation: [Base UI Accordion](https://base-ui.com/react/components/accordion)
+ */
+export function AccordionHeader(componentProps: AccordionHeader.Props) {
+ const {
+ /* eslint-disable unused-imports/no-unused-vars */
+ render,
+ className,
+ /* eslint-enable unused-imports/no-unused-vars */
+ ref,
+ ...elementProps
+ } = componentProps;
+
+ const { state } = useAccordionItemContext();
+
+ const element = useRenderElement('h3', componentProps, {
+ state,
+ ref,
+ props: elementProps,
+ customStyleHookMapping: accordionStyleHookMapping
+ });
+
+ return element;
+}
+
+export namespace AccordionHeader {
+ export type Props = HeadlessUIComponentProps<'h3', AccordionItem.State>;
+}
diff --git a/packages/ui/uikit/headless/components/src/components/Accordion/header/AccordionHeaderDataAttributes.ts b/packages/ui/uikit/headless/components/src/components/Accordion/header/AccordionHeaderDataAttributes.ts
new file mode 100644
index 00000000..3606b080
--- /dev/null
+++ b/packages/ui/uikit/headless/components/src/components/Accordion/header/AccordionHeaderDataAttributes.ts
@@ -0,0 +1,15 @@
+export enum AccordionHeaderDataAttributes {
+ /**
+ * Indicates the index of the accordion item.
+ * @type {number}
+ */
+ index = 'data-index',
+ /**
+ * Present when the accordion item is disabled.
+ */
+ disabled = 'data-disabled',
+ /**
+ * Present when the accordion item is open.
+ */
+ open = 'data-open'
+}
diff --git a/packages/ui/uikit/headless/components/src/components/Accordion/index.parts.ts b/packages/ui/uikit/headless/components/src/components/Accordion/index.parts.ts
new file mode 100644
index 00000000..c464c968
--- /dev/null
+++ b/packages/ui/uikit/headless/components/src/components/Accordion/index.parts.ts
@@ -0,0 +1,5 @@
+export { AccordionHeader as Header } from './header/AccordionHeader';
+export { AccordionItem as Item } from './item/AccordionItem';
+export { AccordionPanel as Panel } from './panel/AccordionPanel';
+export { AccordionRoot as Root } from './root/AccordionRoot';
+export { AccordionTrigger as Trigger } from './trigger/AccordionTrigger';
diff --git a/packages/ui/uikit/headless/components/src/components/Accordion/index.ts b/packages/ui/uikit/headless/components/src/components/Accordion/index.ts
new file mode 100644
index 00000000..bc75beb6
--- /dev/null
+++ b/packages/ui/uikit/headless/components/src/components/Accordion/index.ts
@@ -0,0 +1 @@
+export * as Accordion from './index.parts';
diff --git a/packages/ui/uikit/headless/components/src/components/Accordion/item/AccordionItem.tsx b/packages/ui/uikit/headless/components/src/components/Accordion/item/AccordionItem.tsx
new file mode 100644
index 00000000..4927f1b9
--- /dev/null
+++ b/packages/ui/uikit/headless/components/src/components/Accordion/item/AccordionItem.tsx
@@ -0,0 +1,162 @@
+'use client';
+
+import React from 'react';
+
+import { useEventCallback, useMergedRef } from '@flippo_ui/hooks';
+
+import { EMPTY_OBJECT } from '@lib/constants';
+import { useHeadlessUiId, useRenderElement } from '@lib/hooks';
+
+import type { HeadlessUIComponentProps } from '@lib/types';
+
+import { CollapsibleRootContext } from '../../Collapsible/root/CollapsibleRootContext';
+import { useCollapsibleRoot } from '../../Collapsible/root/useCollapsibleRoot';
+import { useCompositeListItem } from '../../Composite/list/useCompositeListItem';
+import { useAccordionRootContext } from '../root/AccordionRootContext';
+
+import type { CollapsibleRoot } from '../../Collapsible/root/CollapsibleRoot';
+import type { TCollapsibleRootContext } from '../../Collapsible/root/CollapsibleRootContext';
+import type { AccordionRoot } from '../root/AccordionRoot';
+
+import { AccordionItemContext } from './AccordionItemContext';
+import { accordionStyleHookMapping } from './styleHooks';
+
+import type { TAccordionItemContext } from './AccordionItemContext';
+
+/**
+ * Groups an accordion header with the corresponding panel.
+ * Renders a `` element.
+ *
+ * Documentation: [Base UI Accordion](https://base-ui.com/react/components/accordion)
+ */
+export function AccordionItem(componentProps: AccordionItem.Props) {
+ const {
+ /* eslint-disable unused-imports/no-unused-vars */
+ className,
+ render,
+ /* eslint-enable unused-imports/no-unused-vars */
+ disabled: disabledProp = false,
+ onOpenChange: onOpenChangeProp,
+ value: valueProp,
+ ref,
+ ...elementProps
+ } = componentProps;
+
+ const { ref: listItemRef, index } = useCompositeListItem(EMPTY_OBJECT);
+ const mergedRef = useMergedRef(ref, listItemRef);
+
+ const {
+ disabled: contextDisabled,
+ handleValueChange,
+ state: rootState,
+ value: openValues
+ } = useAccordionRootContext();
+
+ const value = valueProp ?? index;
+
+ const disabled = disabledProp || contextDisabled;
+
+ const isOpen = React.useMemo(() => {
+ if (!openValues) {
+ return false;
+ }
+
+ for (let i = 0; i < openValues.length; i += 1) {
+ if (openValues[i] === value) {
+ return true;
+ }
+ }
+
+ return false;
+ }, [openValues, value]);
+
+ const onOpenChange = useEventCallback((nextOpen: boolean) => {
+ handleValueChange(value, nextOpen);
+ onOpenChangeProp?.(nextOpen);
+ });
+
+ const collapsible = useCollapsibleRoot({
+ open: isOpen,
+ onOpenChange,
+ disabled
+ });
+
+ const collapsibleState: CollapsibleRoot.State = React.useMemo(
+ () => ({
+ open: collapsible.open,
+ disabled: collapsible.disabled,
+ hidden: !collapsible.mounted
+ }),
+ [collapsible.open, collapsible.disabled, collapsible.mounted]
+ );
+
+ const collapsibleContext: TCollapsibleRootContext = React.useMemo(
+ () => ({
+ ...collapsible,
+ onOpenChange,
+ state: collapsibleState,
+ transitionStatus: collapsible.transitionStatus
+ }),
+ [collapsible, collapsibleState, onOpenChange]
+ );
+
+ const state: AccordionItem.State = React.useMemo(
+ () => ({
+ ...rootState,
+ index,
+ disabled,
+ open: isOpen
+ }),
+ [
+ disabled,
+ index,
+ isOpen,
+ rootState
+ ]
+ );
+
+ const [triggerId, setTriggerId] = React.useState(useHeadlessUiId());
+
+ const accordionItemContext: TAccordionItemContext = React.useMemo(
+ () => ({
+ open: isOpen,
+ state,
+ setTriggerId,
+ triggerId
+ }),
+ [
+ isOpen,
+ state,
+ setTriggerId,
+ triggerId
+ ]
+ );
+
+ const element = useRenderElement('div', componentProps, {
+ state,
+ ref: mergedRef,
+ props: elementProps,
+ customStyleHookMapping: accordionStyleHookMapping
+ });
+
+ return (
+
+
+ {element}
+
+
+ );
+}
+
+export type AccordionItemValue = any | null;
+
+export namespace AccordionItem {
+ export type State = {
+ index: number;
+ open: boolean;
+ } & AccordionRoot.State;
+
+ export type Props = {
+ value?: AccordionItemValue;
+ } & HeadlessUIComponentProps<'div', State> & Partial>;
+}
diff --git a/packages/ui/uikit/headless/components/src/components/Accordion/item/AccordionItemContext.ts b/packages/ui/uikit/headless/components/src/components/Accordion/item/AccordionItemContext.ts
new file mode 100644
index 00000000..a50cac90
--- /dev/null
+++ b/packages/ui/uikit/headless/components/src/components/Accordion/item/AccordionItemContext.ts
@@ -0,0 +1,27 @@
+'use client';
+
+import React from 'react';
+
+import type { AccordionItem } from './AccordionItem';
+
+export type TAccordionItemContext = {
+ open: boolean;
+ state: AccordionItem.State;
+ setTriggerId: (id: string | undefined) => void;
+ triggerId?: string;
+};
+
+export const AccordionItemContext = React.createContext(
+ undefined
+);
+
+export function useAccordionItemContext() {
+ const context = React.use(AccordionItemContext);
+
+ if (context === undefined) {
+ throw new Error(
+ 'Headless UI: AccordionItemContext is missing. Accordion parts must be placed within .'
+ );
+ }
+ return context;
+}
diff --git a/packages/ui/uikit/headless/components/src/components/Accordion/item/AccordionItemDataAttributes.ts b/packages/ui/uikit/headless/components/src/components/Accordion/item/AccordionItemDataAttributes.ts
new file mode 100644
index 00000000..7362230b
--- /dev/null
+++ b/packages/ui/uikit/headless/components/src/components/Accordion/item/AccordionItemDataAttributes.ts
@@ -0,0 +1,15 @@
+export enum AccordionItemDataAttributes {
+ /**
+ * Indicates the index of the accordion item.
+ * @type {number}
+ */
+ index = 'data-index',
+ /**
+ * Present when the accordion item is disabled.
+ */
+ disabled = 'data-disabled',
+ /**
+ * Present when the accordion item is open.
+ */
+ open = 'data-open'
+}
diff --git a/packages/ui/uikit/headless/components/src/components/Accordion/item/styleHooks.ts b/packages/ui/uikit/headless/components/src/components/Accordion/item/styleHooks.ts
new file mode 100644
index 00000000..423cbd76
--- /dev/null
+++ b/packages/ui/uikit/headless/components/src/components/Accordion/item/styleHooks.ts
@@ -0,0 +1,17 @@
+import { collapsibleOpenStateMapping } from '@lib/collapsibleOpenStateMapping';
+import { transitionStatusMapping } from '@lib/styleHookMapping';
+
+import type { CustomStyleHookMapping } from '@lib/getStyleHookProps';
+
+import { AccordionItemDataAttributes } from './AccordionItemDataAttributes';
+
+import type { AccordionItem } from './AccordionItem';
+
+export const accordionStyleHookMapping: CustomStyleHookMapping = {
+ ...collapsibleOpenStateMapping,
+ index: (value) => {
+ return Number.isInteger(value) ? { [AccordionItemDataAttributes.index]: String(value) } : null;
+ },
+ ...transitionStatusMapping,
+ value: () => null
+};
diff --git a/packages/ui/uikit/headless/components/src/components/Accordion/panel/AccordionPanel.tsx b/packages/ui/uikit/headless/components/src/components/Accordion/panel/AccordionPanel.tsx
new file mode 100644
index 00000000..757760d0
--- /dev/null
+++ b/packages/ui/uikit/headless/components/src/components/Accordion/panel/AccordionPanel.tsx
@@ -0,0 +1,176 @@
+'use client';
+
+import React from 'react';
+
+import { useIsoLayoutEffect, useOpenChangeComplete } from '@flippo_ui/hooks';
+
+import type { TransitionStatus } from '@flippo_ui/hooks';
+
+import { useRenderElement } from '@lib/hooks';
+import { warn } from '@lib/warn';
+
+import type { HeadlessUIComponentProps } from '@lib/types';
+
+import { useCollapsiblePanel } from '../../Collapsible/panel/useCollapsiblePanel';
+import { useCollapsibleRootContext } from '../../Collapsible/root/CollapsibleRootContext';
+import { useAccordionItemContext } from '../item/AccordionItemContext';
+import { accordionStyleHookMapping } from '../item/styleHooks';
+import { useAccordionRootContext } from '../root/AccordionRootContext';
+
+import type { AccordionItem } from '../item/AccordionItem';
+import type { AccordionRoot } from '../root/AccordionRoot';
+
+import { AccordionPanelCssVars } from './AccordionPanelCssVars';
+
+/**
+ * A collapsible panel with the accordion item contents.
+ * Renders a `` element.
+ *
+ * Documentation: [Base UI Accordion](https://base-ui.com/react/components/accordion)
+ */
+export function AccordionPanel(componentProps: AccordionPanel.Props) {
+ const {
+ /* eslint-disable unused-imports/no-unused-vars */
+ className,
+ render,
+ /* eslint-enable unused-imports/no-unused-vars */
+ hiddenUntilFound: hiddenUntilFoundProp,
+ keepMounted: keepMountedProp,
+ id: idProp,
+ ref,
+ ...elementProps
+ } = componentProps;
+
+ const { hiddenUntilFound: contextHiddenUntilFound, keepMounted: contextKeepMounted }
+ = useAccordionRootContext();
+
+ const {
+ abortControllerRef,
+ animationTypeRef,
+ height,
+ mounted,
+ onOpenChange,
+ open,
+ panelId,
+ panelRef,
+ runOnceAnimationsFinish,
+ setDimensions,
+ setHiddenUntilFound,
+ setKeepMounted,
+ setMounted,
+ setOpen,
+ setVisible,
+ transitionDimensionRef,
+ visible,
+ width,
+ setPanelIdState,
+ transitionStatus
+ } = useCollapsibleRootContext();
+
+ const hiddenUntilFound = hiddenUntilFoundProp ?? contextHiddenUntilFound;
+ const keepMounted = keepMountedProp ?? contextKeepMounted;
+
+ if (process.env.NODE_ENV !== 'production') {
+ // eslint-disable-next-line react-hooks/rules-of-hooks
+ useIsoLayoutEffect(() => {
+ if (keepMountedProp === false && hiddenUntilFound) {
+ warn(
+ 'The `keepMounted={false}` prop on a Accordion.Panel will be ignored when using `contextHiddenUntilFound` on the Panel or the Root since it requires the panel to remain mounted when closed.'
+ );
+ }
+ }, [hiddenUntilFound, keepMountedProp]);
+ }
+
+ useIsoLayoutEffect(() => {
+ if (idProp) {
+ setPanelIdState(idProp);
+ return () => {
+ setPanelIdState(undefined);
+ };
+ }
+ return undefined;
+ }, [idProp, setPanelIdState]);
+
+ useIsoLayoutEffect(() => {
+ setHiddenUntilFound(hiddenUntilFound);
+ }, [setHiddenUntilFound, hiddenUntilFound]);
+
+ useIsoLayoutEffect(() => {
+ setKeepMounted(keepMounted);
+ }, [setKeepMounted, keepMounted]);
+
+ useOpenChangeComplete({
+ open: open && transitionStatus === 'idle',
+ ref: panelRef,
+ onComplete() {
+ if (!open) {
+ return;
+ }
+
+ setDimensions({ width: undefined, height: undefined });
+ }
+ });
+
+ const { props } = useCollapsiblePanel({
+ abortControllerRef,
+ animationTypeRef,
+ externalRef: ref,
+ height,
+ hiddenUntilFound,
+ id: idProp ?? panelId,
+ keepMounted,
+ mounted,
+ onOpenChange,
+ open,
+ panelRef,
+ runOnceAnimationsFinish,
+ setDimensions,
+ setMounted,
+ setOpen,
+ setVisible,
+ transitionDimensionRef,
+ visible,
+ width
+ });
+
+ const { state, triggerId } = useAccordionItemContext();
+
+ const panelState: AccordionPanel.State = React.useMemo(
+ () => ({
+ ...state,
+ transitionStatus
+ }),
+ [state, transitionStatus]
+ );
+
+ const element = useRenderElement('div', componentProps, {
+ state: panelState,
+ ref: [ref, panelRef],
+ props: [props, {
+ 'aria-labelledby': triggerId,
+ 'role': 'region',
+ 'style': {
+ [AccordionPanelCssVars.accordionPanelHeight as string]:
+ height === undefined ? 'auto' : `${height}px`,
+ [AccordionPanelCssVars.accordionPanelWidth as string]:
+ width === undefined ? 'auto' : `${width}px`
+ }
+ }, elementProps],
+ customStyleHookMapping: accordionStyleHookMapping
+ });
+
+ const shouldRender = keepMounted || hiddenUntilFound || (!keepMounted && mounted);
+ if (!shouldRender) {
+ return null;
+ }
+
+ return element;
+}
+
+export namespace AccordionPanel {
+ export type State = {
+ transitionStatus: TransitionStatus;
+ } & AccordionItem.State;
+
+ export type Props = { ref: React.RefObject } & Omit, 'ref'> & Pick;
+}
diff --git a/packages/ui/uikit/headless/components/src/components/Accordion/panel/AccordionPanelCssVars.ts b/packages/ui/uikit/headless/components/src/components/Accordion/panel/AccordionPanelCssVars.ts
new file mode 100644
index 00000000..b81dd27a
--- /dev/null
+++ b/packages/ui/uikit/headless/components/src/components/Accordion/panel/AccordionPanelCssVars.ts
@@ -0,0 +1,12 @@
+export enum AccordionPanelCssVars {
+ /**
+ * The accordion panel's height.
+ * @type {number}
+ */
+ accordionPanelHeight = '--accordion-panel-height',
+ /**
+ * The accordion panel's width.
+ * @type {number}
+ */
+ accordionPanelWidth = '--accordion-panel-width'
+}
diff --git a/packages/ui/uikit/headless/components/src/components/Accordion/panel/AccordionPanelDataAttributes.ts b/packages/ui/uikit/headless/components/src/components/Accordion/panel/AccordionPanelDataAttributes.ts
new file mode 100644
index 00000000..4cd381cf
--- /dev/null
+++ b/packages/ui/uikit/headless/components/src/components/Accordion/panel/AccordionPanelDataAttributes.ts
@@ -0,0 +1,29 @@
+import { TransitionStatusDataAttributes } from '@lib/styleHookMapping';
+
+export enum AccordionPanelDataAttributes {
+ /**
+ * Indicates the index of the accordion item.
+ * @type {number}
+ */
+ index = 'data-index',
+ /**
+ * Present when the accordion panel is open.
+ */
+ open = 'data-open',
+ /**
+ * Indicates the orientation of the accordion.
+ */
+ orientation = 'data-orientation',
+ /**
+ * Present when the accordion item is disabled.
+ */
+ disabled = 'data-disabled',
+ /**
+ * Present when the panel is animating in.
+ */
+ startingStyle = TransitionStatusDataAttributes.startingStyle,
+ /**
+ * Present when the panel is animating out.
+ */
+ endingStyle = TransitionStatusDataAttributes.endingStyle
+}
diff --git a/packages/ui/uikit/headless/components/src/components/Accordion/root/AccordionRoot.tsx b/packages/ui/uikit/headless/components/src/components/Accordion/root/AccordionRoot.tsx
new file mode 100644
index 00000000..240801b2
--- /dev/null
+++ b/packages/ui/uikit/headless/components/src/components/Accordion/root/AccordionRoot.tsx
@@ -0,0 +1,226 @@
+'use client';
+
+import React from 'react';
+
+import { useControlledState, useEventCallback, useIsoLayoutEffect } from '@flippo_ui/hooks';
+
+import { useDirection, useRenderElement } from '@lib/hooks';
+import { warn } from '@lib/warn';
+
+import type { HeadlessUIComponentProps, Orientation } from '@lib/types';
+
+import { CompositeList } from '../../Composite/list/CompositeList';
+
+import { AccordionRootContext } from './AccordionRootContext';
+
+import type { TAccordionRootContext } from './AccordionRootContext';
+
+const rootStyleHookMapping = {
+ value: () => null
+};
+
+/**
+ * Groups all parts of the accordion.
+ * Renders a `` element.
+ *
+ * Documentation: [Base UI Accordion](https://base-ui.com/react/components/accordion)
+ */
+export function AccordionRoot(componentProps: AccordionRoot.Props) {
+ const {
+ /* eslint-disable unused-imports/no-unused-vars */
+ render,
+ className,
+ /* eslint-enable unused-imports/no-unused-vars */
+ disabled = false,
+ hiddenUntilFound: hiddenUntilFoundProp,
+ keepMounted: keepMountedProp,
+ loop = true,
+ onValueChange: onValueChangeProp,
+ openMultiple = true,
+ orientation = 'vertical',
+ value: valueProp,
+ defaultValue: defaultValueProp,
+ ref,
+ ...elementProps
+ } = componentProps;
+
+ const direction = useDirection();
+
+ if (process.env.NODE_ENV !== 'production') {
+ // eslint-disable-next-line react-hooks/rules-of-hooks
+ useIsoLayoutEffect(() => {
+ if (hiddenUntilFoundProp && keepMountedProp === false) {
+ warn(
+ 'The `keepMounted={false}` prop on a Accordion.Root will be ignored when using `hiddenUntilFound` since it requires Panels to remain mounted when closed.'
+ );
+ }
+ }, [hiddenUntilFoundProp, keepMountedProp]);
+ }
+
+ // memoized to allow omitting both defaultValue and value
+ // which would otherwise trigger a warning in useControlled
+ const defaultValue = React.useMemo(() => {
+ if (valueProp === undefined) {
+ return defaultValueProp ?? [];
+ }
+
+ return [];
+ }, [valueProp, defaultValueProp]);
+
+ const onValueChange = useEventCallback(onValueChangeProp);
+
+ const accordionItemRefs = React.useRef<(HTMLElement | null)[]>([]);
+
+ const [value, setValue] = useControlledState({
+ prop: valueProp,
+ defaultProp: defaultValue,
+ caller: 'Accordion'
+ });
+
+ const handleValueChange = React.useCallback(
+ (newValue: number | string, nextOpen: boolean) => {
+ if (!openMultiple) {
+ const nextValue = value[0] === newValue ? [] : [newValue];
+ setValue(nextValue);
+ onValueChange(nextValue);
+ }
+ else if (nextOpen) {
+ const nextOpenValues = value.slice();
+ nextOpenValues.push(newValue);
+ setValue(nextOpenValues);
+ onValueChange(nextOpenValues);
+ }
+ else {
+ const nextOpenValues = value.filter((v) => v !== newValue);
+ setValue(nextOpenValues);
+ onValueChange(nextOpenValues);
+ }
+ },
+ [
+ onValueChange,
+ openMultiple,
+ setValue,
+ value
+ ]
+ );
+
+ const state: AccordionRoot.State = React.useMemo(
+ () => ({
+ value,
+ disabled,
+ orientation
+ }),
+ [value, disabled, orientation]
+ );
+
+ const contextValue: TAccordionRootContext = React.useMemo(
+ () => ({
+ accordionItemRefs,
+ direction,
+ disabled,
+ handleValueChange,
+ hiddenUntilFound: hiddenUntilFoundProp ?? false,
+ keepMounted: keepMountedProp ?? false,
+ loop,
+ orientation,
+ state,
+ value
+ }),
+ [
+ direction,
+ disabled,
+ handleValueChange,
+ hiddenUntilFoundProp,
+ keepMountedProp,
+ loop,
+ orientation,
+ state,
+ value
+ ]
+ );
+
+ const element = useRenderElement('div', componentProps, {
+ state,
+ ref,
+ props: [{
+ dir: direction,
+ role: 'region'
+ }, elementProps],
+ customStyleHookMapping: rootStyleHookMapping
+ });
+
+ return (
+
+ {element}
+
+ );
+}
+
+export type AccordionValue = (any | null)[];
+
+export namespace AccordionRoot {
+ export type State = {
+ value: AccordionValue;
+ /**
+ * Whether the component should ignore user interaction.
+ */
+ disabled: boolean;
+ orientation: Orientation;
+ };
+
+ export type Props = {
+ /**
+ * The controlled value of the item(s) that should be expanded.
+ *
+ * To render an uncontrolled accordion, use the `defaultValue` prop instead.
+ */
+ value?: AccordionValue;
+ /**
+ * The uncontrolled value of the item(s) that should be initially expanded.
+ *
+ * To render a controlled accordion, use the `value` prop instead.
+ */
+ defaultValue?: AccordionValue;
+ /**
+ * Whether the component should ignore user interaction.
+ * @default false
+ */
+ disabled?: boolean;
+ /**
+ * Allows the browser’s built-in page search to find and expand the panel contents.
+ *
+ * Overrides the `keepMounted` prop and uses `hidden="until-found"`
+ * to hide the element without removing it from the DOM.
+ * @default false
+ */
+ hiddenUntilFound?: boolean;
+ /**
+ * Whether to keep the element in the DOM while the panel is closed.
+ * This prop is ignored when `hiddenUntilFound` is used.
+ * @default false
+ */
+ keepMounted?: boolean;
+ /**
+ * Whether to loop keyboard focus back to the first item
+ * when the end of the list is reached while using the arrow keys.
+ * @default true
+ */
+ loop?: boolean;
+ /**
+ * Event handler called when an accordion item is expanded or collapsed.
+ * Provides the new value as an argument.
+ */
+ onValueChange?: (value: AccordionValue) => void;
+ /**
+ * Whether multiple items can be open at the same time.
+ * @default true
+ */
+ openMultiple?: boolean;
+ /**
+ * The visual orientation of the accordion.
+ * Controls whether roving focus uses left/right or up/down arrow keys.
+ * @default 'vertical'
+ */
+ orientation?: Orientation;
+ } & HeadlessUIComponentProps<'div', State>;
+}
diff --git a/packages/ui/uikit/headless/components/src/components/Accordion/root/AccordionRootContext.ts b/packages/ui/uikit/headless/components/src/components/Accordion/root/AccordionRootContext.ts
new file mode 100644
index 00000000..dd0af0b2
--- /dev/null
+++ b/packages/ui/uikit/headless/components/src/components/Accordion/root/AccordionRootContext.ts
@@ -0,0 +1,35 @@
+'use client';
+import * as React from 'react';
+
+import type { TTextDirection } from '@lib/hooks';
+import type { Orientation } from '@lib/types';
+
+import type { AccordionRoot, AccordionValue } from './AccordionRoot';
+
+export type TAccordionRootContext = {
+ accordionItemRefs: React.RefObject<(HTMLElement | null)[]>;
+ direction: TTextDirection;
+ disabled: boolean;
+ handleValueChange: (newValue: number | string, nextOpen: boolean) => void;
+ hiddenUntilFound: boolean;
+ keepMounted: boolean;
+ loop: boolean;
+ orientation: Orientation;
+ state: AccordionRoot.State;
+ value: AccordionValue;
+};
+
+export const AccordionRootContext = React.createContext(
+ undefined
+);
+
+export function useAccordionRootContext() {
+ const context = React.use(AccordionRootContext);
+
+ if (context === undefined) {
+ throw new Error(
+ 'Headless UI: AccordionRootContext is missing. Accordion parts must be placed within .'
+ );
+ }
+ return context;
+}
diff --git a/packages/ui/uikit/headless/components/src/components/Accordion/root/AccordionRootDataAttributes.ts b/packages/ui/uikit/headless/components/src/components/Accordion/root/AccordionRootDataAttributes.ts
new file mode 100644
index 00000000..34abbca4
--- /dev/null
+++ b/packages/ui/uikit/headless/components/src/components/Accordion/root/AccordionRootDataAttributes.ts
@@ -0,0 +1,10 @@
+export enum AccordionRootDataAttributes {
+ /**
+ * Present when the accordion is disabled.
+ */
+ disabled = 'data-disabled',
+ /**
+ * Indicates the orientation of the accordion.
+ */
+ orientation = 'data-orientation'
+}
diff --git a/packages/ui/uikit/headless/components/src/components/Accordion/trigger/AccordionTrigger.tsx b/packages/ui/uikit/headless/components/src/components/Accordion/trigger/AccordionTrigger.tsx
new file mode 100644
index 00000000..369d7a38
--- /dev/null
+++ b/packages/ui/uikit/headless/components/src/components/Accordion/trigger/AccordionTrigger.tsx
@@ -0,0 +1,226 @@
+'use client';
+
+import React from 'react';
+
+import { useIsoLayoutEffect } from '@flippo_ui/hooks';
+
+import { triggerOpenStateMapping } from '@lib/collapsibleOpenStateMapping';
+import { useRenderElement } from '@lib/hooks';
+import { isElementDisabled } from '@lib/isElementDisabled';
+
+import type { HeadlessUIComponentProps, NativeButtonProps } from '@lib/types';
+
+import { useCollapsibleRootContext } from '../../Collapsible/root/CollapsibleRootContext';
+import {
+ ARROW_DOWN,
+ ARROW_LEFT,
+ ARROW_RIGHT,
+ ARROW_UP,
+ END,
+ HOME,
+ stopEvent
+} from '../../Composite/composite';
+import { useButton } from '../../use-button';
+import { useAccordionItemContext } from '../item/AccordionItemContext';
+import { useAccordionRootContext } from '../root/AccordionRootContext';
+
+import type { AccordionItem } from '../item/AccordionItem';
+
+const SUPPORTED_KEYS = new Set([
+ ARROW_DOWN,
+ ARROW_UP,
+ ARROW_RIGHT,
+ ARROW_LEFT,
+ HOME,
+ END
+]);
+
+function getActiveTriggers(accordionItemRefs: {
+ current: (HTMLElement | null)[];
+}): HTMLButtonElement[] {
+ const { current: accordionItemElements } = accordionItemRefs;
+
+ const output: HTMLButtonElement[] = [];
+
+ for (let i = 0; i < accordionItemElements.length; i += 1) {
+ const section = accordionItemElements[i];
+ if (!isElementDisabled(section)) {
+ const trigger = section?.querySelector('[type="button"]') as HTMLButtonElement;
+ if (!isElementDisabled(trigger)) {
+ output.push(trigger);
+ }
+ }
+ }
+
+ return output;
+}
+
+/**
+ * A button that opens and closes the corresponding panel.
+ * Renders a `
` element.
+ *
+ * Documentation: [Base UI Accordion](https://base-ui.com/react/components/accordion)
+ */
+export function AccordionPanel(componentProps: AccordionPanel.Props) {
+ const {
+ /* eslint-disable unused-imports/no-unused-vars */
+ className,
+ render,
+ /* eslint-enable unused-imports/no-unused-vars */
+ hiddenUntilFound: hiddenUntilFoundProp,
+ keepMounted: keepMountedProp,
+ id: idProp,
+ ref,
+ ...elementProps
+ } = componentProps;
+
+ const { hiddenUntilFound: contextHiddenUntilFound, keepMounted: contextKeepMounted }
+ = useAccordionRootContext();
+
+ const {
+ abortControllerRef,
+ animationTypeRef,
+ height,
+ mounted,
+ onOpenChange,
+ open,
+ panelId,
+ panelRef,
+ runOnceAnimationsFinish,
+ setDimensions,
+ setHiddenUntilFound,
+ setKeepMounted,
+ setMounted,
+ setOpen,
+ setVisible,
+ transitionDimensionRef,
+ visible,
+ width,
+ setPanelIdState,
+ transitionStatus
+ } = useCollapsibleRootContext();
+
+ const hiddenUntilFound = hiddenUntilFoundProp ?? contextHiddenUntilFound;
+ const keepMounted = keepMountedProp ?? contextKeepMounted;
+
+ if (process.env.NODE_ENV !== 'production') {
+ // eslint-disable-next-line react-hooks/rules-of-hooks
+ useIsoLayoutEffect(() => {
+ if (keepMountedProp === false && hiddenUntilFound) {
+ warn(
+ 'The `keepMounted={false}` prop on a Accordion.Panel will be ignored when using `contextHiddenUntilFound` on the Panel or the Root since it requires the panel to remain mounted when closed.'
+ );
+ }
+ }, [hiddenUntilFound, keepMountedProp]);
+ }
+
+ useIsoLayoutEffect(() => {
+ if (idProp) {
+ setPanelIdState(idProp);
+ return () => {
+ setPanelIdState(undefined);
+ };
+ }
+ return undefined;
+ }, [idProp, setPanelIdState]);
+
+ useIsoLayoutEffect(() => {
+ setHiddenUntilFound(hiddenUntilFound);
+ }, [setHiddenUntilFound, hiddenUntilFound]);
+
+ useIsoLayoutEffect(() => {
+ setKeepMounted(keepMounted);
+ }, [setKeepMounted, keepMounted]);
+
+ useOpenChangeComplete({
+ open: open && transitionStatus === 'idle',
+ ref: panelRef,
+ onComplete() {
+ if (!open) {
+ return;
+ }
+
+ setDimensions({ width: undefined, height: undefined });
+ }
+ });
+
+ const { props } = useCollapsiblePanel({
+ abortControllerRef,
+ animationTypeRef,
+ externalRef: ref,
+ height,
+ hiddenUntilFound,
+ id: idProp ?? panelId,
+ keepMounted,
+ mounted,
+ onOpenChange,
+ open,
+ panelRef,
+ runOnceAnimationsFinish,
+ setDimensions,
+ setMounted,
+ setOpen,
+ setVisible,
+ transitionDimensionRef,
+ visible,
+ width
+ });
+
+ const { state, triggerId } = useAccordionItemContext();
+
+ const panelState: AccordionPanel.State = React.useMemo(
+ () => ({
+ ...state,
+ transitionStatus
+ }),
+ [state, transitionStatus]
+ );
+
+ const element = useRenderElement('div', componentProps, {
+ state: panelState,
+ ref: [ref, panelRef],
+ props: [props, {
+ 'aria-labelledby': triggerId,
+ 'role': 'region',
+ 'style': {
+ [AccordionPanelCssVars.accordionPanelHeight as string]:
+ height === undefined ? 'auto' : `${height}px`,
+ [AccordionPanelCssVars.accordionPanelWidth as string]:
+ width === undefined ? 'auto' : `${width}px`
+ }
+ }, elementProps],
+ customStyleHookMapping: accordionStyleHookMapping
+ });
+
+ const shouldRender = keepMounted || hiddenUntilFound || (!keepMounted && mounted);
+ if (!shouldRender) {
+ return null;
+ }
+
+ return element;
+}
+
+export namespace AccordionPanel {
+ export type State = {
+ transitionStatus: TransitionStatus;
+ } & AccordionItem.State;
+
+ export type Props = { ref: React.RefObject } & Omit, 'ref'> & Pick;
+}
diff --git a/packages/ui/uikit/headless/components/src/components/Accordion/panel/AccordionPanelCssVars.ts b/packages/ui/uikit/headless/components/src/components/Accordion/panel/AccordionPanelCssVars.ts
new file mode 100644
index 00000000..b81dd27a
--- /dev/null
+++ b/packages/ui/uikit/headless/components/src/components/Accordion/panel/AccordionPanelCssVars.ts
@@ -0,0 +1,12 @@
+export enum AccordionPanelCssVars {
+ /**
+ * The accordion panel's height.
+ * @type {number}
+ */
+ accordionPanelHeight = '--accordion-panel-height',
+ /**
+ * The accordion panel's width.
+ * @type {number}
+ */
+ accordionPanelWidth = '--accordion-panel-width'
+}
diff --git a/packages/ui/uikit/headless/components/src/components/Accordion/panel/AccordionPanelDataAttributes.ts b/packages/ui/uikit/headless/components/src/components/Accordion/panel/AccordionPanelDataAttributes.ts
new file mode 100644
index 00000000..4cd381cf
--- /dev/null
+++ b/packages/ui/uikit/headless/components/src/components/Accordion/panel/AccordionPanelDataAttributes.ts
@@ -0,0 +1,29 @@
+import { TransitionStatusDataAttributes } from '@lib/styleHookMapping';
+
+export enum AccordionPanelDataAttributes {
+ /**
+ * Indicates the index of the accordion item.
+ * @type {number}
+ */
+ index = 'data-index',
+ /**
+ * Present when the accordion panel is open.
+ */
+ open = 'data-open',
+ /**
+ * Indicates the orientation of the accordion.
+ */
+ orientation = 'data-orientation',
+ /**
+ * Present when the accordion item is disabled.
+ */
+ disabled = 'data-disabled',
+ /**
+ * Present when the panel is animating in.
+ */
+ startingStyle = TransitionStatusDataAttributes.startingStyle,
+ /**
+ * Present when the panel is animating out.
+ */
+ endingStyle = TransitionStatusDataAttributes.endingStyle
+}
diff --git a/packages/ui/uikit/headless/components/src/components/Accordion/root/AccordionRoot.tsx b/packages/ui/uikit/headless/components/src/components/Accordion/root/AccordionRoot.tsx
new file mode 100644
index 00000000..240801b2
--- /dev/null
+++ b/packages/ui/uikit/headless/components/src/components/Accordion/root/AccordionRoot.tsx
@@ -0,0 +1,226 @@
+'use client';
+
+import React from 'react';
+
+import { useControlledState, useEventCallback, useIsoLayoutEffect } from '@flippo_ui/hooks';
+
+import { useDirection, useRenderElement } from '@lib/hooks';
+import { warn } from '@lib/warn';
+
+import type { HeadlessUIComponentProps, Orientation } from '@lib/types';
+
+import { CompositeList } from '../../Composite/list/CompositeList';
+
+import { AccordionRootContext } from './AccordionRootContext';
+
+import type { TAccordionRootContext } from './AccordionRootContext';
+
+const rootStyleHookMapping = {
+ value: () => null
+};
+
+/**
+ * Groups all parts of the accordion.
+ * Renders a `
` element.
+ *
+ * Documentation: [Base UI Accordion](https://base-ui.com/react/components/accordion)
+ */
+export function AccordionRoot(componentProps: AccordionRoot.Props) {
+ const {
+ /* eslint-disable unused-imports/no-unused-vars */
+ render,
+ className,
+ /* eslint-enable unused-imports/no-unused-vars */
+ disabled = false,
+ hiddenUntilFound: hiddenUntilFoundProp,
+ keepMounted: keepMountedProp,
+ loop = true,
+ onValueChange: onValueChangeProp,
+ openMultiple = true,
+ orientation = 'vertical',
+ value: valueProp,
+ defaultValue: defaultValueProp,
+ ref,
+ ...elementProps
+ } = componentProps;
+
+ const direction = useDirection();
+
+ if (process.env.NODE_ENV !== 'production') {
+ // eslint-disable-next-line react-hooks/rules-of-hooks
+ useIsoLayoutEffect(() => {
+ if (hiddenUntilFoundProp && keepMountedProp === false) {
+ warn(
+ 'The `keepMounted={false}` prop on a Accordion.Root will be ignored when using `hiddenUntilFound` since it requires Panels to remain mounted when closed.'
+ );
+ }
+ }, [hiddenUntilFoundProp, keepMountedProp]);
+ }
+
+ // memoized to allow omitting both defaultValue and value
+ // which would otherwise trigger a warning in useControlled
+ const defaultValue = React.useMemo(() => {
+ if (valueProp === undefined) {
+ return defaultValueProp ?? [];
+ }
+
+ return [];
+ }, [valueProp, defaultValueProp]);
+
+ const onValueChange = useEventCallback(onValueChangeProp);
+
+ const accordionItemRefs = React.useRef<(HTMLElement | null)[]>([]);
+
+ const [value, setValue] = useControlledState({
+ prop: valueProp,
+ defaultProp: defaultValue,
+ caller: 'Accordion'
+ });
+
+ const handleValueChange = React.useCallback(
+ (newValue: number | string, nextOpen: boolean) => {
+ if (!openMultiple) {
+ const nextValue = value[0] === newValue ? [] : [newValue];
+ setValue(nextValue);
+ onValueChange(nextValue);
+ }
+ else if (nextOpen) {
+ const nextOpenValues = value.slice();
+ nextOpenValues.push(newValue);
+ setValue(nextOpenValues);
+ onValueChange(nextOpenValues);
+ }
+ else {
+ const nextOpenValues = value.filter((v) => v !== newValue);
+ setValue(nextOpenValues);
+ onValueChange(nextOpenValues);
+ }
+ },
+ [
+ onValueChange,
+ openMultiple,
+ setValue,
+ value
+ ]
+ );
+
+ const state: AccordionRoot.State = React.useMemo(
+ () => ({
+ value,
+ disabled,
+ orientation
+ }),
+ [value, disabled, orientation]
+ );
+
+ const contextValue: TAccordionRootContext = React.useMemo(
+ () => ({
+ accordionItemRefs,
+ direction,
+ disabled,
+ handleValueChange,
+ hiddenUntilFound: hiddenUntilFoundProp ?? false,
+ keepMounted: keepMountedProp ?? false,
+ loop,
+ orientation,
+ state,
+ value
+ }),
+ [
+ direction,
+ disabled,
+ handleValueChange,
+ hiddenUntilFoundProp,
+ keepMountedProp,
+ loop,
+ orientation,
+ state,
+ value
+ ]
+ );
+
+ const element = useRenderElement('div', componentProps, {
+ state,
+ ref,
+ props: [{
+ dir: direction,
+ role: 'region'
+ }, elementProps],
+ customStyleHookMapping: rootStyleHookMapping
+ });
+
+ return (
+
+ {element}
+
+ );
+}
+
+export type AccordionValue = (any | null)[];
+
+export namespace AccordionRoot {
+ export type State = {
+ value: AccordionValue;
+ /**
+ * Whether the component should ignore user interaction.
+ */
+ disabled: boolean;
+ orientation: Orientation;
+ };
+
+ export type Props = {
+ /**
+ * The controlled value of the item(s) that should be expanded.
+ *
+ * To render an uncontrolled accordion, use the `defaultValue` prop instead.
+ */
+ value?: AccordionValue;
+ /**
+ * The uncontrolled value of the item(s) that should be initially expanded.
+ *
+ * To render a controlled accordion, use the `value` prop instead.
+ */
+ defaultValue?: AccordionValue;
+ /**
+ * Whether the component should ignore user interaction.
+ * @default false
+ */
+ disabled?: boolean;
+ /**
+ * Allows the browser’s built-in page search to find and expand the panel contents.
+ *
+ * Overrides the `keepMounted` prop and uses `hidden="until-found"`
+ * to hide the element without removing it from the DOM.
+ * @default false
+ */
+ hiddenUntilFound?: boolean;
+ /**
+ * Whether to keep the element in the DOM while the panel is closed.
+ * This prop is ignored when `hiddenUntilFound` is used.
+ * @default false
+ */
+ keepMounted?: boolean;
+ /**
+ * Whether to loop keyboard focus back to the first item
+ * when the end of the list is reached while using the arrow keys.
+ * @default true
+ */
+ loop?: boolean;
+ /**
+ * Event handler called when an accordion item is expanded or collapsed.
+ * Provides the new value as an argument.
+ */
+ onValueChange?: (value: AccordionValue) => void;
+ /**
+ * Whether multiple items can be open at the same time.
+ * @default true
+ */
+ openMultiple?: boolean;
+ /**
+ * The visual orientation of the accordion.
+ * Controls whether roving focus uses left/right or up/down arrow keys.
+ * @default 'vertical'
+ */
+ orientation?: Orientation;
+ } & HeadlessUIComponentProps<'div', State>;
+}
diff --git a/packages/ui/uikit/headless/components/src/components/Accordion/root/AccordionRootContext.ts b/packages/ui/uikit/headless/components/src/components/Accordion/root/AccordionRootContext.ts
new file mode 100644
index 00000000..dd0af0b2
--- /dev/null
+++ b/packages/ui/uikit/headless/components/src/components/Accordion/root/AccordionRootContext.ts
@@ -0,0 +1,35 @@
+'use client';
+import * as React from 'react';
+
+import type { TTextDirection } from '@lib/hooks';
+import type { Orientation } from '@lib/types';
+
+import type { AccordionRoot, AccordionValue } from './AccordionRoot';
+
+export type TAccordionRootContext = {
+ accordionItemRefs: React.RefObject<(HTMLElement | null)[]>;
+ direction: TTextDirection;
+ disabled: boolean;
+ handleValueChange: (newValue: number | string, nextOpen: boolean) => void;
+ hiddenUntilFound: boolean;
+ keepMounted: boolean;
+ loop: boolean;
+ orientation: Orientation;
+ state: AccordionRoot.State;
+ value: AccordionValue;
+};
+
+export const AccordionRootContext = React.createContext(
+ undefined
+);
+
+export function useAccordionRootContext() {
+ const context = React.use(AccordionRootContext);
+
+ if (context === undefined) {
+ throw new Error(
+ 'Headless UI: AccordionRootContext is missing. Accordion parts must be placed within .'
+ );
+ }
+ return context;
+}
diff --git a/packages/ui/uikit/headless/components/src/components/Accordion/root/AccordionRootDataAttributes.ts b/packages/ui/uikit/headless/components/src/components/Accordion/root/AccordionRootDataAttributes.ts
new file mode 100644
index 00000000..34abbca4
--- /dev/null
+++ b/packages/ui/uikit/headless/components/src/components/Accordion/root/AccordionRootDataAttributes.ts
@@ -0,0 +1,10 @@
+export enum AccordionRootDataAttributes {
+ /**
+ * Present when the accordion is disabled.
+ */
+ disabled = 'data-disabled',
+ /**
+ * Indicates the orientation of the accordion.
+ */
+ orientation = 'data-orientation'
+}
diff --git a/packages/ui/uikit/headless/components/src/components/Accordion/trigger/AccordionTrigger.tsx b/packages/ui/uikit/headless/components/src/components/Accordion/trigger/AccordionTrigger.tsx
new file mode 100644
index 00000000..369d7a38
--- /dev/null
+++ b/packages/ui/uikit/headless/components/src/components/Accordion/trigger/AccordionTrigger.tsx
@@ -0,0 +1,226 @@
+'use client';
+
+import React from 'react';
+
+import { useIsoLayoutEffect } from '@flippo_ui/hooks';
+
+import { triggerOpenStateMapping } from '@lib/collapsibleOpenStateMapping';
+import { useRenderElement } from '@lib/hooks';
+import { isElementDisabled } from '@lib/isElementDisabled';
+
+import type { HeadlessUIComponentProps, NativeButtonProps } from '@lib/types';
+
+import { useCollapsibleRootContext } from '../../Collapsible/root/CollapsibleRootContext';
+import {
+ ARROW_DOWN,
+ ARROW_LEFT,
+ ARROW_RIGHT,
+ ARROW_UP,
+ END,
+ HOME,
+ stopEvent
+} from '../../Composite/composite';
+import { useButton } from '../../use-button';
+import { useAccordionItemContext } from '../item/AccordionItemContext';
+import { useAccordionRootContext } from '../root/AccordionRootContext';
+
+import type { AccordionItem } from '../item/AccordionItem';
+
+const SUPPORTED_KEYS = new Set([
+ ARROW_DOWN,
+ ARROW_UP,
+ ARROW_RIGHT,
+ ARROW_LEFT,
+ HOME,
+ END
+]);
+
+function getActiveTriggers(accordionItemRefs: {
+ current: (HTMLElement | null)[];
+}): HTMLButtonElement[] {
+ const { current: accordionItemElements } = accordionItemRefs;
+
+ const output: HTMLButtonElement[] = [];
+
+ for (let i = 0; i < accordionItemElements.length; i += 1) {
+ const section = accordionItemElements[i];
+ if (!isElementDisabled(section)) {
+ const trigger = section?.querySelector('[type="button"]') as HTMLButtonElement;
+ if (!isElementDisabled(trigger)) {
+ output.push(trigger);
+ }
+ }
+ }
+
+ return output;
+}
+
+/**
+ * A button that opens and closes the corresponding panel.
+ * Renders a `