@coinbase/cds-web 8.66.2 → 9.0.0-rc.1

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

@@ -0,0 +1,117 @@
+import React from 'react';
+import type { Rect, SharedProps } from '@coinbase/cds-common/types';
+import { type BoxProps } from '../../../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 ChartTextBaseProps = SharedProps & {
+  /**
+   * The text color.
+   * @default 'var(--color-fgMuted)'
+   */
+  color?: string;
+  /**
+   * The background color of the text's background rectangle.
+   * @default 'var(--color-bg)' if elevated, otherwise 'transparent'
+   */
+  background?: string;
+  /**
+   * Whether the text should have an elevated appearance with a shadow.
+   * @default false
+   */
+  elevated?: boolean;
+  /**
+   * 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;
+  /**
+   * Border radius for the background rectangle.
+   * @default 4
+   */
+  borderRadius?: number;
+};
+export type ChartTextProps = ChartTextBaseProps &
+  Pick<BoxProps<'g'>, 'font' | 'fontFamily' | 'fontSize' | 'fontWeight' | 'opacity'> & {
+    /**
+     * The desired x offset in SVG pixels.
+     */
+    dx?: number;
+    /**
+     * The desired y offset in SVG pixels.
+     */
+    dy?: number;
+    /**
+     * 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 component.
+     * @default 'center'
+     */
+    horizontalAlignment?: TextHorizontalAlignment;
+    /**
+     * Vertical alignment of the component.
+     * @default 'middle'
+     */
+    verticalAlignment?: TextVerticalAlignment;
+    style?: React.CSSProperties;
+    styles?: {
+      root?: React.CSSProperties;
+      text?: React.CSSProperties;
+      backgroundRect?: React.CSSProperties;
+    };
+    className?: string;
+    classNames?: {
+      root?: string;
+      text?: string;
+      backgroundRect?: string;
+    };
+  };
+export declare const ChartText: React.NamedExoticComponent<ChartTextProps>;
+export {};
+//# sourceMappingURL=ChartText.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ChartText.d.ts","sourceRoot":"","sources":["../../../../src/visualizations/chart/text/ChartText.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAqD,MAAM,OAAO,CAAC;AAC1E,OAAO,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAIpE,OAAO,EAAO,KAAK,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAGrD,OAAO,EAAE,KAAK,UAAU,EAAiB,MAAM,UAAU,CAAC;AAG1D,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,kBAAkB,GAAG,WAAW,GAAG;IAC7C;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;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;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG,kBAAkB,GAC7C,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,YAAY,GAAG,UAAU,GAAG,YAAY,GAAG,SAAS,CAAC,GAAG;IACnF;;OAEG;IACH,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ;;OAEG;IACH,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ;;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,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;CACH,CAAC;AAkCJ,eAAO,MAAM,SAAS,4CA4MrB,CAAC"}

package/dts/visualizations/chart/text/ChartTextGroup.d.ts

