@papermap/papermap 1.0.1

package/package.json

@@ -0,0 +1,122 @@
+{
+  "name": "@papermap/papermap",
+  "version": "1.0.1",
+  "description": "Embeddable AI chat bar and UI components from the Papermap data analytics platform",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    },
+    "./styles.css": "./styles.css"
+  },
+  "style": "./styles.css",
+  "sideEffects": [
+    "*.css"
+  ],
+  "files": [
+    "dist",
+    "styles.css"
+  ],
+  "scripts": {
+    "build": "tsup && npm run build:styles",
+    "build:styles": "cp src/styles.css styles.css",
+    "dev": "tsup --watch",
+    "storybook": "storybook dev -p 3001",
+    "build-storybook": "storybook build",
+    "lint": "npx eslint src --ext .ts,.tsx",
+    "ts-check": "tsc --noEmit",
+    "format": "prettier --write \"src/**/*.{ts,tsx}\"",
+    "format:check": "prettier --check \"src/**/*.{ts,tsx}\"",
+    "validate": "npm run lint && npm run ts-check",
+    "validate:watch": "npm run validate -- --watch",
+    "clean": "rm -rf dist styles.css",
+    "prepare": "husky || true",
+    "changeset": "changeset",
+    "version-packages": "changeset version",
+    "release": "npm run build && changeset publish"
+  },
+  "lint-staged": {
+    "*.{ts,tsx}": [
+      "prettier --write",
+      "eslint --fix"
+    ]
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "dependencies": {
+    "@radix-ui/react-collapsible": "^1.1.12",
+    "@radix-ui/react-dialog": "^1.1.15",
+    "@radix-ui/react-dropdown-menu": "^2.1.16",
+    "@radix-ui/react-hover-card": "^1.1.15",
+    "@radix-ui/react-icons": "^1.3.2",
+    "@radix-ui/react-select": "^2.2.6",
+    "@radix-ui/react-separator": "^1.1.8",
+    "@radix-ui/react-slider": "^1.3.6",
+    "@radix-ui/react-slot": "^1.2.4",
+    "@radix-ui/react-switch": "^1.2.6",
+    "@radix-ui/react-toast": "^1.2.15",
+    "@radix-ui/react-tooltip": "^1.2.8",
+    "@tanstack/react-query": "^5.22.2",
+    "@tanstack/react-table": "^8.21.3",
+    "axios": "1.7.9",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "framer-motion": "^11.17.0",
+    "html2canvas": "^1.4.1",
+    "lottie-react": "^2.4.1",
+    "lucide-react": "^0.460.0",
+    "react-grid-layout": "^1.4.4",
+    "react-markdown": "^10.1.0",
+    "react-resizable": "^3.0.5",
+    "react-syntax-highlighter": "^16.1.1",
+    "recharts": "^2.15.0",
+    "rehype-raw": "^7.0.0",
+    "remark-gfm": "^4.0.1",
+    "tailwind-merge": "^2.6.0",
+    "zustand": "^5.0.11"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.29.7",
+    "@storybook/addon-essentials": "^8.6.14",
+    "@storybook/blocks": "^8.6.14",
+    "@storybook/react": "^8.6.18",
+    "@storybook/react-vite": "^8.6.18",
+    "@types/react": "^18.3.18",
+    "@types/react-dom": "^18.3.5",
+    "@types/react-syntax-highlighter": "^15.5.13",
+    "@typescript-eslint/eslint-plugin": "^8.19.1",
+    "@typescript-eslint/parser": "^8.19.1",
+    "@vitejs/plugin-react": "^4.7.0",
+    "autoprefixer": "^10.4.27",
+    "eslint": "^8.57.0",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-plugin-prettier": "^5.2.1",
+    "eslint-plugin-react": "^7.37.4",
+    "eslint-plugin-react-hooks": "^5.1.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^15.3.0",
+    "playwright": "^1.58.2",
+    "postcss": "^8.5.8",
+    "prettier": "^3.4.2",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "storybook": "^8.6.18",
+    "tailwindcss": "^3.4.19",
+    "tailwindcss-animate": "^1.0.7",
+    "tsup": "^8.4.0",
+    "typescript": "^5.7.3",
+    "vite": "^6.4.1"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/readme.md

@@ -0,0 +1,296 @@
+# 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.
+
+Two main components are available:
+
+- **`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).
+
+```tsx
+import { PapermapChat, PapermapChartCard } from 'papermap'
+
+// AI chat assistant
+<PapermapChat
+  token="your-base64-api-token"
+  workspaceId="your-workspace-id"
+  dashboardId="your-dashboard-id"
+/>
+
+// Standalone chart card
+<PapermapChartCard
+  token="your-base64-api-token"
+  workspaceId="your-workspace-id"
+  dashboardId="your-dashboard-id"
+  chartId="your-chart-id"
+/>
+
+// Streaming chart card (embedded dialog + chat)
+<PapermapChartCard
+  token="your-base64-api-token"
+  workspaceId="your-workspace-id"
+  dashboardId="your-dashboard-id"
+  variant="streaming"
+  chartId="your-chart-id" // optional; card stays visible with empty state if omitted
+/>
+```
+
+Both components handle everything internally -- API calls, authentication, state, and the full UI.
+
+---
+
+## Quick Start
+
+### 1. Install
+
+```bash
+npm install papermap
+# or
+pnpm add papermap
+```
+
+### 2. Import styles once
+
+```tsx
+import 'papermap/styles.css'
+```
+
+### 3. Pick one integration mode
+
+#### A) Recommended: one-time provider at app root
+
+```tsx
+import { PapermapConfigProvider, PapermapChat, PapermapChartCard } from 'papermap'
+
+function App() {
+  return (
+    <PapermapConfigProvider
+      token="your-base64-api-token"
+      workspaceId="your-workspace-id"
+      dashboardId="your-dashboard-id"
+      // optional: apiUrl="https://dataapi.papermap.ai"
+    >
+      <PapermapChat />
+      <PapermapChartCard chartId="existing-chat-id" />
+    </PapermapConfigProvider>
+  )
+}
+```
+
+#### B) Drop-in standalone components (no provider required)
+
+```tsx
+import { PapermapChat, PapermapChartCard } from 'papermap'
+
+function App() {
+  return (
+    <>
+      <PapermapChat
+        token="your-base64-api-token"
+        workspaceId="your-workspace-id"
+        dashboardId="your-dashboard-id"
+      />
+
+      <PapermapChartCard
+        token="your-base64-api-token"
+        workspaceId="your-workspace-id"
+        dashboardId="your-dashboard-id"
+        chartId="existing-chat-id"
+      />
+    </>
+  )
+}
+```
+
+### 4. 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                         |
+| `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)   |
+| `autoFade`    | `boolean`              | No       | `false`                           | Fade toolbar after inactivity        |
+| `fadeDelay`   | `number`               | No       | `5000`                            | Milliseconds before auto-fade        |
+| `className`   | `string`               | No       | --                                | Extra CSS class on toolbar container |
+
+#### `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)                               |
+| `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                                |
+| `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   |
+
+**Usage with pre-loaded data:**
+
+```tsx
+import { PapermapChartCard } from 'papermap'
+import type { TChartResponse } from 'papermap'
+
+const chart: TChartResponse = {
+  llm_data_chat_id: 'my-chart-id',
+  name: 'Revenue',
+  meta: { title: 'Revenue by Quarter', variant: 'default' },
+  pin: false,
+  chart_response: {
+    chart_type: 'bar',
+    data: [
+      { quarter: 'Q1', revenue: 42000 },
+      { quarter: 'Q2', revenue: 55000 },
+    ],
+    response_type: 'chart',
+    schema_hints: { x_key: 'quarter', y_key: 'revenue', label_key: 'quarter' },
+    visualization_config: { colors: ['#3b82f6'], width: 600, height: 400 },
+  },
+}
+
+<PapermapChartCard
+  token="..."
+  workspaceId="..."
+  dashboardId="..."
+  chart={chart}
+  onEditClick={(id) => console.log('Edit', id)}
+  onDelete={(id) => console.log('Delete', id)}
+/>
+```
+
+**Usage with API fetch:**
+
+```tsx
+<PapermapChartCard
+  token="..."
+  workspaceId="..."
+  dashboardId="..."
+  chartId="existing-chat-id"
+/>
+```
+
+### 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
+
+```tsx
+import { PapermapChartCard } from 'papermap'
+
+export function EmbeddedStreamingChart() {
+  return (
+    <div className="h-[420px] w-[520px]">
+      <PapermapChartCard
+        token="..."
+        workspaceId="..."
+        dashboardId="..."
+        variant="streaming"
+        chartId="existing-chat-id" // optional; without it the card shows a create-chart empty state
+      />
+    </div>
+  )
+}
+```
+
+**Supported chart types:** `bar`, `line`, `area`, `pie`, `radar`, `scatter`, `table`, `tile` -- matching the main Papermap app.
+
+---
+
+## Troubleshooting
+
+### "Cannot find module 'papermap/styles.css'"
+- Make sure you are on a version that exports `./styles.css`.
+- Reinstall dependencies after upgrading the package.
+
+### "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`.
+
+### Charts do not appear in `PapermapChartCard`
+- Pass a valid backend `chartId` (chat id), or
+- Provide preloaded `chart` data directly.
+
+## How It Works
+
+### Authentication
+
+The `token` prop is a base64-encoded JSON:
+
+```json
+{
+  "api_key_id": "ak_...",
+  "workspace_id": "...",
+  "valid_until": 1773246356,
+  "signature": "88b34e..."
+}
+```
+
+The component decodes it and sets these headers on every API request:
+
+- `X-API-Key-ID`
+- `X-Workspace-ID`
+- `X-Valid-Until`
+- `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
+
+---
+
+---
+
+## Future Growth
+
+This package is designed to grow. Current exports:
+
+```tsx
+import { PapermapChat, PapermapChartCard } from 'papermap'
+```
+
+Future embeddings (e.g. `Dashboard`, `DataExplorer`) will follow the same pattern -- self-contained components with `token`/`workspaceId`/`dashboardId` props and optional callbacks.

package/styles.css

@@ -0,0 +1,114 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+@layer base {
+  :root {
+    --background: 0 0% 100%;
+    --foreground: 240 10% 3.9%;
+    --card: 0 0% 100%;
+    --card-foreground: 240 10% 3.9%;
+    --popover: 0 0% 100%;
+    --popover-foreground: 240 10% 3.9%;
+    --primary: 240 5.9% 10%;
+    --primary-foreground: 0 0% 98%;
+    --secondary: 240 4.8% 95.9%;
+    --secondary-foreground: 240 5.9% 10%;
+    --muted: 240 4.8% 95.9%;
+    --muted-foreground: 240 3.8% 46.1%;
+    --accent: 240 4.8% 95.9%;
+    --accent-foreground: 240 5.9% 10%;
+    --destructive: 0 84.2% 60.2%;
+    --destructive-foreground: 0 0% 98%;
+    --border: 240 5.9% 90%;
+    --input: 240 5.9% 90%;
+    --ring: 240 5.9% 10%;
+    --radius: 0.5rem;
+  }
+
+  .dark {
+    --background: 240 10% 3.9%;
+    --foreground: 0 0% 98%;
+    --card: 240 10% 3.9%;
+    --card-foreground: 0 0% 98%;
+    --popover: 240 10% 3.9%;
+    --popover-foreground: 0 0% 98%;
+    --primary: 0 0% 98%;
+    --primary-foreground: 240 5.9% 10%;
+    --secondary: 240 3.7% 15.9%;
+    --secondary-foreground: 0 0% 98%;
+    --muted: 240 3.7% 15.9%;
+    --muted-foreground: 240 5% 64.9%;
+    --accent: 240 3.7% 15.9%;
+    --accent-foreground: 0 0% 98%;
+    --destructive: 0 62.8% 30.6%;
+    --destructive-foreground: 0 0% 98%;
+    --border: 240 3.7% 15.9%;
+    --input: 240 3.7% 15.9%;
+    --ring: 240 4.9% 83.9%;
+  }
+}
+
+@layer base {
+  * {
+    @apply border-border;
+  }
+  body {
+    @apply bg-background text-foreground;
+  }
+}
+
+@layer utilities {
+  .scrollbar-hide {
+    -ms-overflow-style: none;
+    scrollbar-width: none;
+  }
+  .scrollbar-hide::-webkit-scrollbar {
+    display: none !important;
+  }
+
+  .scrollbar-hover-only {
+    scrollbar-width: thin;
+    scrollbar-color: transparent transparent;
+    transition: scrollbar-color 0.2s ease;
+  }
+
+  .scrollbar-hover-only::-webkit-scrollbar {
+    width: 6px;
+    height: 6px;
+  }
+
+  .scrollbar-hover-only::-webkit-scrollbar-track {
+    background: transparent;
+  }
+
+  .scrollbar-hover-only::-webkit-scrollbar-thumb {
+    background-color: transparent;
+    border-radius: 4px;
+    transition: background-color 0.2s ease;
+  }
+
+  .scrollbar-hover-only:hover::-webkit-scrollbar-thumb {
+    background-color: rgba(150, 150, 150, 0.4);
+  }
+
+  .scrollbar-hover-only:hover::-webkit-scrollbar-thumb:hover {
+    background-color: rgba(150, 150, 150, 0.7);
+  }
+
+  .scrollbar-hover-only:hover {
+    scrollbar-color: rgba(150, 150, 150, 0.4) transparent;
+  }
+
+  .dark .scrollbar-hover-only:hover::-webkit-scrollbar-thumb {
+    background-color: rgba(200, 200, 200, 0.4);
+  }
+
+  .dark .scrollbar-hover-only:hover::-webkit-scrollbar-thumb:hover {
+    background-color: rgba(200, 200, 200, 0.7);
+  }
+
+  .dark .scrollbar-hover-only:hover {
+    scrollbar-color: rgba(200, 200, 200, 0.4) transparent;
+  }
+}