@react-fabric/data 1.0.0-beta.51 → 1.0.0-beta.53

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@react-fabric/data",
-  "version": "1.0.0-beta.51",
+  "version": "1.0.0-beta.53",
   "description": "RUF: Data package",
   "author": "Adarsh Pastakia <adarshpastakia@outlook.com>",
   "license": "MIT",
@@ -35,10 +35,10 @@
     "watch": "npm-run-all -p watch:rollup watch:dts"
   },
   "dependencies": {
-    "@react-fabric/core": "^1.0.0-beta.51",
-    "@react-fabric/date": "^1.0.0-beta.51",
-    "@react-fabric/form": "^1.0.0-beta.51",
-    "@react-fabric/utilities": "^1.0.0-beta.50",
+    "@react-fabric/core": "^1.0.0-beta.53",
+    "@react-fabric/date": "^1.0.0-beta.53",
+    "@react-fabric/form": "^1.0.0-beta.53",
+    "@react-fabric/utilities": "^1.0.0-beta.52",
     "@tanstack/react-virtual": "^3.13.9",
     "classnames": "^2.5.1",
     "color": "^4.2.3",
@@ -54,5 +54,5 @@
     "node": ">=18.12.0",
     "npm": ">=8.19.0"
   },
-  "gitHead": "a1b04de4663045f82992bff2aef8db26608eac74"
+  "gitHead": "1042327831f9c908912c552d5c2704b765a6f9c2"
 }

package/src/checklist/CheckList.tsx

@@ -149,6 +149,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

@@ -80,6 +80,34 @@ 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,

package/src/hooks/useFilteredList.tsx

@@ -51,6 +51,25 @@ const filterList = (
   return newList;
 };
 