@@ -0,0 +1,61 @@
+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 ChartTextGroupBaseProps = {
+  /**
+   * 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>;
+  /**
+   * Custom component to render each label
+   * @default ChartText
+   */
+  LabelComponent?: React.FC<ChartTextProps>;
+};
+export type ChartTextGroupProps = ChartTextGroupBaseProps;
+/**
+ * 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 ChartTextGroup: import('react').NamedExoticComponent<ChartTextGroupBaseProps>;
+//# sourceMappingURL=ChartTextGroup.d.ts.map

package/dts/visualizations/chart/text/ChartTextGroup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ChartTextGroup.d.ts","sourceRoot":"","sources":["../../../../src/visualizations/chart/text/ChartTextGroup.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,uBAAuB,GAAG;IACpC;;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;IACzC;;;OAGG;IACH,cAAc,CAAC,EAAE,KAAK,CAAC,EAAE,CAAC,cAAc,CAAC,CAAC;CAC3C,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG,uBAAuB,CAAC;AAiB1D;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,+DA0M1B,CAAC"}

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

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

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

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

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

@@ -0,0 +1,391 @@
+import type React from 'react';
+import type { Rect } from '@coinbase/cds-common/types';
+import { type AxisBounds, type Series } from './chart';
+import type { CartesianChartLayout } from './context';
+import { type ChartAxisScaleType, type ChartScaleFunction, type PointAnchor } from './scale';
+export declare const defaultAxisId = 'DEFAULT_AXIS_ID';
+export declare const defaultAxisScaleType = 'linear';
+/**
+ * Position options for band scale axis elements.
+ *
+ * - `'start'` - At the start of each step (before bar padding)
+ * - `'middle'` - At the center of each band
+ * - `'end'` - At the end of each step (after bar padding)
+ * - `'edges'` - At start of each tick, plus end for the last tick (encloses the chart)
+ *
+ * @note These properties only apply when using a band scale (`scaleType: 'band'`).
+ */
+export type AxisBandPlacement = 'start' | 'middle' | 'end' | 'edges';
+/**
+ * Converts an AxisBandPlacement to the corresponding PointAnchor for use with getPointOnScale.
+ *
+ * @param placement - The axis placement value
+ * @returns The corresponding PointAnchor for scale calculations
+ */
+export declare const toPointAnchor: (placement: AxisBandPlacement) => PointAnchor;
+/**
+ * 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.
+   * @note only used by the category 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';
+};
+export type CartesianAxisConfig = AxisConfig & {
+  /**
+   * Baseline value used as the origin for numeric series on this axis.
+   * Only applies when this axis is the value axis for the current chart layout.
+   * - Non-stacked numeric series render from `[baseline, value]`.
+   * - Multi-series stacks are normalized around this baseline before stacking.
+   *
+   * @default 0 for value axes, undefined for category axes
+   */
+  baseline?: number;
+};
+/**
+ * Axis configuration without computed bounds (used for input)
+ */
+export type CartesianAxisConfigProps = Omit<CartesianAxisConfig, '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);
+};
+export declare const withBaselineDomain: (
+  domain: CartesianAxisConfigProps['domain'],
+  baseline?: number,
+) => CartesianAxisConfigProps['domain'];
+/**
+ * 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.
+ *
+ * Range inversion is determined by axis role (category vs value) and layout:
+ * - Vertical layout: Y axis (value) is inverted for SVG coordinate system
+ * - Horizontal layout: Y axis (category) is inverted (first category at top)
+ *
+ * @param params - Scale parameters
+ * @returns The D3 scale function
+ * @throws An Error if bounds are invalid
+ */
+export declare const getCartesianAxisScale: ({
+  config,
+  type,
+  range,
+  dataDomain,
+  layout,
+}: {
+  config?: CartesianAxisConfig;
+  type: 'x' | 'y';
+  range: AxisBounds;
+  dataDomain: AxisBounds;
+  layout?: CartesianChartLayout;
+}) => 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<CartesianAxisConfigProps> | Partial<CartesianAxisConfigProps>[] | undefined,
+  defaultId?: string,
+  defaultScaleType?: ChartAxisScaleType,
+) => CartesianAxisConfigProps[];
+/**
+ * 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
+ * @param layout - Chart layout ('horizontal' or 'vertical')
+ * @returns The calculated axis bounds
+ */
+export declare const getCartesianAxisDomain: (
+  axisParam: CartesianAxisConfigProps,
+  series: Series[],
+  axisType: 'x' | 'y',
+  layout?: CartesianChartLayout,
+) => 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: CartesianAxisConfigProps,
+  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;
+  /**
+   * Anchor position for band/categorical scales.
+   * Controls where tick labels are positioned within each band.
+   * @default 'middle'
+   */
+  anchor?: PointAnchor;
+};
+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/visualizations/chart/utils/axis.d.ts.map

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