@papermap/papermap 1.0.1 → 1.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@papermap/papermap",
-  "version": "1.0.1",
+  "version": "1.0.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

@@ -1,15 +1,15 @@
 # Papermap
 
-Embeddable AI-powered components from the [Papermap](https://www.papermap.ai) data analytics platform. This is a standalone package -- **completely independent** from the main Papermap app. Services, SSE streaming, and UI are all self-contained; the two repos do not link or depend on each other.
+Embeddable AI-powered components from the [Papermap](https://www.papermap.ai) data analytics platform. This is a standalone package — **independent** from the main Papermap app. Services, SSE streaming, and UI are self-contained; the repos do not depend on each other.
 
-Two main components are available:
+## Main components
 
-- **`PapermapChat`** -- Full AI chat assistant with streaming, conversation history, and chart generation.
-- **`PapermapChartCard`** -- Standalone chart card for embedding individual charts with toolbar actions.
-- **`PapermapChartCard` (streaming variant)** -- Chart card variant that expands into an embedded chart + conversation dialog (without opening the floating assistant UI).
+- **`PapermapChat`** — Full AI chat assistant with streaming, conversation history, and chart generation.
+- **`PapermapChartCard`** — Standalone chart card with toolbar actions. Use `variant="streaming"` for an embedded chart + conversation dialog (without the floating assistant).
+- **`PapermapGridDashboard`** — Responsive grid layout of chart cards, toolbar (screenshot, generate dashboard, theme), optional chat assistant, and controlled or uncontrolled layouts.
 
 ```tsx
-import { PapermapChat, PapermapChartCard } from 'papermap'
+import { PapermapChat, PapermapChartCard, PapermapGridDashboard } from '@papermap/papermap'
 
 // AI chat assistant
 <PapermapChat
@@ -32,36 +32,52 @@ import { PapermapChat, PapermapChartCard } from 'papermap'
   workspaceId="your-workspace-id"
   dashboardId="your-dashboard-id"
   variant="streaming"
-  chartId="your-chart-id" // optional; card stays visible with empty state if omitted
+  chartId="your-chart-id" // optional; card shows empty state if omitted
+/>
+
+// Full grid dashboard (wraps chart cards + optional PapermapChat)
+<PapermapGridDashboard
+  token="..."
+  workspaceId="..."
+  dashboardId="..."
+  showChatAssistant
 />
 ```
 
-Both components handle everything internally -- API calls, authentication, state, and the full UI.
+Each top-level component handles API calls, authentication, and UI internally unless you compose lower-level exports yourself.
 
 ---
 
-## Quick Start
+## Quick start
 
 ### 1. Install
 
 ```bash
-npm install papermap
+npm install @papermap/papermap
 # or
-pnpm add papermap
+pnpm add @papermap/papermap
 ```
 
+**Requirements:** React 18+ and React DOM 18+ (peer dependencies).
+
 ### 2. Import styles once
 
 ```tsx
-import 'papermap/styles.css'
+import '@papermap/papermap/styles.css'
 ```
 
-### 3. Pick one integration mode
+### 3. Choose an integration pattern
+
+#### A) Recommended: provider at app root
 
-#### A) Recommended: one-time provider at app root
+`PapermapConfigProvider` is an alias for `PapermapProvider` — same component, useful for naming consistency in app code.
 
 ```tsx
-import { PapermapConfigProvider, PapermapChat, PapermapChartCard } from 'papermap'
+import {
+  PapermapConfigProvider,
+  PapermapChat,
+  PapermapChartCard,
+} from '@papermap/papermap'
 
 function App() {
   return (
@@ -78,10 +94,12 @@ function App() {
 }
 ```
 
-#### B) Drop-in standalone components (no provider required)
+#### B) Standalone components (no provider)
+
+Pass `token`, `workspaceId`, and `dashboardId` on each component (or rely on an existing parent `PapermapProvider`).
 
 ```tsx
-import { PapermapChat, PapermapChartCard } from 'papermap'
+import { PapermapChat, PapermapChartCard } from '@papermap/papermap'
 
 function App() {
   return (
@@ -105,14 +123,14 @@ function App() {
 
 ### 4. Props
 
-#### `PapermapChat` Props
+#### `PapermapChat` 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                         |
+| `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                         |
 | `theme`       | `'light' \| 'dark'`    | No       | --                                | Force light or dark theme            |
 | `placeholder` | `string`               | No       | `"Ask anything..."`               | Input placeholder text               |
 | `shortcutKey` | `string`               | No       | `"k"`                             | Keyboard shortcut (Cmd/Ctrl + key)   |
@@ -120,31 +138,33 @@ function App() {
 | `fadeDelay`   | `number`               | No       | `5000`                            | Milliseconds before auto-fade        |
 | `className`   | `string`               | No       | --                                | Extra CSS class on toolbar container |
 
-#### `PapermapChartCard` Props
+\*Omit on the component when values come from `PapermapConfigProvider` / `PapermapProvider`.
+
+#### `PapermapChartCard` 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                                                          |
-| `chartId`      | `string`                                 | No       | --                                | Chat ID to fetch the latest chart for                                 |
-| `chart`        | `TChartResponse`                         | No       | --                                | Pre-loaded chart data (skips API fetch)                               |
+| `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                                                          |
+| `chartId`      | `string`                                 | No       | --                                | Backend chat id to load the latest chart for                          |
+| `chart`        | `TChartResponse`                         | No       | --                                | Pre-loaded chart data (skips API fetch)                             |
 | `theme`        | `'light' \| 'dark'`                      | No       | --                                | Force light or dark theme                                             |
 | `onEditClick`  | `(chartId: string) => void`              | No       | --                                | Called when the edit button is clicked                                |
-| `onDelete`     | `(chartId: string) => void`              | No       | --                                | Called when chart deletion is confirmed                                |
+| `onDelete`     | `(chartId: string) => void`              | No       | --                                | Called when chart deletion is confirmed                               |
 | `onPinChange`  | `(chartId: string, pinned: boolean) => void` | No   | --                                | Called when pin state changes                                         |
 | `wide`         | `boolean`                                | No       | `false`                           | Wide mode for table charts                                            |
 | `hideVariants` | `boolean`                                | No       | `true`                            | Hide the chart variation selector                                     |
-| `showToolbar`  | `boolean`                                | No       | `true`                            | Show toolbar with maximize/edit/delete buttons                         |
-| `className`    | `string`                                 | No       | --                                | Extra CSS class on the card container                                  |
-| `variant`      | `'default' \| 'streaming'`               | No       | `'default'`                       | When `'streaming'`, edit opens an embedded dialog + chat experience   |
+| `showToolbar`  | `boolean`                                | No       | `true`                            | Show toolbar with maximize/edit/delete buttons                        |
+| `className`    | `string`                                 | No       | --                                | Extra CSS class on the card container                                 |
+| `variant`      | `'default' \| 'streaming'`               | No       | `'default'`                       | `'streaming'`: edit opens embedded dialog + chat                      |
 
-**Usage with pre-loaded data:**
+**Pre-loaded chart:**
 
 ```tsx
-import { PapermapChartCard } from 'papermap'
-import type { TChartResponse } from 'papermap'
+import { PapermapChartCard } from '@papermap/papermap'
+import type { TChartResponse } from '@papermap/papermap'
 
 const chart: TChartResponse = {
   llm_data_chat_id: 'my-chart-id',
@@ -173,27 +193,27 @@ const chart: TChartResponse = {
 />
 ```
 
-**Usage with API fetch:**
+#### `PapermapGridDashboard` props (high level)
 
-```tsx
-<PapermapChartCard
-  token="..."
-  workspaceId="..."
-  dashboardId="..."
-  chartId="existing-chat-id"
-/>
-```
+| Prop | Notes |
+| ---- | ----- |
+| `token`, `workspaceId`, `dashboardId`, `apiUrl` | Same as other components; can come from provider. |
+| `charts` | Optional pre-loaded charts; otherwise fetched when `enableFetch` is true (default). |
+| `layouts` / `onLayoutsChange` | Controlled grid layouts per breakpoint. |
+| `isEditMode`, `editLayout`, `isViewer` | Edit vs view behavior. |
+| `showToolbar`, `showScreenshot`, `showGenerateDashboard`, `showHeader`, `showChatAssistant` | Feature toggles. |
+| `variant` | `'default' \| 'streaming'` for embedded chart cards (matches `PapermapChartCard`). |
+| `dashboardTheme`, `onDashboardThemeChange`, `persistWorkspaceTheme`, `renderThemeModal` | Theming; built-in modal uses `ThemeCustomizationSettings`. |
+| Callbacks | `onEditChart`, `onDeleteChart`, `onPinChange`, `onGenerateDashboard`, `onTakeScreenshot`, `onThemeModalOpen`, etc. |
+
+See TypeScript types `PapermapGridDashboardProps` and Storybook stories for full detail.
 
 ### Streaming chart card variant
 
-When `variant="streaming"`, clicking the edit icon opens an **embedded** expanded view (`StreamingChartDialog`) with:
-- Chart + conversation side-by-side (chat always available)
-- SSE streaming support
-- Save-to-dashboard + maximize chart actions
-- Audit Log (execution replay) on assistant messages
+With `variant="streaming"`, the edit action opens an embedded expanded view with chart + conversation, SSE streaming, save-to-dashboard and maximize actions, and audit log on assistant messages.
 
 ```tsx
-import { PapermapChartCard } from 'papermap'
+import { PapermapChartCard } from '@papermap/papermap'
 
 export function EmbeddedStreamingChart() {
   return (
@@ -203,40 +223,49 @@ export function EmbeddedStreamingChart() {
         workspaceId="..."
         dashboardId="..."
         variant="streaming"
-        chartId="existing-chat-id" // optional; without it the card shows a create-chart empty state
+        chartId="existing-chat-id"
       />
     </div>
   )
 }
 ```
 
-**Supported chart types:** `bar`, `line`, `area`, `pie`, `radar`, `scatter`, `table`, `tile` -- matching the main Papermap app.
+**Supported chart types:** `bar`, `line`, `area`, `pie`, `radar`, `scatter`, `table`, `tile` — aligned with the main Papermap app.
+
+---
+
+## Advanced exports
+
+For custom layouts, the package also exports subcomponents (for example `ChatAssistant`, `StreamingChartDialog`, `ChartView`, `DataTable`), Zustand store helpers (`usePapermapStore`, `createPapermapStore`), hooks (`useAnalyticsStream`, …), API helpers (`createApiClient`, `decodeToken`, `buildAuthHeaders`), streaming and chart types, **theme presets** (`themePresets`, `defaultTheme`, `ThemeCustomizationSettings`), and **chart card id ↔ chat id** persistence helpers (`getChartCardIdLink`, `resolveChartFetchChatId`, …). Import paths are the same as the main entry: `@papermap/papermap`.
 
 ---
 
 ## Troubleshooting
 
-### "Cannot find module 'papermap/styles.css'"
-- Make sure you are on a version that exports `./styles.css`.
-- Reinstall dependencies after upgrading the package.
+### Cannot find module `@papermap/papermap/styles.css`
+
+- Use the scoped package name and the `./styles.css` export.
+- Reinstall after upgrading.
 
 ### "Papermap... requires token/workspaceId/dashboardId"
-- Provide connection values once via `PapermapConfigProvider`, or
-- Pass them directly to each standalone component.
 
-### Requests are hitting the wrong backend
-- Set `apiUrl` explicitly in `PapermapConfigProvider` (or per component).
-- Default base URL is `https://dataapi.papermap.ai`.
+- Provide values once via `PapermapConfigProvider` / `PapermapProvider`, or pass them on each component.
+
+### Requests hit the wrong backend
+
+- Set `apiUrl` on the provider or per component. Default is `https://dataapi.papermap.ai`.
 
 ### Charts do not appear in `PapermapChartCard`
-- Pass a valid backend `chartId` (chat id), or
-- Provide preloaded `chart` data directly.
 
-## How It Works
+- Pass a valid backend `chartId` (chat id), or supply preloaded `chart` data.
+
+---
+
+## How it works
 
 ### Authentication
 
-The `token` prop is a base64-encoded JSON:
+The `token` prop is base64-encoded JSON:
 
 ```json
 {
@@ -247,7 +276,7 @@ The `token` prop is a base64-encoded JSON:
 }
 ```
 
-The component decodes it and sets these headers on every API request:
+The library decodes it and sends these headers on API requests:
 
 - `X-API-Key-ID`
 - `X-Workspace-ID`
@@ -255,42 +284,21 @@ The component decodes it and sets these headers on every API request:
 - `X-Signature`
 - `X-Tenant-ID: da-app`
 
-### Data Flow
-
-1. User types a message and hits Enter
-2. Component creates a chat via `POST /api/v1/analytics/chats` (if first message)
-3. Message is sent via `POST /api/v1/analytics/charts/stream` with SSE enabled
-4. SSE connection opens to `POST /api/v1/analytics/requests/stream` for real-time updates (agent thoughts, tool calls, phases)
-5. HTTP response serves as fallback if SSE fails
-6. Conversation history is loaded via `GET /api/v1/analytics/chats/{id}/conversations`
-7. Recent chat history for a dashboard is loaded via `GET /api/v1/analytics/chats-history`
-8. Full chart history for a chat is loaded via `GET /api/v1/analytics/chats/{id}/get-all-charts`
-
-### What the User Sees
-
-- A floating input bar fixed at the bottom-center (portaled to `document.body`)
-- Cmd/Ctrl+K to focus, Escape to dismiss
-- Single-line input that expands to multiline when text overflows
-- Backdrop overlay + conversation panel when focused
-- Submit button (arrow-up) becomes stop button (square) during loading
-- New Chat button to start fresh conversations
-- Auto-scroll, pagination on scroll-up for history
-- Recent conversations panel with infinite scroll + delete actions
-- Per-chat chart history panel, including pinning and meta updates
-- Inline feedback (thumbs up / down) on responses, with optional branching to new chats
-- Optional streaming view that shows real-time phases, thoughts, and tool calls (toggled via "View Execution")
-- Model selector and search-the-web actions integrated into the toolbar
+### Chat data flow (overview)
 
----
+1. User sends a message; first message may create a chat via `POST /api/v1/analytics/chats`.
+2. Message goes to `POST /api/v1/analytics/charts/stream` with SSE.
+3. SSE connects to `POST /api/v1/analytics/requests/stream` for live updates; HTTP remains a fallback.
+4. History: `GET /api/v1/analytics/chats/{id}/conversations`, dashboard recent chats, and full chart history per chat as needed.
 
----
+### What users see in `PapermapChat`
 
-## Future Growth
+- Floating input bar (portaled to `document.body`), Cmd/Ctrl+K to focus, Escape to dismiss.
+- Expanding input, backdrop, conversation panel, stop during load, new chat, scroll and history pagination.
+- Recent conversations, per-chat chart history, feedback, optional execution view, model selector, and related toolbar actions.
 
-This package is designed to grow. Current exports:
+---
 
-```tsx
-import { PapermapChat, PapermapChartCard } from 'papermap'
-```
+## Roadmap
 
-Future embeddings (e.g. `Dashboard`, `DataExplorer`) will follow the same pattern -- self-contained components with `token`/`workspaceId`/`dashboardId` props and optional callbacks.
+Additional embeddable surfaces (for example richer explorers) will follow the same pattern: self-contained components with `token` / `workspaceId` / `dashboardId` and optional callbacks, exported from `@papermap/papermap`.