@rebasepro/plugin-insights 0.3.0 → 0.5.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/common/src/collections/default-collections.d.ts

@@ -1,12 +1,9 @@
-import { PostgresCollection } from "@rebasepro/types";
+import type { PostgresCollection } from "@rebasepro/types";
 /**
- * Default users collection definition.
+ * Default users collection.
  *
- * Shared between the admin UI (for navigation/display) and the backend
- * (for schema generation). Both consumers prepend this to the developer's
- * collections array and rely on generic slug-based deduplication
- * (Map keyed by slug, last-write-wins) so that developer-defined
- * collections with the same slug override this default — no hardcoded
- * string checks required.
+ * Prepended to the developer's collections array by the admin and server.
+ * Slug-based dedup (Map keyed by slug, last-write-wins) lets developers
+ * override by defining their own collection with `slug: "users"`.
  */
 export declare const defaultUsersCollection: PostgresCollection;

package/dist/common/src/data/query_builder.d.ts

@@ -1,4 +1,7 @@
-import { FindResponse, CollectionAccessor, QueryBuilderInterface, FilterOperator } from "@rebasepro/types";
+import { FindResponse, CollectionAccessor, QueryBuilderInterface, FilterOperator, LogicalCondition, WhereValue, FilterCondition } from "@rebasepro/types";
+export declare function or(...conditions: (FilterCondition | LogicalCondition)[]): LogicalCondition;
+export declare function and(...conditions: (FilterCondition | LogicalCondition)[]): LogicalCondition;
+export declare function cond(column: string, operator: FilterOperator, value: unknown): FilterCondition;
 export declare class QueryBuilder<M extends Record<string, unknown> = Record<string, unknown>> implements QueryBuilderInterface<M> {
     private collection;
     private params;
@@ -8,7 +11,8 @@ export declare class QueryBuilder<M extends Record<string, unknown> = Record<str
      * @example
      * client.collection('users').where('age', '>=', 18).find()
      */
-    where(column: keyof M & string, operator: FilterOperator, value: unknown): this;
+    where<K extends keyof M & string>(column: K, operator: FilterOperator, value: WhereValue<M[K]>): this;
+    where(logicalCondition: LogicalCondition): this;
     /**
      * Order the results by a specific column.
      * @example

package/dist/common/src/util/permissions.d.ts

@@ -1,6 +1,14 @@
-import { AuthController, Entity, EntityCollection, User } from "@rebasepro/types";
-export declare function checkOperation<M extends Record<string, unknown>, USER extends User>(collection: EntityCollection<M>, authController: AuthController<USER>, entity: Entity<M> | null, targetOperation: "select" | "insert" | "update" | "delete"): boolean;
-export declare function canReadCollection<M extends Record<string, unknown>, USER extends User>(collection: EntityCollection<M>, authController: AuthController<USER>): boolean;
-export declare function canEditEntity<M extends Record<string, unknown>, USER extends User>(collection: EntityCollection<M>, authController: AuthController<USER>, path: string, entity: Entity<M> | null): boolean;
-export declare function canCreateEntity<M extends Record<string, unknown>, USER extends User>(collection: EntityCollection<M>, authController: AuthController<USER>, path: string, entity: Entity<M> | null): boolean;
-export declare function canDeleteEntity<M extends Record<string, unknown>, USER extends User>(collection: EntityCollection<M>, authController: AuthController<USER>, path: string, entity: Entity<M> | null): boolean;
+import { Entity, EntityCollection, User } from "@rebasepro/types";
+/**
+ * Minimal auth context for permission checking.
+ * Only requires the user object — avoids forcing callers to construct
+ * a full AuthController just to check permissions.
+ */
+export interface AuthContext<USER extends User = User> {
+    user: USER | null;
+}
+export declare function checkOperation<M extends Record<string, unknown>, USER extends User>(collection: EntityCollection<M>, authContext: AuthContext<USER>, entity: Entity<M> | null, targetOperation: "select" | "insert" | "update" | "delete"): boolean;
+export declare function canReadCollection<M extends Record<string, unknown>, USER extends User>(collection: EntityCollection<M>, authContext: AuthContext<USER>): boolean;
+export declare function canEditEntity<M extends Record<string, unknown>, USER extends User>(collection: EntityCollection<M>, authContext: AuthContext<USER>, path: string, entity: Entity<M> | null): boolean;
+export declare function canCreateEntity<M extends Record<string, unknown>, USER extends User>(collection: EntityCollection<M>, authContext: AuthContext<USER>, path: string, entity: Entity<M> | null): boolean;
+export declare function canDeleteEntity<M extends Record<string, unknown>, USER extends User>(collection: EntityCollection<M>, authContext: AuthContext<USER>, path: string, entity: Entity<M> | null): boolean;

package/dist/core/src/components/LoginView/LoginView.d.ts

@@ -92,10 +92,18 @@ export interface LoginViewProps {
      * If not set, derived from `authController.capabilities.registration`.
      */
     registrationEnabled?: boolean;
+    /**
+     * Pre-fill the email field (e.g. for demo or testing environments).
+     */
+    defaultEmail?: string;
+    /**
+     * Pre-fill the password field (e.g. for demo or testing environments).
+     */
+    defaultPassword?: string;
 }
 /**
  * Generic login view component that works with any AuthControllerExtended.
  * Feature-detects capabilities to show/hide login methods.
  * @group Core
  */
-export declare function LoginView({ logo, authController, noUserComponent, disableSignupScreen, disabled, notAllowedError, googleClientId, githubClientId, linkedinClientId, title, subtitle, needsSetup, registrationEnabled, additionalComponent }: LoginViewProps): import("react/jsx-runtime").JSX.Element;
+export declare function LoginView({ logo, authController, noUserComponent, disableSignupScreen, disabled, notAllowedError, googleClientId, githubClientId, linkedinClientId, title, subtitle, needsSetup, registrationEnabled, additionalComponent, defaultEmail, defaultPassword }: LoginViewProps): import("react/jsx-runtime").JSX.Element;

package/dist/core/src/components/common/types.d.ts

@@ -1,4 +1,4 @@
-import type { Property } from "@rebasepro/types";
+import type { Property, Entity } from "@rebasepro/types";
 import { CollectionSize, SelectedCellProps } from "@rebasepro/types";
 export type EntityCollectionTableController<M extends Record<string, unknown>> = {
     /**
@@ -26,7 +26,7 @@ export type EntityCollectionTableController<M extends Record<string, unknown>> =
      * Callback used when the value of a cell has changed.
      * @param params
      */
-    onValueChange?: (params: OnCellValueChangeParams<unknown, M>) => void;
+    onValueChange?: (params: OnCellValueChangeParams<unknown, Entity<M>>) => void;
     /**
      * Size of the elements in the collection
      */
@@ -56,7 +56,7 @@ export type UniqueFieldValidator = (props: {
  * Callback when a cell has changed in a table
  * @group Collection components
  */
-export type OnCellValueChange<T, M extends Record<string, unknown>> = (params: OnCellValueChangeParams<T, M>) => Promise<void> | void;
+export type OnCellValueChange<T, M extends Record<string, unknown>> = (params: OnCellValueChangeParams<T, Entity<M>>) => Promise<void> | void;
 /**
  * @group Collection components
  */

package/dist/core/src/hooks/data/useCollectionFetch.d.ts

@@ -16,6 +16,14 @@ export interface CollectionFetchProps<M extends Record<string, any>> {
      * Number of entities to fetch
      */
     itemCount?: number;
+    /**
+     * Number of items to skip
+     */
+    offset?: number;
+    /**
+     * Page number (1-indexed), alternative to offset
+     */
+    page?: number;
     /**
      * Filter the fetched data by the property
      */
@@ -37,6 +45,7 @@ export interface CollectionFetchResult<M extends Record<string, any>> {
     dataLoading: boolean;
     noMoreToLoad: boolean;
     dataLoadingError?: Error;
+    totalCount?: number;
 }
 /**
  * This hook is used to fetch collections using a given collection
@@ -45,7 +54,9 @@ export interface CollectionFetchResult<M extends Record<string, any>> {
  * @param filterValues
  * @param sortBy
  * @param itemCount
+ * @param offset
+ * @param page
  * @param searchString
  * @group Hooks and utilities
  */
-export declare function useCollectionFetch<M extends Record<string, any>, USER extends User>({ path, collection, filterValues, sortBy, itemCount, searchString }: CollectionFetchProps<M>): CollectionFetchResult<M>;
+export declare function useCollectionFetch<M extends Record<string, any>, USER extends User>({ path, collection, filterValues, sortBy, itemCount, offset, page, searchString }: CollectionFetchProps<M>): CollectionFetchResult<M>;