@prairielearn/ui 1.5.0 → 1.7.0

package/src/components/TanstackTable.tsx

@@ -3,10 +3,11 @@ import { useVirtualizer } from '@tanstack/react-virtual';
 import type { Cell, Header, Row, Table } from '@tanstack/table-core';
 import clsx from 'clsx';
 import type { ComponentChildren } from 'preact';
-import { useEffect, useMemo, useRef } from 'preact/hooks';
+import { useEffect, useMemo, useRef, useState } from 'preact/hooks';
 import type { JSX } from 'preact/jsx-runtime';
 import OverlayTrigger from 'react-bootstrap/OverlayTrigger';
 import Tooltip from 'react-bootstrap/Tooltip';
+import { useDebouncedCallback } from 'use-debounce';
 
 import type { ComponentProps } from '@prairielearn/preact-cjs';
 import { run } from '@prairielearn/run';
@@ -472,12 +473,11 @@ export function TanstackTable<RowDataModel>({
  * @param params.singularLabel - The singular label for a single row in the table, e.g. "student"
  * @param params.pluralLabel - The plural label for multiple rows in the table, e.g. "students"
  * @param params.headerButtons - The buttons to display in the header
- * @param params.columnManagerButtons - The buttons to display next to the column manager (View button)
- * @param params.columnManagerTopContent - Optional content to display at the top of the column manager (View) dropdown menu
- * @param params.globalFilter - State management for the global filter
- * @param params.globalFilter.value
- * @param params.globalFilter.setValue
- * @param params.globalFilter.placeholder
+ * @param params.columnManager - Optional configuration for the column manager. See {@link ColumnManager} for more details.
+ * @param params.columnManager.buttons - The buttons to display next to the column manager (View button)
+ * @param params.columnManager.topContent - Optional content to display at the top of the column manager (View) dropdown menu
+ * @param params.globalFilter - Configuration for the global filter
+ * @param params.globalFilter.placeholder - Placeholder text for the search input
  * @param params.tableOptions - Specific options for the table. See {@link TanstackTableProps} for more details.
  * @param params.downloadButtonOptions - Specific options for the download button. See {@link TanstackTableDownloadButtonProps} for more details.
  */
@@ -487,8 +487,7 @@ export function TanstackTableCard<RowDataModel>({
   singularLabel,
   pluralLabel,
   headerButtons,
-  columnManagerButtons,
-  columnManagerTopContent,
+  columnManager,
   globalFilter,
   tableOptions,
   downloadButtonOptions,
@@ -499,22 +498,31 @@ export function TanstackTableCard<RowDataModel>({
   title: string;
   singularLabel: string;
   pluralLabel: string;
-  headerButtons: JSX.Element;
-  columnManagerButtons?: JSX.Element;
-  columnManagerTopContent?: JSX.Element;
+  headerButtons?: JSX.Element;
+  columnManager?: {
+    buttons?: JSX.Element;
+    topContent?: JSX.Element;
+  };
   globalFilter: {
-    value: string;
-    setValue: (value: string) => void;
     placeholder: string;
   };
   tableOptions: Partial<Omit<TanstackTableProps<RowDataModel>, 'table'>>;
   downloadButtonOptions?: Omit<
     TanstackTableDownloadButtonProps<RowDataModel>,
     'table' | 'singularLabel' | 'pluralLabel'
-  >;
+  > & { pluralLabel?: string; singularLabel?: string };
 } & Omit<ComponentProps<'div'>, 'class'>) {
   const searchInputRef = useRef<HTMLInputElement>(null);
 
+  const [inputValue, setInputValue] = useState(
+    () => (table.getState().globalFilter as string) ?? '',
+  );
+
+  // Debounce the filter update
+  const debouncedSetFilter = useDebouncedCallback((value: string) => {
+    table.setGlobalFilter(value);
+  }, 150);
+
   // Focus the search input when Ctrl+F is pressed
   useEffect(() => {
     function onKeyDown(event: KeyboardEvent) {
@@ -559,20 +567,26 @@ export function TanstackTableCard<RowDataModel>({
             class="form-control pl-ui-tanstack-table-search-input pl-ui-tanstack-table-focusable-shadow"
             aria-label={globalFilter.placeholder}
             placeholder={globalFilter.placeholder}
-            value={globalFilter.value}
+            value={inputValue}
             autoComplete="off"
             onInput={(e) => {
               if (!(e.target instanceof HTMLInputElement)) return;
-              globalFilter.setValue(e.target.value);
+              const value = e.target.value;
+              setInputValue(value);
+              debouncedSetFilter(value);
             }}
           />
-          {globalFilter.value && (
+          {inputValue && (
             <OverlayTrigger overlay={<Tooltip>Clear search</Tooltip>}>
               <button
                 type="button"
                 class="btn btn-floating-icon"
                 aria-label="Clear search"
-                onClick={() => globalFilter.setValue('')}
+                onClick={() => {
+                  setInputValue('');
+                  debouncedSetFilter.cancel();
+                  table.setGlobalFilter('');
+                }}
               >
                 <i class="bi bi-x-circle-fill" aria-hidden="true" />
               </button>
@@ -580,8 +594,8 @@ export function TanstackTableCard<RowDataModel>({
           )}
         </div>
         <div class="d-flex flex-wrap flex-row align-items-center gap-2">
-          <ColumnManager table={table} topContent={columnManagerTopContent} />
-          {columnManagerButtons}
+          <ColumnManager table={table} topContent={columnManager?.topContent} />
+          {columnManager?.buttons}
         </div>
         <div class="ms-auto text-muted text-nowrap">
           Showing {displayedCount} of {totalCount} {totalCount === 1 ? singularLabel : pluralLabel}

package/src/components/TanstackTableDownloadButton.tsx

@@ -8,17 +8,19 @@ export interface TanstackTableDownloadButtonProps<RowDataModel> {
   mapRowToData: (row: RowDataModel) => Record<string, string | number | null> | null;
   singularLabel: string;
   pluralLabel: string;
+  hasSelection: boolean;
 }
 /**
  * @param params
- * @param params.singularLabel - The singular label for a single row in the table, e.g. "student"
- * @param params.pluralLabel - The plural label for multiple rows in the table, e.g. "students"
  * @param params.table - The table model
  * @param params.filenameBase - The base filename for the downloads
  * @param params.mapRowToData - A function that maps a row to a record where the
  * keys are the column names, and the values are the cell values. The key order is important,
  * and should match the expected order of the columns in the CSV file. If the function returns null,
  * the row will be skipped.
+ * @param params.singularLabel - The singular label for a single row in the table, e.g. "student"
+ * @param params.pluralLabel - The plural label for multiple rows in the table, e.g. "students"
+ * @param params.hasSelection - Whether the table has selection enabled
  */
 export function TanstackTableDownloadButton<RowDataModel>({
   table,
@@ -26,6 +28,7 @@ export function TanstackTableDownloadButton<RowDataModel>({
   mapRowToData,
   singularLabel,
   pluralLabel,
+  hasSelection,
 }: TanstackTableDownloadButtonProps<RowDataModel>) {
   const allRows = table.getCoreRowModel().rows.map((row) => row.original);
   const allRowsJSON = allRows.map(mapRowToData).filter((row) => row !== null);
@@ -70,7 +73,7 @@ export function TanstackTableDownloadButton<RowDataModel>({
             disabled={allRowsJSON.length === 0}
             onClick={() => downloadJSONAsCSV(allRowsJSON, `${filenameBase}.csv`)}
           >
-            All {pluralLabel} as CSV
+            All {pluralLabel} ({allRowsJSON.length}) as CSV
           </button>
         </li>
         <li role="presentation">
@@ -82,33 +85,39 @@ export function TanstackTableDownloadButton<RowDataModel>({
             disabled={allRowsJSON.length === 0}
             onClick={() => downloadAsJSON(allRowsJSON, `${filenameBase}.json`)}
           >
-            All {pluralLabel} as JSON
-          </button>
-        </li>
-        <li role="presentation">
-          <button
-            class="dropdown-item"
-            type="button"
-            role="menuitem"
-            aria-label={`Download selected ${pluralLabel} as CSV file`}
-            disabled={selectedRowsJSON.length === 0}
-            onClick={() => downloadJSONAsCSV(selectedRowsJSON, `${filenameBase}_selected.csv`)}
-          >
-            Selected {selectedRowsJSON.length === 1 ? singularLabel : pluralLabel} as CSV
-          </button>
-        </li>
-        <li role="presentation">
-          <button
-            class="dropdown-item"
-            type="button"
-            role="menuitem"
-            aria-label={`Download selected ${pluralLabel} as JSON file`}
-            disabled={selectedRowsJSON.length === 0}
-            onClick={() => downloadAsJSON(selectedRowsJSON, `${filenameBase}_selected.json`)}
-          >
-            Selected {selectedRowsJSON.length === 1 ? singularLabel : pluralLabel} as JSON
+            All {pluralLabel} ({allRowsJSON.length}) as JSON
           </button>
         </li>
+        {hasSelection && (
+          <>
+            <li role="presentation">
+              <button
+                class="dropdown-item"
+                type="button"
+                role="menuitem"
+                aria-label={`Download selected ${pluralLabel} as CSV file`}
+                disabled={selectedRowsJSON.length === 0}
+                onClick={() => downloadJSONAsCSV(selectedRowsJSON, `${filenameBase}_selected.csv`)}
+              >
+                Selected {selectedRowsJSON.length === 1 ? singularLabel : pluralLabel} (
+                {selectedRowsJSON.length}) as CSV
+              </button>
+            </li>
+            <li role="presentation">
+              <button
+                class="dropdown-item"
+                type="button"
+                role="menuitem"
+                aria-label={`Download selected ${pluralLabel} as JSON file`}
+                disabled={selectedRowsJSON.length === 0}
+                onClick={() => downloadAsJSON(selectedRowsJSON, `${filenameBase}_selected.json`)}
+              >
+                Selected {selectedRowsJSON.length === 1 ? singularLabel : pluralLabel} (
+                {selectedRowsJSON.length}) as JSON
+              </button>
+            </li>
+          </>
+        )}
         <li role="presentation">
           <button
             class="dropdown-item"
@@ -118,7 +127,8 @@ export function TanstackTableDownloadButton<RowDataModel>({
             disabled={filteredRowsJSON.length === 0}
             onClick={() => downloadJSONAsCSV(filteredRowsJSON, `${filenameBase}_filtered.csv`)}
           >
-            Filtered {filteredRowsJSON.length === 1 ? singularLabel : pluralLabel} as CSV
+            Filtered {filteredRowsJSON.length === 1 ? singularLabel : pluralLabel} (
+            {filteredRowsJSON.length}) as CSV
           </button>
         </li>
         <li role="presentation">
@@ -130,7 +140,8 @@ export function TanstackTableDownloadButton<RowDataModel>({
             disabled={filteredRowsJSON.length === 0}
             onClick={() => downloadAsJSON(filteredRowsJSON, `${filenameBase}_filtered.json`)}
           >
-            Filtered {filteredRowsJSON.length === 1 ? singularLabel : pluralLabel} as JSON
+            Filtered {filteredRowsJSON.length === 1 ? singularLabel : pluralLabel} (
+            {filteredRowsJSON.length}) as JSON
           </button>
         </li>
       </ul>

package/src/components/nuqs.test.ts

@@ -0,0 +1,276 @@
+import type { SortingState } from '@tanstack/table-core';
+import { describe, expect, it } from 'vitest';
+
+import {
+  parseAsColumnPinningState,
+  parseAsColumnVisibilityStateWithColumns,
+  parseAsNumericFilter,
+  parseAsSortingState,
+} from './nuqs.js';
+
+describe('parseAsSortingState', () => {
+  describe('parse', () => {
+    it('parses valid asc', () => {
+      expect(parseAsSortingState.parse('col:asc')).toEqual([{ id: 'col', desc: false }]);
+    });
+    it('parses valid desc', () => {
+      expect(parseAsSortingState.parse('col:desc')).toEqual([{ id: 'col', desc: true }]);
+    });
+    it('parses multiple columns', () => {
+      expect(parseAsSortingState.parse('col1:asc,col2:desc')).toEqual([
+        { id: 'col1', desc: false },
+        { id: 'col2', desc: true },
+      ]);
+    });
+    it('ignores invalid columns in multi-column', () => {
+      expect(parseAsSortingState.parse('col1:asc,invalid,foo:bar,col2:desc')).toEqual([
+        { id: 'col1', desc: false },
+        { id: 'col2', desc: true },
+      ]);
+    });
+    it('returns [] for empty string', () => {
+      expect(parseAsSortingState.parse('')).toEqual([]);
+    });
+    it('returns [] for missing id', () => {
+      expect(parseAsSortingState.parse(':asc')).toEqual([]);
+    });
+    it('returns [] for invalid direction', () => {
+      expect(parseAsSortingState.parse('col:foo')).toEqual([]);
+    });
+    it('returns [] for undefined', () => {
+      expect(parseAsSortingState.parse(undefined as any)).toEqual([]);
+    });
+  });
+
+  describe('serialize', () => {
+    it('serializes asc', () => {
+      const state: SortingState = [{ id: 'col', desc: false }];
+      expect(parseAsSortingState.serialize(state)).toBe('col:asc');
+    });
+    it('serializes desc', () => {
+      const state: SortingState = [{ id: 'col', desc: true }];
+      expect(parseAsSortingState.serialize(state)).toBe('col:desc');
+    });
+    it('serializes multiple columns', () => {
+      const state: SortingState = [
+        { id: 'col1', desc: false },
+        { id: 'col2', desc: true },
+      ];
+      expect(parseAsSortingState.serialize(state)).toBe('col1:asc,col2:desc');
+    });
+    it('serializes empty array as null', () => {
+      expect(parseAsSortingState.serialize([])).toBe(null);
+    });
+    it('serializes missing id as empty string', () => {
+      expect(parseAsSortingState.serialize([{ id: '', desc: false }])).toBe('');
+    });
+  });
+
+  describe('eq', () => {
+    it('returns true for equal states', () => {
+      const a: SortingState = [{ id: 'col', desc: false }];
+      const b: SortingState = [{ id: 'col', desc: false }];
+      expect(parseAsSortingState.eq(a, b)).toBe(true);
+    });
+    it('returns true for equal multi-column states', () => {
+      const a: SortingState = [
+        { id: 'col1', desc: false },
+        { id: 'col2', desc: true },
+      ];
+      const b: SortingState = [
+        { id: 'col1', desc: false },
+        { id: 'col2', desc: true },
+      ];
+      expect(parseAsSortingState.eq(a, b)).toBe(true);
+    });
+    // The order of the sort columns matters for multi-column sorting.
+    it('returns false for different order in multi-column', () => {
+      const a: SortingState = [
+        { id: 'col1', desc: false },
+        { id: 'col2', desc: true },
+      ];
+      const b: SortingState = [
+        { id: 'col2', desc: true },
+        { id: 'col1', desc: false },
+      ];
+      expect(parseAsSortingState.eq(a, b)).toBe(false);
+    });
+    it('returns false for different ids', () => {
+      const a: SortingState = [{ id: 'col1', desc: false }];
+      const b: SortingState = [{ id: 'col2', desc: false }];
+      expect(parseAsSortingState.eq(a, b)).toBe(false);
+    });
+    it('returns false for different desc', () => {
+      const a: SortingState = [{ id: 'col', desc: false }];
+      const b: SortingState = [{ id: 'col', desc: true }];
+      expect(parseAsSortingState.eq(a, b)).toBe(false);
+    });
+    it('returns true for both empty', () => {
+      expect(parseAsSortingState.eq([], [])).toBe(true);
+    });
+    it('returns false for one empty, one not', () => {
+      expect(parseAsSortingState.eq([], [{ id: 'col', desc: false }])).toBe(false);
+    });
+  });
+});
+
+describe('parseAsColumnVisibilityStateWithColumns', () => {
+  const allColumns = ['a', 'b', 'c'];
+  const parser = parseAsColumnVisibilityStateWithColumns(allColumns);
+
+  it('parses empty string as all columns visible', () => {
+    expect(parser.parse('')).toEqual({ a: true, b: true, c: true });
+  });
+
+  it('parses comma-separated columns as only those visible', () => {
+    expect(parser.parse('a,b')).toEqual({ a: true, b: true, c: false });
+    expect(parser.parse('b')).toEqual({ a: false, b: true, c: false });
+  });
+
+  it('serializes partial visibility as comma-separated columns', () => {
+    expect(parser.serialize({ a: true, b: false, c: true })).toBe('a,c');
+    expect(parser.serialize({ a: false, b: true, c: false })).toBe('b');
+  });
+
+  it('eq returns true for equal visibility', () => {
+    expect(parser.eq({ a: true, b: false, c: true }, { a: true, b: false, c: true })).toBe(true);
+  });
+
+  it('eq returns false for different visibility', () => {
+    expect(parser.eq({ a: true, b: false, c: true }, { a: false, b: false, c: true })).toBe(false);
+  });
+});
+
+describe('parseAsColumnPinningState', () => {
+  const parser = parseAsColumnPinningState;
+
+  it('parses empty string as no pinned columns', () => {
+    expect(parser.parse('')).toEqual({ left: [], right: [] });
+  });
+
+  it('parses comma-separated columns as left-pinned', () => {
+    expect(parser.parse('a,b')).toEqual({ left: ['a', 'b'], right: [] });
+    expect(parser.parse('c')).toEqual({ left: ['c'], right: [] });
+  });
+
+  it('serializes left-pinned columns as comma-separated string', () => {
+    expect(parser.serialize({ left: ['a', 'b'], right: [] })).toBe('a,b');
+    expect(parser.serialize({ left: [], right: [] })).toBe('');
+  });
+
+  it('eq returns true for equal pinning', () => {
+    expect(parser.eq({ left: ['a', 'b'], right: [] }, { left: ['a', 'b'], right: [] })).toBe(true);
+  });
+
+  it('eq returns false for different pinning', () => {
+    expect(parser.eq({ left: ['a', 'b'], right: [] }, { left: ['b', 'a'], right: [] })).toBe(false);
+    expect(parser.eq({ left: ['a'], right: [] }, { left: ['a', 'b'], right: [] })).toBe(false);
+  });
+});
+
+describe('parseAsNumericFilter', () => {
+  describe('parse', () => {
+    it('parses gte format', () => {
+      expect(parseAsNumericFilter.parse('gte_5')).toEqual({ filterValue: '>=5', emptyOnly: false });
+    });
+    it('parses lte format', () => {
+      expect(parseAsNumericFilter.parse('lte_10')).toEqual({
+        filterValue: '<=10',
+        emptyOnly: false,
+      });
+    });
+    it('parses gt format', () => {
+      expect(parseAsNumericFilter.parse('gt_3')).toEqual({ filterValue: '>3', emptyOnly: false });
+    });
+    it('parses lt format', () => {
+      expect(parseAsNumericFilter.parse('lt_7')).toEqual({ filterValue: '<7', emptyOnly: false });
+    });
+    it('parses eq format', () => {
+      expect(parseAsNumericFilter.parse('eq_5')).toEqual({ filterValue: '=5', emptyOnly: false });
+    });
+    it('parses empty keyword', () => {
+      expect(parseAsNumericFilter.parse('empty')).toEqual({ filterValue: '', emptyOnly: true });
+    });
+    it('returns default for invalid format', () => {
+      expect(parseAsNumericFilter.parse('invalid')).toEqual({ filterValue: '', emptyOnly: false });
+    });
+    it('returns default for empty string', () => {
+      expect(parseAsNumericFilter.parse('')).toEqual({ filterValue: '', emptyOnly: false });
+    });
+    it('returns default for undefined', () => {
+      expect(parseAsNumericFilter.parse(undefined as any)).toEqual({
+        filterValue: '',
+        emptyOnly: false,
+      });
+    });
+    it('parses decimal values', () => {
+      expect(parseAsNumericFilter.parse('gte_3.14')).toEqual({
+        filterValue: '>=3.14',
+        emptyOnly: false,
+      });
+    });
+    it('parses negative values', () => {
+      expect(parseAsNumericFilter.parse('lt_-5')).toEqual({ filterValue: '<-5', emptyOnly: false });
+    });
+  });
+
+  describe('serialize', () => {
+    it('serializes >= format', () => {
+      expect(parseAsNumericFilter.serialize({ filterValue: '>=5', emptyOnly: false })).toBe(
+        'gte_5',
+      );
+    });
+    it('serializes <= format', () => {
+      expect(parseAsNumericFilter.serialize({ filterValue: '<=10', emptyOnly: false })).toBe(
+        'lte_10',
+      );
+    });
+    it('serializes > format', () => {
+      expect(parseAsNumericFilter.serialize({ filterValue: '>3', emptyOnly: false })).toBe('gt_3');
+    });
+    it('serializes < format', () => {
+      expect(parseAsNumericFilter.serialize({ filterValue: '<7', emptyOnly: false })).toBe('lt_7');
+    });
+    it('serializes = format', () => {
+      expect(parseAsNumericFilter.serialize({ filterValue: '=5', emptyOnly: false })).toBe('eq_5');
+    });
+    it('serializes emptyOnly as empty', () => {
+      expect(parseAsNumericFilter.serialize({ filterValue: '', emptyOnly: true })).toBe('empty');
+    });
+    it('serializes empty filterValue as empty', () => {
+      expect(parseAsNumericFilter.serialize({ filterValue: '', emptyOnly: false })).toBe('empty');
+    });
+    it('returns null for invalid filterValue', () => {
+      expect(parseAsNumericFilter.serialize({ filterValue: 'invalid', emptyOnly: false })).toBe(
+        null,
+      );
+    });
+  });
+
+  describe('eq', () => {
+    it('returns true for equal values', () => {
+      expect(
+        parseAsNumericFilter.eq(
+          { filterValue: '>=5', emptyOnly: false },
+          { filterValue: '>=5', emptyOnly: false },
+        ),
+      ).toBe(true);
+    });
+    it('returns false for different filterValue', () => {
+      expect(
+        parseAsNumericFilter.eq(
+          { filterValue: '>=5', emptyOnly: false },
+          { filterValue: '>=10', emptyOnly: false },
+        ),
+      ).toBe(false);
+    });
+    it('returns false for different emptyOnly', () => {
+      expect(
+        parseAsNumericFilter.eq(
+          { filterValue: '', emptyOnly: true },
+          { filterValue: '', emptyOnly: false },
+        ),
+      ).toBe(false);
+    });
+  });
+});