@rebasepro/plugin-insights 0.17.3 → 0.18.1

package/src/components/InsightWidgetSkeleton.tsx

@@ -1,218 +0,0 @@
-import React, { useRef, useState } 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.
- *
- * 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 function InsightWidgetSkeleton({
-    config,
-    compact = false,
-    embedded = false,
-    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;
-    /** Explicit height to prevent layout shift between skeleton → loaded. */
-    fixedHeight?: number;
-}) {
-    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 ─────────────────────────────────────
-    return <StandardSkeleton
-        hasComparison={hasComparison}
-        hasIcon={hasIcon}
-        hasDateRange={hasDateRange}
-        embedded={embedded}
-        fixedHeight={fixedHeight}
-    />;
-}
-
-// ── Tailwind line-height reference ──────────────────────────────────────
-// All heights below are the **computed** CSS line-heights, accounting
-// for `leading-*` overrides that InsightsScorecardView applies.
-//
-// Title:
-//   text-xs (12px) + leading-snug (1.375)  → 12 × 1.375 = 16.5px
-//   text-[11px]    + leading-snug (1.375)  → 11 × 1.375 = 15.125px
-//
-// DateRange:
-//   text-[10px] with no explicit LH        → normal ≈ 14px (browser)
-//
-// Value:
-//   text-2xl (24px) + leading-tight (1.25) → 24 × 1.25 = 30px
-//   text-xl  (20px) + leading-tight (1.25) → 20 × 1.25 = 25px
-//   text-lg  (18px) + leading-tight (1.25) → 18 × 1.25 = 22.5px
-//
-// Comparison:
-//   text-xs (12px)  → built-in LH 1rem     = 16px
-
-/**
- * Inner component for the standard scorecard skeleton.
- *
- * Mirrors InsightsScorecardView's layout by:
- * 1. Using the same ResizeObserver + containerWidth pattern for
- *    responsive breakpoints (isSmall < 200px, isMedium < 300px).
- * 2. Using placeholder heights derived from the exact computed
- *    Tailwind line-heights that InsightsScorecardView renders.
- * 3. Matching all container classes, margins, paddings, and flex
- *    layout properties identically.
- */
-function StandardSkeleton({
-    hasComparison,
-    hasIcon,
-    hasDateRange,
-    embedded,
-    fixedHeight
-}: {
-    hasComparison: boolean;
-    hasIcon: boolean;
-    hasDateRange: boolean;
-    embedded: boolean;
-    fixedHeight?: number;
-}) {
-    const containerRef = useRef<HTMLDivElement>(null);
-    const [containerWidth, setContainerWidth] = useState<number | null>(null);
-
-    React.useLayoutEffect(() => {
-        if (!containerRef.current) return;
-        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();
-    }, []);
-
-    // Mirror InsightsScorecardView's responsive breakpoints exactly
-    const isSmall = containerWidth !== null && containerWidth < 200;
-
-    // Computed line-heights for each breakpoint
-    // Title: text-xs + leading-snug = 16.5px, text-[11px] + leading-snug = 15.125px
-    const titleHeight = isSmall ? 15 : 16.5;
-    // Value: leading-tight (×1.25) applied on top of font-size
-    const valueHeight = isSmall
-        ? 22.5 // text-lg: 18 × 1.25
-        : (containerWidth !== null && containerWidth < 300)
-            ? 25 // text-xl: 20 × 1.25
-            : 30; // text-2xl: 24 × 1.25
-    // Comparison: text-xs = 12px / 16px line-height (no leading override)
-    const comparisonHeight = 16;
-    // Icon: 14px when small, 18px otherwise
-    const iconSize = isSmall ? 14 : 18;
-
-    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={cls("animate-pulse", baseClass)}
-            style={embedded ? undefined : fixedHeight ? { height: fixedHeight } : { minHeight: isSmall ? 68 : 92 }}
-        >
-            {/* Title row — identical flex structure to InsightsScorecardView */}
-            <div className={`flex items-center justify-between ${isSmall ? "mb-1" : "mb-2"}`}>
-                <div className="flex flex-col min-w-0">
-                    {/* Title placeholder */}
-                    <div className="bg-surface-200 dark:bg-surface-700 rounded"
-                        style={{ height: titleHeight,
-width: "60%" }}
-                    />
-                    {/* DateRange — hidden when isSmall, same as real view (line 134) */}
-                    {hasDateRange && !isSmall && (
-                        <div className="bg-surface-200/60 dark:bg-surface-700/60 rounded mt-0.5"
-                            style={{ height: 14,
-width: "40%" }}
-                        />
-                    )}
-                </div>
-                {/* Icon placeholder — same wrapper as real view */}
-                {hasIcon && (
-                    <span className="ml-2 shrink-0">
-                        <div className="bg-surface-200 dark:bg-surface-700 rounded"
-                            style={{ height: iconSize,
-width: iconSize }}
-                        />
-                    </span>
-                )}
-            </div>
-
-            {/* Main value placeholder */}
-            <div className="bg-surface-200 dark:bg-surface-700 rounded"
-                style={{ height: valueHeight,
-width: "40%" }}
-            />
-
-            {/* Comparison placeholder */}
-            {hasComparison && (
-                <div className={isSmall ? "mt-0.5" : "mt-1"}>
-                    <div className="bg-surface-200/60 dark:bg-surface-700/60 rounded"
-                        style={{ height: comparisonHeight,
-width: "25%" }}
-                    />
-                </div>
-            )}
-        </div>
-    );
-}
-
-InsightWidgetSkeleton.displayName = "InsightWidgetSkeleton";

