@rainbow-oh/yee-c 0.6.4 → 0.8.0

package/src/List/list.tsx

@@ -1,7 +1,9 @@
 import clsx from 'clsx';
 import React, { createContext, forwardRef, useContext } from 'react';
 import { GlobalContext } from '../Config-Provider';
+import useVirtualList from '../hooks/useVirtualList';
 import mergeContextToProps from '../utils/mergeContextToProps';
+import useListKeyboard from './hooks/useListKeyboard';
 import type { ListCtxType, ListProps } from './interface';
 import ListItem from './list-item';
 
@@ -16,43 +18,179 @@ const List = forwardRef<HTMLUListElement, ListProps>((baseprops, ref) => {
   const {
     prefixCls = 'yee-list',
     className,
+    style,
     items,
     bordered,
-    focusedKey,
+    focusedKey: controlledFocusedKey,
     itemRender,
     onClick,
+    onFocusChange,
+    virtual = false,
+    height,
+    itemHeight = 32,
+    columns = 1,
     ...rest
   } = props;
 
+  const multiColumn = columns > 1;
+  const useVirtual = virtual && height !== null && height !== undefined && Array.isArray(items);
+  const safeItems = Array.isArray(items) ? items : [];
+
+  // Keyboard navigation
+  const { focusedKey, onKeyDown } = useListKeyboard({
+    items: safeItems,
+    columns,
+    focusedKey: controlledFocusedKey,
+    onFocusChange,
+    onClick,
+  });
+
+  // Virtual scroll — in multi-column mode, track rows not individual items
+  const rowCount = multiColumn
+    ? Math.ceil(safeItems.length / columns)
+    : safeItems.length;
+
+  const { start, end, offsetY, totalHeight, viewportRef, onScroll } =
+    useVirtualList({
+      itemCount: useVirtual ? rowCount : 0,
+      itemHeight,
+      overscan: 4,
+    });
+
   const cls = clsx(
     prefixCls,
     {
       [`${prefixCls}-bordered`]: bordered,
+      [`${prefixCls}-grid`]: multiColumn && !useVirtual,
     },
     className,
   );
 
-  const itemRenders = () => {
-    return Array.isArray(items)
-      ? items.map((item, index) => {
-          if (typeof itemRender === 'function') {
-            return itemRender(item);
-          }
-          return <ListItem {...item} $key={item.key} key={item.key || index} />;
-        })
-      : null;
+  const renderItem = (item: any, index: number) => {
+    if (typeof itemRender === 'function') {
+      return itemRender(item);
+    }
+    return <ListItem {...item} $key={item.key} key={item.key || index} />;
   };
 
-  return (
-    <ul ref={ref} className={cls} tabIndex={0} aria-label="list" {...rest}>
-      <ListCtx.Provider
-        value={{
-          prefixCls,
-          focusedKey,
-          onClick: onClick,
-        }}
+  // ----- Virtual + multi-column: render rows of N items -----
+  if (useVirtual && multiColumn) {
+    const visibleRows = [];
+    for (let rowIdx = start; rowIdx < end; rowIdx++) {
+      const rowItems = [];
+      for (let col = 0; col < columns; col++) {
+        const flatIdx = rowIdx * columns + col;
+        if (flatIdx < safeItems.length) {
+          rowItems.push({ item: safeItems[flatIdx], flatIdx });
+        }
+      }
+      visibleRows.push({ rowIdx, rowItems });
+    }
+
+    return (
+      <ul
+        ref={ref}
+        className={cls}
+        tabIndex={0}
+        aria-label="list"
+        onKeyDown={onKeyDown}
+        {...rest}
+      >
+        <ListCtx.Provider value={{ prefixCls, focusedKey, onClick }}>
+          <div
+            ref={viewportRef}
+            onScroll={onScroll}
+            style={{ height, overflowY: 'auto' }}
+          >
+            <div style={{ height: totalHeight, position: 'relative' }}>
+              {visibleRows.map(({ rowIdx, rowItems }, ri) => (
+                <div
+                  key={rowIdx}
+                  className={`${prefixCls}-grid-row`}
+                  style={{
+                    position: 'absolute',
+                    top: 0,
+                    left: 0,
+                    right: 0,
+                    height: itemHeight,
+                    transform: `translateY(${offsetY + ri * itemHeight}px)`,
+                    display: 'grid',
+                    gridTemplateColumns: `repeat(${columns}, 1fr)`,
+                  }}
+                >
+                  {rowItems.map(({ item, flatIdx }) =>
+                    renderItem(item, flatIdx),
+                  )}
+                </div>
+              ))}
+            </div>
+          </div>
+        </ListCtx.Provider>
+      </ul>
+    );
+  }
+
+  // ----- Virtual single-column -----
+  if (useVirtual) {
+    const slicedItems = safeItems.slice(start, end);
+    return (
+      <ul
+        ref={ref}
+        className={cls}
+        tabIndex={0}
+        aria-label="list"
+        onKeyDown={onKeyDown}
+        {...rest}
       >
-        {itemRenders()}
+        <ListCtx.Provider value={{ prefixCls, focusedKey, onClick }}>
+          <div
+            ref={viewportRef}
+            onScroll={onScroll}
+            style={{ height, overflowY: 'auto' }}
+          >
+            <div style={{ height: totalHeight, position: 'relative' }}>
+              {slicedItems.map((item, i) => {
+                const element = renderItem(item, start + i);
+                return (
+                  <div
+                    key={item.key || start + i}
+                    style={{
+                      position: 'absolute',
+                      top: 0,
+                      left: 0,
+                      width: '100%',
+                      height: itemHeight,
+                      transform: `translateY(${offsetY + i * itemHeight}px)`,
+                    }}
+                  >
+                    {element}
+                  </div>
+                );
+              })}
+            </div>
+          </div>
+        </ListCtx.Provider>
+      </ul>
+    );
+  }
+
+  // ----- Default mode (non-virtual) -----
+  return (
+    <ul
+      ref={ref}
+      className={cls}
+      tabIndex={0}
+      aria-label="list"
+      onKeyDown={onKeyDown}
+      style={
+        multiColumn
+          ? ({ '--yee-list-columns': columns, ...style } as React.CSSProperties)
+          : style
+      }
+      {...rest}
+    >
+      <ListCtx.Provider value={{ prefixCls, focusedKey, onClick }}>
+        {safeItems.map((item, index) => renderItem(item, index))}
       </ListCtx.Provider>
     </ul>
   );

package/src/List/style/index.less

@@ -6,18 +6,42 @@
   list-style: none;
   background-color: var(--yee-list-bg-color);
 
+  &:focus {
+    outline: none;
+  }
+
   &-item {
     padding: var(--yee-list-item-padding);
 
     &:hover:not(&-disabled) {
       background-color: var(--yee-list-item-bg-hover-color);
+    }
+
+    &-disabled {
       cursor: not-allowed;
+      opacity: 0.5;
+    }
+
+    &-clickable:not(&-disabled) {
+      cursor: pointer;
     }
 
     &-focused {
       background-color: var(--yee-list-item-bg-hover-color);
     }
   }
+
+  // Multi-column grid layout (non-virtual mode).
+  // Column count driven by CSS custom property --yee-list-columns set inline.
+  &-grid {
+    display: grid;
+    grid-template-columns: repeat(var(--yee-list-columns, 1), 1fr);
+  }
+
+  // Virtual multi-column: each row is already a grid via inline style.
+  &-grid-row {
+    align-items: center;
+  }
 }
 
 @{pls}-bordered {

package/src/Select/demo/columns.tsx

@@ -0,0 +1,35 @@
+import { Select } from '@rainbow-oh/yee-c';
+import React from 'react';
+
+const options = Array.from({ length: 24 }, (_, i) => ({
+  label: `Option ${i + 1}`,
+  value: `opt-${i + 1}`,
+}));
+
+export default () => {
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: 24 }}>
+      <div>
+        <p>3 columns:</p>
+        <Select
+          columns={3}
+          popupWidth={360}
+          options={options}
+          placeholder="Select an option"
+          style={{ width: 200 }}
+        />
+      </div>
+      <div>
+        <p>4 columns with multiple selection:</p>
+        <Select
+          columns={4}
+          popupWidth={480}
+          mode="multiple"
+          options={options}
+          placeholder="Select options"
+          style={{ width: 300 }}
+        />
+      </div>
+    </div>
+  );
+};

package/src/Select/hooks/useSelectKeyboard.ts

@@ -9,6 +9,18 @@ interface UseSelectKeyboardParams {
   }>;
   open: boolean;
   selectedKeys: Array<string | number>;
+  /**
+   * Number of columns in multi-column mode.
+   * Affects ArrowLeft/ArrowRight and ArrowUp/ArrowDown behavior.
+   * @default 1
+   */
+  columns?: number;
+  /**
+   * Whether loose value matching is enabled.
+   * Affects initial focus resolution when selectedKeys types differ from option values.
+   * @default false
+   */
+  looseMatch?: boolean;
   onSelect: (value: string | number) => void;
   onClose?: () => void;
   onOpenChange?: (open: boolean) => void;
@@ -25,6 +37,8 @@ export default function useSelectKeyboard({
   options,
   open,
   selectedKeys,
+  columns = 1,
+  looseMatch = false,
   onSelect,
   onClose,
   onOpenChange,
@@ -79,9 +93,15 @@ export default function useSelectKeyboard({
     const optionElements = container.querySelectorAll('[role="option"]');
     const targetElement = optionElements[index] as HTMLElement;
     if (targetElement) {
-      targetElement.scrollIntoView({
-        block: 'nearest',
-      });
+      // Use manual scroll calculation instead of scrollIntoView to avoid
+      // scrolling the entire page (popup is rendered in a portal).
+      const containerRect = container.getBoundingClientRect();
+      const targetRect = targetElement.getBoundingClientRect();
+      if (targetRect.bottom > containerRect.bottom) {
+        container.scrollTop += targetRect.bottom - containerRect.bottom;
+      } else if (targetRect.top < containerRect.top) {
+        container.scrollTop -= containerRect.top - targetRect.top;
+      }
     }
   };
 
@@ -90,12 +110,33 @@ export default function useSelectKeyboard({
     const focusedIndex = getFocusedIndex();
     let nextIndex: number;
 
-    if (focusedIndex === -1) {
-      // No focus yet, focus the last enabled option
-      nextIndex = findNextEnabledIndex(options.length - 1, -1);
+    if (columns > 1) {
+      // Multi-column: move up one row (jump by `columns` items)
+      if (focusedIndex === -1) {
+        nextIndex = findNextEnabledIndex(options.length - 1, -1);
+      } else {
+        const target = focusedIndex - columns;
+        if (target >= 0) {
+          nextIndex = options[target].disabled
+            ? findNextEnabledIndex(target, -1)
+            : target;
+        } else {
+          // Wrap to bottom: find the same column in the last row
+          const lastRowStart =
+            Math.floor((options.length - 1) / columns) * columns;
+          const col = focusedIndex % columns;
+          const wrapTarget = Math.min(lastRowStart + col, options.length - 1);
+          nextIndex = options[wrapTarget]?.disabled
+            ? findNextEnabledIndex(wrapTarget, -1)
+            : wrapTarget;
+        }
+      }
     } else {
-      // Find the previous enabled option
-      nextIndex = findNextEnabledIndex(focusedIndex, -1);
+      if (focusedIndex === -1) {
+        nextIndex = findNextEnabledIndex(options.length - 1, -1);
+      } else {
+        nextIndex = findNextEnabledIndex(focusedIndex, -1);
+      }
     }
 
     if (nextIndex !== -1) {
@@ -110,13 +151,33 @@ export default function useSelectKeyboard({
     const focusedIndex = getFocusedIndex();
     let nextIndex: number;
 
-    if (focusedIndex === -1) {
-      // No focus yet, focus the first enabled option
-      nextIndex = findNextEnabledIndex(0, 1);
+    if (columns > 1) {
+      // Multi-column: move down one row (jump by `columns` items)
+      if (focusedIndex === -1) {
+        nextIndex = findNextEnabledIndex(0, 1);
+      } else {
+        const target = focusedIndex + columns;
+        if (target < options.length) {
+          nextIndex = options[target].disabled
+            ? findNextEnabledIndex(target, 1)
+            : target;
+        } else {
+          // Wrap to top: find the same column in the first row
+          const col = focusedIndex % columns;
+          const wrapTarget = col;
+          nextIndex = options[wrapTarget]?.disabled
+            ? findNextEnabledIndex(wrapTarget, 1)
+            : wrapTarget;
+        }
+      }
     } else {
-      // Find the next enabled option
-      nextIndex = findNextEnabledIndex(focusedIndex, 1);
+      if (focusedIndex === -1) {
+        nextIndex = findNextEnabledIndex(0, 1);
+      } else {
+        nextIndex = findNextEnabledIndex(focusedIndex, 1);
+      }
     }
+
     if (nextIndex !== -1) {
       const nextValue = options[nextIndex].value;
       setFocusedKey(nextValue);
@@ -124,6 +185,28 @@ export default function useSelectKeyboard({
     }
   };
 
+  // Handle ArrowLeft key (multi-column: move to previous item)
+  const handleArrowLeft = () => {
+    const focusedIndex = getFocusedIndex();
+    if (focusedIndex <= 0) return;
+    const nextIndex = findNextEnabledIndex(focusedIndex, -1);
+    if (nextIndex !== -1) {
+      setFocusedKey(options[nextIndex].value);
+      scrollOptionIntoView(nextIndex);
+    }
+  };
+
+  // Handle ArrowRight key (multi-column: move to next item)
+  const handleArrowRight = () => {
+    const focusedIndex = getFocusedIndex();
+    if (focusedIndex >= options.length - 1) return;
+    const nextIndex = findNextEnabledIndex(focusedIndex, 1);
+    if (nextIndex !== -1) {
+      setFocusedKey(options[nextIndex].value);
+      scrollOptionIntoView(nextIndex);
+    }
+  };
+
   // Handle Enter key
   const handleEnter = () => {
     const currentFocusedKey = latestFocusedKey.current;
@@ -161,6 +244,18 @@ export default function useSelectKeyboard({
         event.preventDefault();
         handleArrowDown();
         break;
+      case 'ArrowLeft':
+        if (columns > 1) {
+          event.preventDefault();
+          handleArrowLeft();
+        }
+        break;
+      case 'ArrowRight':
+        if (columns > 1) {
+          event.preventDefault();
+          handleArrowRight();
+        }
+        break;
       case 'Enter':
         event.preventDefault();
         handleEnter();
@@ -179,8 +274,10 @@ export default function useSelectKeyboard({
       // Focus the first selected option, or the first enabled option
       let focusedValue: string | number = '';
       if (selectedKeys?.length > 0) {
-        const firstSelected = options?.find(
-          (opt) => opt.value === selectedKeys[0],
+        const firstSelected = options?.find((opt) =>
+          looseMatch
+            ? String(opt.value) === String(selectedKeys[0])
+            : opt.value === selectedKeys[0],
         );
         if (firstSelected && !firstSelected.disabled) {
           focusedValue = firstSelected.value;

package/src/Select/index.en-US.md

@@ -23,6 +23,7 @@ Select component for choosing from a set of options.
 <code src="./demo/tags.tsx" title="Tags" description="Tags mode Select"></code>
 <code src="./demo/orphan.tsx" title="Orphan Value" description="Display and custom styling when the value is not in options"></code>
 <code src="./demo/virtual.tsx" title="Virtual Scroll" description="Virtual scrolling for large datasets (thousands of options)"></code>
+<code src="./demo/columns.tsx" title="Multi-Column" description="Dropdown panel supports multi-column grid display to save vertical space when there are many options"></code>
 
 ## API
 
@@ -53,6 +54,9 @@ Select component for choosing from a set of options.
 | virtual | `boolean` | Enable virtual scrolling. Only the options in the visible window are rendered, so the DOM node count stays constant regardless of the total. Recommended for hundreds or thousands of options | `false` |
 | itemHeight | `number` | Fixed height of each option in pixels. Must be a fixed value when `virtual` is enabled | `32` |
 | listHeight | `number` | Max height of the dropdown popup in pixels | `200` |
+| columns | `number` | Number of columns in the dropdown panel. Enables grid layout when greater than 1 | `1` |
+| popupWidth | `number` | Fixed width of the dropdown popup in pixels. When set, the popup does not stretch to match the trigger width. Useful with multi-column layout | - |
+| looseMatch | `boolean` | Enable loose value matching. When enabled, value comparison uses `String()` conversion instead of strict equality, resolving number/string type mismatch between `value` and `options`. Note: when enabled, `onChange` returns the option's value type, not the originally passed value type | `false` |
 | data-* | `string` | - | Supports all data-* attributes, forwarded to root DOM element |
 
 ### Option

package/src/Select/index.zh-CN.md

@@ -23,6 +23,7 @@ toc: 'content'
 <code src="./demo/tags.tsx" title="标签模式" description="标签模式的Select"></code>
 <code src="./demo/orphan.tsx" title="孤儿值" description="value 不在 options 中时的显示与自定义样式"></code>
 <code src="./demo/virtual.tsx" title="虚拟滚动" description="大数据量（几千条）下的虚拟滚动"></code>
+<code src="./demo/columns.tsx" title="多列布局" description="下拉面板支持多列网格显示，适合选项较多时节省纵向空间"></code>
 
 ## API
 
@@ -53,6 +54,9 @@ toc: 'content'
 | virtual | `boolean` | 是否开启虚拟滚动。开启后仅渲染可视区内的选项，DOM 节点数与数据总量无关，适合成百上千条数据 | `false` |
 | itemHeight | `number` | 每个选项的固定高度（px），开启 `virtual` 时必须为定值 | `32` |
 | listHeight | `number` | 下拉框最大高度（px） | `200` |
+| columns | `number` | 下拉面板列数，大于 1 时启用网格布局 | `1` |
+| popupWidth | `number` | 下拉面板固定宽度（px），设置后弹出层不再跟随触发元素宽度。配合多列布局使用 | - |
+| looseMatch | `boolean` | 是否启用宽松值匹配。开启后 value 与 options 的 value 通过 `String()` 转换后比较，解决 number/string 类型不一致的问题。注意：开启后 `onChange` 回调中的 value 类型为 option 定义的类型，而非传入的原始类型 | `false` |
 | data-* | `string` | - | 支持所有 data-* 属性，透传到组件根 DOM 元素 |
 
 ### Option

package/src/Select/interface.ts

@@ -137,11 +137,27 @@ export interface SelectProps
    * @default 200
    */
   listHeight?: number;
+  /**
+   * Number of columns in the dropdown panel.
+   * When greater than 1, options are displayed in a grid layout.
+   * @default 1
+   */
+  columns?: number;
+  /**
+   * Fixed width of the dropdown popup in pixels.
+   * When set, the popup will not stretch to match the trigger width.
+   * Useful with multi-column layout to provide enough horizontal space.
+   */
+  popupWidth?: number;
+  /**
+   * Enable loose value matching. When enabled, value comparison uses
+   * `String(a) === String(b)` instead of strict equality (`===`).
+   * Resolves type mismatch when options use string values but the
+   * controlled value is a number (or vice versa).
+   * @default false
+   */
+  looseMatch?: boolean;
 }
-
-/**
- * Props for the internal Option component (renders a single dropdown option).
- */
 export interface OptionProps {
   /**
    * Display label
@@ -178,6 +194,7 @@ export interface OptionsContextValue {
   selectedKeys: Array<string | number>;
   focusedKey: string | number;
   multiple: boolean;
+  looseMatch: boolean;
   onSelect: (
     key: string | number,
     e?: React.MouseEvent | React.KeyboardEvent,
@@ -243,6 +260,15 @@ export interface OptionsProps extends Omit<
   virtualApiRef?: React.MutableRefObject<{
     scrollToIndex: (index: number) => void;
   } | null>;
+  /**
+   * Number of columns in the dropdown grid layout.
+   * @default 1
+   */
+  columns?: number;
+  /**
+   * Whether loose value matching is enabled
+   */
+  looseMatch?: boolean;
   /**
    * Callback when an option is selected
    */
@@ -251,3 +277,4 @@ export interface OptionsProps extends Omit<
     e?: React.MouseEvent | React.KeyboardEvent,
   ) => void;
 }
+

package/src/Select/option.tsx

@@ -7,7 +7,7 @@ import { OptionsCtx } from './options';
 
 const Option = (props: OptionProps) => {
   const { label, value, disabled, title, dataTestId, style } = props;
-  const { prefixCls, selectedKeys, focusedKey, multiple, onSelect } =
+  const { prefixCls, selectedKeys, focusedKey, multiple, looseMatch, onSelect } =
     useContext(OptionsCtx);
 
   const handleClick = (e: React.MouseEvent | React.KeyboardEvent) => {
@@ -22,13 +22,19 @@ const Option = (props: OptionProps) => {
       ? label
       : undefined;
 
-  const selected = selectedKeys.includes(value);
+  const selected = looseMatch
+    ? selectedKeys.some((k) => String(k) === String(value))
+    : selectedKeys.includes(value);
+
+  const focused = looseMatch
+    ? String(focusedKey) === String(value)
+    : focusedKey === value;
 
   return (
     <div
       className={clsx(`${prefixCls}-option`, {
         [`${prefixCls}-option-selected`]: selected,
-        [`${prefixCls}-option-focused`]: focusedKey === value,
+        [`${prefixCls}-option-focused`]: focused,
         [`${prefixCls}-option-disabled`]: disabled,
       })}
       aria-label="option"