@prairielearn/ui 1.3.0 → 1.4.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>
+  );
+}