# Arquitectura

TailwindPHP es una adaptación 1:1. El código reproduce la estructura propia de TailwindCSS: los mismos nombres de archivo y la misma organización, y aísla en `src/_tailwindphp/` las partes que *no pueden* adaptarse directamente (PHP no tiene Rust ni V8). Esta página explica el proceso de compilación, la estructura de los archivos fuente, la reimplementación de `lightningcss` y la convención para documentar las diferencias.

## El proceso

Generar CSS consta de varias etapas. No hay un paso de compilación aparte: cada llamada a `tw::generate()` ejecuta todo el proceso.

```
CSS input          (@import "tailwindcss"; @theme { … })
  │
  ▼
┌──────────────┐
│  Parse CSS   │  css-parser.php → ast.php nodes
└──────┬───────┘
       ▼  design system (theme, utilities, variants)
┌──────────────┐
│ Scan content │  candidate.php — extract class names from HTML
└──────┬───────┘
       ▼  candidates
┌──────────────┐
│   Compile    │  compile.php — candidate → AST, via design-system.php
└──────┬───────┘
       ▼  AST
┌──────────────┐
│   Optimize   │  _tailwindphp/LightningCss.php — nesting, @media, calc()
└──────┬───────┘
       ▼
┌──────────────┐
│  Serialize   │  ast.php toCss()   (minified when requested)
└──────┬───────┘
       ▼
CSS output
```

**Análisis sintáctico.** `css-parser.php` lee la entrada CSS —`@import`, `@theme`, `@utility`, `@layer` y reglas sin procesar— y la convierte en un árbol de sintaxis abstracta compuesto por nodos `ast.php` (reglas de estilo, reglas at y declaraciones). En esta etapa se resuelven y sustituyen las directivas `@import` para módulos virtuales (`tailwindcss`, `tailwindcss/preflight`, …) y las rutas de archivos.

**Construcción del sistema de diseño.** `theme.php` resuelve los valores del tema (colores, espaciado y puntos de interrupción) a partir de los bloques `@theme` analizados y los valores predeterminados. `design-system.php` es el registro central que conecta el tema con las búsquedas de utilidades y variantes definidas en `utilities.php` y `variants.php`.

**Análisis del contenido.** `candidate.php` extrae candidatos a nombres de clase del contenido proporcionado (HTML y plantillas) y analiza cada uno en sus partes: utilidad base, variantes, modificadores, valores arbitrarios y marca de importancia.

**Compilación.** `compile.php` convierte cada candidato en nodos AST buscándolo en el sistema de diseño y aplicando sus variantes y modificadores. Se descartan los candidatos que no correspondan a una utilidad real.

**Serialización y optimización.** `ast.php` recorre el árbol con su `toCss()` (ayudantes en `walk.php`) y genera la cadena CSS. Se aplican las transformaciones equivalentes a `lightningcss` de `_tailwindphp/LightningCss.php` para que el resultado coincida con el que genera TailwindCSS tras su etapa de posprocesamiento de Rust.

