feat: add legendsymbol.path trace attribute for custom legend icons

Allows traces to specify a custom SVG path as their legend symbol,
replacing the default colored square/line. This lets consumer apps
use plotly's native legend (with all its interaction handling) instead
of building separate React legend UIs just for custom icons.

The custom path is rendered centered in the legend item, filled with
the trace color. Runs after all default style functions and removes
their output when active.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: ryan-williams

specs/done/legend-icon-symbols.md

@@ -0,0 +1,65 @@
+# Custom legend symbols (icons)
+
+## Problem
+
+Consumer apps build entirely separate "custom" React legend UIs just to show SVG icons (pedestrian, cyclist, driver, etc.) instead of plotly's default colored squares. This duplicates 95% of the legend interaction logic (hover, pin, fade, click-to-solo) and creates a parallel code path that's harder to maintain and misses plotly-level fixes (like flush toggle rects).
+
+## Solution
+
+Added `legendsymbol.path` trace attribute — a custom SVG path string that replaces the default legend symbol.
+
+### Usage
+
+```js
+{
+    type: 'bar',
+    name: 'Pedestrians',
+    legendsymbol: {
+        path: 'M63.3,68.2l-7,11.2l5.4,14.7...',
+    },
+}
+```
+
+The path is rendered centered in the legend item area (using the same `centerTransform` as built-in symbols like bars), filled with the trace color (`marker.color` or `line.color`), with no stroke.
+
+### Architecture notes
+
+**Legend symbol rendering pipeline** (`src/components/legend/style.js`):
+
+The main `style()` function creates three sibling `<g>` layers inside each trace's legend item:
+- `g.legendfill` — fill areas (beneath)
+- `g.legendlines` — line strokes
+- `g.legendsymbols > g.legendpoints` — marker symbols (on top)
+
+Then 11 type-specific style functions run in sequence (`.each(styleBars)`, `.each(styleLines)`, etc.), each conditionally adding SVG elements to these layers based on trace type.
+
+**Custom symbol strategy**: `styleCustomSymbol` runs *last* in the chain. When `legendsymbol.path` is set, it:
+1. Removes all elements created by the default style functions (from all three layers)
+2. Renders the custom SVG `<path>` in `legendpoints` with `centerTransform`
+3. Fills with the trace color
+
+Running last is simpler than modifying every existing style function to check for custom symbols.
+
+**Key coordinate details**:
+- `centerPos = (itemWidth + itemGap * 2) / 2` ≈ 20px (default `itemWidth=30`, `itemGap=5`)
+- `centerTransform = translate(centerPos, 0)` — centers the symbol in the legend item area
+- Built-in symbols use coordinates in a ~12×12 box centered at origin (e.g. bars: `M6,6H-6V-6H6Z`)
+- Custom paths should use a similar scale, or consumer apps can adjust via `legend.itemwidth`
+
+### Files changed
+
+| File | Change |
+|------|--------|
+| `src/plots/attributes.js` | Added `legendsymbol.path` trace attribute |
+| `src/components/legend/defaults.js` | Coerce `legendsymbol.path` |
+| `src/components/legend/style.js` | `styleCustomSymbol` — renders custom path, removes defaults |
+
+### Interaction
+
+No changes needed — the existing toggle rect, hover detection, and click handling all work on the `<g class="traces">` container, not on the symbol specifically. Custom symbols are purely a rendering change.
+
+### Future work
+
+- `legendsymbol.src` — URL to an SVG file (not implemented yet)
+- Auto-scaling via `viewBox` for paths in arbitrary coordinate systems
+- `legendsymbol.color` override (currently always uses trace color)

specs/legend-icon-symbols.md

@@ -112,6 +112,7 @@ function groupDefaults(legendId, layoutIn, layoutOut, fullData) {
             }
 
             Lib.coerceFont(traceCoerce, 'legendgrouptitle.font', grouptitlefont);
+            traceCoerce('legendsymbol.path');
         }
         if((!isShape && Registry.traceIs(trace, 'bar') && layoutOut.barmode === 'stack') ||
             ['tonextx', 'tonexty'].indexOf(trace.fill) !== -1) {

src/components/legend/defaults.js

@@ -93,7 +93,37 @@ module.exports = function style(s, gd, legend) {
     .each(styleLines)
     .each(stylePoints)
     .each(styleCandles)
-    .each(styleOHLC);
+    .each(styleOHLC)
+    .each(styleCustomSymbol);
+
+    function styleCustomSymbol(d) {
+        var trace = d[0].trace;
+        var legendsymbol = trace.legendsymbol;
+        var customPath = legendsymbol && legendsymbol.path;
+        if(!customPath) return;
+
+        var thisGroup = d3.select(this);
+
+        // Remove all default symbol elements created by prior style functions
+        thisGroup.select('.legendfill').selectAll('*').remove();
+        thisGroup.select('.legendlines').selectAll('*').remove();
+        var ptgroup = thisGroup.select('g.legendpoints');
+        ptgroup.selectAll(':not(.legendcustomsymbol)').remove();
+
+        // Render custom SVG path
+        var pts = ptgroup.selectAll('path.legendcustomsymbol')
+            .data([d]);
+        pts.enter().append('path')
+            .classed('legendcustomsymbol', true)
+            .attr('transform', centerTransform);
+        pts.exit().remove();
+
+        var fillColor = (trace.marker && trace.marker.color) ||
+            (trace.line && trace.line.color) || null;
+        pts.attr('d', customPath)
+            .style('fill', fillColor)
+            .style('stroke', 'none');
+    }
 
     function styleLines(d) {
         var styleGuide = getStyleGuide(d);

src/components/legend/style.js

@@ -92,6 +92,20 @@ module.exports = {
         editType: 'style',
         description: 'Sets the width (in px or fraction) of the legend for this trace.',
     },
+    legendsymbol: {
+        path: {
+            valType: 'string',
+            dflt: '',
+            editType: 'style',
+            description: [
+                'Sets a custom SVG path to use as the legend symbol for this trace,',
+                'replacing the default colored square/line.',
+                'The path is scaled to fit the legend item dimensions',
+                'and filled with the trace color.'
+            ].join(' ')
+        },
+        editType: 'style',
+    },
     opacity: {
         valType: 'number',
         min: 0,