@rebasepro/plugin-insights 0.4.0 → 0.6.0

package/README.md

@@ -0,0 +1,115 @@
+# @rebasepro/plugin-insights
+
+Scorecard and KPI widget plugin for the Rebase admin panel.
+
+## Installation
+
+```bash
+pnpm add @rebasepro/plugin-insights
+```
+
+**Peer dependencies:** `react >= 19.0.0`, `react-dom >= 19.0.0`
+
+## 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.
+
+Widgets appear in three locations automatically:
+
+- **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.insights`
+- **Home page cards** — Compact metrics auto-extracted from collection insights via `home.card.insight`
+
+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.
+
+## 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[] }` |
+| `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 |
+
+### `InsightsPluginConfig`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `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 |
+
+### `ScorecardConfig`
+
+| 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"`) |
+
+## Quick Start
+
+```tsx
+import { useInsightsPlugin } from "@rebasepro/plugin-insights";
+
+const insightsPlugin = useInsightsPlugin({
+    cacheTTL: 120_000,
+    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"
+                }
+            }
+        ],
+        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"
+                    }
+                }
+            ]
+        }
+    }
+});
+
+// Pass to your Rebase app:
+<RebaseFirebaseApp plugins={[insightsPlugin]} />
+```
+
+## Related Packages
+
+- `@rebasepro/core` — Core framework providing the plugin system
+- `@rebasepro/types` — Shared types (`RebasePlugin`, `SlotContribution`)
+- `@rebasepro/ui` — UI components used by insight widgets

package/dist/{plugin-insights/src/components → components}/CollectionInsightsInline.d.ts

@@ -1,3 +1,4 @@
+import React from "react";
 import type { InsightDefinition } from "../types";
 /**
  * Renders scorecard insight widgets inline within a collection's list view,
@@ -11,7 +12,7 @@ export declare function CollectionInsightsInline({ insights, path, parentCollect
     parentCollectionSlugs: string[];
     parentEntityIds: string[];
     insights: InsightDefinition[];
-}): import("react/jsx-runtime").JSX.Element | null;
+}): React.JSX.Element | null;
 export declare namespace CollectionInsightsInline {
     var displayName: string;
 }

package/dist/{plugin-insights/src/components → components}/HomeCardInsightSlot.d.ts

@@ -1,3 +1,4 @@
+import React from "react";
 import type { InsightDefinition } from "../types";
 /**
  * Renders compact insight widgets inline within a home page collection card.
@@ -5,12 +6,12 @@ import type { InsightDefinition } from "../types";
  *
  * Uses a horizontal flex layout so multiple cards sit side by side.
  */
-export declare function HomeCardInsightSlot({ slug, insights, }: {
+export declare function HomeCardInsightSlot({ slug, insights }: {
     slug: string;
     collection: unknown;
     context: unknown;
     insights: InsightDefinition[];
-}): import("react/jsx-runtime").JSX.Element | null;
+}): React.JSX.Element | null;
 export declare namespace HomeCardInsightSlot {
     var displayName: string;
 }

package/dist/{plugin-insights/src/components → components}/HomeInsightsSlot.d.ts

@@ -1,3 +1,4 @@
+import React from "react";
 import type { InsightDefinition } from "../types";
 /**
  * Scorecard insights panel rendered at the top of the home page.
@@ -5,9 +6,9 @@ import type { InsightDefinition } from "../types";
  *
  * Renders scorecards in a responsive grid (up to 4 columns).
  */
-export declare function HomeInsightsSlot({ insights, }: {
+export declare function HomeInsightsSlot({ insights }: {
     insights: InsightDefinition[];
-}): import("react/jsx-runtime").JSX.Element | null;
+}): React.JSX.Element | null;
 export declare namespace HomeInsightsSlot {
     var displayName: string;
 }

package/dist/{plugin-insights/src/components → components}/InsightWidget.d.ts

@@ -1,3 +1,4 @@
+import React from "react";
 import type { InsightDefinition } from "../types";
 /**
  * Single insight widget orchestrator.
@@ -7,7 +8,7 @@ import type { InsightDefinition } from "../types";
  *
  * All theme-awareness is handled via Tailwind `dark:` classes.
  */
