@forsakringskassan/vue-lib-template 1.0.2 → 1.0.4

package/files/_agents/skills/documentation/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: documentation
+description: Write component documentation.
+---
+
+Documentation in this repository uses [`@forsakringskassan/docs-generator`](https://forsakringskassan.github.io/docs-generator/latest/) (source: https://github.com/forsakringskassan/docs-generator) to generate a documentation site.
+When in doubt, you may consult the linked site to find the documentation of the tool itself.
+
+The `docs/` folder holds:
+
+- Build scripts (`docs/build.mts`).
+- Site sourcecode (`docs/src/`).
+- Markdown content.
+
+After building the contents are available in the `public/` folder.
+Files are 1:1 mapped between the `docs/` and `public/` folder, e.g. `docs/components/foo.md` generates `public/components/foo.html`.
+
+## Commands
+
+- `npm run -w docs build` - Build documentation.
+- `npm start -w docs` - Start a webserver hosting the documentation at `http://localhost:8080/`.
+
+If available, use the Chrome Devtools MCP server to access the site.
+
+## Writing documentation
+
+Component documentation is written in Markdown format (`.md`) in the `docs/components` folder.
+Each component should have an associated Markdown file with the same name as the component (e.g. `AwesomeComponent.vue` should have the `AwesomeComponent.md` file).
+Unless instructed otherwise, use Swedish language when writing content.
+Markdown files should be formatted with Prettier.
+
+Use [`template.md`](./template.md) as a template.
+
+The Frontmatter block contains the properties:
+
+- `title` - the document title, should be a human readable name of the component
+- `status` - component status, use `Experimental`, `Draft` or `Produktionsklar` only. If unsure which one to use, ask for clarification.
+- `layout` - must be set to `component` for component documentation.
+- `component` - name of the Vue component.
+
+It may optionally contain these properties:
+
+- `short-title` - a shorter `title` used in the navigation, use this when the regular title is long and/or causes the layout to overflow.
+- `search.terms` - an array of optional keywords the search function should index for this page.
+
+There should not be an h1 heading in the document, it is injected automatically from the `title` property.
+After the preamble and example, start using h2 headings.
+
+Remove sections not relevant to the component, e.g. if it does not have translatable text skip the "Textnycklar" section.
+
+## Examples
+
+Each component documentation should have an example after the preamble.
+Prefer "live examples" over regular runnable examples.
+
+If the component has a "live example", a file with the `LiveExample.vue` suffix, include it with an `import` code fence:
+
+````md
+```import live-example
+FilenameLiveExample.vue
+```
+````
+
+If a live example is not present but the component instead have regular example files, files with the `Example.vue` suffix, include it with an `import` code fence:
+
+````md
+```import
+FilenameExample.vue
+```
+````
+
+If there are no examples, ask for clarification what to do.
+If multiple examples (live examples or regular), ask for clarification which file should be included.
+
+## API
+
+Each component should include the API section and the special `api` container:
+
+```md
+::: api
+vue:ComponentName
+:::
+```
+
+This will insert the generated API documentation for the Vue component with the matching name.
+
+## Grouping related components
+
+A set of related components may optionally be grouped in a subfolder.
+
+```
+example-group
+├── AnotherComponent.md
+├── AwesomeComponent.md
+└── index.json
+```
+
+Each group must have an `index.json` containing the group title (human readable):
+
+```json
+{
+    "title": "Example group"
+}
+```
+
+## Moving files
+
+If a Markdown file is being moved, the Frontmatter block of the file must add the `redirect_from` property:
+
+```
+---
+title: Fantastisk komponent
+redirect_from:
+    - old/old-page.html
+```
+
+The property is an array of old paths (relative to the `public/` folder).
+If the property already exists, add more entries.

package/files/_agents/skills/documentation/template.md

@@ -0,0 +1,33 @@
+---
+title: Komponentens namn
+status: Draft
+layout: component
+component: ComponentName
+---
+
+A short preamble describing the what the component is and is used for.
+
+```import
+ComponentNameExample.vue
+```
+
+## Tänk på att
+
+- Some bullet points with remarks
+- Do's and don'ts
+
+## Copy
+
+- Some bullets points with guidelines about writing copy
+
+## Textnycklar
+
+::: api
+translation:ComponentName
+:::
+
+## API
+
+::: api
+vue:ComponentName
+:::

package/files/_vscode/extensions.json

@@ -0,0 +1,10 @@
+{
+    "recommendations": [
+        "dbaeumer.vscode-eslint",
+        "editorconfig.editorconfig",
+        "esbenp.prettier-vscode",
+        "html-validate.vscode-html-validate",
+        "vitest.explorer",
+        "vue.volar"
+    ]
+}

package/files/_vscode/settings.json

@@ -0,0 +1,13 @@
+{
+    "css.validate": false,
+    "less.validate": false,
+    "scss.validate": false,
+    "eslint.enable": true,
+    "prettier.requireConfig": true,
+    "editor.renderWhitespace": "boundary",
+    "editor.defaultFormatter": "esbenp.prettier-vscode",
+    "explorer.fileNesting.enabled": true,
+    "explorer.fileNesting.patterns": {
+        "tsconfig.json": "tsconfig.*"
+    }
+}

package/files/api-extractor.lib.json

@@ -7,7 +7,7 @@
         "tsconfigFilePath": "<projectFolder>/tsconfig.lib.json"
     },
     "apiReport": {
-        "reportFileName": "<unscopedPackageName>.api.md"
+        "reportFileName": "lib.api.md"
     },
     "docModel": {
         "enabled": true

package/files/api-extractor.selectors.json

@@ -8,7 +8,7 @@
         "tsconfigFilePath": "<projectFolder>/tsconfig.selectors.json"
     },
     "apiReport": {
-        "reportFileName": "<unscopedPackageName>-selectors.api.md"
+        "reportFileName": "selectors.api.md"
     },
     "dtsRollup": {
         "publicTrimmedFilePath": "<projectFolder>/dist/types/selectors.d.ts"

package/files/cypress/support/component.ts

@@ -33,8 +33,12 @@ Cypress.Commands.add("mount", (component, options = {}) => {
             setRunningContext(app);
 
             /* handle warnings as errors */
-            app.config.warnHandler = (msg, b, trace) => {
-                throw new Error(`Vue warning: ${msg}\n${trace}`);
+            app.config.warnHandler = (msg) => {
+                const mochaRunner = Cypress.mocha.getRunner();
+                const body = mochaRunner.test?.body ?? "";
+                if (!body.includes("<expectedException")) {
+                    cy.wrap(`Vue warning: ${msg}`).should("be.empty");
+                }
             };
         },
     });
@@ -42,4 +46,35 @@ Cypress.Commands.add("mount", (component, options = {}) => {
     return mount(component, options);
 });
 
+const uncaughtErrors: string[] = [];
+
+Cypress.on("uncaught:exception", (err) => {
+    const mochaRunner = Cypress.mocha.getRunner();
+    const currentTest = mochaRunner.test;
+
+    const body = currentTest?.body ?? "";
+    const match = body.match(
+        /<expectedException>([\s\S]*?)<\/expectedException>|<expectedException\s*\/>/i,
+    );
+    const message = match ? match[1].trim() : null;
+    if (message?.length === 0 || (message && err.message.includes(message))) {
+        return false;
+    }
+
+    const testName =
+        currentTest?.fullTitle() ?? currentTest?.title ?? "<unknown>";
+
+    uncaughtErrors.push(testName);
+
+    return true;
+});
+
+after(() => {
+    if (uncaughtErrors.length > 0) {
+        throw new Error(
+            `⚠️ Suite failed because an uncaught exception occurred earlier in: ${uncaughtErrors}`,
+        );
+    }
+});
+
 injectSpritesheet();

package/files/cypress/tsconfig.json

@@ -9,7 +9,8 @@
             "cy-mount",
             "cypress-html-validate/commands",
             "@forsakringskassan/cypress-visual-regression/commands",
-            "forced-colors"
+            "forced-colors",
+            "mocha"
         ],
         "typeRoots": ["../node_modules", "../node_modules/@types", "./types"],
         "paths": {

package/files/cypress/types/mocha.d.ts

@@ -0,0 +1,15 @@
+import "mocha";
+
+declare global {
+    namespace Cypress {
+        interface Cypress {
+            /**
+             * Intern referens till Cypress underliggande Mocha-instans.
+             */
+            mocha: {
+                getRunner: () => Mocha.Runner;
+            };
+        }
+    }
+}
+export {};

package/files/docs/package.json

@@ -8,10 +8,10 @@
   },
   "devDependencies": {
     "@fkui/vue": "6.55.0",
-    "@forsakringskassan/docs-generator": "3.6.1",
+    "@forsakringskassan/docs-generator": "3.6.2",
     "@tsconfig/node24": "24.0.5",
     "@tsconfig/recommended": "1.0.13",
     "http-server": "14.1.1",
-    "vue": "3.5.41"
+    "vue": "3.5.42"
   }
 }

