ngx-opalbytes-components 1.28.0 → 1.30.0

package/README.md

@@ -234,17 +234,21 @@ src/
         └── components/
         |   ├── accordion/
         |   ├── accordion-item/
+        |   ├── avatar/
         |   ├── base-button/
         |   ├── base-icon/
         |   ├── base-input/
         |   ├── base-time-range/
         |   ├── base-toggle/
+        |   ├── breadcrumb/
         |   ├── checkbox/
         |   ├── drop-down/
         |   ├── footer/
         |   ├── kpi/
         |   ├── links-button/
         |   ├── paginator/
+        |   ├── progress-bar/
+        |   ├── progress-spinner/
         |   ├── radio/
         |   ├── skeleton/
         |   ├── slide-toggle/
@@ -930,6 +934,61 @@ Um componente de alternância (toggle switch) que funciona com `ngModel` ou `for
 | `inputChange` | `EventEmitter<string>` | Emitido a cada mudança no input. |
 | `statusChanged` | `EventEmitter<CaoBaseToggleComponent>` | Emitido quando o toggle é alternado. |
 
+---
+
+### `CaoBreadcrumbComponent`
+ 
+Trilha de navegação (breadcrumb) com ícones Lucide ou imagem, link de navegação, badge e divisor customizável.
+ 
+**Seletor:** `<cao-breadcrumb>`
+ 
+**Interface `ICaoBreadcrumbItem`**
+ 
+| Propriedade | Tipo | Padrão | Descrição |
+| --- | --- | --- | --- |
+| `label` | `string` | — | Texto do item. |
+| `icon` | `string` | — | Nome do ícone Lucide ou URL/caminho/data URI de imagem. |
+| `isLucideIcon` | `boolean` | `true` | Define se `icon` é Lucide. |
+| `iconPosition` | `'left' \| 'right'` | `'left'` | Direção do ícone em relação ao texto. |
+| `iconColor` / `iconSize` / `iconStrokeWidth` | `string` / `number` / `number` | — / `16` / `1.5` | Aparência do ícone. |
+| `link` | `string \| unknown[]` | — | Navegação interna (`routerLink`). |
+| `queryParams` | `Params` | — | Query params do `link`. |
+| `href` / `target` | `string` / `'_self' \| '_blank' ...` | — | Navegação externa. |
+| `command` | `(e: ICaoBreadcrumbItemClickEvent) => void` | — | Callback de clique (sem `link`/`href` vira `<button>`). |
+| `badge` / `badgeColor` / `badgeBgColor` | `string \| number` / `string` / `string` | — | Badge do item. |
+| `disabled` | `boolean` | `false` | Desabilita o item. |
+| `ariaLabel` / `dataCy` | `string` | — | Acessibilidade e testes E2E. |
+ 
+**Atributos (Inputs)**
+ 
+| Atributo | Tipo | Padrão | Descrição |
+| --- | --- | --- | --- |
+| `items` | `ICaoBreadcrumbItem[]` | `[]` | Itens; o último é a página atual (`aria-current="page"`). |
+| `home` | `ICaoBreadcrumbItem` | `undefined` | Item inicial opcional. |
+| `separator` | `string` | `'/'` | Texto do divisor. |
+| `separatorIcon` | `string` | `''` | Ícone do divisor (sobrepõe `separator`). |
+| `isLucideSeparatorIcon` | `boolean` | `true` | Define se `separatorIcon` é Lucide. |
+| `separatorIconSize` / `separatorIconStrokeWidth` | `number` | `14` / `1.5` | Aparência do ícone divisor. |
+| `linkColor`, `linkHoverColor`, `currentColor`, `separatorColor`, `fontSize`, `gap` | `string` | `''` | Atalhos para as CSS custom properties. |
+| `ariaLabel` | `string` | `'Breadcrumb'` | `aria-label` do `<nav>`. |
+| `dataCy` | `string` | `''` | Atributo para testes E2E. |
+ 
+**Eventos (Outputs):** `itemClick` → `ICaoBreadcrumbItemClickEvent` (`item`, `index`, `originalEvent`).
+ 
+**CSS Custom Properties:** `--cao-breadcrumb-link-color` (`#6b7280`), `--cao-breadcrumb-link-hover-color` (`#4f46e5`), `--cao-breadcrumb-current-color` (`#111827`), `--cao-breadcrumb-separator-color` (`#9ca3af`), `--cao-breadcrumb-disabled-color`, `--cao-breadcrumb-focus-ring`, `--cao-breadcrumb-badge-bg`, `--cao-breadcrumb-badge-text`, `--cao-breadcrumb-gap` (`8px`), `--cao-breadcrumb-font-size` (`0.875rem`).
+ 
+```html
+<cao-breadcrumb
+  [home]="{ icon: 'house', ariaLabel: 'Início', link: '/' }"
+  [items]="[
+    { label: 'Pedidos', icon: 'package', iconPosition: 'right', link: '/pedidos', badge: 12 },
+    { label: 'Pedido #42' }
+  ]"
+  separatorIcon="chevron-right" />
+```
+ 
+> Depende de `BaseIcon` (copie junto ao usar `cao-comp`) e de `@angular/router`.
+
 ---
 ### `CaoAccordionComponent` e `CaoAccordionItemComponent`
 
