## Overview

The Tuple Line Chart widget enables the display of values of a tuple attribute over time. It visualizes time-series data stored in tuple entities by displaying numeric or enumeration values over time. It extracts data from tuple references attached to pages and plots them as line series, making it ideal for monitoring trends, progressions, and changes in associated tuple data.

This widget works specifically with cplace's tuple concept - lightweight data structures representing collections of related attribute values. Each tuple contains a date attribute (for temporal positioning) and one or more value attributes (numeric or enumeration).

## Use Cases

- **Tracking numeric values over time**: Monitor quantitative measurements that change over time (e.g., kilometrage readings, performance metrics, budget consumption)
- **Monitoring status changes**: Track categorical states over time using enumeration values with optional icons (e.g., inspection status history, approval states)
- **Comparing multiple metrics**: Display multiple related measurements from the same tuple simultaneously (e.g., actual vs. projected values)
- **Cross-entity comparison**: Use search mode to compare the same metrics across multiple entities on a dashboard

## Operating Modes

### Embedded Mode (Single Page)
When embedded directly on a page without a search query, the widget displays tuple data from that specific page only. Multiple value attributes create separate series on the same chart. Use this for detail pages showing historical data for one entity.

### Search Mode (Multiple Pages)
When configured with a search query, the widget finds multiple pages and creates separate series for each. If multiple value attributes are selected, series names combine page name with attribute name. Use this for dashboards comparing data across multiple entities.

## Design Considerations

### When to Use Tuple Line Chart
- Data is stored in tuple entities (marked with `.asTuple()`)
- You need to visualize temporal progressions from tuple collections
- Values are either all numeric or all enumeration (not mixed)

### When to Use Base Line Chart Instead
- Data comes from regular page attributes, not tuples
- You need more flexibility in data source configuration
- Time-series data is not stored in tuple structures

### Prerequisites
1. A custom type must be defined as a tuple
2. The tuple type must have at least one date attribute and one numeric or enumeration attribute
3. A main entity type must have a multi-reference attribute pointing to the tuple type
4. Tuple instances must exist and be referenced by pages

## Common Pitfalls

- Selecting value attributes of mixed types (some numeric, some enumeration) - all must be the same type
- Using enumeration attributes with different element sets - all enum attributes must share identical elements
- Configuring a tuple attribute that references multiple tuple types - exactly one tuple type is required

## Related Patterns

- **Base Line Chart** (`cf.cplace.visualizations.scriptingLineChart`) - Generic line chart for non-tuple data sources
- **Tuples Widget** (`cf.cplace.tuplesWidget.widget`) - Table-based display for editing tuple data
- **Connected Bar Chart** (`cf.platform.connectedBarChart`) - Alternative visualization for categorical comparisons