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

package/src/components/auto-complete/auto-complete.stories.tsx

@@ -1,241 +1,656 @@
 import type { Meta, StoryObj } from "@storybook/react-vite";
+import { BuildingIcon, SearchIcon, UserIcon } from "lucide-react";
+import { useRef, useState, useTransition } from "react";
 import {
-  Archive,
-  Calendar,
-  FlameKindling,
-  Github,
-  Mail,
-  Settings,
-  Slack,
-  TicketPercent,
-  User,
-  UserPlus,
-} from "lucide-react";
-import React, { useState } from "react";
-import {
-  AutoComplete,
-  AutoCompleteDialog,
-  AutoCompleteEmpty,
-  AutoCompleteGroup,
-  AutoCompleteInput,
-  AutoCompleteItem,
-  AutoCompleteList,
-  AutoCompleteRoot,
-  AutoCompleteSeparator,
-  AutoCompleteShortcut,
-  Button,
-  MenuContent,
-  MenuGroup,
-  MenuRoot,
-  MenuSub,
-  MenuSubContent,
-  MenuSubTrigger,
-  MenuTrigger,
-  Popover,
-} from "../../components";
-import { useHotkey } from "../../hooks";
-
-const meta: Meta<typeof AutoComplete> = {
-  title: "Data entry/AutoComplete",
-  component: AutoComplete,
+  Autocomplete,
+  AutocompleteCollection,
+  AutocompleteEmpty,
+  AutocompleteGroup,
+  AutocompleteGroupLabel,
+  AutocompleteInput,
+  AutocompleteItem,
+  AutocompleteList,
+  type AutocompleteOption,
+  AutocompletePopup,
+  AutocompleteRoot,
+  AutocompleteRow,
+  AutocompleteSeparator,
+  AutocompleteStatus,
+  AutocompleteValue,
+  useAutocompleteFilter,
+} from "./auto-complete";
+
+/**
+ * Autocomplete / combobox built on [Base UI Autocomplete](https://base-ui.com/react/components/autocomplete).
+ * Provides a composite `<Autocomplete>` for standard use cases and individual primitives
+ * for full structural control (groups, custom layouts, async search).
+ *
+ * Key behaviors:
+ * - `autoHighlight` is `true` by default in `AutocompleteRoot` — the first filtered item is
+ *   highlighted as the user types without requiring an explicit selection.
+ * - `adornment` on `AutocompleteInput` is mutually exclusive: `"trigger"` renders the chevron
+ *   button, `"clear"` renders the X button. Setting both is not possible by design.
+ * - In the composite `Autocomplete`, `onValueChange` fires with the full `TOption` object (or `null`
+ *   on clear), not just the string value. `value` and `defaultValue` also accept `TOption | null`.
+ * - `itemToStringValue` on `AutocompleteRoot` controls what is shown in the input after selection.
+ *   The composite sets it to `(opt) => opt.label` automatically.
+ * - `filter={null}` disables client-side filtering entirely — use it for server-side search.
+ * - `AutocompleteStatus` collapses to zero height when its children are empty (`empty:m-0 empty:p-0`).
+ *   Pass `undefined` (not an empty string) to hide it.
+ * - `AutocompleteEmpty` is shown by Base UI only when the list has no visible items.
+ *
+ * Reference: [Base UI – Autocomplete](https://base-ui.com/react/components/autocomplete)
+ */
+const meta: Meta<typeof Autocomplete> = {
+  title: "Components/Autocomplete",
+  component: Autocomplete,
+  parameters: { layout: "centered" },
+  decorators: [
+    (Story) => (
+      <div className="w-72">
+        <Story />
+      </div>
+    ),
+  ],
+  args: {
+    items: [
+      { value: "apple", label: "Apple" },
+      { value: "banana", label: "Banana" },
+      { value: "cherry", label: "Cherry" },
+      { value: "grape", label: "Grape" },
+      { value: "kiwi", label: "Kiwi" },
+      { value: "mango", label: "Mango" },
+      { value: "orange", label: "Orange" },
+      { value: "peach", label: "Peach" },
+      { value: "pear", label: "Pear" },
+      { value: "strawberry", label: "Strawberry" },
+    ],
+    placeholder: "Search...",
+    emptyMessage: "No results",
+  },
+  argTypes: {
+    onValueChange: { control: false },
+    renderOption: { control: false },
+    startAddon: { control: false },
+    classNames: { control: false },
+  },
 };
 
 export default meta;
