windrunner 1.0.2 → 1.1.0

package/dist/index.d.ts

@@ -1,33 +1,62 @@
-export interface WindrunnerOptions {
-  id?: string;
-  autoStart?: boolean;
-  preflight?: boolean;
-  compatMode?: "none" | "full";
-  compatStyleId?: string;
-  compatGenerateCss?: (options: Record<string, any>) => string;
-  theme?: Record<string, any>;
-  onReady?: () => void;
-  [key: string]: any;
-}
-
-export interface Runtime {
-  processClassName(className: string): string | undefined;
-  processClassList(classList: string | string[] | ArrayLike<string>): string[];
-  processElement(el: Element | null): void;
-  scan(root?: Document | Element): void;
-  observe(root?: Element): void;
-  flush(): void;
-  start(): void;
-  disconnect(): void;
-  isCompatLoaded(): boolean;
-  getCacheSize(): number;
-  getInsertedRuleCount(): number;
-}
-
-export function createWindrunner(options?: WindrunnerOptions): Runtime;
-export function compileRuntimeClassNameWithContext(className: string, context: any): string;
-export function compileClass(className: string, options?: any): string;
-export function parseClass(className: string, screens?: Record<string,string>, containers?: Record<string,string>): { original: string; baseToken: string; variants: string[]; breakpoint: string | null; containerBreakpoint: string | null; important: boolean; starting: boolean } | null;
-
-declare function windrunner(options?: WindrunnerOptions): Runtime;
-export default windrunner;
+// ─── Plugin Types ─────────────────────────────────────────────────────────────
+
+export interface PluginAPI {
+  addUtility(pattern: string | RegExp, handler: string | ((match: RegExpMatchArray, theme: any) => string)): void;
+  addUtilities(utilities: Record<string, string | ((match: RegExpMatchArray, theme: any) => string)>): void;
+  addVariant(name: string, handler: (selector: string) => string): void;
+  addVariants(variants: Record<string, (selector: string) => string>): void;
+  theme(key?: string): any;
+  config(): any;
+}
+
+export interface Plugin {
+  __isWindrunnerPlugin: true;
+  handler: (api: PluginAPI) => void;
+}
+
+export function plugin(handler: (api: PluginAPI) => void): Plugin;
+
+export function defineUtilities(definitions: Record<string, string | Record<string, string>>): Record<string, string>;
+
+export function defineResponsiveUtilities(
+  base: string,
+  values: Record<string, string>,
+  toDeclaration: (key: string, value: string) => string
+): Record<string, string>;
+
+// ─── Runtime Options with Plugins ─────────────────────────────────────────────
+
+export interface WindrunnerOptions {
+  id?: string;
+  autoStart?: boolean;
+  preflight?: boolean;
+  compatMode?: "none" | "full";
+  compatStyleId?: string;
+  compatGenerateCss?: (options: Record<string, any>) => string;
+  theme?: Record<string, any>;
+  plugins?: Plugin[];
+  onReady?: () => void;
+  [key: string]: any;
+}
+
+export interface Runtime {
+  processClassName(className: string): string | undefined;
+  processClassList(classList: string | string[] | ArrayLike<string>): string[];
+  processElement(el: Element | null): void;
+  scan(root?: Document | Element): void;
+  observe(root?: Element): void;
+  flush(): void;
+  start(): void;
+  disconnect(): void;
+  isCompatLoaded(): boolean;
+  getCacheSize(): number;
+  getInsertedRuleCount(): number;
+}
+
+export function createWindrunner(options?: WindrunnerOptions): Runtime;
+export function compileRuntimeClassNameWithContext(className: string, context: any): string;
+export function compileClass(className: string, options?: any): string;
+export function parseClass(className: string, screens?: Record<string,string>, containers?: Record<string,string>): { original: string; baseToken: string; variants: string[]; breakpoint: string | null; containerBreakpoint: string | null; important: boolean; starting: boolean } | null;
+
+declare function windrunner(options?: WindrunnerOptions): Runtime;
+export default windrunner;

