@8wave/ai-elements 0.34.0 β†’ 0.36.0

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 (26) hide show
  1. package/README.md +54 -257
  2. package/dist/assets/memtYaGs126MiZpBA-UFUIcVXSCEkx2cmqvXlWqW106F15M.woff2 +0 -0
  3. package/dist/assets/memtYaGs126MiZpBA-UFUIcVXSCEkx2cmqvXlWqWt06F15M.woff2 +0 -0
  4. package/dist/assets/memtYaGs126MiZpBA-UFUIcVXSCEkx2cmqvXlWqWtE6F15M.woff2 +0 -0
  5. package/dist/assets/memtYaGs126MiZpBA-UFUIcVXSCEkx2cmqvXlWqWtU6F15M.woff2 +0 -0
  6. package/dist/assets/memtYaGs126MiZpBA-UFUIcVXSCEkx2cmqvXlWqWtk6F15M.woff2 +0 -0
  7. package/dist/assets/memtYaGs126MiZpBA-UFUIcVXSCEkx2cmqvXlWqWu06F15M.woff2 +0 -0
  8. package/dist/assets/memtYaGs126MiZpBA-UFUIcVXSCEkx2cmqvXlWqWuU6F.woff2 +0 -0
  9. package/dist/assets/memtYaGs126MiZpBA-UFUIcVXSCEkx2cmqvXlWqWuk6F15M.woff2 +0 -0
  10. package/dist/assets/memtYaGs126MiZpBA-UFUIcVXSCEkx2cmqvXlWqWvU6F15M.woff2 +0 -0
  11. package/dist/assets/memtYaGs126MiZpBA-UFUIcVXSCEkx2cmqvXlWqWxU6F15M.woff2 +0 -0
  12. package/dist/assets/memvYaGs126MiZpBA-UvWbX2vVnXBbObj2OVTS-muw.woff2 +0 -0
  13. package/dist/assets/memvYaGs126MiZpBA-UvWbX2vVnXBbObj2OVTS2mu1aB.woff2 +0 -0
  14. package/dist/assets/memvYaGs126MiZpBA-UvWbX2vVnXBbObj2OVTSCmu1aB.woff2 +0 -0
  15. package/dist/assets/memvYaGs126MiZpBA-UvWbX2vVnXBbObj2OVTSGmu1aB.woff2 +0 -0
  16. package/dist/assets/memvYaGs126MiZpBA-UvWbX2vVnXBbObj2OVTSKmu1aB.woff2 +0 -0
  17. package/dist/assets/memvYaGs126MiZpBA-UvWbX2vVnXBbObj2OVTSOmu1aB.woff2 +0 -0
  18. package/dist/assets/memvYaGs126MiZpBA-UvWbX2vVnXBbObj2OVTSumu1aB.woff2 +0 -0
  19. package/dist/assets/memvYaGs126MiZpBA-UvWbX2vVnXBbObj2OVTSymu1aB.woff2 +0 -0
  20. package/dist/assets/memvYaGs126MiZpBA-UvWbX2vVnXBbObj2OVTUGmu1aB.woff2 +0 -0
  21. package/dist/assets/memvYaGs126MiZpBA-UvWbX2vVnXBbObj2OVTVOmu1aB.woff2 +0 -0
  22. package/dist/floating-chat-widget.es.js +61829 -0
  23. package/dist/floating-chat-widget.es.js.map +1 -0
  24. package/dist/floating-chat-widget.umd.js +162 -0
  25. package/dist/floating-chat-widget.umd.js.map +1 -0
  26. package/package.json +4 -6
package/README.md CHANGED
@@ -1,291 +1,88 @@
1
- # Web Component App
1
+ # @8wave/ai-elements
2
2
 
3
- Applicazione per creare Web Components (Custom Elements) usando Vue 3.
3
+ A framework-agnostic Web Component that embeds a floating AI chat widget into any webpage. Built with Vue 3 and distributed as a standard Custom Element β€” no framework dependency required on the consumer side.
4
4
 
5
- ## πŸ“‹ Descrizione
5
+ ## Overview
6
6
 
