From 4a93837aa7fc75770e680994d6a8852c7601e676 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20F=C3=BCrhoff?= <12294151+imagoiq@users.noreply.github.com> Date: Thu, 24 Aug 2023 12:43:10 +0200 Subject: [PATCH] fix(documentation,internet-header): Clarify and fix internet-header getting started doc (#1792) Co-authored-by: Philipp Gfeller <1659006+gfellerph@users.noreply.github.com> --- .changeset/few-ducks-design.md | 6 ++ .../getting-started.stories.mdx | 84 ++++++++++------- .../internet-header/getting-started.docs.mdx | 92 +++++++++++-------- packages/internet-header/readme.md | 53 +++++++++-- 4 files changed, 154 insertions(+), 81 deletions(-) create mode 100644 .changeset/few-ducks-design.md diff --git a/.changeset/few-ducks-design.md b/.changeset/few-ducks-design.md new file mode 100644 index 0000000000..6c0a12e689 --- /dev/null +++ b/.changeset/few-ducks-design.md @@ -0,0 +1,6 @@ +--- +'@swisspost/internet-header': patch +'@swisspost/design-system-documentation': patch +--- + +Clarified and fixed which internet-header versions are available and how to use them. diff --git a/packages/documentation-v6/src/stories/internet-header/getting-started.stories.mdx b/packages/documentation-v6/src/stories/internet-header/getting-started.stories.mdx index b63882db93..18535e6ca9 100644 --- a/packages/documentation-v6/src/stories/internet-header/getting-started.stories.mdx +++ b/packages/documentation-v6/src/stories/internet-header/getting-started.stories.mdx @@ -17,7 +17,14 @@ The header for client-facing applications. ## Installation -### Angular, Vue JS, React (or any other bundler setup) +### Choosing between lazy-loaded or bare component version + +Internet-header package provide two versions: + +* Lazy-loaded (default): it allows better performance by dynamically load the component when used, so it reduces bundle size, startup time and first paint. +* Bare component: if you already manage the lazy-loading or don't need it for any reason, you can use the component without any overhead. + +### Angular, Vue.js, React (or any other bundler setup) All the popular frameworks come with some form of bundler. This makes it easy to use npm packages like the Internet Header as you can import, bundle and deliver the header with your own code. @@ -27,13 +34,6 @@ When working with Angular or any other framework, the easiest installation metho npm install @swisspost/internet-header ``` -```typescript -// main.ts / index.js / ... -import { defineCustomElements } from '@swisspost/internet-header'; - -defineCustomElements(); -``` - ```html @@ -42,15 +42,48 @@ defineCustomElements(); ``` +#### Lazy-loaded + +```javascript +// main.ts / index.js / ... +import { defineCustomElements } from '@swisspost/internet-header/loader'; + +defineCustomElements(); +``` + +#### Bare component + +```javascript +// main.ts / index.js / ... +import '@swisspost/internet-header/dist/swisspost-internet-header/swisspost-internet-header.esm'; +``` + ### Include from a CDN -If you are not using any loader or don't want to install from npm, you can load the `internet-header` from your favourite [CDN](https://en.wikipedia.org/wiki/Content_delivery_network).
-There are two options available. Make sure to replace `{version}` with the version you want to use. +If you are not using any bundler or don't want to install from npm, you can load the `internet-header` from your favourite [CDN](https://en.wikipedia.org/wiki/Content_delivery_network).
+Make sure to replace `{version}` with the version you want to use or remove `@{version}` to use the latest version. + +Available CDNs: -- [jsDelivr](https://www.jsdelivr.com/) -- [unpkg](https://unpkg.com/) +* [jsDelivr](https://www.jsdelivr.com/): replace `{cdnURL}` with [https://cdn.jsdelivr.net/npm/@swisspost/internet-header](https://cdn.jsdelivr.net/npm/@swisspost/internet-header). +* [unpkg](https://unpkg.com/): replace `{cdnURL}` with [https://unpkg.com/@swisspost/internet-header](https://unpkg.com/@swisspost/internet-header). -#### jsDelivr +#### Lazy-loaded + +```html + + + + + + + +``` +#### Bare component ```html @@ -58,7 +91,7 @@ There are two options available. Make sure to replace `{version}` with the versi @@ -66,22 +99,6 @@ There are two options available. Make sure to replace `{version}` with the versi ``` -```javascript -// main.js | main.ts -import { defineCustomElements } from 'https://cdn.jsdelivr.net/npm/@swisspost/internet-header@{version}/loader/index.min.js'; - -defineCustomElements(); -``` - -#### unpkg - -```javascript -// main.js | main.ts -import { defineCustomElements } from 'https://unpkg.com/@swisspost/internet-header@{version}/loader/index.min.js'; - -defineCustomElements(); -``` - ## Configuration The Internet Header is built to support the already existing Portal Configuration used for the old Internet Header. @@ -89,12 +106,13 @@ The Internet Header is built to support the already existing Portal Configuratio If you're working on a new project, you probably need a new configuration. Please click the button below. - Contact Post Portal Team + Contact Post Portal Team + Not every Online Service has configurations for all environments. For example, "TOPOS" only has `int02` configured and cannot use `int01` as value for environment. If you are not sure what's configured for your project, please reach out to the post-portal team as well. @@ -103,4 +121,4 @@ For settings on the header itself, see the examples provided in the left menu ba ## Help -If you noticed a bug or need assistance with migrating to the new Internet Header, please post your enquiry at the [Design System Github Discussions](https://github.com/swisspost/design-system/discussions/categories/q-a). +If you noticed a bug or need assistance with migrating to the new Internet Header, please post your enquiry at the [Design System GitHub Discussions](https://github.com/swisspost/design-system/discussions/categories/q-a). diff --git a/packages/documentation/src/stories/internet-header/getting-started.docs.mdx b/packages/documentation/src/stories/internet-header/getting-started.docs.mdx index 56db136b21..5db26a9492 100644 --- a/packages/documentation/src/stories/internet-header/getting-started.docs.mdx +++ b/packages/documentation/src/stories/internet-header/getting-started.docs.mdx @@ -12,13 +12,22 @@ import { BADGE } from '../../../.storybook/constants'; The header for client-facing applications. -- [Installation](#installation) -- [Configuration](#configuration) -- [Help](#help) + ## Installation -### Angular, Vue JS, React (or any other bundler setup) +### Choosing between lazy-loaded or bare component version + +Internet-header package provide two versions: + +* Lazy-loaded (default): it allows better performance by dynamically load the component when used, so it reduces bundle size, startup time and first paint. +* Bare component: if you already manage the lazy-loading or don't need it for any reason, you can use the component without any overhead. + +### Angular, Vue.js, React (or any other bundler setup) All the popular frameworks come with some form of bundler. This makes it easy to use npm packages like the Internet Header as you can import, @@ -30,13 +39,6 @@ When working with Angular or any other framework, the easiest installation metho npm install @swisspost/internet-header ``` -```typescript -// main.ts / index.js / ... -import { defineCustomElements } from '@swisspost/internet-header'; - -defineCustomElements(); -``` - ```html @@ -45,18 +47,47 @@ defineCustomElements(); ``` +#### Lazy-loaded + +```javascript +// main.ts / index.js / ... +import { defineCustomElements } from '@swisspost/internet-header/loader'; + +defineCustomElements(); +``` + +#### Bare component + +```javascript +// main.ts / index.js / ... +import '@swisspost/internet-header/dist/swisspost-internet-header/swisspost-internet-header.esm'; +``` + ### Include from a CDN -If you are not using any loader or don't want to install from npm, -you can load the `internet-header` from your favourite -[CDN](https://en.wikipedia.org/wiki/Content_delivery_network).
-There are two options available. -Make sure to replace `{version}` with the version you want to use. +If you are not using any bundler or don't want to install from npm, you can load the `internet-header` from your favourite [CDN](https://en.wikipedia.org/wiki/Content_delivery_network).
+Make sure to replace `{version}` with the version you want to use or remove `@{version}` to use the latest version. + +Available CDNs: -- [jsDelivr](https://www.jsdelivr.com/) -- [unpkg](https://unpkg.com/) +* [jsDelivr](https://www.jsdelivr.com/): replace `{cdnURL}` with [https://cdn.jsdelivr.net/npm/@swisspost/internet-header](https://cdn.jsdelivr.net/npm/@swisspost/internet-header). +* [unpkg](https://unpkg.com/): replace `{cdnURL}` with [https://unpkg.com/@swisspost/internet-header](https://unpkg.com/@swisspost/internet-header). -#### jsDelivr +#### Lazy-loaded + +```html + + + + + + + +``` +#### Bare component ```html @@ -64,7 +95,7 @@ Make sure to replace `{version}` with the version you want to use. @@ -72,22 +103,6 @@ Make sure to replace `{version}` with the version you want to use. ``` -```javascript -// main.js | main.ts -import { defineCustomElements } from 'https://cdn.jsdelivr.net/npm/@swisspost/internet-header@{version}/loader/index.min.js'; - -defineCustomElements(); -``` - -#### unpkg - -```javascript -// main.js | main.ts -import { defineCustomElements } from 'https://unpkg.com/@swisspost/internet-header@{version}/loader/index.min.js'; - -defineCustomElements(); -``` - ## Configuration The Internet Header is built to support the already existing Portal Configuration used for the old Internet Header. @@ -99,7 +114,7 @@ If you're working on a new project, you probably need a new configuration. Pleas href="mailto:digitalconsulting@post.ch" target="_blank" rel="noopener" ->Contact Post Portal Team +>Contact Post Portal Team Not every Online Service has configurations for all environments. For example, "TOPOS" only has `int02` configured and cannot use `int01` as value for environment. @@ -109,5 +124,4 @@ For settings on the header itself, see the examples provided in the left menu ba ## Help -If you noticed a bug or need assistance with migrating to the new Internet Header, -please post your enquiry at the [Design System GitHub Discussions](https://github.com/swisspost/design-system/discussions/categories/q-a). +If you noticed a bug or need assistance with migrating to the new Internet Header, please post your enquiry at the [Design System GitHub Discussions](https://github.com/swisspost/design-system/discussions/categories/q-a). diff --git a/packages/internet-header/readme.md b/packages/internet-header/readme.md index bb7058bf5d..17227688b1 100644 --- a/packages/internet-header/readme.md +++ b/packages/internet-header/readme.md @@ -14,7 +14,7 @@ The header docs are part of the storybook docs for the Design System. There are two possibilities to install the header on a page. -### npm installation +### Npm installation Use this if your project uses a bundler or a framework like Angular, React or Vue. @@ -22,28 +22,63 @@ Use this if your project uses a bundler or a framework like Angular, React or Vu npm install @swisspost/internet-header ``` -`main.ts` +```html + + + + ... + +``` + +#### Lazy-loaded -```ts -import { defineCustomElements } from '@swisspost/internet-header'; +```javascript +// main.ts / index.js / ... +import { defineCustomElements } from '@swisspost/internet-header/loader'; defineCustomElements(); ``` +#### Bare component + +```javascript +// main.ts / index.js / ... +import '@swisspost/internet-header/dist/swisspost-internet-header/swisspost-internet-header.esm'; +``` + ### Basic installation Use this if you want to use the CDN version and if you don't use a bundler or a framework. +Make sure to replace `{version}` with the version you want to use or remove `@{version}` to use the latest version. -`index.html` +#### Lazy-loaded ```html - - - ... + + + + + + + +``` +#### Bare component + +```html + + + + + ```