@zuilib/charts 0.3.0

package/dist/cross-filter.d.ts

@@ -0,0 +1,62 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+
+/** One cross-filtered dimension: a row field and the values kept. JSON-safe. */
+interface CrossFilterEntry {
+    /** The field the values belong to (a row key; doubles as a data-grid column id). */
+    field: string;
+    /** The values kept. A mark click toggles its value here. */
+    values: (string | number)[];
+}
+/**
+ * Transient emphasis (hover, or a grid-selection echo): marks whose `field`
+ * value is in `values` render full-strength, the rest dim.
+ */
+interface CrossFilterHighlight {
+    field: string;
+    values: (string | number)[];
+}
+interface CrossFilterState {
+    filters: CrossFilterEntry[];
+    highlight: CrossFilterHighlight | null;
+}
+declare const defaultCrossFilterState: CrossFilterState;
+interface UseCrossFilterResult {
+    state: CrossFilterState;
+    /** True when any entry has values. */
+    filtered: boolean;
+    /**
+     * Toggles one value. `additive` (shift-click) keeps the field's other
+     * values; otherwise the value replaces them, and clicking the field's
+     * lone kept value clears the field.
+     */
+    toggleValue: (field: string, value: string | number, options?: {
+        additive?: boolean;
+    }) => void;
+    /** Removes the field's entry. */
+    clearField: (field: string) => void;
+    /** Removes every filter and the highlight. */
+    clearAll: () => void;
+    setHighlight: (highlight: CrossFilterHighlight | null) => void;
+    /** The kept values for a field, or null when the field is unfiltered. */
+    valuesFor: (field: string) => (string | number)[] | null;
+}
+interface CrossFilterProviderProps {
+    /**
+     * Controlled state. Left out, the provider keeps its own (from
+     * `defaultState`) and still reports through `onStateChange`.
+     */
+    state?: CrossFilterState;
+    /** Initial state when uncontrolled. @default no filters, no highlight */
+    defaultState?: CrossFilterState;
+    /** Receives the whole next state on every interaction. */
+    onStateChange?: (state: CrossFilterState) => void;
+    children: ReactNode;
+}
+declare function CrossFilterProvider({ state, defaultState, onStateChange, children }: CrossFilterProviderProps): react_jsx_runtime.JSX.Element;
+/** The cross-filter state and actions. Throws outside a `CrossFilterProvider`. */
+declare function useCrossFilter(): UseCrossFilterResult;
+/** Like `useCrossFilter`, but null outside a provider — what chart internals use. */
+declare function useOptionalCrossFilter(): UseCrossFilterResult | null;
+
+export { type CrossFilterEntry, type CrossFilterHighlight, type CrossFilterProviderProps, type CrossFilterState, type UseCrossFilterResult, CrossFilterProvider as default, defaultCrossFilterState, useCrossFilter, useOptionalCrossFilter };

package/dist/cross-filter.js

@@ -0,0 +1,13 @@
+"use client";
+import {
+  cross_filter_default,
+  defaultCrossFilterState,
+  useCrossFilter,
+  useOptionalCrossFilter
+} from "./chunk-WVWGHGZE.js";
+export {
+  cross_filter_default as default,
+  defaultCrossFilterState,
+  useCrossFilter,
+  useOptionalCrossFilter
+};

package/dist/format.d.ts

@@ -0,0 +1,17 @@
+import { F as FormatToken } from './chart-spec-CH0tAkLG.js';
+
+/** Formats one value for an axis tick, tooltip row, or direct label. */
+type FormatterFn = (value: unknown) => string;
+/** Builds a formatter from the part after `:` — `'currency:EUR'` calls `factory('EUR', locale)`. */
+type FormatterFactory = (arg: string, locale?: string) => FormatterFn;
+interface Formatters {
+    /** The formatter for `token`, falling back to `fallback`, then to `String`. */
+    resolve(token: FormatToken | undefined, fallback?: FormatToken): FormatterFn;
+}
+/**
+ * Builds the formatters `<Chart>` and the tooltip/legend contents resolve
+ * tokens through. Formatters are built once per token and cached.
+ */
+declare function createFormatters(locale?: string, custom?: Record<string, FormatterFn | FormatterFactory>): Formatters;
+
+export { type FormatterFactory, type FormatterFn, type Formatters, createFormatters };

