diff --git a/apps/docs-react/stories/0_Introduction.mdx b/apps/docs-react/stories/0_Introduction.mdx new file mode 100644 index 000000000..4cb3001ea --- /dev/null +++ b/apps/docs-react/stories/0_Introduction.mdx @@ -0,0 +1,9 @@ +import { Meta } from '@storybook/blocks' + + + +# About React Components + +All [React Components is generated by Stencil](https://stenciljs.com/docs/react) using [Stencil's output target](https://stenciljs.com/docs/react#output-targets) to automatically generate React components from our Atomium's web components. + +The target of this stories is run Atomium's web components in React environment and show how to use the components. diff --git a/apps/docs-react/stories/0_Introduction.stories.mdx b/apps/docs-react/stories/0_Introduction.stories.mdx deleted file mode 100644 index 378fad06b..000000000 --- a/apps/docs-react/stories/0_Introduction.stories.mdx +++ /dev/null @@ -1,31 +0,0 @@ -import { Meta } from '@storybook/addon-docs' - - - -# About React Components - -All [React Components is generated by Stencil](https://stenciljs.com/docs/react) using [Stencil's output target](https://stenciljs.com/docs/react#output-targets) to automatically generate React components from our Atomium's web components. - -The target of this stories is run Atomium's web components in React environment and show how to use the components. - -**!important** - -There is a problem to render the code of [React'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 - - Button - -``` - -The code above is not shown correctly in the stories, but it is correct in the source code: - -```jsx - - Button - -``` - -Just keep in mind that when check the code of the components inside Storybook diff --git a/apps/docs-vue/stories/0_Introduction.mdx b/apps/docs-vue/stories/0_Introduction.mdx new file mode 100644 index 000000000..ab1246a25 --- /dev/null +++ b/apps/docs-vue/stories/0_Introduction.mdx @@ -0,0 +1,9 @@ +import { Meta } from '@storybook/blocks' + + + +# 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. diff --git a/apps/docs-vue/stories/0_Introduction.stories.mdx b/apps/docs-vue/stories/0_Introduction.stories.mdx deleted file mode 100644 index 222625dd0..000000000 --- a/apps/docs-vue/stories/0_Introduction.stories.mdx +++ /dev/null @@ -1,34 +0,0 @@ -import { Meta } from '@storybook/addon-docs' - - - -# 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 - - Button - -``` - -Just keep in mind that when check the code of the components inside Storybook diff --git a/apps/docs/stories/0_Introduction.mdx b/apps/docs/stories/0_Introduction.mdx new file mode 100644 index 000000000..765088763 --- /dev/null +++ b/apps/docs/stories/0_Introduction.mdx @@ -0,0 +1,9 @@ +import { Meta, Markdown } from '@storybook/blocks' + +import README from '../../../README.md?raw' + + + + + {README} + diff --git a/apps/docs/stories/0_Introduction.stories.mdx b/apps/docs/stories/0_Introduction.stories.mdx deleted file mode 100644 index febda9b8f..000000000 --- a/apps/docs/stories/0_Introduction.stories.mdx +++ /dev/null @@ -1,7 +0,0 @@ -import { Meta, Markdown } from '@storybook/addon-docs' - -import README from '../../../README.md?raw' - - - -{README} diff --git a/apps/docs/stories/1_0_Core.mdx b/apps/docs/stories/1_0_Core.mdx new file mode 100644 index 000000000..9cfb6c75d --- /dev/null +++ b/apps/docs/stories/1_0_Core.mdx @@ -0,0 +1,9 @@ +import { Meta, Markdown } from '@storybook/blocks' + +import README from '../../../packages/core/README.md?raw' + + + + + {README} + diff --git a/apps/docs/stories/1_0_Core.stories.mdx b/apps/docs/stories/1_0_Core.stories.mdx deleted file mode 100644 index 23d445c2f..000000000 --- a/apps/docs/stories/1_0_Core.stories.mdx +++ /dev/null @@ -1,7 +0,0 @@ -import { Meta, Markdown } from '@storybook/addon-docs' - -import README from '../../../packages/core/README.md?raw' - - - -{README} diff --git a/apps/docs/stories/1_1_React.mdx b/apps/docs/stories/1_1_React.mdx new file mode 100644 index 000000000..0474182af --- /dev/null +++ b/apps/docs/stories/1_1_React.mdx @@ -0,0 +1,9 @@ +import { Meta, Markdown } from '@storybook/blocks' + +import README from '../../../packages/react/README.md?raw' + + + + + {README} + diff --git a/apps/docs/stories/1_1_React.stories.mdx b/apps/docs/stories/1_1_React.stories.mdx deleted file mode 100644 index dc43fe9e9..000000000 --- a/apps/docs/stories/1_1_React.stories.mdx +++ /dev/null @@ -1,7 +0,0 @@ -import { Meta, Markdown } from '@storybook/addon-docs' - -import README from '../../../packages/react/README.md?raw' - - - -{README} diff --git a/apps/docs/stories/1_2_Vue.mdx b/apps/docs/stories/1_2_Vue.mdx new file mode 100644 index 000000000..26419713b --- /dev/null +++ b/apps/docs/stories/1_2_Vue.mdx @@ -0,0 +1,9 @@ +import { Meta, Markdown } from '@storybook/blocks' + +import README from '../../../packages/vue/README.md?raw' + + + + + {README} + diff --git a/apps/docs/stories/1_2_Vue.stories.mdx b/apps/docs/stories/1_2_Vue.stories.mdx deleted file mode 100644 index 5389027cd..000000000 --- a/apps/docs/stories/1_2_Vue.stories.mdx +++ /dev/null @@ -1,7 +0,0 @@ -import { Meta, Markdown } from '@storybook/addon-docs' - -import README from '../../../packages/vue/README.md?raw' - - - -{README} diff --git a/apps/docs/stories/1_3_Tokens.mdx b/apps/docs/stories/1_3_Tokens.mdx new file mode 100644 index 000000000..89858b691 --- /dev/null +++ b/apps/docs/stories/1_3_Tokens.mdx @@ -0,0 +1,9 @@ +import { Meta, Markdown } from '@storybook/blocks' + +import README from '../../../packages/tokens/README.md?raw' + + + + + {README} + diff --git a/apps/docs/stories/1_3_Tokens.stories.mdx b/apps/docs/stories/1_3_Tokens.stories.mdx deleted file mode 100644 index bf9125ad9..000000000 --- a/apps/docs/stories/1_3_Tokens.stories.mdx +++ /dev/null @@ -1,7 +0,0 @@ -import { Meta, Markdown } from '@storybook/addon-docs' - -import README from '../../../packages/tokens/README.md?raw' - - - -{README} diff --git a/apps/docs/stories/1_4_Icons.stories.mdx b/apps/docs/stories/1_4_Icons.mdx similarity index 63% rename from apps/docs/stories/1_4_Icons.stories.mdx rename to apps/docs/stories/1_4_Icons.mdx index 6793d6675..9d8ba75b2 100644 --- a/apps/docs/stories/1_4_Icons.stories.mdx +++ b/apps/docs/stories/1_4_Icons.mdx @@ -2,41 +2,42 @@ import { Meta, Title, IconGallery, IconItem } from '@storybook/blocks' import { iconsList } from '../utils/icons-list' - + # Icons The icons are a collection of icons that can be used in your components. It is based on the [Material Design Icons](https://materialdesignicons.com/) library but we can also add our own custom icons. -- [Architecture decisions](/docs/docs-architecture-decision-records-adr-0011-why-host-our-own-icon-library-and-why-cdn--docs) -- [Using icons](/docs/components-icon--docs) -- [How add a custom icon](https://github.com/juntossomosmais/atomium/tree/main/packages/icons#adding-a-new-icon) +* [Architecture decisions](/docs/docs-architecture-decision-records-adr-0011-why-host-our-own-icon-library-and-why-cdn--docs) +* [Using icons](/docs/components-icon--docs) +* [How add a custom icon](https://github.com/juntossomosmais/atomium/tree/main/packages/icons#adding-a-new-icon) ## List of icons See the list of all available icons: -
+
Custom Icons

