ngx-opalbytes-components 1.20.0 → 1.22.0

package/README.md

@@ -145,6 +145,7 @@ src/
         |   ├── kpi/
         |   ├── links-button/
         |   ├── paginator/
+        |   ├── skeleton/
         |   ├── stepper/
         |   ├── tab-group/
         |   ├── tab-panel/
@@ -955,6 +956,80 @@ Controle de paginação para tabelas ou listas.
 
 ---
 
+### `CaoSkeleton`
+Um componente de esqueleto de carregamento (skeleton/placeholder) com variantes de retângulo, círculo e texto, animação shimmer customizável e cor configurável.
+
+**Seletor:** `<cao-skeleton>`
+
+**Tipo `CaoSkeletonVariant`**
+
+| Valor | Descrição |
+| --- | --- |
+| `'rect'` | Retângulo (padrão). |
+| `'circle'` | Círculo (largura/altura devem ser iguais, mas é garantido via `aspect-ratio`). |
+| `'text'` | Linha de texto (altura `1em`, raio `4px`). |
+
+**Atributos (Inputs)**
+
+| Atributo | Tipo | Padrão | Descrição |
+| --- | --- | --- | --- |
+| `borderRadius` | `string` | `'14px'` | Raio da borda do retângulo (ignorado nas variantes `circle` e `text`). |
+| `width` | `string` | `'100%'` | Largura do esqueleto (usada quando `size` não é informado). |
+| `height` | `string` | `'100%'` | Altura do esqueleto (usada quando `size` não é informado). |
+| `bgColor` | `string` | `'#e2e8f0'` | Cor de fundo do esqueleto. |
+| `shine` | `string` | `'#f8fafc'` | Cor do reflexo (shimmer). |
+| `variant` | `CaoSkeletonVariant` | `'rect'` | Formato do esqueleto (`'rect'`, `'circle'` ou `'text'`). |
+| `speed` | `string` | `'2s'` | Duração da animação shimmer. |
+| `size` | `string` | `undefined` | Quando definido, sobrescreve `width` e `height` simultaneamente (ex.: `'48px'`). |
+| `animationDeg` | `string` | `'90deg'` | Ângulo do gradiente da animação shimmer. |
+
+**CSS Custom Properties**
+
+O componente expõe todas as suas propriedades visuais via CSS custom properties, que cascateiam naturalmente e podem ser sobrescritas por um elemento pai ou globalmente:
+
+| Propriedade | Padrão | Descrição |
+| --- | --- | --- |
+| `--skeleton-width` | `100%` | Largura do esqueleto. |
+| `--skeleton-height` | `100%` | Altura do esqueleto. |
+| `--skeleton-bg` | `#e2e8f0` | Cor de fundo do esqueleto. |
+| `--skeleton-shine` | `#f8fafc` | Cor do reflexo (shimmer). |
+| `--skeleton-radius` | `14px` | Raio da borda. |
+| `--skeleton-speed` | `2s` | Duração da animação shimmer. |
+| `--skeleton-animation-deg` | `90deg` | Ângulo do gradiente do shimmer. |
+
+```css
+.my-card {
+  --skeleton-bg: #d1d5db;
+  --skeleton-shine: #f3f4f6;
+  --skeleton-radius: 8px;
+  --skeleton-speed: 2s;
+}
+```
+
+**Exemplo de uso:**
+
+```html
+<!-- Retângulo -->
+<cao-skeleton width="200px" height="40px"></cao-skeleton>
+
+<!-- Círculo -->
+<cao-skeleton variant="circle" size="48px"></cao-skeleton>
+
+<!-- Linha de texto -->
+<cao-skeleton variant="text" width="120px"></cao-skeleton>
+
+<!-- Cores customizadas e duração da animação -->
+<cao-skeleton
+  width="100%"
+  height="24px"
+  bgColor="#e0e7ff"
+  shine="#ffffff"
+  speed="1.5s"
+></cao-skeleton>
+```
+
+---
+
 ### `TimePicker`
 Um seletor de horário.
 

package/cli/cao-comp.cjs

