@prairielearn/ui 1.3.0 → 1.5.0

package/src/components/NumericInputColumnFilter.tsx

@@ -1,31 +1,43 @@
+import type { Column } from '@tanstack/table-core';
 import clsx from 'clsx';
 import Dropdown from 'react-bootstrap/Dropdown';
 
-interface NumericInputColumnFilterProps {
-  columnId: string;
-  columnLabel: string;
-  value: string;
-  onChange: (value: string) => void;
-}
+export type NumericColumnFilterValue =
+  | {
+      filterValue: string;
+      emptyOnly: false;
+    }
+  | {
+      filterValue: '';
+      emptyOnly: true;
+    };
 
 /**
  * A component that allows the user to filter a numeric column using comparison operators.
  * Supports syntax like: <1, >0, <=5, >=10, =5, or just 5 (implicit equals)
  *
  * @param params
- * @param params.columnId - The ID of the column
- * @param params.columnLabel - The label of the column, e.g. "Manual Points"
- * @param params.value - The current filter value (e.g., ">5" or "10")
- * @param params.onChange - Callback when the filter value changes
+ * @param params.column - The TanStack Table column object
  */
-export function NumericInputColumnFilter({
-  columnId,
-  columnLabel,
-  value,
-  onChange,
-}: NumericInputColumnFilterProps) {
-  const hasActiveFilter = value.trim().length > 0;
-  const isInvalid = hasActiveFilter && parseNumericFilter(value) === null;
+export function NumericInputColumnFilter<TData, TValue>({
+  column,
+}: {
+  column: Column<TData, TValue>;
+}) {
+  const columnId = column.id;
+  const value = (column.getFilterValue() as NumericColumnFilterValue | undefined) ?? {
+    filterValue: '',
+    emptyOnly: false,
+  };
+
+  const label =
+    column.columnDef.meta?.label ??
+    (typeof column.columnDef.header === 'string' ? column.columnDef.header : column.id);
+
+  const filterValue = value.filterValue;
+  const emptyOnly = value.emptyOnly;
+  const hasActiveFilter = filterValue.trim().length > 0 || emptyOnly;
+  const isInvalid = filterValue.trim().length > 0 && parseNumericFilter(filterValue) === null;
 
   return (
     <Dropdown align="end">
@@ -36,8 +48,8 @@ export function NumericInputColumnFilter({
           hasActiveFilter && (isInvalid ? 'text-warning' : 'text-primary'),
         )}
         id={`filter-${columnId}`}
-        aria-label={`Filter ${columnLabel.toLowerCase()}`}
-        title={`Filter ${columnLabel.toLowerCase()}`}
+        aria-label={`Filter ${label.toLowerCase()}`}
+        title={`Filter ${label.toLowerCase()}`}
       >
         <i
           class={clsx(
@@ -51,17 +63,42 @@ export function NumericInputColumnFilter({
           aria-hidden="true"
         />
       </Dropdown.Toggle>
-      <Dropdown.Menu>
+      <Dropdown.Menu
+        // eslint-disable-next-line @eslint-react/no-forbidden-props
+        className="p-0"
+      >
         <div class="p-3" style={{ minWidth: '240px' }}>
-          <label class="form-label small fw-semibold mb-2">{columnLabel}</label>
+          <div class="d-flex align-items-center justify-content-between mb-2">
+            <label class="form-label fw-semibold mb-0" id={`${columnId}-filter-label`}>
+              {label}
+            </label>
+            <button
+              type="button"
+              class={clsx(
+                'btn btn-link btn-sm text-decoration-none',
+                !hasActiveFilter && 'invisible',
+              )}
+              onClick={() => {
+                column.setFilterValue({ filterValue: '', emptyOnly: false });
+              }}
+            >
+              Clear
+            </button>
+          </div>
           <input
             type="text"
             class={clsx('form-control form-control-sm', isInvalid && 'is-invalid')}
             placeholder="e.g., >0, <5, =10"
-            value={value}
+            aria-labelledby={`${columnId}-filter-label`}
+            value={filterValue}
+            disabled={emptyOnly}
+            aria-describedby={`${columnId}-filter-description`}
             onInput={(e) => {
               if (e.target instanceof HTMLInputElement) {
-                onChange(e.target.value);
+                column.setFilterValue({
+                  filterValue: e.target.value,
+                  emptyOnly: false,
+                });
               }
             }}
             onClick={(e) => e.stopPropagation()}
@@ -72,22 +109,31 @@ export function NumericInputColumnFilter({
             </div>
           )}
           {!isInvalid && (
-            <div class="form-text small mt-2">
-              Use operators: <code>&lt;</code>, <code>&gt;</code>, <code>&lt;=</code>,{' '}
+            <small class="form-text text-nowrap" id={`${columnId}-filter-description`}>
+              Operators: <code>&lt;</code>, <code>&gt;</code>, <code>&lt;=</code>,{' '}
               <code>&gt;=</code>, <code>=</code>
-              <br />
-              Example: <code>&gt;5</code> or <code>&lt;=10</code>
-            </div>
-          )}
-          {hasActiveFilter && (
-            <button
-              type="button"
-              class="btn btn-sm btn-link text-decoration-none mt-2 p-0"
-              onClick={() => onChange('')}
-            >
-              Clear filter
-            </button>
+            </small>
           )}
+          <div class="form-check mt-2">
+            <input
+              class="form-check-input"
+              type="checkbox"
+              checked={emptyOnly}
+              id={`${columnId}-empty-filter`}
+              onChange={(e) => {
+                if (e.target instanceof HTMLInputElement) {
+                  column.setFilterValue(
+                    e.target.checked
+                      ? { filterValue: '', emptyOnly: true }
+                      : { filterValue: '', emptyOnly: false },
+                  );
+                }
+              }}
+            />
+            <label class="form-check-label" for={`${columnId}-empty-filter`}>
+              Empty values
+            </label>
+          </div>
         </div>
       </Dropdown.Menu>
     </Dropdown>
@@ -129,13 +175,27 @@ export function parseNumericFilter(filterValue: string): {
  *   filterFn: numericColumnFilterFn,
  * }
  */
-export function numericColumnFilterFn(row: any, columnId: string, filterValue: string): boolean {
+export function numericColumnFilterFn(
+  row: any,
+  columnId: string,
+  { filterValue, emptyOnly }: NumericColumnFilterValue,
+): boolean {
+  // Handle object-based filter value
+  const cellValue = row.getValue(columnId) as number | null;
+  const isEmpty = cellValue == null;
+
+  if (emptyOnly) {
+    return isEmpty;
+  }
+
+  // If there's no numeric filter, show all rows
   const parsed = parseNumericFilter(filterValue);
-  if (!parsed) return true; // Invalid or empty filter = show all
+  if (!parsed) return true;
 
-  const cellValue = row.getValue(columnId) as number | null;
-  if (cellValue === null || cellValue === undefined) return false;
+  // If cell is empty and we're doing numeric filtering, don't show it
+  if (isEmpty) return false;
 
+  // Apply numeric filter
   switch (parsed.operator) {
     case '<':
       return cellValue < parsed.value;

package/src/components/OverlayTrigger.tsx

@@ -0,0 +1,168 @@
+import { useEffect, useRef } from 'preact/compat';
+import {
+  // eslint-disable-next-line no-restricted-imports
+  OverlayTrigger as BootstrapOverlayTrigger,
+  type OverlayTriggerProps as BootstrapOverlayTriggerProps,
+  Popover,
+  type PopoverProps,
+  Tooltip,
+  type TooltipProps,
+} from 'react-bootstrap';
+
+import { type FocusTrap, focusFirstFocusableChild, trapFocus } from '@prairielearn/browser-utils';
+
+export interface OverlayTriggerProps extends Omit<BootstrapOverlayTriggerProps, 'overlay'> {
+  popover?: {
+    /**
+     * Additional props to pass to the Popover component.
+     */
+    props?: Omit<PopoverProps, 'children'>;
+    /**
+     * The content to display in the popover body.
+     */
+    body: React.ReactNode;
+    /**
+     * Optional header content for the popover.
+     */
+    header?: React.ReactNode;
+  };
+  tooltip?: {
+    /**
+     * Additional props to pass to the Tooltip component. `id` is required for accessibility.
+     */
+    props: Omit<TooltipProps, 'children' | 'id'> & { id: string };
+    /**
+     * The content to display in the tooltip body.
+     */
+    body: React.ReactNode;
+  };
+  /**
+   * Whether to trap focus inside the overlay when it's shown.
+   * If true, focus will be trapped and moved to the first focusable element.
+   * @default true
+   */
+  trapFocus?: boolean;
+  /**
+   * Whether to return focus to the trigger element when the overlay is hidden.
+   * @default true
+   */
+  returnFocus?: boolean;
+}
+
+/**
+ * A wrapper around react-bootstrap's OverlayTrigger that adds accessibility features:
+ * - Automatic focus trapping when the overlay is shown
+ * - Auto-focus on the first focusable element in the overlay
+ * - Returns focus to the trigger element when the overlay is hidden
+ * - Automatically constructs a Popover with proper ref management
+ *
+ * This component provides a simpler API than react-bootstrap's OverlayTrigger by
+ * handling the Popover construction and ref management internally.
+ *
+ * @example
+ * ```tsx
+ * <OverlayTrigger
+ *   tooltip={{
+ *     body: 'Tooltip content',
+ *     props: { id: 'tooltip-id' },
+ *   }}
+ *   placement="right"
+ * >
+ *   <button>Hover me</button>
+ * </OverlayTrigger>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <OverlayTrigger
+ *   popover={{
+ *     header: 'Popover title',
+ *     body: 'Popover content',
+ *   }}
+ *   placement="right"
+ * >
+ *   <button>Click me</button>
+ * </OverlayTrigger>
+ * ```
+ */
+export function OverlayTrigger({
+  children,
+  popover,
+  tooltip,
+  trapFocus: shouldTrapFocus = true,
+  returnFocus = true,
+  onEntered,
+  onExit,
+  ...props
+}: OverlayTriggerProps) {
+  const overlayBodyRef = useRef<HTMLDivElement>(null);
+  const focusTrapRef = useRef<FocusTrap | null>(null);
+  const triggerElementRef = useRef<HTMLElement | null>(null);
+
+  const handleEntered = (node: HTMLElement, isAppearing: boolean) => {
+    // Store the currently focused element (the trigger) before we move focus
+    if (returnFocus && document.activeElement instanceof HTMLElement) {
+      triggerElementRef.current = document.activeElement;
+    }
+
+    if (shouldTrapFocus && overlayBodyRef.current && props.trigger === 'click') {
+      // Trap focus inside the overlay body
+      focusTrapRef.current = trapFocus(overlayBodyRef.current);
+
+      // Move focus to the first focusable element
+      focusFirstFocusableChild(overlayBodyRef.current);
+    }
+
+    // Call the original onEntered callback if provided
+    onEntered?.(node, isAppearing);
+  };
+
+  // Deactivate the focus trap when the component unmounts
+  useEffect(() => {
+    return () => {
+      focusTrapRef.current?.deactivate();
+    };
+  }, []);
+
+  const handleExit = (node: HTMLElement) => {
+    // Deactivate the focus trap
+    if (focusTrapRef.current) {
+      focusTrapRef.current.deactivate();
+      focusTrapRef.current = null;
+    }
+
+    // Return focus to the trigger element
+    if (returnFocus && triggerElementRef.current) {
+      triggerElementRef.current.focus();
+      triggerElementRef.current = null;
+    }
+
+    // Call the original onExit callback if provided
+    onExit?.(node);
+  };
+
+  if (Boolean(popover) === Boolean(tooltip)) {
+    throw new Error('Only one of popover or tooltip must be provided');
+  }
+
+  // Construct the popover with our managed ref
+  const popoverOverlay = popover ? (
+    <Popover {...popover.props}>
+      {popover.header && <Popover.Header>{popover.header}</Popover.Header>}
+      <Popover.Body ref={overlayBodyRef}>{popover.body}</Popover.Body>
+    </Popover>
+  ) : null;
+
+  const tooltipOverlay = tooltip ? <Tooltip {...tooltip.props}>{tooltip.body}</Tooltip> : null;
+
+  return (
+    <BootstrapOverlayTrigger
+      {...props}
+      overlay={popoverOverlay ?? tooltipOverlay!}
+      onEntered={handleEntered}
+      onExit={handleExit}
+    >
+      {children}
+    </BootstrapOverlayTrigger>
+  );
+}

package/src/components/PresetFilterDropdown.tsx

@@ -0,0 +1,155 @@
+import type { ColumnFiltersState, Table } from '@tanstack/react-table';
+import { useMemo } from 'preact/compat';
+import { ButtonGroup, Dropdown } from 'react-bootstrap';
+
+/**
+ * Compares two filter values for deep equality using JSON serialization.
+ */
+function filtersEqual(a: unknown, b: unknown): boolean {
+  return JSON.stringify(a) === JSON.stringify(b);
+}
+
+/**
+ * Extracts all unique column IDs referenced across all preset options.
+ */
+function getRelevantColumnIds(options: Record<string, ColumnFiltersState>): Set<string> {
+  const columnIds = new Set<string>();
+  for (const filters of Object.values(options)) {
+    for (const filter of filters) {
+      columnIds.add(filter.id);
+    }
+  }
+  return columnIds;
+}
+
+/**
+ * Gets the current filter values for the relevant columns from the table.
+ */
+function getRelevantFilters<TData>(
+  table: Table<TData>,
+  relevantColumnIds: Set<string>,
+): ColumnFiltersState {
+  const allFilters = table.getState().columnFilters;
+  return allFilters.filter((f) => relevantColumnIds.has(f.id));
+}
+
+/**
+ * Checks if the current filters match a preset's filters.
+ * Both must have the same column IDs with equal values.
+ */
+function filtersMatchPreset(current: ColumnFiltersState, preset: ColumnFiltersState): boolean {
+  // If lengths differ, they don't match
+  if (current.length !== preset.length) return false;
+
+  // For empty presets, current must also be empty
+  if (preset.length === 0) return current.length === 0;
+
+  // Check that every preset filter exists in current with the same value
+  for (const presetFilter of preset) {
+    const currentFilter = current.find((f) => f.id === presetFilter.id);
+    if (!currentFilter || !filtersEqual(currentFilter.value, presetFilter.value)) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+/**
+ * A dropdown component that allows users to select from preset filter configurations.
+ * The selected state is derived from the table's current column filters.
+ * If no preset matches, a "Custom" option is shown as selected.
+ *
+ * Currently, this component expects that the filters states are arrays.
+ */
+export function PresetFilterDropdown<OptionName extends string, TData>({
+  table,
+  options,
+  label = 'Filter',
+  onSelect,
+}: {
+  /** The TanStack Table instance */
+  table: Table<TData>;
+  /** Mapping of option names to their filter configurations */
+  options: Record<OptionName, ColumnFiltersState>;
+  /** Label prefix for the dropdown button (e.g., "Filter") */
+  label?: string;
+  /** Callback when an option is selected, useful for side effects like column visibility */
+  onSelect?: (optionName: OptionName) => void;
+}) {
+  const relevantColumnIds = getRelevantColumnIds(options);
+
+  const currentRelevantFilters = useMemo(
+    () => getRelevantFilters(table, relevantColumnIds),
+    [table, relevantColumnIds],
+  );
+
+  // Find which option matches the current filters
+  const selectedOption = useMemo<OptionName | null>(() => {
+    for (const [optionName, presetFilters] of Object.entries(options)) {
+      if (filtersMatchPreset(currentRelevantFilters, presetFilters as ColumnFiltersState)) {
+        return optionName as OptionName;
+      }
+    }
+    return null; // No preset matches - custom filter state
+  }, [options, currentRelevantFilters]);
+
+  const handleOptionClick = (optionName: OptionName) => {
+    const presetFilters = options[optionName];
+
+    // Get current filters, removing any that are in our relevant columns
+    const currentFilters = table.getState().columnFilters;
+    const preservedFilters = currentFilters.filter((f) => !relevantColumnIds.has(f.id));
+
+    // For columns not in the preset, explicitly set empty filter to clear them
+    // This ensures the table's onColumnFiltersChange handler can sync the cleared state
+    const clearedFilters = Array.from(relevantColumnIds)
+      .filter((colId) => !presetFilters.some((f) => f.id === colId))
+      .map((colId) => ({
+        id: colId,
+        // TODO: This expects that we are only clearing filters whose state is an array.
+        value: [],
+      }));
+
+    // Combine preserved filters with the new preset filters and cleared filters
+    const newFilters = [...preservedFilters, ...presetFilters, ...clearedFilters];
+    table.setColumnFilters(newFilters);
+
+    onSelect?.(optionName);
+  };
+
+  const displayLabel = selectedOption ?? 'Custom';
+
+  return (
+    <Dropdown as={ButtonGroup}>
+      <Dropdown.Toggle variant="tanstack-table">
+        <i class="bi bi-funnel me-2" aria-hidden="true" />
+        {label}: {displayLabel}
+      </Dropdown.Toggle>
+      <Dropdown.Menu>
+        {Object.keys(options).map((optionName) => {
+          const isSelected = selectedOption === optionName;
+          return (
+            <Dropdown.Item
+              key={optionName}
+              as="button"
+              type="button"
+              active={isSelected}
+              onClick={() => handleOptionClick(optionName as OptionName)}
+            >
+              <i class={`bi ${isSelected ? 'bi-check-circle-fill' : 'bi-circle'} me-2`} />
+              {optionName}
+            </Dropdown.Item>
+          );
+        })}
+        {/* Show Custom option only when no preset matches */}
+        {selectedOption === null && (
+          <Dropdown.Item as="button" type="button" active disabled>
+            <i class="bi bi-check-circle-fill me-2" />
+            Custom
+          </Dropdown.Item>
+        )}
+      </Dropdown.Menu>
+    </Dropdown>
+  );
+}