@anievo-id/rbac-evolution-vue 0.8.0 → 0.9.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 (2) hide show
  1. package/README.md +16 -91
  2. package/package.json +2 -2
package/README.md CHANGED
@@ -1,120 +1,45 @@
1
1
  # @anievo-id/rbac-evolution-vue
2
2
 
3
- 📖 **[Documentation](https://creation.anievo.id/rbac-evolution/frameworks/vue)**
3
+ Vue 3 bindings for [RBAC Evolution](https://github.com/AniEvo-ID/rbac-evolution): `v-can` and `v-role`, `<Can>` and
4
+ `<HasRole>`, composables and `$can()`, the counterpart of spatie's `@can` and `@role` Blade directives.
4
5
 
5
- Vue 3 bindings for [rbac-evolution](https://github.com/AniEvo-ID/rbac-evolution): a `v-can` / `v-role` directive, `<Can>` / `<HasRole>` components,
6
- composables and template helpers — the Vue counterpart of spatie/laravel-permission's `@can` / `@role` Blade directives.
6
+ > **UI only.** Everything in this package runs in the browser and only decides what the UI shows. Always check
7
+ > permissions on the server too.
7
8
 
8
- > **Security note:** everything in this package runs in the browser and only decides what the UI *shows*.
9
- > A user can always edit client-side state. **Always enforce authorization on the server**
10
- > (e.g. with [`@anievo-id/rbac-evolution-express`](https://www.npmjs.com/package/@anievo-id/rbac-evolution-express)).
9
+ ## Install
11
10
 
12
11
  ```bash
13
- npm i @anievo-id/rbac-evolution @anievo-id/rbac-evolution-vue
12
+ npm i @anievo-id/rbac-evolution @anievo-id/rbac-evolution-vue vue
14
13
  ```
15
14
 
16
- ## Setup
17
-
18
- Send the user's snapshot from the server (`await rbac.for(user).snapshot()` → `{ roles, permissions }`)
19
- and install the plugin:
15
+ ## Usage
20
16
 
21
17
  ```ts
22
18
  import { createApp } from 'vue'
23
19
  import { createRbacPlugin } from '@anievo-id/rbac-evolution-vue'
24
20
 
21
+ // the snapshot comes from the server: await rbac.for(user).snapshot(), or null for guests
25
22
  export const rbac = createRbacPlugin({
26
- snapshot: await fetch('/api/me/permissions').then((r) => r.json()), // or null for guests
27
- wildcard: true, // match `articles.*` like the server (must mirror `createRbac({ wildcard })`)
28
- superAdminRoles: ['super-admin'], // these roles pass every permission check
23
+ snapshot: await fetch('/api/me/permissions').then((r) => r.json()),
24
+ wildcard: true, // must mirror createRbac({ wildcard })
29
25
  })
30
26
 
31
27
  createApp(App).use(rbac).mount('#app')
32
28
 
33
- // after login / logout — everything re-renders:
34
- rbac.setSnapshot(await fetch('/api/me/permissions').then((r) => r.json()))
35
- rbac.setSnapshot(null)
29
+ rbac.setSnapshot(null) // after logout; everything re-renders
36
30
  ```
37
31
 
38
- The object returned by `createRbacPlugin` is also the RBAC instance, so it can be used outside
39
- components (router guards, Pinia stores): `rbac.can('edit articles')`.
40
-
41
- Options: `snapshot`, `wildcard`, `superAdminRoles`, and `directives` / `components` / `globalProperties`
42
- (all `true` by default) to opt out of global registration.
43
-
44
- ## Directives
45
-
46
- Elements are hidden with `display: none` (like `v-show`) and re-evaluated whenever the snapshot or the bound value changes.
47
-
48
32
  ```vue
49
33
  <button v-can="'edit articles'">Edit</button>
50
- <button v-can="['edit articles', 'publish articles']">Edit & publish</button> <!-- all -->
51
- <button v-can.all="['edit articles', 'publish articles']">Edit & publish</button>
52
- <button v-can.any="['edit articles', 'delete articles']">Moderate</button>
53
- <p v-can.not="'edit articles'">Read only</p>
54
-
55
- <a v-role="'admin'">Admin</a>
56
- <a v-role="'admin|editor'">Staff</a> <!-- any (spatie pipe syntax) -->
57
- <a v-role="['admin', 'editor']">Staff</a> <!-- any -->
58
- <a v-role.all="['writer', 'editor']">Both</a>
59
- <a v-role.not="'banned'">Post a comment</a>
60
- ```
61
-
62
- Need the element gone from the DOM instead of hidden? Use `v-if="$can(...)"` or `<Can>`.
63
-
64
- ## Components
65
-
66
- ```vue
67
- <Can permission="edit articles">
68
- <EditButton />
69
- <template #fallback>You can't edit this article.</template>
70
- </Can>
71
-
72
- <Can :any-of="['edit articles', 'delete articles']">...</Can>
73
- <Can :all-of="['edit articles', 'publish articles']">...</Can>
74
- <Can permission="edit articles" not>Read only</Can>
75
-
76
- <HasRole role="admin">...</HasRole>
77
- <HasRole role="admin|editor">...</HasRole>
78
- <HasRole :all-of="['writer', 'editor']">...</HasRole>
34
+ <a v-role="'admin|editor'">Staff</a>
35
+ <Can permission="publish articles"><PublishButton /></Can>
79
36
  ```
80
37
 
81
- They are registered globally by the plugin; you can also import them: `import { Can, HasRole } from '@anievo-id/rbac-evolution-vue'`.
82
-
83
- ## Composables
84
-
85
- All return a `ComputedRef<boolean>` and accept a value, a ref or a getter.
86
-
87
- ```ts
88
- import { useCan, useCanAll, useCanAny, useHasRole, useHasAnyRole, useRbac } from '@anievo-id/rbac-evolution-vue'
89
-
90
- const canEdit = useCan('edit articles')
91
- const canModerate = useCanAny(['edit articles', 'delete articles'])
92
- const canEditThis = useCan(() => `edit ${props.type}`)
93
- const isStaff = useHasRole('admin|editor')
94
-
95
- const rbac = useRbac() // the instance: rbac.can(), rbac.hasRole(), rbac.snapshot, rbac.setSnapshot()
96
- ```
97
-
98
- ## Template helpers
99
-
100
- ```vue
101
- <button v-if="$can('edit articles')">Edit</button>
102
- <span v-if="$hasRole('admin')">Admin</span>
103
- <!-- also: $cannot, $canAny, $canAll, $hasAnyRole, $hasAllRoles, $rbac -->
104
- ```
105
-
106
- They are typed through `ComponentCustomProperties` module augmentation — nothing to configure.
107
-
108
- ## Semantics
38
+ `v-can` hides the element with `display: none`. Use `v-if="$can(...)"` or `<Can>` to keep it out of the DOM.
109
39
 
110
- | Check | Single | List | `'a\|b'` |
111
- | --- | --- | --- | --- |
112
- | `can` / `v-can` / `<Can permission>` | has it | **all** | literal name |
113
- | `canAny` / `v-can.any` / `<Can any-of>` | has it | any | literal name |
114
- | `hasRole` / `v-role` / `<HasRole role>` | has it | **any** | any |
115
- | `hasAllRoles` / `v-role.all` / `<HasRole all-of>` | has it | all | all |
40
+ ## Documentation
116
41
 
117
- An empty list never passes.
42
+ https://creation.anievo.id/rbac-evolution/frameworks/vue
118
43
 
119
44
  ## License
120
45
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@anievo-id/rbac-evolution-vue",
3
- "version": "0.8.0",
3
+ "version": "0.9.0",
4
4
  "description": "Vue 3 bindings for rbac-evolution: v-can directive & composables.",
5
5
  "license": "MIT",
6
6
  "author": "AniEvo-ID (https://github.com/AniEvo-ID)",
@@ -47,7 +47,7 @@
47
47
  "access": "public"
48
48
  },
49
49
  "dependencies": {
50
- "@anievo-id/rbac-evolution": "^0.8.0"
50
+ "@anievo-id/rbac-evolution": "^0.9.0"
51
51
  },
52
52
  "peerDependencies": {
53
53
  "vue": ">=3.3"