@@ -5,9 +5,11 @@ const fs = require('fs');
 const path = require('path');
 
 const USAGE = `cao-comp — Copia um componente da lib ngx-opalbytes-components para qualquer projeto
+e gera o setup de Storybook para visualizar os componentes
 
 Uso:
   cao-comp <componente> <destino> [opcoes]
+  cao-comp storybook <destino> [opcoes]
 
 Argumentos:
   <componente>   Nome da pasta do componente em shared/components (ex: base-button)
@@ -19,10 +21,214 @@ Opcoes:
   -f, --force     Sobrescreve arquivos existentes no destino
   -v, --version   Exibe a versao
 
+Subcomando storybook:
+  Gera o setup minimo do Storybook (.storybook/, exemplo de story e STORYBOOK-SETUP.md)
+  em <destino>, pronto para visualizar os componentes copiados.
+
 Exemplos:
   cao-comp base-button ./src/app/components
   cao-comp stepper ./src/app/components --force
   cao-comp --list
+  cao-comp storybook ./meu-projeto
+  cao-comp base-button ./meu-projeto/src/app/components && cao-comp storybook ./meu-projeto
+`;
+
+const STORYBOOK_FILES = {
+  '.storybook/main.ts': `import type { StorybookConfig } from '@storybook/angular-vite';
+
+const config: StorybookConfig = {
+  "stories": [
+    "../src/**/*.mdx",
+    "../src/**/*.stories.@(js|jsx|mjs|ts|tsx)"
+  ],
+  "addons": [
+    "@storybook/addon-essentials",
+    "@storybook/addon-a11y",
+    "@storybook/addon-docs",
+    "@storybook/addon-onboarding"
+  ],
+  "framework": {
+    "name": "@storybook/angular-vite",
+    "options": {
+      "compodoc": false,
+      "compodocArgs": [
+        "-e",
+        "json",
+        "-d",
+        "."
+      ]
+    }
+  }
+};
+export default config;
+`,
+  '.storybook/preview.ts': `import type { Preview } from '@storybook/angular-vite';
+
+// Para habilitar as docs automaticas (argTypes) com Compodoc:
+// 1. Gere o documentation.json:  npx @compodoc/compodoc -p tsconfig.json -e json -d .
+// 2. Coloque "compodoc": true no framework options do .storybook/main.ts
+// 3. Descomente as linhas abaixo:
+// import { setCompodocJson } from '@storybook/addon-docs/angular';
+// import docJson from '../documentation.json';
+// setCompodocJson(docJson);
+
+const preview: Preview = {
+  parameters: {
+    controls: {
+      matchers: {
+        color: /(background|color)$/i,
+        date: /Date$/i,
+      },
+    },
+  },
+};
+
+export default preview;
+`,
+  '.storybook/tsconfig.json': `{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "allowSyntheticDefaultImports": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "types": ["node"]
+  },
+  "include": ["../src/**/*.stories.*", "./preview.ts", "./main.ts", "./typings.d.ts"]
+}
+`,
+  '.storybook/typings.d.ts': `declare module '*.md';
+`,
+};
+
+const EXAMPLE_STORY_LINES = [
+  `import { Component, EventEmitter, Input, Output } from '@angular/core';`,
+  `import type { Meta, StoryObj } from '@storybook/angular-vite';`,
+  `import { fn } from 'storybook/test';`,
+  ``,
+  `@Component({`,
+  `  standalone: true,`,
+  `  selector: 'storybook-example-button',`,
+  `  template: \``,
+  `    <button`,
+  `      type="button"`,
+  `      (click)="onClick.emit()"`,
+  `      [disabled]="isDisabled"`,
+  `      style="padding:10px 18px;font-size:14px;cursor:pointer;border-radius:6px;border:1px solid #4f46e5;background:#4f46e5;color:#fff;">`,
+  `      {{ label }}`,
+  `    </button>`,
+  `  \`,`,
+  `})`,
+  `export class StorybookExampleButtonComponent {`,
+  `  @Input() label = 'Clique!';`,
+  `  @Input() isDisabled = false;`,
+  `  @Output() readonly onClick = new EventEmitter<void>();`,
+  `}`,
+  ``,
+  `const meta: Meta<StorybookExampleButtonComponent> = {`,
+  `  title: 'Exemplo/Cao Button',`,
+  `  component: StorybookExampleButtonComponent,`,
+  `  tags: ['autodocs'],`,
+  `  args: { onClick: fn() },`,
+  `};`,
+  ``,
+  `export default meta;`,
+  `type Story = StoryObj<StorybookExampleButtonComponent>;`,
+  ``,
+  `export const Default: Story = {`,
+  `  args: { label: 'Clique!' },`,
+  `};`,
+  ``,
+  `export const ComIconeTexto: Story = {`,
+  `  args: { label: 'Salvar' },`,
+  `};`,
+  ``,
+  `export const Desabilitado: Story = {`,
+  `  args: { label: 'Bloqueado', isDisabled: true },`,
+  `};`,
+  ``,
+];
+
+const STORYBOOK_SETUP_DOC = `# Storybook — Setup gerado pelo cao-comp
+
+Este diretorio contem o setup minimo do Storybook para visualizar os
+componentes da lib ngx-opalbytes-components em um projeto externo.
+
+## 1. Instalar as dependencias (no destino)
+
+Adicione as dependencias de desenvolvimento:
+
+\`\`\`bash
+npm i -D storybook @storybook/angular-vite @storybook/addon-essentials @storybook/addon-a11y @storybook/addon-docs @storybook/addon-onboarding @compodoc/compodoc
+\`\`\`
+
+Certifique-se de que as peer dependencies dos componentes estao instaladas:
+\`@angular/core\`, \`@angular/common\`, \`@angular/material\`, \`@angular/cdk\`,
+\`@lucide/angular\` e \`ngx-mask\`.
+
+## 2. Copiar os componentes que deseja visualizar
+
+\`\`\`bash
+cao-comp base-button ./src/app/components
+cao-comp base-input ./src/app/components
+cao-comp --list   # lista todos os componentes disponiveis
+\`\`\`
+
+## 3. Criar stories para os componentes copiados
+
+Abra \`src/stories/CaoButton.stories.ts\` (exemplo gerado) ou crie arquivos
+\`*.stories.ts\` junto dos componentes. Exemplo:
+
+\`\`\`ts
+import type { Meta, StoryObj } from '@storybook/angular-vite';
+import { fn } from 'storybook/test';
+import { CaoBaseButtonComponent } from '../../app/components/base-button/base-button.component';
+
+const meta: Meta<CaoBaseButtonComponent> = {
+  title: 'Components/Base Button',
+  component: CaoBaseButtonComponent,
+  tags: ['autodocs'],
+  args: { buttonClick: fn() },
+};
+
+export default meta;
+type Story = StoryObj<CaoBaseButtonComponent>;
+
+export const Default: Story = { args: { buttonText: 'Clique!' } };
+export const ComIcone: Story = { args: { buttonText: 'Salvar', leadingIcon: 'Save', isLucideIcon: true } };
+\`\`\`
+
+## 4. Rodar
+
+\`\`\`bash
+# Servidor de desenvolvimento (porta 6006)
+npx storybook dev -c .storybook -p 6006
+
+# Build estatico
+npx storybook build -c .storybook -o storybook-static
+\`\`\`
+
+Dica: adicione ao package.json do projeto de destino:
+
+\`\`\`json
+{
+  "scripts": {
+    "storybook": "storybook dev -c .storybook -p 6006",
+    "build-storybook": "storybook build -c .storybook -o storybook-static"
+  }
+}
+\`\`\`
+
+## Opcional: Compodoc (docs automaticas)
+
+1. Gere o JSON de documentacao na raiz do destino:
+   \`\`\`bash
+   npx @compodoc/compodoc -p tsconfig.json -e json -d .
+   \`\`\`
+2. No \`.storybook/main.ts\`, altere \`"compodoc": false\` para \`"compodoc": true\`.
+3. No \`.storybook/preview.ts\`, descomente o bloco do Compodoc.
+
+> O \`--force\` sobrescreve os arquivos gerados pelo cao-comp no destino.
 `;
 
 function resolveTemplatesDir() {
@@ -86,6 +292,57 @@ function copyRecursive(src, dest, force, conflicts) {
   }
 }
 
