@central-ui/react 0.0.0-stage → 0.1.1

package/dist/utils/virtualization/useVirtualizedAutocomplete.d.ts

@@ -0,0 +1,198 @@
+import type { CSSProperties } from 'react';
+import type { GroupShape, ItemShape, ItemType } from '../../components/autocomplete/index.tsx';
+export type UseVirtualizedAutocompleteOptions<T extends readonly GroupShape[]> = {
+    /**
+     * Supply the complete grouped data; rootProps passes this same data to Autocomplete.Root.
+     * Let native search filter it through AutocompleteFilteredItemsSync; do not pass only
+     * the visible rows back to Root. For a flat source, use one group with label: ''.
+     * @example items: cityGroups
+     */
+    items: T;
+    /**
+     * Match the rendered row height in pixels, including any spacing between rows.
+     * Use a callback when rows have known different heights. This hook does not
+     * automatically measure rendered rows; inaccurate sizes can leave gaps or overlaps.
+     * @example estimateSize: 34
+     * @example estimateSize: (city) => city.label.length > 30 ? 56 : 34
+     * @default 34
+     */
+    estimateSize?: number | ((item: ItemType<T>, index: number) => number);
+    /**
+     * Mount extra rows above and below the visible area to reduce blanks during fast
+     * scrolling. Increase this if needed, at the cost of rendering more rows.
+     * @example overscan: 8
+     * @default 5
+     */
+    overscan?: number;
+    /**
+     * Account for space before ItemsList inside ScrollArea, such as a group heading
+     * and leading padding. Match your actual layout; this does not render a heading
+     * or add CSS padding for you. Omit when there is no leading space.
+     * @example paddingStart: 32
+     * @default 0
+     */
+    paddingStart?: number;
+    /**
+     * Account for space after ItemsList inside ScrollArea, such as group bottom
+     * padding. Match the space your markup already supplies; this adds no CSS padding.
+     * @example paddingEnd: 4
+     * @default 0
+     */
+    paddingEnd?: number;
+    /**
+     * Cap the scrolling viewport height while allowing short lists to shrink.
+     * Choose this independently of the space available around the popup.
+     * @example maxHeight: 480
+     * @default 320
+     */
+    maxHeight?: number;
+    /**
+     * Apply an additional CSS max-height to the scrolling viewport.
+     * The default uses the popup's available space so it can fit near a screen edge.
+     * For a custom popup layout without that CSS variable, supply your own constraint.
+     * @example availableHeight: 'calc(100dvh - 160px)'
+     * @default 'var(--available-height)'
+     */
+    availableHeight?: CSSProperties['maxHeight'];
+};
+/**
+ * Virtualize a large Autocomplete while keeping native search and keyboard behavior.
+ * Call this hook in your component, outside Root. Spread each returned props object
+ * on its matching element, and keep AutocompleteFilteredItemsSync mounted inside Popup
+ * so native filtering supplies the complete results. Keep rootProps.onItemHighlighted
+ * connected; it scrolls keyboard highlights into view. Merge it if adding your own callback.
+ *
+ * Filtered groups are flattened into one list: this hook does not virtualize separate
+ * group headings. Use one shared heading, as below, or omit GroupLabel for a flat list
+ * and adjust paddingStart. Preserve the returned refs and layout styles when customizing.
+ * Render only rows, but give Group all filteredItems and each Item its returned index.
+ * The mapped rows already preserve your custom item fields; no manual annotation is needed.
+ *
+ * @example Complete virtualized Autocomplete
+ * import {
+ *   Autocomplete,
+ *   AutocompleteFilteredItemsSync,
+ *   useVirtualizedAutocomplete,
+ * } from '@central-ui/react'
+ *
+ * // Replace this sample with your larger dataset; keep the source stable between renders.
+ * const cityGroups = [{
+ *   label: 'Cities',
+ *   items: [
+ *     { value: 'ma-rabat', label: 'Rabat', country: 'Morocco', population: 580000 },
+ *     { value: 'ma-casablanca', label: 'Casablanca', country: 'Morocco', population: 3359818 },
+ *     { value: 'fr-paris', label: 'Paris', country: 'France', population: 2102650 },
+ *   ],
+ * }]
+ *
+ * function CityAutocomplete() {
+ *   const virtual = useVirtualizedAutocomplete({
+ *     items: cityGroups, // rootProps supplies these complete groups to Root.
+ *     estimateSize: 34, // Match the row height plus spacing in your layout.
+ *     paddingStart: 32, // Match the heading and leading space; adjust if styled differently.
+ *     paddingEnd: 4, // Match the trailing group padding.
+ *   })
+ *
+ *   return (
+ *     <Autocomplete.Root {...virtual.rootProps} openOnInputClick>
+ *       <Autocomplete.Container>
+ *         <Autocomplete.Label>City</Autocomplete.Label>
+ *         <Autocomplete.InputGroup>
+ *           <Autocomplete.Input placeholder="Search cities" />
+ *           <Autocomplete.Addon>
+ *             <Autocomplete.AddonOpenButton aria-label="Show cities">
+ *               <Autocomplete.AddonOpenButtonIcon />
+ *             </Autocomplete.AddonOpenButton>
+ *             <Autocomplete.AddonClearButton aria-label="Clear city">
+ *               <Autocomplete.AddonClearButtonIcon />
+ *             </Autocomplete.AddonClearButton>
+ *           </Autocomplete.Addon>
+ *         </Autocomplete.InputGroup>
+ *         <Autocomplete.Popup>
+ *           <AutocompleteFilteredItemsSync {...virtual.filteredItemsSyncProps} />
+ *           <Autocomplete.Empty // Keep mounted; native filtering controls visibility.
+ *           >
+ *             <Autocomplete.EmptyText>No cities found.</Autocomplete.EmptyText>
+ *           </Autocomplete.Empty>
+ *           <Autocomplete.ScrollArea {...virtual.scrollAreaProps}>
+ *             <Autocomplete.GroupsList>
+ *               {virtual.filteredItems.length > 0 && (
+ *                 <Autocomplete.Group items={virtual.filteredItems}>
+ *                   <Autocomplete.GroupLabel>Cities</Autocomplete.GroupLabel>
+ *                   <Autocomplete.ItemsList {...virtual.itemsListProps}>
+ *                     {virtual.rows.map((row) => (
+ *                       <Autocomplete.Item
+ *                         key={row.key}
+ *                         value={row.item}
+ *                         index={row.index} // Preserve the index in the full filtered list.
+ *                         {...row.itemProps}
+ *                       >
+ *                         <Autocomplete.ItemText>{row.item.label}</Autocomplete.ItemText>
+ *                       </Autocomplete.Item>
+ *                     ))}
+ *                   </Autocomplete.ItemsList>
+ *                 </Autocomplete.Group>
+ *               )}
+ *             </Autocomplete.GroupsList>
+ *           </Autocomplete.ScrollArea>
+ *         </Autocomplete.Popup>
+ *       </Autocomplete.Container>
+ *     </Autocomplete.Root>
+ *   )
+ * }
+ */
+export declare function useVirtualizedAutocomplete<T extends readonly GroupShape[]>({ items: source, estimateSize, overscan, paddingStart, paddingEnd, maxHeight, availableHeight, }: UseVirtualizedAutocompleteOptions<T>): {
+    rootProps: {
+        items: T;
+        virtualized: true;
+        onItemHighlighted: (highlightedValue: ItemType<T> | undefined, eventDetails: import("@base-ui/react").AutocompleteRootHighlightEventDetails) => void;
+    };
+    filteredItemsSyncProps: {
+        onChange: (next: ItemType<T>[]) => void;
+    };
+    filteredItems: ItemType<T>[];
+    scrollAreaProps: {
+        ref: import("react").RefObject<HTMLDivElement | null>;
+        style: {
+            height: number;
+            maxHeight: import("csstype").Property.MaxHeight<string | number>;
+        };
+    };
+    itemsListProps: {
+        style: {
+            position: "relative";
+            height: number;
+            flexShrink: number;
+        };
+    };
+    rows: {
+        key: string | number | bigint;
+        index: number;
+        item: ItemType<T>;
+        start: number;
+        size: number;
+        itemProps: {
+            style: {
+                position: "absolute";
+                top: number;
+                left: number;
+                width: string;
+                transform: `translateY(${number}px)`;
+            };
+            'aria-setsize': number;
+            'aria-posinset': number;
+        };
+    }[];
+    scrollToIndex: (index: number, options?: Parameters<(index: number, { align: initialAlign, behavior, }?: import("@tanstack/virtual-core").ScrollToOptions) => void>[1]) => void;
+    virtualizer: import("@tanstack/react-virtual").ReactVirtualizer<HTMLDivElement, HTMLDivElement>;
+};
+/**
+ * Renders nothing. Mount inside Root (normally inside Popup) to mirror the
+ * complete native search results into the external virtualization hook.
+ * The callback infers the item type, including extra fields, without a cast.
+ */
+export declare function FilteredItemsSync<Item extends ItemShape>({ onChange, }: {
+    /** Spread the hook's filteredItemsSyncProps here to sync all native search results, not just mounted rows. */
+    onChange: (items: Item[]) => void;
+}): null;
+//# sourceMappingURL=useVirtualizedAutocomplete.d.ts.map

