katucharts.js 0.2.1

package/dist/utils/CircularBuffer.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Fixed-capacity ring buffer for bounded data storage.
+ * Evicts oldest items when capacity is reached.
+ */
+export declare class CircularBuffer<T> {
+    private buffer;
+    private head;
+    private _size;
+    private capacity;
+    constructor(capacity: number);
+    /**
+     * Push an item, returning the evicted item if at capacity.
+     */
+    push(item: T): T | undefined;
+    /**
+     * Push multiple items, returning all evicted items.
+     */
+    pushMany(items: T[]): T[];
+    get size(): number;
+    get isFull(): boolean;
+    get(index: number): T | undefined;
+    toArray(): T[];
+    clear(): void;
+}

package/dist/utils/chartText.d.ts

@@ -0,0 +1,18 @@
+export declare const DEFAULT_CHART_TEXT_SIZE = "12px";
+export declare const DEFAULT_CHART_TEXT_COLOR = "#000000";
+/**
+ * Picks a readable label color for text drawn on top of the given background
+ * fill. Dark ink is preferred and kept whenever its contrast against the fill
+ * meets the WCAG large-text threshold; only backgrounds dark enough to make
+ * dark text illegible (deep reds, near-blacks) are switched to white. An
+ * explicit `override` always wins, so caller-configured colors are never
+ * second-guessed, and unparseable fills (gradients, urls, transparent) fall
+ * back to the standard dark text color.
+ */
+export declare function readableTextColor(background: string | undefined, override?: string): string;
+export declare function parseFontSizePx(fontSize: string | undefined): number;
+/**
+ * Measure the rendered width of a text string using canvas 2d measureText.
+ * Falls back to `length * fontPx * 0.62` when running in a non-DOM env.
+ */
+export declare function measureTextWidth(text: string, fontPx: number, fontWeight?: string, fontFamily?: string): number;

package/dist/utils/color.d.ts

@@ -0,0 +1,23 @@
+export interface KatuChartsColor {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+    get(prop: 'rgba'): string;
+    brighten(amount: number): KatuChartsColor;
+    setOpacity(opacity: number): KatuChartsColor;
+    toString(): string;
+}
+export declare function parseColor(input: string | undefined | null): KatuChartsColor;
+export declare const PALETTES: Record<string, string[]>;
+export declare function getPalette(name: string): string[];
+export declare const DEFAULT_COLORS: string[];
+/**
+ * Predefined themes — one light and one dark variant per family. The light
+ * variant uses the bare family name; the dark variant adds a `-dark` suffix.
+ * Each entry is a full options fragment that overrides every color surface, so
+ * passing it overwrites the chart's whole color identity.
+ */
+export declare const THEMES: Record<string, any>;
+export declare const THEME_NAMES: string[];
+export declare function getTheme(name: string): any;

package/dist/utils/decimation.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Point decimation algorithms for rendering large datasets efficiently.
+ * Original data is never modified — these return reduced copies for rendering only.
+ */
+import type { PointOptions } from '../types/options';
+/**
+ * Largest-Triangle-Three-Buckets (LTTB) decimation.
+ * Preserves visual shape better than simple sampling by selecting
+ * the point in each bucket that forms the largest triangle with
+ * the previously selected point and the average of the next bucket.
+ * O(n) time complexity.
+ */
+export declare function lttbDecimate(data: PointOptions[], targetPoints: number): PointOptions[];
+/**
+ * Min-max decimation: for each bucket, keeps the min and max y-value points.
+ * Faster than LTTB but less visually accurate. Good for column/bar charts.
+ * O(n) time complexity.
+ */
+export declare function minMaxDecimate(data: PointOptions[], targetPoints: number): PointOptions[];

package/dist/utils/deepMerge.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Deep merge utility for option objects.
+ */
+export declare function deepMerge<T extends Record<string, any>>(target: T, ...sources: Partial<T>[]): T;
+export declare function deepClone<T>(obj: T): T;

package/dist/utils/dom.d.ts

@@ -0,0 +1,10 @@
+/**
+ * DOM helper utilities.
+ */
+export declare function resolveContainer(containerOrId: string | HTMLElement): HTMLElement;
+export declare function getElementDimensions(el: HTMLElement, heightAspectRatio?: number): {
+    width: number;
+    height: number;
+};
+export declare function createDiv(className?: string, parent?: HTMLElement): HTMLDivElement;
+export declare function removeElement(el: Element | null): void;

package/dist/utils/format.d.ts