+function writeFileIfAllowed(filePath, content, force, conflicts) {
+  if (fs.existsSync(filePath) && !force) {
+    conflicts.push(filePath);
+    return false;
+  }
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, content);
+  return true;
+}
+
+function setupStorybook(destination, force) {
+  const root = path.resolve(destination);
+  const conflicts = [];
+  const created = [];
+
+  for (const [rel, content] of Object.entries(STORYBOOK_FILES)) {
+    const file = path.join(root, rel);
+    if (writeFileIfAllowed(file, content, force, conflicts)) {
+      created.push(path.relative(root, file));
+    }
+  }
+
+  const storyFile = path.join(root, 'src', 'stories', 'CaoButton.stories.ts');
+  if (writeFileIfAllowed(storyFile, EXAMPLE_STORY_LINES.join('\n'), force, conflicts)) {
+    created.push(path.relative(root, storyFile));
+  }
+
+  const docFile = path.join(root, 'STORYBOOK-SETUP.md');
+  if (writeFileIfAllowed(docFile, STORYBOOK_SETUP_DOC, force, conflicts)) {
+    created.push(path.relative(root, docFile));
+  }
+
+  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(
+    `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`
+  );
+  return 0;
+}
+
 function parseArgs(argv) {
   const positionals = [];
   const flags = { help: false, list: false, force: false, version: false };
@@ -146,7 +403,20 @@ function main() {
     return 0;
   }
 
-  const [component, destination] = positionals;
+  const [first, second] = positionals;
+
+  if (first === 'storybook') {
+    if (!second) {
+      process.stderr.write(
+        'Erro: informe o destino do Storybook.\n\n' + USAGE + '\n'
+      );
+      return 1;
+    }
+    return setupStorybook(second, flags.force);
+  }
+
+  const component = first;
+  const destination = second;
   if (!component || !destination) {
     process.stderr.write(
       'Erro: informe o componente e o destino.\n\n' + USAGE + '\n'
@@ -183,4 +453,4 @@ function main() {
   return 0;
 }
 
-process.exit(main());
+process.exit(main());