Core Utilities and Configuration

/**
 * Global configuration instance
 */
const config: Config;

interface Config {
  /** Date formatting function for display */
  dateFormat: (date: Date) => string;
  
  /** Global transition disable flag */
  disableTransitions: boolean;
  
  /** D3.js compatibility settings */
  _d3_3_compatibility: boolean;
}

import { config } from 'dc';

// Customize date formatting
config.dateFormat = d3.timeFormat('%Y-%m-%d');

// Disable all transitions globally
config.disableTransitions = true;

// Check current settings
console.log('Transitions enabled:', !config.disableTransitions);

/**
 * Start a transition on selection if transitions are enabled
 * @param {d3.Selection} selection - The selection to transition
 * @param {Number|Function} [duration=250] - Transition duration in ms
 * @param {Number|Function} [delay] - Transition delay in ms
 * @param {String} [name] - Transition name for concurrent transitions
 * @returns {d3.Transition|d3.Selection} Transition or selection if disabled
 */
function transition(
  selection: d3.Selection, 
  duration?: number | Function, 
  delay?: number | Function, 
  name?: string
): d3.Transition | d3.Selection;

/**
 * Create conditional transition function
 * @param {Boolean} enable - Whether to enable transitions
 * @param {Number} duration - Transition duration
 * @param {Number} delay - Transition delay
 * @param {String} name - Transition name
 * @returns {Function} Function that applies or skips transition
 */
function optionalTransition(
  enable: boolean, 
  duration?: number, 
  delay?: number, 
  name?: string
): (selection: d3.Selection) => d3.Transition | d3.Selection;

/**
 * Execute callback after transition completes
 * @param {d3.Transition} transition - The transition to monitor
 * @param {Function} callback - Callback to execute after completion
 */
function afterTransition(transition: d3.Transition, callback: Function): void;

import { transition, afterTransition } from 'dc';

// Apply transition if globally enabled
const t = transition(selection, 500, 100);

// Execute callback after transition
afterTransition(t, function() {
  console.log('Transition completed');
});

/**
 * Utility functions namespace
 */
const utils: UtilsNamespace;

interface UtilsNamespace {
  /** Format single values for display */
  printSingleValue(value: any): string;
  
  /** Add values with date/percentage support */
  add(left: any, right: any, unit?: string): any;
  
  /** Subtract values with date/percentage support */
  subtract(left: any, right: any, unit?: string): any;
  
  /** Check if value is a number */
  isNumber(value: any): boolean;
  
  /** Check if value is a float */
  isFloat(value: any): boolean;
  
  /** Check if value is an integer */
  isInteger(value: any): boolean;
  
  /** Check if value is negligible (close to zero) */
  isNegligible(value: number): boolean;
  
  /** Constrain value to min/max range */
  clamp(value: number, min: number, max: number): number;
  
  /** Create function that returns constant value */
  constant(value: any): () => any;
  
  /** Generate unique integer ID */
  uniqueId(): number;
  
  /** Convert name to valid HTML/CSS ID */
  nameToId(name: string): string;
  
  /** Append or select DOM elements */
  appendOrSelect(parent: d3.Selection, selector: string, tag?: string): d3.Selection;
  
  /** Return number or 0 for invalid values */
  safeNumber(value: any): number;
  
  /** Compare arrays for equality */
  arraysEqual(arr1: any[], arr2: any[]): boolean;
  
  /** Check array identity (same reference) */
  arraysIdentical(arr1: any[], arr2: any[]): boolean;
  
  /** Get all child paths for hierarchical data */
  allChildren(node: any): any[];
  
  /** Build d3 hierarchy from flat collection */
  toHierarchy(collection: any[], accessor: Function): d3.HierarchyNode;
  
  /** Get ancestor path for hierarchical data */
  getAncestors(node: any): any[];
}

import { utils } from 'dc';

// Format values for display
console.log(utils.printSingleValue(1234.567)); // "1234.57"
console.log(utils.printSingleValue(new Date())); // Formatted date

// Math operations with dates and percentages
const tomorrow = utils.add(new Date(), 1, 'day');
const total = utils.add(100, '10%'); // 110

// Type checking
if (utils.isNumber(value) && !utils.isNegligible(value)) {
  // Process significant numeric value
}

// Array operations
const equal = utils.arraysEqual([1, 2, 3], [1, 2, 3]); // true
const same = utils.arraysIdentical(arr1, arr1); // true

// Unique IDs
const id = utils.uniqueId(); // Generates unique integer
const elementId = utils.nameToId('My Chart Name'); // "my-chart-name"

/**
 * Create property accessor function
 * @param {String} property - Property name to access
 * @param {Function} [transform] - Optional transformation function
 * @returns {Function} Accessor function
 */
function pluck(property: string, transform?: Function): Function;

import { pluck } from 'dc';

// Simple property access
const getName = pluck('name');
console.log(getName({name: 'John', age: 30})); // "John"

// With transformation
const getFormattedPrice = pluck('price', (price, i) => `$${price.toFixed(2)}`);
console.log(getFormattedPrice({price: 19.99})); // "$19.99"

// Use with D3 selections
selection.data(data).text(pluck('label'));

/**
 * Units calculation namespace
 */
const units: UnitsNamespace;

interface UnitsNamespace {
  /** Count integers in range for ordinal scales */
  integers: (start: number, end: number) => number;
  
  /** Ordinal scale mode placeholder */
  ordinal: any;
  
  /** Floating-point precision calculator */
  fp: {
    precision: (value: number) => number;
  };
}

import { units } from 'dc';

