@dev-tcloud/tcloud-ui 6.14.3 → 6.17.0

package/docs/tcloud-ui-scroll-box.md

@@ -0,0 +1,109 @@
+# TCloudUiScrollBox
+
+O componente `tcloud-ui-scroll-box` cria um contêiner com scroll vertical e altura limitada, ideal para envolver conteúdos extensos como tabelas, listas ou formulários longos. Utiliza `ng-content` para projetar qualquer conteúdo filho. Suporta unidades `px` e `vh` — com `px` aplica `max-height` (scroll apenas quando o conteúdo excede a altura), enquanto `vh` aplica `height` fixa relativa à viewport.
+
+## Características
+
+- Contêiner com scroll vertical e altura máxima configurável
+- Projeção de conteúdo via `ng-content` (aceita qualquer conteúdo Angular)
+- Suporte a unidades `px` e `vh` no `maxHeight`
+- Detecção automática da unidade a partir do valor informado
+- Borda opcional ao redor do contêiner
+- Comportamento diferenciado: `max-height` para `px` e `height` para `vh`
+- Componente standalone
+
+## Instalação
+
+Importe o componente diretamente no módulo ou componente standalone:
+
+```typescript
+import { TCloudUiScrollBoxComponent } from 'tcloud-ui';
+```
+
+## Propriedades
+
+### Inputs
+
+| Propriedade | Tipo               | Padrão  | Descrição                                                                                                    |
+|-------------|--------------------|---------|--------------------------------------------------------------------------------------------------------------|
+| `border`    | `boolean`          | `true`  | Exibe uma borda ao redor do contêiner de scroll                                                              |
+| `maxHeight` | `number \| string` | `'400'` | Altura máxima do contêiner. Aceita número (em `px`) ou string com unidade (ex: `'300'`, `'80vh'`, `'500px'`) |
+
+### Outputs
+
+Este componente não possui outputs.
+
+## Exemplos de Uso
+
+### Básico — Tabela com scroll vertical
+
+```html
+<tcloud-ui-scroll-box [maxHeight]="300">
+  <table class="table">
+    <thead>
+      <tr>
+        <th>Nome</th>
+        <th>Nacionalidade</th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr><td>Rodrigo</td><td>Brasileiro</td></tr>
+      <tr><td>Leonardo</td><td>Brasileiro</td></tr>
+      <tr><td>Romano</td><td>Italiano</td></tr>
+      <tr><td>Antônio</td><td>Brasileiro</td></tr>
+      <tr><td>Bruno</td><td>Canadense</td></tr>
+      <tr><td>Ana</td><td>Brasileiro</td></tr>
+      <tr><td>Marcia</td><td>Italiano</td></tr>
+    </tbody>
+  </table>
+</tcloud-ui-scroll-box>
+```
+
+```typescript
+import { TCloudUiScrollBoxComponent } from 'tcloud-ui';
+
+@Component({
+  standalone: true,
+  imports: [TCloudUiScrollBoxComponent],
+  template: `...`
+})
+export class ExemploBasicoComponent {}
+```
+
+### Avançado — Altura relativa à viewport sem borda
+
+```html
+<tcloud-ui-scroll-box maxHeight="60vh" [border]="false">
+  <div *ngFor="let item of itens">
+    <p>{{ item.descricao }}</p>
+  </div>
+</tcloud-ui-scroll-box>
+```
+
+```typescript
+import { TCloudUiScrollBoxComponent } from 'tcloud-ui';
+
+@Component({
+  standalone: true,
+  imports: [TCloudUiScrollBoxComponent],
+  template: `...`
+})
+export class ExemploAvancadoComponent {
+  itens = Array.from({ length: 50 }, (_, i) => ({
+    descricao: `Item ${i + 1}`
+  }));
+}
+```
+
+### Avançado — Lista de cards com altura fixa em pixels
+
+```html
+<tcloud-ui-scroll-box maxHeight="500px">
+  <div class="card mb-2" *ngFor="let usuario of usuarios">
+    <div class="card-body">
+      <h5>{{ usuario.nome }}</h5>
+      <p>{{ usuario.email }}</p>
+    </div>
+  </div>
+</tcloud-ui-scroll-box>
+```

