@dev-tcloud/tcloud-ui 6.14.3 → 6.17.0

package/docs/tcloud-ui-tc-btn.md

@@ -0,0 +1,189 @@
+# Layout — `.tc-btn`
+
+## Características
+
+- Classe base para botões e links estilizados, aplicável às tags `<button>` e `<a>`.
+- Cinco variantes **filled** e três variantes **outline**, cobrindo todos os contextos semânticos: ação principal, destrutiva, alerta, sucesso e neutra.
+- Três tamanhos: `tc-btn-sm`, padrão e `tc-btn-lg`.
+- Classe complementar `.tc-link` para links inline com variantes de cor.
+- Compatível com dark mode e variantes de tema — cores baseadas nos tokens `--c-*`.
+- Estado `disabled` com `opacity: 0.45` e `cursor: not-allowed`, aplicável a qualquer variante.
+- Não há componente Angular envolvido — as classes são aplicadas diretamente no HTML.
+
+## Instalação
+
+As classes são fornecidas pelo stylesheet global do projeto. Nenhuma importação de módulo Angular é necessária.
+Certifique-se de que o stylesheet principal do `tcloud-ui` está incluído na aplicação:
+
+```ts
+// angular.json — styles
+"styles": [
+  "projects/tcloud-ui/assets/scss/tcloud-ui.scss"
+]
+```
+
+---
+
+## API — Classes
+
+### Propriedades base — `.tc-btn`
+
+| Propriedade CSS | Valor | Descrição |
+|---|---|---|
+| `display` | `inline-flex` | Permite alinhar ícones ao lado do texto |
+| `padding` | `8px 18px` | Espaçamento interno padrão |
+| `border-radius` | `8px` | Bordas arredondadas |
+| `border` | `2px solid transparent` | Reserva espaço para variantes outline sem deslocar layout |
+| `font-weight` | `600` | Texto semi-negrito |
+| `font-size` | `0.9rem` | Tamanho padrão |
+| `transition` | `background, color, border-color, transform, opacity — 0.15s` | Animação suave de estados |
+
+---
+
+### Estados
+
+| Estado | Seletor CSS | Comportamento |
+|---|---|---|
+| Default | `.tc-btn` | Estado inicial do botão |
+| Hover | `.tc-btn:hover` | Escurece o background em ~10% |
+| Active | `.tc-btn:active` | Escurece mais e aplica `scale(0.98)` |
+| Focus | `.tc-btn:focus-visible` | Outline de 3px usando `--c-primary-400` |
+| Disabled | `.tc-btn:disabled` | `opacity: 0.45` + `cursor: not-allowed` |
+
+---
+
+### Variantes Filled
+
+| Classe completa | Uso recomendado |
+|---|---|
+| `tc-btn tc-btn-primary` | Ação principal da tela |
+| `tc-btn tc-btn-danger` | Ação destrutiva ou irreversível |
+| `tc-btn tc-btn-alert` | Ação que requer atenção |
+| `tc-btn tc-btn-success` | Confirmação ou conclusão |
+| `tc-btn tc-btn-neutral` | Ação secundária sem destaque |
+
+---
+
+### Variantes Outline
+
+| Classe completa | Uso recomendado |
+|---|---|
+| `tc-btn tc-btn-outline-primary` | Alternativa à primary com menos peso visual |
+| `tc-btn tc-btn-outline-danger` | Destrutiva de baixo impacto visual |
+| `tc-btn tc-btn-outline-neutral` | Ação terciária discreta |
+
+---
+
+### Tamanhos
+
+| Classe modificadora | Descrição |
+|---|---|
+| `tc-btn-sm` | Tamanho pequeno |
+| *(sem modificador)* | Tamanho padrão |
+| `tc-btn-lg` | Tamanho grande |
+
+---
+
+### `.tc-link` — Links inline
+
+Classe para links inline. Utiliza `border-bottom` em vez de `text-decoration` para controle preciso de espessura e cor.
+
+| Classe completa | Uso recomendado |
+|---|---|
+| `tc-link` | Link padrão — cor primária |
+| `tc-link tc-link-danger` | Link de ação destrutiva |
+| `tc-link tc-link-muted` | Link discreto — ação secundária |
+
+---
+
+## Exemplos de Uso
+
+### Uso Básico
+
+```html
+<!-- Botões filled -->
+<button class="tc-btn tc-btn-primary">Salvar</button>
+<button class="tc-btn tc-btn-danger">Excluir</button>
+<button class="tc-btn tc-btn-success">Confirmar</button>
+<button class="tc-btn tc-btn-neutral">Cancelar</button>
+
+<!-- Botões outline -->
+<button class="tc-btn tc-btn-outline-primary">Cancelar</button>
+<button class="tc-btn tc-btn-outline-danger">Remover</button>
+
+<!-- Desabilitado -->
+<button class="tc-btn tc-btn-primary" disabled>Processando…</button>
+```
+
+---
+
+### Uso Avançado
+
+#### Tamanhos
+
+```html
+<button class="tc-btn tc-btn-primary tc-btn-sm">Pequeno</button>
+<button class="tc-btn tc-btn-primary">Padrão</button>
+<button class="tc-btn tc-btn-primary tc-btn-lg">Grande</button>
+```
+
+#### Link estilizado como botão
+
+```html
+<a href="/nova-rota" class="tc-btn tc-btn-primary">Navegar</a>
+<a href="/voltar" class="tc-btn tc-btn-outline-neutral">Voltar</a>
+```
+
+#### Links inline
+
+```html
+<p class="f-14 font-regular text-neutral-700">
+  Não possui cadastro? <a href="#" class="tc-link">Crie sua conta</a>
+</p>
+
+<a href="#" class="tc-link tc-link-danger">Remover item</a>
+<a href="#" class="tc-link tc-link-muted">Ver detalhes</a>
+```
+
+#### Par de ações em formulário (padrão primária + outline)
+
+```html
+<div style="display: flex; gap: 8px;">
+  <button class="tc-btn tc-btn-primary" type="submit">Salvar</button>
+  <button class="tc-btn tc-btn-outline-neutral" type="button" (click)="cancel()">Cancelar</button>
+</div>
+```
+
+#### Ação destrutiva com confirmação
+
+```html
+<div style="display: flex; gap: 8px;">
+  <button class="tc-btn tc-btn-danger" (click)="delete()">Excluir registro</button>
+  <button class="tc-btn tc-btn-outline-neutral" (click)="goBack()">Voltar</button>
+</div>
+```
+
+#### Estado de carregamento via classe e `disabled`
+
+```html
+<button
+  class="tc-btn tc-btn-primary"
+  [disabled]="isLoading"
+  (click)="save()"
+>
+  {{ isLoading ? 'Salvando…' : 'Salvar' }}
+</button>
+```
+
+```ts
+export class ExampleComponent {
+  isLoading = false;
+
+  save() {
+    this.isLoading = true;
+    this.myService.save().subscribe(() => {
+      this.isLoading = false;
+    });
+  }
+}
+```

