Semiotic 3.1.0 — Click-Testing Fixes & Streaming Regression Suite

[emeeks]

Comprehensive fix pass addressing 61 issues discovered during manual click-testing of the docs
site. Fixes span the entire library: streaming color pipeline, tooltip content, layout
algorithms, dark mode, hit testing, and 25+ docs page improvements. Adds a Playwright
integration test suite to prevent regressions.

74 files changed, +3238 / -630 lines. 1834 unit tests passing, 0 TypeScript errors.

Streaming Color Pipeline (root cause fix)

• Grey fills on push API — When using the push API (ref.current.push()), HOC charts passed
  undefined color scales to their style functions, causing all fills to fall back to hash-based
  grey. Fixed by:
  • HOC pieceStyle/pointStyle/lineStyle functions now omit fill/stroke when colorScale is
    unavailable
  • OrdinalPipelineStore.resolvePieceStyle fills in from the frame's color scheme when HOC
    returns no fill
  • PipelineStore.resolveLineStyle/resolveAreaStyle/point scene builder do the same for XY
    charts
  • New resolveGroupColor method provides palette assignment for streaming groups
• Affected charts fixed: StackedBarChart, PieChart, DonutChart, GroupedBarChart, BubbleChart,
  StackedAreaChart, AreaChart, LineChart, Scatterplot, QuadrantChart, ChordDiagram
• Streaming legends — New useStreamingLegend hook discovers categories from pushed data and
  builds legends dynamically. Integrated into StackedBarChart, PieChart, DonutChart,
  GroupedBarChart.

Runtime Errors Fixed

• LineChart infinite re-render loop — Circular dependency between useEffect →
  setSegmentAwareStyle → baseLineStyle → colorScale → statisticalResult. Fixed by guarding
  statistical effect to only run when forecast/anomaly is present, and deriving
  effectiveLineStyle without unnecessary state.
• createColorScale crash on undefined data — Added null guards (d?. + .filter(v => v != null))
  so push API charts with sparse data don't throw.
• OrdinalSVGOverlay duplicate React keys — Keys now include category/group for uniqueness
  across stacked/grouped layouts.

Tooltip Improvements

• Area/StackedArea tooltips showing "-" — hitTestAreaPath now extracts the specific data point
  at the hover index (like hitTestLine does) instead of returning the entire data array.
• Ordinal frame tooltips — Default tooltip now shows category + value using
  __oAccessor/__rAccessor metadata.
• Geo chart tooltips — ChoroplethMap shows country names (not numeric IDs),
  ProportionalSymbolMap shows formatted metrics with labels, FlowMap shows source → target with
  values.

Layout & Interaction

• Force graph centering — Added forceCenter to simulation, strengthened forceX/forceY, clamped
  node positions to canvas bounds. Fixed finalizeLayout overwriting force-computed positions
  from stale bounding boxes during streaming warm-starts.
• Streaming force refresh — Force simulation now runs on topology changes during push API
  streaming.
• FIFO category ordering — Streaming ordinal charts preserve insertion order instead of
  re-sorting by value (fixes violin/histogram flicker).
• Edge hit areas — Expanded to 5px minimum tolerance across XY lines, network edges (bezier +
  path), and geo lines. Added pointToSegmentDist for accurate perpendicular distance
  calculation.
• Sankey crossing reduction — Added barycenter-based initial node ordering before iterative
  relaxation.
• QuadrantChart streaming — Fixed quadrant backgrounds disappearing after first point; points
  now auto-color by quadrant when no colorBy provided.
• Anti-meridian line handling — Geo lines that wrap across the projection edge are split into
  segments with smooth opacity fades.
• Distance cartogram centering — Center node is pinned to viewport center during streaming.
• Orthographic drag jank — Pointer-move rotations now coalesce via pendingRotationRef,
  applying once per rAF frame.

Visual / Dark Mode

• Orbit diagram — Ring/connecting lines changed from currentColor (invisible on canvas) to
  rgba(128,128,128,0.35). Root nodes use scheme color instead of grey.
