vue-accessguard 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sawalabs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,181 @@
+<div align="center">
+  <img src="./public/logo.png" alt="AccessGuard Logo" width="100%" />
+</div>
+
+# @sawalabs/vue-accessguard
+
+The **vue-accessguard** library is a robust, lightweight **Role-Based Access Control (RBAC)** solution for **Vue 3** applications. It provides granular control over UI rendering and module protection using Directives, Components, and Composables for protecting views depending on user *roles* or *permissions*. It supports dynamic **Wildcard Matching** (e.g. `*` for Super Admin or `resource:*` for namespaces).
+
+![Vue 3](https://img.shields.io/badge/Vue.js-3.5%2B-brightgreen?logo=vuedotjs)
+![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue)
+![Storybook](https://img.shields.io/badge/Storybook-10.2-FF4785)
+
+## Features
+- 🚀 **`v-can` Directive:** Quickly hide DOM elements using logical checks.
+- 📦 **`<Guard>` Component:** Dynamically render elements reactively if conditions are met.
+- 🛠️ **Composable (`useAccessGuard`):** A unified API to pragmatically validate authorization states within Vue components logic/setup context.
+- ⭐ **Wildcard Permissions:** Simplify access checks using wildcard notation like `admin:*` or globally with `*`.
+- 📘 **Storybook Integrated:** Interactive visual documentation inside `./src/stories`.
+- ⚡ **Vite Support:** ES / UMD modules included. Built tightly with Vue 3 `provide` / `inject`.
+
+
+## Installation
+
+Using `pnpm`, `npm` or `yarn`:
+
+```bash
+pnpm add @sawalabs/vue-accessguard
+```
+
+## Setup & Configuration
+
+Vue-accessguard needs an `AccessGuardProvider` context wrapped around the app layout. You need to provide user data with their `roles` and `permissions` to allow access management globally.
+
+### 1. Register the Plugin
+Include the plugin into your main entry file, like `main.ts`, in order to register the `v-can` directive globally.
+
+```typescript
+import { createApp } from 'vue'
+import App from './App.vue'
+import { install as AccessGuardPlugin } from '@sawalabs/vue-accessguard'
+
+const app = createApp(App)
+
+app.use(AccessGuardPlugin)
+app.mount('#app')
+```
+
+### 2. Wrap App with `AccessGuardProvider`
+Add `AccessGuardProvider` at the root component or main application layout. Supply the user permissions asynchronously.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { AccessGuardProvider, type AccessUser } from '@sawalabs/vue-accessguard'
+
+// Example of authentication user state
+const currentUser = ref<AccessUser>({
+  roles: ['editor'],
+  permissions: ['post:read', 'post:write']
+})
+</script>
+
+<template>
+  <AccessGuardProvider :user="currentUser">
+    <AppContent />
+  </AccessGuardProvider>
+</template>
+```
+
+---
+
+## Core Concepts
+
+Understanding these fundamental access concepts is the key to effectively using the Vue AccessGuard library parameters:
+
+### `permissions` vs `roles`
+* **`permissions`**: Fine-grained, action-oriented strings that explicitly describe what an entity can *do* within a system (e.g., `'article:read'`, `'post:delete'`, `'user:impersonate'`). Usually, these reflect direct API actions or view visibility rules.
+* **`roles`**: Generalized groups or titles assigned to a user (e.g., `'admin'`, `'editor'`, `'viewer'`). Behind the scenes, a role is essentially a collection of various permissions. Use `roles` across broad system boundaries (e.g., entirely hiding the "Admin Area Layout") and `permissions` for specific sub-components (e.g., the "Delete" button within the dashboard).
+
+### Match Modes (`any` vs `all`)
+Whenever you pass an array of required roles or permissions strings to evaluate, AccessGuard needs to know *how* to evaluate them using the `mode` parameter:
+* **`mode: 'any'` (Default)**: The check passes if the authenticated user has **at least one** of the requested strings. Used as a logical **OR**.
+* **`mode: 'all'`**: The check strictly passes only if the authenticated user has **100%** of the requested strings. Used as a logical **AND**.
+
+---
+
+## Directives (`v-can`)
+
+The `v-can` directive removes elements from the screen by manipulating the style `display: none` property based on user permissions.
+
+```vue
+<template>
+  <!-- Single permission check -->
+  <button v-can="'post:delete'">Delete Post</button>
+
+  <!-- Multiple permission check (any of them will render) -->
+  <button v-can="['post:edit', 'post:delete']">Manage Post</button>
+
+  <!-- Strictly require ALL permissions in the array -->
+  <button v-can="{ permission: ['post:edit', 'post:publish'], mode: 'all' }">
+    Publish Post
+  </button>
+</template>
+```
+
+---
+
+## Component (`<Guard>`)
+
+The `<Guard>` component conditionally renders DOM trees based on *roles* or *permissions*. Unlike `v-can`, the entire DOM subtree inside `Guard` isn't created if the authorization fails.
+
+```vue
+<script setup lang="ts">
+import { Guard } from '@sawalabs/vue-accessguard'
+</script>
+
+<template>
+  <!-- Renders if user has 'admin' or 'manager' role -->
+  <Guard :role="['admin', 'manager']" mode="any">
+    <AdminPanel />
+  </Guard>
+
+  <!-- Only renders if user has both permissions -->
+  <Guard :permission="['user:create', 'user:delete']" mode="all">
+    <UserManagement />
+  </Guard>
+</template>
+```
+
+---
+
+## Composable (`useAccessGuard`)
+
+Used inside `<script setup>` contexts to handle granular logical flows pragmatically.
+
+```vue
+<script setup lang="ts">
+import { useAccessGuard } from '@sawalabs/vue-accessguard'
+
+const { can, cannot, hasRole } = useAccessGuard()
+
+const submitForm = () => {
+  if (!hasRole('admin')) {
+    alert("Admins only!")
+    return
+  }
+  
+  if (can(['article:write', 'article:publish'], 'all')) {
+    console.log("Ready to execute logic.")
+  }
+}
+</script>
+
+<template>
+  <button @click="submitForm" :disabled="cannot('article:publish')">
+    Submit
+  </button>
+</template>
+```
+
+---
+
+## Wildcard Matching
+
+Vue-accessguard scales linearly with enterprise needs with built in string-based access matchers:
+
+- **Super Admin (`*`)**: Given the string `['*']`, AccessGuard bypasses all validations locally. Giving infinite access to all parts.
+- **Resource Wildcard (`[resource]:*`)**: Providing user permissions such as `['post:*']` covers all operations linked to `can('post:read')`, `can('post:delete')`, `can('post:create')`.
+
+## Storybook
+
+You can visually test permission mocking by launching Storybook locally:
+
+```bash
+pnpm run storybook
+```
+
+Navigate to `http://localhost:6006` to modify UI controls, testing elements against random permutations.
+
+---
+**License**: MIT 

package/dist/vue-access-guard.es.js

@@ -0,0 +1,112 @@
+import { defineComponent as l, toRef as y, provide as A, effectScope as v, watchEffect as h, inject as G, computed as w } from "vue";
+const u = /* @__PURE__ */ Symbol("AccessGuard"), b = l({
+  name: "AccessGuardProvider",
+  props: {
+    user: {
+      type: Object,
+      required: !0
+    }
+  },
+  setup(r, { slots: n }) {
+    const s = y(r, "user");
+    return A(u, {
+      user: s
+    }), () => n.default?.();
+  }
+});
+function d(r, n, s = "any") {
+  if (!r?.length) return !1;
+  const t = Array.isArray(n) ? n : [n], e = (o) => {
+    if (r.includes("*") || r.includes(o)) return !0;
+    const [c] = o.split(":"), i = `${c}:*`;
+    return r.includes(i);
+  };
+  return s === "all" ? t.every(e) : t.some(e);
+}
+const S = {
+  mounted(r, n) {
+    const s = n.instance;
+    if (!s) return;
+    let t = s.$.parent, e;
+    for (; t && !e; )
+      e = t.provides?.[u], t = t.parent;
+    if (!e)
+      throw new Error("[AccessGuard] v-can used outside AccessGuardProvider");
+    const o = v();
+    o.run(() => {
+      h(() => {
+        const c = n.value;
+        let i, a = "any";
+        typeof c == "string" || Array.isArray(c) ? i = c : (i = c.permission, a = c.mode ?? "any");
+        const m = e.user.value?.permissions ?? [], p = d(m, i, a);
+        r.style.display = p ? "" : "none";
+      });
+    }), r._scope = o;
+  },
+  unmounted(r) {
+    r._scope?.stop();
+  }
+};
+function f() {
+  const r = G(
+    u
+  );
+  if (!r)
+    throw new Error("useAccessGuard must be used within AccessGuardProvider");
+  const n = (t, e = "any") => {
+    const o = r.user.value?.permissions || [];
+    return d(o, t, e);
+  };
+  return {
+    can: n,
+    cannot: (t, e) => !n(t, e),
+    hasRole: (t, e = "any") => {
+      const o = r.user.value?.roles || [], c = Array.isArray(t) ? t : [t];
+      return e === "all" ? c.every((i) => o.includes(i)) : c.some((i) => o.includes(i));
+    }
+  };
+}
+const g = l({
+  name: "Guard",
+  props: {
+    permission: {
+      type: [String, Array],
+      required: !1
+    },
+    role: {
+      type: [String, Array],
+      required: !1
+    },
+    mode: {
+      type: String,
+      default: "any"
+    }
+  },
+  setup(r, { slots: n }) {
+    const s = f(), t = w(() => {
+      if (!r.permission && !r.role) return !0;
+      let e = !0;
+      return r.permission && (e = e && s.can(r.permission, r.mode)), r.role && e && (e = e && s.hasRole(r.role, r.mode)), e;
+    });
+    return () => t.value ? n.default?.() : null;
+  }
+});
+function x(r) {
+  const { can: n, hasRole: s } = f();
+  return r.beforeEach((t) => {
+    const e = t.meta;
+    if (e.permission && !n(e.permission, e.mode) || e.role && !s(e.role, e.mode))
+      return e.redirect || "/";
+  });
+}
+function E(r) {
+  r.directive("can", S);
+}
+export {
+  b as AccessGuardProvider,
+  u as AccessGuardSymbol,
+  g as Guard,
+  x as applyAccessGuard,
+  E as install,
+  f as useAccessGuard
+};

package/dist/vue-access-guard.umd.js

@@ -0,0 +1 @@
+(function(t,c){typeof exports=="object"&&typeof module<"u"?c(exports,require("vue")):typeof define=="function"&&define.amd?define(["exports","vue"],c):(t=typeof globalThis<"u"?globalThis:t||self,c(t.VueAccessGuard={},t.Vue))})(this,(function(t,c){"use strict";const d=Symbol("AccessGuard"),y=c.defineComponent({name:"AccessGuardProvider",props:{user:{type:Object,required:!0}},setup(r,{slots:s}){const o=c.toRef(r,"user");return c.provide(d,{user:o}),()=>s.default?.()}});function f(r,s,o="any"){if(!r?.length)return!1;const n=Array.isArray(s)?s:[s],e=i=>{if(r.includes("*")||r.includes(i))return!0;const[u]=i.split(":"),a=`${u}:*`;return r.includes(a)};return o==="all"?n.every(e):n.some(e)}const p={mounted(r,s){const o=s.instance;if(!o)return;let n=o.$.parent,e;for(;n&&!e;)e=n.provides?.[d],n=n.parent;if(!e)throw new Error("[AccessGuard] v-can used outside AccessGuardProvider");const i=c.effectScope();i.run(()=>{c.watchEffect(()=>{const u=s.value;let a,m="any";typeof u=="string"||Array.isArray(u)?a=u:(a=u.permission,m=u.mode??"any");const v=e.user.value?.permissions??[],w=f(v,a,m);r.style.display=w?"":"none"})}),r._scope=i},unmounted(r){r._scope?.stop()}};function l(){const r=c.inject(d);if(!r)throw new Error("useAccessGuard must be used within AccessGuardProvider");const s=(n,e="any")=>{const i=r.user.value?.permissions||[];return f(i,n,e)};return{can:s,cannot:(n,e)=>!s(n,e),hasRole:(n,e="any")=>{const i=r.user.value?.roles||[],u=Array.isArray(n)?n:[n];return e==="all"?u.every(a=>i.includes(a)):u.some(a=>i.includes(a))}}}const A=c.defineComponent({name:"Guard",props:{permission:{type:[String,Array],required:!1},role:{type:[String,Array],required:!1},mode:{type:String,default:"any"}},setup(r,{slots:s}){const o=l(),n=c.computed(()=>{if(!r.permission&&!r.role)return!0;let e=!0;return r.permission&&(e=e&&o.can(r.permission,r.mode)),r.role&&e&&(e=e&&o.hasRole(r.role,r.mode)),e});return()=>n.value?s.default?.():null}});function G(r){const{can:s,hasRole:o}=l();return r.beforeEach(n=>{const e=n.meta;if(e.permission&&!s(e.permission,e.mode)||e.role&&!o(e.role,e.mode))return e.redirect||"/"})}function h(r){r.directive("can",p)}t.AccessGuardProvider=y,t.AccessGuardSymbol=d,t.Guard=A,t.applyAccessGuard=G,t.install=h,t.useAccessGuard=l,Object.defineProperty(t,Symbol.toStringTag,{value:"Module"})}));

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "vue-accessguard",
+  "publishConfig": {
+    "access": "public"
+  },
+  "version": "1.0.0",
+  "type": "module",
+  "main": "dist/vue-access-guard.umd.js",
+  "module": "dist/vue-access-guard.es.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "import": "./dist/vue-access-guard.es.js",
+      "require": "./dist/vue-access-guard.umd.js"
+    }
+  },
+  "dependencies": {
+    "vue": "^3.5.25"
+  },
+  "devDependencies": {
+    "@chromatic-com/storybook": "^3.2.7",
+    "@storybook/addon-a11y": "^8.6.17",
+    "@storybook/addon-actions": "^8.6.17",
+    "@storybook/addon-docs": "^8.6.17",
+    "@storybook/addon-onboarding": "^8.6.17",
+    "@storybook/blocks": "^8.6.14",
+    "@storybook/vue3": "^8.6.17",
+    "@storybook/vue3-vite": "^8.6.17",
+    "@types/node": "^24.10.1",
+    "@vitejs/plugin-vue": "^6.0.2",
+    "@vitest/browser-playwright": "4.0.18",
+    "@vitest/coverage-v8": "4.0.18",
+    "@vue/test-utils": "^2.4.6",
+    "@vue/tsconfig": "^0.8.1",
+    "jsdom": "^28.1.0",
+    "playwright": "^1.58.2",
+    "storybook": "^8.6.17",
+    "storybook-vue3-router": "^4.0.1",
+    "typescript": "~5.9.3",
+    "vite": "^7.3.1",
+    "vitest": "^4.0.18",
+    "vue-router": "^4.6.4",
+    "vue-tsc": "^3.1.5"
+  },
+  "peerDependencies": {
+    "vue": "^3.5.29"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "dev": "vite",
+    "build": "vue-tsc -b && vite build",
+    "storybook": "storybook dev -p 6006",
+    "build-storybook": "storybook build"
+  }
+}