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

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "@rebasepro/plugin-insights",
+  "type": "module",
+  "version": "0.0.1-canary.4f204c2",
+  "main": "./dist/index.umd.js",
+  "module": "./dist/index.es.js",
+  "types": "./dist/index.d.ts",
+  "source": "src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "development": "./src/index.ts",
+      "import": "./dist/index.es.js",
+      "require": "./dist/index.umd.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "lucide-react": "1.14.0",
+    "react-compiler-runtime": "1.0.0",
+    "@rebasepro/core": "0.0.1-canary.4f204c2",
+    "@rebasepro/types": "0.0.1-canary.4f204c2"
+  },
+  "peerDependencies": {
+    "react": ">=19.0.0",
+    "react-dom": ">=19.0.0"
+  },
+  "browserslist": {
+    "production": [
+      ">0.2%",
+      "not dead",
+      "not op_mini all"
+    ],
+    "development": [
+      "last 1 chrome version",
+      "last 1 firefox version",
+      "last 1 safari version"
+    ]
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.9.1",
+    "@types/jest": "^29.5.14",
+    "@types/react": "^19.0.8",
+    "@types/react-dom": "^19.0.3",
+    "@vitejs/plugin-react": "^4.3.4",
+    "babel-jest": "^29.7.0",
+    "babel-plugin-react-compiler": "^19.0.0-beta-af1b7da-20250417",
+    "eslint-plugin-react-compiler": "^19.1.0-rc.2",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.4.5",
+    "typescript": "^5.9.3",
+    "vite": "^7.2.4"
+  },
+  "jest": {
+    "transform": {
+      "^.+\\.tsx?$": "ts-jest"
+    },
+    "testRegex": "(/__tests__/.*|(\\.|/)(test|spec))\\.tsx?$",
+    "moduleFileExtensions": [
+      "ts",
+      "tsx",
+      "js",
+      "jsx",
+      "json",
+      "node"
+    ]
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build && tsc --emitDeclarationOnly -p tsconfig.prod.json",
+    "test": "jest --passWithNoTests"
+  }
+}

package/src/components/CollectionInsightsInline.tsx

@@ -0,0 +1,30 @@
+import React from "react";
+import type { InsightDefinition } from "../types";
+import { InsightWidget } from "./InsightWidget";
+
+/**
+ * Renders scorecard insight widgets inline within a collection's list view,
+ * positioned below the title and above the main data list.
+ *
+ * Injected via the `collection.insights` slot.
+ */
+export function CollectionInsightsInline({
+    insights,
+}: {
+    path: string;
+    collection: unknown;
+    parentCollectionIds: string[];
+    insights: InsightDefinition[];
+}) {
+    if (!insights || insights.length === 0) return null;
+
+    return (
+        <div className="grid grid-cols-2 sm:grid-cols-3 lg:grid-cols-4 gap-3 pb-4">
+            {insights.map((def) => (
+                <InsightWidget key={def.id} definition={def} />
+            ))}
+        </div>
+    );
+}
+
+CollectionInsightsInline.displayName = "CollectionInsightsInline";

package/src/components/HomeCardInsightSlot.tsx

@@ -0,0 +1,36 @@
+import React from "react";
+import type { InsightDefinition } from "../types";
+import { InsightWidget } from "./InsightWidget";
+
+/**
+ * Renders compact insight widgets inline within a home page collection card.
+ * Injected via the `home.card.insight` slot.
+ *
+ * Uses a horizontal flex layout so multiple cards sit side by side.
+ */
+export function HomeCardInsightSlot({
+    slug,
+    insights,
+}: {
+    slug: string;
+    collection: unknown;
+    context: unknown;
+    insights: InsightDefinition[];
+}) {
+    if (!insights || insights.length === 0) return null;
+
+    return (
+        <div className="flex flex-wrap items-center gap-1.5 mt-2" style={{ minHeight: 46 }}>
+            {insights.map((def) => (
+                <InsightWidget
+                    key={def.id}
+                    definition={def}
+                    collectionSlug={slug}
+                    compact={true}
+                />
+            ))}
+        </div>
+    );
+}
+
+HomeCardInsightSlot.displayName = "HomeCardInsightSlot";

