vanillaforge 1.9.0

package/src/plugins/icons/icons-plugin.js

@@ -0,0 +1,130 @@
+/**
+ * VanillaForge built-in icons plugin.
+ *
+ * Provides zero-dependency, inline-SVG icons so apps don't need Font Awesome
+ * or any other external icon library. Icons render as accessible <svg> elements
+ * directly in the HTML string — no external requests, no flash of missing icons.
+ *
+ * Usage:
+ *   import { createApp, iconsPlugin } from './src/framework.js';
+ *   const app = createApp({ ... });
+ *   app.use(iconsPlugin);              // install with defaults
+ *   app.use(iconsPlugin, {
+ *     icons: { logo: '<path .../>' }  // add/override individual icons
+ *   });
+ *
+ * In any component:
+ *   getTemplate() {
+ *     return `<button>${this.icon('check', { size: 18 })} Save</button>`;
+ *   }
+ *
+ * Users can still bring their own icon library — just don't install this plugin
+ * and wire up whatever they prefer.
+ */
+
+import { defaultIcons } from './default-icons.js';
+
+/**
+ * Service that stores and renders inline SVG icons.
+ * Registered under the key 'icons' via app.provide().
+ */
+export class IconsService {
+    constructor(icons = {}) {
+        this._icons = new Map(Object.entries(icons));
+        this._warnedUnknown = new Set();
+    }
+
+    /**
+     * Register a custom icon (or override an existing one).
+     *
+     * @param {string} name - Icon name
+     * @param {string} innerSvg - SVG inner content (everything inside <svg>...</svg>)
+     * @returns {IconsService} this, for chaining
+     */
+    register(name, innerSvg) {
+        this._icons.set(name, innerSvg);
+        return this;
+    }
+
+    /**
+     * Check whether a named icon is registered.
+     *
+     * @param {string} name
+     * @returns {boolean}
+     */
+    has(name) {
+        return this._icons.has(name);
+    }
+
+    /**
+     * Render a named icon as an inline SVG string.
+     *
+     * @param {string} name - Icon name (e.g. 'check', 'trash', 'menu')
+     * @param {Object} [opts={}]
+     * @param {number} [opts.size=24] - Width and height in pixels
+     * @param {string} [opts.className=''] - Extra CSS class on the <svg> element
+     * @param {string} [opts.title] - Accessible title; omit for decorative icons
+     * @param {string} [opts.color] - Inline color override (defaults to currentColor)
+     * @returns {string} Inline SVG string, or '' for unknown icons
+     */
+    render(name, opts = {}) {
+        const inner = this._icons.get(name);
+        if (!inner) {
+            if (!this._warnedUnknown.has(name)) {
+                console.warn(`[VanillaForge icons] Unknown icon: "${name}"`);
+                this._warnedUnknown.add(name);
+            }
+            return '';
+        }
+
+        const size = opts.size ?? 24;
+        const cls = ['vf-icon', opts.className].filter(Boolean).join(' ');
+        const colorStyle = opts.color ? ` style="color:${opts.color}"` : '';
+        const titleTag = opts.title
+            ? `<title>${escapeHtml(opts.title)}</title>`
+            : '';
+        const aria = opts.title
+            ? `role="img" aria-label="${escapeHtml(opts.title)}"`
+            : 'aria-hidden="true"';
+
+        return (
+            `<svg xmlns="http://www.w3.org/2000/svg" ` +
+            `class="${cls}" ` +
+            `width="${size}" height="${size}" ` +
+            `viewBox="0 0 24 24" ` +
+            `fill="none" ` +
+            `${aria}` +
+            `${colorStyle}>` +
+            `${titleTag}${inner}` +
+            `</svg>`
+        );
+    }
+}
+
+/**
+ * Plugin object. Install with app.use(iconsPlugin) or
+ * app.use(iconsPlugin, { icons: { myIcon: '<path .../>' } }).
+ *
+ * Options:
+ *   icons {Object} - Additional icon definitions merged on top of the defaults.
+ *                    A key that already exists in defaults is overridden.
+ */
+export const iconsPlugin = {
+    name: 'icons',
+
+    install(app, options = {}) {
+        const merged = { ...defaultIcons, ...(options.icons || {}) };
+        const service = new IconsService(merged);
+        app.provide('icons', service);
+    },
+};
+
+// ---- private helpers ----
+
+function escapeHtml(str) {
+    return String(str)
+        .replace(/&/g, '&amp;')
+        .replace(/"/g, '&quot;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;');
+}

package/src/plugins/store/store-plugin.js

@@ -0,0 +1,127 @@
+/**
+ * Store plugin — shared reactive state for VanillaForge applications.
+ *
+ * Provides a lightweight key/value store layered on top of the EventBus.
+ * Any component (or plugin) can read, write, and subscribe to named keys.
+ *
+ * Usage:
+ *
+ *   app.use(storePlugin);
+ *
+ *   // From a component:
+ *   const store = this.service('store');
+ *
+ *   store.set('cart', [...items]);          // write
+ *   store.get('cart');                      // read (current value)
+ *   const unsub = store.subscribe('cart', (items) => {
+ *     this.setState({ items });
+ *   });
+ *   unsub();                                // stop listening
+ *
+ * Events emitted on the shared EventBus:
+ *   'store:change' — { key, value, prev } — every time a key changes.
+ *   'store:change:<key>' — { value, prev } — per-key variant for targeted listeners.
+ */
+
+export class StoreService {
+  /**
+   * @param {import('../../core/event-bus.js').EventBus} eventBus
+   */
+  constructor(eventBus) {
+    this._bus = eventBus;
+    this._state = new Map();
+  }
+
+  /**
+   * Write a value to the store under `key`.
+   * Identical values (via Object.is) are silently ignored — no events fired.
+   *
+   * @param {string} key
+   * @param {*} value
+   */
+  set(key, value) {
+    const prev = this._state.get(key);
+    if (Object.is(prev, value)) return;
+    this._state.set(key, value);
+    this._bus.emit('store:change', { key, value, prev });
+    this._bus.emit(`store:change:${key}`, { value, prev });
+  }
+
+  /**
+   * Read the current value for `key`.
+   * Returns `undefined` when the key has never been written.
+   *
+   * @param {string} key
+   * @returns {*}
+   */
+  get(key) {
+    return this._state.get(key);
+  }
+
+  /**
+   * Subscribe to changes for a specific `key`.
+   * The handler is called with `(value, prev)` whenever the key changes.
+   * Returns an unsubscribe function.
+   *
+   * @param {string} key
+   * @param {(value: *, prev: *) => void} handler
+   * @returns {() => void} unsubscribe
+   */
+  subscribe(key, handler) {
+    return this._bus.on(`store:change:${key}`, ({ value, prev }) => {
+      handler(value, prev);
+    });
+  }
+
+  /**
+   * Subscribe to ALL store changes.
+   * The handler is called with `(key, value, prev)` on every write.
+   * Returns an unsubscribe function.
+   *
+   * @param {(key: string, value: *, prev: *) => void} handler
+   * @returns {() => void} unsubscribe
+   */
+  subscribeAll(handler) {
+    return this._bus.on('store:change', ({ key, value, prev }) => {
+      handler(key, value, prev);
+    });
+  }
+
+  /**
+   * Remove a key from the store and fire change events with `value: undefined`.
+   *
+   * @param {string} key
+   */
+  delete(key) {
+    if (!this._state.has(key)) return;
+    const prev = this._state.get(key);
+    this._state.delete(key);
+    this._bus.emit('store:change', { key, value: undefined, prev });
+    this._bus.emit(`store:change:${key}`, { value: undefined, prev });
+  }
+
+  /**
+   * Returns all keys currently in the store.
+   * @returns {string[]}
+   */
+  keys() {
+    return Array.from(this._state.keys());
+  }
+}
+
+/**
+ * Install the store plugin.
+ *
+ * Registers a `StoreService` instance as the 'store' service.
+ * After install, components access it via `this.service('store')`.
+ *
+ * @type {import('../../framework.js').Plugin}
+ */
+export const storePlugin = {
+  name: 'store',
+
+  install(app) {
+    const store = new StoreService(app.eventBus);
+    app.provide('store', store);
+  },
+};

package/src/plugins/theme/base-styles.js

@@ -0,0 +1,58 @@
+/**
+ * VanillaForge base stylesheet.
+ *
+ * Injected by ThemeService when base !== false (the default).
+ * Every rule uses the --vf-* custom properties set by the token block,
+ * so swapping tokens is enough to retheme everything here.
+ */
+
+export const BASE_STYLES = `
+/* --- VanillaForge base --- */
+*, *::before, *::after { box-sizing: border-box; }
+
+body {
+  font-family: var(--vf-font-sans);
+  color: var(--vf-text);
+  background: var(--vf-background);
+  line-height: 1.5;
+  margin: 0;
+}
+
+a { color: var(--vf-primary); }
+a:hover { color: var(--vf-primary-dark); }
+
+/* --- .vf-card --- */
+.vf-card {
+  background: var(--vf-surface);
+  border-radius: var(--vf-radius-lg);
+  box-shadow: var(--vf-shadow-md);
+  padding: 1.5rem;
+}
+
+/* --- .vf-btn --- */
+.vf-btn {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  padding: 8px 16px;
+  border-radius: var(--vf-radius);
+  border: none;
+  cursor: pointer;
+  font: inherit;
+  font-weight: 600;
+  font-size: .9rem;
+  text-decoration: none;
+  transition: opacity .15s;
+}
+.vf-btn:hover { opacity: .85; }
+.vf-btn:active { opacity: .7; }
+.vf-btn:disabled { opacity: .45; cursor: not-allowed; }
+
+.vf-btn-primary  { background: var(--vf-primary);   color: #fff; }
+.vf-btn-secondary { background: var(--vf-border);  color: var(--vf-text); }
+.vf-btn-danger   { background: var(--vf-danger);    color: #fff; }
+.vf-btn-success  { background: var(--vf-success);   color: #fff; }
+
+/* --- .vf-icon (icons plugin companion) --- */
+.vf-icon { vertical-align: middle; }
+`;

package/src/plugins/theme/theme-plugin.js

@@ -0,0 +1,160 @@
+/**
+ * VanillaForge built-in theme plugin.
+ *
+ * Injects a block of CSS custom properties (--vf-*) into <head> and,
+ * by default, a small base stylesheet that makes apps look sensible
+ * out of the box without Tailwind, Bootstrap, or any external CSS.
+ *
+ * Usage:
+ *   import { createApp, themePlugin } from './src/framework.js';
+ *   const app = createApp({ ... });
+ *
+ *   app.use(themePlugin);                        // defaults only
+ *   app.use(themePlugin, {
+ *     tokens: { primary: '#6366f1', radius: '8px' }
+ *   });
+ *   app.use(themePlugin, { base: false });        // token vars only, no base stylesheet
+ *
+ * In any component:
+ *   this.service('theme').setTokens({ primary: '#ef4444' }); // live update
+ *   this.service('theme').getToken('primary');                // '#ef4444'
+ *
+ * In CSS / inline styles:
+ *   color: var(--vf-primary);
+ *   border-radius: var(--vf-radius);
+ */
+
+import { BASE_STYLES } from './base-styles.js';
+
+// ---------------------------------------------------------------------------
+// Default design tokens
+// ---------------------------------------------------------------------------
+
+const DEFAULT_TOKENS = {
+  // Colors
+  primary: '#3b82f6',
+  primaryDark: '#2563eb',
+  secondary: '#6b7280',
+  surface: '#ffffff',
+  background: '#f4f5f7',
+  text: '#1f2933',
+  textMuted: '#7b8794',
+  border: '#e5e7eb',
+  danger: '#ef4444',
+  success: '#10b981',
+  warning: '#f59e0b',
+  // Shape
+  radius: '6px',
+  radiusSm: '4px',
+  radiusLg: '12px',
+  // Typography
+  fontSans: 'system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
+  fontMono: '"JetBrains Mono", "Fira Code", monospace',
+  // Shadows
+  shadowSm: '0 1px 3px rgba(0,0,0,.08)',
+  shadowMd: '0 4px 16px rgba(0,0,0,.08)',
+  shadowLg: '0 10px 30px rgba(0,0,0,.12)',
+  // Base spacing unit (useful for calc()-based layouts)
+  space: '4px',
+};
+
+// ---------------------------------------------------------------------------
+// ThemeService
+// ---------------------------------------------------------------------------
+
+/**
+ * Manages design tokens and injects them as CSS custom properties.
+ * Registered under the key 'theme' via app.provide().
+ */
+export class ThemeService {
+  constructor(options = {}) {
+    this._tokens = { ...DEFAULT_TOKENS, ...(options.tokens || {}) };
+    this._includeBase = options.base !== false;
+    this._styleEl = null;
+    this._inject();
+  }
+
+  /**
+   * Update one or more tokens and re-inject the style block.
+   *
+   * @param {Object} tokens - Partial token map to merge in
+   * @returns {ThemeService} this, for chaining
+   */
+  setTokens(tokens) {
+    Object.assign(this._tokens, tokens);
+    this._inject();
+    return this;
+  }
+
+  /**
+   * Read a single token value by its camelCase name.
+   *
+   * @param {string} name - e.g. 'primary', 'fontSans'
+   * @returns {string|null}
+   */
+  getToken(name) {
+    return Object.prototype.hasOwnProperty.call(this._tokens, name)
+      ? this._tokens[name]
+      : null;
+  }
+
+  // ---- private -----------------------------------------------------------
+
+  _inject() {
+    if (typeof document === 'undefined') return;
+
+    if (!this._styleEl) {
+      // Reuse an element a previous ThemeService instance may have left behind
+      // (e.g. hot-reload or a second app.use() call after override).
+      this._styleEl = document.getElementById('vf-theme');
+      if (!this._styleEl) {
+        this._styleEl = document.createElement('style');
+        this._styleEl.id = 'vf-theme';
+        document.head.appendChild(this._styleEl);
+      }
+    }
+
+    this._styleEl.textContent = this._buildCSS();
+  }
+
+  _buildCSS() {
+    const vars = Object.entries(this._tokens)
+      .map(([k, v]) => `  --vf-${camelToKebab(k)}: ${v};`)
+      .join('\n');
+    const rootBlock = `:root {\n${vars}\n}`;
+    return this._includeBase
+      ? `${rootBlock}\n${BASE_STYLES}`
+      : rootBlock;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Plugin export
+// ---------------------------------------------------------------------------
+
+/**
+ * Plugin object. Install with:
+ *   app.use(themePlugin)
+ *   app.use(themePlugin, { tokens: { primary: '#6366f1' } })
+ *   app.use(themePlugin, { base: false })
+ *
+ * Options:
+ *   tokens {Object} - Token overrides merged on top of defaults.
+ *   base   {boolean} - Set to false to skip the base stylesheet (default: true).
+ */
+export const themePlugin = {
+  name: 'theme',
+
+  install(app, options = {}) {
+    const service = new ThemeService(options);
+    app.provide('theme', service);
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Private helpers
+// ---------------------------------------------------------------------------
+
+function camelToKebab(str) {
+  return str.replace(/([A-Z])/g, '-$1').toLowerCase();
+}

package/src/utils/decorators.js

@@ -0,0 +1,51 @@
+/**
+ * Decorators for performance and caching
+ */
+
+import { performanceUtils } from './performance.js';
+
+/**
+ * Performance decorator for methods
+ * @param {string} label - Performance label
+ * @returns {Function} Decorator function
+ */
+export function perf(label) {
+  return function(target, propertyKey, descriptor) {
+    const originalMethod = descriptor.value;
+
+    descriptor.value = function(...args) {
+      return performanceUtils.measure(
+        () => originalMethod.apply(this, args),
+        `${target.constructor.name}.${propertyKey}${label ? ` (${label})` : ''}`
+      );
+    };
+
+    return descriptor;
+  };
+}
+
+/**
+ * Cache decorator for methods
+ * @param {number} ttl - Time to live in milliseconds
+ * @returns {Function} Decorator function
+ */
+export function cache(ttl = 300000) {
+  return function(target, propertyKey, descriptor) {
+    const originalMethod = descriptor.value;
+
+    descriptor.value = function(...args) {
+      const cacheKey = `${target.constructor.name}.${propertyKey}.${JSON.stringify(args)}`;
+      const cached = performanceUtils.getCache(cacheKey);
+
+      if (cached !== null) {
+        return cached;
+      }
+
+      const result = originalMethod.apply(this, args);
+      performanceUtils.setCache(cacheKey, result, ttl);
+      return result;
+    };
+
+    return descriptor;
+  };
+}

package/src/utils/dom.js

@@ -0,0 +1,40 @@
+/**
+ * DOM-related utilities
+ */
+
+/**
+ * Optimize images for different screen sizes
+ * @param {HTMLImageElement} img - Image element
+ * @param {Object} sizes - Size configuration
+ */
+export function optimizeImage(img, sizes = {}) {
+  const defaultSizes = {
+    small: '(max-width: 480px)',
+    medium: '(max-width: 768px)',
+    large: '(min-width: 769px)'
+  };
+
+  const imageSizes = { ...defaultSizes, ...sizes };
+
+  const picture = document.createElement('picture');
+
+  Object.entries(imageSizes).forEach(([size, media]) => {
+    const source = document.createElement('source');
+    source.media = media;
+    source.srcset = img.dataset[`src${size.charAt(0).toUpperCase() + size.slice(1)}`] || img.src;
+    picture.appendChild(source);
+  });
+
+  picture.appendChild(img.cloneNode(true));
+  return picture;
+}
+
+/**
+ * Batch DOM operations to avoid layout thrashing
+ * @param {Function[]} operations - Array of DOM operations
+ */
+export function batchDOMOperations(operations) {
+  requestAnimationFrame(() => {
+    operations.forEach(operation => operation());
+  });
+}