@namphuongtechnologi/np-hub 0.1.8 → 0.1.10

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 (25) hide show
  1. package/README.md +174 -79
  2. package/dist/{chunk-ZZQ7CSFN.js → chunk-LH3GOL37.js} +64 -26
  3. package/dist/chunk-LH3GOL37.js.map +1 -0
  4. package/dist/index.cjs +63 -25
  5. package/dist/index.cjs.map +1 -1
  6. package/dist/index.d.cts +1 -1
  7. package/dist/index.d.ts +1 -1
  8. package/dist/index.js +1 -1
  9. package/dist/np-hub.min.global.js +31 -51
  10. package/dist/react.cjs +72 -26
  11. package/dist/react.cjs.map +1 -1
  12. package/dist/react.d.cts +10 -2
  13. package/dist/react.d.ts +10 -2
  14. package/dist/react.js +10 -2
  15. package/dist/react.js.map +1 -1
  16. package/dist/register.cjs +63 -25
  17. package/dist/register.cjs.map +1 -1
  18. package/dist/register.js +1 -1
  19. package/dist/{support-widget.element-n5LtBGX6.d.cts → support-widget.element-DjptQgh_.d.cts} +9 -7
  20. package/dist/{support-widget.element-n5LtBGX6.d.ts → support-widget.element-DjptQgh_.d.ts} +9 -7
  21. package/docs/DEVELOPER_GUIDE.md +137 -57
  22. package/docs/PUBLIC_RELEASE.md +63 -45
  23. package/docs/USAGE_STATIC_REACT.md +152 -9
  24. package/package.json +1 -1
  25. package/dist/chunk-ZZQ7CSFN.js.map +0 -1
package/README.md CHANGED
@@ -1,50 +1,67 @@
1
- # NP Hub
1
+ # @namphuongtechnologi/np-hub
2
2
 