package/src/components/InsightsScorecardView.tsx

@@ -1,169 +0,0 @@
-import React, { useRef, useState } from "react";
-import { getIcon } from "@rebasepro/app";
-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"
-    };
-
-    // Only pin the fraction digits when the config asks for a specific count.
-    // Without this, Intl's per-style defaults apply: integers stay integers
-    // ("80", not "80.0") while currency keeps its two decimals ("$452.95").
-    if (format?.decimals !== undefined) {
-        options.maximumFractionDigits = format.decimals;
-        options.minimumFractionDigits = format.decimals;
-    }
-
-    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/app`.
- */
-export function InsightsScorecardView({
-    config,
-    data,
-    title,
-    compact = false,
-    embedded = false,
-    fixedHeight
-}: {
-    config: ScorecardConfig;
-    data: DataRow;
-    title: string;
-    compact?: boolean;
-    /** When true, skip own border/bg since the parent card provides them. */
-    embedded?: boolean;
-    /** Explicit height to prevent layout shift between skeleton → loaded. */
-    fixedHeight?: number;
-}) {
-    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 : fixedHeight ? { height: fixedHeight } : { 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.test.ts

@@ -1,53 +0,0 @@
-import { InsightsCache } from "./InsightsCache";
-import type { InsightDataResult } from "../types";
-
-describe("InsightsCache", () => {
-    it("should set and get values from cache", () => {
-        const cache = new InsightsCache();
-        const data: InsightDataResult = {
-            rows: [{ count: 10 }]
-        };
-        cache.set("query_key", data);
-        expect(cache.get("query_key")).toEqual(data);
-    });
-
-    it("should return null for expired keys", () => {
-        const cache = new InsightsCache(-1); // -1ms TTL to force immediate expiry
-        const data: InsightDataResult = {
-            rows: [{ count: 10 }]
-        };
-        cache.set("query_key", data);
-        // Expired immediately
-        expect(cache.get("query_key")).toBeNull();
-    });
-
-    it("should manage inflight requests", () => {
-        const cache = new InsightsCache();
-        const promise = Promise.resolve<InsightDataResult>({
-            rows: []
-        });
-        expect(cache.getInflight("query_key")).toBeNull();
-
-        cache.setInflight("query_key", promise);
-        expect(cache.getInflight("query_key")).toBe(promise);
-
-        // Setting a result should remove the inflight reference
-        const data: InsightDataResult = { rows: [] };
-        cache.set("query_key", data);
-        expect(cache.getInflight("query_key")).toBeNull();
-    });
-
-    it("should invalidate entries", () => {
-        const cache = new InsightsCache();
-        const data: InsightDataResult = { rows: [] };
-        cache.set("key_1", data);
-        cache.set("key_2", data);
-
-        cache.invalidate("key_1");
-        expect(cache.get("key_1")).toBeNull();
-        expect(cache.get("key_2")).toEqual(data);
-
-        cache.invalidate();
-        expect(cache.get("key_2")).toBeNull();
-    });
-});

package/src/engine/InsightsCache.ts

@@ -1,53 +0,0 @@
-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 = 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

@@ -1,38 +0,0 @@
-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);
-}

package/src/engine/useInsightsData.ts

@@ -1,103 +0,0 @@
-import { useEffect, useState } from "react";
-import type { InsightDefinition, InsightDataResult, InsightContext } from "../types";
-import { useInsightsEngine } from "./InsightsProvider";
-import { useAuthController } from "@rebasepro/app";
-
-/**
- * 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,
-    context: InsightContext
-): {
-    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}:${context.path ?? context.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(context);
-
-        cache.setInflight(cacheKey, promise);
-
-        promise
-            .then((result) => {
-                cache.set(cacheKey, result);
-                if (!cancelled) {
-                    setData(result);
-                }
-            })
-            .catch((err) => {
-                cache.invalidate(cacheKey);
-                if (!cancelled) {
-                    setError(err instanceof Error ? err : new Error(String(err)));
-                }
-            })
-            .finally(() => {
-                if (!cancelled) setLoading(false);
-            });
-
-        return () => {
-            cancelled = true;
-        };
-    }, [definition.id, definition.data, context.path, context.collectionSlug, cacheKey, cache, authReady]);
-
-    return { data,
-loading,
-error };
-}

package/src/index.ts

@@ -1,22 +0,0 @@
-// ── 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";