hpo-react-visualizer 0.0.1

package/src/HpoVisualizer.tsx

@@ -0,0 +1,210 @@
+import { type CSSProperties, useId, useMemo } from "react";
+import { BODY_VIEWBOX, DEFAULT_COLOR_NAME, ORGAN_IDS } from "./constants";
+import { createStrictColorPalette } from "./lib";
+import { OrganSvg } from "./OrganSvg";
+import { Body } from "./svg/Body";
+import type { HpoVisualizerProps, OrganConfig, OrganId, StrictColorPalette } from "./types";
+import { useOrganInteraction } from "./useOrganInteraction";
+
+/**
+ * Default positions and viewBox dimensions for each organ in the visualizer
+ * Positions are relative to Body SVG coordinate system (122x325 viewBox)
+ * viewBox: original coordinate system of the organ SVG
+ */
+const ORGAN_POSITIONS: Record<
+  OrganId,
+  { x: number; y: number; width: number; height: number; viewBox: string }
+> = {
+  growth: { x: 104, y: 1, width: 12, height: 349, viewBox: "0 0 12 349" },
+  constitutional: { x: 0, y: 0, width: 122, height: 358, viewBox: "0 0 122 358" },
+  thoracicCavity: { x: 31, y: 79, width: 60, height: 50, viewBox: "0 0 60 50" },
+  lung: { x: 35, y: 85, width: 52, height: 41, viewBox: "0 0 52 41" },
+  breast: { x: 26, y: 103, width: 70, height: 30, viewBox: "0 0 70 30" },
+  heart: { x: 50, y: 91, width: 22, height: 23, viewBox: "0 0 22 23" },
+  digestive: { x: 41, y: 119, width: 42, height: 86, viewBox: "0 0 42 86" },
+  kidney: { x: 49, y: 162, width: 24, height: 30, viewBox: "0 0 24 30" },
+  limbs: { x: 31, y: 146, width: 87, height: 203, viewBox: "0 0 87 203" },
+  integument: { x: 6, y: 91, width: 90, height: 235, viewBox: "0 0 90 235" },
+  head: { x: 35, y: 4, width: 52, height: 68, viewBox: "0 0 52 68" },
+  eye: { x: 69, y: 24, width: 12, height: 12, viewBox: "0 0 12 12" },
+  ear: { x: 34, y: 30, width: 13, height: 13, viewBox: "0 0 13 13" },
+  nervous: { x: 27, y: 4, width: 68, height: 185, viewBox: "0 0 68 185" },
+  voice: { x: 54, y: 56, width: 14, height: 22, viewBox: "0 0 14 22" },
+  metabolism: { x: 50, y: 128, width: 22, height: 21, viewBox: "0 0 22 21" },
+  cell: { x: 27, y: 185, width: 11, height: 18, viewBox: "0 0 11 18" },
+  endocrine: { x: 50, y: 64, width: 26, height: 99, viewBox: "0 0 26 99" },
+  neoplasm: { x: 81, y: 80, width: 11, height: 12, viewBox: "0 0 11 12" },
+  immune: { x: 57, y: 81, width: 30, height: 58, viewBox: "0 0 30 58" },
+  muscle: { x: 13, y: 79, width: 83, height: 182, viewBox: "0 0 83 182" },
+  prenatal: { x: 44, y: 170, width: 34, height: 24, viewBox: "0 0 34 24" },
+  blood: { x: 6, y: 182, width: 6, height: 10, viewBox: "0 0 6 10" },
+};
+
+const BACKGROUND_ORGANS: readonly OrganId[] = ["growth"] as const;
+const FOREGROUND_ORGANS: readonly OrganId[] = [
+  "constitutional",
+  "thoracicCavity",
+  "lung",
+  "breast",
+  "heart",
+  "digestive",
+  "kidney",
+  "limbs",
+  "integument",
+  "head",
+  "eye",
+  "ear",
+  "nervous",
+  "voice",
+  "metabolism",
+  "cell",
+  "endocrine",
+  "neoplasm",
+  "immune",
+  "muscle",
+  "prenatal",
+  "blood",
+] as const;
+
+/**
+ * HPO Visualizer - Interactive human organ visualization component
+ *
+ * Features:
+ * - Displays organs as interactive SVG graphics
+ * - Hover effect with visual highlighting
+ * - Click to select/deselect organs
+ * - Hover effects work independently even when an organ is selected
+ * - Exposes hover and selection state via callbacks
+ */
+export function HpoVisualizer({
+  organs,
+  visibleOrgans,
+  hoveredOrgan: controlledHovered,
+  selectedOrgan: controlledSelected,
+  onHover,
+  onSelect,
+  colorPalette: inputColorPalette,
+  width = BODY_VIEWBOX.width,
+  height = BODY_VIEWBOX.height,
+  className,
+  style,
+}: HpoVisualizerProps) {
+  const visualizerID = useId();
+
+  // Create strict color palette with all required colors and alpha values
+  const colorPalette: StrictColorPalette = useMemo(
+    () => createStrictColorPalette(inputColorPalette),
+    [inputColorPalette],
+  );
+  // Determine which organs are visible based on visibleOrgans prop
+  // Priority: visibleOrgans > organs > all organs
+  // - visibleOrgans (array): only the specified organs are visible
+  // - visibleOrgans (empty array): no organs are visible
+  // - visibleOrgans (undefined) + organs (array): organs from organs prop are visible
+  // - both undefined: all organs are visible
+  const visibleOrganIds = useMemo((): OrganId[] => {
+    if (visibleOrgans !== undefined) {
+      return visibleOrgans;
+    }
+    if (organs !== undefined) {
+      return organs.map((o) => o.id);
+    }
+    return [...ORGAN_IDS];
+  }, [visibleOrgans, organs]);
+
+  // Create organ config map for quick lookup
+  const organConfigMap = useMemo((): Map<OrganId, OrganConfig> => {
+    const map = new Map<OrganId, OrganConfig>();
+    if (organs) {
+      for (const config of organs) {
+        map.set(config.id, config);
+      }
+    }
+    return map;
+  }, [organs]);
+
+  // Use the interaction hook
+  const { handlers, isHovered, isSelected } = useOrganInteraction({
+    hoveredOrgan: controlledHovered,
+    selectedOrgan: controlledSelected,
+    onHover,
+    onSelect,
+  });
+
+  const containerStyle: CSSProperties = {
+    display: "flex",
+    justifyContent: "center",
+    alignItems: "flex-end",
+    userSelect: "none",
+    position: "relative",
+    width: width,
+    height: height,
+    ...style,
+  };
+
+  const viewBox = `0 0 ${BODY_VIEWBOX.width} ${BODY_VIEWBOX.height}`;
+  const scale = Math.min(Number(width) / BODY_VIEWBOX.width, Number(height) / BODY_VIEWBOX.height);
+  const translateX = (Number(width) - BODY_VIEWBOX.width * scale) / 2;
+
+  // Helper function to render an organ
+  const renderOrgan = (organId: OrganId, isVisible: boolean) => {
+    const position = ORGAN_POSITIONS[organId];
+    const config = organConfigMap.get(organId);
+
+    // Check if organ should be visible based on config style (different from visibleOrgans)
+    if (config?.style?.visible === false) {
+      return null;
+    }
+
+    const x = translateX + position.x * scale;
+    const y = position.y * scale;
+    const width = position.width * scale;
+    const height = position.height * scale;
+
+    return (
+      <OrganSvg
+        key={`${visualizerID}-${organId}`}
+        organId={organId}
+        config={config}
+        colorPalette={colorPalette}
+        isHovered={isHovered(organId)}
+        isSelected={isSelected(organId)}
+        onMouseEnter={() => handlers.handleMouseEnter(organId)}
+        onMouseLeave={handlers.handleMouseLeave}
+        onClick={() => handlers.handleClick(organId)}
+        x={x}
+        y={y}
+        width={width}
+        height={height}
+        viewBox={position.viewBox}
+        showOutline={config?.showOutline}
+        isVisible={isVisible}
+      />
+    );
+  };
+
+  return (
+    <div className={className} style={containerStyle}>
+      {BACKGROUND_ORGANS.map((organId) => renderOrgan(organId, visibleOrganIds.includes(organId)))}
+      {/* Background Body - rendered as nested SVG for flat structure */}
+      <svg
+        x={translateX}
+        y="0"
+        width={width}
+        height={height}
+        viewBox={viewBox}
+        style={{ position: "absolute", top: "0", left: "0" }}
+        pointerEvents="none"
+      >
+        <title>Human body</title>
+        <Body
+          colorScale={colorPalette[DEFAULT_COLOR_NAME]}
+          style={{
+            fill: "#fff",
+          }}
+        />
+      </svg>
+      {FOREGROUND_ORGANS.map((organId) => renderOrgan(organId, visibleOrganIds.includes(organId)))}
+    </div>
+  );
+}

