@prairielearn/ui 1.2.0 → 1.4.0

package/src/components/TanstackTableDownloadButton.tsx

@@ -6,11 +6,13 @@ export interface TanstackTableDownloadButtonProps<RowDataModel> {
   table: Table<RowDataModel>;
   filenameBase: string;
   mapRowToData: (row: RowDataModel) => Record<string, string | number | null> | null;
+  singularLabel: string;
   pluralLabel: string;
 }
 /**
  * @param params
- * @param params.pluralLabel - What you are downloading, e.g. "students"
+ * @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
@@ -22,6 +24,7 @@ export function TanstackTableDownloadButton<RowDataModel>({
   table,
   filenameBase,
   mapRowToData,
+  singularLabel,
   pluralLabel,
 }: TanstackTableDownloadButtonProps<RowDataModel>) {
   const allRows = table.getCoreRowModel().rows.map((row) => row.original);
@@ -91,7 +94,7 @@ export function TanstackTableDownloadButton<RowDataModel>({
             disabled={selectedRowsJSON.length === 0}
             onClick={() => downloadJSONAsCSV(selectedRowsJSON, `${filenameBase}_selected.csv`)}
           >
-            Selected {pluralLabel} as CSV
+            Selected {selectedRowsJSON.length === 1 ? singularLabel : pluralLabel} as CSV
           </button>
         </li>
         <li role="presentation">
@@ -103,7 +106,7 @@ export function TanstackTableDownloadButton<RowDataModel>({
             disabled={selectedRowsJSON.length === 0}
             onClick={() => downloadAsJSON(selectedRowsJSON, `${filenameBase}_selected.json`)}
           >
-            Selected {pluralLabel} as JSON
+            Selected {selectedRowsJSON.length === 1 ? singularLabel : pluralLabel} as JSON
           </button>
         </li>
         <li role="presentation">
@@ -115,7 +118,7 @@ export function TanstackTableDownloadButton<RowDataModel>({
             disabled={filteredRowsJSON.length === 0}
             onClick={() => downloadJSONAsCSV(filteredRowsJSON, `${filenameBase}_filtered.csv`)}
           >
-            Filtered {pluralLabel} as CSV
+            Filtered {filteredRowsJSON.length === 1 ? singularLabel : pluralLabel} as CSV
           </button>
         </li>
         <li role="presentation">
@@ -127,7 +130,7 @@ export function TanstackTableDownloadButton<RowDataModel>({
             disabled={filteredRowsJSON.length === 0}
             onClick={() => downloadAsJSON(filteredRowsJSON, `${filenameBase}_filtered.json`)}
           >
-            Filtered {pluralLabel} as JSON
+            Filtered {filteredRowsJSON.length === 1 ? singularLabel : pluralLabel} as JSON
           </button>
         </li>
       </ul>

package/src/components/TanstackTableHeaderCell.tsx

@@ -0,0 +1,207 @@
+import { flexRender } from '@tanstack/react-table';
+import type { Header, SortDirection, Table } from '@tanstack/table-core';
+import clsx from 'clsx';
+import type { JSX } from 'preact/jsx-runtime';
+
+function SortIcon({ sortMethod }: { sortMethod: false | SortDirection }) {
+  if (sortMethod === 'asc') {
+    return <i class="bi bi-sort-up-alt" aria-hidden="true" />;
+  } else if (sortMethod === 'desc') {
+    return <i class="bi bi-sort-down" aria-hidden="true" />;
+  } else {
+    return <i class="bi bi-arrow-down-up opacity-75 text-muted" aria-hidden="true" />;
+  }
+}
+
+function ResizeHandle<RowDataModel>({
+  header,
+  setColumnSizing,
+  onResizeEnd,
+}: {
+  header: Header<RowDataModel, unknown>;
+  setColumnSizing: Table<RowDataModel>['setColumnSizing'];
+  onResizeEnd?: () => void;
+}) {
+  const minSize = header.column.columnDef.minSize ?? 0;
+  const maxSize = header.column.columnDef.maxSize ?? 0;
+  const handleKeyDown = (e: KeyboardEvent) => {
+    if (e.key === 'ArrowLeft' || e.key === 'ArrowRight') {
+      e.preventDefault();
+      const currentSize = header.getSize();
+      const increment = e.shiftKey ? 20 : 5; // Larger increment with Shift key
+      const newSize =
+        e.key === 'ArrowLeft'
+          ? Math.max(minSize, currentSize - increment)
+          : Math.min(maxSize, currentSize + increment);
+
+      setColumnSizing((prevSizing) => ({
+        ...prevSizing,
+        [header.column.id]: newSize,
+      }));
+    } else if (e.key === 'Home') {
+      e.preventDefault();
+      header.column.resetSize();
+    }
+  };
+
+  const columnName =
+    typeof header.column.columnDef.header === 'string'
+      ? header.column.columnDef.header
+      : header.column.id;
+
+  return (
+    <div class="py-1 h-100" style={{ position: 'absolute', right: 0, top: 0, width: '4px' }}>
+      {/* separator role is focusable, so these jsx-a11y-x rules are false positives.
+        https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/separator_role#focusable_separator
+      */}
+      {/* eslint-disable-next-line jsx-a11y-x/no-noninteractive-element-interactions */}
+      <div
+        role="separator"
+        aria-label={`Resize '${columnName}' column`}
+        aria-valuetext={`${header.getSize()}px`}
+        aria-orientation="vertical"
+        aria-valuemin={minSize}
+        aria-valuemax={maxSize}
+        aria-valuenow={header.getSize()}
+        // eslint-disable-next-line jsx-a11y-x/no-noninteractive-tabindex
+        tabIndex={0}
+        class="h-100"
+        style={{
+          background: header.column.getIsResizing() ? 'var(--bs-primary)' : 'var(--bs-gray-400)',
+          cursor: 'col-resize',
+          transition: 'background-color 0.2s',
+        }}
+        onMouseDown={header.getResizeHandler()}
+        onMouseUp={onResizeEnd}
+        onTouchStart={header.getResizeHandler()}
+        onTouchEnd={onResizeEnd}
+        onKeyDown={handleKeyDown}
+      />
+    </div>
+  );
+}
+
+/**
+ * Helper function to get aria-sort value
+ */
+function getAriaSort(sortDirection: false | SortDirection) {
+  switch (sortDirection) {
+    case 'asc':
+      return 'ascending';
+    case 'desc':
+      return 'descending';
+    default:
+      return 'none';
+  }
+}
+
+export function TanstackTableHeaderCell<RowDataModel>({
+  header,
+  filters,
+  table,
+  handleResizeEnd,
+  isPinned,
+  measurementMode = false,
+}: {
+  header: Header<RowDataModel, unknown>;
+  filters: Record<string, (props: { header: Header<RowDataModel, unknown> }) => JSX.Element>;
+  table: Table<RowDataModel>;
+  handleResizeEnd?: () => void;
+  isPinned: 'left' | false;
+  measurementMode?: boolean;
+}) {
+  const sortDirection = header.column.getIsSorted();
+  const canSort = header.column.getCanSort();
+  const canFilter = header.column.getCanFilter();
+  const columnName =
+    header.column.columnDef.meta?.label ??
+    (typeof header.column.columnDef.header === 'string'
+      ? header.column.columnDef.header
+      : header.column.id);
+
+  // In measurement mode, we don't want to set the size of the header from tanstack.
+  const headerSize = measurementMode ? undefined : header.getSize();
+  const style: JSX.CSSProperties = {
+    display: 'flex',
+    width: headerSize,
+    minWidth: 0,
+    maxWidth: headerSize,
+    flexShrink: 0,
+    position: isPinned === 'left' ? 'sticky' : 'relative',
+    top: 0,
+    zIndex: isPinned === 'left' ? 2 : 1,
+    left: isPinned === 'left' ? header.getStart() : undefined,
+    boxShadow:
+      'inset 0 calc(-1 * var(--bs-border-width)) 0 0 rgba(0, 0, 0, 1), inset 0 var(--bs-border-width) 0 0 var(--bs-border-color)',
+  };
+
+  const isNormalColumn = canSort || canFilter;
+
+  return (
+    <th
+      key={header.id}
+      data-column-id={header.column.id}
+      class={clsx(isPinned === 'left' && 'bg-light')}
+      style={style}
+      aria-sort={canSort ? getAriaSort(sortDirection) : undefined}
+      role="columnheader"
+    >
+      <div
+        class={clsx(
+          'd-flex align-items-center flex-grow-1',
+          isNormalColumn ? 'justify-content-between' : 'justify-content-center',
+        )}
+        style={{
+          minWidth: 0,
+        }}
+      >
+        <div
+          class={clsx(
+            'text-nowrap text-start',
+            // e.g. checkboxes
+            !isNormalColumn && 'd-flex align-items-center justify-content-center',
+          )}
+          style={{
+            minWidth: 0,
+            flex: '1 1 0%',
+            overflow: 'hidden',
+            textOverflow: 'ellipsis',
+            background: 'transparent',
+            border: 'none',
+          }}
+        >
+          {header.isPlaceholder
+            ? null
+            : flexRender(header.column.columnDef.header, header.getContext())}
+          {canSort && (
+            <span class="visually-hidden">, {getAriaSort(sortDirection)}, click to sort</span>
+          )}
+        </div>
+
+        {(canSort || canFilter) && (
+          <div class="d-flex align-items-center" style={{ flexShrink: 0 }}>
+            {canSort && (
+              <button
+                type="button"
+                class="btn btn-link text-muted p-0"
+                aria-label={`Sort ${columnName.toLowerCase()}, current sort is ${getAriaSort(sortDirection)}`}
+                title={`Sort ${columnName.toLowerCase()}`}
+                onClick={header.column.getToggleSortingHandler()}
+              >
+                <SortIcon sortMethod={sortDirection} />
+              </button>
+            )}
+            {canFilter && filters[header.column.id]?.({ header })}
+          </div>
+        )}
+      </div>
+      {header.column.getCanResize() && (
+        <ResizeHandle
+          header={header}
+          setColumnSizing={table.setColumnSizing}
+          onResizeEnd={handleResizeEnd}
+        />
+      )}
+    </th>
+  );
+}