package/src/components/HomeInsightsSlot.tsx

@@ -0,0 +1,30 @@
+import React from "react";
+import type { InsightDefinition } from "../types";
+import { InsightWidget } from "./InsightWidget";
+
+/**
+ * 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 function HomeInsightsSlot({
+    insights,
+}: {
+    insights: InsightDefinition[];
+}) {
+    if (!insights || insights.length === 0) return null;
+
+    return (
+        <div
+            className="grid grid-cols-2 sm:grid-cols-3 lg:grid-cols-4 gap-3 pb-6"
+            style={{ minHeight: 92 }}
+        >
+            {insights.map((def) => (
+                <InsightWidget key={def.id} definition={def} />
+            ))}
+        </div>
+    );
+}
+
+HomeInsightsSlot.displayName = "HomeInsightsSlot";

package/src/components/InsightWidget.tsx

@@ -0,0 +1,65 @@
+import React from "react";
+import type { InsightDefinition, DataRow } from "../types";
+import { useInsightsData } from "../engine/useInsightsData";
+import { InsightsScorecardView } from "./InsightsScorecardView";
+import { InsightWidgetSkeleton } from "./InsightWidgetSkeleton";
+
+/**
+ * Single insight widget orchestrator.
+ *
+ * Fetches data via the engine, renders the scorecard visualization,
+ * and manages loading/error states.
+ *
+ * All theme-awareness is handled via Tailwind `dark:` classes.
+ */
+export function InsightWidget({
+    definition,
+    collectionSlug,
+    compact = false,
+    embedded = false,
+}: {
+    definition: InsightDefinition;
+    collectionSlug?: string;
+    compact?: boolean;
+    /** When true, inner views skip their own borders since the parent card provides them. */
+    embedded?: boolean;
+}) {
+    const { data, loading, error } = useInsightsData(definition, collectionSlug);
+
+    if (loading) {
+        return <InsightWidgetSkeleton config={definition.scorecard} compact={compact} embedded={embedded} />;
+    }
+
+    if (error) {
+        return (
+            <div
+                className={`text-red-500/70 dark:text-red-400/70 text-[0.8125rem] ${embedded ? "px-5 py-4 h-full" : `rounded-lg bg-red-500/5 dark:bg-red-400/5 border border-red-500/10 dark:border-red-400/10 ${compact ? "px-3.5 py-3" : "px-5 py-4"}`}`}
+            >
+                <div className="font-semibold mb-1">{definition.title}</div>
+                <div>{error.message}</div>
+            </div>
+        );
+    }
+
+    if (!data || data.rows.length === 0) {
+        return (
+            <div
+                className={`text-surface-400 dark:text-surface-500 text-[0.8125rem] ${embedded ? "px-5 py-4 h-full" : `rounded-lg bg-surface-100 dark:bg-surface-800 border border-surface-200 dark:border-surface-700 ${compact ? "px-3.5 py-3" : "px-5 py-4"}`}`}
+            >
+                {definition.title} — No data
+            </div>
+        );
+    }
+
+    return (
+        <InsightsScorecardView
+            config={definition.scorecard}
+            data={data.rows[0] as DataRow}
+            title={definition.title}
+            compact={compact}
+            embedded={embedded}
+        />
+    );
+}
+
+InsightWidget.displayName = "InsightWidget";

package/src/components/InsightWidgetSkeleton.tsx

