# Trend Chart Module

## Short Description

Trend Chart Module is a reusable Yeeflow dashboard custom code template that queries records from a data list, groups them by date, and displays the result as a line, area, or column trend chart.

## Purpose / What This Is For

Use this template when a dashboard needs to show how operational volume changes over time. It helps customers answer questions such as:

- How many requests were submitted each day?
- How has approval volume changed this month?
- Are inbound and outbound records increasing or decreasing?
- How many tasks were completed each week?
- What is the monthly issue/case volume trend?

Instead of creating a one-off chart for each dashboard, teams can configure this reusable module with a Yeeflow data list and a date field.

## Supported Placement

This template is optimized for:

- Dashboard page

It is a display/analytics module and does not write values back to form fields or dashboard variables.

## When To Use This Template

Use Trend Chart Module when:

- You need to count records over time.
- The source data is stored in a Yeeflow data list.
- The list has a reliable date field such as created date, submitted date, completed date, or attendance date.
- Users need a line, area, or column chart on a dashboard.
- You want reusable configuration across multiple customer apps.

## Recommended Defaults

For most dashboard modules, start with:

| Parameter | Recommended Value |
| --- | --- |
| `chartType` | `line` |
| `timeGranularity` | `day` |
| `maxPoints` | `12` |
| `showPointLabels` | `false` |
| `showXAxisLabels` | `true` |
| `showYAxis` | `true` |
| `colorMode` | `yeeflow` |
| `sortMode` | `chronological` |
| `dateRangeMode` | `last30Days` |
| `cumulativeMode` | `false` |
| `fillMissingBuckets` | `true` |
| `height` | `280` |
| `pageSize` | `500` |

## Input Parameters Overview

| Parameter | Type | Required | Purpose | Example Value |
| --- | --- | --- | --- | --- |
| `dataListId` | Expression editor | Yes | Target Yeeflow data list used as the data source. | `2034150397060198400` |
| `dateField` | Expression editor | Yes | Field ID/name used as the time axis. | `CreatedTime` |
| `titleText` | Plain text | No | Title shown at the top of the module. | `Request Trend` |
| `subtitleText` | Plain text | No | Supporting text below the title. | `Daily submitted requests` |
| `chartType` | Plain text | No | Chart presentation mode. | `line` |
| `timeGranularity` | Plain text | No | Time bucket grouping. | `day` |
| `maxPoints` | Numeric config | No | Maximum number of time buckets shown. | `12` |
| `showPointLabels` | Expression editor | No | Whether value labels are shown on chart points/columns. | `false` |
| `showXAxisLabels` | Expression editor | No | Whether date labels are shown on the x-axis. | `true` |
| `showYAxis` | Expression editor | No | Whether y-axis labels and grid lines are shown. | `true` |
| `emptyText` | Plain text | No | Text shown when no valid dated records are available. | `No trend data found` |
| `colorMode` | Plain text | No | Chart color tone. | `yeeflow` |
| `sortMode` | Plain text | No | Time sorting behavior. | `chronological` |
| `filterExpression` | Expression editor | No | Optional Yeeflow query filter object, array, or JSON value. | `[{"field":"Status","operator":"neq","value":"Cancelled"}]` |
| `height` | Numeric config | No | Minimum chart area height in pixels. | `280` |
| `pageSize` | Numeric config | No | Maximum records queried for aggregation. | `500` |
| `dateRangeMode` | Plain text | No | Local date range applied after query. | `last30Days` |
| `cumulativeMode` | Expression editor | No | Whether the chart shows running totals. | `false` |
| `fillMissingBuckets` | Expression editor | No | Whether missing date buckets are shown as zero. | `true` |
| `unknownDateLabel` | Plain text | No | Internal label for invalid dates in diagnostics. | `Invalid date` |

## Detailed Parameter Explanation

### `dataListId`

The Yeeflow data list ID to query. This should point to the list that contains the records you want to trend.

This parameter uses the expression editor so it can be configured from a static value, variable, temp variable, or expression result.

### `dateField`

The field ID or field name used for the time axis. The field should contain a valid date or date/time value.

Examples:

- `CreatedTime`
- `SubmitDate`
- `CompletedDate`
- `AttendanceDate`
- `RequestDate`

The code reads common Yeeflow row shapes defensively, including direct fields, `values`, `Fields`, and array-style field values.

### `titleText`

Optional title displayed at the top of the module.

### `subtitleText`

Optional helper text displayed below the title. Use it to clarify the date range or data scope.

### `chartType`

Controls the chart presentation.

Supported values:

- `line`
- `area`
- `areaLine`
- `column`
- `bar`

If blank or invalid, the module uses `line`.

### `timeGranularity`

Controls how records are grouped by time.

Supported values:

- `day`
- `week`
- `month`

Daily aggregation is the default. Weekly grouping uses Monday as the start of the week.

### `maxPoints`

Limits the number of time buckets displayed. If the chart has more buckets than the limit, the latest buckets are shown.

Default: `12`

### `showPointLabels`

Controls whether numeric labels appear above line points or columns.

This parameter uses the expression editor and supports values such as `true`, `false`, `1`, `0`, `yes`, and `no`.

### `showXAxisLabels`

Controls whether date bucket labels appear along the x-axis.

### `showYAxis`

Controls whether the y-axis labels and light grid lines are displayed.

