@outsidedata/dolex 0.1.1 → 0.1.2

package/README.md

@@ -4,31 +4,15 @@
 
 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
-
 ## Install
 
 ```bash
 npm install @outsidedata/dolex
 ```
 
-## MCP Server Setup
-
-### Claude Desktop
+## Claude Desktop
 
-Add this to your Claude Desktop configuration file (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
 
 ```json
 {
@@ -41,15 +25,15 @@ Add this to your Claude Desktop configuration file (`~/Library/Application Suppo
 }
 ```
 
-Restart Claude Desktop. You'll see Dolex's 17 tools available in the tool picker.
+Restart Claude Desktop. Dolex's 17 tools appear in the tool picker.
 
-### Claude Code
+## Claude Code
 
 ```bash
 claude mcp add dolex -- npx @outsidedata/dolex
 ```
 
-### Other MCP Clients
+## Other MCP Clients
 
 Any MCP-compatible client (ChatGPT, VS Code, Goose, etc.) can connect via stdio:
 
@@ -57,29 +41,35 @@ Any MCP-compatible client (ChatGPT, VS Code, Goose, etc.) can connect via stdio:
 npx @outsidedata/dolex
 ```
 
-### MCP Tools
+## What It Does
+
+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.
+
+Charts render inline in the conversation as interactive HTML. No external dependencies, no CDN calls, fully offline.
 
-| Tool | Description |
+### Tools
+
+| Tool | What it does |
 |------|-------------|
-| `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 |
+| `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` | Return full self-contained HTML for a visualization |
-| `screenshot` | Render a visualization to PNG via headless Chromium |
+| `export_html` | Get raw HTML for a chart |
+| `screenshot` | Render a chart to PNG |
 
-## Pattern Catalog
+### Patterns
 
 | Category | Patterns |
 |----------|----------|
@@ -91,78 +81,18 @@ npx @outsidedata/dolex
 | **Flow** (4) | Sankey, Alluvial, Chord, Funnel |
 | **Geo** (2) | Choropleth, Proportional Symbol |
 
-## Library Usage
-
-### Pattern Selection
-
-```typescript
-import { selectPattern, registry } from '@outsidedata/dolex';
-
-const result = selectPattern(data, columns, 'compare rankings over time');
-console.log(result.recommended.pattern.name); // "Bump Chart"
-console.log(result.recommended.reasoning);
-
-const patterns = registry.getAll(); // 43 patterns
-const comparison = registry.getByCategory('comparison'); // 9 patterns
-```
-
-### React Components
-
-```tsx
-import { BumpChart, Beeswarm, Waffle, Scatter, Line } from '@outsidedata/dolex/react';
-
-function Dashboard({ spec }) {
-  return <BumpChart spec={spec} width={800} height={500} />;
-}
-```
-
-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)
-
-```typescript
-import { buildChartHtml } from '@outsidedata/dolex/html';
-
-const html = buildChartHtml(spec);
-// Complete self-contained HTML document with embedded D3 + data
-```
-
-### Theme
+### Data Connectors
 
-```typescript
-import { theme, getTheme } from '@outsidedata/dolex/theme';
-
-const dark = getTheme('dark');
-const palette = dark.palettes.categorical;
-```
+- **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
 
-### Smart Labels
+All connectors support the declarative DSL query language with joins, aggregations, groupBy (with time bucketing), filters, orderBy, and limit.
 
-```typescript
-import { labelStrategy, truncateLabel, abbreviate } from '@outsidedata/dolex/utils';
+### Offline Maps
 
-const strategy = labelStrategy(['January Sales', 'February Sales', ...], 400);
-```
-
-## Exports Map
-
-| Import Path | Contents |
-|-------------|----------|
-| `@outsidedata/dolex` | Types, patterns, theme, utilities, HTML builders |
-| `@outsidedata/dolex/react` | React components (requires React >=18) |
-| `@outsidedata/dolex/html` | Self-contained HTML chart builders |
-| `@outsidedata/dolex/theme` | Design system tokens |
-| `@outsidedata/dolex/utils` | Smart labels, responsive, export utilities |
-| `@outsidedata/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.1",
+  "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",