@coinbase/cds-web-visualization 3.3.0 → 3.4.0-beta.2

package/dts/chart/scrubber/ScrubberProvider.d.ts

@@ -0,0 +1,17 @@
+import React from 'react';
+import { type ScrubberContextValue } from '../utils';
+export type ScrubberProviderProps = Partial<
+  Pick<ScrubberContextValue, 'enableScrubbing' | 'onScrubberPositionChange'>
+> & {
+  children: React.ReactNode;
+  /**
+   * A reference to the root SVG element, where interaction event handlers will be attached.
+   */
+  svgRef: React.RefObject<SVGSVGElement> | null;
+};
+/**
+ * A component which encapsulates the ScrubberContext.
+ * It depends on a ChartContext in order to provide accurate mouse tracking.
+ */
+export declare const ScrubberProvider: React.FC<ScrubberProviderProps>;
+//# sourceMappingURL=ScrubberProvider.d.ts.map

package/dts/chart/scrubber/ScrubberProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ScrubberProvider.d.ts","sourceRoot":"","sources":["../../../src/chart/scrubber/ScrubberProvider.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAoD,MAAM,OAAO,CAAC;AAGzE,OAAO,EAAuC,KAAK,oBAAoB,EAAE,MAAM,UAAU,CAAC;AAE1F,MAAM,MAAM,qBAAqB,GAAG,OAAO,CACzC,IAAI,CAAC,oBAAoB,EAAE,iBAAiB,GAAG,0BAA0B,CAAC,CAC3E,GAAG;IACF,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B;;OAEG;IACH,MAAM,EAAE,KAAK,CAAC,SAAS,CAAC,aAAa,CAAC,GAAG,IAAI,CAAC;CAC/C,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAE,KAAK,CAAC,EAAE,CAAC,qBAAqB,CAsQ5D,CAAC"}

package/dts/chart/scrubber/index.d.ts

@@ -0,0 +1,2 @@
+export * from './Scrubber';
+//# sourceMappingURL=index.d.ts.map

package/dts/chart/scrubber/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/chart/scrubber/index.ts"],"names":[],"mappings":"AACA,cAAc,YAAY,CAAC"}

package/dts/chart/text/ChartText.d.ts

@@ -0,0 +1,114 @@
+import React from 'react';
+import type { ElevationLevels, Rect, SharedProps } from '@coinbase/cds-common/types';
+import { type BoxProps } from '@coinbase/cds-web/layout';
+import { type ChartInset } from '../utils';
+type ValidChartTextChildElements =
+  | React.ReactElement<React.SVGProps<SVGTSpanElement>, 'tspan'>
+  | React.ReactElement<React.SVGProps<SVGTextPathElement>, 'textPath'>;
+/**
+ * The supported content types for ChartText.
+ */
+export type ChartTextChildren =
+  | string
+  | number
+  | null
+  | undefined
+  | ValidChartTextChildElements
+  | ValidChartTextChildElements[];
+/**
+ * Horizontal alignment options for chart text.
+ */
+export type TextHorizontalAlignment = 'left' | 'center' | 'right';
+/**
+ * Vertical alignment options for chart text.
+ */
+export type TextVerticalAlignment = 'top' | 'middle' | 'bottom';
+export type ChartTextProps = SharedProps &
+  Pick<BoxProps<'g'>, 'font' | 'fontFamily' | 'fontSize' | 'fontWeight' | 'opacity'> & {
+    /**
+     * The text color.
+     * @default 'var(--color-fgMuted)'
+     */
+    color?: string;
+    /**
+     * The background color of the text's background rectangle.
+     * @default 'transparent' if not elevated, 'var(--color-bg)' if elevated
+     */
+    background?: string;
+    /**
+     * The desired x offset in SVG pixels.
+     */
+    dx?: number;
+    /**
+     * The desired y offset in SVG pixels.
+     */
+    dy?: number;
+    /**
+     * The elevation for the background.
+     */
+    elevation?: ElevationLevels;
+    /**
+     * The text content to display.
+     */
+    children: ChartTextChildren;
+    /**
+     * The desired x position in SVG pixels.
+     * @note Text will be automatically positioned to fit within bounds unless `disableRepositioning` is true.
+     */
+    x: number;
+    /**
+     * The desired y position in SVG pixels.
+     * @note Text will be automatically positioned to fit within bounds unless `disableRepositioning` is true.
+     */
+    y: number;
+    /**
+     * Horizontal alignment of the text.
+     * @default 'center'
+     */
+    horizontalAlignment?: TextHorizontalAlignment;
+    /**
+     * Vertical alignment of the text.
+     * @default 'middle'
+     */
+    verticalAlignment?: TextVerticalAlignment;
+    /**
+     * When true, disables automatic repositioning to fit within bounds.
+     */
+    disableRepositioning?: boolean;
+    /**
+     * Optional bounds rectangle to constrain the text within. If provided, text will be positioned
+     * to stay within these bounds. Defaults to the full chart bounds when not provided.
+     */
+    bounds?: Rect;
+    /**
+     * Callback fired when text dimensions change.
+     * Used for collision detection and smart positioning.
+     * Returns the adjusted position and dimensions.
+     */
+    onDimensionsChange?: (rect: Rect) => void;
+    /**
+     * Inset around the text content for the background rect.
+     * Only affects the background, text position remains unchanged.
+     */
+    inset?: number | ChartInset;
+    style?: React.CSSProperties;
+    styles?: {
+      root?: React.CSSProperties;
+      text?: React.CSSProperties;
+      backgroundRect?: React.CSSProperties;
+    };
+    className?: string;
+    classNames?: {
+      root?: string;
+      text?: string;
+      backgroundRect?: string;
+    };
+    /**
+     * Border radius for the background rectangle.
+     * @default 4
+     */
+    borderRadius?: number;
+  };
+export declare const ChartText: React.NamedExoticComponent<ChartTextProps>;
+export {};
+//# sourceMappingURL=ChartText.d.ts.map

