@sproutsocial/seeds-react-data-viz 0.7.32 → 0.14.0

package/dist/bar/index.d.mts

@@ -0,0 +1,208 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { TypeIconName } from '@sproutsocial/seeds-react-icon';
+import { c as TypeChartNumberFormat, k as TypeChartStyleColor } from '../types-B7ILUQ6_.mjs';
+import { C as ChartExportHandle } from '../chartExport-CKYpuhik.mjs';
+import 'highcharts';
+
+type TypeValuePercentInput = "decimal" | "whole";
+type TypeValueFormatterOptions = Readonly<{
+    /** The raw numeric value. For duration, milliseconds. */
+    value: number;
+    /** default "decimal" */
+    numberFormat?: TypeChartNumberFormat;
+    /** Only used when numberFormat === "currency". default "USD" */
+    currency?: string;
+    /** true → 10k threshold; number → max(1000, abs(n)); false → never. default true */
+    abbreviate?: boolean | number;
+    /** "decimal" scales 0.42 → "42%"; "whole" treats 42 → "42%". default "decimal" */
+    percentInput?: TypeValuePercentInput;
+    /** locale for decimal/currency/percent (formatNumeral) */
+    numberLocale?: Intl.LocalesArgument;
+    /** locale for duration (formatDuration) */
+    textLocale?: Intl.LocalesArgument;
+}>;
+/**
+ * Declarative value-format config for axis ticks and the default tooltip — the
+ * full {@link TypeValueFormatterOptions} surface minus `value`, which is
+ * supplied per-tick / per-row by the caller (the adapter and tooltip).
+ */
+type ValueFormat = Omit<TypeValueFormatterOptions, "value">;
+
+interface ChartTooltipDataRow {
+    color: TypeChartStyleColor;
+    name: string;
+    value: number | null;
+}
+/** Tooltip render-prop signature for v2 charts. */
+interface ChartTooltipProps {
+    data: ChartTooltipDataRow[];
+    /** Resolved x-axis position. Category name for category axes, numeric for time/linear. */
+    position: number | string;
+    /** Resolved chart timezone — pass to date formatters when `position` is a numeric timestamp. Undefined on category axes. */
+    timezone?: string;
+    /** Declarative annotation anchored at this position, if any. Rendered in the tooltip header. */
+    annotation?: {
+        icon?: TypeIconName;
+        color?: string;
+        title?: string;
+        description?: string;
+    };
+    /** True when the chart has an `onClick` handler — used by the default tooltip to render the click-label footer. */
+    hasOnClick?: boolean;
+    /** Footer content shown in the default tooltip when the chart is clickable. */
+    tooltipClickLabel?: ReactNode;
+    /** Content shown in place of a row's value when the value is null. Defaults to an em-dash. */
+    invalidNumberLabel?: ReactNode;
+    /** Declarative value format for the tooltip value cell. Omit for raw rendering. Applied at full precision (abbreviation off). */
+    valueFormat?: ValueFormat;
+}
+
+/**
+ * Declarative annotation shape — the DS renders the marker and tooltip header
+ * internally; consumers don't supply render functions. See CE-7.
+ */
+interface ChartAnnotation {
+    /** Numeric x-axis coordinate — a category index (category axes) or the raw coordinate (datetime/linear axes). */
+    position: number;
+    /** Icon shown above the chart at `position` and inline with `title` in the tooltip header. */
+    icon?: TypeIconName;
+    /** Color applied to the marker's vertical line. */
+    color?: string;
+    /** Tooltip header line 1. */
+    title?: string;
+    /** Tooltip header line 2. */
+    description?: string;
+}
+
+/**
+ * Pure, Highcharts-free datetime axis label formatter for v2 chart families.
+ *
+ * Ports v1's `helpers/xAxisLabelFormatter` into a rendering-agnostic shape: it
+ * returns a `{ primary, secondary? }` object instead of an HTML string, leaving
+ * SVG rendering to the caller. The timezone- and DST-correct boundary detection
+ * (calendar parts read in the target timezone) and the per-granularity
+ * `Intl.DateTimeFormat` option sets are a near-verbatim port of v1.
+ *
+ * The one net-new piece versus v1 is granularity derivation: v1 receives
+ * `unitName` from Highcharts, but `charts/` may not depend on Highcharts types
+ * (see `charts/README.md` invariants), so granularity is derived from the
+ * spacing of `tickPositions`.
+ */
+type DatetimeTimeFormat = "12" | "24";
+
+/** A datetime data point: `[msSinceEpoch, value]` tuple or `{ x, y }` object. */
+type DatetimePoint = [number, number | null] | {
+    x: number;
+    y: number | null;
+};
+/** A value on a category axis, or a datetime point when the axis is `"datetime"`. */
+type ChartDataPoint = number | null | DatetimePoint;
+/** Category axis — labels indexed parallel to `series.data`. The default axis type. */
+interface CategoryAxis {
+    type?: "category";
+    /** Category labels, indexed parallel to `series.data`. */
+    categories: Array<string>;
+    crosshair?: boolean;
+}
+/** Datetime axis — `series.data` carries timestamped points. */
+interface DatetimeAxis {
+    type: "datetime";
+    crosshair?: boolean;
+    /**
+     * 12- or 24-hour clock for hour-granularity tick labels (e.g. `9 AM` vs
+     * `09:00`). Default `"12"`. Coarser granularities (day/month/year) ignore it.
+     */
+    timeFormat?: DatetimeTimeFormat;
+}
+
+/** A datetime data point: `[msSinceEpoch, value]` tuple or `{ x, y }` object. */
+type BarDatetimePoint = DatetimePoint;
+/** A category y-value, or a datetime point when the dimensional axis is `"datetime"`. */
+type BarDataPoint = ChartDataPoint;
+interface BarSeries {
+    name: string;
+    /**
+     * Y-values indexed parallel to `xAxis.categories` on a category axis, or
+     * `[timestamp, value]` / `{ x, y }` points on a datetime axis.
+     */
+    data: Array<BarDataPoint>;
+    color?: string;
+    /** Seeds icon or partner-logo name rendered before the series name in the legend. */
+    icon?: TypeIconName;
+}
+type BarXAxis = CategoryAxis | DatetimeAxis;
+interface BarYAxis {
+    min?: number;
+    max?: number;
+    /** Default: true. */
+    showGridLines?: boolean;
+    title?: string;
+    /**
+     * Declarative value formatting applied to y-axis tick labels and the default
+     * tooltip value. Omit for the zero-config decimal default (smart 1k/10k
+     * abbreviation on the axis, raw values in the tooltip).
+     */
+    format?: ValueFormat;
+    /**
+     * Show y-axis tick labels. Default `true`. `false` hides them (maps to
+     * Highcharts' `labels.enabled`, replacing v1's `() => ""` formatter trick).
+     */
+    showLabels?: boolean;
+}
+/**
+ * Direction in which bars are drawn. Single-member union for now; expands to
+ * `"vertical" | "horizontal"` when `HorizontalBarChart` ships.
+ */
+type BarChartDirection = "vertical";
+interface BarChartProps {
+    /** Wired into Highcharts' `accessibility.description`. */
+    description: string;
+    series: Array<BarSeries>;
+    /**
+     * Maximum number of series to display. Series beyond the limit are dropped to
+     * keep the chart readable and accessible. Default `10`.
+     */
+    seriesLimit?: number;
+    /**
+     * Suppress the `console.warn` emitted when the series count exceeds the limit.
+     * The cap still applies. Default `false`.
+     */
+    hideSeriesLimitWarning?: boolean;
+    xAxis: BarXAxis;
+    yAxis?: BarYAxis;
+    /** IANA timezone for datetime-axis ticks and tooltips. Default `"UTC"`. Ignored for category axes. */
+    timezone?: string;
+    /**
+     * Stacking mode for multi-series charts. Defaults to `"normal"` — the
+     * canonical design-system spec renders multi-series bar charts as a single
+     * stacked column per category. `"percent"` normalizes each column to 100%.
+     * `"grouped"` renders series as adjacent bars per category; not part of the
+     * canonical spec, but available for non-standard use cases.
+     */
+    stacking?: "normal" | "percent" | "grouped";
+    /** Appended to each tooltip value (e.g., `" MT"`, `"%"`). */
+    valueSuffix?: string;
+    /** Override for the default tooltip content. */
+    tooltip?: (args: ChartTooltipProps) => ReactNode;
+    /** Declarative annotations rendered at positions on the chart. */
+    annotations?: ChartAnnotation[];
+    /** Click handler invoked with the dimensional-axis value of the clicked column — the category name on a category axis, the numeric timestamp on a datetime axis. `position` is direction-agnostic: the x-axis value on `VerticalBarChart`, the y-axis value on `HorizontalBarChart`. */
+    onClick?: ({ position }: {
+        position: number | string;
+    }) => void;
+    /** Footer content shown in the default tooltip when `onClick` is set. */
+    tooltipClickLabel?: ReactNode;
+    /** Override for the value shown when a data point is invalid/missing (null). Defaults to an em-dash. */
+    invalidNumberLabel?: ReactNode;
+    /**
+     * Fired once per chart instance with an opaque {@link ChartExportHandle} for
+     * triggering PNG/SVG/PDF/CSV downloads. Re-fires only on a genuine remount,
+     * never on data or prop updates.
+     */
+    onReady?: (handle: ChartExportHandle) => void;
+}
+
+declare const VerticalBarChart: react.NamedExoticComponent<BarChartProps>;
+
+export { type BarChartDirection, type BarChartProps, type BarDataPoint, type BarDatetimePoint, type BarSeries, type BarXAxis, type BarYAxis, type CategoryAxis, ChartExportHandle, type DatetimeAxis, type ValueFormat, VerticalBarChart };

