@aparte/plugin-cards 0.0.0-stage → 0.29.0

package/dist/stats/index.d.ts

@@ -0,0 +1,137 @@
+/**
+ * @aparte/plugin-cards/stats — a tool's key figures, drawn as a card.
+ *
+ *   import { setupStatsCard } from '@aparte/plugin-cards/stats';
+ *
+ *   setupStatsCard({
+ *     tool: 'get_sales_summary',
+ *     map: (result) => ({ title: 'Sales this week', items: result.kpis }),
+ *   });
+ *
+ * Three variants of one card: `tiles` (a grid of KPI tiles — label, big number, the change
+ * as a pill, a sparkline under it), `list` (a fact sheet: one row per figure, the value
+ * at the end, for five to twelve facts) and `hero` (the first figure large over a wide
+ * chart, the others as a row of small ones beneath).
+ *
+ * Your tool keeps its own fields: `readStats` reads a list of figures, one figure, a
+ * `{ title, items }` envelope, or a plain record — `{ Revenue: 12000, Orders: 340 }` — as
+ * label → value pairs; and the usual spellings of each field (`name` for `label`, `amount`
+ * or `count` for `value`, `delta` for `change`, `history` for `trend`). `map` covers the rest.
+ * A record's `currency` and `unit` are how its figures are written, never figures: the
+ * currency goes to the keys that name money (`revenue`, `avgOrderValue`, `mrr` — not
+ * `orders`, nor `refundRate`), the unit to the others, and a figure's own always wins.
+ *
+ * **How a change is read.** A change is a percentage unless `changeFormat: 'absolute'`
+ * says it is in the figure's own unit. A percentage given as a number follows one rule:
+ * at most 1 in size it is a ratio (`0.12` → +12 %), above that it is already in percent
+ * (`12` → +12 %). So `1` is +100 %; write `"1%"` — a string with its sign is never
+ * ambiguous — or use `changePercent`, which is always in percent, for one per cent.
+ * A `percent` figure's value follows the same rule.
+ */
+import type { AparteConfig } from '@aparte/core';
+import { type CardSetupOptions } from '../kit/define.js';
+import { STAT_ICONS } from './icons.js';
+export type StatsVariant = 'tiles' | 'list' | 'hero';
+/** How a figure's value is written. */
+export type StatFormat = 'number' | 'percent' | 'currency' | 'compact' | 'duration' | 'text';
+/** The glyphs a figure may wear beside its label. */
+export type StatIcon = keyof typeof STAT_ICONS;
+/**
+ * One figure as `map` returns it. Only `label` and `value` are needed; every other field
+ * adds a line when it is there and nothing when it is not.
+ */
+export interface StatInput {
+    label: string;
+    /** A number, or a short text (`"Gold"`, `"4.8/5"`). `"12%"` is read as a percentage. */
+    value: number | string;
+    /**
+     * `number` (the default), `percent` (see the rule above), `currency` (with `currency`),
+     * `compact` (`12K`, `1.2M`), `duration` (seconds → `1 hr 20 min`) or `text`.
+     */
+    format?: StatFormat;
+    /** An ISO 4217 code (`EUR`) or a usual symbol (`€`); alone, it makes the figure a sum. */
+    currency?: string;
+    /** An `Intl` unit (`kilometer`, `megabyte`, `kilometer-per-hour`), or any text, appended. */
+    unit?: string;
+    /** Decimals shown, 0–6. */
+    digits?: number;
+    /** The change: a percentage (the rule above) or, with `changeFormat: 'absolute'`, in the figure's unit. */
+    change?: number | string;
+    changeFormat?: 'percent' | 'absolute';
+    /** What the change compares with: "vs last week". */
+    changeLabel?: string;
+    /** Which way is good — it colours the change green or red, and says which to a screen reader. Without it the change is neutral. */
+    good?: 'up' | 'down';
+    /** Past values, oldest first, for the sparkline. */
+    trend?: number[];
+    /** One short line under the figure. */
+    hint?: string;
+    icon?: StatIcon;
+}
+/** What `map` returns: figures with a heading, a list of them, one figure, or a record of label → value. */
+export type StatsInput = {
+    title?: string;
+    subtitle?: string;
+    items: StatInput[];
+    footnote?: string;
+    updatedAt?: string | number | Date;
+} | StatInput[] | StatInput | Record<string, number | string>;
+/** One figure as the card draws it, once read. */
+export interface Stat {
+    label: string;
+    /** A number in the scale it is drawn in (a `percent` figure's is a ratio), or — for `text` — a text drawn as given. */
+    value: number | string;
+    /** `text` exactly when `value` is a string; never `currency` without a currency. */
+    format: StatFormat;
+    /** An ISO 4217 code. */
+    currency?: string;
+    unit?: string;
+    digits?: number;
+    /** A ratio for a `percent` change; in the value's own scale for an `absolute` one. */
+    change?: number;
+    changeFormat: 'percent' | 'absolute';
+    changeLabel?: string;
+    good?: 'up' | 'down';
+    /** Two points at least, finite. */
+    trend?: number[];
+    hint?: string;
+    icon?: StatIcon;
+}
+/** The data as the card draws it. */
+export interface StatsData {
+    title?: string;
+    subtitle?: string;
+    items: Stat[];
+    footnote?: string;
+    updatedAt?: Date;
+}
+/**
+ * `key` as a label when a record gave it: `conversionRate` → "Conversion rate",
+ * `avg_order_value` → "Avg order value". A key already written for people — with a space,
+ * or a single word in capitals like `MRR` — is kept as it is.
+ */
+export declare function humanizeKey(key: string): string;
+/**
+ * The card's data from the loose shape `map` returns — a `{ title, items }` envelope (also
+ * `stats`, `metrics`, `kpis`, `figures`), a list of figures, one figure, or a record of
+ * label → value pairs (`{ Revenue: 12000 }`, or `{ Revenue: { value: 12000, change: 0.1 } }`)
+ * — or `null` when not one figure has a label and a value. At most twelve are kept.
+ */
+export declare function readStats(raw: unknown): StatsData | null;
+/** The figure's value as drawn: its number in its format, or its text. */
+export declare function statValue(config: AparteConfig, stat: Stat): string;
+/** The change as drawn, signed: `+12%`, `−3.5%`, or `+€1,200` for an absolute one. */
+export declare function statChange(config: AparteConfig, stat: Stat): string | undefined;
+export declare const statsCard: {
+    name: string;
+    variants: readonly StatsVariant[];
+    setup: (options?: CardSetupOptions<StatsData, StatsVariant>) => () => void;
+    segment: (raw: unknown, options?: {
+        id?: string;
+        variant?: StatsVariant | undefined;
+        config?: AparteConfig;
+    }) => import("../index.js").AparteCardSegment;
+};
+/** Draw a tool's key figures as this card — returns the function that stops it. */
+export declare function setupStatsCard(options?: CardSetupOptions<StatsData, StatsVariant>): () => void;
+//# sourceMappingURL=index.d.ts.map

package/dist/stats/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/stats/index.ts"],"names":[],"mappings":"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"}