@squadbase/vantage 0.6.2-dev1.b332e5a → 0.6.2-dev1.d7c0911

package/docs/en/parts/format.md

@@ -0,0 +1,43 @@
+# format / comparison
+
+> The number formatting (formatValue) and change calculation (computeComparison) shared by KPIs, tables and charts.
+
+The formatting and comparison logic that `KpiCard` / `Delta` use internally, exposed as functions. Use
+them when a table cell or a chart's `valueFormatter` should match the KPIs. Shortening (e.g. "4.8億")
+is left to `Intl.NumberFormat`; no unit strings are hard-coded.
+
+```tsx
+import {
+  formatValue,
+  formatDelta,
+  toValueFormatter,
+  computeComparison,
+} from "@squadbase/vantage/components";
+import type { ValueFormat, Comparison, ComparisonResult } from "@squadbase/vantage/components";
+```
+
+## ValueFormat
+
+One of `"number" | "compact" | "currency" | "percent" | "multiple"`, or `{ type, digits?, currency? }`.
+The default format is `"compact"`, the default currency `JPY`, the default locale `"ja-JP"`. `percent`
+takes a ratio (`0.124` → 12.4%). `null` / `undefined` / `NaN` format as "—".
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `formatValue(value, format?, locale?)` | `string` | Format a value. |
+| `formatDelta(value, format?, locale?)` | `string` | For differences: always signed except zero (`+12.4%`). |
+| `toValueFormatter(format?, locale?)` | `(value) => string` | A one-argument formatter with the format and locale bound — fits a chart's `valueFormatter`. |
+
+```tsx
+formatValue(48_200_000, "currency");                // "￥48,200,000"
+formatValue(0.021, { type: "percent", digits: 1 }); // "2.1%"
+<LineChart valueFormatter={toValueFormatter("compact")} … />
+```
+
+## computeComparison
+
+`computeComparison(current, comparison, { polarity?, neutralBand? })` returns
+`{ current, previous, difference, ratio, direction, sentiment, label, vs }`. A rate is produced only
+when the previous value is a non-zero number; moves inside `neutralBand` (default 0.01) give
+`direction: "flat"`. `sentiment` (`"positive" | "negative" | "neutral"`) follows `polarity`. Leave the
+rendering to [`Delta`](parts/delta) rather than building arrows and colours yourself.

package/docs/en/parts/kpi-card.md

@@ -0,0 +1,57 @@
+# KpiCard
+
+> One KPI as a card — value, change, previous actual and a one-line conclusion, all derived from numbers.
+
+A card that shows one KPI. **Pass numbers and enums only**, and it lays out, top to bottom: the metric
+name → the value → the change ([`Delta`](parts/delta)) → the previous actual → a
+one-sentence conclusion. Direction, rate, colour, remaining-to-target, achievement and record highs are
+all computed inside the card, so no two props can disagree. Reach for this before composing a KPI tile
+from `DashboardCardPreset` + `MetricValue`.
+
+```tsx
+import { KpiCard } from "@squadbase/vantage/components";
+import type { KpiCardProps, KpiCardSource, Comparison, Polarity, ValueFormat } from "@squadbase/vantage/components";
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `label` | `string` |  | The metric name. **Required.** |
+| `value` | `number \| null \| undefined` |  | The current value. **Required.** `null` / `undefined` renders "—". |
+| `format` | `ValueFormat` | `"compact"` | How the value is formatted (see the format / comparison page); also used for previous, target and remaining. |
+| `locale` | `string` | `"ja-JP"` | The formatting locale. |
+| `comparison` | `Comparison` |  | What the value is compared against (`{ previous, vs, label? }`). Adds the change and the previous-actual line. |
+| `polarity` | `"higher-is-better" \| "lower-is-better"` | `"higher-is-better"` | Whether a rise is good. Use `"lower-is-better"` for metrics like churn. |
+| `neutralBand` | `number` | `0.01` | Absolute ratio below which the change reads as flat. |
+| `showPrevious` | `boolean` | `true` | Show the previous actual ("前期 400"). Needs `comparison`. |
+| `summary` | `string` |  | The conclusion sentence, as a **template** whose placeholders (below) the card fills. |
+| `target` | `number` |  | Target for the current period; adds a remaining / achievement line. |
+| `period` | `{ start: Date \| string \| number; end: Date \| string \| number }` |  | The current period. With `target`, adds a pace projection (marked 見込み) while the period is in progress. |
+| `history` | `ReadonlyArray<number \| null \| undefined>` |  | Series ending at the current period (last point = `value`); adds a record badge. |
+| `historyGrain` | `"day" \| "week" \| "month" \| "quarter" \| "year"` | `"month"` | The grain of `history`. |
+| `source` | `{ period?: string; count?: number; name?: string }` |  | A data-source footnote (period, row count, source name). |
+| `updatedAt` | `Date \| string \| number` |  | When the data was last refreshed; shown as relative time. |
+| `now` | `Date \| number` |  | Reference time for the projection and relative time (for deterministic rendering). |
+| `isLoading` | `boolean` | `false` | Render a skeleton with the final shape instead of the values. |
+| `className` | `string` |  | Classes to add. |
+
+## Summary placeholders
+
+`{value}` `{delta}` `{difference}` `{previous}` `{label}` `{target}` `{achievement}` `{remaining}`.
+Unknown placeholders are left as written; a known one whose value is missing becomes "—".
+
+> [!WARNING]
+> **Never put numbers in the template itself.** Insert every number through a placeholder, so the
+> sentence can't go stale when the value changes.
+
+```tsx
+<KpiCard
+  label="Revenue"
+  value={48_200_000}
+  format="currency"
+  comparison={{ previous: 42_900_000, vs: "prior-period" }}
+  summary="{label} grew {difference} ({delta}) on last month."
+/>
+```
+
+The card's built-in wording (labels such as 前期比 and 目標まであと) is Japanese. To place just the
+change inside a table or tile, use [`Delta`](parts/delta) on its own.

package/docs/en/parts/metric-value.md

@@ -2,7 +2,8 @@
 
 > The KPI number, with MetricUnit for the unit.
 
-A tight-tracking display for a KPI's number. Units and other trailing text go in `MetricUnit`.
+A tight-tracking display for a KPI's number. Units and other trailing text go in `MetricUnit`. For a whole KPI
+tile, consider [`KpiCard`](parts/kpi-card) first — it also shows the change and the previous actual.
 
 ```tsx
 import { MetricValue, MetricUnit, metricValueVariants } from "@squadbase/vantage/components";