@@ -0,0 +1,122 @@
+import React from "react";
+import { cls, defaultBorderMixin } from "@rebasepro/ui";
+import type { ScorecardConfig } from "../types";
+
+/**
+ * Skeleton loader for scorecard insight widgets — displays animated
+ * shimmer placeholders that exactly match the final rendered layout
+ * of InsightsScorecardView for a given config, preventing layout shift.
+ *
+ * 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.
+ */
+export function InsightWidgetSkeleton({
+    config,
+    compact = false,
+    embedded = false,
+}: {
+    /** 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;
+}) {
+    const hasComparison = Boolean(config.comparison);
+    const hasIcon = Boolean(config.icon);
+    const hasDateRange = Boolean(config.dateRange);
+
+    // ── Compact scorecard skeleton ──────────────────────────────────────
+    // Matches InsightsScorecardView compact layout:
+    //   container: flex flex-col gap-0.5 px-2.5 py-2 rounded-md border
+    //   title:     text-[10px] uppercase → line-height ~14px
+    //   value row: text-sm font-semibold → line-height ~20px
+    //   + optional comparison text-[10px] inside value row
+    if (compact) {
+        return (
+            <div
+                className={cls(
+                    "animate-pulse",
+                    embedded
+                        ? "h-full px-2.5 py-2"
+                        : "flex flex-col gap-0.5 rounded-md bg-transparent border min-w-0 px-2.5 py-2",
+                    !embedded && defaultBorderMixin
+                )}
+            >
+                {/* Title line */}
+                <div className="bg-surface-200 dark:bg-surface-700 rounded-sm"
+                    style={{ height: 14, width: 48 }}
+                />
+                {/* Value + optional comparison row */}
+                <div className="flex items-baseline gap-1.5">
+                    <div className="bg-surface-200 dark:bg-surface-700 rounded-sm"
+                        style={{ height: 20, width: 40 }}
+                    />
+                    {hasComparison && (
+                        <div className="bg-surface-200/60 dark:bg-surface-700/60 rounded-sm"
+                            style={{ height: 14, width: 28 }}
+                        />
+                    )}
+                </div>
+            </div>
+        );
+    }
+
+    // ── Standard scorecard skeleton ─────────────────────────────────────
+    // Matches InsightsScorecardView standard layout (isSmall = false):
+    //   container: rounded-lg px-5 py-4 border, minHeight 92
+    //   title row: flex justify-between mb-2
+    //     title:     text-xs → line-height ~16px
+    //     dateRange: text-[10px] mt-0.5 → ~14px  (optional)
+    //     icon:      18×18 ml-2                    (optional)
+    //   value:     text-2xl → line-height ~32px
+    //   comparison: text-xs mt-1 → ~16px           (optional)
+    return (
+        <div
+            className={cls(
+                "animate-pulse",
+                embedded
+                    ? "h-full px-5 py-4"
+                    : "rounded-lg bg-transparent border px-5 py-4",
+                !embedded && defaultBorderMixin
+            )}
+            style={embedded ? undefined : { minHeight: 92 }}
+        >
+            {/* Title row */}
+            <div className="flex items-center justify-between mb-2">
+                <div className="flex flex-col min-w-0">
+                    {/* Title */}
+                    <div className="bg-surface-200 dark:bg-surface-700 rounded"
+                        style={{ height: 16, width: "60%" }}
+                    />
+                    {/* DateRange (only if config has it) */}
+                    {hasDateRange && (
+                        <div className="bg-surface-200/60 dark:bg-surface-700/60 rounded mt-0.5"
+                            style={{ height: 14, width: "40%" }}
+                        />
+                    )}
+                </div>
+                {/* Icon placeholder (only if config has it) */}
+                {hasIcon && (
+                    <div className="bg-surface-200 dark:bg-surface-700 rounded ml-2 shrink-0"
+                        style={{ height: 18, width: 18 }}
+                    />
+                )}
+            </div>
+
+            {/* Main value */}
+            <div className="bg-surface-200 dark:bg-surface-700 rounded"
+                style={{ height: 32, width: "40%" }}
+            />
+
+            {/* Comparison (only if config has it) */}
+            {hasComparison && (
+                <div className="bg-surface-200/60 dark:bg-surface-700/60 rounded mt-1"
+                    style={{ height: 16, width: "25%" }}
+                />
+            )}
+        </div>
+    );
+}
+
+InsightWidgetSkeleton.displayName = "InsightWidgetSkeleton";

package/src/components/InsightsScorecardView.tsx

