@automattic/charts 2.0.1 → 3.1.0

package/dist/index.d.cts

@@ -510,6 +510,17 @@ type SeriesChartLegendConfig = ChartLegendConfig<SeriesData[]> & {
    */
   collapseGroups?: boolean;
 };
+/**
+ * Initial visibility options for charts built from labelled series.
+ */
+interface SeriesVisibilityProps {
+  /**
+   * Series labels to hide from the first defined value. User changes persist until
+   * the chart remounts or its ID changes; later values for the same ID are ignored.
+   * Omit to retain the provider's existing visibility for the chart ID.
+   */
+  defaultHiddenSeries?: readonly string[];
+}
 /**
  * Base properties shared across all chart components
  */
@@ -604,37 +615,6 @@ type BaseChartProps<T = DataPoint | DataPointDate | LeaderboardEntry> = {
     };
   };
 };
-/**
- * Properties for grid components
- */
-type GridProps = {
-  /**
-   * Width of the grid in pixels
-   */
-  width: number;
-  /**
-   * Height of the grid in pixels
-   */
-  height: number;
-  /**
-   * Grid visibility. x is default.
-   */
-  gridVisibility?: 'x' | 'y' | 'xy' | 'none';
-  /**
-   * X-axis scale for the grid
-   * TODO: Fix any type after resolving visx scale type issues
-   */
-  xScale: any;
-  /**
-   * Y-axis scale for the grid
-   * TODO: Fix any type after resolving visx scale type issues
-   */
-  yScale: any;
-  /**
-   * Top offset for the grid
-   */
-  top?: number;
-};
 //#endregion
 //#region src/components/legend/types.d.ts
 type VisxLegendProps = Pick<ComponentProps<typeof LegendOrdinal>, 'className' | 'shape' | 'fill' | 'size' | 'labelFormat' | 'labelTransform'>;
