@papermap/papermap 1.0.2 → 1.0.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/index.d.mts +12 -12
- package/dist/index.d.ts +12 -12
- package/dist/index.js +30 -36
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +27 -33
- package/dist/index.mjs.map +1 -1
- package/package.json +10 -3
- package/readme.md +70 -70
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@papermap/papermap",
|
|
3
|
-
"version": "1.0.
|
|
3
|
+
"version": "1.0.4",
|
|
4
4
|
"description": "Embeddable AI chat bar and UI components from the Papermap data analytics platform",
|
|
5
5
|
"main": "./dist/index.js",
|
|
6
6
|
"module": "./dist/index.mjs",
|
|
@@ -31,6 +31,8 @@
|
|
|
31
31
|
"ts-check": "tsc --noEmit",
|
|
32
32
|
"format": "prettier --write \"src/**/*.{ts,tsx}\"",
|
|
33
33
|
"format:check": "prettier --check \"src/**/*.{ts,tsx}\"",
|
|
34
|
+
"test": "vitest run",
|
|
35
|
+
"test:watch": "vitest",
|
|
34
36
|
"validate": "npm run lint && npm run ts-check",
|
|
35
37
|
"validate:watch": "npm run validate -- --watch",
|
|
36
38
|
"clean": "rm -rf dist styles.css",
|
|
@@ -64,7 +66,7 @@
|
|
|
64
66
|
"@radix-ui/react-tooltip": "^1.2.8",
|
|
65
67
|
"@tanstack/react-query": "^5.22.2",
|
|
66
68
|
"@tanstack/react-table": "^8.21.3",
|
|
67
|
-
"axios": "1.
|
|
69
|
+
"axios": "1.8.2",
|
|
68
70
|
"class-variance-authority": "^0.7.1",
|
|
69
71
|
"clsx": "^2.1.1",
|
|
70
72
|
"framer-motion": "^11.17.0",
|
|
@@ -87,6 +89,9 @@
|
|
|
87
89
|
"@storybook/blocks": "^8.6.14",
|
|
88
90
|
"@storybook/react": "^8.6.18",
|
|
89
91
|
"@storybook/react-vite": "^8.6.18",
|
|
92
|
+
"@testing-library/jest-dom": "^6.9.1",
|
|
93
|
+
"@testing-library/react": "^16.3.2",
|
|
94
|
+
"@testing-library/user-event": "^14.6.1",
|
|
90
95
|
"@types/react": "^18.3.18",
|
|
91
96
|
"@types/react-dom": "^18.3.5",
|
|
92
97
|
"@types/react-syntax-highlighter": "^15.5.13",
|
|
@@ -100,6 +105,7 @@
|
|
|
100
105
|
"eslint-plugin-react": "^7.37.4",
|
|
101
106
|
"eslint-plugin-react-hooks": "^5.1.0",
|
|
102
107
|
"husky": "^9.1.7",
|
|
108
|
+
"jsdom": "^29.0.2",
|
|
103
109
|
"lint-staged": "^15.3.0",
|
|
104
110
|
"playwright": "^1.58.2",
|
|
105
111
|
"postcss": "^8.5.8",
|
|
@@ -111,7 +117,8 @@
|
|
|
111
117
|
"tailwindcss-animate": "^1.0.7",
|
|
112
118
|
"tsup": "^8.4.0",
|
|
113
119
|
"typescript": "^5.7.3",
|
|
114
|
-
"vite": "^6.4.1"
|
|
120
|
+
"vite": "^6.4.1",
|
|
121
|
+
"vitest": "^4.1.3"
|
|
115
122
|
},
|
|
116
123
|
"engines": {
|
|
117
124
|
"node": ">=18"
|
package/readme.md
CHANGED
|
@@ -2,24 +2,28 @@
|
|
|
2
2
|
|
|
3
3
|
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.
|
|
4
4
|
|
|
5
|
+
## Backend setup
|
|
6
|
+
|
|
7
|
+
For **server-side setup** (HMAC auth, dashboards per tenant, embed tokens, API endpoints), see the [Backend implementation guide](https://docs.papermap.ai/documentation/multi-tenancy/backend) in the Papermap docs.
|
|
8
|
+
|
|
5
9
|
## Main components
|
|
6
10
|
|
|
7
|
-
- **`
|
|
8
|
-
- **`
|
|
9
|
-
- **`
|
|
11
|
+
- **`PaperChat`** — Full AI chat assistant with streaming, conversation history, and chart generation.
|
|
12
|
+
- **`PaperCard`** — Standalone chart card with toolbar actions. Use `variant="streaming"` for an embedded chart + conversation dialog (without the floating assistant).
|
|
13
|
+
- **`PaperBoard`** — Responsive grid layout of chart cards, toolbar (screenshot, generate dashboard, theme), optional chat assistant, and controlled or uncontrolled layouts.
|
|
10
14
|
|
|
11
15
|
```tsx
|
|
12
|
-
import {
|
|
16
|
+
import { PaperChat, PaperCard, PaperBoard } from '@papermap/papermap'
|
|
13
17
|
|
|
14
18
|
// AI chat assistant
|
|
15
|
-
<
|
|
19
|
+
<PaperChat
|
|
16
20
|
token="your-base64-api-token"
|
|
17
21
|
workspaceId="your-workspace-id"
|
|
18
22
|
dashboardId="your-dashboard-id"
|
|
19
23
|
/>
|
|
20
24
|
|
|
21
25
|
// Standalone chart card
|
|
22
|
-
<
|
|
26
|
+
<PaperCard
|
|
23
27
|
token="your-base64-api-token"
|
|
24
28
|
workspaceId="your-workspace-id"
|
|
25
29
|
dashboardId="your-dashboard-id"
|
|
@@ -27,7 +31,7 @@ import { PapermapChat, PapermapChartCard, PapermapGridDashboard } from '@paperma
|
|
|
27
31
|
/>
|
|
28
32
|
|
|
29
33
|
// Streaming chart card (embedded dialog + chat)
|
|
30
|
-
<
|
|
34
|
+
<PaperCard
|
|
31
35
|
token="your-base64-api-token"
|
|
32
36
|
workspaceId="your-workspace-id"
|
|
33
37
|
dashboardId="your-dashboard-id"
|
|
@@ -35,8 +39,8 @@ import { PapermapChat, PapermapChartCard, PapermapGridDashboard } from '@paperma
|
|
|
35
39
|
chartId="your-chart-id" // optional; card shows empty state if omitted
|
|
36
40
|
/>
|
|
37
41
|
|
|
38
|
-
// Full grid dashboard (wraps chart cards + optional
|
|
39
|
-
<
|
|
42
|
+
// Full grid dashboard (wraps chart cards + optional PaperChat)
|
|
43
|
+
<PaperBoard
|
|
40
44
|
token="..."
|
|
41
45
|
workspaceId="..."
|
|
42
46
|
dashboardId="..."
|
|
@@ -73,11 +77,7 @@ import '@papermap/papermap/styles.css'
|
|
|
73
77
|
`PapermapConfigProvider` is an alias for `PapermapProvider` — same component, useful for naming consistency in app code.
|
|
74
78
|
|
|
75
79
|
```tsx
|
|
76
|
-
import {
|
|
77
|
-
PapermapConfigProvider,
|
|
78
|
-
PapermapChat,
|
|
79
|
-
PapermapChartCard,
|
|
80
|
-
} from '@papermap/papermap'
|
|
80
|
+
import { PapermapConfigProvider, PaperChat, PaperCard } from '@papermap/papermap'
|
|
81
81
|
|
|
82
82
|
function App() {
|
|
83
83
|
return (
|
|
@@ -87,8 +87,8 @@ function App() {
|
|
|
87
87
|
dashboardId="your-dashboard-id"
|
|
88
88
|
// optional: apiUrl="https://dataapi.papermap.ai"
|
|
89
89
|
>
|
|
90
|
-
<
|
|
91
|
-
<
|
|
90
|
+
<PaperChat />
|
|
91
|
+
<PaperCard chartId="existing-chat-id" />
|
|
92
92
|
</PapermapConfigProvider>
|
|
93
93
|
)
|
|
94
94
|
}
|
|
@@ -99,18 +99,18 @@ function App() {
|
|
|
99
99
|
Pass `token`, `workspaceId`, and `dashboardId` on each component (or rely on an existing parent `PapermapProvider`).
|
|
100
100
|
|
|
101
101
|
```tsx
|
|
102
|
-
import {
|
|
102
|
+
import { PaperChat, PaperCard } from '@papermap/papermap'
|
|
103
103
|
|
|
104
104
|
function App() {
|
|
105
105
|
return (
|
|
106
106
|
<>
|
|
107
|
-
<
|
|
107
|
+
<PaperChat
|
|
108
108
|
token="your-base64-api-token"
|
|
109
109
|
workspaceId="your-workspace-id"
|
|
110
110
|
dashboardId="your-dashboard-id"
|
|
111
111
|
/>
|
|
112
112
|
|
|
113
|
-
<
|
|
113
|
+
<PaperCard
|
|
114
114
|
token="your-base64-api-token"
|
|
115
115
|
workspaceId="your-workspace-id"
|
|
116
116
|
dashboardId="your-dashboard-id"
|
|
@@ -123,47 +123,47 @@ function App() {
|
|
|
123
123
|
|
|
124
124
|
### 4. Props
|
|
125
125
|
|
|
126
|
-
#### `
|
|
127
|
-
|
|
128
|
-
| Prop | Type
|
|
129
|
-
| ------------- |
|
|
130
|
-
| `token` | `string`
|
|
131
|
-
| `workspaceId` | `string`
|
|
132
|
-
| `dashboardId` | `string`
|
|
133
|
-
| `apiUrl` | `string`
|
|
134
|
-
| `theme` | `'light' \| 'dark'`
|
|
135
|
-
| `placeholder` | `string`
|
|
136
|
-
| `shortcutKey` | `string`
|
|
137
|
-
| `autoFade` | `boolean`
|
|
138
|
-
| `fadeDelay` | `number`
|
|
139
|
-
| `className` | `string`
|
|
126
|
+
#### `PaperChat` props
|
|
127
|
+
|
|
128
|
+
| Prop | Type | Required | Default | Description |
|
|
129
|
+
| ------------- | ------------------- | -------- | ----------------------------- | ------------------------------------ |
|
|
130
|
+
| `token` | `string` | Yes\* | -- | Base64-encoded API key token |
|
|
131
|
+
| `workspaceId` | `string` | Yes\* | -- | Workspace ID |
|
|
132
|
+
| `dashboardId` | `string` | Yes\* | -- | Dashboard ID |
|
|
133
|
+
| `apiUrl` | `string` | No | `https://dataapi.papermap.ai` | API base URL |
|
|
134
|
+
| `theme` | `'light' \| 'dark'` | No | -- | Force light or dark theme |
|
|
135
|
+
| `placeholder` | `string` | No | `"Ask anything..."` | Input placeholder text |
|
|
136
|
+
| `shortcutKey` | `string` | No | `"k"` | Keyboard shortcut (Cmd/Ctrl + key) |
|
|
137
|
+
| `autoFade` | `boolean` | No | `false` | Fade toolbar after inactivity |
|
|
138
|
+
| `fadeDelay` | `number` | No | `5000` | Milliseconds before auto-fade |
|
|
139
|
+
| `className` | `string` | No | -- | Extra CSS class on toolbar container |
|
|
140
140
|
|
|
141
141
|
\*Omit on the component when values come from `PapermapConfigProvider` / `PapermapProvider`.
|
|
142
142
|
|
|
143
|
-
#### `
|
|
144
|
-
|
|
145
|
-
| Prop | Type
|
|
146
|
-
| -------------- |
|
|
147
|
-
| `token` | `string`
|
|
148
|
-
| `workspaceId` | `string`
|
|
149
|
-
| `dashboardId` | `string`
|
|
150
|
-
| `apiUrl` | `string`
|
|
151
|
-
| `chartId` | `string`
|
|
152
|
-
| `chart` | `TChartResponse`
|
|
153
|
-
| `theme` | `'light' \| 'dark'`
|
|
154
|
-
| `onEditClick` | `(chartId: string) => void`
|
|
155
|
-
| `onDelete` | `(chartId: string) => void`
|
|
156
|
-
| `onPinChange` | `(chartId: string, pinned: boolean) => void` | No
|
|
157
|
-
| `wide` | `boolean`
|
|
158
|
-
| `hideVariants` | `boolean`
|
|
159
|
-
| `showToolbar` | `boolean`
|
|
160
|
-
| `className` | `string`
|
|
161
|
-
| `variant` | `'default' \| 'streaming'`
|
|
143
|
+
#### `PaperCard` props
|
|
144
|
+
|
|
145
|
+
| Prop | Type | Required | Default | Description |
|
|
146
|
+
| -------------- | -------------------------------------------- | -------- | ----------------------------- | ------------------------------------------------ |
|
|
147
|
+
| `token` | `string` | Yes\* | -- | Base64-encoded API key token |
|
|
148
|
+
| `workspaceId` | `string` | Yes\* | -- | Workspace ID |
|
|
149
|
+
| `dashboardId` | `string` | Yes\* | -- | Dashboard ID |
|
|
150
|
+
| `apiUrl` | `string` | No | `https://dataapi.papermap.ai` | API base URL |
|
|
151
|
+
| `chartId` | `string` | No | -- | Backend chat id to load the latest chart for |
|
|
152
|
+
| `chart` | `TChartResponse` | No | -- | Pre-loaded chart data (skips API fetch) |
|
|
153
|
+
| `theme` | `'light' \| 'dark'` | No | -- | Force light or dark theme |
|
|
154
|
+
| `onEditClick` | `(chartId: string) => void` | No | -- | Called when the edit button is clicked |
|
|
155
|
+
| `onDelete` | `(chartId: string) => void` | No | -- | Called when chart deletion is confirmed |
|
|
156
|
+
| `onPinChange` | `(chartId: string, pinned: boolean) => void` | No | -- | Called when pin state changes |
|
|
157
|
+
| `wide` | `boolean` | No | `false` | Wide mode for table charts |
|
|
158
|
+
| `hideVariants` | `boolean` | No | `true` | Hide the chart variation selector |
|
|
159
|
+
| `showToolbar` | `boolean` | No | `true` | Show toolbar with maximize/edit/delete buttons |
|
|
160
|
+
| `className` | `string` | No | -- | Extra CSS class on the card container |
|
|
161
|
+
| `variant` | `'default' \| 'streaming'` | No | `'default'` | `'streaming'`: edit opens embedded dialog + chat |
|
|
162
162
|
|
|
163
163
|
**Pre-loaded chart:**
|
|
164
164
|
|
|
165
165
|
```tsx
|
|
166
|
-
import {
|
|
166
|
+
import { PaperCard } from '@papermap/papermap'
|
|
167
167
|
import type { TChartResponse } from '@papermap/papermap'
|
|
168
168
|
|
|
169
169
|
const chart: TChartResponse = {
|
|
@@ -183,7 +183,7 @@ const chart: TChartResponse = {
|
|
|
183
183
|
},
|
|
184
184
|
}
|
|
185
185
|
|
|
186
|
-
<
|
|
186
|
+
<PaperCard
|
|
187
187
|
token="..."
|
|
188
188
|
workspaceId="..."
|
|
189
189
|
dashboardId="..."
|
|
@@ -193,32 +193,32 @@ const chart: TChartResponse = {
|
|
|
193
193
|
/>
|
|
194
194
|
```
|
|
195
195
|
|
|
196
|
-
#### `
|
|
196
|
+
#### `PaperBoard` props (high level)
|
|
197
197
|
|
|
198
|
-
| Prop
|
|
199
|
-
|
|
|
200
|
-
| `token`, `workspaceId`, `dashboardId`, `apiUrl`
|
|
201
|
-
| `charts`
|
|
202
|
-
| `layouts` / `onLayoutsChange`
|
|
203
|
-
| `isEditMode`, `editLayout`, `isViewer`
|
|
204
|
-
| `showToolbar`, `showScreenshot`, `showGenerateDashboard`, `showHeader`, `showChatAssistant` | Feature toggles.
|
|
205
|
-
| `variant`
|
|
206
|
-
| `dashboardTheme`, `onDashboardThemeChange`, `persistWorkspaceTheme`, `renderThemeModal`
|
|
207
|
-
| Callbacks
|
|
198
|
+
| Prop | Notes |
|
|
199
|
+
| ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
|
|
200
|
+
| `token`, `workspaceId`, `dashboardId`, `apiUrl` | Same as other components; can come from provider. |
|
|
201
|
+
| `charts` | Optional pre-loaded charts; otherwise fetched when `enableFetch` is true (default). |
|
|
202
|
+
| `layouts` / `onLayoutsChange` | Controlled grid layouts per breakpoint. |
|
|
203
|
+
| `isEditMode`, `editLayout`, `isViewer` | Edit vs view behavior. |
|
|
204
|
+
| `showToolbar`, `showScreenshot`, `showGenerateDashboard`, `showHeader`, `showChatAssistant` | Feature toggles. |
|
|
205
|
+
| `variant` | `'default' \| 'streaming'` for embedded chart cards (matches `PaperCard`). |
|
|
206
|
+
| `dashboardTheme`, `onDashboardThemeChange`, `persistWorkspaceTheme`, `renderThemeModal` | Theming; built-in modal uses `ThemeCustomizationSettings`. |
|
|
207
|
+
| Callbacks | `onEditChart`, `onDeleteChart`, `onPinChange`, `onGenerateDashboard`, `onTakeScreenshot`, `onThemeModalOpen`, etc. |
|
|
208
208
|
|
|
209
|
-
See TypeScript types `
|
|
209
|
+
See TypeScript types `PaperBoardProps` and Storybook stories for full detail.
|
|
210
210
|
|
|
211
211
|
### Streaming chart card variant
|
|
212
212
|
|
|
213
213
|
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.
|
|
214
214
|
|
|
215
215
|
```tsx
|
|
216
|
-
import {
|
|
216
|
+
import { PaperCard } from '@papermap/papermap'
|
|
217
217
|
|
|
218
218
|
export function EmbeddedStreamingChart() {
|
|
219
219
|
return (
|
|
220
220
|
<div className="h-[420px] w-[520px]">
|
|
221
|
-
<
|
|
221
|
+
<PaperCard
|
|
222
222
|
token="..."
|
|
223
223
|
workspaceId="..."
|
|
224
224
|
dashboardId="..."
|
|
@@ -255,7 +255,7 @@ For custom layouts, the package also exports subcomponents (for example `ChatAss
|
|
|
255
255
|
|
|
256
256
|
- Set `apiUrl` on the provider or per component. Default is `https://dataapi.papermap.ai`.
|
|
257
257
|
|
|
258
|
-
### Charts do not appear in `
|
|
258
|
+
### Charts do not appear in `PaperCard`
|
|
259
259
|
|
|
260
260
|
- Pass a valid backend `chartId` (chat id), or supply preloaded `chart` data.
|
|
261
261
|
|
|
@@ -291,7 +291,7 @@ The library decodes it and sends these headers on API requests:
|
|
|
291
291
|
3. SSE connects to `POST /api/v1/analytics/requests/stream` for live updates; HTTP remains a fallback.
|
|
292
292
|
4. History: `GET /api/v1/analytics/chats/{id}/conversations`, dashboard recent chats, and full chart history per chat as needed.
|
|
293
293
|
|
|
294
|
-
### What users see in `
|
|
294
|
+
### What users see in `PaperChat`
|
|
295
295
|
|
|
296
296
|
- Floating input bar (portaled to `document.body`), Cmd/Ctrl+K to focus, Escape to dismiss.
|
|
297
297
|
- Expanding input, backdrop, conversation panel, stop during load, new chat, scroll and history pagination.
|