@@ -1130,7 +1189,110 @@ export class FaqComponent {}
 - Fora de um `<cao-accordion>`, o item se comporta como um cartão expansível independente.
 
 ---
+### `CaoAvatarComponent`
+
+Avatar para representar usuários ou entidades, com imagem, ícone (Lucide ou imagem) ou texto (iniciais). Possui imagem padrão embutida, usada enquanto nenhuma fonte for informada ou quando a imagem falha ao carregar. Tamanho, formato e contorno (stroke) são configuráveis.
+
+**Seletor:** `<cao-avatar>`
+
+**Tipos**
+
+| Tipo | Valores |
+| --- | --- |
+| `CaoAvatarPresetSize` | `'small'` (24px) \| `'normal'` (32px) \| `'large'` (48px) \| `'xlarge'` (64px) |
+| `CaoAvatarShape` | `'circle'` \| `'rounded'` \| `'square'` |
+| `CaoAvatarStrokeStyle` | `'solid'` \| `'dashed'` \| `'dotted'` \| `'double'` |
+
+**Atributos (Inputs)**
+
+| Atributo | Tipo | Padrão | Descrição |
+| --- | --- | --- | --- |
+| `src` | `string \| null \| undefined` | `''` | URL da imagem. Se vazia ou se falhar ao carregar, o avatar usa `icon`, `label` ou a imagem padrão (nessa ordem). |
+| `defaultSrc` | `string` | `''` | Imagem padrão customizada. Se vazia, usa a silhueta embutida (`CAO_AVATAR_DEFAULT_SRC`). |
+| `label` | `string` | `''` | Texto exibido (ex.: iniciais) quando não há imagem nem ícone. |
+| `icon` | `string` | `''` | Nome do ícone Lucide ou caminho/URL de imagem usada como ícone. |
+| `isLucideIcon` | `boolean` | `true` | Define se `icon` é um ícone Lucide. |
+| `iconColor` | `string` | `''` | Cor do ícone Lucide. Se vazia, usa `textColor`. |
+| `size` | `CaoAvatarPresetSize \| number \| string` | `'normal'` | Tamanho predefinido, número em px ou texto (`'72px'`, `'4.5rem'`). Valores inválidos voltam para `'normal'`. |
+| `shape` | `CaoAvatarShape` | `'circle'` | Formato do avatar. |
+| `strokeWidth` | `number \| string` | `0` | Espessura do contorno. Número é convertido para `px`; `0` remove o contorno. |
+| `strokeColor` | `string` | `'#ffffff'` | Cor do contorno. |
+| `strokeStyle` | `CaoAvatarStrokeStyle` | `'solid'` | Estilo do contorno. |
+| `bgColor` | `string` | `''` | Cor de fundo (sobrescreve `--cao-avatar-bg`). |
+| `textColor` | `string` | `''` | Cor do texto/ícone (sobrescreve `--cao-avatar-text`). |
+| `alt` | `string` | `''` | Texto alternativo do avatar. |
+| `ariaLabel` | `string` | `''` | `aria-label` do avatar. Prioridade: `ariaLabel` → `alt` → `label` → `'Avatar'`. |
+| `dataCy` | `string` | `''` | Atributo para testes E2E com Cypress. |
+
+**Ordem de exibição**
+
+1. `src` (se informado e carregado com sucesso);
+2. `icon`;
+3. `label`;
+4. imagem padrão (`defaultSrc` ou a silhueta embutida).
+
+Se o `src` falhar ao carregar (erro 404, URL inválida etc.), o componente passa automaticamente para o próximo item da lista.
+
+**Constantes exportadas**
+
+| Constante | Descrição |
+| --- | --- |
+| `CAO_AVATAR_DEFAULT_SRC` | Data URI da imagem padrão (silhueta em SVG, funciona offline). |
+| `CAO_AVATAR_SIZES` | Mapa dos tamanhos predefinidos em px (`small`, `normal`, `large`, `xlarge`). |
 