-type Story = StoryObj<typeof AutoComplete>;
+type Story = StoryObj<typeof Autocomplete>;
+
+export const Default: Story = {};
+
+/**
+ * `className` styles the input field. `classNames` exposes the popup, list,
+ * item, empty, and status slots for fine-grained tweaks without dropping to
+ * the primitive composition.
+ *
+ * For deeper customization (custom layouts, extra slots, async patterns) use
+ * the primitives directly — they are the real extension point.
+ */
+export const WithClassNames: Story = {
+  args: {
+    className: "w-80",
+    classNames: {
+      popup: "max-h-60",
+      item: "py-2",
+      empty: "italic",
+    },
+  },
+};
+
+/**
+ * The trigger button opens and closes the popup on click — useful when
+ * the user wants to browse all options without typing.
+ */
+export const WithTrigger: Story = {
+  args: {
+    adornment: "trigger",
+  },
+};
 
-const items = [
-  { value: "apple", label: "Apple" },
-  { value: "banana", label: "Banana" },
-  { value: "cherry", label: "Cherry" },
-];
+/**
+ * The clear button appears whenever the input has a value and resets it on click.
+ * `adornment` is mutually exclusive — `"clear"` and `"trigger"` cannot both be active.
+ */
+export const WithClear: Story = {
+  args: {
+    adornment: "clear",
+  },
+};
 