-export declare function InsightWidget({ definition, collectionSlug, path, parentCollectionSlugs, parentEntityIds, compact, embedded, }: {
+export declare function InsightWidget({ definition, collectionSlug, path, parentCollectionSlugs, parentEntityIds, compact, embedded }: {
     definition: InsightDefinition;
     collectionSlug?: string;
     path?: string;
@@ -16,7 +17,7 @@ export declare function InsightWidget({ definition, collectionSlug, path, parent
     compact?: boolean;
     /** When true, inner views skip their own borders since the parent card provides them. */
     embedded?: boolean;
-}): import("react/jsx-runtime").JSX.Element;
+}): React.JSX.Element;
 export declare namespace InsightWidget {
     var displayName: string;
 }

package/dist/{plugin-insights/src/components → components}/InsightWidgetSkeleton.d.ts

@@ -1,3 +1,4 @@
+import React from "react";
 import type { ScorecardConfig } from "../types";
 /**
  * Skeleton loader for scorecard insight widgets — displays animated
@@ -14,7 +15,7 @@ import type { ScorecardConfig } from "../types";
  * Tailwind line-heights (accounting for `leading-*` overrides).
  * This guarantees a pixel-perfect skeleton → loaded transition.
  */
-export declare function InsightWidgetSkeleton({ config, compact, embedded, fixedHeight, }: {
+export declare function InsightWidgetSkeleton({ config, compact, embedded, fixedHeight }: {
     /** Scorecard config — used to match optional elements (comparison, dateRange, icon). */
     config: ScorecardConfig;
     compact?: boolean;
@@ -22,7 +23,7 @@ export declare function InsightWidgetSkeleton({ config, compact, embedded, fixed
     embedded?: boolean;
     /** Explicit height to prevent layout shift between skeleton → loaded. */
     fixedHeight?: number;
-}): import("react/jsx-runtime").JSX.Element;
+}): React.JSX.Element;
 export declare namespace InsightWidgetSkeleton {
     var displayName: string;
 }

package/dist/{plugin-insights/src/components → components}/InsightsScorecardView.d.ts

@@ -1,3 +1,4 @@
+import React from "react";
 import type { DataRow, ScorecardConfig } from "../types";
 /**
  * Scorecard widget for the Rebase design system.
@@ -6,7 +7,7 @@ import type { DataRow, ScorecardConfig } from "../types";
  * Uses Tailwind `dark:` classes — no JS dark mode detection.
  * Icons are resolved via `getIcon` from `@rebasepro/core`.
  */
-export declare function InsightsScorecardView({ config, data, title, compact, embedded, fixedHeight, }: {
+export declare function InsightsScorecardView({ config, data, title, compact, embedded, fixedHeight }: {
     config: ScorecardConfig;
     data: DataRow;
     title: string;
@@ -15,7 +16,7 @@ export declare function InsightsScorecardView({ config, data, title, compact, em
     embedded?: boolean;
     /** Explicit height to prevent layout shift between skeleton → loaded. */
     fixedHeight?: number;
-}): import("react/jsx-runtime").JSX.Element;
+}): React.JSX.Element;
 export declare namespace InsightsScorecardView {
     var displayName: string;
 }

package/dist/{plugin-insights/src/engine → engine}/InsightsProvider.d.ts

@@ -1,4 +1,4 @@
-import { type PropsWithChildren } from "react";
+import React, { type PropsWithChildren } from "react";
 import { InsightsCache } from "./InsightsCache";
 interface InsightsContextValue {
     cache: InsightsCache;
@@ -12,7 +12,7 @@ interface InsightsContextValue {
  */
 export declare function InsightsProvider({ cacheTTL, children }: PropsWithChildren<{
     cacheTTL?: number;
-}>): import("react/jsx-runtime").JSX.Element;
+}>): React.JSX.Element;
 /**
  * Access the insights cache (for advanced usage).
  * Returns null when called outside of an `InsightsProvider`

package/dist/{plugin-insights/src/index.d.ts → index.d.ts}

@@ -1,4 +1,4 @@
-export type { DataRow, ScorecardFormat, ScorecardConfig, InsightDataResult, InsightDefinition, InsightsPluginConfig, } from "./types";
+export type { DataRow, ScorecardFormat, ScorecardConfig, InsightDataResult, InsightDefinition, InsightsPluginConfig } from "./types";
 export { useInsightsPlugin } from "./useInsightsPlugin";
 export { InsightsProvider, useInsightsEngine } from "./engine/InsightsProvider";
 export { InsightsCache } from "./engine/InsightsCache";