ngx-opalbytes-components

v1.12.0

Published

2 months ago

Uma biblioteca de componentes de UI reutilizáveis para aplicações Angular, projetada para acelerar o desenvolvimento e manter a consistência visual.

0High
0Medium
0Low

micaelmacedo

ngx-opalbytes-components

Uma biblioteca de componentes de UI reutilizáveis para aplicações Angular, projetada para acelerar o desenvolvimento e manter a consistência visual.

Compatibilidade

|Tecnologia | Versão | Descrição | |------------|----------|-------------------------------------| | Angular | ^21.0.0 | Framework principal da biblioteca |

Instalação

Para instalar a biblioteca, execute o seguinte comando:

npm install ngx-opalbytes-components

Dependências

Esta biblioteca possui as seguintes dependências:

`peerDependencies`

| Pacote | Versão | | :----- | :----- | | @angular/common | ^21.0.0 | | @angular/core | ^21.0.0 | | @angular/material | ^21.0.3 |

`dependencies`

| Pacote | Versão | | :----- | :----- | | tslib | ^2.3.0 |

Como Usar

Os componentes nesta biblioteca são standalone, o que significa que você pode importá-los diretamente nos seus componentes ou módulos.

Exemplo de importação em um componente:

import { Component } from '@angular/core';
// Importe os componentes desejados
import { BaseButton, CaoAutocompleteComponent } from 'ngx-opalbytes-components';
import { FormControl, ReactiveFormsModule } from '@angular/forms'; // Adicione ReactiveFormsModule e FormControl

@Component({
  selector: 'app-exemplo',
  standalone: true,
  imports: [
    BaseButton, // Adicione o componente aos imports
    CaoAutocompleteComponent, // Adicione o componente aos imports
    ReactiveFormsModule // Importe ReactiveFormsModule
  ],
  template: `
    <cao-button buttonText="Clique Aqui"></cao-button>
    <cao-autocomplete label="Selecione um Item" [options]="opcoesExemplo" [control]="meuControl"></cao-autocomplete>
  `
})
export class ExemploComponent {
  meuControl = new FormControl();
  opcoesExemplo = [
    { id: 1, nome: 'Opção 1' },
    { id: 2, nome: 'Opção 2' }
  ];
}

Organização de Pastas

Dentro da pasta src/lib/, os componentes são organizados em shared/components/ e cada componente reside em sua própria pasta, contendo seus arquivos (.ts, .html, .css, .spec.ts).

src/
└── lib/
    └── shared/
        └── components/
        |   ├── autocomplete/
        |   ├── base-button/
        |   ├── base-input/
        |   ├── base-time-range/
        |   ├── drop-down/
        |   ├── footer/
        |   ├── links-button/
        |   ├── paginator/
        |   ├── stepper/
        |   └── time-picker/
        └── features/
            ├── base-modal/
            ├── base-table/
            ├── base-table-paginated/
            ├── base-dialog/
            └── base-alert/

Detalhes dos Componentes

`BaseButton`

Um botão customizável com suporte a ícones, estado de loading e tooltip.

Seletor: <cao-button>

Atributos (Inputs)

| Atributo | Tipo | Padrão | Descrição | | --- | --- | --- | --- | | buttonText | string | 'Clique!' | O texto exibido no botão. | | isDarkMode | boolean | false | Aplica o tema escuro ao botão. | | isDisabled | boolean | false | Desabilita o botão. | | isLoading | boolean | false | Exibe um spinner de carregamento no botão. | | btnClass | string | '' | Classes CSS customizadas para o botão. | | tooltip | string | undefined | Texto a ser exibido em uma tooltip. | | trailingIcon | string | undefined | Ícone a ser exibido após o texto. | | leadingIcon | string | undefined | Ícone a ser exibido antes do texto. | | isLucideIcon | boolean | true | Define se o ícone é do pacote Lucide. | | dataCy | string | undefined | Atributo para testes E2E com Cypress. |

Eventos (Outputs)

| Evento | Tipo | Descrição | | --- | --- | --- | | buttonClick | EventEmitter<void> | Emitido quando o botão é clicado. |

`Stepper`

Um componente de passo a passo que guia o usuário através de um processo.

Seletor: <cao-stepper>

Atributos (Inputs)

| Atributo | Tipo | Padrão | Descrição | | -------- | -------- | ------ | ------------------------------------- | | title | string | '' | O título exibido acima do stepper. |

Eventos (Outputs)

| Evento | Tipo | Descrição | | ----------------- | ------------------- | ------------------------------------------------- | | maxReachedEvent | EventEmitter<null> | Emitido quando o último passo do stepper é alcançado. |

Métodos

| Método | Descrição | | -------------- | -------------------------------------------------------------------------------------- | | nextStep() | Avança para o próximo passo. Se estiver no último passo, emite o evento maxReachedEvent. | | prevStep() | Retorna ao passo anterior. Não faz nada se estiver no primeiro passo. | | resetStepper()| Reinicia o stepper, voltando ao primeiro passo e desativando todos os outros. |

