# KPI Card Set

## A. Template name

KPI Card Set

## B. Short description

KPI Card Set is a reusable Yeeflow dashboard custom code template that displays a clean set of configurable KPI cards from a JSON array, variable, temp variable, or expression result.

## C. Purpose / what this is for

This template helps teams present important business metrics on Yeeflow dashboards in a consistent, readable format. It is useful when a dashboard needs to show a quick operational summary, such as totals, counts, performance values, service levels, or current status indicators.

Customers use this template when they want a polished KPI section without building custom UI from scratch each time. It keeps the display logic reusable while allowing each app or dashboard to provide different metric data.

## D. Supported placement

This template is optimized for:

- Dashboard page

It can display values from fixed JSON, dashboard variables, temp variables, or expressions. It does not write values back to form fields or temp variables.

## E. When to use this template

Use this template when:

- A dashboard needs 2-8 summary metrics.
- Metrics are already available as variables, temp variables, or expression results.
- The same KPI card layout should be reused across multiple dashboards.
- Delivery teams need a clean, enterprise-ready dashboard component.
- You want consistent visual treatment for totals, trends, targets, and status indicators.

Do not use this template when the dashboard needs a full chart, pivot table, drill-down table, or complex data exploration experience.

## F. Input parameters overview table

| Parameter name | Type | Required | Purpose | Example value |
| --- | --- | --- | --- | --- |
| `cardsConfig` | Expression / variable | Recommended | KPI card data as JSON array, object, variable, temp variable, or expression result. | See example below |
| `titleText` | Plain text | Optional | Title shown above the KPI card set. | `Executive Summary` |
| `subtitleText` | Plain text | Optional | Supporting text below the title. | `Current operational performance` |
| `layoutMode` | Plain text | Optional | Card layout: `auto`, `one`, `two`, `three`, or `four`. | `auto` |
| `cardTone` | Plain text | Optional | Default card color tone. | `blue` |
| `titleField` | Expression / variable | Optional | Source JSON field used as the card title. | `MetricName` |
| `valueField` | Expression / variable | Optional | Source JSON field used as the card value. | `MetricValue` |
| `subtitleField` | Expression / variable | Optional | Source JSON field used as subtitle/helper text. | `Description` |
| `trendField` | Expression / variable | Optional | Source JSON field used as trend/change text. | `ChangeText` |
| `trendDirectionField` | Expression / variable | Optional | Source JSON field used as trend direction. | `ChangeDirection` |
| `toneField` | Expression / variable | Optional | Source JSON field used as card tone. | `StatusColor` |
| `formatField` | Expression / variable | Optional | Source JSON field used as value format. | `ValueFormat` |
| `prefixField` | Expression / variable | Optional | Source JSON field used as value prefix. | `CurrencySymbol` |
| `suffixField` | Expression / variable | Optional | Source JSON field used as value suffix. | `UnitText` |
| `iconField` | Expression / variable | Optional | Source JSON field used as icon/marker text. | `ShortCode` |
| `targetLabelField` | Expression / variable | Optional | Source JSON field used as target label. | `GoalLabel` |
| `targetValueField` | Expression / variable | Optional | Source JSON field used as target value. | `GoalValue` |
| `decimalsField` | Expression / variable | Optional | Source JSON field used as decimal places. | `DecimalPlaces` |
| `showTrend` | Expression / variable | Optional | Shows or hides trend labels. | `true` |
| `showIcon` | Expression / variable | Optional | Shows or hides card icon/initial markers. | `true` |
| `compactMode` | Expression / variable | Optional | Uses tighter spacing for dense dashboards. | `false` |
| `emptyStateText` | Plain text | Optional | Text shown when no card data is configured. | `No KPI data available` |
| `numberLocale` | Plain text | Optional | Locale for number formatting. | `en-US` |
| `decimalPlaces` | Numeric config text | Optional | Default decimal places for numeric values. | `0` |
| `minCardWidth` | Numeric config text | Optional | Minimum card width in auto layout. | `220` |
| `valueSize` | Plain text | Optional | KPI value size: `small`, `medium`, or `large`. | `medium` |

## G. Detailed parameter explanation

### `cardsConfig`

The main KPI data source. This parameter uses the expression editor type so it can support static JSON, dashboard variables, temp variables, complex variables, or dynamic expressions.

Recommended format:

```json
[
  {
    "title": "Open Requests",
    "value": 42,
    "subtitle": "Pending review",
    "trend": "+12%",
    "trendDirection": "up",
    "tone": "blue",
    "format": "number"
  }
]
```

Supported card fields include:

| Field | Purpose | Example |
| --- | --- | --- |
| `title` | Card title. | `Open Requests` |
| `value` | Main KPI value. | `42` |
| `subtitle` | Short supporting text. | `Pending review` |
| `trend` | Change or trend label. | `+12%` |
| `trendDirection` | Trend style: `up`, `down`, or `neutral`. | `up` |
| `tone` | Card tone: `blue`, `green`, `amber`, `red`, `violet`, `slate`. | `green` |
| `format` | Value format: `auto`, `number`, `percent`, or `text`. | `number` |
| `prefix` | Text before the value. | `$` |
| `suffix` | Text after the value. | `hrs` |
| `decimals` | Card-specific decimal places. | `1` |
| `icon` | Small text marker shown in the icon area. | `REQ` |
| `targetLabel` | Optional target label. | `Target` |
| `targetValue` | Optional target value. | `95%` |

If `cardsConfig` is an object with `cards`, `items`, `data`, `list`, or `values`, the template will try to use that array. If it is a JSON string, the template will parse it safely. If it is invalid or blank, the empty state is shown.

You can use `cardsConfig` in two ways:

1. Use the built-in KPI schema shown above, with fields such as `title`, `value`, `subtitle`, and `trend`.
2. Pass any JSON array and use the field-mapping parameters below to tell the template which source fields to read.

Flexible source data example:

```json
[
  {
    "MetricName": "Open Requests",
    "MetricValue": 42,
    "Description": "Pending review",
    "ChangeText": "+12%",
    "ChangeDirection": "up",
    "StatusColor": "blue",
    "ValueFormat": "number"
  }
]
```

For the example above, configure:

| Parameter | Value |
| --- | --- |
| `titleField` | `MetricName` |
| `valueField` | `MetricValue` |
| `subtitleField` | `Description` |
| `trendField` | `ChangeText` |
| `trendDirectionField` | `ChangeDirection` |
| `toneField` | `StatusColor` |
| `formatField` | `ValueFormat` |

Field names are matched case-insensitively. Nested paths are also supported using dot notation, such as `metric.name` or `summary.currentValue`.

### Field mapping parameters

Field mapping parameters are optional expression-editor parameters. Use them when the data source uses customer-specific field names instead of the built-in KPI schema.

If a mapping parameter is blank, the template falls back to the built-in field names. For example, if `titleField` is blank, the template looks for `title`, `label`, `name`, or `heading`.

### `titleField`

The field in each source JSON item used as the KPI title.

Example: `MetricName`

### `valueField`

The field in each source JSON item used as the main KPI value.

Example: `MetricValue`

### `subtitleField`

The field used as the small helper text under the title.

Example: `Description`

### `trendField`

The field used as the trend or change label.

Example: `ChangeText`

### `trendDirectionField`

The field used to style the trend as `up`, `down`, or `neutral`.

Example: `ChangeDirection`

### `toneField`

The field used as each card's color tone.

Example: `StatusColor`

### `formatField`

The field used as each value's display format.

Example: `ValueFormat`

### `prefixField` and `suffixField`

Fields used to place text before or after the KPI value.

Examples: `CurrencySymbol`, `UnitText`

### `iconField`

The field used as the small card marker text.

Example: `ShortCode`

### `targetLabelField` and `targetValueField`

Fields used to show target or goal information at the bottom of the card.

Examples: `GoalLabel`, `GoalValue`

### `decimalsField`

The field used as card-specific decimal places.

Example: `DecimalPlaces`

### `titleText`

Optional title shown above the card grid. Use this when the KPI section needs a dashboard heading.

Example: `Procurement Overview`

### `subtitleText`

Optional helper text under the title. Keep it short and business-friendly.

Example: `Live summary for active supplier requests`

### `layoutMode`

Controls how many columns the card grid tries to use.

Supported values:

- `auto`: responsive layout based on available width
- `one`: one column
- `two`: two columns
- `three`: three columns
- `four`: four columns

Use `auto` for most dashboards.

### `cardTone`

Default visual tone for cards that do not define their own `tone`.

Supported values:

- `blue`
- `green`
- `amber`
- `red`
- `violet`
- `slate`

Use calm tones that match the business meaning. For example, green for healthy values, amber for warning, red for risk, blue for neutral operational metrics.

### `showTrend`

Controls whether trend labels are shown. This is an expression-editor parameter, so it can be a fixed `true`/`false`, dashboard variable, temp variable, or expression.

Accepted values include `true`, `false`, `1`, `0`, `yes`, `no`, `on`, and `off`.

### `showIcon`

Controls whether the small card marker is shown. If a card has an `icon`, that text is shown. Otherwise, the template derives initials from the card title.