package/docs/tcloud-ui-search-bar.md

@@ -0,0 +1,88 @@
+# Search Bar
+
+## Características
+
+O `TCloudUiSearchBarComponent` é um componente Angular standalone que exibe uma barra de busca com input estilizado. A cada digitação, emite o valor atual do campo via evento `searchChange`.
+
+Funcionalidades principais:
+- Input com placeholder descritivo para buscas por usuário, instância ou rotina.
+- Emissão de evento `searchChange` a cada keystroke, permitindo busca em tempo real.
+- Layout flexbox com border-radius arredondado (pill style).
+
+## Instalação
+
+Importe o `TCloudUiSearchBarComponent` no componente standalone:
+
+```typescript
+import { TCloudUiSearchBarComponent } from 'tcloud-ui';
+
+@Component({
+    selector: 'app-exemplo',
+    standalone: true,
+    imports: [TCloudUiSearchBarComponent],
+    template: '...'
+})
+export class ExemploComponent {}
+```
+
+## Propriedades (API)
+
+### Inputs
+
+Este componente não possui `@Input()` públicos.
+
+### Outputs
+
+| Nome         | Tipo de Evento | Descrição                                              |
+|--------------|----------------|--------------------------------------------------------|
+| searchChange | `string`       | Emitido a cada digitação com o valor atual do input.   |
+
+## Exemplos de Uso
+
+### Uso Básico
+
+```html
+<tcloud-ui-search-bar (searchChange)="onSearchChange($event)"></tcloud-ui-search-bar>
+```
+
+```typescript
+@Component({
+    selector: 'app-exemplo',
+    standalone: true,
+    imports: [TCloudUiSearchBarComponent],
+    template: `
+      <tcloud-ui-search-bar (searchChange)="onSearchChange($event)"></tcloud-ui-search-bar>
+    `
+})
+export class ExemploComponent {
+  onSearchChange(value: string): void {
+    console.log('Buscando:', value);
+  }
+}
+```
+
+### Uso Avançado — Filtragem de Lista em Tempo Real
+
+```typescript
+@Component({
+    selector: 'app-exemplo',
+    standalone: true,
+    imports: [CommonModule, TCloudUiSearchBarComponent],
+    template: `
+      <tcloud-ui-search-bar (searchChange)="onSearch($event)"></tcloud-ui-search-bar>
+      <ul>
+        <li *ngFor="let item of filteredItems">{{ item }}</li>
+      </ul>
+    `
+})
+export class ExemploComponent {
+  items = ['Usuário Admin', 'Instância Produção', 'Rotina Backup', 'Usuário Dev'];
+  filteredItems = [...this.items];
+
+  onSearch(term: string): void {
+    this.filteredItems = this.items.filter(item =>
+      item.toLowerCase().includes(term.toLowerCase())
+    );
+  }
+}
+```

package/docs/tcloud-ui-search-in-object.md

