Selection Operations

/**
 * Selects the first descendant element matching the selector for each element
 * @param selector - CSS selector string or function
 * @returns New transition on the selected elements
 */
transition.select(selector: string | SelectFunction): Transition;

// CSS selector
transition.select("circle");
transition.select(".highlight");
transition.select("#main-item");

// Function-based selection
transition.select(function(d, i) {
  return this.querySelector(".item-" + i);
});

// Complex selectors
transition.select("g.axis text");
transition.select("[data-category='primary']");

// Chaining with animation
transition
  .select("circle")
  .attr("fill", "red")
  .attr("r", 10);

/**
 * Selects all descendant elements matching the selector for each element
 * @param selector - CSS selector string or function
 * @returns New transition on the selected elements
 */
transition.selectAll(selector: string | SelectAllFunction): Transition;

// Select all matching elements
transition.selectAll("circle");
transition.selectAll(".data-point");

// Function-based selection
transition.selectAll(function(d, i) {
  return this.querySelectorAll(".item");
});

// Multiple classes
transition.selectAll(".primary, .secondary");

// Animate all selected elements
transition
  .selectAll("rect")
  .attr("width", 20)
  .style("fill", "blue");

// Common pattern: select parent, then children
select("svg")
  .transition()
  .selectAll("circle")
  .attr("r", d => d.value);

/**
 * Selects the first child element matching the optional selector
 * @param selector - Optional CSS selector string or function
 * @returns New transition on the selected child elements
 */
transition.selectChild(selector?: string | SelectFunction): Transition;

// Select first child
transition.selectChild();

// Select first child of specific type
transition.selectChild("circle");
transition.selectChild("text");

// Function-based child selection
transition.selectChild(function() {
  return this.children[0];
});

// Use case: animate container and first child
select("g")
  .transition()
  .attr("transform", "translate(100, 0)")
  .selectChild("circle")
  .attr("r", 15);

/**
 * Selects all child elements matching the optional selector
 * @param selector - Optional CSS selector string or function
 * @returns New transition on the selected child elements
 */
transition.selectChildren(selector?: string | SelectFunction): Transition;

// Select all children
transition.selectChildren();

// Select all children of specific type
transition.selectChildren("rect");
transition.selectChildren("text");

// Function-based children selection
transition.selectChildren(function() {
  return Array.from(this.children);
});

// Animate all child elements
transition
  .selectChildren("circle")
  .attr("opacity", 0.7)
  .attr("stroke-width", 2);

/**
 * Filters elements in the transition based on a predicate
 * @param filter - CSS selector string or predicate function
 * @returns New transition containing only matching elements
 */
transition.filter(filter: string | FilterFunction): Transition;

// CSS selector filter
transition.filter(".active");
transition.filter("[data-visible='true']");

// Function-based filter
transition.filter(function(d, i) {
  return d.value > 10;
});

// Filter by index
transition.filter((d, i) => i % 2 === 0); // Even indices only

// Filter by data properties
transition.filter(d => d.category === "important");

// Combine with animation
transition
  .filter(".highlighted")
  .style("stroke", "red")
  .style("stroke-width", 3);

// Complex filtering
transition
  .filter(function(d) {
    return d.score > 50 && d.active;
  })
  .attr("fill", "gold");

/**
 * Merges this transition with another transition of the same ID
 * @param other - Another transition to merge with
 * @returns New transition with merged elements
 */
transition.merge(other: Transition): Transition;

// Merge enter and update transitions
const update = select("svg")
  .selectAll("circle")
  .data(data)
  .transition()
  .attr("fill", "blue");

const enter = update.selection()
  .enter()
  .append("circle")
  .transition()
  .attr("r", 5);

// Merge and apply common animation
update.merge(enter)
  .attr("cx", d => d.x)
  .attr("cy", d => d.y);

// Common D3 pattern: update + enter + exit
const circles = svg.selectAll("circle").data(data);

const update = circles.transition().attr("fill", "blue");
const enter = circles.enter().append("circle").transition().attr("r", 0);
const exit = circles.exit().transition().attr("r", 0).remove();

// Merge update and enter for common properties
update.merge(enter)
  .attr("cx", d => d.x)
  .attr("cy", d => d.y)
  .attr("r", 5);

// Parent transition configuration
const parent = transition()
  .duration(1000)
  .ease(d3.easeBounceOut);

// Child transitions inherit timing
parent
  .selectAll("circle")
  .attr("r", 10)          // Uses parent's duration and easing
  .select("text")
  .style("opacity", 0);   // Also inherits parent's timing

// Animate container, then contents
select("g.chart")
  .transition()
  .duration(500)
  .attr("transform", "translate(50, 50)")
  .transition()           // Chained transition
  .selectAll("rect")
  .attr("height", d => d.value);

// Different animations based on selection
const baseTransition = selectAll(".item").transition();

// Animate visible items
baseTransition
  .filter(".visible")
  .style("opacity", 1);

// Hide invisible items
baseTransition
  .filter(":not(.visible)")
  .style("opacity", 0);

// Multi-level selection and animation
transition
  .selectAll("g.group")
  .attr("transform", d => `translate(${d.x}, ${d.y})`)
  .selectAll("circle")
  .attr("r", d => d.radius)
  .attr("fill", d => d.color);

type SelectFunction = (this: Element, d: any, i: number, group: Element[]) => Element | null;
type SelectAllFunction = (this: Element, d: any, i: number, group: Element[]) => Element[] | NodeList;
type FilterFunction = (this: Element, d: any, i: number, group: Element[]) => boolean;