package/src/OrganSvg.tsx

@@ -0,0 +1,141 @@
+import { type CSSProperties, useMemo } from "react";
+import {
+  DEFAULT_COLOR_NAME,
+  DEFAULT_STROKE_COLOR,
+  DEFAULT_STROKE_WIDTH,
+  TRANSITION_STYLE,
+} from "./constants";
+import { ORGAN_COMPONENTS } from "./svg";
+import type { OrganConfig, OrganId, OrganStyle, StrictColorPalette } from "./types";
+
+export interface OrganSvgWrapperProps {
+  /** Organ identifier */
+  organId: OrganId;
+  /** Organ configuration */
+  config?: OrganConfig;
+  /** Color palette to use for this organ (with guaranteed alpha values) */
+  colorPalette: StrictColorPalette;
+  /** Whether the organ is currently hovered */
+  isHovered: boolean;
+  /** Whether the organ is currently selected */
+  isSelected: boolean;
+  /** Mouse enter handler */
+  onMouseEnter: () => void;
+  /** Mouse leave handler */
+  onMouseLeave: () => void;
+  /** Click handler */
+  onClick: () => void;
+  /** X position in parent coordinate system */
+  x: number;
+  /** Y position in parent coordinate system */
+  y: number;
+  /** Width of the organ SVG viewport */
+  width: number;
+  /** Height of the organ SVG viewport */
+  height: number;
+  /** ViewBox for the organ SVG (local coordinate system) */
+  viewBox: string;
+  /** Show red outline around this organ */
+  showOutline?: boolean;
+  /** Whether the organ is visible (controls opacity for animation) */
+  isVisible?: boolean;
+}
+
+/**
+ * Merge multiple OrganStyle objects with priority (later objects override earlier)
+ */
+function mergeStyles(...styles: (OrganStyle | undefined)[]): OrganStyle {
+  const result: OrganStyle = {};
+  for (const style of styles) {
+    if (style) {
+      if (style.fill !== undefined) result.fill = style.fill;
+      if (style.stroke !== undefined) result.stroke = style.stroke;
+      if (style.strokeWidth !== undefined) result.strokeWidth = style.strokeWidth;
+      if (style.opacity !== undefined) result.opacity = style.opacity;
+      if (style.visible !== undefined) result.visible = style.visible;
+      if (style.blur !== undefined) result.blur = style.blur;
+    }
+  }
+  return result;
+}
+
+/**
+ * Wrapper component for organ SVG with interaction handling
+ */
+export function OrganSvg({
+  organId,
+  config,
+  colorPalette,
+  isHovered,
+  isSelected,
+  onMouseEnter,
+  onMouseLeave,
+  onClick,
+  x,
+  y,
+  width,
+  height,
+  viewBox,
+  showOutline = false,
+  isVisible = true,
+}: OrganSvgWrapperProps) {
+  const OrganComponent = ORGAN_COMPONENTS[organId];
+  const isActive = isHovered || isSelected;
+
+  // Compute the final style based on state and colorScheme
+  const computedStyle = useMemo((): OrganStyle => {
+    const userStyle = config?.style;
+    const strokeStyle = {
+      stroke: DEFAULT_STROKE_COLOR,
+      strokeWidth: showOutline ? DEFAULT_STROKE_WIDTH : 0,
+    };
+
+    return mergeStyles(userStyle, strokeStyle);
+  }, [config?.style, showOutline]);
+
+  const svgStyle: CSSProperties = {
+    position: "absolute",
+    left: x,
+    top: y,
+    transition: `${TRANSITION_STYLE}, visibility 0s`,
+    zIndex: isSelected ? 1 : 0,
+  };
+  const filter = isActive ? "blur(1px)" : undefined;
+
+  return (
+    <svg
+      width={width}
+      height={height}
+      viewBox={viewBox}
+      style={svgStyle}
+      filter={filter}
+      aria-label={organId}
+      overflow="visible"
+      pointerEvents="none"
+      opacity={isVisible ? 1 : 0}
+      visibility={isVisible ? "visible" : "hidden"}
+    >
+      <title>{organId}</title>
+      <g
+        role="menuitem"
+        onMouseEnter={onMouseEnter}
+        onMouseLeave={onMouseLeave}
+        onClick={onClick}
+        onKeyDown={(e) => {
+          if (e.key === "Enter" || e.key === " ") {
+            e.preventDefault();
+            onClick();
+          }
+        }}
+        cursor="pointer"
+        pointerEvents="auto"
+      >
+        <OrganComponent
+          isActive={isActive}
+          style={computedStyle}
+          colorScale={colorPalette[config?.colorName ?? DEFAULT_COLOR_NAME]}
+        />
+      </g>
+    </svg>
+  );
+}