package/dts/chart/text/ChartText.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ChartText.d.ts","sourceRoot":"","sources":["../../../src/chart/text/ChartText.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAqD,MAAM,OAAO,CAAC;AAC1E,OAAO,KAAK,EAAE,eAAe,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAErF,OAAO,EAAO,KAAK,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAK9D,OAAO,EAAE,KAAK,UAAU,EAAiB,MAAM,UAAU,CAAC;AAE1D,KAAK,2BAA2B,GAC5B,KAAK,CAAC,YAAY,CAAC,KAAK,CAAC,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC,GAC5D,KAAK,CAAC,YAAY,CAAC,KAAK,CAAC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,UAAU,CAAC,CAAC;AAEvE;;GAEG;AACH,MAAM,MAAM,iBAAiB,GACzB,MAAM,GACN,MAAM,GACN,IAAI,GACJ,SAAS,GACT,2BAA2B,GAC3B,2BAA2B,EAAE,CAAC;AAElC;;GAEG;AACH,MAAM,MAAM,uBAAuB,GAAG,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC;AAElE;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG,KAAK,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAEhE,MAAM,MAAM,cAAc,GAAG,WAAW,GACtC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,YAAY,GAAG,UAAU,GAAG,YAAY,GAAG,SAAS,CAAC,GAAG;IACnF;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;OAEG;IACH,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ;;OAEG;IACH,EAAE,CAAC,EAAE,MAAM,CAAC;IAEZ;;OAEG;IACH,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B;;OAEG;IACH,QAAQ,EAAE,iBAAiB,CAAC;IAC5B;;;OAGG;IACH,CAAC,EAAE,MAAM,CAAC;IACV;;;OAGG;IACH,CAAC,EAAE,MAAM,CAAC;IACV;;;OAGG;IACH,mBAAmB,CAAC,EAAE,uBAAuB,CAAC;IAC9C;;;OAGG;IACH,iBAAiB,CAAC,EAAE,qBAAqB,CAAC;IAC1C;;OAEG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B;;;OAGG;IACH,MAAM,CAAC,EAAE,IAAI,CAAC;IACd;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,IAAI,CAAC;IAC1C;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,UAAU,CAAC;IAC5B,KAAK,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC;IAC5B,MAAM,CAAC,EAAE;QACP,IAAI,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC;QAC3B,IAAI,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC;QAC3B,cAAc,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC;KACtC,CAAC;IACF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE;QACX,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,cAAc,CAAC,EAAE,MAAM,CAAC;KACzB,CAAC;IACF;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAkCJ,eAAO,MAAM,SAAS,4CAgMrB,CAAC"}

package/dts/chart/text/SmartChartTextGroup.d.ts

