From 74d42a817ce7325f42b9d82d8d069433278aa300 Mon Sep 17 00:00:00 2001 From: Gery Hirschfeld Date: Mon, 4 Mar 2024 10:55:45 +0100 Subject: [PATCH] update upgrade guide to v16 --- .../bal-notification.stories.ts | 4 +- .../02-upgrade/upgrade-guide.v16.stories.mdx | 237 ++++++++++-------- package-lock.json | 2 +- packages/core/package.json | 2 +- packages/devkit/src/ng-upgrade-16/index.ts | 2 +- 5 files changed, 140 insertions(+), 107 deletions(-) diff --git a/docs/stories/components/bal-notification/bal-notification.stories.ts b/docs/stories/components/bal-notification/bal-notification.stories.ts index 21aea5ed..f7f44f53 100644 --- a/docs/stories/components/bal-notification/bal-notification.stories.ts +++ b/docs/stories/components/bal-notification/bal-notification.stories.ts @@ -1,6 +1,6 @@ import type { JSX } from '@baloise/ds-core' import type { Meta } from '@storybook/html' -import { withRender, withContent, withDefaultContent, withComponentControls, StoryFactory } from '../../utils' +import { withRender, withContent, withDefaultContent, withComponentControls, StoryFactory, props } from '../../utils' type Args = JSX.BalNotification & { content: string } @@ -16,7 +16,7 @@ const meta: Meta = { ...withComponentControls({ tag: 'bal-notification' }), }, ...withRender( - ({ content }) => ` + ({ content, ...args }) => ` ${content} `, ), diff --git a/docs/stories/development/02-upgrade/upgrade-guide.v16.stories.mdx b/docs/stories/development/02-upgrade/upgrade-guide.v16.stories.mdx index caefaba3..f4bb4b70 100644 --- a/docs/stories/development/02-upgrade/upgrade-guide.v16.stories.mdx +++ b/docs/stories/development/02-upgrade/upgrade-guide.v16.stories.mdx @@ -29,10 +29,113 @@ Updating from v15 to v16 +## Overview + +Here is an overview of the breaking changes of the newly introduced version 16: + +- [Simplifying Our Package Names](#simplifying-our-package-name) +- [Standardizing Design Tokens](#standardizing-design-tokens) +- [Components](#components) + +## Simplifying Our Package Names + +### Why the Change? + +In our continuous effort to enhance your development experience, we've made some important changes to our package names. +This update addresses four main issues that many of you have voiced: + +1. **Lengthy Names:** The previous package names were cumbersome, leading to a less than ideal experience in your IDEs. Long names not only clutter your workspace but also make auto-completion less efficient, slowing down your coding process. +2. **Relevance:** Over time, as our libraries evolved, the original package names no longer accurately reflected the content and functionality they enclose. This mismatch could cause confusion and make it harder for new users to find what they need. +3. **Sub-Packages Refinement:** The Angular sub-packages have been reorganized for direct, independent installation, addressing issues of incorrect imports and side-effects. + +### What's Changing? + +We've undertaken a comprehensive review of our package naming convention to address these concerns. The result is a set of shorter, more intuitive names that better describe the package contents. +Here's a summary of the key changes: + + + {` +| Old Package Name | New Package Name | Description | +| :--------------------------------------------------- | :------------------------- | :-------------------------------------------------------------------------------------- | +| @baloise/design-system-components | @baloise/ds-core | Core features of the Design System like Web-Components, Components-Styles and Utilities | +| @baloise/design-system-components-angular | @baloise/ds-angular-module | Angular component and provider library based on Angular Module and ESBuild | +| @baloise/design-system-components-angular/standalone | @baloise/ds-angular | Angular component and provider library based on Angular Standalone and ESBuild | +| @baloise/design-system-components-angular/legacy | @baloise/ds-angular-legacy | Angular component and provider library based on Angular Module and Webpack | +| @baloise/design-system-components-react | @baloise/ds-react | React component library | +| @baloise/design-system-components-vue | @baloise/ds-vue | Vue component library | +| @baloise/design-system-components-table | @baloise/ds-table | AG-Grid components and styles | +| @baloise/design-system-cli | @baloise/ds-devkit | Angular and NX schematics | +| @baloise/design-system-\\\* | @baloise/ds-\\\* | | +`} + + +### How to Upgrade + +Upgrading to the new package names is now more streamlined, thanks to our newly introduced Angular Schematics script +for Angular projects. For projects not using Angular, the upgrade will need to be carried out manually. +Here's how to proceed in both scenarios: + +#### For Angular Projects + +1. **Install Devkit:** First install the devkit package with the angular schematics script: + +```bash +npm add -D -E @baloise/ds-devkit +``` + +2. **Angular Schematics Script:** Rename the packages by simply run the following command in your project's root directory: + +```bash +ng generate @baloise/ds-devkit:up16 +``` + +3. **Verify the Changes:** Once the script has run, review the changes to ensure everything has been updated correctly. It's a good practice to check the git diff if your project is version-controlled. + +4. **Test Your Application:** Run your application and execute your test suite to ensure that everything works as expected. The schematic should handle the renaming seamlessly, but it's important to verify that no issues have arisen from the change. + +#### For Non-Angular Projects: + +1. **Check the Full List:** Refer to the detailed mapping table above. This table lists all old and new package names, ensuring you're aware of all the changes. + +2. **Update Your Dependencies:** Manually modify the dependencies in your package.json. + +3. **Refactor Your Imports:** Manually update import statements in your codebase to reflect the new package names. + +4. **Test Thoroughly:** After making these updates, thoroughly test your application to ensure that all functionalities work as expected. The manual process might be more prone to human error, so a comprehensive testing phase is crucial. + +## Standardizing Design Tokens + +### Why the Change? + The objective of this breaking change is to standardize the design tokens, facilitating their export to platforms such as Figma and others. With the introduction of these new design tokens, we can automatically generate CSS utility classes. This enhancement extends functionality, particularly in responsive design and pseudo-states. +> **Non-Breaking Nature of the Update** +> +> Importantly, this token changes has been designed to be non-breaking. +> +> Our goal is to ensure that you can benefit from these new features without disrupting your existing workflows. +> +> Therefore keep the `@baloise/ds-css` package instead of the new `@baloise/ds-styles` package. However, then you will not benefit from the new improved CSS-Utility Classes. +> +> The previous documentation of version `15.x.x` with the old CSS-Utility Classes can be found [here](https://baloise-design-system-v15.vercel.app). +> +>
+> Here is how you do it. +> +> 1. **Install Package:** First lets install the deprecated `@baloise/ds-css`. +> +> ```bash +> npm add @baloise/ds-css +> ``` +> +> 2. **Update Imports:** Adjust the import paths of your source files. + +### What's Changing? + +Here are some examples of the changes to see there benefit: + 1. The **RENAMING** (or removing of prefixes like `is-*` or `has-*`) of the classes should **improve the readability** too. - -The following workflow walks you through the upgrade steps. -Note that the actual steps required for your project may vary, and these steps should be treated as general guidance -rather than strict instructions. - - - - - -
- -**Lets start:** - -```bash -npm add -E @baloise/design-system-components-angular@16 -``` - -If there are more `@baloise/design-system` dependencies in the projects `package.json` file upgrade them as well. - - - -## CSS Utilities - -### Non Breaking Upgrade +As part of this change, we are introducing a new package called `@baloise/ds-styles`. -First update the `@baloise` packages to v16. +### How to Upgrade -The deprecated package `@baloise/design-system-css` needs to be installed. +Upgrading to the new styles package is streamlined, thanks to our newly introduced `@baloise/ds-styles` +package CLI. Here's how to proceed: -```bash -npm add -E @baloise/design-system-components-css@16 -``` - -Replace the required stylesheets from the `css` package with the new ones from the `styles` package and keep the deprecated CSS utilities classes. - - - - - -- If the stylesheet `baloise-design-system` was used the please split into the following files. -- It is recommended to migrate `legacy` sass file. - - - -### Migrate with CLI - -Before running the CLI to migrate to new styles package make sure the git stage is empty, because -then it is easier to see all the changes of the CLI. - -1. Install the CLI to help with the migration. +1. **Install Styles:** First we need to install the new styles package if yet not there. ```bash -npm add -D -E @baloise/design-system-cli@16 +npm add -D -E @baloise/ds-styles@16 ``` -2. Run the migration cli to rename the changed CSS utility classes. +2. **Start CLI:**: Run the migration CLI to rename the changed CSS utility classes. The CLI updates the global stylesheet, component stylesheets, HTML files and Angular inline templates. ```bash npx bds-migrate-to-styles ``` -The CLI updates the global stylesheet, component stylesheets, HTML files and Angular inline templates. +3. **Verify the Changes:** Once the CLI has run, review the changes to ensure everything has been updated correctly. It's a good practice to check the git diff if your project is version-controlled. -### Migrate Manual +4. **Test Your Application:** Run your application and execute your test suite to ensure that everything works as expected. + The CLI should handle the renaming seamlessly, but it's important to verify that no issues have arisen from the change. -1. Change the import from `@baloise/design-system-css` to `@baloise/design-system-styles`. +#### Migrate Manually + +1. Change the import from `@baloise/design-system-css` to `@baloise/ds-styles`. - Check the `styles.scss` file and change the paths. or ... ```css // SASS mixins and SASS variables -@import '@baloise/design-system-styles/sass/mixins'; +@import '@baloise/ds-styles/sass/mixins'; // Resets CSS for all browser -@import '@baloise/design-system-styles/css/normalize'; -@import '@baloise/design-system-styles/css/structure'; +@import '@baloise/ds-styles/css/normalize'; +@import '@baloise/ds-styles/css/structure'; // Custom font faces -@import '@baloise/design-system-styles/css/font'; +@import '@baloise/ds-styles/css/font'; // Core CSS with CSS variables, always required -@import '@baloise/design-system-styles/css/core'; +@import '@baloise/ds-styles/css/core'; // CSS utilities classes (optional) -@import '@baloise/design-system-styles/css/utilities/background'; -@import '@baloise/design-system-styles/css/utilities/border'; -@import '@baloise/design-system-styles/css/utilities/elevation'; -@import '@baloise/design-system-styles/css/utilities/flex'; -@import '@baloise/design-system-styles/css/utilities/interaction'; -@import '@baloise/design-system-styles/css/utilities/layout'; -@import '@baloise/design-system-styles/css/utilities/sizing'; -@import '@baloise/design-system-styles/css/utilities/spacing'; -@import '@baloise/design-system-styles/css/utilities/typography'; +@import '@baloise/ds-styles/css/utilities/background'; +@import '@baloise/ds-styles/css/utilities/border'; +@import '@baloise/ds-styles/css/utilities/elevation'; +@import '@baloise/ds-styles/css/utilities/flex'; +@import '@baloise/ds-styles/css/utilities/interaction'; +@import '@baloise/ds-styles/css/utilities/layout'; +@import '@baloise/ds-styles/css/utilities/sizing'; +@import '@baloise/ds-styles/css/utilities/spacing'; +@import '@baloise/ds-styles/css/utilities/typography'; ``` - Check the component style files if the `mixins` are used and change the path. ```css -@import '@baloise/design-system-styles/sass/mixins'; +@import '@baloise/ds-styles/sass/mixins'; ``` 2. Go through all the HTML files and replace the old CSS utility class with the new one. @@ -520,6 +551,8 @@ The spacing helpers have not been renamed only the responsive markers. ## Components +Moreover, there are two breaking changes in the components section: + ### Button Properties `topRounded` and `bottomRounded` has been removed, due to not match the design criteria. diff --git a/package-lock.json b/package-lock.json index d28d1418..e32e4d29 100644 --- a/package-lock.json +++ b/package-lock.json @@ -48734,7 +48734,6 @@ "version": "0.0.5", "license": "Apache-2.0", "dependencies": { - "@baloise/ds-css": "0.0.5", "@baloise/ds-icons": "0.0.5", "@baloise/ds-styles": "0.0.5", "@baloise/web-app-utils": "3.11.2", @@ -48758,6 +48757,7 @@ }, "devDependencies": { "@baloise/ds-brand-icons": "0.0.5", + "@baloise/ds-css": "0.0.5", "@baloise/ds-favicons": "0.0.5", "@baloise/ds-maps": "0.0.5", "@baloise/output-target-angular": "0.0.0", diff --git a/packages/core/package.json b/packages/core/package.json index 8df881e4..0bbf5fae 100644 --- a/packages/core/package.json +++ b/packages/core/package.json @@ -29,7 +29,6 @@ }, "dependencies": { "@baloise/ds-styles": "0.0.5", - "@baloise/ds-css": "0.0.5", "@baloise/ds-icons": "0.0.5", "@baloise/web-app-utils": "3.11.2", "@floating-ui/dom": "~1.6.3", @@ -54,6 +53,7 @@ "@baloise/output-target-angular": "0.0.0", "@baloise/output-target-react": "0.0.0", "@baloise/output-target-vue": "0.0.0", + "@baloise/ds-css": "0.0.5", "@baloise/ds-maps": "0.0.5", "@baloise/ds-brand-icons": "0.0.5", "@baloise/ds-favicons": "0.0.5" diff --git a/packages/devkit/src/ng-upgrade-16/index.ts b/packages/devkit/src/ng-upgrade-16/index.ts index 287c75ed..1ef74553 100644 --- a/packages/devkit/src/ng-upgrade-16/index.ts +++ b/packages/devkit/src/ng-upgrade-16/index.ts @@ -87,7 +87,7 @@ export function changePackageName(_options: any): Rule { changePackage('design-system-fonts', 'ds-fonts') changePackage('design-system-maps', 'ds-maps') - changePackage('design-system-grid', 'ds-table') + changePackage('design-system-components-table', 'ds-table') changePackage('design-system-testing', 'ds-testing') changePackage('design-system-cli', 'ds-devkit')