package/dist/format.js

@@ -0,0 +1,7 @@
+import {
+  createFormatters
+} from "./chunk-7WABBHMT.js";
+import "./chunk-3VGLTPGL.js";
+export {
+  createFormatters
+};

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export { Chart, ChartProps, CustomChartProps, configFromSpec, crossFilterFieldOf, Chart as default } from './chart.js';
+export { AnyChartSpec, ChartRegistry, ChartTypeDef, CustomChartSpec, chartSpecJsonSchema, chartTypeSchema, createChartRegistry, defaultChartRegistry, defaultChartTypes, defineChartType } from './registry.js';
+export { C as ChartConfig, a as ChartFrame, b as ChartFrameProps, c as ChartLabels, d as ChartSeriesConfig, e as defaultChartLabels, f as fillLabel } from './chart-frame-B9fxUxGG.js';
+export { ChartTooltipPanel, ChartTooltipPanelProps } from './chart-tooltip.js';
+export { ChartLegendList, ChartLegendListProps } from './chart-legend.js';
+export { CHART_COLOR_COUNT, DIMMED_OPACITY, cartesianGridDefaults, chartColorVar, seriesColorProperty, seriesColorVar, tooltipCrosshairDefaults, tooltipCursorDefaults, xAxisDefaults, yAxisDefaults } from './chart-defaults.js';
+export { CrossFilterEntry, CrossFilterHighlight, default as CrossFilterProvider, CrossFilterProviderProps, CrossFilterState, UseCrossFilterResult, defaultCrossFilterState, useCrossFilter, useOptionalCrossFilter } from './cross-filter.js';
+export { ColumnFilter, applyFilters, fromColumnFilters, toColumnFilters, toHighlight } from './interop.js';
+export { FormatterFactory, FormatterFn, Formatters, createFormatters } from './format.js';
+export { A as AreaChartSpec, a as AxisSpec, B as BarChartSpec, C as CartesianFrameSpec, b as CartesianSpecCommon, c as ChartMarkEvent, d as ChartRow, e as ChartSpec, f as ChartSpecCommon, g as ComposedChartSpec, F as FormatToken, h as FunnelChartSpec, L as LineChartSpec, P as PieChartSpec, R as RadarChartSpec, i as RadialBarChartSpec, j as ReferenceLineSpec, S as ScatterChartSpec, k as SeriesSpec, T as TreemapChartSpec } from './chart-spec-CH0tAkLG.js';
+import 'react';
+import './authoring.js';
+import 'react/jsx-runtime';

package/dist/index.js

@@ -0,0 +1,93 @@
+"use client";
+import {
+  applyFilters,
+  fromColumnFilters,
+  toColumnFilters,
+  toHighlight
+} from "./chunk-D7K23UFP.js";
+import {
+  chart_default,
+  configFromSpec,
+  crossFilterFieldOf
+} from "./chunk-BFTWWI46.js";
+import {
+  chartSpecJsonSchema,
+  chartTypeSchema,
+  createChartRegistry,
+  defaultChartRegistry,
+  defaultChartTypes,
+  defineChartType
+} from "./chunk-YMPZODMC.js";
+import "./chunk-HNJKYOPE.js";
+import {
+  chart_frame_default
+} from "./chunk-G4FXJJ66.js";
+import {
+  createFormatters
+} from "./chunk-7WABBHMT.js";
+import "./chunk-3VGLTPGL.js";
+import {
+  ChartTooltipPanel
+} from "./chunk-PV27RZSV.js";
+import {
+  ChartLegendList
+} from "./chunk-SHQZRND7.js";
+import {
+  cross_filter_default,
+  defaultCrossFilterState,
+  useCrossFilter,
+  useOptionalCrossFilter
+} from "./chunk-WVWGHGZE.js";
+import {
+  defaultChartLabels,
+  fillLabel
+} from "./chunk-UN3XPBZ5.js";
+import "./chunk-IPOBQIYU.js";
+import {
+  CHART_COLOR_COUNT,
+  DIMMED_OPACITY,
+  cartesianGridDefaults,
+  chartColorVar,
+  seriesColorProperty,
+  seriesColorVar,
+  tooltipCrosshairDefaults,
+  tooltipCursorDefaults,
+  xAxisDefaults,
+  yAxisDefaults
+} from "./chunk-7WJ26NHR.js";
+export {
+  CHART_COLOR_COUNT,
+  chart_default as Chart,
+  chart_frame_default as ChartFrame,
+  ChartLegendList,
+  ChartTooltipPanel,
+  cross_filter_default as CrossFilterProvider,
+  DIMMED_OPACITY,
+  applyFilters,
+  cartesianGridDefaults,
+  chartColorVar,
+  chartSpecJsonSchema,
+  chartTypeSchema,
+  configFromSpec,
+  createChartRegistry,
+  createFormatters,
+  crossFilterFieldOf,
+  chart_default as default,
+  defaultChartLabels,
+  defaultChartRegistry,
+  defaultChartTypes,
+  defaultCrossFilterState,
+  defineChartType,
+  fillLabel,
+  fromColumnFilters,
+  seriesColorProperty,
+  seriesColorVar,
+  toColumnFilters,
+  toHighlight,
+  tooltipCrosshairDefaults,
+  tooltipCursorDefaults,
+  useCrossFilter,
+  useOptionalCrossFilter,
+  xAxisDefaults,
+  yAxisDefaults
+};