+/**
+ * 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 const useFilteredList = <
   T extends AnyObject = KeyValue,
   Q extends AnyObject = string,

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,

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,

package/src/i18n/ar.json

@@ -32,5 +32,10 @@
     "uncheckAll": "الغاءالكل",
     "addFilter": "أضف عامل تصفية",
     "addFilterNot": "إضافة لا تصفية"
+  },
+  "data": {
+    "tree": {
+      "noItems": "لا توجد عناصر شجرة متوفرة"
+    }
   }
 }

package/src/i18n/en.json

@@ -32,5 +32,10 @@
     "uncheckAll": "Uncheck All",
     "addFilter": "Add Filter",
     "addFilterNot": "Add not Filter"
+  },
+  "data": {
+    "tree": {
+      "noItems": "No tree items available"
+    }
   }
 }

package/src/json/JsonViewer.tsx

@@ -346,6 +346,32 @@ const JsonEntry = ({
   );
 };
 
+/**
+ * JsonViewer component to display JSON data in a structured format.
+ * It supports inline display, property filtering, and custom formatting.
+ * The component can handle nested objects and arrays, displaying them in a tree-like structure.
+ * It also provides options for copying values and filtering properties.
+ *
+ * @param {JsonViewProps<T>} props - The properties for the JsonViewer component.
+ * @returns {JSX.Element} The rendered JsonViewer component.
+ *
+ * @example
+ * ```jsx
+ * <JsonViewer
+ *   json={{ name: "John", age: 30, address: { city: "New York", zip: "10001" } }}
+ *   copy={true}
+ *   filters={true}
+ *   propertyScheme={{ date: ["createdAt"], phone: ["contact"] }}
+ *   inline={true}
+ *   labelWidth="25%"
+ *   formatter={(path, value) => (path === "age" ? `${value} years` : value)}
+ *   labeler={(path) => path.replace(/_/g, " ").toUpperCase()}
+ *   onFilter={(path, value, negate) => console.log(`Filter ${negate ? "negate" : ""} on ${path}:`, value)}
+ * />
+ * ```
+ *
+ * @see {@link https://adarshpastakia.github.io/react-fabric/?path=/docs/data-jsonviewer--docs}
+ */
 export const JsonViewer = <T extends KeyValue = KeyValue>({
   className,
   json,

package/src/pagination/Pagination.tsx

@@ -48,6 +48,16 @@ export interface PaginationProps {
   onPageChange: (page: number) => void;
 }
 
+/**
+ * Pagination component to navigate through pages of data.
+ * It displays buttons for navigating to the first, previous, next, and last pages,
+ * as well as buttons for specific page numbers based on the provided ranges.
+ * The component supports a minimal view that shows the current page and total pages.
+ * It uses memoization to optimize rendering performance.
+ *
+ * @param {PaginationProps} props - The properties for the Pagination component.
+ * @returns {JSX.Element} The rendered Pagination component.
+ */
 export const Pagination = memo(
   ({ page, ranges, totalPages, minimal, onPageChange }: PaginationProps) => {
     const [start, mid, last] = ranges;

package/src/table/Table.tsx

@@ -48,6 +48,19 @@ import { type TableProps } from "./types";
 import { useTableColumns } from "./useTableColumns";
 import { useVirtualTable } from "./useVirtualTable";
 
+/**
+ * Table component for displaying data in a tabular format with features like sorting, filtering, and virtual scrolling.
+ * It supports expandable rows, checkable rows, and customizable columns.
+ * The component is designed to handle large datasets efficiently by rendering only the visible rows.
+ * It also provides a way to manage column visibility and allows for custom rendering of group headers.
+ * Uses TanStack's `useVirtual` for virtualization and React's `useMemo` for performance optimization.
+ *
+ * @param {TableProps<T>} props - The properties for the Table component.
+ * @returns {JSX.Element} The rendered Table component.
+ *
+ * @see {@link https://adarshpastakia.github.io/react-fabric/?path=/story/data-table--table}
+ * @see {@link https://tanstack.com/table/v8/docs/api/virtual}
+ */
 export const Table = <T extends KeyValue = KeyValue>({
   ref,
   data,
@@ -166,7 +179,7 @@ export const Table = <T extends KeyValue = KeyValue>({
       >
         <div
           data-ref="tableHeader"
-          className="bg-base font-medium sticky top-0 h-8 area-head border-b select-none flex flex-nowrap z-5"
+          className="bg-base font-medium sticky top-0 h-8 area-head border-b select-none flex flex-nowrap z-2"
         >
           <div className={wrapperStart}>
             {canExpand && <div className="w-6" />}
@@ -234,7 +247,7 @@ export const Table = <T extends KeyValue = KeyValue>({
                   ref={measureElement}
                   data-index={index}
                   className={classNames(
-                    "px-2 py-1 text-md bg-base border-y border-tint-100 cursor-pointer flex items-center gap-1 z-3",
+                    "px-2 py-1 text-md bg-base border-y border-tint-100 cursor-pointer flex items-center gap-1 z-1",
                     isActiveSticky(index) && "sticky top-8",
                   )}
                   role="none"

package/src/table/types.ts

@@ -34,6 +34,34 @@ export const COL_MIN_WIDTH = "3rem";
 export const COL_MAX_WIDTH = "64rem";
 export const COL_DEFAULT_WIDTH = "12rem";
 
+/**
+ * TableColumn interface defines the structure of a column in a table.
+ * It includes properties for column identification, display options, alignment,
+ * visibility, resizing, sorting, filtering, and rendering.
+ *
+ * @template T - The type of data the column will represent, defaulting to KeyValue.
+ * @property {keyof T | string} id - Unique identifier for the column.
+ * @property {"string" | "number" | "boolean" | "datetime" | "date" | "time" | "unknown"} [dataType] - Data type of the column values.
+ * @property {string} [label] - Display label for the column header.
+ * @property {string} [tooltip] - Tooltip text for the column header.
+ * @property {string} [format] - Format string for displaying the column values.
+ * @property {"start" | "center" | "end"} [align] - Text alignment within the column.
+ * @property {"start" | "end"} [locked] - Indicates if the column is locked at the start or end.
+ * @property {boolean} [hidden] - Whether the column is hidden.
+ * @property {boolean} [truncate] - Whether to truncate the text in the column.
+ * @property {boolean} [hideable] - Whether the column can be hidden by the user.
+ * @property {boolean} [resizable] - Whether the column can be resized by the user.
+ * @property {boolean} [sortable] - Whether the column can be sorted.
+ * @property {boolean} [filterable] - Whether the column can be filtered.
+ * @property {AnyObject} [filter] - Filter criteria for the column.
+ * @property {ReactElement[]} [actions] - Array of action elements to be displayed in the column.
+ * @property {AnyObject[]} [filterOptions] - Options for filtering the column.
+ * @property {string | number} [width] - Width of the column.
+ * @property {string | number} [minWidth] - Minimum width of the column.
+ * @property {string | number} [maxWidth] - Maximum width of the column.
+ * @property {KeyValue} [valueMap] - Mapping of values for the column.
+ * @property {(value: AnyObject, data: T, index: number) => Elements<AnyObject>} [renderer] - Custom renderer function for the column values.
+ */
 export interface TableColumn<T = KeyValue>
   extends CssProp,
     IconProps,

package/src/tree/TreeNode.tsx

@@ -166,7 +166,7 @@ export const TreeNode = ({
           }
         >
           {nodeIcon && (
-            <div className="flex-content w-6 self-center leading-none">
+            <div className="flex-content max-w-6 me-1 self-center leading-none">
               {isValidElement(nodeIcon) && nodeIcon}
               {isString(nodeIcon) && (
                 <Icon

package/src/tree/TreePanel.tsx

@@ -38,6 +38,47 @@ import { useTree } from "./useTree";
 
 // TODO: implement keyboard handler for navigating tree
 
+/**
+ * TreePanel component renders a virtualized tree structure with support for
+ * selection, expansion, and filtering. It allows for custom rendering of tree
+ * nodes and supports checkable nodes.
+ *
+ * @param {TreePanelProps<T>} props - The properties for the TreePanel component.
+ * @returns {JSX.Element} The rendered TreePanel component.
+ * @template T - The type of items in the tree, extending KeyValue.
+ *
+ * @example
+ * ```jsx
+ * <TreePanel
+ *   items={items}
+ *   selected={selectedItem}
+ *   checked={checkedItems}
+ *   checkable={true}
+ *   renderer={(item) => <span>{item.name}</span>}
+ *   searchable={true}
+ *   selectable={true}
+ *   matcher={(item, query) => item.name.toLowerCase().includes(query.toLowerCase())}
+ *   filterPlaceholder="Search..."
+ *   defaultLeafIcon={<Icon icon={CoreIcons.file} />}
+ *   defaultNodeIcon={<Icon icon={CoreIcons.folder} />}
+ *   expander="caret"
+ *   onChecked={(checkedItems) => console.log(checkedItems)}
+ *   onLoad={(id) => console.log(`Load children for ${id}`)}
+ *   onQuery={(query) => console.log(`Query: ${query}`)}
+ *   onSelect={(selectedItem) => console.log(selectedItem)}
+ *   onClick={(item) => console.log(`Clicked on ${item.id}`)}
+ *   sorter={(a, b) => a.label.localeCompare(b.label)}
+ *   makeLabel={(item) => item.name}
+ *   makeIcon={(item) => item.icon ? <Icon icon={item.icon} /> : null}
+ *   defaultExpanded={["root"]}
+ *   onExpandToggle={(id, expanded) => console.log(`Toggle expand for ${id}: ${expanded}`)}
+ *   leafClassName="leaf-node"
+ *   nodeClassName="tree-node"
+ * />
+ * ```
+ *
+ * @see {@link https://adarshpastakia.github.io/react-fabric/?path=/docs/data-treepanel--docs}
+ */
 export const TreePanel = <T extends KeyValue>({
   ref,
   items,

package/src/virtual/Gallery.tsx

@@ -294,7 +294,7 @@ const _VirtualGallery = <T extends AnyObject>({
     >
       <div
         className={classNames(
-          "inline-flex flex-nowrap gap-2 justify-center min-h-full min-w-full",
+          "flex flex-nowrap justify-center gap-2 min-h-full",
         )}
       >
         <div
@@ -318,7 +318,7 @@ const _VirtualGallery = <T extends AnyObject>({
             <div style={{ height: virtualItems[0]?.start }} />
             {virtualItems.map(({ key, index }) => (
               <div
-                className="flex justify-center"
+                className="flex"
                 key={key}
                 data-index={index}
                 ref={virtualizer.measureElement}
@@ -367,4 +367,37 @@ const _VirtualGallery = <T extends AnyObject>({
 _VirtualGallery.displayName = "VirtualGallery";
 
 const GenericMemo: <T>(c: T) => T = memo;
+
+/**
+ * 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 const VirtualGallery = GenericMemo(_VirtualGallery);

package/src/virtual/List.tsx

@@ -269,7 +269,7 @@ const _VirtualList = <T extends AnyObject>({
     >
       <div
         className={classNames(
-          "inline-flex flex-nowrap gap-2 justify-center min-h-full min-w-full",
+          "flex flex-nowrap gap-2 justify-center min-h-full min-w-full",
           orientation === "horizontal" && "flex-col",
         )}
       >
@@ -360,4 +360,41 @@ const _VirtualList = <T extends AnyObject>({
 _VirtualList.displayName = "VirtualList";
 
 const GenericMemo: <T>(c: T) => T = memo;
+
+/**
+ * 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 const VirtualList = GenericMemo(_VirtualList);