@react-fabric/data 1.0.0-beta.5 → 1.0.0-beta.52

package/src/checklist/CheckList.tsx

@@ -22,12 +22,14 @@
  */
 
 import { Badge, CoreIcons, EmptyContent, Icon } from "@react-fabric/core";
-import { type BadgeType } from "@react-fabric/core/dist/types/types";
+import {
+  type BadgeType,
+  type TestProps,
+} from "@react-fabric/core/dist/types/types";
 import { isString } from "@react-fabric/utilities";
 import {
   Fragment,
   isValidElement,
-  memo,
   useEffect,
   useMemo,
   useState,
@@ -47,7 +49,7 @@ export interface CheckListItem extends KeyValue {
   isDisabled?: boolean;
 }
 
-export interface CheckListProps extends SelectableProps {
+export interface CheckListProps extends SelectableProps, TestProps {
   /**
    * list items
    */
@@ -73,97 +75,121 @@ const CheckItem: FC<
     selected?: number;
     allowNegative?: boolean;
   }
-> = memo(
-  ({
-    id,
-    allowNegative,
-    selected,
-    icon,
-    label,
-    isDisabled,
-    onClick,
-    badge,
-  }: Omit<CheckListItem, "selected"> & {
-    selected?: number;
-    allowNegative?: boolean;
-  }) => {
-    return (
-      <div
-        role="none"
-        className="ax-checkList__item"
-        data-disabled={isDisabled}
-        onClick={() => onClick(id, false)}
-        onContextMenu={(e) => [
-          allowNegative && onClick(id, true),
-          e.preventDefault(),
-        ]}
-      >
-        {!allowNegative && (
+> = ({
+  id,
+  allowNegative,
+  selected,
+  icon,
+  label,
+  isDisabled,
+  onClick,
+  badge,
+  ...aria
+}: Omit<CheckListItem, "selected"> & {
+  selected?: number;
+  allowNegative?: boolean;
+}) => {
+  return (
+    <div
+      role="none"
+      className="ax-checkList__item"
+      data-disabled={isDisabled}
+      onClick={() => onClick(id, false)}
+      onContextMenu={(e) => [
+        allowNegative && onClick(id, true),
+        e.preventDefault(),
+      ]}
+      {...aria}
+    >
+      {!allowNegative && (
+        <Icon
+          data-type="checkbox"
+          className="ax-checkList__checkbox"
+          data-selected={selected === 1}
+          icon={selected ? CoreIcons.checkboxInt : CoreIcons.checkboxOff}
+        />
+      )}
+      {allowNegative && (
+        <Fragment>
           <Icon
-            data-type="checkbox"
+            data-type="multiple"
             className="ax-checkList__checkbox"
-            data-selected={selected === 1}
-            icon={selected ? CoreIcons.checkboxInt : CoreIcons.checkboxOff}
+            icon={
+              selected === 1
+                ? CoreIcons.expand
+                : selected === -1
+                  ? CoreIcons.collapse
+                  : CoreIcons.checkboxOff
+            }
+            data-selected={selected}
           />
-        )}
-        {allowNegative && (
-          <Fragment>
+          <div className="ax-checkList__checkbox">
             <Icon
-              data-type="multiple"
-              className="ax-checkList__checkbox"
+              data-type="positive"
+              onClick={(e) => [(onClick(id, false), e.stopPropagation())]}
+              icon={selected === 1 ? CoreIcons.expandActive : CoreIcons.expand}
+              data-selected={selected === 1}
+            />
+            <Icon
+              data-type="negative"
+              onClick={(e) => [(onClick(id, true), e.stopPropagation())]}
               icon={
-                selected === 1
-                  ? CoreIcons.expand
-                  : selected === -1
-                    ? CoreIcons.collapse
-                    : CoreIcons.checkboxOff
+                selected === -1 ? CoreIcons.collapseActive : CoreIcons.collapse
               }
-              data-selected={selected}
+              data-selected={selected === -1}
             />
-            <div className="ax-checkList__checkbox">
-              <Icon
-                data-type="positive"
-                onClick={(e) => [(onClick(id, false), e.stopPropagation())]}
-                icon={
-                  selected === 1 ? CoreIcons.expandActive : CoreIcons.expand
-                }
-                data-selected={selected === 1}
-              />
-              <Icon
-                data-type="negative"
-                onClick={(e) => [(onClick(id, true), e.stopPropagation())]}
-                icon={
-                  selected === -1
-                    ? CoreIcons.collapseActive
-                    : CoreIcons.collapse
-                }
-                data-selected={selected === -1}
-              />
-            </div>
-          </Fragment>
-        )}
-        {isValidElement(icon) && icon}
-        {isString(icon) && <Icon icon={icon} />}
-        <label>{label}</label>
-        <Badge {...badge} />
-      </div>
-    );
-  },
-);
-CheckItem.displayName = "CheckItem";
+          </div>
+        </Fragment>
+      )}
+      {isValidElement(icon) && icon}
+      {isString(icon) && <Icon icon={icon} />}
+      <label>{label}</label>
+      <Badge {...badge} />
+    </div>
+  );
+};
 
+/**
+ * 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,
   allowNegative,
   emptyMessage,
   sortItems = true,
-  ...props
+  selected,
+  nonselected,
+  onChange,
+  onClick,
+  ...aria
 }: CheckListProps) => {
   const { t } = useTranslation("data");
   const { selection, toggleSelection } = useSelectableList({
     items,
-    ...props,
+    selected,
+    nonselected,
+    onChange,
+    onClick,
   });
   const [showMore, setShowMore] = useState(false);
 
@@ -186,7 +212,7 @@ export const CheckList: FC<CheckListProps> = ({
   }, [items, selection, maxCount, showMore, sortItems]);
 
   return (
-    <div className="ax-checkList">
+    <div {...aria}>
       {listItems.map((item, index) => (
         <CheckItem
           {...item}

package/src/histogram/Histogram.tsx

@@ -31,12 +31,12 @@ import {
 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";
@@ -49,7 +49,7 @@ interface HistogramItem {
   disabled?: boolean;
 }
 
-export interface HistogramProps {
+export interface HistogramProps extends TestProps {
   /**
    * histogram items list
    */
@@ -80,14 +80,43 @@ export interface HistogramProps {
   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,
   onClick,
+  ...aria
 }: HistogramProps) => {
   const { t } = useTranslation("data");
   const maxTotal = useMemo(() => {
@@ -103,10 +132,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
       }
     >
@@ -124,15 +154,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-gradient-to-r rtl:bg-gradient-to-l",
+              "fabric-histoBar",
             )}
             style={{
               width: `${Math.min(item.count / maxTotal, 1) * 100}%`,
@@ -145,6 +177,7 @@ export const Histogram = ({
                 key="negative"
                 color="danger"
                 size="sm"
+                stopPropagation
                 icon={CoreIcons.funnelMinus}
                 aria-label="Filter Negative"
                 onClick={() => onClick?.(item.id, true)}
@@ -153,6 +186,7 @@ export const Histogram = ({
                 key="positive"
                 color="primary"
                 size="sm"
+                stopPropagation
                 icon={CoreIcons.funnelPlus}
                 aria-label="Filter"
                 onClick={() => onClick?.(item.id)}
@@ -164,7 +198,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

@@ -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,
@@ -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,

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/index.ts

@@ -28,7 +28,7 @@ export { Histogram } from "./histogram/Histogram";
 export { JsonViewer } from "./json/JsonViewer";
 export { Pagination } from "./pagination/Pagination";
 export { Table } from "./table/Table";
-export { type TableRef } from "./table/types";
+export { type TableColumn, type TableRef } from "./table/types";
 export { TreePanel } from "./tree/TreePanel";
 export { type TreeNodeType as TreeNode } from "./tree/types";
 export { VirtualGallery, type VirtualGalleryRef } from "./virtual/Gallery";

package/src/json/JsonViewer.tsx

@@ -22,7 +22,6 @@
  */
 
 import {
-  ActionLabel,
   Button,
   Copy,
   CoreIcons,
@@ -181,6 +180,8 @@ const JsonEntry = ({
       ret = actualValue ? t("json.true") : t("json.false");
     if (ret?.length > 128) {
       ret = <Text clamp={3}>{ret}</Text>;
+    } else {
+      ret = <div className="break-words">{ret}</div>;
     }
 
     return (
@@ -216,37 +217,36 @@ const JsonEntry = ({
 
   const labelDisplay = useMemo(
     () => (
-      <ActionLabel
-        className="text-dimmed text-sm px-2 flex-1 truncate"
-        actions={
-          !canExpand && canFilter
-            ? [
-                <Button
-                  key="negative"
-                  color="danger"
-                  size="sm"
-                  variant="link"
-                  icon={CoreIcons.funnelMinus}
-                  aria-label="Filter Negative"
-                  onClick={() =>
-                    onFilter?.(pathWithoutOrdinal, actualValue, true)
-                  }
-                />,
-                <Button
-                  key="positive"
-                  color="primary"
-                  size="sm"
-                  variant="link"
-                  icon={CoreIcons.funnelPlus}
-                  aria-label="Filter"
-                  onClick={() => onFilter?.(pathWithoutOrdinal, actualValue)}
-                />,
-              ]
-            : []
-        }
+      <div
+        className={classNames(
+          "text-dimmed text-sm px-2 flex-1 group",
+          inline ? "truncate" : "break-words",
+        )}
       >
+        {!canExpand && canFilter && (
+          <div className="hidden pe-1 group-hover:inline-block">
+            <Button
+              key="negative"
+              color="danger"
+              size="xs"
+              variant="link"
+              icon={CoreIcons.funnelMinus}
+              aria-label="Filter Negative"
+              onClick={() => onFilter?.(pathWithoutOrdinal, actualValue, true)}
+            />
+            <Button
+              key="positive"
+              color="primary"
+              size="xs"
+              variant="link"
+              icon={CoreIcons.funnelPlus}
+              aria-label="Filter"
+              onClick={() => onFilter?.(pathWithoutOrdinal, actualValue)}
+            />
+          </div>
+        )}
         {labeler?.(path) ?? field}
-      </ActionLabel>
+      </div>
     ),
     [field, labeler, pathWithoutOrdinal, actualValue, canExpand, canFilter],
   );
@@ -283,9 +283,14 @@ const JsonEntry = ({
             {labelDisplay}
           </div>
           {display && (
-            <div className={classNames("px-2", inline && "flex-1")}>
+            <div
+              className={classNames(
+                "px-2 flex flex-nowrap overflow-hidden",
+                inline && "flex-1",
+              )}
+            >
               {canCopy && <Copy size="xs" text={actualValue} />}
-              {display}
+              <div className="flex-1">{display}</div>
             </div>
           )}
         </div>
@@ -309,9 +314,14 @@ const JsonEntry = ({
           >
             {labelDisplay}
           </div>
-          <div className={classNames("px-2", inline && "flex-1")}>
+          <div
+            className={classNames(
+              "px-2 flex flex-nowrap overflow-hidden",
+              inline && "flex-1",
+            )}
+          >
             {canCopy && <Copy size="xs" text={value} />}
-            {display}
+            <div className="flex-1">{display}</div>
           </div>
         </div>
       )}
@@ -336,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,
@@ -356,7 +392,7 @@ export const JsonViewer = <T extends KeyValue = KeyValue>({
   const list = useMemo(() => reduceObject(json), [json]);
 
   return (
-    <div {...rest} className={classNames(className, "p-4 bg-alternate")}>
+    <div {...rest} className={classNames(className, "bg-alternate")}>
       {!isEmpty(json) ? (
         list.map((item) => (
           <JsonEntry