package/dist/utils/virtualization/useVirtualizedAutocomplete.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useVirtualizedAutocomplete.d.ts","sourceRoot":"","sources":["../../../src/utils/virtualization/useVirtualizedAutocomplete.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAA;AAE1C,OAAO,KAAK,EACV,UAAU,EACV,SAAS,EACT,QAAQ,EACT,MAAM,yCAAyC,CAAA;AAEhD,MAAM,MAAM,iCAAiC,CAAC,CAAC,SAAS,SAAS,UAAU,EAAE,IAC3E;IACE;;;;;OAKG;IACH,KAAK,EAAE,CAAC,CAAA;IACR;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC,CAAA;IACtE;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,aAAa,CAAC,WAAW,CAAC,CAAA;CAC7C,CAAA;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqFG;AACH,wBAAgB,0BAA0B,CAAC,CAAC,SAAS,SAAS,UAAU,EAAE,EAAE,EAC1E,KAAK,EAAE,MAAM,EACb,YAAiB,EACjB,QAAY,EACZ,YAAgB,EAChB,UAAc,EACd,SAAe,EACf,eAA2C,GAC5C,EAAE,iCAAiC,CAAC,CAAC,CAAC;;;;;;;yBA4F5B,QAAQ,CAAC,CAAC,CAAC,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;2BA5BX,MAAM,YACH,UAAU,gHAAkC,CAAC,CAAC,CAAC;;EAyC9D;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,SAAS,SAAS,EAAE,EACxD,QAAQ,GACT,EAAE;IACD,8GAA8G;IAC9G,QAAQ,EAAE,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,IAAI,CAAA;CAClC,QAUA"}