**Minificación.** Cuando `minify` está habilitado, `toCss()` genera CSS minificado durante la serialización. `_tailwindphp/CssMinifier.php` se encarga de la etapa independiente de procesamiento de cadenas `tw::minify()`. Consulte [Almacenamiento en caché y minificación](https://tailwindphp.inline0.dev/es/docs/advanced/caching).

## Estructura del código fuente

`src/` reproduce TailwindCSS. El único cambio estructural: el `utilities.ts` de TailwindCSS tiene más de 6,000 líneas, así que se divide en `src/utilities/`, con un archivo por categoría para facilitar el mantenimiento.

```
src/
├── _tailwindphp/                # PHP-specific — NOT part of the TailwindCSS port
│   ├── LightningCss.php         # CSS transforms (lightningcss Rust library equivalent)
│   ├── CssMinifier.php          # CSS minification
│   └── lib/                     # Companion library ports (TailwindPHP\Lib\*)
│       ├── clsx/                # clsx port
│       ├── tailwind-merge/      # tailwind-merge port
│       └── cva/                 # CVA port
│
├── plugin/                      # Plugin system
│   └── plugins/
│       ├── typography-plugin.php  # @tailwindcss/typography port
│       └── forms-plugin.php       # @tailwindcss/forms port
│
├── utilities/                   # Split from TailwindCSS utilities.ts (one file per category)
│   ├── accessibility.php        # sr-only, forced-colors
│   ├── backgrounds.php          # bg-*, gradient-*, from-*, via-*, to-*
│   ├── borders.php              # border-*, rounded-*, divide-*, outline-*
│   ├── effects.php              # shadow-*, opacity-*, mix-blend-*
│   ├── filters.php              # blur-*, brightness-*, contrast-*, …
│   ├── flexbox.php              # flex-*, grid-*, gap-*, justify-*, align-*
│   ├── interactivity.php        # cursor-*, scroll-*, touch-*, select-*
│   ├── layout.php               # display, position, z-*, overflow-*, …
│   ├── masks.php                # mask-linear-*, mask-radial-*, mask-conic-*
│   ├── sizing.php               # w-*, h-*, min-*, max-*, size-*
│   ├── spacing.php              # m-*, p-*, space-*
│   ├── svg.php                  # fill-*, stroke-*
│   ├── tables.php               # border-collapse, table-layout
│   ├── transforms.php           # translate-*, rotate-*, scale-*, skew-*
│   ├── transitions.php          # transition-*, duration-*, ease-*, delay-*
│   └── typography.php           # font-*, text-*, leading-*, tracking-*
│
├── utils/                       # Helper functions (ported from utils/)
│
├── index.php                    # Main entry — compile(), cn(), variants(), merge(), join()
├── ast.php                      # AST nodes and toCss()
├── candidate.php                # Candidate parsing (class name → parts)
├── compile.php                  # Candidate to CSS compilation
├── css-functions.php            # theme(), --theme(), --spacing(), --alpha()
├── css-parser.php               # CSS parsing
├── design-system.php            # Central registry for utilities/variants
├── plugin.php                   # Plugin system (PluginInterface, PluginAPI, PluginManager)
├── theme.php                    # Theme value resolution
├── utilities.php                # Utility registration and lookup
├── value-parser.php             # CSS value parsing
├── variants.php                 # Variant handling (hover, focus, responsive, …)
└── walk.php                     # AST traversal
```

## El equivalente a lightningcss

TailwindCSS delega el posprocesamiento de CSS —anidamiento, gestión de consultas de medios y simplificación de valores— en [lightningcss](https://lightningcss.dev/), un analizador, transformador y minificador escrito en Rust. PHP no puede cargar una biblioteca Rust, así que `src/_tailwindphp/LightningCss.php` vuelve a implementar las transformaciones de las que realmente depende TailwindPHP y produce una salida idéntica byte por byte para los casos que cubre el conjunto de pruebas.

Las transformaciones confirmadas incluyen:

| Transformación | Qué hace |
|-----------|--------------|
| Aplanamiento de anidamiento | Resuelve los selectores `&` con las reglas `:is(…)` de la referencia y aplana las reglas anidadas (`handleNesting()` en `ast.php`, un port del proceso TailwindCSS); `transformNesting` reduce de nivel el anidamiento restante por debajo del primer nivel que contiene declaraciones |
| Aplanamiento de reglas condicionales | Aplana en su lugar las reglas anidadas `@media`, `@supports`, `@container` y `@starting-style`, conserva el orden del código fuente y combina solo las reglas hermanas directamente adyacentes que tienen condiciones idénticas |
| Orden de las declaraciones | Reordena las declaraciones según la cadena de manejadores de declaraciones de lightningcss para que las propiedades aparezcan en el orden de la referencia (`reorderDeclarations`) |
| Simplificación de `calc()` | Simplifica las expresiones `calc()` (`simplifyCalcExpressions`) |
| Eliminación de ceros iniciales | `0.5` → `.5` (`normalizeLeadingZeros`) |
| Espaciado de funciones de transformación | Normaliza los espacios dentro de las funciones de transformación (`normalizeTransformFunctions`) |
| Normalización de valores de cuadrícula | Añade espacios alrededor de `/` en los valores span; convierte los enteros sin unidad a px para `grid-template-*` (`normalizeGridValues`) |
| Normalización de colores | Normaliza la sintaxis de color y evalúa `color-mix()` como `oklab()` (`normalizeColors`, `evaluateColorMix`) |
| Comillas de URL | `url(./x.jpg)` → `url("./x.jpg")` (`normalizeUrlQuoting`) |
| Prefijos de proveedor | Prefijado equivalente a Autoprefixer (`addVendorPrefixes`) |

Este archivo está aislado deliberadamente en `_tailwindphp/` y marcado como `@port-deviation:replacement`: representa una dependencia externa en lugar de portar el código fuente de TailwindCSS.

## Marcadores de desviación del port

Cada archivo de implementación incluye marcadores `@port-deviation:*` en su bloque de documentación que indican dónde y por qué la implementación de PHP difiere de la versión original de TypeScript. Así, quien compare PHP con el código fuente de TailwindCSS no tendrá que preguntarse si una diferencia es intencional.

| Marcador | Significado |
|--------|---------|
| `@port-deviation:none` | Port directo 1:1 sin desviaciones importantes |
| `@port-deviation:async` | PHP usa código síncrono en lugar de async/await |
| `@port-deviation:storage` | Estructuras de datos diferentes (matriz PHP frente a Map/Set de JS) |
| `@port-deviation:types` | Anotaciones PHPDoc en lugar de tipos de TypeScript |
| `@port-deviation:sourcemaps` | Se omite el seguimiento de mapas de origen |
| `@port-deviation:enum` | Constantes de PHP en lugar de enumeraciones de TypeScript |
| `@port-deviation:errors` | Enfoque diferente para gestionar errores |
| `@port-deviation:replacement` | Implementación de PHP que sustituye una biblioteca externa (e.g. lightningcss) |
| `@port-deviation:helper` | Ayudante específico de PHP que no existe en el original |
| `@port-deviation:performance` | Optimización específica de PHP que conserva una salida idéntica |
| `@port-deviation:omitted` | Módulo o función completa no portada (fuera del alcance) |

Consulta los marcadores `@port-deviation:performance` y cómo se garantiza la paridad en [Rendimiento y pruebas](https://tailwindphp.inline0.dev/es/docs/advanced/performance).