@gamention/pulse-elements 0.1.0 → 0.1.2

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.
Files changed (2) hide show
  1. package/README.md +150 -0
  2. package/package.json +3 -3
package/README.md ADDED
@@ -0,0 +1,150 @@
1
+ # @gamention/pulse-elements
2
+
3
+ Drop-in web components for real-time collaboration — **comments, cursors, presence, drawing, notifications, and more**. Built with [Lit](https://lit.dev/), works with any framework.
4
+
5
+ ## Installation
6
+
7
+ ```bash
8
+ npm install @gamention/pulse-elements
9
+ ```
10
+
11
+ ## Quick Start
12
+
13
+ ### Option 1: Single Widget (Recommended)
14
+
15
+ One tag gives you everything — comments, cursors, presence, drawing, notifications, pins, and activity feed:
16
+
17
+ ```html
18
+ <pulse-widget
19
+ api-key="pk_..."
20
+ token="YOUR_JWT_TOKEN"
21
+ room="my-page"
22
+ endpoint="wss://pulse.hire.rest"
23
+ ></pulse-widget>
24
+
25
+ <script type="module">
26
+ import '@gamention/pulse-elements';
27
+ </script>
28
+ ```
29
+
30
+ ### Option 2: CDN (No Build Step)
31
+
32
+ ```html
33
+ <script src="https://pulse.hire.rest/sdk/pulse.js"></script>
34
+
35
+ <pulse-widget
36
+ api-key="pk_..."
37
+ token="YOUR_JWT_TOKEN"
38
+ room="my-page"
39
+ endpoint="wss://pulse.hire.rest"
40
+ ></pulse-widget>
41
+ ```
42
+
43
+ ### Option 3: Framework Integration
44
+
45
+ **React:**
46
+ ```tsx
47
+ import '@gamention/pulse-elements';
48
+
49
+ function App() {
50
+ return (
51
+ <pulse-widget
52
+ api-key="pk_..."
53
+ token={token}
54
+ room="dashboard"
55
+ endpoint="wss://pulse.hire.rest"
56
+ />
57
+ );
58
+ }
59
+ ```
60
+
61
+ **Vue:**
62
+ ```vue
63
+ <template>
64
+ <pulse-widget
65
+ :api-key="apiKey"
66
+ :token="token"
67
+ room="dashboard"
68
+ endpoint="wss://pulse.hire.rest"
69
+ />
70
+ </template>
71
+
72
+ <script setup>
73
+ import '@gamention/pulse-elements';
74
+ </script>
75
+ ```
76
+
77
+ ## Features
78
+
79
+ | Feature | Description |
80
+ |---------|-------------|
81
+ | **Comments** | Threaded comments with @mentions, edit/delete, reactions |
82
+ | **Pin Anywhere** | Click anywhere on the page to pin a comment (element-anchored, works across viewports) |
83
+ | **Live Cursors** | See other users' cursors in real-time |
84
+ | **Presence** | Online/idle status with avatars |
85
+ | **Drawing** | Freehand annotations with auto-fade (pen pressure support) |
86
+ | **Notifications** | Bell icon with unread badge for replies, mentions, reactions |
87
+ | **Activity Feed** | Chronological room activity log |
88
+ | **Media Attachments** | Image uploads with lightbox, audio notes (WhatsApp-style), video notes (Telegram-style) |
89
+ | **Follow Mode** | Click an avatar to auto-scroll with another user |
90
+ | **Mobile Support** | Touch/pen events, responsive bottom-sheet panels, 44px touch targets |
91
+
92
+ ## Widget Configuration
93
+
94
+ ```html
95
+ <pulse-widget
96
+ api-key="pk_..." <!-- Publishable API key -->
97
+ token="..." <!-- JWT from your backend via POST /auth/token -->
98
+ room="page-id" <!-- Room identifier (one per page/view) -->
99
+ endpoint="wss://..." <!-- Your Pulse server URL -->
100
+ position="bottom-right" <!-- bottom-right | bottom-left | top-right | top-left -->
101
+ display="floating" <!-- floating (fixed position) | inline (in page flow) -->
102
+ ></pulse-widget>
103
+ ```
104
+
105
+ ## Theming
106
+
107
+ Override CSS custom properties to match your brand:
108
+
109
+ ```css
110
+ pulse-widget {
111
+ --pulse-primary: #e11d48;
112
+ --pulse-bg: #ffffff;
113
+ --pulse-text: #0f172a;
114
+ --pulse-border: #e2e8f0;
115
+ --pulse-radius: 12px;
116
+ --pulse-font: 'Inter', sans-serif;
117
+ }
118
+ ```
119
+
120
+ ## Auth Flow
121
+
122
+ Your backend mints JWT tokens using a secret key:
123
+
124
+ ```bash
125
+ curl -X POST https://pulse.hire.rest/auth/token \
126
+ -H "Authorization: Bearer sk_your_secret_key" \
127
+ -H "Content-Type: application/json" \
128
+ -d '{"userId": "user-123", "name": "Alice"}'
129
+ ```
130
+
131
+ Pass the returned token to the widget's `token` attribute.
132
+
133
+ ## Documentation
134
+
135
+ Full docs at **[pulse.hire.rest/docs](https://pulse.hire.rest/docs)**
136
+
137
+ - [Quick Start](https://pulse.hire.rest/docs/getting-started/quickstart)
138
+ - [Widget Setup](https://pulse.hire.rest/docs/widget/setup)
139
+ - [Theming](https://pulse.hire.rest/docs/widget/theming)
140
+ - [Framework Guides](https://pulse.hire.rest/docs/widget/frameworks) (React, Vue, Svelte, Angular, Next.js)
141
+ - [REST API](https://pulse.hire.rest/docs/api/overview)
142
+
143
+ ## Related Packages
144
+
145
+ - [`@gamention/pulse-core`](https://www.npmjs.com/package/@gamention/pulse-core) — Core client SDK for building custom UI
146
+ - [`@gamention/pulse-shared`](https://www.npmjs.com/package/@gamention/pulse-shared) — Shared TypeScript types and protocol
147
+
148
+ ## License
149
+
150
+ MIT
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@gamention/pulse-elements",
3
- "version": "0.1.0",
3
+ "version": "0.1.2",
4
4
  "description": "Drop-in web components for real-time collaboration — comments, cursors, presence, drawing, and more",
5
5
  "type": "module",
6
6
  "main": "./dist/pulse-elements.cjs",
@@ -34,8 +34,8 @@
34
34
  },
35
35
  "dependencies": {
36
36
  "@lit/context": "^1.1.0",
37
- "@gamention/pulse-core": "workspace:*",
38
- "@gamention/pulse-shared": "workspace:*",
37
+ "@gamention/pulse-core": "^0.1.2",
38
+ "@gamention/pulse-shared": "^0.1.2",
39
39
  "lit": "^3.2.0",
40
40
  "lucide": "^0.577.0"
41
41
  },