amber components

componentes âmbar

Componentes da Web Implementação do sistema de design âmbar.

Este repositório tem como objetivo principalmente desenvolvedores e colaboradores, para a documentação e o StyleGuide adequados, consulte https://amber.bitrock.it.

Você pode visualizar/experimentar os componentes no livro de histórias ao vivo.

Uso

Instalar

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

Opcionalmente, convém adicionar os polifilos dos componentes da Web para suportar versões anteriores do Firefox e Edge.

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

Adicionar no projeto

Você pode importar os componentes do seu projeto de maneira diferente, dependendo do meio ambiente:

como arquivos JavaScript com um empacotador (como 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' ,

como arquivos javascript de html sem um empacotador

 <!-- 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 >

Em seguida, em um arquivo .html , ou em um modelo que produz uma saída HTML:

 <!-- myfile.html -->

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

Desenvolvimento

Uma breve descrição da arquitetura de desenvolvimento, pilha e como trabalhar no código:

WebComponents

A especificação do WebComponents é um termo guarda -chuva para agrupar a especificação de elementos personalizados V1 e Shadow DOM V1. Essas APIs do navegador permitem escrever tags HTML personalizadas compatíveis com o W3C com suas próprias funcionalidades, estilos de escopo e marcação que funcionam entre navegadores e estruturas de front -end.

TypeScript

Para obter uma melhor resiliência de código, todos os componentes são escritos no TypeScript para aproveitar principalmente a verificação do tipo estático e a sintaxe dos decoradores. Também é usado para transpilar código para ES-2015.

Baseado em lit-html e litelement

Como os componentes da Web como padrão não lidam com a mecânica de renderização e a ligação de dados, estamos adotando o LIT-HTML e sua classe de componentes da Web como uma camada de fundação para todos os comoponentes dessa biblioteca.

Utilitários internos

• triggerEvent(element, name, ?detail) - Um invólucro para criar um novo evento personalizado e despachar -o com um objeto detail opcional. Bubling já está ligado.

Adicione um novo componente

Para criar rapidamente o calderplate necessário (mas mínimo) para um novo componente âmbar, incluímos um pequeno utilitário da CLI:

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

Isso criará uma subpasta na pasta ./src/components components com os dois arquivos de partida necessários index.ts e style.scss .

Você precisará importar apenas o novo componente dentro do arquivo ./src/components/library.ts para acioná -lo no processo de desenvolvimento e construção.

Estilo

Você pode definir os estilos de cada componente usando SASS, o arquivo principal index.scss na pasta do componente é processado pelo compilador e depois é injetado no DOM da sombra.

Se você precisar compartilhar estilos, mixins ou qualquer outra coisa entre os componentes, você deve criar um arquivo separado e importá -lo onde forem necessários.

Testes

No momento, apenas as bibliotecas principais ( arquivos .ts simples na pasta src/libs ) estão sendo testados via JEST.

Tarefas NPM disponíveis

Inicie o projeto no modo de desenvolvimento com um livro de histórias de recarga ao vivo

$ yarn start

Inicie o projeto no modo de desenvolvimento com uma página simples HTML

$ yarn dev

Crie um livro de histórias estático construído na pasta ./dist

$ yarn build:storybook

Execute os testes de unidade

$ yarn test:unit

Política de ramificação

Este projeto segue uma política de ramificação simples:

• master contém apenas código estável e não deve ser atualizado diretamente
• development onde o código evolução ou experimental é escrito
• gh-pages , onde os arquivos de construção de histórias estáticas distubutáveis são implantadas

Não se development diretamente no master ( está bloqueado pelo administrador ... ), sempre envie um PR para ter uma revisão.

Publique uma nova versão

Antes de tentar publicar uma nova versão do pacote no NPM, passe pela primeira vez nesta lista de verificação:

• Testes passes (é necessário para o PRS)
• Número da versão incremental no arquivo package.json seguindo as diretrizes semver
• Relate as alterações nos documentos âmbar-website

Se o lançamento incluir um novo componente :

• A versão deve ser incrementada por uma versão menor
• Certifique -se de adicionar um novo ponto de entrada webpack.config.js , isso é necessário para criar o módulo independente
• Certifique -se de importar o componente e adicione -o nos arquivos /src/components/library.ts , dessa maneira ele estará acessível quando o usuário importar toda a biblioteca
• Adicione a etiqueta do componente Nomeie -a na matriz /src/elements.ts , isso pode ajudar com a compatibilidade do Vue.js em alguns casos

Quando uma nova versão buminada é empurrada para a filial master , ele aciona automaticamente a implantação no NPM ( depois de todas as verificações automatizadas ) usando a conta Bitrock-Admin.

Licença

O código neste repositório e o logotipo do Amber Design Sytem são distribuídos pela equipe de engenharia da interface do usuário do Bitrock, lançada sob a licença do MIT.