feat(cicd): Configure build, deployment and add documentation (#14)

* build(config): add license, types and files to package.json

* refactor(vite): use ts for index.ts

* fix(releaserc): typo in css

* fix(vite): fix entrypoint

* fix(build): try to fix build by not specifying "module" in package.json

vitejs/vite#12446 (comment)

* fix(build): try to fix build by following wuruoyun/vue-component-lib-starter

* fix(build): fix typos in package.json

* fix(build): switch to vitepress for demo and developement setup

* feat(build) split up deployment and add gh-pages deployment

* fix(build): add npm ci to deploy-npm job

* fix(build): add vitepress build to job

* fix(build): add path to download-artifact step

.github/workflows/build.yaml

@@ -5,11 +5,38 @@ on: [push]
 jobs:
   build:
     runs-on: ubuntu-latest
+    permissions:
+      contents: read # to be able to publish a GitHub release
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+          registry-url: "https://registry.npmjs.org"
+      - run: npm ci             # install dependencies
+      - run: npm run build      # build library
+      - run: npm run docs:build # build docs
+      - name: upload library artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: library_dist
+          path: ./dist
+      - name: upload vitepress artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: vitepress_dist
+          path: ./docs/.vitepress/dist
+
+  deploy-npm:
+    runs-on: ubuntu-latest
+    needs: build
     permissions:
       contents: write # to be able to publish a GitHub release
       issues: write # to be able to comment on released issues
       pull-requests: write # to be able to comment on released pull requests
       id-token: write # to enable use of OIDC for npm provenance
+    if: github.ref == 'refs/heads/main' || github.ref == 'refs/heads/beta'
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
@@ -18,10 +45,38 @@ jobs:
           cache: "npm"
           registry-url: "https://registry.npmjs.org"
       - run: npm ci        # install dependencies
-      - run: npm run build # or any other step to build your package
+      - name: Download build-results
+        uses: actions/download-artifact@v4
+        with:
+          name: library_dist
+          path: ./dist
       - name: run semantic-release
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
         run: npm run semantic-release
 
+  deploy-gh-pages:
+    runs-on: ubuntu-latest
+    needs: build
+    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
+    permissions:
+      pages: write      # to deploy to Pages
+      id-token: write   # to verify the deployment originates from an appropriate source
+    # Deploy to the github-pages environment
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    if: github.ref == 'refs/heads/main'
+    steps:
+      - name: Download build-results
+        uses: actions/download-artifact@v4
+        with:
+          name: vitepress_dist
+          path: ./docs/.vitepress/dist
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v4
+        id: deployment
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs/.vitepress/dist

.releaserc.json

@@ -22,19 +22,15 @@
       {
         "assets": [
           {
-            "path": "dist/mde5-patternlab-vue.js",
+            "path": "dist/muc-patternlab-vue.es.js",
             "label": "JS distribution"
           },
-          {
-            "path": "dist/mde5-patternlab-vue.umd.cjs",
-            "label": "UMD/CJS distribution"
-          },
           {
             "path": "dist/assets/temporary/muenchende-style.css",
             "label": "CSS distribution"
           },
           {
-            "path": "dist/assets/temporary/muenchende-fontface.css",
+            "path": "dist/assets/temporary/muenchende-fontfaces.css",
             "label": "CSS fontface distribution"
           },
           {

README.md

@@ -20,45 +20,19 @@ See the [open issues](#) for a full list of proposed features (and known issues)
 
 ## Usage
 
-### Installation
-
-```shell
-npm i @muenchen/muc-patternlab-vue
-```
-
-Required Peer Dependencies:
-
-```
-"vue": "^3.4.0"
-```
-
-### Use
-
-e.G. Using the MucBanner-Component:
-
-```vue
-<script setup>
-import { MucBanner } from "@muenchen/muc-patternlab-vue";
-</script>
-
-<template>
-  <muc-banner title="Hello Muc">
-    <div>How are you?</div>
-  </muc-banner>
-</template>
-```
+Please refer to the [documentation](docs/guide/index.md).
 
 ## Develop
 
+### Setup
+
 ```shell
 git clone https://github.com/it-at-m/muc-patternlab-vue.git
 cd muc-patternlab-vue
 npm install
-npm run dev
+npm run docs:dev
 ```
 
-## Documentation
-
 ### Release and Publish
 
 This project uses [semantic-release](https://github.com/semantic-release/semantic-release)!
@@ -76,8 +50,12 @@ It follows [Angulars Commit Message Conventions](https://github.com/angular/angu
 1. Create a new Folder under `./src/components`-Directory
 2. Create Vue-Component (with composition api) and index.ts-File which exports your component
 3. Add your new Component to `./src/components/index.ts`
+4. Create documentation for your component
+   1. Create at least one "Basic" demo at `./docs/components/demo/<your-component>`
+   2. Create a doc-File for your component at `./docs/components/<your-component>.md`
+   3. Add your component doc to the sidebar at `./docs/.vitepress/config.ts`
 
-### Using MDE Patternlab-Icons
+### Using MDE5 Patternlab-Icons
 
 Patternlab-Icons are provided by a svg-Sprite which is automatically injected in this repos App.vue-File for local testing. You can expect the users of this library to do the same thing.
 

docs/.vitepress/components/DemoContainer.vue

@@ -0,0 +1,16 @@
+<script setup>
+import sprites from "../../../public/assets/temporary/muc-icons.svg?raw"
+</script>
+
+<template>
+  <div>
+    <svg
+        style="display: none;"
+        v-html="sprites">
+    </svg>
+
+    <div class="demo-container">
+      <slot></slot>
+    </div>
+  </div>
+</template>

docs/.vitepress/config.ts

@@ -0,0 +1,33 @@
+const path = require('path')
+
+module.exports = {
+  title: 'My Lib',
+  description: 'Just playing around.',
+  themeConfig: {
+    repo: 'https://github.com/wuruoyun/vue-component-lib-starter',
+    sidebar: [
+      {
+        text: 'Introduction',
+        children: [
+          { text: 'What is My Lib?', link: '/' },
+          { text: 'Getting Started', link: '/guide/' },
+        ],
+      }, {
+        text: 'Components',
+        children: [
+          { text: 'MucBanner', link: '/components/muc-banner' },
+          { text: 'MucButton', link: '/components/muc-button' },
+          { text: 'MucIntro', link: '/components/muc-intro' },
+        ],
+      }
+    ],
+  },
+  vite: {
+    resolve: {
+      alias: {
+        'muc-patternlab-vue': path.resolve(__dirname, '../../src'),
+      },
+      dedupe: ['vue'], // avoid error when using dependencies that also use Vue
+    }
+  }
+}

docs/.vitepress/theme/custom.css

@@ -0,0 +1,5 @@
+.demo-container {
+  border: 1px solid lightgrey;
+  border-radius: 5px;
+  padding: 10px 20px;
+}

docs/.vitepress/theme/index.js

@@ -0,0 +1,13 @@
+import DefaultTheme from 'vitepress/theme'
+import DemoContainer from '../components/DemoContainer.vue'
+import MucPatternlabVue from 'muc-patternlab-vue'
+
+import './custom.css'
+
+export default {
+  ...DefaultTheme,
+  enhanceApp({ app }) {
+    app.use(MucPatternlabVue)
+    app.component('DemoContainer', DemoContainer)
+  }
+}

docs/components/demo/MucBanner/Basic.vue

@@ -0,0 +1,20 @@
+<template>
+  <div>
+    <muc-banner type="warning">
+      Lorem ipsum dolor sit amet, consetetur sadipscing elitr.
+    </muc-banner>
+
+    <muc-banner type="emergency">
+      Lorem ipsum dolor sit amet, consetetur sadipscing elitr.
+    </muc-banner>
+
+    <muc-banner type="info">
+      Lorem ipsum dolor sit amet, consetetur sadipscing elitr.
+    </muc-banner>
+  </div>
+</template>
+<style scoped>
+div * {
+  margin-bottom: 16px;
+}
+</style>

docs/components/demo/MucButton/Basic.vue

@@ -0,0 +1,3 @@
+<template>
+  <muc-button>Click me</muc-button>
+</template>

docs/components/demo/MucIntro/Basic.vue

@@ -0,0 +1,6 @@
+<template>
+  <muc-intro title="Intro-Titel">
+    Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum.
+    Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.
+  </muc-intro>
+</template>

docs/components/index.md

@@ -0,0 +1,3 @@
+# Components
+
+You may add a summary of the components here.

docs/components/muc-banner.md

@@ -0,0 +1,35 @@
+<script setup>
+import Basic from './demo/MucBanner/Basic.vue'
+</script>
+
+# muc-banner
+
+//todo describe banner
+
+## Example Usage
+
+<DemoContainer>
+  <Basic/>
+</DemoContainer>
+
+<<< @/components/demo/MucBanner/Basic.vue
+
+## Reference
+
+### Properties
+
+| Name | Type   | Default | Description    |
+| ---- | ------ | ------- | -------------- |
+| msg  | string | null    | Messge to show |
+
+### Events
+
+| Name | Parameters | Description |
+| ---- | ---------- | ----------- |
+|      |            |             |
+
+### Slots
+
+| Name | Parameters | Description |
+| ---- | ---------- | ----------- |
+|      |            |             |

docs/components/muc-button.md

@@ -0,0 +1,35 @@
+<script setup>
+import Basic from './demo/MucButton/Basic.vue'
+</script>
+
+# muc-button
+
+//todo describe button
+
+## Example Usage
+
+<DemoContainer>
+  <Basic/>
+</DemoContainer>
+
+<<< @/components/demo/MucButton/Basic.vue
+
+## Reference
+
+### Properties
+
+| Name | Type   | Default | Description    |
+| ---- | ------ | ------- | -------------- |
+| msg  | string | null    | Messge to show |
+
+### Events
+
+| Name | Parameters | Description |
+| ---- | ---------- | ----------- |
+|      |            |             |
+
+### Slots
+
+| Name | Parameters | Description |
+| ---- | ---------- | ----------- |
+|      |            |             |

docs/components/muc-intro.md

@@ -0,0 +1,35 @@
+<script setup>
+import Basic from './demo/MucIntro/Basic.vue'
+</script>
+
+# muc-intro
+
+//todo describe intro
+
+## Example Usage
+
+<DemoContainer>
+  <Basic/>
+</DemoContainer>
+
+<<< @/components/demo/MucIntro/Basic.vue
+
+## Reference
+
+### Properties
+
+| Name | Type   | Default | Description    |
+| ---- | ------ | ------- | -------------- |
+| msg  | string | null    | Messge to show |
+
+### Events
+
+| Name | Parameters | Description |
+| ---- | ---------- | ----------- |
+|      |            |             |
+
+### Slots
+
+| Name | Parameters | Description |
+| ---- | ---------- | ----------- |
+|      |            |             |