package/dist/interop.d.ts

@@ -0,0 +1,46 @@
+import { CrossFilterState, CrossFilterEntry, CrossFilterHighlight } from './cross-filter.js';
+import 'react/jsx-runtime';
+import 'react';
+
+/**
+ * Pure converters between the cross-filter state and the shapes a data
+ * table speaks — structurally compatible with `@zuilib/data-grid`
+ * (`DataGridState.columnFilters`, selected rows) without importing it, so
+ * charts stay standalone. Follows the data-grid `server-adapter` rule:
+ * untrusted input never throws.
+ */
+
+/** A column filter as data-grid / TanStack Table shape it: `{ id, value }`. */
+interface ColumnFilter {
+    id: string;
+    value: unknown;
+}
+/**
+ * The cross-filter entries as data-grid select-filter `columnFilters`
+ * (`value` is the kept values array). Empty entries are dropped.
+ */
+declare function toColumnFilters(state: CrossFilterState): {
+    id: string;
+    value: (string | number)[];
+}[];
+/**
+ * The inverse: the entries for `fields` found in a grid's `columnFilters`.
+ * Non-array and non-scalar values are ignored, never thrown on.
+ */
+declare function fromColumnFilters(columnFilters: readonly ColumnFilter[], fields: readonly string[]): CrossFilterEntry[];
+/**
+ * Grid-selected rows folded into a highlight on `field` (deduplicated;
+ * null/undefined values dropped). Null when nothing usable is selected.
+ */
+declare function toHighlight<T extends Record<string, unknown>>(rows: readonly T[], field: string): CrossFilterHighlight | null;
+/**
+ * The rows that pass every filter entry — a client-side convenience for
+ * feeding a second chart or a summary tile. `except` skips one field's
+ * entry: the standard cross-filter rule that a chart ignores its own
+ * field's filter so its clicked mark stays visible.
+ */
+declare function applyFilters<T extends Record<string, unknown>>(rows: readonly T[], state: CrossFilterState, options?: {
+    except?: string;
+}): T[];
+
+export { type ColumnFilter, applyFilters, fromColumnFilters, toColumnFilters, toHighlight };

package/dist/interop.js

@@ -0,0 +1,12 @@
+import {
+  applyFilters,
+  fromColumnFilters,
+  toColumnFilters,
+  toHighlight
+} from "./chunk-D7K23UFP.js";
+export {
+  applyFilters,
+  fromColumnFilters,
+  toColumnFilters,
+  toHighlight
+};

package/dist/registry.d.ts