package/dist/index.esm.js

@@ -3260,13 +3260,160 @@ function buildDivideDeclaration(baseToken, theme2) {
   return void 0;
 }
 
+// src/plugins.js
+var PluginRegistry = class {
+  constructor() {
+    this.utilities = /* @__PURE__ */ new Map();
+    this.variants = /* @__PURE__ */ new Map();
+  }
+  /**
+   * Register a custom utility
+   * @param {string|RegExp} pattern - Class name pattern (e.g., "glass" or /^glass-(.+)$/)
+   * @param {Function|string} handler - Function that returns CSS or CSS string
+   */
+  addUtility(pattern, handler) {
+    this.utilities.set(pattern, handler);
+  }
+  /**
+   * Register multiple utilities at once
+   * @param {Object} utilities - Object mapping patterns to handlers
+   */
+  addUtilities(utilities) {
+    Object.entries(utilities).forEach(([pattern, handler]) => {
+      this.addUtility(pattern, handler);
+    });
+  }
+  /**
+   * Register a custom variant
+   * @param {string} name - Variant name (e.g., "parent-hover")
+   * @param {Function} handler - Function that transforms selector
+   */
+  addVariant(name, handler) {
+    this.variants.set(name, handler);
+  }
+  /**
+   * Register multiple variants at once
+   * @param {Object} variants - Object mapping names to handlers
+   */
+  addVariants(variants2) {
+    Object.entries(variants2).forEach(([name, handler]) => {
+      this.addVariant(name, handler);
+    });
+  }
+  /**
+   * Check if a token matches any custom utility pattern
+   * @param {string} token - The base token to match
+   * @returns {Object|null} - { handler, match } or null
+   */
+  matchUtility(token) {
+    for (const [pattern, handler] of this.utilities) {
+      if (pattern instanceof RegExp) {
+        const match = pattern.exec(token);
+        if (match) {
+          return { handler, match };
+        }
+      } else if (pattern === token) {
+        return { handler, match: [token] };
+      }
+    }
+    return null;
+  }
+  /**
+   * Check if a variant name matches any custom variant
+   * @param {string} variantName - The variant to check
+   * @returns {Function|null} - Handler function or null
+   */
+  matchVariant(variantName) {
+    return this.variants.get(variantName) || null;
+  }
+  /**
+   * Get all registered utility patterns (for debugging)
+   */
+  getUtilities() {
+    return Array.from(this.utilities.keys());
+  }
+  /**
+   * Get all registered variant names (for debugging)
+   */
+  getVariants() {
+    return Array.from(this.variants.keys());
+  }
+  /**
+   * Clear all registered plugins
+   */
+  clear() {
+    this.utilities.clear();
+    this.variants.clear();
+  }
+};
+function plugin(handler) {
+  if (typeof handler !== "function") {
+    throw new Error("Plugin handler must be a function");
+  }
+  return {
+    __isWindrunnerPlugin: true,
+    handler
+  };
+}
+function isPlugin(obj) {
+  return obj && obj.__isWindrunnerPlugin === true && typeof obj.handler === "function";
+}
+function defineUtilities(definitions) {
+  const utilities = {};
+  Object.entries(definitions).forEach(([className, css]) => {
+    utilities[className] = typeof css === "string" ? css : objectToCss(css);
+  });
+  return utilities;
+}
+function defineResponsiveUtilities(base, values, toDeclaration) {
+  const utilities = {};
+  Object.entries(values).forEach(([key, value]) => {
+    const className = key === "DEFAULT" ? base : `${base}-${key}`;
+    utilities[className] = toDeclaration(key, value);
+  });
+  return utilities;
+}
+function objectToCss(obj) {
+  return Object.entries(obj).map(([prop, value]) => `${prop}: ${value};`).join(" ");
+}
+
 // src/compiler.js