Uso com Step

O Stepper deve ser usado em conjunto com o componente Step.

<cao-stepper title="Meu Stepper">
  <cao-step title="1"></cao-step>
  <cao-step title="2"></cao-step>
  <cao-step title="3"></cao-step>
</cao-stepper>

`Step`

Representa um único passo dentro do componente Stepper.

Seletor: <cao-step>

Atributos (Inputs)

| Atributo | Tipo | Padrão | Descrição | | ---------- | --------- | ------- | ----------------------------------------- | | title | string | '' | O texto exibido dentro do passo (ex: "1"). | | isActive | boolean | false | Define se o passo está ativo. |

`BaseInput`

Um campo de entrada de texto customizável com suporte a ícones, máscaras e validação.

Seletor: <cao-input>

Atributos (Inputs)

| Atributo | Tipo | Padrão | Descrição | | --- | --- | --- | --- | | type | string | 'text' | O tipo de input (text, password, email, etc). | | placeholder | string | '' | O texto de placeholder. | | label | string | '' | O rótulo do campo. | | inputClass | string | '' | Classes CSS customizadas para o input. | | value | string | number | boolean | Date | '' | O valor do input. | | errorMessage | string | '' | Mensagem de erro a ser exibida. | | isDisabled | boolean | false | Desabilita o input. | | maxLength | number | undefined | Número máximo de caracteres. | | searchMode | boolean | false | Ativa o modo de busca, exibindo um ícone de busca. | | showBorder | boolean | false | Exibe uma borda no input. | | isLucideIcon | boolean | false | Define se o ícone é do pacote Lucide. | | mask | string | undefined | Máscara a ser aplicada ao input (usando ngx-mask). | | control | AbstractControl | null | null | O FormControl associado. | | tooltip | string | '' | Texto a ser exibido em uma tooltip. | | dataCy | string | undefined | Atributo para testes E2E com Cypress. | | textareaRows | string | undefined | Número de linhas para um textarea. | | decimalMarker | '.' \| ',' \| ['.', ','] | ',' | Marcador decimal para números. | | thousandSeparator | string | '.' | Separador de milhares para números. | | allowNegativeNumbers| boolean| false| Permite números negativos. | | separatorLimit | string | '' | Limite do separador. | | leadingIcon | string | undefined | Ícone a ser exibido antes do texto. | | trailingIcon | string | undefined | Ícone a ser exibido após o texto. |

Eventos (Outputs)

| Evento | Tipo | Descrição | | --- | --- | --- | | valueChange | EventEmitter<string> | Emitido quando o valor do input muda. | | searchClick | EventEmitter<void> | Emitido quando o ícone de busca é clicado. | | inputChange | EventEmitter<string> | Emitido a cada mudança no input. |

`BaseAlert`

Um componente para exibir alertas de sucesso, erro, informação ou aviso. Geralmente utilizado com um serviço de diálogo.

Seletor: <cao-alert>

Atributos (Inputs via data)

| Atributo | Tipo | Descrição | | --- | --- | --- | | type | 'success' \| 'error' \| 'info' \| 'warning' | O tipo de alerta a ser exibido. | | title | string | O título do alerta. | | message | string | A mensagem do alerta. | | alertIcon | string | (Opcional) Caminho para um ícone customizado. |

`AlertService`

O AlertService é responsável por exibir os alertas na tela. Por padrão, ele utiliza o componente BaseAlert.

Como estender o AlertService para usar um componente de alerta customizado:

Para personalizar a aparência ou o comportamento dos alertas, você pode estender o AlertService e sobrescrever o método generateComponentPortal(). Este método deve retornar o seu componente customizado, que DEVE estender o BaseAlert.

Exemplo:

Crie seu componente de alerta customizado (ex: CustomAlertComponent):

// custom-alert.component.ts
import { Component } from '@angular/core';
import { BaseAlert } from 'ngx-opalbytes-components';

@Component({
  selector: 'app-custom-alert',
  template: `
    <div class="custom-alert-container" [ngClass]="data.type">
      <img *ngIf="data.alertIcon" [src]="data.alertIcon" alt="Alert Icon" class="alert-icon">
      <div class="content">
        <h3 class="title">{{ data.title }}</h3>
        <p class="message">{{ data.message }}</p>
      </div>
    </div>
  `,
  styles: [`
    .custom-alert-container {
      /* seus estilos personalizados */
    }
  `]
})
export class CustomAlertComponent extends BaseAlert {
  // Você pode adicionar lógica específica aqui se precisar
}

Crie um serviço que estende o AlertService:

// custom-alert.service.ts
import { Injectable } from '@angular/core';
import { AlertService } from 'ngx-opalbytes-components';
import { CustomAlertComponent } from './custom-alert.component'; // Importe seu componente customizado