package/src/__tests__/colorScheme.test.tsx

@@ -0,0 +1,146 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { DEFAULT_COLOR_PALETTE } from "../constants";
+import { createStrictColorPalette } from "../lib";
+import { OrganSvg } from "../OrganSvg";
+
+const strictColorPalette = createStrictColorPalette(DEFAULT_COLOR_PALETTE);
+
+describe("COLOR_PALETTES", () => {
+  it("should have blue, yellow, and gray color schemes", () => {
+    expect(DEFAULT_COLOR_PALETTE.blue).toBeDefined();
+    expect(DEFAULT_COLOR_PALETTE.yellow).toBeDefined();
+    expect(DEFAULT_COLOR_PALETTE.gray).toBeDefined();
+  });
+
+  it("each palette should have 100, 200, and 300 colors", () => {
+    for (const scheme of ["blue", "yellow", "gray"] as const) {
+      const palette = DEFAULT_COLOR_PALETTE[scheme];
+      expect(palette[100]).toBeDefined();
+      expect(palette[200]).toBeDefined();
+      expect(palette[300]).toBeDefined();
+    }
+  });
+});
+
+describe("OrganSvg", () => {
+  const defaultProps = {
+    organId: "heart" as const,
+    isHovered: false,
+    isSelected: false,
+    onMouseEnter: () => {},
+    onMouseLeave: () => {},
+    onClick: () => {},
+    x: 0,
+    y: 0,
+    width: 22,
+    height: 23,
+    viewBox: "0 0 22 23",
+  };
+
+  it("should render with default blue color scheme when no colorScheme is provided", () => {
+    render(
+      <svg>
+        <title>Heart</title>
+        <OrganSvg colorPalette={strictColorPalette} {...defaultProps} />
+      </svg>,
+    );
+
+    const organElement = screen.getByLabelText("heart");
+    expect(organElement).toBeInTheDocument();
+
+    // Check that the path has the blue base color
+    const path = organElement.querySelector("path");
+    expect(path).toHaveAttribute("fill", DEFAULT_COLOR_PALETTE.blue[200]);
+  });
+
+  it("should use yellow color scheme when specified", () => {
+    render(
+      <svg>
+        <title>Heart</title>
+        <OrganSvg
+          colorPalette={strictColorPalette}
+          {...defaultProps}
+          config={{ id: "heart", colorName: "yellow" }}
+        />
+      </svg>,
+    );
+
+    const organElement = screen.getByLabelText("heart");
+    const path = organElement.querySelector("path");
+    expect(path).toHaveAttribute("fill", DEFAULT_COLOR_PALETTE.yellow[200]);
+  });
+
+  it("should use gray color scheme when specified", () => {
+    render(
+      <svg>
+        <title>Heart</title>
+        <OrganSvg
+          colorPalette={strictColorPalette}
+          {...defaultProps}
+          config={{ id: "heart", colorName: "gray" }}
+        />
+      </svg>,
+    );
+
+    const organElement = screen.getByLabelText("heart");
+    const path = organElement.querySelector("path");
+    expect(path).toHaveAttribute("fill", DEFAULT_COLOR_PALETTE.gray[200]);
+  });
+
+  it("should use hover color when isHovered is true", () => {
+    render(
+      <svg>
+        <title>Heart</title>
+        <OrganSvg
+          colorPalette={strictColorPalette}
+          {...defaultProps}
+          isHovered={true}
+          config={{ id: "heart", colorName: "blue" }}
+        />
+      </svg>,
+    );
+
+    const organElement = screen.getByLabelText("heart");
+    const path = organElement.querySelector("path");
+    expect(path).toHaveAttribute("fill", DEFAULT_COLOR_PALETTE.blue[300]);
+  });
+
+  it("should use active color when isSelected is true", () => {
+    render(
+      <svg>
+        <title>Heart</title>
+        <OrganSvg
+          colorPalette={strictColorPalette}
+          {...defaultProps}
+          isSelected={true}
+          config={{ id: "heart", colorName: "yellow" }}
+        />
+      </svg>,
+    );
+
+    const organElement = screen.getByLabelText("heart");
+    const path = organElement.querySelector("path");
+    expect(path).toHaveAttribute("fill", DEFAULT_COLOR_PALETTE.yellow[300]);
+  });
+
+  it("should allow style override via config.style", () => {
+    const customFill = "#ff0000";
+    render(
+      <svg>
+        <title>Heart</title>
+        <OrganSvg
+          colorPalette={strictColorPalette}
+          {...defaultProps}
+          config={{ id: "heart", colorName: "blue", style: { fill: customFill } }}
+        />
+      </svg>,
+    );
+
+    const organElement = screen.getByLabelText("heart");
+    const path = organElement.querySelector("path");
+    // When not hovered/selected, user style is applied after base default
+    // But since it's merged, fill should still be customFill
+    expect(path).toHaveAttribute("fill", customFill);
+  });
+});

