amber components

Bernsteinkomponenten

Webkomponenten Implementierung des Amber -Design -Systems.

Dieses Repository richtet sich hauptsächlich an Entwickler und Mitwirkende, um die richtige Dokumentation und den StyleGuide zu erhalten. Weitere Informationen finden Sie unter https://amber.bitrock.it.

Sie können die Komponenten des Live -Storybooks Vorschau anstellen/ausprobieren.

Verwendung

Installieren

$ yarn add @amber-ds/components
--- or ---
$ npm install @amber-ds/components

Optional möchten Sie die Polyfills von Webkomponenten hinzufügen, um frühere Versionen von Firefox und Edge zu unterstützen.

$ yarn add @webcomponents/webcomponentsjs
--- or ---
$ npm install @webcomponents/webcomponentsjs

Projekt hinzufügen

Sie können die Komponenten je nach Umgebung auf unterschiedliche Weise in Ihrem Projekt importieren:

Als JavaScript -Dateien mit einem Bundler (wie WebPack)

 // myfile.js

// import the whole components library
import AmberComponents from '@amber-ds/components' ;

// import a single component (button for instance)
import '@amber-ds/components/button' ,

als JavaScript -Dateien von HTML ohne Bundler

 <!-- mypage.html -->

<!-- import the whole components library -->
< script type =" module " src =" ./node_modules/@amber-ds/components/index.js " > </ script >
<!-- import a single component (button for instance) -->
< script type =" module " src =" ./node_modules/@amber-ds/components/button.js " > </ script >

dann in einer .html -Datei oder einer Vorlagen, die eine HTML -Ausgabe erzeugt:

 <!-- myfile.html -->

< amber-button priority =" primary " >
  Get ready!
< amber-button > 

Entwicklung

Eine kurze Beschreibung der Entwicklungsarchitektur, der Stapel und der Arbeit am Code:

Webcomponenten

Die WebComponents -Spezifikation ist ein Dachbegriff, um die benutzerdefinierten Elemente V1- und Shadow DOM V1 -Spezifikation zu gruppieren. Mit diesen Browser -APIs können Sie W3C -konformen benutzerdefinierten HTML -Tags mit eigenen Funktionen, Scoped -Stilen und Markups schreiben, die in Browsern und Frontend -Frameworks funktionieren.

Typoskript

Um eine bessere Code -Resilienz zu erreichen, werden alle Komponenten in Typenkript geschrieben, um hauptsächlich die statische Überprüfung des Typs und die Syntax der Dekorateure zu nutzen. Es wird auch verwendet, um Code in ES-2015 zu transpilieren.

Basierend auf Lit-HTML & Litelement

Da Webkomponenten als Standard die Rendering-Mechanik und die Datenbindung nicht behandeln, nehmen wir Lit-HTML und seine Litelement für Webkomponenten als Grundlagenschicht für jeden Comoponenten in dieser Bibliothek ein.

Interne Versorgungsunternehmen

• triggerEvent(element, name, ?detail) - Eine Wrapper zum Erstellen eines neuen benutzerdefinierten Ereignisses und zum Versenden mit einem optionalen detail . Blasen ist bereits eingeschaltet.

Fügen Sie eine neue Komponente hinzu

Um schnell die erforderliche (aber minimale) Kesselplatte für eine neue Bernsteinkomponente zu erstellen, haben wir ein kleines CLI -Dienstprogramm aufgenommen:

$ yarn create:component [name]
--- or ---
$ npm run create:component [name]

Dadurch wird ein Unterordner im Ordner ./src/components mit den beiden erforderlichen Starter -Dateien index.ts und style.scss erstellt.

Sie müssen die neue Komponente nur in die Datei ./src/components/library.ts in.

Styling

Sie können index.scss Stile jeder Komponente mithilfe von SASS definieren.

Wenn Sie Styles, Mixins oder was auch immer zwischen Komponenten weitergeben müssen, sollten Sie eine getrennte Datei erstellen und dann dort importieren, wo sie erforderlich sind.

Tests

Im Moment werden nur die Kernbibliotheken ( einfache .ts -Dateien innerhalb des src/libs -Ordners ) über Scherz getestet.

Verfügbare NPM -Aufgaben

Starten Sie das Projekt im Entwicklungsmodus mit einem Live -Reload -Storybook

$ yarn start

Starten Sie das Projekt im Entwicklungsmodus mit einer einfachen HTML -Seite

$ yarn dev

Erstellen Sie im Ordner ./dist ein statisches Storybook -Build

$ yarn build:storybook

Führen Sie die Einheitstests durch

$ yarn test:unit

Verzweigungsrichtlinie

Dieses Projekt folgt einer einfachen Verzweigungsrichtlinie:

• master enthält nur stabilen Code und sollte nicht direkt aktualisiert werden
• development , bei der Evolutive oder experimenteller Code geschrieben wird
• gh-pages , bei denen die auffallenden statischen Storybook-Build-Dateien bereitgestellt werden

Fusionieren Sie nicht direkt development in master ( es ist admin-gesperrt ... ) und senden Sie immer eine PR, um eine Bewertung zu erhalten.

Veröffentlichen Sie eine neue Version

Bevor Sie versuchen, eine neue Version des Pakets auf NPM zu veröffentlichen, führen Sie zuerst diese Checkliste durch:

• Tests vergehen (es ist für PRs erforderlich)
• Die Versionsnummer in der package.json -Datei nach Semver -Richtlinien inkrementieren
• Melden Sie die Änderungen an den Amber-Websit-Dokumenten

Wenn die Veröffentlichung eine neue Komponente enthält:

• Die Versionierung sollte von einer kleinen Version erhöht werden
• Stellen Sie sicher, dass Sie einen neuen Einstiegspunkt webpack.config.js hinzufügen. Dies ist erforderlich
• Stellen Sie /src/components/library.ts
• Fügen Sie den Komponenten -Tag -Namen in das Array /src/elements.ts -Array hinzu. Dies kann in einigen Fällen bei der Kompatibilität von VUE.JS helfen

Wenn eine neue gestoppte Version in den master Zweig gebracht wird, wird die Bereitstellung der Bereitstellung auf NPM ( nach allen automatisierten Schecks ) mithilfe des Bitrock-Admin-Kontos automatisch ausgelöst.

Lizenz

Der Code in diesem Repo und im Amber Design SYTEM -Logo werden vom Bitrock UI Engineering Team verteilt, das unter der MIT -Lizenz veröffentlicht wurde.