Skip to content

Commit eb251a9

Browse files
robsongajuniorrobsongajunior
authored
Merge pull request #506 from aziontech/feat/ENG-37137-trigger-release
feat: trigger release for PrimeVue abstraction layer (ENG-37137)
2 parents 899e242 + 4e246b1 commit eb251a9

File tree

1 file changed

+360
-0
lines changed

1 file changed

+360
-0
lines changed

‎packages/webkit/PRIMEVUE_ABSTRACTION.md‎

Lines changed: 360 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,360 @@
1+
# PrimeVue Abstraction Layer for @aziontech/webkit
2+
3+
Webkit provides a complete abstraction layer over PrimeVue, allowing consumer applications to use PrimeVue components, services, and composables without a direct dependency on the `primevue` package.
4+
5+
## Table of Contents
6+
7+
- [Overview](#overview)
8+
- [Plugin Setup](#plugin-setup)
9+
- [Composables](#composables)
10+
- [Utilities](#utilities)
11+
- [Components](#components)
12+
- [Exports Reference](#exports-reference)
13+
- [Migration Guide](#migration-guide)
14+
- [Architecture](#architecture)
15+
- [Troubleshooting](#troubleshooting)
16+
17+
---
18+
19+
## Overview
20+
21+
The abstraction layer consists of:
22+
23+
- **WebkitPlugin**: Unified Vue plugin that registers PrimeVue core, services, and directives
24+
- **Composable wrappers**: `useToast` (with semantic shortcuts) and `useDialog`
25+
- **Utility re-exports**: `FilterMatchMode` and other PrimeVue API constants
26+
- **Component wrappers**: `DynamicDialog`, `ConfirmDialog`, and all existing PrimeVue wrappers
27+
- **Directive re-exports**: `Tooltip`
28+
29+
**Why this exists:**
30+
- Consumer apps (e.g., console-kit) can remove `primevue` from their direct dependencies
31+
- Webkit controls the PrimeVue version and can upgrade/swap without breaking consumers
32+
- Composable wrappers allow adding convenience methods (e.g., `toast.success()`)
33+
34+
---
35+
36+
## Plugin Setup
37+
38+
Register all PrimeVue services in a single call:
39+
40+
```js
41+
// main.js
42+
import { WebkitPlugin } from '@aziontech/webkit/plugin'
43+
44+
const app = createApp(App)
45+
app.use(WebkitPlugin)
46+
```
47+
48+
### What the plugin registers
49+
50+
| Registration | What it does |
51+
|-------------|-------------|
52+
| `PrimeVue` | Core configuration (locale, ripple, zIndex, etc.) |
53+
| `ToastService` | Enables `useToast()` and `$toast` global property |
54+
| `DialogService` | Enables `useDialog()` and `$dialog` global property |
55+
| `v-tooltip` | Tooltip directive available in all templates |
56+
57+
### Passing options to PrimeVue
58+
59+
```js
60+
app.use(WebkitPlugin, { ripple: true })
61+
```
62+
63+
Options are forwarded directly to `PrimeVue` config.
64+
65+
---
66+
67+
## Composables
68+
69+
### useToast
70+
71+
```js
72+
import { useToast } from '@aziontech/webkit/use-toast'
73+
```
74+
75+
#### Original API (fully compatible)
76+
77+
```js
78+
const toast = useToast()
79+
80+
toast.add({
81+
severity: 'success',
82+
summary: 'Done',
83+
detail: 'Item saved',
84+
life: 5000
85+
})
86+
87+
toast.remove(message)
88+
toast.removeAllGroups()
89+
```
90+
91+
#### Shortcut methods
92+
93+
```js
94+
const toast = useToast()
95+
96+
toast.success('Item saved') // severity: success, life: 5000ms
97+
toast.error('Something went wrong') // severity: error, life: 0 (manual close)
98+
toast.warn('Check your input') // severity: warn, life: 5000ms
99+
toast.info('New version available') // severity: info, life: 5000ms
100+
```
101+
102+
| Method | Severity | Default Life | Customizable |
103+
|--------|----------|:------------:|:------------:|
104+
| `success(detail, life?)` | success | 5000ms | Yes |
105+
| `error(detail)` | error | 0 (manual close) | No |
106+
| `warn(detail, life?)` | warn | 5000ms | Yes |
107+
| `info(detail, life?)` | info | 5000ms | Yes |
108+
109+
Shortcuts are additive. The original `toast.add()` API works unchanged.
110+
111+
---
112+
113+
### useDialog
114+
115+
```js
116+
import { useDialog } from '@aziontech/webkit/use-dialog'
117+
```
118+
119+
#### Usage
120+
121+
```js
122+
const dialog = useDialog()
123+
124+
dialog.open(MyDialogComponent, {
125+
props: {
126+
header: 'Confirm Action',
127+
modal: true,
128+
blockScroll: true,
129+
style: { width: '32rem' }
130+
},
131+
data: {
132+
id: 123
133+
},
134+
onClose: () => {
135+
// handle close
136+
}
137+
})
138+
```
139+
140+
This is a direct wrapper around PrimeVue's `useDialog`. The API is identical.
141+
142+
---
143+
144+
## Utilities
145+
146+
### FilterMatchMode
147+
148+
```js
149+
import { FilterMatchMode } from '@aziontech/webkit/api'
150+
151+
const filters = ref({
152+
global: { value: '', matchMode: FilterMatchMode.CONTAINS }
153+
})
154+
```
155+
156+
All `FilterMatchMode` constants are available: `STARTS_WITH`, `CONTAINS`, `NOT_CONTAINS`, `ENDS_WITH`, `EQUALS`, `NOT_EQUALS`, `IN`, `LESS_THAN`, `LESS_THAN_OR_EQUAL_TO`, `GREATER_THAN`, `GREATER_THAN_OR_EQUAL_TO`, `BETWEEN`, `DATE_IS`, `DATE_IS_NOT`, `DATE_BEFORE`, `DATE_AFTER`.
157+
158+
---
159+
160+
## Components
161+
162+
### DynamicDialog
163+
164+
Required at app root level for `useDialog()` to work:
165+
166+
```vue
167+
<script setup>
168+
import DynamicDialog from '@aziontech/webkit/dynamic-dialog'
169+
</script>
170+
171+
<template>
172+
<DynamicDialog />
173+
<router-view />
174+
</template>
175+
```
176+
177+
### ConfirmDialog
178+
179+
```vue
180+
<script setup>
181+
import ConfirmDialog from '@aziontech/webkit/confirm-dialog'
182+
</script>
183+
184+
<template>
185+
<ConfirmDialog />
186+
</template>
187+
```
188+
189+
**Props:**
190+
- `group` (String) - Optional group name
191+
- `breakpoints` (Object) - Responsive breakpoints
192+
193+
### Tooltip Directive
194+
195+
Already registered globally by `WebkitPlugin`. For standalone use:
196+
197+
```js
198+
import { Tooltip } from '@aziontech/webkit/tooltip'
199+
200+
app.directive('tooltip', Tooltip)
201+
```
202+
203+
---
204+
205+
## Exports Reference
206+
207+
| Export Path | Type | Description |
208+
|-------------|------|-------------|
209+
| `@aziontech/webkit/plugin` | Plugin | `WebkitPlugin` - unified PrimeVue setup |
210+
| `@aziontech/webkit/use-toast` | Composable | `useToast` with shortcut methods |
211+
| `@aziontech/webkit/use-dialog` | Composable | `useDialog` wrapper |
212+
| `@aziontech/webkit/api` | Utility | `FilterMatchMode` constants |
213+
| `@aziontech/webkit/dynamic-dialog` | Component | DynamicDialog wrapper |
214+
| `@aziontech/webkit/confirm-dialog` | Component | ConfirmDialog wrapper |
215+
| `@aziontech/webkit/tooltip` | Directive | Tooltip re-export |
216+
217+
---
218+
219+
## Migration Guide
220+
221+
### Step 1: Replace plugin setup in main.js
222+
223+
**Before:**
224+
```js
225+
import PrimeVue from 'primevue/config'
226+
import Tooltip from 'primevue/tooltip'
227+
import ToastService from 'primevue/toastservice'
228+
import DialogService from 'primevue/dialogservice'
229+
230+
app.use(PrimeVue)
231+
app.directive('tooltip', Tooltip)
232+
app.use(ToastService)
233+
app.use(DialogService)
234+
```
235+
236+
**After:**
237+
```js
238+
import { WebkitPlugin } from '@aziontech/webkit/plugin'
239+
240+
app.use(WebkitPlugin)
241+
```
242+
243+
### Step 2: Replace imports across codebase
244+
245+
| Before | After |
246+
|--------|-------|
247+
| `import { useToast } from 'primevue/usetoast'` | `import { useToast } from '@aziontech/webkit/use-toast'` |
248+
| `import { useDialog } from 'primevue/usedialog'` | `import { useDialog } from '@aziontech/webkit/use-dialog'` |
249+
| `import { FilterMatchMode } from 'primevue/api'` | `import { FilterMatchMode } from '@aziontech/webkit/api'` |
250+
| `import DynamicDialog from 'primevue/dynamicdialog'` | `import DynamicDialog from '@aziontech/webkit/dynamic-dialog'` |
251+
| `import ConfirmDialog from 'primevue/confirmdialog'` | `import ConfirmDialog from '@aziontech/webkit/confirm-dialog'` |
252+
| `import Toast from 'primevue/toast'` | `import Toast from '@aziontech/webkit/toast'` |
253+
| `import Dialog from 'primevue/dialog'` | `import Dialog from '@aziontech/webkit/dialog'` |
254+
| `import Button from 'primevue/button'` | `import Button from '@aziontech/webkit/button'` |
255+
256+
### Step 3: Remove primevue from package.json
257+
258+
After all imports point to `@aziontech/webkit/*`, remove `primevue` from `dependencies`. It becomes a transitive dependency through webkit.
259+
260+
---
261+
262+
## Architecture
263+
264+
```
265+
Consumer App (console-kit)
266+
│
267+
├── import { WebkitPlugin } from '@aziontech/webkit/plugin'
268+
├── import { useToast } from '@aziontech/webkit/use-toast'
269+
├── import { useDialog } from '@aziontech/webkit/use-dialog'
270+
└── import Button from '@aziontech/webkit/button'
271+
│
272+
▼
273+
@aziontech/webkit
274+
│
275+
├── src/plugins/primevue/index.js → WebkitPlugin
276+
├── src/composables/use-toast/index.js → useToast wrapper
277+
├── src/composables/use-dialog/index.js → useDialog wrapper
278+
├── src/services/primevue-api/index.js → FilterMatchMode
279+
├── src/directives/tooltip/index.js → Tooltip
280+
└── src/core/primevue/*/ → Component wrappers
281+
│
282+
▼
283+
primevue (transitive dependency)
284+
```
285+
286+
### How PrimeVue services work internally
287+
288+
```
289+
WebkitPlugin useToast() <Toast> component
290+
│ │ │
291+
▼ ▼ ▼
292+
app.provide(Symbol, svc) inject(Symbol) → svc ToastEventBus.on('add')
293+
│ │ │
294+
└──────────────────────────────┘ │
295+
│ │
296+
▼ │
297+
svc.add(msg) ──→ ToastEventBus.emit('add') ───────────┘
298+
```
299+
300+
The webkit wrappers use the **same PrimeVue Symbols** internally, so components and composables communicate seamlessly.
301+
302+
---
303+
304+
## Troubleshooting
305+
306+
### useToast/useDialog throws "not provided" error
307+
308+
**Problem:** `No PrimeVue Toast provided!` or similar error.
309+
310+
**Solution:** Ensure `WebkitPlugin` is registered before the component mounts:
311+
312+
```js
313+
app.use(WebkitPlugin) // Must come before app.mount()
314+
app.mount('#app')
315+
```
316+
317+
### DynamicDialog doesn't open
318+
319+
**Problem:** `dialog.open()` is called but nothing appears.
320+
321+
**Solution:** Ensure `<DynamicDialog />` is mounted at root level (e.g., `App.vue`):
322+
323+
```vue
324+
<template>
325+
<DynamicDialog />
326+
<router-view />
327+
</template>
328+
```
329+
330+
### Toast styles not applied
331+
332+
**Problem:** Toast appears but without custom styling via `pt` prop.
333+
334+
**Solution:** The webkit Toast wrapper explicitly forwards the `pt` prop. Ensure you're passing it correctly:
335+
336+
```vue
337+
<Toast :pt="{ root: { class: 'my-class' } }">
338+
<template #message="{ message }">
339+
<!-- custom template -->
340+
</template>
341+
</Toast>
342+
```
343+
344+
### PrimeVue version mismatch
345+
346+
**Problem:** Unexpected behavior after updating webkit.
347+
348+
**Solution:** Check which PrimeVue version webkit uses:
349+
350+
```bash
351+
cat node_modules/@aziontech/webkit/package.json | grep primevue
352+
```
353+
354+
Consumer apps should not have `primevue` in their own `package.json` to avoid version conflicts.
355+
356+
---
357+
358+
**Last Updated:** 2026-04-02
359+
**Version:** 1.0.0
360+
**Maintainer:** Azion WebKit Team

0 commit comments

Comments
 (0)