Exclusivobeta
Real Terms <mv-real-terms>
Muestra un cambio frente a lo que hizo el mundo en el mismo periodo, no solo frente a cero, para que un crecimiento que apenas sigue el ritmo (o se queda atrás) nunca se confunda con progreso: ingresos, salarios, precios, tráfico, cuota de mercado, rentabilidad de inversiones. Dale el cambio nominal (un porcentaje, o importes inicial y final) y una o varias referencias que aporta la app, cada una tipada como inflación, benchmark o índice, pares o cohorte, estacional (mismo periodo del año anterior) o tendencia objetivo; muestra el cambio nominal, el cambio de la referencia y el resultado relativo (puntos porcentuales, o una ratio compuesta: cambio real descontada la inflación por defecto) con un veredicto en palabras e iconos: ganando terreno, al mismo ritmo o perdiendo terreno, y nombra explícitamente los casos contraintuitivos (“Pierdes terreno pese a crecer”, “Ganas terreno pese a caer”, “Pierdes terreno por quedarte quieto”) en una frase completa (“Baja un 3,2 %, pero el índice cayó un 8,9 %: ganaste terreno (+5,7 pts)”). Con importes, también dice lo que suponía seguir el ritmo en dinero (“Seguir el ritmo de los precios suponía llegar a 88.494 $: faltan 1294 $”) y, descontada la inflación, cuánto vale el importe final a precios del inicio del periodo. Un conmutador Nominal / Real (o Relativo) cambia la cifra principal; un visual compacto dibuja ambos cambios sobre una misma línea de cero (dos barras con la diferencia rayada, o un gráfico de pendiente desde un inicio común) con un equivalente en texto; varias referencias aparecen como un cuadro de resultados navegable con el teclado donde cada opción ya muestra su propio veredicto. La cifra nominal nunca se colorea como buena o mala: solo el veredicto. Las métricas en las que menos es mejor (costos, churn, tiempo de respuesta) invierten el veredicto, una tolerancia define “seguir el ritmo”, los números pasan por Intl, y el método estático puro MvRealTerms.compare(nominal, baseline, options) devuelve el mismo cálculo para tablas, exportaciones o código de servidor. Una variante inline cabe en celdas de tabla y filas de KPI.
| Categoría | Visualización de datos |
|---|---|
| Tipo | Web Component (<mv-real-terms>) |
| Estado | beta |
| Kit | Cifras que se explican solas |
| Keywords | exclusive, culture, kpi, benchmark, inflation, real-terms, nominal, relative-performance, market-share, peers, cohort, seasonality, year-over-year, salary, investment, returns, delta, verdict, dashboard, finance |
When to use
- A KPI grew and people need to know whether it beat the market, peers or last year's same period, not just zero
- Salaries, prices, budgets or savings must be read in real terms, after inflation, rather than as nominal amounts
- An investment or fund report must show performance against its benchmark, including when both fell
- A review table should flag metrics that grow but lose ground, or shrink yet gain ground
Avoid when
- A row of headline figures with sparklines is needed, without any external baseline → use Stats instead
- The question is whether a goal will be met by a deadline at the current pace → use Steady Pace instead
- The comparison is a rank among named competitors with the factors behind it → use Mirror Rank instead
Instalación
node scripts/add.mjs real-terms --out ./src/marvelousAgente de IA con el servidor MCP de Marvelous UI: install_components({ slugs: ["real-terms"], target_dir: "<absolute path>/src/marvelous", framework: "react" }).
Archivos copiados (dependencias incluidas): tokens/tokens.css, core/base.css, core/dom.js, core/element.js, core/focus.js, core/motion.js, core/observe.js, components/real-terms/real-terms.js, components/real-terms/real-terms.css.
Uso
Inicio rápido, el marcado mínimo que funciona:
<mv-real-terms label="Base salary" start="86000" end="87200" format="currency">
<script type="application/json" data-baselines>[{ "id": "cpi", "label": "Inflation (CPI)", "kind": "inflation", "change": "2.9%" }]</script>
</mv-real-terms>Marcado de referencia: parte de él y personalízalo con atributos, data-* y variables CSS:
<div id="rt-demo" style="width:min(100%,56rem);margin-inline:auto">
<style>
#rt-demo { display:grid; gap:1rem; align-content:start }
#rt-demo .rt-pair { display:grid; grid-template-columns:repeat(auto-fit,minmax(min(100%,22rem),1fr)); gap:1rem }
#rt-demo .rt-controls { display:flex; align-items:center; justify-content:space-between; gap:.5rem 1.25rem; flex-wrap:wrap; margin-top:-.25rem; padding:0 .25rem }
#rt-demo .rt-controls span { display:flex; gap:1.25rem; flex-wrap:wrap }
#rt-demo .mv-choice { font-size:.8125rem }
#rt-demo .rt-log { margin:0; color:var(--mv-fg-subtle); font:.75rem/1.4 var(--mv-font-mono) }
#rt-demo .rt-table { overflow:hidden; border:1px solid var(--mv-border); border-radius:var(--mv-radius-xl); background:var(--mv-surface); box-shadow:var(--mv-shadow-xs) }
#rt-demo .rt-table h4 { margin:0; padding:.875rem 1.25rem; border-bottom:1px solid var(--mv-border); font-size:.875rem }
#rt-demo table { width:100%; border-collapse:collapse; font-size:.8125rem }
#rt-demo th, #rt-demo td { padding:.625rem 1.25rem; text-align:start; vertical-align:middle }
#rt-demo thead th { color:var(--mv-fg-muted); font-size:.75rem; font-weight:500; background:var(--mv-bg-subtle) }
#rt-demo tbody tr + tr td, #rt-demo tbody tr + tr th { border-top:1px solid var(--mv-border) }
#rt-demo tbody th { font-weight:500; white-space:nowrap }
#rt-demo tbody th small { display:block; color:var(--mv-fg-muted); font-weight:400 }
@media (max-width:40rem) { #rt-demo thead { display:none } #rt-demo tbody tr { display:grid } #rt-demo tbody td { padding-top:0 } }
</style>
<!-- Revenue grew, but the category grew faster: several baselines to compare with -->
<mv-real-terms id="rt-arr" label="Annual recurring revenue" period="FY 2026 · Oct 2025 to Sep 2026"
start="4200000" end="4540000" format="currency" compact baseline="category" subject="Northwind">
<script type="application/json" data-baselines>
[
{ "id": "category", "label": "Category growth", "name": "the category", "kind": "benchmark", "change": "10.4%",
"note": "Mid-market HR software, analyst consensus.", "source": "Industry revenue survey, Sep 2026" },
{ "id": "peers", "label": "Peer median", "name": "peers", "kind": "peers", "change": "6.2%",
"note": "Median of 14 private SaaS companies with $3M-$8M ARR." },
{ "id": "cpi", "label": "Inflation (CPI)", "kind": "inflation", "change": "2.9%",
"note": "US consumer prices, Sep 2025 to Sep 2026.", "source": "Bureau of Labor Statistics", "sourceUrl": "https://www.bls.gov/cpi/" },
{ "id": "plan", "label": "Board plan", "name": "the plan", "kind": "target", "change": "12%",
"note": "Growth approved in the FY 2026 budget." }
]
</script>
</mv-real-terms>
<div class="rt-controls">
<span>
<label class="mv-choice"><input type="checkbox" class="mv-switch" data-size="sm" id="rt-slope"> Slope chart</label>
<label class="mv-choice"><input type="checkbox" class="mv-switch" data-size="sm" id="rt-lock"> Lock the baseline (veto changes)</label>
</span>
<p class="rt-log" id="rt-log" aria-live="polite">Pick a baseline or switch to Relative.</p>
</div>
<div class="rt-pair">
<!-- A raise that is a pay cut in real terms: shown in the real view -->
<mv-real-terms label="Your base salary" period="Oct 2025 → Oct 2026" start="86000" end="87200"
format="currency" view="real" baseline="cpi">
<script type="application/json" data-baselines>
[
{ "id": "cpi", "label": "Inflation (CPI)", "kind": "inflation", "change": "2.9%", "note": "US consumer prices over the same 12 months." },
{ "id": "role", "label": "Same role, median raise", "name": "the median raise", "kind": "peers", "change": "3.6%", "note": "Senior product designers, US, 2,300 salary reports." }
]
</script>
</mv-real-terms>
<!-- The counterintuitive case: down, yet ahead -->
<mv-real-terms label="Retirement portfolio" period="Q3 2026" start="312400" end="302400"
format="currency" visual="slope" baseline="index" subject="Portfolio">
<script type="application/json" data-baselines>
[
{ "id": "index", "label": "Global equity index", "name": "the index", "kind": "benchmark", "change": "-8.9%", "note": "Total return, dividends reinvested." },
{ "id": "balanced", "label": "60/40 benchmark", "name": "a 60/40 mix", "kind": "benchmark", "change": "-5.1%" }
]
</script>
</mv-real-terms>
</div>
<!-- Inline, in a KPI table: every row judged against its own baseline -->
<section class="rt-table" aria-labelledby="rt-table-title">
<h4 id="rt-table-title">Monthly review · December 2026</h4>
<table>
<thead><tr><th scope="col">Metric</th><th scope="col">Change, in context</th></tr></thead>
<tbody>
<tr>
<th scope="row">Organic sessions<small>Dec vs Nov</small></th>
<td><mv-real-terms variant="inline" change="40%" id="rt-traffic"></mv-real-terms></td>
</tr>
<tr>
<th scope="row">Paid subscribers<small>Year over year</small></th>
<td><mv-real-terms variant="inline" change="0%" id="rt-subs"></mv-real-terms></td>
</tr>
<tr>
<th scope="row">Support cost per ticket<small>Year over year · lower is better</small></th>
<td><mv-real-terms variant="inline" change="2.6%" direction="lower" id="rt-support"></mv-real-terms></td>
</tr>
<tr>
<th scope="row">Hosting cost per user<small>Year over year · lower is better</small></th>
<td><mv-real-terms variant="inline" change="1%" direction="lower" id="rt-hosting"></mv-real-terms></td>
</tr>
</tbody>
</table>
</section>
<script type="module">
const arr = document.getElementById("rt-arr");
const log = document.getElementById("rt-log");
const lock = document.getElementById("rt-lock");
const pct = (x) => `${x > 0 ? "+" : ""}${(x * 100).toFixed(1)}`;
arr.addEventListener("mv-baseline-change", (e) => {
if (lock.checked) {
e.preventDefault();
log.textContent = `Vetoed: the baseline is locked to ${e.detail.from}.`;
return;
}
const r = e.detail.result;
log.textContent = `mv-baseline-change → ${e.detail.to} · ${r.verdict} (${pct(r.relative)}${r.method === "points" ? " pts" : "%"})`;
});
arr.addEventListener("mv-view-change", (e) => { log.textContent = `mv-view-change → ${e.detail.to}`; });
document.getElementById("rt-slope").addEventListener("change", (e) => { arr.visual = e.target.checked ? "slope" : "bars"; });
// Baselines can also be set as a property.
const cpi = { id: "cpi", label: "inflation", kind: "inflation", change: 0.029 };
document.getElementById("rt-traffic").baselines = [{ id: "ly", label: "same period last year", kind: "seasonal", change: 0.45 }];
document.getElementById("rt-subs").baselines = [{ id: "peers", label: "peer median", kind: "peers", change: 0.041 }];
document.getElementById("rt-support").baselines = [cpi];
document.getElementById("rt-hosting").baselines = [cpi];
</script>
</div>Referencia cultural
A través del espejo, Lewis Carroll (1871, libro). En la carrera de la Reina Roja, Alicia corre tan rápido como puede solo para descubrir que sigue en el mismo sitio, porque todo el paisaje se mueve con ella. En la interfaz, cada cambio se mide frente a lo que hizo el mundo en el mismo periodo, así que un crecimiento que solo sigue el ritmo se lee como “al mismo ritmo”, y uno más lento que el mercado, como “pierdes terreno pese a crecer”.
API
Attributes
| Name | Tipo | Default | Description |
|---|---|---|---|
label | string | Metric name shown at the top of the card (as a heading, see heading-level). | |
period | string | The period both changes cover, shown next to the label (“FY 2026”, “Oct 2025 → Oct 2026”). Baselines must describe the same period. | |
start / end | number | Amounts at the start and end of the period. The nominal change is derived from them, and they enable the pace line (what keeping pace meant) and, for inflation, the value at start-of-period prices. | |
change | string | number | Nominal change when you have no amounts: a fraction (0.08) or a percentage string ("8%", "-3.2%"). Takes precedence over start/end for the change itself. | |
baseline | string | Id of the selected baseline (defaults to the first). Reflects the user's choice; setting it is silent (no event). | |
view | nominal | real | nominal | Headline figure: the nominal change, or the result against the selected baseline (real change after inflation, relative change otherwise). The toggle reads “Real” for an inflation baseline and “Relative” for any other. |
direction | higher | lower | higher | Whether a higher value is better. With lower (costs, churn, latency), rising less than the baseline is gaining ground. |
tolerance | string | number | 0.5% | Band within which the result counts as keeping pace: a fraction (0.005) or "0.5%" / "0.5 pts". A result that rounds to zero at the shown precision is always keeping pace. |
method | auto | points | ratio | auto | How the relative result is computed, unless a baseline sets its own: points = nominal − baseline in percentage points; ratio = (1 + nominal) / (1 + baseline) − 1, the compounded real change. auto uses ratio for inflation and points otherwise. |
format | number | currency | percent | number | Intl format of the amounts (start, end, pace). Changes are always percentages. |
currency | string | USD | ISO currency for format="currency". |
compact | boolean | Compact notation for the amounts ($4.54M). | |
unit | string | Suffix for plain number amounts (“sessions”, “seats”). | |
locale | string | en-US | Locale for every number. |
decimals | number | 1 | Fraction digits of percentages and points (0-4). |
variant | card | inline | card | card: full component with toggle, visual and baseline scorecard. inline: one line for tables and KPI rows (nominal change · baseline change · verdict with the difference), the full sentence as a tooltip. |
visual | bars | slope | none | bars | bars: both changes on one zero line, the difference hatched in the verdict color and a dashed mark at the baseline. slope: both lines from a common start (index 100), the gap bracketed at the end. none: text only. |
subject | string | You | Name of the measured thing in the visual (“Northwind”, “Portfolio”). |
heading-level | number | 3 | Heading level of the label (1-6); 0 renders it as a paragraph. |
data-verdict / data-despite / data-view | ahead | even | behind | none | Set by the component on the host for styling: the verdict for the selected baseline, whether it is a counterintuitive case, and the current view. |
Properties
| Name | Tipo | Description |
|---|---|---|
baselines | Array<{ id, label, name?, kind?: "inflation" | "benchmark" | "peers" | "seasonal" | "target" | "custom", change | start+end, method?, note?, source?, sourceUrl? }> | Baselines for the same period (or a child <script type="application/json" data-baselines>). label is shown in the scorecard and visual; name is used inside sentences (“the category grew 10.4%”; defaults: prices, peers, the same period last year, the target trend, else label). note and source (optional http(s) link) show under the card for the selected one. |
nominal | number | Nominal change as a fraction (read-only). |
selected | object | null | The selected baseline (copy, read-only). |
result | object | null | compare() result for the selected baseline (read-only). |
results | Array<object> | compare() results for every baseline, each with id and label (read-only). |
formatter | (value: number) => string | Custom formatter for the amounts; overrides format, currency, unit and compact. |
strings | Partial<Record<string, string>> | Overrides for every visible text and announcement: verdict titles (ahead, aheadDespiteDown, aheadDespiteUp, aheadDespiteFlat, behind, behindDespiteUp, behindDespiteDown, behindDespiteFlat, even), sentence parts (subjectUp, subjectDown, subjectFlat, baseUp, baseDown, baseFlat, inflationUp, inflationDown, inflationFlat, targetAny, targetFlat, sentenceDespite, sentenceWhile, sentenceEven, outcomeAhead, outcomeBehind, outcomeEven), units (points, relReal, relRatio), pace lines (paceAbove, paceBelow, paceEven, realAmount), labels (subject, compareWith, showAs, viewNominal, viewReal, viewRelative, captionNominal, captionReal, captionRelative, amounts, gap, source, slopeStart, inlineBase, visualLabel, noBaseline, noData, announce). English defaults with {placeholders}. |
Methods
| Name | Description |
|---|---|
MvRealTerms.compare(nominal, baseline, options?) | Pure static function, no DOM. nominal / baseline: fraction, "8%", { change } or { start, end } (baseline may also carry kind and method). options: { kind, method, direction, tolerance, decimals, start }. Returns null for unreadable input, else { nominal, baseline, kind, method, direction, relative, points, ratio, verdict: "ahead" | "even" | "behind", despite, nominalDirection, baselineDirection, relativeDirection ("up" | "down" | "flat") } plus, with start, { start, end, pace, gapValue, realEnd }. |
select(id) | Selects a baseline as the user would: emits the cancelable mv-baseline-change. Returns false if vetoed or unknown. |
setView(view) / toggleView() | Switches between "nominal" and "real" as the user would: emits the cancelable mv-view-change. Returns false if vetoed. |
Events
| Name | Description |
|---|---|
mv-baseline-change | Cancelable, before the user (or select()) changes the baseline. detail: { from, to, baseline, result } with the compare() result for the new baseline. preventDefault() keeps the current one (focus returns to it). |
mv-view-change | Cancelable, before switching the headline between nominal and real. detail: { from, to }. |
Content structure
| Name | Description |
|---|---|
script[data-baselines] | A child <script type="application/json" data-baselines> with the baselines array, read once on first connection (the baselines property wins if set before). |
CSS classes
| Name | Description |
|---|---|
mv-real-terms-root | The card (a container-query box; the figure and visual sit side by side from 36rem): -head, -titles, -label, -period, -views / -view (toggle), -body, -main, -foot, -empty. |
mv-real-terms-figure | Headline: -number (-arrow + -value), -sub (-caption, -amounts). |
mv-real-terms-story | -verdict (pill with -verdict-icon and -verdict-text), -sentence, -pace. |
mv-real-terms-visual | role="img" with a text label. Bars: -bars, -rails (-zero, -mark), -row (-row-you, -row-base, -row-gap) with -bar-name, -track, -bar, -bar-value. Slope: -slope, -plot, -slope-svg (-slope-you, -slope-base, -slope-gap, -slope-zero), -dot, -slope-start, -ends (-end, -end-you, -end-gap, -end-base with -end-name and -end-value). |
mv-real-terms-picker | Baseline scorecard: -options (radiogroup) of -option buttons (-option-label, -option-change, -option-rel), each with data-verdict. |
mv-real-terms-inline | Inline variant: -inline-nominal, -inline-base, -sep, -verdict. |
CSS variables
| Name | Default | Description |
|---|---|---|
--mv-real-terms-you | var(--mv-accent) | Color of the measured thing (bar, slope line). |
--mv-real-terms-baseline | muted gray | Color of the baseline bar and dashed slope line. |
--mv-real-terms-ahead | var(--mv-success) | Verdict color when gaining ground. |
--mv-real-terms-behind | var(--mv-danger) | Verdict color when losing ground. |
--mv-real-terms-even | var(--mv-info) | Verdict color when keeping pace. |
--mv-real-terms-padding | var(--mv-space-5) | Card inner padding. |
--mv-real-terms-bar-height | 0.75rem | Bar thickness. |
--mv-real-terms-slope-height | 8.5rem | Height of the slope chart. |
Accessibility
The verdict is always stated in words and never by color alone: a pill with a distinct icon per verdict (rising trend, falling trend, equals) and a text title, followed by a full sentence that names both changes and the difference with its sign and unit (“Up 8.1%, but the category grew 10.4%: you lost ground (−2.3 pts)”). The nominal arrow shows the direction of the number only and stays neutral, so a green “up” can never be read as “good” when the business lost ground. The visual is a role="img" element whose label gives the same numbers as text (“Northwind +8.1%; Category growth +10.4%; difference −2.3 pts.”), and its value labels are real text; the baseline in the slope chart is dashed, so the two lines differ by pattern too. The Nominal / Real toggle is a labelled group of two buttons with aria-pressed. Baselines form a radiogroup (“Compare with”) with a roving tabindex: Tab enters on the selected option, arrow keys, Home and End move and select, and each option's accessible name carries its baseline change and verdict (“Peer median: peers grew 6.2%. Gaining ground (+1.9 pts)”). A vetoed change keeps focus on the still-selected option. Changing the baseline or the view announces the new verdict and sentence once in a polite live region. Numbers use Intl for the locale and a true minus sign, which screen readers read as “minus”. The inline variant keeps its visible text self-explanatory and adds the full sentence as a title. Forced-colors mode draws the bars and lines with system colors and marks the pressed toggle and selected option with an outline. Reduced motion (OS or data-motion="reduce"): bars, lines and marks appear in place without growing or sliding.