@meta-1/design 0.0.199 → 0.0.201

package/src/components/uix/data-grid/index.tsx

@@ -0,0 +1,625 @@
+// biome-ignore-all lint/suspicious/noExplicitAny: DataGrid props
+import { useCallback, useContext, useEffect, useMemo, useRef, useState } from "react";
+import { DotsHorizontalIcon, LayoutIcon } from "@radix-ui/react-icons";
+import {
+  AllCommunityModule,
+  type ColDef,
+  colorSchemeDark,
+  colorSchemeLight,
+  type GridApi,
+  type GridReadyEvent,
+  ModuleRegistry,
+  themeBalham,
+} from "ag-grid-community";
+import { AgGridReact } from "ag-grid-react";
+import get from "lodash/get";
+import isArray from "lodash/isArray";
+import isFunction from "lodash/isFunction";
+import isString from "lodash/isString";
+import isUndefined from "lodash/isUndefined";
+import { useTheme } from "next-themes";
+
+import {
+  Action,
+  cn,
+  Dropdown,
+  type DropdownMenuItemProps,
+  Filters,
+  type FiltersProps,
+  type Formatters,
+  generateColumnStorageKey,
+  Pagination,
+  type PaginationProps,
+  Spin,
+  ValueFormatter,
+} from "@meta-1/design";
+import { UIXContext } from "@meta-1/design/components/uix/config-provider";
+import { LoadingOverlay, NoRowsOverlay } from "./overlays";
+
+import "./style.css";
+
+ModuleRegistry.registerModules([AllCommunityModule]);
+
+export interface StickyColumnProps {
+  key: string;
+  position: "left" | "right";
+  size: number;
+}
+
+export type DataGridColumn<TData> = Partial<ColDef<TData>> & {
+  /** 列的 ID，如果不提供则使用 accessorKey 或 field */
+  id?: string;
+  /** 数据字段路径，支持点号分隔的嵌套路径，如 "user.name" */
+  accessorKey?: string;
+  /** 列标题，可以是字符串或返回 React 元素的函数 */
+  header?: string | ((params: { column: any; header: any; table: any }) => React.ReactNode);
+  /** 自定义单元格渲染函数 */
+  cell?: (params: {
+    getValue: () => any;
+    row: { original: TData; getValue: (key: string) => any };
+    column: any;
+    table: any;
+  }) => React.ReactNode;
+  /** 是否启用排序 */
+  enableSorting?: boolean;
+  /** 是否启用调整大小 */
+  enableResizing?: boolean;
+  /** 是否启用隐藏 */
+  enableHiding?: boolean;
+  /** 列宽 */
+  size?: number;
+  /** 最小列宽 */
+  minSize?: number;
+  /** 最大列宽 */
+  maxSize?: number;
+  /** 单元格 CSS 类名 */
+  className?: string;
+  /** 格式化函数数组，按顺序应用 */
+  formatters?: Formatters;
+};
+
+export interface DataGridProps<TData> {
+  columns: DataGridColumn<TData>[];
+  data: TData[];
+  showColumnVisibility?: boolean;
+  stickyColumns?: StickyColumnProps[];
+  checkbox?: boolean;
+  onRowSelectionChange?: (selectedRows: TData[]) => void;
+  rowActions?: DropdownMenuItemProps[] | ((cell: TData) => DropdownMenuItemProps[]);
+  onRowActionClick?: (item: DropdownMenuItemProps, row: TData) => void;
+  loading?: boolean;
+  load?: (params?: unknown) => Promise<unknown> | unknown;
+  filter?: FiltersProps;
+  pagination?: PaginationProps | boolean;
+  empty?: string;
+  showHeader?: boolean;
+  onRowClick?: (row: TData) => void;
+  /** 表格最大高度，设置后内容区将滚动，表头固定。支持 CSS 单位如 '500px', '50vh' 等 */
+  maxHeight?: string | number;
+  /** 获取行的唯一 ID，用于 ag-grid 的 getRowId */
+  getRowId?: (data: TData) => string;
+  /** 行高，可以是固定数值（像素）或函数返回动态高度 */
+  rowHeight?: number | ((params: { data: TData; node?: any }) => number | undefined);
+  /** 是否启用行高自适应，开启后 rowHeight 无效，行高将根据内容自动调整 */
+  autoRowHeight?: boolean;
+  /** 操作列单元格的 CSS 类名 */
+  actionsCellClassName?: string;
+}
+
+const LOCAL_STORAGE_PREFIX = "datagrid_columns_";
+
+const saveColumnVisibility = (storageKey: string, visibility: Record<string, boolean>) => {
+  try {
+    localStorage.setItem(`${LOCAL_STORAGE_PREFIX}${storageKey}`, JSON.stringify(visibility));
+  } catch (_error) {
+    // console.warn('Failed to save column visibility to localStorage:', error)
+  }
+};
+
+const loadColumnVisibility = (storageKey: string): Record<string, boolean> => {
+  try {
+    const stored = localStorage.getItem(`${LOCAL_STORAGE_PREFIX}${storageKey}`);
+    return stored ? JSON.parse(stored) : {};
+  } catch (_error) {
+    // console.warn('Failed to load column visibility from localStorage:', error)
+    return {};
+  }
+};
+
+const hasActions = (rowActions: DropdownMenuItemProps[] | ((cell: any) => DropdownMenuItemProps[])) => {
+  if (isFunction(rowActions)) {
+    return true;
+  }
+  if (isArray(rowActions)) {
+    return !!rowActions.length;
+  }
+  return false;
+};
+
+// 将 DataGridColumn 转换为 ag-grid 的 ColDef
+function convertColumnDefToAgGrid<TData>(
+  columnDef: DataGridColumn<TData>,
+  stickyColumns: StickyColumnProps[],
+): ColDef<TData> {
+  const accessorKey = columnDef.accessorKey;
+  const colId =
+    columnDef.id || columnDef.colId || (typeof accessorKey === "string" ? accessorKey.replace(/\./g, "_") : undefined);
+
+  // 检查是否是粘性列
+  // 支持通过 id、accessorKey 或 colId 匹配
+  const stickyCol = stickyColumns.find((sc) => {
+    const key = sc.key;
+    // 直接匹配 colId
+    if (key === colId) return true;
+    // 匹配原始 accessorKey（如果 key 包含点号）
+    if (typeof accessorKey === "string" && key === accessorKey) return true;
+    // 匹配 id
+    if (columnDef.id && key === columnDef.id) return true;
+    return false;
+  });
+  const pinned = stickyCol ? (stickyCol.position === "left" ? "left" : "right") : undefined;
+
+  // 从 columnDef 中提取 ag-grid 支持的属性
+  const agColDef: ColDef<TData> = {
+    ...columnDef,
+    colId: colId || columnDef.colId || String(Math.random()),
+    pinned: pinned || columnDef.pinned,
+    sortable: columnDef.enableSorting !== false ? columnDef.sortable !== false : false,
+    filter: columnDef.filter ?? false,
+    resizable: columnDef.enableResizing !== false ? columnDef.resizable !== false : false,
+    hide: columnDef.enableHiding === false ? false : columnDef.hide,
+    cellClass: columnDef.className || columnDef.cellClass,
+  };
+
+  if (pinned) {
+    if (columnDef.size) agColDef.width = columnDef.size;
+    if (columnDef.minSize) agColDef.minWidth = columnDef.minSize;
+    if (columnDef.maxSize) agColDef.maxWidth = columnDef.maxSize;
+  } else {
+    if (columnDef.size) {
+      agColDef.width = columnDef.size;
+      if (columnDef.minSize) agColDef.minWidth = columnDef.minSize;
+      if (columnDef.maxSize) agColDef.maxWidth = columnDef.maxSize;
+    } else if (!agColDef.width && !agColDef.flex) {
+      agColDef.flex = 1;
+      agColDef.minWidth = columnDef.minSize || 100;
+      if (columnDef.maxSize) agColDef.maxWidth = columnDef.maxSize;
+    }
+  }
+
+  if (!agColDef.field && typeof accessorKey === "string") {
+    agColDef.field = accessorKey as any;
+  }
+
+  if (isString(columnDef.header)) {
+    agColDef.headerName = columnDef.header;
+  } else if (isFunction(columnDef.header)) {
+    agColDef.headerComponent = (params: any) => {
+      const headerFn = columnDef.header as (params: { column: any; header: any; table: any }) => React.ReactNode;
+      const result = headerFn({
+        column: params.column,
+        header: params,
+        table: params.api,
+      });
+      if (typeof result === "string" || typeof result === "number") {
+        return result;
+      }
+      return result;
+    };
+  } else if (columnDef.headerName) {
+    agColDef.headerName = columnDef.headerName;
+  }
+
+  const formatters = columnDef.formatters || [];
+  const hasFormatters = formatters.length > 0;
+  const hasCustomCell = !!columnDef.cell;
+
+  if (hasCustomCell || hasFormatters) {
+    agColDef.cellRenderer = (params: any) => {
+      let cellContent: any;
+
+      if (hasCustomCell && isFunction(columnDef.cell)) {
+        const cellContext = {
+          getValue: () => params.value,
+          row: { original: params.data, getValue: (key: string) => get(params.data, key) },
+          column: params.column,
+          table: params.api,
+        };
+        cellContent = columnDef.cell(cellContext);
+      } else {
+        cellContent = params.value;
+      }
+
+      if (hasFormatters) {
+        return <ValueFormatter formatters={formatters} value={cellContent} />;
+      }
+
+      return cellContent;
+    };
+  }
+
+  return agColDef;
+}
+
+export function DataGrid<TData>(props: DataGridProps<TData>) {
+  const {
+    data,
+    columns,
+    showColumnVisibility = true,
+    rowActions,
+    checkbox = false,
+    onRowSelectionChange,
+    stickyColumns = [],
+    onRowActionClick,
+    filter,
+    loading,
+    pagination,
+    load,
+    maxHeight,
+    getRowId,
+    rowHeight = 34,
+    autoRowHeight = false,
+    actionsCellClassName,
+  } = props;
+
+  const config = useContext(UIXContext);
+  const { resolvedTheme } = useTheme();
+  const empty = props.empty || get(config.locale, "DataTable.empty");
+
+  const gridApiRef = useRef<GridApi<TData> | null>(null);
+  const [mounted, setMounted] = useState(false);
+  const [columnVisibility, setColumnVisibility] = useState<Record<string, boolean>>({});
+
+  const storageKey = useMemo(() => {
+    return generateColumnStorageKey(columns);
+  }, [columns]);
+
+  useEffect(() => {
+    setMounted(true);
+    const storedVisibility = loadColumnVisibility(storageKey);
+    setColumnVisibility(storedVisibility);
+  }, [storageKey]);
+
+  useEffect(() => {
+    if (mounted && gridApiRef.current) {
+      // 应用列可见性
+      const columnsToShow: string[] = [];
+      const columnsToHide: string[] = [];
+      Object.entries(columnVisibility).forEach(([colId, visible]) => {
+        if (visible) {
+          columnsToShow.push(colId);
+        } else {
+          columnsToHide.push(colId);
+        }
+      });
+      if (columnsToShow.length > 0) {
+        gridApiRef.current.setColumnsVisible(columnsToShow, true);
+      }
+      if (columnsToHide.length > 0) {
+        gridApiRef.current.setColumnsVisible(columnsToHide, false);
+      }
+    }
+  }, [columnVisibility, mounted]);
+
+  // 转换列定义
+  const agGridColumns = useMemo<ColDef<TData>[]>(() => {
+    const newColumns: ColDef<TData>[] = [];
+
+    // 添加 checkbox 列
+    if (checkbox) {
+      // 检查是否在 stickyColumns 中明确配置，如果没有则默认固定在左侧
+      const stickySelect = stickyColumns.find((sc) => sc.key === "select");
+      const pinnedSelect = stickySelect
+        ? stickySelect.position === "left"
+          ? "left"
+          : stickySelect.position === "right"
+            ? "right"
+            : undefined
+        : "left"; // 默认固定在左侧
+
+      newColumns.push({
+        colId: "select",
+        checkboxSelection: true,
+        headerCheckboxSelection: true,
+        width: 40,
+        pinned: pinnedSelect,
+        lockPosition: pinnedSelect === "left" ? "left" : pinnedSelect === "right" ? "right" : undefined,
+        suppressMovable: true,
+        resizable: false,
+        sortable: false,
+        filter: false,
+        headerName: "",
+      });
+    }
+
+    // 转换用户定义的列
+    columns.forEach((col) => {
+      newColumns.push(convertColumnDefToAgGrid(col, stickyColumns));
+    });
+
+    // 添加 actions 列
+    if (hasActions(rowActions!)) {
+      // 检查是否在 stickyColumns 中明确配置，如果没有则默认固定在右侧
+      const stickyActions = stickyColumns.find((sc) => sc.key === "actions");
+      const pinnedActions = stickyActions
+        ? stickyActions.position === "left"
+          ? "left"
+          : stickyActions.position === "right"
+            ? "right"
+            : undefined
+        : "right"; // 默认固定在右侧
+
+      newColumns.push({
+        colId: "actions",
+        pinned: pinnedActions,
+        lockPosition: pinnedActions === "left" ? "left" : pinnedActions === "right" ? "right" : undefined,
+        width: 42,
+        resizable: false,
+        sortable: false,
+        filter: false,
+        headerName: "",
+        cellClass: cn("!px-0", actionsCellClassName),
+        cellRenderer: (params: any) => {
+          let items = rowActions;
+          if (isFunction(rowActions)) {
+            items = rowActions(params.data);
+          }
+          return (
+            <div className="flex w-full justify-center py-1" onClick={(e) => e.stopPropagation()}>
+              <Dropdown
+                align="end"
+                asChild={true}
+                items={items as DropdownMenuItemProps[]}
+                onItemClick={(item) => onRowActionClick?.(item, params.data)}
+              >
+                <Action className="!p-0 h-6 w-6">
+                  <DotsHorizontalIcon />
+                </Action>
+              </Dropdown>
+            </div>
+          );
+        },
+      });
+    }
+
+    return newColumns;
+  }, [columns, checkbox, rowActions, onRowActionClick, stickyColumns]);
+
+  // ag-grid 主题
+  const gridTheme = useMemo(() => {
+    const isDark = resolvedTheme === "dark";
+    return themeBalham.withPart(isDark ? colorSchemeDark : colorSchemeLight);
+  }, [resolvedTheme]);
+
+  // 默认列配置
+  const defaultColDef = useMemo<ColDef<TData>>(
+    () => ({
+      resizable: true,
+      filter: false,
+      sortable: true,
+      ...(autoRowHeight
+        ? {
+            autoHeight: true,
+            wrapText: true,
+          }
+        : {}),
+    }),
+    [autoRowHeight],
+  );
+
+  // 注册自定义组件
+  const components = useMemo(
+    () => ({
+      loadingOverlay: LoadingOverlay,
+      noRowsOverlay: NoRowsOverlay,
+    }),
+    [],
+  );
+
+  const onGridReady = useCallback(
+    (event: GridReadyEvent<TData>) => {
+      gridApiRef.current = event.api;
+
+      // 应用存储的列可见性
+      const storedVisibility = loadColumnVisibility(storageKey);
+      const columnsToShow: string[] = [];
+      const columnsToHide: string[] = [];
+      Object.entries(storedVisibility).forEach(([colId, visible]) => {
+        if (visible) {
+          columnsToShow.push(colId);
+        } else {
+          columnsToHide.push(colId);
+        }
+      });
+      if (columnsToShow.length > 0) {
+        event.api.setColumnsVisible(columnsToShow, true);
+      }
+      if (columnsToHide.length > 0) {
+        event.api.setColumnsVisible(columnsToHide, false);
+      }
+    },
+    [storageKey],
+  );
+
+  const onSelectionChanged = useCallback(() => {
+    if (!gridApiRef.current || !checkbox) return;
+    const selected = gridApiRef.current.getSelectedRows() || [];
+    onRowSelectionChange?.(selected);
+  }, [checkbox, onRowSelectionChange]);
+
+  const onColumnVisible = useCallback(() => {
+    if (!gridApiRef.current) return;
+    const allColumns = gridApiRef.current.getColumns() || [];
+    const visibility: Record<string, boolean> = {};
+    allColumns.forEach((col) => {
+      if (col.getColId() !== "select" && col.getColId() !== "actions") {
+        visibility[col.getColId()] = col.isVisible() ?? true;
+      }
+    });
+    setColumnVisibility(visibility);
+    saveColumnVisibility(storageKey, visibility);
+  }, [storageKey]);
+
+  // 列设置菜单项
+  const columnSettings = useMemo<DropdownMenuItemProps[]>(() => {
+    if (!gridApiRef.current) return [];
+    const allColumns = gridApiRef.current.getColumns() || [];
+    return allColumns
+      .filter((col) => {
+        const colId = col.getColId();
+        return colId !== "select" && colId !== "actions" && col.getUserProvidedColDef()?.hide !== false;
+      })
+      .map((col) => {
+        const colId = col.getColId();
+        const columnDef = columns.find((c) => {
+          const accessorKey = (c as any).accessorKey;
+          const key = c.id || (typeof accessorKey === "string" ? accessorKey.replace(/\./g, "_") : undefined);
+          return key === colId;
+        });
+        let label = colId;
+        if (columnDef) {
+          if (isString(columnDef.header)) {
+            label = columnDef.header;
+          } else if (isFunction(columnDef.header)) {
+            // 简化处理，使用 colId 作为 label
+            label = colId;
+          }
+        }
+        const checked = columnVisibility[colId];
+        return {
+          id: colId,
+          label,
+          type: "checkbox",
+          checked: isUndefined(checked) ? (col.isVisible() ?? true) : checked,
+          onCheckedChange: (_item, value) => {
+            gridApiRef.current?.setColumnsVisible([colId], value);
+          },
+        };
+      });
+  }, [columns, columnVisibility]);
+
+  const showVisibilityControl = useMemo(
+    () => showColumnVisibility && columnSettings.length,
+    [showColumnVisibility, columnSettings],
+  );
+
+  const showToolbar = useMemo(() => filter || showVisibilityControl, [filter, showVisibilityControl]);
+
+  const showPagination = useMemo(() => {
+    if (!pagination) {
+      return false;
+    }
+    if (typeof pagination === "boolean") {
+      return pagination;
+    }
+    return pagination.total > 0;
+  }, [pagination]);
+
+  const handleRowClick = useCallback(
+    (event: { data?: TData }) => {
+      if (props.onRowClick && event.data) {
+        props.onRowClick(event.data);
+      }
+    },
+    [props],
+  );
+
+  // 根据 loading 状态控制覆盖层的显示
+  useEffect(() => {
+    if (!gridApiRef.current) return;
+    gridApiRef.current.setGridOption("loading", loading || false);
+  }, [loading]);
+
+  const gridHeight = useMemo(() => {
+    if (!maxHeight) return undefined;
+    return typeof maxHeight === "number" ? `${maxHeight}px` : maxHeight;
+  }, [maxHeight]);
+
+  return (
+    <div className={cn("relative")}>
+      <div className={"flex flex-col gap-md"}>
+        <div>
+          {showToolbar ? (
+            <div
+              className={cn(
+                "border-0 border-secondary border-b border-solid pb-2",
+                "flex items-end",
+                filter ? "justify-between" : "justify-end",
+              )}
+            >
+              {filter ? <Filters {...filter} load={load} loading={loading} /> : null}
+              {showVisibilityControl ? (
+                <Dropdown align="end" asChild={true} items={columnSettings}>
+                  <Action className="size-button p-0">
+                    <LayoutIcon className="size-4" />
+                  </Action>
+                </Dropdown>
+              ) : null}
+            </div>
+          ) : null}
+          <div
+            className={cn(
+              "data-grid",
+              gridHeight ? "h-full" : "",
+              "[&_.ag-root-wrapper]:!border-none",
+              "relative",
+              !mounted && "invisible",
+            )}
+            style={gridHeight ? { height: gridHeight } : undefined}
+          >
+            <AgGridReact<TData>
+              columnDefs={agGridColumns}
+              components={components}
+              defaultColDef={defaultColDef}
+              domLayout={gridHeight ? undefined : "autoHeight"}
+              getRowHeight={
+                autoRowHeight
+                  ? undefined
+                  : typeof rowHeight === "function"
+                    ? (params: any) => rowHeight({ data: params.data, node: params.node })
+                    : undefined
+              }
+              getRowId={getRowId ? (params) => getRowId(params.data) : undefined}
+              loadingOverlayComponent="loadingOverlay"
+              noRowsOverlayComponent="noRowsOverlay"
+              noRowsOverlayComponentParams={empty ? { noRowsMessage: empty } : undefined}
+              onColumnVisible={onColumnVisible}
+              onGridReady={onGridReady}
+              onRowClicked={handleRowClick}
+              onSelectionChanged={onSelectionChanged}
+              rowData={loading ? [] : data}
+              rowHeight={autoRowHeight ? undefined : typeof rowHeight === "number" ? rowHeight : undefined}
+              rowSelection={checkbox ? "multiple" : undefined}
+              suppressAnimationFrame={false}
+              suppressColumnVirtualisation={false}
+              suppressHorizontalScroll={false}
+              suppressRowClickSelection={!checkbox}
+              suppressRowVirtualisation={gridHeight ? false : true}
+              theme={gridTheme}
+              tooltipHideDelay={200}
+              tooltipShowDelay={0}
+            />
+          </div>
+        </div>
+        {showPagination ? (
+          <div className={cn(!mounted && "invisible")}>
+            <Pagination
+              {...(pagination as PaginationProps)}
+              onChange={(page: number) => {
+                load?.({ page });
+              }}
+              onPageSizeChange={(size: number) => {
+                load?.({ size, page: 1 });
+              }}
+            />
+          </div>
+        ) : null}
+      </div>
+      {loading || !mounted ? (
+        <div className="dark:!bg-black/5 absolute top-0 right-0 bottom-0 left-0 z-50 flex items-center justify-center bg-white/50">
+          <Spin />
+        </div>
+      ) : null}
+    </div>
+  );
+}