3
- NP Hub là widget hỗ trợ dạng nút nổi góc dưới phải. Nhúng được vào **web tĩnh** hoặc **React**.
3
+ Floating support widget for Nam Phương So applications. Drop it into any static site or React app — users open a form, submit a support request, and the request is sent to the Nam Phương API.
4
+
5
+ [![npm version](https://img.shields.io/npm/v/@namphuongtechnologi/np-hub.svg)](https://www.npmjs.com/package/@namphuongtechnologi/np-hub)
6
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
7
+
8
+ ---
9
+
10
+ ## Features
11
+
12
+ - **Web Component** (`<np-hub>`) — works in plain HTML and most frameworks
13
+ - **React wrapper** — typed `SupportWidget` component
14
+ - **Drag-and-drop launcher** — position persists in `localStorage`
15
+ - **Form prefill** — optional user / content / attachment seeding; required fields still validated on submit
16
+ - **Environment switch** — Production by default; Development via `isDev` / `is-dev`
17
+
18
+ ---
19
+
20
+ ## Installation
21
+
22
+ ```bash
23
+ npm install @namphuongtechnologi/np-hub
24
+ ```
25
+
26
+ **CDN (static HTML, no npm):**
27
+
28
+ ```
29
+ https://cdn.jsdelivr.net/npm/@namphuongtechnologi/np-hub@0.1.9/dist/np-hub.min.global.js
30
+ ```
4
31
 
5
32
  ---
6
33
 
7
- ## A) Web tĩnh (HTML)
34
+ ## Quick start
8
35
 
9
- Không cần `npm install`. Tạo **một file JS** cấu hình, rồi nhúng vào `index.html`.
36
+ ### Static HTML
10
37
 
11
- **`np-hub.js`** — load thư viện từ CDN và cấu hình tại đây:
38
+ Create a config script, then include it once in your page.
39
+
40
+ **`np-hub.js`**
12
41
 
13
42
  ```js
14
43
  var NP_HUB_CDN =
15
- "https://cdn.jsdelivr.net/npm/@namphuongtechnologi/np-hub@0.1.1/dist/np-hub.min.global.js";
44
+ "https://cdn.jsdelivr.net/npm/@namphuongtechnologi/np-hub@0.1.9/dist/np-hub.min.global.js";
16
45
 
17
46
  function initNpHub() {
18
47
  var widget = document.createElement("np-hub");
19
- widget.setAttribute("project-id", "NPP"); // bắt buộc
20
- // widget.setAttribute("is-dev", ""); // bỏ comment nếu dùng API dev
21
48
 
22
- // Cấu hình dự án (Project Config)
23
- widget.priority = 0;
24
- widget.coordinators = [];
25
- widget.emailContacts = [];
49
+ widget.setConfig({
50
+ projectId: "NPP",
51
+ isDev: false,
52
+ priority: 0,
53
+ coordinators: [],
54
+ emailContacts: [],
55
+ });
26
56
 
27
57
  document.body.appendChild(widget);
28
58
 
29
- // Optional khi config — chỉ prefill; form UI vẫn bắt buộc nhập
30
- // widget.setUser({
31
- // name: "Nguyen Van A",
32
- // email: "a@gmail.com",
33
- // phoneNumber: "0912345678",
34
- // });
35
-
36
- // Optional khi config — chỉ prefill nội dung/file
37
- // widget.setFormPrefill({
38
- // content: "Mô tả sự cố cần hỗ trợ...",
39
- // attachments: [],
40
- // });
41
-
42
59
  widget.addEventListener("np-hub-submit-success", function (event) {
43
- console.log("Tạo yêu cầu thành công:", event.detail);
60
+ console.log("Support request created:", event.detail);
44
61
  });
45
62
 
46
63
  widget.addEventListener("np-hub-submit-error", function (event) {
47
- console.error("Lỗi gửi yêu cầu:", event.detail);
64
+ console.error("Support request failed:", event.detail);
48
65
  });
49
66
  }
50
67
 
@@ -54,7 +71,7 @@ script.onload = initNpHub;
54
71
  document.head.appendChild(script);
55
72
  ```
56
73
 
57
- **`index.html`** — chỉ cần một dòng:
74
+ **`index.html`**
58
75
 
59
76
  ```html
60
77
  <!doctype html>
@@ -70,17 +87,11 @@ document.head.appendChild(script);
70
87
  </html>
71
88
  ```
72
89
 
73
- Ví dụ đầy đủ: `examples/static-html/`.
90
+ Full example: [`examples/static-html/`](./examples/static-html/).
74
91
 
75
- ---
76
-
77
- ## B) React
78
-
79
- ```bash
80
- npm install @namphuongtechnologi/np-hub
81
- ```
92
+ ### React
82
93
 
83
- Import `SupportWidget` và đặt **một lần** ở root app (ví dụ `App.tsx`, `main.tsx` hoặc root layout):
94
+ Mount **once** at the application root (`App.tsx`, `main.tsx`, or root layout).
84
95
 
85
96
  ```tsx
86
97
  import { SupportWidget } from "@namphuongtechnologi/np-hub/react";
@@ -88,65 +99,149 @@ import { SupportWidget } from "@namphuongtechnologi/np-hub/react";
88
99
  export default function App() {
89
100
  return (
90
101
  <>
91
- {/* nội dung app */}
102
+ {/* app content */}
92
103
  <SupportWidget
93
104
  projectId="NPP"
94
- isDev
105
+ isDev={false}
95
106
  priority={0}
96
107
  coordinators={[]}
97
108
  emailContacts={[]}
98
- // Optional khi config — chỉ prefill; form UI vẫn bắt buộc nhập
99
- // user={{
100
- // name: "Nguyen Van A",
101
- // email: "a@gmail.com",
102
- // phoneNumber: "0912345678",
103
- // }}
104
- // formPrefill={{
105
- // content: "Mô tả sự cố cần hỗ trợ...",
106
- // attachments: [],
107
- // }}
108
- onSubmitSuccess={(detail) => console.log("Thành công:", detail)}
109
- onSubmitError={(error) => console.error("Lỗi:", error)}
109
+ onSubmitSuccess={(detail) => console.log("Success:", detail)}
110
+ onSubmitError={(error) => console.error("Error:", error)}
110
111
  />
111
112
  </>
112
113
  );
113
114
  }
114
115
  ```
115
116
 
116
- ### Props
117
-
118
- | Prop | Bắt buộc | Mô tả |
119
- | -------------------- | -------- | ------------------------------------------------- |
120
- | `projectId` | Có | Mã dự án |
121
- | `isDev` | Không | `true` = API Development; mặc định Production |
122
- | `priority` | Không | Độ ưu tiên (mặc định `0`) |
123
- | `coordinators` | Không | Danh sách điều phối viên (mảng email) |
124
- | `emailContacts` | Không | Danh sách email liên hệ nhận bản tin |
125
- | `user` | Không | Prefill tên/email/SĐT (form vẫn bắt buộc nhập) |
126
- | `formPrefill` | Không | Prefill nội dung form (`content`, `attachments`) |
127
- | `width` / `height` | Không | Kích thước nút nổi (mặc định `72px`) |
128
- | `onSubmitSuccess` | Không | Callback khi gửi thành công |
129
- | `onSubmitError` | Không | Callback khi gửi lỗi |
130
- | `onOpen` / `onClose` | Không | Callback khi mở/đóng modal |
117
+ ---
118
+
119
+ ## Configuration
120
+
121
+ ### `setConfig` / React props
122
+
123
+ | Name | Required | Default | Description |
124
+ | --------------- | -------- | ------------- | ------------------------------------------------ |
125
+ | `projectId` | No | — | Project code forwarded to the API |
126
+ | `isDev` | No | `false` | `true` → Development API; otherwise Production |
127
+ | `priority` | No | `0` | Request priority |
128
+ | `coordinators` | No | `[]` | Coordinator email list |
129
+ | `emailContacts` | No | `[]` | Contact emails that receive the notification |
130
+
131
+ ### Prefill (optional)
132
+
133
+ | Name | Method / prop | Description |
134
+ | ------------- | ----------------- | --------------------------------------------------------------------------- |
135
+ | User | `setUser` / `user` | Prefills name, email, phone. Form UI still requires these fields on submit. |
136
+ | Form content | `setFormPrefill` / `formPrefill` | Prefills `content` and `attachments`. |
137
+
138
+ ```js
139
+ // Web Component
140
+ widget.setUser({
141
+ name: "Nguyen Van A",
142
+ email: "a@example.com",
143
+ phoneNumber: "0912345678",
144
+ });
145
+
146
+ widget.setFormPrefill({
147
+ content: "Describe the issue...",
148
+ attachments: [],
149
+ });
150
+ ```
151
+
152
+ ```tsx
153
+ // React
154
+ <SupportWidget
155
+ projectId="NPP"
156
+ user={{
157
+ name: "Nguyen Van A",
158
+ email: "a@example.com",
159
+ phoneNumber: "0912345678",
160
+ }}
161
+ formPrefill={{
162
+ content: "Describe the issue...",
163
+ attachments: [],
164
+ }}
165
+ />
166
+ ```
167
+
168
+ ### Launcher size & position
169
+
170
+ Default: **65×65px**, anchored **20px** from the bottom-right corner.
171
+
172
+ | Attribute / prop | Description |
173
+ | ---------------------- | ------------------------------------------------ |
174
+ | `width` / `height` | Launcher size (default `65`) |
175
+ | `right` / `bottom` | Offset from bottom-right (default `20`) |
176
+ | `left` / `top` | Use instead of `right` / `bottom` for other corners |
177
+
178
+ Numeric values from React props are treated as pixels. After the user drags the launcher, the stored `localStorage` position takes precedence.
179
+
180
+ ```js
181
+ widget.setAttribute("right", "24");
182
+ widget.setAttribute("bottom", "24");
183
+ ```
184
+
185
+ ```tsx
186
+ <SupportWidget projectId="NPP" right={24} bottom={24} />
187
+ ```
188
+
189
+ ---
190
+
191
+ ## Events & methods
192
+
193
+ ### Events (Web Component)
194
+
195
+ | Event | When |
196
+ | ----------------------- | --------------------------------- |
197
+ | `np-hub-open` | Modal opens |
198
+ | `np-hub-close` | Modal closes |
199
+ | `np-hub-submit-success` | API accepted the support request |
200
+ | `np-hub-submit-error` | Validation or API failure |
201
+
202
+ React equivalent props: `onOpen`, `onClose`, `onSubmitSuccess`, `onSubmitError`.
203
+
204
+ ### Methods (Web Component)
205
+
206
+ | Method | Description |
207
+ | ---------------------- | ------------------------------ |
208
+ | `setConfig(config)` | Apply project / API settings |
209
+ | `setUser(user)` | Prefill requester fields |
210
+ | `setFormPrefill(data)` | Prefill content / attachments |
211
+ | `open()` / `close()` | Open or close the modal |
131
212
 
132
213
  ---
133
214
 
134
- ## Cấu hình API
215
+ ## API environments
135
216
 
136
- | Môi trường | URL |
137
- | -------------------------------- | --------------------------------------------- |
138
- | Production (mặc định) | `https://namphuong-api.azurewebsites.net` |
139
- | Development (`is-dev` / `isDev`) | `https://namphuong-api-dev.azurewebsites.net` |
217
+ | Environment | Base URL |
218
+ | ----------------------------------- | ------------------------------------------------- |
219
+ | Production (default) | `https://namphuong-api.azurewebsites.net` |
220
+ | Development (`isDev` / `is-dev`) | `https://namphuong-api-dev.azurewebsites.net` |
140
221
 
141
- ## Xử lý sự cố
222
+ ---
223
+
224
+ ## Troubleshooting
225
+
226
+ | Error | Resolution |
227
+ | ---------------------------------------------- | -------------------------------------------------------------------------- |
228
+ | `projectId cannot be empty.` | If provided, `projectId` / `project-id` must be a non-empty string |
229
+ | `user.name/email/phoneNumber is required.` | Requester fields are required on submit; `user` only prefills |
230
+ | `Content is required.` | User must enter message content before submit |
231
+ | API call fails in local testing | Set `isDev` / `is-dev` when targeting the Development environment |
232
+
233
+ ---
234
+
235
+ ## Documentation
142
236
 
143
- | Lỗi | Cách xử lý |
144
- | ------------------------------------------ | -------------------------------------------------------- |
145
- | `projectId is required.` | Kiểm tra `project-id` / `projectId` |
146
- | `user.name/email/phoneNumber is required.` | Form vẫn bắt buộc đủ tên/email/SĐT; prop `user` chỉ prefill (optional) |
147
- | `Content is required.` | Người dùng cần nhập nội dung trước khi submit |
148
- | Gọi API thất bại | Kiểm tra `is-dev` / `isDev` nếu đang test môi trường dev |
237
+ | Document | Audience |
238
+ | -------- | -------- |
239
+ | [Usage (static & React)](./docs/USAGE_STATIC_REACT.md) | Integrators |
240
+ | [Developer guide](./docs/DEVELOPER_GUIDE.md) | Contributors |
241
+ | [Public release](./docs/PUBLIC_RELEASE.md) | Maintainers |
242
+
243
+ ---
149
244
 
150
245
  ## License
151
246
 
152
- MIT
247
+ MIT © Nam Phương So