@ojiepermana/angular 22.1.10 → 22.1.12

package/types/ojiepermana-angular-chart-core.d.ts

@@ -1 +1,811 @@
-export * from '@ojiepermana/angular-chart/core';
+import * as _angular_core from '@angular/core';
+import { Type, Signal } from '@angular/core';
+import { ScaleBand, ScaleLinear, scalePoint, scaleLinear, ScalePoint, scaleBand } from 'd3-scale';
+import * as _ojiepermana_angular_chart_core from '@ojiepermana/angular/chart/core';
+
+/**
+ * Theme-aware color definition for a chart series.
+ *
+ * Either:
+ * - a single `color` string (raw CSS color — hex, hsl, oklch, CSS var ref), or
+ * - a `theme` map whose keys match the document color scheme (`light` / `dark`).
+ *
+ * Values are injected verbatim into a scoped `<style>` block as
+ * `--color-<key>: <value>;`, so any valid CSS color works.
+ *
+ * Defaults reference the theme tokens from `@ojiepermana/angular/theme/styles`
+ * (e.g. `'hsl(var(--chart-1))'`).
+ */
+interface ChartSeriesConfig {
+    /** Human-readable label (shown in legend, tooltip). */
+    readonly label?: string;
+    /** Optional icon component rendered next to the label. */
+    readonly icon?: Type<unknown>;
+    /** Raw color. Mutually exclusive with `theme`. */
+    readonly color?: string;
+    /** Theme-aware colors — keyed by color scheme. */
+    readonly theme?: Readonly<Record<ChartThemeKey, string>>;
+}
+/** Supported color scheme keys. */
+type ChartThemeKey = 'light' | 'dark';
+/** Map of series-key → config. */
+type ChartConfig = Readonly<Record<string, ChartSeriesConfig>>;
+/** CSS selector under which a chart instance is scoped. */
+declare const CHART_DATA_ATTRIBUTE = "data-chart";
+/** Default color schemes supported by the generated `<style>` block. */
+declare const CHART_THEMES: ReadonlyArray<{
+    readonly key: ChartThemeKey;
+    readonly selector: string;
+}>;
+/**
+ * Whether a value is safe to interpolate into the generated `<style>` block.
+ *
+ * The check is deliberately layered rather than one clever regular expression:
+ *
+ *  1. reject anything containing a character that can end a declaration or a
+ *     rule, which is what actually stops an injection;
+ *  2. restrict the remaining characters to those a color can be built from;
+ *  3. require balanced parentheses, so a truncated function cannot swallow the
+ *     rest of the block;
+ *  4. require every function called to be a color function.
+ *
+ * Real values keep working: `#2563eb`, `red`, `var(--chart-2)`,
+ * `hsl(var(--chart-1))`, `rgb(0 0 0 / 50%)`, `color-mix(in srgb, red, blue)`.
+ */
+declare function isSafeCssColorValue(value: string): boolean;
+/**
+ * Generate the CSS rule-set for a chart instance: one `--color-<key>` per
+ * series, scoped to the owning `[data-chart]` element, with optional dark
+ * variant via `[data-mode="dark"] [data-chart="…"]`.
+ *
+ * Series without any color are skipped (consumer can fall back to a default), and
+ * so is any series whose color fails {@link isSafeCssColorValue}: the value never
+ * reaches the stylesheet, and the series falls back to its default exactly as an
+ * unset color would. `chartId` is escaped, so it cannot break out of the
+ * attribute selector either.
+ *
+ * @param chartId  Unique chart id (used as attribute value).
+ * @param config   Series configuration map.
+ */
+declare function buildChartCss(chartId: string, config: ChartConfig): string;
+/**
+ * Escape a string so it is safe to use as a CSS custom-property identifier or as
+ * an attribute selector value. The result only ever holds `[A-Za-z0-9_-]`.
+ *
+ * A string that is ALREADY an identifier passes through untouched, which is
+ * every real series key: `sales` stays `--color-sales`.
+ *
+ * Anything else has its unsafe characters replaced with `_` AND gains a short
+ * fingerprint of the ORIGINAL string, because the replacement alone is not
+ * injective. `'a b'` and `'a_b'` both collapse to `a_b`, and two series sharing
+ * one custom property is silent data loss: {@link buildChartCss} emits both
+ * declarations into the same rule so the last one wins, and
+ * {@link seriesColorVar} then resolves both series to that one token.
+ */
+declare function escapeCssIdent(input: string): string;
+/** Resolve the `var(--color-<key>)` reference for a given series. */
+declare function seriesColorVar(seriesKey: string): string;
+/**
+ * Resolve a raw per-datum colour to a paint value for an SVG attribute
+ * (`[attr.fill]`, `[attr.stroke]`).
+ *
+ * `raw` is `unknown` so a caller can hand over `datum[colorKey]` directly
+ * without its own `typeof` guard.
+ *
+ * The rule, which is the union of the two copies this replaces:
+ *  1. not a string, or empty            -> `fallback`
+ *  2. looks like a CSS colour or calls a
+ *     function (`var(`, `#`, `rgb`,
+ *     `hsl`, or a `(` anywhere)         -> used verbatim
+ *  3. anything else is a series key     -> `var(--color-<key>)`
+ *
+ * Deliberately NOT added: no `.trim()`, and no named-colour detector. Either
+ * would move an input that today lands on branch 3, so `'red'` stays a series
+ * key rather than becoming the colour red. That is the existing behaviour and
+ * changing it is a separate decision.
+ */
+declare function resolveSeriesColor(raw: unknown, fallback: string): string;
+
+/**
+ * Resolves the live spacing unit in pixels for SVG chart geometry, and re-emits
+ * when the global `theme-space` axis switches.
+ *
+ * Charts are the one part of the library CSS cannot reach: plot margins are
+ * numbers handed to SVG, not properties a token can cascade into. Without a
+ * bridge, choosing `compact` tightens every card and control on a dashboard and
+ * leaves the charts sitting in exactly as much white space as before -- one
+ * island of the old density in the middle of the new one.
+ *
+ * This is deliberately the same shape as {@link ChartThemeRadius}: an attribute
+ * `MutationObserver`, an SSR-safe read, and a fallback constant. Copying a
+ * pattern that already works beats inventing a second one, and it means both
+ * bridges can be tested the same way.
+ *
+ * It reads `--spacing-base`, NOT `--spacing`. They hold the same number, but
+ * `--spacing` is declared inside Tailwind's `@theme inline` block, which is
+ * inlined into utilities at build time and never lands on `<html>` as something
+ * `getComputedStyle` can read back. Reading it would have returned an empty
+ * string, and this bridge would have quietly served its fallback forever while
+ * looking perfectly correct.
+ *
+ * SSR-safe: with no document it returns the fallback and skips observing.
+ */
+declare class ChartThemeSpace {
+    private readonly document;
+    private readonly unitPx;
+    /** Resolved spacing unit (`--spacing-base`) in px; reactive to the theme-space axis. */
+    readonly px: _angular_core.Signal<number>;
+    constructor();
+    /** Scale one margin constant, expressed in spacing units, into pixels. */
+    scale(units: number): number;
+    private readUnitPx;
+    private toPx;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ChartThemeSpace, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<ChartThemeSpace>;
+}
+
+/** A single row of chart data — one categorical key + N numeric series. */
+type ChartDatum = Readonly<Record<string, unknown>>;
+/** Render-area margins inside the chart's SVG (px). */
+interface ChartMargin {
+    readonly top: number;
+    readonly right: number;
+    readonly bottom: number;
+    readonly left: number;
+}
+/**
+ * Default margins, one per chart geometry. THREE constants, not one: the
+ * families disagree on purpose, and collapsing them would silently relayout
+ * pie, radial, and radar.
+ *
+ * Cartesian charts need a bottom gutter for the axis and a wide left gutter for
+ * y tick labels. Polar charts have no axes to make room for. Radar needs
+ * symmetric room for its outer labels.
+ */
+declare const DEFAULT_CARTESIAN_MARGIN: ChartMargin;
+/** Polar geometry (pie, radial): no axis gutters. */
+declare const DEFAULT_POLAR_MARGIN: ChartMargin;
+/** Radar geometry: symmetric room for the outer axis labels. */
+declare const DEFAULT_RADAR_MARGIN: ChartMargin;
+/**
+ * The same three margins expressed in SPACING UNITS rather than pixels.
+ *
+ * A chart draws its plot area with numbers, so no token can cascade into it.
+ * These are what {@link ChartThemeSpace} multiplies by the live spacing unit, so
+ * plot gutters tighten along with everything else when the density axis moves.
+ *
+ * The px constants above stay exactly as they are, and stay exported. They are
+ * the published defaults and the SSR fallback, and at the `normal` preset the
+ * unit maths reproduces them precisely: 4px per unit gives back 8/8/24/40,
+ * 8 all round, and 24 all round.
+ */
+declare const DEFAULT_CARTESIAN_MARGIN_UNITS: ChartMargin;
+declare const DEFAULT_POLAR_MARGIN_UNITS: ChartMargin;
+declare const DEFAULT_RADAR_MARGIN_UNITS: ChartMargin;
+/** Axis orientation for cartesian charts. */
+type ChartOrientation = 'vertical' | 'horizontal';
+/** Primary axis scale — band for categorical, linear for numeric. */
+type CategoryScale = ScaleBand<string>;
+type ValueScale = ScaleLinear<number, number>;
+/**
+ * Cartesian plotting frame shared between a chart type (Bar, Line, Area…)
+ * and its axis / grid primitives.
+ *
+ * The owning chart component provides an instance and publishes its scales;
+ * descendants read them via signals and re-render when dimensions or data
+ * change.
+ */
+declare class CartesianContext {
+    /** Inner width (outer width − margin.left − margin.right). */
+    readonly innerWidth: _angular_core.WritableSignal<number>;
+    /** Inner height (outer height − margin.top − margin.bottom). */
+    readonly innerHeight: _angular_core.WritableSignal<number>;
+    /** Margins around the plotting area. */
+    readonly margin: _angular_core.WritableSignal<ChartMargin>;
+    /** Layout orientation (drives which axis holds the band scale). */
+    readonly orientation: _angular_core.WritableSignal<ChartOrientation>;
+    /** Band (categorical) scale. */
+    readonly categoryScale: _angular_core.WritableSignal<CategoryScale | null>;
+    /** Linear (numeric) scale. */
+    readonly valueScale: _angular_core.WritableSignal<ValueScale | null>;
+    /** Ordered category domain (e.g. x labels for vertical, y labels for horizontal). */
+    readonly categories: _angular_core.WritableSignal<readonly string[]>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<CartesianContext, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<CartesianContext>;
+}
+/** Resolve the scale that maps to the X axis for a given orientation. */
+declare function xScale(ctx: Pick<CartesianContext, 'orientation' | 'categoryScale' | 'valueScale'>): Signal<CategoryScale | ValueScale | null>;
+/** Resolve the scale that maps to the Y axis for a given orientation. */
+declare function yScale(ctx: Pick<CartesianContext, 'orientation' | 'categoryScale' | 'valueScale'>): Signal<CategoryScale | ValueScale | null>;
+/**
+ * The plot margin actually in effect: the consumer's `margin` input when they
+ * set one, otherwise the default scaled by the live spacing unit.
+ *
+ * An explicit `margin` always wins. A consumer who has already tuned their
+ * gutters chose those exact numbers, and quietly rescaling them when the
+ * density axis moves would override a decision they made on purpose.
+ *
+ * This is why the `margin` inputs accept `null` and default to it: a chart has
+ * to be able to tell "the caller wants 8px here" apart from "nobody said", and
+ * an eagerly-defaulted object cannot express the difference.
+ */
+declare function resolveChartMargin(margin: Signal<ChartMargin | null>, units: ChartMargin, space: ChartThemeSpace): Signal<ChartMargin>;
+
+/**
+ * Emitted when a datum-bearing mark is activated by pointer or keyboard: a
+ * line or area dot, a bar, a pie slice, a radial bar, a scatter point.
+ *
+ * Before this existed, each chart family declared its own interface with the
+ * same five fields, so a consumer handling two chart families wrote the same
+ * handler twice against two unrelated types. The per-family names are still
+ * exported, now as deprecated aliases of this one.
+ *
+ * The `= ChartDatum` default matters: every legacy alias and every
+ * `output<...ClickEvent>()` in the library is written without a type argument.
+ * It stays an `interface` so a consumer can still `extends` it.
+ */
+interface ChartPointClickEvent<TDatum = ChartDatum> {
+    /** Series the mark belongs to. This is the `--color-<key>` key. */
+    readonly seriesKey: string;
+    /**
+     * Index into the chart's own `data()` array. Always absolute: the line and
+     * area charts add their viewport offset before emitting, so a zoomed chart
+     * still reports the row the user actually clicked.
+     */
+    readonly datumIndex: number;
+    /** Categorical label of the mark. */
+    readonly category: string;
+    /** Numeric magnitude of the mark. */
+    readonly value: number;
+    /** The source row at `datumIndex`. */
+    readonly datum: TDatum;
+}
+
+interface ChartIndexRange {
+    readonly startIndex: number;
+    readonly endIndex: number;
+}
+type NumericDomain = readonly [number, number];
+declare function normalizeIndexRange(start: number, end: number, maxCount: number): ChartIndexRange | null;
+declare function effectiveIndexRange(range: ChartIndexRange | null, maxCount: number): ChartIndexRange | null;
+declare function indexRangeSize(range: ChartIndexRange | null, maxCount: number): number;
+declare function sliceByIndexRange<T>(data: readonly T[], range: ChartIndexRange | null): readonly T[];
+declare function zoomIndexRange(current: ChartIndexRange | null, maxCount: number, anchorIndex: number, factor: number): ChartIndexRange | null;
+declare function panIndexRange(current: ChartIndexRange | null, maxCount: number, deltaSteps: number): ChartIndexRange | null;
+/**
+ * The value domain for a chart drawn against a zero baseline.
+ *
+ * A bar, a line, or an area is read against the origin, so the domain has to
+ * reach it in both directions: negative data below, positive above. Clamping
+ * one end at zero is what pushed negative marks outside the plot.
+ *
+ * A dataset that is entirely zero would collapse the domain onto a point, which
+ * d3 maps to the middle of the range for every value, so it is opened by one
+ * unit instead.
+ */
+declare function zeroBaselineDomain(minValue: number, maxValue: number): NumericDomain;
+declare function normalizeNumericDomain(a: number, b: number): NumericDomain;
+declare function zoomNumericDomain(current: NumericDomain, full: NumericDomain, anchor: number, factor: number): NumericDomain;
+declare function panNumericDomain(current: NumericDomain, full: NumericDomain, delta: number): NumericDomain;
+
+declare class CategoricalViewportContext {
+    readonly dataCount: _angular_core.WritableSignal<number>;
+    readonly brushRange: _angular_core.WritableSignal<ChartIndexRange | null>;
+    readonly zoomRange: _angular_core.WritableSignal<ChartIndexRange | null>;
+    readonly hasZoom: _angular_core.Signal<boolean>;
+    resetZoom(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<CategoricalViewportContext, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<CategoricalViewportContext>;
+}
+
+/**
+ * The scaffolding every cartesian chart needs, in one place.
+ *
+ * Line, area, bar, and scatter each used to hand-roll the same four geometry
+ * computeds, the same layout-publishing effect, and the same click plus
+ * active-point plus aria-label handlers. That was around 55 duplicated lines per
+ * chart, and the copies had already drifted (three different aria-label
+ * wordings, two different ways of reaching the same margin default).
+ *
+ * What stays per chart is what genuinely differs: the layout computation, the
+ * event payload, and the aria-label sentence. Those come in as options.
+ */
+/**
+ * The minimum a rendered mark must expose to take part in the shared click and
+ * active-point plumbing. `LinePoint`, `BarRect`, and `ScatterPoint` already
+ * satisfy it structurally, so no layout type had to change.
+ *
+ * `datumIndex` here is the index into the VISIBLE window, not the full dataset.
+ * {@link CartesianChartSetup.resolveDatumIndex} converts it.
+ */
+interface CartesianMark {
+    readonly seriesKey: string;
+    readonly datumIndex: number;
+}
+interface CartesianChartOptions<M extends CartesianMark, E> {
+    /** The full, unwindowed dataset. A thunk so it is only read inside reactive contexts. */
+    readonly data: () => readonly ChartDatum[];
+    /** The chart's `margin` input. */
+    readonly margin: () => ChartMargin;
+    /**
+     * Present when the chart provides a `CartesianContext` (line, area, bar). The
+     * setup owns orientation, margin, and the inner geometry on it; scales and
+     * categories stay with the chart, in {@link publishLayout}. Scatter omits it.
+     */
+    readonly cartesian?: {
+        readonly context: CartesianContext;
+        readonly orientation: () => ChartOrientation;
+    };
+    /**
+     * Present when the chart supports index brush or zoom (line, area). It drives
+     * `visibleStartIndex` and `visibleData`, and the setup keeps its `dataCount`
+     * in step with the data. Bar and scatter omit it, and their `visibleData` is
+     * simply `data()`.
+     */
+    readonly viewport?: CategoricalViewportContext;
+    /**
+     * The chart-specific half of the layout effect: push this chart's own layout
+     * downstream. It runs inside the single effect the setup creates, so every
+     * signal it reads is tracked. It receives the inner geometry so it never has
+     * to reach back into the object it is being passed to.
+     */
+    readonly publishLayout?: (inner: {
+        readonly width: number;
+        readonly height: number;
+    }) => void;
+    /** The chart's click output. */
+    readonly click: {
+        /** Must be a bound lambda, not a detached `output.emit` reference. */
+        readonly emit: (event: E) => void;
+        /** `datumIndex` is absolute (the viewport offset is already applied). */
+        readonly payload: (mark: M, datumIndex: number, datum: ChartDatum) => E;
+    };
+    /**
+     * The aria-label for one mark. `seriesLabel` arrives already resolved from the
+     * chart config, so each chart only writes its own sentence.
+     */
+    readonly ariaLabel: (mark: M, seriesLabel: string) => string;
+}
+interface CartesianChartSetup<M extends CartesianMark> {
+    /** Plot width, margins removed, never negative. */
+    readonly innerWidth: Signal<number>;
+    /** Plot height, margins removed, never negative. */
+    readonly innerHeight: Signal<number>;
+    /** `viewBox` for the outer svg, in RAW dimensions (not the inner geometry). */
+    readonly viewBox: Signal<string>;
+    /** `transform` that moves the inner group inside the margins. */
+    readonly innerTransform: Signal<string>;
+    /** First absolute index the current window shows. `0` without a viewport. */
+    readonly visibleStartIndex: Signal<number>;
+    /** The windowed data, or the whole dataset when there is no viewport. */
+    readonly visibleData: Signal<readonly ChartDatum[]>;
+    /** Absolute index into the full dataset for a rendered mark. */
+    resolveDatumIndex(mark: M): number;
+    /** `config[key].label` when the chart config names the series, else the key. */
+    seriesLabel(seriesKey: string): string;
+    /** The four handlers a chart template binds. */
+    pointAriaLabel(mark: M): string;
+    emitClick(mark: M): void;
+    /**
+     * Accepts a pointer gesture as well as keyboard focus: a chart whose marks are
+     * the only hover surface (scatter has no `ChartPointerTracker`) has nothing
+     * else to publish an active point from.
+     */
+    setActivePoint(event: PointerEvent | FocusEvent, mark: M): void;
+    clearActivePoint(): void;
+}
+/**
+ * Build the shared cartesian scaffolding.
+ *
+ * MUST be called in an injection context, so a field initializer or the
+ * constructor: it injects `ChartContext` and creates one `effect`.
+ */
+declare function setupCartesianChart<M extends CartesianMark, E>(options: CartesianChartOptions<M, E>): CartesianChartSetup<M>;
+
+/**
+ * The scaffolding every polar chart needs, in one place.
+ *
+ * The sibling of {@link setupCartesianChart} for the charts that draw around a
+ * centre rather than along two axes. Pie, radar, and radial each hand-rolled the
+ * same four geometry computeds and the same active-point handler — around 90
+ * duplicated lines — and every copy of the handler re-derived the element
+ * rectangle inline even though `elementClientCenter` already existed.
+ *
+ * What stays per chart is what genuinely differs: the layout computation, the
+ * centring transform it produces, and the click payload. A polar chart has no
+ * viewport, no orientation, and nothing to publish downstream, so unlike the
+ * cartesian setup this one owns no effect.
+ */
+/**
+ * The minimum a rendered mark must expose to take part in the shared
+ * active-point plumbing. `PieSliceRect` and `RadialBarRect` already satisfy it
+ * structurally; radar builds one per dot from its axis index.
+ *
+ * A polar chart draws its whole dataset at once, so there is no visible window
+ * and `datumIndex` is always absolute.
+ */
+interface PolarMark {
+    readonly seriesKey: string;
+    readonly datumIndex: number;
+}
+interface PolarChartOptions {
+    /** The chart's `margin` input. */
+    readonly margin: () => ChartMargin;
+}
+interface PolarChartSetup {
+    /** Plot width, margins removed, never negative. */
+    readonly innerWidth: Signal<number>;
+    /** Plot height, margins removed, never negative. */
+    readonly innerHeight: Signal<number>;
+    /** `viewBox` for the outer svg, in RAW dimensions (not the inner geometry). */
+    readonly viewBox: Signal<string>;
+    /** `transform` that moves the inner group inside the margins. */
+    readonly innerTransform: Signal<string>;
+    /** `config[key].label` when the chart config names the series, else the key. */
+    seriesLabel(seriesKey: string): string;
+    /** The two handlers a chart template binds. */
+    setActivePoint(event: PointerEvent | FocusEvent, mark: PolarMark): void;
+    clearActivePoint(): void;
+}
+/**
+ * Build the shared polar scaffolding.
+ *
+ * MUST be called in an injection context, so a field initializer or the
+ * constructor: it injects `ChartContext`.
+ */
+declare function setupPolarChart(options: PolarChartOptions): PolarChartSetup;
+
+/** Pixel dimensions of the chart render area. */
+interface ChartDimensions {
+    readonly width: number;
+    readonly height: number;
+}
+/** Active data point (for tooltip / crosshair) shared across primitives. */
+interface ChartActivePoint {
+    readonly index: number;
+    readonly datumIndex?: number;
+    readonly seriesKey?: string;
+    readonly clientX?: number;
+    readonly clientY?: number;
+}
+/**
+ * Shared chart state provided by `ChartContainer` to all nested chart
+ * components (axes, grid, tooltip, legend, chart types).
+ *
+ * All state is exposed as signals so consumers can derive computed state
+ * (scales, visible series, tooltip position) without manual subscriptions.
+ */
+declare class ChartContext {
+    /** Stable instance id — used in the `data-chart` attribute and CSS scope. */
+    readonly id: _angular_core.WritableSignal<string>;
+    /** User-provided series config. */
+    readonly config: _angular_core.WritableSignal<Readonly<Record<string, _ojiepermana_angular_chart_core.ChartSeriesConfig>>>;
+    /** Measured render-area dimensions (ResizeObserver-driven). */
+    readonly dimensions: _angular_core.WritableSignal<ChartDimensions>;
+    /** Currently highlighted data point (tooltip / crosshair). */
+    readonly activePoint: _angular_core.WritableSignal<ChartActivePoint | null>;
+    /** Series keys the user has toggled off via legend. */
+    readonly hiddenSeries: _angular_core.WritableSignal<ReadonlySet<string>>;
+    /** Ordered list of series keys (from `config`). */
+    readonly seriesKeys: Signal<readonly string[]>;
+    /** Series keys currently visible (config order minus `hiddenSeries`). */
+    readonly visibleSeriesKeys: Signal<readonly string[]>;
+    /** Toggle visibility of a series. */
+    toggleSeries(key: string): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ChartContext, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<ChartContext>;
+}
+
+/**
+ * Emits a scoped `<style>` block mapping every series key in the current
+ * `ChartConfig` to a `--color-<key>` CSS custom property, scoped to
+ * `[data-chart="<id>"]`. Dark-mode values are scoped under `[data-mode="dark"]`.
+ *
+ * Implemented as an empty component that injects a real `<style>` element
+ * into its host via `Renderer2`. We avoid rendering `<style>` directly in a
+ * template — Angular hoists those into component CSS and strips
+ * interpolations from them.
+ *
+ * Consumers never instantiate this directly — `ChartContainer` renders it.
+ */
+declare class ChartStyle {
+    private readonly ctx;
+    private readonly host;
+    private readonly renderer;
+    private styleEl;
+    protected readonly css: _angular_core.Signal<string>;
+    constructor();
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ChartStyle, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<ChartStyle, "ChartStyle", never, {}, {}, never, never, true, never>;
+}
+
+/**
+ * Presentational style of a chart family.
+ *
+ * Every chart component exposes a `styles` input that defaults to `'base'`
+ * (the classic look). Families may widen this union with their own custom
+ * styles — e.g. the bar family adds `'dot'` for a dot-matrix rendering.
+ *
+ * Custom styles are implemented inside each chart family (not in the theme
+ * library) but must only use theme CSS variables (`--muted`, `--color-<key>`,
+ * …) so they follow the active theme automatically.
+ */
+type ChartStyleVariant = 'base';
+/**
+ * Resolve the effective chart style from the canonical `styleVariant` input and
+ * the deprecated `styles` input.
+ *
+ * `styleVariant` wins whenever it is bound, which is the only direction that is
+ * implementable: `styles` keeps its `'base'` default, so there is no way to tell
+ * an explicit `styles="base"` from an unset one. Giving `styleVariant` the
+ * `undefined` default leaves the deprecated input's emitted type untouched.
+ *
+ * The precedence rule lives here alone, so the seven chart families cannot drift
+ * from each other. The two `input()` calls themselves have to stay literal in
+ * each class body: the compiler discovers signal inputs by looking at the field
+ * initializer, and an `input()` hidden behind a helper is never registered.
+ */
+declare function resolveChartStyle<T extends string>(styleVariant: () => T | undefined, styles: () => T): Signal<T>;
+
+/**
+ * Root of every chart. Provides `ChartContext` to descendants, reflects the
+ * chart id via `data-chart`, injects the per-instance CSS-variable
+ * `<style>` block, and tracks its render-area dimensions via
+ * `ResizeObserver`.
+ *
+ * Usage:
+ * ```html
+ * <Chart [config]="cfg">
+ *   <ChartBar [data]="data" />
+ *   <ChartLegend />
+ * </Chart>
+ * ```
+ *
+ * The chart render area is laid out on top; any projected `<ChartLegend>` is
+ * rendered as a centered row beneath it. Render-area dimensions are measured on
+ * the chart area only, so the legend never shrinks the chart.
+ */
+declare class ChartContainer {
+    protected readonly ctx: ChartContext;
+    private readonly zone;
+    private readonly platformId;
+    private readonly destroyRef;
+    private readonly areaRef;
+    /** Series configuration. Required for color / label resolution. */
+    readonly config: _angular_core.InputSignal<Readonly<Record<string, _ojiepermana_angular_chart_core.ChartSeriesConfig>>>;
+    /**
+     * Tailwind aspect-ratio utility for the chart render area. Defaults to
+     * `aspect-video` for cartesian charts; override with `aspect-square` for
+     * radial / pie layouts, or e.g. `aspect-auto h-80` for a fixed height.
+     */
+    readonly aspect: _angular_core.InputSignal<string>;
+    protected readonly areaClass: _angular_core.Signal<string>;
+    /**
+     * Optional explicit id override. When omitted, a stable auto-id is
+     * generated (`chart-<n>`), unique across the document.
+     */
+    readonly chartId: _angular_core.InputSignal<string | null>;
+    constructor();
+    private observeSize;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ChartContainer, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<ChartContainer, "Chart", never, { "config": { "alias": "config"; "required": true; "isSignal": true; }; "aspect": { "alias": "aspect"; "required": false; "isSignal": true; }; "chartId": { "alias": "chartId"; "required": false; "isSignal": true; }; }, {}, never, ["*", "ChartLegend"], true, never>;
+}
+
+/** Screen-reader fallback for charts whose visual SVG is not tabular content. */
+declare class ChartDataTable {
+    readonly data: _angular_core.InputSignal<readonly Readonly<Record<string, unknown>>[]>;
+    readonly columns: _angular_core.InputSignal<readonly string[]>;
+    readonly label: _angular_core.InputSignal<string>;
+    readonly rowHeaderKey: _angular_core.InputSignal<string | null>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ChartDataTable, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<ChartDataTable, "ChartDataTable", never, { "data": { "alias": "data"; "required": true; "isSignal": true; }; "columns": { "alias": "columns"; "required": true; "isSignal": true; }; "label": { "alias": "label"; "required": false; "isSignal": true; }; "rowHeaderKey": { "alias": "rowHeaderKey"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Keeps dense SVG charts to one tab stop while preserving arrow-key access to
+ * every interactive mark. Marks are discovered by their `role="img"` and
+ * `tabindex` attributes so chart implementations do not need a shared base
+ * class or additional DOM wrappers.
+ */
+declare class ChartRovingFocus {
+    private readonly host;
+    private readonly destroyRef;
+    private activeMark;
+    constructor();
+    protected onFocusIn(event: FocusEvent): void;
+    protected onKeydown(event: KeyboardEvent): void;
+    private marks;
+    private syncTabStops;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ChartRovingFocus, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ChartRovingFocus, "svg[ChartRovingFocus]", never, {}, {}, never, never, true, never>;
+}
+
+/**
+ * The focus treatment shared by every interactive chart mark.
+ *
+ * SVG shapes cannot carry the `ring-*` box-shadow the HTML controls use, so the
+ * indicator is painted as a stroke in the theme's dedicated `--ring` token,
+ * which is a near-black in light mode and a near-white in dark mode and so
+ * separates the focused mark from its own fill on either ground. The class
+ * takes precedence over the `stroke` presentation attribute a mark may already
+ * carry, which is why the emphasis strokes bound elsewhere do not have to know
+ * about focus at all.
+ *
+ * `outline-none` lives here rather than in the templates so the suppression and
+ * its replacement can never drift apart.
+ */
+declare class ChartMarkFocus {
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ChartMarkFocus, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ChartMarkFocus, "[ChartMarkFocus]", never, {}, {}, never, never, true, never>;
+}
+
+declare class ScatterViewportContext {
+    readonly innerWidth: _angular_core.WritableSignal<number>;
+    readonly innerHeight: _angular_core.WritableSignal<number>;
+    readonly fullXDomain: _angular_core.WritableSignal<NumericDomain | null>;
+    readonly fullYDomain: _angular_core.WritableSignal<NumericDomain | null>;
+    readonly zoomXDomain: _angular_core.WritableSignal<NumericDomain | null>;
+    readonly zoomYDomain: _angular_core.WritableSignal<NumericDomain | null>;
+    readonly xScale: _angular_core.WritableSignal<ScaleLinear<number, number, never> | null>;
+    readonly yScale: _angular_core.WritableSignal<ScaleLinear<number, number, never> | null>;
+    readonly hasZoom: _angular_core.Signal<boolean>;
+    resetZoom(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ScatterViewportContext, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<ScatterViewportContext>;
+}
+
+/** A tick descriptor for rendering axes. */
+interface ChartTick {
+    readonly value: string | number;
+    /** Offset (px) along the axis. For band scales this is the band center. */
+    readonly offset: number;
+    /** Display label. */
+    readonly label: string;
+}
+/** Produce evenly-spaced ticks for a band (categorical) scale. */
+declare function bandTicks(scale: ScaleBand<string>): ChartTick[];
+/**
+ * Produce ticks for a linear scale.
+ *
+ * @param scale      The linear scale.
+ * @param count      Approximate number of ticks (hint, d3 may return fewer/more).
+ * @param formatter  Label formatter.
+ */
+declare function linearTicks(scale: ScaleLinear<number, number>, count?: number, formatter?: (value: number) => string): ChartTick[];
+
+interface ClientPoint {
+    readonly clientX: number;
+    readonly clientY: number;
+}
+/**
+ * Given a pointer event's local (x, y) relative to the chart's inner group,
+ * resolve the nearest category index along the categorical axis.
+ *
+ * @returns index into `ctx.categories()` (or −1 if no scale / no data).
+ */
+declare function nearestCategoryIndex(ctx: Pick<CartesianContext, 'categoryScale' | 'categories' | 'orientation'>, localX: number, localY: number): number;
+/** Resolve the client-space center point of a focused or clicked SVG/HTML element. */
+declare function elementClientCenter(target: EventTarget | null): ClientPoint | null;
+/**
+ * Where the tooltip should sit for whichever gesture activated a mark.
+ *
+ * A pointer carries a real cursor position, so the tooltip follows it. Keyboard
+ * focus carries none, and falls back to the centre of the mark that took focus.
+ */
+declare function activationClientPoint(event: PointerEvent | FocusEvent): ClientPoint | null;
+
+/**
+ * Read a numeric value from a datum, tolerating strings.
+ *
+ * Every layout in this library reads its numbers through here. Bar and line
+ * each used to carry their own identical copy while the polar and scatter
+ * layouts reached for a bare `Number(d[key] ?? 0)`, so the same dataset drew
+ * correctly as a bar chart and silently lost marks as a pie: `Number('n/a')`
+ * is `NaN`, and a `NaN` flows straight into the path data.
+ *
+ * Anything that is not a finite number or a parseable numeric string reads as
+ * `0`. That is the behaviour bar and line already shipped, so it is the one the
+ * rest of the family adopts.
+ */
+declare function readNumber(datum: ChartDatum, key: string): number;
+
+/** Curve type shared by line & area charts. */
+type LineCurve = 'linear' | 'monotone' | 'step';
+/** A single series ready to render as either a line or an area. */
+interface LineSeriesPath {
+    readonly seriesKey: string;
+    readonly color: string;
+    readonly linePath: string;
+    /** Optional area path — only populated when `computeAreaLayout` is used. */
+    readonly areaPath?: string;
+    /** Raw points for dots / active markers. */
+    readonly points: readonly LinePoint[];
+}
+/** One resolved (x, y) point for a series. */
+interface LinePoint {
+    readonly seriesKey: string;
+    readonly datumIndex: number;
+    readonly category: string;
+    readonly value: number;
+    readonly x: number;
+    readonly y: number;
+}
+interface CartesianBase {
+    readonly data: readonly ChartDatum[];
+    readonly xKey: string;
+    readonly seriesKeys: readonly string[];
+    readonly orientation: ChartOrientation;
+    readonly innerWidth: number;
+    readonly innerHeight: number;
+    readonly curve: LineCurve;
+}
+interface LineLayoutResult {
+    readonly series: readonly LineSeriesPath[];
+    readonly points: readonly LinePoint[];
+    readonly categoryScale: ReturnType<typeof scalePoint<string>>;
+    readonly valueScale: ReturnType<typeof scaleLinear<number, number>>;
+    readonly categories: readonly string[];
+}
+interface AreaLayoutResult extends LineLayoutResult {
+    readonly stacked: boolean;
+}
+/** Build category + value scales for point-based charts (line / area). */
+declare function buildCartesianScales(input: CartesianBase): {
+    categories: readonly string[];
+    categoryScale: ReturnType<typeof scalePoint<string>>;
+    valueScale: ReturnType<typeof scaleLinear<number, number>>;
+};
+/** Compute line-chart geometry. */
+declare function computeLineLayout(input: CartesianBase): LineLayoutResult;
+interface AreaLayoutInput extends CartesianBase {
+    readonly stacked: boolean;
+    readonly expanded?: boolean;
+}
+/** Compute area-chart geometry (single or stacked). */
+declare function computeAreaLayout(input: AreaLayoutInput): AreaLayoutResult;
+
+/**
+ * Publish a `scalePoint` from line/area layouts to the `CartesianContext`,
+ * which expects a `scaleBand`. Line/area points sit on the range edges (the
+ * point scale has zero padding, so the first point touches the y-axis and the
+ * last touches the right edge). We extend the band range by half a step on
+ * each side so band centers — used to position axis ticks — line up exactly
+ * with those edge-touching points.
+ *
+ * This keeps axes/grid primitives agnostic to whether the underlying chart
+ * uses `scaleBand` (bar) or `scalePoint` (line/area).
+ */
+declare function pointToBandAdapter(pointScale: ScalePoint<string>, range: [number, number]): ReturnType<typeof scaleBand<string>>;
+/** Recreate a linear scale with the same domain/range (handy for effects). */
+declare function cloneLinear(scale: ReturnType<typeof scaleLinear<number, number>>): ReturnType<typeof scaleLinear<number, number>>;
+declare function provideCartesianFromLineLayout(ctx: CartesianContext, layout: {
+    categoryScale: ScalePoint<string>;
+    valueScale: ReturnType<typeof scaleLinear<number, number>>;
+    categories: readonly string[];
+}, orientation: 'vertical' | 'horizontal', innerWidth: number, innerHeight: number): void;
+
+/**
+ * Resolves the live theme corner radius (the `--radius` token) in pixels for SVG
+ * chart geometry, and re-emits when the global `theme-radius` axis switches.
+ *
+ * SVG `rx`/`ry` need px numbers, so this reads the computed `--radius` off
+ * `<html>` and converts rem→px. A `MutationObserver` on the `<html theme-radius>`
+ * attribute keeps the `px` signal in sync with `ThemeRadiusService` at runtime;
+ * charts default their corner radius to this value (still overridable per chart).
+ *
+ * SSR-safe: with no document it returns the `md` fallback and skips observing.
+ */
+declare class ChartThemeRadius {
+    private readonly document;
+    private readonly basePx;
+    /** Resolved base radius (`--radius`) in px; reactive to the theme-radius axis. */
+    readonly px: _angular_core.Signal<number>;
+    constructor();
+    private readBasePx;
+    private toPx;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ChartThemeRadius, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<ChartThemeRadius>;
+}
+
+export { CHART_DATA_ATTRIBUTE, CHART_THEMES, CartesianContext, CategoricalViewportContext, ChartContainer, ChartContext, ChartDataTable, ChartMarkFocus, ChartRovingFocus, ChartStyle, ChartThemeRadius, ChartThemeSpace, DEFAULT_CARTESIAN_MARGIN, DEFAULT_CARTESIAN_MARGIN_UNITS, DEFAULT_POLAR_MARGIN, DEFAULT_POLAR_MARGIN_UNITS, DEFAULT_RADAR_MARGIN, DEFAULT_RADAR_MARGIN_UNITS, ScatterViewportContext, activationClientPoint, bandTicks, buildCartesianScales, buildChartCss, cloneLinear, computeAreaLayout, computeLineLayout, effectiveIndexRange, elementClientCenter, escapeCssIdent, indexRangeSize, isSafeCssColorValue, linearTicks, nearestCategoryIndex, normalizeIndexRange, normalizeNumericDomain, panIndexRange, panNumericDomain, pointToBandAdapter, provideCartesianFromLineLayout, readNumber, resolveChartMargin, resolveChartStyle, resolveSeriesColor, seriesColorVar, setupCartesianChart, setupPolarChart, sliceByIndexRange, xScale, yScale, zeroBaselineDomain, zoomIndexRange, zoomNumericDomain };
+export type { AreaLayoutInput, AreaLayoutResult, CartesianBase, CartesianChartOptions, CartesianChartSetup, CartesianMark, CategoryScale, ChartActivePoint, ChartConfig, ChartDatum, ChartDimensions, ChartIndexRange, ChartMargin, ChartOrientation, ChartPointClickEvent, ChartSeriesConfig, ChartStyleVariant, ChartThemeKey, ChartTick, ClientPoint, LineCurve, LineLayoutResult, LinePoint, LineSeriesPath, NumericDomain, PolarChartOptions, PolarChartSetup, PolarMark, ValueScale };