package/dist/utils/virtualization/useVirtualizedAutocomplete.js

@@ -0,0 +1,180 @@
+import { Autocomplete as BaseAutocomplete } from '@base-ui/react/autocomplete';
+import { useCallback, useLayoutEffect, useRef, useState } from 'react';
+import { useVirtualizer } from '@tanstack/react-virtual';
+/**
+ * Virtualize a large Autocomplete while keeping native search and keyboard behavior.
+ * Call this hook in your component, outside Root. Spread each returned props object
+ * on its matching element, and keep AutocompleteFilteredItemsSync mounted inside Popup
+ * so native filtering supplies the complete results. Keep rootProps.onItemHighlighted
+ * connected; it scrolls keyboard highlights into view. Merge it if adding your own callback.
+ *
+ * Filtered groups are flattened into one list: this hook does not virtualize separate
+ * group headings. Use one shared heading, as below, or omit GroupLabel for a flat list
+ * and adjust paddingStart. Preserve the returned refs and layout styles when customizing.
+ * Render only rows, but give Group all filteredItems and each Item its returned index.
+ * The mapped rows already preserve your custom item fields; no manual annotation is needed.
+ *
+ * @example Complete virtualized Autocomplete
+ * import {
+ *   Autocomplete,
+ *   AutocompleteFilteredItemsSync,
+ *   useVirtualizedAutocomplete,
+ * } from '@central-ui/react'
+ *
+ * // Replace this sample with your larger dataset; keep the source stable between renders.
+ * const cityGroups = [{
+ *   label: 'Cities',
+ *   items: [
+ *     { value: 'ma-rabat', label: 'Rabat', country: 'Morocco', population: 580000 },
+ *     { value: 'ma-casablanca', label: 'Casablanca', country: 'Morocco', population: 3359818 },
+ *     { value: 'fr-paris', label: 'Paris', country: 'France', population: 2102650 },
+ *   ],
+ * }]
+ *
+ * function CityAutocomplete() {
+ *   const virtual = useVirtualizedAutocomplete({
+ *     items: cityGroups, // rootProps supplies these complete groups to Root.
+ *     estimateSize: 34, // Match the row height plus spacing in your layout.
+ *     paddingStart: 32, // Match the heading and leading space; adjust if styled differently.
+ *     paddingEnd: 4, // Match the trailing group padding.
+ *   })
+ *
+ *   return (
+ *     <Autocomplete.Root {...virtual.rootProps} openOnInputClick>
+ *       <Autocomplete.Container>
+ *         <Autocomplete.Label>City</Autocomplete.Label>
+ *         <Autocomplete.InputGroup>
+ *           <Autocomplete.Input placeholder="Search cities" />
+ *           <Autocomplete.Addon>
+ *             <Autocomplete.AddonOpenButton aria-label="Show cities">
+ *               <Autocomplete.AddonOpenButtonIcon />
+ *             </Autocomplete.AddonOpenButton>
+ *             <Autocomplete.AddonClearButton aria-label="Clear city">
+ *               <Autocomplete.AddonClearButtonIcon />
+ *             </Autocomplete.AddonClearButton>
+ *           </Autocomplete.Addon>
+ *         </Autocomplete.InputGroup>
+ *         <Autocomplete.Popup>
+ *           <AutocompleteFilteredItemsSync {...virtual.filteredItemsSyncProps} />
+ *           <Autocomplete.Empty // Keep mounted; native filtering controls visibility.
+ *           >
+ *             <Autocomplete.EmptyText>No cities found.</Autocomplete.EmptyText>
+ *           </Autocomplete.Empty>
+ *           <Autocomplete.ScrollArea {...virtual.scrollAreaProps}>
+ *             <Autocomplete.GroupsList>
+ *               {virtual.filteredItems.length > 0 && (
+ *                 <Autocomplete.Group items={virtual.filteredItems}>
+ *                   <Autocomplete.GroupLabel>Cities</Autocomplete.GroupLabel>
+ *                   <Autocomplete.ItemsList {...virtual.itemsListProps}>
+ *                     {virtual.rows.map((row) => (
+ *                       <Autocomplete.Item
+ *                         key={row.key}
+ *                         value={row.item}
+ *                         index={row.index} // Preserve the index in the full filtered list.
+ *                         {...row.itemProps}
+ *                       >
+ *                         <Autocomplete.ItemText>{row.item.label}</Autocomplete.ItemText>
+ *                       </Autocomplete.Item>
+ *                     ))}
+ *                   </Autocomplete.ItemsList>
+ *                 </Autocomplete.Group>
+ *               )}
+ *             </Autocomplete.GroupsList>
+ *           </Autocomplete.ScrollArea>
+ *         </Autocomplete.Popup>
+ *       </Autocomplete.Container>
+ *     </Autocomplete.Root>
+ *   )
+ * }
+ */
+export function useVirtualizedAutocomplete({ items: source, estimateSize = 34, overscan = 5, paddingStart = 0, paddingEnd = 0, maxHeight = 320, availableHeight = 'var(--available-height)', }) {
+    const [filteredItems, setFilteredItems] = useState([]);
+    const scrollRef = useRef(null);
+    const virtualizer = useVirtualizer({
+        count: filteredItems.length,
+        getScrollElement: () => scrollRef.current,
+        estimateSize: (index) => typeof estimateSize === 'function'
+            ? estimateSize(filteredItems[index], index)
+            : estimateSize,
+        getItemKey: (index) => filteredItems[index].value,
+        overscan,
+        paddingStart,
+        paddingEnd,
+    });
+    // Filtering or sorting supplies a new array; scrolling alone must not reset it.
+    useLayoutEffect(() => {
+        virtualizer.scrollToOffset(0);
+    }, [filteredItems, virtualizer]);
+    const totalSize = virtualizer.getTotalSize();
+    const virtualRows = virtualizer.getVirtualItems();
+    const scrollAreaProps = {
+        ref: scrollRef,
+        style: {
+            height: Math.min(totalSize, maxHeight),
+            maxHeight: availableHeight,
+        },
+    };
+    // Exclude the space already occupied by the caller's heading and padding.
+    const itemsListProps = {
+        style: {
+            position: 'relative',
+            height: totalSize - paddingStart - paddingEnd,
+            flexShrink: 0,
+        },
+    };
+    const rows = virtualRows.map((row) => ({
+        key: row.key,
+        index: row.index,
+        item: filteredItems[row.index],
+        start: row.start,
+        size: row.size,
+        itemProps: {
+            style: {
+                position: 'absolute',
+                top: 0,
+                left: 0,
+                width: '100%',
+                transform: `translateY(${row.start - paddingStart}px)`,
+            },
+            'aria-setsize': filteredItems.length,
+            'aria-posinset': row.index + 1,
+        },
+    }));
+    const scrollToIndex = useCallback((index, options) => virtualizer.scrollToIndex(index, { align: 'auto', ...options }), [virtualizer]);
+    const onItemHighlighted = useCallback((item, details) => {
+        if (!item || details.index < 0)
+            return;
+        const isStart = details.index === 0;
+        const isEnd = details.index === filteredItems.length - 1;
+        // Match Base UI's virtualized example: it handles ordinary keyboard
+        // movement; the virtualizer handles initial highlights and either end.
+        if (details.reason === 'none' ||
+            (details.reason === 'keyboard' && (isStart || isEnd))) {
+            queueMicrotask(() => scrollToIndex(details.index, { align: isEnd ? 'start' : 'end' }));
+        }
+    }, [scrollToIndex, filteredItems.length]);
+    const onFilteredItemsChange = useCallback((next) => setFilteredItems(next), []);
+    return {
+        rootProps: { items: source, virtualized: true, onItemHighlighted },
+        filteredItemsSyncProps: { onChange: onFilteredItemsChange },
+        filteredItems,
+        scrollAreaProps,
+        itemsListProps,
+        rows,
+        scrollToIndex,
+        virtualizer,
+    };
+}
+/**
+ * Renders nothing. Mount inside Root (normally inside Popup) to mirror the
+ * complete native search results into the external virtualization hook.
+ * The callback infers the item type, including extra fields, without a cast.
+ */
+export function FilteredItemsSync({ onChange, }) {
+    const groups = BaseAutocomplete.useFilteredItems();
+    useLayoutEffect(() => {
+        onChange(groups.flatMap((group) => group.items));
+    }, [groups, onChange]);
+    return null;
+}
+//# sourceMappingURL=useVirtualizedAutocomplete.js.map