@@ -0,0 +1,42 @@
+export declare function setUseUTC(value: boolean): void;
+export declare function getUseUTC(): boolean;
+export declare function dateFormat(formatStr: string, timestamp: number): string;
+export declare function numberFormat(value: number, decimals?: number, decPoint?: string, thousandsSep?: string): string;
+/**
+ * Formats a numeric value with SI suffixes (k, M, G, T) when the absolute
+ * value is >= 1,000, for standard axis label formatting.
+ * Values below 1,000 are shown as-is.
+ */
+export declare function siFormat(value: number): string;
+/**
+ * Substitutes `{path}` / `{path:format}` placeholders in a template string with
+ * values resolved from `context`. When `escapeValues` is true the substituted
+ * data values are HTML-escaped while the surrounding template markup is left
+ * intact — use this whenever the result is injected as `innerHTML` so that
+ * user-supplied data (series/point names, categories) cannot inject markup.
+ */
+export declare function templateFormat(template: string, context: Record<string, any>, escapeValues?: boolean): string;
+/**
+ * Escapes HTML-significant characters so untrusted data can be safely placed in
+ * an `innerHTML` string.
+ */
+export declare function escapeHtml(value: unknown): string;
+/**
+ * Prepares a value for a CSV field. Cells whose text begins with a spreadsheet
+ * formula trigger (=, +, -, @, tab, CR) are prefixed with a single quote so
+ * Excel/Sheets treat them as text instead of executing them — plain numeric
+ * literals are exempt so negative numbers survive. The field is then quoted per
+ * RFC 4180 when it contains the delimiter, a double quote, or a line break.
+ */
+export declare function escapeCsvCell(value: unknown, delimiter?: string): string;
+/**
+ * Returns `color` when it matches a safe CSS color token (hex, rgb/rgba,
+ * hsl/hsla, or a bare keyword), otherwise `fallback`. Prevents attribute
+ * injection when a user-supplied color is interpolated into an inline style.
+ */
+export declare function sanitizeColor(color: unknown, fallback?: string): string;
+/**
+ * Strips HTML tags from a string, suitable for rendering text in SVG context
+ * where innerHTML is not available. <br/> tags are replaced with spaces.
+ */
+export declare function stripHtmlTags(text: string): string;

package/dist/utils/index.d.ts

@@ -0,0 +1,7 @@
+export { deepMerge, deepClone } from './deepMerge';
+export { resolveContainer, getElementDimensions, createDiv, removeElement } from './dom';
+export { parseColor, DEFAULT_COLORS, type KatuChartsColor } from './color';
+export { dateFormat, numberFormat, templateFormat, stripHtmlTags } from './format';
+export { clamp, pick, isNumber, normalizeAngle, degreesToRadians, radiansToDegrees } from './math';
+export { throttle, debounce } from './throttle';
+export { CircularBuffer } from './CircularBuffer';

package/dist/utils/math.d.ts

@@ -0,0 +1,6 @@
+export declare function clamp(value: number, min: number, max: number): number;
+export declare function pick<T>(...values: (T | undefined | null)[]): T;
+export declare function isNumber(value: unknown): value is number;
+export declare function normalizeAngle(angle: number): number;
+export declare function degreesToRadians(degrees: number): number;
+export declare function radiansToDegrees(radians: number): number;

package/dist/utils/throttle.d.ts

@@ -0,0 +1,2 @@
+export declare function throttle<T extends (...args: any[]) => void>(fn: T, limit: number): T;
+export declare function debounce<T extends (...args: any[]) => void>(fn: T, delay: number): T;

package/package.json

@@ -0,0 +1,95 @@
+{
+  "name": "katucharts.js",
+  "version": "0.2.1",
+  "description": "D3.js charting library with a simple declarative interface",
+  "type": "module",
+  "main": "./dist/katucharts.umd.js",
+  "module": "./dist/katucharts.es.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/katucharts.es.js",
+      "require": "./dist/katucharts.umd.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./bio": {
+      "import": "./dist/katucharts-bio.es.js",
+      "require": "./dist/katucharts-bio.umd.js",
+      "types": "./dist/bio.d.ts"
+    },
+    "./finance": {
+      "import": "./dist/katucharts-finance.es.js",
+      "require": "./dist/katucharts-finance.umd.js",
+      "types": "./dist/finance.d.ts"
+    },
+    "./datatable": {
+      "import": "./dist/katucharts-datatable.es.js",
+      "require": "./dist/katucharts-datatable.umd.js",
+      "types": "./dist/datatable.d.ts"
+    },
+    "./react": {
+      "import": "./dist/katucharts-react.es.js",
+      "require": "./dist/katucharts-react.umd.js",
+      "types": "./dist/react.d.ts"
+    }
+  },
+  "keywords": [
+    "charts",
+    "charting",
+    "d3",
+    "visualization",
+    "svg",
+    "graphs",
+    "data-visualization"
+  ],
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build && BUILD_ENTRY=bio vite build && BUILD_ENTRY=finance vite build && BUILD_ENTRY=datatable vite build && BUILD_ENTRY=react vite build && tsc --emitDeclarationOnly",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@noble/curves": "^2.2.0",
+    "d3": "^7.9.0",
+    "d3-sankey": "^0.12.3",
+    "topojson-client": "^3.1.0"
+  },
+  "devDependencies": {
+    "@types/d3": "^7.4.3",
+    "@types/d3-sankey": "^0.12.5",
+    "@types/react": "^18.0.0",
+    "@types/topojson-client": "^3.1.5",
+    "jsdom": "^24.0.0",
+    "typescript": "^5.4.0",
+    "vite": "^5.4.0",
+    "vitest": "^2.0.0"
+  },
+  "peerDependencies": {
+    "jspdf": "^2.5.0",
+    "react": ">=17.0.0",
+    "react-dom": ">=17.0.0"
+  },
+  "peerDependenciesMeta": {
+    "jspdf": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
+  "author": "katudv",
+  "license": "SEE LICENSE IN LICENSE",
+  "homepage": "https://github.com/Katu-Data-Visualization/katucharts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Katu-Data-Visualization/katucharts.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Katu-Data-Visualization/katucharts/issues"
+  }
+}