7
- Questa app permette di creare custom elements nativi del browser usando Vue 3. I componenti sono completamente autonomi e possono essere usati in qualsiasi progetto HTML, indipendentemente dal framework utilizzato.
7
+ The package exposes a single custom element, `<floating-chat-widget>`, that renders a fixed-position button in the bottom-right corner of the page. Clicking the button opens a full chat interface powered by the 8wave AI backend. Anonymous authentication is handled automatically by the component.
8
8
 
9
- ## πŸš€ Caratteristiche
10
-
11
- - βœ… Web Components nativi del browser
12
- - βœ… Costruiti con Vue 3
13
- - βœ… Shadow DOM per incapsulamento degli stili
14
- - βœ… Props reattive tramite attributi HTML
15
- - βœ… Eventi custom personalizzati
16
- - βœ… Bundle ottimizzato (ES modules e UMD)
17
- - βœ… TypeScript support
18
-
19
- ## πŸ“¦ Struttura
20
-
21
- ```
22
- web-component/
23
- β”œβ”€β”€ src/
24
- β”‚ β”œβ”€β”€ main.ts # Entry point - registra i custom elements
25
- β”‚ β”œβ”€β”€ MyElement.ce.vue # Esempio di custom element
26
- β”‚ └── vite-env.d.ts # Type definitions
27
- β”œβ”€β”€ index.html # Pagina demo per testare i componenti
28
- β”œβ”€β”€ package.json
29
- β”œβ”€β”€ tsconfig.json
30
- └── vite.config.ts # Configurazione Vite per custom elements
31
- ```
32
-
33
- ## πŸ› οΈ Setup
34
-
35
- ### Installazione dipendenze
36
-
37
- Dalla root del monorepo:
9
+ ## Installation
38
10
 
39
11
  ```bash
40
- pnpm install
12
+ npm install @8wave/ai-elements
13
+ # or
14
+ pnpm add @8wave/ai-elements
41
15
  ```
42
16
 
43
- ### Sviluppo
44
-
45
- ```bash
46
- # Dalla root del monorepo
47
- pnpm --filter web-component dev
48
-
49
- # Oppure
50
- cd apps/web-component
51
- pnpm dev
52
- ```
53
-
54
- Questo avvierΓ  un server di sviluppo su `http://localhost:8082` con la pagina di demo.
55
-
56
- ### Build
57
-
58
- ```bash
59
- # Dalla root del monorepo
60
- pnpm --filter web-component build
61
-
62
- # Oppure
63
- cd apps/web-component
64
- pnpm build
65
- ```
66
-
67
- Questo genererΓ  i file ottimizzati nella cartella `dist/`:
68
- - `web-components.es.js` - ES modules (raccomandato)
69
- - `web-components.umd.js` - UMD format (per compatibilitΓ  legacy)
70
-
71
- ## πŸ“– Come creare un nuovo Custom Element
72
-
73
- ### 1. Crea un componente Vue con estensione `.ce.vue`
74
-
75
- ```vue
76
- <!-- src/NewElement.ce.vue -->
77
- <template>
78
- <div class="new-element">
79
- <h3>{{ title }}</h3>
80
- <slot></slot>
81
- </div>
82
- </template>
83
-
84
- <script setup lang="ts">
85
- import { toRefs } from 'vue'
86
-
87
- const props = defineProps<{
88
- title?: string
89
- }>()
90
-
91
- const { title = 'Default Title' } = toRefs(props)
92
- </script>
93
-
94
- <style scoped>
95
- .new-element {
96
- padding: 20px;
97
- border: 1px solid #ccc;
98
- }
99
- </style>
100
- ```
101
-
102
- ### 2. Registra il custom element in `main.ts`
103
-
104
- ```typescript
105
- import { defineCustomElement } from 'vue'
106
- import NewElement from './NewElement.ce.vue'
107
-
108
- const NewElementCE = defineCustomElement(NewElement)
109
- customElements.define('new-element', NewElementCE)
110
-
111
- export { NewElementCE }
112
- ```
17
+ ## Usage
113
18
 
114
- ### 3. Usa il custom element in HTML
19
+ ### Via npm package
115
20
 
