@walterra/pi-charts 0.0.1 → 0.0.3

package/README.md

@@ -5,16 +5,10 @@ Vega-Lite chart extension for [pi coding agent](https://github.com/badlogic/pi-m
 ## Installation
 
 ```bash
-pi install @walterra/pi-charts
+pi install npm:@walterra/pi-charts
 ```
 
-Or add to your pi config manually:
-
-```bash
-npm install @walterra/pi-charts
-```
-
-Then in your pi config, add the extension path.
+This installs the package globally and adds it to your pi settings.
 
 ## Features
 
@@ -29,13 +23,13 @@ Renders a Vega-Lite specification as a PNG image.
 
 ### Parameters
 
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `spec` | string | ✅ | Vega-Lite JSON specification |
-| `tsv_data` | string | | Optional TSV data to replace spec.data.values |
-| `width` | number | | Chart width in pixels (default: 600) |
-| `height` | number | | Chart height in pixels (default: 400) |
-| `save_path` | string | | Optional file path to save the PNG |
+| Parameter   | Type   | Required | Description                                   |
+| ----------- | ------ | -------- | --------------------------------------------- |
+| `spec`      | string | ✅       | Vega-Lite JSON specification                  |
+| `tsv_data`  | string |          | Optional TSV data to replace spec.data.values |
+| `width`     | number |          | Chart width in pixels (default: 600)          |
+| `height`    | number |          | Chart height in pixels (default: 400)         |
+| `save_path` | string |          | Optional file path to save the PNG            |
 
 ### Example
 
@@ -44,22 +38,22 @@ Renders a Vega-Lite specification as a PNG image.
   "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
   "data": {
     "values": [
-      {"category": "A", "value": 28},
-      {"category": "B", "value": 55},
-      {"category": "C", "value": 43}
+      { "category": "A", "value": 28 },
+      { "category": "B", "value": 55 },
+      { "category": "C", "value": 43 }
     ]
   },
   "mark": "bar",
   "encoding": {
-    "x": {"field": "category", "type": "nominal"},
-    "y": {"field": "value", "type": "quantitative"}
+    "x": { "field": "category", "type": "nominal" },
+    "y": { "field": "value", "type": "quantitative" }
   }
 }
 ```
 
 ## Reference Documentation
 
-See [vega-lite-reference.md](./extensions/vega-chart/vega-lite-reference.md) for comprehensive documentation on:
+See [vega-lite-reference.md](./extensions/vega-chart/vega-lite-reference.md) for documentation on:
 
 - Data types and encoding channels
 - All mark types and properties

package/extensions/vega-chart/index.ts

@@ -10,13 +10,13 @@
  * - Data-driven: Inline data or separate TSV input
  */
 
-import type { ExtensionAPI } from '@mariozechner/pi-coding-agent';
-import { Type } from '@sinclair/typebox';
 import { execSync } from 'node:child_process';
 import { readFileSync, unlinkSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import type { ExtensionAPI } from '@mariozechner/pi-coding-agent';
+import { Type } from '@sinclair/typebox';
 
 // Compute reference path using ESM import.meta.url
 const VEGA_REFERENCE_PATH = join(dirname(fileURLToPath(import.meta.url)), 'vega-lite-reference.md');
@@ -72,14 +72,14 @@ Reference: https://vega.github.io/vega-lite/docs/`,
       tsv_data: Type.Optional(
         Type.String({
           description: 'Optional TSV data - if provided, replaces spec.data.values',
-        }),
+        })
       ),
       width: Type.Optional(Type.Number({ description: 'Chart width in pixels (default: 600)' })),
       height: Type.Optional(Type.Number({ description: 'Chart height in pixels (default: 400)' })),
       save_path: Type.Optional(
         Type.String({
           description: 'Optional file path to save the PNG chart (in addition to displaying it)',
-        }),
+        })
       ),
     }),
 
@@ -239,7 +239,7 @@ print('OK')
             encoding: 'utf-8',
             timeout: 60000, // Longer timeout for first run when uv downloads packages
             maxBuffer: 10 * 1024 * 1024,