-function compileBaseToken(baseToken, theme2) {
+function compileBaseToken(baseToken, theme2, pluginRegistry) {
+  if (pluginRegistry) {
+    const pluginMatch = pluginRegistry.matchUtility(baseToken);
+    if (pluginMatch) {
+      const { handler, match } = pluginMatch;
+      try {
+        if (typeof handler === "function") {
+          const result = handler(match, theme2);
+          if (result) return result;
+        } else if (typeof handler === "string") {
+          return handler;
+        }
+      } catch (error) {
+        console.warn(`[Windrunner] Plugin utility handler error for "${baseToken}":`, error);
+      }
+    }
+  }
   return buildLayoutDeclaration(baseToken, theme2) || buildPositionInsetDeclaration(baseToken, theme2) || buildSpacingDeclaration(baseToken, theme2) || buildSpaceBetweenDeclaration(baseToken, theme2) || buildGapDeclaration(baseToken, theme2) || buildDimensionDeclaration(baseToken, theme2) || buildFlexGridDeclaration(baseToken, theme2) || buildBorderDeclaration(baseToken, theme2) || buildBorderRadiusDeclaration(baseToken, theme2) || buildBorderSpacingDeclaration(baseToken, theme2) || buildDivideDeclaration(baseToken, theme2) || buildOpacityDeclaration(baseToken, theme2) || buildShadowDeclaration(baseToken, theme2) || buildInsetShadowDeclaration(baseToken, theme2) || buildInsetRingDeclaration(baseToken, theme2) || buildRingDeclaration(baseToken, theme2) || buildRingOffsetDeclaration(baseToken, theme2) || buildTextShadowDeclaration(baseToken, theme2) || buildTransitionDeclaration(baseToken) || buildTransformDeclaration(baseToken, theme2) || buildFilterDeclaration(baseToken, theme2) || buildBackgroundDeclaration(baseToken, theme2) || buildGradientDeclaration(baseToken, theme2) || buildColorDeclaration(baseToken, theme2) || buildTypographyDeclaration(baseToken, theme2) || buildBlendingDeclaration(baseToken) || buildInteractivityDeclaration(baseToken, theme2) || buildAnimationDeclaration(baseToken) || buildMaskDeclaration(baseToken) || buildContainerQueryDeclaration(baseToken) || buildScrollSnapDeclaration(baseToken) || buildAccessibilityDeclaration(baseToken) || buildZoomDeclaration(baseToken, theme2) || buildForcedColorDeclaration(baseToken);
 }
-function applyVariants(selector, variants2) {
+function applyVariants(selector, variants2, pluginRegistry) {
   let currentSelector = selector;
   for (const variant of variants2) {
+    if (pluginRegistry) {
+      const customHandler = pluginRegistry.matchVariant(variant);
+      if (customHandler) {
+        try {
+          const result = customHandler(currentSelector);
+          if (result) {
+            currentSelector = result;
+            continue;
+          }
+        } catch (error) {
+          console.warn(`[Windrunner] Plugin variant handler error for "${variant}":`, error);
+        }
+      }
+    }
     switch (variant) {
       case "dark":
         currentSelector = `.dark ${currentSelector}`;
@@ -3307,15 +3454,66 @@ function applyVariants(selector, variants2) {
       case "invalid":
         currentSelector = `${currentSelector}:invalid`;
         break;
+      case "target":
+        currentSelector = `${currentSelector}:target`;
+        break;
+      case "enabled":
+        currentSelector = `${currentSelector}:enabled`;
+        break;
+      case "default":
+        currentSelector = `${currentSelector}:default`;
+        break;
+      case "optional":
+        currentSelector = `${currentSelector}:optional`;
+        break;
+      case "user-valid":
+        currentSelector = `${currentSelector}:user-valid`;
+        break;
+      case "user-invalid":
+        currentSelector = `${currentSelector}:user-invalid`;
+        break;
+      case "in-range":
+        currentSelector = `${currentSelector}:in-range`;
+        break;
+      case "out-of-range":
+        currentSelector = `${currentSelector}:out-of-range`;
+        break;
+      case "placeholder-shown":
+        currentSelector = `${currentSelector}:placeholder-shown`;
+        break;
+      case "autofill":
+        currentSelector = `${currentSelector}:autofill`;
+        break;
+      case "details-content":
+        currentSelector = `${currentSelector}:details-content`;
+        break;
       case "placeholder":
         currentSelector = `${currentSelector}::placeholder`;
         break;
+      case "backdrop":
+        currentSelector = `${currentSelector}::backdrop`;
+        break;
       case "before":
         currentSelector = `${currentSelector}::before`;
         break;
       case "after":
         currentSelector = `${currentSelector}::after`;
         break;
+      case "first-letter":
+        currentSelector = `${currentSelector}::first-letter`;
+        break;
+      case "first-line":
+        currentSelector = `${currentSelector}::first-line`;
+        break;
+      case "marker":
+        currentSelector = `${currentSelector}::marker`;
+        break;
+      case "selection":
+        currentSelector = `${currentSelector}::selection`;
+        break;
+      case "file":
+        currentSelector = `${currentSelector}::file-selector-button`;
+        break;
       case "first":
         currentSelector = `${currentSelector}:first-child`;
         break;
@@ -3396,11 +3594,40 @@ function applyVariants(selector, variants2) {
 }
 function resolveRuntimeContext(options = {}) {
   const config = getConfigOptions(options, []);
+  const pluginRegistry = new PluginRegistry();
+  if (options.plugins && Array.isArray(options.plugins)) {
+    options.plugins.forEach((pluginDef) => {
+      if (isPlugin(pluginDef)) {
+        try {
+          pluginDef.handler({
+            addUtility: (pattern, handler) => pluginRegistry.addUtility(pattern, handler),
+            addUtilities: (utilities) => pluginRegistry.addUtilities(utilities),
+            addVariant: (name, handler) => pluginRegistry.addVariant(name, handler),
+            addVariants: (variants2) => pluginRegistry.addVariants(variants2),
+            theme: (key) => {
+              if (!key) return config.theme || {};
+              const keys = key.split(".");
+              let value = config.theme || {};
+              for (const k of keys) {
+                value = value[k];
+                if (value === void 0) break;
+              }
+              return value;
+            },
+            config: () => config
+          });
+        } catch (error) {
+          console.error("[Windrunner] Plugin initialization error:", error);
+        }
+      }
+    });
+  }
   return {
     config,
     theme: config.theme || {},
     screens: config.theme && config.theme.screens || config.screens || {},
-    containers: config.theme && config.theme.containers || config.containers || {}
+    containers: config.theme && config.theme.containers || config.containers || {},
+    plugins: pluginRegistry
   };
 }
 function getBaseTailwindOptions(options = {}) {
@@ -3444,10 +3671,10 @@ function parseClass(className, screens = {}, containers = {}) {
 function compileRuntimeClassNameWithContext(className, context) {
   const parsed = parseClass(className, context.screens, context.containers);
   if (!parsed) return "";
-  const declaration = compileBaseToken(parsed.baseToken, context.theme);
+  const declaration = compileBaseToken(parsed.baseToken, context.theme, context.plugins);
   if (!declaration) return "";
   const selector = `.${escapeCssIdentifier(parsed.original)}`;
-  const variantSelector = applyVariants(selector, parsed.variants);
+  const variantSelector = applyVariants(selector, parsed.variants, context.plugins);
   if (!variantSelector) return "";
   const finalDeclaration = appendImportant(
     isChildScoped(declaration) ? declaration.declaration : declaration,
@@ -3737,6 +3964,9 @@ function windrunner(options = {}) {
 export {
   compileClass,
   createWindrunner,
+  defineResponsiveUtilities,
+  defineUtilities,
   parseClass,
+  plugin,
   windrunner
 };