@@ -0,0 +1,111 @@
+import { ComponentType } from 'react';
+import { C as ChartConfig } from './chart-frame-B9fxUxGG.js';
+import { RendererProps } from './authoring.js';
+import { e as ChartSpec, f as ChartSpecCommon } from './chart-spec-CH0tAkLG.js';
+import './format.js';
+import './cross-filter.js';
+import 'react/jsx-runtime';
+
+/**
+ * The open chart-type registry. Every chart type — built-in or
+ * app-registered — is one `ChartTypeDef` binding a spec `type` string to
+ * its renderer, its cross-filter behavior, and a complete JSON Schema of
+ * its spec variant. `<Chart>` dispatches through a registry (the built-in
+ * one by default), so an app adds a chart type by listing a def after
+ * `defaultChartTypes` — no package edits, and no second dispatch table to
+ * keep in step. The same defs are the single source of the ChartSpec JSON
+ * Schema (`chartSpecJsonSchema`), so validation and structured generation
+ * can never drift from what actually renders.
+ */
+
+/**
+ * A spec handled by an app-registered chart type: the shared options plus
+ * whatever fields that type's schema declares. Built-in specs stay the
+ * closed `ChartSpec` union — `<Chart>` only accepts this escape hatch
+ * together with an explicit `registry`, so a typo in a built-in spec is
+ * still a type error.
+ */
+interface CustomChartSpec extends ChartSpecCommon {
+    type: string;
+    [field: string]: unknown;
+}
+/** Any spec a registry can dispatch: a built-in variant or a custom one. */
+type AnyChartSpec = ChartSpec | CustomChartSpec;
+/** One registry entry: a spec `type` bound to a renderer and its contract. */
+interface ChartTypeDef<S extends AnyChartSpec = AnyChartSpec> {
+    /** The `type` string specs use. Lower-kebab-case by convention. */
+    type: string;
+    /**
+     * Which field family the spec uses — `'cartesian'` (`xKey` + `series`),
+     * `'radar'`, `'scatter'` (`xKey`/`yKey`), `'named'` (`nameKey` +
+     * `valueKey`) or `'treemap'` (`nameKey` + `sizeKey`) — so spec-editing
+     * UIs can offer the right field pickers without a per-type table of
+     * their own. A custom def names the closest family (or its own).
+     */
+    family?: string;
+    /** The component drawn inside `<ChartFrame>` for specs of this type. */
+    render: ComponentType<RendererProps<S>>;
+    /**
+     * The field mark clicks cross-filter on. Left out, `<Chart>` falls back
+     * to the spec's `xKey` — declare it for any type whose category lives
+     * elsewhere.
+     */
+    crossFilterField?: (spec: S) => string;
+    /**
+     * The field whose values the legend lists as clickable categories
+     * (colored per row, not per series). Left out, the legend lists series.
+     */
+    categoryField?: (spec: S) => string | undefined;
+    /**
+     * The series config (labels, colors, formats) the spec implies. Left
+     * out, `<Chart>` derives it from the spec's `series` array — declare it
+     * for types whose values live under other fields.
+     */
+    configFrom?: (spec: S) => ChartConfig;
+    /**
+     * JSON Schema (draft 2020-12 vocabulary) of this variant's spec —
+     * complete, including the shared options, so `chartSpecJsonSchema` can
+     * assemble a validating whole from the parts.
+     */
+    schema: Record<string, unknown>;
+}
+/** A resolved set of chart-type definitions keyed by `type`. */
+interface ChartRegistry {
+    types: ReadonlyMap<string, ChartTypeDef>;
+}
+/**
+ * Identity helper that checks a definition against its concrete spec type
+ * (so `spec` is fully typed inside `render` and the field callbacks), then
+ * erases it to the registry-level shape a heterogeneous map can hold.
+ */
+declare function defineChartType<S extends AnyChartSpec>(def: ChartTypeDef<S>): ChartTypeDef;
+/**
+ * Merges definition lists (and/or existing registries) into one registry.
+ * Later sources win on `type` collisions, so apps can override a built-in
+ * entry by listing their own definition after `defaultChartTypes`.
+ */
+declare function createChartRegistry(...sources: Array<ChartTypeDef[] | ChartRegistry>): ChartRegistry;
+/**
+ * A closed object schema for one spec variant: the shared options, the
+ * `type` discriminant, and the variant's own fields. `additionalProperties:
+ * false` is what makes cross-family mistakes (an `xKey` on a pie) fail
+ * validation instead of passing silently.
+ */
+declare function chartTypeSchema(type: string, properties: Record<string, unknown>, required: readonly string[]): Record<string, unknown>;
+/**
+ * The built-in chart types, one def per `type` string, in the order
+ * pickers should offer them. Spread them into `createChartRegistry` ahead
+ * of app defs to extend or override the set.
+ */
+declare const defaultChartTypes: ChartTypeDef[];
+/** The registry `<Chart>` uses when none is passed: the built-ins only. */
+declare const defaultChartRegistry: ChartRegistry;
+/**
+ * The full ChartSpec JSON Schema (draft 2020-12) of a registry: `type` is
+ * an enum of the registered types, and per-type `if`/`then` conditionals
+ * apply each def's complete variant schema — so a field from the wrong
+ * family fails validation instead of flattening into one all-optional bag.
+ */
+declare function chartSpecJsonSchema(registry?: ChartRegistry): Record<string, unknown>;
+
+export { type AnyChartSpec, type ChartRegistry, type ChartTypeDef, type CustomChartSpec, chartSpecJsonSchema, chartTypeSchema, createChartRegistry, defaultChartRegistry, defaultChartTypes, defineChartType };