package/src/components/styles.css

@@ -0,0 +1,58 @@
+/* Global styles for the PrairieLearn UI components. These should be included in any
+page that uses the PrairieLearn UI components, and class names should not be directly referenced by consumers.
+*/
+
+body.pl-ui-no-user-select {
+  user-select: none;
+  -webkit-user-select: none;
+}
+
+.pl-ui-tanstack-table-search-input {
+  padding-right: 2.5rem;
+}
+
+.btn.btn-floating-icon {
+  position: absolute;
+  right: 0;
+  top: 50%;
+  transform: translateY(-50%);
+  padding: 0.25rem 0.5rem;
+  color: var(--bs-secondary);
+  opacity: 0.6;
+  transition: opacity 0.15s ease-in-out;
+  text-decoration: none;
+}
+
+.btn.btn-floating-icon:hover {
+  opacity: 1;
+  color: var(--bs-secondary);
+  text-decoration: none;
+}
+
+.btn.btn-floating-icon:focus {
+  opacity: 1;
+  color: var(--bs-secondary);
+  text-decoration: none;
+}
+
+/* https://react-bootstrap.github.io/docs/getting-started/theming/#new-variants-and-sizes */
+.btn.btn-tanstack-table {
+  --bs-btn-color: var(--bs-body-color);
+  --bs-btn-bg: var(--bs-input-bg);
+  --bs-btn-border-color: var(--bs-border-color);
+  --bs-btn-hover-color: var(--bs-body-color);
+  --bs-btn-hover-bg: var(--bs-border-color);
+  --bs-btn-hover-border-color: var(--bs-border-color);
+  --bs-btn-focus-shadow-rgb: var(--bs-primary-rgb);
+  --bs-btn-active-color: var(--bs-body-color);
+  --bs-btn-active-bg: var(--bs-border-color);
+  --bs-btn-active-border-color: var(--bs-border-color);
+  --bs-btn-active-shadow: inset 0 3px 5px rgba(0, 0, 0, 0.125);
+  --bs-btn-disabled-color: var(--bs-body-color);
+  --bs-btn-disabled-bg: var(--bs-secondary-bg);
+  --bs-btn-disabled-border-color: var(--bs-border-color);
+}
+
+:is(.btn.btn-tanstack-table, .pl-ui-tanstack-table-focusable-shadow):not(:focus-visible) {
+  box-shadow: var(--bs-box-shadow-sm);
+}

