feat(opengrid): add multi-select jurisdiction filter for utilities

Nicholas Brown · Nicholas Brown · commit eb281ea9664b · 2026-02-25T10:00:23.000-05:00
- Add jurisdictions[] array to ExplorerState for tracking selected state codes
- Serialize/deserialize jurisdiction filter in URL (?jurisdictions=CA,TX,NY)
- Add JurisdictionFilter component: dropdown with search + checkboxes
- Update UtilityListPanel to render JurisdictionFilter and apply jurisdiction filtering
- Update explorer/utilities/page.tsx with same multi-select behavior
- Filtering logic: a utility matches if its jurisdiction field contains ANY selected state
  (utilities with multi-state jurisdictions like 'AL, GA, MS' match any of those states)

Fixes MAI-39
diff --git a/components/explorer/ExplorerContext.tsx b/components/explorer/ExplorerContext.tsx
@@ -30,6 +30,7 @@ export interface ExplorerState {
   q: string;
   segment: string;
   type: string;
+  jurisdictions: string[]; // selected state codes for multi-select jurisdiction filter
   // Map interaction
   highlightGeoJSON: FeatureCollection | null;
   hoveredSlug: string | null;
@@ -44,9 +45,10 @@ type ExplorerAction =
   | { type: "SET_SEARCH"; q: string }
   | { type: "SET_SEGMENT"; segment: string }
   | { type: "SET_TYPE"; typeFilter: string }
+  | { type: "SET_JURISDICTIONS"; jurisdictions: string[] }
   | { type: "SET_HIGHLIGHT"; geoJSON: FeatureCollection | null }
   | { type: "SET_HOVERED_SLUG"; slug: string | null }
-  | { type: "SYNC_FROM_URL"; mode: ViewMode; view: EntityView | null; slug: string | null; q: string; segment: string; typeFilter: string };
+  | { type: "SYNC_FROM_URL"; mode: ViewMode; view: EntityView | null; slug: string | null; q: string; segment: string; typeFilter: string; jurisdictions: string[] };
 
 interface ExplorerContextValue {
   state: ExplorerState;
@@ -56,6 +58,7 @@ interface ExplorerContextValue {
   setSearch: (q: string) => void;
   setSegment: (segment: string) => void;
   setTypeFilter: (type: string) => void;
+  setJurisdictions: (jurisdictions: string[]) => void;
   setHighlight: (geoJSON: FeatureCollection | null) => void;
   setHoveredSlug: (slug: string | null) => void;
   goBack: () => void;
@@ -72,6 +75,7 @@ const initialState: ExplorerState = {
   q: "",
   segment: "all",
   type: "all",
+  jurisdictions: [],
   highlightGeoJSON: null,
   hoveredSlug: null,
   previousView: null,
@@ -88,6 +92,7 @@ function reducer(state: ExplorerState, action: ExplorerAction): ExplorerState {
         q: "",
         segment: "all",
         type: "all",
+        jurisdictions: [],
         highlightGeoJSON: null,
         hoveredSlug: null,
         previousView: null,
@@ -123,6 +128,9 @@ function reducer(state: ExplorerState, action: ExplorerAction): ExplorerState {
     case "SET_TYPE":
       return { ...state, type: action.typeFilter };
 
+    case "SET_JURISDICTIONS":
+      return { ...state, jurisdictions: action.jurisdictions };
+
     case "SET_HIGHLIGHT":
       return { ...state, highlightGeoJSON: action.geoJSON };
 
@@ -138,6 +146,7 @@ function reducer(state: ExplorerState, action: ExplorerAction): ExplorerState {
         q: action.q,
         segment: action.segment,
         type: action.typeFilter,
+        jurisdictions: action.jurisdictions,
       };
 
     default:
@@ -156,6 +165,7 @@ function stateToSearchParams(state: ExplorerState): string {
   if (state.q) params.set("q", state.q);
   if (state.segment && state.segment !== "all") params.set("segment", state.segment);
   if (state.type && state.type !== "all") params.set("type", state.type);
+  if (state.jurisdictions && state.jurisdictions.length > 0) params.set("jurisdictions", state.jurisdictions.join(","));
   const str = params.toString();
   return str ? `/explore?${str}` : "/explore";
 }
@@ -200,6 +210,8 @@ export function ExplorerProvider({ children }: { children: ReactNode }) {
     const qParam = searchParams.get("q") ?? "";
     const segmentParam = searchParams.get("segment") ?? "all";
     const typeParam = searchParams.get("type") ?? "all";
+    const jurisdictionsParam = searchParams.get("jurisdictions");
+    const jurisdictionsFromUrl = jurisdictionsParam ? jurisdictionsParam.split(",").filter(Boolean) : [];
 
     const { mode, view } = parseViewMode(viewParam);
 
@@ -210,7 +222,8 @@ export function ExplorerProvider({ children }: { children: ReactNode }) {
       slugParam !== state.slug ||
       qParam !== state.q ||
       segmentParam !== state.segment ||
-      typeParam !== state.type
+      typeParam !== state.type ||
+      JSON.stringify(jurisdictionsFromUrl) !== JSON.stringify(state.jurisdictions)
     ) {
       isUrlSync.current = true;
       dispatch({
@@ -221,6 +234,7 @@ export function ExplorerProvider({ children }: { children: ReactNode }) {
         q: qParam,
         segment: segmentParam,
         typeFilter: typeParam,
+        jurisdictions: jurisdictionsFromUrl,
       });
     }
     // eslint-disable-next-line react-hooks/exhaustive-deps
@@ -235,7 +249,7 @@ export function ExplorerProvider({ children }: { children: ReactNode }) {
     const url = stateToSearchParams(state);
     router.push(url, { scroll: false });
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [state.mode, state.view, state.slug, state.q, state.segment, state.type]);
+  }, [state.mode, state.view, state.slug, state.q, state.segment, state.type, state.jurisdictions]);
 
   const navigateToLanding = useCallback(() => dispatch({ type: "NAVIGATE_LANDING" }), []);
   const navigateToList = useCallback((view: ListView) => dispatch({ type: "NAVIGATE_LIST", view }), []);
@@ -246,6 +260,7 @@ export function ExplorerProvider({ children }: { children: ReactNode }) {
   const setSearch = useCallback((q: string) => dispatch({ type: "SET_SEARCH", q }), []);
   const setSegment = useCallback((segment: string) => dispatch({ type: "SET_SEGMENT", segment }), []);
   const setTypeFilter = useCallback((type: string) => dispatch({ type: "SET_TYPE", typeFilter: type }), []);
+  const setJurisdictions = useCallback((jurisdictions: string[]) => dispatch({ type: "SET_JURISDICTIONS", jurisdictions }), []);
   const setHighlight = useCallback(
     (geoJSON: FeatureCollection | null) => dispatch({ type: "SET_HIGHLIGHT", geoJSON }),
     []
@@ -280,11 +295,12 @@ export function ExplorerProvider({ children }: { children: ReactNode }) {
       setSearch,
       setSegment,
       setTypeFilter,
+      setJurisdictions,
       setHighlight,
       setHoveredSlug,
       goBack,
     }),
-    [state, navigateToLanding, navigateToList, navigateToDetail, setSearch, setSegment, setTypeFilter, setHighlight, setHoveredSlug, goBack]
+    [state, navigateToLanding, navigateToList, navigateToDetail, setSearch, setSegment, setTypeFilter, setJurisdictions, setHighlight, setHoveredSlug, goBack]
   );
 
   return <ExplorerCtx.Provider value={value}>{children}</ExplorerCtx.Provider>;
diff --git a/components/explorer/panels/UtilityListPanel.tsx b/components/explorer/panels/UtilityListPanel.tsx
@@ -8,7 +8,7 @@ import {
   DataTable,
   EmptyState,
 } from "@texturehq/edges";
-import { useCallback, useMemo } from "react";
+import { useCallback, useMemo, useRef, useState } from "react";
 import { useExplorer } from "../ExplorerContext";
 import { getAllUtilities, searchEntities, sortByName } from "@/lib/data";
 import {
@@ -41,8 +41,198 @@ const segmentFilterOptions = [
   })),
 ];
 
+// All US state/territory codes present in the data
+const ALL_STATE_CODES = [
+  "AK","AL","AR","AZ","CA","CO","CT","DC","DE","FL","GA","HI",
+  "IA","ID","IL","IN","KS","KY","LA","MA","MD","ME","MI","MN",
+  "MO","MS","MT","NC","ND","NE","NH","NJ","NM","NV","NY","OH",
+  "OK","OR","PA","RI","SC","SD","TN","TX","UT","VA","VT","WA",
+  "WI","WV","WY",
+];
+
+/** Returns all individual state codes from a comma-separated jurisdiction string */
+function parseJurisdictionStates(jurisdiction: string | null): string[] {
+  if (!jurisdiction) return [];
+  return jurisdiction.split(",").map((s) => s.trim()).filter(Boolean);
+}
+
+/** True if the utility matches any of the selected jurisdictions */
+function matchesJurisdictions(utility: Utility, selected: string[]): boolean {
+  if (selected.length === 0) return true;
+  const states = parseJurisdictionStates(utility.jurisdiction);
+  return selected.some((j) => states.includes(j));
+}
+
+// ---------------------------------------------------------------------------
+// Jurisdiction multi-select dropdown
+// ---------------------------------------------------------------------------
+
+interface JurisdictionFilterProps {
+  selected: string[];
+  onChange: (jurisdictions: string[]) => void;
+}
+
+function JurisdictionFilter({ selected, onChange }: JurisdictionFilterProps) {
+  const [open, setOpen] = useState(false);
+  const [search, setSearch] = useState("");
+  const ref = useRef<HTMLDivElement>(null);
+
+  // Close on outside click
+  const handleBlur = useCallback((e: React.FocusEvent<HTMLDivElement>) => {
+    if (!ref.current?.contains(e.relatedTarget as Node)) {
+      setOpen(false);
+    }
+  }, []);
+
+  const filteredCodes = useMemo(
+    () =>
+      search
+        ? ALL_STATE_CODES.filter((code) =>
+            code.toLowerCase().includes(search.toLowerCase())
+          )
+        : ALL_STATE_CODES,
+    [search]
+  );
+
+  const toggle = useCallback(
+    (code: string) => {
+      if (selected.includes(code)) {
+        onChange(selected.filter((s) => s !== code));
+      } else {
+        onChange([...selected, code]);
+      }
+    },
+    [selected, onChange]
+  );
+
+  const clearAll = useCallback(() => {
+    onChange([]);
+    setSearch("");
+  }, [onChange]);
+
+  const label =
+    selected.length === 0
+      ? "All Jurisdictions"
+      : selected.length === 1
+      ? selected[0]
+      : `${selected.length} States`;
+
+  return (
+    <div ref={ref} className="relative" onBlur={handleBlur}>
+      <button
+        type="button"
+        onClick={() => setOpen((o) => !o)}
+        className={`h-10 sm:h-8 inline-flex items-center gap-1.5 rounded-md border px-2 text-base sm:text-sm transition-colors ${
+          selected.length > 0
+            ? "border-brand-primary bg-brand-primary/10 text-brand-primary font-medium"
+            : "border-border-default bg-background-surface text-text-body"
+        }`}
+        aria-haspopup="listbox"
+        aria-expanded={open}
+      >
+        {label}
+        {selected.length > 0 && (
+          <span
+            role="button"
+            tabIndex={0}
+            aria-label="Clear jurisdiction filter"
+            className="ml-1 text-brand-primary hover:text-brand-primary/70 leading-none"
+            onClick={(e) => {
+              e.stopPropagation();
+              clearAll();
+            }}
+            onKeyDown={(e) => {
+              if (e.key === "Enter" || e.key === " ") {
+                e.stopPropagation();
+                clearAll();
+              }
+            }}
+          >
+            ×
+          </span>
+        )}
+        <svg
+          className={`w-3 h-3 ml-0.5 transition-transform ${open ? "rotate-180" : ""}`}
+          fill="none"
+          viewBox="0 0 24 24"
+          stroke="currentColor"
+          strokeWidth={2}
+          aria-hidden="true"
+        >
+          <path strokeLinecap="round" strokeLinejoin="round" d="M19 9l-7 7-7-7" />
+        </svg>
+      </button>
+
+      {open && (
+        <div
+          className="absolute right-0 top-full mt-1 z-50 w-52 rounded-lg border border-border-default bg-background-surface shadow-lg flex flex-col"
+          role="listbox"
+          aria-multiselectable="true"
+          aria-label="Filter by jurisdiction"
+        >
+          {/* Search */}
+          <div className="p-2 border-b border-border-default">
+            <input
+              autoFocus
+              type="text"
+              value={search}
+              onChange={(e) => setSearch(e.target.value)}
+              placeholder="Search states..."
+              className="w-full h-7 rounded-md border border-border-default bg-background-page px-2 text-sm text-text-body placeholder:text-text-muted focus:outline-none focus:ring-1 focus:ring-brand-primary"
+            />
+          </div>
+
+          {/* Options */}
+          <div className="overflow-y-auto max-h-56 py-1">
+            {filteredCodes.length === 0 ? (
+              <div className="px-3 py-2 text-sm text-text-muted">No states found</div>
+            ) : (
+              filteredCodes.map((code) => {
+                const isChecked = selected.includes(code);
+                return (
+                  <label
+                    key={code}
+                    className="flex items-center gap-2 px-3 py-1.5 text-sm text-text-body cursor-pointer hover:bg-background-hover select-none"
+                    role="option"
+                    aria-selected={isChecked}
+                  >
+                    <input
+                      type="checkbox"
+                      checked={isChecked}
+                      onChange={() => toggle(code)}
+                      className="rounded border-border-default text-brand-primary focus:ring-brand-primary"
+                    />
+                    {code}
+                  </label>
+                );
+              })
+            )}
+          </div>
+
+          {/* Footer */}
+          {selected.length > 0 && (
+            <div className="px-3 py-2 border-t border-border-default">
+              <button
+                type="button"
+                onClick={clearAll}
+                className="text-xs text-text-muted hover:text-text-body transition-colors"
+              >
+                Clear all ({selected.length})
+              </button>
+            </div>
+          )}
+        </div>
+      )}
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Main panel
+// ---------------------------------------------------------------------------
+
 export function UtilityListPanel() {
-  const { state, setSearch, setSegment, navigateToDetail, navigateToLanding } = useExplorer();
+  const { state, setSearch, setSegment, setJurisdictions, navigateToDetail, navigateToLanding } = useExplorer();
 
   const allUtilities = useMemo(() => getAllUtilities(), []);
 
@@ -54,9 +244,12 @@ export function UtilityListPanel() {
     if (state.segment !== "all") {
       result = result.filter((u) => u.segment === state.segment);
     }
+    if (state.jurisdictions.length > 0) {
+      result = result.filter((u) => matchesJurisdictions(u, state.jurisdictions));
+    }
     result = sortByName(result, "asc");
     return result;
-  }, [allUtilities, state.q, state.segment]);
+  }, [allUtilities, state.q, state.segment, state.jurisdictions]);
 
   const rows: UtilityRow[] = useMemo(
     () =>
@@ -141,17 +334,23 @@ export function UtilityListPanel() {
             onChange: () => {},
           }}
           customControls={
-            <select
-              value={state.segment}
-              onChange={(e) => setSegment(e.target.value)}
-              className="h-10 sm:h-8 rounded-md border border-border-default bg-background-surface px-2 text-base sm:text-sm text-text-body"
-            >
-              {segmentFilterOptions.map((opt) => (
-                <option key={opt.id} value={opt.value}>
-                  {opt.label}
-                </option>
-              ))}
-            </select>
+            <div className="flex items-center gap-2">
+              <select
+                value={state.segment}
+                onChange={(e) => setSegment(e.target.value)}
+                className="h-10 sm:h-8 rounded-md border border-border-default bg-background-surface px-2 text-base sm:text-sm text-text-body"
+              >
+                {segmentFilterOptions.map((opt) => (
+                  <option key={opt.id} value={opt.value}>
+                    {opt.label}
+                  </option>
+                ))}
+              </select>
+              <JurisdictionFilter
+                selected={state.jurisdictions}
+                onChange={setJurisdictions}
+              />
+            </div>
           }
           sticky={true}
         />
@@ -161,7 +360,7 @@ export function UtilityListPanel() {
           <EmptyState
             icon="Lightning"
             title="No utilities found"
-            description={state.q ? "Try adjusting your search criteria." : "No utilities in the dataset."}
+            description={state.q ? "Try adjusting your search criteria." : "No utilities match the selected filters."}
             fullHeight={true}
           />
         ) : (
diff --git a/explorer/app/(shell)/utilities/page.tsx b/explorer/app/(shell)/utilities/page.tsx