package/src/__tests__/createStrictColorPalette.test.ts

@@ -0,0 +1,135 @@
+import { describe, expect, it } from "vitest";
+import { DEFAULT_COLOR_PALETTE } from "../constants";
+import { createStrictColorPalette } from "../lib/createStrictColorPalette";
+import type { ColorPalette, StrictColorPalette } from "../types";
+
+describe("createStrictColorPalette", () => {
+  describe("when palette is undefined", () => {
+    it("should return StrictColorPalette with all colors from DEFAULT_COLOR_PALETTE", () => {
+      const result = createStrictColorPalette(undefined);
+
+      expect(result.blue[100]).toBe(DEFAULT_COLOR_PALETTE.blue[100]);
+      expect(result.blue[200]).toBe(DEFAULT_COLOR_PALETTE.blue[200]);
+      expect(result.blue[300]).toBe(DEFAULT_COLOR_PALETTE.blue[300]);
+      expect(result.yellow[100]).toBe(DEFAULT_COLOR_PALETTE.yellow[100]);
+      expect(result.gray[100]).toBe(DEFAULT_COLOR_PALETTE.gray[100]);
+    });
+
+    it("should generate alpha colors using color-mix", () => {
+      const result = createStrictColorPalette(undefined);
+
+      expect(result.blue.alpha[100]).toBe(
+        `color-mix(in srgb, ${DEFAULT_COLOR_PALETTE.blue[100]} 50%, transparent)`,
+      );
+      expect(result.blue.alpha[200]).toBe(
+        `color-mix(in srgb, ${DEFAULT_COLOR_PALETTE.blue[200]} 50%, transparent)`,
+      );
+      expect(result.blue.alpha[300]).toBe(
+        `color-mix(in srgb, ${DEFAULT_COLOR_PALETTE.blue[300]} 50%, transparent)`,
+      );
+    });
+  });
+
+  describe("when palette is empty object", () => {
+    it("should return StrictColorPalette with all colors from DEFAULT_COLOR_PALETTE", () => {
+      const result = createStrictColorPalette({});
+
+      expect(result.blue[100]).toBe(DEFAULT_COLOR_PALETTE.blue[100]);
+      expect(result.yellow[200]).toBe(DEFAULT_COLOR_PALETTE.yellow[200]);
+      expect(result.gray[300]).toBe(DEFAULT_COLOR_PALETTE.gray[300]);
+    });
+  });
+
+  describe("when palette has partial colors", () => {
+    it("should use provided colors and fallback to DEFAULT for missing ones", () => {
+      const customBlue = {
+        100: "#custom100",
+        200: "#custom200",
+        300: "#custom300",
+      };
+      const palette: Partial<ColorPalette> = {
+        blue: customBlue,
+      };
+
+      const result = createStrictColorPalette(palette);
+
+      // Custom blue colors should be used
+      expect(result.blue[100]).toBe("#custom100");
+      expect(result.blue[200]).toBe("#custom200");
+      expect(result.blue[300]).toBe("#custom300");
+
+      // Missing yellow and gray should fallback to DEFAULT
+      expect(result.yellow[100]).toBe(DEFAULT_COLOR_PALETTE.yellow[100]);
+      expect(result.gray[100]).toBe(DEFAULT_COLOR_PALETTE.gray[100]);
+    });
+
+    it("should generate alpha for custom colors using color-mix", () => {
+      const customBlue = {
+        100: "#custom100",
+        200: "#custom200",
+        300: "#custom300",
+      };
+      const palette: Partial<ColorPalette> = {
+        blue: customBlue,
+      };
+
+      const result = createStrictColorPalette(palette);
+
+      expect(result.blue.alpha[100]).toBe("color-mix(in srgb, #custom100 50%, transparent)");
+      expect(result.blue.alpha[200]).toBe("color-mix(in srgb, #custom200 50%, transparent)");
+    });
+  });
+
+  describe("when palette has alpha colors", () => {
+    it("should use provided alpha colors instead of generating", () => {
+      const customAlpha = {
+        100: "#alpha100",
+        200: "#alpha200",
+        300: "#alpha300",
+      };
+      const palette: Partial<ColorPalette> = {
+        blue: {
+          100: "#blue100",
+          200: "#blue200",
+          300: "#blue300",
+          alpha: customAlpha,
+        },
+      };
+
+      const result = createStrictColorPalette(palette);
+
+      expect(result.blue.alpha[100]).toBe("#alpha100");
+      expect(result.blue.alpha[200]).toBe("#alpha200");
+      expect(result.blue.alpha[300]).toBe("#alpha300");
+    });
+  });
+
+  describe("return type validation", () => {
+    it("should return a valid StrictColorPalette", () => {
+      const result = createStrictColorPalette(undefined);
+
+      // Check that all required properties exist
+      const colorNames = ["blue", "yellow", "gray"] as const;
+      const steps = [100, 200, 300] as const;
+
+      for (const colorName of colorNames) {
+        expect(result[colorName]).toBeDefined();
+
+        for (const step of steps) {
+          expect(result[colorName][step]).toBeDefined();
+          expect(typeof result[colorName][step]).toBe("string");
+        }
+
+        expect(result[colorName].alpha).toBeDefined();
+        for (const step of steps) {
+          expect(result[colorName].alpha[step]).toBeDefined();
+          expect(typeof result[colorName].alpha[step]).toBe("string");
+        }
+      }
+
+      // Type check - this should compile without errors
+      const _typeCheck: StrictColorPalette = result;
+      expect(_typeCheck).toBeDefined();
+    });
+  });
+});