package/src/components/uix/data-grid/overlays.tsx

@@ -0,0 +1,26 @@
+import { type ILoadingOverlayParams, type INoRowsOverlayParams } from "ag-grid-community";
+
+export const LoadingOverlay = (_params: ILoadingOverlayParams) => {
+  return (
+    <div className="flex h-full w-full items-center justify-center bg-background/80 backdrop-blur-sm">
+      <div className="flex flex-col items-center space-y-3">
+        <div className="relative">
+          <div className="h-8 w-8 animate-spin rounded-full border-2 border-primary border-t-transparent"></div>
+        </div>
+        <div className="text-muted-foreground text-sm">加载中...</div>
+      </div>
+    </div>
+  );
+};
+
+export const NoRowsOverlay = (params: INoRowsOverlayParams) => {
+  // biome-ignore lint/suspicious/noExplicitAny: <noRowsMessage>
+  const message = (params as any).noRowsMessage || "暂无数据";
+  return (
+    <div className="flex h-full w-full items-center justify-center">
+      <div className="flex flex-col items-center space-y-2">
+        <div className="text-muted-foreground">{message}</div>
+      </div>
+    </div>
+  );
+};

package/src/components/uix/data-grid/style.css

@@ -0,0 +1,6 @@
+@import "../../../assets/style/theme.css";
+
+/* 自定义样式已移除，后续按需添加 */
+.data-grid {
+  --ag-row-height: 34px;
+}