package/dist/utils/virtualization/useVirtualizedAutocomplete.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useVirtualizedAutocomplete.js","sourceRoot":"","sources":["../../../src/utils/virtualization/useVirtualizedAutocomplete.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,IAAI,gBAAgB,EAAE,MAAM,6BAA6B,CAAA;AAC9E,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAA;AAEtE,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAA;AAgExD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqFG;AACH,MAAM,UAAU,0BAA0B,CAAkC,EAC1E,KAAK,EAAE,MAAM,EACb,YAAY,GAAG,EAAE,EACjB,QAAQ,GAAG,CAAC,EACZ,YAAY,GAAG,CAAC,EAChB,UAAU,GAAG,CAAC,EACd,SAAS,GAAG,GAAG,EACf,eAAe,GAAG,yBAAyB,GACN;IACrC,MAAM,CAAC,aAAa,EAAE,gBAAgB,CAAC,GAAG,QAAQ,CAAgB,EAAE,CAAC,CAAA;IAErE,MAAM,SAAS,GAAG,MAAM,CAAiB,IAAI,CAAC,CAAA;IAE9C,MAAM,WAAW,GAAG,cAAc,CAAiC;QACjE,KAAK,EAAE,aAAa,CAAC,MAAM;QAC3B,gBAAgB,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,OAAO;QACzC,YAAY,EAAE,CAAC,KAAK,EAAE,EAAE,CACtB,OAAO,YAAY,KAAK,UAAU;YAChC,CAAC,CAAC,YAAY,CAAC,aAAa,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;YAC3C,CAAC,CAAC,YAAY;QAClB,UAAU,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,KAAK;QACjD,QAAQ;QACR,YAAY;QACZ,UAAU;KACX,CAAC,CAAA;IAEF,gFAAgF;IAChF,eAAe,CAAC,GAAG,EAAE;QACnB,WAAW,CAAC,cAAc,CAAC,CAAC,CAAC,CAAA;IAC/B,CAAC,EAAE,CAAC,aAAa,EAAE,WAAW,CAAC,CAAC,CAAA;IAEhC,MAAM,SAAS,GAAG,WAAW,CAAC,YAAY,EAAE,CAAA;IAC5C,MAAM,WAAW,GAAG,WAAW,CAAC,eAAe,EAAE,CAAA;IAEjD,MAAM,eAAe,GAAG;QACtB,GAAG,EAAE,SAAS;QACd,KAAK,EAAE;YACL,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,SAAS,CAAC;YACtC,SAAS,EAAE,eAAe;SACH;KAC1B,CAAA;IAED,0EAA0E;IAC1E,MAAM,cAAc,GAAG;QACrB,KAAK,EAAE;YACL,QAAQ,EAAE,UAAU;YACpB,MAAM,EAAE,SAAS,GAAG,YAAY,GAAG,UAAU;YAC7C,UAAU,EAAE,CAAC;SACU;KAC1B,CAAA;IAED,MAAM,IAAI,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QACrC,GAAG,EAAE,GAAG,CAAC,GAAG;QACZ,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,IAAI,EAAE,aAAa,CAAC,GAAG,CAAC,KAAK,CAAC;QAC9B,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,SAAS,EAAE;YACT,KAAK,EAAE;gBACL,QAAQ,EAAE,UAAU;gBACpB,GAAG,EAAE,CAAC;gBACN,IAAI,EAAE,CAAC;gBACP,KAAK,EAAE,MAAM;gBACb,SAAS,EAAE,cAAc,GAAG,CAAC,KAAK,GAAG,YAAY,KAAK;aAC/B;YACzB,cAAc,EAAE,aAAa,CAAC,MAAM;YACpC,eAAe,EAAE,GAAG,CAAC,KAAK,GAAG,CAAC;SAC/B;KACF,CAAC,CAAC,CAAA;IAEH,MAAM,aAAa,GAAG,WAAW,CAC/B,CACE,KAAa,EACb,OAAyD,EACzD,EAAE,CAAC,WAAW,CAAC,aAAa,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,EAAE,CAAC,EACpE,CAAC,WAAW,CAAC,CACd,CAAA;IAED,MAAM,iBAAiB,GAAG,WAAW,CAGnC,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE;QAChB,IAAI,CAAC,IAAI,IAAI,OAAO,CAAC,KAAK,GAAG,CAAC;YAAE,OAAM;QACtC,MAAM,OAAO,GAAG,OAAO,CAAC,KAAK,KAAK,CAAC,CAAA;QACnC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,KAAK,aAAa,CAAC,MAAM,GAAG,CAAC,CAAA;QACxD,oEAAoE;QACpE,uEAAuE;QACvE,IACE,OAAO,CAAC,MAAM,KAAK,MAAM;YACzB,CAAC,OAAO,CAAC,MAAM,KAAK,UAAU,IAAI,CAAC,OAAO,IAAI,KAAK,CAAC,CAAC,EACrD,CAAC;YACD,cAAc,CAAC,GAAG,EAAE,CAClB,aAAa,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CACjE,CAAA;QACH,CAAC;IACH,CAAC,EACD,CAAC,aAAa,EAAE,aAAa,CAAC,MAAM,CAAC,CACtC,CAAA;IAED,MAAM,qBAAqB,GAAG,WAAW,CACvC,CAAC,IAAmB,EAAE,EAAE,CAAC,gBAAgB,CAAC,IAAI,CAAC,EAC/C,EAAE,CACH,CAAA;IAED,OAAO;QACL,SAAS,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,IAAa,EAAE,iBAAiB,EAAE;QAC3E,sBAAsB,EAAE,EAAE,QAAQ,EAAE,qBAAqB,EAAE;QAC3D,aAAa;QACb,eAAe;QACf,cAAc;QACd,IAAI;QACJ,aAAa;QACb,WAAW;KACZ,CAAA;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAyB,EACxD,QAAQ,GAIT;IACC,MAAM,MAAM,GAAG,gBAAgB,CAAC,gBAAgB,EAE7C,CAAA;IAEH,eAAe,CAAC,GAAG,EAAE;QACnB,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAA;IAClD,CAAC,EAAE,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAA;IAEtB,OAAO,IAAI,CAAA;AACb,CAAC"}