• Treemap/CirclePack labels — Luminance-based contrast text color (white on dark fills, dark
  on light fills). Treemap parent labels positioned at top-left of rectangle.
• Dark mode fixes — Serialization page text, streaming system model background, candlestick
  wick color, uncertainty tooltip background.

Docs Pages (25+ fixes)

• Home page: meaningful tooltips on bar chart, bubble chart, network graph (degree centrality)
• Chart pages: streaming sankey pastel colors, chord multi-color fix, ScatterplotMatrix
  colored diagonal histograms
• Features: highlight hover uses distinct red line, more distinctive custom theme, top/bottom
  legend examples, chart container year controls work, responsive frame data fix, styling offset
  fix, linked dashboard color consistency
• Cookbook: candlestick dark mode, uncertainty tooltip dark mode, isotype chart person icons,
  radar/isotype duplicate key fix
• Recipes: network explorer renders (fixed .data wrapper access), Rosling bubble
  annotations/extent/tooltip, benchmark log scale fix, forecast sparkline card
• Playground: force graph sparse preset parameters, choropleth sizing
• DocumentFrame: added 100+ missing prop names to processNodes
• Tile map: production provider documentation
• CLAUDE.md: legend positioning advice for narrow/short charts, tile map production guidance

Integration Tests

New streaming regression test suite (streaming-regression.spec.ts, 20+ tests):

• Color regression — Samples canvas pixels to verify colored fills (saturation > 0.1) across 8
  streaming chart types
• Legend regression — Verifies legend items appear after push API data arrives (4 chart types)
• Tooltip regression — Hovers area chart and asserts tooltip contains numeric values, not
  dashes
• Stability — LineChart streaming pushes 50 points with no "Maximum update depth" errors
• Force centering — Verifies drawn content centroid is within 30% of canvas center
• Error-free rendering — All 11 test fixtures render without JS errors

[Copilot]

Pull request overview

This PR is a broad stabilization pass for Semiotic 3.1.0 focused on fixing streaming/push-API regressions found during docs click-testing, improving hit-testing and tooltips, and adding Playwright streaming regression tests to prevent recurrence.

Changes:

• Fix push-API/streaming color fallbacks across XY/ordinal/network/geo rendering and legends (including a new streaming legend hook).
• Improve interaction robustness: hit testing tolerances, tooltip datum extraction, geo anti-meridian line splitting with edge fading, and force-layout centering/clamping.
• Add streaming regression integration tests and update docs/examples to match corrected APIs and behaviors.

Reviewed changes

