@rebasepro/plugin-insights 0.23.0 → 0.24.0

package/README.md

@@ -16,99 +16,122 @@ of it resolves too: Node has supported `require(esm)` since 22.12.
 
 ## What This Package Does
 
-This plugin injects data-driven scorecard widgets into the Rebase admin UI. You define insight definitions with custom `data()` callbacks — use the Rebase SDK, call a custom function, or hit any external API. The plugin handles caching, rendering, and slot injection.
+This plugin puts figures — revenue, orders, open tickets — into the Rebase admin
+UI, each beside its change over a comparison period. You declare named
+`sources`, functions that fetch one record of figures for that period: use the
+Rebase SDK, call a backend function, or hit any API. Each insight names the
+source and the field it reads. The plugin fetches each source once per signed-in
+user, caches it, works out the change, and renders it in the right slots.
 
-Widgets appear in three locations automatically:
+Figures appear in three places:
 
-- **Home page header** — KPI overview cards via the `home.children.start` slot
-- **Collection list view** — Inline scorecards below the title, above the data list via `collection.widgets`
-- **Home page cards** — Compact metrics auto-extracted from collection insights via `home.card.widget`
+- **Home page header**: a row of KPI cards via the `home.children.start` slot
+- **Collection list view**: a row of figures below the title, above the list, via `collection.widgets`
+- **Home page cards**: compact figures on each collection's card via `home.card.widget`
 
-Collection-level insights are the single source of truth: define once under `collections.<slug>`, and they render both in the collection view and on the home card.
+Collection insights are defined once, under `collections.<slug>`, and render
+both in the collection's list view and on its home card. Every insight that
+reads a source shares one fetch of it, so a figure shown in two places is the
+same number.
 
 ## Key Exports
 
 | Export | Type | Description |
 |---|---|---|
 | `useInsightsPlugin` | Hook | Creates the plugin from an `InsightsPluginConfig`. Returns a `RebasePlugin` |
-| `InsightsPluginConfig` | Type | Top-level config: `insights` (home + collections) and optional `cacheTTL` |
-| `InsightDefinition` | Type | Single insight: `id`, `title`, `data()` callback, `scorecard` config |
-| `InsightDataResult` | Type | Return type of `data()`: `{ rows: DataRow[] }` |
+| `InsightsPluginConfig` | Type | Top-level config: `sources`, `insights` (home + collections), optional `period` and `cacheTTL` |
+| `InsightSource` | Type | `(context: { period }) => Promise<DataRow>`: fetches one record of figures |
+| `InsightSourceContext` | Type | What a source is called with: `{ period: InsightPeriod }` |
+| `InsightPeriod` | Type | The resolved windows: `days`, `from`, `to`, `previousFrom` |
+| `InsightPeriodConfig` | Type | `{ days }`, the comparison window |
+| `InsightDefinition` | Type | One figure: `id`, `title`, `source`, `value`, optional `comparison` and `icon` |
+| `InsightComparison` | Type | `previous` field, `intent`, and `show` (`percent` or `absolute`) |
+| `InsightFormat` | Type | Number formatting: `style` (decimal/currency/percent), `notation`, `currency`, `decimals` |
 | `DataRow` | Type | `Record<string, string \| number \| boolean \| null>` |
-| `ScorecardConfig` | Type | Field mapping for value, comparison, icon, dateRange |
-| `ScorecardFormat` | Type | Number formatting: style (decimal/currency/percent), notation, currency, decimals, showSign |
 | `InsightsProvider` | Component | React context provider (injected automatically by the plugin) |
 | `useInsightsEngine` | Hook | Access the insights engine from context (advanced) |
-| `InsightsCache` | Class | TTL-based cache for insight data (advanced) |
-| `useInsightsData` | Hook | Fetch and cache data for a specific insight (advanced) |
-| `InsightsScorecardView` | Component | Renders a scorecard from data + config (custom layouts) |
-| `InsightWidget` | Component | Single insight widget container (custom layouts) |
-| `InsightWidgetSkeleton` | Component | Loading placeholder for insight widgets |
+| `InsightsEngine` | Class | Fetches and caches sources per user, and anchors the period (advanced) |
+| `resolvePeriod` | Function | `(days, to) => InsightPeriod` (advanced) |
+| `useInsightSource` | Hook | Reads one source for the signed-in user (custom layouts) |
+| `InsightsRow` | Component | A row of insights under the period label (custom layouts) |
+| `InsightsScorecardView` | Component | Renders one figure from a record and its definition (custom layouts) |
+| `InsightWidget` | Component | Single insight container (custom layouts) |
 
 ### `InsightsPluginConfig`
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
+| `sources` | `Record<string, InsightSource>` | — | Where the figures come from, by name. Required |
 | `insights.home` | `InsightDefinition[]` | — | Insights shown at the top of the home page |
 | `insights.collections` | `Record<string, InsightDefinition[]>` | — | Insights per collection slug |
