Merge pull request #31 from patcon/feat/29-metrics-floating-modal-legend

Show FloatingModal legend for obs-column annotations in metrics layer

Author: patcon

CHANGELOG.md

@@ -4,6 +4,14 @@
 
 ### Added
 
+- `FloatingModal` legend when viewing an obs-column annotation in the metrics layer ([#29](https://github.com/patcon/polislike-human-cartography-prototype-v2/issues/29)).
+  - Shows the column name as the label and colored category swatches for categorical columns; continuous columns show an empty modal (legend to follow).
+  - Prev/next arrows (and ←/→ keyboard shortcuts) cycle through available obs columns, updating the active annotation.
+  - X button returns to the groups layer, matching the statement-modal behavior.
+  - Extended `FloatingModal` with optional `title` and `legendItems` props for the annotation rendering path; existing statement rendering is unchanged.
+  - Categorical annotation layers use a dedicated Tableau 20 palette (20 colors) separate from the 10-color painting palette, giving more range without affecting group colors.
+  - Legend is hidden for columns with >65 categories (e.g. timestamps, UUIDs) — only the column title is shown, matching continuous column behavior.
+  - Blank category labels are displayed as **N/A**.
 - Prev/next navigation buttons on `FloatingModal` for touch-friendly statement cycling in votes layer mode ([#27](https://github.com/patcon/polislike-human-cartography-prototype-v2/issues/27)).
   - Extracted shared `cycleStatement` callback so keyboard arrow keys and buttons use the same logic.
   - `onPrev` / `onNext` are optional injected props — buttons only render when provided, keeping the modal reusable for other contexts.

CLAUDE.md

@@ -78,6 +78,7 @@ Tests use Vitest with jsdom. `src/test-setup.ts` mocks `matchMedia`, `ResizeObse
 `CHANGELOG.md` follows [Keep a Changelog](https://keepachangelog.com) conventions with `Added`, `Changed`, and `Fixed` subsections under each release.
 
 - **Every feature branch must include a `CHANGELOG.md` update** in the same commit (or PR) as the code change.
+- **Claude must always update `CHANGELOG.md`** when implementing any feature, fix, or notable change — without waiting to be asked.
 - Entries go under `## [Unreleased]` until a version is tagged.
 - Link each entry to its GitHub issue (`[#27](.../issues/27)`) if one exists, otherwise fall back to the PR (`[#42](.../pull/42)`).
 - On release: rename `[Unreleased]` to the new version + date, update its compare URL to `compare/vPREV...vNEW`, and add a fresh empty `[Unreleased]` block at the top pointing to `compare/vNEW...main`.

src/components/convo-explorer/App.tsx

@@ -23,6 +23,7 @@ import { useShiftKeyTempMode } from "../../hooks/useShiftKeyTempMode";
 import { useLayerModeCycling } from "../../hooks/useLayerModeCycling";
 import type { MetricConfig } from "./MetricsLayerConfig";
 import type { ObsColumnType } from "@/lib/color-schemes";
+import { getAnnotationCategoricalColor } from "@/lib/color-schemes";
 import type { ObsColumnInfo } from "@/lib/h5ad-loader";
 
 // Helper function for ID matching - can be optimized later for performance
@@ -291,6 +292,40 @@ export const App: React.FC<AppProps> = ({ testAnimation = false, kedroBaseUrl, i
     }
   }, [currentDisplayState, currentPipelineId]);
 
+  // Derive obs column keys from preloaded data for the "Other" metrics option
+  // Exclude the display mask column so it doesn't appear in the dropdown
+  const obsColumnKeys = React.useMemo(() => {
+    if (!preloadedData?.obsColumns) return undefined;
+    const keys = Object.keys(preloadedData.obsColumns).filter(k => k !== DISPLAY_MASK_COLUMN);
+    return keys.length > 0 ? keys : undefined;
+  }, [preloadedData?.obsColumns]);
+
+  const cycleObsColumn = React.useCallback((direction: 'prev' | 'next') => {
+    if (!obsColumnKeys || obsColumnKeys.length === 0) return;
+    if (metricConfig.type !== 'obs-column') return;
+    const currentIndex = obsColumnKeys.indexOf(metricConfig.column);
+    if (currentIndex === -1) return;
+    const newIndex = direction === 'prev'
+      ? (currentIndex === 0 ? obsColumnKeys.length - 1 : currentIndex - 1)
+      : (currentIndex === obsColumnKeys.length - 1 ? 0 : currentIndex + 1);
+    setMetricConfig({ type: 'obs-column', column: obsColumnKeys[newIndex] });
+  }, [obsColumnKeys, metricConfig]);
+
+  // Derive legend items for the metrics FloatingModal (categorical columns only)
+  const metricsLegendItems = React.useMemo(() => {
+    if (metricConfig.type !== 'obs-column') return undefined;
+    if (!preloadedData?.obsColumns) return undefined;
+    const columnInfo = preloadedData.obsColumns[metricConfig.column];
+    if (!columnInfo || columnInfo.type !== 'categorical') return undefined;
+    const categories = columnInfo.categories ?? [];
+    // Hide legend when there are too many categories to be useful
+    if (categories.length > 65) return undefined;
+    return categories.map((cat, i) => ({
+      label: String(cat),
+      color: getAnnotationCategoricalColor(i),
+    }));
+  }, [metricConfig, preloadedData?.obsColumns]);
+
   const cycleStatement = React.useCallback((direction: 'prev' | 'next') => {
     if (statements.length === 0) return;
     const currentIndex = statements.findIndex(s => String(s.statement_id) === statementId);
@@ -320,6 +355,15 @@ export const App: React.FC<AppProps> = ({ testAnimation = false, kedroBaseUrl, i
         }
       }
 
+      // Handle left/right arrow keys for obs column cycling when metrics layer is active
+      if (layerMode === "metrics" && metricConfig.type === "obs-column" && obsColumnKeys && obsColumnKeys.length > 1) {
+        if (event.key === 'ArrowLeft' || event.key === 'ArrowRight') {
+          cycleObsColumn(event.key === 'ArrowLeft' ? 'prev' : 'next');
+          event.preventDefault();
+          return;
+        }
+      }
+
       // Handle number keys 1-9 and 0 for color selection
       if (event.key >= '1' && event.key <= '9') {
         const index = parseInt(event.key, 10);
@@ -342,7 +386,7 @@ export const App: React.FC<AppProps> = ({ testAnimation = false, kedroBaseUrl, i
     return () => {
       document.removeEventListener('keydown', handleKeyDown);
     };
-  }, [layerMode, statements, statementId, cycleStatement]);
+  }, [layerMode, statements, statementId, cycleStatement, metricConfig, obsColumnKeys, cycleObsColumn]);
 
   // Initialize point arrays when dataset is loaded
   React.useEffect(() => {
@@ -623,14 +667,6 @@ export const App: React.FC<AppProps> = ({ testAnimation = false, kedroBaseUrl, i
   // Vote stats calculation removed from App level - now handled in StatementExplorerDrawer
   // This avoids calculating stats for all statements when only group tab statements need them
 
-  // Derive obs column keys from preloaded data for the "Other" metrics option
-  // Exclude the display mask column so it doesn't appear in the dropdown
-  const obsColumnKeys = React.useMemo(() => {
-    if (!preloadedData?.obsColumns) return undefined;
-    const keys = Object.keys(preloadedData.obsColumns).filter(k => k !== DISPLAY_MASK_COLUMN);
-    return keys.length > 0 ? keys : undefined;
-  }, [preloadedData?.obsColumns]);
-
   // Derive display mask array (parallel to dataset) from obs column
   const displayMask = React.useMemo(() => {
     if (!preloadedData?.obsColumns) return undefined;
@@ -928,6 +964,18 @@ export const App: React.FC<AppProps> = ({ testAnimation = false, kedroBaseUrl, i
         />
       )}
 
+      {/* FloatingModal - shows annotation legend in metrics mode (obs-column) */}
+      {layerMode === "metrics" && metricConfig.type === "obs-column" && (
+        <FloatingModal
+          title={metricConfig.column}
+          legendItems={metricsLegendItems}
+          isVisible={true}
+          onClose={() => setLayerMode("groups")}
+          onPrev={obsColumnKeys && obsColumnKeys.length > 1 ? () => cycleObsColumn('prev') : undefined}
+          onNext={obsColumnKeys && obsColumnKeys.length > 1 ? () => cycleObsColumn('next') : undefined}
+        />
+      )}
+
       {/* Clear Colors Dialog */}
       <ClearColorsDialog
         open={clearDialogOpen}

src/components/convo-explorer/D3Map.tsx

@@ -4,7 +4,7 @@ import * as React from "react";
 import * as d3 from "d3";
 import { PALETTE_COLORS, UNPAINTED_COLOR, UNPAINTED_VALUE, OUTLINE_RADIUS, OUTLINE_OPACITY, OUTLINE_SUSPEND_DURING_ANIMATION } from "@/constants";
 import type { ObsColumnType } from "@/lib/color-schemes";
-import { BOOLEAN_COLORS, NULL_COLOR, createContinuousScale, getCategoricalColor } from "@/lib/color-schemes";
+import { BOOLEAN_COLORS, NULL_COLOR, createContinuousScale, getAnnotationCategoricalColor } from "@/lib/color-schemes";
 import { usePipelineOptions } from "../../../.storybook/hooks/usePipelineOptions";
 import { MapProjectionSelector } from "./MapProjectionSelector";
 import { Button } from "../ui/button";
@@ -270,7 +270,7 @@ export const D3Map: React.FC<D3MapProps> = ({
         case "boolean":
           return colorValue ? BOOLEAN_COLORS.true : BOOLEAN_COLORS.false;
         case "categorical":
-          return getCategoricalColor(colorValue);
+          return getAnnotationCategoricalColor(colorValue);
         case "continuous":
         default:
           return continuousColorScale(colorValue);

src/components/convo-explorer/FloatingModal.tsx

@@ -10,16 +10,22 @@ type Statement = {
   moderated?: number;
 };
 
+export type LegendItem = { label: string; color: string };
+
 type FloatingModalProps = {
-  statement: Statement;
+  // Statement mode (existing)
+  statement?: Statement;
+  // Annotation/legend mode
+  title?: string;
+  legendItems?: LegendItem[];
   isVisible?: boolean;
   onClose?: () => void;
   onPrev?: () => void;
   onNext?: () => void;
 } & React.ComponentPropsWithoutRef<typeof Card>;
 
 export const FloatingModal = React.forwardRef<HTMLDivElement, FloatingModalProps>(
-  ({ statement, isVisible = true, onClose, onPrev, onNext, className, ...props }, ref) => {
+  ({ statement, title, legendItems, isVisible = true, onClose, onPrev, onNext, className, ...props }, ref) => {
     if (!isVisible) return null;
 
     const insertBreaks = (val: string | null | undefined) => {
@@ -80,36 +86,67 @@ export const FloatingModal = React.forwardRef<HTMLDivElement, FloatingModalProps
           </button>
         )}
 
-        {/* Statement content */}
-        <div className="flex gap-2 items-start">
-          {/* Statement ID */}
-          <div className="flex-shrink-0 pt-0.5">
-            <span className={`text-gray-400 text-[12px] font-mono inline-block text-right ${hasNav ? "min-w-[3rem]" : "w-10"}`}>
-              #{statement.statement_id}
-            </span>
-          </div>
+        {/* Content: statement mode or annotation/legend mode */}
+        {statement ? (
+          <div className="flex gap-2 items-start">
+            {/* Statement ID */}
+            <div className="flex-shrink-0 pt-0.5">
+              <span className={`text-gray-400 text-[12px] font-mono inline-block text-right ${hasNav ? "min-w-[3rem]" : "w-10"}`}>
+                #{statement.statement_id}
+              </span>
+            </div>
 
-          {/* Statement Text */}
-          <div className="flex-1 min-w-0">
-            <span
-              key={statement.statement_id}
-              translate="yes"
-              className={`text-sm leading-relaxed ${
-                statement.moderated === -1 ? "text-red-700" : ""
-              } ${
-                statement.moderated === 0 ? "text-gray-500" : ""
-              } ${
-                statement.moderated === 1 ? "text-gray-900 dark:text-gray-100" : ""
-              } ${
-                statement.moderated === undefined ? "text-gray-900 dark:text-gray-100" : ""
-              }`}
-            >
-              {insertBreaks(statement.txt)}
-              {statement.moderated === -1 ? " (moderated)" : ""}
-              {statement.moderated === 0 ? " (unmoderated)" : ""}
-            </span>
+            {/* Statement Text */}
+            <div className="flex-1 min-w-0">
+              <span
+                key={statement.statement_id}
+                translate="yes"
+                className={`text-sm leading-relaxed ${
+                  statement.moderated === -1 ? "text-red-700" : ""
+                } ${
+                  statement.moderated === 0 ? "text-gray-500" : ""
+                } ${
+                  statement.moderated === 1 ? "text-gray-900 dark:text-gray-100" : ""
+                } ${
+                  statement.moderated === undefined ? "text-gray-900 dark:text-gray-100" : ""
+                }`}
+              >
+                {insertBreaks(statement.txt)}
+                {statement.moderated === -1 ? " (moderated)" : ""}
+                {statement.moderated === 0 ? " (unmoderated)" : ""}
+              </span>
+            </div>
           </div>
-        </div>
+        ) : (
+          <div className="flex flex-col gap-2 pl-10">
+            {/* Annotation label */}
+            {title && (
+              <span className="text-xs font-semibold text-gray-500 uppercase tracking-wide leading-none text-center w-full block">
+                {title}
+              </span>
+            )}
+            {/* Category swatches */}
+            {legendItems && legendItems.length > 0 && (
+              <div className="flex flex-wrap gap-x-4 gap-y-1.5">
+                {legendItems.map(({ label, color }) => {
+                  const isBlank = label.trim() === "";
+                  const displayLabel = isBlank ? "N/A" : label;
+                  return (
+                    <div key={label} className="flex items-center gap-1.5">
+                      <span
+                        className="inline-block w-3 h-3 rounded-sm flex-shrink-0"
+                        style={{ backgroundColor: color }}
+                      />
+                      <span className="text-xs text-gray-800 dark:text-gray-200">
+                        {displayLabel}
+                      </span>
+                    </div>
+                  );
+                })}
+              </div>
+            )}
+          </div>
+        )}
       </Card>
     );
   }

src/components/convo-explorer/MetricsLayerConfig.tsx

@@ -4,7 +4,6 @@
 import * as React from "react";
 import { Label } from "@/components/ui/label";
 import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group";
-import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group";
 import { Input } from "@/components/ui/input";
 import {
   Select,
@@ -64,11 +63,11 @@ export function MetricsLayerConfig({
     }
   };
 
-  const handleStyleChange = (style: string) => {
-    if (config.type === "vote-count" && (style === "color" || style === "opacity")) {
-      onConfigChange?.({ type: "vote-count", style });
-    }
-  };
+  // const handleStyleChange = (style: string) => {
+  //   if (config.type === "vote-count" && (style === "color" || style === "opacity")) {
+  //     onConfigChange?.({ type: "vote-count", style });
+  //   }
+  // };
 
   const handleObsColumnChange = (column: string) => {
     setLastObsColumn(column);

src/lib/color-schemes.ts

@@ -18,3 +18,22 @@ export function createContinuousScale() {
 export function getCategoricalColor(index: number): string {
   return PALETTE_COLORS[index % PALETTE_COLORS.length];
 }
+
+// Annotation categorical palette — Tableau 20 (the standard 10 + their lighter paired variants).
+// Gives more range for obs-column annotation layers without touching the painting palette.
+export const ANNOTATION_PALETTE_COLORS: string[] = [
+  "#1f77b4", "#aec7e8", // blue
+  "#ff7f0e", "#ffbb78", // orange
+  "#2ca02c", "#98df8a", // green
+  "#d62728", "#ff9896", // red
+  "#9467bd", "#c5b0d5", // purple
+  "#8c564b", "#c49c94", // brown
+  "#e377c2", "#f7b6d2", // pink
+  "#7f7f7f", "#c7c7c7", // gray
+  "#bcbd22", "#dbdb8d", // lime
+  "#17becf", "#9edae5", // teal
+];
+
+export function getAnnotationCategoricalColor(index: number): string {
+  return ANNOTATION_PALETTE_COLORS[index % ANNOTATION_PALETTE_COLORS.length];
+}