Copilot reviewed 73 out of 74 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
src/vendor/sankey-plus/index.js	Adds barycenter-based ordering heuristic to reduce sankey crossings when no custom sort is provided.
src/components/stream/renderers/lineCanvasRenderer.ts	Adds edge-fade canvas rendering path for anti-meridian split geo line segments.
src/components/stream/networkTypes.ts	Adds labelMode option to streaming network config/props types.
src/components/stream/layouts/orbitLayoutPlugin.ts	Adjusts orbit ring/edge styling away from currentColor to canvas-safe RGBA.
src/components/stream/layouts/hierarchyLayoutPlugin.ts	Adds contrast-aware label colors and labelMode handling; improves parent/leaf label placement.
src/components/stream/layouts/forceLayoutPlugin.ts	Introduces force centering/clamping and resets bounding boxes to avoid stale finalizeLayout overrides.
src/components/stream/layouts/forceLayoutPlugin.test.ts	Adds/updates tests for centering, clamping, warm-start relayout, and bounding-box reset behavior.
src/components/stream/StreamOrdinalFrame.tsx	Improves default ordinal tooltips using accessor hints; adds swarm/point tooltip behavior.
src/components/stream/StreamNetworkFrame.tsx	Plumbs labelMode through to the network pipeline config.
src/components/stream/StreamGeoFrame.tsx	Coalesces orthographic drag rotations via a pending rotation ref applied per animation frame.
src/components/stream/SceneToSVG.tsx	Fixes duplicate React keys for ordinal SVG overlay nodes in stacked/grouped layouts.
src/components/stream/PipelineStore.ts	Improves log-scale padding, streaming color fallbacks for line/area/points, and adds resolveGroupColor.
src/components/stream/OrdinalPipelineStore.ts	Preserves FIFO category order for push-API data, prunes evicted categories, and fills missing piece colors from scheme.
src/components/stream/OrdinalPipelineStore.test.ts	Adds tests for push-API FIFO ordering and category pruning/clear behavior.
src/components/stream/NetworkCanvasHitTester.ts	Improves edge hit testing using isPointInPath and isPointInStroke with tolerances.
src/components/stream/GeoPipelineStore.ts	Splits anti-meridian-wrapping lines into segments with fade markers; re-centers distance cartogram around center node.
src/components/stream/GeoCanvasHitTester.ts	Enforces a minimum 5px hit tolerance for geo line hit testing.
src/components/stream/CanvasHitTester.ts	Improves line hit testing via point-to-segment distance; fixes area tooltip datum extraction to return the hovered point.
src/components/charts/xy/StackedAreaChart.tsx	Avoids forcing grey fills when colorScale is unavailable (push API); lets frame resolve colors.
src/components/charts/xy/ScatterplotMatrix.tsx	Adds category-colored diagonal histograms when colorBy is a string field.
src/components/charts/xy/Scatterplot.tsx	Avoids applying fill when colorScale is missing in push mode; falls back to frame palette.
src/components/charts/xy/QuadrantChart.tsx	Adds quadrant-based default coloring when no colorBy is provided; makes background rendering resilient during streaming.
src/components/charts/xy/LineChart.tsx	Guards statistical effects (forecast/anomaly) to prevent infinite re-render loops; improves push-API color behavior.
src/components/charts/xy/BubbleChart.tsx	Avoids forcing fill when colorScale is missing in push mode; relies on frame palette.
src/components/charts/xy/AreaChart.tsx	Avoids forcing fill/stroke when colorScale is missing in push mode; relies on frame palette.
src/components/charts/shared/useStreamingLegend.ts	New hook to build legends dynamically from pushed data and keep legend colors stable in push mode.
src/components/charts/shared/colorUtils.ts	Fixes createColorScale to ignore null/undefined colorBy values (prevents push-mode crashes).
src/components/charts/shared/annotationRules.tsx	Fixes React key collisions for annotation-generated circles.
src/components/charts/ordinal/StackedBarChart.tsx	Integrates streaming legend discovery for push API and avoids forced fill when colorScale is missing.
src/components/charts/ordinal/PieChart.tsx	Integrates streaming legend discovery for push API and avoids forced fill when colorScale is missing.
src/components/charts/ordinal/GroupedBarChart.tsx	Integrates streaming legend discovery for push API and avoids forced fill when colorScale is missing.
src/components/charts/ordinal/DonutChart.tsx	Integrates streaming legend discovery for push API and avoids forced fill when colorScale is missing.
src/components/charts/network/Treemap.tsx	Plumbs labelMode to hierarchy streaming renderer for treemap label control.
src/components/charts/network/OrbitDiagram.tsx	Uses scheme color for root nodes and canvas-safe edge styling for dark mode readability.
src/components/charts/network/ChordDiagram.tsx	Skips passing HOC node/edge styles when push-mode has no inferred nodes, allowing plugin palette to apply.
src/components/charts/network/ChordDiagram.test.tsx	Adds tests ensuring push-mode doesn’t pass nodeStyle/edgeStyle when no data is present.
src/components/charts/geo/ProportionalSymbolMap.tsx	Improves default tooltip content with labels and numeric formatting.
src/components/charts/geo/FlowMap.tsx	Makes default tooltip handle areas, flows, and nodes with formatted values.
src/components/charts/geo/ChoroplethMap.tsx	Improves tooltip name resolution and numeric formatting for choropleths.
src/components/ChartContainer.tsx	Centers chart body content via flex layout and improves fullscreen sizing alignment.
package.json	Adds streaming regression examples page to serve-examples.
integration-tests/streaming-regression.spec.ts	New Playwright regression suite covering streaming color/legend/tooltip/stability/force-centering/error-free rendering.
integration-tests/streaming-regression-examples/index.js	Adds push-mode fixtures for multiple chart types used by Playwright streaming regression tests.
integration-tests/streaming-regression-examples/index.html	Adds a dedicated page to host streaming regression fixtures.
integration-tests/index.html	Links the new streaming regression examples suite from the integration test index.
docs/src/process.js	Expands prop name processing list for docs tooling (many missing prop names added).
docs/src/pages/recipes/RoslingBubbleChartPage.js	Sets explicit extents for log-scale rosling example for stable view.
docs/src/pages/recipes/NetworkExplorerPage.js	Updates recipe to use .data wrapper access and new nodeSize/nodeLabel API.
docs/src/pages/recipes/KpiCardSparklinePage.js	Updates sparkline usage to StreamXYFrame data/chartType and adds forecast sparkline example with bounds.
docs/src/pages/playground/ForceDirectedGraphPlayground.js	Tweaks sparse dataset defaults for better force stability.
docs/src/pages/playground/ChoroplethMapPlayground.js	Adjusts default height and adds fitPadding for better sizing.
docs/src/pages/features/ThemingPage.js	Updates custom theme example (colors + typography).
docs/src/pages/features/StylingPage.js	Makes background/foreground graphics responsive to size/margins via functions.
docs/src/pages/features/StreamingSystemModelPage.js	Fixes background color for dark mode by using CSS variables.
docs/src/pages/features/SerializationPage.js	Fixes dark mode text/background colors in config round-trip UI.
docs/src/pages/features/ResponsivePage.js	Fixes responsive example by specifying size explicitly.
docs/src/pages/features/LegendsPage.js	Adds legend positioning documentation + live examples.
docs/src/pages/features/InteractionPage.js	Adjusts highlight hover styling for stronger visual distinction.
docs/src/pages/features/ChartModesPage.js	Adds CategoryColorProvider to keep colors consistent across linked dashboard charts.
docs/src/pages/features/ChartContainersPage.js	Improves container examples (height alignment, year selector wiring, code updates).
docs/src/pages/features/AnnotationsPage.js	Adjusts callout annotation offsets in docs example.
docs/src/pages/cookbook/IsotypeChartPage.js	Updates narrative and code snippets to match new isotype implementation.
docs/src/pages/cookbook/CandlestickChartPage.js	Adjusts wick color for dark mode legibility.
docs/src/pages/charts/TileMapPage.js	Adds production tile provider guidance and API key handling advice.
docs/src/pages/charts/SankeyDiagramPage.js	Adds a pastel color scheme for streaming sankey examples.
docs/src/pages/charts/OrbitDiagramPage.js	Clarifies tooltip behavior for animated vs static orbit diagrams.
docs/src/examples/recipes/RoslingBubbleChart.js	Fixes tooltip styling and sets explicit extents for log-scale stability.
docs/src/examples/recipes/NetworkExplorer.js	Updates example to use .data wrapper access and new labeling/size APIs.
docs/src/examples/recipes/KpiCardSparkline.js	Adds forecast KPI sparkline example using bounds + grouped lines.
docs/src/examples/UncertaintyVisualization.js	Fixes tooltip styling for dark mode via CSS variables.
docs/src/examples/IsotypeChart.js	Replaces StreamOrdinalFrame-based icon bar with a direct responsive SVG implementation.
docs/src/examples/CandlestickChart.js	Adjusts wick color for dark mode legibility.
docs/src/Landing.js	Improves gallery tooltips and adds degree-centrality tooltip for network graph.
CLAUDE.md	Updates legend positioning and tile map production guidance in contributor notes.

[Copilot]

Pull request overview

Copilot reviewed 73 out of 74 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 73 out of 74 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 78 out of 79 changed files in this pull request and generated 3 comments.