@@ -0,0 +1,143 @@
+# TCloudUiSearchInObjectService
+
+O serviço `TCloudUiSearchInObjectService` realiza busca full-text em arrays de objetos ou arrays simples. Através do método `meet`, é possível pesquisar um termo em todas as propriedades de um objeto (ou em campos específicos), com normalização de acentos e case-insensitive. Suporta automaticamente valores do tipo `Date` (formatando em `dd/MM/yyyy hh:mm` e `medium` para comparação) e aplica o pipe `StatusInfoPipe` para transformar valores antes da busca. É o mecanismo de busca utilizado internamente pelo componente `tcloud-ui-input-search`.
+
+## Características
+
+- Busca full-text em arrays de objetos por qualquer propriedade
+- Busca em arrays simples (strings, números)
+- Filtragem por campos específicos via parâmetro `camposDebusca`
+- Normalização automática de acentos e diacríticos (NFD)
+- Busca case-insensitive
+- Detecção e formatação automática de valores `Date` para comparação textual
+- Transformação de valores via `StatusInfoPipe` antes da comparação
+- Remoção de duplicatas nos resultados
+- Serviço injetável com `providedIn: 'root'`
+
+## Instalação
+
+Importe o serviço diretamente no componente ou módulo:
+
+```typescript
+import { TCloudUiSearchInObjectService } from 'tcloud-ui';
+```
+
+O serviço é registrado com `providedIn: 'root'`, portanto está disponível globalmente via injeção de dependência sem necessidade de declaração em providers.
+
+## API
+
+### Métodos
+
+| Método | Retorno | Descrição |
+|--------|---------|-----------|
+| `meet(valor, emObject, camposDebusca?)` | `any[]` | Procura o termo `valor` dentro do array `emObject`, retornando os itens que contêm o termo |
+
+### Parâmetros do método `meet`
+
+| Parâmetro       | Tipo       | Obrigatório | Descrição                                                                                          |
+|-----------------|------------|-------------|-----------------------------------------------------------------------------------------------------|
+| `valor`         | `string`   | Sim         | Texto a ser pesquisado. Quando vazio, retorna o array original sem filtrar                          |
+| `emObject`      | `any`      | Sim         | Array de objetos ou array simples onde a busca será realizada                                       |
+| `camposDebusca` | `any[]`    | Não         | Lista de chaves (propriedades) do objeto para restringir a busca. Quando omitido, busca em todas as propriedades |
+
+## Exemplos de Uso
+
+### Básico — Busca em todas as propriedades de um array de objetos
+
+```typescript
+import { TCloudUiSearchInObjectService } from 'tcloud-ui';
+
+@Component({
+  standalone: true,
+  imports: [CommonModule],
+  template: `
+    <input type="text" #inputBusca class="tc-form-control">
+    <button (click)="buscar(inputBusca.value)">Procurar</button>
+    <pre>{{ resultados | json }}</pre>
+  `
+})
+export class ExemploBasicoComponent {
+  dados = [
+    { name: 'Rodrigo', last_name: 'Rea' },
+    { name: 'João', last_name: 'Alves' },
+    { name: 'Maria', last_name: 'Alves' }
+  ];
+
+  resultados: any[] = [];
+
+  constructor(private searchService: TCloudUiSearchInObjectService) {}
+
+  buscar(valor: string) {
+    this.resultados = this.searchService.meet(valor, this.dados);
+  }
+}
+```
+
+### Avançado — Busca restrita a campos específicos
+
+```typescript
+import { TCloudUiSearchInObjectService } from 'tcloud-ui';
+
+@Component({
+  standalone: true,
+  imports: [CommonModule],
+  template: `
+    <input type="text" (input)="buscar($event.target.value)" class="tc-form-control" placeholder="Buscar por nome...">
+    <table class="table">
+      <thead>
+        <tr><th>Nome</th><th>Sobrenome</th><th>Cidade</th></tr>
+      </thead>
+      <tbody>
+        <tr *ngFor="let item of resultados">
+          <td>{{ item.name }}</td>
+          <td>{{ item.last_name }}</td>
+          <td>{{ item.city }}</td>
+        </tr>
+      </tbody>
+    </table>
+  `
+})
+export class ExemploAvancadoComponent {
+  dados = [
+    { name: 'Rodrigo', last_name: 'Rea', city: 'São Paulo' },
+    { name: 'João', last_name: 'Alves', city: 'Rio de Janeiro' },
+    { name: 'Maria', last_name: 'Alves', city: 'Curitiba' }
+  ];
+
+  resultados: any[] = [...this.dados];
+  camposBusca = ['name', 'last_name'];
+
+  constructor(private searchService: TCloudUiSearchInObjectService) {}
+
+  buscar(valor: string) {
+    this.resultados = this.searchService.meet(valor, this.dados, this.camposBusca);
+  }
+}
+```
+
+### Avançado — Busca em array simples
+
+```typescript
+import { TCloudUiSearchInObjectService } from 'tcloud-ui';
+
+@Component({
+  standalone: true,
+  imports: [CommonModule],
+  template: `
+    <input type="text" (input)="filtrar($event.target.value)" class="tc-form-control" placeholder="Filtrar tags...">
+    <ul>
+      <li *ngFor="let tag of tagsFiltradas">{{ tag }}</li>
+    </ul>
+  `
+})
+export class ExemploArraySimplesComponent {
+  tags = ['Angular', 'React', 'Vue', 'Svelte', 'Next.js'];
+  tagsFiltradas: string[] = [...this.tags];
+
+  constructor(private searchService: TCloudUiSearchInObjectService) {}
+
+  filtrar(valor: string) {
+    this.tagsFiltradas = this.searchService.meet(valor, this.tags);
+  }
+}
+```

