diff --git a/.github/actions/bundle-gh-page/action.yml b/.github/actions/bundle-gh-page/action.yml index c78ea260f..587ec98c0 100644 --- a/.github/actions/bundle-gh-page/action.yml +++ b/.github/actions/bundle-gh-page/action.yml @@ -1,3 +1,4 @@ +--- name: 'Bundle GitHub Page' description: 'This action bundles the current gh-page branch with the out folder' inputs: diff --git a/.github/actions/download-tar-artifact/action.yml b/.github/actions/download-tar-artifact/action.yml index d1cc8803a..0ff49ef45 100644 --- a/.github/actions/download-tar-artifact/action.yml +++ b/.github/actions/download-tar-artifact/action.yml @@ -1,3 +1,4 @@ +--- name: 'Download Tar Artifact' description: 'Downloads an artifact and unzips it' inputs: diff --git a/.github/actions/npm-cache/action.yml b/.github/actions/npm-cache/action.yml index 4353f4fdd..8056dba79 100644 --- a/.github/actions/npm-cache/action.yml +++ b/.github/actions/npm-cache/action.yml @@ -1,3 +1,4 @@ +--- name: 'NPM Cache Action' description: 'Initialize NPM Cache' inputs: diff --git a/.github/actions/upload-tar-artifact/action.yml b/.github/actions/upload-tar-artifact/action.yml index f717e6f99..91095d2f2 100644 --- a/.github/actions/upload-tar-artifact/action.yml +++ b/.github/actions/upload-tar-artifact/action.yml @@ -1,3 +1,4 @@ +--- name: 'Upload Tar Artifact' description: 'Upload an artifact and zips it as {name}.tar.gz' inputs: diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 9419b2b53..648f0a2e6 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -1,3 +1,4 @@ +--- version: 2 updates: - package-ecosystem: 'github-actions' diff --git a/.github/labeler.yml b/.github/labeler.yml index 081086a6a..d188b090e 100644 --- a/.github/labeler.yml +++ b/.github/labeler.yml @@ -1,3 +1,4 @@ +--- # Add 'repo' label to any root file changes repo: - '*' diff --git a/.github/workflows/00-init.yml b/.github/workflows/00-init.yml index 574d0b325..f94573054 100644 --- a/.github/workflows/00-init.yml +++ b/.github/workflows/00-init.yml @@ -1,3 +1,4 @@ +--- name: Init Workflow on: diff --git a/.github/workflows/01-build-all.yml b/.github/workflows/01-build-all.yml index 634c69150..34607dade 100644 --- a/.github/workflows/01-build-all.yml +++ b/.github/workflows/01-build-all.yml @@ -1,3 +1,4 @@ +--- name: Build Pages on: diff --git a/.github/workflows/01-build-showcases.yml b/.github/workflows/01-build-showcases.yml index dd70a06a4..34e0bb71d 100644 --- a/.github/workflows/01-build-showcases.yml +++ b/.github/workflows/01-build-showcases.yml @@ -1,3 +1,4 @@ +--- name: Build Showcases on: diff --git a/.github/workflows/01-build-stencil-targets.yml b/.github/workflows/01-build-stencil-targets.yml index 75075770a..8c8556bc9 100644 --- a/.github/workflows/01-build-stencil-targets.yml +++ b/.github/workflows/01-build-stencil-targets.yml @@ -1,3 +1,4 @@ +--- name: Build Stencil Targets on: diff --git a/.github/workflows/01-build-storybook.yml b/.github/workflows/01-build-storybook.yml index 3afd232fd..12ca42ddc 100644 --- a/.github/workflows/01-build-storybook.yml +++ b/.github/workflows/01-build-storybook.yml @@ -1,3 +1,4 @@ +--- name: Build Storybook on: diff --git a/.github/workflows/01-test.yml b/.github/workflows/01-test.yml index 40840375d..77c41e8ee 100644 --- a/.github/workflows/01-test.yml +++ b/.github/workflows/01-test.yml @@ -1,3 +1,4 @@ +--- name: 🔬 Run unit/snapshot tests on: diff --git a/.github/workflows/01-validate.yml b/.github/workflows/01-validate.yml index 52a575319..45d626340 100644 --- a/.github/workflows/01-validate.yml +++ b/.github/workflows/01-validate.yml @@ -1,3 +1,4 @@ +--- name: 🔬 Validate repo on: @@ -19,3 +20,5 @@ jobs: node ./scripts/cypress-component-check.js node ./scripts/angular-module-component-check.js npm run lint:eslint + npm run lint:stylelint + npm run lint:markdownlint diff --git a/.github/workflows/02-cypress.yml b/.github/workflows/02-cypress.yml index 006f51475..2a1ee3463 100644 --- a/.github/workflows/02-cypress.yml +++ b/.github/workflows/02-cypress.yml @@ -1,3 +1,4 @@ +--- name: Run Cypress on repo on: diff --git a/.github/workflows/03-deploy-gh-pages.yml b/.github/workflows/03-deploy-gh-pages.yml index 3b6e8050e..6680f545b 100644 --- a/.github/workflows/03-deploy-gh-pages.yml +++ b/.github/workflows/03-deploy-gh-pages.yml @@ -1,3 +1,4 @@ +--- name: Deploy to gh-pages on: diff --git a/.github/workflows/03-npm-publish.yml b/.github/workflows/03-npm-publish.yml index ad221433f..2a5c5608d 100644 --- a/.github/workflows/03-npm-publish.yml +++ b/.github/workflows/03-npm-publish.yml @@ -1,3 +1,4 @@ +--- name: Publish NPM Repo on: diff --git a/.github/workflows/auto-merge.yml b/.github/workflows/99-auto-merge.yml similarity index 80% rename from .github/workflows/auto-merge.yml rename to .github/workflows/99-auto-merge.yml index 307fb2f8d..aabf2dfde 100644 --- a/.github/workflows/auto-merge.yml +++ b/.github/workflows/99-auto-merge.yml @@ -1,25 +1,24 @@ +--- name: Dependabot auto-merge -on: pull_request - -permissions: - pull-requests: write +on: + workflow_call: jobs: dependabot: runs-on: ubuntu-latest if: ${{ github.actor == 'dependabot[bot]' }} steps: - - name: Dependabot metadata + - name: ⬇ Dependabot metadata id: metadata uses: dependabot/fetch-metadata@v1.3.3 with: github-token: '${{ secrets.GITHUB_TOKEN }}' - - name: Approve a PR + - name: ✔ Approve a PR run: gh pr review --approve "$PR_URL" env: PR_URL: ${{github.event.pull_request.html_url}} GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}} - - name: Enable auto-merge for Dependabot PRs + - name: 🤖 Enable auto-merge for Dependabot PRs if: ${{steps.metadata.outputs.update-type == 'version-update:semver-patch'}} run: gh pr merge --auto --merge "$PR_URL" env: diff --git a/.github/workflows/99-codeql-analysis.yml b/.github/workflows/99-codeql-analysis.yml new file mode 100644 index 000000000..5644b1f85 --- /dev/null +++ b/.github/workflows/99-codeql-analysis.yml @@ -0,0 +1,28 @@ +--- +name: 'CodeQL' +on: + workflow_call: + +jobs: + analyze: + name: Analyze + runs-on: ubuntu-latest + strategy: + fail-fast: false + matrix: + language: ['javascript'] + + steps: + - name: ⬇ Checkout repo + uses: actions/checkout@v3 + + - name: 🔄 Initialize CodeQL + uses: github/codeql-action/init@v2 + with: + languages: ${{ matrix.language }} + + - name: 🔨 Autobuild + uses: github/codeql-action/autobuild@v2 + + - name: 🔎 Perform CodeQL Analysis + uses: github/codeql-action/analyze@v2 diff --git a/.github/workflows/dependency-review.yml b/.github/workflows/99-dependency-review.yml similarity index 59% rename from .github/workflows/dependency-review.yml rename to .github/workflows/99-dependency-review.yml index a25de591b..ead0efb99 100644 --- a/.github/workflows/dependency-review.yml +++ b/.github/workflows/99-dependency-review.yml @@ -1,14 +1,13 @@ +--- name: 'Dependency Review' -on: [pull_request] - -permissions: - contents: read +on: + workflow_call: jobs: dependency-review: runs-on: ubuntu-latest steps: - - name: 'Checkout Repository' + - name: ⬇ Checkout repo uses: actions/checkout@v3 - - name: 'Dependency Review' + - name: 🔎 Dependency Review uses: actions/dependency-review-action@v2 diff --git a/.github/workflows/labeler.yml b/.github/workflows/99-labeler.yml similarity index 60% rename from .github/workflows/labeler.yml rename to .github/workflows/99-labeler.yml index 0406f45dd..f5306e685 100644 --- a/.github/workflows/labeler.yml +++ b/.github/workflows/99-labeler.yml @@ -1,14 +1,14 @@ +--- name: 'Pull Request Labeler' -on: [pull_request] +on: + workflow_call: jobs: triage: - permissions: - contents: read - pull-requests: write runs-on: ubuntu-latest steps: - - uses: actions/labeler@v4 + - name: 🏷️ Labeler + uses: actions/labeler@v4 with: repo-token: '${{ secrets.GITHUB_TOKEN }}' sync-labels: true diff --git a/.github/workflows/cleanup.yml b/.github/workflows/cleanup.yml index f6c7268f0..57c536af8 100644 --- a/.github/workflows/cleanup.yml +++ b/.github/workflows/cleanup.yml @@ -1,10 +1,10 @@ +--- name: Cleans all preview pages for gh-pages on: push: branches: - main - - develop jobs: clean: diff --git a/.github/workflows/codeql-analysis.yml b/.github/workflows/codeql-analysis.yml deleted file mode 100644 index 36f6cacd8..000000000 --- a/.github/workflows/codeql-analysis.yml +++ /dev/null @@ -1,38 +0,0 @@ -name: 'CodeQL' - -on: - push: - branches: ['main'] - pull_request: - branches: ['main'] - schedule: - - cron: '25 18 * * 0' - -jobs: - analyze: - name: Analyze - runs-on: ubuntu-latest - permissions: - actions: read - contents: read - security-events: write - - strategy: - fail-fast: false - matrix: - language: ['javascript'] - - steps: - - name: Checkout repository - uses: actions/checkout@v3 - - - name: Initialize CodeQL - uses: github/codeql-action/init@v2 - with: - languages: ${{ matrix.language }} - - - name: Autobuild - uses: github/codeql-action/autobuild@v1 - - - name: Perform CodeQL Analysis - uses: github/codeql-action/analyze@v2 diff --git a/.github/workflows/default.yml b/.github/workflows/default.yml index 7e74a561a..efb66462c 100644 --- a/.github/workflows/default.yml +++ b/.github/workflows/default.yml @@ -1,4 +1,5 @@ -name: Test and deploy to GitHub Pages +--- +name: Default On-Push on: [push] diff --git a/.github/workflows/pull-request.yml b/.github/workflows/pull-request.yml new file mode 100644 index 000000000..4b152f1c9 --- /dev/null +++ b/.github/workflows/pull-request.yml @@ -0,0 +1,25 @@ +--- +name: Default On-Pull-Request + +on: + pull_request: + branches: ['main'] + +permissions: + pull-requests: write + contents: read + actions: read + security-events: write + +jobs: + dependabot: + uses: ./.github/workflows/99-auto-merge.yml + + codeql: + uses: ./.github/workflows/99-codeql-analysis.yml + + dependency-review: + uses: ./.github/workflows/99-dependency-review.yml + + labeler: + uses: ./.github/workflows/99-labeler.yml diff --git a/.husky/pre-commit b/.husky/pre-commit index a509e923b..177696d99 100755 --- a/.husky/pre-commit +++ b/.husky/pre-commit @@ -5,4 +5,7 @@ npx --yes pretty-quick --staged node ./scripts/cypress-component-check.js node ./scripts/angular-module-component-check.js npm run lint:eslint +npm run lint:stylelint +npm run lint:markdownlint npx validate-branch-name + diff --git a/.markdown-lint.yml b/.markdown-lint.yml new file mode 100644 index 000000000..2ba2578cb --- /dev/null +++ b/.markdown-lint.yml @@ -0,0 +1,37 @@ +--- +########################### +########################### +## Markdown Linter rules ## +########################### +########################### + +# Linter rules doc: +# - https://github.com/DavidAnson/markdownlint +# +# Note: +# To comment out a single error: +# +# any violations you want +# +# + +############### +# Rules by id # +############### +MD004: false # Unordered list style +MD007: + indent: 2 # Unordered list indentation +MD013: + line_length: 500 # Line length 80 is far to short +MD024: false #/no-duplicate-heading/no-duplicate-header +MD026: + punctuation: '.,;:!。，；:' # List of not allowed +MD029: false # Ordered list item prefix +MD033: false # Allow inline HTML +MD036: false # Emphasis used instead of a heading +MD049: false # emphasis-style Emphasis style should be consistent + +################# +# Rules by tags # +################# +blank_lines: false # Error on blank lines diff --git a/.markdownlintignore b/.markdownlintignore new file mode 100644 index 000000000..dd441328f --- /dev/null +++ b/.markdownlintignore @@ -0,0 +1,2 @@ +**/node_modules/** +packages/db-ui-elements-stencil/src/components/** diff --git a/.stylelintrc.json b/.stylelintrc.json new file mode 100644 index 000000000..0714fd04d --- /dev/null +++ b/.stylelintrc.json @@ -0,0 +1,12 @@ +{ + "extends": [ + "stylelint-config-standard-scss", + "stylelint-config-prettier-scss" + ], + "rules": { + "at-rule-no-unknown": null, + "scss/at-rule-no-unknown": true, + "scss/at-extend-no-missing-placeholder": null, + "scss/at-mixin-argumentless-call-parentheses": null + } +} diff --git a/.yamllint b/.yamllint new file mode 100644 index 000000000..ac1de4c48 --- /dev/null +++ b/.yamllint @@ -0,0 +1,6 @@ +extends: default + +rules: + line-length: + max: 120 + level: warning diff --git a/.yamllint.yaml b/.yamllint.yaml index 8d9a7ffab..53c48e4ed 100644 --- a/.yamllint.yaml +++ b/.yamllint.yaml @@ -1,3 +1,4 @@ +--- extends: default ignore: | diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index dd41eaf2e..58d1e9e0c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,3 +1,5 @@ +# Contributing + Thanks for your interest in our project. Contributions are welcome. Feel free to [open an issue](https://github.com/db-ui/elements/issues/new) with questions or reporting ideas and bugs, or [open pull requests](https://github.com/db-ui/elements/compare) to contribute code. We are committed to fostering a welcoming, respectful, and harassment-free environment. Be kind! diff --git a/README.md b/README.md index 34f8b5163..e276f545e 100644 --- a/README.md +++ b/README.md @@ -63,8 +63,11 @@ If you miss a component than [contribute](CONTRIBUTING.md), please. ## Deutsche Bahn brand -As we'd like to perfectly support our users and customers on their digital journey, the usage of Deutsche Bahn brand and trademarks are bound to clear guidelines and restrictions even when being used with the code that we're providing with this product; Deutsche Bahn fully reserves all rights and ownership regarding the Deutsche Bahn brand, even though that we're providing the code of DB UI products free to use and release it under the Apache 2.0 license. -Please have a look at our brand portal at for any further questions and whom to contact on any brand issues. As these assets and visual guidelines are retrieved from our Deutsche Bahn Marketingportal, you'll agree with the ["Allgemeine Nutzungsbedingungen für das DB-Marketingportal" (german)](https://marketingportal.extranet.deutschebahn.com/de/nutzungsbedingungen) in case of using them. +As we'd like to perfectly support our users and customers on their digital journey, the usage of Deutsche Bahn brand and trademarks are bound to clear guidelines and restrictions even when being used with the code that we're providing with this product. +Deutsche Bahn fully reserves all rights and ownership regarding the Deutsche Bahn brand, even though that we're providing the code of DB UI products free to use and release it under the Apache 2.0 license. +Please have a look at our brand portal at for any further questions and whom to contact on any brand issues. + +As these assets and visual guidelines are retrieved from our Deutsche Bahn Marketingportal, you'll agree with the ["Allgemeine Nutzungsbedingungen für das DB-Marketingportal" (german)](https://marketingportal.extranet.deutschebahn.com/de/nutzungsbedingungen) in case of using them. For any usage outside of Deutsche Bahn websites and applications you must remove or replace any Deutsche Bahn brand and design assets as well as protected characteristics and trademarks. We're even also planning to provide a neutral theme that would make it much easier for you to use our product without the trademarks by Deutsche Bahn. diff --git a/doc/adr/README.md b/doc/adr/README.md index f10197926..d010fe6a0 100644 --- a/doc/adr/README.md +++ b/doc/adr/README.md @@ -1,4 +1,4 @@ -## Internal ADRs +# Internal ADRs We've removed totally internal ADRs e.g. regarding tool setups etc. that we either don't want to publish or that are obsolete after publishing to GitHub. diff --git a/doc/adr/TechEval.md b/doc/adr/TechEval.md index e8a553841..d3d541c7e 100644 --- a/doc/adr/TechEval.md +++ b/doc/adr/TechEval.md @@ -11,44 +11,44 @@ ### Technische Eigenschaften * Größe des Bundles pro Element * Explizites Interface: Methoden, Parameter, Events, Style -* In JavaScript keine Seiteneffekte außerhalb der Komponente +* In JavaScript keine Seiteneffekte außerhalb der Komponente * Einzeln testbar * i18n * Accessibility -### Style +### Style * Style für Themes muss von außen der Komponenten kommen * Sonst soll das Style von außen gekappselt sein -sonst ein Subset von https://github.com/webcomponents/gold-standard/wiki +sonst ein Subset von ## Anforderungen aus Entwicklerperspektive (Konsument der DB UI Elements) -* Grundlagen - * Zentral versioniert - * Changelog - * Release Notes - * Installationsanleitung - * Anwendungsprinzipien -* Einfache Konsumierbarkeit - * Standarisierter Komponentenaufruf (living standard) - * Intuitive Anwendung - * Sprechende & einheitliche Attributnamen - * Einheitliche Referenzierung - * Trennung Semantik von Styling (relevanten Tags) / keine Styling relevanten Kompositionen, sondern lediglich logische - * Als Leitmotiv sollten stets bestehende HTML Tag Implementierungen herangezogen werden, da diese eine etablierte und adaptierbare Handhabung bedingen. - * Einfacher Installationsprozess -* Enkapsuliertes Styling - * wg. Vererbung -* Standard-Kompatibilität - * Bei Wrapping nativer Elemente sollten diese nach außen wie nach innen dem Standard folgen in Bezug auf Funktionalität und die APIs - * Living Standards -* Möglichst Framework agnostisch -* Komponenten sind gekapselt ohne Auswirkung nach außen +* Grundlagen + * Zentral versioniert + * Changelog + * Release Notes + * Installationsanleitung + * Anwendungsprinzipien +* Einfache Konsumierbarkeit + * Standarisierter Komponentenaufruf (living standard) + * Intuitive Anwendung + * Sprechende & einheitliche Attributnamen + * Einheitliche Referenzierung + * Trennung Semantik von Styling (relevanten Tags) / keine Styling relevanten Kompositionen, sondern lediglich logische + * Als Leitmotiv sollten stets bestehende HTML Tag Implementierungen herangezogen werden, da diese eine etablierte und adaptierbare Handhabung bedingen. + * Einfacher Installationsprozess +* Enkapsuliertes Styling + * wg. Vererbung +* Standard-Kompatibilität + * Bei Wrapping nativer Elemente sollten diese nach außen wie nach innen dem Standard folgen in Bezug auf Funktionalität und die APIs + * Living Standards +* Möglichst Framework agnostisch +* Komponenten sind gekapselt ohne Auswirkung nach außen Anforderungen aus verschiedenen Domänen -* Unterstützung backendseitiger template-/data-binding Projekte (Java, PHP, Node.js) -* Unterschiedliches Theming verschiedener Geschäftsbereiche -* Governance (Fremdentwicklung & Konzeption mit Designern) -* CSS statt SCSS verwenden +* Unterstützung backendseitiger template-/data-binding Projekte (Java, PHP, Node.js) +* Unterschiedliches Theming verschiedener Geschäftsbereiche +* Governance (Fremdentwicklung & Konzeption mit Designern) +* CSS statt SCSS verwenden diff --git a/doc/adr/adr-01-framework.md b/doc/adr/adr-01-framework.md index a44c1972e..f67858024 100644 --- a/doc/adr/adr-01-framework.md +++ b/doc/adr/adr-01-framework.md @@ -12,16 +12,16 @@ Wir werden Web Components für die UI Library erstellen. Es geht darum, dies möglichst effizient zu tun. Folgende Optionen haben wir uns angeschaut: -- StencilJS (https://stenciljs.com/) +- StencilJS () - Vanila JS -- Polymer (https://www.polymer-project.org/) -- lit-element (https://lit-element.polymer-project.org) +- Polymer () +- lit-element () Web Links -- https://medium.com/@thangman22/stencil-js-vs-lit-element-vs-vanilla-vs-shadow-dom-vs-vue-js-5d2ade971183 -- https://github.com/shprink/web-components-todo -- https://wc-todo.firebaseapp.com/ +- +- +- ## Entscheidung diff --git a/doc/adr/adr-02-styling.md b/doc/adr/adr-02-styling.md index 1c90e1eb6..3a8ff3b6e 100644 --- a/doc/adr/adr-02-styling.md +++ b/doc/adr/adr-02-styling.md @@ -34,7 +34,9 @@ In DB UI Elements gibt es drei Wirkungsbereiche für CSS: - gilt für die Komponente und soll global gesetzt werden. -Mit der unter dem Sammelbegriff "Web Components" eingeführte Technologie "Shadow DOM" lassen sich sowohl reguläre Elemente als auch Custom Elements um einen eingebetteten, abgetrennten DOM erweitern; dieser dient der Abgrenzung von Styles und JavaScript, was dazu führt, dass globale CSS Definitionen und JavaScript Selektionen in der Komponente nicht wirken. Stand heute werden nur CSS-Variablen durch den Shadow DOM durchgelassen. Das Vererben weiterer CSS Deklarationen in den Shadow DOM lässt sich durch weitere CSS Deklarationen verhindern (`:host{all:initial}`). +Mit der unter dem Sammelbegriff "Web Components" eingeführte Technologie "Shadow DOM" lassen sich sowohl reguläre Elemente als auch Custom Elements um einen eingebetteten, abgetrennten DOM erweitern; dieser dient der Abgrenzung von Styles und JavaScript, was dazu führt, dass globale CSS Definitionen und JavaScript Selektionen in der Komponente nicht wirken. + +Stand heute werden nur CSS-Variablen durch den Shadow DOM durchgelassen. Das Vererben weiterer CSS Deklarationen in den Shadow DOM lässt sich durch weitere CSS Deklarationen verhindern (`:host{all:initial}`). Die Herausforderung ist, zu definieren, wie die einzelnen Wirkungsbereiche von CSS technisch umgesetzt werden sollen. diff --git a/doc/adr/adr-03-viewEncapsulation.md b/doc/adr/adr-03-viewEncapsulation.md index 2afcfa884..15d5d1619 100644 --- a/doc/adr/adr-03-viewEncapsulation.md +++ b/doc/adr/adr-03-viewEncapsulation.md @@ -8,9 +8,9 @@ ## Entscheidung und Begründung -Zur Verringerung des Seiteneffektpotentials (Erhöhung der Wartbarkeit) und aus Performance-technischen Gründen sollten Komponenten nach Variante A mit shadow:true deklariert werden. +Zur Verringerung des Seiteneffektpotentials (Erhöhung der Wartbarkeit) und aus Performance-technischen Gründen sollten Komponenten nach Variante A mit shadow:true deklariert werden. -Ausnahme bilden Komponenten, welche native HTML Elemente nachstellen. Komponenten, wie Buttons, Checkboxen oder Inputfelder müssen nach Variante B mit scoped:true deklariert werden, um das native Verhalten des zugehörigen HTML Elements abbilden zu können. +Ausnahme bilden Komponenten, welche native HTML Elemente nachstellen. Komponenten, wie Buttons, Checkboxen oder Inputfelder müssen nach Variante B mit scoped:true deklariert werden, um das native Verhalten des zugehörigen HTML Elements abbilden zu können. ## Problembeschreibung und Kontext @@ -22,7 +22,9 @@ Ist als Default eingestellt. Komponenten ohne ViewEncapsulation haben keinen ein ### ViewEncapsulation mit shadowDom (shadow:true) -Bei Shadow DOM handelt es sich um eine Unterform des standardmäßigen Document Object Models (DOM) und eine der vier elementaren Säulen der 2012 vom W3C-Konsortium standardisierten Web Components. Ein ShadowDOM Komponente wird von gängigen Browsern wie ein gewöhnliches DOM automatisch aus dem HTML-Code generiert, gilt aber nicht für das gesamte Webprojekt. Zudem grenzen Shadow DOMs die enthaltenen Elemente von jeglichen Design- und Strukturierungsvorgaben ab, die projektübergreifend gelten – wie etwa bestimmte CSS-Anweisungen. Vereinfacht gesagt sind Shadow DOMs also eigenständige Code-Kapseln innerhalb eines gewöhnlichen DOMs, die einen eigenen Gültigkeitsbereich besitzen. +Bei Shadow DOM handelt es sich um eine Unterform des standardmäßigen Document Object Models (DOM) und eine der vier elementaren Säulen der 2012 vom W3C-Konsortium standardisierten Web Components. Ein ShadowDOM Komponente wird von gängigen Browsern wie ein gewöhnliches DOM automatisch aus dem HTML-Code generiert, gilt aber nicht für das gesamte Webprojekt. + +Zudem grenzen Shadow DOMs die enthaltenen Elemente von jeglichen Design- und Strukturierungsvorgaben ab, die projektübergreifend gelten – wie etwa bestimmte CSS-Anweisungen. Vereinfacht gesagt sind Shadow DOMs also eigenständige Code-Kapseln innerhalb eines gewöhnlichen DOMs, die einen eigenen Gültigkeitsbereich besitzen. ### ViewEncapsulation mit scoped (scoped:true) @@ -92,7 +94,7 @@ Shadow DOM ist eine im Browser integrierte API, die die DOM-Kapselung und die St #### Buildtime -- einfache Konfiguration durch shadow: true +- einfache Konfiguration durch shadow: true #### Bewertung diff --git a/doc/adr/adr-04-Bundling for patternlab components.md b/doc/adr/adr-04-Bundling for patternlab components.md index d8e2ebdbd..0d7ae0172 100644 --- a/doc/adr/adr-04-Bundling for patternlab components.md +++ b/doc/adr/adr-04-Bundling for patternlab components.md @@ -13,14 +13,14 @@ Im Moment haben wir keinen Bedarf für komplexe Komponenten in Pattern Lab und somit können wir mit den Nachteilen gut leben. Soll sich der Bedarf Richtung konplexerer Komponenten für Pattern Lab ändern, -müssen wir diese Entscheidung nochmal betrachten. +müssen wir diese Entscheidung nochmal betrachten. ## Problembeschreibung und Kontext Neben den DB-UI Elements Komponenten, die als Lib consumiert werden sollen, gibt es Bedarf für Komponenten um das Pattern Lab (Storybook) zu erweitern. -Nutzt man für Pattern Lab Komponenten Stencil, dann werden diese auch im npm-Paket +Nutzt man für Pattern Lab Komponenten Stencil, dann werden diese auch im npm-Paket mitveröffentlicht, so dass die Consumenten unnötig ihre Apps größer machen müssen. ## Rahmenbedingungen und Entscheidungskriterien @@ -38,14 +38,14 @@ Einfach Verständlich * Ausnahmen zum Vorgehen der Frameworks müssen gut dokumentiert sein -* Keine bzw. nur die nötigste Logik in Storybook Dateien +* Keine bzw. nur die nötigste Logik in Storybook Dateien ## Alternativen ### A - zwei Konfigurationen -In der /tsconfig.json kann man Ordner aus der Build excludieren. +In der /tsconfig.json kann man Ordner aus der Build excludieren. Die Komponenten dort werden dann nicht verarbeitet und landen somit nicht im *dist* ```javascript @@ -56,11 +56,11 @@ Die Komponenten dort werden dann nicht verarbeitet und landen somit nicht im *di ``` Damit die Pattern Lab Komponenten in Storybook benutzt werden können, müssen diese allerdings gebaut werden. -Ansatz hier ist zwei Konfigurationen: eine für Pattern Lab und eine für *npm publish* +Ansatz hier ist zwei Konfigurationen: eine für Pattern Lab und eine für *npm publish* #### Bewertung -Im Moment die einzige Möglichkeit in Stencil die Komponenten aus *dist* zu entfernen. +Im Moment die einzige Möglichkeit in Stencil die Komponenten aus *dist* zu entfernen. Der Nachteil ist die höhere Komplexität in der CI/CD Pipeline in der wir heute am wenigsten Know How haben. ### B - Bundles @@ -74,14 +74,14 @@ In der */stencil.config.ts* ist es möglich mehrere Komponenten in ein Bundle zu ], ``` -Man würde alle Pattern Lab Komponenten in ein Bundle platzieren und somit die Vermischung zwischen -Pattern Lab und DB-UI Komponenten reduzieren. +Man würde alle Pattern Lab Komponenten in ein Bundle platzieren und somit die Vermischung zwischen +Pattern Lab und DB-UI Komponenten reduzieren. #### Bewertung Problem: in */dist/db-ui-elements/de-ui-elements.esm.js* werden alle Module referenziert. -Somit würden die Consumenten, die *{ defineCustomElements } from '../dist/esm/loader'* nutzen -auch Pattern Lab Komponenten in ihrer App definieren. +Somit würden die Consumenten, die *{ defineCustomElements } from '../dist/esm/loader'* nutzen +auch Pattern Lab Komponenten in ihrer App definieren. ### C - Anderes Templating Mechanismus @@ -122,14 +122,14 @@ export const ColorsList = (args) => { #### Bewertung -* MDX ist verbreitet https://mdxjs.com/ +* MDX ist verbreitet * MDX setzt die Kenntnis von React und MD voraus * VS Code unterstützt kein Intellisence für MDX * MDX muss um React Code erweitert werden um asynchrone Features (z.B. Änderung der Themes) zu nutzen. ### E - Eigenes Repo für Pattern Lab/Styleguide -Pattern Lab und die dazu gehörigen Komponenten aus DB-UI Elements rausnehmen und in ein eigenes Repository +Pattern Lab und die dazu gehörigen Komponenten aus DB-UI Elements rausnehmen und in ein eigenes Repository umziehen. Dort DB-UI Elements importieren. Auch ein Monorepo Ansatz ist denkbar diff --git a/doc/adr/adr-06-e2e Puppeteer Cypress.md b/doc/adr/adr-06-e2e Puppeteer Cypress.md index fdda547a9..3e85ec6b8 100644 --- a/doc/adr/adr-06-e2e Puppeteer Cypress.md +++ b/doc/adr/adr-06-e2e Puppeteer Cypress.md @@ -42,5 +42,5 @@ Bei `stecil generate` sollten e2e Tests nicht ausgewählt werden. Dafür muss ma ## Links -- https://www.cypress.io/ -- https://github.com/buildkite/docker-puppeteer \ No newline at end of file +- +- \ No newline at end of file diff --git a/doc/howto-angular.md b/doc/howto-angular.md index b58e92882..29a8a9c33 100644 --- a/doc/howto-angular.md +++ b/doc/howto-angular.md @@ -9,7 +9,7 @@ You are an Application Developer and you want to use DB UI Elements in your own [Read the "How to Start" documentation](https://github.com/db-ui/elements/-/blob/main/doc/howto-start.md). -### Integrate in your app +### Integrate in your app 1. Import the DB UI Elements Angular library into your `app.modules.ts` file: @@ -76,7 +76,7 @@ Maybe if this doesn't solve your problem, you could try to add ``"preserveSymlin Inside your ``angular.json`` file you have a "build" step. Under "options" you need to add your style like this: -``` +```json "options":{ ... "assets": [ diff --git a/doc/howto-build.md b/doc/howto-build.md index 947b7d327..c8fe24c20 100644 --- a/doc/howto-build.md +++ b/doc/howto-build.md @@ -1,4 +1,4 @@ -## Typical developer flow +# Typical developer flow ```bash npm ci @@ -11,20 +11,20 @@ npm start ``` -# How to build +## How to build DB-UI Elements provides two artifacts: lib and living styleguide. Styleguide requires lib to be built. -## How to add a new component +## How to add a new component ```bash npm run generate new-component ``` To see your new component in storybook create a "stories" folder in the new component folder and create a db-test.intro.stories.mdx file with the following content. Adapt the file name to your component name and in the file adapt as well as in the tag the /Test/ part - "Test" is the second part of your new component. -``` +```typescript import { Meta, Canvas } from '@storybook/addon-docs'; import Readme from './../readme.md'; diff --git a/doc/howto-javascript.md b/doc/howto-javascript.md index a3a46581a..72bdb5b4c 100644 --- a/doc/howto-javascript.md +++ b/doc/howto-javascript.md @@ -11,7 +11,7 @@ Maybe there is a good reason for you, why you don't use a framework. Maybe you a [Read the "How to Start" documentation](https://github.com/db-ui/elements/-/blob/main/doc/howto-start.md). -### Integrate web components in your app +### Integrate web components in your app After installation is done, you have to integrate DB UI Elements into your application. @@ -37,7 +37,7 @@ There are two steps you need to get the styles in your application. First copy a For your copy use the folder below and copy it in your assets folder: -``` +```json { src: 'node_modules/@db-ui/core/dist/fonts', dest: 'fonts' @@ -66,7 +66,7 @@ dest: 'static/css/db-ui-core.vars.css' and for your import use the vars file: -``` +```html ``` @@ -76,7 +76,7 @@ Events and event handlers are an important link between HTML and JavaScript. A c Use **this.value** to process the expected value. -``` +```html ``` diff --git a/doc/howto-learn.md b/doc/howto-learn.md index 10e5b673d..493c4cb6b 100644 --- a/doc/howto-learn.md +++ b/doc/howto-learn.md @@ -9,7 +9,7 @@ These ressources we used to learn and get inspired for DB UI Elements ## Stencil -- https://github.com/mappmechanic/awesome-stenciljs#component-libraries - Great Overview +- - Great Overview for stencil Products ## Storybook @@ -30,9 +30,9 @@ These ressources we used to learn and get inspired for DB UI Elements - [Extensive overview on Design Systems](https://designsystemsrepo.com/design-systems/) - [Extensive collection of Design Systems searchable by element](https://www.uiguideline.com/) -- https://www.duetds.com/ - (Stencil) -- https://github.com/telekom/scale - (Stencil) -- https://github.com/BlazeSoftware/atoms - (Stencil) +- - (Stencil) +- - (Stencil) +- - (Stencil) ### Blaze diff --git a/doc/howto-react.md b/doc/howto-react.md index 1454ed5d0..ce2125e9a 100644 --- a/doc/howto-react.md +++ b/doc/howto-react.md @@ -9,7 +9,7 @@ You are an Application Developer and you want to use DB UI Elements in your own [Read the "How to Start" documentation](https://github.com/db-ui/elements/-/blob/main/doc/howto-start.md). -### Integrate in your app +### Integrate in your app You can use db-ui-element components like default React components. Import your component like this: @@ -21,7 +21,7 @@ import { DbButton } from "@db-ui/react-elements-enterprise"; | WARNING: Some components require fonts and/or icons to work properly | | --- | You can import fonts and icons with the provided css file from DB UI Core: - + ``import "@db-ui/core/dist/css/db-ui-core.vars.css"`` Import this css before you use components. For example you could import it inside your `App.ts` file. @@ -29,7 +29,7 @@ Import this css before you use components. For example you could import it insid ### Bundle your App 1. Create 3 folders in you public directory: -```` +````shell mkdir public/fonts mkdir public/icons mkdir public/images @@ -38,7 +38,7 @@ mkdir public/js 2. Add a new ``prebuild`` script to your `package.json` like this: -``` +```json "prebuild": "npx -y shx cp node_modules/@db-ui/core/dist/fonts/* public/fonts & npx -y shx cp node_modules/@db-ui/core/dist/images/* public/images & npx -y shx cp node_modules/@db-ui/core/dist/js/* public/js & npx -y shx cp node_modules/@db-ui/core/dist/icons/* public/icons", ``` diff --git a/doc/howto-style.md b/doc/howto-style.md index 8c35cfa85..3232a0fb5 100644 --- a/doc/howto-style.md +++ b/doc/howto-style.md @@ -7,25 +7,25 @@ This is a guide to how styling works for DB UI Elements. At the Deutsche Bahn there is a [standard for UI/UX](https://marketingportal.extranet.deutschebahn.com/de/ui-komponenten). Every tenant (like: Fernverkehr, Regio, Enterprise) can variate the style at predefined parts. -DB UI Elements is intended to provide components for all Deutsche Bahn tenants. +DB UI Elements is intended to provide components for all Deutsche Bahn tenants. Currently we focus on "enterprise" and "fernverkehr" style. ## Big picture -The standardization process is ongoing and will continue. +The standardization process is ongoing and will continue. Today we do not know which parts of the style should be customizable by tenants. In order to keep the implementation of the components stable we [decided](./adr/adr-02-styling.md) to separate style definition from the implementation. The style and its life-cycle is handled by DB UI Core, which provides the necessary pattern partials. DB UI Elements uses the fix part at build time inside the web components. -This part of the style can't be changed from outside. +This part of the style can't be changed from outside. The customizable part is used by applications in order to overwrite the style. -Every tenant has its own predefined values for these css variables, +Every tenant has its own predefined values for these css variables, which are also provided by DB UI Core and DB UI Base. The application combines the web components with tenant relevant css variables -in order to get styled components. +in order to get styled components. Mostly an app belongs to a single tenant, but technically it is possible to exchange the style at runtime easily. @@ -34,7 +34,7 @@ In the following is the overview on how style is implemented from definition dow // TODO ## Style defintion format -Web components are closed for style changes from outside. +Web components are closed for style changes from outside. The only way to set style externally is using css custom properties (css variables). For every customizable style definition there is a css variable in **root**: scope. @@ -59,12 +59,12 @@ For instance for button are following css variables relevant: --button-secondary-hover-backgroundColor: #282d37; ``` -DB UI Core and DB UI Base provide for every tenant the list of all css variables with +DB UI Core and DB UI Base provide for every tenant the list of all css variables with tenant specific values. -Our strategy in DB UI Elements is to keep the overhead for components as low as possible. -So, every component is a standalone module. The consumer app can pick the relevant -components with the relevant style. You can find the relevant style imports in API doc of +Our strategy in DB UI Elements is to keep the overhead for components as low as possible. +So, every component is a standalone module. The consumer app can pick the relevant +components with the relevant style. You can find the relevant style imports in API doc of each component. ### CSS Variables / CSS Custom Properties @@ -88,7 +88,7 @@ e.g. The customizable part for style is provided by DB UI Core. -``` +```shell /node_modules/@db-ui/core/dist/css/{theme} ``` @@ -110,15 +110,15 @@ If you need to change it, then make a change request for DB UI Elements. The customizable part of style can be changed by overwriting the corresponding css variable in your app css. -Please keep in mind, that then the style is probably not compliant -with tenant style guidelines. +Please keep in mind, that then the style is probably not compliant +with tenant style guidelines. For permanent change make a change request for DB UI Elements. ### Not resetting inheritable styles `Inheritable styles (background, color, font, line-height, etc.) continue to inherit in shadow DOM. That is, they pierce the shadow DOM boundary by default. If you want to start with a fresh slate, use all: initial; to reset inheritable styles to their initial value when they cross the shadow boundary.` -compare to https://developers.google.com/web/fundamentals/web-components/shadowdom#reset, https://stackoverflow.com/a/49709787 and https://stackoverflow.com/a/49709787 +compare to , and We've decided against resetting inheritable styles by default, as we're expecting to be in a controlled and/or DB ecosystem most of the times, and would have a bigger benefit from inheritance (like e.g. simpler/less code/declarations) than experiencing any heavier collisions/incompatibilities. -Consolidated lists of CSS properties that are inherited by default: https://gist.github.com/dcneiner/1137601 \ No newline at end of file +Consolidated lists of CSS properties that are inherited by default: \ No newline at end of file diff --git a/doc/howto-update.md b/doc/howto-update.md index 5d2c9cad6..925586c20 100644 --- a/doc/howto-update.md +++ b/doc/howto-update.md @@ -1,10 +1,10 @@ -## Update as Application Developer +# Update as Application Developer -### Purpose +## Purpose You are an Application Developer and you want to update DB UI Elements in your own application. -### Update +## Update If you like to update DB UI Elements use: @@ -17,6 +17,6 @@ Please have a look at the [CHANGELOG.md](https://github.com/db-ui/elements/-/blo DB UI Elements follows the [semantic version](https://semver.org/lang/de/) logic. You can add a **^** before the version in package.json in order to get minor and fixes releases on **npm update**. -### Documentation +## Documentation Please find our Architectural Decision Records within the [adr subfolder](https://github.com/db-ui/elements/-/tree/main/doc/adr). diff --git a/doc/howto-vue.md b/doc/howto-vue.md index 5e5e15192..bd6cce8a3 100644 --- a/doc/howto-vue.md +++ b/doc/howto-vue.md @@ -9,7 +9,7 @@ You are an Application Developer and you want to use DB UI Elements in your own [Read the "How to Start" documentation](https://github.com/db-ui/elements/-/blob/main/doc/howto-start.md). -### Integrate in your app +### Integrate in your app Import a db-ui-elements component into a vue component (*.vue) like this: @@ -26,7 +26,7 @@ import { | WARNING: Some components require fonts and/or icons to work properly | | --- | You can import fonts and icons with the provided css file from DB UI Core: - + ``import "@db-ui/core/dist/css/db-ui-core.vars.css"`` Import this css before you use components. For example you could import it inside your ``main.ts`` file. @@ -64,7 +64,7 @@ In order to test the installation just add a component to your ``