@@ -18,6 +19,6 @@ It carries vertical margin (`my-4`) by default. Inside a card, pass `className="
 ```tsx
 <DashboardCardPreset title="Revenue">
   <MetricValue className="my-0">$12,400</MetricValue>
-  <TrendIndicator value={12.4} direction="up" />
+  <Delta value={12_400} comparison={{ previous: 11_030, vs: "prior-period" }} />
 </DashboardCardPreset>
 ```

package/docs/en/parts/sparkline.md

@@ -44,4 +44,4 @@ series. `Sparkline` conveys the *shape* of a series and nothing else — **no ti
 > [!NOTE]
 > It is `aria-hidden="true"`, so screen readers skip it. Put the actual number next to it as text —
 > [`MetricValue`](parts/metric-value) or
-> [`TrendIndicator`](parts/trend-indicator).
+> [`Delta`](parts/delta).

package/docs/en/parts/trend-indicator.md

@@ -1,6 +1,22 @@
 # TrendIndicator
 
-> An arrow and a percentage; positiveIsGood decides the colour.
+> Deprecated — use Delta for new code. An arrow and a percentage.
+
+> [!WARNING]
+> **Deprecated. Use [`Delta`](parts/delta) in new code.** `TrendIndicator` takes the
+> direction and colour by hand, so the value and the arrow can disagree. `Delta` computes direction,
+> rate, colour and label from the current and compared values. To show a KPI as a card, use
+> [`KpiCard`](parts/kpi-card).
+
+```tsx
+// Before
+<TrendIndicator value={12.4} direction="up" />
+<TrendIndicator value={0.4} direction="down" positiveIsGood={false} />
+
+// After
+<Delta value={1_240_000} comparison={{ previous: 1_103_000, vs: "prior-period" }} />
+<Delta value={0.021} comparison={{ previous: 0.026, vs: "prior-period" }} polarity="lower-is-better" />
+```
 
 Shows a change as an arrow plus a percentage. **Up doesn't always mean good**, so the colour comes
 from `direction` combined with `positiveIsGood` — pass `positiveIsGood={false}` for metrics like

package/docs/en/ui-and-theming.md

@@ -36,7 +36,7 @@ In `/ui` (a selection): `Button`, `Card`, the `Table` primitives, `Tabs`, `Input
 `DropdownMenu`, `Sidebar`, `Alert` / `Skeleton` / `Spinner`, `Loading` / `Empty` / `ErrorState`.
 
 In `/components` (a selection): `PageShell`, `AppShell`, `DashboardCard`, `DataTable`, `EChart`,
-`FunnelSteps`, `FilterBar`, `DateRangePicker`, `MetricValue`, `TrendIndicator`.
+`FunnelSteps`, `FilterBar`, `DateRangePicker`, `KpiCard`, `Delta`.
 
 Props and usage for every component live in the [Components](components) tab.