@robosophy/ui-vue 1.1.12 → 1.2.0

package/icon-scanner.md

@@ -2,280 +2,373 @@
 
 ## 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.
+`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.
 
-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.
+**Pipeline:**
 
-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.
+```
+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.
 
 ---
 
-## Detection Patterns
+## 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` |
 
-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
+## Automatic Detection
 
-**Regex:** `/ <RsIcon\b([^>]*)>/g`
+Estos 7 patrones se activan solos. No requieren configuracion manual, solo codigo fuente
+donde los nombres de icono aparezcan como **string literals**.
 
-Parses the attributes with `parseStaticAttributes` and reads `name`, `:name`, `family`,
-`:family`, `weight`, `:weight`.
+### Component Patterns
 
-**Detected:**
+#### 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" />
-<RsIcon name="home" weight="200" />
+<RsIcon :name="cond ? 'home' : 'settings'" family="rounded" weight="200" />
+<RsIcon
+  name="home"
+  family="rounded"
+/>
+<RsIcon :name="`home`" />
 ```
 
-**Not detected** (variable references):
+**No detectado** (variables en `:name`):
 ```vue
 <RsIcon :name="iconVar" />
 <RsIcon :name="item.icon" />
+<RsIcon v-for="name in list" :name="name" />
 ```
 
-**Filter:** icon names must match `/^[a-z0-9_]+$/` (lowercase with underscores).
+> 💡 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.
 
-**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
 
-### Pattern 2: `rsPrimeIcon()` Helper
+**Regex:** `/\brsPrimeIcon\(\s*["'`]([a-z0-9_]+)["'`](?:\s*,\s*\{([^)]*)\})?/g`
 
-**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.
 
-**Detected:**
+**Detectado:**
 ```ts
 rsPrimeIcon("home")
 rsPrimeIcon('settings', { family: 'rounded' })
+rsPrimeIcon(`home`)
 ```
 
-**Not detected:**
+**No detectado:**
 ```ts
-rsPrimeIcon(dynamicName)
+rsPrimeIcon(variableName)
 ```
 
-### Pattern 3: Object Literal `icon:` Property
+---
 
-**Regex:** `/\bicon\s*:\s*["']([a-z0-9_]+)["']/g`
+### Data Patterns
 
-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.
+#### Pattern 3: `icon:` property
 
-**Detected:**
+**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` },
+]
 ```
 
-**Not detected** (no `icon:` string literal):
+**No detectado:**
 ```ts
-const items = [{ icon: dynamicVar }];  // variable reference
-{ icon }  // shorthand property
-{ ["icon"]: "home" }  // computed property
+{ icon: dynamicVar }     // variable reference
+{ icon }                 // shorthand property
+{ ["icon"]: "home" }     // computed property key
 ```
 
-**`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:`
+> 💡 Pattern 3 es la forma mas comun de declarar iconos en datos de navegacion.
+> RsSidebar recibe `items` con `icon:` — se detecta automaticamente.
 
-```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
+#### Pattern 5: Icon arrays
 
-**Regex:** `/\/\/\s*@robosophy-icon:\s*([a-z0-9_]+)(?:\s+family=(\w+))?(?:\s+weight=(\d+))?/g`
+**Regex:** `/(?:const|let|var)\s+(\w*[Ii]con\w*)\s*=\s*\[/g`
 
-For cases where the scanner cannot detect an icon statically (props, variables, API responses,
-computed properties), use magic comments to declare them explicitly.
+Detecta arrays asignados a variables cuyo nombre contiene "icon" (case-insensitive).
+Extrae strings del nivel superior del array, incluyendo arrays anidados y template literals.
 
-**Usage:**
+**Detectado:**
 ```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" },
-];
+const iconNames = ["home", "settings", "info"]
+const sidebarIcons = ["home", "search"]
+const ICON_LIST = ["warning", "error"]
 ```
 
-**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.
+```ts
+// Arrays anidados
+const iconGroups = [
+  ["home", "settings"],   // ✅ detectados
+  "search"                // ✅ detectado
+]
+```
 
-### Pattern 5: Arrays of Icon Strings
+**No detectado:**
+```ts
+const names = ["home", "settings"]   // sin "icon" en nombre
+const items = [{ icon: "home" }]     // Pattern 3 lo cubre
+```
 
-**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...
+#### Pattern 5b: Icon objects
 
-Actually, Pattern 5 detects arrays assigned to variables whose name contains "icon" (case-insensitive).
+**Regex:** `/(?:const|let|var)\s+(\w*[Ii]con\w*)[^=]*=\s*\{/g`
 
-**Regex:** `/(?:const|let|var)\s+(\w*[Ii]con\w*)\s*=\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 `<>`.
 
-After finding the start of an icon array, it extracts all string literals from the brackets.
+**Detectado:**
+```ts
+const variantIconMap: Record<string, string> = {
+  pc: "article",
+  alta: "account_circle",
+  cc: "account_balance_wallet",
+  cyo: "nest_eco_leaf",
+}
+```
 
-**Detected:**
 ```ts
-const iconNames = ["home", "settings", "info"];
-const sidebarIcons = ["home", "search"];
-const ICON_LIST = ["warning", "error"];
+const iconConfig = {
+  default: "home",
+  active: "settings",
+}
 ```
 
-**Not detected** (no "icon" in variable name):
+**No detectado:**
 ```ts
-const names = ["home", "settings"];  // variable name doesn't contain "icon"
-const items = [{ icon: "home" }];     // already handled by Pattern 3
+const names = { key: "article" }   // sin "icon" en nombre
 ```
 
-**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.
+> 💡 Pattern 5b fue creado especificamente para `variantIconMap` en RsSidebar,
+> donde las claves son nombres de variante y los valores son iconos.
 
 ---
 
-## Plugin Options
+### Cross-file Patterns
 
-| 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>`. |
+#### Pattern 6a: Component icon prop
 
----
-
-## `icon-manifest.json`
+**Regex:** `/<([A-Z][a-zA-Z0-9_]*)\b([\s\S]*?)>/g`
 
-The build script (`scripts/generate-icon-manifest.mjs`) scans the library's own components
-under `src/components/` and produces `dist/icon-manifest.json`.
+Detecta el atributo `icon`, `iconName` o `icon-name` en cualquier tag PascalCase
+(excepto `<RsIcon>` que usa `name`). Funciona sin analisis cross-file.
 
-**File format:**
-```json
-{
-  "outlined": ["home", "search", "settings"],
-  "rounded": ["settings"],
-  "sharp": []
-}
+**Detectado:**
+```vue
+<CustomButton icon="home" />
+<AnotherComponent iconName="settings" />
+<ThirdThing icon-name="search" />
 ```
 
-**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
+**No detectado:**
+```vue
+<RsIcon icon="home" />           <!-- RsIcon usa name, no icon -->
+<CustomButton :icon="var" />     <!-- dynamic binding -->
+```
 
-**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.
+> 💡 Este patron es util cuando un componente expone un prop `icon` y el valor
+> se pasa como string literal en el template del consumidor.
 
 ---
 
-## Known Limitations
+#### Pattern 6b: Proxy components
+
+**Analisis en dos fases:**
 
-### Icon names passed as props
+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
-<!-- RsSidebar uses :name="icon" which is a prop -->
-<RsIcon :name="icon" />
+<script setup lang="ts">
+defineOptions({ name: "CustomIconButton" })
+defineProps<{ icon: string }>()
+</script>
+<template>
+  <RsIcon :name="icon" />
+</template>
+```
 
-<!-- RsSidebar uses :name="item.icon" from v-for iteration -->
-<RsIcon :name="item.icon" />
+Consumo (`App.vue`):
+```vue
+<CustomIconButton icon="home" />       <!-- ✅ detectado -->
+<CustomIconButton icon="settings" />   <!-- ✅ detectado -->
 ```
 
-The scanner cannot resolve the runtime value of `icon` or `item.icon`.
+**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.**
 
-**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)
+### Magic comments (Pattern 4)
 
-### Icon names in arrays of strings
+**Regex:** `/(?:\/\/|\/\*)\s*@robosophy-icon:\s*([a-z0-9_]+)/g`
+
+Declara el icono explicitamente en el mismo archivo donde se usa:
 
 ```ts
-const iconNames = ["home", "settings"];
+// @robosophy-icon: manage_accounts
+const item = { icon: props.iconName }
 ```
 
-Pattern 5 detects these only if the variable name contains "icon".
-
-### Icon names in enums or constants
+Soporta `family=` y `weight=` opcionales en la misma linea:
 
 ```ts
-export enum Icons {
-  HOME = "home",
-  SETTINGS = "settings",
-}
+// @robosophy-icon: settings family=rounded weight=200
 ```
 
-Not detected. Use magic comments or `include`.
+### `include` (plugin config)
 
-### Icon names from API responses
+Para iconos usados en muchos lugares o controlados por configuracion remota:
 
 ```ts
-const config = await fetchConfig();
-return <RsIcon :name="config.iconName" />;
+robosophyMaterialSymbols({
+  include: [
+    "home",
+    { family: "rounded", name: "settings", weight: 200 },
+  ],
+})
 ```
 
-Cannot be detected statically. Use `include` or magic comments.
+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
 
-### For AI agents editing consuming projects
+### Para escribir codigo que se detecta solo
 
-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
+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
 
-### For humans
+### 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>
+```
 
-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`
+### Cuando nada funciona
 
-### Tag helper
+Usa magic comments o `include` — pero considera si podes reescribir el codigo para
+que el scanner lo detecte automaticamente. Es menos mantenimiento a futuro.
 
-To quickly test if an icon name exists in the Material Symbols set:
+### Testing de nombres
 
 ```
 https://fonts.google.com/icons?icon.query=icon_name
@@ -287,7 +380,9 @@ https://fonts.google.com/icons?icon.query=icon_name
 
 | 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`: 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 |
+| 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 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@robosophy/ui-vue",
-  "version": "1.1.12",
+  "version": "1.2.0",
   "private": false,
   "license": "UNLICENSED",
   "homepage": "https://robosophy.gitlab.io/robosophy-basf/robosophy-library/",
@@ -68,4 +68,4 @@
     "vue-tsc": "^3.1.0"
   },
   "dependencies": {}
-}
+}