This parameter supports expression-editor values.

### `compactMode`

Uses tighter spacing and smaller card height. This is useful for dense dashboards or narrow dashboard sections.

This parameter supports expression-editor values.

### `emptyStateText`

Text shown when no valid cards are available.

Example: `No KPI data available`

### `numberLocale`

Locale used for number formatting. Leave blank to use the browser default.

Examples:

- `en-US`
- `en-GB`
- `de-DE`

### `decimalPlaces`

Default number of decimal places for numeric KPI values. A card can override this with its own `decimals` field.

Example: `1`

### `minCardWidth`

Minimum card width in pixels when `layoutMode` is `auto`.

Recommended values:

- `200` for dense dashboards
- `220` for normal dashboards
- `260` for wider executive dashboards

### `valueSize`

Controls the size of the KPI value.

Supported values:

- `small`
- `medium`
- `large`

Use `medium` for most dashboards.

## H. Step-by-step setup guide

1. Add a Custom Code control to a Yeeflow dashboard page.
2. Open the custom code editor.
3. Paste the `kpi-card-set.tsx` code.
4. Save the code.
5. Open input parameters.
6. Configure `cardsConfig` with a JSON array or select a dashboard variable/temp variable that returns the KPI card array.
7. If the source JSON does not use the built-in KPI field names, configure `titleField`, `valueField`, `subtitleField`, `trendField`, and any other field mappings you need.
8. Optionally configure `titleText` and `subtitleText`.
9. Set `layoutMode` to `auto` unless a fixed column count is needed.
10. Configure `showTrend`, `showIcon`, and `compactMode` as needed.
11. Save the dashboard.
12. Preview and confirm the card values, layout, number formatting, trend styles, and mobile/narrow behavior.

## I. Result / expected output

After setup, users will see a responsive set of KPI cards on the dashboard. Each card can show:

- title
- main value
- subtitle
- trend/change label
- tone/accent color
- optional icon marker
- optional target label/value

The template is display-only. It does not save values back into Yeeflow fields or variables.

## J. Real business examples

### Procurement dashboard

Show open purchase requests, approved requests this month, overdue supplier reviews, and average approval cycle time.

### Customer service dashboard

Show open tickets, SLA compliance, average response time, and escalations.

### HR operations dashboard

Show active onboarding cases, pending approvals, monthly new hires, and training completion rate.

### Asset management dashboard

Show total assets, maintenance due, overdue inspections, and asset utilization.

## K. Notes / assumptions / limitations

- This template is optimized for dashboard display.
- It expects KPI values to be prepared by variables, temp variables, expressions, or upstream dashboard logic.
- It supports custom source JSON field names through field mapping parameters.
- It does not query a Yeeflow data list directly in this version.
- It does not save output values.
- Invalid JSON or empty card data will show the empty state instead of crashing.
- `percent` format appends `%` to the provided numeric value. If you want `85%`, provide `85`, not `0.85`.
- Use short card titles and subtitles for best dashboard readability.

## L. Testing checklist

- Confirm the dashboard renders with a valid `cardsConfig` JSON array.
- Confirm field mappings work with customer-specific JSON field names.
- Confirm blank field mappings fall back to the built-in KPI schema.
- Confirm the empty state appears when `cardsConfig` is blank or invalid.
- Test `layoutMode`: `auto`, `two`, `three`, and `four`.
- Test `showTrend` with `true` and `false`.
- Test `showIcon` with `true` and `false`.
- Test `compactMode` with `true` and `false`.
- Test numeric values with `numberLocale` and `decimalPlaces`.
- Test card-level tones: `blue`, `green`, `amber`, `red`, `violet`, `slate`.
- Test mobile or narrow dashboard width.
- Test expression-editor input using a dashboard temp variable.

## M. Troubleshooting

### No cards appear

Check that `cardsConfig` is not blank and contains a valid JSON array or an expression result with a card array. If the data is inside an object, use a property such as `cards`, `items`, or `data`.

### The value formatting looks wrong

Check each card's `format`, `prefix`, `suffix`, and `decimals`. For percent values, pass the display number directly, such as `92`, and use `"format": "percent"`.

### Trend color is not correct

Set `trendDirection` on the card to `up`, `down`, or `neutral`. If this is omitted, the template infers `up` from values starting with `+` and `down` from values starting with `-`.

### The layout has too many or too few columns

Use `layoutMode` for fixed layouts or `minCardWidth` to tune responsive `auto` layout.

### A variable or temp variable does not render as expected

Check what the variable returns. The template supports arrays, JSON strings, and objects with `cards`, `items`, or `data`, but the final resolved value must contain card data.