package/dist/bar/index.d.ts

@@ -0,0 +1,208 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { TypeIconName } from '@sproutsocial/seeds-react-icon';
+import { c as TypeChartNumberFormat, k as TypeChartStyleColor } from '../types-B7ILUQ6_.js';
+import { C as ChartExportHandle } from '../chartExport-CKYpuhik.js';
+import 'highcharts';
+
+type TypeValuePercentInput = "decimal" | "whole";
+type TypeValueFormatterOptions = Readonly<{
+    /** The raw numeric value. For duration, milliseconds. */
+    value: number;
+    /** default "decimal" */
+    numberFormat?: TypeChartNumberFormat;
+    /** Only used when numberFormat === "currency". default "USD" */
+    currency?: string;
+    /** true → 10k threshold; number → max(1000, abs(n)); false → never. default true */
+    abbreviate?: boolean | number;
+    /** "decimal" scales 0.42 → "42%"; "whole" treats 42 → "42%". default "decimal" */
+    percentInput?: TypeValuePercentInput;
+    /** locale for decimal/currency/percent (formatNumeral) */
+    numberLocale?: Intl.LocalesArgument;
+    /** locale for duration (formatDuration) */
+    textLocale?: Intl.LocalesArgument;
+}>;
+/**
+ * Declarative value-format config for axis ticks and the default tooltip — the
+ * full {@link TypeValueFormatterOptions} surface minus `value`, which is
+ * supplied per-tick / per-row by the caller (the adapter and tooltip).
+ */
+type ValueFormat = Omit<TypeValueFormatterOptions, "value">;
+
+interface ChartTooltipDataRow {
+    color: TypeChartStyleColor;
+    name: string;
+    value: number | null;
+}
+/** Tooltip render-prop signature for v2 charts. */
+interface ChartTooltipProps {
+    data: ChartTooltipDataRow[];
+    /** Resolved x-axis position. Category name for category axes, numeric for time/linear. */
+    position: number | string;
+    /** Resolved chart timezone — pass to date formatters when `position` is a numeric timestamp. Undefined on category axes. */
+    timezone?: string;
+    /** Declarative annotation anchored at this position, if any. Rendered in the tooltip header. */
+    annotation?: {
+        icon?: TypeIconName;
+        color?: string;
+        title?: string;
+        description?: string;
+    };
+    /** True when the chart has an `onClick` handler — used by the default tooltip to render the click-label footer. */
+    hasOnClick?: boolean;
+    /** Footer content shown in the default tooltip when the chart is clickable. */
+    tooltipClickLabel?: ReactNode;
+    /** Content shown in place of a row's value when the value is null. Defaults to an em-dash. */
+    invalidNumberLabel?: ReactNode;
+    /** Declarative value format for the tooltip value cell. Omit for raw rendering. Applied at full precision (abbreviation off). */
+    valueFormat?: ValueFormat;
+}
+
+/**
+ * Declarative annotation shape — the DS renders the marker and tooltip header
+ * internally; consumers don't supply render functions. See CE-7.
+ */
+interface ChartAnnotation {
+    /** Numeric x-axis coordinate — a category index (category axes) or the raw coordinate (datetime/linear axes). */
+    position: number;
+    /** Icon shown above the chart at `position` and inline with `title` in the tooltip header. */
+    icon?: TypeIconName;
+    /** Color applied to the marker's vertical line. */
+    color?: string;
+    /** Tooltip header line 1. */
+    title?: string;
+    /** Tooltip header line 2. */
+    description?: string;
+}
+
+/**
+ * Pure, Highcharts-free datetime axis label formatter for v2 chart families.
+ *
+ * Ports v1's `helpers/xAxisLabelFormatter` into a rendering-agnostic shape: it
+ * returns a `{ primary, secondary? }` object instead of an HTML string, leaving
+ * SVG rendering to the caller. The timezone- and DST-correct boundary detection
+ * (calendar parts read in the target timezone) and the per-granularity
+ * `Intl.DateTimeFormat` option sets are a near-verbatim port of v1.
+ *
+ * The one net-new piece versus v1 is granularity derivation: v1 receives
+ * `unitName` from Highcharts, but `charts/` may not depend on Highcharts types
+ * (see `charts/README.md` invariants), so granularity is derived from the
+ * spacing of `tickPositions`.
+ */
+type DatetimeTimeFormat = "12" | "24";
+
+/** A datetime data point: `[msSinceEpoch, value]` tuple or `{ x, y }` object. */
+type DatetimePoint = [number, number | null] | {
+    x: number;
+    y: number | null;
+};
+/** A value on a category axis, or a datetime point when the axis is `"datetime"`. */
+type ChartDataPoint = number | null | DatetimePoint;
+/** Category axis — labels indexed parallel to `series.data`. The default axis type. */
+interface CategoryAxis {
+    type?: "category";
+    /** Category labels, indexed parallel to `series.data`. */
+    categories: Array<string>;
+    crosshair?: boolean;
+}
+/** Datetime axis — `series.data` carries timestamped points. */
+interface DatetimeAxis {
+    type: "datetime";
+    crosshair?: boolean;
+    /**
+     * 12- or 24-hour clock for hour-granularity tick labels (e.g. `9 AM` vs
+     * `09:00`). Default `"12"`. Coarser granularities (day/month/year) ignore it.
+     */
+    timeFormat?: DatetimeTimeFormat;
+}
+
+/** A datetime data point: `[msSinceEpoch, value]` tuple or `{ x, y }` object. */
+type BarDatetimePoint = DatetimePoint;
+/** A category y-value, or a datetime point when the dimensional axis is `"datetime"`. */
+type BarDataPoint = ChartDataPoint;
+interface BarSeries {
+    name: string;
+    /**
+     * Y-values indexed parallel to `xAxis.categories` on a category axis, or
+     * `[timestamp, value]` / `{ x, y }` points on a datetime axis.
+     */
+    data: Array<BarDataPoint>;
+    color?: string;
+    /** Seeds icon or partner-logo name rendered before the series name in the legend. */
+    icon?: TypeIconName;
+}
+type BarXAxis = CategoryAxis | DatetimeAxis;
+interface BarYAxis {
+    min?: number;
+    max?: number;
+    /** Default: true. */
+    showGridLines?: boolean;
+    title?: string;
+    /**
+     * Declarative value formatting applied to y-axis tick labels and the default
+     * tooltip value. Omit for the zero-config decimal default (smart 1k/10k
+     * abbreviation on the axis, raw values in the tooltip).
+     */
+    format?: ValueFormat;
+    /**
+     * Show y-axis tick labels. Default `true`. `false` hides them (maps to
+     * Highcharts' `labels.enabled`, replacing v1's `() => ""` formatter trick).
+     */
+    showLabels?: boolean;
+}
+/**
+ * Direction in which bars are drawn. Single-member union for now; expands to
+ * `"vertical" | "horizontal"` when `HorizontalBarChart` ships.
+ */
+type BarChartDirection = "vertical";
+interface BarChartProps {
+    /** Wired into Highcharts' `accessibility.description`. */
+    description: string;
+    series: Array<BarSeries>;
+    /**
+     * Maximum number of series to display. Series beyond the limit are dropped to
+     * keep the chart readable and accessible. Default `10`.
+     */
+    seriesLimit?: number;
+    /**
+     * Suppress the `console.warn` emitted when the series count exceeds the limit.
+     * The cap still applies. Default `false`.
+     */
+    hideSeriesLimitWarning?: boolean;
+    xAxis: BarXAxis;
+    yAxis?: BarYAxis;
+    /** IANA timezone for datetime-axis ticks and tooltips. Default `"UTC"`. Ignored for category axes. */
+    timezone?: string;
+    /**
+     * Stacking mode for multi-series charts. Defaults to `"normal"` — the
+     * canonical design-system spec renders multi-series bar charts as a single
+     * stacked column per category. `"percent"` normalizes each column to 100%.
+     * `"grouped"` renders series as adjacent bars per category; not part of the
+     * canonical spec, but available for non-standard use cases.
+     */
+    stacking?: "normal" | "percent" | "grouped";
+    /** Appended to each tooltip value (e.g., `" MT"`, `"%"`). */
+    valueSuffix?: string;
+    /** Override for the default tooltip content. */
+    tooltip?: (args: ChartTooltipProps) => ReactNode;
+    /** Declarative annotations rendered at positions on the chart. */
+    annotations?: ChartAnnotation[];
+    /** Click handler invoked with the dimensional-axis value of the clicked column — the category name on a category axis, the numeric timestamp on a datetime axis. `position` is direction-agnostic: the x-axis value on `VerticalBarChart`, the y-axis value on `HorizontalBarChart`. */
+    onClick?: ({ position }: {
+        position: number | string;
+    }) => void;
+    /** Footer content shown in the default tooltip when `onClick` is set. */
+    tooltipClickLabel?: ReactNode;
+    /** Override for the value shown when a data point is invalid/missing (null). Defaults to an em-dash. */
+    invalidNumberLabel?: ReactNode;
+    /**
+     * Fired once per chart instance with an opaque {@link ChartExportHandle} for
+     * triggering PNG/SVG/PDF/CSV downloads. Re-fires only on a genuine remount,
+     * never on data or prop updates.
+     */
+    onReady?: (handle: ChartExportHandle) => void;
+}
+
+declare const VerticalBarChart: react.NamedExoticComponent<BarChartProps>;
+
+export { type BarChartDirection, type BarChartProps, type BarDataPoint, type BarDatetimePoint, type BarSeries, type BarXAxis, type BarYAxis, type CategoryAxis, ChartExportHandle, type DatetimeAxis, type ValueFormat, VerticalBarChart };