@rc-component/listy 1.1.0

package/lib/VirtualList/index.js

@@ -0,0 +1,159 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var React = _interopRequireWildcard(require("react"));
+var _virtualList = _interopRequireDefault(require("@rc-component/virtual-list"));
+var _util = require("@rc-component/util");
+var _GroupHeader = _interopRequireDefault(require("../GroupHeader"));
+var _useGroupSegments = _interopRequireDefault(require("../hooks/useGroupSegments"));
+var _useFlattenRows = _interopRequireDefault(require("./useFlattenRows"));
+var _useStickyGroupHeader = _interopRequireDefault(require("./useStickyGroupHeader"));
+function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+function _getRequireWildcardCache(e) { if ("function" != typeof WeakMap) return null; var r = new WeakMap(), t = new WeakMap(); return (_getRequireWildcardCache = function (e) { return e ? t : r; })(e); }
+function _interopRequireWildcard(e, r) { if (!r && e && e.__esModule) return e; if (null === e || "object" != typeof e && "function" != typeof e) return { default: e }; var t = _getRequireWildcardCache(r); if (t && t.has(e)) return t.get(e); var n = { __proto__: null }, a = Object.defineProperty && Object.getOwnPropertyDescriptor; for (var u in e) if ("default" !== u && Object.prototype.hasOwnProperty.call(e, u)) { var i = a ? Object.getOwnPropertyDescriptor(e, u) : null; i && (i.get || i.set) ? Object.defineProperty(n, u, i) : n[u] = e[u]; } return n.default = e, t && t.set(e, n), n; }
+// ============================== Types ===============================
+
+function VirtualList(props, ref) {
+  // ============================== Props ==============================
+  const {
+    data,
+    group,
+    height,
+    itemHeight,
+    itemRender,
+    onScroll,
+    prefixCls,
+    rowKey,
+    sticky
+  } = props;
+
+  // =============================== Refs ===============================
+  const listRef = React.useRef(null);
+
+  // =============================== Data ===============================
+  const groupData = (0, _useGroupSegments.default)(data, group);
+
+  // =============================== Keys ===============================
+  const getItemKey = (0, _util.useEvent)(item => {
+    if (typeof rowKey === 'function') {
+      return rowKey(item);
+    }
+    return item[rowKey];
+  });
+  const getKey = (0, _util.useEvent)(row => {
+    if (row.type === 'header') {
+      return row.groupKey;
+    }
+    return getItemKey(row.item);
+  });
+
+  // ============================== Rows ================================
+  const {
+    rows,
+    groupKeys,
+    groupKeyToItems
+  } = (0, _useFlattenRows.default)(data, groupData, group);
+
+  // ============================== Lookup ==============================
+  const itemKeyToGroupKey = React.useMemo(() => {
+    const itemGroupMap = new Map();
+    groupData.forEach((groupItems, groupKey) => {
+      groupItems.forEach(({
+        item
+      }) => {
+        itemGroupMap.set(getItemKey(item), groupKey);
+      });
+    });
+    return itemGroupMap;
+  }, [getItemKey, groupData]);
+
+  // ============================== Scroll ==============================
+  const scrollTo = (0, _util.useEvent)(config => {
+    // Group headers are rows in the virtual data, so group scroll maps to key scroll.
+    if (config && typeof config === 'object' && 'groupKey' in config) {
+      const {
+        groupKey,
+        align,
+        offset
+      } = config;
+      listRef.current?.scrollTo({
+        key: groupKey,
+        align,
+        offset
+      });
+      return;
+    }
+
+    // For sticky grouped lists, top-aligned item scroll should land below its header.
+    if (config && typeof config === 'object' && 'key' in config && sticky && group && config.align === 'top') {
+      const groupKey = itemKeyToGroupKey.get(config.key);
+      if (groupKey !== undefined) {
+        const {
+          offset = 0
+        } = config;
+        listRef.current?.scrollTo({
+          ...config,
+          // Use the measured header height so top-aligned items stay below it.
+          offset: ({
+            getSize
+          }) => {
+            const headerSize = getSize(groupKey);
+            const headerHeight = headerSize.bottom - headerSize.top;
+            return offset + (Number.isFinite(headerHeight) ? headerHeight : 0);
+          }
+        });
+        return;
+      }
+    }
+
+    // Other scroll shapes are already supported by the underlying virtual list.
+    listRef.current?.scrollTo(config);
+  });
+
+  // ============================ Imperative ============================
+  React.useImperativeHandle(ref, () => ({
+    scrollTo
+  }), [scrollTo]);
+
+  // ============================== Sticky ==============================
+  const extraRender = (0, _useStickyGroupHeader.default)({
+    enabled: !!(sticky && group),
+    group,
+    groupKeys,
+    groupKeyToItems,
+    prefixCls,
+    listRef
+  });
+
+  // ============================ Render Row ============================
+  const renderHeaderRow = React.useCallback(groupKey => {
+    const groupItems = groupKeyToItems.get(groupKey) || [];
+    return /*#__PURE__*/React.createElement(_GroupHeader.default, {
+      group: group,
+      groupKey: groupKey,
+      groupItems: groupItems,
+      prefixCls: prefixCls
+    });
+  }, [group, groupKeyToItems, prefixCls]);
+
+  // ============================== Render ==============================
+  return /*#__PURE__*/React.createElement(_virtualList.default, {
+    ref: listRef,
+    data: rows,
+    fullHeight: false,
+    height: height,
+    itemHeight: itemHeight,
+    itemKey: getKey,
+    onScroll: onScroll,
+    prefixCls: prefixCls,
+    virtual: true,
+    extraRender: extraRender
+  }, row => row.type === 'header' ? renderHeaderRow(row.groupKey) : /*#__PURE__*/React.createElement("div", {
+    className: `${prefixCls}-item`
+  }, itemRender(row.item, row.index)));
+}
+const VirtualListWithRef = /*#__PURE__*/React.forwardRef(VirtualList);
+var _default = exports.default = VirtualListWithRef;

