From 1d3ef7cb2be5f15ae1d44519a8b9f2d5704d707f Mon Sep 17 00:00:00 2001 From: stanig2106 Date: Fri, 14 Nov 2025 06:18:04 +0100 Subject: [PATCH] docs: translate readme for release --- README.md | 158 ++++++++++++++++++++++++++++++------------------------ 1 file changed, 89 insertions(+), 69 deletions(-) diff --git a/README.md b/README.md index 85a7b7e..d50406a 100644 --- a/README.md +++ b/README.md @@ -5,29 +5,30 @@ [![License][license-src]][license-href] [![Nuxt][nuxt-src]][nuxt-href] -`nuxt-can` apporte deux directives Vue (`v-can`, `v-cannot`) pour écrire des permissions ultra lisibles dans les templates Nuxt. Les directives sont transformées à la compilation en appels à une fonction `__can__` fournie par l’application hôte tout en restant 100 % tree-shake friendly et parfaitement typées côté TypeScript. +`nuxt-can` ships two Vue directives (`v-can`, `v-cannot`) so you can encode permissions directly in Nuxt templates. Each directive is transformed at build time into a composable `__can__` call provided by your app, keeping the runtime lean, tree-shake friendly, and fully typed. -- [✨  Release Notes](/CHANGELOG.md) +- [✨ Release Notes](/CHANGELOG.md) -## Features +## Highlights -- ✅ Directives `v-can` / `v-cannot` transformées en `v-if` / `!v-if` -- ✅ Merge automatique avec des `v-if` existants (pas de runtime inutile) -- ✅ Proxy global `can` + types générés selon votre configuration de permissions -- ✅ Import configurable de la fonction `__can__` (store, API, …) -- ✅ Erreurs compile-time claires (cas interdits détectés avant build) +- ✅ Cleanly adds permissions to existing templates without rewriting your business `v-if`s +- ✅ Compile-time transform of `v-can` / `v-cannot` into `v-if` guards +- ✅ Smart merge with existing `v-if` conditions (no extra wrappers) +- ✅ Auto-generated `can` proxy with types derived from your permissions map +- ✅ Pluggable import of the host `__can__` function (stores, APIs, etc.) +- ✅ Helpful DX errors for unsupported directive shapes -## Quick Setup +## Quick Start -Installez le module dans votre application Nuxt : +Install the module in your Nuxt app: ```bash npm install nuxt-can -# ou +# or npx nuxi module add nuxt-can ``` -Déclarez ensuite le module et configurez vos permissions : +Enable it inside `nuxt.config.ts` and describe the permissions tree: ```ts // nuxt.config.ts @@ -40,12 +41,12 @@ export default defineNuxtConfig({ employee: ['view', 'edit'], contract: ['create'], }, - canFunctionImport: '~/permissions/can', // chemin vers votre implémentation __can__ + canFunctionImport: '~/permissions/can', // path to your __can__ implementation }, }) ``` -Implémentez la fonction `__can__` dans le fichier ciblé (`~/permissions/can` dans l’exemple) : +Provide the `__can__` implementation referenced above: ```ts // permissions/can.ts @@ -56,88 +57,107 @@ export function __can__(path: string[]) { } ``` -Le module génère automatiquement un proxy `can` typé : +Now you can write directives that stay type-safe: ```vue ``` -Résultat compilé : +…and the compiler rewrites them into plain conditionals: ```vue - - -

Accès refusé

+ + +

Access denied

