@boxcustodia/library 2.0.0-alpha.11 → 2.0.0-alpha.13

package/src/components/combobox/combobox.tsx

@@ -0,0 +1,898 @@
+import { Combobox as ComboboxPrimitive } from "@base-ui/react/combobox";
+import { Field as FieldPrimitive } from "@base-ui/react/field";
+import { ChevronsUpDownIcon, XIcon } from "lucide-react";
+import * as React from "react";
+import { cn } from "../../lib";
+import { Input, inputBaseClasses } from "../input";
+import { ScrollArea } from "../scroll-area";
+
+// ─── Context ─────────────────────────────────────────────────────────────────
+
+export const ComboboxContext: React.Context<{
+  chipsRef: React.RefObject<Element | null> | null;
+  multiple: boolean;
+}> = React.createContext<{
+  chipsRef: React.RefObject<Element | null> | null;
+  multiple: boolean;
+}>({
+  chipsRef: null,
+  multiple: false,
+});
+
+// ─── Primitives ───────────────────────────────────────────────────────────────
+
+export function ComboboxRoot<
+  Value,
+  Multiple extends boolean | undefined = false,
+>({
+  onChange,
+  ...props
+}: Omit<ComboboxPrimitive.Root.Props<Value, Multiple>, "onValueChange"> & {
+  onChange?: ComboboxPrimitive.Root.Props<Value, Multiple>["onValueChange"];
+}): React.ReactElement {
+  const chipsRef = React.useRef<Element | null>(null);
+  return (
+    <ComboboxContext.Provider value={{ chipsRef, multiple: !!props.multiple }}>
+      <ComboboxPrimitive.Root onValueChange={onChange} {...props} />
+    </ComboboxContext.Provider>
+  );
+}
+
+export function ComboboxChipsInput({
+  className,
+  ...props
+}: Omit<ComboboxPrimitive.Input.Props, "size"> & {
+  ref?: React.Ref<HTMLInputElement>;
+}): React.ReactElement {
+  return (
+    <ComboboxPrimitive.Input
+      className={cn(
+        "min-w-12 flex-1 text-base outline-none placeholder:text-muted-foreground sm:text-sm [[data-slot=combobox-chip]+&]:ps-0.5",
+        className,
+      )}
+      data-slot="combobox-chips-input"
+      {...props}
+    />
+  );
+}
+
+export function ComboboxInput({
+  className,
+  showTrigger = true,
+  showClear = false,
+  startAddon,
+  triggerProps,
+  clearProps,
+  ...props
+}: Omit<ComboboxPrimitive.Input.Props, "size"> & {
+  showTrigger?: boolean;
+  showClear?: boolean;
+  startAddon?: React.ReactNode;
+  ref?: React.Ref<HTMLInputElement>;
+  triggerProps?: ComboboxPrimitive.Trigger.Props;
+  clearProps?: ComboboxPrimitive.Clear.Props;
+}): React.ReactElement {
+  return (
+    <ComboboxPrimitive.InputGroup
+      className="relative not-has-[>*.w-full]:w-fit w-full text-foreground has-disabled:opacity-64"
+      data-slot="combobox-input-group"
+    >
+      {startAddon && (
+        <div
+          aria-hidden="true"
+          className="pointer-events-none absolute inset-y-0 start-px z-10 flex items-center ps-[calc(--spacing(3)-1px)] opacity-80 [&_svg:not([class*='size-'])]:size-4.5 sm:[&_svg:not([class*='size-'])]:size-4 [&_svg]:-mx-0.5"
+          data-slot="combobox-start-addon"
+        >
+          {startAddon}
+        </div>
+      )}
+      <ComboboxPrimitive.Input
+        className={cn(
+          startAddon &&
+            "*:data-[slot=combobox-input]:ps-[calc(--spacing(8.5)-1px)] sm:*:data-[slot=combobox-input]:ps-[calc(--spacing(8)-1px)]",
+          "pr-6",
+          className,
+        )}
+        data-slot="combobox-input"
+        render={(props) => (
+          <Input
+            className="has-disabled:opacity-100"
+            nativeInput
+            {...props}
+            onChange={(_, event) => props?.onChange?.(event)}
+          />
+        )}
+        {...props}
+      />
+      <ComboboxEndAdornment
+        showTrigger={showTrigger}
+        showClear={showClear}
+        triggerProps={triggerProps}
+        clearProps={clearProps}
+      />
+    </ComboboxPrimitive.InputGroup>
+  );
+}
+
+export function ComboboxTrigger({
+  className,
+  children,
+  ...props
+}: ComboboxPrimitive.Trigger.Props): React.ReactElement {
+  return (
+    <ComboboxPrimitive.Trigger
+      className={className}
+      data-slot="combobox-trigger"
+      {...props}
+    >
+      {children}
+    </ComboboxPrimitive.Trigger>
+  );
+}
+
+export function ComboboxSelectTrigger({
+  className,
+  placeholder,
+  children,
+  showClear,
+  clearProps,
+  ...props
+}: ComboboxPrimitive.Trigger.Props & {
+  placeholder?: React.ReactNode;
+  showClear?: boolean;
+  clearProps?: ComboboxPrimitive.Clear.Props;
+}): React.ReactElement {
+  const trigger = (
+    <ComboboxPrimitive.Trigger
+      className={cn(
+        "relative flex w-full items-center rounded-md border border-input bg-background px-3 py-2 pe-9 text-sm outline-none transition-shadow",
+        "focus-visible:border-ring",
+        "aria-invalid:border-error focus-visible:aria-invalid:ring-error/20",
+        "data-disabled:cursor-not-allowed data-disabled:opacity-50",
+        "data-placeholder:text-muted-foreground",
+        className,
+      )}
+      data-slot="combobox-select-trigger"
+      {...props}
+    >
+      {children ?? <ComboboxPrimitive.Value placeholder={placeholder} />}
+    </ComboboxPrimitive.Trigger>
+  );
+
+  if (!showClear) {
+    return (
+      <ComboboxPrimitive.Trigger
+        className={cn(
+          "relative flex w-full items-center rounded-md border border-input bg-background px-3 py-2 pe-9 text-sm outline-none transition-shadow",
+          "focus-visible:border-ring",
+          "aria-invalid:border-error focus-visible:aria-invalid:ring-error/20",
+          "data-disabled:cursor-not-allowed data-disabled:opacity-50",
+          "data-placeholder:text-muted-foreground",
+          className,
+        )}
+        data-slot="combobox-select-trigger"
+        {...props}
+      >
+        {children ?? (
+          <>
+            <ComboboxPrimitive.Value placeholder={placeholder} />
+            <div
+              aria-hidden="true"
+              className="pointer-events-none absolute end-0.5 top-1/2 inline-flex size-8 -translate-y-1/2 items-center justify-center text-muted-foreground opacity-80 sm:size-7 [&_svg:not([class*='size-'])]:size-4.5 sm:[&_svg:not([class*='size-'])]:size-4"
+            >
+              <ChevronsUpDownIcon />
+            </div>
+          </>
+        )}
+      </ComboboxPrimitive.Trigger>
+    );
+  }
+
+  return (
+    <div
+      className="relative w-full text-foreground has-disabled:opacity-64"
+      data-slot="combobox-select-trigger-group"
+    >
+      {trigger}
+      <ComboboxEndAdornment showTrigger showClear clearProps={clearProps} />
+    </div>
+  );
+}
+
+export function ComboboxSearchInput({
+  className,
+  ...props
+}: Omit<ComboboxPrimitive.Input.Props, "size"> & {
+  ref?: React.Ref<HTMLInputElement>;
+}): React.ReactElement {
+  return (
+    <div className="border-b p-2" data-slot="combobox-search-input-wrapper">
+      <ComboboxPrimitive.Input
+        className={cn(
+          "flex h-9 w-full rounded-md bg-transparent text-base placeholder:text-muted-foreground outline-none disabled:cursor-not-allowed disabled:opacity-64 sm:h-8 sm:text-sm",
+          className,
+        )}
+        autoComplete="off"
+        data-slot="combobox-search-input"
+        {...props}
+      />
+    </div>
+  );
+}
+
+export function ComboboxPopup({
+  className,
+  children,
+  side = "bottom",
+  sideOffset = 4,
+  alignOffset,
+  align = "start",
+  anchor: anchorProp,
+  portalProps,
+  ...props
+}: ComboboxPrimitive.Popup.Props & {
+  align?: ComboboxPrimitive.Positioner.Props["align"];
+  sideOffset?: ComboboxPrimitive.Positioner.Props["sideOffset"];
+  alignOffset?: ComboboxPrimitive.Positioner.Props["alignOffset"];
+  side?: ComboboxPrimitive.Positioner.Props["side"];
+  anchor?: ComboboxPrimitive.Positioner.Props["anchor"];
+  portalProps?: ComboboxPrimitive.Portal.Props;
+}): React.ReactElement {
+  const { chipsRef } = React.useContext(ComboboxContext);
+  const anchor = anchorProp ?? chipsRef;
+
+  return (
+    <ComboboxPrimitive.Portal {...portalProps}>
+      <ComboboxPrimitive.Positioner
+        align={align}
+        alignOffset={alignOffset}
+        anchor={anchor}
+        className="z-50 select-none"
+        data-slot="combobox-positioner"
+        side={side}
+        sideOffset={sideOffset}
+      >
+        <span
+          className={cn(
+            "relative flex max-h-full min-w-(--anchor-width) max-w-(--available-width) origin-(--transform-origin) rounded-lg border bg-popover not-dark:bg-clip-padding shadow-lg/5 transition-[scale,opacity] before:pointer-events-none before:absolute before:inset-0 before:rounded-[calc(var(--radius-lg)-1px)] before:shadow-[0_1px_--theme(--color-black/4%)] dark:before:shadow-[0_-1px_--theme(--color-white/6%)]",
+            className,
+          )}
+        >
+          <ComboboxPrimitive.Popup
+            className="flex max-h-[min(var(--available-height),23rem)] flex-1 flex-col text-foreground"
+            data-slot="combobox-popup"
+            {...props}
+          >
+            {children}
+          </ComboboxPrimitive.Popup>
+        </span>
+      </ComboboxPrimitive.Positioner>
+    </ComboboxPrimitive.Portal>
+  );
+}
+
+export function ComboboxItem({
+  className,
+  children,
+  ...props
+}: ComboboxPrimitive.Item.Props): React.ReactElement {
+  return (
+    <ComboboxPrimitive.Item
+      className={cn(
+        "flex justify-between min-h-8 in-data-[side=none]:min-w-[calc(var(--anchor-width)+1.25rem)] cursor-default grid-cols-[1rem_1fr] items-center gap-2 rounded-sm py-1 px-2 text-base outline-none data-disabled:pointer-events-none data-highlighted:bg-accent data-highlighted:text-accent-foreground data-disabled:opacity-64 sm:min-h-7 sm:text-sm [&_svg:not([class*='size-'])]:size-4.5 sm:[&_svg:not([class*='size-'])]:size-4 [&_svg]:pointer-events-none [&_svg]:shrink-0",
+        className,
+      )}
+      data-slot="combobox-item"
+      {...props}
+    >
+      {children}
+      <ComboboxPrimitive.ItemIndicator className="col-end-1">
+        <svg
+          aria-hidden="true"
+          fill="none"
+          height="24"
+          stroke="currentColor"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+          strokeWidth="2"
+          viewBox="0 0 24 24"
+          width="24"
+          xmlns="http://www.w3.org/2000/svg"
+        >
+          <path d="M5.252 12.7 10.2 18.63 18.748 5.37" />
+        </svg>
+      </ComboboxPrimitive.ItemIndicator>
+    </ComboboxPrimitive.Item>
+  );
+}
+
+export function ComboboxSeparator({
+  className,
+  ...props
+}: ComboboxPrimitive.Separator.Props): React.ReactElement {
+  return (
+    <ComboboxPrimitive.Separator
+      className={cn("mx-2 my-1 h-px bg-border last:hidden", className)}
+      data-slot="combobox-separator"
+      {...props}
+    />
+  );
+}
+
+export function ComboboxGroup({
+  className,
+  ...props
+}: ComboboxPrimitive.Group.Props): React.ReactElement {
+  return (
+    <ComboboxPrimitive.Group
+      className={cn("[[role=group]+&]:mt-1.5", className)}
+      data-slot="combobox-group"
+      {...props}
+    />
+  );
+}
+
+export function ComboboxGroupLabel({
+  className,
+  ...props
+}: ComboboxPrimitive.GroupLabel.Props): React.ReactElement {
+  return (
+    <ComboboxPrimitive.GroupLabel
+      className={cn(
+        "px-2 py-1.5 font-medium text-muted-foreground text-xs",
+        className,
+      )}
+      data-slot="combobox-group-label"
+      {...props}
+    />
+  );
+}
+
+export function ComboboxEmpty({
+  className,
+  ...props
+}: ComboboxPrimitive.Empty.Props): React.ReactElement {
+  return (
+    <ComboboxPrimitive.Empty
+      className={cn(
+        "not-empty:p-2 text-center text-base text-muted-foreground sm:text-sm",
+        className,
+      )}
+      data-slot="combobox-empty"
+      {...props}
+    />
+  );
+}
+
+export function ComboboxRow({
+  className,
+  ...props
+}: ComboboxPrimitive.Row.Props): React.ReactElement {
+  return (
+    <ComboboxPrimitive.Row
+      className={className}
+      data-slot="combobox-row"
+      {...props}
+    />
+  );
+}
+
+export function ComboboxValue({
+  ...props
+}: ComboboxPrimitive.Value.Props): React.ReactElement {
+  return <ComboboxPrimitive.Value data-slot="combobox-value" {...props} />;
+}
+
+export function ComboboxList({
+  className,
+  ...props
+}: ComboboxPrimitive.List.Props): React.ReactElement {
+  return (
+    <ScrollArea scrollbarGutter scrollFade>
+      <ComboboxPrimitive.List
+        className={cn(
+          "not-empty:scroll-py-1 not-empty:px-1 not-empty:py-1 in-data-has-overflow-y:pe-3",
+          className,
+        )}
+        data-slot="combobox-list"
+        {...props}
+      />
+    </ScrollArea>
+  );
+}
+
+export function ComboboxClear({
+  className,
+  ...props
+}: ComboboxPrimitive.Clear.Props): React.ReactElement {
+  return (
+    <ComboboxPrimitive.Clear
+      className={className}
+      data-slot="combobox-clear"
+      {...props}
+    />
+  );
+}
+
+const endBtnClass =
+  "absolute end-0.5 top-1/2 inline-flex size-8 shrink-0 -translate-y-1/2 cursor-pointer items-center justify-center rounded-md border border-transparent opacity-80 outline-none transition-opacity pointer-coarse:after:absolute pointer-coarse:after:min-h-11 pointer-coarse:after:min-w-11 hover:opacity-100 sm:size-7 [&_svg:not([class*='size-'])]:size-4.5 sm:[&_svg:not([class*='size-'])]:size-4 [&_svg]:pointer-events-none [&_svg]:shrink-0";
+
+function ComboboxEndAdornment({
+  showTrigger = true,
+  showClear = false,
+  triggerProps,
+  clearProps,
+}: {
+  showTrigger?: boolean;
+  showClear?: boolean;
+  triggerProps?: ComboboxPrimitive.Trigger.Props;
+  clearProps?: ComboboxPrimitive.Clear.Props;
+}): React.ReactElement | null {
+  if (!showTrigger && !showClear) return null;
+  return (
+    <div className="text-muted-foreground hover:text-foreground transition-colors">
+      {showTrigger && (
+        <ComboboxTrigger
+          className={cn(
+            endBtnClass,
+            "text-muted-foreground has-[+[data-slot=combobox-clear]]:hidden",
+          )}
+          {...triggerProps}
+        >
+          <ComboboxPrimitive.Icon data-slot="combobox-icon">
+            <ChevronsUpDownIcon />
+          </ComboboxPrimitive.Icon>
+        </ComboboxTrigger>
+      )}
+      {showClear && (
+        <ComboboxClear className={endBtnClass} {...clearProps}>
+          <XIcon />
+        </ComboboxClear>
+      )}
+    </div>
+  );
+}
+
+export function ComboboxStatus({
+  className,
+  ...props
+}: ComboboxPrimitive.Status.Props): React.ReactElement {
+  return (
+    <ComboboxPrimitive.Status
+      className={cn(
+        "px-3 py-2 font-medium text-muted-foreground text-xs empty:m-0 empty:p-0",
+        className,
+      )}
+      data-slot="combobox-status"
+      {...props}
+    />
+  );
+}
+
+export function ComboboxCollection(
+  props: ComboboxPrimitive.Collection.Props,
+): React.ReactElement {
+  return (
+    <ComboboxPrimitive.Collection data-slot="combobox-collection" {...props} />
+  );
+}
+
+export function ComboboxChips({
+  className,
+  children,
+  startAddon,
+  ...props
+}: ComboboxPrimitive.Chips.Props & {
+  startAddon?: React.ReactNode;
+}): React.ReactElement {
+  const { chipsRef } = React.useContext(ComboboxContext);
+
+  return (
+    <FieldPrimitive.Validity>
+      {({ validity }) => (
+        <ComboboxPrimitive.Chips
+          aria-invalid={validity.valid === false ? true : undefined}
+          className={cn(
+            inputBaseClasses,
+            "relative inline-flex pr-6 w-full flex-wrap gap-1",
+            "placeholder:text-muted-foreground",
+            "focus-within:border-ring",
+            "aria-invalid:border-error focus-within:aria-invalid:ring-error/20",
+            "has-disabled:cursor-not-allowed has-disabled:opacity-50",
+            className,
+          )}
+          data-slot="combobox-chips"
+          ref={chipsRef as React.Ref<HTMLDivElement> | null}
+          {...props}
+        >
+          {startAddon && (
+            <div
+              aria-hidden="true"
+              className="flex shrink-0 items-center ps-2 opacity-80 has-[+[data-slot=combobox-chip]]:pe-2 [&_svg:not([class*='size-'])]:size-4.5 sm:[&_svg:not([class*='size-'])]:size-4 [&_svg]:pointer-events-none [&_svg]:-ms-0.5 [&_svg]:-me-1.5"
+              data-slot="combobox-start-addon"
+            >
+              {startAddon}
+            </div>
+          )}
+          {children}
+        </ComboboxPrimitive.Chips>
+      )}
+    </FieldPrimitive.Validity>
+  );
+}
+
+export function ComboboxChip({
+  children,
+  removeProps,
+  ...props
+}: ComboboxPrimitive.Chip.Props & {
+  removeProps?: ComboboxPrimitive.ChipRemove.Props;
+}): React.ReactElement {
+  return (
+    <ComboboxPrimitive.Chip
+      className="flex items-center pl-1 rounded-[calc(var(--radius-md)-1px)] bg-accent font-medium text-accent-foreground text-sm outline-none sm:text-xs/(--text-xs--line-height) [&_svg:not([class*='size-'])]:size-4 sm:[&_svg:not([class*='size-'])]:size-3.5"
+      data-slot="combobox-chip"
+      {...props}
+    >
+      {children}
+      <ComboboxChipRemove {...removeProps} />
+    </ComboboxPrimitive.Chip>
+  );
+}
+
+export function ComboboxChipRemove(
+  props: ComboboxPrimitive.ChipRemove.Props,
+): React.ReactElement {
+  return (
+    <ComboboxPrimitive.ChipRemove
+      aria-label="Remove"
+      className="h-full shrink-0 cursor-pointer px-1 opacity-80 hover:opacity-100 [&_svg:not([class*='size-'])]:size-4 sm:[&_svg:not([class*='size-'])]:size-3.5"
+      data-slot="combobox-chip-remove"
+      {...props}
+    >
+      <XIcon />
+    </ComboboxPrimitive.ChipRemove>
+  );
+}
+
+// ─── Chip Overflow ────────────────────────────────────────────────────────────
+
+const CHIP_GAP = 4; // gap-1
+const CHIPS_PADDING_X = 24; // px-3 × 2
+const END_ADORNMENT = 36; // clear button + end-0.5 offset
+const OVERFLOW_WIDTH = 68; // max "+99 más" at text-sm + px-1
+
+function calculateChipVisible(
+  containerWidth: number,
+  chipWidths: number[],
+): number {
+  const available = containerWidth - CHIPS_PADDING_X - END_ADORNMENT;
+  let usedWidth = 0;
+  let count = 0;
+
+  for (let i = 0; i < chipWidths.length; i++) {
+    const chipWidth = chipWidths[i];
+    const willHaveOverflow = i < chipWidths.length - 1;
+
+    const projected =
+      usedWidth +
+      (i > 0 ? CHIP_GAP : 0) +
+      chipWidth +
+      (willHaveOverflow ? CHIP_GAP + OVERFLOW_WIDTH : 0);
+
+    if (projected > available) break;
+
+    usedWidth += (i > 0 ? CHIP_GAP : 0) + chipWidth;
+    count++;
+  }
+
+  return count;
+}
+
+function useChipOverflow(
+  itemCount: number,
+  containerRef: React.RefObject<Element | null> | null,
+): { visibleCount: number; isMeasuring: boolean } {
+  const [stableCount, setStableCount] = React.useState<{
+    items: number;
+    visible: number;
+  } | null>(null);
+  const chipWidthsRef = React.useRef<number[]>([]);
+
+  const isMeasuring = stableCount === null || stableCount.items !== itemCount;
+
+  React.useLayoutEffect(() => {
+    if (!isMeasuring) return;
+
+    const container = containerRef?.current as HTMLElement | null;
+    if (!container) return;
+
+    const chipEls = container.querySelectorAll('[data-slot="combobox-chip"]');
+    chipWidthsRef.current = Array.from(chipEls).map(
+      (el) => (el as HTMLElement).offsetWidth,
+    );
+
+    const visible = calculateChipVisible(
+      container.clientWidth,
+      chipWidthsRef.current,
+    );
+    setStableCount({ items: itemCount, visible });
+  }, [isMeasuring, itemCount, containerRef]);
+
+  React.useEffect(() => {
+    const container = containerRef?.current as HTMLElement | null;
+    if (!container) return;
+
+    const observer = new ResizeObserver(() => {
+      if (!chipWidthsRef.current.length) return;
+      const visible = calculateChipVisible(
+        container.clientWidth,
+        chipWidthsRef.current,
+      );
+      setStableCount((prev) => (prev ? { ...prev, visible } : null));
+    });
+
+    observer.observe(container);
+    return () => observer.disconnect();
+  }, [containerRef]);
+
+  return { visibleCount: stableCount?.visible ?? itemCount, isMeasuring };
+}
+
+function ComboboxMultipleChipsContent({
+  value,
+  getLabel,
+  getValue,
+}: {
+  value: unknown[];
+  getLabel: (item: unknown) => string;
+  getValue: (item: unknown) => string;
+}): React.ReactElement {
+  const { chipsRef } = React.useContext(ComboboxContext);
+  const { visibleCount, isMeasuring } = useChipOverflow(value.length, chipsRef);
+
+  const visibleItems = isMeasuring ? value : value.slice(0, visibleCount);
+  const hiddenCount = isMeasuring ? 0 : value.length - visibleCount;
+
+  return (
+    <>
+      {visibleItems.map((item) => (
+        <ComboboxChip key={getValue(item)} aria-label={getLabel(item)}>
+          {getLabel(item)}
+        </ComboboxChip>
+      ))}
+      {hiddenCount > 0 && (
+        <span className="flex items-center whitespace-nowrap px-1 text-sm text-muted-foreground">
+          +{hiddenCount} más
+        </span>
+      )}
+    </>
+  );
+}
+
+// ─── Composite ────────────────────────────────────────────────────────────────
+
+function defaultGetLabel(item: unknown): string {
+  if (item == null) return "";
+  if (typeof item === "string" || typeof item === "number") return String(item);
+  if (typeof item === "object" && "label" in item)
+    return String((item as Record<string, unknown>).label);
+  return String(item);
+}
+
+function defaultGetValue(item: unknown): string {
+  if (item == null) return "";
+  if (typeof item === "string" || typeof item === "number") return String(item);
+  if (typeof item === "object" && "value" in item)
+    return String((item as Record<string, unknown>).value);
+  return String(item);
+}
+
+function ComboboxSingleTrigger({
+  placeholder,
+  showClear,
+  inputProps,
+}: {
+  placeholder?: string;
+  showClear?: boolean;
+  inputProps?: React.ComponentProps<typeof ComboboxInput>;
+}): React.ReactElement {
+  return (
+    <ComboboxInput
+      placeholder={placeholder}
+      showClear={showClear}
+      {...inputProps}
+    />
+  );
+}
+
+function ComboboxMultipleTrigger({
+  getLabel,
+  getValue,
+  chipsProps,
+  showClear,
+  clearProps,
+}: {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  getLabel: (item: any) => string;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  getValue: (item: any) => string;
+  chipsProps?: React.ComponentProps<typeof ComboboxChips>;
+  showClear?: boolean;
+  clearProps?: ComboboxPrimitive.Clear.Props;
+}): React.ReactElement {
+  return (
+    <ComboboxChips {...chipsProps}>
+      <ComboboxValue>
+        {(value: unknown[]) => (
+          <ComboboxMultipleChipsContent
+            value={value}
+            getLabel={getLabel}
+            getValue={getValue}
+          />
+        )}
+      </ComboboxValue>
+      <ComboboxEndAdornment
+        showTrigger={!showClear}
+        showClear={showClear}
+        clearProps={clearProps}
+      />
+    </ComboboxChips>
+  );
+}
+
+type ComboboxRootPropsAlias<V, M extends boolean | undefined = false> = Omit<
+  ComboboxPrimitive.Root.Props<V, M>,
+  "onValueChange"
+> & {
+  onChange?: ComboboxPrimitive.Root.Props<V, M>["onValueChange"];
+};
+
+type ComboboxBaseProps<TItem = unknown> = Omit<
+  ComboboxRootPropsAlias<TItem, boolean>,
+  | "items"
+  | "itemToStringLabel"
+  | "itemToStringValue"
+  | "children"
+  | "multiple"
+  | "onChange"
+  | "value"
+  | "defaultValue"
+> & {
+  items: readonly TItem[];
+  getLabel?: (item: TItem) => string;
+  getValue?: (item: TItem) => string;
+  renderItem?: (item: TItem) => React.ReactNode;
+  placeholder?: string;
+  emptyText?: string;
+  inputProps?: React.ComponentProps<typeof ComboboxInput>;
+  chipsProps?: React.ComponentProps<typeof ComboboxChips>;
+  chipsInputProps?: React.ComponentProps<typeof ComboboxChipsInput>;
+  popupProps?: React.ComponentProps<typeof ComboboxPopup>;
+  itemProps?: ComboboxPrimitive.Item.Props;
+  listProps?: Omit<ComboboxPrimitive.List.Props, "children">;
+  showClear?: boolean;
+};
+
+export type ComboboxProps<TItem = unknown> =
+  | (ComboboxBaseProps<TItem> & {
+      multiple?: false;
+      value?: TItem | null;
+      defaultValue?: TItem | null;
+      onChange?: (value: TItem | null) => void;
+    })
+  | (ComboboxBaseProps<TItem> & {
+      multiple: true;
+      value?: TItem[];
+      defaultValue?: TItem[];
+      onChange?: (value: TItem[]) => void;
+    });
+
+/**
+ * Composite combobox for single and multiple selection.
+ *
+ * Items shaped as `{ label, value }` or plain strings/numbers work with no
+ * extra props. For other shapes, provide `getLabel` and/or `getValue`.
+ *
+ * In multiple mode, chips are fit dynamically based on the container width —
+ * overflowing items show as "+N más". The popup anchors to the chips container automatically.
+ *
+ * `renderItem` customizes the content **inside** each `ComboboxItem` (the
+ * checkmark indicator is always rendered by the item wrapper).
+ *
+ * Use `ComboboxRoot` + primitives directly when you need full structural
+ * control beyond what escape-hatch props offer.
+ */
+export function Combobox<TItem = unknown>(
+  allProps: ComboboxProps<TItem>,
+): React.ReactElement {
+  // Cast internally — ComboboxProps discriminated union enforces correctness for consumers.
+  // The union can't be spread directly into ComboboxRoot because TypeScript can't resolve
+  // which branch is active at the call site.
+  const {
+    items,
+    getLabel: getLabelProp,
+    getValue: getValueProp,
+    renderItem,
+    placeholder,
+    emptyText = "Sin resultados.",
+    multiple,
+    onChange,
+    value,
+    defaultValue,
+    inputProps,
+    chipsProps,
+    chipsInputProps,
+    popupProps,
+    itemProps,
+    listProps,
+    showClear = true,
+    ...rest
+  } = allProps as ComboboxBaseProps<TItem> & {
+    multiple?: boolean;
+    onChange?: (value: any, eventDetails?: any) => void;
+    value?: any;
+    defaultValue?: any;
+  };
+
+  const getLabel: (item: TItem) => string = getLabelProp ?? defaultGetLabel;
+  const getValue: (item: TItem) => string = getValueProp ?? defaultGetValue;
+
+  return (
+    <ComboboxRoot
+      items={items}
+      itemToStringLabel={getLabel}
+      itemToStringValue={getValue}
+      multiple={multiple as boolean}
+      onChange={onChange}
+      value={value}
+      defaultValue={defaultValue}
+      autoHighlight
+      loopFocus
+      {...rest}
+    >
+      {multiple ? (
+        <ComboboxMultipleTrigger
+          getLabel={getLabel}
+          getValue={getValue}
+          chipsProps={chipsProps}
+          showClear={showClear}
+        />
+      ) : (
+        <ComboboxSingleTrigger
+          placeholder={placeholder}
+          showClear={showClear}
+          inputProps={inputProps}
+        />
+      )}
+      <ComboboxPopup {...popupProps}>
+        {multiple && (
+          <div
+            className="border-b p-2"
+            data-slot="combobox-chips-input-wrapper"
+          >
+            <ComboboxChipsInput
+              placeholder={placeholder}
+              {...chipsInputProps}
+            />
+          </div>
+        )}
+        <ComboboxEmpty>{emptyText}</ComboboxEmpty>
+        <ComboboxList {...listProps}>
+          {(item: TItem) => (
+            <ComboboxItem key={getValue(item)} value={item} {...itemProps}>
+              {renderItem ? renderItem(item) : getLabel(item)}
+            </ComboboxItem>
+          )}
+        </ComboboxList>
+      </ComboboxPopup>
+    </ComboboxRoot>
+  );
+}
+
+// ─── Exports ──────────────────────────────────────────────────────────────────
+
+export const useComboboxFilter: typeof ComboboxPrimitive.useFilter =
+  ComboboxPrimitive.useFilter;
+
+export { ComboboxPrimitive };