diff --git a/src/components/MdxIcon/icons/webcomponents.png b/src/components/MdxIcon/icons/webcomponents.png new file mode 100644 index 00000000000..e5b5b3e52b6 Binary files /dev/null and b/src/components/MdxIcon/icons/webcomponents.png differ diff --git a/src/components/MdxIcon/index.js b/src/components/MdxIcon/index.js index e992bc7018a..36f14c0d914 100644 --- a/src/components/MdxIcon/index.js +++ b/src/components/MdxIcon/index.js @@ -11,6 +11,7 @@ import illustrator from './icons/illustrator.svg'; import react from './icons/react.png'; import vue from './icons/vue.png'; import angular from './icons/angular.png'; +import webcomponents from './icons/webcomponents.png'; import npm from './icons/npm.svg'; const localIcons = { @@ -22,6 +23,7 @@ const localIcons = { react, vue, angular, + webcomponents, npm, }; diff --git a/src/pages/developing/dev-resources/index.mdx b/src/pages/developing/dev-resources/index.mdx index db2c02c7cc9..983936cd861 100644 --- a/src/pages/developing/dev-resources/index.mdx +++ b/src/pages/developing/dev-resources/index.mdx @@ -70,6 +70,14 @@ your framework of choice. + + + + + + ### Storybooks @@ -105,6 +113,17 @@ your framework of choice. + + + + + + + + ### Tools diff --git a/src/pages/developing/frameworks/angular.mdx b/src/pages/developing/frameworks/angular.mdx index 8c6402e69a4..ee6b4f563d9 100644 --- a/src/pages/developing/frameworks/angular.mdx +++ b/src/pages/developing/frameworks/angular.mdx @@ -2,8 +2,17 @@ title: Frameworks description: The Carbon Design System is built React first. We also support core parts of - the system in vanilla JS, Angular, Vue, and Svelte. -tabs: ['React', 'Vanilla', 'Angular', 'Vue', 'Svelte', 'Other frameworks'] + the system in vanilla JS, Angular, Vue, Svelte, and web components. +tabs: + [ + 'React', + 'Vanilla', + 'Angular', + 'Vue', + 'Svelte', + 'Web Components', + 'Other frameworks', + ] --- diff --git a/src/pages/developing/frameworks/other-frameworks.mdx b/src/pages/developing/frameworks/other-frameworks.mdx index d2f492f1943..bb3957f79c1 100755 --- a/src/pages/developing/frameworks/other-frameworks.mdx +++ b/src/pages/developing/frameworks/other-frameworks.mdx @@ -2,15 +2,25 @@ title: Frameworks description: The Carbon Design System is built React first. We also support core parts of - the system in vanilla JS, Angular, Vue, and Svelte. -tabs: ['React', 'Vanilla', 'Angular', 'Vue', 'Svelte', 'Other frameworks'] + the system in vanilla JS, Angular, Vue, Svelte, and web components. +tabs: + [ + 'React', + 'Vanilla', + 'Angular', + 'Vue', + 'Svelte', + 'Web Components', + 'Other frameworks', + ] --- The Carbon Design System is built React first. We also support core parts of the -system in vanilla JS, Angular, Vue, and Svelte. If you’re using a different -framework, you can still build components by following the guidelines below. +system in vanilla JS, Angular, Vue, Svelte, and web components. If you’re using +a different framework, you can still build components by following the +guidelines below. @@ -41,7 +51,7 @@ there are no zombie event handlers. The easiest way to hook on the creation/destruction of DOM elements is by defining a "wrapping component", with the JavaScript framework of your choice. -Here's an example using Web Components' +Here's an example using web components' [Custom Elements v1 spec](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Custom_Elements), but the notion of components, along with the lifecycle callbacks, are commonly found in many other JavaScript frameworks. diff --git a/src/pages/developing/frameworks/react.mdx b/src/pages/developing/frameworks/react.mdx index cdfd7871e90..4994eba7d57 100755 --- a/src/pages/developing/frameworks/react.mdx +++ b/src/pages/developing/frameworks/react.mdx @@ -2,8 +2,17 @@ title: Frameworks description: The Carbon Design System is built React first. We also support core parts of - the system in vanilla JS, Angular, Vue, and Svelte. -tabs: ['React', 'Vanilla', 'Angular', 'Vue', 'Svelte', 'Other frameworks'] + the system in vanilla JS, Angular, Vue, Svelte, and web components. +tabs: + [ + 'React', + 'Vanilla', + 'Angular', + 'Vue', + 'Svelte', + 'Web Components', + 'Other frameworks', + ] --- diff --git a/src/pages/developing/frameworks/svelte.mdx b/src/pages/developing/frameworks/svelte.mdx index 7e562e65f67..ceb5114f980 100644 --- a/src/pages/developing/frameworks/svelte.mdx +++ b/src/pages/developing/frameworks/svelte.mdx @@ -2,8 +2,17 @@ title: Frameworks description: The Carbon Design System is built React first. We also support core parts of - the system in vanilla JS, Angular, Vue, and Svelte. -tabs: ['React', 'Vanilla', 'Angular', 'Vue', 'Svelte', 'Other frameworks'] + the system in vanilla JS, Angular, Vue, Svelte, and web components. +tabs: + [ + 'React', + 'Vanilla', + 'Angular', + 'Vue', + 'Svelte', + 'Web Components', + 'Other frameworks', + ] --- diff --git a/src/pages/developing/frameworks/vanilla.mdx b/src/pages/developing/frameworks/vanilla.mdx index 88584ab1c1b..b5202b81fec 100755 --- a/src/pages/developing/frameworks/vanilla.mdx +++ b/src/pages/developing/frameworks/vanilla.mdx @@ -2,8 +2,17 @@ title: Frameworks description: The Carbon Design System is built React first. We also support core parts of - the system in vanilla JS, Angular, Vue, and Svelte. -tabs: ['React', 'Vanilla', 'Angular', 'Vue', 'Svelte', 'Other frameworks'] + the system in vanilla JS, Angular, Vue, Svelte, and web components. +tabs: + [ + 'React', + 'Vanilla', + 'Angular', + 'Vue', + 'Svelte', + 'Web Components', + 'Other frameworks', + ] --- @@ -298,7 +307,7 @@ there are no zombie event handlers. The easiest way to hook on the creation/destroy of DOM elements is defining a "wrapping component", with the JavaScript framework of your choice. Here's an -example using Web Components' +example using web components' [Custom Elements v1 spec](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Custom_Elements), but the notion of components, along with the lifecycle callbacks, are commonly found in many other JavaScript frameworks. diff --git a/src/pages/developing/frameworks/vue.mdx b/src/pages/developing/frameworks/vue.mdx index b4583f867ba..cce0a7a2c6e 100644 --- a/src/pages/developing/frameworks/vue.mdx +++ b/src/pages/developing/frameworks/vue.mdx @@ -2,8 +2,17 @@ title: Frameworks description: The Carbon Design System is built React first. We also support core parts of - the system in vanilla JS, Angular, Vue, and Svelte. -tabs: ['React', 'Vanilla', 'Angular', 'Vue', 'Svelte', 'Other frameworks'] + the system in vanilla JS, Angular, Vue, Svelte, and web components. +tabs: + [ + 'React', + 'Vanilla', + 'Angular', + 'Vue', + 'Svelte', + 'Web Components', + 'Other frameworks', + ] --- diff --git a/src/pages/developing/frameworks/web-components.mdx b/src/pages/developing/frameworks/web-components.mdx new file mode 100644 index 00000000000..de64de2e5ee --- /dev/null +++ b/src/pages/developing/frameworks/web-components.mdx @@ -0,0 +1,185 @@ +--- +title: Frameworks +description: + The Carbon Design System is built React first. We also support core parts of + the system in vanilla JS, Angular, Vue, Svelte, and web components. +tabs: + [ + 'React', + 'Vanilla', + 'Angular', + 'Vue', + 'Svelte', + 'Web Components', + 'Other frameworks', + ] +--- + + + +The library provides front-end developers and engineers a collection of reusable +web components to build websites and user interfaces. Adopting the library +enables developers to use consistent markup, styles, and behavior in prototype +and production work. + +This library uses Custom Elements v1 and Shadow DOM v1 specs. + + + + + +The web components library is maintained by members of the Carbon community. For +support, contact the +[Carbon Web Components team](https://github.com/carbon-design-system/carbon-web-components/issues/new/choose). + + + +## Resources + + + + + +![Storybook icon](images/storybook.svg) + + + + + + + + + + +## Getting started + +To install `carbon-web-components` in your project, you will need to run the +following command using [npm](https://www.npmjs.com/): + +```bash +npm install -S carbon-web-components carbon-components lit-html lit-element +``` + +If you prefer [Yarn](https://yarnpkg.com/en/), use the following command +instead: + +```bash +yarn add carbon-web-components carbon-components lit-html lit-element +``` + +### Basic usage + +Our example at [CodeSandbox](https://codesandbox.io) shows the most basic usage: + +[![Edit carbon-web-components](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/s/github/carbon-design-system/carbon-web-components/tree/master/examples/codesandbox/basic) + +The first thing you need to do is **set up a module bundler** to resolve +ECMAScript `import`s. The above example uses [Webpack](https://webpack.js.org) but you +can use other bundlers like [Rollup](https://rollupjs.org/) too. + +Once you set up a module bundler, you can start importing our component modules, +for example: + +```javascript +import 'carbon-web-components/es/components/dropdown/dropdown.js'; +import 'carbon-web-components/es/components/dropdown/dropdown-item.js'; +``` + +Once you've imported the component modules, you can use our components in the same manner as native HTML +tags, for example: + +```html + + Option 1 + Option 2 + Option 3 + Option 4 + Option 5 + +``` + +If you just want to try our components for demonstrations and so on, you can use +CDNs that support module mapping (for example, [JSPM](https://jspm.org)). With +CDNs, you can import just our modules in ` + + + +
+ + Option 1 + Option 2 + Option 3 + Option 4 + Option 5 + +
+ + +``` + +### List of available components + +View available web components +[here](https://web-components.carbondesignsystem.com). Usage information is +available in the notes provided with each story. + +### JavaScript framework integration + +In addition to the available web component versions of Carbon components, this +library also supports usage with JavaScript frameworks like Angular, React, and +Vue if the desire is to use instead of the pure framework versions of Carbon +components. Specifically for React, this library comes with a wrapper +implementation around the Carbon Web Components for more seamless integration +with your React application. + +This is achievable since web components is the modern browser standard, and +works well with other front-end frameworks that exist in the application. In +turn, this also comes with the benefits of encapsulation within the Shadow DOM: + +- [Carbon Web Components with Angular](https://web-components.carbondesignsystem.com/angular/index.html) +- [Carbon Web Components with React](https://web-components.carbondesignsystem.com/react/index.html) +- [Carbon Web Components with Vue](https://web-components.carbondesignsystem.com/vue/index.html) + + + +**Note:** The approaches above detail the usage of Carbon Web Components within +popular JavaScript frameworks. The APIs are based on how the web components are +used, and differ from its pure framework counterparts (Carbon React, Carbon +Angular, Carbon Vue). + + + +## Troubleshooting + +If you experience any issues while getting set up with Carbon Web Components, +please head over to the +[GitHub repo](https://github.com/carbon-design-system/carbon-web-components) for +more guidelines and support. Please +[create an issue](https://github.com/carbon-design-system/carbon-web-components/issues) +if your issue does not already exist. diff --git a/src/pages/developing/get-started.mdx b/src/pages/developing/get-started.mdx index e05f43433a6..c75ea1878a2 100644 --- a/src/pages/developing/get-started.mdx +++ b/src/pages/developing/get-started.mdx @@ -101,6 +101,7 @@ question to you and will jump in to help you out. - [#carbon-react](https://ibm-studios.slack.com/archives/C2K6RFJ1G) - [#carbon-ng](https://ibm-studios.slack.com/archives/CBZC0LM2N) - [#carbon-vue](https://ibm-studios.slack.com/archives/CAM5P6NR1) +- [#carbon-web-components](https://ibm-studios.slack.com/archives/CL83LMKSA) - [#carbon-tutorial](https://ibm-studios.slack.com/archives/CJUGA7P6H) And be sure to sign up for the latest Carbon news at diff --git a/src/pages/index.mdx b/src/pages/index.mdx index 1a122129bee..5f1f872a970 100755 --- a/src/pages/index.mdx +++ b/src/pages/index.mdx @@ -112,6 +112,16 @@ building websites and user interfaces. + + + + + + ### Latest news and articles