@ggterm/core 0.2.0 → 0.2.5

package/README.md

@@ -0,0 +1,102 @@
+# @ggterm/core
+
+[![npm version](https://img.shields.io/npm/v/@ggterm/core.svg)](https://www.npmjs.com/package/@ggterm/core)
+[![npm downloads](https://img.shields.io/npm/dm/@ggterm/core.svg)](https://www.npmjs.com/package/@ggterm/core)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A Grammar of Graphics for Terminal User Interfaces.
+
+**ggterm** is a TypeScript library implementing Leland Wilkinson's Grammar of Graphics for terminal-based rendering. Create publication-quality data visualizations directly in your terminal.
+
+## Installation
+
+```bash
+npm install @ggterm/core
+```
+
+## Quick Example
+
+```typescript
+import { gg, geom_point, geom_line } from '@ggterm/core'
+
+const data = [
+  { x: 1, y: 10 },
+  { x: 2, y: 25 },
+  { x: 3, y: 18 },
+  { x: 4, y: 30 }
+]
+
+const plot = gg(data)
+  .aes({ x: 'x', y: 'y' })
+  .geom(geom_point())
+  .geom(geom_line())
+  .labs({ title: 'My Plot', x: 'Time', y: 'Value' })
+
+console.log(plot.render({ width: 60, height: 20 }))
+```
+
+## Features
+
+- **20+ Geometry Types**: point, line, bar, histogram, boxplot, violin, area, heatmap, contour, and more
+- **50+ Scales**: Continuous, discrete, color (viridis, brewer), date/time
+- **Faceting**: `facet_wrap()` and `facet_grid()` for multi-panel plots
+- **Themes**: Customizable themes for different visual styles
+- **Export**: Convert to Vega-Lite for publication-quality PNG/SVG output
+
+## Available Geoms
+
+```typescript
+// Points and Lines
+geom_point(), geom_line(), geom_path(), geom_step(), geom_smooth()
+
+// Bars and Areas
+geom_bar(), geom_col(), geom_histogram(), geom_area(), geom_ribbon()
+
+// Distributions
+geom_boxplot(), geom_violin(), geom_density_2d(), geom_qq()
+
+// 2D Plots
+geom_tile(), geom_raster(), geom_contour(), geom_contour_filled()
+
+// Annotations
+geom_text(), geom_label(), geom_hline(), geom_vline(), geom_abline()
+
+// Uncertainty
+geom_errorbar(), geom_errorbarh(), geom_crossbar(), geom_linerange(), geom_pointrange()
+```
+
+## Color Support
+
+Works in terminals with truecolor, 256-color, and 16-color support:
+
+```typescript
+plot.render({
+  width: 80,
+  height: 24,
+  colorMode: 'truecolor' // or '256', '16', 'none'
+})
+```
+
+## Export to Vega-Lite
+
+```typescript
+import { plotSpecToVegaLite } from '@ggterm/core'
+
+const vegaSpec = plotSpecToVegaLite(plot.spec())
+// Use with Vega-Embed to render PNG/SVG in browsers
+```
+
+## Framework Integrations
+
+- **React**: `@ggterm/opentui`
+- **Vue**: `@ggterm/vue`
+- **Svelte**: `@ggterm/svelte`
+- **Solid**: `@ggterm/solid`
+
+## Documentation
+
+Full documentation and examples: [github.com/shandley/ggterm](https://github.com/shandley/ggterm)
+
+## License
+
+MIT

package/dist/canvas/canvas.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Canvas - Abstract 2D buffer for terminal rendering
+ */
+import type { Canvas, CanvasCell, RGBA } from '../types';
+/**
+ * Default colors
+ */
+export declare const DEFAULT_FG: RGBA;
+export declare const DEFAULT_BG: RGBA;
+/**
+ * Concrete Canvas implementation
+ */
+export declare class TerminalCanvas implements Canvas {
+    readonly width: number;
+    readonly height: number;
+    cells: CanvasCell[][];
+    constructor(width: number, height: number);
+    /**
+     * Set a cell at the given position
+     */
+    setCell(x: number, y: number, cell: Partial<CanvasCell>): void;
+    /**
+     * Get a cell at the given position
+     */
+    getCell(x: number, y: number): CanvasCell;
+    /**
+     * Clear the canvas
+     */
+    clear(): void;
+    /**
+     * Draw a character at position
+     */
+    drawChar(x: number, y: number, char: string, fg?: RGBA): void;
+    /**
+     * Draw a string horizontally starting at position
+     */
+    drawString(x: number, y: number, str: string, fg?: RGBA): void;
+    /**
+     * Draw a horizontal line
+     */
+    drawHLine(x: number, y: number, length: number, char?: string, fg?: RGBA): void;
+    /**
+     * Draw a vertical line
+     */
+    drawVLine(x: number, y: number, length: number, char?: string, fg?: RGBA): void;
+    /**
+     * Draw a point marker
+     */
+    drawPoint(x: number, y: number, fg?: RGBA, shape?: string): void;
+    /**
+     * Fill a rectangular region
+     */
+    fillRect(x: number, y: number, width: number, height: number, char?: string, fg?: RGBA, bg?: RGBA): void;
+    /**
+     * Draw a box border
+     */
+    drawBox(x: number, y: number, width: number, height: number, style?: 'single' | 'double' | 'rounded', fg?: RGBA): void;
+    /**
+     * Render canvas to plain string (no colors)
+     */
+    toString(): string;
+    /**
+     * Render canvas to ANSI-colored string
+     */
+    toAnsiString(): string;
+}
+/**
+ * Create a new canvas
+ */
+export declare function createCanvas(width: number, height: number): TerminalCanvas;
+//# sourceMappingURL=canvas.d.ts.map

package/dist/canvas/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Canvas exports
+ */
+export { TerminalCanvas, createCanvas, DEFAULT_FG, DEFAULT_BG } from './canvas';
+//# sourceMappingURL=index.d.ts.map

package/dist/geoms/area.d.ts

@@ -0,0 +1,18 @@
+/**
+ * geom_area - Area geometry
+ */
+import type { Geom } from '../types';
+export interface AreaOptions {
+    alpha?: number;
+    color?: string;
+    fill?: string;
+}
+/**
+ * Render filled area under a line
+ */
+export declare function geom_area(options?: AreaOptions): Geom;
+/**
+ * Render a ribbon (band between ymin and ymax)
+ */
+export declare function geom_ribbon(options?: AreaOptions): Geom;
+//# sourceMappingURL=area.d.ts.map

package/dist/geoms/boxplot.d.ts

@@ -0,0 +1,25 @@
+/**
+ * geom_boxplot - Boxplot geometry
+ */
+import type { Geom } from '../types';
+export interface BoxplotOptions {
+    /** Width of the box (default: 0.75) */
+    width?: number;
+    /** Coefficient for whisker length (default: 1.5 * IQR) */
+    coef?: number;
+    /** Show outliers (default: true) */
+    outliers?: boolean;
+    /** Show notch (default: false) */
+    notch?: boolean;
+    /** Alpha transparency */
+    alpha?: number;
+    /** Border color */
+    color?: string;
+    /** Fill color */
+    fill?: string;
+}
+/**
+ * Render boxplot (box and whisker plot)
+ */
+export declare function geom_boxplot(options?: BoxplotOptions): Geom;
+//# sourceMappingURL=boxplot.d.ts.map

package/dist/geoms/line.d.ts

@@ -0,0 +1,31 @@
+/**
+ * geom_line - Line geometry
+ */
+import type { Geom } from '../types';
+export interface LineOptions {
+    linewidth?: number;
+    linetype?: 'solid' | 'dashed' | 'dotted';
+    alpha?: number;
+    color?: string;
+}
+/**
+ * Connect data points with lines
+ */
+export declare function geom_line(options?: LineOptions): Geom;
+/**
+ * Add a horizontal reference line
+ */
+export declare function geom_hline(options: {
+    yintercept: number;
+    linetype?: 'solid' | 'dashed' | 'dotted';
+    color?: string;
+}): Geom;
+/**
+ * Add a vertical reference line
+ */
+export declare function geom_vline(options: {
+    xintercept: number;
+    linetype?: 'solid' | 'dashed' | 'dotted';
+    color?: string;
+}): Geom;
+//# sourceMappingURL=line.d.ts.map

package/dist/geoms/segment.d.ts

@@ -0,0 +1,33 @@
+/**
+ * geom_segment - Line segments from (x, y) to (xend, yend)
+ */
+import type { Geom } from '../types';
+export interface SegmentOptions {
+    /** Line width (default: 1) */
+    linewidth?: number;
+    /** Line type (default: 'solid') */
+    linetype?: 'solid' | 'dashed' | 'dotted';
+    /** Opacity (default: 1) */
+    alpha?: number;
+    /** Fixed color for all segments */
+    color?: string;
+    /** Add arrow to end (default: false) */
+    arrow?: boolean;
+    /** Arrow type (default: 'closed') */
+    arrowType?: 'open' | 'closed';
+}
+/**
+ * Draw line segments between pairs of points
+ *
+ * Required aesthetics: x, y, xend, yend
+ * Optional aesthetics: color, alpha
+ */
+export declare function geom_segment(options?: SegmentOptions): Geom;
+/**
+ * Draw curves between points (alias for segment with potential future curve support)
+ */
+export declare function geom_curve(options?: SegmentOptions & {
+    /** Curvature amount (-1 to 1, default: 0.5) */
+    curvature?: number;
+}): Geom;
+//# sourceMappingURL=segment.d.ts.map

package/dist/pipeline/pipeline.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Main rendering pipeline
+ *
+ * Orchestrates the full flow from PlotSpec to rendered output.
+ */
+import type { PlotSpec, RenderOptions } from '../types';
+import { TerminalCanvas } from '../canvas/canvas';
+/**
+ * Layout configuration for plot elements
+ */
+export interface PlotLayout {
+    width: number;
+    height: number;
+    margins: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+    plotArea: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    legendArea?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+/**
+ * Calculate layout based on render options and content
+ */
+export declare function calculateLayout(spec: PlotSpec, options: RenderOptions): PlotLayout;
+/**
+ * Render a plot specification to a canvas
+ */
+export declare function renderToCanvas(spec: PlotSpec, options: RenderOptions): TerminalCanvas;
+/**
+ * Render a plot specification to a string
+ */
+export declare function renderToString(spec: PlotSpec, options: RenderOptions): string;
+//# sourceMappingURL=pipeline.d.ts.map

package/dist/stats/bin.d.ts

@@ -0,0 +1,33 @@
+/**
+ * stat_bin - Bin continuous data for histograms
+ */
+import type { DataSource, Stat } from '../types';
+export interface StatBinParams {
+    /** Number of bins (default: 30) */
+    bins?: number;
+    /** Bin width (overrides bins if specified) */
+    binwidth?: number;
+    /** Center of one bin */
+    center?: number;
+    /** Boundary between bins */
+    boundary?: number;
+}
+/**
+ * Compute bins for histogram data
+ */
+export declare function computeBins(data: DataSource, field: string, params?: StatBinParams): {
+    bins: BinResult[];
+    binWidth: number;
+};
+export interface BinResult {
+    x: number;
+    xmin: number;
+    xmax: number;
+    count: number;
+    density: number;
+}
+/**
+ * Create stat_bin transformation
+ */
+export declare function stat_bin(params?: StatBinParams): Stat;
+//# sourceMappingURL=bin.d.ts.map

package/dist/stats/boxplot.d.ts

@@ -0,0 +1,28 @@
+/**
+ * stat_boxplot - Compute summary statistics for boxplots
+ */
+import type { Stat } from '../types';
+export interface StatBoxplotParams {
+    /** Coefficient for whisker length (default: 1.5 * IQR) */
+    coef?: number;
+}
+export interface BoxplotResult {
+    x: string | number;
+    lower: number;
+    q1: number;
+    median: number;
+    q3: number;
+    upper: number;
+    outliers: number[];
+    notchlower?: number;
+    notchupper?: number;
+}
+/**
+ * Compute boxplot statistics for a group of values
+ */
+export declare function computeBoxplotStats(values: number[], coef?: number): Omit<BoxplotResult, 'x'>;
+/**
+ * Create stat_boxplot transformation
+ */
+export declare function stat_boxplot(params?: StatBoxplotParams): Stat;
+//# sourceMappingURL=boxplot.d.ts.map

package/dist/stats/smooth.d.ts

@@ -0,0 +1,33 @@
+/**
+ * stat_smooth - Smoothing and regression lines
+ */
+import type { DataSource, Stat } from '../types';
+export interface StatSmoothParams {
+    /** Method: 'lm' (linear), 'loess', 'lowess' (default: 'lm') */
+    method?: 'lm' | 'loess' | 'lowess';
+    /** Span for loess smoothing (default: 0.75) */
+    span?: number;
+    /** Number of points to evaluate (default: 80) */
+    n?: number;
+    /** Include standard error bands (default: true) */
+    se?: boolean;
+    /** Confidence level for SE bands (default: 0.95) */
+    level?: number;
+}
+export interface SmoothResult {
+    x: number;
+    y: number;
+    ymin?: number;
+    ymax?: number;
+    se?: number;
+    [key: string]: unknown;
+}
+/**
+ * Compute smoothed values
+ */
+export declare function computeSmooth(data: DataSource, xField: string, yField: string, params?: StatSmoothParams): DataSource;
+/**
+ * Create stat_smooth transformation
+ */
+export declare function stat_smooth(params?: StatSmoothParams): Stat;
+//# sourceMappingURL=smooth.d.ts.map

package/dist/stats/summary.d.ts

@@ -0,0 +1,32 @@
+/**
+ * stat_summary - Summarize y values at each unique x
+ */
+import type { DataSource, Stat } from '../types';
+export type SummaryFun = (values: number[]) => number;
+export interface StatSummaryParams {
+    /** Function to compute y value (default: mean) */
+    fun?: 'mean' | 'median' | 'min' | 'max' | 'sum' | SummaryFun;
+    /** Function to compute ymin (default: min) */
+    funMin?: 'mean' | 'median' | 'min' | 'max' | 'sum' | 'se_lower' | 'sd_lower' | SummaryFun;
+    /** Function to compute ymax (default: max) */
+    funMax?: 'mean' | 'median' | 'min' | 'max' | 'sum' | 'se_upper' | 'sd_upper' | SummaryFun;
+    /** Preset: 'mean_se', 'mean_sd', 'mean_cl_normal', 'median_range' */
+    funData?: 'mean_se' | 'mean_sd' | 'mean_cl_normal' | 'median_range';
+}
+export interface SummaryResult {
+    x: string | number;
+    y: number;
+    ymin?: number;
+    ymax?: number;
+    n: number;
+    [key: string]: unknown;
+}
+/**
+ * Compute summary statistics for each group
+ */
+export declare function computeSummary(data: DataSource, xField: string, yField: string, params?: StatSummaryParams): DataSource;
+/**
+ * Create stat_summary transformation
+ */
+export declare function stat_summary(params?: StatSummaryParams): Stat;
+//# sourceMappingURL=summary.d.ts.map

package/dist/themes/default.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Default theme for ggterm
+ */
+import type { Theme } from '../types';
+/**
+ * Minimal default theme
+ */
+export declare function defaultTheme(): Theme;
+/**
+ * Minimal theme with no decorations
+ */
+export declare function themeMinimal(): Theme;
+/**
+ * Dark theme
+ */
+export declare function themeDark(): Theme;
+/**
+ * Classic theme (ggplot2 style)
+ */
+export declare function themeClassic(): Theme;
+/**
+ * Empty theme (just the plot area)
+ */
+export declare function themeVoid(): Theme;
+//# sourceMappingURL=default.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ggterm/core",
-  "version": "0.2.0",
+  "version": "0.2.5",
   "description": "Grammar of Graphics engine for terminals",
   "type": "module",
   "main": "./dist/index.js",
@@ -35,12 +35,12 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/handleylab/ggterm.git",
+    "url": "https://github.com/shandley/ggterm.git",
     "directory": "packages/core"
   },
-  "homepage": "https://github.com/handleylab/ggterm#readme",
+  "homepage": "https://github.com/shandley/ggterm#readme",
   "bugs": {
-    "url": "https://github.com/handleylab/ggterm/issues"
+    "url": "https://github.com/shandley/ggterm/issues"
   },
   "peerDependencies": {},
   "devDependencies": {

package/dist/demo.d.ts

@@ -1,6 +0,0 @@
-/**
- * Comprehensive Demo - Showcases all geometries and aesthetics
- * Run with: npx bun packages/core/src/demo.ts
- */
-export {};
-//# sourceMappingURL=demo.d.ts.map

package/dist/demo.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"demo.d.ts","sourceRoot":"","sources":["../src/demo.ts"],"names":[],"mappings":"AAAA;;;GAGG"}