-export const Default: Story = {
+export const WithStartAddon: Story = {
   args: {
-    items: items,
-    onSelect: console.log,
-    placeholder: "Search fruits",
+    startAddon: <SearchIcon />,
+  },
+};
+
+export const Disabled: Story = {
+  args: { disabled: true },
+};
+
+export const ReadOnly: Story = {
+  args: { readOnly: true, defaultValue: { value: "mango", label: "Mango" } },
+};
+
+/**
+ * `renderOption` receives the full option object typed as `TOption extends AutocompleteOption`
+ * and returns a `ReactNode`. Use it to render icons, metadata, descriptions, or any layout.
+ * When `renderOption` is provided, `option.label` is NOT rendered automatically.
+ *
+ * Extend `AutocompleteOption` to add extra fields:
+ * ```ts
+ * interface UserOption extends AutocompleteOption {
+ *   role: "admin" | "user" | "company";
+ * }
+ * ```
+ */
+export const WithCustomOption: Story = {
+  render: () => {
+    interface UserOption {
+      value: string;
+      label: string;
+      role: string;
+    }
+
+    const users: UserOption[] = [
+      { value: "ana", label: "Ana García", role: "admin" },
+      { value: "carlos", label: "Carlos López", role: "user" },
+      { value: "maria", label: "María Fernández", role: "admin" },
+      { value: "acme", label: "Acme Corp.", role: "company" },
+    ];
+
+    const RoleIcon = ({ role }: { role: string }) =>
+      role === "company" ? (
+        <BuildingIcon className="size-4 shrink-0 text-muted-foreground" />
+      ) : (
+        <UserIcon className="size-4 shrink-0 text-muted-foreground" />
+      );
+
+    return (
+      <Autocomplete
+        items={users}
+        placeholder="Search user..."
+        emptyMessage="No users found"
+        adornment="clear"
+        startAddon={<SearchIcon />}
+        renderOption={(u) => (
+          <span className="flex items-center gap-2">
+            <RoleIcon role={u.role} />
+            <span className="flex-1">{u.label}</span>
+            <span className="text-xs capitalize text-muted-foreground">
+              {u.role}
+            </span>
+          </span>
+        )}
+      />
+    );
   },
 };
 
 /**
- * Componente primitive AutoComplete que permite construir un campo de búsqueda con sugerencias.
- * Filtra y ordena los elementos de una lista de sugerencias.
- * ## Estructura
+ * `onValueChange` fires with the full `TOption` object (or `null` when cleared).
+ * `value` and `defaultValue` also accept `TOption | null`, matching the
+ * same pattern as `Select` and `Combobox` in this library.
+ *
+ * To clear programmatically, set `value={null}`.
+ */
+export const Controlled: Story = {
+  render: () => {
+    const items = [
+      { value: "apple", label: "Apple" },
+      { value: "banana", label: "Banana" },
+      { value: "cherry", label: "Cherry" },
+      { value: "grape", label: "Grape" },
+      { value: "mango", label: "Mango" },
+      { value: "orange", label: "Orange" },
+    ];
+    const [selected, setSelected] = useState<AutocompleteOption | null>(null);
+
+    return (
+      <div className="flex flex-col gap-4">
+        <Autocomplete
+          items={items}
+          value={selected}
+          onValueChange={setSelected}
+          adornment="clear"
+          placeholder="Search fruit..."
+          emptyMessage="No results"
+        />
+        <p className="text-sm text-muted-foreground">
+          Selected:{" "}
+          <strong>
+            {selected ? `${selected.label} (${selected.value})` : "—"}
+          </strong>
+        </p>
+      </div>
+    );
+  },
+};
+
+/**
+ * For server-side search, set `filter={null}` on `AutocompleteRoot` to disable client-side
+ * filtering entirely — the caller owns the `items` prop and updates it on each keystroke.
+ *
+ * Pattern:
+ * - `useTransition` exposes a `isPending` flag without blocking the UI.
+ * - `AbortController` cancels the previous request when the user types again.
+ * - `useAutocompleteFilter` provides the same `contains` logic used internally,
+ *   so you can apply it on the server response if needed.
+ * - Hide `AutocompleteEmpty` while `isPending` to avoid a flash of "no results".
+ *
+ * ```tsx
+ * <AutocompleteRoot
+ *   items={results}
+ *   filter={null}
+ *   itemToStringValue={(item) => item.label}
+ *   onValueChange={search}
+ * >
+ *   <AutocompleteInput placeholder="Search..." adornment="clear"/>
+ *   <AutocompletePopup>
+ *     <AutocompleteStatus>{isPending ? "Searching..." : undefined}</AutocompleteStatus>
+ *     <AutocompleteList>
+ *       {(item) => (
+ *         <AutocompleteItem key={item.value} value={item}>
+ *           {item.label}
+ *         </AutocompleteItem>
+ *       )}
+ *     </AutocompleteList>
+ *     {!isPending && <AutocompleteEmpty>No results</AutocompleteEmpty>}
+ *   </AutocompletePopup>
+ * </AutocompleteRoot>
+ * ```
+ */
+export const AsyncSearch: Story = {
+  render: () => {
+    const allFruits = [
+      { value: "apple", label: "Apple" },
+      { value: "banana", label: "Banana" },
+      { value: "cherry", label: "Cherry" },
+      { value: "grape", label: "Grape" },
+      { value: "kiwi", label: "Kiwi" },
+      { value: "mango", label: "Mango" },
+      { value: "orange", label: "Orange" },
+    ];
+
+    const [results, setResults] = useState<typeof allFruits>([]);
+    const [isPending, startTransition] = useTransition();
+    const abortRef = useRef<AbortController | null>(null);
+    const { contains } = useAutocompleteFilter();
+
+    const search = (query: string) => {
+      abortRef.current?.abort();
+      const controller = new AbortController();
+      abortRef.current = controller;
+
+      if (!query) {
+        setResults([]);
+        return;
+      }
+
+      startTransition(async () => {
+        await new Promise((r) => setTimeout(r, 400));
+        if (controller.signal.aborted) return;
+        startTransition(() => {
+          setResults(allFruits.filter((f) => contains(f.label, query)));
+        });
+      });
+    };
+
+    return (
+      <AutocompleteRoot items={results} filter={null} onValueChange={search}>
+        <AutocompleteInput placeholder="Search fruit..." adornment="clear" />
+        <AutocompletePopup>
+          <AutocompleteStatus>
+            {isPending ? "Searching..." : undefined}
+          </AutocompleteStatus>
+          <AutocompleteList>
+            {(fruit) => (
+              <AutocompleteItem key={fruit.value} value={fruit}>
+                {fruit.label}
+              </AutocompleteItem>
+            )}
+          </AutocompleteList>
+          {!isPending && <AutocompleteEmpty>No results</AutocompleteEmpty>}
+        </AutocompletePopup>
+      </AutocompleteRoot>
+    );
+  },
+};
+
+/**
+ * Grouped items require the primitive composition pattern — the composite `Autocomplete`
+ * does not support groups. Pass group objects to `AutocompleteRoot.items`, where each group
+ * has a nested `items` array. Use `AutocompleteCollection` inside each `AutocompleteGroup`
+ * so Base UI can filter and highlight items within groups independently.
+ *
+ * `AutocompleteGroupLabel` is sticky and not selectable. `[[role=group]+&]:mt-1.5` on
+ * `AutocompleteGroup` adds spacing between consecutive groups automatically.
+ *
  * ```tsx
- * <AutocompleteRoot>
- *   <AutocompleteInput placeholder="Buscar..." />
+ * <AutocompleteRoot items={groups}>
  *   <AutocompleteList>
- *     <AutocompleteEmpty>No Se Encontraron Resultados</AutocompleteEmpty>
- *     <AutocompleteGroup>
- *       <AutocompleteItem>Calendario</AutocompleteItem>
- *       <AutocompleteItem>Eventos</AutocompleteItem>
- *       <AutocompleteItem>Archivados</AutocompleteItem>
- *     </AutocompleteGroup>
+ *     {(group) => (
+ *       <AutocompleteGroup key={group.value} items={group.items}>
+ *         <AutocompleteGroupLabel>{group.label}</AutocompleteGroupLabel>
+ *         <AutocompleteCollection>
+ *           {(item) => (
+ *             <AutocompleteItem key={item.value} value={item}>
+ *               {item.label}
+ *             </AutocompleteItem>
+ *           )}
+ *         </AutocompleteCollection>
+ *       </AutocompleteGroup>
+ *     )}
  *   </AutocompleteList>
  * </AutocompleteRoot>
- *  ```
- *  */
-export const Primitive: Story = {
+ * ```
+ */
+export const WithGroups: Story = {
   render: () => {
+    interface FoodItem {
+      value: string;
+      label: string;
+    }
+    interface FoodGroup {
+      value: string;
+      items: FoodItem[];
+    }
+
+    const groups: FoodGroup[] = [
+      {
+        value: "fruits",
+        items: [
+          { value: "apple", label: "Apple" },
+          { value: "banana", label: "Banana" },
+          { value: "orange", label: "Orange" },
+        ],
+      },
+      {
+        value: "vegetables",
+        items: [
+          { value: "carrot", label: "Carrot" },
+          { value: "spinach", label: "Spinach" },
+          { value: "broccoli", label: "Broccoli" },
+        ],
+      },
+    ];
+
     return (
-      <AutoCompleteRoot className="border border-input">
-        <AutoCompleteInput placeholder="Buscar..." />
-        <AutoCompleteList>
-          <AutoCompleteEmpty>No se encontraron resultados</AutoCompleteEmpty>
-          <AutoCompleteGroup>
-            <AutoCompleteItem>Calendario</AutoCompleteItem>
-            <AutoCompleteItem>Eventos</AutoCompleteItem>
-            <AutoCompleteItem>Archivados</AutoCompleteItem>
-          </AutoCompleteGroup>
-          <AutoCompleteSeparator />
-        </AutoCompleteList>
-      </AutoCompleteRoot>
+      <AutocompleteRoot items={groups}>
+        <AutocompleteInput placeholder="Search food..." adornment="trigger" />
+        <AutocompletePopup>
+          <AutocompleteList>
+            {(group: FoodGroup) => (
+              <AutocompleteGroup key={group.value} items={group.items}>
+                <AutocompleteGroupLabel className="capitalize">
+                  {group.value}
+                </AutocompleteGroupLabel>
+                <AutocompleteCollection>
+                  {(item: FoodItem) => (
+                    <AutocompleteItem key={item.value} value={item}>
+                      {item.label}
+                    </AutocompleteItem>
+                  )}
+                </AutocompleteCollection>
+              </AutocompleteGroup>
+            )}
+          </AutocompleteList>
+          <AutocompleteEmpty>No results</AutocompleteEmpty>
+        </AutocompletePopup>
+      </AutocompleteRoot>
     );
   },
 };
 
-export const Dialog: Story = {
+/**
+ * Base UI's `render` prop replaces the underlying DOM element while preserving all
+ * autocomplete behavior (keyboard navigation, ARIA attributes, filtering, selection).
+ *
+ * Pass `render={<textarea />}` to `AutocompleteInput` to enable multiline text entry.
+ * The override works because `{...props}` is spread after the default
+ * `render={<input autoComplete="off" />}` inside `AutocompleteInput`.
+ *
+ * Override `h-10` from `inputBaseClasses` via `className="h-auto"` since textarea
+ * height is determined by `rows` rather than a fixed value.
+ */
+export const customRender: Story = {
+  render: () => (
+    <AutocompleteRoot
+      items={[
+        { value: "apple", label: "Apple" },
+        { value: "banana", label: "Banana" },
+        { value: "cherry", label: "Cherry" },
+        { value: "grape", label: "Grape" },
+        { value: "kiwi", label: "Kiwi" },
+      ]}
+    >
+      <AutocompleteInput
+        placeholder="Search..."
+        render={<textarea rows={3} />}
+        className="h-auto resize-none"
+      />
+      <AutocompletePopup>
+        <AutocompleteList>
+          {(item) => (
+            <AutocompleteItem key={item.value} value={item}>
+              {item.label}
+            </AutocompleteItem>
+          )}
+        </AutocompleteList>
+        <AutocompleteEmpty>No results</AutocompleteEmpty>
+      </AutocompletePopup>
+    </AutocompleteRoot>
+  ),
+};
+
+/**
+ * `triggerProps.render` replaces the trigger's `<button>` element.
+ * Base UI transfers all accessibility attributes (aria-*, data-*, event handlers)
+ * to the provided element, so the open/close behavior is fully preserved.
+ *
+ * `triggerProps.children` replaces the default `ChevronsUpDown` icon.
+ * `triggerProps.className` is merged with (not replaced by) the default trigger classes,
+ * so positioning and sizing stay intact.
+ */
+export const WithCustomTrigger: Story = {
+  render: () => (
+    <AutocompleteRoot
+      items={[
+        { value: "apple", label: "Apple" },
+        { value: "banana", label: "Banana" },
+        { value: "cherry", label: "Cherry" },
+        { value: "grape", label: "Grape" },
+        { value: "kiwi", label: "Kiwi" },
+      ]}
+    >
+      <AutocompleteInput
+        adornment="trigger"
+        placeholder="Search fruit..."
+        triggerProps={{
+          render: <button type="button" />,
+          className:
+            "px-2 text-xs font-medium text-muted-foreground hover:text-foreground",
+          children: "▾",
+        }}
+      />
+      <AutocompletePopup>
+        <AutocompleteList>
+          {(item) => (
+            <AutocompleteItem key={item.value} value={item}>
+              {item.label}
+            </AutocompleteItem>
+          )}
+        </AutocompleteList>
+        <AutocompleteEmpty>No results</AutocompleteEmpty>
+      </AutocompletePopup>
+    </AutocompleteRoot>
+  ),
+};
+
+/**
+ * `AutocompleteRow` groups items into a horizontal row for multi-column list layouts.
+ * Useful for compact grids like color pickers, flag selectors, or emoji pickers.
+ * Each item inside the row is individually selectable and keyboard-navigable.
+ *
+ * Pass rows as the `items` array — each entry is a row, and the row's items are
+ * rendered with `AutocompleteItem` inside.
+ */
+export const WithRow: Story = {
   render: () => {
-    const [open, setOpen] = React.useState(false);
-    useHotkey("shift+/", () => setOpen((open) => !open), {
-      ignoreInputFields: false,
-    });
+    interface ColorOption {
+      value: string;
+      label: string;
+      hex: string;
+    }
+    type ColorRow = ColorOption[];
+
+    const colorRows: ColorRow[] = [
+      [
+        { value: "red", label: "Red", hex: "#ef4444" },
+        { value: "orange", label: "Orange", hex: "#f97316" },
+        { value: "yellow", label: "Yellow", hex: "#eab308" },
+      ],
+      [
+        { value: "green", label: "Green", hex: "#22c55e" },
+        { value: "blue", label: "Blue", hex: "#3b82f6" },
+        { value: "purple", label: "Purple", hex: "#a855f7" },
+      ],
+    ];
 
     return (
-      <>
-        <p className="text-sm flex items-center gap-x-2">
-          Presiona
-          <kbd className="pointer-events-none inline-flex h-5 select-none items-center gap-1 rounded border bg-muted px-1.5 font-mono text-[10px] font-medium text-muted-foreground opacity-100">
-            /
-          </kbd>
-          para abrir el diálogo de comandos.
-        </p>
-        <AutoCompleteDialog open={open} onOpenChange={setOpen}>
-          <AutoCompleteInput placeholder="Busca una vista o escribe un comando..." />
-          <AutoCompleteList>
-            <AutoCompleteEmpty>No se encontraron resultados</AutoCompleteEmpty>
-            <AutoCompleteGroup heading="Sugerencias">
-              <AutoCompleteItem onSelect={(value) => console.log(value)}>
-                <Calendar />
-                <span>Calendario</span>
-              </AutoCompleteItem>
-              <AutoCompleteItem>
-                <TicketPercent />
-                <span>Eventos</span>
-              </AutoCompleteItem>
-              <AutoCompleteItem>
-                <Archive />
-                <span>Archivados</span>
-              </AutoCompleteItem>
-            </AutoCompleteGroup>
-            <AutoCompleteSeparator />
-            <AutoCompleteGroup heading="Configuraciones">
-              <AutoCompleteItem>
-                <User />
-                <span>Mi perfil</span>
-                <AutoCompleteShortcut>P</AutoCompleteShortcut>
-              </AutoCompleteItem>
-              <AutoCompleteItem>
-                <Settings />
-                <span>Configuración</span>
-                <AutoCompleteShortcut>C</AutoCompleteShortcut>
-              </AutoCompleteItem>
-            </AutoCompleteGroup>
-          </AutoCompleteList>
-        </AutoCompleteDialog>
-      </>
+      <AutocompleteRoot
+        items={colorRows}
+        itemToStringValue={(row) => (row as ColorRow)[0]?.label ?? ""}
+      >
+        <AutocompleteInput placeholder="Search color..." />
+        <AutocompletePopup>
+          <AutocompleteList>
+            {(row: ColorRow) => (
+              <AutocompleteRow key={row[0].value}>
+                {row.map((color) => (
+                  <AutocompleteItem
+                    key={color.value}
+                    value={color}
+                    className="flex-col gap-1 rounded-md p-2 text-center text-xs"
+                  >
+                    <span
+                      className="block size-6 rounded-full border"
+                      style={{ background: color.hex }}
+                    />
+                    {color.label}
+                  </AutocompleteItem>
+                ))}
+              </AutocompleteRow>
+            )}
+          </AutocompleteList>
+          <AutocompleteEmpty>No results</AutocompleteEmpty>
+        </AutocompletePopup>
+      </AutocompleteRoot>
     );
   },
 };
 
-export const SearchableMenu = {
-  name: "Menu",
+/**
+ * `AutocompleteValue` renders the selected item's label outside the input.
+ * Use it when you need to display the current selection independently —
+ * e.g., inside a custom trigger, a badge, or a read-only display area.
+ *
+ * It renders nothing when no item is selected, so no conditional rendering is needed.
+ * The displayed text is determined by `itemToStringValue` on `AutocompleteRoot`.
+ */
+export const WithValueDisplay: Story = {
   render: () => {
-    const [open, setOpen] = useState(false);
+    const countries = [
+      { value: "ar", label: "Argentina" },
+      { value: "br", label: "Brazil" },
+      { value: "cl", label: "Chile" },
+      { value: "co", label: "Colombia" },
+      { value: "mx", label: "Mexico" },
+      { value: "uy", label: "Uruguay" },
+    ];
 
     return (
-      <MenuRoot open={open} onOpenChange={setOpen}>
-        <MenuTrigger asChild>
-          <Button variant="outline">Open</Button>
-        </MenuTrigger>
-        <MenuContent className="w-56">
-          <MenuSub>
-            <MenuSubTrigger>
-              <UserPlus className="mr-2 h-4 w-4" />
-              Añadir usuario
-            </MenuSubTrigger>
-            <MenuGroup>
-              <MenuSubContent>
-                <AutoCompleteRoot>
-                  <AutoCompleteInput placeholder="Buscar..." autoFocus={true} />
-                  <AutoCompleteList>
-                    <AutoCompleteEmpty>No hay resultados</AutoCompleteEmpty>
-                    <AutoCompleteGroup heading="Medio de notificación">
-                      <AutoCompleteItem>
-                        <Mail />
-                        Correo electrónico
-                      </AutoCompleteItem>
-                      <AutoCompleteItem>
-                        <Slack />
-                        Slack
-                      </AutoCompleteItem>
-                      <AutoCompleteItem>
-                        <Github />
-                        Github
-                      </AutoCompleteItem>
-                      <AutoCompleteItem>
-                        <FlameKindling />
-                        Señal de humo
-                      </AutoCompleteItem>
-                    </AutoCompleteGroup>
-                  </AutoCompleteList>
-                </AutoCompleteRoot>
-              </MenuSubContent>
-            </MenuGroup>
-          </MenuSub>
-        </MenuContent>
-      </MenuRoot>
+      <AutocompleteRoot
+        items={countries}
+        itemToStringValue={(c) => (c as (typeof countries)[0]).label}
+      >
+        <AutocompleteInput placeholder="Search country..." adornment="clear" />
+        <div className="mt-2 flex items-center gap-2 text-sm text-muted-foreground">
+          <span>Selected:</span>
+          <AutocompleteValue />
+        </div>
+        <AutocompletePopup>
+          <AutocompleteList>
+            {(country) => (
+              <AutocompleteItem key={country.value} value={country}>
+                {country.label}
+              </AutocompleteItem>
+            )}
+          </AutocompleteList>
+          <AutocompleteEmpty>No results</AutocompleteEmpty>
+        </AutocompletePopup>
+      </AutocompleteRoot>
     );
   },
 };
 
-export const SearchablePopover = {
-  name: "Popover",
+/**
+ * Direct composition with all primitives for full structural control.
+ * Use when the composite `Autocomplete` is not enough — custom element ordering,
+ * extra slots between parts, non-standard layouts, or `AutocompleteSeparator` usage.
+ *
+ * `AutocompleteSeparator` uses `last:hidden` to suppress a trailing divider automatically.
+ *
+ * ```tsx
+ * <AutocompleteRoot items={items}>
+ *   <AutocompleteInput placeholder="Search..." adornment="clear"/>
+ *   <AutocompletePopup>
+ *     <AutocompleteStatus>{status}</AutocompleteStatus>
+ *     <AutocompleteList>
+ *       {(item) => (
+ *         <>
+ *           <AutocompleteItem key={item.value} value={item}>
+ *             {item.label}
+ *           </AutocompleteItem>
+ *           <AutocompleteSeparator />
+ *         </>
+ *       )}
+ *     </AutocompleteList>
+ *     <AutocompleteEmpty>No results</AutocompleteEmpty>
+ *   </AutocompletePopup>
+ * </AutocompleteRoot>
+ * ```
+ */
+export const Primitive: Story = {
   render: () => {
+    const countries = [
+      { value: "ar", label: "Argentina" },
+      { value: "br", label: "Brazil" },
+      { value: "cl", label: "Chile" },
+      { value: "co", label: "Colombia" },
+      { value: "mx", label: "Mexico" },
+      { value: "uy", label: "Uruguay" },
+    ];
+
     return (
-      <Popover
-        trigger={
-          <Button>
-            <UserPlus className="mr-2 h-4 w-4" />
-            Añadir usuario
-          </Button>
-        }
-      >
-        <AutoCompleteRoot>
-          <AutoCompleteInput placeholder="Buscar..." autoFocus={true} />
-          <AutoCompleteList>
-            <AutoCompleteEmpty>No hay resultados</AutoCompleteEmpty>
-            <AutoCompleteGroup heading="Medio de notificación">
-              <AutoCompleteItem>
-                <Mail />
-                Correo electrónico
-              </AutoCompleteItem>
-              <AutoCompleteItem>
-                <Slack />
-                Slack
-              </AutoCompleteItem>
-              <AutoCompleteItem>
-                <Github />
-                Github
-              </AutoCompleteItem>
-              <AutoCompleteItem>
-                <FlameKindling />
-                Señal de humo
-              </AutoCompleteItem>
-            </AutoCompleteGroup>
-          </AutoCompleteList>
-        </AutoCompleteRoot>
-      </Popover>
+      <AutocompleteRoot items={countries}>
+        <AutocompleteInput placeholder="Search country..." adornment="clear" />
+        <AutocompletePopup>
+          <AutocompleteList>
+            {(country) => (
+              <>
+                <AutocompleteItem key={country.value} value={country}>
+                  {country.label}
+                </AutocompleteItem>
+                <AutocompleteSeparator />
+              </>
+            )}
+          </AutocompleteList>
+          <AutocompleteEmpty>No results</AutocompleteEmpty>
+        </AutocompletePopup>
+      </AutocompleteRoot>
     );
   },
 };