@outsidedata/dolex 0.1.0 → 0.1.2

package/README.md

@@ -4,89 +4,72 @@
 
 Every AI assistant suggests a bar chart. Dolex suggests the *right* chart — bump charts for rankings, beeswarms for distributions, connected dot plots for two-metric comparisons, waffle charts for precise proportions.
 
-## Features
-
-- **43 Visualization Patterns** across 7 categories: comparison, distribution, composition, time, relationship, flow, and geo
-- **Pattern Selector** — analyzes data shape + user intent, scores every pattern, returns ranked recommendations with reasoning
-- **Data Source Connectors** — connect CSV, SQLite, PostgreSQL, or MySQL; query with a declarative DSL including joins, aggregations, and time bucketing
-- **React Components** — 43 thin-wrapper components with D3 lifecycle management
-- **HTML Builders** — 43 self-contained HTML documents, perfect for MCP Apps / iframes
-- **MCP Server** — 17 tools for Claude Desktop, ChatGPT, VS Code, and any MCP-compatible client
-- **Dashboard Builder** — multi-view dashboards with global filters and cross-view interactions
-- **Compound Visualizations** — chart + data table with linked highlighting
-- **Design System** — dark/light themes with color palettes, typography, and spacing tokens
-- **Smart Labels** — truncation, abbreviation, collision avoidance, adaptive strategies
-- **Offline Maps** — choropleth and proportional symbol maps with 33 embedded TopoJSON files covering world, continents, US states/counties, and 17 country subdivision maps
-
-## Quick Start
+## Install
 
 ```bash
-npm install dolex
+npm install @outsidedata/dolex
 ```
 
-### Pattern Selection
+## Claude Desktop
 
-```typescript
-import { selectPattern, registry } from 'dolex';
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
 
-// Let Dolex choose the right pattern
-const result = selectPattern(data, columns, 'compare rankings over time');
-console.log(result.recommended.pattern.name); // "Bump Chart"
-console.log(result.recommended.reasoning);
-
-// Browse all patterns
-const patterns = registry.getAll(); // 43 patterns
-const comparison = registry.getByCategory('comparison'); // 9 patterns
-```
-
-### React Components
-
-```tsx
-import { BumpChart, Beeswarm, Waffle, Scatter, Line } from 'dolex/react';
-
-function Dashboard({ spec }) {
-  return <BumpChart spec={spec} width={800} height={500} />;
+```json
+{
+  "mcpServers": {
+    "dolex": {
+      "command": "npx",
+      "args": ["@outsidedata/dolex"]
+    }
+  }
 }
 ```
 
-Available components: `Bar`, `DivergingBar`, `SlopeChart`, `BumpChart`, `ConnectedDotPlot`, `Lollipop`, `Bullet`, `GroupedBar`, `Waterfall`, `Histogram`, `Beeswarm`, `StripPlot`, `Violin`, `Ridgeline`, `BoxPlot`, `DensityPlot`, `StackedBar`, `Waffle`, `Treemap`, `Sunburst`, `CirclePack`, `Metric`, `Donut`, `Marimekko`, `Icicle`, `Line`, `Area`, `SmallMultiples`, `SparklineGrid`, `CalendarHeatmap`, `StreamGraph`, `HorizonChart`, `Scatter`, `ConnectedScatter`, `ParallelCoordinates`, `Radar`, `Heatmap`, `Sankey`, `Alluvial`, `Chord`, `Funnel`, `Choropleth`, `ProportionalSymbol`
-
-### HTML Builders (MCP Apps / Iframes)
+Restart Claude Desktop. Dolex's 17 tools appear in the tool picker.
 
-```typescript
-import { buildChartHtml } from 'dolex/html';
+## Claude Code
 
-const html = buildChartHtml(spec);
-// Complete self-contained HTML document with embedded D3 + data
-// Perfect for iframe srcdoc, MCP Apps, or saving to file
+```bash
+claude mcp add dolex -- npx @outsidedata/dolex
 ```
 
-### Theme
+## Other MCP Clients
 
-```typescript
-import { theme, getTheme } from 'dolex/theme';
+Any MCP-compatible client (ChatGPT, VS Code, Goose, etc.) can connect via stdio:
 
-const dark = getTheme('dark');
-const bg = dark.colors.background;
-const palette = dark.palettes.categorical;
-const titleStyle = dark.typography.textStyles.chartTitle;
+```bash
+npx @outsidedata/dolex
 ```
 
-### Smart Labels
+## What It Does
 
-```typescript
-import { labelStrategy, truncateLabel, abbreviate } from 'dolex/utils';
+You give Claude your data and ask a question. Dolex analyzes the data shape and your intent, then picks the right visualization from 43 handcrafted patterns — not the obvious chart, the *informative* one.
 
-// Automatically choose the best labeling strategy
-const strategy = labelStrategy(['January Sales', 'February Sales', ...], 400);
-// Returns { mode: 'abbreviated', labels: ['Jan Sales', 'Feb Sales', ...] }
+Charts render inline in the conversation as interactive HTML. No external dependencies, no CDN calls, fully offline.
 
