feat(vue)!: add vue transpiler 🚀 (#436)

Co-authored-by: Maurício Mutte <[email protected]>

README.md

@@ -23,6 +23,7 @@
 | ------- | ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
 | Core | [`@juntossomosmais/atomium`](https://github.com/juntossomosmais/atomium/pkgs/npm/atomium) | <img src="https://img.shields.io/github/package-json/v/juntossomosmais/atomium?filename=packages%2Fcore%2Fpackage.json" alt="version"> | [README](./packages/core/README.md)   |
 | React | [`@juntossomosmais/atomium/react`](https://github.com/juntossomosmais/atomium/pkgs/npm/atomium) | <img src="https://img.shields.io/github/package-json/v/juntossomosmais/atomium?filename=packages%2Fcore%2Fpackage.json" alt="version"> | [README](./packages/react/README.md)  |
+| Vue | [`@juntossomosmais/atomium/vue`](https://github.com/juntossomosmais/atomium/pkgs/npm/atomium) | <img src="https://img.shields.io/github/package-json/v/juntossomosmais/atomium?filename=packages%2Fcore%2Fpackage.json" alt="version"> | [README](./packages/react/README.md)  |
 | Tokens | [`@juntossomosmais/atomium-tokens`](https://github.com/juntossomosmais/atomium/pkgs/npm/atomium-tokens) | <img src="https://img.shields.io/github/package-json/v/juntossomosmais/atomium?filename=packages%2Ftokens%2Fpackage.json" alt="version"> | [README](./packages/tokens/README.md) |
 
 ## About
@@ -69,6 +70,12 @@ If you want to run React Stories locally, you need to run the following command
 npm run docs-react:start
 ```
 
+And if you want to run Vue Stories locally, you need to run the following command before `npm start`:
+
+```bash
+npm run docs-vue:start
+```
+
 ### Running Tests
 
 ```bash
@@ -89,8 +96,10 @@ npm run docs:build
 
 * `apps/docs`: Contains the main documentation for the project.
 * `apps/docs-react`: Provides a React version of Storybook for showcasing components.
+* `apps/docs-vue`: Provides a Vue version of Storybook for showcasing components.
 * `packages/core`: The core of Atomium, responsible for building all the components.
 * `packages/react`: The React version of Atomium, automatically generated by Stencil.
+* `packages/vue`: The Vue version of Atomium, automatically generated by Stencil.
 * `packages/tokens`: Contains the design tokens for Atomium, where all the tokens are defined.
 * `packages/icons`: Contains the icons used in Atomium, where all the icons are stored.
 * `utils/**`: Contains utility modules used throughout the project, providing various helper functions and tools.

apps/docs-react/.storybook/preview.ts

@@ -1,5 +1,3 @@
-import { defineCustomElements } from '@juntossomosmais/atomium/loader'
-
 import { CustomViewports } from '@atomium/storybook-utils/custom-viewports'
 import DocumentationTemplate from '@atomium/storybook-utils/DocumentationTemplate.mdx'
 
@@ -8,8 +6,6 @@ import '@atomium/storybook-utils/preview.css'
 import '@juntossomosmais/atomium-tokens/tokens.css'
 import '@juntossomosmais/atomium/dist/core/core.css'
 
-defineCustomElements()
-
 const preview = {
   parameters: {
     viewport: {

apps/docs-vue/.storybook/main.ts

@@ -0,0 +1,21 @@
+module.exports = {
+  stories: [
+    '../stories/*.stories.@(js|jsx|ts|tsx|mdx)',
+    '../../../packages/core/src/**/*.vue.stories.@(js|jsx|ts|tsx|mdx)',
+  ],
+  addons: [
+    '@storybook/addon-essentials',
+    '@storybook/addon-docs',
+    '@storybook/addon-actions',
+    '@storybook/addon-a11y',
+    '@storybook/addon-viewport',
+    '@storybook/theming',
+  ],
+  framework: {
+    name: '@storybook/vue3-vite',
+    options: {},
+  },
+  docs: {
+    autodocs: true,
+  },
+}

apps/docs-vue/.storybook/manager-head.html

@@ -0,0 +1,7 @@
+<meta name="robots" content="noindex" />
+
+<style>
+  .sidebar-subheading {
+    letter-spacing: 0.2em !important;
+  }
+</style>

apps/docs-vue/.storybook/manager.ts

@@ -0,0 +1,7 @@
+import { addons } from '@storybook/addons'
+
+import theme from '@atomium/storybook-utils/theme'
+
+addons.setConfig({
+  theme,
+})

apps/docs-vue/.storybook/preview.ts

@@ -0,0 +1,21 @@
+import { CustomViewports } from '@atomium/storybook-utils/custom-viewports'
+import DocumentationTemplate from '@atomium/storybook-utils/DocumentationTemplate.mdx'
+
+import '@atomium/storybook-utils/preview.css'
+
+import '@juntossomosmais/atomium-tokens/tokens.css'
+import '@juntossomosmais/atomium/dist/core/core.css'
+
+const preview = {
+  parameters: {
+    viewport: {
+      viewports: CustomViewports,
+    },
+    actions: { argTypesRegex: '^atom.*' },
+    docs: {
+      page: DocumentationTemplate,
+    },
+  },
+}
+
+export default preview

apps/docs-vue/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@atomium/docs-vue",
+  "private": true,
+  "scripts": {
+    "start": "storybook dev -p 8006 --no-open",
+    "build": "storybook build -o ../docs/storybook-static/vue"
+  },
+  "nx": {
+    "targets": {
+      "build": {
+        "dependsOn": [
+          {
+            "projects": [
+              "@juntossomosmais/atomium-vue"
+            ],
+            "target": "build"
+          }
+        ]
+      }
+    }
+  }
+}

apps/docs-vue/stories/0_Introduction.stories.mdx

@@ -0,0 +1,34 @@
+import { Meta } from '@storybook/addon-docs'
+
+<Meta title='Introduction' />
+
+# About Vue Components
+
+All [Vue Components is generated by Stencil](https://stenciljs.com/docs/vue) using [Stencil's output target](https://stenciljs.com/docs/vue#output-targets) to automatically generate Vue components from our Atomium's web components.
+
+The target of this stories is run Atomium's web components in Vue environment and show how to use the components.
+
+**!important**
+
+There is a problem to render the code of [Vue's components outputed by Stencil in Storybook](https://github.com/storybookjs/storybook/issues/22287), so the code of the components is not shown correctly in the stories.
+
+Example, in [Button component](?path=/docs/react_components-button--docs):
+
+```jsx
+{
+  render: args => createButton(args),
+  args: {
+    ...ButtonComponentArgs
+  }
+}
+```
+
+The code above is not shown correctly in the stories, but it is correct in the source code:
+
+```jsx
+<AtomButton color='primary' fill='solid' mode='md' shape='round' type='button'>
+  Button
+</AtomButton>
+```
+
+Just keep in mind that when check the code of the components inside Storybook

apps/docs-vue/vite.config.js

@@ -0,0 +1,14 @@
+import { fileURLToPath, URL } from 'node:url'
+
+import vue from '@vitejs/plugin-vue'
+import { defineConfig } from 'vite'
+
+// https://vitejs.dev/config/
+export default defineConfig({
+  plugins: [vue()],
+  resolve: {
+    alias: {
+      '@': fileURLToPath(new URL('./src', import.meta.url)),
+    },
+  },
+})

apps/docs/.storybook/main.ts

@@ -1,5 +1,32 @@
 import type { StorybookConfig } from '@storybook/web-components-webpack5'
 
+function getStorybookRefs(configType: string) {
+  if (configType === 'DEVELOPMENT') {
+    return {
+      react: {
+        title: 'React (localhost:7006)',
+        url: 'http://localhost:7006',
+      },
+      vue: {
+        title: 'Vue (localhost:8006)',
+        url: 'http://localhost:8006',
+      },
+    }
+  }
+  return {
+    react: {
+      title: 'React Library',
+      url: 'react',
+      expanded: false,
+    },
+    vue: {
+      title: 'Vue Library',
+      url: 'vue',
+      expanded: false,
+    },
+  }
+}
+
 const config: StorybookConfig = {
   stories: [
     '../stories/**/*.stories.@(js|jsx|ts|tsx|mdx)',
@@ -23,22 +50,8 @@ const config: StorybookConfig = {
   docs: {
     autodocs: true,
   },
-  refs: (config, { configType }) => {
-    if (configType === 'DEVELOPMENT') {
-      return {
-        react: {
-          title: 'React (localhost:7006)',
-          url: 'http://localhost:7006',
-        },
-      }
-    }
-    return {
-      react: {
-        title: 'React Library',
-        url: 'react',
-        expanded: false,
-      },
-    }
+  refs: (config, { configType = '' }) => {
+    return getStorybookRefs(configType)
   },
 }
 

apps/docs/stories/architecture-decision-records/0007-why-do-we-transpile-web-components-for-react-and-vue.stories.mdx

@@ -0,0 +1,40 @@
+import { Meta } from '@storybook/addon-docs'
+
+<Meta title='Docs/Architecture Decision Records/ADR 0007: Why do we transpile Web Components for React and Vue?' />
+
+# ADR 0007: Why do we transpile Web Components for React and Vue?
+
+🗓️ ~2023-04~ 2024-05 · ✍️ [@felipefialho](https://twitter.com/felipefialho_)
+
+## Context
+
+We need to use Web Components in our projects built with Vue and React (Next.js) while maintaining a good Developer Experience (DX).
+
+## Problems
+
+### React
+
+- We need to use `Event Listeners` to handle events and methods when using Web Components
+- React [use `SyntheticEvent` to handle events](https://legacy.reactjs.org/docs/events.html), and we need to convert it to `CustomEvent` to use Web Components
+- Props that use `array` or `object` need to be converted to JSON for compatibility
+- We need to use `ref` to access the Web Component API in React
+- Sometimes, we need to create wrappers to effectively use Web Components in React
+- Overall, the Developer Experience in React is not optimal when working with Web Components
+
+### Vue
+
+- Props that use `array` or `object` need to be converted to JSON for compatibility
+- We need to use `ref` to access the Web Component API in Vue
+- We need to create wrappers to effectively use Web Components in Vue and it is not always straightforward
+
+## Decision
+
+~To address these challenges, we have decided to use Stencil to create a transpiled version of Web Components specifically for React, while keeping the original version for Vue.~
+
+~Currently, we are using Vue 2 (as of April 2022), and the transpiler of Stencil is not compatible with Vue 2, however, Vue provides a good DX and seamless compatibility with Web Components.~
+
+~In the future, when we migrate to Vue 3, we may reevaluate this decision and consider transpiling Web Components for Vue as well.~
+
+### Update
+
+Now we are using Vue 3, and we have decided to transpile Web Components for both React and Vue to provide a better Developer Experience (DX) and to ensure compatibility with the latest versions of both libraries.