-          },
+          }
         );
 
         if (!result.includes('OK')) {

package/extensions/vega-chart/vega-lite-reference.md

@@ -1,6 +1,6 @@
 # Vega-Lite Visualization Reference
 
-A comprehensive reference for creating data visualizations using Vega-Lite specifications. This guide follows best practices from the [UW Interactive Data Lab Visualization Curriculum](https://idl.uw.edu/visualization-curriculum/intro.html) and established visualization research.
+Reference for creating data visualizations using Vega-Lite specifications. This guide follows best practices from the [UW Interactive Data Lab Visualization Curriculum](https://idl.uw.edu/visualization-curriculum/intro.html) and established visualization research.
 
 ## Prerequisites
 
@@ -23,7 +23,7 @@ If dependencies cannot be installed, the tool returns an error with instructions
 
 ## Philosophy
 
-> "A visualization is a mapping from data to visual properties. The key insight is that this mapping should be **declarative** rather than imperative."
+At its core, a visualization maps data to visual properties. Instead of specifying step-by-step drawing instructions (imperative), you describe what the visualization should represent (declarative).
 
 Vega-Lite embodies a **grammar of graphics**: you describe _what_ you want to visualize, not _how_ to draw it. This enables:
 
@@ -648,7 +648,12 @@ Control how scales/axes/legends are shared or independent.
   },
   "mark": { "type": "bar", "cornerRadius": 3 },
   "encoding": {
-    "x": { "field": "month", "type": "ordinal", "title": null, "axis": { "labelAngle": 0 } },
+    "x": {
+      "field": "month",
+      "type": "ordinal",
+      "title": null,
+      "axis": { "labelAngle": 0 }
+    },
     "y": {
       "field": "revenue",
       "type": "quantitative",
@@ -664,7 +669,11 @@ Control how scales/axes/legends are shared or independent.
 ```json
 {
   "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
-  "title": { "text": "Daily Temperature", "subtitle": "December 2025", "anchor": "start" },
+  "title": {
+    "text": "Daily Temperature",
+    "subtitle": "December 2025",
+    "anchor": "start"
+  },
   "width": 600,
   "height": 200,
   "data": {
@@ -679,14 +688,26 @@ Control how scales/axes/legends are shared or independent.
   "layer": [
     { "mark": { "type": "area", "opacity": 0.2, "color": "#e45756" } },
     { "mark": { "type": "line", "color": "#e45756", "strokeWidth": 2 } },
-    { "mark": { "type": "point", "color": "#e45756", "filled": true, "size": 50 } },
+    {
+      "mark": {
+        "type": "point",
+        "color": "#e45756",
+        "filled": true,
+        "size": 50
+      }
+    },
     {
       "mark": { "type": "rule", "strokeDash": [4, 4], "color": "#999" },
       "encoding": { "y": { "datum": 20 } }
     }
   ],
   "encoding": {
-    "x": { "field": "date", "type": "temporal", "title": null, "axis": { "format": "%b %d" } },
+    "x": {
+      "field": "date",
+      "type": "temporal",
+      "title": null,
+      "axis": { "format": "%b %d" }
+    },
     "y": {
       "field": "temp",
       "type": "quantitative",
@@ -718,11 +739,21 @@ Control how scales/axes/legends are shared or independent.
   },
   "layer": [
     {
-      "mark": { "type": "line", "strokeWidth": 2.5, "point": { "filled": true, "size": 50 } }
+      "mark": {
+        "type": "line",
+        "strokeWidth": 2.5,
+        "point": { "filled": true, "size": 50 }
+      }
     },
     {
       "transform": [{ "filter": "datum.date == '2025-03'" }],
-      "mark": { "type": "text", "align": "left", "dx": 8, "fontSize": 12, "fontWeight": "bold" },
+      "mark": {
+        "type": "text",
+        "align": "left",
+        "dx": 8,
+        "fontSize": 12,
+        "fontWeight": "bold"
+      },
       "encoding": { "text": { "field": "team" } }
     }
   ],
@@ -824,7 +855,12 @@ Control how scales/axes/legends are shared or independent.
   "mark": "bar",
   "encoding": {
     "x": { "field": "month", "type": "ordinal", "title": null },
-    "y": { "field": "sales", "type": "quantitative", "stack": "zero", "title": "Sales" },
+    "y": {
+      "field": "sales",
+      "type": "quantitative",
+      "stack": "zero",
+      "title": "Sales"
+    },
     "color": { "field": "category", "type": "nominal", "title": null }
   }
 }
@@ -961,14 +997,22 @@ Use sorted bar chart instead - see "Never Use Pie or Donut Charts" in Best Pract
       "mark": "bar",
       "encoding": {
         "x": { "field": "date", "type": "temporal" },
-        "y": { "field": "precipitation", "type": "quantitative", "title": "Precipitation (mm)" }
+        "y": {
+          "field": "precipitation",
+          "type": "quantitative",
+          "title": "Precipitation (mm)"
+        }
       }
     },
     {
       "mark": { "type": "line", "color": "firebrick" },
       "encoding": {
         "x": { "field": "date", "type": "temporal" },
-        "y": { "field": "temperature", "type": "quantitative", "title": "Temperature (°C)" }
+        "y": {
+          "field": "temperature",
+          "type": "quantitative",
+          "title": "Temperature (°C)"
+        }
       }
     }
   ],
@@ -1108,7 +1152,12 @@ Legends force eye movement. Label directly on the chart:
       "encoding": { "color": { "field": "series", "legend": null } }
     },
     {
-      "mark": { "type": "text", "align": "left", "dx": 8, "fontWeight": "bold" },
+      "mark": {
+        "type": "text",
+        "align": "left",
+        "dx": 8,
+        "fontWeight": "bold"
+      },
       "transform": [{ "filter": "datum.date == '2025-12-29'" }],
       "encoding": {
         "x": { "field": "date", "type": "temporal" },
@@ -1588,10 +1637,3 @@ Before finalizing any chart, verify:
 - [Vega-Lite Examples](https://vega.github.io/vega-lite/examples/)
 - [UW Visualization Curriculum](https://idl.uw.edu/visualization-curriculum/intro.html)
 - [Altair Documentation](https://altair-viz.github.io/)
-
-### Visual Design References
-
-- _Sémiologie Graphique_ (1967) — semiotics of graphics, visual variables
-- _The Visual Display of Quantitative Information_ (1983) — data-ink ratio, minimalist approach
-- _The Functional Art_, _How Charts Lie_ — clarity over minimalism, communicative approach
-- _Visualization Analysis and Design_ (2014) — systematic approach to visualization design

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@walterra/pi-charts",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "Vega-Lite chart extension for pi coding agent - render data visualizations as inline images",
   "type": "module",
   "files": [
@@ -18,6 +18,7 @@
     "directory": "packages/pi-charts"
   },
   "keywords": [
+    "pi-package",
     "pi",
     "pi-coding-agent",
     "extension",