package/docs/tcloud-ui-tc-colors.md

@@ -0,0 +1,204 @@
+# Design System — Cores `--c-*`
+
+## Características
+
+- Paleta completa de tokens CSS definidos como variáveis `--c-{grupo}-{shade}`, organizados em grupos semânticos: neutros, primária, danger, alert, info e success.
+- Os tokens são remapeados automaticamente no dark mode e nas variantes de tema — componentes não precisam de alterações específicas.
+- Nunca use valores hexadecimais diretamente em componentes — sempre referencie os tokens CSS.
+- Três classes utilitárias geradas automaticamente para cada combinação de cor e shade: `.text-*`, `.bg-*` e `.border-*`.
+- Dark mode ativado pela classe `tc-dark` no `<body>`.
+- Variante **Prime Modern** ativada pela classe `tc-prime-modern` no `<body>`, substituindo apenas os tokens `--c-primary-*` pela paleta roxa.
+
+## Instalação
+
+Os tokens e classes utilitárias são fornecidos pelo stylesheet global do projeto. Nenhuma importação de módulo Angular é necessária.
+Certifique-se de que o stylesheet principal do `tcloud-ui` está incluído na aplicação:
+
+```ts
+// angular.json — styles
+"styles": [
+  "projects/tcloud-ui/assets/scss/tcloud-ui.scss"
+]
+```
+
+---
+
+## Tokens CSS — Paleta completa
+
+### Neutros
+
+| Token | Uso recomendado |
+|---|---|
+| `--c-neutral-50` | Fundo principal da página / superfície mais clara |
+| `--c-neutral-100` | Fundo de cards, headers de tabelas |
+| `--c-neutral-200` | Bordas, divisórias, separadores |
+| `--c-neutral-300` | Borda padrão de inputs — estado padrão |
+| `--c-neutral-400` | Ícones, placeholders, textos auxiliares |
+| `--c-neutral-500` | Textos secundários, descrições |
+| `--c-neutral-600` | Textos de ênfase moderada, labels |
+| `--c-neutral-700` | Texto principal — cor base do corpo |
+| `--c-neutral-800` | Texto de alto contraste |
+| `--c-neutral-900` | Máximo contraste — preto absoluto no light |
+
+### Primária
+
+| Token | Uso recomendado |
+|---|---|
+| `--c-primary-300` | Fundo de glow de foco, highlight suave |
+| `--c-primary-400` | Variante clara — hover sobre elementos primários |
+| `--c-primary-500` | Cor principal da marca — botões, links, foco |
+| `--c-primary-600` | Hover / pressed sobre elementos primários |
+| `--c-primary-700` | Versão mais escura — alto contraste |
+
+### Danger
+
+| Token | Uso recomendado |
+|---|---|
+| `--c-danger-300` | Fundo de campos com erro |
+| `--c-danger-400` | Ícone de erro, badges de alerta |
+| `--c-danger-500` | Borda e texto de erro — ação destrutiva |
+| `--c-danger-600` | Hover de botões destrutivos |
+| `--c-danger-700` | Pressed / alto contraste em danger |
+
+### Alert
+
+| Token | Uso recomendado |
+|---|---|
+| `--c-alert-300` | Fundo de notificações de aviso |
+| `--c-alert-400` | Ícone de aviso, badge de atenção |
+| `--c-alert-500` | Cor principal de aviso — atenção necessária |
+| `--c-alert-600` | Hover sobre alertas |
+| `--c-alert-700` | Alto contraste em alert |
+
+### Info
+
+| Token | Uso recomendado |
+|---|---|
+| `--c-info-300` | Fundo de banners informativos |
+| `--c-info-400` | Ícone informativo, detalhe suave |
+| `--c-info-500` | Cor principal informativa |
+
+### Success
+
+| Token | Uso recomendado |
+|---|---|
+| `--c-success-300` | Fundo de confirmações e sucessos |
+| `--c-success-400` | Ícone de sucesso, badge de confirmação |
+| `--c-success-500` | Cor principal de sucesso — ação concluída |
+| `--c-success-600` | Hover sobre elementos de sucesso |
+| `--c-success-700` | Alto contraste em success |
+
+---
+
+## Classes Utilitárias
+
+Geradas automaticamente para cada combinação de cor e shade.
+
+| Padrão da classe | Propriedade CSS | Exemplo |
+|---|---|---|
+| `.text-{cor}-{shade}` | `color` | `.text-primary-500` |
+| `.bg-{cor}-{shade}` | `background-color` | `.bg-neutral-100` |
+| `.border-{cor}-{shade}` | `border-color` | `.border-danger-500` |
+
+---
+
+## Temas e Dark Mode
+
+### Dark mode
+
+Adicione a classe `tc-dark` ao `<body>` para ativar o tema escuro. Todos os tokens `--c-*` são remapeados automaticamente — nenhum componente precisa de alteração.
+
+```html
+<body class="tc-dark">
+  <!-- Toda a aplicação renderiza no tema escuro -->
+</body>
+```
+
+### Variante Prime Modern
+
+Adicione `tc-prime-modern` ao `<body>` para substituir apenas os tokens `--c-primary-*` pela paleta roxa. Compatível com dark mode.
+
+```html
+<!-- Apenas a cor primária é substituída (paleta roxa) -->
+<body class="tc-prime-modern">...</body>
+
+<!-- Combinando dark mode + Prime Modern -->
+<body class="tc-dark tc-prime-modern">...</body>
+```
+
+---
+
+## Exemplos de Uso
+
+### Uso Básico — tokens CSS inline
+
+```html
+<!-- Cor de texto via token -->
+<p style="color: var(--c-primary-500);">Texto em cor primária</p>
+
+<!-- Fundo via token -->
+<div style="background-color: var(--c-neutral-100);">Card com fundo neutro</div>
+
+<!-- Borda via token -->
+<div style="border: 1px solid var(--c-neutral-300);">Container com borda</div>
+```
+
+### Uso com classes utilitárias
+
+```html
+<!-- Texto colorido -->
+<span class="text-primary-500">Link ou ação primária</span>
+<span class="text-danger-500">Mensagem de erro</span>
+<span class="text-success-500">Operação concluída</span>
+<span class="text-neutral-500">Texto secundário</span>
+
+<!-- Fundo semântico -->
+<div class="bg-success-300 text-success-700">Confirmação realizada com sucesso.</div>
+<div class="bg-danger-300 text-danger-600">Falha ao processar a solicitação.</div>
+<div class="bg-alert-300 text-alert-700">Atenção: verifique os dados antes de prosseguir.</div>
+<div class="bg-info-300 text-info-500">Dica: este campo aceita CPF ou CNPJ.</div>
+```
+
+### Uso avançado — tokens em CSS customizado
+
+```scss
+// styles.scss — nunca use hex, sempre os tokens
+.meu-componente {
+  color: var(--c-neutral-700);
+  background-color: var(--c-neutral-50);
+  border: 1px solid var(--c-neutral-300);
+
+  &:hover {
+    border-color: var(--c-primary-500);
+    background-color: var(--c-primary-300);
+  }
+
+  &.is-error {
+    border-color: var(--c-danger-500);
+    background-color: var(--c-danger-300);
+    color: var(--c-danger-600);
+  }
+}
+```
+
+### Integração com Angular — class binding condicional
+
+```html
+<div
+  [class]="'f-14 font-regular ' + (hasError ? 'text-danger-500' : 'text-neutral-700')"
+>
+  {{ mensagem }}
+</div>
+
+<div
+  [ngClass]="{
+    'bg-success-300 text-success-700': status === 'success',
+    'bg-danger-300 text-danger-600':   status === 'error',
+    'bg-alert-300 text-alert-700':     status === 'warning',
+    'bg-info-300 text-info-500':       status === 'info'
+  }"
+  class="f-14 font-regular"
+>
+  {{ mensagem }}
+</div>
+```

