@rc-component/listy 1.1.0

package/es/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/es/VirtualList/useFlattenRows.js

@@ -0,0 +1,62 @@
+import * as React from 'react';
+
+// ============================== 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.
+ */
+export default 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/es/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/es/VirtualList/useStickyGroupHeader.js

@@ -0,0 +1,82 @@
+import * as React from 'react';
+import Portal from '@rc-component/portal';
+import GroupHeader from "../GroupHeader";
+
+// ============================== 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 ==============================
+
+export default 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, {
+      open: true,
+      getContainer: () => container
+    }, /*#__PURE__*/React.createElement("div", {
+      className: `${prefixCls}-group-header-holder`
+    }, /*#__PURE__*/React.createElement(GroupHeader, {
+      fixed: true,
+      group: group,
+      groupKey: currGroupKey,
+      groupItems: groupItems,
+      prefixCls: prefixCls,
+      style: {
+        top
+      }
+    })));
+  }, [enabled, group, groupKeys, groupKeyToItems, prefixCls, listRef]);
+
+  // ============================== Return ==============================
+  return extraRender;
+}

package/es/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/es/hooks/useGroupSegments.js

@@ -0,0 +1,39 @@
+import * as React from 'react';
+
+// ============================== 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.
+ */
+export default 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/es/index.d.ts

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

package/es/index.js

@@ -0,0 +1,2 @@
+import Listy from "./List";
+export default Listy;

package/lib/GroupHeader.d.ts

@@ -0,0 +1,15 @@
+import * as React from 'react';
+import type { Group } from './hooks/useGroupSegments';
+export interface GroupHeaderProps<T, K extends React.Key = React.Key> {
+    group: Group<T, K>;
+    groupKey: K;
+    groupItems: T[];
+    prefixCls: string;
+    fixed?: boolean;
+    sticky?: boolean;
+    style?: React.CSSProperties;
+}
+declare const GroupHeaderWithRef: <T, K extends React.Key = React.Key>(props: GroupHeaderProps<T, K> & {
+    ref?: React.Ref<HTMLDivElement>;
+}) => React.ReactElement;
+export default GroupHeaderWithRef;

package/lib/GroupHeader.js

@@ -0,0 +1,40 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var React = _interopRequireWildcard(require("react"));
+var _clsx = _interopRequireDefault(require("clsx"));
+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 GroupHeader(props, ref) {
+  // ============================== Props ==============================
+  const {
+    group,
+    groupKey,
+    groupItems,
+    prefixCls,
+    fixed,
+    sticky,
+    style
+  } = props;
+
+  // ============================= Classes =============================
+  const className = (0, _clsx.default)(`${prefixCls}-group-header`, {
+    [`${prefixCls}-group-header-sticky`]: sticky,
+    [`${prefixCls}-group-header-fixed`]: fixed
+  });
+
+  // ============================== Render ==============================
+  return /*#__PURE__*/React.createElement("div", {
+    ref: ref,
+    className: className,
+    style: style
+  }, group.title(groupKey, groupItems));
+}
+const GroupHeaderWithRef = /*#__PURE__*/React.forwardRef(GroupHeader);
+var _default = exports.default = GroupHeaderWithRef;

package/lib/List.d.ts

@@ -0,0 +1,49 @@
+import * as React from 'react';
+import type { Group } from './hooks/useGroupSegments';
+export type RowKey<T> = keyof T | ((item: T) => React.Key);
+export type ScrollAlign = 'top' | 'bottom' | 'auto';
+export interface GroupScrollToConfig {
+    groupKey: React.Key;
+    align?: ScrollAlign;
+    offset?: number;
+}
+export interface KeyScrollToConfig {
+    key: React.Key;
+    align?: ScrollAlign;
+    offset?: number;
+}
+export interface PositionScrollToConfig {
+    left?: number;
+    top?: number;
+}
+export type ListyScrollToConfig = number | null | KeyScrollToConfig | PositionScrollToConfig | GroupScrollToConfig;
+export interface ListyRef {
+    scrollTo: (config?: ListyScrollToConfig) => void;
+}
+export interface ListyProps<T, K extends React.Key = React.Key> {
+    items?: T[];
+    sticky?: boolean;
+    itemHeight?: number;
+    height?: number;
+    group?: Group<T, K>;
+    virtual?: boolean;
+    prefixCls?: string;
+    rowKey: RowKey<T>;
+    onScroll?: React.UIEventHandler<HTMLElement>;
+    itemRender: (item: T, index: number) => React.ReactNode;
+}
+export interface ListComponentProps<T, K extends React.Key = React.Key> {
+    data: T[];
+    sticky?: boolean;
+    itemHeight?: number;
+    height?: number;
+    group?: Group<T, K>;
+    prefixCls: string;
+    rowKey: RowKey<T>;
+    onScroll?: React.UIEventHandler<HTMLElement>;
+    itemRender: (item: T, index: number) => React.ReactNode;
+}
+declare const ListyWithForwardRef: <T, K extends React.Key = React.Key>(props: ListyProps<T, K> & {
+    ref?: React.Ref<ListyRef>;
+}) => React.ReactElement;
+export default ListyWithForwardRef;

