mvindahl / designsystem Goto Github PK

Kirby Design System is a UX Component library implementing the Kirby Design Philosophy.

Kirby Components are built on top of Angular and can be used in Angular projects.

The Kirby Cookbook, containing samples, status of components etc. can be accessed from https://cookbook.kirby.design.

• Installation
  • Include KirbyModule
  • Sass
  • Icons
  • Testing
  • Migration Guide
• Folder Structure
• Scripts
• Developing new features in Kirby
  • "New feature"-process
  • Testing new features
• Polyfills
• Chart Components

Install through npm:

npm i @kirbydesign/designsystem

Import the KirbyModule in your AppModule:

import { KirbyModule } from '@kirbydesign/designsystem';

...

@NgModule({
    imports: [
        ...,
        KirbyModule
    ],
    ...
})
export class AppModule {}

Include the Kirby global styles in your app:

• Eg. in src/styles.scss:

  @import '~@kirbydesign/designsystem/scss/global-styles';

  In each .scss file where you need to access the Sass utility functions from Kirby (e.g. colors or fonts) you must import the scss utilities:

  @import '~@kirbydesign/designsystem/scss/utils';

To unit-test applications using Kirby's Components, we recommend importing one of the following modules:

• When using jasmine: import { KirbyTestingModule } from '@kirbydesign/designsystem/testing-jasmine';
• When using jest: import { KirbyTestingModule } from '@kirbydesign/designsystem/testing-jest';

Example:

import { KirbyTestingModule } from '@kirbydesign/designsystem/testing-jasmine';

describe('AppComponent', () => {
  beforeEach(async(() => {
    TestBed.configureTestingModule({
      imports: [KirbyTestingModule],
      declarations: [AppComponent]
    }).compileComponents();
  }));

  ...

});

For unit test performance reasons it's highly recommended to utilize these modules, since they provide a template-less implementation of the Kirby Components, but still translude content through <ng-content></ng-content> and provide @Input-decorated properties and @Output-decorated EventEmitters, without having to reflow the DOM, execute component logic etc.

To upgrade, please perform the following tasks:

• v0.x.x => v1.0.0

  Simplified namespaces

  Import @kirbydesign/designsystem instead of @kirbydesign/designsystem/list or @kirbydesign/designsystem/modal. This can be done by executing the following commands (Mac/Linux and Windows respectively):

  Mac / Linux

  cd <root folder of your application>
  find . -name "*.ts" ! -name "*.spec.ts" -type f -exec sed -i '' -e "s|from '@kirbydesign/designsystem/.*';$|from '@kirbydesign/designsystem';|g" {} \;
  find . -name "*.spec.ts" -type f -exec sed -i '' -e "s|from '@kirbydesign/designsystem/testing';$|from '@kirbydesign/designsystem/testing-jasmine';|g" {} \;

  Note: If you're using jest you should replace with @kirbydesign/designsystem/testing-jest instead.

  Windows

  cd <root folder of your application>
  Get-ChildItem "*.ts" -Recurse | ForEach {
  (Get-Content $_ | ForEach  { $_ `
    -replace "from '@kirbydesign/designsystem/((?!testing).)*';$", "from '@kirbydesign/designsystem';" `
    -replace "from '@kirbydesign/designsystem/testing';$", "from '@kirbydesign/designsystem/testing-jasmine';" `
  }) | Set-Content $_
  }

  Note: If you're using jest you should replace with @kirbydesign/designsystem/testing-jest instead.

  Change TypeScript configuration

  Due to Kirby not being distributed as a source-distribution package any more, changes to tsconfig.json, tsconfig.app.json as well as tsconfig.spec.json should be reverted:

  In tsconfig.json:

  • Remove the line "./node_modules/@kirbydesign/designsystem/**/*.ts" from the includes-array

  In tsconfig.app.json:

  • Remove the line "./node_modules/@kirbydesign/designsystem/**/*.ts" from the includes-array
  • Remove the line "../node_modules/@kirbydesign/designsystem/testing/**/*.*" from the excludes-array

  In tsconfig.spec.json:

  • Remove the line "../node_modules/@kirbydesign/designsystem/**/*.ts", from the includes-array

  Changed dependencies

  Remove any previously installed dev-dependencies for sass-extract, sass-extract-loader and ng-mocks (unless otherwise used in your application). This can be done by the following command:

  npm uninstall --save-dev sass-extract sass-extract-loader ng-mocks

  Deprecation

  The following legacy components have been removed:

  • ListItemComponent (<kirby-list-item>)
  • ListFlexItemComponent (<kirby-list-flex-item>)
  • ListCellComponent (<kirby-list-cell>)
  • ListCellLineComponent (<kirby-list-cell-line>)

  The following directives have been deprecated and will be removed in future versions:

  • ListItemDirective ([kirbyListItem])
  • ListFlexItemDirective ([kirbyListFlexItem])

  Please see the list documentation on how to use the list component(s) and directives.

Kirby comes bundled with a default set of icons. Make sure the .svg files used by Kirby are copied to your output folder by adding the following to build > options > assets in angular.json:

{
  ...
  "build": {
    "options": {
      "assets": [
        ...,
        {
          "glob": "**/*.svg",
          "input": "node_modules/@kirbydesign/designsystem/icons/svg",
          "output": "./assets/kirby/icons/svg"
        },
        ...
      ],
    }
  }
}

The folder structure of the repository is based on Nrwl's NX mono-repository project.

A basic walkthrough is outlined in the structure below:

@kirbydesign/designsystem
├── apps                    # Contains source code for applications
|  ├── cookbook             # - Cookbook application (showcase and examples)
|  └── cookbook-e2e         # - End-to-end tests for Cookbook application
├── config
|  └── helm
├── dist                    # Contains output files when building artifacts (for distribution)
|  ├── apps
|  └── libs
├── libs                    # Contains source code for libraries
|  └── designsystem         # - Actual implementation of library (designsystem)
├── scripts                 # Scripts for building artifacts
└── tools                   # Contains various tools
   ├── generate-mocks       # - CLI utility for generating mocks for `@kirbydesign/designsystem/testing-jasmine`
   |                        #   and `@kirbydesign/designsystem/testing-jest` entry points.
   ├── sass-to-ts           # - CLI and Webpack plugin for extract global variables from SASS to TS
   ├── schematics           # - Angular schematics
   └── tslint-rules         # - Custom lintiong rules

Below is an overview of most widely used scripts, available for this project.
Use them in your terminal like: npm run <script>:

When developing new features in the Kirby Designsystem library, please follow the process described below:

TBD

Developing new features should also include that they should be tested.

1. Make sure that the code is unit tested.

2. Make sure that examples and showcases are added for the new features (in the cookbook)

   ... this will also act as documentation for users of the Designsystem library.

3. Test the new features in your own application

   The easiest way to do this is to build a distribution package, and install it in your own project.

   # 1. From the root of this repository, execute (this may take a minute or two):
   ./scripts/publish.js
   
   # Them, from the root of your application, execute:
   <path-to-root-of-designsystem>/dist/kirbydesign-designsystem-<version>.tgz
   
   # ... where <path-to-root-of-designsystem> is replaced with the real path
   #     and <version> is the version of designsystem that was build (in the previous step)
   
   # You do NOT want to commit the changes made to package.json and package-lock.json to your code base!
   

Some features of Kirby requires polyfills to ensure compability across all major browsers (e.g. the ResizeObserverService used by the automagic sizing feature of the Kirby Card component).

To enable the polyfill, you register a polyfill loader that checks whether the polyfill is needed or the feature is already supported by the browser (and can skip requesting the polyfill).
To use the sizing feature of Kirby Card across all major browsers, you must copy additional files from the Kirby package to your output folder.
Add the following to build > options > assets in angular.json:

{
  ...
  "build": {
    "options": {
      "assets": [
        ...,
        {
          "glob": "**/*",
          "input": "./node_modules/@kirbydesign/designsystem/polyfills",
          "output": "./kirby/polyfills"
        },
        ...
      ],
    }
  }
}

Finally, add the following to index.html:

<head>
  ...
  <script src="kirby/polyfills/resize-observer-polyfill-loader.min.js"></script>
</head>

Please note: If you don't want the additional http request for the polyfill loader, you can copy the contents of node_modules/@kirbydesign/designsystem/polyfills/resize-observer-polyfill-loader.js into a script tag in index.html instead

The Kirby chart components use Highcharts. Note that this is a licensed product.