+**CSS Custom Properties**
+
+| Propriedade | Padrão | Descrição |
+| --- | --- | --- |
+| `--cao-avatar-bg` | `#e5e7eb` | Cor de fundo. |
+| `--cao-avatar-text` | `#374151` | Cor do texto/ícone. |
+| `--cao-avatar-radius` | `25%` | Raio da borda no formato `rounded`. |
+
+**Exemplo básico:**
+
+```html
+<!-- Sem src: exibe a imagem padrão -->
+<cao-avatar></cao-avatar>
+
+<!-- Com imagem -->
+<cao-avatar src="https://exemplo.com/foto.png" alt="Foto de Maria" size="large"></cao-avatar>
+
+<!-- Com iniciais -->
+<cao-avatar label="MB" bgColor="#eef2ff" textColor="#4338ca"></cao-avatar>
+
+<!-- Com ícone Lucide -->
+<cao-avatar icon="user" bgColor="#dcfce7" iconColor="#166534"></cao-avatar>
+```
+
+**Exemplo com tamanho, formato e contorno:**
+
+```html
+<cao-avatar src="assets/foto.png" size="xlarge" shape="rounded"></cao-avatar>
+<cao-avatar src="assets/foto.png" [size]="96" shape="square"></cao-avatar>
+<cao-avatar src="assets/foto.png" size="7rem"></cao-avatar>
+
+<cao-avatar
+  src="assets/foto.png"
+  size="xlarge"
+  [strokeWidth]="3"
+  strokeColor="#4f46e5"
+  strokeStyle="dashed">
+</cao-avatar>
+```
+
+**Exemplo com imagem padrão customizada:**
+
+```html
+<cao-avatar [src]="usuario.foto" defaultSrc="assets/avatar-padrao.png"></cao-avatar>
+```
+
+**Observações:**
+
+- Possui `role="img"` com `aria-label`; a imagem interna é decorativa (`alt=""`), evitando leitura duplicada.
+- A imagem padrão é um SVG em data URI e passa por `DomSanitizer.bypassSecurityTrustUrl` (conteúdo controlado pela lib). Data URIs em SVG informadas em `src` **não** recebem esse tratamento e podem ser bloqueadas pelo sanitizador do Angular — use URL, caminho de arquivo ou PNG/JPEG em base64.
+- Para ícones Lucide, registre os ícones usados com `provideLucideIcons` (de `@lucide/angular`).
+- Depende de `BaseIcon` (copie junto ao usar `cao-comp`).
+---
 ### `CaoSlideToggleComponent`
 
 Um switch (slide toggle) acessível e customizável, com suporte a `ngModel` e formulários reativos via `ControlValueAccessor`. O visual é construído com trilho e thumb animados, sem depender do Material em runtime.
@@ -1889,6 +2051,142 @@ Controle de paginação para tabelas ou listas.
 | --- | --- | --- |
 | `pageEvent` | `EventEmitter<PageEvent>` | Emitido em qualquer evento de paginação. |
 
