@vmz/plugin-iconify 0.0.0 → 0.0.3

package/README.md

@@ -1,3 +1,36 @@
 # @vmz/plugin-iconify
 
-Placeholder package (0.0.0). Reserved for the VMZ project.
+## Use a broad icon vocabulary without owning every SVG
+
+`@vmz/plugin-iconify` connects Iconify collections to VMZ applications. It is a practical choice for product interfaces,
+navigation, documentation, internal tools, and design systems that need consistent access to established icon sets.
+
+## What to consider
+
+Icons improve scanning and recognition, but they are still product assets with delivery, licensing, and offline
+implications. Iconify is attractive when breadth and familiar collections matter. A project that needs strict offline
+builds, a locked visual language, or carefully audited assets may prefer to ship a selected local collection instead.
+
+| Iconify is a good fit when...                   | Curated local assets are better when...                     |
+|-------------------------------------------------|-------------------------------------------------------------|
+| You need broad, familiar icon coverage          | Offline builds and audited assets are mandatory             |
+| Product speed matters more than owning each SVG | Brand control and a narrow visual language are the priority |
+
+VMZ keeps that decision at the asset boundary. Icons should not become an untracked runtime dependency that changes how
+the rest of the application compiles, renders, or deploys.
+
+## VMZ boundary
+
+This plugin provides icon access. VMZ retains responsibility for page output, resource placement, SSR behavior, testing,
+and explainable application delivery.
+
+## A broad vocabulary, used deliberately ✨
+
+- Product navigation can use familiar symbols instead of text-heavy controls.
+- Documentation can distinguish notes, warnings, links, files, and actions at a glance.
+- Operational tools can cover many domains without commissioning every utility icon.
+- Design systems can prototype broadly before curating a final set.
+
+The production question is not simply “does an icon exist?” It is how the application guarantees that icon in
+development, CI, SSR, offline use, and long-term design consistency. Iconify solves discovery and breadth; a mature
+product may then freeze the exact assets it depends on.

package/components/Iconify.vmz

@@ -0,0 +1,17 @@
+<template>
+  <span class="iconify-host" html={html != null ? html : iconFallback(name)}></span>
+</template>
+
+<script client>
+import { loadIconSvg, iconFallback } from '@vmz/plugin-iconify/runtime';
+
+export default class Iconify {
+  /** Iconify id, e.g. `mdi:home`. */
+  public name: string = '';
+  html: string | null = null;
+
+  async onMount() {
+    this.html = (await loadIconSvg(this.name)) || iconFallback(this.name);
+  }
+}
+</script>

package/package.json

@@ -1,10 +1,43 @@
 {
   "name": "@vmz/plugin-iconify",
-  "version": "0.0.0",
-  "description": "VMZ placeholder — not for production use.",
+  "version": "0.0.3",
+  "type": "module",
+  "description": "VMZ Iconify adapter - <Iconify>",
   "license": "MIT",
-  "private": false,
-  "files": [
-    "README.md"
-  ]
+  "main": "./vmz.plugin.ts",
+  "types": "./vmz.plugin.ts",
+  "exports": {
+    ".": {
+      "types": "./vmz.plugin.ts",
+      "default": "./vmz.plugin.ts"
+    },
+    "./runtime": {
+      "types": "./runtime.ts",
+      "default": "./runtime.ts"
+    }
+  },
+  "dependencies": {
+    "@vmz/plugin": "0.0.3"
+  },
+  "peerDependencies": {
+    "@iconify/utils": ">=2"
+  },
+  "peerDependenciesMeta": {
+    "@iconify/utils": {
+      "optional": true
+    }
+  },
+  "keywords": [
+    "vmz",
+    "plugin",
+    "iconify",
+    "icon"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/doki-land/vmz-framework.git"
+  }
 }

package/runtime.ts

@@ -0,0 +1,36 @@
+/**
+ * Iconify SVG fetch helper (runtime). Prefer build-time offline collections later.
+ */
+
+const cache = new Map<string, string>();
+
+/** `name` is icon set:name e.g. `mdi:home`. */
+export async function loadIconSvg(name: string): Promise<string> {
+    const key = String(name ?? '');
+    if (cache.has(key)) return cache.get(key)!;
+    const [prefix, icon] = key.split(':');
+    if (!prefix || !icon) {
+        const empty = '';
+        cache.set(key, empty);
+        return empty;
+    }
+    try {
+        const res = await fetch(`https://api.iconify.design/${prefix}/${icon}.svg`);
+        if (!res.ok) throw new Error(String(res.status));
+        const svg = await res.text();
+        cache.set(key, svg);
+        return svg;
+    } catch {
+        const empty = '';
+        cache.set(key, empty);
+        return empty;
+    }
+}
+
+export function iconFallback(name: string): string {
+    const escaped = String(name ?? '')
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;');
+    return `<span class="iconify-fallback" data-icon="${escaped}"></span>`;
+}

package/vmz.plugin.ts

@@ -0,0 +1,46 @@
+import { definePlugin, loadPluginSource } from '@vmz/plugin';
+
+const source = loadPluginSource(import.meta.url, 'components/Iconify.vmz');
+
+export default definePlugin({
+    name: '@vmz/plugin-iconify',
+    version: '0.1.0',
+    protocol: '0.1.0',
+    stages: ['workspace_resolve', 'analyzer'],
+    deterministic: true,
+    async contribute(ctx) {
+        if (ctx.stage === 'workspace_resolve') {
+            return {
+                stage: 'workspace_resolve',
+                cacheKey: `@vmz/plugin-iconify:Iconify.vmz:${source.contentHash.slice(0, 12)}`,
+                items: [
+                    {
+                        id: 'component-iconify',
+                        kind: 'source',
+                        path: 'src/components/Iconify.vmz',
+                        content: source.content,
+                        contentHash: source.contentHash,
+                        materialize: true,
+                    },
+                ],
+            };
+        }
+        if (ctx.stage === 'analyzer') {
+            return {
+                stage: 'analyzer',
+                cacheKey: '@vmz/plugin-iconify:analyzer',
+                items: [
+                    {
+                        id: 'component-iconify-online',
+                        kind: 'analyzer',
+                        path: 'src/components/Iconify.vmz',
+                        severity: 'advice',
+                        message: 'Iconify component online',
+                        code: 'vmz.plugin.iconify',
+                    },
+                ],
+            };
+        }
+        return { stage: ctx.stage, items: [] };
+    },
+});