-// Or use individual utilities
-truncateLabel('Very Long Category Name', 80); // "Very Long Ca…"
-abbreviate('Department of Technology'); // "Dept of Tech"
-```
+### Tools
+
+| Tool | What it does |
+|------|-------------|
+| `visualize` | Inline data + intent → ranked chart recommendations |
+| `visualize_from_source` | Data source + DSL query + intent → chart recommendations |
+| `list_patterns` | Browse all 43 patterns |
+| `refine_visualization` | Tweak a chart — sort, limit, flip axes, colors, title |
+| `add_source` | Connect CSV, SQLite, PostgreSQL, or MySQL |
+| `list_sources` | List connected sources |
+| `remove_source` | Disconnect a source |
+| `describe_source` | Column profiles and sample rows |
+| `analyze_source` | Auto-generate an analysis plan with DSL queries |
+| `query_source` | Run a declarative query (joins, aggregations, filters) |
+| `create_dashboard` | Multi-view dashboard with filters and cross-filtering |
+| `refine_dashboard` | Iterate on a dashboard |
+| `server_status` | Inspect cached data |
+| `clear_cache` | Clear cached specs and results |
+| `report_bug` | Generate a sanitized bug report |
+| `export_html` | Get raw HTML for a chart |
+| `screenshot` | Render a chart to PNG |
 
-## Pattern Catalog
+### Patterns
 
 | Category | Patterns |
 |----------|----------|
@@ -98,56 +81,18 @@ abbreviate('Department of Technology'); // "Dept of Tech"
 | **Flow** (4) | Sankey, Alluvial, Chord, Funnel |
 | **Geo** (2) | Choropleth, Proportional Symbol |
 
-## MCP Server
-
-Dolex includes an MCP server for AI assistant integration.
+### Data Connectors
 
-```bash
-# Run via stdio (for Claude Desktop, etc.)
-npx dolex
-```
+- **CSV** — load local CSV files into an in-memory SQLite database
+- **SQLite** — read-only access to SQLite databases
+- **PostgreSQL** — connect to Postgres instances
+- **MySQL** — connect to MySQL instances
 
-### MCP Tools
+All connectors support the declarative DSL query language with joins, aggregations, groupBy (with time bucketing), filters, orderBy, and limit.
 
-| Tool | Description |
-|------|-------------|
-| `visualize` | Takes inline data + intent, returns visualization recommendations |
-| `visualize_from_source` | Takes a data source + DSL query + intent, returns visualization recommendations |
-| `list_patterns` | Browse all 43 available patterns |
-| `refine_visualization` | Tweak a visualization — sort, limit, flip axes, change colors, update title |
-| `add_source` | Connect a data source (CSV, SQLite, PostgreSQL, MySQL) |
-| `list_sources` | List all connected data sources |
-| `remove_source` | Disconnect and remove a data source |
-| `describe_source` | Column profiles for a data source |
-| `analyze_source` | Generate a structured analysis plan with ready-to-execute DSL queries |
-| `query_source` | Run a declarative DSL query against a data source |
-| `create_dashboard` | Multi-view dashboard with global filters and cross-view interactions |
-| `refine_dashboard` | Iterate on a dashboard — add/remove views, change layout, filters, themes |
-| `server_status` | Inspect cached data in server memory |
-| `clear_cache` | Clear cached specs and query results |
-| `report_bug` | Generate a sanitized bug report |
-| `export_html` | Return full self-contained HTML for a visualization |
-| `screenshot` | Render a visualization to PNG via headless Chromium |
+### Offline Maps
 
-## Exports Map
-
-| Import Path | Contents |
-|-------------|----------|
-| `dolex` | Types, patterns, theme, utilities, HTML builders |
-| `dolex/react` | React components (requires React >=18) |
-| `dolex/html` | Self-contained HTML chart builders |
-| `dolex/theme` | Design system tokens |
-| `dolex/utils` | Smart labels, responsive, export utilities |
-| `dolex/patterns` | Pattern registry and selector |
-
-## Development
-
-```bash
-npm run build        # TypeScript compilation
-npm test             # Run tests (818 tests)
-npm run dev          # Watch mode for MCP server
-npm run mcp:stdio    # Run MCP server via tsx
-```
+33 TopoJSON files ship with the package — world maps, US states/counties, 6 continent maps, and 17 country subdivision maps (Germany, France, Japan, China, etc.). All map data is embedded inline in the chart HTML. No CDN calls, ever.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@outsidedata/dolex",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Visualization intelligence for AI — 43 handcrafted chart patterns with React components, MCP server, and self-contained HTML builders",
   "type": "module",
   "license": "MIT",
@@ -20,6 +20,9 @@
     "choropleth",
     "pattern-library"
   ],
+  "bin": {
+    "dolex": "./dist/src/mcp/index.js"
+  },
   "main": "./dist/src/index.js",
   "types": "./dist/src/index.d.ts",
   "exports": {