diff --git a/packages/beeq-angular/README.md b/packages/beeq-angular/README.md index 629854ef1..c4f01bee6 100644 --- a/packages/beeq-angular/README.md +++ b/packages/beeq-angular/README.md @@ -4,24 +4,18 @@ An Angular-specific wrapper on top of BEEQ web components that enables NG_VALUE_ ## Package installation -- install the package - -``` -npm install @beeq/angular -``` - -- update the package +> [!TIP] +> Please always refer to the [official BEEQ documentation](https://www.beeq.design/3d466e231/p/359a26-for-developers/b/08eb89) for more information about the installation. -``` -npm install @beeq/angular@latest -``` - -if the `@beeq/core` package is added to your `package.json` should update both +- install the package ``` npm install @beeq/{core,angular} ``` +> [!NOTE] +> Make sure that you have installed the `@beeq/core` package. + ## Setup ### Call `defineCustomElements` @@ -43,7 +37,10 @@ applyPolyfills().then(() => { ### Add BEEQ styles and assets -> ❗️The icons SVG are shipped in a separate folder. Projects will need to include `node_modules/@beeq/core/dist/beeq/svg` in their build and try to make it in a certain way that it respond to: `http:///svg` +> [!TIP] +> BEEQ uses SVG icons and these assets are shipped in a separate folder. You can use the `setBasePath` method to set the path to the icons. Make sure that your project bundle the icons in a way that they are accessible from the browser. + +You can move the icons from the node_modules folder to your assets folder and set the path like this: ```json /** angular.json */ @@ -65,7 +62,7 @@ applyPolyfills().then(() => { { "glob": "**/*", "input": "node_modules/@beeq/core/dist/beeq/svg", - "output": "/svg/" + "output": "assets/svg/" } ], "styles": [ @@ -81,6 +78,25 @@ applyPolyfills().then(() => { } ``` +```js +// main.ts +import { setBasePath } from '@beeq/core'; + +setBasePath('/assets/svg/'); +``` + +But you can also use a different icons library or a CDN (*no need to move the icons to your assets folder via angular.json*): + +```js +import { setBasePath } from '@beeq/core'; + +// Using heroicons library +setBasePath('https://cdn.jsdelivr.net/npm/heroicons@2.1.5/24/outline'); +``` + +> [!CAUTION] +> When using a different icons library, make sure you use the correct icon names provided by the library or the CDN. + BEEQ styles can be also imported into your application's main style file: ```css @@ -112,7 +128,8 @@ export class AppModule {} To enable two-way binding and the use of [ngModel] within BEEQ form components, you will need to add the Value Accessors in your module declarations, along with `@angular/forms`. -> ❗️❗️ *Please notice that* **you might need to disable** `aot` *for enabling two-way data binding**. Details: https://github.com/ionic-team/stencil-ds-output-targets/issues/317* +> [!CAUTION] +> *Please notice that* **you might need to disable** `aot` *for enabling two-way data binding**. Details: https://github.com/ionic-team/stencil-ds-output-targets/issues/317* ```ts import { NgModule } from '@angular/core'; diff --git a/packages/beeq-react/README.md b/packages/beeq-react/README.md index a67b6f25f..a2acc2395 100644 --- a/packages/beeq-react/README.md +++ b/packages/beeq-react/README.md @@ -2,35 +2,90 @@ A lightweight utility that wraps BEEQ custom elements ("web components") so they can be used like native React components. +## Why is this necessary? + +React and custom elements don't play nicely together. The problem is best described by [Custom Elements Everywhere](https://custom-elements-everywhere.com/#react): + +> **Handling data** +> +> React passes all data to Custom Elements in the form of HTML attributes. For primitive data this is fine, but the system breaks down when passing rich data, like objects or arrays. In these instances you end up with stringified values like some-attr="[object Object]" which can't actually be used. +> +> **Handling events** +> +> Because React implements its own synthetic event system, it cannot listen for DOM events coming from Custom Elements without the use of a workaround. Developers will need to reference their Custom Elements using a ref and manually attach event listeners with addEventListener. This makes working with Custom Elements cumbersome. + +This utility solves these problems by exposing a native React component that maps properties and events to the underlying custom element. ✨ + ## Package installation +> [!TIP] +> Please always refer to the [official BEEQ documentation](https://www.beeq.design/3d466e231/p/359a26-for-developers/b/28e01f) for more information about the installation. + - install the package ``` -npm install @beeq/react +npm install @beeq/{core,react} ``` -- update the package +> [!NOTE] +> Make sure that you have installed the `@beeq/core` package. + +### Add BEEQ styles and assets +Import BEEQ styles into your application's main style file: + +```css +@import "@beeq/core/dist/beeq/beeq.css"; ``` -npm install @beeq/react@latest + +> [!TIP] +> BEEQ uses SVG icons and these assets are shipped in a separate folder. You can use the `setBasePath` method to set the path to the icons. Make sure that your project bundle the icons in a way that they are accessible from the browser. + +You can move the icons from the node_modules folder to your assets folder and set the path like this: + +```js +// vite.config.js +import { defineConfig } from 'vite'; +import { viteStaticCopy } from 'vite-plugin-static-copy'; +import react from '@vitejs/plugin-react'; + +export default defineConfig({ + plugins: [ + react(), + viteStaticCopy({ + targets: [ + { + src: './node_modules/@beeq/core/dist/beeq/svg/*', + dest: 'icons/svg', + }, + // add more targets if needed + ], + }), + ], + // other configurations +}); ``` -if `@beeq/core` package is installed you should update both +```js +// main.ts +import { setBasePath } from "@beeq/core/dist/components"; -``` -npm install @beeq/{core,react} +setBasePath('icons/svg'); ``` -### Add BEEQ styles and assets +> Please, notice the path 👆 -Make sure that BEEQ main style is imported into your application's main style file: +But you can also use a different icons library or a CDN: -```css -@import "@beeq/core/dist/beeq/beeq"; +```js +import { setBasePath } from "@beeq/core/dist/components"; + +// Using heroicons library +setBasePath('https://cdn.jsdelivr.net/npm/heroicons@2.1.5/24/outline'); ``` -> ❗️The icons SVG are shipped in a separate folder. Depending on your React stack, your project will need to include `node_modules/@beeq/core/dist/beeq/svg` in the build in such a way that it respond to: `http:///svg` +> [!CAUTION] +> When using a different icons library, make sure you use the correct icon names provided by the library or the CDN. ## Usage @@ -52,17 +107,3 @@ function App() { export default App; ``` - -## Why is this necessary? - -React and custom elements don't play nicely together. The problem is best described by [Custom Elements Everywhere](https://custom-elements-everywhere.com/#react): - -> **Handling data** -> -> React passes all data to Custom Elements in the form of HTML attributes. For primitive data this is fine, but the system breaks down when passing rich data, like objects or arrays. In these instances you end up with stringified values like some-attr="[object Object]" which can't actually be used. -> -> **Handling events** -> -> Because React implements its own synthetic event system, it cannot listen for DOM events coming from Custom Elements without the use of a workaround. Developers will need to reference their Custom Elements using a ref and manually attach event listeners with addEventListener. This makes working with Custom Elements cumbersome. - -This utility solves these problems by exposing a native React component that maps properties and events to the underlying custom element. ✨ diff --git a/packages/beeq-vue/README.md b/packages/beeq-vue/README.md index 032811332..104a4f3e2 100644 --- a/packages/beeq-vue/README.md +++ b/packages/beeq-vue/README.md @@ -2,35 +2,93 @@ A lightweight utility that wraps BEEQ custom elements ("web components") so they can be seamlessly integrated into Vue applications. +## Why is this necessary? + +BEEQ can generate Vue component wrappers for your web components. This allows BEEQ components to be used within a Vue 3 application. The benefits of using BEEQ's component wrappers over the standard web components include: + +- Type checking with your components. +- Integration with the router link and Vue router. +- Optionally, form control web components can be used with `v-model`. + +(*Adapted from the [Stencil official documentation](https://stenciljs.com/docs/vue)*) + ## Package installation +> [!TIP] +> Please always refer to the [official BEEQ documentation](https://www.beeq.design/3d466e231/p/359a26-for-developers/b/53475d) for more information about the installation. + - install the package ``` -npm install @beeq/vue +npm install @beeq/{core,vue} ``` -- update the package +> [!NOTE] +> Make sure that you have installed the `@beeq/core` package. +### Add BEEQ styles and assets + +Import BEEQ styles into your application's main style file: + +```css +@import "@beeq/core/dist/beeq/beeq.css"; ``` -npm install @beeq/vue@latest + +> [!TIP] +> BEEQ uses SVG icons and these assets are shipped in a separate folder. You can use the `setBasePath` method to set the path to the icons. Make sure that your project bundle the icons in a way that they are accessible from the browser. + +You can move the icons from the node_modules folder to your assets folder and set the path like this: + +```js +// vite.config.js +import { defineConfig } from "vite"; +import vue from "@vitejs/plugin-vue"; +import vueJsx from "@vitejs/plugin-vue-jsx"; +import { viteStaticCopy } from "vite-plugin-static-copy"; + +export default defineConfig({ + plugins: [ + vue({ + template: { + compilerOptions: { + // treat all BEEQ tags as custom elements + isCustomElement: (tag) => tag.includes("bq-"), + }, + }, + }), + vueJsx(), + viteStaticCopy({ + targets: [ + { + src: "./node_modules/@beeq/core/dist/beeq/svg/*", + dest: "assets/svg", + }, + // other assets + ], + }), + ], + // other configurations +}); ``` -if `@beeq/core` package is installed you should update both +```js +// main.ts +import { setBasePath } from '@beeq/core'; -``` -npm install @beeq/{core,vue} +setBasePath('icons/svg'); ``` -### Add BEEQ styles and assets +But you can also use a different icons library or a CDN: -Make sure that BEEQ main style is imported into your application's main style file: +```js +import { setBasePath } from '@beeq/core'; -```css -@import "@beeq/core/dist/beeq/beeq"; +// Using heroicons library +setBasePath('https://cdn.jsdelivr.net/npm/heroicons@2.1.5/24/outline'); ``` -> ❗️The icons SVG are shipped in a separate folder. Depending on your stack, your project will need to include `node_modules/@beeq/core/dist/beeq/svg` in the build in such a way that it respond to: `http:///svg` +> [!CAUTION] +> When using a different icons library, make sure you use the correct icon names provided by the library or the CDN. ## Usage @@ -52,13 +110,3 @@ const name = ref('John Doe'); ``` - -## Why is this necessary? - -BEEQ can generate Vue component wrappers for your web components. This allows BEEQ components to be used within a Vue 3 application. The benefits of using BEEQ's component wrappers over the standard web components include: - -- Type checking with your components. -- Integration with the router link and Vue router. -- Optionally, form control web components can be used with `v-model`. - -(*Adapted from the [Stencil official documentation](https://stenciljs.com/docs/vue)*) diff --git a/packages/beeq/README.md b/packages/beeq/README.md index 7d5f246f8..614ef4887 100644 --- a/packages/beeq/README.md +++ b/packages/beeq/README.md @@ -4,9 +4,10 @@ The elements and components provided by BEEQ are being implemented with [Stencil ## Installation -BEEQ elements, components, patterns, utilities, etc., are available as an npm package. +> [!TIP] +> Please always refer to the [official BEEQ documentation](https://www.beeq.design/3d466e231/p/359a26-for-developers) for more information about the installation. -### For `stable` releases +BEEQ elements, components, patterns, utilities, etc., are available as an npm package. ```bash $ npm i @beeq/core @@ -28,7 +29,8 @@ BEEQ components are regular HTML elements, or custom elements (often referred to ``` -> ❗️The icons SVG are shipped in a separate folder. Projects will need to include `node_modules/@beeq/core/dist/beeq/svg` in their build and try to make it in a certain way that it respond to: `http:///svg` +> [!CAUTION] +> The icons SVG are shipped in a separate folder. Projects will need to include `node_modules/@beeq/core/dist/beeq/svg` in their build and try to make it in a certain way that it respond to: `http:///svg` ### Events