+---
+### `CaoProgressBarComponent`
+
+Barra de progresso baseada no `mat-progress-bar` do Angular Material, **sem depender do Material em runtime** (apenas `@angular/core`). Suporta os modos `determinate`, `indeterminate`, `buffer` e `query`, cores e altura configuráveis e exibição opcional do percentual.
+
+**Seletor:** `<cao-progress-bar>`
+
+**Tipo `CaoProgressBarMode`**
+
+| Valor | Descrição |
+| --- | --- |
+| `'determinate'` | Progresso conhecido, controlado por `value` (padrão). |
+| `'indeterminate'` | Progresso desconhecido, animação contínua. |
+| `'buffer'` | Exibe `value` (progresso) e `bufferValue` (buffer), com pontos animados no restante. |
+| `'query'` | Indeterminado com a animação invertida (ex.: aguardando resposta antes de passar a `determinate`). |
+
+**Atributos (Inputs)**
+
+| Atributo | Tipo | Padrão | Descrição |
+| --- | --- | --- | --- |
+| `mode` | `CaoProgressBarMode` | `'determinate'` | Modo de exibição. |
+| `value` | `number` | `0` | Progresso de 0 a 100 (`determinate` e `buffer`). Valores fora do intervalo são limitados. |
+| `bufferValue` | `number` | `0` | Valor do buffer de 0 a 100 (`buffer`). |
+| `color` | `string` | `''` | Cor da barra (qualquer cor CSS). Padrão visual: `#4f46e5`. |
+| `trackColor` | `string` | `''` | Cor do trilho. Padrão visual: `#e5e7eb`. |
+| `bufferColor` | `string` | `''` | Cor do buffer. Padrão: `color` com 35% de opacidade. |
+| `height` | `string` | `'4px'` | Altura da barra. |
+| `borderRadius` | `string` | `''` | Raio da borda. Padrão: totalmente arredondada. |
+| `animationDuration` | `string` | `''` | Duração do ciclo nos modos indeterminado/query. Padrão visual: `2s`. |
+| `showValue` | `boolean` | `false` | Exibe o percentual ao lado da barra (`determinate` e `buffer`). |
+| `ariaLabel` | `string` | `''` | `aria-label` da barra. |
+| `ariaLabelledBy` | `string` | `''` | `aria-labelledby` da barra. |
+| `dataCy` | `string` | `''` | Atributo para testes E2E com Cypress. |
+
+**CSS Custom Properties**
+
+| Propriedade | Padrão | Descrição |
+| --- | --- | --- |
+| `--cao-progress-bar-color` | `#4f46e5` | Cor da barra. |
+| `--cao-progress-bar-track-color` | `#e5e7eb` | Cor do trilho. |
+| `--cao-progress-bar-buffer-color` | `color-mix(in srgb, <cor> 35%, transparent)` | Cor do buffer. |
+| `--cao-progress-bar-text-color` | `#374151` | Cor do percentual (`showValue`). |
+| `--cao-progress-bar-radius` | `999px` | Raio da borda. |
+| `--cao-progress-bar-duration` | `2s` | Duração do ciclo da animação. |
+
+**Exemplos:**
+
+```html
+<!-- Determinate com percentual -->
+<cao-progress-bar [value]="progresso" [showValue]="true" ariaLabel="Upload do arquivo"></cao-progress-bar>
+
+<!-- Indeterminate -->
+<cao-progress-bar mode="indeterminate" ariaLabel="Carregando"></cao-progress-bar>
+
+<!-- Buffer -->
+<cao-progress-bar mode="buffer" [value]="30" [bufferValue]="65"></cao-progress-bar>
+
+<!-- Query, cores e altura customizadas -->
+<cao-progress-bar mode="query" color="#16a34a" trackColor="#dcfce7" height="8px"></cao-progress-bar>
+```
+
+**Observações:**
+
+- Usa `role="progressbar"` com `aria-valuemin`, `aria-valuemax` e `aria-valuenow` (omitido nos modos indeterminado e query). Informe `ariaLabel` ou `ariaLabelledBy` para leitores de tela.
+- `value` e `bufferValue` aceitam string (`value="50"`), convertida com `numberAttribute`.
+- Respeita `prefers-reduced-motion`: transições são removidas e a animação indeterminada fica mais lenta.
+- Não possui dependências externas.
+---
+### `CaoProgressSpinnerComponent`
+
+Spinner de progresso circular baseado no `mat-progress-spinner` do Angular Material, **sem depender do Material em runtime** (apenas `@angular/core`; o visual é um SVG). Suporta os modos `determinate` e `indeterminate`, diâmetro, espessura, cores, trilho e percentual central configuráveis.
+
+**Seletor:** `<cao-progress-spinner>`
+
+**Tipos**
+
+| Tipo | Valores |
+| --- | --- |
+| `CaoProgressSpinnerMode` | `'determinate'` \| `'indeterminate'` |
+| `CaoProgressSpinnerLinecap` | `'round'` \| `'butt'` \| `'square'` |
+
+**Atributos (Inputs)**
+
+| Atributo | Tipo | Padrão | Descrição |
+| --- | --- | --- | --- |
+| `mode` | `CaoProgressSpinnerMode` | `'indeterminate'` | Modo de exibição. |
+| `value` | `number` | `0` | Progresso de 0 a 100 (`determinate`). Valores fora do intervalo são limitados. |
+| `diameter` | `number` | `48` | Diâmetro em px (mínimo `8`). |
+| `strokeWidth` | `number` | `0` | Espessura do traço em px. `0` = automático (10% do diâmetro). |
+| `strokeLinecap` | `CaoProgressSpinnerLinecap` | `'round'` | Formato da ponta do traço. |
+| `color` | `string` | `''` | Cor do indicador (qualquer cor CSS). Padrão visual: `#4f46e5`. |
+| `trackColor` | `string` | `''` | Cor do trilho (círculo de fundo). Padrão: transparente. |
+| `animationDuration` | `string` | `''` | Duração de uma volta no modo indeterminado. Padrão visual: `1.4s`. |
+| `showValue` | `boolean` | `false` | Exibe o percentual no centro (`determinate`). |
+| `textColor` | `string` | `''` | Cor do percentual. Padrão visual: `#111827`. |
+| `ariaLabel` | `string` | `''` | `aria-label` do spinner. |
+| `ariaLabelledBy` | `string` | `''` | `aria-labelledby` do spinner. |
+| `dataCy` | `string` | `''` | Atributo para testes E2E com Cypress. |
+
+**CSS Custom Properties**
+
+| Propriedade | Padrão | Descrição |
+| --- | --- | --- |
+| `--cao-progress-spinner-color` | `#4f46e5` | Cor do indicador. |
+| `--cao-progress-spinner-track-color` | `transparent` | Cor do trilho. |
+| `--cao-progress-spinner-text-color` | `#111827` | Cor do percentual. |
+| `--cao-progress-spinner-duration` | `1.4s` | Duração de uma volta (indeterminado). |
+
+**Exemplos:**
+
+```html
+<!-- Indeterminate -->
+<cao-progress-spinner ariaLabel="Carregando"></cao-progress-spinner>
+
+<!-- Determinate com trilho e percentual -->
+<cao-progress-spinner
+  mode="determinate"
+  [value]="progresso"
+  [diameter]="96"
+  trackColor="#e5e7eb"
+  [showValue]="true"
+  ariaLabel="Progresso do envio">
+</cao-progress-spinner>
+
+<!-- Tamanho, espessura e cor customizados -->
+<cao-progress-spinner [diameter]="24" [strokeWidth]="3" color="#16a34a"></cao-progress-spinner>
+```
+
+**Observações:**
+
+- Usa `role="progressbar"` com `aria-valuemin`, `aria-valuemax` e `aria-valuenow` (omitido no modo indeterminado). Informe `ariaLabel` ou `ariaLabelledBy` para leitores de tela.
+- `value`, `diameter` e `strokeWidth` aceitam string (`diameter="64"`), convertida com `numberAttribute`.
+- O diâmetro padrão é `48` (o Material usa `100`); informe `[diameter]="100"` para o mesmo tamanho.
+- Respeita `prefers-reduced-motion`: transições são removidas e a rotação fica mais lenta.
+- Não possui dependências externas.
+
 ---
 
 ### `CaoSkeleton`

