@rebasepro/plugin-insights 0.0.1-canary.4f204c2

package/src/engine/useInsightsData.ts

@@ -0,0 +1,100 @@
+import { useEffect, useState } from "react";
+import type { InsightDefinition, InsightDataResult } from "../types";
+import { useInsightsEngine } from "./InsightsProvider";
+import { useAuthController } from "@rebasepro/core";
+
+/**
+ * Hook that fetches and caches data for a single insight definition.
+ *
+ * Calls the definition's own `data()` callback and manages:
+ * - TTL-based caching via InsightsCache
+ * - Inflight request deduplication (multiple mounts of the same widget)
+ * - Loading and error state management
+ *
+ * @param definition - The insight to fetch data for
+ * @param collectionSlug - Optional collection context for cache key scoping
+ */
+export function useInsightsData(
+    definition: InsightDefinition,
+    collectionSlug?: string
+): {
+    data: InsightDataResult | null;
+    loading: boolean;
+    error: Error | null;
+} {
+    const engine = useInsightsEngine();
+    const cache = engine?.cache ?? null;
+    const { initialLoading, authLoading, user, loginSkipped } = useAuthController();
+    const authReady = !initialLoading && !authLoading && (Boolean(user) || loginSkipped);
+    const [data, setData] = useState<InsightDataResult | null>(null);
+    const [loading, setLoading] = useState(true);
+    const [error, setError] = useState<Error | null>(null);
+
+    const cacheKey = `${definition.id}:${collectionSlug ?? "global"}`;
+
+    useEffect(() => {
+        // Keep showing skeleton until both auth and engine are ready
+        if (!authReady || !cache) {
+            return;
+        }
+
+        let cancelled = false;
+
+        // 1. Check cache
+        const cached = cache.get(cacheKey);
+        if (cached) {
+            setData(cached);
+            setLoading(false);
+            return;
+        }
+
+        // 2. Check inflight — deduplicate concurrent requests for the same widget
+        const inflight = cache.getInflight(cacheKey);
+        if (inflight) {
+            setLoading(true);
+            inflight
+                .then((result) => {
+                    if (!cancelled) {
+                        setData(result);
+                    }
+                })
+                .catch((err) => {
+                    if (!cancelled) setError(err instanceof Error ? err : new Error(String(err)));
+                })
+                .finally(() => {
+                    if (!cancelled) setLoading(false);
+                });
+            return;
+        }
+
+        // 3. Fresh fetch — invoke the definition's own data callback
+        setLoading(true);
+        setError(null);
+
+        const promise = definition.data();
+
+        cache.setInflight(cacheKey, promise);
+
+        promise
+            .then((result) => {
+                cache.set(cacheKey, result);
+                if (!cancelled) {
+                    setData(result);
+                }
+            })
+            .catch((err) => {
+                if (!cancelled) {
+                    setError(err instanceof Error ? err : new Error(String(err)));
+                }
+            })
+            .finally(() => {
+                if (!cancelled) setLoading(false);
+            });
+
+        return () => {
+            cancelled = true;
+        };
+    }, [definition.id, definition.data, collectionSlug, cacheKey, cache, authReady]);
+
+    return { data, loading, error };
+}

package/src/index.ts

@@ -0,0 +1,22 @@
+// ── Types ─────────────────────────────────────────────────────────────
+export type {
+    DataRow,
+    ScorecardFormat,
+    ScorecardConfig,
+    InsightDataResult,
+    InsightDefinition,
+    InsightsPluginConfig,
+} from "./types";
+
+// ── Plugin ────────────────────────────────────────────────────────────
+export { useInsightsPlugin } from "./useInsightsPlugin";
+
+// ── Engine (for advanced usage) ───────────────────────────────────────
+export { InsightsProvider, useInsightsEngine } from "./engine/InsightsProvider";
+export { InsightsCache } from "./engine/InsightsCache";
+export { useInsightsData } from "./engine/useInsightsData";
+
+// ── Widget components (for custom layouts) ────────────────────────────
+export { InsightsScorecardView } from "./components/InsightsScorecardView";
+export { InsightWidget } from "./components/InsightWidget";
+export { InsightWidgetSkeleton } from "./components/InsightWidgetSkeleton";

package/src/types/engine.ts