package/dist/utils/virtualization/useVirtualizedCombobox.d.ts

@@ -0,0 +1,200 @@
+import { Combobox as BaseCombobox } from '@base-ui/react/combobox';
+import type { CSSProperties } from 'react';
+import type { GroupShape, ItemShape, ItemType } from '../../components/combobox/index.tsx';
+export type UseVirtualizedComboboxOptions<T extends readonly GroupShape[]> = {
+    /**
+     * Supply the complete grouped data; rootProps passes this same data to Combobox.Root.
+     * Let native search filter it through ComboboxFilteredItemsSync; do not pass only
+     * the visible rows back to Root. For a flat source, use one group with label: ''.
+     * @example items: cityGroups
+     */
+    items: T;
+    /**
+     * Match the rendered row height in pixels, including any spacing between rows.
+     * Use a callback when rows have known different heights. This hook does not
+     * automatically measure rendered rows; inaccurate sizes can leave gaps or overlaps.
+     * @example estimateSize: 34
+     * @example estimateSize: (city) => city.label.length > 30 ? 56 : 34
+     * @default 34
+     */
+    estimateSize?: number | ((item: ItemType<T>, index: number) => number);
+    /**
+     * Mount extra rows above and below the visible area to reduce blanks during fast
+     * scrolling. Increase this if needed, at the cost of rendering more rows.
+     * @example overscan: 8
+     * @default 5
+     */
+    overscan?: number;
+    /**
+     * Account for space before ItemsList inside ScrollArea, such as a group heading
+     * and leading padding. Match your actual layout; this does not render a heading
+     * or add CSS padding for you. Omit when there is no leading space.
+     * @example paddingStart: 32
+     * @default 0
+     */
+    paddingStart?: number;
+    /**
+     * Account for space after ItemsList inside ScrollArea, such as group bottom
+     * padding. Match the space your markup already supplies; this adds no CSS padding.
+     * @example paddingEnd: 4
+     * @default 0
+     */
+    paddingEnd?: number;
+    /**
+     * Cap the scrolling viewport height while allowing short lists to shrink.
+     * Choose this independently of the space available around the popup.
+     * @example maxHeight: 480
+     * @default 320
+     */
+    maxHeight?: number;
+    /**
+     * Apply an additional CSS max-height to the scrolling viewport.
+     * The default uses the popup's available space so it can fit near a screen edge.
+     * For a custom popup layout without that CSS variable, supply your own constraint.
+     * @example availableHeight: 'calc(100dvh - 160px)'
+     * @default 'var(--available-height)'
+     */
+    availableHeight?: CSSProperties['maxHeight'];
+};
+/**
+ * Virtualize a large Combobox while keeping native search and keyboard behavior.
+ * Call this hook in your component, outside Root. Spread each returned props object
+ * on its matching element, and keep ComboboxFilteredItemsSync mounted inside Popup
+ * so native filtering supplies the complete results. Keep rootProps.onItemHighlighted
+ * connected; it scrolls keyboard highlights into view. Merge it if adding your own callback.
+ *
+ * Filtered groups are flattened into one list: this hook does not virtualize separate
+ * group headings. Use one shared heading, as below, or omit GroupLabel for a flat list
+ * and adjust paddingStart. Preserve the returned refs and layout styles when customizing.
+ * Render only rows, but give Group all filteredItems and each Item its returned index.
+ * The mapped rows already preserve your custom item fields; no manual annotation is needed.
+ *
+ * @example Complete virtualized Combobox
+ * import {
+ *   Combobox,
+ *   ComboboxFilteredItemsSync,
+ *   useVirtualizedCombobox,
+ * } from '@central-ui/react'
+ *
+ * // Replace this sample with your larger dataset; keep the source stable between renders.
+ * const cityGroups = [{
+ *   label: 'Cities',
+ *   items: [
+ *     { value: 'ma-rabat', label: 'Rabat', country: 'Morocco', population: 580000 },
+ *     { value: 'ma-casablanca', label: 'Casablanca', country: 'Morocco', population: 3359818 },
+ *     { value: 'fr-paris', label: 'Paris', country: 'France', population: 2102650 },
+ *   ],
+ * }]
+ *
+ * function CityCombobox() {
+ *   const virtual = useVirtualizedCombobox({
+ *     items: cityGroups, // rootProps supplies these complete groups to Root.
+ *     estimateSize: 34, // Match the row height plus spacing in your layout.
+ *     paddingStart: 32, // Match the heading and leading space; adjust if styled differently.
+ *     paddingEnd: 4, // Match the trailing group padding.
+ *   })
+ *
+ *   return (
+ *     <Combobox.Root {...virtual.rootProps}>
+ *       <Combobox.Container>
+ *         <Combobox.Label>City</Combobox.Label>
+ *         <Combobox.InputGroup>
+ *           <Combobox.Input placeholder="Search cities" />
+ *           <Combobox.Addon>
+ *             <Combobox.AddonOpenButton aria-label="Show cities">
+ *               <Combobox.AddonOpenButtonIcon />
+ *             </Combobox.AddonOpenButton>
+ *             <Combobox.AddonClearButton aria-label="Clear city">
+ *               <Combobox.AddonClearButtonIcon />
+ *             </Combobox.AddonClearButton>
+ *           </Combobox.Addon>
+ *         </Combobox.InputGroup>
+ *         <Combobox.Popup>
+ *           <ComboboxFilteredItemsSync {...virtual.filteredItemsSyncProps} />
+ *           <Combobox.Empty // Keep mounted; native filtering controls visibility.
+ *           >
+ *             <Combobox.EmptyText>No cities found.</Combobox.EmptyText>
+ *           </Combobox.Empty>
+ *           <Combobox.ScrollArea {...virtual.scrollAreaProps}>
+ *             <Combobox.GroupsList>
+ *               {virtual.filteredItems.length > 0 && (
+ *                 <Combobox.Group items={virtual.filteredItems}>
+ *                   <Combobox.GroupLabel>Cities</Combobox.GroupLabel>
+ *                   <Combobox.ItemsList {...virtual.itemsListProps}>
+ *                     {virtual.rows.map((row) => (
+ *                       <Combobox.Item
+ *                         key={row.key}
+ *                         value={row.item}
+ *                         index={row.index} // Preserve the index in the full filtered list.
+ *                         {...row.itemProps}
+ *                       >
+ *                         <Combobox.ItemText>{row.item.label}</Combobox.ItemText>
+ *                         <Combobox.ItemIndicator />
+ *                       </Combobox.Item>
+ *                     ))}
+ *                   </Combobox.ItemsList>
+ *                 </Combobox.Group>
+ *               )}
+ *             </Combobox.GroupsList>
+ *           </Combobox.ScrollArea>
+ *         </Combobox.Popup>
+ *       </Combobox.Container>
+ *     </Combobox.Root>
+ *   )
+ * }
+ */
+export declare function useVirtualizedCombobox<T extends readonly GroupShape[]>({ items: source, estimateSize, overscan, paddingStart, paddingEnd, maxHeight, availableHeight, }: UseVirtualizedComboboxOptions<T>): {
+    rootProps: {
+        items: T;
+        virtualized: true;
+        onItemHighlighted: (highlightedValue: ItemType<T> | undefined, eventDetails: BaseCombobox.Root.HighlightEventDetails) => void;
+    };
+    filteredItemsSyncProps: {
+        onChange: (next: ItemType<T>[]) => void;
+    };
+    filteredItems: ItemType<T>[];
+    scrollAreaProps: {
+        ref: import("react").RefObject<HTMLDivElement | null>;
+        style: {
+            height: number;
+            maxHeight: import("csstype").Property.MaxHeight<string | number>;
+        };
+    };
+    itemsListProps: {
+        style: {
+            position: "relative";
+            height: number;
+            flexShrink: number;
+        };
+    };
+    rows: {
+        key: string | number | bigint;
+        index: number;
+        item: ItemType<T>;
+        start: number;
+        size: number;
+        itemProps: {
+            style: {
+                position: "absolute";
+                top: number;
+                left: number;
+                width: string;
+                transform: `translateY(${number}px)`;
+            };
+            'aria-setsize': number;
+            'aria-posinset': number;
+        };
+    }[];
+    scrollToIndex: (index: number, options?: Parameters<(index: number, { align: initialAlign, behavior, }?: import("@tanstack/virtual-core").ScrollToOptions) => void>[1]) => void;
+    virtualizer: import("@tanstack/react-virtual").ReactVirtualizer<HTMLDivElement, HTMLDivElement>;
+};
+/**
+ * Renders nothing. Mount inside Root (normally inside Popup) to mirror the
+ * complete native search results into the external virtualization hook.
+ * The callback infers the item type, including extra fields, without a cast.
+ */
+export declare function FilteredItemsSync<Item extends ItemShape>({ onChange, }: {
+    /** Spread the hook's filteredItemsSyncProps here to sync all native search results, not just mounted rows. */
+    onChange: (items: Item[]) => void;
+}): null;
+//# sourceMappingURL=useVirtualizedCombobox.d.ts.map