-| `cacheTTL` | `number` | `60_000` | Cache TTL in milliseconds |
+| `period.days` | `number` | `30` | The comparison window: the last N days against the N days before them |
+| `cacheTTL` | `number` | `60_000` | How long a fetched source is reused, in milliseconds |
 
-### `ScorecardConfig`
+Creating the plugin throws when an insight names a source that `sources` does
+not declare, or when `period.days` is not a whole number of at least 1. Pass a
+memoized config: a new `sources` object starts a new cache.
+
+### `InsightDefinition`
 
 | Prop | Type | Description |
 |---|---|---|
-| `value.field` | `string` | Column name from data rows for the main value |
-| `value.format` | `ScorecardFormat` | Number formatting options |
-| `comparison.field` | `string` | Column name for comparison/delta value |
-| `comparison.format` | `ScorecardFormat` | Formatting for comparison |
-| `comparison.intent` | `"increase_is_good" \| "decrease_is_good"` | Controls green/red coloring |
-| `icon` | `string` | Icon key (e.g., `"shopping_cart"`) |
-| `dateRange` | `string` | Label text (e.g., `"Last 30 days"`) |
+| `source` | `string` | The key in `sources` this insight reads |
+| `value.field` | `string` | The field holding the figure |
+| `value.format` | `InsightFormat` | How to write it, in the admin panel's language |
+| `comparison.previous` | `string` | The field holding the same figure for the previous period |
+| `comparison.intent` | `"increase_is_good" \| "decrease_is_good"` | Which direction reads as good news |
+| `comparison.show` | `"percent" \| "absolute"` | The relative change (default), or the difference. Use `absolute` for small counts |
+| `icon` | `string` | Icon key (e.g., `"ShoppingCart"`), resolved via `getIcon` |
 
 ## Quick Start
 
 ```tsx
+import { useMemo } from "react";
 import { Rebase } from "@rebasepro/app";
 import { RebaseShell } from "@rebasepro/cms";
 import { useInsightsPlugin } from "@rebasepro/plugin-insights";
-
-const insightsPlugin = useInsightsPlugin({
-    cacheTTL: 120_000,
+import type { DataRow, InsightPeriod } from "@rebasepro/plugin-insights";
+
+const windowQuery = (period: InsightPeriod) => new URLSearchParams({
+    previousFrom: period.previousFrom.toISOString(),
+    from: period.from.toISOString(),
+    to: period.to.toISOString()
+}).toString();
+
+const insightsPlugin = useInsightsPlugin(useMemo(() => ({
+    period: { days: 30 },
+    sources: {
+        // One request answers every insight below: { revenue, previousRevenue, shipped, previousShipped }
+        orders: ({ period }) => rebaseClient.functions.invoke<DataRow>("insights", undefined, {
+            method: "GET",
+            path: `orders?${windowQuery(period)}`
+        })
+    },
     insights: {
         home: [
             {
                 id: "revenue",
                 title: "Revenue",
-                data: async () => {
-                    const res = await fetch("/api/analytics/revenue");
-                    return { rows: [await res.json()] };
-                },
-                scorecard: {
-                    value: { field: "total", format: { style: "currency", currency: "USD", notation: "compact" } },
-                    comparison: { field: "delta_pct", format: { style: "percent", decimals: 1 }, intent: "increase_is_good" },
-                    icon: "attach_money",
-                    dateRange: "Last 30 days"
-                }
+                source: "orders",
+                icon: "DollarSign",
+                value: { field: "revenue", format: { style: "currency", currency: "USD", notation: "compact" } },
+                comparison: { previous: "previousRevenue", intent: "increase_is_good" }
             }
         ],
         collections: {
             orders: [
                 {
-                    id: "total_orders",
-                    title: "Total Orders",
-                    data: async () => {
-                        const count = await rebaseClient.data.orders.count();
-                        return { rows: [{ total: count }] };
-                    },
-                    scorecard: {
-                        value: { field: "total", format: { style: "decimal", notation: "compact" } },
-                        icon: "shopping_cart"
-                    }
+                    id: "shipped",
+                    title: "Shipped",
+                    source: "orders",
+                    icon: "Truck",
+                    value: { field: "shipped" },
+                    comparison: { previous: "previousShipped", intent: "increase_is_good", show: "absolute" }
                 }
             ]
         }
     }
-});
+}), []));
 
 // Pass to your Rebase app:
 <Rebase client={rebaseClient} plugins={[insightsPlugin]}>
@@ -116,6 +139,10 @@ const insightsPlugin = useInsightsPlugin({
 </Rebase>
 ```
 
