From 8c06302e54903eec4a1bdce8591ec869117f9c7a Mon Sep 17 00:00:00 2001 From: qa46hx Date: Wed, 14 Jul 2021 16:45:55 +0200 Subject: [PATCH] chore: fix documentation of how to import core elements --- .changeset/pink-poems-think.md | 5 ++ README.md | 2 +- docs/blog/extending-lions-website.md | 4 +- docs/blog/introducing-lions-website.md | 6 +- .../babel-plugin-extend-docs/overview.md | 8 +- docs/docs/systems/core/overview.md | 4 +- docs/docs/systems/icon/overview.md | 2 +- docs/docs/systems/overlays/overview.md | 2 +- docs/guides/how-to/get-started.md | 2 +- docs/guides/principles/scoped-elements.md | 4 +- packages/core/README.md | 83 +------------------ 11 files changed, 24 insertions(+), 98 deletions(-) create mode 100644 .changeset/pink-poems-think.md diff --git a/.changeset/pink-poems-think.md b/.changeset/pink-poems-think.md new file mode 100644 index 000000000..ea52f769a --- /dev/null +++ b/.changeset/pink-poems-think.md @@ -0,0 +1,5 @@ +--- +'@lion/core': patch +--- + +fix documentation of how to import core elements diff --git a/README.md b/README.md index f1c3c4f8a..fb5c4ff8d 100644 --- a/README.md +++ b/README.md @@ -67,7 +67,7 @@ npm i @lion/ **This is the main use case for lion**. To import component classes, and extend them for your own design system's components. ```js -import { css } from '@mdjs/mdjs-preview'; +import { css } from '@lion/core'; import { LionInput } from '@lion/input'; class MyInput extends LionInput { diff --git a/docs/blog/extending-lions-website.md b/docs/blog/extending-lions-website.md index 889a5ef37..00a770745 100644 --- a/docs/blog/extending-lions-website.md +++ b/docs/blog/extending-lions-website.md @@ -84,7 +84,7 @@ Let's convert an example page `lion-calendar` is a reusable and accessible calendar view. It depends on [calendar](?path=/docs/calendar--default-story). ```js script -import { html, css } from '@mdjs/mdjs-preview'; +import { html, css } from '@lion/core'; import './lion-calendar.js'; export default { @@ -103,7 +103,7 @@ export default { `lion-calendar` is a reusable and accessible calendar view. It depends on [calendar](../../path/to/calendar.md). ```js script -import { html, css } from '@mdjs/mdjs-preview'; +import { html, css } from '@lion/core'; import '@lion/calendar/define'; ``` diff --git a/docs/blog/introducing-lions-website.md b/docs/blog/introducing-lions-website.md index 9ca867ac8..4765016f7 100644 --- a/docs/blog/introducing-lions-website.md +++ b/docs/blog/introducing-lions-website.md @@ -36,11 +36,11 @@ Let's convert an example page `lion-calendar` is a reusable and accessible calendar view. It depends on [calendar](?path=/docs/calendar--default-story). ```js script -import { html, css } from '@mdjs/mdjs-preview'; +import { html, css } from '@lion/core'; import './lion-calendar.js'; export default { - title: 'Others/Calendar', + title: 'Others/Calendar', }; ``` @@ -55,7 +55,7 @@ export default { `lion-calendar` is a reusable and accessible calendar view. It depends on [calendar](../../path/to/calendar.md). ```js script -import { html, css } from '@mdjs/mdjs-preview'; +import { html, css } from '@lion/core'; import '@lion/calendar/define'; ``` diff --git a/docs/docs/node-tools/babel-plugin-extend-docs/overview.md b/docs/docs/node-tools/babel-plugin-extend-docs/overview.md index 6a225dc6a..c8147c80c 100644 --- a/docs/docs/node-tools/babel-plugin-extend-docs/overview.md +++ b/docs/docs/node-tools/babel-plugin-extend-docs/overview.md @@ -83,7 +83,7 @@ paths: [ We have an existing demo code which we want to reuse. ```js -import { LitElement, html } from '@mdjs/mdjs-preview'; +import { LitElement, html } from '@lion/core'; import 'source-pkg/counter/define'; class MyApp extends LitElement { render() { @@ -112,7 +112,7 @@ tag: { ### Result of Replacement of tags ```js -import { LitElement, html } from '@mdjs/mdjs-preview'; +import { LitElement, html } from '@lion/core'; import 'extension-pkg/counter/define'; class MyApp extends LitElement { render() { @@ -130,7 +130,7 @@ customElements.define('my-app', MyApp); We have an existing demo code which we want to reuse. ```js -import { LitElement, html } from '@mdjs/mdjs-preview'; +import { LitElement, html } from '@lion/core'; import { SourceCounter } from 'source-pkg/counter'; class TenCounter extends SourceCounter { inc() { @@ -167,7 +167,7 @@ variable: { ### Result of Replacement of classes ```js -import { LitElement, html } from '@mdjs/mdjs-preview'; +import { LitElement, html } from '@lion/core'; import { SourceCounter } from 'extension-pkg/counter'; class TenCounter extends SourceCounter { inc() { diff --git a/docs/docs/systems/core/overview.md b/docs/docs/systems/core/overview.md index 85320daf5..f8d68ee29 100644 --- a/docs/docs/systems/core/overview.md +++ b/docs/docs/systems/core/overview.md @@ -7,7 +7,7 @@ To be sure a compatible version is used you should import it via this package. ```js // DO -import { LitElement, html, render } from '@mdjs/mdjs-preview'; +import { LitElement, html, render } from '@lion/core'; // DON'T import { LitElement, html, render } from 'lit-element'; @@ -29,7 +29,7 @@ npm i --save @lion/core ``` ```js -import { dedupeMixin, LitElement } from '@mdjs/mdjs-preview'; +import { dedupeMixin, LitElement } from '@lion/core'; ``` ### Example diff --git a/docs/docs/systems/icon/overview.md b/docs/docs/systems/icon/overview.md index a1566e5ee..92b3f6302 100644 --- a/docs/docs/systems/icon/overview.md +++ b/docs/docs/systems/icon/overview.md @@ -9,7 +9,7 @@ application, and you don't need to worry about carefully coordinating the dynami For security reasons, icons are defined using lit-html templates to guarantee XSS safety: ```js -import { html } from '@mdjs/mdjs-preview'; +import { html } from '@lion/core'; export default html` ... `; ``` diff --git a/docs/docs/systems/overlays/overview.md b/docs/docs/systems/overlays/overview.md index 895354adb..8e3bb0c86 100644 --- a/docs/docs/systems/overlays/overview.md +++ b/docs/docs/systems/overlays/overview.md @@ -69,7 +69,7 @@ const ctrl = new OverlayController({ Or creating your own Web Component which uses the Overlay System ```js -import { LitElement, html } from '@mdjs/mdjs-preview'; +import { LitElement, html } from '@lion/core'; import { OverlayMixin, withModalDialogConfig } from '@lion/overlays'; class MyOverlayComponent extends OverlayMixin(LitElement) { diff --git a/docs/guides/how-to/get-started.md b/docs/guides/how-to/get-started.md index f2089f695..b78877085 100644 --- a/docs/guides/how-to/get-started.md +++ b/docs/guides/how-to/get-started.md @@ -32,7 +32,7 @@ npm i @lion/ **This is the main use case for lion**. To import component classes, and extend them for your own design system's components. ```js -import { css } from '@mdjs/mdjs-preview'; +import { css } from '@lion/core'; import { LionInput } from '@lion/input'; class MyInput extends LionInput { diff --git a/docs/guides/principles/scoped-elements.md b/docs/guides/principles/scoped-elements.md index 3de9ed719..d65fd64a7 100644 --- a/docs/guides/principles/scoped-elements.md +++ b/docs/guides/principles/scoped-elements.md @@ -6,7 +6,7 @@ Whenever a lion component uses composition (meaning it uses another lion compone apply ScopedElementsMixin to make sure it uses the right version of this internal component. ```js -import { ScopedElementsMixin, LitElement, html } from '@mdjs/mdjs-preview'; +import { ScopedElementsMixin, LitElement, html } from '@lion/core'; import { LionInput } from '@lion/input'; import { LionButton } from '@lion/button'; @@ -89,7 +89,7 @@ connectedCallback() { In a less complex case, we might just want to add a child node to the dom. ```js -import { ScopedElementsMixin, LitElement, getScopedTagNamegetScopedTagName } from '@mdjs/mdjs-preview'; +import { ScopedElementsMixin, LitElement, getScopedTagNamegetScopedTagName } from '@lion/core'; ... diff --git a/packages/core/README.md b/packages/core/README.md index d77371057..c3be73104 100644 --- a/packages/core/README.md +++ b/packages/core/README.md @@ -1,82 +1,3 @@ -# Systems >> Core >> Overview || 10 +# Lion Core -The `@lion/core` package is mostly for in depth usage. -It handles the version of `lit-element` and `lit-html`. - -In order to be sure a compatible version is used import it via this package. - -```js -import { LitElement, html, render } from '@mdjs/mdjs-preview'; -``` - -## Features - -- [function to deduplicate mixins (dedupeMixin)](https://github.com/ing-bank/lion/blob/master/docs/docs/systems/core/#deduping-of-mixins) -- Mixin to handle disabled (DisabledMixin) -- Mixin to handle disabled AND tabIndex (DisabledWithTabIndexMixin) -- Mixin to manage auto generated needed slot elements in light dom (SlotMixin) - -> These features are not well documented - care to help out? - -## How to use - -### Installation - -```bash -npm i --save @lion/core -``` - -```js -import { dedupeMixin, LitElement } from '@mdjs/mdjs-preview'; -``` - -### Example - -```js -const BaseMixin = dedupeMixin((superClass) => { - return class extends superClass { ... }; -}); -``` - -## Deduping of mixins - -### Why is deduping of mixins necessary? - -Imagine you are developing web components and creating ES classes for Custom Elements. You have two generic mixins (let's say `M1` and `M2`) which require independently the same even more generic mixin (`BaseMixin`). `M1` and `M2` can be used independently, that means they have to inherit from `BaseMixin` also independently. But they can be also used in combination. Sometimes `M1` and `M2` are used in the same component and can mess up the inheritance chain if `BaseMixin` is applied twice. -In other words, this may happen to the protoype chain `... -> M2 -> BaseMixin -> M1 -> BaseMixin -> ...`. - -An example of this may be a `LocalizeMixin` used across different components and mixins. Some mixins may need it and many components need it too and can not rely on other mixins to have it by default, so must inherit from it independently. - -The more generic the mixin is, the higher the chance of being appliend more than once. As a mixin author you can't control how it is used, and can't always predict it. So as a safety measure it is always recommended to create deduping mixins. - -### Usage of dedupeMixin() - -This is an example of how to make a conventional ES mixin deduping. - -```js -const BaseMixin = dedupeMixin((superClass) => { - return class extends superClass { ... }; -}); - -// inherits from BaseMixin -const M1 = dedupeMixin((superClass) => { - return class extends BaseMixin(superClass) { ... }; -}); - -// inherits from BaseMixin -const M2 = dedupeMixin((superClass) => { - return class extends BaseMixin(superClass) { ... }; -}); - -// component inherits from M1 -// MyCustomElement -> M1 -> BaseMixin -> BaseCustomElement; -class MyCustomElement extends M1(BaseCustomElement) { ... } - -// component inherits from M2 -// MyCustomElement -> M2 -> BaseMixin -> BaseCustomElement; -class MyCustomElement extends M2(BaseCustomElement) { ... } - -// component inherits from both M1 and M2 -// MyCustomElement -> M2 -> M1 -> BaseMixin -> BaseCustomElement; -class MyCustomElement extends M2(M1(BaseCustomElement)) { ... } -``` +[=> See Source <=](../../docs/docs/systems/core/overview.md)