@bccampus/ui-components 0.7.2 → 0.8.0

package/src/components/ui/composite/CompositeData.ts

@@ -1,22 +1,24 @@
-import type { CompositeDataOptions, CompositeItemKey, CompositeOptions, CompositeProviderOptions } from "./types";
+import type { CompositeDataOptions, CompositeItemKey, CompositeOptions, CompositeManagerOptions } from "./types";
 import { CompositeDataItem } from "./CompositeDataItem";
-import type { AbstractFocusProvider } from "./FocusProvider/AbstractFocusProvider";
-import type { AbstractSelectionProvider } from "./SelectionProvider/AbstractSelectionProvider";
+import type { AbstractFocusManager } from "./FocusManager/AbstractFocusManager";
+import type { AbstractSelectionManager } from "./SelectionManager/AbstractSelectionManager";
 import { union } from "@/lib/set-operations";
+import { atom } from "nanostores";
 
 export class CompositeData<T extends object> implements Iterable<CompositeDataItem<T>> {
   #options: CompositeDataOptions<T>;
+  #version = atom(0);
 
   lookup: Map<CompositeItemKey, CompositeDataItem<T>> = new Map();
 
-  focusProvider: AbstractFocusProvider<T>;
-  selectionProvider?: AbstractSelectionProvider<T>;
+  focusManager: AbstractFocusManager<T>;
+  selectionManager?: AbstractSelectionManager<T>;
 
   disabledKeys: Set<CompositeItemKey> = new Set();
 
-  root!: CompositeDataItem<T>;
+  root?: CompositeDataItem<T> = undefined;
 
-  constructor(items: T[], providerOptions: CompositeProviderOptions<T>, options?: CompositeOptions) {
+  constructor(items: T[] | null, managerOptions: CompositeManagerOptions<T>, options?: CompositeOptions) {
     this.#options = {
       itemKeyProp: "key",
       itemChildrenProp: "children",
@@ -25,19 +27,19 @@ export class CompositeData<T extends object> implements Iterable<CompositeDataIt
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
       getItemKey: (item: any) => item[this.#options.itemKeyProp] as CompositeItemKey,
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      getItemChildren: (item: any) => item[this.#options.itemChildrenProp] ? item[this.#options.itemChildrenProp] as T[] : undefined,
+      getItemChildren: (item: any) =>
+        item[this.#options.itemChildrenProp] ? (item[this.#options.itemChildrenProp] as T[]) : undefined,
 
-      ...options
+      ...options,
     };
 
-    this.focusProvider = providerOptions.focusProvider;
-    this.selectionProvider = providerOptions.selectionProvider;
-
-    this.init(items);
+    this.focusManager = managerOptions.focusManager;
+    this.selectionManager = managerOptions.selectionManager;
+    if (items) this.setItems(items);
   }
 
   *[Symbol.iterator](): Iterator<CompositeDataItem<T>> {
-    if (this.root.children) {
+    if (this.root?.children) {
       for (const node of this.root.children) {
         yield node;
       }
@@ -45,33 +47,41 @@ export class CompositeData<T extends object> implements Iterable<CompositeDataIt
   }
 
   toJSON() {
+    if (!this.root) return [] as T[];
+
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const json: any = this.root.toJSON()
+    const json: any = this.root.toJSON();
 
     return json[this.#options.itemChildrenProp] as T[];
   }
 
+  get version() {
+    return this.#version;
+  }
 
-  init(items: T[]) {
+  setItems(items: T[]) {
     this.root = new CompositeDataItem(
       { [this.#options.itemKeyProp]: "ALL", [this.#options.itemChildrenProp]: items } as T,
       this.#options,
-      null
+      null,
     );
 
     // Build item lookup table
-    this.lookup = new Map([...this.root].map(item => [item.key, item]));
+    this.lookup = new Map([...this.root].map((item) => [item.key, item]));
 
-    // Set initially disabled items
-    this.#options.disabledKeys.forEach(disabledKey => this.#disable(disabledKey));
+    // Set default disabled items
+    this.#options.disabledKeys.forEach((disabledKey) => this.#disable(disabledKey));
 
-    if (this.selectionProvider)
-      this.selectionProvider.init(this, this.#options);
+    if (this.selectionManager) this.selectionManager.init(this, this.#options);
 
-    this.focusProvider.init(this, this.#options);
+    this.focusManager.init(this, this.#options);
+
+    this.#version.set(this.#version.value + 1);
   }
 
-  item(key: CompositeItemKey) { return this.lookup.get(key) };
+  item(key: CompositeItemKey) {
+    return this.lookup.get(key);
+  }
 
   descendants(itemKey: CompositeItemKey) {
     const item = this.lookup.get(itemKey);
@@ -97,14 +107,12 @@ export class CompositeData<T extends object> implements Iterable<CompositeDataIt
     this.disabledKeys = union(this.disabledKeys, disabledKeys);
   }
 
-
   updateItem(key: CompositeItemKey, data: Partial<T> | ((item: T) => Partial<T>)) {
     const item = this.lookup.get(key);
     if (item) {
       const newData = {
-        ...item.data.get(), ...(
-          (typeof data === "function") ? data(item.data.get()) : data
-        )
+        ...item.data.get(),
+        ...(typeof data === "function" ? data(item.data.get()) : data),
       };
 
       const newKey = this.#options.getItemKey(newData);
@@ -116,8 +124,8 @@ export class CompositeData<T extends object> implements Iterable<CompositeDataIt
   }
 
   #updateIfSelectedItem(key: CompositeItemKey) {
-    if (this.selectionProvider && this.selectionProvider.selectedKeys.get().has(key)) {
-      this.selectionProvider.selectedKeys.set(new Set([...this.selectionProvider.selectedKeys.get()]));
+    if (this.selectionManager && this.selectionManager.selectedKeys.get().has(key)) {
+      this.selectionManager.selectedKeys.set(new Set([...this.selectionManager.selectedKeys.get()]));
     }
   }
 }

package/src/components/ui/composite/{FocusProvider/AbstractFocusProvider.ts → FocusManager/AbstractFocusManager.ts}

@@ -2,29 +2,9 @@ import { atom, type PreinitializedWritableAtom } from "nanostores";
 import type { CompositeData } from "../CompositeData";
 import { CompositeDataItem } from "../CompositeDataItem";
 import type { CompositeDataOptions, CompositeItemKey } from "../types";
+import type { IFocusManager } from "./types";
 
-export interface FocusProvider<T extends object> {
-  getFocusedItem(): CompositeDataItem<T> | null;
-
-  focus(itemKey: CompositeItemKey): void;
-  focus(item: CompositeDataItem<T>): void;
-  focus(item: CompositeDataItem<T> | CompositeItemKey | null): void;
-  blur(): void;
-
-  focusUp(): void;
-  focusDown(): void;
-  focusLeft(): void;
-  focusRight(): void;
-  focusPageUp(): void;
-  focesPageDown(): void;
-  focusToFirst(): void;
-  focusToLast(): void;
-  focusToFirstInRow(): void;
-  focusToLastInRow(): void;
-  focusToTypeAheadMatch(): void;
-}
-
-export abstract class AbstractFocusProvider<T extends object> implements FocusProvider<T> {
+export abstract class AbstractFocusManager<T extends object> implements IFocusManager<T> {
   protected data!: CompositeData<T>;
   protected dataOptions!: CompositeDataOptions<T>;
 
@@ -41,6 +21,19 @@ export abstract class AbstractFocusProvider<T extends object> implements FocusPr
 
     this.firstFocusableItem = first;
     this.lastFocusableItem = last;
+
+    // Restore previos state
+    const prevFocusedItem = this.focusedItem.get();
+    if (prevFocusedItem) {
+      const _item = this.data.lookup.get(prevFocusedItem.key);
+      if (!_item) {
+        this.focusedItem.set(null);
+        return;
+      }
+
+      _item.state.setKey("focused", true);
+      this.focusedItem.set(_item);
+    }
   }
 
   isFocusable(itemAtom: CompositeDataItem<T>) {
@@ -60,10 +53,10 @@ export abstract class AbstractFocusProvider<T extends object> implements FocusPr
     const _item = item instanceof CompositeDataItem ? item : this.data.lookup.get(item);
     if (!_item) return;
 
-    if (this.focusedItem.get()) {
-      if (_item.key === this.focusedItem.get()?.key) return;
-
-      this.focusedItem.get()!.state.setKey("focused", false);
+    const focusedItem = this.focusedItem.get();
+    if (focusedItem) {
+      if (_item.key === focusedItem.key) return;
+      focusedItem.state.setKey("focused", false);
     }
 
     _item.state.setKey("focused", true);

package/src/components/ui/composite/{FocusProvider/ListboxFocusProvider.ts → FocusManager/ListboxFocusManager.ts}

@@ -1,7 +1,7 @@
 import type { CompositeDataItem } from "../CompositeDataItem";
-import { AbstractFocusProvider } from "./AbstractFocusProvider";
+import { AbstractFocusManager } from "./AbstractFocusManager";
 
-export class ListboxFocusProvider<T extends object> extends AbstractFocusProvider<T> {
+export class ListboxFocusManager<T extends object> extends AbstractFocusManager<T> {
   setFocusPointers() {
     let first: CompositeDataItem<T> | null = null;
     let last: CompositeDataItem<T> | null = null;

package/src/components/ui/composite/FocusManager/index.ts

@@ -0,0 +1,3 @@
+export * from "./AbstractFocusManager";
+export * from "./ListboxFocusManager";
+export type * from "./types";

package/src/components/ui/composite/FocusManager/types.ts

@@ -0,0 +1,23 @@
+import type { CompositeDataItem } from "../CompositeDataItem";
+import type { CompositeItemKey } from "../types";
+
+export interface IFocusManager<T extends object> {
+  getFocusedItem(): CompositeDataItem<T> | null;
+
+  focus(itemKey: CompositeItemKey): void;
+  focus(item: CompositeDataItem<T>): void;
+  focus(item: CompositeDataItem<T> | CompositeItemKey | null): void;
+  blur(): void;
+
+  focusUp(): void;
+  focusDown(): void;
+  focusLeft(): void;
+  focusRight(): void;
+  focusPageUp(): void;
+  focesPageDown(): void;
+  focusToFirst(): void;
+  focusToLast(): void;
+  focusToFirstInRow(): void;
+  focusToLastInRow(): void;
+  focusToTypeAheadMatch(): void;
+}

package/src/components/ui/composite/{SelectionProvider/AbstractSelectionProvider.ts → SelectionManager/AbstractSelectionManager.ts}

@@ -2,37 +2,17 @@ import { atom, type PreinitializedWritableAtom } from "nanostores";
 import type { CompositeData } from "../CompositeData";
 import { CompositeDataItem } from "../CompositeDataItem";
 import type { CompositeDataOptions, CompositeItemKey } from "../types";
+import type { SelectionManager, SelectionManagerOptions } from "./types";
 
-export interface SelectionProvider<T extends object> {
-  getSelectedKeys(): Set<CompositeItemKey>;
-
-  select(itemKey?: CompositeItemKey, recursive?: boolean): void;
-  select(item: CompositeDataItem<T>, recursive?: boolean): void;
-  select(item?: CompositeDataItem<T> | CompositeItemKey, recursive?: boolean): void;
-
-  deselect(itemKey?: CompositeItemKey, recursive?: boolean): void;
-  deselect(item: CompositeDataItem<T>, recursive?: boolean): void;
-  deselect(item?: CompositeDataItem<T> | CompositeItemKey, recursive?: boolean): void;
-
-  toggleSelect(itemKey?: CompositeItemKey, recursive?: boolean): void;
-  toggleSelect(item: CompositeDataItem<T>, recursive?: boolean): void;
-  toggleSelect(item: CompositeDataItem<T> | CompositeItemKey, recursive?: boolean): void;
-}
-
-export interface SelectionProviderOptions<T extends object> {
-  onSelect?: (item: T) => void;
-  onDeselect?: (item: T) => void;
-  onChange?: (item: Set<CompositeItemKey>) => void;
-}
-
-export abstract class AbstractSelectionProvider<T extends object> {
+export abstract class AbstractSelectionManager<T extends object> implements SelectionManager<T> {
   protected data!: CompositeData<T>;
   protected dataOptions!: CompositeDataOptions<T>;
+  protected abstract multiselect: boolean;
 
   selectedKeys: PreinitializedWritableAtom<Set<CompositeItemKey>> = atom(new Set());
-  options?: SelectionProviderOptions<T>;
+  options?: SelectionManagerOptions<T>;
 
-  constructor(options?: SelectionProviderOptions<T>) {
+  constructor(options?: SelectionManagerOptions<T>) {
     this.options = options;
   }
 
@@ -40,8 +20,13 @@ export abstract class AbstractSelectionProvider<T extends object> {
     this.data = data;
     this.dataOptions = dataOptions;
 
-    // Set initially selected items : SelectionProvider
-    this.dataOptions.selectedKeys.forEach((selectedKey) => this.select(selectedKey));
+    if (this.data.version.get() > 0) {
+      // Restore previos state
+      this.selectedKeys.get().forEach((key) => this.select(key));
+    } else {
+      // Set default selected items
+      this.dataOptions.selectedKeys.forEach((selectedKey) => this.select(selectedKey));
+    }
   }
 
   getSelectedKeys() {
@@ -64,7 +49,7 @@ export abstract class AbstractSelectionProvider<T extends object> {
       ? item instanceof CompositeDataItem
         ? item
         : this.data.lookup.get(item)
-      : this.data.focusProvider.focusedItem.get();
+      : this.data.focusManager.focusedItem.get();
     if (!_item) return;
 
     if (_item.state.get().selected) this.deselect(_item, recursive);

package/src/components/ui/composite/{SelectionProvider/MultipleSelectionProvider.ts → SelectionManager/MultipleSelectionManager.ts}

@@ -1,9 +1,11 @@
 import { CompositeDataItem } from "../CompositeDataItem";
 import type { CompositeItemKey } from "../types";
-import { AbstractSelectionProvider } from "./AbstractSelectionProvider";
+import { AbstractSelectionManager } from "./AbstractSelectionManager";
 import { difference, union } from "@/lib/set-operations";
 
-export class MultipleSelectionProvider<T extends object> extends AbstractSelectionProvider<T> {
+export class MultipleSelectionManager<T extends object> extends AbstractSelectionManager<T> {
+  protected multiselect: boolean = true;
+
   select(itemKey: CompositeItemKey, recursive?: boolean): void;
   select(item: CompositeDataItem<T>, recursive?: boolean): void;
   select(item: CompositeDataItem<T> | CompositeItemKey, recursive: boolean = false) {

package/src/components/ui/composite/{SelectionProvider/SingleSelectionProvider.ts → SelectionManager/SingleSelectionManager.ts}

@@ -2,10 +2,12 @@
 
 import { CompositeDataItem } from "../CompositeDataItem";
 import type { CompositeItemKey } from "../types";
-import { AbstractSelectionProvider } from "./AbstractSelectionProvider";
+import { AbstractSelectionManager } from "./AbstractSelectionManager";
 import { difference } from "@/lib/set-operations";
 
-export class SingleSelectionProvider<T extends object> extends AbstractSelectionProvider<T> {
+export class SingleSelectionManager<T extends object> extends AbstractSelectionManager<T> {
+  protected multiselect: boolean = false;
+
   select(itemKey?: CompositeItemKey, recursive?: boolean): void;
   select(item: CompositeDataItem<T>, recursive?: boolean): void;
   select(item?: CompositeDataItem<T> | CompositeItemKey, _recursive: boolean = false) {
@@ -13,7 +15,7 @@ export class SingleSelectionProvider<T extends object> extends AbstractSelection
       ? item instanceof CompositeDataItem
         ? item
         : this.data.lookup.get(item)
-      : this.data.focusProvider.focusedItem.get();
+      : this.data.focusManager.focusedItem.get();
     if (!_item) return;
 
     this.selectedKeys.get().forEach((selectedKey) => {
@@ -38,7 +40,7 @@ export class SingleSelectionProvider<T extends object> extends AbstractSelection
       ? item instanceof CompositeDataItem
         ? item
         : this.data.lookup.get(item)
-      : this.data.focusProvider.focusedItem.get();
+      : this.data.focusManager.focusedItem.get();
     if (!_item) return;
 
     const deselectedKeys = _item.deselect(false);

package/src/components/ui/composite/SelectionManager/index.ts

@@ -0,0 +1,4 @@
+export * from "./AbstractSelectionManager";
+export * from "./SingleSelectionManager";
+export * from "./MultipleSelectionManager";
+export type * from "./types";

package/src/components/ui/composite/SelectionManager/types.ts

@@ -0,0 +1,24 @@
+import type { CompositeDataItem } from "../CompositeDataItem";
+import type { CompositeItemKey } from "../types";
+
+export interface SelectionManager<T extends object> {
+  getSelectedKeys(): Set<CompositeItemKey>;
+
+  select(itemKey?: CompositeItemKey, recursive?: boolean): void;
+  select(item: CompositeDataItem<T>, recursive?: boolean): void;
+  select(item?: CompositeDataItem<T> | CompositeItemKey, recursive?: boolean): void;
+
+  deselect(itemKey?: CompositeItemKey, recursive?: boolean): void;
+  deselect(item: CompositeDataItem<T>, recursive?: boolean): void;
+  deselect(item?: CompositeDataItem<T> | CompositeItemKey, recursive?: boolean): void;
+
+  toggleSelect(itemKey?: CompositeItemKey, recursive?: boolean): void;
+  toggleSelect(item: CompositeDataItem<T>, recursive?: boolean): void;
+  toggleSelect(item: CompositeDataItem<T> | CompositeItemKey, recursive?: boolean): void;
+}
+
+export interface SelectionManagerOptions<T extends object> {
+  onSelect?: (item: T) => void;
+  onDeselect?: (item: T) => void;
+  onChange?: (selectedKeys: Set<CompositeItemKey>) => void;
+}

package/src/components/ui/composite/{composite-component.tsx → components/composite-component.tsx}

@@ -1,34 +1,14 @@
-import { useCallback, useEffect, useImperativeHandle, useMemo, type FocusEventHandler } from "react";
-import type { CompositeItemKey, CompositeProps } from "./types";
+import { useCallback, useEffect, useImperativeHandle, type FocusEventHandler } from "react";
+import type { CompositeItemKey } from "../types";
+import type { CompositeProps } from "./types.ts";
 import { CompositeComponentItem } from "./composite-component-item";
 import { useId } from "@/hooks/use-id";
 import { useRequiredRef } from "@/hooks/use-required-ref";
-import type { CompositeDataItem } from "./CompositeDataItem";
-
-const defaultRoles = {
-  listbox: {
-    rootRole: "listbox",
-    groupRole: "group",
-    itemRole: "option",
-  },
-  grid: {
-    rootRole: "grid",
-    groupRole: "rowgroup",
-    itemRole: "row",
-  },
-  custom: undefined,
-};
-
-const isOutsideElement = (parent: Element | null, el: Element | null) => {
-  if (parent === el) return false;
-
-  const nodeId = !!el?.id && CSS.escape(el.id);
-  return !nodeId || parent?.querySelector(`#${nodeId}`) === null;
-};
+import type { CompositeDataItem } from "../CompositeDataItem";
+import { isOutsideElement } from "./utils";
 
 export function CompositeComponent<T extends object>({
   data,
-  variant,
   rootRole,
   itemRole,
   groupRole,
@@ -50,41 +30,36 @@ export function CompositeComponent<T extends object>({
   const focusElement = useCallback(() => {
     if (softFocus) return;
 
-    const itemKey = data.focusProvider.focusedItem.get()?.key;
+    const itemKey = data.focusManager.focusedItem.get()?.key;
 
     if (itemKey && $rootRef.current) {
       const focusedItemEl = $rootRef.current.querySelector<HTMLElement>(`[data-key="${itemKey}"]`);
       if (focusedItemEl) focusedItemEl.focus();
     }
-  }, [softFocus, data.focusProvider.focusedItem, $rootRef]);
+  }, [softFocus, data.focusManager.focusedItem, $rootRef]);
 
   useImperativeHandle(handleRef, () => {
     return {
-      focusProvider: data.focusProvider,
-      selectionProvider: data.selectionProvider,
+      focusManager: data.focusManager,
+      selectionManager: data.selectionManager,
       focusElement,
     };
   }, [data, focusElement]);
 
-  const roles = useMemo(
-    () => defaultRoles[variant] ?? { rootRole, groupRole, itemRole },
-    [groupRole, itemRole, rootRole, variant],
-  );
-
   const intiFocus = useCallback(
     (onlyData: boolean) => {
       let initialFocusItem: CompositeDataItem<T> | CompositeItemKey | null = null;
 
-      if (initialFocus === "FirstItem") initialFocusItem = data.focusProvider.firstFocusableItem;
+      if (initialFocus === "FirstItem") initialFocusItem = data.focusManager.firstFocusableItem;
       else if (initialFocus === "SelectedItem") {
-        const selecedItem = data.selectionProvider?.selectedKeys.get().values().next().value;
-        initialFocusItem = selecedItem ?? data.focusProvider.firstFocusableItem;
+        const selecedItem = data.selectionManager?.selectedKeys.get().values().next().value;
+        initialFocusItem = selecedItem ?? data.focusManager.firstFocusableItem;
       }
 
-      data.focusProvider.focus(initialFocusItem);
+      data.focusManager.focus(initialFocusItem);
       if (!onlyData) focusElement();
     },
-    [data.focusProvider, data.selectionProvider?.selectedKeys, focusElement, initialFocus],
+    [data.focusManager, data.selectionManager?.selectedKeys, focusElement, initialFocus],
   );
 
   const onFocusHandler: FocusEventHandler = useCallback(
@@ -103,7 +78,7 @@ export function CompositeComponent<T extends object>({
       id={compositeId}
       className={className}
       tabIndex={initialFocus === "None" ? 0 : -1}
-      role={roles.rootRole}
+      role={rootRole}
       {...props}
       onFocus={onFocusHandler}
     >
@@ -111,8 +86,8 @@ export function CompositeComponent<T extends object>({
         <CompositeComponentItem
           className={itemClassName}
           id={`${compositeId}-${item.key}`}
-          role={roles.itemRole}
-          groupRole={roles.groupRole}
+          role={itemRole}
+          groupRole={groupRole}
           item={item}
           key={item.key}
           render={renderItem}

package/src/components/ui/composite/components/index.ts

@@ -0,0 +1,5 @@
+export * from "./composite-component.tsx";
+export * from "./composite-component-item.tsx";
+export * from "./listbox.tsx";
+export * from "./utils.ts";
+export type * from "./types";

package/src/components/ui/composite/{listbox.tsx → components/listbox.tsx}

@@ -1,15 +1,17 @@
 import { CompositeComponent } from "./composite-component";
 import { useCallback } from "react";
-import { CompositeDataItem } from "./CompositeDataItem";
+import { CompositeDataItem } from "../CompositeDataItem";
 import type { BaseCompositeProps } from "./types";
 import { useKeyboardEvent } from "@/hooks/use-keyboard-event";
 import { useRequiredRef } from "@/hooks/use-required-ref";
+import { cn } from "@/lib";
 
 export function Listbox<T extends object>({
   data,
   rootRef,
   handleRef,
   initialFocus = "SelectedItem",
+  className,
   ...props
 }: BaseCompositeProps<T>) {
   const $handleRef = useRequiredRef(handleRef);
@@ -17,47 +19,50 @@ export function Listbox<T extends object>({
   const handleKeyboardEvent = useKeyboardEvent(
     {
       ArrowUp: () => {
-        data.focusProvider.focusUp();
+        data.focusManager.focusUp();
         $handleRef.current?.focusElement();
       },
       ArrowDown: () => {
-        data.focusProvider.focusDown();
+        data.focusManager.focusDown();
         $handleRef.current?.focusElement();
       },
       Home: () => {
-        data.focusProvider.focusToFirst();
+        data.focusManager.focusToFirst();
         $handleRef.current?.focusElement();
       },
       End: () => {
-        data.focusProvider.focusToLast();
+        data.focusManager.focusToLast();
         $handleRef.current?.focusElement();
       },
       Space: () => {
-        data.selectionProvider?.toggleSelect();
+        data.selectionManager?.toggleSelect();
         $handleRef.current?.focusElement();
       },
     },
-    [$handleRef, data.focusProvider],
+    [$handleRef, data.focusManager],
   );
 
   const handleItemMouseEvent = useCallback(
     (item: CompositeDataItem<T>) => {
-      data.focusProvider.focus(item.key);
-      data.selectionProvider?.toggleSelect(item);
+      data.focusManager.focus(item.key);
+      data.selectionManager?.toggleSelect(item);
       $handleRef.current?.focusElement();
     },
-    [$handleRef, data.focusProvider, data.selectionProvider],
+    [$handleRef, data.focusManager, data.selectionManager],
   );
 
   return (
     <CompositeComponent
       rootRef={rootRef}
       handleRef={$handleRef}
-      variant="listbox"
+      rootRole="listbox"
+      groupRole="group"
+      itemRole="option"
       data={data}
       initialFocus={initialFocus}
       onKeyDown={handleKeyboardEvent}
       itemMouseEventHandler={handleItemMouseEvent}
+      className={cn("flex flex-col gap-1", className)}
       {...props}
     />
   );

package/src/components/ui/composite/components/types.ts

@@ -0,0 +1,66 @@
+import type { AriaRole, KeyboardEventHandler, MouseEventHandler, ReactNode } from "react";
+import type { CompositeData } from "../CompositeData";
+import type { CompositeDataItemState, CompositeItemKey } from "../types";
+import type { IFocusManager } from "../FocusManager";
+import type { SelectionManager } from "../SelectionManager";
+import type { CompositeDataItem } from "../CompositeDataItem";
+
+export type InitialFocusTarget = "None" | "LastFocusedItem" | "SelectedItem" | "FirstItem";
+
+export interface BaseCompositeProps<T extends object> extends React.ComponentPropsWithoutRef<"div"> {
+  data: CompositeData<T>;
+  className?: string;
+  rootRef?: React.RefObject<HTMLDivElement | null>;
+  handleRef?: React.RefObject<CompositeHandle<T> | null>;
+
+  renderItem: CompositeItemRenderFn<T>;
+  itemClassName?: string;
+
+  initialFocus?: InitialFocusTarget;
+  /**
+   * Set `item.focused = true`, but not focus on the HTMLElement
+   */
+  softFocus?: boolean;
+}
+
+export interface CompositeProps<T extends object> extends BaseCompositeProps<T>, CompositeItemEventHandlerFunctions<T> {
+  rootRole: AriaRole;
+  itemRole: AriaRole;
+  groupRole: AriaRole;
+}
+
+export interface CompositeHandle<T extends object> {
+  focusManager: IFocusManager<T>;
+  focusElement: () => void;
+  selectionManager?: SelectionManager<T>;
+}
+
+export type CompositeItemRenderFn<T extends object> = (
+  item: { data: T; level: number; key: CompositeItemKey },
+  state: CompositeDataItemState,
+  eventHandlers: CompositeEventHandlers,
+) => ReactNode;
+
+export interface CompositeItemProps<T extends object> extends CompositeItemEventHandlerFunctions<T> {
+  id: string;
+  className?: string;
+  role?: AriaRole;
+  groupRole?: AriaRole;
+
+  item: CompositeDataItem<T>;
+
+  remove?: () => void;
+  render: CompositeItemRenderFn<T>;
+
+  softFocus?: boolean;
+}
+
+export interface CompositeEventHandlers {
+  mouseEventHandler?: MouseEventHandler<HTMLElement>;
+  keyboardEventHandler?: KeyboardEventHandler<HTMLElement>;
+}
+
+export interface CompositeItemEventHandlerFunctions<T extends object> {
+  itemMouseEventHandler?: (itemAtom: CompositeDataItem<T>) => void;
+  itemKeyboardEventHandler?: (itemAtom: CompositeDataItem<T>) => void;
+}

package/src/components/ui/composite/components/utils.ts

@@ -0,0 +1,6 @@
+export const isOutsideElement = (parent: Element | null, el: Element | null) => {
+  if (parent === el) return false;
+
+  const nodeId = !!el?.id && CSS.escape(el.id);
+  return !nodeId || parent?.querySelector(`#${nodeId}`) === null;
+};