package/docs/tcloud-ui-tc-form-control.md

@@ -0,0 +1,200 @@
+# Layout — `.tc-form-control`
+
+## Características
+
+- Classe CSS aplicada a qualquer `<input>` para estilização padronizada de campos de texto no projeto.
+- Visual em pílula (`border-radius: 40px`) com altura fixa de `40px` e padding horizontal consistente.
+- Adaptável ao dark mode — `color`, `background` e `border` utilizam tokens CSS do design system.
+- Suporte a estados visuais: padrão, foco, erro e desabilitado.
+- Classe modificadora `.tc-form-control--error` para indicação de validação inválida.
+- Combina com `.tc-form-field` para agrupar label, dica (`.tc-form-hint`) e mensagem de erro (`.tc-form-error`) de forma semântica e acessível.
+- Não há componente Angular envolvido — as classes são aplicadas diretamente no HTML.
+
+## Instalação
+
+As classes são fornecidas pelo stylesheet global do projeto. Nenhuma importação de módulo Angular é necessária.
+Certifique-se de que o stylesheet principal do `tcloud-ui` está incluído na aplicação:
+
+```ts
+// angular.json — styles
+"styles": [
+  "projects/tcloud-ui/assets/scss/tcloud-ui.scss"
+]
+```
+
+---
+
+## API — Classes
+
+### `.tc-form-control`
+
+Classe principal aplicada ao `<input>`.
+
+| Propriedade CSS | Valor / Token | Descrição |
+|---|---|---|
+| `border` | `1px solid var(--c-neutral-400)` | Borda padrão — cor do token neutral |
+| `border-radius` | `var(--bor-radius-pill)` | Bordas arredondadas em pílula (40px) |
+| `height` | `var(--size-40)` | Altura fixa de 2.5rem (40px) |
+| `padding` | `0 var(--size-16)` | Espaçamento interno horizontal |
+| `font-size` | `var(--f-size-14)` | Tamanho de texto padrão (0.875rem) |
+| `line-height` | `var(--l-height-20)` | Altura de linha (1.43) |
+| `color` | `var(--c-neutral-700)` | Cor do texto — adapta ao dark mode |
+| `background` | `var(--c-neutral-50)` | Fundo — adapta ao dark mode |
+| `transition` | `.2s ease` | Animação suave de estados |
+| `max-width` | `100%` | Respeita o container pai |
+
+---
+
+### Classes modificadoras e auxiliares
+
+| Classe | Elemento | Descrição |
+|---|---|---|
+| `.tc-form-control--error` | `<input>` | Aplica borda e fundo com cor `danger` — campo com validação inválida |
+| `.tc-form-field` | `<div>` container | Agrupa label + input + mensagens de forma semântica |
+| `.tc-form-hint` | `<p>` | Texto auxiliar abaixo do campo (dica ou instrução) |
+| `.tc-form-error` | `<p>` | Mensagem de erro de validação abaixo do campo |
+
+---
+
+### Estados
+
+| Estado | Descrição |
+|---|---|
+| Padrão | Estado inicial do campo |
+| Com valor | Campo preenchido pelo usuário |
+| Foco | Borda primary + glow — ao clicar no campo |
+| Erro | Borda e fundo danger — validação inválida (`tc-form-control--error`) |
+| Desabilitado | Fundo neutro + cursor `not-allowed` (atributo `disabled`) |
+
+---
+
+### Tipos de input suportados
+
+| `type` | Uso recomendado |
+|---|---|
+| `text` | Texto livre — campos genéricos |
+| `email` | Endereço de e-mail |
+| `password` | Senhas — oculta o conteúdo |
+| `number` | Valores numéricos |
+| `search` | Campo de busca |
+| `tel` | Número de telefone |
+
+---
+
+## Exemplos de Uso
+
+### Uso Básico
+
+```html
+<!-- Campo simples -->
+<input class="tc-form-control" type="text" placeholder="Digite algo…" />
+
+<!-- Campo desabilitado -->
+<input class="tc-form-control" type="text" disabled placeholder="Campo desabilitado" />
+
+<!-- Campo com erro -->
+<input class="tc-form-control tc-form-control--error" type="text" value="dado inválido" />
+```
+
+---
+
+### Uso Avançado
+
+#### Campo completo com `.tc-form-field`, label e dica
+
+```html
+<div class="tc-form-field">
+  <label for="nome">Nome completo</label>
+  <input class="tc-form-control" id="nome" type="text" placeholder="Ex.: João Silva" />
+  <p class="tc-form-hint">Informe seu nome como consta no documento.</p>
+</div>
+```
+
+#### Campo com mensagem de erro de validação
+
+```html
+<div class="tc-form-field">
+  <label for="cpf">CPF</label>
+  <input
+    class="tc-form-control tc-form-control--error"
+    id="cpf"
+    type="text"
+    value="123.456"
+  />
+  <p class="tc-form-error">CPF inválido. Verifique o número informado.</p>
+</div>
+```
+
+#### Campo somente leitura / gerado automaticamente
+
+```html
+<div class="tc-form-field">
+  <label for="codigo">Código de cliente</label>
+  <input
+    class="tc-form-control"
+    id="codigo"
+    type="text"
+    value="CLI-00421"
+    disabled
+  />
+  <p class="tc-form-hint">Gerado automaticamente — não editável.</p>
+</div>
+```
+
+#### Formulário com múltiplos campos
+
+```html
+<form>
+  <div class="tc-form-field">
+    <label for="nome">Nome completo</label>
+    <input class="tc-form-control" id="nome" type="text" placeholder="Ex.: João Silva" />
+  </div>
+
+  <div class="tc-form-field">
+    <label for="email">E-mail</label>
+    <input class="tc-form-control" id="email" type="email" placeholder="email@exemplo.com" />
+  </div>
+
+  <div class="tc-form-field">
+    <label for="tel">Telefone</label>
+    <input class="tc-form-control" id="tel" type="tel" placeholder="(00) 00000-0000" />
+    <p class="tc-form-hint">DDD + número com 9 dígitos.</p>
+  </div>
+
+  <div class="tc-form-field">
+    <label for="senha">Senha</label>
+    <input class="tc-form-control" id="senha" type="password" placeholder="Mínimo 8 caracteres" />
+  </div>
+</form>
+```
+
+#### Integração com Angular Reactive Forms
+
+```html
+<form [formGroup]="form">
+  <div class="tc-form-field">
+    <label for="email">E-mail</label>
+    <input
+      class="tc-form-control"
+      [class.tc-form-control--error]="form.get('email')?.invalid && form.get('email')?.touched"
+      id="email"
+      type="email"
+      formControlName="email"
+      placeholder="email@exemplo.com"
+    />
+    <p class="tc-form-error" *ngIf="form.get('email')?.invalid && form.get('email')?.touched">
+      E-mail inválido. Verifique e tente novamente.
+    </p>
+  </div>
+</form>
+```
+
+```ts
+export class ExampleComponent {
+  form = this.fb.group({
+    email: ['', [Validators.required, Validators.email]]
+  });
+
+  constructor(private fb: FormBuilder) {}
+}
+```