package/docs/tcloud-ui-search-input.md

@@ -0,0 +1,74 @@
+# Search Input
+
+## Características
+
+O componente `tcloud-ui-search-input` fornece um campo de busca com debounce integrado. Ele encapsula um `FormControl` reativo que emite o texto pesquisado após 500ms de inatividade, aplicando `distinctUntilChanged` para evitar emissões duplicadas. O texto é automaticamente convertido para minúsculas. Suporta two-way binding via `[(searchText)]` e foco automático opcional.
+
+## Instalação
+
+Importe o `TCloudUiModule` ou o componente standalone `TCloudUiSearchInputComponent`:
+
+```typescript
+import { TCloudUiModule } from 'tcloud-ui';
+// ou
+import { TCloudUiSearchInputComponent } from 'tcloud-ui';
+```
+
+## API
+
+### Inputs
+
+| Nome         | Tipo      | Descrição                                             | Valor Default |
+| ------------ | --------- | ----------------------------------------------------- | ------------- |
+| `searchText` | `string`  | Texto de pesquisa (suporta two-way binding).          | `''`          |
+| `placeholder`| `string`  | Texto placeholder exibido no campo de busca.          | `''`          |
+| `autoFocus`  | `boolean` | Aplica foco automático ao campo ao inicializar.       | `false`       |
+
+### Outputs
+
+| Nome               | Tipo de Evento | Descrição                                                        |
+| ------------------ | -------------- | ---------------------------------------------------------------- |
+| `searchTextChange` | `string`       | Emitido quando o texto muda (para two-way binding).              |
+| `onSearch`         | `string`       | Emitido após debounce de 500ms com o texto pesquisado em lowercase. |
+
+## Exemplos de Uso
+
+### Uso Básico
+
+```html
+<tcloud-ui-search-input
+  placeholder="Pesquisar..."
+  (onSearch)="onSearch($event)"
+></tcloud-ui-search-input>
+```
+
+```typescript
+onSearch(text: string): void {
+  console.log('Texto pesquisado:', text);
+}
+```
+
+### Uso Avançado
+
+Two-way binding com `searchText` e auto focus:
+
+```html
+<tcloud-ui-search-input
+  [(searchText)]="searchText"
+  placeholder="Pesquisar itens..."
+  [autoFocus]="true"
+  (onSearch)="filtrarLista($event)"
+></tcloud-ui-search-input>
+
+<p>Valor atual: {{ searchText }}</p>
+```
+
+```typescript
+searchText: string = '';
+
+filtrarLista(text: string): void {
+  this.listaFiltrada = this.listaCompleta.filter(item =>
+    item.nome.toLowerCase().includes(text)
+  );
+}
+```