@react-fabric/data 1.0.0-beta.6 → 1.0.0-beta.61

package/dist/types/virtual/Gallery.d.ts

@@ -7,7 +7,7 @@ export interface VirtualGalleryRef {
 }
 export interface VirtualGalleryProps<T> extends TestProps {
     children: (props: {
-        data: T;
+        item: T;
         index: number;
         isLast: boolean;
     }) => ReactElement;
@@ -24,6 +24,12 @@ export interface VirtualGalleryProps<T> extends TestProps {
      * default item width
      */
     defaultWidth?: number;
+    /**
+     * full width list
+     */
+    fullWidth?: boolean;
+    maxWidth?: string | number;
+    minWidth?: string | number;
     /**
      * padding
      */
@@ -32,6 +38,7 @@ export interface VirtualGalleryProps<T> extends TestProps {
      * data list
      */
     items: T[];
+    total?: number;
     /**
      * loading state
      */
@@ -44,13 +51,45 @@ export interface VirtualGalleryProps<T> extends TestProps {
     /**
      * load more callback
      */
-    onLoadMore?: () => void;
+    onLoadMore?: (lastIndex?: number) => void;
     /**
      * scroll handler
      */
     onScroll?: (top: number) => void;
 }
+/**
+ * VirtualGallery component provides a virtualized gallery view for displaying a large list of items efficiently.
+ * It supports features like fixed columns, loading states, and customizable item rendering.
+ * The component uses virtualization to render only the visible items, improving performance for large datasets.
+ * It also provides a scroller for easy navigation through the items.
+ *
+ * @param {VirtualGalleryProps<T>} props - The properties for the VirtualGallery component.
+ * @returns {JSX.Element} The rendered VirtualGallery component.
+ *
+ * @example
+ * ```jsx
+ * <VirtualGallery
+ *   items={items}
+ *   columns={3}
+ *   defaultHeight={100}
+ *   defaultWidth={100}
+ *   fullWidth={true}
+ *   onLoadMore={(lastIndex) => console.log("Load more items from index:", lastIndex)}
+ *   onScroll={(top) => console.log("Scrolled to top:", top)}
+ * >
+ *   {({ item, index, isLast }) => (
+ *     <div className="gallery-item" key={item.id}>
+ *       <img src={item.image} alt={item.label} />
+ *       <p>{item.label}</p>
+ *     </div>
+ *   )}
+ * </VirtualGallery>
+ * ```
+ *
+ * @see {@link https://adarshpastakia.github.io/react-fabric/?path=/docs/data-virtualgallery--docs}
+ * @see {@link https://tanstack.com/docs/react-virtual/latest/overview}
+ */
 export declare const VirtualGallery: {
-    <T extends KeyValue<any>>({ items, children, columns, padding, defaultHeight: height, defaultWidth: width, hideScroller, initialScroll, loading, onLoadMore, onScroll, galleryRef, ...aria }: VirtualGalleryProps<T>): import("react/jsx-runtime").JSX.Element;
+    <T extends unknown>({ items, children, columns, fullWidth, maxWidth, minWidth, total, padding, defaultHeight: height, defaultWidth: width, hideScroller, initialScroll, loading, onLoadMore, onScroll, galleryRef, ...aria }: VirtualGalleryProps<T>): import("react/jsx-runtime").JSX.Element;
     displayName: string;
 };

package/dist/types/virtual/List.d.ts

@@ -7,7 +7,7 @@ export interface VirtualListRef {
 }
 export interface VirtualListProps<T> extends TestProps {
     children: (props: {
-        data: T;
+        item: T;
         index: number;
         isLast: boolean;
     }) => ReactElement;
@@ -24,6 +24,8 @@ export interface VirtualListProps<T> extends TestProps {
      * full width list
      */
     fullWidth?: boolean;
+    maxWidth?: string | number;
+    minWidth?: string | number;
     /**
      * padding
      */
@@ -36,6 +38,7 @@ export interface VirtualListProps<T> extends TestProps {
      * data list
      */
     items: T[];
+    total?: number;
     initialScroll?: number;
     /**
      * loading state
@@ -48,13 +51,49 @@ export interface VirtualListProps<T> extends TestProps {
     /**
      * load more callback
      */
-    onLoadMore?: (page?: number) => void;
+    onLoadMore?: (lastIndex?: number) => void;
     /**
      * scroll handler
      */
     onScroll?: (top: number) => void;
 }
+/**
+ * VirtualList component for rendering large lists efficiently using virtualization.
+ * It supports horizontal and vertical orientations, custom item heights and widths,
+ * and provides a scroller for navigating through the list.
+ * It also supports loading more items on scroll and provides a way to hilight items.
+ * It can be used with a ref to control scrolling and hilighting of items.
+ *
+ * @param {VirtualListProps<T>} props - The properties for the VirtualList component.
+ * @returns {JSX.Element} The rendered VirtualList component.
+ * @template T - The type of items in the list, extending AnyObject.
+ *
+ * @example
+ * ```jsx
+ * <VirtualList
+ *   items={items}
+ *   children={({ item, index, isLast }) => (
+ *     <div key={index} className="item">
+ *       {item.label}
+ *     </div>
+ *   )}
+ *   fullWidth={true}
+ *   orientation="vertical"
+ *   defaultHeight={50}
+ *   onLoadMore={(lastIndex) => console.log("Load more items from index:", lastIndex)}
+ *   onScroll={(top) => console.log("Scrolled to top:", top)}
+ *   listRef={virtualListRef}
+ * >
+ *   {({ item, index, isLast }) => (
+ *     <div className="gallery-item" key={item.id}>
+ *       <img src={item.image} alt={item.label} />
+ *       <p>{item.label}</p>
+ *     </div>
+ *   )}
+ * </VirtualList>
+ * ```
+ */
 export declare const VirtualList: {
-    <T extends KeyValue<any>>({ items, children, fullWidth, padding, orientation, defaultHeight: height, defaultWidth: width, hideScroller, initialScroll, loading, onLoadMore, onScroll, listRef, ...aria }: VirtualListProps<T>): import("react/jsx-runtime").JSX.Element;
+    <T extends unknown>({ items, total, children, fullWidth, maxWidth, minWidth, padding, orientation, defaultHeight: height, defaultWidth: width, hideScroller, initialScroll, loading, onLoadMore, onScroll, listRef, ...aria }: VirtualListProps<T>): import("react/jsx-runtime").JSX.Element;
     displayName: string;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@react-fabric/data",
-  "version": "1.0.0-beta.6",
+  "version": "1.0.0-beta.61",
   "description": "RUF: Data package",
   "author": "Adarsh Pastakia <adarshpastakia@outlook.com>",
   "license": "MIT",
@@ -11,9 +11,11 @@
   "types": "dist/types/index.d.ts",
   "directories": {
     "src": "src",
+    "styles": "css",
     "test": "tests"
   },
   "files": [
+    "css",
     "src",
     "dist"
   ],
@@ -33,24 +35,24 @@
     "watch": "npm-run-all -p watch:rollup watch:dts"
   },
   "dependencies": {
-    "@react-fabric/core": "^1.0.0-beta.6",
-    "@react-fabric/date": "^1.0.0-beta.6",
-    "@react-fabric/form": "^1.0.0-beta.6",
-    "@react-fabric/utilities": "^1.0.0-beta.6",
-    "@tanstack/react-virtual": "^3.8.6",
-    "classnames": "^2.5.1",
-    "color": "^4.2.3",
-    "memoize-one": "^6.0.0"
+    "@react-fabric/core": "^1.0.0-beta.61",
+    "@react-fabric/date": "^1.0.0-beta.61",
+    "@react-fabric/form": "^1.0.0-beta.61",
+    "@react-fabric/utilities": "^1.0.0-beta.61",
+    "@tanstack/react-virtual": "~3.13.12",
+    "classnames": "~2.5.1",
+    "color": "~5.0.2",
+    "memoize-one": "~6.0.0"
   },
   "peerDependencies": {
-    "i18next": "^23.15.1",
-    "react": ">=18.0.0 <20.0.0",
-    "react-dom": ">=18.0.0 <20.0.0",
-    "react-i18next": "^15.0.2"
+    "i18next": "~25.6.0",
+    "react": "~19.2.0",
+    "react-dom": "~19.2.0",
+    "react-i18next": "~16.2.1"
   },
   "engines": {
     "node": ">=18.12.0",
     "npm": ">=8.19.0"
   },
-  "gitHead": "21167df13cedeae8b365e87b9bab6d7401298cb6"
+  "gitHead": "a0b0c571bf9c189fa3355bbc3b896ecc4b9d6a04"
 }

package/src/checklist/CheckList.tsx

@@ -21,7 +21,7 @@
  * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
-import { Badge, CoreIcons, EmptyContent, Icon } from "@react-fabric/core";
+import { Badge, EmptyContent, Icon } from "@react-fabric/core";
 import {
   type BadgeType,
   type TestProps,
@@ -106,7 +106,11 @@ const CheckItem: FC<
           data-type="checkbox"
           className="ax-checkList__checkbox"
           data-selected={selected === 1}
-          icon={selected ? CoreIcons.checkboxInt : CoreIcons.checkboxOff}
+          icon={
+            selected
+              ? "icon-[mdi--checkbox-marked]"
+              : "icon-[mdi--checkbox-blank-outline]"
+          }
         />
       )}
       {allowNegative && (
@@ -116,10 +120,10 @@ const CheckItem: FC<
             className="ax-checkList__checkbox"
             icon={
               selected === 1
-                ? CoreIcons.expand
+                ? "icon-[mdi--plus-box-outline]"
                 : selected === -1
-                  ? CoreIcons.collapse
-                  : CoreIcons.checkboxOff
+                  ? "icon-[mdi--minus-box-outline]"
+                  : "icon-[mdi--checkbox-blank-outline]"
             }
             data-selected={selected}
           />
@@ -127,14 +131,20 @@ const CheckItem: FC<
             <Icon
               data-type="positive"
               onClick={(e) => [(onClick(id, false), e.stopPropagation())]}
-              icon={selected === 1 ? CoreIcons.expandActive : CoreIcons.expand}
+              icon={
+                selected === 1
+                  ? "icon-[mdi--plus-box]"
+                  : "icon-[mdi--plus-box-outline]"
+              }
               data-selected={selected === 1}
             />
             <Icon
               data-type="negative"
               onClick={(e) => [(onClick(id, true), e.stopPropagation())]}
               icon={
-                selected === -1 ? CoreIcons.collapseActive : CoreIcons.collapse
+                selected === -1
+                  ? "icon-[mdi--minus-box]"
+                  : "icon-[mdi--minus-box-outline]"
               }
               data-selected={selected === -1}
             />
@@ -149,6 +159,28 @@ const CheckItem: FC<
   );
 };
 
+/**
+ * CheckList component to display a list of selectable items with checkboxes.
+ * It supports selection, deselection, and allows for negative selections.
+ *
+ * @param {CheckListProps} props - The properties for the CheckList component.
+ * @returns {JSX.Element} The rendered CheckList component.
+ *
+ * @example
+ * ```jsx
+ * <CheckList
+ *   items={[
+ *     { id: "1", label: "Item 1", icon: "icon1" },
+ *     { id: "2", label: "Item 2", icon: "icon2", badge: { text: "New" } },
+ *   ]}
+ *   maxCount={5}
+ *   allowNegative={true}
+ *   emptyMessage="No items available"
+ *   onChange={(selectedItems) => console.log(selectedItems)}
+ *   onClick={(itemId, isNegative) => console.log(itemId, isNegative)}
+ * />
+ * ```
+ */
 export const CheckList: FC<CheckListProps> = ({
   items = [],
   maxCount = 0,

package/src/histogram/Histogram.tsx

@@ -21,23 +21,16 @@
  * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
-import {
-  ActionLabel,
-  Button,
-  CoreIcons,
-  EmptyContent,
-  Icon,
-} from "@react-fabric/core";
+import { ActionLabel, Button, EmptyContent, Icon } from "@react-fabric/core";
 import {
   type ColorType,
   type PaletteType,
   type TestProps,
 } from "@react-fabric/core/dist/types/types";
-import { compareValues, Format } from "@react-fabric/utilities";
+import { compareValues, Format, isColor } from "@react-fabric/utilities";
 import classNames from "classnames";
 import { useMemo } from "react";
 import { useTranslation } from "react-i18next";
-import classes from "./Histogram.module.css";
 
 const emptyIcon =
   "M20.84 22.73L11.11 13H3V11H9.11L6.11 8H3V6H4.11L1.11 3L2.39 1.73L22.11 21.46L20.84 22.73M15 11H14.2L15 11.8V11M21 8V6H9.2L11.2 8H21M3 18H9V16H3V18Z";
@@ -81,10 +74,38 @@ export interface HistogramProps extends TestProps {
   onClick?: (id: string, negative?: true) => void;
 }
 
+/**
+ * Histogram component displays a bar chart of items with counts.
+ * It allows users to visualize the distribution of counts across different items.
+ * The component supports sorting, custom colors, and click handling for each item.
+ * It also provides an empty state when there are no items to display.
+ *
+ * @param {HistogramProps} props - The properties for the Histogram component.
+ * @returns {JSX.Element} - The rendered Histogram component.
+ *
+ * @example
+ * ```jsx
+ * <Histogram
+ *   items={[
+ *     { id: "1", label: "Item 1", count: 10 },
+ *     { id: "2", label: "Item 2", count: 20 },
+ *     { id: "3", label: "Item 3", count: 5, disabled: true },
+ *   ]}
+ *   total={30}
+ *   color="primary-500"
+ *   sortBy="count"
+ *   emptyTitle="No Data Available"
+ *   emptyMessage="Please check back later."
+ *   onClick={(id, negative) => console.log(`Clicked on ${id}`, negative ? "Negative" : "Positive")}
+ * />
+ * ```
+ *
+ * @see {@link https://adarshpastakia.github.io/react-fabric/?path=/docs/data-histogram--docs}
+ */
 export const Histogram = ({
   items = [],
   total,
-  color = "primary",
+  color = "primary-500",
   sortBy = "count",
   emptyTitle,
   emptyMessage,
@@ -105,11 +126,11 @@ export const Histogram = ({
 
   return (
     <div
-      className={classes.histogram}
+      className={"fabric-histogram from-0% to-100%"}
       {...aria}
       style={
         {
-          "--color": `var(--${color})`,
+          "--color": isColor(color) ? color : `var(--color-${color})`,
         } as AnyObject
       }
     >
@@ -127,16 +148,17 @@ export const Histogram = ({
           data-disabled={item.count === 0 || item.disabled}
           className={classNames(
             "relative cursor-pointer flex flex-nowrap items-center select-none overflow-hidden min-h-6 my-px",
-            classes.histoLabel,
-            (item.count === 0 || item.disabled) && "pointer-events-none",
+            "fabric-histoLabel",
+            ((item.total ?? item.count) === 0 || item.disabled) &&
+              "pointer-events-none",
           )}
           data-testid={item.id}
           onClick={(e) => [onClick?.(item.id), e.stopPropagation()]}
         >
           <div
             className={classNames(
-              "absolute z-0 inset-0 opacity-50 min-w-2 ltr:bg-gradient-to-r rtl:bg-gradient-to-l from-0% to-100%",
-              classes.histoBar,
+              "absolute z-0 inset-0 opacity-50 min-w-2 ltr:bg-linear-to-r rtl:bg-linear-to-l",
+              "fabric-histoBar",
             )}
             style={{
               width: `${Math.min(item.count / maxTotal, 1) * 100}%`,
@@ -149,7 +171,8 @@ export const Histogram = ({
                 key="negative"
                 color="danger"
                 size="sm"
-                icon={CoreIcons.funnelMinus}
+                stopPropagation
+                icon="icon-[mdi--filter-minus]"
                 aria-label="Filter Negative"
                 onClick={() => onClick?.(item.id, true)}
               />,
@@ -157,7 +180,8 @@ export const Histogram = ({
                 key="positive"
                 color="primary"
                 size="sm"
-                icon={CoreIcons.funnelPlus}
+                stopPropagation
+                icon="icon-[mdi--filter-plus]"
                 aria-label="Filter"
                 onClick={() => onClick?.(item.id)}
               />,
@@ -168,7 +192,7 @@ export const Histogram = ({
           <span
             className={classNames(
               "z-1 rounded-full text-xs font-medium px-2 py-1 leading-none",
-              classes.histoBadge,
+              "fabric-histoBadge",
             )}
           >
             {Format.number(item.count)}

package/src/hooks/useFilteredList.tsx

@@ -21,7 +21,7 @@
  * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
-import { isString, matchString } from "@react-fabric/utilities";
+import { isArray, isString, matchString } from "@react-fabric/utilities";
 import {
   useCallback,
   useDeferredValue,
@@ -33,6 +33,7 @@ import {
 const filterList = (
   items: AnyObject[],
   query: AnyObject = "",
+  matchAll: boolean = true,
   matcher?: AnyObject,
 ) => {
   const newList: AnyObject[] = [];
@@ -40,7 +41,20 @@ const filterList = (
     if (matcher) {
       return matcher?.(item, query) && newList.push(item);
     }
-    if (query && isString(query)) {
+    if (query && isArray(query) && query.length > 0) {
+      if (
+        matchAll &&
+        query.every((q) => matchString(item.label ?? item.toString(), q))
+      ) {
+        return newList.push(item);
+      }
+      if (
+        !matchAll &&
+        query.some((q) => matchString(item.label ?? item.toString(), q))
+      ) {
+        return newList.push(item);
+      }
+    } else if (query && isString(query)) {
       if (matchString(item.label ?? item.toString(), query)) {
         return newList.push(item);
       }
@@ -51,28 +65,114 @@ const filterList = (
   return newList;
 };
 
-export const useFilteredList = <
+interface RetType<T, Q> {
+  onSearch: (query?: Q) => void;
+  query: Q;
+  filteredList: T[];
+  isSearching: boolean;
+}
+
+/**
+ * Custom hook to filter a list of items based on a query.
+ * It provides a way to search through the items and returns the filtered list.
+ * The hook uses a deferred value to optimize performance during transitions.
+ * It also allows for a custom matcher function to define how items should be matched against the query.
+ *
+ * @param items - The list of items to filter.
+ * @param matchAll - Match all phrases in the query list against the items.
+ * @returns An object containing the search function, current query, filtered list, and a boolean indicating if a search is in progress.
+ *
+ * @example
+ * ```jsx
+ * useFilteredList(items, (item, query) => {
+ *   return item.name.includes(query);
+ * });
+ * ```
+ *
+ * @see {@link https://adarshpastakia.github.io/react-fabric/?path=/docs/data-usefilteredlist--docs}
+ */
+export function useFilteredList<
+  T extends AnyObject = KeyValue,
+  Q extends AnyObject = string,
+>(items: T[], matchAll?: boolean): RetType<T, Q>;
+
+/**
+ * Custom hook to filter a list of items based on a query.
+ * It provides a way to search through the items and returns the filtered list.
+ * The hook uses a deferred value to optimize performance during transitions.
+ * It also allows for a custom matcher function to define how items should be matched against the query.
+ *
+ * @param items - The list of items to filter.
+ * @param matcher - An optional function to match items against the query.
+ * @returns An object containing the search function, current query, filtered list, and a boolean indicating if a search is in progress.
+ *
+ * @example
+ * ```jsx
+ * useFilteredList(items, (item, query) => {
+ *   return item.name.includes(query);
+ * });
+ * ```
+ *
+ * @see {@link https://adarshpastakia.github.io/react-fabric/?path=/docs/data-usefilteredlist--docs}
+ */
+export function useFilteredList<
+  T extends AnyObject = KeyValue,
+  Q extends AnyObject = string,
+>(items: T[], matcher?: (item: T, query: Q) => boolean): RetType<T, Q>;
+
+/**
+ * Custom hook to filter a list of items based on a query.
+ * It provides a way to search through the items and returns the filtered list.
+ * The hook uses a deferred value to optimize performance during transitions.
+ * It also allows for a custom matcher function to define how items should be matched against the query.
+ *
+ * @param items - The list of items to filter.
+ * @param matchAll - Match all phrases in the query list against the items.
+ * @param matcher - An optional function to match items against the query.
+ * @returns An object containing the search function, current query, filtered list, and a boolean indicating if a search is in progress.
+ *
+ * @example
+ * ```jsx
+ * useFilteredList(items, (item, query) => {
+ *   return item.name.includes(query);
+ * });
+ * ```
+ *
+ * @see {@link https://adarshpastakia.github.io/react-fabric/?path=/docs/data-usefilteredlist--docs}
+ */
+export function useFilteredList<
   T extends AnyObject = KeyValue,
   Q extends AnyObject = string,
 >(
   items: T[],
+  matchAll?: boolean,
   matcher?: (item: T, query: Q) => boolean,
-) => {
+): RetType<T, Q>;
+
+export function useFilteredList<
+  T extends AnyObject = KeyValue,
+  Q extends AnyObject = string,
+>(items: T[], matchAll?: AnyObject, matcher?: (item: T, query: Q) => boolean) {
   const [query, setQuery] = useState<Q>();
   const _items = useDeferredValue(items ?? []);
   const [filteredList, setFilteredList] = useState<T[]>([]);
   const [isSearching, startTransition] = useTransition();
 
+  const matchingAll = typeof matchAll === "boolean" ? matchAll : true;
+  const matcherFn = typeof matchAll === "function" ? matchAll : matcher;
+
   const filterItems = useCallback(
-    (items: T[], query?: Q) =>
-      startTransition(() => setFilteredList(filterList(items, query, matcher))),
+    (items: T[], query?: Q, matchingAll?: boolean) =>
+      startTransition(() =>
+        setFilteredList(filterList(items, query, matchingAll, matcherFn)),
+      ),
     [],
   );
 
   useEffect(() => {
-    if (query) filterItems(_items, query);
+    if (query) filterItems(_items, query, matchingAll);
     else setFilteredList(items);
-  }, [query, _items]);
+  }, [query, matchingAll, _items]);
 
   return { onSearch: setQuery, query, filteredList, isSearching };
-};
+}

package/src/hooks/usePagination.tsx

@@ -57,6 +57,25 @@ const makeRange = (start: number, end: number) => {
   return Array.from({ length }, (_: AnyObject, idx: number) => idx + start);
 };
 
+/**
+ * Custom hook to manage pagination state and logic.
+ * It calculates the total number of pages, generates page ranges,
+ * and provides a way to change the current page.
+ * It also handles the transition of page changes to optimize performance.
+ *
+ * @param options - The pagination options including total records, current page, records per page, and change handler.
+ * @returns An object containing the current page, total pages, head label, ranges for pagination pills, and a function to change the page.
+ *
+ * @example
+ * ```jsx
+ * const { page, totalPages, headLabel, ranges, onPageChange } = usePagination({
+ *   totalRecords: 100,
+ *   currentPage: 0,
+ *   perPage: 10,
+ *   onChange: (newPage) => console.log("Page changed to:", newPage),
+ * });
+ * ```
+ */
 export const usePagination = ({
   totalRecords,
   currentPage = 0,
@@ -111,9 +130,12 @@ export const usePagination = ({
 
   /** ***************** set page *******************/
   useEffect(() => {
-    setPage(Math.min(currentPage, totalPages - 1));
-    onChange?.(Math.min(currentPage, totalPages - 1));
-  }, [currentPage, totalPages]);
+    if (totalRecords > -1) {
+      const actual = Math.min(currentPage, totalPages - 1);
+      setPage(actual);
+      actual !== currentPage && onChange?.(actual);
+    }
+  }, [currentPage, totalRecords, totalPages]);
 
   const headLabel = useMemo(
     () => (
@@ -126,10 +148,13 @@ export const usePagination = ({
     [page, perPage, totalRecords],
   );
 
-  const onPageChange = useCallback((page: number) => {
-    setPage(page);
-    startTransition(() => onChange?.(page));
-  }, []);
+  const onPageChange = useCallback(
+    (page: number) => {
+      setPage(page);
+      startTransition(() => onChange?.(page));
+    },
+    [onChange],
+  );
 
   return { page, totalPages, headLabel, ranges, onPageChange };
 };

package/src/hooks/useSelectableList.ts

@@ -46,6 +46,35 @@ export interface SelectableProps {
   onClick?: (id: string, isNegative: boolean) => void;
 }
 
+/**
+ * Custom hook to manage selection of items in a list.
+ * It allows toggling selection state of items, handling both selected and non-selected states.
+ * The hook maintains a selection state and provides a function to toggle the selection of items.
+ * It also supports callbacks for when the selection changes or when an item is clicked.
+ *
+ * @param items - The list of items to manage selection for.
+ * @param selected - An array of item IDs that are currently selected.
+ * @param nonselected - An array of item IDs that are currently non-selected.
+ * @param onChange - Callback function that is called when the selection changes.
+ * @param onClick - Callback function that is called when an item is clicked.
+ * @returns An object containing the current selection state and a function to toggle selection of items.
+ *
+ * @example
+ * ```jsx
+ * const { selection, toggleSelection } = useSelectableList({
+ *   items: [{ id: '1', label: 'Item 1' }, { id: '2', label: 'Item 2' }],
+ *   selected: ['1'],
+ *   nonselected: ['2'],
+ *   onChange: (selectedIds, nonSelectedIds) => {
+ *     console.log('Selected:', selectedIds);
+ *     console.log('Non-selected:', nonSelectedIds);
+ *   },
+ *   onClick: (id, isNegative) => {
+ *     console.log(`Item ${id} clicked, isNegative: ${isNegative}`);
+ *   },
+ * });
+ * ```
+ */
 export const useSelectableList = ({
   items,
   selected,