ngx-opalbytes-components 1.18.0 → 1.20.0

package/README.md

@@ -72,6 +72,59 @@ export class ExemploComponent {
 
 ---
 
+## Comandos CLI
+
+A biblioteca disponibiliza uma CLI (`cao-comp`) para copiar o código-fonte de um componente da `ngx-opalbytes-components` para qualquer projeto. Isso é útil quando você precisa customizar o código-fonte de um componente internamente, sem depender apenas da API pública.
+
+### Instalação global
+
+Para utilizar o comando `cao-comp` de qualquer lugar, instale a biblioteca globalmente:
+
+```bash
+npm install -g ngx-opalbytes-components
+```
+
+Para desenvolvimento local, a partir da pasta `projects/ngx-opalbytes-components`:
+
+```bash
+npm link
+```
+
+> Caso não queira instalar, também é possível executar o script diretamente:
+> `node ./node_modules/ngx-opalbytes-components/cli/cao-comp.cjs ...`
+
+### Uso
+
+```bash
+cao-comp <componente> <destino> [opcoes]
+```
+
+**Argumentos:**
+
+| Argumento | Descrição |
+| --- | --- |
+| `<componente>` | Nome da pasta do componente em `shared/components` (ex: `base-button`). |
+| `<destino>` | Pasta de destino onde os arquivos serão gerados (criada se não existir). |
+
+**Opções:**
+
+| Opção | Descrição |
+| --- | --- |
+| `-h, --help` | Exibe a ajuda. |
+| `-l, --list` | Lista os componentes disponíveis para cópia. |
+| `-f, --force` | Sobrescreve arquivos existentes no destino. |
+| `-v, --version` | Exibe a versão. |
+
+**Exemplos:**
+
+```bash
+cao-comp base-button ./src/app/components
+cao-comp stepper ./src/app/components --force
+cao-comp --list
+```
+
+---
+
 ## 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`).
@@ -89,6 +142,7 @@ src/
         |   ├── base-toggle/
         |   ├── drop-down/
         |   ├── footer/
+        |   ├── kpi/
         |   ├── links-button/
         |   ├── paginator/
         |   ├── stepper/
@@ -816,6 +870,55 @@ Um rodapé simples para a aplicação.
 
 ---
 
+### `CaoKpi`
+
+Um componente de KPI (Key Performance Indicator) que exibe um cartão com ícone, valor, título, cor de texto e cor de borda configuráveis.
+
+**Seletor:** `<cao-kpi>`
+
+**Interface `ICaoKPI`**
+
+| Propriedade | Tipo | Descrição |
+| --- | --- | --- |
+| `title` | `string` | O título do KPI. |
+| `value` | `string` | O valor exibido (ex: `"R$ 12.345"`). |
+| `textColor` | `string` | Cor do texto (valor e título). |
+| `borderColor` | `string` | Cor da borda do cartão. |
+| `icon` | `ICaoImage` | O ícone exibido no canto superior direito. |
+
+**Interface `ICaoImage`**
+
+| Propriedade | Tipo | Descrição |
+| --- | --- | --- |
+| `src` | `string` | Caminho ou URL da imagem do ícone. |
+| `alt` | `string` | Texto alternativo (acessibilidade) da imagem. |
+
+**Atributos (Inputs)**
+
+| Atributo | Tipo | Padrão | Descrição |
+| --- | --- | --- | --- |
+| `kpiData` | `ICaoKPI` | — (obrigatório) | Dados do KPI, recebidos via `input.required`. |
+
+**Exemplo de uso:**
+
+```html
+<cao-kpi [kpiData]="meuKpi"></cao-kpi>
+```
+
+```typescript
+import { CaoKpi, ICaoKPI } from 'ngx-opalbytes-components';
+
+meuKpi: ICaoKPI = {
+  title: 'Total de Vendas',
+  value: 'R$ 12.345',
+  textColor: '#16a34a',
+  borderColor: '#16a34a',
+  icon: { src: 'assets/icon-vendas.svg', alt: 'Vendas' }
+};
+```
+
+---
+
 ### `LinksButton`
 Exibe uma lista de links de navegação como botões.
 

package/cli/cao-comp.cjs

@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const USAGE = `cao-comp — Copia um componente da lib ngx-opalbytes-components para qualquer projeto
+
+Uso:
+  cao-comp <componente> <destino> [opcoes]
+
+Argumentos:
+  <componente>   Nome da pasta do componente em shared/components (ex: base-button)
+  <destino>      Pasta de destino onde os arquivos serao gerados (criada se nao existir)
+
+Opcoes:
+  -h, --help      Exibe esta ajuda
+  -l, --list      Lista os componentes disponiveis para copia
+  -f, --force     Sobrescreve arquivos existentes no destino
+  -v, --version   Exibe a versao
+
+Exemplos:
+  cao-comp base-button ./src/app/components
+  cao-comp stepper ./src/app/components --force
+  cao-comp --list
+`;
+
+function resolveTemplatesDir() {
+  const candidates = [
+    path.join(__dirname, '..', 'templates'),
+    path.join(__dirname, '..', 'src', 'lib', 'shared', 'components'),
+    path.join(__dirname, '..', '..', 'src', 'lib', 'shared', 'components'),
+  ];
+  for (const dir of candidates) {
+    if (fs.existsSync(dir) && fs.statSync(dir).isDirectory()) {
+      return dir;
+    }
+  }
+  return null;
+}
+
+function resolvePackageVersion() {
+  const candidates = [
+    path.join(__dirname, '..', 'package.json'),
+    path.join(__dirname, '..', '..', 'package.json'),
+    path.join(__dirname, '..', '..', '..', 'package.json'),
+  ];
+  for (const file of candidates) {
+    if (fs.existsSync(file)) {
+      try {
+        const pkg = JSON.parse(fs.readFileSync(file, 'utf8'));
+        if (pkg && pkg.version) {
+          return pkg.version;
+        }
+      } catch (_) {
+        /* ignore */
+      }
+    }
+  }
+  return 'desconhecida';
+}
+
+function listComponents(templatesDir) {
+  return fs
+    .readdirSync(templatesDir, { withFileTypes: true })
+    .filter((e) => e.isDirectory())
+    .map((e) => e.name)
+    .sort();
+}
+
+function copyRecursive(src, dest, force, conflicts) {
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      fs.mkdirSync(destPath, { recursive: true });
+      copyRecursive(srcPath, destPath, force, conflicts);
+    } else {
+      if (fs.existsSync(destPath) && !force) {
+        conflicts.push(destPath);
+        continue;
+      }
+      fs.mkdirSync(path.dirname(destPath), { recursive: true });
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+function parseArgs(argv) {
+  const positionals = [];
+  const flags = { help: false, list: false, force: false, version: false };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    switch (arg) {
+      case '-h':
+      case '--help':
+        flags.help = true;
+        break;
+      case '-l':
+      case '--list':
+        flags.list = true;
+        break;
+      case '-f':
+      case '--force':
+        flags.force = true;
+        break;
+      case '-v':
+      case '--version':
+        flags.version = true;
+        break;
+      default:
+        positionals.push(arg);
+    }
+  }
+  return { positionals, flags };
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  const { positionals, flags } = parseArgs(argv);
+
+  if (flags.help) {
+    process.stdout.write(USAGE + '\n');
+    return 0;
+  }
+
+  if (flags.version) {
+    process.stdout.write(`cao-comp ${resolvePackageVersion()}\n`);
+    return 0;
+  }
+
+  const templatesDir = resolveTemplatesDir();
+  if (!templatesDir) {
+    process.stderr.write(
+      'Erro: nao foi possivel localizar a pasta de templates dos componentes.\n'
+    );
+    return 1;
+  }
+
+  if (flags.list) {
+    const components = listComponents(templatesDir);
+    process.stdout.write('Componentes disponiveis:\n');
+    for (const c of components) {
+      process.stdout.write(`  - ${c}\n`);
+    }
+    return 0;
+  }
+
+  const [component, destination] = positionals;
+  if (!component || !destination) {
+    process.stderr.write(
+      'Erro: informe o componente e o destino.\n\n' + USAGE + '\n'
+    );
+    return 1;
+  }
+
+  const sourceDir = path.join(templatesDir, component);
+  if (!fs.existsSync(sourceDir) || !fs.statSync(sourceDir).isDirectory()) {
+    const available = listComponents(templatesDir).join(', ');
+    process.stderr.write(
+      `Erro: componente "${component}" nao encontrado.\n` +
+        `Componentes disponiveis: ${available}\n`
+    );
+    return 1;
+  }
+
+  fs.mkdirSync(destination, { recursive: true });
+  const conflicts = [];
+  copyRecursive(sourceDir, destination, flags.force, conflicts);
+
+  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'
+    );
+    return 1;
+  }
+
+  process.stdout.write(
+    `Componente "${component}" copiado para "${destination}".\n`
+  );
+  return 0;
+}
+
+process.exit(main());