@robosophy/ui-vue 1.1.8 → 1.1.10

package/icon-scanner.md

@@ -0,0 +1,293 @@
+# 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 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@robosophy/ui-vue",
-  "version": "1.1.8",
+  "version": "1.1.10",
   "private": false,
   "license": "UNLICENSED",
   "homepage": "https://robosophy.gitlab.io/robosophy-basf/robosophy-library/",
@@ -25,12 +25,14 @@
     },
     "./AGENTS.md": "./AGENTS.md",
     "./ai-context.md": "./ai-context.md",
-    "./components.md": "./components.md"
+    "./components.md": "./components.md",
+    "./icon-scanner.md": "./icon-scanner.md"
   },
   "files": [
     "AGENTS.md",
     "ai-context.md",
     "components.md",
+    "icon-scanner.md",
     "dist",
     "README.md",
     "package.json"