Timing Control

/**
 * Sets or gets the transition delay in milliseconds
 * @param value - Delay in milliseconds (constant or function), omit to get current delay
 * @returns The transition instance for chaining, or current delay if no value provided
 */
transition.delay(value?: number | DelayFunction): Transition | number;

// Constant delay
transition.delay(500); // 500ms delay

// Function-based delay (staggered animation)
transition.delay(function(d, i) {
  return i * 100; // 0ms, 100ms, 200ms, etc.
});

// Data-driven delay
transition.delay(d => d.delayTime);

// Common stagger pattern
selectAll("circle")
  .transition()
  .delay((d, i) => i * 50)
  .attr("r", 10);

// Get current delay (returns delay of first element)
const currentDelay = transition.delay();

/**
 * Sets or gets the transition duration in milliseconds
 * @param value - Duration in milliseconds (constant or function), omit to get current duration
 * @returns The transition instance for chaining, or current duration if no value provided
 */
transition.duration(value?: number | DurationFunction): Transition | number;

// Constant duration
transition.duration(1000); // 1 second

// Function-based duration
transition.duration(function(d, i) {
  return 500 + (i * 100); // Variable duration based on index
});

// Data-driven duration
transition.duration(d => d.animationTime);

// Common patterns
transition.duration(d => d.important ? 2000 : 500);

// Get current duration
const currentDuration = transition.duration();

// Short animation
transition.duration(150).style("opacity", 0);

// Long, dramatic animation
transition.duration(3000).attr("transform", "scale(2)");

/**
 * Sets or gets the easing function for the transition
 * @param value - Easing function, omit to get current easing function
 * @returns The transition instance for chaining, or current easing function if no value provided
 */
transition.ease(value?: EaseFunction): Transition | EaseFunction;

// Linear easing
transition.ease(d3.easeLinear);

// Cubic easing (default family)
transition.ease(d3.easeCubic);        // cubic in-out
transition.ease(d3.easeCubicIn);      // cubic in
transition.ease(d3.easeCubicOut);     // cubic out
transition.ease(d3.easeCubicInOut);   // cubic in-out (default)

// Bounce easing
transition.ease(d3.easeBounce);       // bounce out
transition.ease(d3.easeBounceIn);     // bounce in
transition.ease(d3.easeBounceOut);    // bounce out
transition.ease(d3.easeBounceInOut);  // bounce in-out

// Elastic easing
transition.ease(d3.easeElastic);      // elastic out
transition.ease(d3.easeElasticIn);    // elastic in
transition.ease(d3.easeElasticOut);   // elastic out
transition.ease(d3.easeElasticInOut); // elastic in-out

// Back easing
transition.ease(d3.easeBack);         // back out
transition.ease(d3.easeBackIn);       // back in
transition.ease(d3.easeBackOut);      // back out
transition.ease(d3.easeBackInOut);    // back in-out

// Smooth, natural animation
transition
  .duration(800)
  .ease(d3.easeCubicOut)
  .style("transform", "translateX(100px)");

// Bouncy effect
transition
  .duration(1500)
  .ease(d3.easeBounceOut)
  .attr("cy", 300);

// Custom easing function
transition.ease(function(t) {
  return t * t * t; // cubic in
});

// Linear for constant speed
transition
  .ease(d3.easeLinear)
  .duration(2000)
  .attr("stroke-dashoffset", 0);

// Get current easing function
const currentEase = transition.ease();

/**
 * Sets per-element easing functions using a factory
 * @param factory - Function that returns an easing function for each element
 * @returns The transition instance for chaining
 */
transition.easeVarying(factory: EaseFactory): Transition;

// Different easing based on data
transition.easeVarying(function(d, i) {
  return d.type === "primary" ? d3.easeBounceOut : d3.easeLinear;
});

// Alternating easing based on index
transition.easeVarying(function(d, i) {
  return i % 2 === 0 ? d3.easeBackOut : d3.easeBackIn;
});

// Data-driven easing intensity
transition.easeVarying(function(d) {
  if (d.priority === "high") return d3.easeElasticOut;
  if (d.priority === "medium") return d3.easeCubicOut;
  return d3.easeLinear;
});

// Staggered entrance with bounce
selectAll(".item")
  .transition()
  .delay((d, i) => i * 100)          // Stagger by 100ms
  .duration(800)                      // 800ms duration
  .ease(d3.easeBounceOut)            // Bounce easing
  .style("opacity", 1)
  .style("transform", "translateY(0)");

// Variable timing based on data
selectAll("circle")
  .transition()
  .delay(d => d.startTime)           // Data-driven delay  
  .duration(d => d.animationLength)  // Data-driven duration
  .ease(d3.easeBackOut)             // Consistent easing
  .attr("r", d => d.targetRadius);

// Sequential phases with different timing
const phase1 = transition()
  .duration(500)
  .ease(d3.easeLinear);

const phase2 = phase1.transition()   // Chained transition
  .duration(1000)
  .ease(d3.easeBounceOut);

selectAll(".element")
  .transition(phase1)
  .style("opacity", 0.5)
  .transition(phase2)  
  .style("transform", "scale(1.5)");

type DelayFunction = (this: Element, d: any, i: number, group: Element[]) => number;
type DurationFunction = (this: Element, d: any, i: number, group: Element[]) => number;
type EaseFunction = (t: number) => number;
type EaseFactory = (this: Element, d: any, i: number, group: Element[]) => EaseFunction;