package/lib/VirtualList/useFlattenRows.d.ts

@@ -0,0 +1,21 @@
+import * as React from 'react';
+import type { Group, GroupSegmentItem } from '../hooks/useGroupSegments';
+export type Row<T, K extends React.Key = React.Key> = {
+    type: 'header';
+    groupKey: K;
+} | {
+    type: 'item';
+    item: T;
+    index: number;
+};
+export interface FlattenRowsResult<T, K extends React.Key = React.Key> {
+    rows: Row<T, K>[];
+    groupKeys: K[];
+    groupKeyToItems: Map<K, T[]>;
+}
+/**
+ * Flatten grouped data into header and item rows.
+ * When grouping is enabled, items follow the insertion order of the group map
+ * while preserving their original indexes.
+ */
+export default function useFlattenRows<T, K extends React.Key = React.Key>(data: T[], groupData: Map<K, GroupSegmentItem<T>[]>, group?: Group<T, K>): FlattenRowsResult<T, K>;

package/lib/VirtualList/useFlattenRows.js

@@ -0,0 +1,69 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = useFlattenRows;
+var React = _interopRequireWildcard(require("react"));
+function _getRequireWildcardCache(e) { if ("function" != typeof WeakMap) return null; var r = new WeakMap(), t = new WeakMap(); return (_getRequireWildcardCache = function (e) { return e ? t : r; })(e); }
+function _interopRequireWildcard(e, r) { if (!r && e && e.__esModule) return e; if (null === e || "object" != typeof e && "function" != typeof e) return { default: e }; var t = _getRequireWildcardCache(r); if (t && t.has(e)) return t.get(e); var n = { __proto__: null }, a = Object.defineProperty && Object.getOwnPropertyDescriptor; for (var u in e) if ("default" !== u && Object.prototype.hasOwnProperty.call(e, u)) { var i = a ? Object.getOwnPropertyDescriptor(e, u) : null; i && (i.get || i.set) ? Object.defineProperty(n, u, i) : n[u] = e[u]; } return n.default = e, t && t.set(e, n), n; }
+// ============================== Types ===============================
+
+/**
+ * Flatten grouped data into header and item rows.
+ * When grouping is enabled, items follow the insertion order of the group map
+ * while preserving their original indexes.
+ */
+function useFlattenRows(data, groupData, group) {
+  return React.useMemo(() => {
+    // ============================== Init ================================
+    const flatRows = [];
+    const groupKeys = [];
+    const groupKeyToItems = new Map();
+
+    // ============================ No Group ==============================
+    if (!group) {
+      data.forEach((item, index) => {
+        flatRows.push({
+          type: 'item',
+          item,
+          index
+        });
+      });
+      return {
+        rows: flatRows,
+        groupKeys,
+        groupKeyToItems
+      };
+    }
+
+    // ============================= Flatten ==============================
+    groupData.forEach((groupItems, groupKey) => {
+      groupKeyToItems.set(groupKey, groupItems.map(({
+        item
+      }) => item));
+      groupKeys.push(groupKey);
+      flatRows.push({
+        type: 'header',
+        groupKey
+      });
+      groupItems.forEach(({
+        item,
+        index
+      }) => {
+        flatRows.push({
+          type: 'item',
+          item,
+          index
+        });
+      });
+    });
+
+    // ============================== Return ==============================
+    return {
+      rows: flatRows,
+      groupKeys,
+      groupKeyToItems
+    };
+  }, [data, group, groupData]);
+}