// For bar charts with integer data
chart.xUnits(units.integers);

// For ordinal data
chart.xUnits(units.ordinal);

// Calculate precision
const precision = units.fp.precision(0.123456); // 6

/**
 * Library constants
 */
const constants: ConstantsObject;

interface ConstantsObject {
  /** CSS class for all charts */
  CHART_CLASS: 'dc-chart';
  
  /** CSS class for debug group */
  DEBUG_GROUP_CLASS: 'debug';
  
  /** CSS class for stacks */
  STACK_CLASS: 'stack';
  
  /** CSS class for deselected elements */
  DESELECTED_CLASS: 'deselected';
  
  /** CSS class for selected elements */
  SELECTED_CLASS: 'selected';
  
  /** Property name for node indices */
  NODE_INDEX_NAME: '__index__';
  
  /** Property name for group indices */
  GROUP_INDEX_NAME: '__group_index__';
  
  /** Default chart group identifier */
  DEFAULT_CHART_GROUP: '__default_chart_group__';
  
  /** Default event throttling delay */
  EVENT_DELAY: 40;
  
  /** Threshold for negligible numbers */
  NEGLIGIBLE_NUMBER: 1e-10;
}

import { constants } from 'dc';

// Use in CSS selectors
d3.selectAll(`.${constants.CHART_CLASS}`)
  .classed(constants.SELECTED_CLASS, true);

// Check for negligible values
if (Math.abs(value) < constants.NEGLIGIBLE_NUMBER) {
  // Treat as zero
}

/**
 * Event management namespace
 */
const events: EventsNamespace;

interface EventsNamespace {
  /** Throttled event execution */
  trigger: (callback: Function, delay?: number) => void;
}

/**
 * Global logger instance
 */
const logger: Logger;

interface Logger {
  /** Enable/disable debug mode */
  enableDebugLog: boolean;
  
  /** Log debug message */
  debug: (message: any, ...args: any[]) => void;
  
  /** Log warning message */
  warn: (message: any, ...args: any[]) => void;
  
  /** Log info message */
  info: (message: any, ...args: any[]) => void;
}

import { logger } from 'dc';

// Enable debug logging
logger.enableDebugLog = true;

// Log messages
logger.debug('Chart render started', chart);
logger.warn('Deprecated method used');
logger.info('Data updated');

/**
 * Display formatting namespace
 */
const printers: PrintersNamespace;

interface PrintersNamespace {
  /** Format filter arrays for display */
  filters: (filters: any[]) => string;
  
  /** Format single filter for display */
  filter: (filter: any) => string;
}

import { printers } from 'dc';

const currentFilters = chart.filters();
const filterDisplay = printers.filters(currentFilters);
console.log(`Current filters: ${filterDisplay}`);

/**
 * Check if object is a DC.js chart instance
 * @param {any} object - Object to test
 * @returns {Boolean} True if object is a DC.js chart
 */
function instanceOfChart(object: any): boolean;

import { instanceOfChart, BarChart } from 'dc';

const chart = new BarChart('#chart');
const div = d3.select('#chart');

console.log(instanceOfChart(chart)); // true
console.log(instanceOfChart(div)); // false

/**
 * Set/get global renderlet function
 * @param {Function} [renderletFunction] - Function to execute after each render
 * @returns {Function|null} Current renderlet or null
 */
function renderlet(renderletFunction?: Function): Function | null;

import { renderlet } from 'dc';

// Set global renderlet
renderlet(() => {
  console.log('A chart was rendered');
  // Custom post-render logic
});

// Get current renderlet
const currentRenderlet = renderlet();

interface Config {
  dateFormat: (date: Date) => string;
  disableTransitions: boolean;
}

interface UtilsNamespace {
  printSingleValue(value: any): string;
  add(left: any, right: any, unit?: string): any;
  subtract(left: any, right: any, unit?: string): any;
  isNumber(value: any): boolean;
  isFloat(value: any): boolean;
  isInteger(value: any): boolean;
  isNegligible(value: number): boolean;
  clamp(value: number, min: number, max: number): number;
  constant(value: any): () => any;
  uniqueId(): number;
  nameToId(name: string): string;
  appendOrSelect(parent: d3.Selection, selector: string, tag?: string): d3.Selection;
  safeNumber(value: any): number;
  arraysEqual(arr1: any[], arr2: any[]): boolean;
  arraysIdentical(arr1: any[], arr2: any[]): boolean;
  allChildren(node: any): any[];
  toHierarchy(collection: any[], accessor: Function): d3.HierarchyNode;
  getAncestors(node: any): any[];
}

interface UnitsNamespace {
  integers: (start: number, end: number) => number;
  ordinal: any;
  fp: {
    precision: (value: number) => number;
  };
}

interface ConstantsObject {
  CHART_CLASS: string;
  DEBUG_GROUP_CLASS: string;
  STACK_CLASS: string;
  DESELECTED_CLASS: string;
  SELECTED_CLASS: string;
  NODE_INDEX_NAME: string;
  GROUP_INDEX_NAME: string;
  DEFAULT_CHART_GROUP: string;
  EVENT_DELAY: number;
  NEGLIGIBLE_NUMBER: number;
}

interface Logger {
  enableDebugLog: boolean;
  debug: (message: any, ...args: any[]) => void;
  warn: (message: any, ...args: any[]) => void;
  info: (message: any, ...args: any[]) => void;
}

interface PrintersNamespace {
  filters: (filters: any[]) => string;
  filter: (filter: any) => string;
}

interface EventsNamespace {
  trigger: (callback: Function, delay?: number) => void;
}