+A source runs in the browser under the signed-in user's permissions. The demo
+app's `insights` backend function (`app/backend/functions/insights.ts`) is one
+way to compute both windows in a single query.
+
 ## Related Packages
 
 - `@rebasepro/app` — Core framework providing the plugin system

package/dist/components/CollectionInsightsInline.d.ts

@@ -6,11 +6,7 @@ import type { InsightDefinition } from "../types/index.js";
  *
  * Injected via the `collection.widgets` slot.
  */
-export declare function CollectionInsightsInline({ insights, path, parentCollectionSlugs, parentEntityIds }: {
-    path: string;
-    collection: unknown;
-    parentCollectionSlugs: string[];
-    parentEntityIds: string[];
+export declare function CollectionInsightsInline({ insights }: {
     insights: InsightDefinition[];
 }): React.JSX.Element | null;
 export declare namespace CollectionInsightsInline {

package/dist/components/HomeCardInsightSlot.d.ts

@@ -1,15 +1,10 @@
 import React from "react";
 import type { InsightDefinition } from "../types/index.js";
 /**
- * Renders compact insight widgets inline within a home page collection card.
+ * Renders compact insight readouts inside a home page collection card.
  * Injected via the `home.card.widget` slot.
- *
- * Uses a horizontal flex layout so multiple cards sit side by side.
  */
-export declare function HomeCardInsightSlot({ slug, insights }: {
-    slug: string;
-    collection: unknown;
-    context: unknown;
+export declare function HomeCardInsightSlot({ insights }: {
     insights: InsightDefinition[];
 }): React.JSX.Element | null;
 export declare namespace HomeCardInsightSlot {

package/dist/components/HomeInsightsSlot.d.ts

@@ -3,8 +3,6 @@ import type { InsightDefinition } from "../types/index.js";
 /**
  * Scorecard insights panel rendered at the top of the home page.
  * Injected via the `home.children.start` slot.
- *
- * Renders scorecards in a responsive grid (up to 4 columns).
  */
 export declare function HomeInsightsSlot({ insights }: {
     insights: InsightDefinition[];

package/dist/components/InsightWidget.d.ts

@@ -1,22 +1,9 @@
 import React from "react";
 import type { InsightDefinition } from "../types/index.js";
-/**
- * Single insight widget orchestrator.
- *
- * Wraps skeleton and loaded states in a fixed-height container
- * (computed from the scorecard config) to prevent layout shift.
- *
- * All theme-awareness is handled via Tailwind `dark:` classes.
- */
-export declare function InsightWidget({ definition, collectionSlug, path, parentCollectionSlugs, parentEntityIds, compact, embedded }: {
+/** One insight, reading its source through the shared engine. */
+export declare function InsightWidget({ definition, compact }: {
     definition: InsightDefinition;
-    collectionSlug?: string;
-    path?: string;
-    parentCollectionSlugs?: string[];
-    parentEntityIds?: string[];
     compact?: boolean;
-    /** When true, inner views skip their own borders since the parent card provides them. */
-    embedded?: boolean;
 }): React.JSX.Element;
 export declare namespace InsightWidget {
     var displayName: string;

package/dist/components/InsightsRow.d.ts

@@ -0,0 +1,13 @@
+import React from "react";
+import type { InsightDefinition } from "../types/index.js";
+/**
+ * A row of insight tiles. When any of them compares with the previous period,
+ * the row says which period once, above the tiles, rather than on each.
+ */
+export declare function InsightsRow({ insights, className }: {
+    insights: InsightDefinition[];
+    className?: string;
+}): React.JSX.Element;
+export declare namespace InsightsRow {
+    var displayName: string;
+}

package/dist/components/InsightsScorecardView.d.ts

@@ -1,21 +1,22 @@
 import React from "react";
-import type { DataRow, ScorecardConfig } from "../types/index.js";
+import type { InsightDefinition } from "../types/index.js";
+import type { SourceResult } from "../engine/InsightsEngine.js";
 /**
- * Scorecard widget for the Rebase design system.
+ * One insight: its label, its value and its change on the previous period.
  *
- * Renders a single KPI metric with optional comparison value and icon.
- * Uses Tailwind `dark:` classes — no JS dark mode detection.
- * Icons are resolved via `getIcon` from `@rebasepro/app`.
+ * The label and icon are known before the figures are, so they render while
+ * the source loads and only the figures pulse. Loading, loaded and failed
+ * share one shell, so nothing moves when the data arrives.
+ *
+ * `compact` is the inline readout on a home-page card; the default is a tile.
  */
-export declare function InsightsScorecardView({ config, data, title, compact, embedded, fixedHeight }: {
-    config: ScorecardConfig;
-    data: DataRow;
-    title: string;
+export declare function InsightsScorecardView({ definition, result, loading, error, compact }: {
+    definition: InsightDefinition;
+    /** The source's record and the period it was fetched for. */
+    result: SourceResult | null;
+    loading?: boolean;
+    error?: Error | null;
     compact?: boolean;
-    /** When true, skip own border/bg since the parent card provides them. */
-    embedded?: boolean;
-    /** Explicit height to prevent layout shift between skeleton → loaded. */
-    fixedHeight?: number;
 }): React.JSX.Element;
 export declare namespace InsightsScorecardView {
     var displayName: string;

package/dist/engine/InsightsEngine.d.ts

@@ -0,0 +1,48 @@
+import type { DataRow, InsightPeriod, InsightSource } from "../types/index.js";
+export declare const DEFAULT_PERIOD_DAYS = 30;
+/** The current and previous windows of `days` days, ending at `to`. */
+export declare function resolvePeriod(days: number, to: Date): InsightPeriod;
+/** A source's record, with the period it was fetched for. */
+export interface SourceResult {
+    row: DataRow;
+    period: InsightPeriod;
+}
+/**
+ * The cache key for one source, for one user.
+ *
+ * The engine lives at the root of the app and outlives a sign-out, and a figure
+ * is computed under the permissions and row-level security of whoever asked
+ * for it. A key without the user would serve the previous account's numbers to
+ * the next one that signs in on the same tab, until the TTL ran out.
+ */
+export declare function sourceCacheKey(sourceId: string, userId: string | null): string;
+/**
+ * Fetches and caches the plugin's sources.
+ *
+ * Every insight that reads a source shares one fetch of it: concurrent reads
+ * join the request in flight, later ones read the cache until the TTL passes.
+ * That is what keeps a figure shown on the home page and in a collection view
+ * the same number.
+ */
+export declare class InsightsEngine {
+    private readonly sources;
+    readonly periodDays: number;
+    private readonly ttl;
+    private readonly now;
+    private readonly cache;
+    private readonly inflight;
+    private anchor;
+    constructor(sources: Record<string, InsightSource>, periodDays?: number, ttl?: number, now?: () => number);
+    /**
+     * The period a fetch starting now is asked for. Its end is fixed by the
+     * first fetch and kept until the TTL passes, so sources fetched for the
+     * same screen describe the same window.
+     */
+    period(): InsightPeriod;
+    /** The cached result for this source and user, if it is still fresh. */
+    peek(sourceId: string, userId: string | null): SourceResult | null;
+    /** The source's record for this user: from the cache, the fetch in flight, or a new fetch. */
+    load(sourceId: string, userId: string | null): Promise<SourceResult>;
+    /** Drops every cached result and fetch in flight, and re-anchors the period on the next fetch. */
+    invalidate(): void;
+}

package/dist/engine/InsightsProvider.d.ts

@@ -1,22 +1,20 @@
 import React, { type PropsWithChildren } from "react";
-import { InsightsCache } from "./InsightsCache.js";
-interface InsightsContextValue {
-    cache: InsightsCache;
-}
+import type { InsightSource } from "../types/index.js";
+import { InsightsEngine } from "./InsightsEngine.js";
 /**
  * Root-level provider for the insights data engine.
  * Injected automatically by the plugin via `providers: [{ scope: "root" }]`.
  *
- * Manages a single `InsightsCache` instance shared by all insight widgets
- * for TTL-based caching and inflight request deduplication.
+ * Holds the one `InsightsEngine` every insight widget reads its source from.
  */
-export declare function InsightsProvider({ cacheTTL, children }: PropsWithChildren<{
+export declare function InsightsProvider({ sources, periodDays, cacheTTL, children }: PropsWithChildren<{
+    sources: Record<string, InsightSource>;
+    periodDays?: number;
     cacheTTL?: number;
 }>): React.JSX.Element;
 /**
- * Access the insights cache (for advanced usage).
+ * The insights engine (for advanced usage).
  * Returns null when called outside of an `InsightsProvider`
  * (e.g. during auth-loading phase before plugin providers mount).
  */
-export declare function useInsightsEngine(): InsightsContextValue | null;
-export {};
+export declare function useInsightsEngine(): InsightsEngine | null;

package/dist/engine/useInsightSource.d.ts

@@ -0,0 +1,12 @@
+import { type SourceResult } from "./InsightsEngine.js";
+/**
+ * Reads one source for the signed-in user.
+ *
+ * Waits for auth to settle: a source runs under the caller's permissions, so
+ * fetching before the user is known would compute the figures for nobody.
+ */
+export declare function useInsightSource(sourceId: string): {
+    result: SourceResult | null;
+    loading: boolean;
+    error: Error | null;
+};

package/dist/format.d.ts

@@ -0,0 +1,21 @@
+import type { InsightComparison, InsightFormat } from "./types/index.js";
+/** Writes a value the way its insight asks, in the admin panel's language. */
+export declare function formatValue(value: number, format: InsightFormat | undefined, locale: string | undefined): string;
+export type ChangeDirection = "up" | "down" | "flat";
+export interface FormattedChange {
+    direction: ChangeDirection;
+    /** The size of the change, unsigned: the direction carries the sign. */
+    magnitude: string;
+}
+/**
+ * The change from `previous` to `current`, written as the comparison asks.
+ *
+ * A percentage needs a previous figure to be a percentage of, so a change
+ * from zero is written as the difference instead. Under 10% keeps one
+ * decimal (`0.2%`), above it none (`42%`): the decimal stops carrying
+ * information once the change is that large.
+ */
+export declare function formatChange(current: number, previous: number, comparison: InsightComparison, format: InsightFormat | undefined, locale: string | undefined): FormattedChange;
+export type ChangeTone = "positive" | "negative" | "neutral";
+/** Whether a change in this direction is good news for this insight. */
+export declare function changeTone(direction: ChangeDirection, intent: InsightComparison["intent"]): ChangeTone;

package/dist/index.d.ts

@@ -1,8 +1,9 @@
-export type { DataRow, ScorecardFormat, ScorecardConfig, InsightDataResult, InsightDefinition, InsightsPluginConfig } from "./types/index.js";
+export type { DataRow, InsightFormat, InsightComparison, InsightDefinition, InsightPeriod, InsightPeriodConfig, InsightSource, InsightSourceContext, InsightsPluginConfig } from "./types/index.js";
 export { useInsightsPlugin } from "./useInsightsPlugin.js";
 export { InsightsProvider, useInsightsEngine } from "./engine/InsightsProvider.js";
-export { InsightsCache } from "./engine/InsightsCache.js";
-export { useInsightsData } from "./engine/useInsightsData.js";
+export { InsightsEngine, resolvePeriod } from "./engine/InsightsEngine.js";
+export type { SourceResult } from "./engine/InsightsEngine.js";
+export { useInsightSource } from "./engine/useInsightSource.js";
 export { InsightsScorecardView } from "./components/InsightsScorecardView.js";
 export { InsightWidget } from "./components/InsightWidget.js";
-export { InsightWidgetSkeleton } from "./components/InsightWidgetSkeleton.js";
+export { InsightsRow } from "./components/InsightsRow.js";