@@ -0,0 +1,55 @@
+import { type ChartTextChildren, type ChartTextProps } from './ChartText';
+/**
+ * Configuration for a single text label in the display list
+ */
+export type TextLabelData = {
+  /**
+   * The text content to display
+   */
+  label: ChartTextChildren;
+  /**
+   * X coordinate where the text should be positioned
+   */
+  x: number;
+  /**
+   * Y coordinate where the text should be positioned
+   */
+  y: number;
+  /**
+   * Additional props to pass to the ChartText component for this specific label
+   */
+  chartTextProps?: Partial<ChartTextProps>;
+};
+export type TextLabelDataWithKey = TextLabelData & {
+  key: string;
+};
+export type SmartChartTextGroupProps = {
+  /**
+   * Array of text labels to display
+   */
+  labels: TextLabelData[];
+  /**
+   * Minimum gap between labels in pixels
+   * @default 8
+   */
+  minGap?: number;
+  /**
+   * Whether to always show first and last labels
+   * @default true
+   */
+  prioritizeEndLabels?: boolean;
+  /**
+   * Common props to apply to all ChartText components
+   */
+  chartTextProps?: Partial<ChartTextProps>;
+};
+/**
+ * A smart text display component that prevents label overlap through collision detection.
+ *
+ * This component renders a list of ChartText components and automatically hides overlapping elements
+ * to ensure readability.
+ *
+ * The component focuses solely on overlap prevention logic for better separation of concerns.
+ */
+export declare const SmartChartTextGroup: import('react').NamedExoticComponent<SmartChartTextGroupProps>;
+//# sourceMappingURL=SmartChartTextGroup.d.ts.map

package/dts/chart/text/SmartChartTextGroup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SmartChartTextGroup.d.ts","sourceRoot":"","sources":["../../../src/chart/text/SmartChartTextGroup.tsx"],"names":[],"mappings":"AAGA,OAAO,EAAa,KAAK,iBAAiB,EAAE,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAErF;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B;;OAEG;IACH,KAAK,EAAE,iBAAiB,CAAC;IACzB;;OAEG;IACH,CAAC,EAAE,MAAM,CAAC;IACV;;OAEG;IACH,CAAC,EAAE,MAAM,CAAC;IACV;;OAEG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC;CAC1C,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG,aAAa,GAAG;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnE,MAAM,MAAM,wBAAwB,GAAG;IACrC;;OAEG;IACH,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B;;OAEG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC;CAC1C,CAAC;AAiBF;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,gEAoM/B,CAAC"}

package/dts/chart/text/index.d.ts

@@ -0,0 +1,3 @@
+export * from './ChartText';
+export * from './SmartChartTextGroup';
+//# sourceMappingURL=index.d.ts.map

package/dts/chart/text/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/chart/text/index.ts"],"names":[],"mappings":"AACA,cAAc,aAAa,CAAC;AAC5B,cAAc,uBAAuB,CAAC"}

package/dts/chart/utils/axis.d.ts