@@ -711,7 +691,7 @@ interface ChartLegendOptions {
  */
 declare function useChartLegendItems<T extends SeriesData[] | DataPointDate[] | DataPointPercentageCalculated[]>(data: T, options?: ChartLegendOptions, legendShape?: LegendShape<SeriesData[], number>): BaseLegendItem[];
 //#endregion
-//#region src/charts/private/single-chart-context/single-chart-context.d.ts
+//#region src/charts/private/chart-instance-context/chart-instance-context.d.ts
 interface ChartInstanceRef {
   getScales: () => {
     xScale: unknown;
@@ -728,7 +708,6 @@ interface ChartInstanceRef {
     };
   };
 }
-type SingleChartRef = ChartInstanceRef;
 //#endregion
 //#region src/visx/types.d.ts
 type RenderTooltipParams<Datum extends object> = TooltipContextType<Datum> & {
@@ -775,7 +754,7 @@ type RenderLineGlyphProps<Datum extends object> = GlyphProps<Datum> & {
   glyphStyle?: SVGProps<SVGCircleElement>;
   position?: 'start' | 'end';
 };
-interface LineChartProps extends BaseChartProps<SeriesData[]> {
+interface LineChartProps extends BaseChartProps<SeriesData[]>, SeriesVisibilityProps {
   /**
    * Legend configuration. Supports `collapseGroups` on top of the shared options.
    */
@@ -800,8 +779,8 @@ interface LineChartProps extends BaseChartProps<SeriesData[]> {
    */
   zoomable?: boolean;
   /**
-   * Whether the Y axis rescales to fit only the visible series when series are
-   * hidden or shown through the interactive legend.
+   * Whether the Y axis rescales to fit only the visible series when the set of
+   * visible series changes — via the interactive legend or otherwise.
    * Defaults to `true` (the pre-existing behaviour). Set to `false` to pin the Y
    * axis to the full data extent so hiding series does not move the chart's
    * baseline — useful for comparison charts. Matches `AreaChart`.
@@ -816,7 +795,7 @@ type TooltipDatum = {
 };
 //#endregion
 //#region src/charts/area-chart/types.d.ts
-interface AreaChartProps extends BaseChartProps<SeriesData[]> {
+interface AreaChartProps extends BaseChartProps<SeriesData[]>, SeriesVisibilityProps {
   /**
    * Legend configuration. Supports `collapseGroups` on top of the shared options.
    */
@@ -871,8 +850,8 @@ interface AreaChartProps extends BaseChartProps<SeriesData[]> {
    */
   zoomable?: boolean;
   /**
-   * Whether the Y axis rescales to fit only the visible series when series are
-   * hidden or shown through the interactive legend.
+   * Whether the Y axis rescales to fit only the visible series when the set of
+   * visible series changes — via the interactive legend or otherwise.
    * Defaults to `true`, matching LineChart. Set to `false` to pin the Y axis to
    * the full data extent so hiding series does not move the chart's baseline.
    * @default true
@@ -914,13 +893,13 @@ type AreaChartSubComponents = {
   Legend: typeof Legend;
 };
 type AreaChartBaseProps = Optional<AreaChartProps, 'width' | 'height' | 'size'>;
-type AreaChartComponent = React.ForwardRefExoticComponent<AreaChartBaseProps & React.RefAttributes<SingleChartRef>> & AreaChartSubComponents;
-type AreaChartResponsiveComponent = React.ForwardRefExoticComponent<AreaChartBaseProps & ResponsiveConfig & React.RefAttributes<SingleChartRef>> & AreaChartSubComponents;
+type AreaChartComponent = React.ForwardRefExoticComponent<AreaChartBaseProps & React.RefAttributes<ChartInstanceRef>> & AreaChartSubComponents;
+type AreaChartResponsiveComponent = React.ForwardRefExoticComponent<AreaChartBaseProps & ResponsiveConfig & React.RefAttributes<ChartInstanceRef>> & AreaChartSubComponents;
 declare const AreaChart: AreaChartComponent;
 declare const AreaChartResponsive: AreaChartResponsiveComponent;
 //#endregion
 //#region src/charts/bar-chart/bar-chart.d.ts
-interface BarChartProps extends BaseChartProps<SeriesData[]> {
+interface BarChartProps extends BaseChartProps<SeriesData[]>, SeriesVisibilityProps {
   /**
    * Legend configuration. Supports `collapseGroups` on top of the shared options.
    */
@@ -1184,6 +1163,14 @@ type HeatmapCell = {
    * days completing the first/last week fall outside the covered range.
    */
   hidden?: boolean;
+  /**
+   * Paint the cell as a faded empty slot that carries no claim about the day:
+   * it is set apart from a measured day that scored zero, and skipped by
+   * hover, tooltips, keyboard navigation and the accessibility tree. For grid
+   * filler — slots drawn only so a short range still fills its container,
+   * which were never measured.
+   */
+  placeholder?: boolean;
 };
 /** A heatmap column (rendered left→right); its cells render top→bottom. */
 type HeatmapColumn = {
@@ -1249,6 +1236,19 @@ declare const buildCalendarHeatmapData: (series: DataPointDate[], options?: {
    * blank cells even when the series has no entry for them.
    */
   hideOutOfRangeDays?: boolean;
+  /**
+   * Draw the grid over this span (`yyyy-MM-dd` bounds) instead of the
+   * series' own. Days inside the grid but outside the series become
+   * placeholder cells: painted as empty slots so a short series still
+   * fills its container, but reporting nothing, since they were never
+   * measured. A start bound is drawn from the beginning of its week, so
+   * the grid always opens on a whole column. Bounds narrower than the
+   * series are ignored — the grid never drops a day that carries data.
+   */
+  gridSpan?: {
+    start?: string;
+    end?: string;
+  };
 }) => CalendarHeatmapResult;
 //#endregion
 //#region src/charts/heatmap-chart/private/heatmap-legend.d.ts
@@ -1310,8 +1310,7 @@ interface LeaderboardChartProps extends Pick<BaseChartProps<LeaderboardEntry>, '
    * Custom styling for the chart container
    */
   style?: React.CSSProperties & {
-    '--a8c-charts-border-radius-leaderboard-bar'?: string; /** @deprecated Use `--a8c-charts-border-radius-leaderboard-bar`. */
-    '--a8c--charts--leaderboard--bar--border-radius'?: string;
+    '--a8c-charts-border-radius-leaderboard-bar'?: string;
   };
   /**
    * Custom labels for legend items
@@ -1560,6 +1559,21 @@ declare const relativeLuminance: (hex: string) => number;
  */
 declare const prefersLightText: (backgroundHex: string) => boolean;
 //#endregion
+//#region src/utils/resolve-css-var.d.ts
+/**
+ * Resolves a CSS custom property (variable) to its computed value.
+ * Handles multiple formats:
+ * - Plain variable names: '--my-color'
+ * - CSS var() syntax: 'var(--my-color)'
+ * - CSS var() with fallback: 'var(--my-color, #ffffff)'
+ * - Regular values (returned as-is): '#ffffff', 'red'
+ *
+ * @param value   - A CSS variable name, var() expression, or regular value
+ * @param element - Optional DOM element to resolve the variable from (defaults to document.documentElement)
+ * @return The resolved value, fallback value, or null if unresolvable
+ */
+declare const resolveCssVariable: (value: string, element?: HTMLElement | null) => string | null;
+//#endregion
 //#region src/charts/leaderboard-chart/hooks/use-leaderboard-legend-items.d.ts
 /**
  * Hook to create legend items from leaderboard data
@@ -1609,8 +1623,8 @@ type LineChartAnnotationComponents = {
   Legend: typeof Legend;
 };
 type LineChartBaseProps = Optional<LineChartProps, 'width' | 'height' | 'size'>;
-type LineChartComponent = React.ForwardRefExoticComponent<LineChartBaseProps & React.RefAttributes<SingleChartRef>> & LineChartAnnotationComponents;
-type LineChartResponsiveComponent = React.ForwardRefExoticComponent<LineChartBaseProps & ResponsiveConfig & React.RefAttributes<SingleChartRef>> & LineChartAnnotationComponents;
+type LineChartComponent = React.ForwardRefExoticComponent<LineChartBaseProps & React.RefAttributes<ChartInstanceRef>> & LineChartAnnotationComponents;
+type LineChartResponsiveComponent = React.ForwardRefExoticComponent<LineChartBaseProps & ResponsiveConfig & React.RefAttributes<ChartInstanceRef>> & LineChartAnnotationComponents;
 declare const LineChart: LineChartComponent;
 declare const LineChartResponsive: LineChartResponsiveComponent;
 //#endregion
@@ -2042,8 +2056,13 @@ interface GlobalChartsContextValue {
   getChartData: (id: string) => ChartRegistration | undefined;
   theme: CompleteChartTheme;
   getElementStyles: (params: GetElementStylesParams) => ElementStyles;
-  resolveThemeColor: (value: string) => string;
   toggleSeriesVisibility: (chartId: string, seriesLabel: string) => void;
+  setSeriesVisibility: (chartId: string, seriesLabel: string, visible: boolean) => void;
+  setChartHiddenSeries: (chartId: string, seriesLabels: readonly string[]) => void;
+  /** Applies a chart's defaults once. A no-op for a chart that has already been seeded. */
+  seedChartHiddenSeries: (chartId: string, seriesLabels: readonly string[]) => void;
+  /** Whether this chart's defaults have already been seeded, in this or an earlier mount. */
+  hasSeededChart: (chartId: string) => boolean;
   isSeriesVisible: (chartId: string, seriesLabel: string) => boolean;
   getHiddenSeries: (chartId: string) => Set<string>;
   isColorPaletteResolved: boolean;
@@ -2060,6 +2079,21 @@ declare const GlobalChartsProvider: FC<GlobalChartsProviderProps>;
 //#region src/providers/chart-context/hooks/use-global-charts-context.d.ts
 declare const useGlobalChartsContext: () => GlobalChartsContextValue;
 //#endregion
+//#region src/providers/chart-context/hooks/use-chart-registration.d.ts
+declare const useChartRegistration: ({
+  chartId,
+  legendItems,
+  chartType,
+  isDataValid,
+  metadata
+}: {
+  chartId: string;
+  legendItems: BaseLegendItem[];
+  chartType: ChartType;
+  isDataValid: boolean;
+  metadata?: Record<string, unknown>;
+}) => void;
+//#endregion
 //#region src/providers/chart-context/hooks/use-global-charts-theme.d.ts
 /**
  * Hook to get the global chart theme from GlobalChartsProvider
@@ -2074,5 +2108,13 @@ declare const useGlobalChartsTheme: () => CompleteChartTheme;
  */
 declare const defaultTheme: CompleteChartTheme;
 //#endregion
-export { AccessibleTooltip, type AnnotationStyles, type ArcData, AreaChartResponsive as AreaChart, type AreaChartProps, AreaChart as AreaChartUnresponsive, type AxisOptions, BarChartResponsive as BarChart, type BarChartProps, BarChart as BarChartUnresponsive, BarListChartResponsive as BarListChart, type BarListChartProps, BarListChart as BarListChartUnresponsive, type BaseChartProps, type BaseLegendItem, type BaseLegendProps, BaseTooltip, type BaseTooltipProps, type CalendarHeatmapResult, type ChartLegendConfig, type ChartLegendOptions, type ChartTheme, type CompleteChartTheme, ConversionFunnelChartWithProvider as ConversionFunnelChart, type ConversionFunnelChartProps, type CurveType, type DataPoint, type DataPointDate, type DataPointPercentage, type EventHandlerParams, type FunnelStep, GeoChartResponsive as GeoChart, type GeoChartError, type GeoChartProps, GeoChartWithProvider as GeoChartUnresponsive, type GeoData, type GeoRegion, type GeoResolution, GlobalChartsContext, GlobalChartsProvider, GlobalChartsProvider as ThemeProvider, type GoogleDataTableColumn, type GoogleDataTableColumnRoleType, type GoogleDataTableRow, type GradientConfig, type GradientStop, type GridProps, type GridStyles, type HeatmapCell, HeatmapChartResponsive as HeatmapChart, type HeatmapChartProps, HeatmapChart as HeatmapChartUnresponsive, type HeatmapColumn, type HeatmapTooltipData, LeaderboardChartResponsive as LeaderboardChart, type LeaderboardChartProps, LeaderboardChart as LeaderboardChartUnresponsive, type LeaderboardEntry, Legend, type LegendItemStyles, type LegendLabelStyles, type LegendPosition, type LegendProps, type LegendShape, type LegendShapeLabel, type LegendShapeRenderProps, type LegendShapeStyles, type LegendValueDisplay, LineChartResponsive as LineChart, type LineChartAnnotationProps, type LineChartProps, LineChart as LineChartUnresponsive, type LineStyles, type MainMetricRenderProps, type MetricValueType, type MultipleDataPointsDate, type Optional, type OrientationType, PieChartResponsive as PieChart, type PieChartProps, type PieChartRenderTooltipParams, PieChart as PieChartUnresponsive, PieSemiCircleChartResponsive as PieSemiCircleChart, type PieSemiCircleChartProps, type PieSemiCircleChartRenderTooltipParams, PieSemiCircleChart as PieSemiCircleChartUnresponsive, type RenderLabelProps, type RenderLineGlyphProps, type RenderTooltipGlyphProps, type RenderTooltipParams, type RenderValueProps, type ScaleOptions, type SeriesChartLegendConfig, type SeriesData, type SeriesDataOptions, Sparkline, type SparklineDataPoint, type SparklineProps, SparklineUnresponsive, type StepLabelRenderProps, type StepRateRenderProps, type TickResolution, type TooltipData, type TooltipDatum, type TooltipProps, type TooltipRenderProps, type TrendDirection, TrendIndicator, type TrendIndicatorProps, type XyChartTooltipProps, buildCalendarHeatmapData, defaultTheme, formatMetricValue, formatPercentage, getColorDistance, hexToRgba, isValidHexColor, lightenHexColor, mergeThemes, mixHexColors, normalizeColorToHex, parseAsLocalDate, parseHslString, parseRgbString, prefersLightText, relativeLuminance, useChartLegendItems, useGlobalChartsContext, useGlobalChartsTheme, useLeaderboardLegendItems, validateHexColor };
+//#region src/providers/chart-scope/use-chart-scope-element.d.ts
+/**
+ * Returns the nearest chart scope element, or `null` when rendered outside any scope (and during SSR, before the ref is attached).
+ *
+ * @return {HTMLElement | null} The nearest chart scope element, or `null`.
+ */
+declare const useChartScopeElement: () => HTMLElement | null;
+//#endregion
+export { AccessibleTooltip, type AnnotationStyles, type ArcData, AreaChartResponsive as AreaChart, type AreaChartProps, AreaChart as AreaChartUnresponsive, type AxisOptions, BarChartResponsive as BarChart, type BarChartProps, BarChart as BarChartUnresponsive, BarListChartResponsive as BarListChart, type BarListChartProps, BarListChart as BarListChartUnresponsive, type BaseChartProps, type BaseLegendItem, type BaseLegendProps, BaseTooltip, type BaseTooltipProps, type CalendarHeatmapResult, type ChartLegendConfig, type ChartLegendOptions, type ChartTheme, type CompleteChartTheme, ConversionFunnelChartWithProvider as ConversionFunnelChart, type ConversionFunnelChartProps, type CurveType, type DataPoint, type DataPointDate, type DataPointPercentage, type EventHandlerParams, type FunnelStep, GeoChartResponsive as GeoChart, type GeoChartError, type GeoChartProps, GeoChartWithProvider as GeoChartUnresponsive, type GeoData, type GeoRegion, type GeoResolution, GlobalChartsContext, GlobalChartsProvider, GlobalChartsProvider as ThemeProvider, type GoogleDataTableColumn, GoogleDataTableColumnRoleType, type GoogleDataTableRow, type GradientConfig, type GradientStop, type GridStyles, type HeatmapCell, HeatmapChartResponsive as HeatmapChart, type HeatmapChartProps, HeatmapChart as HeatmapChartUnresponsive, type HeatmapColumn, type HeatmapTooltipData, LeaderboardChartResponsive as LeaderboardChart, type LeaderboardChartProps, LeaderboardChart as LeaderboardChartUnresponsive, type LeaderboardEntry, Legend, type LegendItemStyles, type LegendLabelStyles, type LegendPosition, type LegendProps, type LegendShape, type LegendShapeLabel, type LegendShapeRenderProps, type LegendShapeStyles, type LegendValueDisplay, LineChartResponsive as LineChart, type LineChartAnnotationProps, type LineChartProps, LineChart as LineChartUnresponsive, type LineStyles, type MainMetricRenderProps, type MetricValueType, type MultipleDataPointsDate, type Optional, type OrientationType, PieChartResponsive as PieChart, type PieChartProps, type PieChartRenderTooltipParams, PieChart as PieChartUnresponsive, PieSemiCircleChartResponsive as PieSemiCircleChart, type PieSemiCircleChartProps, type PieSemiCircleChartRenderTooltipParams, PieSemiCircleChart as PieSemiCircleChartUnresponsive, type RenderLabelProps, type RenderLineGlyphProps, type RenderTooltipGlyphProps, type RenderTooltipParams, type RenderValueProps, type ScaleOptions, type SeriesChartLegendConfig, type SeriesData, type SeriesDataOptions, type SeriesVisibilityProps, Sparkline, type SparklineDataPoint, type SparklineProps, SparklineUnresponsive, type StepLabelRenderProps, type StepRateRenderProps, type TickResolution, type TooltipData, type TooltipDatum, type TooltipProps, type TooltipRenderProps, type TrendDirection, TrendIndicator, type TrendIndicatorProps, type XyChartTooltipProps, buildCalendarHeatmapData, defaultTheme, formatMetricValue, formatPercentage, getColorDistance, hexToRgba, isValidHexColor, lightenHexColor, mergeThemes, mixHexColors, normalizeColorToHex, parseAsLocalDate, parseHslString, parseRgbString, prefersLightText, relativeLuminance, resolveCssVariable, useChartLegendItems, useChartRegistration, useChartScopeElement, useGlobalChartsContext, useGlobalChartsTheme, useLeaderboardLegendItems, validateHexColor };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.ts

@@ -510,6 +510,17 @@ type SeriesChartLegendConfig = ChartLegendConfig<SeriesData[]> & {
    */
   collapseGroups?: boolean;
 };
+/**
+ * Initial visibility options for charts built from labelled series.
+ */
+interface SeriesVisibilityProps {
+  /**
+   * Series labels to hide from the first defined value. User changes persist until
+   * the chart remounts or its ID changes; later values for the same ID are ignored.
+   * Omit to retain the provider's existing visibility for the chart ID.
+   */
+  defaultHiddenSeries?: readonly string[];
+}
 /**
  * Base properties shared across all chart components
  */
@@ -604,37 +615,6 @@ type BaseChartProps<T = DataPoint | DataPointDate | LeaderboardEntry> = {
     };
   };
 };
-/**
- * Properties for grid components
- */
-type GridProps = {
-  /**
-   * Width of the grid in pixels
-   */
-  width: number;
-  /**
-   * Height of the grid in pixels
-   */
-  height: number;
-  /**
-   * Grid visibility. x is default.
-   */
-  gridVisibility?: 'x' | 'y' | 'xy' | 'none';
-  /**
-   * X-axis scale for the grid
-   * TODO: Fix any type after resolving visx scale type issues
-   */
-  xScale: any;
-  /**
-   * Y-axis scale for the grid
-   * TODO: Fix any type after resolving visx scale type issues
-   */
-  yScale: any;
-  /**
-   * Top offset for the grid
-   */
-  top?: number;
-};
 //#endregion
 //#region src/components/legend/types.d.ts
 type VisxLegendProps = Pick<ComponentProps<typeof LegendOrdinal>, 'className' | 'shape' | 'fill' | 'size' | 'labelFormat' | 'labelTransform'>;
@@ -711,7 +691,7 @@ interface ChartLegendOptions {
  */
 declare function useChartLegendItems<T extends SeriesData[] | DataPointDate[] | DataPointPercentageCalculated[]>(data: T, options?: ChartLegendOptions, legendShape?: LegendShape<SeriesData[], number>): BaseLegendItem[];
 //#endregion
-//#region src/charts/private/single-chart-context/single-chart-context.d.ts
+//#region src/charts/private/chart-instance-context/chart-instance-context.d.ts
 interface ChartInstanceRef {
   getScales: () => {
     xScale: unknown;
@@ -728,7 +708,6 @@ interface ChartInstanceRef {
     };
   };
 }
-type SingleChartRef = ChartInstanceRef;
 //#endregion
 //#region src/visx/types.d.ts
 type RenderTooltipParams<Datum extends object> = TooltipContextType<Datum> & {
@@ -775,7 +754,7 @@ type RenderLineGlyphProps<Datum extends object> = GlyphProps<Datum> & {
   glyphStyle?: SVGProps<SVGCircleElement>;
   position?: 'start' | 'end';
 };
-interface LineChartProps extends BaseChartProps<SeriesData[]> {
+interface LineChartProps extends BaseChartProps<SeriesData[]>, SeriesVisibilityProps {
   /**
    * Legend configuration. Supports `collapseGroups` on top of the shared options.
    */
@@ -800,8 +779,8 @@ interface LineChartProps extends BaseChartProps<SeriesData[]> {
    */
   zoomable?: boolean;
   /**
-   * Whether the Y axis rescales to fit only the visible series when series are
-   * hidden or shown through the interactive legend.
+   * Whether the Y axis rescales to fit only the visible series when the set of
+   * visible series changes — via the interactive legend or otherwise.
    * Defaults to `true` (the pre-existing behaviour). Set to `false` to pin the Y
    * axis to the full data extent so hiding series does not move the chart's
    * baseline — useful for comparison charts. Matches `AreaChart`.
@@ -816,7 +795,7 @@ type TooltipDatum = {
 };
 //#endregion
 //#region src/charts/area-chart/types.d.ts
-interface AreaChartProps extends BaseChartProps<SeriesData[]> {
+interface AreaChartProps extends BaseChartProps<SeriesData[]>, SeriesVisibilityProps {
   /**
    * Legend configuration. Supports `collapseGroups` on top of the shared options.
    */
@@ -871,8 +850,8 @@ interface AreaChartProps extends BaseChartProps<SeriesData[]> {
    */
   zoomable?: boolean;
   /**
-   * Whether the Y axis rescales to fit only the visible series when series are
-   * hidden or shown through the interactive legend.
+   * Whether the Y axis rescales to fit only the visible series when the set of
+   * visible series changes — via the interactive legend or otherwise.
    * Defaults to `true`, matching LineChart. Set to `false` to pin the Y axis to
    * the full data extent so hiding series does not move the chart's baseline.
    * @default true
@@ -914,13 +893,13 @@ type AreaChartSubComponents = {
   Legend: typeof Legend;
 };
 type AreaChartBaseProps = Optional<AreaChartProps, 'width' | 'height' | 'size'>;
-type AreaChartComponent = React.ForwardRefExoticComponent<AreaChartBaseProps & React.RefAttributes<SingleChartRef>> & AreaChartSubComponents;
-type AreaChartResponsiveComponent = React.ForwardRefExoticComponent<AreaChartBaseProps & ResponsiveConfig & React.RefAttributes<SingleChartRef>> & AreaChartSubComponents;
+type AreaChartComponent = React.ForwardRefExoticComponent<AreaChartBaseProps & React.RefAttributes<ChartInstanceRef>> & AreaChartSubComponents;
+type AreaChartResponsiveComponent = React.ForwardRefExoticComponent<AreaChartBaseProps & ResponsiveConfig & React.RefAttributes<ChartInstanceRef>> & AreaChartSubComponents;
 declare const AreaChart: AreaChartComponent;
 declare const AreaChartResponsive: AreaChartResponsiveComponent;
 //#endregion
 //#region src/charts/bar-chart/bar-chart.d.ts
-interface BarChartProps extends BaseChartProps<SeriesData[]> {
+interface BarChartProps extends BaseChartProps<SeriesData[]>, SeriesVisibilityProps {
   /**
    * Legend configuration. Supports `collapseGroups` on top of the shared options.
    */
@@ -1184,6 +1163,14 @@ type HeatmapCell = {
    * days completing the first/last week fall outside the covered range.
    */
   hidden?: boolean;
+  /**
+   * Paint the cell as a faded empty slot that carries no claim about the day:
+   * it is set apart from a measured day that scored zero, and skipped by
+   * hover, tooltips, keyboard navigation and the accessibility tree. For grid
+   * filler — slots drawn only so a short range still fills its container,
+   * which were never measured.
+   */
+  placeholder?: boolean;
 };
 /** A heatmap column (rendered left→right); its cells render top→bottom. */
 type HeatmapColumn = {
@@ -1249,6 +1236,19 @@ declare const buildCalendarHeatmapData: (series: DataPointDate[], options?: {
    * blank cells even when the series has no entry for them.
    */
   hideOutOfRangeDays?: boolean;
+  /**
+   * Draw the grid over this span (`yyyy-MM-dd` bounds) instead of the
+   * series' own. Days inside the grid but outside the series become
+   * placeholder cells: painted as empty slots so a short series still
+   * fills its container, but reporting nothing, since they were never
+   * measured. A start bound is drawn from the beginning of its week, so
+   * the grid always opens on a whole column. Bounds narrower than the
+   * series are ignored — the grid never drops a day that carries data.
+   */
+  gridSpan?: {
+    start?: string;
+    end?: string;
+  };
 }) => CalendarHeatmapResult;
 //#endregion
 //#region src/charts/heatmap-chart/private/heatmap-legend.d.ts
@@ -1310,8 +1310,7 @@ interface LeaderboardChartProps extends Pick<BaseChartProps<LeaderboardEntry>, '
    * Custom styling for the chart container
    */
   style?: React.CSSProperties & {
-    '--a8c-charts-border-radius-leaderboard-bar'?: string; /** @deprecated Use `--a8c-charts-border-radius-leaderboard-bar`. */
-    '--a8c--charts--leaderboard--bar--border-radius'?: string;
+    '--a8c-charts-border-radius-leaderboard-bar'?: string;
   };
   /**
    * Custom labels for legend items
@@ -1560,6 +1559,21 @@ declare const relativeLuminance: (hex: string) => number;
  */
 declare const prefersLightText: (backgroundHex: string) => boolean;
 //#endregion
+//#region src/utils/resolve-css-var.d.ts
+/**
+ * Resolves a CSS custom property (variable) to its computed value.
+ * Handles multiple formats:
+ * - Plain variable names: '--my-color'
+ * - CSS var() syntax: 'var(--my-color)'
+ * - CSS var() with fallback: 'var(--my-color, #ffffff)'
+ * - Regular values (returned as-is): '#ffffff', 'red'
+ *
+ * @param value   - A CSS variable name, var() expression, or regular value
+ * @param element - Optional DOM element to resolve the variable from (defaults to document.documentElement)
+ * @return The resolved value, fallback value, or null if unresolvable
+ */
+declare const resolveCssVariable: (value: string, element?: HTMLElement | null) => string | null;
+//#endregion
 //#region src/charts/leaderboard-chart/hooks/use-leaderboard-legend-items.d.ts
 /**
  * Hook to create legend items from leaderboard data
@@ -1609,8 +1623,8 @@ type LineChartAnnotationComponents = {
   Legend: typeof Legend;
 };
 type LineChartBaseProps = Optional<LineChartProps, 'width' | 'height' | 'size'>;
-type LineChartComponent = React.ForwardRefExoticComponent<LineChartBaseProps & React.RefAttributes<SingleChartRef>> & LineChartAnnotationComponents;
-type LineChartResponsiveComponent = React.ForwardRefExoticComponent<LineChartBaseProps & ResponsiveConfig & React.RefAttributes<SingleChartRef>> & LineChartAnnotationComponents;
+type LineChartComponent = React.ForwardRefExoticComponent<LineChartBaseProps & React.RefAttributes<ChartInstanceRef>> & LineChartAnnotationComponents;
+type LineChartResponsiveComponent = React.ForwardRefExoticComponent<LineChartBaseProps & ResponsiveConfig & React.RefAttributes<ChartInstanceRef>> & LineChartAnnotationComponents;
 declare const LineChart: LineChartComponent;
 declare const LineChartResponsive: LineChartResponsiveComponent;
 //#endregion
@@ -2042,8 +2056,13 @@ interface GlobalChartsContextValue {
   getChartData: (id: string) => ChartRegistration | undefined;
   theme: CompleteChartTheme;
   getElementStyles: (params: GetElementStylesParams) => ElementStyles;
-  resolveThemeColor: (value: string) => string;
   toggleSeriesVisibility: (chartId: string, seriesLabel: string) => void;
+  setSeriesVisibility: (chartId: string, seriesLabel: string, visible: boolean) => void;
+  setChartHiddenSeries: (chartId: string, seriesLabels: readonly string[]) => void;
+  /** Applies a chart's defaults once. A no-op for a chart that has already been seeded. */
+  seedChartHiddenSeries: (chartId: string, seriesLabels: readonly string[]) => void;
+  /** Whether this chart's defaults have already been seeded, in this or an earlier mount. */
+  hasSeededChart: (chartId: string) => boolean;
   isSeriesVisible: (chartId: string, seriesLabel: string) => boolean;
   getHiddenSeries: (chartId: string) => Set<string>;
   isColorPaletteResolved: boolean;
@@ -2060,6 +2079,21 @@ declare const GlobalChartsProvider: FC<GlobalChartsProviderProps>;
 //#region src/providers/chart-context/hooks/use-global-charts-context.d.ts
 declare const useGlobalChartsContext: () => GlobalChartsContextValue;
 //#endregion
+//#region src/providers/chart-context/hooks/use-chart-registration.d.ts
+declare const useChartRegistration: ({
+  chartId,
+  legendItems,
+  chartType,
+  isDataValid,
+  metadata
+}: {
+  chartId: string;
+  legendItems: BaseLegendItem[];
+  chartType: ChartType;
+  isDataValid: boolean;
+  metadata?: Record<string, unknown>;
+}) => void;
+//#endregion
 //#region src/providers/chart-context/hooks/use-global-charts-theme.d.ts
 /**
  * Hook to get the global chart theme from GlobalChartsProvider
@@ -2074,5 +2108,13 @@ declare const useGlobalChartsTheme: () => CompleteChartTheme;
  */
 declare const defaultTheme: CompleteChartTheme;
 //#endregion
-export { AccessibleTooltip, type AnnotationStyles, type ArcData, AreaChartResponsive as AreaChart, type AreaChartProps, AreaChart as AreaChartUnresponsive, type AxisOptions, BarChartResponsive as BarChart, type BarChartProps, BarChart as BarChartUnresponsive, BarListChartResponsive as BarListChart, type BarListChartProps, BarListChart as BarListChartUnresponsive, type BaseChartProps, type BaseLegendItem, type BaseLegendProps, BaseTooltip, type BaseTooltipProps, type CalendarHeatmapResult, type ChartLegendConfig, type ChartLegendOptions, type ChartTheme, type CompleteChartTheme, ConversionFunnelChartWithProvider as ConversionFunnelChart, type ConversionFunnelChartProps, type CurveType, type DataPoint, type DataPointDate, type DataPointPercentage, type EventHandlerParams, type FunnelStep, GeoChartResponsive as GeoChart, type GeoChartError, type GeoChartProps, GeoChartWithProvider as GeoChartUnresponsive, type GeoData, type GeoRegion, type GeoResolution, GlobalChartsContext, GlobalChartsProvider, GlobalChartsProvider as ThemeProvider, type GoogleDataTableColumn, type GoogleDataTableColumnRoleType, type GoogleDataTableRow, type GradientConfig, type GradientStop, type GridProps, type GridStyles, type HeatmapCell, HeatmapChartResponsive as HeatmapChart, type HeatmapChartProps, HeatmapChart as HeatmapChartUnresponsive, type HeatmapColumn, type HeatmapTooltipData, LeaderboardChartResponsive as LeaderboardChart, type LeaderboardChartProps, LeaderboardChart as LeaderboardChartUnresponsive, type LeaderboardEntry, Legend, type LegendItemStyles, type LegendLabelStyles, type LegendPosition, type LegendProps, type LegendShape, type LegendShapeLabel, type LegendShapeRenderProps, type LegendShapeStyles, type LegendValueDisplay, LineChartResponsive as LineChart, type LineChartAnnotationProps, type LineChartProps, LineChart as LineChartUnresponsive, type LineStyles, type MainMetricRenderProps, type MetricValueType, type MultipleDataPointsDate, type Optional, type OrientationType, PieChartResponsive as PieChart, type PieChartProps, type PieChartRenderTooltipParams, PieChart as PieChartUnresponsive, PieSemiCircleChartResponsive as PieSemiCircleChart, type PieSemiCircleChartProps, type PieSemiCircleChartRenderTooltipParams, PieSemiCircleChart as PieSemiCircleChartUnresponsive, type RenderLabelProps, type RenderLineGlyphProps, type RenderTooltipGlyphProps, type RenderTooltipParams, type RenderValueProps, type ScaleOptions, type SeriesChartLegendConfig, type SeriesData, type SeriesDataOptions, Sparkline, type SparklineDataPoint, type SparklineProps, SparklineUnresponsive, type StepLabelRenderProps, type StepRateRenderProps, type TickResolution, type TooltipData, type TooltipDatum, type TooltipProps, type TooltipRenderProps, type TrendDirection, TrendIndicator, type TrendIndicatorProps, type XyChartTooltipProps, buildCalendarHeatmapData, defaultTheme, formatMetricValue, formatPercentage, getColorDistance, hexToRgba, isValidHexColor, lightenHexColor, mergeThemes, mixHexColors, normalizeColorToHex, parseAsLocalDate, parseHslString, parseRgbString, prefersLightText, relativeLuminance, useChartLegendItems, useGlobalChartsContext, useGlobalChartsTheme, useLeaderboardLegendItems, validateHexColor };
+//#region src/providers/chart-scope/use-chart-scope-element.d.ts
+/**
+ * Returns the nearest chart scope element, or `null` when rendered outside any scope (and during SSR, before the ref is attached).
+ *
+ * @return {HTMLElement | null} The nearest chart scope element, or `null`.
+ */
+declare const useChartScopeElement: () => HTMLElement | null;
+//#endregion
+export { AccessibleTooltip, type AnnotationStyles, type ArcData, AreaChartResponsive as AreaChart, type AreaChartProps, AreaChart as AreaChartUnresponsive, type AxisOptions, BarChartResponsive as BarChart, type BarChartProps, BarChart as BarChartUnresponsive, BarListChartResponsive as BarListChart, type BarListChartProps, BarListChart as BarListChartUnresponsive, type BaseChartProps, type BaseLegendItem, type BaseLegendProps, BaseTooltip, type BaseTooltipProps, type CalendarHeatmapResult, type ChartLegendConfig, type ChartLegendOptions, type ChartTheme, type CompleteChartTheme, ConversionFunnelChartWithProvider as ConversionFunnelChart, type ConversionFunnelChartProps, type CurveType, type DataPoint, type DataPointDate, type DataPointPercentage, type EventHandlerParams, type FunnelStep, GeoChartResponsive as GeoChart, type GeoChartError, type GeoChartProps, GeoChartWithProvider as GeoChartUnresponsive, type GeoData, type GeoRegion, type GeoResolution, GlobalChartsContext, GlobalChartsProvider, GlobalChartsProvider as ThemeProvider, type GoogleDataTableColumn, GoogleDataTableColumnRoleType, type GoogleDataTableRow, type GradientConfig, type GradientStop, type GridStyles, type HeatmapCell, HeatmapChartResponsive as HeatmapChart, type HeatmapChartProps, HeatmapChart as HeatmapChartUnresponsive, type HeatmapColumn, type HeatmapTooltipData, LeaderboardChartResponsive as LeaderboardChart, type LeaderboardChartProps, LeaderboardChart as LeaderboardChartUnresponsive, type LeaderboardEntry, Legend, type LegendItemStyles, type LegendLabelStyles, type LegendPosition, type LegendProps, type LegendShape, type LegendShapeLabel, type LegendShapeRenderProps, type LegendShapeStyles, type LegendValueDisplay, LineChartResponsive as LineChart, type LineChartAnnotationProps, type LineChartProps, LineChart as LineChartUnresponsive, type LineStyles, type MainMetricRenderProps, type MetricValueType, type MultipleDataPointsDate, type Optional, type OrientationType, PieChartResponsive as PieChart, type PieChartProps, type PieChartRenderTooltipParams, PieChart as PieChartUnresponsive, PieSemiCircleChartResponsive as PieSemiCircleChart, type PieSemiCircleChartProps, type PieSemiCircleChartRenderTooltipParams, PieSemiCircleChart as PieSemiCircleChartUnresponsive, type RenderLabelProps, type RenderLineGlyphProps, type RenderTooltipGlyphProps, type RenderTooltipParams, type RenderValueProps, type ScaleOptions, type SeriesChartLegendConfig, type SeriesData, type SeriesDataOptions, type SeriesVisibilityProps, Sparkline, type SparklineDataPoint, type SparklineProps, SparklineUnresponsive, type StepLabelRenderProps, type StepRateRenderProps, type TickResolution, type TooltipData, type TooltipDatum, type TooltipProps, type TooltipRenderProps, type TrendDirection, TrendIndicator, type TrendIndicatorProps, type XyChartTooltipProps, buildCalendarHeatmapData, defaultTheme, formatMetricValue, formatPercentage, getColorDistance, hexToRgba, isValidHexColor, lightenHexColor, mergeThemes, mixHexColors, normalizeColorToHex, parseAsLocalDate, parseHslString, parseRgbString, prefersLightText, relativeLuminance, resolveCssVariable, useChartLegendItems, useChartRegistration, useChartScopeElement, useGlobalChartsContext, useGlobalChartsTheme, useLeaderboardLegendItems, validateHexColor };
 //# sourceMappingURL=index.d.ts.map