## Overview

Visualizes an attribute of a table or a search configurable in the widget as a pie chart.

The Connected Pie Chart widget visualizes the distribution of values in a selected attribute as an interactive pie chart. It aggregates data by counting the frequency of each distinct value and displays the results as proportional slices with percentages and a legend.

The widget can operate in two modes: connected to a table widget for dynamic updates based on table filters, or with a direct search query for independent data visualization.

## Use Cases

### Status Distribution Analysis
Display the distribution of items across different status values to get a quick overview of work progress. For example, a project manager can see how many tasks are in each status category (Open, In Progress, Completed) to understand project health at a glance.

### Category Breakdown
Visualize how items are distributed across categorical attributes like priority, type, or department. This helps identify where resources should be focused, such as showing the distribution of support tickets by priority level.

### Demographic Analysis
Display demographic breakdowns such as team distribution, location distribution, or role distribution within an organization.

### Connected Filtering Scenario
When connected to a table widget, the pie chart updates dynamically based on table filters, providing real-time distribution visualization of filtered data. As users filter the table, the chart automatically reflects the filtered subset.

## Design Considerations

### Data Source Selection

The widget requires exactly one data source:

**Connected Table Mode (Recommended)**
- Links to an existing table widget on the same page
- Automatically responds to table filters and updates dynamically
- Enables interactive exploration of data alongside the table

**Direct Search Mode (Fallback)**
- Defines a search query directly in the widget
- Operates independently without dependency on other widgets
- **Use only when no table on the page holds the data to visualize**

> **Best Practice**: Always prefer connecting to a table widget. The table provides synchronized filtering, dynamic updates, and a consistent user experience. Only use direct search mode when the data to visualize is not represented by any table on the page.

### Attribute Requirements

The selected attribute must be an enumeration or reference attribute that can be aggregated. The widget counts occurrences of each distinct value and displays them as proportional slices.

### Visualization Behavior

- Displays percentages in tooltips
- Shows a legend with value names on the right side
- Slices can be selected/highlighted interactively
- Values are sorted alphabetically by display name

## Alternatives

### Connected Bar Chart
The `cf.platform.connectedBarChart` widget provides nearly identical functionality but displays data as vertical bars instead of pie slices.

**When to use Pie Chart:**
- You want to emphasize the proportion of parts to a whole (e.g., "50% of tasks are complete")
- You have a small number of categories (ideally 5-7 or fewer)

**When to use Bar Chart:**
- You have many categories
- You want to compare absolute values more precisely
- Categories have similar proportions that would be hard to distinguish as slices

## Related Patterns

- **cf.platform.connectedBarChart** - Same data visualization concept with bar chart display
- **cf.platform.connectedMatrix** - Two-dimensional visualization of relationships
- **cf.platform.connectedTableFilter** - Provides filtering controls that can drive connected charts
- **cf.platform.connectedSingleAttribute** - Displays a single attribute value from a selected table row
- **cf.platform.connectedAttributesGroup** - Displays multiple attributes from a selected table row