@@ -0,0 +1,85 @@
+import type { DataRow, ScorecardConfig } from "./widgets";
+
+/**
+ * Result returned by an insight's data callback.
+ */
+export interface InsightDataResult {
+    rows: DataRow[];
+}
+
+/**
+ * A single insight definition — the "dry" configuration that describes
+ * what data to fetch and how to render it.
+ *
+ * Each insight owns its own `data()` callback, giving the developer
+ * full flexibility: use the Rebase client SDK, call a custom function,
+ * hit an external API — whatever makes sense for that widget.
+ */
+export interface InsightDefinition {
+    /** Unique identifier for this insight */
+    id: string;
+    /** Display title */
+    title: string;
+    /** Optional description */
+    description?: string;
+
+    /**
+     * Async callback that fetches data for this insight.
+     *
+     * The developer has full control — they can use any data source:
+     * - `rebaseClient.data.orders.find({ limit: 100 })`
+     * - `rebaseClient.call("functions/my-analytics", { ... })`
+     * - A plain `fetch()` to any external API
+     * - Static data for prototyping
+     *
+     * @returns Tabular data as `{ rows: DataRow[] }`.
+     *
+     * @example
+     * ```typescript
+     * data: async () => {
+     *     const res = await rebaseClient.data.orders.find({
+     *         limit: 1000,
+     *         orderBy: "created_at",
+     *     });
+     *     return { rows: res.data };
+     * }
+     * ```
+     */
+    data: () => Promise<InsightDataResult>;
+
+    /** Scorecard field mapping + formatting. */
+    scorecard: ScorecardConfig;
+}
+
+/**
+ * Full plugin configuration passed to `useInsightsPlugin`.
+ *
+ * The developer defines scorecard widgets by placement and provides
+ * their own data callbacks. No global fetch function needed — each
+ * widget is self-contained.
+ *
+ * Collection-level insights (`collections.<slug>`) are rendered in two places
+ * automatically:
+ * - **Collection list view**: Scorecards appear inline below the title and
+ *   above the data list.
+ * - **Home page cards**: Scorecards are auto-extracted and rendered as compact
+ *   widgets inside each collection's card on the home page.
+ *
+ * This eliminates the need to duplicate definitions across different locations.
+ */
+export interface InsightsPluginConfig {
+    /**
+     * Insight definitions keyed by placement.
+     *
+     * - `home`: Rendered at the top of the home page via `home.children.start`.
+     * - `collections.<slug>`: Rendered inline in that collection's list view
+     *   and auto-extracted as compact scorecards on the home card.
+     */
+    insights: {
+        home?: InsightDefinition[];
+        collections?: Record<string, InsightDefinition[]>;
+    };
+
+    /** Optional cache TTL in milliseconds (default: 60_000) */
+    cacheTTL?: number;
+}

package/src/types/index.ts

@@ -0,0 +1,5 @@
+// ── Insights engine types ────────────────────────────────────────────
+export * from "./engine";
+
+// ── Widget data & scorecard types ────────────────────────────────────
+export * from "./widgets";

package/src/types/widgets.ts

@@ -0,0 +1,66 @@
+/**
+ * Tabular data types used by insight widgets.
+ */
+
+/** A single row of data as key-value pairs. */
+export type DataRow = Record<string, string | number | boolean | null>;
+
+/**
+ * Formatting options for scorecard numbers.
+ * Uses Intl.NumberFormat standard.
+ */
+export interface ScorecardFormat {
+    /**
+     * The style of formatting.
+     * - `decimal`: 1,234.5
+     * - `currency`: $1,234.50
+     * - `percent`: 12.5%
+     */
+    style: "decimal" | "currency" | "percent";
+
+    /**
+     * How to display the number.
+     * - `standard`: 1,234,567 (default)
+     * - `compact`: 1.2M
+     */
+    notation?: "standard" | "compact";
+
+    /** Required if style is 'currency' (e.g., "USD", "EUR") */
+    currency?: string;
+
+    /** Number of decimal places to show */
+    decimals?: number;
+
+    /** If true, adds a '+' sign for positive numbers (e.g., +12.5%) */
+    showSign?: boolean;
+}
+
+/**
+ * Scorecard widget configuration — field mapping + formatting.
+ */
+export interface ScorecardConfig {
+    /** Main value configuration */
+    value: {
+        /** The column name from the query result for the main value */
+        field: string;
+        /** How to format this number */
+        format?: ScorecardFormat;
+    };
+    /** Comparison value configuration (optional) */
+    comparison?: {
+        /** The column name from the query result for the comparison value */
+        field: string;
+        /** How to format this number */
+        format?: ScorecardFormat;
+        /**
+         * Determines the color (green/red) based on the value.
+         * - `increase_is_good`: Positive = green, negative = red.
+         * - `decrease_is_good`: Positive = red, negative = green.
+         */
+        intent: "increase_is_good" | "decrease_is_good";
+    };
+    /** Optional icon key (e.g., "shopping_cart", "users") — resolved via getIcon */
+    icon?: string;
+    /** Optional date range text (e.g., "Last 30 days") */
+    dateRange?: string;
+}