Some custom icons have the `-colorful` variation because they have specific colors that make up their identity.

{iconsList?.custom?.map((icon) => ( - - - - ))} + + + + ))}
-
+
Material Design Icons + {iconsList?.mdi?.map((icon) => ( - - - - ))} + + + + ))}
diff --git a/apps/docs/stories/architecture-decision-records/0000-why-design-system.stories.mdx b/apps/docs/stories/architecture-decision-records/0000-why-design-system.mdx similarity index 79% rename from apps/docs/stories/architecture-decision-records/0000-why-design-system.stories.mdx rename to apps/docs/stories/architecture-decision-records/0000-why-design-system.mdx index 4635bba43..b0fdf6c5f 100644 --- a/apps/docs/stories/architecture-decision-records/0000-why-design-system.stories.mdx +++ b/apps/docs/stories/architecture-decision-records/0000-why-design-system.mdx @@ -1,6 +1,6 @@ -import { Meta } from '@storybook/addon-docs' +import { Meta } from '@storybook/blocks' - + # ADR 0000: Why Design System? @@ -14,11 +14,11 @@ Create a new design system will allow us to create reusable components, establis ## Decision Drivers -- **Consistency**: We want to ensure that all of our digital products have a consistent look and feel, which can be achieved through the use of a design system. -- **Efficiency**: By creating a set of reusable components and clear design guidelines, we can increase efficiency and reduce duplication of effort across multiple projects. -- **Scalability**: As our organization grows and we take on more projects, a design system will become even more important to maintain consistency and efficiency. -- **Collaboration**: A design system will help to facilitate collaboration between designers and developers, making it easier to communicate design decisions and ensure that everyone is on the same page. -- **Branding**: By establishing clear visual guidelines and using consistent branding elements, we can help to build and reinforce our brand across all digital products. +* **Consistency**: We want to ensure that all of our digital products have a consistent look and feel, which can be achieved through the use of a design system. +* **Efficiency**: By creating a set of reusable components and clear design guidelines, we can increase efficiency and reduce duplication of effort across multiple projects. +* **Scalability**: As our organization grows and we take on more projects, a design system will become even more important to maintain consistency and efficiency. +* **Collaboration**: A design system will help to facilitate collaboration between designers and developers, making it easier to communicate design decisions and ensure that everyone is on the same page. +* **Branding**: By establishing clear visual guidelines and using consistent branding elements, we can help to build and reinforce our brand across all digital products. ## Decision diff --git a/apps/docs/stories/architecture-decision-records/0001-why-web-components.stories.mdx b/apps/docs/stories/architecture-decision-records/0001-why-web-components.mdx similarity index 77% rename from apps/docs/stories/architecture-decision-records/0001-why-web-components.stories.mdx rename to apps/docs/stories/architecture-decision-records/0001-why-web-components.mdx index 4f44389d2..198d891a0 100644 --- a/apps/docs/stories/architecture-decision-records/0001-why-web-components.stories.mdx +++ b/apps/docs/stories/architecture-decision-records/0001-why-web-components.mdx @@ -1,6 +1,6 @@ -import { Meta } from '@storybook/addon-docs' +import { Meta } from '@storybook/blocks' - + # ADR 0001: Why Web Components? @@ -12,11 +12,11 @@ We need to decide which technology and architecture to use for building componen ## Decision Drivers -- Reusability: We need our components to be reusable across different projects. -- Framework agnostic: We need our components to be usable in different frameworks, such as React, Vue, and Angular. -- Platform agnostic: We need our components to be usable on different platforms, such as web, mobile, and desktop. -- Device agnostic: We need our components to be usable on different devices, such as desktops, laptops, tablets, and mobile phones. -- Browser compatibility: We need our components to work on different browsers, such as Chrome, Firefox, Safari, and Edge. +* Reusability: We need our components to be reusable across different projects. +* Framework agnostic: We need our components to be usable in different frameworks, such as React, Vue, and Angular. +* Platform agnostic: We need our components to be usable on different platforms, such as web, mobile, and desktop. +* Device agnostic: We need our components to be usable on different devices, such as desktops, laptops, tablets, and mobile phones. +* Browser compatibility: We need our components to work on different browsers, such as Chrome, Firefox, Safari, and Edge. ## Decision diff --git a/apps/docs/stories/architecture-decision-records/0002-why-ionic.stories.mdx b/apps/docs/stories/architecture-decision-records/0002-why-ionic.mdx similarity index 84% rename from apps/docs/stories/architecture-decision-records/0002-why-ionic.stories.mdx rename to apps/docs/stories/architecture-decision-records/0002-why-ionic.mdx index 7cd381f73..126822b29 100644 --- a/apps/docs/stories/architecture-decision-records/0002-why-ionic.stories.mdx +++ b/apps/docs/stories/architecture-decision-records/0002-why-ionic.mdx @@ -1,6 +1,6 @@ -import { Meta } from '@storybook/addon-docs' +import { Meta } from '@storybook/blocks' - + # ADR 0002: Why Ionic? @@ -12,20 +12,20 @@ We need to choose a Material's framework UI to build our web components design s ## Decision Drivers -- We need to build UI components using web components -- We need a framework with Material Design components -- We need a complete suite of components -- We need a framework that is easy to integrate with other frameworks -- We need a framework with good documentation -- We need a framework with a good community +* We need to build UI components using web components +* We need a framework with Material Design components +* We need a complete suite of components +* We need a framework that is easy to integrate with other frameworks +* We need a framework with good documentation +* We need a framework with a good community ## Considered Options -- **[Material Web Components](https://github.com/material-components/material-web)**: a web component library that implements the Material Design guidelines. It provides a set of pre-built components that can be used with any web framework. Material Web Components are built using modern web technologies and are designed to work across different platforms and browsers. However, it is still in beta version, and some components may not be available. +* **[Material Web Components](https://github.com/material-components/material-web)**: a web component library that implements the Material Design guidelines. It provides a set of pre-built components that can be used with any web framework. Material Web Components are built using modern web technologies and are designed to work across different platforms and browsers. However, it is still in beta version, and some components may not be available. -- **[Material Design Lite](https://getmdl.io/)**: a front-end framework that implements Material Design guidelines. It provides a set of pre-built components and styles to help developers create web applications with a consistent look and feel. Material Design Lite is a lightweight framework that is easy to use and can be customized to fit the needs of different projects. However, it doesn't use web components, which may limit its compatibility with certain frameworks. +* **[Material Design Lite](https://getmdl.io/)**: a front-end framework that implements Material Design guidelines. It provides a set of pre-built components and styles to help developers create web applications with a consistent look and feel. Material Design Lite is a lightweight framework that is easy to use and can be customized to fit the needs of different projects. However, it doesn't use web components, which may limit its compatibility with certain frameworks. -- **[Ionic](https://ionicframework.com/)**: a complete framework for building hybrid mobile and web applications. It provides a set of pre-built UI components, tools, and services to help developers create high-quality applications faster and more efficiently. Ionic is based on Angular, but it can also be used with other frameworks like React and Vue. It uses web technologies like HTML, CSS, and JavaScript to create cross-platform applications that work on different devices and operating systems. Ionic has a large community and a well-documented API, making it a popular choice for developers. However, it may not be the best fit for projects that do not require a full-featured framework. +* **[Ionic](https://ionicframework.com/)**: a complete framework for building hybrid mobile and web applications. It provides a set of pre-built UI components, tools, and services to help developers create high-quality applications faster and more efficiently. Ionic is based on Angular, but it can also be used with other frameworks like React and Vue. It uses web technologies like HTML, CSS, and JavaScript to create cross-platform applications that work on different devices and operating systems. Ionic has a large community and a well-documented API, making it a popular choice for developers. However, it may not be the best fit for projects that do not require a full-featured framework. ## Decision diff --git a/apps/docs/stories/architecture-decision-records/0003-why-stencil.stories.mdx b/apps/docs/stories/architecture-decision-records/0003-why-stencil.mdx similarity index 77% rename from apps/docs/stories/architecture-decision-records/0003-why-stencil.stories.mdx rename to apps/docs/stories/architecture-decision-records/0003-why-stencil.mdx index ed1f356ed..7ef5452a8 100644 --- a/apps/docs/stories/architecture-decision-records/0003-why-stencil.stories.mdx +++ b/apps/docs/stories/architecture-decision-records/0003-why-stencil.mdx @@ -1,6 +1,6 @@ -import { Meta } from '@storybook/addon-docs' +import { Meta } from '@storybook/blocks' - + # ADR 0003: Why Stencil? @@ -12,17 +12,17 @@ We need to choose a framework to build our web components library ## Decision Drivers -- We need to build a web components library that is lightweight and performant. -- We need a solution that is framework agnostic, so we can use it with any JavaScript framework. -- We want to use a compiler to generate web components, to make development easier and more efficient. -- We want to use a framework that has a good community, so we can get support and contribute to the ecosystem. -- We need good integration with Ionic, React, and Vue, as these are the frameworks we use in our projects. +* We need to build a web components library that is lightweight and performant. +* We need a solution that is framework agnostic, so we can use it with any JavaScript framework. +* We want to use a compiler to generate web components, to make development easier and more efficient. +* We want to use a framework that has a good community, so we can get support and contribute to the ecosystem. +* We need good integration with Ionic, React, and Vue, as these are the frameworks we use in our projects. ## Considered Options -- **[Lit](https://lit.dev/)**: A library for building fast, lightweight web components. Not a compiler, so we would need to use a separate tool to generate web components. -- **[Svelte](https://svelte.dev/)**: A framework that shifts most of the work to a compile step, making it fast and lightweight. Not a compiler for web components, so we would need to use a separate tool to generate them. -- **[Stencil](https://stenciljs.com/)**: A compiler for generating web components and progressive web apps. Framework agnostic with a good community and good integrations with Ionic, React, and Vue. +* **[Lit](https://lit.dev/)**: A library for building fast, lightweight web components. Not a compiler, so we would need to use a separate tool to generate web components. +* **[Svelte](https://svelte.dev/)**: A framework that shifts most of the work to a compile step, making it fast and lightweight. Not a compiler for web components, so we would need to use a separate tool to generate them. +* **[Stencil](https://stenciljs.com/)**: A compiler for generating web components and progressive web apps. Framework agnostic with a good community and good integrations with Ionic, React, and Vue. ## Decision diff --git a/apps/docs/stories/architecture-decision-records/0004-why-a-monorepo.stories.mdx b/apps/docs/stories/architecture-decision-records/0004-why-a-monorepo.mdx similarity index 80% rename from apps/docs/stories/architecture-decision-records/0004-why-a-monorepo.stories.mdx rename to apps/docs/stories/architecture-decision-records/0004-why-a-monorepo.mdx index bc95de1d0..1524c6567 100644 --- a/apps/docs/stories/architecture-decision-records/0004-why-a-monorepo.stories.mdx +++ b/apps/docs/stories/architecture-decision-records/0004-why-a-monorepo.mdx @@ -1,6 +1,6 @@ -import { Meta } from '@storybook/addon-docs' +import { Meta } from '@storybook/blocks' - + # ADR 0004: Why a Monorepo? @@ -12,16 +12,16 @@ We need to choose an architecture for our project that enables us to efficiently ## Decision Drivers -- We need to be able to independently version each package. -- We need to share code and configuration between packages. -- We need to share dependencies between packages. -- We need a centralized documentation for our Design System. +* We need to be able to independently version each package. +* We need to share code and configuration between packages. +* We need to share dependencies between packages. +* We need a centralized documentation for our Design System. ## Considered Options -- **[Monorepo](https://monorepo.tools/)**: A monorepo is a software development practice where multiple projects are stored in the same repository. In the context of a design system, this means that all the packages (e.g., UI components, typography, color scheme, etc.) are kept in a single repository and versioned together. This approach allows for easy sharing of code, configuration, and dependencies between packages, and provides a centralized location for documentation and tooling. It can also simplify the development workflow by enabling atomic commits, shared testing, and a unified deployment pipeline. +* **[Monorepo](https://monorepo.tools/)**: A monorepo is a software development practice where multiple projects are stored in the same repository. In the context of a design system, this means that all the packages (e.g., UI components, typography, color scheme, etc.) are kept in a single repository and versioned together. This approach allows for easy sharing of code, configuration, and dependencies between packages, and provides a centralized location for documentation and tooling. It can also simplify the development workflow by enabling atomic commits, shared testing, and a unified deployment pipeline. -- **Separate Repositories**: This refers to the practice of keeping each package (e.g., UI components, typography, color scheme, etc.) in a separate repository. Each package has its own versioning and development lifecycle, and can be developed and deployed independently of the others. However, this approach can lead to code duplication, configuration fragmentation, and dependency management issues, especially if multiple packages need to share common code or dependencies. It also makes it harder to maintain a centralized documentation and tooling, as these would need to be replicated across multiple repositories. +* **Separate Repositories**: This refers to the practice of keeping each package (e.g., UI components, typography, color scheme, etc.) in a separate repository. Each package has its own versioning and development lifecycle, and can be developed and deployed independently of the others. However, this approach can lead to code duplication, configuration fragmentation, and dependency management issues, especially if multiple packages need to share common code or dependencies. It also makes it harder to maintain a centralized documentation and tooling, as these would need to be replicated across multiple repositories. ## Decision diff --git a/apps/docs/stories/architecture-decision-records/0005-why-nx.stories.mdx b/apps/docs/stories/architecture-decision-records/0005-why-nx.mdx similarity index 77% rename from apps/docs/stories/architecture-decision-records/0005-why-nx.stories.mdx rename to apps/docs/stories/architecture-decision-records/0005-why-nx.mdx index 1f2bb6f1c..9ec861056 100644 --- a/apps/docs/stories/architecture-decision-records/0005-why-nx.stories.mdx +++ b/apps/docs/stories/architecture-decision-records/0005-why-nx.mdx @@ -1,6 +1,6 @@ -import { Meta } from '@storybook/addon-docs' +import { Meta } from '@storybook/blocks' - + # ADR 0005: Why NX? @@ -12,18 +12,18 @@ We need to select a tool to help manage our monorepo for our design system. ## Decision Drivers -- We need a robust and well-tested tool. -- We require a tool with comprehensive documentation. -- We need a tool with a large and active community for long-term support. -- We need a tool that can integrate well with other essential tools like Storybook, Jest, Typescript, etc. +* We need a robust and well-tested tool. +* We require a tool with comprehensive documentation. +* We need a tool with a large and active community for long-term support. +* We need a tool that can integrate well with other essential tools like Storybook, Jest, Typescript, etc. ## Considered Options -- **[Pnpm/Yarn Workspaces](https://classic.yarnpkg.com/en/docs/workspaces/)**: A tool for managing JavaScript projects with multiple packages. It allows you to manage dependencies and run commands across packages in a monorepo, while still allowing each package to have its own version and dependencies. Both Pnpm and Yarn have been tested and widely used in the JavaScript community. -- **[Lerna](https://lerna.js.org/)**: A popular tool for managing JavaScript projects with multiple packages. It provides tools for managing versioning, publishing, and running commands across packages in a monorepo. It has a large community and is well-documented. -- **[Turborepo](https://turborepo.com/)**: A new tool for managing JavaScript projects with multiple packages. It provides features for fast and scalable builds, dependency management, and developer workflows in a monorepo. It's relatively new, but it has already received positive feedback from some developers. -- **[Bit.dev](https://bit.dev/)**: A platform for building, distributing, and collaborating on individual components. It allows you to share and reuse components across different projects and teams. It also has tools for managing dependencies and versioning, and it integrates with popular frameworks and tools like React, Vue, and Storybook. -- **[NX](https://nx.dev/)**: A set of extensible dev tools for monorepos. It provides features for managing dependencies, building and testing code, and generating code scaffolding. It also has plugins for popular frameworks like React, Angular, and Vue, and it integrates with popular tools like Jest and Cypress. It has a large and active community, and it's well-documented. +* **[Pnpm/Yarn Workspaces](https://classic.yarnpkg.com/en/docs/workspaces/)**: A tool for managing JavaScript projects with multiple packages. It allows you to manage dependencies and run commands across packages in a monorepo, while still allowing each package to have its own version and dependencies. Both Pnpm and Yarn have been tested and widely used in the JavaScript community. +* **[Lerna](https://lerna.js.org/)**: A popular tool for managing JavaScript projects with multiple packages. It provides tools for managing versioning, publishing, and running commands across packages in a monorepo. It has a large community and is well-documented. +* **[Turborepo](https://turborepo.com/)**: A new tool for managing JavaScript projects with multiple packages. It provides features for fast and scalable builds, dependency management, and developer workflows in a monorepo. It's relatively new, but it has already received positive feedback from some developers. +* **[Bit.dev](https://bit.dev/)**: A platform for building, distributing, and collaborating on individual components. It allows you to share and reuse components across different projects and teams. It also has tools for managing dependencies and versioning, and it integrates with popular frameworks and tools like React, Vue, and Storybook. +* **[NX](https://nx.dev/)**: A set of extensible dev tools for monorepos. It provides features for managing dependencies, building and testing code, and generating code scaffolding. It also has plugins for popular frameworks like React, Angular, and Vue, and it integrates with popular tools like Jest and Cypress. It has a large and active community, and it's well-documented. ## Decision diff --git a/apps/docs/stories/architecture-decision-records/0006-why-that-component-creation-definition.stories.mdx b/apps/docs/stories/architecture-decision-records/0006-why-that-component-creation-definition.mdx similarity index 80% rename from apps/docs/stories/architecture-decision-records/0006-why-that-component-creation-definition.stories.mdx rename to apps/docs/stories/architecture-decision-records/0006-why-that-component-creation-definition.mdx index a59a04211..5f7521ab6 100644 --- a/apps/docs/stories/architecture-decision-records/0006-why-that-component-creation-definition.stories.mdx +++ b/apps/docs/stories/architecture-decision-records/0006-why-that-component-creation-definition.mdx @@ -1,6 +1,6 @@ -import { Meta } from '@storybook/addon-docs' +import { Meta } from '@storybook/blocks' - + # ADR 0006: Why that component creation definition? @@ -12,12 +12,12 @@ We need to create new components and modify existing Ionic components for use in ## Decision Drivers -- We need to create wrappers to facilitate the reuse of modified Ionic components. -- We need to create new components for our projects. -- We need to use CSS variables as tokens to ensure consistency across projects. -- We will only create new components if the Ionic components do not meet our needs. -- We will only create a component once and use it across all projects. -- We need a way to create new components and modify Ionic components without changing the Ionic codebase. +* We need to create wrappers to facilitate the reuse of modified Ionic components. +* We need to create new components for our projects. +* We need to use CSS variables as tokens to ensure consistency across projects. +* We will only create new components if the Ionic components do not meet our needs. +* We will only create a component once and use it across all projects. +* We need a way to create new components and modify Ionic components without changing the Ionic codebase. ## Decision diff --git a/apps/docs/stories/architecture-decision-records/0007-why-do-we-transpile-web-components-for-react-and-vue.mdx b/apps/docs/stories/architecture-decision-records/0007-why-do-we-transpile-web-components-for-react-and-vue.mdx new file mode 100644 index 000000000..9ae851779 --- /dev/null +++ b/apps/docs/stories/architecture-decision-records/0007-why-do-we-transpile-web-components-for-react-and-vue.mdx @@ -0,0 +1,40 @@ +import { Meta } from '@storybook/blocks' + + + +# 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. diff --git a/apps/docs/stories/architecture-decision-records/0007-why-do-we-transpile-web-components-for-react-and-vue.stories.mdx b/apps/docs/stories/architecture-decision-records/0007-why-do-we-transpile-web-components-for-react-and-vue.stories.mdx deleted file mode 100644 index 89c174bb0..000000000 --- a/apps/docs/stories/architecture-decision-records/0007-why-do-we-transpile-web-components-for-react-and-vue.stories.mdx +++ /dev/null @@ -1,40 +0,0 @@ -import { Meta } from '@storybook/addon-docs' - - - -# 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. diff --git a/apps/docs/stories/architecture-decision-records/0008-why-do-we-need-grids.stories.mdx b/apps/docs/stories/architecture-decision-records/0008-why-do-we-need-grids.mdx similarity index 92% rename from apps/docs/stories/architecture-decision-records/0008-why-do-we-need-grids.stories.mdx rename to apps/docs/stories/architecture-decision-records/0008-why-do-we-need-grids.mdx index 16ffa04e3..9e0c85614 100644 --- a/apps/docs/stories/architecture-decision-records/0008-why-do-we-need-grids.stories.mdx +++ b/apps/docs/stories/architecture-decision-records/0008-why-do-we-need-grids.mdx @@ -1,6 +1,6 @@ -import { Meta } from '@storybook/addon-docs' +import { Meta } from '@storybook/blocks' - + # ADR 0008: Why do we need Grids diff --git a/apps/docs/stories/architecture-decision-records/0009-why-use-onclick-event-on-breadcrumb-component-event-undocumented.stories.mdx b/apps/docs/stories/architecture-decision-records/0009-why-use-onclick-event-on-breadcrumb-component-event-undocumented.mdx similarity index 86% rename from apps/docs/stories/architecture-decision-records/0009-why-use-onclick-event-on-breadcrumb-component-event-undocumented.stories.mdx rename to apps/docs/stories/architecture-decision-records/0009-why-use-onclick-event-on-breadcrumb-component-event-undocumented.mdx index 5586b7db6..27a0a0839 100644 --- a/apps/docs/stories/architecture-decision-records/0009-why-use-onclick-event-on-breadcrumb-component-event-undocumented.stories.mdx +++ b/apps/docs/stories/architecture-decision-records/0009-why-use-onclick-event-on-breadcrumb-component-event-undocumented.mdx @@ -1,6 +1,6 @@ -import { Meta } from '@storybook/addon-docs' +import { Meta } from '@storybook/blocks' - + # Why use `onClick` event on breadcrumb component even undocumented? diff --git a/apps/docs/stories/architecture-decision-records/0010-why-do-we-need-react-fix.stories.mdx b/apps/docs/stories/architecture-decision-records/0010-why-do-we-need-react-fix.mdx similarity index 83% rename from apps/docs/stories/architecture-decision-records/0010-why-do-we-need-react-fix.stories.mdx rename to apps/docs/stories/architecture-decision-records/0010-why-do-we-need-react-fix.mdx index 992f60807..2c71dc509 100644 --- a/apps/docs/stories/architecture-decision-records/0010-why-do-we-need-react-fix.stories.mdx +++ b/apps/docs/stories/architecture-decision-records/0010-why-do-we-need-react-fix.mdx @@ -1,6 +1,6 @@ -import { Meta } from '@storybook/addon-docs' +import { Meta } from '@storybook/blocks' - + # ADR 0010: Why do we need a fix in React? @@ -45,8 +45,8 @@ expect(atom - button).toBeDisabled() After we consider the options: -- Living with the problem for possibly in the near future react will offer better [support](https://github.com/facebook/react/issues/11347) for web-components. +* Living with the problem for possibly in the near future react will offer better [support](https://github.com/facebook/react/issues/11347) for web-components. > We can see [tests in a experimental branch here](https://custom-elements-everywhere.com/libraries/react-experimental/results/results.html) -- We are already transpiling the web-component to React, could use a workaround. +* We are already transpiling the web-component to React, could use a workaround. Based on these options, we decide to use workaround which will basically set/remove attributes after [occurs a update in component.](https://react.dev/reference/react/Component#componentdidupdate) diff --git a/apps/docs/stories/architecture-decision-records/0011-why-host-our-own-icon-library-and-cdn.stories.mdx b/apps/docs/stories/architecture-decision-records/0011-why-host-our-own-icon-library-and-cdn.mdx similarity index 78% rename from apps/docs/stories/architecture-decision-records/0011-why-host-our-own-icon-library-and-cdn.stories.mdx rename to apps/docs/stories/architecture-decision-records/0011-why-host-our-own-icon-library-and-cdn.mdx index c914fbc59..e590455fb 100644 --- a/apps/docs/stories/architecture-decision-records/0011-why-host-our-own-icon-library-and-cdn.stories.mdx +++ b/apps/docs/stories/architecture-decision-records/0011-why-host-our-own-icon-library-and-cdn.mdx @@ -1,6 +1,6 @@ -import { Meta } from '@storybook/addon-docs' +import { Meta } from '@storybook/blocks' - + # ADR 0011: Why host our own icon library and why CDN? @@ -16,14 +16,14 @@ We use Material Design Icons as our icon library, but we also have our own custo The following factors were considered when making the decision about how to serve icons: -- **Framework agnostic:** The icons must be able to be used in any framework or technology. -- **Consistency:** The icons must have a consistent look across all products. +* **Framework agnostic:** The icons must be able to be used in any framework or technology. +* **Consistency:** The icons must have a consistent look across all products. ## Considered Options -- **Use Ionic Icons library:** This would be a good option because the Ionic Icons library is built with Web Components and is easy to use. However, the Ionic Icons library does not contain all of the icons that we need. -- **Publish an icon library:** This would be a very good option because it would ensure that we have access to all of the icons that we need. However, it would be a significant amount of work to create and maintain a published library. -- **Use icons from CDN:** We already have a CDN infrastructure in place to serve our static assets. We can use this infrastructure to serve our icons in a framework-agnostic way. +* **Use Ionic Icons library:** This would be a good option because the Ionic Icons library is built with Web Components and is easy to use. However, the Ionic Icons library does not contain all of the icons that we need. +* **Publish an icon library:** This would be a very good option because it would ensure that we have access to all of the icons that we need. However, it would be a significant amount of work to create and maintain a published library. +* **Use icons from CDN:** We already have a CDN infrastructure in place to serve our static assets. We can use this infrastructure to serve our icons in a framework-agnostic way. ## Decision diff --git a/apps/docs/stories/architecture-decision-records/0012-why-have-a-carousel-with-swiper.stories.mdx b/apps/docs/stories/architecture-decision-records/0012-why-have-a-carousel-with-swiper.mdx similarity index 79% rename from apps/docs/stories/architecture-decision-records/0012-why-have-a-carousel-with-swiper.stories.mdx rename to apps/docs/stories/architecture-decision-records/0012-why-have-a-carousel-with-swiper.mdx index a706c9f2a..0cfb178a0 100644 --- a/apps/docs/stories/architecture-decision-records/0012-why-have-a-carousel-with-swiper.stories.mdx +++ b/apps/docs/stories/architecture-decision-records/0012-why-have-a-carousel-with-swiper.mdx @@ -1,6 +1,6 @@ -import { Meta } from '@storybook/addon-docs' +import { Meta } from '@storybook/blocks' - + # ADR 0012: Carousel with Swiper @@ -12,9 +12,9 @@ We need a Carousel component with consistent layout across projects. ## Decision Drivers -- We need a Carousel component/library must be web component; -- The Carousel component/library must give us the possibility to adjust styles as we need to match our Style Guide; -- The Carousel component/library should have a good integrations with Ionic components, once it is the source of our Design System. +* We need a Carousel component/library must be web component; +* The Carousel component/library must give us the possibility to adjust styles as we need to match our Style Guide; +* The Carousel component/library should have a good integrations with Ionic components, once it is the source of our Design System. ## Considered Options diff --git a/apps/docs/stories/architecture-decision-records/0013-why-do-we-need-to-convert-carousel-item.stories.mdx b/apps/docs/stories/architecture-decision-records/0013-why-do-we-need-to-convert-carousel-item.mdx similarity index 90% rename from apps/docs/stories/architecture-decision-records/0013-why-do-we-need-to-convert-carousel-item.stories.mdx rename to apps/docs/stories/architecture-decision-records/0013-why-do-we-need-to-convert-carousel-item.mdx index 4d942002b..506e251ff 100644 --- a/apps/docs/stories/architecture-decision-records/0013-why-do-we-need-to-convert-carousel-item.stories.mdx +++ b/apps/docs/stories/architecture-decision-records/0013-why-do-we-need-to-convert-carousel-item.mdx @@ -1,4 +1,4 @@ -import { Meta } from '@storybook/addon-docs' +import { Meta } from '@storybook/blocks' @@ -25,16 +25,16 @@ To convert the inner `` to ``, and we have two ## Decision Drivers -- Performance -- Complexity -- Compatibility +* Performance +* Complexity +* Compatibility ### Performance We had performed a test with both approach using 9 items inside the Carousel: -- With children `atom-carousel-item` doing the conversion, it took _0.50ms_ -- With parent `atom-carousel` doing the conversion, it took _0.20ms_ +* With children `atom-carousel-item` doing the conversion, it took *0.50ms* +* With parent `atom-carousel` doing the conversion, it took *0.20ms* ### Complexity @@ -72,7 +72,7 @@ Taking in consideration the complexity of both codes, not only the parent's conv This subject was in fact the decision maker, even tho the performance of the first approach took half of the time, when it came to compatibility we discovered why. -For simples cases, such static card, plain text or image showcases, no difference between both, but when we started to use with complex components, that had to deal with framework functions such reactivity we face a bigger issue. The HTMLString conversion component loose _"connections "_ with the inner content. So it just became a plain HTML String copy, instead of a state and object reference. +For simples cases, such static card, plain text or image showcases, no difference between both, but when we started to use with complex components, that had to deal with framework functions such reactivity we face a bigger issue. The HTMLString conversion component loose *"connections "* with the inner content. So it just became a plain HTML String copy, instead of a state and object reference. When using `.innerHTML.replace` our components lost its ability to re-render once loading is ready, update values and even trigger framework events. When using `appendChild` behavior, we copy the whole HTMLElement and its props, functions, children, and every memory reference we had. And working as needed and expected. @@ -83,4 +83,4 @@ Once a perfect work alongside with frameworks such React and Vue is one of the m ### Alert -Because of the need of _transport_ of `atom-carousel-item` content to inside `swiper-slide` to achieve framework compatibility we loose the lazy property. At our case is not a problem because swiper-slide's lazy property only add a loading spinner while image loads. +Because of the need of *transport* of `atom-carousel-item` content to inside `swiper-slide` to achieve framework compatibility we loose the lazy property. At our case is not a problem because swiper-slide's lazy property only add a loading spinner while image loads. diff --git a/apps/docs/stories/architecture-decision-records/0014-why-use-popperjs.stories.mdx b/apps/docs/stories/architecture-decision-records/0014-why-use-popperjs.mdx similarity index 71% rename from apps/docs/stories/architecture-decision-records/0014-why-use-popperjs.stories.mdx rename to apps/docs/stories/architecture-decision-records/0014-why-use-popperjs.mdx index 88dfb4a91..7eb7e0aa3 100644 --- a/apps/docs/stories/architecture-decision-records/0014-why-use-popperjs.stories.mdx +++ b/apps/docs/stories/architecture-decision-records/0014-why-use-popperjs.mdx @@ -1,6 +1,6 @@ -import { Meta } from '@storybook/addon-docs' +import { Meta } from '@storybook/blocks' - + # ADR 0014: Why PopperJS @@ -14,14 +14,14 @@ It was necessary due to the complexity of modifying the `ion-popover` to meet th These changes included things like: -- Removing a class that locks the scroll on the site (added to the body) when using the `ion-popover`; -- Adding scroll tracking; -- Ensuring responsiveness in terms of automatically changing side/direction. +* Removing a class that locks the scroll on the site (added to the body) when using the `ion-popover`; +* Adding scroll tracking; +* Ensuring responsiveness in terms of automatically changing side/direction. ## Decision Drivers -- Bundle Size: The size of the library was considered. If the size was too large, it would be a NO-GO for inclusion in the project. As the entire library currently (2024/11/05) only 8.9KB, we understood that the size would not negatively impact the user experience; -- Popularity and Maintenance: PopperJS is the most well-known library for handling this type of work. Many libraries that implement some type of "popper" use it to provide this functionality. +* Bundle Size: The size of the library was considered. If the size was too large, it would be a NO-GO for inclusion in the project. As the entire library currently (2024/11/05) only 8.9KB, we understood that the size would not negatively impact the user experience; +* Popularity and Maintenance: PopperJS is the most well-known library for handling this type of work. Many libraries that implement some type of "popper" use it to provide this functionality. ## Decision diff --git a/packages/tokens/stories/1_Colors.stories.mdx b/packages/tokens/stories/1_Colors.mdx similarity index 83% rename from packages/tokens/stories/1_Colors.stories.mdx rename to packages/tokens/stories/1_Colors.mdx index e5abb7a79..203514846 100644 --- a/packages/tokens/stories/1_Colors.stories.mdx +++ b/packages/tokens/stories/1_Colors.mdx @@ -1,6 +1,6 @@ -import { Meta, ColorPalette, ColorItem } from '@storybook/addon-docs/blocks' +import { Meta, ColorPalette, ColorItem } from '@storybook/blocks' - + # Colors @@ -12,7 +12,7 @@ Neutral colors are shades of gray at different levels of saturation used in text + + + + + # Spacings diff --git a/packages/tokens/stories/3_Typography.stories.mdx b/packages/tokens/stories/3_Typography.mdx similarity index 96% rename from packages/tokens/stories/3_Typography.stories.mdx rename to packages/tokens/stories/3_Typography.mdx index 627c9697d..9505de56f 100644 --- a/packages/tokens/stories/3_Typography.stories.mdx +++ b/packages/tokens/stories/3_Typography.mdx @@ -1,6 +1,6 @@ -import { Meta, Typeset } from '@storybook/addon-docs/blocks' +import { Meta, Typeset } from '@storybook/blocks' - + # Typography @@ -26,7 +26,7 @@ All typography tokens available in the design system. '46px', '52px', ]} - sampleText='Atomium is the best!' + sampleText="Atomium is the best!" /> ## Using diff --git a/packages/tokens/stories/4_Screens.stories.mdx b/packages/tokens/stories/4_Screens.mdx similarity index 90% rename from packages/tokens/stories/4_Screens.stories.mdx rename to packages/tokens/stories/4_Screens.mdx index 23fc5b2f5..85034d4a9 100644 --- a/packages/tokens/stories/4_Screens.stories.mdx +++ b/packages/tokens/stories/4_Screens.mdx @@ -1,6 +1,6 @@ -import { Meta } from '@storybook/addon-docs/blocks' +import { Meta } from '@storybook/blocks' - + # Screens diff --git a/packages/tokens/stories/5_Grid.stories.mdx b/packages/tokens/stories/5_Grid.mdx similarity index 91% rename from packages/tokens/stories/5_Grid.stories.mdx rename to packages/tokens/stories/5_Grid.mdx index 19e4bde16..01920bf77 100644 --- a/packages/tokens/stories/5_Grid.stories.mdx +++ b/packages/tokens/stories/5_Grid.mdx @@ -1,6 +1,6 @@ -import { Meta } from '@storybook/addon-docs/blocks' +import { Meta } from '@storybook/blocks' - + # Grid diff --git a/packages/tokens/stories/6_Misc.stories.mdx b/packages/tokens/stories/6_Misc.mdx similarity index 86% rename from packages/tokens/stories/6_Misc.stories.mdx rename to packages/tokens/stories/6_Misc.mdx index a7fd4da55..5d627887d 100644 --- a/packages/tokens/stories/6_Misc.stories.mdx +++ b/packages/tokens/stories/6_Misc.mdx @@ -1,7 +1,7 @@ -import { Meta } from '@storybook/addon-docs/blocks' +import { Meta } from '@storybook/blocks' import { Box, BoxList } from './components/Box.jsx' - + # Miscellaneous @@ -25,10 +25,13 @@ This token must be used **only** with `border-radius` CSS property. ### Example - - - - + + + + + + + ## transition-duration diff --git a/packages/tokens/stories/7_Elevation.stories.mdx b/packages/tokens/stories/7_Elevation.mdx similarity index 85% rename from packages/tokens/stories/7_Elevation.stories.mdx rename to packages/tokens/stories/7_Elevation.mdx index a01a81f9f..41bac1bd5 100644 --- a/packages/tokens/stories/7_Elevation.stories.mdx +++ b/packages/tokens/stories/7_Elevation.mdx @@ -1,7 +1,7 @@ -import { Meta } from '@storybook/addon-docs/blocks' +import { Meta } from '@storybook/blocks' import { Box, BoxList } from './components/Box.jsx' - + # Elevation @@ -36,12 +36,19 @@ filter: drop-shadow(var(--elevation-8)); ``` - - - - - - - - + + + + + + + + + + + + + + +