@rebasepro/ui 0.14.0 → 0.14.1-canary.g7e666eb

package/dist/views/CollectionView/CollectionViewTypes.d.ts

@@ -1,4 +1,5 @@
 import React from "react";
+import type { VirtualTableSortKey } from "../../components/VirtualTable/VirtualTableProps";
 /** Supported view modes */
 export type CollectionViewMode = "table" | "cards" | "kanban" | "list";
 /** Supported collection sizes */
@@ -57,8 +58,9 @@ export interface CollectionDataController<T = Record<string, unknown>> {
     error?: Error;
     filterValues?: Record<string, [string, unknown]>;
     setFilterValues?: (values: Record<string, [string, unknown]> | undefined) => void;
-    sortBy?: [string, "asc" | "desc"];
-    setSortBy?: (sort?: [string, "asc" | "desc"]) => void;
+    /** The sort keys in order of significance; the second breaks ties on the first. */
+    sortBy?: VirtualTableSortKey[];
+    setSortBy?: (sort?: VirtualTableSortKey[]) => void;
     searchString?: string;
     setSearchString?: (search?: string) => void;
     clearFilter?: () => void;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rebasepro/ui",
   "type": "module",
-  "version": "0.14.0",
+  "version": "0.14.1-canary.g7e666eb",
   "description": "Rebase design system — React components and design tokens built on Radix UI, Tailwind CSS and lucide-react",
   "funding": {
     "url": "https://github.com/sponsors/rebaseco"
@@ -116,7 +116,7 @@
     "build": "rm -rf dist || true && vite build && cp dist/src/index.css dist/src/theme.css dist/ && tsc --emitDeclarationOnly -p tsconfig.prod.json && node ../../scripts/assert-build-output.mjs",
     "test:lint": "eslint \"src/**\" --quiet",
     "test": "jest --passWithNoTests",
-    "clean": "rm -rf dist && find ./src -name '*.js' -type f | xargs rm -f",
+    "clean": "rm -rf dist && find ./src \\( -name '*.js' -o -name '*.d.ts' \\) -type f | xargs rm -f",
     "generateIcons": "bun --esm src/scripts/generateIcons.ts"
   }
 }

package/src/components/VirtualTable/VirtualTable.tsx

@@ -13,6 +13,7 @@ import {
     VirtualTableColumn,
     VirtualTableFilterValues,
     VirtualTableProps,
+    VirtualTableSortKey,
     VirtualTableWhereFilterOp
 } from "./VirtualTableProps";
 
@@ -142,8 +143,18 @@ const VirtualTableInner = React.memo<VirtualTableProps<Record<string, unknown>>>
         extraData
     }: VirtualTableProps<T>) {
 
-        const sortByProperty: string | undefined = sortBy ? sortBy[0] : undefined;
-        const currentSort: "asc" | "desc" | undefined = sortBy ? sortBy[1] : undefined;
+        // Where each sorted column sits in the order, so a header can show both
+        // which way it runs and how much it counts: `roles ↑1, created_at ↓2`
+        // reads as "by role, newest first within each role". Without the rank a
+        // multi-key sort shows two arrows and no way to tell which one wins.
+        const sortIndex = useMemo(() => {
+            const index = new Map<string, { direction: "asc" | "desc"; position: number }>();
+            (sortBy ?? []).forEach(([key, direction], position) => {
+                if (!index.has(key)) index.set(key, { direction,
+position });
+            });
+            return index;
+        }, [sortBy]);
 
         const [columns, setColumns] = useState(columnsProp);
 
@@ -243,16 +254,37 @@ const VirtualTableInner = React.memo<VirtualTableProps<Record<string, unknown>>>
             }
         }, []);
 