package/lib/VirtualList/useStickyGroupHeader.d.ts

@@ -0,0 +1,14 @@
+import * as React from 'react';
+import type { ListProps as VirtualListProps, ListRef as RcVirtualListRef } from '@rc-component/virtual-list';
+import type { Group } from '../hooks/useGroupSegments';
+type ExtraRenderInfo = Parameters<NonNullable<VirtualListProps<unknown>['extraRender']>>[0];
+export interface StickyHeaderParams<T, K extends React.Key = React.Key> {
+    enabled: boolean;
+    group: Group<T, K> | undefined;
+    groupKeys: K[];
+    groupKeyToItems: Map<K, T[]>;
+    prefixCls: string;
+    listRef: React.RefObject<RcVirtualListRef | null>;
+}
+export default function useStickyGroupHeader<T, K extends React.Key = React.Key>(params: StickyHeaderParams<T, K>): (info: ExtraRenderInfo) => React.JSX.Element;
+export {};

package/lib/VirtualList/useStickyGroupHeader.js

@@ -0,0 +1,90 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = useStickyGroupHeader;
+var React = _interopRequireWildcard(require("react"));
+var _portal = _interopRequireDefault(require("@rc-component/portal"));
+var _GroupHeader = _interopRequireDefault(require("../GroupHeader"));
+function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+function _getRequireWildcardCache(e) { if ("function" != typeof WeakMap) return null; var r = new WeakMap(), t = new WeakMap(); return (_getRequireWildcardCache = function (e) { return e ? t : r; })(e); }
+function _interopRequireWildcard(e, r) { if (!r && e && e.__esModule) return e; if (null === e || "object" != typeof e && "function" != typeof e) return { default: e }; var t = _getRequireWildcardCache(r); if (t && t.has(e)) return t.get(e); var n = { __proto__: null }, a = Object.defineProperty && Object.getOwnPropertyDescriptor; for (var u in e) if ("default" !== u && Object.prototype.hasOwnProperty.call(e, u)) { var i = a ? Object.getOwnPropertyDescriptor(e, u) : null; i && (i.get || i.set) ? Object.defineProperty(n, u, i) : n[u] = e[u]; } return n.default = e, t && t.set(e, n), n; }
+// ============================== Types ===============================
+
+// ============================== Utils ===============================
+const HEADER_TOP_TOLERANCE = 1;
+function findActiveHeaderIndex(groupKeys, getHeaderTop, scrollTop) {
+  let left = 0;
+  let right = groupKeys.length - 1;
+  let activeIndex = 0;
+  while (left <= right) {
+    const mid = Math.floor((left + right) / 2);
+    if (getHeaderTop(groupKeys[mid]) <= scrollTop + HEADER_TOP_TOLERANCE) {
+      activeIndex = mid;
+      left = mid + 1;
+    } else {
+      right = mid - 1;
+    }
+  }
+  return activeIndex;
+}
+
+// ============================== Params ==============================
+
+function useStickyGroupHeader(params) {
+  // ============================== Props ==============================
+  const {
+    enabled,
+    group,
+    groupKeys,
+    groupKeyToItems,
+    prefixCls,
+    listRef
+  } = params;
+
+  // ============================ Extra Render ==========================
+  const extraRender = React.useCallback(info => {
+    const {
+      getSize,
+      scrollTop,
+      virtual
+    } = info;
+    if (!enabled || !group || !groupKeys.length || !virtual) {
+      return null;
+    }
+    const container = listRef.current?.nativeElement;
+    if (!container) {
+      return null;
+    }
+
+    // The sticky header is the group whose section the viewport top sits in.
+    const activeHeaderIdx = findActiveHeaderIndex(groupKeys, groupKey => getSize(groupKey).top, scrollTop);
+    const currGroupKey = groupKeys[activeHeaderIdx];
+    const groupItems = groupKeyToItems.get(currGroupKey) || [];
+    const currentSize = getSize(currGroupKey);
+    const headerHeight = currentSize.bottom - currentSize.top;
+    const nextGroupKey = groupKeys[activeHeaderIdx + 1];
+    const top = nextGroupKey ? Math.min(0, getSize(nextGroupKey).top - headerHeight - scrollTop) : 0;
+
+    // Render a cloned header pinned over the virtual list.
+    return /*#__PURE__*/React.createElement(_portal.default, {
+      open: true,
+      getContainer: () => container
+    }, /*#__PURE__*/React.createElement("div", {
+      className: `${prefixCls}-group-header-holder`
+    }, /*#__PURE__*/React.createElement(_GroupHeader.default, {
+      fixed: true,
+      group: group,
+      groupKey: currGroupKey,
+      groupItems: groupItems,
+      prefixCls: prefixCls,
+      style: {
+        top
+      }
+    })));
+  }, [enabled, group, groupKeys, groupKeyToItems, prefixCls, listRef]);
+
+  // ============================== Return ==============================
+  return extraRender;
+}