package/dist/registry.js

@@ -0,0 +1,25 @@
+"use client";
+import {
+  chartSpecJsonSchema,
+  chartTypeSchema,
+  createChartRegistry,
+  defaultChartRegistry,
+  defaultChartTypes,
+  defineChartType
+} from "./chunk-YMPZODMC.js";
+import "./chunk-HNJKYOPE.js";
+import "./chunk-3VGLTPGL.js";
+import "./chunk-PV27RZSV.js";
+import "./chunk-SHQZRND7.js";
+import "./chunk-WVWGHGZE.js";
+import "./chunk-UN3XPBZ5.js";
+import "./chunk-IPOBQIYU.js";
+import "./chunk-7WJ26NHR.js";
+export {
+  chartSpecJsonSchema,
+  chartTypeSchema,
+  createChartRegistry,
+  defaultChartRegistry,
+  defaultChartTypes,
+  defineChartType
+};

package/package.json

@@ -0,0 +1,98 @@
+{
+  "name": "@zuilib/charts",
+  "version": "0.3.0",
+  "description": "ZUI — enterprise analytics charts on Recharts: a serializable chart spec, styled primitives, and cross-filtering that links charts to data tables",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./chart": {
+      "types": "./dist/chart.d.ts",
+      "import": "./dist/chart.js"
+    },
+    "./registry": {
+      "types": "./dist/registry.d.ts",
+      "import": "./dist/registry.js"
+    },
+    "./chart-frame": {
+      "types": "./dist/chart-frame.d.ts",
+      "import": "./dist/chart-frame.js"
+    },
+    "./authoring": {
+      "types": "./dist/authoring.d.ts",
+      "import": "./dist/authoring.js"
+    },
+    "./chart-tooltip": {
+      "types": "./dist/chart-tooltip.d.ts",
+      "import": "./dist/chart-tooltip.js"
+    },
+    "./chart-legend": {
+      "types": "./dist/chart-legend.d.ts",
+      "import": "./dist/chart-legend.js"
+    },
+    "./chart-defaults": {
+      "types": "./dist/chart-defaults.d.ts",
+      "import": "./dist/chart-defaults.js"
+    },
+    "./cross-filter": {
+      "types": "./dist/cross-filter.d.ts",
+      "import": "./dist/cross-filter.js"
+    },
+    "./interop": {
+      "types": "./dist/interop.d.ts",
+      "import": "./dist/interop.js"
+    },
+    "./format": {
+      "types": "./dist/format.d.ts",
+      "import": "./dist/format.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0",
+    "recharts": "^3.0.0",
+    "@zuilib/tokens": "^0.2.0"
+  },
+  "dependencies": {
+    "@zuilib/components": "^0.2.0"
+  },
+  "devDependencies": {
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/jest-dom": "^7.0.1",
+    "@testing-library/react": "^16.3.3",
+    "@testing-library/user-event": "^14.6.6",
+    "@types/react": "^18.0.0",
+    "@types/react-dom": "^18.0.0",
+    "ajv": "^8.17.1",
+    "axe-core": "^4.13.0",
+    "jsdom": "^30.0.1",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "recharts": "^3.0.0",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.11",
+    "@zuilib/tokens": "^0.2.0"
+  },
+  "keywords": [
+    "charts",
+    "recharts",
+    "analytics",
+    "dataviz",
+    "cross-filter",
+    "design-system",
+    "react",
+    "typescript"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "node scripts/check-logical.mjs && vitest run"
+  }
+}