-        const onColumnSort = useCallback((key: string) => {
-
-            const isDesc = sortByProperty === key && currentSort === "desc";
-            const isAsc = sortByProperty === key && currentSort === "asc";
-            const newSort = isAsc ? "desc" : (isDesc ? undefined : "asc");
-            const newSortProperty: string | undefined = isDesc ? undefined : key;
+        /**
+         * Click a header to sort by that column: ascending, descending, then
+         * off. Shift-click to keep the sort you already have and add this
+         * column under it — the same idiom spreadsheets use, and the only way
+         * to build "by role, newest first" out of two clicks.
+         *
+         * Shift cycles the column it lands on through the same three states, so
+         * a key added by mistake is removed by shift-clicking it twice more,
+         * without disturbing the keys around it.
+         */
+        const onColumnSort = useCallback((key: string, additive = false) => {
+
+            const current = sortIndex.get(key);
+            const next: "asc" | "desc" | undefined = current === undefined
+                ? "asc"
+                : current.direction === "asc" ? "desc" : undefined;
+
+            const existing = sortBy ?? [];
+            let newSortBy: VirtualTableSortKey[] | undefined;
+            if (!additive) {
+                newSortBy = next ? [[key, next]] : undefined;
+            } else if (next === undefined) {
+                newSortBy = existing.filter(([existingKey]) => existingKey !== key);
+            } else if (current === undefined) {
+                newSortBy = [...existing, [key, next]];
+            } else {
+                newSortBy = existing.map((entry) => entry[0] === key ? [key, next] as VirtualTableSortKey : entry);
+            }
+            if (newSortBy?.length === 0) newSortBy = undefined;
 
             const filter = filterRef.current;
-
-            const newSortBy: [string, "asc" | "desc"] | undefined = newSort && newSortProperty ? [newSortProperty, newSort] : undefined;
             if (filter) {
                 if (checkFilterCombination && !checkFilterCombination(filter, newSortBy)) {
                     if (onFilterUpdate)
@@ -269,7 +301,7 @@ const VirtualTableInner = React.memo<VirtualTableProps<Record<string, unknown>>>
             }
 
             scrollToTop();
-        }, [checkFilterCombination, currentSort, onFilterUpdate, onResetPagination, onSortByUpdate, scrollToTop, sortByProperty]);
+        }, [checkFilterCombination, onFilterUpdate, onResetPagination, onSortByUpdate, scrollToTop, sortBy, sortIndex]);
 
         const maxScroll = Math.max((data?.length ?? 0) * rowHeight - bounds.height, 0);
 
@@ -311,14 +343,13 @@ const VirtualTableInner = React.memo<VirtualTableProps<Record<string, unknown>>>
             } else {
                 newFilterValue[column.key] = filterForProperty;
             }
-            const newSortBy: [string, "asc" | "desc"] | undefined = sortByProperty && currentSort ? [sortByProperty, currentSort] : undefined;
-            const isNewFilterCombinationValid = !checkFilterCombination || checkFilterCombination(newFilterValue, newSortBy);
+            const isNewFilterCombinationValid = !checkFilterCombination || checkFilterCombination(newFilterValue, sortBy);
             if (!isNewFilterCombinationValid) {
                 newFilterValue = filterForProperty ? { [column.key]: filterForProperty } as VirtualTableFilterValues<Extract<keyof T, string>> : {};
             }
 
             if (onFilterUpdate) onFilterUpdate(newFilterValue);
-        }, [checkFilterCombination, currentSort, onFilterUpdate, sortByProperty]);
+        }, [checkFilterCombination, onFilterUpdate, sortBy]);
 
         const empty = !loading && (data?.length ?? 0) === 0;
         const customView = (error && (data?.length ?? 0) === 0)
@@ -349,7 +380,6 @@ const VirtualTableInner = React.memo<VirtualTableProps<Record<string, unknown>>>
             headerHeight: headerHeight,
             cellRenderer,
             columns,
-            currentSort,
             onRowClick,
             customView,
             onColumnResize: onColumnResizeInternal,
@@ -357,7 +387,7 @@ const VirtualTableInner = React.memo<VirtualTableProps<Record<string, unknown>>>
             filter: filterRef.current,
             onColumnSort,
             onFilterUpdate: onFilterUpdateInternal,