package/lib/hooks/useGroupSegments.d.ts

@@ -0,0 +1,16 @@
+import * as React from 'react';
+export interface Group<T, K extends React.Key = React.Key> {
+    key: (item: T) => K;
+    title: (groupKey: K, items: T[]) => React.ReactNode;
+}
+export interface GroupSegmentItem<T> {
+    item: T;
+    index: number;
+}
+/**
+ * Build a lookup map from group key to all matching data items and their
+ * original indexes.
+ * This groups by key across the full data set and does not require items with
+ * the same key to be contiguous.
+ */
+export default function useGroupSegments<T, K extends React.Key = React.Key>(data: T[], group?: Group<T, K>): Map<K, GroupSegmentItem<T>[]>;

package/lib/hooks/useGroupSegments.js

@@ -0,0 +1,46 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = useGroupSegments;
+var React = _interopRequireWildcard(require("react"));
+function _getRequireWildcardCache(e) { if ("function" != typeof WeakMap) return null; var r = new WeakMap(), t = new WeakMap(); return (_getRequireWildcardCache = function (e) { return e ? t : r; })(e); }
+function _interopRequireWildcard(e, r) { if (!r && e && e.__esModule) return e; if (null === e || "object" != typeof e && "function" != typeof e) return { default: e }; var t = _getRequireWildcardCache(r); if (t && t.has(e)) return t.get(e); var n = { __proto__: null }, a = Object.defineProperty && Object.getOwnPropertyDescriptor; for (var u in e) if ("default" !== u && Object.prototype.hasOwnProperty.call(e, u)) { var i = a ? Object.getOwnPropertyDescriptor(e, u) : null; i && (i.get || i.set) ? Object.defineProperty(n, u, i) : n[u] = e[u]; } return n.default = e, t && t.set(e, n), n; }
+// ============================== Types ===============================
+
+/**
+ * Build a lookup map from group key to all matching data items and their
+ * original indexes.
+ * This groups by key across the full data set and does not require items with
+ * the same key to be contiguous.
+ */
+function useGroupSegments(data, group) {
+  return React.useMemo(() => {
+    // ============================== Init ================================
+    const map = new Map();
+
+    // ============================ No Group ==============================
+    if (!group) {
+      return map;
+    }
+
+    // ============================= Collect ==============================
+    data.forEach((item, index) => {
+      const groupKey = group.key(item);
+      const groupItems = map.get(groupKey);
+      const groupSegmentItem = {
+        item,
+        index
+      };
+      if (groupItems) {
+        groupItems.push(groupSegmentItem);
+      } else {
+        map.set(groupKey, [groupSegmentItem]);
+      }
+    });
+
+    // ============================== Return ==============================
+    return map;
+  }, [data, group]);
+}