116
- ```html
117
- <script type="module" src="./dist/web-components.es.js"></script>
21
+ Import the package once (e.g. in your app entry point). The custom element registers itself automatically.
118
22
 
119
- <new-element title="Hello World">
120
- Questo Γ¨ il contenuto dello slot
121
- </new-element>
23
+ ```js
24
+ import '@8wave/ai-elements'
122
25
  ```
123
26
 
124
- ## 🎯 Uso nei Progetti
125
-
126
- ### In un progetto HTML statico
27
+ Then use the element anywhere in your HTML:
127
28
 
128
29
  ```html
129
- <!DOCTYPE html>
130
- <html>
131
- <head>
132
- <meta charset="UTF-8">
133
- <title>My App</title>
134
- </head>
135
- <body>
136
- <!-- Usa il custom element -->
137
- <my-element
138
- title="Benvenuto"
139
- message="Questo Γ¨ un web component!">
140
- </my-element>
141
-
142
- <!-- Importa il bundle -->
143
- <script type="module" src="./web-components.es.js"></script>
144
- </body>
145
- </html>
30
+ <floating-chat-widget
31
+ organization-slug="your-org-slug"
32
+ agent-id="your-agent-id"
33
+ ></floating-chat-widget>
146
34
  ```
147
35
 
148
- ### In React
149
-
150
- ```jsx
151
- import { useEffect } from 'react';
152
-
153
- function App() {
154
- useEffect(() => {
155
- // Importa il web component
156
- import('./web-components.es.js');
157
- }, []);
158
-
159
- return (
160
- <div>
161
- <my-element
162
- title="From React"
163
- message="Web component in React!"
164
- />
165
- </div>
166
- );
167
- }
168
- ```
169
-
170
- ### In Angular
171
-
172
- ```typescript
173
- // app.module.ts
174
- import { CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
175
-
176
- @NgModule({
177
- schemas: [CUSTOM_ELEMENTS_SCHEMA]
178
- })
179
- export class AppModule { }
180
- ```
36
+ ### Via CDN (no bundler)
181
37
 
182
38
  ```html
183
- <!-- app.component.html -->
184
- <my-element
185
- [title]="'From Angular'"
186
- [message]="'Web component in Angular!'">
187
- </my-element>
188
- ```
39
+ <!-- unpkg -->
40
+ <script type="module" async src="https://unpkg.com/@8wave/ai-elements"></script>
41
+ <!-- or jsDelivr -->
42
+ <!-- <script type="module" async src="https://cdn.jsdelivr.net/npm/@8wave/ai-elements"></script> -->
189
43
 
190
- ```typescript
191
- // app.component.ts
192
- import './web-components.es.js';
44
+ <floating-chat-widget
45
+ organization-slug="your-org-slug"
46
+ agent-id="your-agent-id"
47
+ ></floating-chat-widget>
193
48
  ```
194
49
 
195
- ## 🎨 Styling
196
-
197
- Gli stili definiti nei componenti `.ce.vue` sono incapsulati nel Shadow DOM. Per sovrascriverli dall'esterno, puoi usare CSS custom properties (variabili CSS):
50
+ ## Attributes
198
51
 
199
- ```vue
200
- <!-- Nel componente -->
201
- <style scoped>
202
- .my-element {
203
- background-color: var(--my-element-bg, #f9f9f9);
204
- color: var(--my-element-color, #333);
205
- }
206
- </style>
207
- ```
208
-
209
- ```css
210
- /* Nel CSS esterno */
211
- my-element {
212
- --my-element-bg: #e0e0e0;
213
- --my-element-color: #000;
214
- }
215
- ```
52
+ | Attribute | Type | Required | Default | Description |
53
+ | ------------------- | -------- | -------- | ------------------------- | ------------------------------------------------------------ |
54
+ | `agent-id` | `string` | βœ… | β€” | The unique identifier of the AI agent to connect to. |
55
+ | `organization-slug` | `string` | βœ… | β€” | The slug of the organization that owns the agent. |
56
+ | `prefix-url` | `string` | ❌ | `VITE_BACKEND_URL` (build-time) | Base URL of the 8wave backend API. Override this when self-hosting or pointing to a different environment. |
216
57
 
217
- ## πŸ“‘ Eventi
58
+ ## How it works
218
59
 
219
- I custom elements possono emettere eventi personalizzati:
60
+ 1. On mount the component automatically signs in as an anonymous user via the 8wave Auth service.
61
+ 2. Once authenticated it fetches the agent configuration (name, interface colors, etc.) from the public API.
62
+ 3. A circular floating button appears in the bottom-right corner, styled with the agent's `mainColor` and `secondaryColor`.
63
+ 4. Clicking the button toggles the chat panel open/closed.
64
+ 5. All styles are encapsulated inside a Shadow DOM β€” no CSS leaks in or out.
220
65
 
221
- ```vue
222
- <!-- Nel componente -->
223
- <script setup lang="ts">
224
- const emit = defineEmits<{
225
- customEvent: [data: string]
226
- }>()
66
+ ## Development
227
67
 
228
- const handleClick = () => {
229
- emit('customEvent', 'Hello from custom element!')
230
- }
231
- </script>
232
- ```
233
-
234
- ```javascript
235
- // Nel JavaScript esterno
236
- const element = document.querySelector('my-element');
237
- element.addEventListener('customEvent', (event) => {
238
- console.log(event.detail); // ['Hello from custom element!']
239
- });
240
- ```
241
-
242
- ## πŸ”§ Configurazione Avanzata
243
-
244
- ### Vite Config
245
-
246
- La configurazione in `vite.config.ts` Γ¨ ottimizzata per la build di custom elements:
247
-
248
- - **`customElement: true`**: Abilita la modalitΓ  custom element in Vue
249
- - **Library mode**: Crea un bundle ottimizzato per il riutilizzo
250
- - **Multiple formats**: Genera sia ES modules che UMD
251
-
252
- ### TypeScript
253
-
254
- Il progetto usa TypeScript con configurazione estesa da `tsconfig/tsconfig.vite.json` del monorepo.
255
-
256
- ## πŸ“š Risorse
257
-
258
- - [Vue 3 - Web Components](https://it.vuejs.org/guide/extras/web-components.html)
259
- - [MDN - Custom Elements](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements)
260
- - [Vite - Library Mode](https://vitejs.dev/guide/build.html#library-mode)
261
-
262
- ## πŸ› Troubleshooting
263
-
264
- ### Il componente non si registra
68
+ ```bash
69
+ # install dependencies (from the monorepo root)
70
+ pnpm install
265
71
 
266
- Assicurati che il nome del custom element contenga un trattino (`-`):
267
- ```typescript
268
- // βœ… Corretto
269
- customElements.define('my-element', MyElementCE)
72
+ # start the dev server (port 8082)
73
+ pnpm nx run web-component:dev
270
74
 
271
- // ❌ Errato (manca il trattino)
272
- customElements.define('myelement', MyElementCE)
75
+ # build the library bundle
76
+ pnpm nx run web-component:build
273
77
  ```
274
78
 
275
- ### Gli stili non vengono applicati
276
-
277
- Verifica che:
278
- 1. Gli stili siano definiti nel componente `.ce.vue`
279
- 2. Il tag `<style scoped>` sia presente
280
- 3. Gli stili non siano in conflitto con il CSS della pagina host
281
-
282
- ### Eventi non ricevuti
79
+ The dev server mounts the component against a real backend using the credentials configured in your local `.env` file.
283
80
 
284
- Assicurati di:
285
- 1. Emettere eventi con `emit()`
286
- 2. Ascoltare eventi dopo che il DOM Γ¨ caricato
287
- 3. Usare `event.detail` per accedere ai dati dell'evento
81
+ ## Build output
288
82
 
289
- ## πŸ“„ Licenza
83
+ | File | Format | Description |
84
+ | -------------------------------- | ------ | ------------------------ |
85
+ | `dist/floating-chat-widget.es.js` | ESM | For bundlers / `import` |
86
+ | `dist/floating-chat-widget.umd.js` | UMD | For CDN / `require` |
290
87
 
291
- Questo progetto fa parte del monorepo 8bot-ai e segue la stessa licenza.
88
+ CSS is injected directly into the Shadow DOM by the JavaScript bundle β€” no separate stylesheet needs to be loaded.