Exclusifbêta
Trend Chip <mv-trend-chip>
La petite puce « ▲ +12,4 % vs la semaine dernière » pour les cartes KPI, les tableaux de bord, les grilles tarifaires et les rapports : donnez-lui la variation (value="0.124") ou deux montants (from / to) et elle affiche la valeur signée via Intl en pourcentage, en points de pourcentage, en nombre simple, dans n’importe quelle devise ou n’importe quelle unité (« −32 ms »), avec une période facultative. better="down" fait lire une baisse du churn, de la latence ou du coût comme positive, et le ton passe par la forme autant que par la couleur (triangle plein sur fond doux pour le positif, triangle creux dans une puce à contour pour le négatif, flèche fine pour le neutre, tiret pour la stagnation), avec une bande de tolérance qui compte les petits mouvements comme quasi stables. Ce que d’autres oublient : les lecteurs d’écran entendent une vraie phrase (« En hausse de 12,4 % vs la semaine dernière, une amélioration », « En baisse de 0,3 point de pourcentage vs le mois dernier, une amélioration ») au lieu de « plus 12 pour cent flèche vers le haut » ; le signe et l’arrondi sont corrects (un vrai signe moins, jamais « −0,0 % », et une variation trop petite pour la précision affiche « <0,1 % » plutôt qu’un zéro trompeur) ; et elle se lit sans JS : le texte rendu côté serveur à l’intérieur est conservé jusqu’à l’exécution du script, l’attribut value seul fixe déjà le ton et la flèche en CSS, et un export pur describe() renvoie le même texte, la même phrase et le même ton pour le rendu côté serveur.
| Catégorie | Affichage de données |
|---|---|
| Type | Web Component (<mv-trend-chip>) |
| Statut | bêta |
| Keywords | exclusive, light, trend, delta, change, kpi, dashboard, percent, badge, intl, ssr, a11y |
When to use
- A KPI card or dashboard tile shows how a figure moved since the previous period
- A report or pricing table lists changes where some metrics are better when they go down, like churn, cost or latency
- A change badge must not rely on color alone and must be read as a sentence by screen readers
- Server-rendered pages should print the change in HTML and keep it readable before or without JavaScript
Avoid when
- The change must be judged against inflation, a benchmark or peers rather than against zero → use Real Terms instead
- A whole section of headline figures with counters and sparklines is needed → use Stats instead
- The number itself should count up or roll when it changes → use Number Ticker instead
Installation
node scripts/add.mjs trend-chip --out ./src/marvelousAgent IA avec le serveur MCP de Marvelous UI : install_components({ slugs: ["trend-chip"], target_dir: "<absolute path>/src/marvelous", framework: "react" }).
Fichiers copiés (dépendances comprises) : tokens/tokens.css, core/base.css, core/element.js, components/trend-chip/trend-chip.js, components/trend-chip/trend-chip.css.
Utilisation
Démarrage rapide, le balisage minimal qui fonctionne :
<mv-trend-chip value="0.124" period="vs last week"></mv-trend-chip>Balisage de référence : partez de celui-ci et personnalisez-le avec les attributs, data-* et les variables CSS :
<div id="mv-tc-demo" style="display:grid;gap:1.25rem;width:min(100%,52rem);margin-inline:auto">
<div style="display:grid;grid-template-columns:repeat(auto-fit,minmax(11.5rem,1fr));gap:.75rem">
<section style="display:grid;gap:.45rem;padding:1rem;border:1px solid var(--mv-border);border-radius:var(--mv-radius-lg);background:var(--mv-surface);box-shadow:var(--mv-shadow-xs)">
<h3 style="margin:0;font-size:.8rem;font-weight:500;color:var(--mv-fg-muted)">Revenue</h3>
<p style="margin:0;font-size:1.5rem;font-weight:600;letter-spacing:-.02em;font-variant-numeric:tabular-nums">$48,210</p>
<mv-trend-chip id="mv-tc-revenue" value="0.124" period="vs last week">+12.4% vs last week</mv-trend-chip>
</section>
<section style="display:grid;gap:.45rem;padding:1rem;border:1px solid var(--mv-border);border-radius:var(--mv-radius-lg);background:var(--mv-surface);box-shadow:var(--mv-shadow-xs)">
<h3 style="margin:0;font-size:.8rem;font-weight:500;color:var(--mv-fg-muted)">Churn rate</h3>
<p style="margin:0;font-size:1.5rem;font-weight:600;letter-spacing:-.02em;font-variant-numeric:tabular-nums">2.1%</p>
<mv-trend-chip from="0.024" to="0.021" format="points" better="down" period="vs last month"></mv-trend-chip>
</section>
<section style="display:grid;gap:.45rem;padding:1rem;border:1px solid var(--mv-border);border-radius:var(--mv-radius-lg);background:var(--mv-surface);box-shadow:var(--mv-shadow-xs)">
<h3 style="margin:0;font-size:.8rem;font-weight:500;color:var(--mv-fg-muted)">p95 latency</h3>
<p style="margin:0;font-size:1.5rem;font-weight:600;letter-spacing:-.02em;font-variant-numeric:tabular-nums">214 ms</p>
<mv-trend-chip from="182" to="214" format="millisecond" better="down" period="vs last week"></mv-trend-chip>
</section>
<section style="display:grid;gap:.45rem;padding:1rem;border:1px solid var(--mv-border);border-radius:var(--mv-radius-lg);background:var(--mv-surface);box-shadow:var(--mv-shadow-xs)">
<h3 style="margin:0;font-size:.8rem;font-weight:500;color:var(--mv-fg-muted)">Active users</h3>
<p style="margin:0;font-size:1.5rem;font-weight:600;letter-spacing:-.02em;font-variant-numeric:tabular-nums">12,480</p>
<mv-trend-chip value="-0.036" period="vs last week"></mv-trend-chip>
</section>
</div>
<div style="display:flex;flex-wrap:wrap;align-items:center;gap:.75rem;font-size:.8125rem;color:var(--mv-fg-muted)">
<button class="mv-button" data-variant="outline" data-size="sm" id="mv-tc-refresh">Load next week</button>
<span>Screen readers hear: <q id="mv-tc-said" style="color:var(--mv-fg)"></q></span>
</div>
<div class="mv-table-wrap">
<table class="mv-table">
<caption>September report. Plain variant; costs and refunds are lower-is-better.</caption>
<thead><tr><th>Metric</th><th data-align="end">September</th><th data-align="end">Change vs August</th></tr></thead>
<tbody>
<tr><td>Support cost</td><td data-align="end">$17,950</td><td data-align="end"><mv-trend-chip data-variant="plain" id="mv-tc-cost" from="18400" to="17950" format="currency" better="down"></mv-trend-chip></td></tr>
<tr><td>Sign-ups</td><td data-align="end">1,204,410</td><td data-align="end"><mv-trend-chip data-variant="plain" from="1204300" to="1204410"></mv-trend-chip></td></tr>
<tr><td>Refund rate (±0.5% counts as flat)</td><td data-align="end">1.9%</td><td data-align="end"><mv-trend-chip data-variant="plain" id="mv-tc-refunds" value="0.003" better="down"></mv-trend-chip></td></tr>
<tr><td>Uptime</td><td data-align="end">99.95%</td><td data-align="end"><mv-trend-chip data-variant="plain" from="0.9995" to="0.9995" format="points"></mv-trend-chip></td></tr>
<tr><td>Headcount</td><td data-align="end">45</td><td data-align="end"><mv-trend-chip data-variant="plain" from="42" to="45" format="number" better="neutral"></mv-trend-chip></td></tr>
</tbody>
</table>
</div>
</div>
<script type="module">
const root = document.getElementById("mv-tc-demo");
const revenue = root.querySelector("#mv-tc-revenue");
const said = root.querySelector("#mv-tc-said");
root.querySelector("#mv-tc-cost").digits = 0;
root.querySelector("#mv-tc-refunds").tolerance = 0.005;
const weeks = ["0.124", "-0.048", "0.0004", "0"];
let i = 0;
const show = () => customElements.whenDefined("mv-trend-chip").then(() => { said.textContent = revenue.state.label; });
root.querySelector("#mv-tc-refresh").addEventListener("click", () => {
i = (i + 1) % weeks.length;
revenue.value = weeks[i];
show();
});
show();
</script>API
Attributes
| Name | Type | Default | Description |
|---|---|---|---|
value | number | The change. For percent and points it is a fraction (0.124 = +12.4%, 0.003 = +0.3 pts); for number, currency and units it is the difference itself. Takes precedence over from / to. | |
from / to | number | Or give the previous and current amounts: percent computes (to − from) / |from| (from = 0 gives no comparison), the other formats use to − from. For points, give rates as fractions (0.024 → 0.021). | |
format | percent | points | number | currency | ISO 4217 code | Intl unit | percent | How the change is printed, always through Intl: “+12.4%”, “−0.3 pts”, “+140”, “−$450.00” (currency = USD, or a code such as EUR), or a unit such as millisecond, kilobyte or hour (“−32 ms”). |
period | string | What the change is measured against, shown after the chip and placed in the sentence: “vs last week”. | |
better | up | down | neutral | up | Which direction is an improvement. down: a fall reads as good (churn, cost, latency). neutral: no judgment, only the direction. |
lang (inherited) | BCP 47 | Number locale from the nearest [lang] ancestor, else en-US. | |
data-variant | plain | Styling hook: colored text and glyph without the pill, for dense tables and inline copy (bad changes get a dotted underline as a second cue). | |
data-dir / data-tone | up | down | flat | none / good | bad | neutral | Set by the component (for styling). A server can write them too, from describe(). |
Properties
| Name | Type | Default | Description |
|---|---|---|---|
tolerance | number | 0 | A change whose size is at or below this (same units as value: 0.005 = half a percent) is about flat: dash glyph, neutral tone, and a sentence that still says which way it moved (“About flat vs last month, up 0.3%”). |
digits | number | 1 for percent and points, the currency's own for money, up to 1 otherwise | Fraction digits. Percent and points always print exactly this many, so every chip on a page rounds the same way. |
strings | object | MvTrendChip.strings | Translatable text, merged over the defaults: whole sentences upGood, upBad, up, downGood, downBad, down, flat, nearUp, nearDown, none with {value} and {period} placeholders, plus under (“<{value}”), underLong (“less than {value}”), points, pointsLong and empty (“-”). |
state | { dir, tone, text, period, label, change } | Read-only: the current result, including the spoken sentence (label) and the raw change. | |
value / from / to / format / period / better | string | Mirror the attributes; changes re-render at once. All can be set before the element is defined. |
Methods
| Name | Description |
|---|---|
describe({ value, from, to, format, period, better, tolerance, digits, locale, strings }) | Named export (and static MvTrendChip.describe): pure and server-safe, returns { dir, tone, text, period, label, change }, the exact visible text and sentence the element renders. |
render() | Re-render now (rarely needed: attribute and property changes already do it). |
Content structure
| Name | Description |
|---|---|
(text) | Server-rendered fallback, read as is before the script loads; replaced by the parts once it runs. Without value or from / to, the text is left untouched. |
.mv-trend-chip-value / -period / -label | Or render the final parts on the server (from describe()): they are adopted in place, so nothing shifts on upgrade. |
CSS classes
| Name | Description |
|---|---|
mv-trend-chip-value | The pill: glyph (::before, a CSS mask) and signed value; aria-hidden. |
mv-trend-chip-period | The muted period text; aria-hidden (it is part of the sentence). |
mv-trend-chip-label | The visually hidden sentence read by screen readers (mv-sr-only). |
CSS variables
| Name | Default | Description |
|---|---|---|
--mv-trend-chip-good | var(--mv-success) | Good tone. |
--mv-trend-chip-bad | var(--mv-danger) | Bad tone. |
--mv-trend-chip-neutral | var(--mv-fg-muted) | Neutral and flat tone. |
--mv-trend-chip-font-size | var(--mv-text-xs) | Text size (the glyph scales with it). |
--mv-trend-chip-radius | var(--mv-radius-full) | Pill corner radius. |
--mv-trend-chip-gap | 0.4em | Space between the pill and the period. |
Accessibility
Plain inline content, no role and no tab stop. The visible pill and period are aria-hidden and a visually hidden span carries one complete sentence built from a whole-sentence template (never glued fragments): “Up 12.4% vs last week, an improvement”, “Down 32 ms vs last week, an improvement” with better="down", “Up 3” with better="neutral", “Unchanged vs yesterday”, “About flat vs last month, up 0.3%” inside the tolerance, “Up less than 0.1% vs yesterday, an improvement” for tiny changes, and “No comparison available” when the change cannot be computed. The number in the sentence is unsigned (the word carries the direction), so nothing reads “plus” or “minus” or “up arrow”. Updates are silent (no live region): a dashboard refreshing its tiles never interrupts the reader, and the text is only written when it actually changes. Meaning never depends on color alone (WCAG 1.4.1): direction is the glyph's orientation, good is a filled triangle, bad is a hollow triangle in an outlined chip (plus a dotted underline in the plain variant), neutral is a thin arrow and flat is a dash. Text colors are mixed toward the foreground for contrast on the tinted pill, in light and dark themes. Forced colors: the glyph is drawn in CanvasText, the chip gets a border, dashed when the change is bad. The glyph's turn when the direction flips uses the motion tokens and is removed under prefers-reduced-motion and [data-motion="reduce"]. Before or without JS, server-rendered text inside the element is read as written, and CSS already derives tone and direction from the value attribute.