package/dist/utils/virtualization/useVirtualizedCombobox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useVirtualizedCombobox.d.ts","sourceRoot":"","sources":["../../../src/utils/virtualization/useVirtualizedCombobox.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,IAAI,YAAY,EAAE,MAAM,yBAAyB,CAAA;AAElE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAA;AAE1C,OAAO,KAAK,EACV,UAAU,EACV,SAAS,EACT,QAAQ,EACT,MAAM,qCAAqC,CAAA;AAE5C,MAAM,MAAM,6BAA6B,CAAC,CAAC,SAAS,SAAS,UAAU,EAAE,IAAI;IAC3E;;;;;OAKG;IACH,KAAK,EAAE,CAAC,CAAA;IACR;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC,CAAA;IACtE;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,aAAa,CAAC,WAAW,CAAC,CAAA;CAC7C,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsFG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,SAAS,SAAS,UAAU,EAAE,EAAE,EACtE,KAAK,EAAE,MAAM,EACb,YAAiB,EACjB,QAAY,EACZ,YAAgB,EAChB,UAAc,EACd,SAAe,EACf,eAA2C,GAC5C,EAAE,6BAA6B,CAAC,CAAC,CAAC;;;;;;;yBAiFxB,QAAQ,CAAC,CAAC,CAAC,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;2BAjBX,MAAM,YACH,UAAU,gHAAkC,CAAC,CAAC,CAAC;;EA8B9D;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,SAAS,SAAS,EAAE,EACxD,QAAQ,GACT,EAAE;IACD,8GAA8G;IAC9G,QAAQ,EAAE,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,IAAI,CAAA;CAClC,QAUA"}