# Plotly.js Property Mappings

This document lists which `chartOptions` properties correspond to Plotly.js properties.

## Overview

- **Total chartOptions**: 109 properties
- **Mapped to Plotly.js**: 37 properties (34%)
- **Protobi-specific**: 72 properties (66%)

## Plotly.js Layout Properties (28 properties)

These properties map to Plotly's `layout` object, which controls the overall chart appearance.

### Dimensions & Spacing
| Protobi Property | Plotly Property | Documentation |
|-----------------|-----------------|---------------|
| `chartOptions.width` | `layout.width` | [📖](https://plotly.com/javascript/reference/layout/#layout-width) |
| `chartOptions.height` | `layout.height` | [📖](https://plotly.com/javascript/reference/layout/#layout-height) |
| `chartOptions.margin.l` | `layout.margin.l` | [📖](https://plotly.com/javascript/reference/layout/#layout-margin-l) |
| `chartOptions.margin.r` | `layout.margin.r` | [📖](https://plotly.com/javascript/reference/layout/#layout-margin-r) |
| `chartOptions.margin.t` | `layout.margin.t` | [📖](https://plotly.com/javascript/reference/layout/#layout-margin-t) |
| `chartOptions.margin.b` | `layout.margin.b` | [📖](https://plotly.com/javascript/reference/layout/#layout-margin-b) |

### Legend
| Protobi Property | Plotly Property | Documentation |
|-----------------|-----------------|---------------|
| `chartOptions.showlegend` | `layout.showlegend` | [📖](https://plotly.com/javascript/reference/layout/#layout-showlegend) |
| `chartOptions.legend.orientation` | `layout.legend.orientation` | [📖](https://plotly.com/javascript/reference/layout/#layout-legend-orientation) |
| `chartOptions.legend.xanchor` | `layout.legend.xanchor` | [📖](https://plotly.com/javascript/reference/layout/#layout-legend-xanchor) |
| `chartOptions.legend.yanchor` | `layout.legend.yanchor` | [📖](https://plotly.com/javascript/reference/layout/#layout-legend-yanchor) |

### Bar Charts
| Protobi Property | Plotly Property | Documentation |
|-----------------|-----------------|---------------|
| `chartOptions.barmode` | `layout.barmode` | [📖](https://plotly.com/javascript/reference/layout/#layout-barmode) |

### Font
| Protobi Property | Plotly Property | Documentation |
|-----------------|-----------------|---------------|
| `chartOptions.fontFamily` | `layout.font.family` | [📖](https://plotly.com/javascript/reference/layout/#layout-font-family) |

### X-Axis
| Protobi Property | Plotly Property | Documentation |
|-----------------|-----------------|---------------|
| `chartOptions.xaxis.visible` | `layout.xaxis.visible` | [📖](https://plotly.com/javascript/reference/layout/xaxis/#layout-xaxis-visible) |
| `chartOptions.xaxis.showticklabels` | `layout.xaxis.showticklabels` | [📖](https://plotly.com/javascript/reference/layout/xaxis/#layout-xaxis-showticklabels) |
| `chartOptions.xaxis.tickangle` | `layout.xaxis.tickangle` | [📖](https://plotly.com/javascript/reference/layout/xaxis/#layout-xaxis-tickangle) |
| `chartOptions.xaxis.tickformat` | `layout.xaxis.tickformat` | [📖](https://plotly.com/javascript/reference/layout/xaxis/#layout-xaxis-tickformat) |
| `chartOptions.xaxis.tickfont` | `layout.xaxis.tickfont` | [📖](https://plotly.com/javascript/reference/layout/xaxis/#layout-xaxis-tickfont) |
| `chartOptions.xaxis.autorange` | `layout.xaxis.autorange` | [📖](https://plotly.com/javascript/reference/layout/xaxis/#layout-xaxis-autorange) |
| `chartOptions.xaxis.rangemode` | `layout.xaxis.rangemode` | [📖](https://plotly.com/javascript/reference/layout/xaxis/#layout-xaxis-rangemode) |

### Y-Axis
| Protobi Property | Plotly Property | Documentation |
|-----------------|-----------------|---------------|
| `chartOptions.yaxis.visible` | `layout.yaxis.visible` | [📖](https://plotly.com/javascript/reference/layout/yaxis/#layout-yaxis-visible) |
| `chartOptions.yaxis.showticklabels` | `layout.yaxis.showticklabels` | [📖](https://plotly.com/javascript/reference/layout/yaxis/#layout-yaxis-showticklabels) |
| `chartOptions.yaxis.tickangle` | `layout.yaxis.tickangle` | [📖](https://plotly.com/javascript/reference/layout/yaxis/#layout-yaxis-tickangle) |
| `chartOptions.yaxis.tickfont` | `layout.yaxis.tickfont` | [📖](https://plotly.com/javascript/reference/layout/yaxis/#layout-yaxis-tickfont) |
| `chartOptions.yaxis.autorange` | `layout.yaxis.autorange` | [📖](https://plotly.com/javascript/reference/layout/yaxis/#layout-yaxis-autorange) |
| `chartOptions.yaxis.rangemode` | `layout.yaxis.rangemode` | [📖](https://plotly.com/javascript/reference/layout/yaxis/#layout-yaxis-rangemode) |
| `chartOptions.yaxis.nticks` | `layout.yaxis.nticks` | [📖](https://plotly.com/javascript/reference/layout/yaxis/#layout-yaxis-nticks) |

### Uniform Text
| Protobi Property | Plotly Property | Documentation |
|-----------------|-----------------|---------------|
| `chartOptions.uniformtext.mode` | `layout.uniformtext.mode` | [📖](https://plotly.com/javascript/reference/layout/#layout-uniformtext-mode) |
| `chartOptions.uniformtext.minsize` | `layout.uniformtext.minsize` | [📖](https://plotly.com/javascript/reference/layout/#layout-uniformtext-minsize) |

## Plotly.js Trace Properties (9 properties)

These properties map to Plotly's trace objects, which control individual data series appearance.

### General Trace Properties
| Protobi Property | Plotly Property | Documentation |
|-----------------|-----------------|---------------|
| `chartOptions.orientation` | `trace.orientation` | [📖](https://plotly.com/javascript/reference/bar/#bar-orientation) |
| `chartOptions.textposition` | `trace.textposition` | [📖](https://plotly.com/javascript/reference/bar/#bar-textposition) |

### Pie Chart Properties
| Protobi Property | Plotly Property | Documentation |
|-----------------|-----------------|---------------|
| `chartOptions.series.textinfo` | `trace.textinfo` | [📖](https://plotly.com/javascript/reference/pie/#pie-textinfo) |
| `chartOptions.series.hole` | `trace.hole` | [📖](https://plotly.com/javascript/reference/pie/#pie-hole) |
| `chartOptions.series.insidetextorientation` | `trace.insidetextorientation` | [📖](https://plotly.com/javascript/reference/pie/#pie-insidetextorientation) |
| `chartOptions.series.direction` | `trace.direction` | [📖](https://plotly.com/javascript/reference/pie/#pie-direction) |

### Styling Properties
| Protobi Property | Plotly Property | Documentation |
|-----------------|-----------------|---------------|
| `chartOptions.series.marker` | `trace.marker` | [📖](https://plotly.com/javascript/reference/bar/#bar-marker) |
| `chartOptions.series.line` | `trace.line` | [📖](https://plotly.com/javascript/reference/scatter/#scatter-line) |

### Interaction Properties
| Protobi Property | Plotly Property | Documentation |
|-----------------|-----------------|---------------|
| `chartOptions.series.hoverinfo` | `trace.hoverinfo` | [📖](https://plotly.com/javascript/reference/bar/#bar-hoverinfo) |

## Protobi-Specific Properties (72 properties)

These properties are **not** part of Plotly.js and are handled by Protobi's custom charting logic.

### Data Processing
- `chartOptions.coalesceBars` - Simplify graph by showing summary stats
- `chartOptions.coalesceSortLast` - Combine values marked as 'sortLast'
- `chartOptions.coalesceSortLastLabel` - Label for sortLast category
- `chartOptions.coalesceStats` - Simplify using summary stats
- `chartOptions.limit` - Maximum values to display
- `chartOptions.maxRows` - Maximum rows to display
- `chartOptions.minBasis` - Show only values with frequencies > minBasis
- `chartOptions.minPercent` - Show only values with percent > minPercent
- `chartOptions.transposeData` - Transpose data
- `chartOptions.recursive` - Recursive processing

### Display Options
- `chartOptions.expandCompactGroups` - Expand compact groups
- `chartOptions.showBasisInTitles` - Show N size in labels
- `chartOptions.showKeys` - Show element keys
- `chartOptions.showOverall` - Include all respondents in crosstabs
- `chartOptions.showSubtitles` - Show banner element titles
- `chartOptions.showTitles` - Show titles
- `chartOptions.showValuesAbove` - Show values above threshold
- `chartOptions.hideRedundantBasis` - Hide redundant basis

### Statistical Tests
- `chartOptions.showSignificance` - Whether to show significance tests
- `chartOptions.testPairedSamples` - Use paired samples tests
- `chartOptions.testUsingPairedSamples` - Use paired samples if possible

### Layout & Sizing
- `chartOptions.barWidth` - Bar width
- `chartOptions.columnWidth` - Column width
- `chartOptions.rowHeight` - Row height
- `chartOptions.numCols` - Number of columns in worksheet
- `chartOptions.numRows` - Number of rows in worksheet
- `chartOptions.preferredWidthColumn` - Default column width
- `chartOptions.preferredWidthLabel` - Default label width
- `chartOptions.preferredWidthMajor` - Major width
- `chartOptions.preferredWidthMinor` - Minor width

### Colors & Styling
- `chartOptions.color` - Element icon color
- `chartOptions.colorBy` - Color strategy
- `chartOptions.leftColor` - Left side color
- `chartOptions.rightColor` - Right side color
- `chartOptions.legendLabelColors` - Vary legend label colors
- `chartOptions.opacity` - Transparency (0-1)
- `chartOptions.fontWeight` - Font weight

### Text & Labels
- `chartOptions.dataLabels.showVal` - Show data values
- `chartOptions.dataLabelsOutside` - Show labels outside
- `chartOptions.dataValues` - Show data values on chart
- `chartOptions.enquote` - Quote text
- `chartOptions.wrap` - Wrap or truncate text
- `chartOptions.leftTitle` - Left side title
- `chartOptions.rightTitle` - Right side title

### Legend
- `chartOptions.legendLabelsAnchor` - Vertical alignment of legend labels
- `chartOptions.legendLabelsHeight` - Legend labels height (px)
- `chartOptions.legendSymbolHeight` - Legend symbols height (px)
- `chartOptions.showLegendSymbols` - Show series icons
- `chartOptions.nestCategoryAndLegend` - Nest category and legends
- `chartOptions.swapCategoryAndLegend` - Swap variables for category/legend

### Word Cloud
- `chartOptions.maxFontSize` - Size of most frequent word
- `chartOptions.minFontSize` - Minimum word size
- `chartOptions.maxWeight` - Weight of most frequent word
- `chartOptions.maxWords` - Maximum words to show
- `chartOptions.scaleToMaxFontSize` - Scale to maxFontSize vs fit margin
- `chartOptions.shuffle` - Randomly shuffle positions
- `chartOptions.shape` - Word cloud shape (circle, square, etc.)
- `chartOptions.drawOutOfBound` - Show words extending out of bounds

### Export Settings
- `chartOptions.powerpoint.exportAs` - Export as 'native', 'shapes', or 'image'
- `chartOptions.powerpoint.renderTableAsShapes` - Render table as shapes
- `chartOptions.plotlyType` - Plotly chart type to render

### Sankey Diagram
- `chartOptions.nodePadding` - Padding between nodes
- `chartOptions.nodeWidth` - Width of nodes

### Interaction
- `chartOptions.paging` - Enable paging
- `chartOptions.pagesize` - Page size
- `chartOptions.selecting` - Enable selection
- `chartOptions.sorting` - Sorting mode

### Formatting
- `chartOptions.percentFormat` - Percent format
- `chartOptions.horizontal` - Horizontal vs vertical orientation

### Other
- `chartOptions.left` - Left position
- `chartOptions.right` - Right position
- `chartOptions.showBars` - Whether to show bars

## Usage Examples

### Checking if a property is a Plotly property

```javascript
import properties from './properties-dict-enhanced.json';

const prop = properties['chartOptions.barmode'];
if (prop.plotly) {
  console.log(`This maps to Plotly: ${prop.plotly.property}`);
  console.log(`Documentation: ${prop.plotly.url}`);
} else {
  console.log('This is a Protobi-specific property');
}
```

### Getting all Plotly-mapped properties

```javascript
const plotlyProps = Object.entries(properties)
  .filter(([k, v]) => v.plotly)
  .map(([k, v]) => ({
    protobi: k,
    plotly: v.plotly.property,
    url: v.plotly.url
  }));
```

### Building Plotly config from Protobi chartOptions

```javascript
function buildPlotlyLayout(chartOptions) {
  const layout = {};

  // Map Protobi properties to Plotly layout
  if (chartOptions.width) layout.width = chartOptions.width;
  if (chartOptions.height) layout.height = chartOptions.height;
  if (chartOptions.barmode) layout.barmode = chartOptions.barmode;
  if (chartOptions.showlegend !== undefined) layout.showlegend = chartOptions.showlegend;

  // Map margin properties
  if (chartOptions.margin) {
    layout.margin = {
      l: chartOptions.margin.l,
      r: chartOptions.margin.r,
      t: chartOptions.margin.t,
      b: chartOptions.margin.b
    };
  }

  // Map xaxis properties
  if (chartOptions.xaxis) {
    layout.xaxis = { ...chartOptions.xaxis };
  }

  // Map yaxis properties
  if (chartOptions.yaxis) {
    layout.yaxis = { ...chartOptions.yaxis };
  }

  return layout;
}
```

---

*This document is automatically maintained based on properties-dict-enhanced.json*