package/src/useInsightsPlugin.tsx

@@ -0,0 +1,117 @@
+import React from "react";
+import type { RebasePlugin, SlotContribution } from "@rebasepro/types";
+import type { InsightsPluginConfig } from "./types";
+import { InsightsProvider } from "./engine/InsightsProvider";
+import { HomeCardInsightSlot } from "./components/HomeCardInsightSlot";
+import { HomeInsightsSlot } from "./components/HomeInsightsSlot";
+import { CollectionInsightsInline } from "./components/CollectionInsightsInline";
+
+/**
+ * Creates the Insights plugin for Rebase.
+ *
+ * This plugin injects scorecard widgets into key UI locations:
+ * - **Home page header**: KPI overview via `home.children.start` slot
+ * - **Collection list view**: Scorecards inline (below title, above list) via `collection.insights` slot
+ * - **Home page cards**: Compact scorecard metrics auto-extracted from collection insights via `home.card.insight` slot
+ *
+ * Collection-level insights (`collections.<slug>`) are the single source of truth:
+ * scorecards render in the collection list view and are automatically extracted
+ * to show as compact widgets on the corresponding home page card.
+ *
+ * Each insight owns its own `data()` callback — use the Rebase client SDK,
+ * call a custom function, or hit any external API. Full flexibility, zero new endpoints.
+ *
+ * @example
+ * ```typescript
+ * import { useInsightsPlugin } from "@rebasepro/plugin-insights";
+ *
+ * const insightsPlugin = useInsightsPlugin({
+ *     cacheTTL: 120_000,
+ *     insights: {
+ *         home: [
+ *             { id: "revenue", title: "Revenue", data: async () => ..., scorecard: { ... } },
+ *         ],
+ *         collections: {
+ *             orders: [
+ *                 { id: "total", title: "Total Orders", data: async () => ..., scorecard: { ... } },
+ *             ],
+ *         },
+ *     },
+ * });
+ * ```
+ */
+export function useInsightsPlugin(config: InsightsPluginConfig): RebasePlugin {
+    const { insights, cacheTTL } = config;
+    const slots: SlotContribution[] = [];
+
+    // ── Home page insights ────────────────────────────────────────────
+    if (insights.home && insights.home.length > 0) {
+        const homeInsights = insights.home;
+        slots.push({
+            slot: "home.children.start" as const,
+            Component: (props: Record<string, unknown>) => (
+                <HomeInsightsSlot
+                    {...props}
+                    insights={homeInsights}
+                />
+            ),
+            order: 10,
+        });
+    }
+
+    // ── Per-collection insights ───────────────────────────────────────
+    // A single `collections.<slug>` definition serves two slots:
+    // 1. collection.insights  → inline scorecards in the list view
+    // 2. home.card.insight    → compact scorecards on the home card
+    if (insights.collections) {
+        for (const [slug, defs] of Object.entries(insights.collections)) {
+            if (defs.length === 0) continue;
+            const collectionInsights = defs;
+
+            // 1. Inline in collection list view
+            slots.push({
+                slot: "collection.insights" as const,
+                Component: (props: Record<string, unknown>) => {
+                    const path = props.path as string;
+                    const collectionSlug = path?.split("/").filter(Boolean).pop() ?? "";
+                    if (collectionSlug !== slug) return null;
+                    return (
+                        <CollectionInsightsInline
+                            {...props as { path: string; collection: unknown; parentCollectionIds: string[] }}
+                            insights={collectionInsights}
+                        />
+                    );
+                },
+                order: 10,
+            });
+
+            // 2. Auto-extract scorecards for home page card
+            slots.push({
+                slot: "home.card.insight" as const,
+                Component: (props: Record<string, unknown>) => {
+                    const cardSlug = props.slug as string;
+                    if (cardSlug !== slug) return null;
+                    return (
+                        <HomeCardInsightSlot
+                            {...props as { slug: string; collection: unknown; context: unknown }}
+                            insights={collectionInsights}
+                        />
+                    );
+                },
+                order: 10,
+            });
+        }
+    }
+
+    return {
+        key: "plugin-insights",
+        slots,
+        providers: [
+            {
+                scope: "root" as const,
+                Component: InsightsProvider as React.ComponentType<React.PropsWithChildren<Record<string, unknown>>>,
+                props: { cacheTTL },
+            },
+        ],
+    };
+}