package/src/components/useAutoSizeColumns.tsx

@@ -0,0 +1,168 @@
+import type { ColumnSizingState, Header, Table } from '@tanstack/react-table';
+import type { RefObject } from 'preact';
+import { render } from 'preact/compat';
+import { useEffect, useRef, useState } from 'preact/hooks';
+import type { JSX } from 'preact/jsx-runtime';
+
+import { TanstackTableHeaderCell } from './TanstackTableHeaderCell.js';
+
+function HiddenMeasurementHeader<TData>({
+  table,
+  columnsToMeasure,
+  filters = {},
+}: {
+  table: Table<TData>;
+  columnsToMeasure: { id: string }[];
+  filters?: Record<string, (props: { header: Header<TData, unknown> }) => JSX.Element>;
+}) {
+  const headerGroups = table.getHeaderGroups();
+  const leafHeaderGroup = headerGroups[headerGroups.length - 1];
+
+  return (
+    <div
+      style={{
+        position: 'fixed',
+        visibility: 'hidden',
+        pointerEvents: 'none',
+        top: '-9999px',
+      }}
+    >
+      <table class="table table-hover mb-0" style={{ display: 'grid', tableLayout: 'fixed' }}>
+        <thead style={{ display: 'grid' }}>
+          <tr style={{ display: 'flex' }}>
+            {columnsToMeasure.map((col) => {
+              const header = leafHeaderGroup.headers.find((h) => h.column.id === col.id);
+              if (!header) return null;
+
+              return (
+                <TanstackTableHeaderCell
+                  key={header.id}
+                  header={header}
+                  filters={filters}
+                  table={table}
+                  isPinned={false}
+                  measurementMode={true}
+                />
+              );
+            })}
+          </tr>
+        </thead>
+      </table>
+    </div>
+  );
+}
+
+/**
+ * Custom hook that automatically measures and sets column widths based on header content.
+ * Only measures columns that have `meta: { autoSize: true }` and don't have explicit sizes set.
+ * User resizes are preserved.
+ *
+ * @param table - The TanStack Table instance
+ * @param tableRef - Ref to the table container element
+ * @param filters - Optional filters map for rendering filter components in measurement
+ * @returns A boolean indicating whether the initial measurement has completed
+ */
+export function useAutoSizeColumns<TData>(
+  table: Table<TData>,
+  tableRef: RefObject<HTMLDivElement>,
+  filters?: Record<string, (props: { header: Header<TData, unknown> }) => JSX.Element>,
+): boolean {
+  const [hasMeasured, setHasMeasured] = useState(false);
+  const measurementContainerRef = useRef<HTMLDivElement | null>(null);
+
+  // Perform measurement
+  useEffect(() => {
+    if (hasMeasured || !tableRef.current) {
+      return;
+    }
+
+    const allColumns = table.getAllLeafColumns();
+
+    const columnsToMeasure = allColumns.filter((col) => col.columnDef.meta?.autoSize);
+
+    if (columnsToMeasure.length === 0) {
+      // eslint-disable-next-line @eslint-react/hooks-extra/no-direct-set-state-in-use-effect
+      setHasMeasured(true);
+      return;
+    }
+
+    // Wait for next frame to ensure DOM is ready
+    const rafId = requestAnimationFrame(() => {
+      if (!tableRef.current) {
+        return;
+      }
+
+      // Create or reuse measurement container
+      let container = measurementContainerRef.current;
+      if (!container) {
+        container = document.createElement('div');
+        document.body.append(container);
+        measurementContainerRef.current = container;
+      }
+
+      // Render headers into hidden container
+      render(
+        <HiddenMeasurementHeader
+          table={table}
+          columnsToMeasure={columnsToMeasure}
+          filters={filters ?? {}}
+        />,
+        container,
+      );
+
+      // Force layout calculation
+      void container.offsetWidth;
+
+      // Measure each header and build sizing state
+      const newSizing: ColumnSizingState = {};
+
+      for (const col of columnsToMeasure) {
+        const headerElement = container.querySelector(
+          `th[data-column-id="${col.id}"]`,
+        ) as HTMLElement;
+
+        if (headerElement) {
+          const measuredWidth = headerElement.scrollWidth;
+          const resizeHandlePadding = col.getCanResize() ? 4 : 0;
+          const minSize = col.columnDef.minSize ?? 0;
+          const maxSize = col.columnDef.maxSize ?? Infinity;
+
+          const finalWidth = Math.max(
+            minSize,
+            Math.min(maxSize, measuredWidth + resizeHandlePadding),
+          );
+
+          newSizing[col.id] = finalWidth;
+        }
+      }
+
+      // Clear container content by unmounting Preact components
+      render(null, container);
+
+      // Apply measurements
+      if (Object.keys(newSizing).length > 0) {
+        table.setColumnSizing((prev) => ({ ...prev, ...newSizing }));
+      }
+
+      setHasMeasured(true);
+    });
+
+    return () => {
+      cancelAnimationFrame(rafId);
+    };
+  }, [table, tableRef, filters, hasMeasured]);
+
+  // Clean up measurement container on unmount
+  useEffect(() => {
+    return () => {
+      const container = measurementContainerRef.current;
+      if (container) {
+        render(null, container);
+        container.remove();
+        measurementContainerRef.current = null;
+      }
+    };
+  }, []);
+
+  return hasMeasured;
+}