package/lib/List.js

@@ -0,0 +1,41 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _react = _interopRequireWildcard(require("react"));
+var React = _react;
+var _RawList = _interopRequireDefault(require("./RawList"));
+var _VirtualList = _interopRequireDefault(require("./VirtualList"));
+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 Listy(props, ref) {
+  // ============================== Props ==============================
+  const {
+    items,
+    virtual = true,
+    prefixCls = 'rc-listy',
+    ...restProps
+  } = props;
+
+  // =============================== Data ===============================
+  const data = React.useMemo(() => items || [], [items]);
+
+  // ============================== Render ===============================
+  const sharedListProps = {
+    ...restProps,
+    data,
+    prefixCls,
+    ref
+  };
+  const listNode = virtual ? /*#__PURE__*/React.createElement(_VirtualList.default, sharedListProps) : /*#__PURE__*/React.createElement(_RawList.default, sharedListProps);
+  return listNode;
+}
+
+// Const to support generic with forwardRef
+const ListyWithForwardRef = /*#__PURE__*/(0, _react.forwardRef)(Listy);
+var _default = exports.default = ListyWithForwardRef;

package/lib/RawList/index.d.ts

@@ -0,0 +1,5 @@
+import * as React from 'react';
+import type { ListComponentProps } from '../List';
+export type RawListProps<T, K extends React.Key = React.Key> = ListComponentProps<T, K>;
+declare const RawListWithRef: any;
+export default RawListWithRef;

package/lib/RawList/index.js

@@ -0,0 +1,98 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var React = _interopRequireWildcard(require("react"));
+var _util = require("@rc-component/util");
+var _GroupHeader = _interopRequireDefault(require("../GroupHeader"));
+var _useGroupSegments = _interopRequireDefault(require("../hooks/useGroupSegments"));
+var _useRawListScroll = _interopRequireDefault(require("./useRawListScroll"));
+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; }
+function _extends() { _extends = Object.assign ? Object.assign.bind() : function (target) { for (var i = 1; i < arguments.length; i++) { var source = arguments[i]; for (var key in source) { if (Object.prototype.hasOwnProperty.call(source, key)) { target[key] = source[key]; } } } return target; }; return _extends.apply(this, arguments); }
+// ============================== Types ===============================
+
+function RawList(props, ref) {
+  // ============================== Props ==============================
+  const {
+    data,
+    group,
+    height,
+    itemRender,
+    onScroll,
+    prefixCls,
+    rowKey,
+    sticky
+  } = props;
+
+  // =============================== Refs ===============================
+  const holderRef = (0, _useRawListScroll.default)(ref, prefixCls, !!(sticky && group));
+
+  // =============================== Data ===============================
+  const groupData = (0, _useGroupSegments.default)(data, group);
+
+  // ============================== Utils ===============================
+  const getItemKey = (0, _util.useEvent)(item => {
+    if (typeof rowKey === 'function') {
+      return rowKey(item);
+    }
+    return item[rowKey];
+  });
+  const getScrollTargetProps = React.useCallback(key => ({
+    'data-key': String(key)
+  }), []);
+
+  // ============================ Render Item ===========================
+  const renderItem = React.useCallback((item, index, groupKey) => {
+    const key = getItemKey(item);
+    const scrollTargetProps = getScrollTargetProps(key);
+    return /*#__PURE__*/React.createElement("div", _extends({
+      key: key,
+      className: `${prefixCls}-item`,
+      style: sticky && groupKey !== undefined ? {
+        scrollMarginTop: `var(--${prefixCls}-item-scroll-margin-top, 0px)`
+      } : undefined
+    }, scrollTargetProps), itemRender(item, index));
+  }, [getItemKey, getScrollTargetProps, itemRender, prefixCls, sticky]);
+
+  // ============================= Content ==============================
+  const rawContent = group ? Array.from(groupData, ([groupKey, groupItems]) => {
+    const currentGroupItems = groupItems.map(({
+      item
+    }) => item);
+    return /*#__PURE__*/React.createElement("div", _extends({
+      key: groupKey,
+      className: `${prefixCls}-group-section`
+    }, getScrollTargetProps(groupKey)), /*#__PURE__*/React.createElement(_GroupHeader.default, {
+      group: group,
+      groupKey: groupKey,
+      groupItems: currentGroupItems,
+      prefixCls: prefixCls,
+      sticky: sticky
+    }), groupItems.map(({
+      item,
+      index
+    }) => {
+      return renderItem(item, index, groupKey);
+    }));
+  }) : data.map((item, index) => {
+    return renderItem(item, index);
+  });
+
+  // ============================== Render ==============================
+  return /*#__PURE__*/React.createElement("div", {
+    ref: holderRef,
+    className: prefixCls,
+    style: {
+      maxHeight: height,
+      overflowY: height === undefined ? undefined : 'auto',
+      overflowAnchor: 'none'
+    },
+    onScroll: onScroll
+  }, rawContent);
+}
+const RawListWithRef = /*#__PURE__*/React.forwardRef(RawList);
+var _default = exports.default = RawListWithRef;