### `emptyText`

Text shown when the query succeeds but no valid dated records are available.

### `colorMode`

Controls the chart tone.

Supported values:

- `yeeflow`
- `green`
- `amber`
- `red`
- `violet`
- `slate`

Default: `yeeflow`

### `sortMode`

Controls time ordering.

Supported values:

- `chronological`
- `reverseChronological`

Default: `chronological`

### `filterExpression`

Optional filter passed to the list query. This can be a JSON string, object, array, variable, or temp variable from the expression editor.

The template passes common filter aliases (`filters`, `filter`, `where`, and `filterExpression`) because exact Yeeflow query filter support may differ by runtime. If the filter shape is not supported by the current tenant/runtime, leave this parameter blank or adjust the filter format to match that environment.

### `height`

Minimum chart area height in pixels.

Default: `280`

### `pageSize`

Maximum number of records queried for aggregation. Increase it for larger lists, but keep dashboard performance in mind.

Default: `500`

### `dateRangeMode`

Applies a local date range after records are returned by the query.

Supported values:

- `all`
- `last7Days`
- `last30Days`
- `last90Days`
- `thisMonth`
- `last12Months`

Default: `all`

### `cumulativeMode`

When enabled, each point shows a running total instead of the count for that individual bucket.

This is useful for showing year-to-date volume, cumulative completions, or growing backlog count when the source data represents created records.

### `fillMissingBuckets`

When enabled, missing date buckets between the first and last bucket are shown as zero. This helps trend charts avoid visual gaps.

### `unknownDateLabel`

Used internally for invalid date handling. Invalid or empty dates are excluded from the chart and counted in the skipped-record note.

## Step-By-Step Setup Guide

1. Add a Custom Code control to a Yeeflow dashboard page.
2. Open the code editor and paste the `trend-chart-module.tsx` code.
3. Set `dataListId` to the target data list ID.
4. Set `dateField` to the field ID/name that contains the record date.
5. Add a clear `titleText`, such as `Request Trend`.
6. Choose `chartType`, such as `line`, `area`, or `column`.
7. Choose `timeGranularity`, such as `day`, `week`, or `month`.
8. Configure `dateRangeMode`, `maxPoints`, and `pageSize`.
9. Optionally configure `filterExpression` to limit which records are included.
10. Preview the dashboard and confirm the chart matches the expected list data.
11. Publish the dashboard when the result is correct.

## Result / Expected Output

After configuration, users see a dashboard card with:

- title and optional subtitle
- total record count
- line, area, or column trend chart
- optional point labels
- optional x-axis labels and y-axis grid
- empty/loading/error states when appropriate
- note when records are skipped because their date is empty or invalid

The template reads records from the configured data list and displays aggregated counts by date bucket. It does not save values back to fields or variables.

## Real Business Examples

### Daily Request Trend

Group service request records by `CreatedTime` using `day` granularity to show daily request volume.

### Monthly Approval Volume

Group approval records by `SubmitDate` using `month` granularity and `column` chart type.

### Weekly Task Completion Trend

Group completed task records by `CompletedDate` using `week` granularity and `area` chart type.

### Attendance Trend

Group attendance records by `AttendanceDate` to show daily check-in volume for operations dashboards.

## Notes / Assumptions / Limitations

- The template is optimized for dashboard display and does not write output values.
- The query uses `yeeSDKClient.lists.queryItems(...)`.
- The code sends common query payload aliases for compatibility, but exact filter support may vary by Yeeflow runtime.
- Aggregation is performed in the custom code after records are returned.
- Very large lists should use a reasonable `pageSize`, a dashboard-specific filtered list, or a server-side filtered query for performance.
- Empty or invalid dates are excluded from the trend and shown as skipped records.
- Weekly buckets start on Monday.
- `dateRangeMode` is applied locally after query results are returned.

## Testing Checklist

- Confirm the module renders on a dashboard page.
- Confirm `dataListId` loads the correct data list.
- Confirm `dateField` reads the correct date value.
- Test `line`, `area`, and `column`.
- Test `day`, `week`, and `month`.
- Test `showPointLabels = true` and `false`.
- Test `showXAxisLabels = true` and `false`.
- Test `showYAxis = true` and `false`.
- Test `dateRangeMode`, especially `last30Days` and `thisMonth`.
- Test `cumulativeMode = true`.
- Test `fillMissingBuckets = true`.
- Test empty data state.
- Test missing configuration state.
- Test invalid or empty date values.
- Test mobile or narrow dashboard widths.

## Troubleshooting

### The chart says to configure Data List ID and Date Field

Check that both `dataListId` and `dateField` are configured. If using expression editor values, confirm the expression returns a real list ID and field ID/name.

### The chart shows no data

Confirm the data list contains records and the selected date field has valid values. Also check whether `filterExpression` or `dateRangeMode` is excluding all records.

### Counts do not match expectations

The template counts records returned by `queryItems`. Check `pageSize`, filters, date range, and whether the list has more records than the query limit.

### Date labels look wrong

Confirm that `dateField` is the correct Yeeflow field ID/name. If the field returns text, use a standard date format such as `YYYY-MM-DD` or a Yeeflow date/date-time field.

### Filter does not work

Filter support can vary by Yeeflow runtime. Try leaving `filterExpression` blank first. Then test the filter shape expected by your specific data list query environment.