@@ -0,0 +1,160 @@
+import React, { useRef, useState } from "react";
+import { getIcon } from "@rebasepro/core";
+import { cls, defaultBorderMixin } from "@rebasepro/ui";
+import type { DataRow, ScorecardConfig, ScorecardFormat } from "../types";
+
+function formatNumber(value: number, format?: ScorecardFormat): string {
+    if (value === null || value === undefined) return "N/A";
+
+    const options: Intl.NumberFormatOptions = {
+        style: format?.style ?? "decimal",
+        notation: format?.notation ?? "standard",
+        maximumFractionDigits: format?.decimals ?? 1,
+        minimumFractionDigits: format?.decimals ?? 1,
+    };
+
+    if (format?.style === "currency") {
+        options.currency = format.currency ?? "USD";
+    }
+
+    let formatted = new Intl.NumberFormat("en-US", options).format(value);
+
+    if (format?.showSign && value > 0) {
+        formatted = "+" + formatted;
+    }
+
+    return formatted;
+}
+
+/**
+ * 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`.
+ */
+export function InsightsScorecardView({
+    config,
+    data,
+    title,
+    compact = false,
+    embedded = false,
+}: {
+    config: ScorecardConfig;
+    data: DataRow;
+    title: string;
+    compact?: boolean;
+    /** When true, skip own border/bg since the parent card provides them. */
+    embedded?: boolean;
+}) {
+    const containerRef = useRef<HTMLDivElement>(null);
+    const [containerWidth, setContainerWidth] = useState<number | null>(null);
+
+    React.useLayoutEffect(() => {
+        if (!containerRef.current) return;
+        // Read initial width synchronously before paint
+        setContainerWidth(containerRef.current.offsetWidth);
+        const observer = new ResizeObserver((entries) => {
+            for (const entry of entries) {
+                setContainerWidth(entry.contentRect.width);
+            }
+        });
+        observer.observe(containerRef.current);
+        return () => observer.disconnect();
+    }, []);
+
+    const mainValue = data[config.value.field];
+    const formattedValue = typeof mainValue === "number"
+        ? formatNumber(mainValue, config.value.format)
+        : String(mainValue ?? "N/A");
+
+    // Comparison rendering
+    let comparisonElement: React.ReactNode = null;
+    if (config.comparison) {
+        const comparisonValue = data[config.comparison.field];
+        if (typeof comparisonValue === "number") {
+            const formattedComparison = formatNumber(comparisonValue, config.comparison.format);
+            const isPositive = comparisonValue > 0;
+            const isNegative = comparisonValue < 0;
+
+            let colorClass = "text-surface-500 dark:text-surface-400";
+            if (config.comparison.intent === "increase_is_good") {
+                if (isPositive) colorClass = "text-emerald-500";
+                if (isNegative) colorClass = "text-red-500";
+            } else if (config.comparison.intent === "decrease_is_good") {
+                if (isPositive) colorClass = "text-red-500";
+                if (isNegative) colorClass = "text-emerald-500";
+            }
+
+            comparisonElement = (
+                <span className={`font-medium ${compact ? "text-[10px]" : "text-xs"} ${colorClass}`}>
+                    {formattedComparison}
+                </span>
+            );
+        }
+    }
+
+    const isSmall = compact || (containerWidth !== null && containerWidth < 200);
+
+    // Resolve icon via getIcon (Lucide-based resolution)
+    const iconElement = config.icon
+        ? getIcon(config.icon, "text-surface-400 dark:text-surface-500", undefined, isSmall ? 14 : 18)
+        : null;
+
+    // ── Compact card-inline layout ──────────────────────────────────────
+    if (compact) {
+        return (
+            <div className={cls("flex flex-col gap-0.5 px-2.5 py-2 rounded-md bg-transparent border min-w-0", defaultBorderMixin)}>
+                <span className="text-[10px] uppercase tracking-wider text-surface-400 dark:text-surface-500 truncate">
+                    {title}
+                </span>
+                <div className="flex items-baseline gap-1.5">
+                    <span className="text-sm font-semibold tabular-nums text-surface-800 dark:text-surface-100">
+                        {formattedValue}
+                    </span>
+                    {comparisonElement}
+                </div>
+            </div>
+        );
+    }
+
+    // ── Standard scorecard layout ───────────────────────────────────────
+    const baseClass = embedded
+        ? `flex flex-col min-w-0 h-full ${isSmall ? "px-3.5 py-3" : "px-5 py-4"}`
+        : cls("rounded-lg flex flex-col min-w-0 bg-transparent border", defaultBorderMixin, isSmall ? "px-3.5 py-3" : "px-5 py-4");
+
+    return (
+        <div ref={containerRef} className={baseClass} style={embedded ? undefined : { minHeight: isSmall ? 68 : 92 }}>
+            {/* Title row */}
+            <div className={`flex items-center justify-between ${isSmall ? "mb-1" : "mb-2"}`}>
+                <div className="flex flex-col min-w-0">
+                    <span className={`font-medium leading-snug truncate text-surface-500 dark:text-surface-400 ${isSmall ? "text-[11px]" : "text-xs"}`}>
+                        {title}
+                    </span>
+                    {config.dateRange && !isSmall && (
+                        <span className="text-[10px] text-surface-400 dark:text-surface-500 truncate mt-0.5">
+                            {config.dateRange}
+                        </span>
+                    )}
+                </div>
+                {iconElement && (
+                    <span className="ml-2 shrink-0">{iconElement}</span>
+                )}
+            </div>
+
+            {/* Main value */}
+            <div className={`font-semibold leading-tight tracking-tight break-all text-surface-800 dark:text-surface-100 ${isSmall ? "text-lg" : (containerWidth !== null && containerWidth < 300) ? "text-xl" : "text-2xl"}`}>
+                {formattedValue}
+            </div>
+
+            {/* Comparison */}
+            {comparisonElement && (
+                <div className={isSmall ? "mt-0.5" : "mt-1"}>
+                    {comparisonElement}
+                </div>
+            )}
+        </div>
+    );
+}
+
+InsightsScorecardView.displayName = "InsightsScorecardView";