package/cli/cao-comp.cjs

@@ -185,7 +185,7 @@ import { fn } from 'storybook/test';
 import { CaoBaseButtonComponent } from '../../app/components/base-button/base-button.component';
 
 const meta: Meta<CaoBaseButtonComponent> = {
-  title: 'Components/Base Button',
+  title: 'Componentes/Base Button',
   component: CaoBaseButtonComponent,
   tags: ['autodocs'],
   args: { buttonClick: fn() },
@@ -327,18 +327,18 @@ function setupStorybook(destination, force) {
   if (conflicts.length) {
     process.stderr.write(
       `Erro: os seguintes arquivos ja existem no destino (use --force para sobrescrever):\n` +
-        conflicts.map((c) => `  - ${c}`).join('\n') +
-        '\n'
+      conflicts.map((c) => `  - ${c}`).join('\n') +
+      '\n'
     );
     return 1;
   }
 
   process.stdout.write(
     `Setup de Storybook gerado em "${root}".\n` +
-      `Arquivos criados:\n` +
-      created.map((c) => `  - ${c}`).join('\n') +
-      '\n' +
-      `Leia ${path.join(root, 'STORYBOOK-SETUP.md')} para instalar as dependencias e rodar.\n`
+    `Arquivos criados:\n` +
+    created.map((c) => `  - ${c}`).join('\n') +
+    '\n' +
+    `Leia ${path.join(root, 'STORYBOOK-SETUP.md')} para instalar as dependencias e rodar.\n`
   );
   return 0;
 }
@@ -429,7 +429,7 @@ function main() {
     const available = listComponents(templatesDir).join(', ');
     process.stderr.write(
       `Erro: componente "${component}" nao encontrado.\n` +
-        `Componentes disponiveis: ${available}\n`
+      `Componentes disponiveis: ${available}\n`
     );
     return 1;
   }
@@ -441,8 +441,8 @@ function main() {
   if (conflicts.length) {
     process.stderr.write(
       `Erro: os seguintes arquivos ja existem no destino (use --force para sobrescrever):\n` +
-        conflicts.map((c) => `  - ${c}`).join('\n') +
-        '\n'
+      conflicts.map((c) => `  - ${c}`).join('\n') +
+      '\n'
     );
     return 1;
   }