@Injectable({
  providedIn: 'root'
})
export class CustomAlertService extends AlertService {
  override generateComponentPortal(): typeof CustomAlertComponent {
    return CustomAlertComponent;
  }
}

`BaseDialog`

Exibe uma caixa de diálogo modal para interações que exigem confirmação do usuário.

Seletor: <cao-dialog>

Atributos (Inputs via config)

| Atributo | Tipo | Descrição | | --- | --- | --- | | type | 'success' \| 'error' \| 'info' \| 'warning' | O tipo de diálogo. | | title | string | O título do diálogo. | | logoIcon | string | (Opcional) Caminho para o ícone do logo. | | message | string | A mensagem principal do diálogo. | | confirmButtonText| string | Texto para o botão de confirmação. | | cancelButtonText | string | Texto para o botão de cancelamento. | | onConfirm | () => void | Função a ser executada na confirmação. | | onCancel | () => void | Função a ser executada no cancelamento. |

Como estender o DialogService para usar um componente de dialoga customizado:

Para personalizar a aparência ou o comportamento dos dialogos, você pode estender o DialogService e sobrescrever o método generateComponentPortal(). Este método deve retornar o seu componente customizado, que DEVE estender o BaseDialog.

Exemplo:

Crie seu componente de dialoga customizado (ex: CustomDialogComponent):

// custom-dialog.component.ts
import { Component } from '@angular/core';
import { BaseDialog } from 'ngx-opalbytes-components';

@Component({
  selector: 'app-custom-dialog',
  template: `
    <div class="custom-dialog-container" [ngClass]="data.type">
      <img *ngIf="data.dialogIcon" [src]="data.dialogIcon" alt="Dialog Icon" class="dialog-icon">
      <div class="content">
        <h3 class="title">{{ data.title }}</h3>
        <p class="message">{{ data.message }}</p>
         @if (config.cancelButtonText) {
          <button
            type="button"
            class="cancel-button"
            [attr.data-cy]="config.cancelButtonText"
            (keydown)="handleCancel()"
            (click)="handleCancel()">
            {{ config.cancelButtonText }}
          </button>
          } @if (config.confirmButtonText) {
          <button
            type="button"
            class="confirm-button"
            [ngClass]="config.type"
            [attr.data-cy]="config.confirmButtonText"
            (click)="handleConfirm()"
            (keydown)="handleConfirm()"
            >
            {{ config.confirmButtonText }}
          </button>
          }
      </div>
    </div>
  `,
  styles: [`
    .custom-dialog-container {
      /* seus estilos personalizados */
    }
  `]
})
export class CustomDialogComponent extends BaseDialog {
  // Você pode adicionar lógica específica aqui se precisar
}

Crie um serviço que estende o DialogService:

// custom-dialog.service.ts
import { Injectable } from '@angular/core';
import { DialogService } from 'ngx-opalbytes-components';
import { CustomDialogComponent } from './custom-dialog.component'; // Importe seu componente customizado

@Injectable({
  providedIn: 'root'
})
export class CustomDialogService extends DialogService {
  override generateComponentPortal(): typeof CustomDialogComponent {
    return CustomDialogComponent;
  }
}

`FeatureBaseModal`

Um componente de modal genérico que pode ser customizado.

Seletor: <cao-feature-base-modal>

Atributos (Inputs)

Um rodapé simples para a aplicação.

Seletor: <cao-footer>

Atributos (Inputs)

Para adicionar um novo componente a esta biblioteca, siga os passos abaixo:

Crie os arquivos do seu componente dentro da pasta src/lib/shared/components/, seguindo a estrutura de pastas existente.
Exponha o componente na API pública da biblioteca, adicionando uma linha de exportação no arquivo src/public-api.ts.
Adicione ou atualize os testes unitários para garantir a cobertura e o funcionamento esperado.
Faça o commit seguindo as regras de commit do projeto, usando o escopo components.
```
git commit -m "feat(components): add new component"
```

Regras e Convenções

Prefixo

O prefixo para componentes nesta biblioteca é cao.

Componentes: Utilize o prefixo <cao-...> nos seletores dos elementos.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

ngx-opalbytes-components

Compatibilidade

Instalação

Dependências

peerDependencies

dependencies

Como Usar

Organização de Pastas

Detalhes dos Componentes

BaseButton

Stepper

Step

BaseInput

BaseAlert

AlertService

BaseDialog

FeatureBaseModal

CaoAutocompleteComponent

BaseTable

BaseTablePaginated

BaseTimeRange

DropDown

Footer

LinksButton

Paginator

TimePicker

Como Contribuir

Regras e Convenções

Prefixo

`peerDependencies`

`dependencies`

`BaseButton`

`Stepper`

`Step`

`BaseInput`

`BaseAlert`

`AlertService`

`BaseDialog`

`FeatureBaseModal`

`BaseTable`

`BaseTimeRange`

`DropDown`

`Footer`

`LinksButton`

`Paginator`

`TimePicker`