@papermap/papermap 1.1.1 → 1.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@papermap/papermap",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "description": "Embeddable AI chat bar and UI components from the Papermap data analytics platform",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",

package/readme.md

@@ -10,10 +10,11 @@ For **server-side setup** (HMAC auth, dashboards per tenant, embed tokens, API e
 
 - **`PaperChat`** — Full AI chat assistant with streaming, conversation history, and chart generation. Supports four layouts: **default** (floating toolbar + modal assistant), **side** (fixed side panel for sheet-style pages), **floating** (chart preview overlay), and **dialog** (tawk.to-style floating launcher + popup chat widget).
 - **`PaperCard`** — Standalone chart card with toolbar actions. Use `variant="streaming"` for an embedded chart + conversation dialog (without the floating assistant).
-- **`PaperBoard`** — Responsive grid layout of chart cards, toolbar (screenshot, generate dashboard, theme), optional chat assistant, and controlled or uncontrolled layouts.
+- **`PaperInsight`** — "Quick Insights" panel: streams up to 3 AI-generated insights (highlight / trends / recommendation) for a dashboard + date range.
+- **`PaperBoard`** — Responsive grid layout of chart cards, toolbar (screenshot, generate dashboard, theme), optional chat assistant + `PaperInsight` tile, and controlled or uncontrolled layouts.
 
 ```tsx
-import { PaperChat, PaperCard, PaperBoard } from '@papermap/papermap'
+import { PaperChat, PaperCard, PaperInsight, PaperBoard } from '@papermap/papermap'
 
 // Default: floating toolbar + expandable assistant (dashboard-style)
 <PaperChat
@@ -71,12 +72,22 @@ import { PaperChat, PaperCard, PaperBoard } from '@papermap/papermap'
   chartId="your-chart-id" // optional; card shows empty state if omitted
 />
 
-// Full grid dashboard (wraps chart cards + optional PaperChat)
+// Standalone Quick Insights panel (streams 3 AI insights for the period)
+<PaperInsight
+  token="your-base64-api-token"
+  workspaceId="your-workspace-id"
+  dashboardId="your-dashboard-id"
+  startDate="2026-04-25"
+  endDate="2026-05-25"
+/>
+
+// Full grid dashboard (wraps chart cards + optional PaperChat + insight tile)
 <PaperBoard
   token="..."
   workspaceId="..."
   dashboardId="..."
   showChatAssistant
+  showInsights
 />
 ```
 
@@ -329,6 +340,36 @@ const chart: TChartResponse = {
 />
 ```
 
+#### `PaperInsight` props
+
+| Prop                      | Type                                               | Required | Default                       | Description                                                                                                                                 |
+| ------------------------- | -------------------------------------------------- | -------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `token`                   | `string`                                           | Yes\*    | --                            | Base64-encoded API key token                                                                                                                |
+| `workspaceId`             | `string`                                           | Yes\*    | --                            | Workspace ID                                                                                                                                |
+| `dashboardId`             | `string`                                           | Yes\*    | --                            | Dashboard ID                                                                                                                                |
+| `apiUrl`                  | `string`                                           | No       | `https://dataapi.papermap.ai` | API base URL                                                                                                                                |
+| `startDate`               | `Date \| string` (`yyyy-MM-dd`)                    | Yes      | --                            | Inclusive start of the insight window                                                                                                       |
+| `endDate`                 | `Date \| string` (`yyyy-MM-dd`)                    | Yes      | --                            | Inclusive end of the insight window                                                                                                         |
+| `theme`                   | `'light' \| 'dark' \| 'system'`                    | No       | --                            | Scoped color scheme (independent of host page)                                                                                              |
+| `dashboardTheme`          | `DashboardTheme \| null`                           | No       | --                            | Themed mark color + module surface (matches main app workspace theme)                                                                       |
+| `isEditMode`              | `boolean`                                          | No       | `false`                       | Disable interactions while a parent grid is in layout-edit mode                                                                             |
+| `periodPreset`            | `InsightsPeriodPreset`                             | No       | --                            | Show the period dropdown (`last_3_months \| this_week \| this_month \| this_year \| custom`). Hide by omitting.                             |
+| `onPeriodPresetChange`    | `(preset: InsightsPeriodPreset) => void`           | No       | --                            | Fired when the user picks a preset                                                                                                          |
+| `onRangeChange`           | `(start: Date, end: Date) => void`                 | No       | --                            | Required for the inline custom-range scrubber to function — the host owns the dates and updates them when this fires                        |
+| `showCustomRangeScrubber` | `boolean`                                          | No       | `true`                        | Render the inline `TimelineRange` scrubber when `periodPreset === 'custom'`. Set `false` when a parent (e.g. `PaperBoard`) renders its own. |
+| `onExplore`               | `(chatId: string) => void`                         | No       | (opens chat assistant)        | Per-row "Explore in Chat" arrow. Defaults to calling `openPapermapChatAssistant` when a store is mounted.                                   |
+| `onInsight`               | `(insight: DashboardInsight) => void`              | No       | --                            | Fired once per `insight` SSE event                                                                                                          |
+| `onComplete`              | `(result: DashboardInsightsResult) => void`        | No       | --                            | Fired when the server emits `insights_complete`                                                                                             |
+| `onError`                 | `(error: Error) => void`                           | No       | --                            | Fired on transport / `error` SSE event                                                                                                      |
+| `className`               | `string`                                           | No       | --                            | Root element class                                                                                                                          |
+| `style`                   | `CSSProperties`                                    | No       | --                            | Root element inline style                                                                                                                   |
+| `classNames`              | `Partial<Record<PaperInsightSlot, string>>`        | No       | --                            | Per-slot class overrides (`header`, `title`, `dateLabel`, `refreshButton`, `row`, `body`, `footer`, …)                                      |
+| `styles`                  | `Partial<Record<PaperInsightSlot, CSSProperties>>` | No       | --                            | Per-slot inline style overrides                                                                                                             |
+
+\*Omit on the component when values come from `PapermapProvider`.
+
+The SSE call is `POST /api/v1/analytics/dashboards/:dashboardId/insights/stream` with body `{ start_date, end_date }`. The component renders the panel's chrome (Activity icon, "Quick Insights" title, animated `TickSpinner` + cycling "Thinking… / Crunching… / Cooking…", optional period dropdown, Refresh button) and up to 3 streamed insights with metric chips and an "Explore in Chat" arrow.
+
 #### `PaperBoard` props (high level)
 
 | Prop                                                                                        | Notes                                                                                                              |
@@ -338,6 +379,10 @@ const chart: TChartResponse = {
 | `layouts` / `onLayoutsChange`                                                               | Controlled grid layouts per breakpoint.                                                                            |
 | `isEditMode`, `editLayout`, `isViewer`                                                      | Edit vs view behavior.                                                                                             |
 | `showToolbar`, `showScreenshot`, `showGenerateDashboard`, `showHeader`, `showChatAssistant` | Feature toggles.                                                                                                   |
+| `showInsights`                                                                              | Mount the `PaperInsight` tile at the top of the grid (mirrors main app `TimelineInsights`).                        |
+| `insightsPeriodPreset`, `onInsightsPeriodPresetChange`                                      | Controlled period for the insight tile. Defaults internally to `'last_3_months'`.                                  |
+| `insightsStartDate`, `insightsEndDate`                                                      | Controlled range overrides (use with `'custom'` to drive the dashboard `TimelineRange` scrubber from the host).    |
+| `onInsightExplore`                                                                          | Per-row "Explore in Chat" arrow. Defaults to opening the floating chat assistant when one is mounted.              |
 | `variant`                                                                                   | `'default' \| 'streaming'` for embedded chart cards (matches `PaperCard`).                                         |
 | `dashboardTheme`, `onDashboardThemeChange`, `persistWorkspaceTheme`, `renderThemeModal`     | Theming; built-in modal uses `ThemeCustomizationSettings`.                                                         |
 | Callbacks                                                                                   | `onEditChart`, `onDeleteChart`, `onPinChange`, `onGenerateDashboard`, `onTakeScreenshot`, `onThemeModalOpen`, etc. |
@@ -564,6 +609,112 @@ Refetch host state after a chart is pinned or the embedded assistant closes.
 />
 ```
 
+### PaperInsight
+
+#### Minimal — fixed date range
+
+```tsx
+<PaperInsight
+  token="..."
+  workspaceId="..."
+  dashboardId="..."
+  startDate="2026-04-25"
+  endDate="2026-05-25"
+/>
+```
+
+#### With period dropdown + custom-range scrubber
+
+When `periodPreset === 'custom'` the inline `TimelineRange` scrubber renders between the header and the insight rows; dragging it fires `onRangeChange`.
+
+```tsx
+import {
+  PaperInsight,
+  computeInsightsPeriodRange,
+  type InsightsPeriodPreset,
+  type InsightsPeriodMenuPreset,
+} from '@papermap/papermap'
+
+function MyInsights() {
+  const [preset, setPreset] = useState<InsightsPeriodPreset>('last_3_months')
+  const [range, setRange] = useState(() => computeInsightsPeriodRange('last_3_months'))
+
+  return (
+    <PaperInsight
+      token="..."
+      workspaceId="..."
+      dashboardId="..."
+      startDate={range.start}
+      endDate={range.end}
+      periodPreset={preset}
+      onPeriodPresetChange={(next) => {
+        setPreset(next)
+        if (next !== 'custom') {
+          setRange(computeInsightsPeriodRange(next as InsightsPeriodMenuPreset))
+        }
+      }}
+      onRangeChange={(start, end) => {
+        setRange({ start, end })
+        setPreset('custom')
+      }}
+    />
+  )
+}
+```
+
+#### Wire "Explore in Chat" to the floating assistant
+
+`PaperInsight` defaults `onExplore` to `openPapermapChatAssistant(storeApi, { editChartId: chatId })` whenever a `PapermapProvider` is mounted. Override to route somewhere else (e.g. your own router).
+
+```tsx
+<PaperInsight
+  token="..."
+  workspaceId="..."
+  dashboardId="..."
+  startDate="2026-04-25"
+  endDate="2026-05-25"
+  onExplore={(chatId) => router.push(`/dashboard?conversation_id=${chatId}`)}
+/>
+```
+
+#### Custom styling via slots
+
+```tsx
+<PaperInsight
+  token="..."
+  workspaceId="..."
+  dashboardId="..."
+  startDate="2026-04-25"
+  endDate="2026-05-25"
+  className="rounded-2xl shadow-xl"
+  classNames={{
+    title: 'font-serif text-amber-200',
+    refreshButton: 'bg-amber-500 text-black hover:bg-amber-400',
+    row: 'hover:bg-amber-500/10',
+  }}
+  styles={{
+    body: { paddingInline: 24 },
+  }}
+/>
+```
+
+#### Listen to stream events (analytics)
+
+```tsx
+<PaperInsight
+  token="..."
+  workspaceId="..."
+  dashboardId="..."
+  startDate="2026-04-25"
+  endDate="2026-05-25"
+  onInsight={(insight) => track('insight_received', { type: insight.insightType })}
+  onComplete={(result) => track('insights_complete', { count: result.insights.length })}
+  onError={(err) => Sentry.captureException(err)}
+/>
+```
+
+---
+
 ### PaperBoard
 
 #### Default streaming grid
@@ -649,9 +800,60 @@ Adds an opt-in tour button to the header (does not auto-start).
 />
 ```
 
+#### With the Quick Insights tile
+
+`showInsights` mounts the `PaperInsight` tile at the top of the grid and renders the dashboard-level `TimelineRange` scrubber between the header and the grid when the user picks `Custom range`. The insight tile and the scrubber share the same preset / range state internally.
+
+```tsx
+<PaperBoard
+  token="..."
+  workspaceId="..."
+  dashboardId="..."
+  variant="streaming"
+  showToolbar
+  showChatAssistant
+  showInsights
+/>
+```
+
+Pass a controlled preset / range if the host owns the dashboard timeline:
+
+```tsx
+import {
+  PaperBoard,
+  computeInsightsPeriodRange,
+  type InsightsPeriodPreset,
+  type InsightsPeriodMenuPreset,
+} from '@papermap/papermap'
+
+function MyDashboard() {
+  const [preset, setPreset] = useState<InsightsPeriodPreset>('last_3_months')
+  const [range, setRange] = useState(() => computeInsightsPeriodRange('last_3_months'))
+
+  return (
+    <PaperBoard
+      token="..."
+      workspaceId="..."
+      dashboardId="..."
+      showInsights
+      insightsPeriodPreset={preset}
+      onInsightsPeriodPresetChange={(next) => {
+        setPreset(next)
+        if (next !== 'custom') {
+          setRange(computeInsightsPeriodRange(next as InsightsPeriodMenuPreset))
+        }
+      }}
+      insightsStartDate={range.start}
+      insightsEndDate={range.end}
+      onInsightExplore={(chatId) => router.push(`?conversation_id=${chatId}`)}
+    />
+  )
+}
+```
+
 ---
 
-## Advanced exports
+<!-- ## Advanced exports
 
 For custom layouts, the package also exports:
 
@@ -659,10 +861,15 @@ For custom layouts, the package also exports:
 - **Store:** `usePapermapStore`, `usePapermapStoreApi`, `createPapermapStore`, `PapermapProvider`, `CHAT_MODAL_TAB`, and **`openPapermapChatAssistant(storeApi, options?)`** — opens/focuses the assistant and optionally primes edit mode from a chart (`editChartId`, `chart`, `suppressOpen` for embedded streaming UIs).
 - **Hooks:** `useAnalyticsStream`, `useKeyboardShortcuts`, `useAutoResize`, `useAutoFade`, `useTour`, …
 - **API:** `createApiClient`, `decodeToken`, `buildAuthHeaders`, `papermapQueryKeys`
+- **Insights:**
+  - **Component:** `PaperInsight`, slot types (`PaperInsightSlot`, `PaperInsightClassNames`, `PaperInsightStyles`)
+  - **Service:** `streamDashboardInsights`, `normalizeInsightType`, `orderInsightsForDisplay`, `formatInsightDate`, `parseInsightMetricToTrend` — and types `DashboardInsight`, `DashboardInsightType`, `DashboardInsightsResult`, `StreamDashboardInsightsOptions`.
+  - **Period helpers:** `computeInsightsPeriodRange`, `formatInsightsDateLabel`, `INSIGHTS_PERIOD_LABELS`, `INSIGHTS_PERIOD_SELECT_OPTIONS`, types `InsightsPeriodPreset`, `InsightsPeriodMenuPreset`.
+  - **Grid layout:** `PAPER_INSIGHT_GRID_ID`, `ensurePaperInsightLayoutItem(layouts, gridId, defaults?)` — inject the insight slot into custom `PaperBoardLayouts`.
 - **Types:** streaming (`TimelineEvent`, `ToolCall`, …), charts (`TChartResponse`, …), messages
 - **Theming:** `themePresets`, `defaultTheme`, `ThemeCustomizationSettings`
 - **Persistence:** chart card `id` ↔ backend chat id helpers (`getChartCardIdLink`, `resolveChartFetchChatId`, …)
-- **Platform (hosts / extensions):** `PAPERMAP_SDK_VERSION`, `PAPERMAP_PLUGIN_CONTRACT_VERSION`, `checkPluginPeerCompatibility`, `createPluginContext`, `createPapermapObservability`, and related types
+- **Platform (hosts / extensions):** `PAPERMAP_SDK_VERSION`, `PAPERMAP_PLUGIN_CONTRACT_VERSION`, `checkPluginPeerCompatibility`, `createPluginContext`, `createPapermapObservability`, and related types -->
 
 All paths use the package entry: `@papermap/papermap`.