package/src/engine/InsightsCache.ts

@@ -0,0 +1,52 @@
+import type { InsightDataResult } from "../types";
+
+interface CacheEntry {
+    data: InsightDataResult;
+    timestamp: number;
+}
+
+/**
+ * In-memory cache for insight query results.
+ * Supports TTL-based expiry and inflight request deduplication
+ * to prevent redundant network requests when multiple widgets
+ * share the same query.
+ */
+export class InsightsCache {
+    private cache = new Map<string, CacheEntry>();
+    private inflight = new Map<string, Promise<InsightDataResult>>();
+
+    constructor(private ttl: number = 60_000) {}
+
+    get(key: string): InsightDataResult | null {
+        const entry = this.cache.get(key);
+        if (!entry) return null;
+        if (Date.now() - entry.timestamp > this.ttl) {
+            this.cache.delete(key);
+            return null;
+        }
+        return entry.data;
+    }
+
+    set(key: string, data: InsightDataResult): void {
+        this.cache.set(key, { data, timestamp: Date.now() });
+        this.inflight.delete(key);
+    }
+
+    getInflight(key: string): Promise<InsightDataResult> | null {
+        return this.inflight.get(key) ?? null;
+    }
+
+    setInflight(key: string, promise: Promise<InsightDataResult>): void {
+        this.inflight.set(key, promise);
+    }
+
+    invalidate(key?: string): void {
+        if (key) {
+            this.cache.delete(key);
+            this.inflight.delete(key);
+        } else {
+            this.cache.clear();
+            this.inflight.clear();
+        }
+    }
+}

package/src/engine/InsightsProvider.tsx

@@ -0,0 +1,38 @@
+import React, { createContext, useContext, useMemo, type PropsWithChildren } from "react";
+import { InsightsCache } from "./InsightsCache";
+
+interface InsightsContextValue {
+    cache: InsightsCache;
+}
+
+const InsightsContext = createContext<InsightsContextValue | null>(null);
+
+/**
+ * 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.
+ */
+export function InsightsProvider({
+    cacheTTL,
+    children
+}: PropsWithChildren<{ cacheTTL?: number }>) {
+    const cache = useMemo(() => new InsightsCache(cacheTTL), [cacheTTL]);
+    const value = useMemo(() => ({ cache }), [cache]);
+
+    return (
+        <InsightsContext.Provider value={value}>
+            {children}
+        </InsightsContext.Provider>
+    );
+}
+
+/**
+ * Access the insights cache (for advanced usage).
+ * Returns null when called outside of an `InsightsProvider`
+ * (e.g. during auth-loading phase before plugin providers mount).
+ */
+export function useInsightsEngine(): InsightsContextValue | null {
+    return useContext(InsightsContext);
+}