feat: ✨ use twoslash for code blocks (#13)

Author: laruiss

docs/.vitepress/config.ts

@@ -1,7 +1,13 @@
+import { transformerTwoslash } from '@shikijs/vitepress-twoslash'
 import { defineConfig } from 'vitepress'
 
 // https://vitepress.dev/reference/site-config
 export default defineConfig({
+  markdown: {
+    codeTransformers: [
+      transformerTwoslash()
+    ]
+  },
   title: "Projets JS/TS",
   description: "Conventions de la Fabrique Numérique",
   themeConfig: {

docs/.vitepress/theme/index.ts

@@ -1,8 +1,13 @@
 // https://vitepress.dev/guide/custom-theme
+import type { EnhanceAppContext } from 'vitepress'
+
 import { h } from 'vue'
 import Theme from 'vitepress/theme'
 import './style.css'
 
+import TwoSlashFloatingVue from '@shikijs/vitepress-twoslash/client'
+import '@shikijs/vitepress-twoslash/style.css'
+
 export default {
   ...Theme,
   outlineTitle: 'Sur cette page',
@@ -11,7 +16,7 @@ export default {
       // https://vitepress.dev/guide/extending-default-theme#layout-slots
     })
   },
-  enhanceApp({ app, router, siteData }) {
-    // ...
+  enhanceApp({ app, router, siteData }: EnhanceAppContext) {
+    app.use(TwoSlashFloatingVue)
   }
 }

docs/api-examples.md

@@ -2,45 +2,30 @@
 
 ## Le composable `useToaster`
 
-```typescript
+```ts twoslash
+const reactive = <T>(val: T): T => val
+// ---cut---
 // use-toaster.ts
-import { reactive } from 'vue'
-
-const alphanumBase = 'abcdefghijklmnopqrstuvwyz0123456789'
-
-const alphanum = alphanumBase.repeat(10)
-
-const getRandomAlphaNum = () => {
-  const randomIndex = Math.floor(Math.random() * alphanum.length)
-  return alphanum[randomIndex]
-}
-
-const getRandomHtmlId = (prefix = '', suffix = '') => {
-  return (prefix ? prefix + '-' : '') + getRandomString(5) + (suffix ? '-' + suffix : '')
-}
-const getRandomString = (length: number) => {
-  return Array.from({ length })
-    .map(getRandomAlphaNum).join('')
-}
+import { getRandomId, type TitleTag } from '@gouvminint/vue-dsfr'
 
 export type Message = {
   id?: string;
   title?: string;
   description: string;
   type: 'info' | 'success' | 'warning' | 'error';
   closeable: boolean;
-  titleTag: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
+  titleTag: TitleTag;
   timeout?: number;
   style?: Record<string, string>;
   class?: string | Record<string, string> | Array<string | Record<string, string>>;
 }
 
 const timeouts: Record<string, number> = {}
-const messages: Message[] = reactive([])
+const messages: Message[] = reactive<Message[]>([])
 
 const useToaster = () => {
 
-  function removeMessage (id: string) {
+  const removeMessage = (id: string): void => {
     const index = messages.findIndex(message => message.id === id)
     clearTimeout(timeouts[id])
     if (index === -1) {
@@ -49,8 +34,8 @@ const useToaster = () => {
     messages.splice(index, 1)
   }
 
-  function addMessage (message: Message) {
-    message.id ??= getRandomHtmlId('toaster')
+  const addMessage = (message: Message): void => {
+    message.id ??= getRandomId('toaster')
     messages.push({ ...message, description: `${message.description} (${message.timeout})` })
     timeouts[message.id] = window.setTimeout(() => removeMessage(message.id as string), message.timeout)
   }
@@ -202,7 +187,7 @@ setTimeout(() => toaster.addMessage({ // Ajout d’un troisième message...
     v-model="searchQuery"
     :service-title="serviceTitle"
     :service-description="serviceDescription"
-    :logo-text="logoText"****
+    :logo-text="logoText"
     :quick-links="quickLinks"
     show-search
   />
@@ -216,6 +201,4 @@ setTimeout(() => toaster.addMessage({ // Ajout d’un troisième message...
     @close-message="toaster.removeMessage($event)"
   />
 </template>
-
-
 ```

docs/client/toaster.md

@@ -24,9 +24,8 @@ Le projet généré contient tout ce qu’il faut pour commencer à travailler
 - une application d’exemple avec un en-tête
 - un router minimal avec deux routes intégré à l’application
 - un store minimal intégré à l’application
+- les plugins [unplugin-auto-import](https://github.com/unplugin/unplugin-auto-import) et [unplugin-vue-components](https://github.com/unplugin/unplugin-vue-components)
 
 ## Ce qu’on peut rajouter
 
-- [prettier](https://prettier.io/)
-- [auto-imports](https://github.com/antfu/unplugin-auto-import) (sera peut-être fait dans une prochaine version de `create-vue-dsfr`)
 - [date-fns](https://date-fns.org/) si le projet manipule et/ou affiche des dates

docs/client/vue3.md

@@ -0,0 +1,45 @@
+@protocol = http
+@host = localhost
+@port = 3000
+@apiPrefix = /api/v1
+@baseUrl = {{protocol}}://{{host}}:{{port}}{{apiPrefix}}
+
+###
+
+{{baseUrl}}/version
+
+
+###
+# @name login
+POST {{baseUrl}}/auth/token HTTP/1.1
+Content-Type: application/json
+
+{
+  "email": "[email protected]",
+  "password": "53CR37P455!"
+}
+
+###
+POST {{baseUrl}}/docs HTTP/1.1
+Content-Type: application/json
+Authorization: Bearer {{login.response.body.token}}
+
+{
+  "title": "Conventions",
+  "description": "Ensemble des conventions (fortement) recommandées pour les projets de la Fabrique Numérique",
+  "tags": ["conventions", "javascript", "typescript"],
+  "content": "Lorem ipsum dolor sit amet, consectetur"
+}
+
+###
+PATCH  {{baseUrl}}/docs/1 HTTP/1.1
+Content-Type: application/json
+Authorization: Bearer {{login.response.body.token}}
+
+{
+  "tags": ["conventions", "javascript", "typescript", "dossiers"],
+}
+
+###
+DELETE  {{baseUrl}}/docs/1 HTTP/1.1
+Authorization: Bearer {{login.response.body.token}}

docs/conventions/api.rest

@@ -26,8 +26,8 @@ insert_final_newline = true
 
 Le code doit être *lint*é et formaté. Le minimum est ESLint avec [standard](https://standardjs.com/) et les seules règles à modifier par rapport à standard sont les suivantes :
 
-- [comma-dangle](https://eslint.org/docs/latest/rules/comma-dangle)
-- [no-irregular-whitespace](https://eslint.org/docs/latest/rules/no-irregular-whitespace)
+- [comma-dangle](https://eslint.org/docs/latest/rules/comma-dangle) : `['error', 'always-multiline']`
+- [no-irregular-whitespace](https://eslint.org/docs/latest/rules/no-irregular-whitespace) : `'warning'`
 
 ```javascript
 rules: {
@@ -37,101 +37,14 @@ rules: {
 }
 ```
 
-Pour NestJS, il faut aussi rajouter ces règles pour les injections de dépendances :
+Pour NestJS, il faut aussi désactiver la règle `no-unused-vars` pour les **injections de dépendances**, autrement dit surcharger les valeurs pour ces 2 règles :
 
 ```javascript
 rules: {
   'no-unused-vars': 'off',
-  '@typescript-eslint/no-unused-vars': 'off',
+  '@typescript-eslint/no-unused-vars': 'off',  // Si vous n’utilisez pas @antfu/eslint-config
+  // 'ts/no-unused-vars': 'off', // Si vous utilisez @antfu/eslint-config
 }
 ```
 
-Un fichier de configuration ESLint pour NestJS :
-
-```javascript
-/* eslint-env node */
-require('@rushstack/eslint-patch/modern-module-resolution')
-
-module.exports = {
-  parser: '@typescript-eslint/parser',
-  plugins: [
-    'prettier', //
-  ],
-  extends: [
-    'eslint:recommended', //
-    'plugin:vue/vue3-recommended',
-    '@vue/eslint-config-typescript/recommended',
-    'standard',
-  ],
-  root: true,
-  env: {
-    node: true,
-    jest: true,
-    'vue/setup-compiler-macros': true,
-  },
-  ignorePatterns: ['.eslintrc.js'],
-  rules: {
-    '@typescript-eslint/interface-name-prefix': 'off', //
-    '@typescript-eslint/explicit-function-return-type': 'off',
-    '@typescript-eslint/explicit-module-boundary-types': 'off',
-    'comma-dangle': ['error', 'always-multiline'],
-  },
-  overrides: [
-    {
-      files: ['cypress/support/*.{js,ts,jsx,tsx}', 'cypress/integration/*.{spec,e2e}.{js,ts,jsx,tsx}', 'src/**/*.ct.{js,ts,jsx,tsx}'],
-      extends: ['plugin:cypress/recommended'],
-    },
-    {
-      files: ['src/**/*.{spec,test}.{js,ts,jsx,tsx}'],
-      env: {
-        jest: true,
-      },
-    },
-  ],
-}
-```
-
-## Optionnellement [Prettier](https://prettier.io/)
-
-Si prettier (>3.0.0) est utilisé en plus d’ESLint, il doit l’être avec la version ces options :
-
-```json
-{
-  "singleQuote": true,
-  "semi": false,
-  "singleAttributePerLine": true
-}
-```
-
-et ESLint doit être utilisé avec [eslint-config-prettier](https://github.com/prettier/eslint-config-prettier),
-et il faut ajouter cette ligne à la configuration eslint :
-
-```diff
-   extends: [
-     'eslint:recommended', //
-     'plugin:vue/vue3-recommended',
-     '@vue/eslint-config-typescript/recommended',
-     'standard',
-+    'plugin:prettier/recommended',
-   ],
-```
-
-### Les scripts de lint et de formattage
-
-Les scripts de formattage et de fix doivent être séparés :
-
-```json
-"lint": "eslint \"{src,apps,libs,test}/**/*.ts\"",
-"format": "eslint \"{src,apps,libs,test}/**/*.ts\" --fix",
-```
-
-Si prettier est utilisé :
-
-```json
-"format": "run-s prettify lint:fix",
-"lint": "eslint \"{src,apps,libs,test}/**/*.ts\"",
-"lint:fix": "eslint \"{src,apps,libs,test}/**/*.ts\" --fix",
-"prettify": "prettier --write \"{src,apps,libs,test}/**/*.ts\"",
-```
-
-`run-s` est issu du package npm [`npm-run-all`](https://github.com/mysticatea/npm-run-all) et signifie « exécution en série », `npm-run-all` a aussi `run-p` qui permet d’exécuter des scripts en parallèle.
+Plus de [détails ici](../outils/eslint.md).

docs/conventions/lint-formattage.md

@@ -0,0 +1,10 @@
+{{baseUrl}}
+###
+
+POST {{baseUrl}} HTTP/1.1
+Content-Type: application/json
+
+{
+  "email": "{{adminUser}}",
+  "password": "{{adminPassword}}"
+}

docs/conventions/test-api.rest

@@ -27,4 +27,4 @@ enum HttpMethod {
 }
 ```
 
-Au lieu d’utiliser les namespaces, il faut utiliser les modules. Cf. Cette réponse sur [SO](https://stackoverflow.com/questions/56059351/tslint-namespace-and-module-are-disallowed#56061134), par exemple.
+Au lieu d’utiliser les namespaces, il faut utiliser les modules. Cf. cette réponse sur [StackOverflow](https://stackoverflow.com/questions/56059351/tslint-namespace-and-module-are-disallowed#56061134), par exemple.