KPI explained

A figure with its meaning, formula, source, freshness and host-defined thresholds.

Web · ✓Mobile · n/aBureau · ✓BêtaBlocs

import { KpiExplained } from "@krizaka/ui/kpi-explained";

Ventes du mois

Dans les attentes

6 994,46 $

Ce montant est entré dans la caisse en mars, avant les remboursements.

Calcul: Ventes TTC − remboursements
Source: export-mars.csvVérifier

Lu: 31 mars 2026, 18 h 00

Web uniquement — React, depuis @krizaka/ui/kpi-explained. Bêta : son API peut encore changer à une version mineure.

Mobile · n/a. The native twin is a follow-up; compose the same data in a native screen for now. → Stat

Pourquoi il est là. Akinaza's shop dashboard: monthly sales, spend and margin explained with their source and cadence; Orazaka later.

Quand l’utiliser

A shop owner needs to understand a monthly figure, not just read a number.
A dashboard must show the origin and age of a key figure.

Quand ne pas l’utiliser

A value needs only a label and a trend.À la place : Stat
A reader needs to change or enter the value.À la place : Field

Installation

Installer

npm install @krizaka/ui @krizaka/tailwind @krizaka/tokens tailwindcss

Styles

@import "tailwindcss";
@import "@krizaka/tailwind";
@import "@krizaka/ui/tailwind.css";

Importer

import { KpiExplained } from "@krizaka/ui/kpi-explained";

Exemples

A salon's month

A shop owner's revenue figure, explained in French with its source and read cadence.

Ventes du mois

Dans les attentes

6 994,46 $

Ce montant est entré dans la caisse en mars, avant les remboursements.

Calcul: Ventes TTC − remboursements
Source: export-mars.csvVérifier

Lu: 31 mars 2026, 18 h 00

A founder's cockpit

A masked figure for a public capture, without exposing its raw value.

Dépenses mensuelles

À surveiller

• •••••• •

Le total des factures payées ce mois-ci.

Calcul: Factures payées, taxes incluses
Source: ledger/octobre.csv

Lu: 22 oct. 2026, 12 h 00

Props

A key figure that explains what it means, how it is calculated and where it came from.

Prop	Type	Défaut	Description
`format`requis	`KpiFormat`	—	How to format the value with `@krizaka/intl`.
`formula`requis	`string`	—	The calculation in words, e.g. “dépenses TTC ÷ ventes TTC”.
`formulaLabel`requis	`ReactNode`	—	The localized label for the formula row.
`freshness`requis	`{ lastRead: DateInput; expectedAt: DateInput; now: DateInput; lastReadLabel: ReactNode; staleLabel: ReactNode; }`	—	Reading time and the expected next reading time (the host derives it from its cadence).
`label`requis	`ReactNode`	—	The figure's name.
`locale`requis	`Locale`	—	The app's locale, e.g. `fr-CA`.
`maskedLabel`requis	`string`	—	The accessible name shown instead of the value when masked.
`meaning`requis	`string`	—	One plain-language sentence about what the figure means.
`source`requis	`ReactNode`	—	The source link or file name, supplied by the host.
`sourceLabel`requis	`ReactNode`	—	The localized label for the source row.
`stateLabels`requis	`Record<KpiState, ReactNode>`	—	Host-provided words for the derived state.
`thresholds`requis	`{ direction: "above" \| "below"; watchAt: number; actAt: number; }`	—	Host-provided thresholds in the same units as `value`.
`value`requis	`number`	—	The raw number: money is integer minor units; percentages are ratios such as 0.125.
`masked`	`boolean`	`false`	Replace every non-space character in the value while preserving its formatted shape.
`sparkline`	`ReactNode`	—	An optional Sparkline from `@krizaka/charts`, with its own accessible summary.
`timeZone`	`string`	`UTC`	The IANA time zone for freshness dates; defaults to UTC for deterministic rendering.
`verify`	`ReactNode`	—	A host-provided action such as “Verify”, next to the source.

Accessibilité

The state and stale words remain visible; colour is never the only signal.
When masked, the figure is replaced in the DOM and its accessible name is maskedLabel.

Clavier

Touches	Action
`Tab`	Moves to the optional source and verify actions.

Bonnes pratiques

Give the meaning and formula in the host's plain language; thresholds and state words come from the host too.
Pass the expected read time derived from the host's cadence and an injected now for stable rendering.
Pass the host's IANA time zone for freshness dates; the default is UTC.
Pass a Sparkline from @krizaka/charts in sparkline; it owns its accessible summary.

Générée depuis le code de @krizaka/ui 3.63.1 : son meta.ts, ses exemples et ses types.Modifier cette documentation sur GitHub