HIGHWAY_FILTER_USAGE.md

Highway Filter Dropdown Feature

Overview

The highway layer now includes a user-controlled dropdown filter in the map legend, replacing the previous automatic zoom-based filtering behavior.

Changes Made

1. MapComponent (src/components/map-arcgis/map.tsx)

• Added highwayFilter prop: Controls which highway types are displayed
• Added onHighwayFilterChange prop: Callback when filter changes
• Removed zoom-based automatic filtering for highways
• Added dropdown UI in legend next to the Highways checkbox

2. MapShell (src/components/map-arcgis/MapShell.tsx)

• Added internal state management for highway filter (default: 'ih-us')
• Passes filter props down to MapComponent
• Supports both controlled and uncontrolled usage

3. Layer Definition (src/lib/map/layers.ts)

• Updated documentation for createHighwayLayer()
• Default filter set to show Interstates + US Routes

Highway Filter Options

Filter Value	Label	Description
'ih'	Interstates	Only Interstate Highways (IH-*)
'ih-us'	IH + US	Interstates + US Routes (default)
'ih-us-sh'	IH + US + SH	Interstates + US + State Highways
'major'	Major Roads	IH + US + SH + State Loops (SL)
'all'	All Highways	All highway types (no filter)

Usage Examples

Basic Usage (Uncontrolled)

The MapShell component manages the highway filter state internally:

import MapShell from "@/components/map-arcgis/MapShell";

function MyMapPage() {
  return (
    <MapShell
      preset="pmis"
      showLegend={true}
      includeRefAndHighways={true}
    />
  );
}

Controlled Usage

Manage the highway filter state in your parent component:

import { useState } from "react";
import MapShell from "@/components/map-arcgis/MapShell";

function MyMapPage() {
  const [filter, setFilter] = useState<'all' | 'ih' | 'ih-us' | 'ih-us-sh' | 'major'>('ih');

  const handleFilterChange = (newFilter) => {
    console.log('Highway filter changed to:', newFilter);
    setFilter(newFilter);
    // Could save to localStorage, analytics, etc.
  };

  return (
    <MapShell
      preset="pmis"
      showLegend={true}
      includeRefAndHighways={true}
      highwayFilter={filter}
      onHighwayFilterChange={handleFilterChange}
    />
  );
}

Direct MapComponent Usage

If using MapComponent directly (without MapShell):

import { useState } from "react";
import MapComponent from "@/components/map-arcgis/map";
import { createHighwayLayer, createPMISLayer } from "@/lib/map/layers";

function MyCustomMap() {
  const [highwayFilter, setHighwayFilter] = useState('ih-us');

  const layers = [
    { layer: createHighwayLayer(), name: "Highways", visible: true },
    { layer: createPMISLayer(), name: "PMIS Data", visible: true },
  ];

  return (
    <MapComponent
      layers={layers}
      showLegend={true}
      highwayFilter={highwayFilter}
      onHighwayFilterChange={setHighwayFilter}
    />
  );
}

UI Behavior

Desktop

• Dropdown appears inline next to the Highways checkbox in the legend
• Label: "Filter:"
• Full option labels displayed

Mobile (< 768px)

• Compact layout with shorter label: "Type:"
• Smaller font sizes for better fit
• Touch-friendly dropdown with proper tap targets

Disabled State

• Dropdown is disabled when Highways layer is unchecked
• Visual feedback: opacity reduced to 50%
• Re-enabled automatically when layer is checked again

Migration Notes

Before: Highways automatically filtered based on zoom level

• Zoom ≤ 4: Only Interstates
• Zoom 4-8: Interstates + US Routes
• Zoom ≥ 8: All highways

After: User controls filter via dropdown

• Default: Interstates + US Routes ('ih-us')
• User can select any filter option at any zoom level
• Zoom no longer affects highway visibility

Technical Implementation

The filter works by setting the ArcGIS definitionExpression on the highway FeatureLayer:

switch (filter) {
  case 'ih':
    featureLayer.definitionExpression = "SUBSTRING(RTE_NM,1,2)='IH'";
    break;
  case 'ih-us':
    featureLayer.definitionExpression = "(SUBSTRING(RTE_NM,1,2)='IH' or SUBSTRING(RTE_NM,1,2)='US')";
    break;
  case 'ih-us-sh':
    featureLayer.definitionExpression = "(SUBSTRING(RTE_NM,1,2)='IH' or SUBSTRING(RTE_NM,1,2)='US' or SUBSTRING(RTE_NM,1,2)='SH')";
    break;
  case 'major':
    featureLayer.definitionExpression = "(SUBSTRING(RTE_NM,1,2)='IH' or SUBSTRING(RTE_NM,1,2)='US' or SUBSTRING(RTE_NM,1,2)='SH' or SUBSTRING(RTE_NM,1,2)='SL')";
    break;
  case 'all':
    featureLayer.definitionExpression = "1=1";
    break;
}

This SQL-like expression filters the features at the service level before rendering, ensuring optimal performance.