@rebasepro/plugin-insights 0.17.3 → 0.18.1

package/src/types/engine.ts

@@ -1,95 +0,0 @@
-import type { DataRow, ScorecardConfig } from "./widgets";
-
-export interface InsightContext {
-    /** The resolved path of the collection (e.g., "products/123/orders" or "orders") */
-    path?: string;
-    parentCollectionSlugs?: string[];
-    /** The parent entity IDs if this is a subcollection (e.g., ["123"]) */
-    parentEntityIds?: string[];
-    /** The collection slug if this is an insight at the collection level */
-    collectionSlug?: string;
-}
-
-/**
- * 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: (context: InsightContext) => 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

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

package/src/types/widgets.ts

@@ -1,66 +0,0 @@
-/**
- * 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

@@ -1,129 +0,0 @@
-import React from "react";
-import type { RebasePlugin, SlotContribution } from "@rebasepro/cms-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.widgets` slot
- * - **Home page cards**: Compact scorecard metrics auto-extracted from collection insights via `home.card.widget` 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;
-
-    return React.useMemo(() => {
-        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.widgets   → inline scorecards in the list view
-        // 2. home.card.widget     → 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.widgets" 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;
-
-                        // Skip relation-scoped views (e.g. a single product's Orders
-                        // tab). These aggregations are collection-wide — `InsightContext`
-                        // carries no parent entity id, so a definition cannot narrow to
-                        // the parent — and rendering "Revenue $36.2K" above one product's
-                        // two orders reads as a figure for those orders.
-                        const parentEntityIds = props.parentEntityIds as string[] | undefined;
-                        if (parentEntityIds && parentEntityIds.length > 0) return null;
-
-                        return (
-                            <CollectionInsightsInline
-                                {...props as { path: string; collection: unknown; parentCollectionSlugs: string[], parentEntityIds: string[] }}
-                                insights={collectionInsights}
-                            />
-                        );
-                    },
-                    order: 10
-                });
-
-                // 2. Auto-extract scorecards for home page card
-                slots.push({
-                    slot: "home.card.widget" 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 }
-                }
-            ]
-        };
-    }, [insights, cacheTTL]);
-}