DataRoom Charts

A vanilla JS, CSS and HTML library for creating D3-powered chart components using custom HTML elements. Built on the dataroom-js framework with webpack for bundling.

Installation

Clone the repository:

git clone <your-repo-url>
cd dataroom-charts
npm install

Usage

The main component is <dataroom-chart>, a custom HTML element that renders various chart types using D3.js.

Basic Example

<dataroom-chart type="bar" width="600" height="400">
[
  { "label": "A", "value": 30 },
  { "label": "B", "value": 80 },
  { "label": "C", "value": 45 },
  { "label": "D", "value": 60 }
]
</dataroom-chart>

Chart Types

Bar Chart

• Type: bar or barchart
• Orientations: vertical (default), horizontal
• Data Format: Array of objects with label and value properties

<dataroom-chart type="bar" orientation="horizontal">
[
  { "label": "Category A", "value": 25 },
  { "label": "Category B", "value": 40 },
  { "label": "Category C", "value": 35 }
]
</dataroom-chart>

Scatter Plot

• Type: scatter or scatterchart
• Data Format: Array of objects with x, y, optional r (radius), c (category/color)

<dataroom-chart type="scatter" width="500" height="300">
[
  { "x": 1, "y": 10, "r": 5, "c": "Group 1" },
  { "x": 2, "y": 20, "r": 8, "c": "Group 1" },
  { "x": 3, "y": 15, "r": 6, "c": "Group 2" }
]
</dataroom-chart>

Line Graph

• Type: line, line-graph, or linegraph
• Data Format: Same as scatter plot
• Features: Connects points with lines, grouped by category
• Styling: stroke width, point radius and bubble size range are camelCase options (lineWidth, radius, minRadius, maxRadius) — see camelCase options for how to set them

<dataroom-chart type="line">
[
  { "x": 1, "y": 10, "c": "Series A" },
  { "x": 2, "y": 15, "c": "Series A" },
  { "x": 3, "y": 12, "c": "Series A" },
  { "x": 1, "y": 5, "c": "Series B" },
  { "x": 2, "y": 8, "c": "Series B" },
  { "x": 3, "y": 11, "c": "Series B" }
]
</dataroom-chart>

Candlestick Chart

• Type: candlestick or candle
• Data Format: Array of objects with OHLC values. Use date (or x/label) for the time axis and open, high, low, close (or o, h, l, c) for prices
• Features: Up candles (close >= open) use --chart-up; down candles use --chart-down. Monochrome mode renders up candles hollow and down candles filled

<dataroom-chart type="candlestick" width="700" height="450">
[
  { "date": "2024-01-01", "open": 150.00, "high": 155.20, "low": 148.50, "close": 152.30 },
  { "date": "2024-01-02", "open": 152.50, "high": 153.80, "low": 149.20, "close": 150.10 }
]
</dataroom-chart>

Heikin-Ashi Chart

• Type: heikin-ashi or heikinashi
• Data Format: Same OHLC format as candlestick
• Features: Computes Heikin-Ashi values (HA-Close = (O+H+L+C)/4, HA-Open = (prev HA-Open + prev HA-Close)/2) and renders smoothed candles

<dataroom-chart type="heikin-ashi" width="700" height="450">
[
  { "date": "2024-01-01", "open": 150.00, "high": 155.20, "low": 148.50, "close": 152.30 },
  { "date": "2024-01-02", "open": 152.50, "high": 153.80, "low": 149.20, "close": 150.10 }
]
</dataroom-chart>

Donut Chart

• Type: donut or donutchart
• Data Format: Array of objects with label and value properties
• Features: Labels can be disabled with labels="false"

<dataroom-chart type="donut" width="400" height="400">
[
  { "label": "Slice A", "value": 30 },
  { "label": "Slice B", "value": 25 },
  { "label": "Slice C", "value": 45 }
]
</dataroom-chart>

Attributes

| Attribute | Description | Default | Chart Types | |-----------|-------------|---------|-------------| | type | Chart type (bar, scatter, line, donut, candlestick, heikin-ashi) | Required | All | | width | Chart width in pixels | 400 (600 for candlestick/heikin-ashi) | All | | height | Chart height in pixels | 400 | All | | orientation | Bar chart orientation (vertical, horizontal) | vertical | Bar | | monochrome | Enable monochrome mode with patterns | false | All | | color | Override default single-series color | CSS --accent, then --hi, then palette | All | | labels | Show/hide labels (labels="false" hides) | true | Donut | | radius | Point radius | 5 (scatter), 4 (line) | Scatter, Line | | projection | isometric renders bar prisms / a raised donut | — (2D) | Bar, Donut | | data | JSON data as attribute | Content | All | | src | URL to an external JSON data file | null | All |

camelCase options

Three options are read from camelCase property names and cannot be set as HTML attributes — lineWidth (line stroke width, default 2), minRadius (minimum bubble radius, default 2) and maxRadius (maximum bubble radius, default 15), used by the scatter and line charts.