package/src/index.ts

@@ -1,4 +1,11 @@
-export { TanstackTable, TanstackTableCard } from './components/TanstackTable.js';
+// Augment @tanstack/react-table types
+import './react-table.js';
+
+export {
+  TanstackTable,
+  TanstackTableCard,
+  TanstackTableEmptyState,
+} from './components/TanstackTable.js';
 export { ColumnManager } from './components/ColumnManager.js';
 export { TanstackTableDownloadButton } from './components/TanstackTableDownloadButton.js';
 export { CategoricalColumnFilter } from './components/CategoricalColumnFilter.js';
@@ -7,5 +14,7 @@ export {
   NumericInputColumnFilter,
   parseNumericFilter,
   numericColumnFilterFn,
+  type NumericColumnFilterValue,
 } from './components/NumericInputColumnFilter.js';
 export { useShiftClickCheckbox } from './components/useShiftClickCheckbox.js';
+export { OverlayTrigger, type OverlayTriggerProps } from './components/OverlayTrigger.js';

package/src/react-table.ts

@@ -0,0 +1,17 @@
+import type { RowData } from '@tanstack/react-table';
+
+declare module '@tanstack/react-table' {
+  // https://tanstack.com/table/latest/docs/api/core/column-def#meta
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  interface ColumnMeta<TData extends RowData, TValue> {
+    /** If true, the column will wrap text instead of being truncated. */
+    wrapText?: boolean;
+    /** If set, this will be used as the label for the column in the column manager. */
+    label?: string;
+    /** If true, the column will be automatically sized based on the header content. */
+    autoSize?: boolean;
+  }
+}
+
+// eslint-disable-next-line unicorn/require-module-specifiers
+export {};

package/tsconfig.json

@@ -6,6 +6,5 @@
     "types": ["node"],
     "jsx": "react-jsx",
     "jsxImportSource": "@prairielearn/preact-cjs"
-  },
-  "include": ["src/*"]
+  }
 }

package/dist/components/TanstackTable.css

@@ -1,4 +0,0 @@
-body.no-user-select {
-  user-select: none;
-  -webkit-user-select: none;
-}

package/src/components/TanstackTable.css

@@ -1,4 +0,0 @@
-body.no-user-select {
-  user-select: none;
-  -webkit-user-select: none;
-}