@robosophy/ui-vue 1.1.12 → 1.1.13

package/icon-scanner.md

@@ -1,293 +1,388 @@
-# Icon Scanner — @robosophy/ui-vue
-
-## Overview
-
-The Vite plugin `robosophyMaterialSymbols()` automatically detects which Material Symbols
-icons are used in source code and generates an SVG sprite with only those icons.
-No fonts are loaded.
-
-The scanner works at **build time** (and in dev mode via file watching).
-It scans every `.vue`, `.ts`, `.tsx`, `.js`, `.jsx`, and `.mjs` file in the project's `src/` directory
-(or custom `roots`), extracts icon names, families, and weights, then downloads the matching SVGs
-from the Google Material Design Icons repository.
-
-When the package is built (`npm run build`), a **pre-scan** (the manifest script in
-`scripts/generate-icon-manifest.mjs`) identifies icons used by the library's own components
-(`RsSidebar`, `RsAccountSelector`, etc.) and writes them to `dist/icon-manifest.json`.
-The Vite plugin loads this manifest at dev/build time as a baseline, then adds icons found
-by scanning the consuming project's source.
-
----
-
-## Detection Patterns
-
-The scanner uses five patterns to find icon usage in source code.
-Patterns 4 and 5 were added for cases that the original three could not handle.
-
-### Pattern 1: `<RsIcon>` Component Tag
-
-**Regex:** `/ <RsIcon\b([^>]*)>/g`
-
-Parses the attributes with `parseStaticAttributes` and reads `name`, `:name`, `family`,
-`:family`, `weight`, `:weight`.
-
-**Detected:**
-```vue
-<RsIcon name="home" />
-<RsIcon name="home" family="rounded" />
-<RsIcon :name="cond ? 'home' : 'settings'" family="rounded" />
-<RsIcon name="home" weight="200" />
-```
-
-**Not detected** (variable references):
-```vue
-<RsIcon :name="iconVar" />
-<RsIcon :name="item.icon" />
-```
-
-**Filter:** icon names must match `/^[a-z0-9_]+$/` (lowercase with underscores).
-
-**Dynamic `:name` with ternaries:** any string literal inside the `:name` expression
-is extracted. For example `:name="cond ? 'add' : 'remove'"` extracts both `add` and `remove`.
-
-**Dynamic `:name` without string literals:** if the binding is a plain variable reference
-like `:name="current_icon"`, the scanner no longer treats it as an icon name
-(improvement 3, see changelog). Use `include` or magic comments for these cases.
-
-### Pattern 2: `rsPrimeIcon()` Helper
-
-**Regex:** `/\brsPrimeIcon\(\s*["']([a-z0-9_]+)["'](?:\s*,\s*\{([^)]*)\})?/g`
-
-**Detected:**
-```ts
-rsPrimeIcon("home")
-rsPrimeIcon('settings', { family: 'rounded' })
-```
-
-**Not detected:**
-```ts
-rsPrimeIcon(dynamicName)
-```
-
-### Pattern 3: Object Literal `icon:` Property
-
-**Regex:** `/\bicon\s*:\s*["']([a-z0-9_]+)["']/g`
-
-After matching, the scanner finds the enclosing `{...}` object and extracts `weight` and
-`family` from its body (using `findEnclosingObject`). Comments are stripped from the body
-before searching for these properties.
-
-**Detected:**
-```ts
-const items = [
-  { label: "Inbox", icon: "inbox" },
-  { label: "Settings", icon: "settings", family: "rounded", weight: 200 },
-];
-```
-
-**Not detected** (no `icon:` string literal):
-```ts
-const items = [{ icon: dynamicVar }];  // variable reference
-{ icon }  // shorthand property
-{ ["icon"]: "home" }  // computed property
-```
-
-**`findEnclosingObject` behavior:**
-- Scans backward from the `icon:` match to find the nearest opening `{`
-- Skips over strings, template literals, escaped quotes, and comments (`//` and `/* */`)
-- Scans forward to find the matching `}`
-- Returns the body content between `{` and `}`
-- The body is then cleaned of comments before searching for `weight:` and `family:`
-
-```ts
-// This correctly reads weight=200 and family="rounded":
-{ icon: "home", weight: 200, family: "rounded" }
-
-// Comments are ignored:
-{ /* weight: 200, family: "rounded" */ icon: "home" }
-// → default weight 400, default family "outlined"
-```
-
-### Pattern 4: Magic Comments
-
-**Regex:** `/\/\/\s*@robosophy-icon:\s*([a-z0-9_]+)(?:\s+family=(\w+))?(?:\s+weight=(\d+))?/g`
-
-For cases where the scanner cannot detect an icon statically (props, variables, API responses,
-computed properties), use magic comments to declare them explicitly.
-
-**Usage:**
-```ts
-// @robosophy-icon: home
-// @robosophy-icon: settings family=rounded
-// @robosophy-icon: warning weight=200
-// @robosophy-icon: manage_accounts family=rounded weight=200
-
-const sidebarItems = [
-  { id: "home", label: "Home", icon: "home" },
-  { id: "settings", label: "Settings", icon: "settings" },
-];
-```
-
-**Best for:**
-- Icon names passed as props to parent components
-- Icon names in constants, enums, or configuration objects
-- Icon names from API responses
-- Icon names in computed properties or functions
-
-**Placement:** anywhere in the source file. The scanner reads the entire file content.
-
-### Pattern 5: Arrays of Icon Strings
-
-**Regex:** `/\/\/\s*@robosophy-icon:\s*([a-z0-9_]+)(?:\s+family=(\w+))?(?:\s+weight=(\d+))?/g`
-
-Wait, that's the same as Pattern 4. Let me check the actual regex I used...
-
-Actually, Pattern 5 detects arrays assigned to variables whose name contains "icon" (case-insensitive).
-
-**Regex:** `/(?:const|let|var)\s+(\w*[Ii]con\w*)\s*=\s*\[/g`
-
-After finding the start of an icon array, it extracts all string literals from the brackets.
-
-**Detected:**
-```ts
-const iconNames = ["home", "settings", "info"];
-const sidebarIcons = ["home", "search"];
-const ICON_LIST = ["warning", "error"];
-```
-
-**Not detected** (no "icon" in variable name):
-```ts
-const names = ["home", "settings"];  // variable name doesn't contain "icon"
-const items = [{ icon: "home" }];     // already handled by Pattern 3
-```
-
-**Caveat:** This pattern uses a heuristic (variable name contains "icon"). It may miss icons
-stored in arrays with unrelated names. Use magic comments for those.
-
----
-
-## Plugin Options
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `include` | `IconInput[]` | `[]` | Icons to include regardless of detection. Each entry is a string (name) or `{ family, name, weight? }`. If weight is omitted, all valid weights (100-700) are included. |
-| `scan` | `boolean` | `true` | Set to `false` to disable source scanning entirely. All icons must be in `include`. |
-| `roots` | `string[]` | `["./src"]` | Directories to scan for icon usage. |
-| `outputDir` | `string` | `"assets"` | Output directory for the SVG sprite. |
-| `fontDisplay` | `string` | — | CSS `font-display` value. |
-| `preload` | `boolean` | `false` | Preload the SVG sprite in the `<head>`. |
-
----
-
-## `icon-manifest.json`
-
-The build script (`scripts/generate-icon-manifest.mjs`) scans the library's own components
-under `src/components/` and produces `dist/icon-manifest.json`.
-
-**File format:**
-```json
-{
-  "outlined": ["home", "search", "settings"],
-  "rounded": ["settings"],
-  "sharp": []
-}
-```
-
-**Role in the pipeline:**
-1. Build generates the manifest from the library's component source
-2. Vite plugin loads the manifest as a baseline
-3. Plugin then scans the consuming project's source for additional icons
-4. Plugin fetches SVGs for the combined set
-
-**Why not just use the manifest alone?**
-The manifest ensures that icons required by library components are always available,
-even if the consuming project doesn't use those components. However, the manifest may
-include icons that the consumer never uses (it's a conservative baseline). The plugin's
-source scan adds only the icons that the consumer's own code references.
-
----
-
-## Known Limitations
-
-### Icon names passed as props
-
-```vue
-<!-- RsSidebar uses :name="icon" which is a prop -->
-<RsIcon :name="icon" />
-
-<!-- RsSidebar uses :name="item.icon" from v-for iteration -->
-<RsIcon :name="item.icon" />
-```
-
-The scanner cannot resolve the runtime value of `icon` or `item.icon`.
-
-**Solutions:**
-1. Use `include` in the Vite plugin config
-2. Add magic comments (`// @robosophy-icon: icon_name`) in the component file
-3. Declare the icon in the same file as the data source (Pattern 3 will detect it)
-
-### Icon names in arrays of strings
-
-```ts
-const iconNames = ["home", "settings"];
-```
-
-Pattern 5 detects these only if the variable name contains "icon".
-
-### Icon names in enums or constants
-
-```ts
-export enum Icons {
-  HOME = "home",
-  SETTINGS = "settings",
-}
-```
-
-Not detected. Use magic comments or `include`.
-
-### Icon names from API responses
-
-```ts
-const config = await fetchConfig();
-return <RsIcon :name="config.iconName" />;
-```
-
-Cannot be detected statically. Use `include` or magic comments.
-
----
-
-## Best Practices
-
-### For AI agents editing consuming projects
-
-1. **Static icons:** use `<RsIcon name="icon_name" />` — always detected by Pattern 1
-2. **Object configs:** use `{ icon: "icon_name" }` — detected by Pattern 3
-3. **Dynamic icons:** use magic comments or `include`
-4. **PrimeVue buttons:** use `rsPrimeIcon('icon_name')` — detected by Pattern 2
-5. **Props to RsSidebar:** icons in the `items` array objects are detected by Pattern 3
-
-### For humans
-
-When adding a new icon to the codebase:
-1. Check if it's statically detectable (direct string literal)
-2. If not, add a magic comment near the usage
-3. If the icon is used in many places, add it to the plugin config's `include`
-
-### Tag helper
-
-To quickly test if an icon name exists in the Material Symbols set:
-
-```
-https://fonts.google.com/icons?icon.query=icon_name
-```
-
----
-
-## Changelog
-
-| Date | Change |
-|------|--------|
-| 2026-07-13 | **Pattern 4** (magic comments) and **Pattern 5** (icon arrays) added |
-| 2026-07-13 | `findEnclosingObject`: now handles comments, escaped quotes, and template literals |
-| 2026-07-13 | `resolveNames`: dynamic `:name` bindings no longer fall back to treating variable names as icon names |
-| 2026-07-13 | Pattern 3: weight and family are now extracted from the enclosing object literal |
+# Icon Scanner — @robosophy/ui-vue
+
+## Overview
+
+`robosophyMaterialSymbols()` es un plugin de Vite que genera un sprite SVG con solo los
+iconos de **Material Symbols** que tu codigo realmente usa. Sin fuentes tipograficas,
+sin subset fonts, sin dependencias npm.
+
+**Pipeline:**
+
+```
+source code → scan (8 patterns) → merge with manifest → download SVGs → inline SVG sprite
+```
+
+El scanner opera en **build time** y en **dev mode** (con file watching). Escanea archivos
+`.vue`, `.ts`, `.tsx`, `.js`, `.jsx`, y `.mjs` del proyecto, extrae nombres de icono,
+familias y pesos, y descarga los SVGs correspondientes del repositorio oficial de Google.
+
+Los iconos que usan los componentes internos de la libreria (`RsSidebar`, `RsAccountSelector`,
+etc.) se precargan en `dist/icon-manifest.json` durante el build del paquete y se fusionan
+con los detectados en el proyecto consumidor.
+
+---
+
+## Quick Reference
+
+| # | Pattern | Categoria | Detecta | Ejemplo |
+|---|---------|-----------|---------|---------|
+| 1 | `<RsIcon>` tag | Componente | `name` estatico + ternarias | `<RsIcon name="home" />` |
+| 2 | `rsPrimeIcon()` | Componente | String literal en helper | `rsPrimeIcon("home")` |
+| 3 | `icon:` property | Dato | Objeto con `icon:` key | `{ icon: "home" }` |
+| 5 | Icon arrays | Dato | Array en variable `*icon*` | `const iconNames = ["home"]` |
+| 5b | Icon objects | Dato | Objeto en variable `*icon*` | `const iconMap = { pc: "article" }` |
+| 6a | Component icon prop | Cross-file | `icon=` en tag PascalCase | `<CustomButton icon="home" />` |
+| 6b | Proxy components | Cross-file | Prop forwarding a `<RsIcon :name>` | `<ProxyIcon icon="home" />` |
+| 4 | Magic comments | Fallback | Declaracion explicita | `// @robosophy-icon: home` |
+
+---
+
+## Automatic Detection
+
+Estos 7 patrones se activan solos. No requieren configuracion manual, solo codigo fuente
+donde los nombres de icono aparezcan como **string literals**.
+
+### Component Patterns
+
+#### Pattern 1: `<RsIcon>` tag
+
+**Regex:** `/ <RsIcon\b([\s\S]*?)>/g`
+
+Detecta usos directos del componente `<RsIcon>` con `name` estatico, ternarias en `:name`,
+template literals, y tags multi-linea. Soporta `family`, `:family`, `weight`, `:weight`.
+
+**Detectado:**
+```vue
+<RsIcon name="home" />
+<RsIcon name="home" family="rounded" />
+<RsIcon :name="cond ? 'home' : 'settings'" family="rounded" weight="200" />
+<RsIcon
+  name="home"
+  family="rounded"
+/>
+<RsIcon :name="`home`" />
+```
+
+**No detectado** (variables en `:name`):
+```vue
+<RsIcon :name="iconVar" />
+<RsIcon :name="item.icon" />
+<RsIcon v-for="name in list" :name="name" />
+```
+
+> 💡 Si el binding tiene ternarias con string literals, ambas ramas se extraen.
+> Si es solo una variable (`:name="iconProp"`), usa Pattern 3 en la fuente de datos
+> o Magic Comments como ultimo recurso.
+
+---
+
+#### Pattern 2: `rsPrimeIcon()` helper
+
+**Regex:** `/\brsPrimeIcon\(\s*["'`]([a-z0-9_]+)["'`](?:\s*,\s*\{([^)]*)\})?/g`
+
+Detecta el helper que PrimeVue usa como string de clases para `Button.icon`,
+`MenuItem.icon`, etc. Soporta `family` opcional.
+
+**Detectado:**
+```ts
+rsPrimeIcon("home")
+rsPrimeIcon('settings', { family: 'rounded' })
+rsPrimeIcon(`home`)
+```
+
+**No detectado:**
+```ts
+rsPrimeIcon(variableName)
+```
+
+---
+
+### Data Patterns
+
+#### Pattern 3: `icon:` property
+
+**Regex:** `/\bicon\s*:\s*["'`]([a-z0-9_]+)["'`]/g`
+
+Detecta objetos con una propiedad `icon:` y extrae `weight:` y `family:` del mismo objeto.
+Usa `findEnclosingObject` para encontrar los limites del objeto, ignorando comentarios,
+strings escapados y template literals.
+
+**Detectado:**
+```ts
+const items = [
+  { label: "Inbox", icon: "inbox" },
+  { label: "Settings", icon: "settings", family: "rounded", weight: 200 },
+  { icon: `home` },
+]
+```
+
+**No detectado:**
+```ts
+{ icon: dynamicVar }     // variable reference
+{ icon }                 // shorthand property
+{ ["icon"]: "home" }     // computed property key
+```
+
+> 💡 Pattern 3 es la forma mas comun de declarar iconos en datos de navegacion.
+> RsSidebar recibe `items` con `icon:` — se detecta automaticamente.
+
+---
+
+#### Pattern 5: Icon arrays
+
+**Regex:** `/(?:const|let|var)\s+(\w*[Ii]con\w*)\s*=\s*\[/g`
+
+Detecta arrays asignados a variables cuyo nombre contiene "icon" (case-insensitive).
+Extrae strings del nivel superior del array, incluyendo arrays anidados y template literals.
+
+**Detectado:**
+```ts
+const iconNames = ["home", "settings", "info"]
+const sidebarIcons = ["home", "search"]
+const ICON_LIST = ["warning", "error"]
+```
+
+```ts
+// Arrays anidados
+const iconGroups = [
+  ["home", "settings"],   // ✅ detectados
+  "search"                // ✅ detectado
+]
+```
+
+**No detectado:**
+```ts
+const names = ["home", "settings"]   // sin "icon" en nombre
+const items = [{ icon: "home" }]     // Pattern 3 lo cubre
+```
+
+---
+
+#### Pattern 5b: Icon objects
+
+**Regex:** `/(?:const|let|var)\s+(\w*[Ii]con\w*)[^=]*=\s*\{/g`
+
+Detecta objetos literales asignados a variables con "icon" en el nombre y extrae todos
+los string values que matchean el patron de nombre de icono. Soporta anotaciones de tipo
+TypeScript (`: Record<K, V>`) y TypeScript generics con `<>`.
+
+**Detectado:**
+```ts
+const variantIconMap: Record<string, string> = {
+  pc: "article",
+  alta: "account_circle",
+  cc: "account_balance_wallet",
+  cyo: "nest_eco_leaf",
+}
+```
+
+```ts
+const iconConfig = {
+  default: "home",
+  active: "settings",
+}
+```
+
+**No detectado:**
+```ts
+const names = { key: "article" }   // sin "icon" en nombre
+```
+
+> 💡 Pattern 5b fue creado especificamente para `variantIconMap` en RsSidebar,
+> donde las claves son nombres de variante y los valores son iconos.
+
+---
+
+### Cross-file Patterns
+
+#### Pattern 6a: Component icon prop
+
+**Regex:** `/<([A-Z][a-zA-Z0-9_]*)\b([\s\S]*?)>/g`
+
+Detecta el atributo `icon`, `iconName` o `icon-name` en cualquier tag PascalCase
+(excepto `<RsIcon>` que usa `name`). Funciona sin analisis cross-file.
+
+**Detectado:**
+```vue
+<CustomButton icon="home" />
+<AnotherComponent iconName="settings" />
+<ThirdThing icon-name="search" />
+```
+
+**No detectado:**
+```vue
+<RsIcon icon="home" />           <!-- RsIcon usa name, no icon -->
+<CustomButton :icon="var" />     <!-- dynamic binding -->
+```
+
+> 💡 Este patron es util cuando un componente expone un prop `icon` y el valor
+> se pasa como string literal en el template del consumidor.
+
+---
+
+#### Pattern 6b: Proxy components
+
+**Analisis en dos fases:**
+
+1. **Fase 1** — Encuentra componentes que hacen forwarding de un prop a `<RsIcon>`:
+   - Tienen `defineProps` con al menos un prop
+   - Tienen `<RsIcon :name="propName">` donde `propName` es un prop
+   - Tienen `defineOptions({ name: "ComponentName" })`
+2. **Fase 2** — Escanea los consumos de esos componentes y extrae valores del prop `icon`
+
+**Detectado:**
+
+Componente (`CustomIconButton.vue`):
+```vue
+<script setup lang="ts">
+defineOptions({ name: "CustomIconButton" })
+defineProps<{ icon: string }>()
+</script>
+<template>
+  <RsIcon :name="icon" />
+</template>
+```
+
+Consumo (`App.vue`):
+```vue
+<CustomIconButton icon="home" />       <!-- ✅ detectado -->
+<CustomIconButton icon="settings" />   <!-- ✅ detectado -->
+```
+
+**No detectado:**
+- Componentes sin `defineProps`
+- Componentes sin `defineOptions({ name: ... })`
+- Props que no se pasan a `<RsIcon :name="prop">`
+- Bindings dinamicos (`:icon="variable"`)
+
+---
+
+## Manual Fallbacks
+
+Cuando ningun patron automatico detecta tu icono (ej: viene de una API, de un enum,
+o de una variable calculada), tenes dos opciones. **Usalas solo cuando los patrones
+automaticos no alcancen.**
+
+### Magic comments (Pattern 4)
+
+**Regex:** `/(?:\/\/|\/\*)\s*@robosophy-icon:\s*([a-z0-9_]+)/g`
+
+Declara el icono explicitamente en el mismo archivo donde se usa:
+
+```ts
+// @robosophy-icon: manage_accounts
+const item = { icon: props.iconName }
+```
+
+Soporta `family=` y `weight=` opcionales en la misma linea:
+
+```ts
+// @robosophy-icon: settings family=rounded weight=200
+```
+
+### `include` (plugin config)
+
+Para iconos usados en muchos lugares o controlados por configuracion remota:
+
+```ts
+robosophyMaterialSymbols({
+  include: [
+    "home",
+    { family: "rounded", name: "settings", weight: 200 },
+  ],
+})
+```
+
+Si se omite `weight`, se incluyen todos los pesos validos (100-700).
+
+---
+
+## Plugin Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `include` | `IconInput[]` | `[]` | Iconos forzados. String = nombre, objeto = `{ family?, name, weight? }` |
+| `scan` | `boolean` | `true` | `false` desactiva el escaneo. Todos los iconos deben ir en `include` |
+| `roots` | `string[]` | `["./src"]` | Directorios a escanear |
+| `outputDir` | `string` | `"assets"` | Directorio de salida del sprite SVG |
+| `fontDisplay` | `string` | — | CSS `font-display` |
+| `preload` | `boolean` | `false` | Precarga el sprite en el `<head>` |
+
+---
+
+## `icon-manifest.json`
+
+Generado por `scripts/generate-icon-manifest.mjs` durante el build del paquete.
+Escanea `src/components/` y produce `dist/icon-manifest.json`.
+
+```json
+{
+  "outlined": ["home", "search", "settings"],
+  "rounded": ["settings"],
+  "sharp": []
+}
+```
+
+**Rol en el pipeline:**
+1. Build genera el manifiesto desde los componentes de la libreria
+2. Plugin de Vite carga el manifiesto como baseline
+3. Plugin escanea el proyecto consumidor para iconos adicionales
+4. Plugin descarga los SVGs del set combinado
+
+El manifiesto asegura que los iconos de `RsSidebar`, `RsAccountSelector`, etc. esten
+siempre disponibles, incluso si el proyecto consumidor no usa esos componentes.
+
+---
+
+## Best Practices
+
+### Para escribir codigo que se detecta solo
+
+1. **Usa `<RsIcon name="home" />`** — siempre detectado por Pattern 1
+2. **Declara iconos en objetos con `icon:`** — Pattern 3 extrae automaticamente
+3. **Nombra variables con "icon"** cuando almacenes nombres de icono — Patterns 5 y 5b se activan
+4. **Pasa iconos como string literal** a componentes con prop `icon` — Pattern 6a lo detecta
+5. **Usa `rsPrimeIcon("home")`** para PrimeVue — Pattern 2 lo cubre
+
+### Para componentes que envuelven RsIcon
+
+Si creas un componente que recibe un icono por prop y lo pasa a `<RsIcon :name>`:
+
+- Usa `defineProps` con el nombre del prop tipado
+- Usa `defineOptions({ name: "ComponentName" })` para registrar el nombre
+- Pattern 6b lo detectara automaticamente
+
+Ejemplo:
+```vue
+<script setup lang="ts">
+defineOptions({ name: "MyIconButton" })
+defineProps<{ icon: string }>()
+</script>
+<template>
+  <button><RsIcon :name="icon" /></button>
+</template>
+```
+
+### Cuando nada funciona
+
+Usa magic comments o `include` — pero considera si podes reescribir el codigo para
+que el scanner lo detecte automaticamente. Es menos mantenimiento a futuro.
+
+### Testing de nombres
+
+```
+https://fonts.google.com/icons?icon.query=icon_name
+```
+
+---
+
+## Changelog
+
+| Date | Change |
+|------|--------|
+| 2026-07-17 | Documentacion reestructurada: 8 patrones agrupados por categoria, automaticos primero |
+| 2026-07-17 | **Pattern 5b** (icon objects), **Pattern 6a** (component icon prop), **Pattern 6b** (proxy components) added |
+| 2026-07-13 | **Pattern 4** (magic comments) and **Pattern 5** (icon arrays) added |
+| 2026-07-13 | `findEnclosingObject`: ahora maneja comentarios, strings escapados y template literals |
+| 2026-07-13 | `resolveNames`: bindings `:name` dinamicos ya no tratan nombres de variable como iconos |
+| 2026-07-13 | Pattern 3: weight y family se extraen del objeto contenedor |