package/lib/RawList/useRawListScroll.d.ts

@@ -0,0 +1,3 @@
+import * as React from 'react';
+import type { ListyRef } from '../List';
+export default function useRawListScroll(ref: React.Ref<ListyRef>, prefixCls: string, stickyGroup: boolean): React.RefObject<HTMLDivElement>;

package/lib/RawList/useRawListScroll.js

@@ -0,0 +1,79 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = useRawListScroll;
+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; }
+function useRawListScroll(ref, prefixCls, stickyGroup) {
+  // =============================== Refs ===============================
+  const holderRef = React.useRef(null);
+
+  // ============================== Utils ===============================
+  const getStickyHeaderHeight = React.useCallback(targetElement => {
+    if (!stickyGroup) {
+      return 0;
+    }
+    const groupSection = targetElement.closest(`.${CSS.escape(`${prefixCls}-group-section`)}`);
+    const groupHeader = groupSection?.querySelector(`.${CSS.escape(`${prefixCls}-group-header`)}`);
+    if (!groupHeader) {
+      return 0;
+    }
+    const rect = groupHeader.getBoundingClientRect();
+    const height = rect.height || rect.bottom - rect.top || groupHeader.offsetHeight;
+    return Number.isFinite(height) ? height : 0;
+  }, [prefixCls, stickyGroup]);
+  const setTargetScrollMargin = React.useCallback((targetElement, align) => {
+    const marginTop = align === 'top' ? getStickyHeaderHeight(targetElement) : 0;
+    targetElement.style.setProperty(`--${prefixCls}-item-scroll-margin-top`, `${marginTop}px`);
+  }, [getStickyHeaderHeight, prefixCls]);
+
+  // ============================== Scroll ==============================
+  const scrollTo = React.useCallback(config => {
+    const holder = holderRef.current;
+    if (!holder || config == null) {
+      return;
+    }
+    if (typeof config === 'number') {
+      holder.scrollTop = config;
+      return;
+    }
+    if ('key' in config || 'groupKey' in config) {
+      const {
+        align = 'top'
+      } = config;
+      const targetKey = 'groupKey' in config ? config.groupKey : config.key;
+      const targetElement = holder.querySelector(`[data-key="${CSS.escape(String(targetKey))}"]`);
+      if (targetElement) {
+        if ('key' in config) {
+          setTargetScrollMargin(targetElement, align);
+        }
+        targetElement.scrollIntoView({
+          block: align === 'bottom' ? 'end' : align === 'auto' ? 'nearest' : 'start',
+          inline: 'nearest'
+        });
+      }
+      return;
+    }
+    const {
+      left,
+      top
+    } = config;
+    if (left !== undefined) {
+      holder.scrollLeft = left;
+    }
+    if (top !== undefined) {
+      holder.scrollTop = top;
+    }
+  }, [setTargetScrollMargin]);
+
+  // ============================ Imperative ============================
+  React.useImperativeHandle(ref, () => ({
+    scrollTo
+  }), [scrollTo]);
+
+  // ============================== Return ==============================
+  return holderRef;
+}

package/lib/VirtualList/index.d.ts

@@ -0,0 +1,5 @@
+import * as React from 'react';
+import type { ListComponentProps } from '../List';
+export type VirtualListProps<T, K extends React.Key = React.Key> = ListComponentProps<T, K>;
+declare const VirtualListWithRef: any;
+export default VirtualListWithRef;