package/files/package.json

@@ -1,23 +1,6 @@
 {
   "name": "${name}",
   "version": "${version}",
-  "description": "${description}",
-  "keywords": [
-    "template",
-    "vue",
-    "cloneman",
-    "library"
-  ],
-  "homepage": "https://github.com/Forsakringskassan/vue-lib-template#readme",
-  "bugs": {
-    "url": "https://github.com/Forsakringskassan/vue-lib-template/issues"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Forsakringskassan/vue-lib-template.git"
-  },
-  "license": "MIT",
-  "author": "Försäkringskassan",
   "exports": {
     ".": {
       "types": "./dist/types/index.d.ts",
@@ -93,29 +76,29 @@
     "@forsakringskassan/commitlint-config": "4.2.8",
     "@forsakringskassan/cypress-axe": "5.1.5",
     "@forsakringskassan/cypress-visual-regression": "5.1.0",
-    "@forsakringskassan/docs-generator": "3.6.1",
+    "@forsakringskassan/docs-generator": "3.6.2",
     "@forsakringskassan/docs-live-example": "3.0.1",
-    "@forsakringskassan/eslint-config": "15.8.13",
-    "@forsakringskassan/eslint-config-cli": "15.8.9",
-    "@forsakringskassan/eslint-config-cypress": "15.8.12",
-    "@forsakringskassan/eslint-config-jest": "15.8.9",
-    "@forsakringskassan/eslint-config-typescript": "15.8.14",
-    "@forsakringskassan/eslint-config-typescript-typeinfo": "15.8.14",
-    "@forsakringskassan/eslint-config-vitest": "15.8.11",
-    "@forsakringskassan/eslint-config-vue": "15.8.14",
+    "@forsakringskassan/eslint-config": "15.9.0",
+    "@forsakringskassan/eslint-config-cli": "15.9.0",
+    "@forsakringskassan/eslint-config-cypress": "15.9.0",
+    "@forsakringskassan/eslint-config-jest": "15.9.0",
+    "@forsakringskassan/eslint-config-typescript": "15.9.0",
+    "@forsakringskassan/eslint-config-typescript-typeinfo": "15.9.0",
+    "@forsakringskassan/eslint-config-vitest": "15.9.0",
+    "@forsakringskassan/eslint-config-vue": "15.9.0",
     "@forsakringskassan/prettier-config": "3.7.8",
     "@forsakringskassan/stylelint-config": "3.4.5",
-    "@forsakringskassan/vite-lib-config": "5.10.1",
+    "@forsakringskassan/vite-lib-config": "5.10.2",
     "@forsakringskassan/vitest-config-jsdom": "2.7.0",
-    "@forsakringskassan/vue-lib-template": "1.0.2",
+    "@forsakringskassan/vue-lib-template": "1.0.4",
     "@html-validate/release-scripts": "7.6.8",
     "@types/node": "24.13.3",
     "@typescript/native": "npm:typescript@7.0.2",
-    "@vue/server-renderer": "3.5.41",
-    "@vue/test-utils": "2.4.11",
-    "cloneman": "1.19.6",
+    "@vue/server-renderer": "3.5.42",
+    "@vue/test-utils": "2.5.0",
+    "cloneman": "1.22.0",
     "core-js": "3.50.0",
-    "cypress": "15.21.0",
+    "cypress": "15.21.1",
     "cypress-html-validate": "9.0.0",
     "html-validate": "11.10.0",
     "html-validate-markdown": "6.0.0",
@@ -128,7 +111,7 @@
     "typescript": "npm:@typescript/typescript6@6.0.2",
     "vite": "8.2.2",
     "vitest": "4.1.11",
-    "vue": "3.5.41",
+    "vue": "3.5.42",
     "vue-tsc": "3.3.11"
   },
   "peerDependencies": {
@@ -149,9 +132,5 @@
     "fsevents": false,
     "unrs-resolver": true
   },
-  "cloneman": {
-    "template": "@forsakringskassan/vue-lib-template",
-    "version": "1.0.2"
-  },
   "externalDependencies": []
 }

package/files/renovate.json

@@ -1,7 +1,5 @@
 {
-    "extends": [
-        "local>forsakringskassan/renovate-config"
-    ],
+    "extends": ["local>forsakringskassan/renovate-config"],
     "ignoreDeps": [
         "@babel/core",
         "@babel/preset-env",

package/hooks/install.mjs

@@ -0,0 +1,15 @@
+/**
+ * @param {import("cloneman").InstallContext} context
+ */
+export default async (context) => {
+    const { getParameter, updateJsonFile } = context;
+
+    /* write repository url to "package.json" */
+    const repoUrl = getParameter("repo-url");
+    await updateJsonFile("package.json", {
+        repository: {
+            type: "git",
+            url: repoUrl,
+        },
+    });
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forsakringskassan/vue-lib-template",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "Vue library template based on Cloneman",
   "keywords": [
     "template",
@@ -24,19 +24,20 @@
   },
   "cloneman": {
     "boilerplateFiles": [
+      ".agents/skills/documentation/SKILL.md",
+      ".agents/skills/documentation/template.md",
       ".editorconfig",
       ".gitignore",
       ".htmlvalidate.json",
       ".htmlvalidateignore",
       ".prettierignore",
-      "CHANGELOG.md",
-      "CODEOWNERS",
-      "Jenkinsfile",
-      "LICENSE.md",
-      "README.md",
+      ".vscode/extensions.json",
+      ".vscode/settings.json",
       "api-extractor.lib.json",
       "api-extractor.selectors.json",
       "babel.config.js",
+      "CHANGELOG.md",
+      "CODEOWNERS",
       "cypress.config.ts",
       "cypress/fixtures/example.json",
       "cypress/support/commands/forced-colors.ts",
@@ -47,6 +48,7 @@
       "cypress/tsconfig.json",
       "cypress/types/cy-mount.d.ts",
       "cypress/types/forced-colors.d.ts",
+      "cypress/types/mocha.d.ts",
       "docs/build.mts",
       "docs/components/AwesomeComponent.md",
       "docs/components/index.md",
@@ -56,13 +58,16 @@
       "docs/src/setup.ts",
       "docs/tsconfig.json",
       "eslint.config.mjs",
-      "etc/vue-lib-template-selectors.api.md",
-      "etc/vue-lib-template.api.md",
+      "etc/lib.api.md",
+      "etc/selectors.api.md",
+      "Jenkinsfile",
+      "LICENSE.md",
+      "README.md",
       "renovate.json",
+      "src/awesome-component-logic.ts",
       "src/AwesomeComponent.cy.ts",
       "src/AwesomeComponent.vue",
       "src/AwesomeComponentLogic.spec.ts",
-      "src/awesome-component-logic.ts",
       "src/examples/DummyExample.vue",
       "src/index.ts",
       "src/local.scss",
@@ -76,13 +81,18 @@
       "vite.config.mts"
     ],
     "managedFiles": [
+      ".agents/skills/documentation/SKILL.md",
+      ".agents/skills/documentation/template.md",
       ".editorconfig",
       ".gitignore",
       ".htmlvalidate.json",
       ".prettierignore",
+      ".vscode/extensions.json",
+      ".vscode/settings.json",
       "api-extractor.lib.json",
       "api-extractor.selectors.json",
       "babel.config.js",
+      "cypress.config.ts",
       "cypress/fixtures/example.json",
       "cypress/support/commands/forced-colors.ts",
       "cypress/support/common.ts",
@@ -92,7 +102,7 @@
       "cypress/tsconfig.json",
       "cypress/types/cy-mount.d.ts",
       "cypress/types/forced-colors.d.ts",
-      "cypress.config.ts",
+      "cypress/types/mocha.d.ts",
       "docs/build.mts",
       "docs/package.json",
       "docs/src/main.scss",
@@ -123,6 +133,14 @@
       "!@fkui/tsconfig",
       "@forsakringskassan/*-api",
       "fk-icons"
+    ],
+    "parameters": [
+      {
+        "key": "repo-url",
+        "description": "URL to repository",
+        "help": null,
+        "required": true
+      }
     ]
   }
 }