@@ -0,0 +1,342 @@
+import type React from 'react';
+import type { Rect } from '@coinbase/cds-common/types';
+import { type AxisBounds, type Series } from './chart';
+import { type ChartAxisScaleType, type ChartScaleFunction } from './scale';
+export declare const defaultAxisId = 'DEFAULT_AXIS_ID';
+export declare const defaultAxisScaleType = 'linear';
+/**
+ * Axis configuration with computed bounds
+ */
+export type AxisConfig = {
+  /** The type of scale to use */
+  scaleType: ChartAxisScaleType;
+  /**
+   * Domain bounds for the axis (data space)
+   */
+  domain: AxisBounds;
+  /**
+   * Range bounds for the axis (visual space in pixels)
+   */
+  range: AxisBounds;
+  /**
+   * Data for the axis
+   */
+  data?: string[] | number[];
+  /**
+   * Padding between categories for band scales (0-1, where 0.1 = 10% spacing)
+   * Only used when scaleType is 'band'
+   * @default 0.1
+   */
+  categoryPadding?: number;
+  /**
+   * Domain limit type for numeric scales
+   * - 'nice': Rounds the domain to human-friendly values
+   * - 'strict': Uses the exact min/max values from the data
+   */
+  domainLimit: 'nice' | 'strict';
+};
+/**
+ * Axis configuration without computed bounds (used for input)
+ */
+export type AxisConfigProps = Omit<AxisConfig, 'domain' | 'range'> & {
+  /**
+   * Unique identifier for this axis.
+   */
+  id: string;
+  /**
+   * Domain configuration for the axis (data space).
+   *
+   * The domainLimit parameter (inherited from AxisConfig) controls how initial domain bounds are calculated:
+   * - 'nice' (default for y axes): Rounds the domain to human-friendly values (e.g., 0-100 instead of 1.2-97.8)
+   * - 'strict' (default for x axes): Uses the exact min/max values from the data
+   *
+   * The domain can be:
+   * - A partial bounds object to override specific min/max values
+   * - A function that receives the limit-processed bounds and allows further customization
+   *
+   * This allows you to first apply nice/strict processing, then optionally transform the result.
+   */
+  domain?: Partial<AxisBounds> | ((bounds: AxisBounds) => AxisBounds);
+  /**
+   * Range configuration for the axis (visual space in pixels).
+   * Can be a partial bounds object to override specific values, or a function that transforms the calculated range.
+   *
+   * When using a function, it receives the initial calculated range bounds and allows you to adjust them.
+   * This replaces the previous rangeOffset approach and provides more flexibility for range customization.
+   */
+  range?: Partial<AxisBounds> | ((bounds: AxisBounds) => AxisBounds);
+};
+/**
+ * Gets a D3 scale based on the axis configuration.
+ * Handles both numeric (linear/log) and categorical (band) scales.
+ *
+ * For numeric scales, the domain limit controls whether bounds are "nice" (human-friendly)
+ * or "strict" (exact min/max). Range can be customized using function-based configuration.
+ *
+ * @param params - Scale parameters
+ * @returns The D3 scale function
+ * @throws An Error if bounds are invalid
+ */
+export declare const getAxisScale: ({
+  config,
+  type,
+  range,
+  dataDomain,
+}: {
+  config?: AxisConfig;
+  type: 'x' | 'y';
+  range: AxisBounds;
+  dataDomain: AxisBounds;
+}) => ChartScaleFunction;
+/**
+ * Formats the array of user-provided axis configs with default values and validates axis ids.
+ * Ensures at least one axis config exists if no input is provided.
+ * Requires specific axis ids when there are more than 1 axes.
+ * Defaults the axis id for a single axis config if there is no id.
+ * @param type - the type of axis, 'x' or 'y'
+ * @param axes - array of axis configs or single axis config
+ * @param defaultId - the default id to use for the axis
+ * @param defaultScaleType - the default scale type to use for the axis
+ * @returns array of axis configs with IDs
+ */
+export declare const getAxisConfig: (
+  type: 'x' | 'y',
+  axes: Partial<AxisConfigProps> | Partial<AxisConfigProps>[] | undefined,
+  defaultId?: string,
+  defaultScaleType?: ChartAxisScaleType,
+) => AxisConfigProps[];
+/**
+ * Calculates the data domain for an axis based on its configuration and series data.
+ * Handles both x and y axes, categorical data, custom domain configurations, and stacking.
+ *
+ * @param axisParam - The axis configuration
+ * @param series - Array of series objects (for stacking support)
+ * @param axisType - Whether this is an 'x' or 'y' axis
+ * @returns The calculated axis bounds
+ */
+export declare const getAxisDomain: (
+  axisParam: AxisConfigProps,
+  series: Series[],
+  axisType: 'x' | 'y',
+) => AxisBounds;
+/**
+ * Calculates the visual range for an axis based on the chart rectangle and configuration.
+ * Handles custom range configurations including functions and partial bounds.
+ *
+ * @param axisParam - The axis configuration
+ * @param chartRect - The chart drawing area rectangle
+ * @param axisType - Whether this is an 'x' or 'y' axis
+ * @returns The calculated axis range bounds
+ */
+export declare const getAxisRange: (
+  axisParam: AxisConfigProps,
+  chartRect: Rect,
+  axisType: 'x' | 'y',
+) => AxisBounds;
+/**
+ * Options for tick generation behavior
+ */
+type TickGenerationOptions = {
+  /**
+   * Minimum step size allowed for ticks.
+   * Prevents the step from being smaller than this value.
+   * @example 1 // Prevents fractional steps like 0.5
+   */
+  minStep?: number;
+  /**
+   * Maximum step size allowed for ticks.
+   * Prevents the step from being larger than this value.
+   * @example 100 // Prevents steps larger than 100
+   */
+  maxStep?: number;
+  /**
+   * Minimum number of ticks to generate when using tickInterval.
+   * @default 4
+   */
+  minTickCount?: number;
+};
+export type GetAxisTicksDataProps = {
+  /**
+   * Custom tick configuration for the axis.
+   * - **Array**: Uses these exact values for tick positioning and labels.
+   *   - For numeric scales: exact values to display
+   *   - For band scales: category indices to display
+   * - **Function**: Filters based on the predicate function.
+   *   - For numeric scales: filters generated tick values
+   *   - For band scales: filters category indices
+   */
+  ticks?: number[] | ((value: number) => boolean);
+  /**
+   * The scale function to use for positioning and tick generation.
+   * Can be either a numeric scale or a band scale.
+   */
+  scaleFunction: ChartScaleFunction;
+  /**
+   * Requested number of ticks to display (only used for numeric scales).
+   * For band/categorical scales, use the `ticks` parameter to control which categories are shown.
+   */
+  requestedTickCount?: number;
+  /**
+   * Categories for band scales
+   */
+  categories?: string[];
+  /**
+   * Possible tick values to filter from when using function-based ticks.
+   * Used for discrete data (such as 'band' scale indices).
+   */
+  possibleTickValues?: number[];
+  /**
+   * Interval at which to show ticks in pixels.
+   * When provided, calculates tick count based on available space and generates
+   * evenly distributed ticks that always include first and last domain values.
+   * Only applies to numeric scales and overrides requestedTickCount.
+   *
+   * @example
+   * // For a chart with 400px width, tickInterval: 64 would generate ~6 ticks
+   * // evenly distributed across the data range, always including first and last values
+   * getAxisTicksData({
+   *   scaleFunction: numericScale,
+   *   tickInterval: 32,
+   *   possibleTickValues: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
+   * });
+   * // Result: ticks at indices [0, 2, 4, 6, 8, 10] with their corresponding positions
+   */
+  tickInterval?: number;
+  /**
+   * Options for tick generation behavior
+   */
+  options?: TickGenerationOptions;
+};
+/**
+ * Formats a tick value for display on an axis.
+ * Consolidates the identical formatting logic shared between XAxis and YAxis.
+ *
+ * @param value - The raw tick value to format
+ * @param tickFormatter - Optional custom formatter function
+ * @returns The formatted tick value as a React node
+ */
+export declare const formatAxisTick: (
+  value: any,
+  tickFormatter?: (value: any) => React.ReactNode,
+) => React.ReactNode;
+/**
+ * Processes tick configuration and returns tick data with positions.
+ *
+ * **Parameter Precedence by Scale Type:**
+ *
+ * **For Numeric Scales (linear/log):**
+ * 1. `ticks` (array) - Explicit tick values override all other options
+ * 2. `ticks` (function) - Filter function for tick selection
+ * 3. `ticks` (boolean) - Show/hide all possible ticks
+ * 4. `requestedTickCount` - D3 automatic tick generation (overrides tickInterval)
+ * 5. `tickInterval` - Pixel-based spacing (fallback)
+ *
+ * **For Categorical Scales (band):**
+ * 1. `ticks` (array) - Explicit category indices to display
+ * 2. `ticks` (function) - Filter function for category selection
+ * 3. `ticks` (boolean) - Show/hide all categories
+ * 4. Default - Show all categories (requestedTickCount and tickInterval are ignored)
+ *
+ * @param params - Tick processing parameters
+ * @param params.ticks - Custom tick configuration with multiple formats:
+ *   - **Array**: For numeric scales: exact tick values; For band scales: category indices
+ *   - **Function**: Predicate to filter tick values or category indices
+ *   - **Boolean**: Show all (true) or no ticks (false) for both scale types
+ * @param params.scaleFunction - D3 scale function (numeric or band scale)
+ * @param params.requestedTickCount - Number of ticks for D3 generation (**numeric scales only**, overrides tickInterval)
+ * @param params.categories - Category labels (**band scales only**)
+ * @param params.possibleTickValues - Available tick values for filtering/selection (**numeric scales only**)
+ * @param params.tickInterval - Pixel spacing between ticks (**numeric scales only**, fallback option)
+ * @returns Array of tick data with values and positions
+ *
+ * @example
+ * // Basic usage with tickInterval for pixel-based spacing
+ * import { scaleLinear } from 'd3-scale';
+ *
+ * const numericScale = scaleLinear().domain([0, 10]).range([0, 400]);
+ * const result = getAxisTicksData({
+ *   scaleFunction: numericScale,
+ *   tickInterval: 80, // 80 pixels between ticks
+ *   possibleTickValues: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
+ * });
+ * // Returns: [
+ * //   { tick: 0, position: 0 },    // Always includes first
+ * //   { tick: 2, position: 80 },
+ * //   { tick: 5, position: 200 },
+ * //   { tick: 7, position: 280 },
+ * //   { tick: 10, position: 400 }  // Always includes last
+ * // ]
+ *
+ * @example
+ * // Using requestedTickCount for D3-generated ticks
+ * const result = getAxisTicksData({
+ *   scaleFunction: numericScale,
+ *   requestedTickCount: 5
+ * });
+ * // Uses D3's tick generation algorithm
+ *
+ * @example
+ * // Using explicit tick values
+ * const result = getAxisTicksData({
+ *   scaleFunction: numericScale,
+ *   ticks: [0, 2.5, 5, 7.5, 10]
+ * });
+ * // Returns exact positions for specified values
+ *
+ * @example
+ * // Using tick filter function
+ * const result = getAxisTicksData({
+ *   scaleFunction: numericScale,
+ *   ticks: (value) => value % 2 === 0, // Only even numbers
+ *   possibleTickValues: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
+ * });
+ * // Returns: [0, 2, 4, 6, 8, 10] with their positions
+ *
+ * @example
+ * // Band scale with categories (requestedTickCount and tickInterval are ignored)
+ * import { scaleBand } from 'd3-scale';
+ *
+ * const bandScale = scaleBand().domain([0, 1, 2, 3, 4]).range([0, 400]).padding(0.1);
+ * const result = getAxisTicksData({
+ *   scaleFunction: bandScale,
+ *   categories: ['Jan', 'Feb', 'Mar', 'Apr', 'May'],
+ *   ticks: [0, 2, 4], // Show only Jan (index 0), Mar (index 2), May (index 4)
+ *   requestedTickCount: 10, // IGNORED for band scales
+ *   tickInterval: 50 // IGNORED for band scales
+ * });
+ * // Returns tick positions centered in each selected band
+ */
+export declare const getAxisTicksData: ({
+  ticks,
+  scaleFunction,
+  requestedTickCount,
+  categories,
+  possibleTickValues,
+  tickInterval,
+  options,
+}: GetAxisTicksDataProps) => Array<{
+  tick: number;
+  position: number;
+}>;
+export type RegisteredAxis = {
+  id: string;
+  position: 'top' | 'bottom' | 'left' | 'right';
+  size: number;
+};
+/**
+ * Calculates the total amount of padding needed to render a set of axes on the main drawing area of the chart.
+ * Returns the registed axes, an API for adding/removing axes as well as the total calculated padding that must be reserved in the drawing area.
+ */
+export declare const useTotalAxisPadding: () => {
+  renderedAxes: Map<string, RegisteredAxis>;
+  axisPadding: {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+  };
+  registerAxis: (id: string, position: 'top' | 'bottom' | 'left' | 'right', size: number) => void;
+  unregisterAxis: (id: string) => void;
+};
+export {};
+//# sourceMappingURL=axis.d.ts.map

package/dts/chart/utils/axis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"axis.d.ts","sourceRoot":"","sources":["../../../src/chart/utils/axis.ts"],"names":[],"mappings":"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"}

package/dts/chart/utils/bar.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Calculates the size adjustment needed for bars when accounting for gaps between them.
+ * This function helps determine how much to reduce each bar's width to accommodate
+ * the specified gap size between multiple bars in a group.
+ *
+ * @param barCount - The number of bars in the group
+ * @param gapSize - The desired gap size between bars
+ * @returns The amount to reduce each bar's size by, or 0 if there's only one bar
+ *
+ * @example
+ * ```typescript
+ * // For 3 bars with 12px gaps, each bar should be reduced by 8px
+ * const adjustment = getBarSizeAdjustment(3, 12);
+ *
+ * // Single bar needs no adjustment
+ * const singleBarAdjustment = getBarSizeAdjustment(1, 10);
+ * ```
+ */
+export declare function getBarSizeAdjustment(barCount: number, gapSize: number): number;
+//# sourceMappingURL=bar.d.ts.map

package/dts/chart/utils/bar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bar.d.ts","sourceRoot":"","sources":["../../../src/chart/utils/bar.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAM9E"}