-            sortByProperty,
+            sortIndex,
             hoverRow: hoverRow ?? false,
             createFilterField,
             rowClassName,
@@ -369,7 +399,7 @@ const VirtualTableInner = React.memo<VirtualTableProps<Record<string, unknown>>>
             } : undefined,
             draggingColumnId,
             extraData
-        }), [data, rowHeight, cellRenderer, columns, currentSort, onRowClick, customView, onColumnResizeInternal, onColumnResizeEndInternal, filterInput, onColumnSort, onFilterUpdateInternal, sortByProperty, hoverRow, createFilterField, rowClassName, endAdornment, AddColumnComponent, onColumnsOrderChange, draggingColumnId, extraData]);
+        }), [data, rowHeight, cellRenderer, columns, onRowClick, customView, onColumnResizeInternal, onColumnResizeEndInternal, filterInput, onColumnSort, onFilterUpdateInternal, sortIndex, hoverRow, createFilterField, rowClassName, endAdornment, AddColumnComponent, onColumnsOrderChange, draggingColumnId, extraData]);
 
         // Get sortable column keys (excluding frozen columns)
         const sortableColumnKeys = columns

package/src/components/VirtualTable/VirtualTableHeader.tsx

@@ -36,9 +36,14 @@ type VirtualTableHeaderProps<M extends Record<string, unknown>> = {
     columnIndex: number;
     isResizingIndex: number;
     column: VirtualTableColumn<unknown>;
-    onColumnSort: (key: Extract<keyof M, string>) => void;
+    onColumnSort: (key: Extract<keyof M, string>, additive?: boolean) => void;
     filter?: [VirtualTableWhereFilterOp, unknown];
     sort: VirtualTableSort;
+    /**
+     * This column's zero-based rank in a multi-key sort, or `undefined` when
+     * only one column is sorted and a rank would say nothing.
+     */
+    sortPosition?: number;
     onFilterUpdate: (column: VirtualTableColumn, filterForProperty?: [VirtualTableWhereFilterOp, unknown]) => void;
     onClickResizeColumn?: (columnIndex: number, column: VirtualTableColumn) => void;
     createFilterField?: (props: FilterFormFieldProps<unknown>) => React.ReactNode;
@@ -47,12 +52,27 @@ type VirtualTableHeaderProps<M extends Record<string, unknown>> = {
     isDraggable?: boolean;
 };
 
+/**
+ * What the next click on this column's sort control will do, spelled out for
+ * the tooltip and for screen readers. An unlabelled arrow that means three
+ * different things depending on the state it is in is a control you have to
+ * click to learn.
+ */
+function sortActionTitle(sort: VirtualTableSort, sortPosition?: number): string {
+    const rank = sortPosition !== undefined ? ` (sort key ${sortPosition + 1})` : "";
+    const addKey = " — shift-click to add it under the current sort instead";
+    if (sort === "asc") return `Sorted ascending${rank}. Click to sort descending.${addKey}`;
+    if (sort === "desc") return `Sorted descending${rank}. Click to remove this sort.${addKey}`;
+    return `Click to sort ascending.${addKey}`;
+}
+
 export const VirtualTableHeader = React.memo<VirtualTableHeaderProps<Record<string, unknown>>>(
     function VirtualTableHeader<M extends Record<string, unknown>>({
         resizeHandleRef,
         columnIndex,
         isResizingIndex,
         sort,
+        sortPosition,
         onColumnSort,
         onFilterUpdate,
         filter,
@@ -141,14 +161,23 @@ export const VirtualTableHeader = React.memo<VirtualTableHeaderProps<Record<stri
                             <AdditionalHeaderWidget onHover={onHover || openFilter}/>}
 
                         {column.sortable && (sort || hovered || openFilter) &&
-                            <div className="flex-shrink-0">
+                            <div className="flex-shrink-0 flex items-center">
                                 <Badge color="secondary"
                                     invisible={!sort}>
                                     <IconButton
                                         size={"small"}
                                         className={onHover || openFilter ? "bg-white dark:bg-surface-900" : undefined}
-                                        onClick={() => {
-                                            onColumnSort(column.key as Extract<keyof M, string>);
+                                        // Shift keeps the sort already in place
+                                        // and adds this column beneath it, which
+                                        // is how a two-key order is built from
+                                        // header clicks. Plain click still
+                                        // replaces the whole sort, so the common
+                                        // case takes no modifier and nothing a
+                                        // user knew before stops working.
+                                        title={sortActionTitle(sort, sortPosition)}
+                                        aria-label={sortActionTitle(sort, sortPosition)}
+                                        onClick={(event: React.MouseEvent) => {
+                                            onColumnSort(column.key as Extract<keyof M, string>, event.shiftKey);
                                         }}
                                     >
                                         {!sort &&
@@ -159,6 +188,18 @@ export const VirtualTableHeader = React.memo<VirtualTableHeaderProps<Record<stri
                                             <ArrowUpIcon size={14} className="flex-shrink-0 rotate-180" />}
                                     </IconButton>
                                 </Badge>
+                                {/* The rank, shown only once there is more than
+                                    one key: two arrows with no numbers beside
+                                    them say a table is sorted by both columns
+                                    and nothing about which one decides. */}
+                                {sort && sortPosition !== undefined && (
+                                    <span
+                                        className="flex-shrink-0 -ml-0.5 mr-0.5 text-[10px] font-bold leading-none tabular-nums text-text-secondary dark:text-text-secondary-dark"
+                                        aria-hidden={true}
+                                    >
+                                        {sortPosition + 1}
+                                    </span>
+                                )}
                             </div>
                         }
                     </>

package/src/components/VirtualTable/VirtualTableHeaderRow.tsx

@@ -16,8 +16,8 @@ const SortableColumnHeader = ({
     isResizing,
     onFilterUpdate,
     filter,
-    sortByProperty,
-    currentSort,
+    sortIndex,
+    sortCount,
     onColumnSort,
     onClickResizeColumn,
     createFilterField,
@@ -30,9 +30,9 @@ const SortableColumnHeader = ({
     isResizing: number;
     onFilterUpdate: (column: VirtualTableColumn, filterForProperty?: [VirtualTableWhereFilterOp, unknown]) => void;
     filter: [VirtualTableWhereFilterOp, unknown] | undefined;
-    sortByProperty: string | undefined;
-    currentSort: "asc" | "desc" | undefined;
-    onColumnSort: (key: string) => void;
+    sortIndex: Map<string, { direction: "asc" | "desc"; position: number }>;
+    sortCount: number;
+    onColumnSort: (key: string, additive?: boolean) => void;
     onClickResizeColumn: (index: number) => void;
     createFilterField: ((props: import("./VirtualTableHeader").FilterFormFieldProps<unknown>) => React.ReactNode) | undefined;
     isDragging: boolean;
@@ -96,7 +96,8 @@ const SortableColumnHeader = ({
                 isResizingIndex={isResizing}
                 onFilterUpdate={onFilterUpdate}
                 filter={filter}
-                sort={sortByProperty === column.key ? currentSort : undefined}
+                sort={sortIndex.get(column.key)?.direction}
+                sortPosition={sortCount > 1 ? sortIndex.get(column.key)?.position : undefined}
                 onColumnSort={onColumnSort}
                 onClickResizeColumn={onClickResizeColumn}
                 column={column}
@@ -110,10 +111,9 @@ const SortableColumnHeader = ({
 
 export const VirtualTableHeaderRow = ({
     columns,
-    currentSort,
+    sortIndex,
     onColumnSort,
     onFilterUpdate,
-    sortByProperty,
     filter,
     onColumnResize,
     onColumnResizeEnd,
@@ -230,8 +230,8 @@ export const VirtualTableHeaderRow = ({
                                 isResizing={isResizing}
                                 onFilterUpdate={onFilterUpdate}
                                 filter={filterForThisProperty}
-                                sortByProperty={sortByProperty}
-                                currentSort={currentSort}
+                                sortIndex={sortIndex}
+                                sortCount={sortIndex.size}
                                 onColumnSort={onColumnSort}
                                 onClickResizeColumn={onClickResizeColumn}
                                 createFilterField={createFilterField}

package/src/components/VirtualTable/VirtualTableProps.tsx

@@ -3,6 +3,9 @@
 import React from "react";
 import type { FilterFormFieldProps } from "./VirtualTableHeader";
 
+/** One sort key: the column, and which way it runs. */
+export type VirtualTableSortKey = [string, "asc" | "desc"];
+
 export type OnRowClickParams<T extends Record<string, unknown>> = {
     rowData: T;
     rowIndex: number;
@@ -39,7 +42,7 @@ export interface VirtualTableProps<T extends Record<string, unknown>> {
      * @param sortBy
      */
     checkFilterCombination?: (filterValues: VirtualTableFilterValues<Extract<keyof T, string>>,
-        sortBy?: [string, "asc" | "desc"]) => boolean;
+        sortBy?: VirtualTableSortKey[]) => boolean;
 
     /**
      * A callback function when scrolling the table to near the end
@@ -96,15 +99,16 @@ export interface VirtualTableProps<T extends Record<string, unknown>> {
     }) => void;
 
     /**
-     * Default sort applied to this collection
+     * Sort applied to this collection: the keys in order of significance, the
+     * second breaking ties on the first.
      */
-    sortBy?: [string, "asc" | "desc"];
+    sortBy?: VirtualTableSortKey[];
 
     /**
      * Callback used when sorting is updated
      * @param sortBy
      */
-    onSortByUpdate?: (sortBy?: [string, "asc" | "desc"]) => void;
+    onSortByUpdate?: (sortBy?: VirtualTableSortKey[]) => void;
 
     /**
      * If there is an error loading data you can pass it here, so it gets

package/src/components/VirtualTable/types.tsx

@@ -27,14 +27,14 @@ export type VirtualTableContextProps<T> = {
     headerHeight?: number,
     columns: VirtualTableColumn[];
     cellRenderer: React.ComponentType<CellRendererParams<T>>;
-    currentSort: "asc" | "desc" | undefined;
+    /** Each sorted column's direction and its rank in the sort, keyed by column. */
+    sortIndex: Map<string, { direction: "asc" | "desc"; position: number }>;
     filter?: VirtualTableFilterValues<string>;
     onRowClick?: (props: OnRowClickParams<Record<string, unknown>>) => void;
-    onColumnSort: (key: string) => void;
+    onColumnSort: (key: string, additive?: boolean) => void;
     onColumnResize: (params: OnVirtualTableColumnResizeParams) => void;
     onColumnResizeEnd: (params: OnVirtualTableColumnResizeParams) => void;
     onFilterUpdate: (column: VirtualTableColumn, filterForProperty?: [VirtualTableWhereFilterOp, unknown]) => void;
-    sortByProperty?: string;
     customView?: React.ReactNode,
     hoverRow: boolean;
     createFilterField?: (props: FilterFormFieldProps<unknown>) => React.ReactNode;

package/src/views/CollectionView/CollectionViewTypes.ts

@@ -1,4 +1,5 @@
 import React from "react";
+import type { VirtualTableSortKey } from "../../components/VirtualTable/VirtualTableProps";
 
 /** Supported view modes */
 export type CollectionViewMode = "table" | "cards" | "kanban" | "list";
@@ -80,8 +81,9 @@ export interface CollectionDataController<T = Record<string, unknown>> {
     filterValues?: Record<string, [string, unknown]>;
     setFilterValues?: (values: Record<string, [string, unknown]> | undefined) => void;
 
-    sortBy?: [string, "asc" | "desc"];
-    setSortBy?: (sort?: [string, "asc" | "desc"]) => void;
+    /** The sort keys in order of significance; the second breaks ties on the first. */
+    sortBy?: VirtualTableSortKey[];
+    setSortBy?: (sort?: VirtualTableSortKey[]) => void;
 
     searchString?: string;
     setSearchString?: (search?: string) => void;