``` -### Règles et erreurs surveillées +## Usage Rules & Errors -- `v-cannot` doit suivre immédiatement un `v-can` (aucun autre composant entre les deux). -- Un `v-can` ne peut pas cohabiter avec `v-else` / `v-else-if`. -- `v-cannot` n’accepte ni expression, ni argument, ni `v-if`. -- Un seul `v-cannot` par `v-can`. -- Les expressions doivent suivre le pattern `can.x.y` (au moins deux niveaux après `can`). +The transformer validates every template and throws descriptive errors when: -Toute violation produit une erreur compile-time lisible. +- `v-cannot` does not immediately follow its matching `v-can`. +- `v-can` appears on an element already using `v-else` / `v-else-if`. +- `v-cannot` uses an argument, modifiers, or a `v-if` condition. +- Multiple `v-cannot` blocks exist for the same `v-can`. +- The expression is not a static dotted path like `can.resource.action`. -### Types générés +## Generated Types -À partir de la clé `permissions`, le module génère un fichier `.d.ts` qui expose : +The `permissions` map feeds a generated `types/nuxt-can.d.ts` declaration that augments: -- `can` / `$can` sur `ComponentCustomProperties` -- `__can__` sur les templates/scripts Nuxt -- `NuxtApp.$can` et `NuxtApp.$__can__` +- `ComponentCustomProperties` with `can`, `$can`, and `__can__`. +- `NuxtApp` with `$can` and `$__can__`. +- Runtime typings for the `#build/nuxt-can/can-import.mjs` bridge. -La DX template + TypeScript reste donc impeccable sans configuration additionnelle. +No extra setup is required for editors or strict TypeScript projects. +## Why `v-can`? -## Contribution +Retrofitting authorization into an existing codebase often means revisiting every `v-if` to sprinkle permission checks alongside business logic. That makes templates harder to read, increases the risk of regressions, and couples security rules with UI state management. `v-can` and `v-cannot` isolate the permission layer: you keep your original conditions untouched while the transformer injects the `__can__` guards for you. As a result, business logic stays readable, authorization lives in one place, and code reviews can focus on either concern without stepping on each other. -
- Local development - - ```bash - # Install dependencies - npm install - - # Generate type stubs - npm run dev:prepare - - # Develop with the playground - npm run dev - - # Build the playground - npm run dev:build - - # Run ESLint - npm run lint - - # Run Vitest - npm run test - npm run test:watch - - # Release new version - npm run release - ``` +## Playground -
+Run `npm run dev` to explore the playground app located in `/playground`. It demonstrates: +- Stacked `v-can` / `v-cannot` pairs. +- Interaction with existing `v-if`s and `v-for`s. +- Template blocks that share the same permission guard. +- A live permission summary powered by the injected `__can__` function. + +Feel free to wire your own `~/playground/permissions/__can__.ts` to mimic a real backend. + +## Local Development + +```bash +# Install dependencies +npm install + +# Prepare type stubs and the playground +npm run dev:prepare + +# Playground dev server +npm run dev + +# Build the playground +npm run dev:build + +# Lint & tests +npm run lint +npm run test +npm run test:watch + +# Type checks (module + playground) +npm run test:types + +# Release pipeline +npm run release +``` + +## Contributing + +1. Fork & clone the repo. +2. Run `npm run dev:prepare` once to scaffold stubs. +3. Use the playground (`npm run dev`) to reproduce issues. +4. Add tests under `test/` and fixtures under `test/fixtures/*`. +5. Open a PR following Conventional Commits (e.g. `feat:`, `fix:`). + +--- -[npm-version-src]: https://img.shields.io/npm/v/my-module/latest.svg?style=flat&colorA=020420&colorB=00DC82 -[npm-version-href]: https://npmjs.com/package/my-module +[npm-version-src]: https://img.shields.io/npm/v/nuxt-can/latest.svg?style=flat&colorA=020420&colorB=00DC82 +[npm-version-href]: https://npmjs.com/package/nuxt-can -[npm-downloads-src]: https://img.shields.io/npm/dm/my-module.svg?style=flat&colorA=020420&colorB=00DC82 -[npm-downloads-href]: https://npm.chart.dev/my-module +[npm-downloads-src]: https://img.shields.io/npm/dm/nuxt-can.svg?style=flat&colorA=020420&colorB=00DC82 +[npm-downloads-href]: https://npm.chart.dev/nuxt-can -[license-src]: https://img.shields.io/npm/l/my-module.svg?style=flat&colorA=020420&colorB=00DC82 -[license-href]: https://npmjs.com/package/my-module +[license-src]: https://img.shields.io/npm/l/nuxt-can.svg?style=flat&colorA=020420&colorB=00DC82 +[license-href]: https://npmjs.com/package/nuxt-can [nuxt-src]: https://img.shields.io/badge/Nuxt-020420?logo=nuxt.js [nuxt-href]: https://nuxt.com