@synthex-engineers/refined-tech 0.0.0-stage → 1.0.1

package/README.md

@@ -1,3 +1,188 @@
-# Temporary Holding Version
+# @synthex/refined-tech
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Librería canónica oficial de diseño, tokens y componentes UI multi-framework (Angular 19+, React 19+, HTML/Tailwind) con catálogo interactivo y sincronización automática para el ecosistema **Synthex**.
+
+---
+
+## 1. Instalación y Consumo en Proyectos
+
+Gracias a la configuración de **npm workspaces** en la raíz del monorepo (`synthex/package.json`), el paquete está enlazado simbólicamente de forma automática en todos los proyectos (`brand/landing`, `synthex-gym-erp/web`, `synthex-ledger/web`).
+
+Para añadirlo explícitamente en el `package.json` de cualquier proyecto del monorepo:
+
+```json
+{
+  "dependencies": {
+    "@synthex/refined-tech": "file:../../brand/synthex-refined-tech"
+  }
+}
+```
+
+Al utilizar enlaces simbólicos nativos (`symlink`), **cualquier cambio realizado en los componentes o tokens de Synthex Refined Tech se actualiza automáticamente en tus proyectos en tiempo real**, sin necesidad de compilaciones manuales intermedias ni publicaciones a npm.
+
+---
+
+## 2. Puntos de Entrada y Uso
+
+### A. Componentes Angular 19+ (Standalone)
+
+```typescript
+import {
+  ButtonPrimaryComponent,
+  ButtonSecondaryComponent,
+  ButtonOutlineComponent,
+  CommandKTriggerComponent,
+  TimerWidgetComponent,
+  MetricCardComponent,
+  BentoCardComponent,
+  BadgeStatusComponent,
+  InputTextComponent,
+  ToggleSwitchComponent,
+  ManifestoIconBoxComponent,
+  WorkspaceSwitcherComponent,
+  TableLedgerRowComponent,
+  MagicLinkCardComponent,
+  PreloaderComponent,
+  FooterBounceComponent,
+  MagneticButtonComponent,
+} from '@synthex/refined-tech/angular';
+
+@Component({
+  imports: [ButtonPrimaryComponent, CommandKTriggerComponent],
+  template: `
+    <st-button-primary (onClick)="handleSubmit()">Confirmar Acción</st-button-primary>
+    <st-command-k-trigger (onOpen)="openCommandPalette()"></st-command-k-trigger>
+  `
+})
+export class MiComponente {}
+```
+
+### B. Componentes React 19+ (TypeScript)
+
+```tsx
+import {
+  ButtonPrimary,
+  ButtonSecondary,
+  ButtonOutline,
+  CommandKTrigger,
+  TimerWidget,
+  MetricCard,
+  BentoGridCard,
+  BadgeStatus,
+  InputText,
+  ToggleSwitch,
+  ManifestoIconBox,
+  WorkspaceSwitcher,
+  TableLedgerRow,
+  MagicLinkCard,
+  Preloader,
+  FooterBounce,
+  MagneticButton,
+} from '@synthex/refined-tech/react';
+
+export function MiPanel() {
+  return (
+    <div className="flex gap-4">
+      <ButtonPrimary onClick={() => console.log('Confirmado')}>
+        Confirmar Acción
+      </ButtonPrimary>
+      <CommandKTrigger onOpen={() => console.log('Paleta')} />
+    </div>
+  );
+}
+```
+
+### C. Tokens Canónicos de Diseño
+
+```typescript
+import { colors, fonts, radii, shadows, borders, tokens } from '@synthex/refined-tech/tokens';
+
+console.log(colors.pistachio);    // #E0F9B5
+console.log(colors.charcoal);     // #111111
+console.log(colors.slateSurface); // #1E1E1E
+console.log(fonts.display);       // 'Outfit', ...
+```
+
+### D. Tokens CSS (:root)
+
+```css
+@import '@synthex/refined-tech/css';
+```
+
+### E. Preset Oficial de Tailwind CSS
+
+En tu archivo `tailwind.config.mjs`:
+
+```javascript
+import refinedTechPreset from '@synthex/refined-tech/tailwind-preset';
+
+export default {
+  presets: [refinedTechPreset],
+  content: ['./src/**/*.{html,ts,tsx,astro}'],
+  // ...
+};
+```
+
+---
+
+## 3. Motor de Sincronización Automática
+
+El script `scripts/sync-components.js` gestiona la arquitectura *"1 Componente = 1 ID Canónico + 1 Carpeta por Tecnología"*:
+
+1. **Inspección Dinámica:** Escanea recursivamente `src/components/library/`.
+2. **Generación de Barriles:** Regenera de forma atómica:
+   - `src/components/library/angular/index.ts`
+   - `src/components/library/react/index.ts`
+3. **Registro Maestro:** Actualiza `registry/components.json` y los archivos `meta.json` de cada componente.
+4. **Ganchos Automáticos (Hooks):**
+   - Se ejecuta automáticamente antes de `npm run dev`, `npm run build` y `npm test` (`predev`, `prebuild`, `pretest`).
+   - El modo `npm run dev` incorpora un vigilante de archivos (`fs.watch`) para resincronizar en caliente cualquier componente que crees o modifiques al instante.
+
+---
+
+## 4. Comandos de Flujo de Trabajo
+
+- **Iniciar servidor de desarrollo y catálogo interactivo:**
+  ```bash
+  npm run dev
+  ```
+- **Sincronizar manualmente componentes y barriles:**
+  ```bash
+  npm run sync
+  ```
+- **Ejecutar suite completa de tests TDD (Vitest):**
+  ```bash
+  npm test
+  ```
+- **Comprobar tipado estricto Astro / TypeScript:**
+  ```bash
+  npm run check
+  ```
+- **Compilar para producción:**
+  ```bash
+  npm run build
+  ```
+
+---
+
+## 5. Catálogo de los 17 Componentes Canónicos
+
+| ID Canónico | Slug | Nombre | Angular | React | HTML | Animación |
+| :--- | :--- | :--- | :---: | :---: | :---: | :---: |
+| `SRT-BTN-01` | `button-primary` | Botón Primario Pistacho | ✓ | ✓ | ✓ | — |
+| `SRT-BTN-02` | `button-secondary` | Botón Secundario Pizarra | ✓ | ✓ | ✓ | — |
+| `SRT-BTN-03` | `button-outline` | Botón Contorno Técnico | ✓ | ✓ | ✓ | — |
+| `SRT-TMR-01` | `timer-widget` | Widget de Cronómetro Monospace | ✓ | ✓ | ✓ | — |
+| `SRT-CMD-01` | `command-k-trigger` | Disparador Command K | ✓ | ✓ | ✓ | — |
+| `SRT-CRD-01` | `metric-card` | Tarjeta Métrica Bento | ✓ | ✓ | ✓ | — |
+| `SRT-CRD-02` | `bento-grid-card` | Tarjeta Bento de Ingeniería | ✓ | ✓ | ✓ | — |
+| `SRT-BDG-01` | `badge-status` | Badge de Estado Técnico | ✓ | ✓ | ✓ | — |
+| `SRT-INP-01` | `input-text` | Campo de Entrada Micro-Borde | ✓ | ✓ | ✓ | — |
+| `SRT-TGL-01` | `toggle-switch` | Interruptor Toggle Booleano | ✓ | ✓ | ✓ | — |
+| `SRT-ICN-01` | `manifesto-icon-box` | Caja Isotipo Squircle | ✓ | ✓ | ✓ | — |
+| `SRT-SWT-01` | `workspace-switcher` | Selector de Workspace Multi-Empresa | ✓ | ✓ | ✓ | — |
+| `SRT-TBL-01` | `table-ledger-row` | Fila de Ledger Criptográfico | ✓ | ✓ | ✓ | — |
+| `SRT-MLC-01` | `magic-link-card` | Tarjeta Acceso Magic Link | ✓ | ✓ | ✓ | — |
+| `SRT-GSAP-PRE01` | `gsap-preloader` | Preload Metamorfosis Geométrica | ✓ | ✓ | ✓ | GSAP MorphSVG |
+| `SRT-GSAP-FBT01` | `gsap-footer-bounce` | Rebote Elástico de Footer | ✓ | ✓ | ✓ | GSAP Elastic Curve |
+| `SRT-GSAP-MAG01` | `gsap-magnetic-button` | Botón con Atracción Magnética | ✓ | ✓ | ✓ | GSAP quickTo |