@rebasepro/plugin-insights 0.0.1-canary.e259309 → 0.0.1-canary.eb08332

package/LICENSE

@@ -1,6 +1,21 @@
-Source code in this repository is variously licensed under the Business Source
-License 1.1 (BSL), Apache version 2.0 and the MIT license. A copy of each
-license can be found in each one of the packages under the folder packages
-under a file called License. Source code in a given file is licensed under the
-BSL and the copyright belongs to Rebase Authors unless otherwise noted at the
-beginning of the file.
+MIT License
+
+Copyright (c) 2026 Rebase
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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/app` — 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,
@@ -5,12 +6,13 @@ import type { InsightDefinition } from "../types";
  *
  * Injected via the `collection.insights` slot.
  */
-export declare function CollectionInsightsInline({ insights, }: {
+export declare function CollectionInsightsInline({ insights, path, parentCollectionSlugs, parentEntityIds }: {
     path: string;
     collection: unknown;
-    parentCollectionIds: string[];
+    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,19 +1,23 @@
+import React from "react";
 import type { InsightDefinition } from "../types";
 /**
  * Single insight widget orchestrator.
  *
- * Fetches data via the engine, renders the scorecard visualization,
- * and manages loading/error states.
+ * 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, compact, embedded, }: {
+export declare function InsightWidget({ definition, collectionSlug, path, parentCollectionSlugs, parentEntityIds, compact, embedded }: {
     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;
-}): 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
@@ -7,14 +8,22 @@ import type { ScorecardConfig } from "../types";
  * The skeleton receives the scorecard config so it can conditionally
  * render placeholder lines for comparison, dateRange, and icon —
  * only when the loaded view will also render them.
+ *
+ * The standard skeleton mirrors InsightsScorecardView's responsive
+ * container-width breakpoints (ResizeObserver → isSmall / isMedium)
+ * and uses placeholder heights that exactly match the **computed**
+ * Tailwind line-heights (accounting for `leading-*` overrides).
+ * This guarantees a pixel-perfect skeleton → loaded transition.
  */
-export declare function InsightWidgetSkeleton({ config, compact, embedded, }: {
+export declare function InsightWidgetSkeleton({ config, compact, embedded, fixedHeight }: {
     /** Scorecard config — used to match optional elements (comparison, dateRange, icon). */
     config: ScorecardConfig;
     compact?: boolean;
     /** When true, skip own border since the parent card provides it. */
     embedded?: boolean;
-}): import("react/jsx-runtime").JSX.Element;
+    /** Explicit height to prevent layout shift between skeleton → loaded. */
+    fixedHeight?: number;
+}): React.JSX.Element;
 export declare namespace InsightWidgetSkeleton {
     var displayName: string;
 }

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

@@ -1,19 +1,22 @@
+import React from "react";
 import type { DataRow, ScorecardConfig } from "../types";
 /**
  * Scorecard widget for the Rebase design system.
  *
  * 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/core`.
+ * Icons are resolved via `getIcon` from `@rebasepro/app`.
  */
-export declare function InsightsScorecardView({ config, data, title, compact, embedded, }: {
+export declare function InsightsScorecardView({ config, data, title, compact, embedded, fixedHeight }: {
     config: ScorecardConfig;
     data: DataRow;
     title: string;
     compact?: boolean;
     /** When true, skip own border/bg since the parent card provides them. */
     embedded?: boolean;
-}): import("react/jsx-runtime").JSX.Element;
+    /** Explicit height to prevent layout shift between skeleton → loaded. */
+    fixedHeight?: number;
+}): 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/engine → engine}/useInsightsData.d.ts

@@ -1,4 +1,4 @@
-import type { InsightDefinition, InsightDataResult } from "../types";
+import type { InsightDefinition, InsightDataResult, InsightContext } from "../types";
 /**
  * Hook that fetches and caches data for a single insight definition.
  *
@@ -10,7 +10,7 @@ import type { InsightDefinition, InsightDataResult } from "../types";
  * @param definition - The insight to fetch data for
  * @param collectionSlug - Optional collection context for cache key scoping
  */
-export declare function useInsightsData(definition: InsightDefinition, collectionSlug?: string): {
+export declare function useInsightsData(definition: InsightDefinition, context: InsightContext): {
     data: InsightDataResult | null;
     loading: boolean;
     error: Error | null;

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";