eleventy-plugin-uncharted 0.4.1 → 0.4.3

package/README.md

@@ -2,6 +2,8 @@
 
 A CSS-based chart plugin for Eleventy. Renders charts as pure HTML/CSS.
 
+**[Full Documentation](https://uncharted.docs.seanlunsford.com/)**
+
 ## Installation
 
 ```bash
@@ -19,349 +21,22 @@ export default function(eleventyConfig) {
 }
 ```
 
-The plugin automatically copies the CSS to your output directory and injects the stylesheet link into pages that contain charts.
-
-### Options
-
-```javascript
-eleventyConfig.addPlugin(uncharted, {
-  dataDir: '_data',              // where to find CSV files (default: '_data')
-  animate: true,                 // enable animations globally (default: false)
-  cssPath: '/css/uncharted.css', // output path for stylesheet (default: '/css/uncharted.css')
-  injectCss: false,              // disable automatic CSS handling (default: true)
-  downloadData: true,            // enable download links globally (default: false)
-  dataPassthrough: true,         // copy CSV files to public path (default: false)
-  dataPath: '/data/'             // public URL path for CSV files (default: '/data/')
-});
-```
-
-If you set `injectCss: false`, you'll need to manually include the stylesheet in your layout:
-
-```html
-<link rel="stylesheet" href="/css/uncharted.css">
-```
-
-## Chart Types
-
-| Type | Description | Negative Values |
-|------|-------------|-----------------|
-| `donut` | Pie/donut chart using conic-gradient | No |
-| `stacked-bar` | Horizontal bars with stacked segments | No |
-| `stacked-column` | Vertical columns with stacked segments | Yes |
-| `dot` | Categorical dot chart with Y-axis positioning | Yes |
-| `scatter` | XY scatter plot with continuous axes | Yes (X and Y) |
-
-## Value Formatting
-
-Format displayed numbers with thousands separators, compact notation, or currency symbols.
-Raw values are preserved for calculations; only display output is affected.
-
-### Options
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `thousands` | boolean | Add commas: `1000` → `1,000` |
-| `compact` | boolean | Use suffixes: `1000` → `1K`, `1000000` → `1M` |
-| `decimals` | number | Decimal places (default: 0, or 1 if compact) |
-| `currency.symbol` | string | Currency symbol: `$`, `€`, etc. |
-| `currency.position` | string | `prefix` (default) or `suffix` |
-
-### Examples
-
-**Thousands separators:**
-
-```yaml
-format:
-  thousands: true
-# 1234567 → 1,234,567
-```
-
-**Compact notation:**
-
-```yaml
-format:
-  compact: true
-# 1500 → 1.5K, 2000000 → 2M
-```
-
-**Currency:**
-
-```yaml
-format:
-  thousands: true
-  currency:
-    symbol: "$"
-# 1234 → $1,234
-```
-
-**Scatter charts** support separate X/Y formatting:
-
-```yaml
-format:
-  x:
-    thousands: true
-  y:
-    compact: true
-    currency:
-      symbol: "$"
-```
-
-## Usage
+## Quick Example
 
-### Page Frontmatter
-
-Define charts in your page's frontmatter and reference them with the `chart` shortcode:
+Define a chart in frontmatter and render with the shortcode:
 
 ```markdown
 ---
 charts:
-  growth:
-    type: stacked-bar
-    title: Platform Growth
-    subtitle: Models by domain
-    max: 25
-    file: charts/platform-growth.csv
----
-
-{% chart "growth" %}
-```
-
-### Global Data Files
-
-Define charts in `_data/charts.json` or `_data/charts.yaml`:
-
-```json
-{
-  "releases": {
-    "type": "stacked-column",
-    "title": "Release Cadence",
-    "file": "charts/releases.csv",
-    "legend": ["Production", "Hotfix", "Beta"]
-  }
-}
-```
-
-```markdown
-{% chart "releases" %}
-```
-
-### Inline Data
-
-Embed data directly in frontmatter:
-
-```yaml
-charts:
-  issues:
-    type: donut
-    title: Issue Types
-    center:
-      value: total
-      label: Issues
-    data:
-      - label: Features
-        value: 33
-      - label: Bugs
-        value: 21
-      - label: Other
-        value: 4
-```
-
-## CSV Format
-
-CSV files use the first column as labels and subsequent columns as data series. The column names can be anything descriptive:
-
-```csv
-department,existing,new
-Finance,11,11
-Sales,16,2
-Core,8,0
-```
-
-For scatter plots, columns are positional: point label, X value, Y value, and optionally series. Column names become axis labels by default:
-
-```csv
-country,population,gdp,region
-USA,330,21,Americas
-China,1400,14,Asia
-Germany,83,4,Europe
-```
-
-This displays "population" as the X-axis title and "gdp" as the Y-axis title. Override with explicit titles:
-
-```yaml
-charts:
-  my-scatter:
-    type: scatter
-    file: charts/data.csv
-    titleX: "Population (millions)"
-    titleY: "GDP (trillions)"
-```
-
-## Negative Values
-
-Stacked column, dot, and scatter charts support negative values. When negative values are present, a zero axis line appears automatically and values are positioned relative to it.
-
-For stacked columns, positive values stack upward from zero and negative values stack downward:
-
-```csv
-quarter,Cost,Profit
-Q1,20,10
-Q2,25,-10
-Q3,15,25
-Q4,30,-10
-```
-
-The chart automatically calculates the range from the maximum positive stack to the minimum negative stack, ensuring proper scaling.
-
-## Configuration Options
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `type` | string | Chart type (required) |
-| `title` | string | Chart title |
-| `subtitle` | string | Subtitle below title |
-| `file` | string | Path to CSV file (relative to dataDir) |
-| `data` | array | Inline data array |
-| `max` | number | Maximum Y value for scaling |
-| `min` | number | Minimum Y value for scaling (column, dot) |
-| `maxX` | number | Maximum X value (scatter only) |
-| `maxY` | number | Maximum Y value (scatter only) |
-| `minX` | number | Minimum X value (scatter only) |
-| `minY` | number | Minimum Y value (scatter only) |
-| `titleX` | string | X-axis title (scatter only, defaults to column name) |
-| `titleY` | string | Y-axis title (scatter only, defaults to column name) |
-| `legend` | array | Custom legend labels |
-| `center` | object | Donut center content (`value`, `label`) |
-| `showPercentages` | boolean | Show percentages instead of values in donut legend |
-| `animate` | boolean | Override global animation setting |
-| `format` | object | Number formatting options (see Value Formatting) |
-| `rotateLabels` | boolean | Rotate X-axis labels vertically (stacked-column, dot) |
-| `downloadData` | boolean/string | Enable download link (`true`, `false`, or custom label) |
-
-## Download Links
-
-Add download links below charts so users can download the source CSV data.
-
-### Setup
-
-Enable globally in plugin options:
-
-```javascript
-eleventyConfig.addPlugin(uncharted, {
-  downloadData: true,     // show download links on all charts
-  dataPassthrough: true,  // copy CSV files to output
-  dataPath: '/data/'      // URL path for files (default)
-});
-```
-
-### Per-Chart Override
-
-```yaml
-charts:
-  # Uses global setting
-  revenue:
+  sales:
     type: stacked-bar
-    file: charts/revenue.csv
-
-  # Custom label
-  expenses:
-    type: stacked-column
-    file: charts/expenses.csv
-    downloadData: "Download expense report"
-
-  # Disable for this chart
-  internal:
-    type: donut
-    file: charts/internal.csv
-    downloadData: false
-```
-
-### Without Passthrough
-
-If `dataPassthrough` is false, you're responsible for ensuring CSV files are available at the expected URLs. The plugin generates links based on `dataPath` + `file`.
-
-## Styling
-
-### CSS Custom Properties
-
-Override the default color palette and sizing:
-
-```css
-:root {
-  --chart-color-1: #2196f3;
-  --chart-color-2: #4caf50;
-  --chart-color-3: #ffc107;
-  --chart-color-4: #ff7043;
-  --chart-color-5: #9c27b0;
-  --chart-color-6: #e91e63;
-  --chart-color-7: #009688;
-  --chart-color-8: #78909c;
-  --chart-bg: rgba(128, 128, 128, 0.15);
-  --chart-height: 12rem;           /* Height of bar/column/dot/scatter charts */
-  --chart-column-width: 1rem;      /* Min width per column */
-  --chart-donut-size: 20rem;       /* Donut chart max diameter */
-  --chart-donut-hole: 30%;         /* Donut hole size (percentage of diameter) */
-}
-```
-
-### Responsive Donut Charts
-
-Donut charts automatically adapt to their container using CSS container queries:
-
-- **Narrow containers**: Donut on top, legend wraps below horizontally
-- **Wide containers** (24rem+): Donut and legend side by side
-
-The donut scales to 80% of container width (minimum 8rem, maximum `--chart-donut-size`).
-
-### Per-Chart Styling
-
-Each chart gets a class based on its ID for targeted styling:
-
-```yaml
-charts:
-  sales-growth:
-    type: stacked-column
+    title: Quarterly Sales
     file: charts/sales.csv
-```
-
-```css
-/* Target this specific chart */
-.chart-sales-growth {
-  --chart-height: 16rem;
-  --chart-color-1: #ff6b6b;
-}
-```
-
-### Dual Class System
-
-Each chart element gets two classes for styling flexibility:
-
-1. **Ordinal**: `.chart-color-1`, `.chart-color-2`, etc.
-2. **Semantic**: `.chart-series-{slugified-name}`
-
-```css
-/* Style by position */
-.chart-color-1 { --color: #ff6b6b; }
-
-/* Style by series name */
-.chart-series-production { --color: #51cf66; }
-```
-
-## Animations
-
-Animations are CSS-based with staggered reveals. Enable globally or per-chart:
+---
 
-```javascript
-// Global
-eleventyConfig.addPlugin(uncharted, { animate: true });
+{% chart "sales" %}
 ```
 
-```yaml
-# Per-chart override
-charts:
-  static-chart:
-    type: donut
-    animate: false
-```
+Chart types: `donut`, `stacked-bar`, `stacked-column`, `dot`, `scatter`
 
-For scroll-triggered animations, add your own Intersection Observer to toggle the `.chart-animate` class.
+See the [documentation](https://uncharted.docs.seanlunsford.com/) for configuration options, styling, animations, and more.

package/css/uncharted.css

@@ -59,6 +59,7 @@
   display: flex;
   flex-direction: column;
   flex: 1;
+  min-width: 16rem;
 }
 
 .chart-title {
@@ -368,8 +369,10 @@
   flex-wrap: wrap;
   align-items: center;
   align-content: center;
+  justify-content: center;
   gap: 2rem;
   flex: 1;
+  min-width: 0;
 }
 
 .chart-donut .donut-container {
@@ -435,6 +438,7 @@
   flex-wrap: wrap;
   justify-content: center;
   gap: 0.5rem 1rem;
+  max-width: 100%;
 }
 
 /* Wide container: legend beside donut, stack items vertically
@@ -569,24 +573,36 @@
    ========================================================================== */
 
 .chart-scatter .chart-body {
-  align-items: stretch;
+  display: grid;
+  grid-template-columns: auto 1fr;
+  grid-template-rows: 1fr auto;
+}
+
+.chart-scatter .chart-y-axis {
+  grid-row: 1;
+  grid-column: 1;
 }
 
 .chart-scatter .scatter-container {
-  display: flex;
-  flex-direction: column;
-  flex: 1;
+  grid-row: 1 / -1;
+  grid-column: 2;
+  display: grid;
+  grid-template-rows: subgrid;
 }
 
 .chart-scatter .dot-area {
+  grid-row: 1;
   position: relative;
-  flex: 1;
   min-height: var(--chart-height);
   background: var(--chart-bg);
   border-radius: 3px;
   box-sizing: border-box;
 }
 
+.chart-scatter .chart-x-axis {
+  grid-row: 2;
+}
+
 /* Inner field sized to content area - dots position relative to this */
 .chart-scatter .dot-field {
   position: absolute;
@@ -867,7 +883,7 @@
   background-color: currentColor;
   opacity: 0.4;
   pointer-events: none;
-  z-index: -1;
+  z-index: 0;
 }
 
 .chart-scatter.has-negative-y .dot-field::after {
@@ -880,7 +896,7 @@
   background-color: currentColor;
   opacity: 0.4;
   pointer-events: none;
-  z-index: -1;
+  z-index: 0;
 }
 
 .chart-scatter.has-negative-x .dot-field::before {
@@ -893,7 +909,7 @@
   background-color: currentColor;
   opacity: 0.4;
   pointer-events: none;
-  z-index: -1;
+  z-index: 0;
 }
 
 /* ==========================================================================

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eleventy-plugin-uncharted",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "An Eleventy plugin that renders CSS-based charts from CSV data using shortcodes",
   "main": "eleventy.config.js",
   "type": "module",
@@ -27,7 +27,7 @@
     "type": "git",
     "url": "git+https://github.com/slunsford/uncharted.git"
   },
-  "homepage": "https://github.com/slunsford/uncharted#readme",
+  "homepage": "https://uncharted.docs.seanlunsford.com",
   "bugs": {
     "url": "https://github.com/slunsford/uncharted/issues"
   },