package/lib/index.d.ts

@@ -0,0 +1,3 @@
+import Listy from './List';
+export type { ListyRef, ListyProps } from './List';
+export default Listy;

package/lib/index.js

@@ -0,0 +1,9 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _List = _interopRequireDefault(require("./List"));
+function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+var _default = exports.default = _List.default;

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@rc-component/listy",
+  "version": "1.1.0",
+  "description": "React Listy Component",
+  "keywords": [
+    "react",
+    "react-component",
+    "list",
+    "high performance",
+    "headless ui"
+  ],
+  "homepage": "https://github.com/react-component/listy",
+  "author": "",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/react-component/listy.git"
+  },
+  "bugs": {
+    "url": "https://github.com/react-component/listy/issues"
+  },
+  "files": [
+    "es",
+    "lib",
+    "assets/**/*.css",
+    "assets/**/*.less"
+  ],
+  "license": "MIT",
+  "main": "./lib/index",
+  "module": "./es/index",
+  "scripts": {
+    "start": "dumi dev",
+    "build": "dumi build",
+    "compile": "father build && lessc assets/index.less assets/index.css",
+    "prepublishOnly": "npm run compile && rc-np",
+    "lint": "eslint src/ docs/examples/ --ext .tsx,.ts,.jsx,.js",
+    "test": "rc-test",
+    "prettier": "prettier --write .",
+    "coverage": "rc-test --coverage",
+    "now-build": "npm run build"
+  },
+  "dependencies": {
+    "@rc-component/motion": "^1.1.4",
+    "@rc-component/portal": "^2.0.0",
+    "@rc-component/resize-observer": "^1.0.0",
+    "@rc-component/util": "^1.3.1",
+    "clsx": "^2.1.1",
+    "@rc-component/virtual-list": "^1.2.0"
+  },
+  "devDependencies": {
+    "@rc-component/father-plugin": "^2.1.3",
+    "@rc-component/np": "^1.0.4",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.0",
+    "@types/classnames": "^2.3.4",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^24.10.0",
+    "@types/react": "^19.2.2",
+    "@types/react-dom": "^19.2.2",
+    "@umijs/fabric": "^4.0.1",
+    "cross-env": "^10.1.0",
+    "dumi": "^2.4.21",
+    "eslint": "^8.57.1",
+    "father": "^4.6.7",
+    "less": "^4.4.2",
+    "prettier": "^3.6.2",
+    "rc-test": "^7.1.2",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "regenerator-runtime": "^0.14.1",
+    "typescript": "^6.0.3"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  }
+}