The DOM lowercases attribute names on HTML elements (both the HTML parser and setAttribute() do this per the DOM standard), so writing line-width="3" or even setAttribute('lineWidth', '3') stores a lowercased name that the renderers never read — the option is silently ignored. Set them programmatically through the element's attribute store instead, then re-render:

const chart = document.createElement('dataroom-chart');
chart.setAttribute('type', 'line');        // lowercase options work as attributes
container.appendChild(chart);              // connects + auto-initializes (attrs now exists)
chart.attrs.lineWidth = '3';               // camelCase options go through the store
chart.attrs.minRadius = '2';
chart.attrs.maxRadius = '8';
chart.render();                            // re-renders from the updated store

Data Formats

Data can be provided to the chart in three ways; when none are present the chart falls back to a built-in sample data set. getData() picks the first source that is present and does not fall through on failure: the priority is

1. data attribute (parsed as JSON)
2. src attribute (fetched and parsed as JSON)
3. element content (parsed as JSON)
4. built-in sample data

If the selected source is present but invalid — unparseable JSON or a failed src fetch — getData() returns an empty array and the chart renders a "No data provided" error instead of trying the next source.

Via Element Content (Recommended)

<dataroom-chart type="bar">
[
  { "label": "A", "value": 30 },
  { "label": "B", "value": 80 }
]
</dataroom-chart>

Valid JSON content is removed from the light DOM once the chart renders, so only the generated svg (plus its hover aside) remains.

Via Data Attribute

<dataroom-chart type="bar" data='[{"label":"A","value":30},{"label":"B","value":80}]'></dataroom-chart>

Via External JSON File (src)

You can load data from an external JSON file by providing a URL to the src attribute.

<dataroom-chart type="bar" src="path/to/your/data.json"></dataroom-chart>

Monochrome Mode

Enable monochrome mode with patterns for print-friendly or accessible charts:

<dataroom-chart type="bar" monochrome="true">
[
  { "label": "A", "value": 30 },
  { "label": "B", "value": 80 }
]
</dataroom-chart>

Monochrome mode uses SVG patterns (diagonal stripes, dots, circles, etc.) instead of colors to differentiate data series. The pattern ink is the element's computed color on its computed background-color, so it follows the surrounding theme.

Isometric Projection

Bar and donut charts accept projection="isometric" for a 2.5D render:

<dataroom-chart type="bar" projection="isometric" width="600" height="400">
[
  { "label": "A", "value": 30 },
  { "label": "B", "value": 80 },
  { "label": "C", "value": 45 }
]
</dataroom-chart>

• Bar: each datum becomes a three-face prism (top / front / right walls) drawn on the 30° isometric axes; front walls are shaded to 80% and side walls to 60% of the fill color
• Donut: the ring lifts as a raised disk while the outer walls extrude downward; back wedges show inner walls through the hole
• Other chart types ignore the attribute and render in 2D

Extracting the Rendered SVG

The chart renders into a plain light-DOM <svg> appended directly to the element (no Shadow DOM), so el.querySelector('svg').outerHTML yields self-contained markup you can ingest elsewhere. Consumers should know:

• The serialized svg carries no xmlns — stamp it before treating the markup as a standalone SVG (e.g. for <img> or data URLs)
• A sibling <aside class="chart-aside"> (hover tooltip) is created next to the svg; drop it when extracting
• Monochrome pattern fills reference <defs> inside the svg — keep the defs with the markup or the fills break
• Colors are read from the theme CSS variables at render time and baked in as literal fills; set the variables (below) before rendering to get themed output

Theming

The component reads CSS custom properties from :root at render time:

:root {
  --color-1: #440154;   /* 12-color palette, cycled per data series */
  /* ... up to --color-12 */
  --hi: #fde725;        /* highlight color */
  --accent: #9f1113;    /* preferred over --hi for single-series fills */
  --chart-up: #119f11;  /* candlestick/heikin-ashi up candles */
  --chart-down: #9f1111;/* candlestick/heikin-ashi down candles */
}

• --color-1 … --color-12: the categorical palette. Bars and donut slices cycle through it per datum (wrapping around after 12); if none are set, a built-in Viridis-inspired 12-color fallback is used.
• --accent, then --hi: single-series color for scatter dots and line strokes/points — --accent wins when both are set. The color attribute overrides both.
• --chart-up / --chart-down: candle bodies and wicks; falls back to currentColor when unset.
• Donut labels and axes use the element's computed color.

styles/variables.css ships a default set of these variables.

Development

Running the Project

npm run start

Starts the development server on port 3000.

Running the Tests

npm test

Runs the isometric-geometry test suite (test/iso-projection.test.js).

Building the Project

npm run build

Creates optimized files in the dist folder. The generated dist/index.html can be deployed directly to GitHub Pages.

Build Customization

Create a .env file to customize build output:

OUTPUT_FILE_NAME=dataroom-charts.min.js
PORT=8080

When deploying to a GitHub Pages project site (e.g. https://<user>.github.io/charts/), set the base path so asset URLs resolve correctly:

BASE_PATH=/charts/