npm - windrunner - Versions diffs - 1.0.2 → 1.1.0 - Mend

windrunner 1.0.2 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/LICENSE CHANGED Viewed

@@ -1,15 +1,15 @@
-ISC License
-Copyright (c) 2026 Bigetion
-Permission to use, copy, modify, and/or distribute this software for any
-purpose with or without fee is hereby granted, provided that the above
-copyright notice and this permission notice appear in all copies.
-THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
-WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
-MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
-ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
-WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
-ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
-OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+ISC License
+Copyright (c) 2026 Bigetion
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md CHANGED Viewed

@@ -1,240 +1,328 @@
-# windrunner
-Zero-config Tailwind v4 runtime for the browser. Compile utility classes on-demand — no build step, no PostCSS, no config file.
-Drop a `<script>` tag and start using Tailwind classes anywhere.
-## How it works
-Instead of generating a full CSS bundle upfront, `windrunner` scans the DOM for class names and compiles only the CSS rules actually used — then injects them into a `<style>` tag in `<head>`. A `MutationObserver` watches for DOM changes and compiles new classes as they appear.
-```
-Page loads → scan DOM → compile used classes → inject <style>
-                ↑                                      |
-    MutationObserver detects new classes ←─────────────┘
-```
-## Install
-```bash
-npm install windrunner
-```
-## Usage
-### Drop-in script (zero config)
-```html
-<script type="module">
-  import { windrunner } from "windrunner";
-  windrunner({ autoStart: true });
-</script>
-<div class="flex items-center gap-4 p-6 bg-blue-50 rounded-xl">
-  <h1 class="text-2xl font-bold text-slate-900">Hello</h1>
-  <button class="px-4 py-2 bg-blue-500 text-white rounded-lg hover:bg-blue-600 transition-colors duration-200">
-    Click me
-  </button>
-</div>
-```
-### CDN
-```html
-<script type="module">
-  import { windrunner } from "https://cdn.jsdelivr.net/npm/windrunner@1.0.1/dist/index.min.js";
-  windrunner({ autoStart: true });
-</script>
-```
-### Live demo / Example landing page
-Try the example landing page:
-- CodeSandbox (example landing): https://xj6q66.csb.app
-### React / Vue
-```js
-import { useEffect } from "react";
-import { windrunner } from "windrunner";
-export default function App() {
-  useEffect(() => {
-    const wind = windrunner({ id: "my-app", autoStart: true });
-    return () => wind.disconnect();
-  }, []);
-  return (
-    <main className="min-h-screen bg-slate-50 p-8">
-      <h1 className="text-3xl font-bold text-slate-900">React + Windrunner</h1>
-    </main>
-  );
-}
-```
-### Manual control
-```js
-import { createWindrunner, compileClass } from "windrunner";
-// Compile a single class to a CSS rule string
-const css = compileClass("md:hover:bg-blue-500");
-// → '@media (min-width: 768px) { .md\\:hover\\:bg-blue-500:hover { background-color: oklch(...); } }'
-// Create an instance with full control
-const wind = createWindrunner({ id: "my-app" });
-wind.processClassList("flex items-center justify-between gap-4");
-wind.scan(); // scan entire document
-wind.observe(); // start watching DOM mutations
-wind.disconnect(); // stop watching
-```
-## API
-### `windrunner(options?)`
-Auto-start mode. Scans DOM and begins observing immediately.
-```ts
-windrunner({
-  id?: string,            // style tag id, default: "tailwind-runtime-css"
-  autoStart?: boolean,    // default: true
-  theme?: {               // override/extend theme values
-    extend: {
-      colors: { brand: "#ff6b6b" }
-    }
-  }
-})
-```
-### `createWindrunner(options?)`
-Returns a runtime instance with manual control methods:
-| Method | Description |
-|---|---|
-| `start()` | Scan DOM + start observer (waits for DOMContentLoaded) |
-| `scan(root?)` | One-time scan of all `[class]` elements |
-| `observe(root?)` | Start MutationObserver |
-| `processClassName(cls)` | Compile + inject one class |
-| `processClassList(str)` | Compile + inject space-separated classes |
-| `processElement(el)` | Compile all classes on a DOM element |
-| `flush()` | Force-flush pending element queue |
-| `disconnect()` | Stop observer, cleanup |
-| `getCacheSize()` | Number of compiled classes in cache |
-| `getInsertedRuleCount()` | Number of CSS rules injected |
-### `compileClass(className, options?)`
-Compile a single class name to a CSS rule string. Works in Node.js too.
-```js
-compileClass("hover:text-blue-500")
-// → '.hover\\:text-blue-500:hover { color: oklch(0.623 0.214 259.8); }'
-```
-### `parseClass(className, screens?, containers?)`
-Parse a class name into its parts:
-```js
-parseClass("md:hover:mt-4", { md: "768px" })
-// → { original: "md:hover:mt-4", baseToken: "mt-4", variants: ["hover"],
-//     breakpoint: "md", containerBreakpoint: null, important: false, starting: false }
-```
-## Supported utilities
-Full Tailwind v4 coverage including:
-- **Layout** — display, position, overflow, z-index, visibility, float, clear, aspect-ratio, columns, isolation, object-fit/position
-- **Spacing** — margin, padding, gap, space (with negative values)
-- **Sizing** — width, height, min/max-w/h, size-*
-- **Flexbox** — flex, grow, shrink, basis, direction, wrap, align, justify, place
-- **Grid** — grid-cols/rows, col/row-span, grid-flow, auto-cols/rows, place-*
-- **Typography** — font-size, font-weight, line-height, letter-spacing, text-align, text-color, text-decoration, text-transform, text-overflow, whitespace, word-break, list-style
-- **Colors** — all OKLCH P3 Tailwind v4 palette + mauve/olive/mist/taupe, opacity modifier (`bg-blue-500/50`)
-- **Backgrounds** — bg-color, bg-linear-to-* (v4), gradient stops (from/via/to), bg-size/position/repeat/attachment/clip/origin
-- **Borders** — border-width/style/color/radius (all sides + logical)
-- **Effects** — shadow, opacity, inset-shadow-* (v4), ring, inset-ring-* (v4)
-- **Transforms** — rotate, scale, translate (2D + 3D), skew, origin, perspective, backface, transform-style
-- **Filters** — blur, brightness, contrast, grayscale, hue-rotate, invert, saturate, sepia, drop-shadow, all backdrop-* variants
-- **Transitions** — transition, duration, delay, ease
-- **Animations** — animate-spin/ping/pulse/bounce
-- **Interactivity** — cursor, select, resize, outline, pointer-events, appearance, touch-action, scroll-behavior, scroll-margin/padding, will-change
-- **v4 New** — field-sizing-*, mask-*, @container, @container breakpoints (@sm: @md: etc.)
-- **Variants** — hover, focus, focus-visible, active, visited, disabled, dark, group-hover/focus, peer-*, not-hover/focus/disabled, in-hover, starting: (@starting-style), first/last/odd/even, before/after, placeholder
-## Custom theme
-```js
-windrunner({
-  autoStart: true,
-  theme: {
-    extend: {
-      colors: {
-        brand: {
-          50: "oklch(0.97 0.01 200)",
-          500: "oklch(0.55 0.18 200)",
-          900: "oklch(0.25 0.10 200)",
-        }
-      },
-      spacing: {
-        18: "4.5rem",
-        128: "32rem",
-      }
-    }
-  }
-});
-```
-## Preventing FOUC
-Because windrunner compiles CSS at runtime, browsers may briefly render unstyled content before styles are injected (Flash of Unstyled Content). The recommended fix:
-```html
-<head>
-  <!-- 1. Hide the page before styles are ready -->
-  <style>html { opacity: 0; transition: opacity 0.2s ease; }</style>
-  <!-- 2. Reveal after windrunner finishes its first scan -->
-  <script type="module">
-    import { windrunner } from "windrunner";
-    windrunner({
-      autoStart: true,
-      onReady: () => document.documentElement.style.opacity = "1",
-    });
-  </script>
-</head>
-```
-The `onReady` callback fires after the initial DOM scan completes and CSS rules are injected, ensuring the page is fully styled before it becomes visible. The `transition` gives a smooth 200ms fade-in instead of an abrupt pop.
-## Preflight
-windrunner injects a CSS reset (based on Tailwind's preflight) automatically. To opt out:
-```js
-windrunner({ autoStart: true, preflight: false });
-```
-## vs Tailwind Play CDN
-| | windrunner | Tailwind Play CDN |
-|---|---|---|
-| Size | ~78 KB min | ~350 KB |
-| Dependencies | 0 | 0 |
-| Tailwind version | v4 | v4 |
-| Works in Node.js | ✓ (compile only) | ✗ |
-| Custom theme | ✓ | ✓ |
-| Arbitrary values | ✓ | ✓ |
-| Preflight | ✓ | ✓ |
-| FOUC prevention | ✓ (onReady) | ✗ |
-| Plugins | ✗ | ✓ |
-| Full utility coverage | ✓ | ✓ |
-## License
-ISC
+# windrunner
+Zero-config Tailwind v4 runtime for the browser. Compile utility classes on-demand — no build step, no PostCSS, no config file.
+Drop a `<script>` tag and start using Tailwind classes anywhere.
+## How it works
+Instead of generating a full CSS bundle upfront, `windrunner` scans the DOM for class names and compiles only the CSS rules actually used — then injects them into a `<style>` tag in `<head>`. A `MutationObserver` watches for DOM changes and compiles new classes as they appear.
+```
+Page loads → scan DOM → compile used classes → inject <style>
+                ↑                                      |
+    MutationObserver detects new classes ←─────────────┘
+```
+## Install
+```bash
+npm install windrunner
+```
+## Usage
+### Drop-in script (zero config)
+```html
+<script type="module">
+  import { windrunner } from "windrunner";
+  windrunner({ autoStart: true });
+</script>
+<div class="flex items-center gap-4 p-6 bg-blue-50 rounded-xl">
+  <h1 class="text-2xl font-bold text-slate-900">Hello</h1>
+  <button class="px-4 py-2 bg-blue-500 text-white rounded-lg hover:bg-blue-600 transition-colors duration-200">
+    Click me
+  </button>
+</div>
+```
+### CDN
+```html
+<script type="module">
+  import { windrunner } from "https://cdn.jsdelivr.net/npm/windrunner@1.0.1/dist/index.min.js";
+  windrunner({ autoStart: true });
+</script>
+```
+### Live demo / Example landing page
+Try the example landing page:
+- CodeSandbox (example landing): https://xj6q66.csb.app
+### React / Vue
+```js
+import { useEffect } from "react";
+import { windrunner } from "windrunner";
+export default function App() {
+  useEffect(() => {
+    const wind = windrunner({ id: "my-app", autoStart: true });
+    return () => wind.disconnect();
+  }, []);
+  return (
+    <main className="min-h-screen bg-slate-50 p-8">
+      <h1 className="text-3xl font-bold text-slate-900">React + Windrunner</h1>
+    </main>
+  );
+}
+```
+### Manual control
+```js
+import { createWindrunner, compileClass } from "windrunner";
+// Compile a single class to a CSS rule string
+const css = compileClass("md:hover:bg-blue-500");
+// → '@media (min-width: 768px) { .md\\:hover\\:bg-blue-500:hover { background-color: oklch(...); } }'
+// Create an instance with full control
+const wind = createWindrunner({ id: "my-app" });
+wind.processClassList("flex items-center justify-between gap-4");
+wind.scan(); // scan entire document
+wind.observe(); // start watching DOM mutations
+wind.disconnect(); // stop watching
+```
+## API
+### `windrunner(options?)`
+Auto-start mode. Scans DOM and begins observing immediately.
+```ts
+windrunner({
+  id?: string,            // style tag id, default: "tailwind-runtime-css"
+  autoStart?: boolean,    // default: true
+  plugins?: Plugin[],     // custom plugins (see Plugin System)
+  theme?: {               // override/extend theme values
+    extend: {
+      colors: { brand: "#ff6b6b" }
+    }
+  }
+})
+```
+### Plugin System (NEW in v1.1.0)
+Create custom utilities and variants:
+```js
+import { windrunner, plugin } from 'windrunner';
+// Define a plugin
+const myPlugin = plugin(({ addUtility, addVariant, theme }) => {
+  // Add custom utility
+  addUtility('glass', 'backdrop-filter: blur(10px); background: rgba(255,255,255,0.1);');
+  // Add pattern-based utility
+  addUtility(/^text-stroke-(\d+)$/, (match) => {
+    return `-webkit-text-stroke-width: ${match[1]}px;`;
+  });
+  // Add custom variant
+  addVariant('parent-hover', (selector) => `.parent:hover ${selector}`);
+  // Access theme
+  const colors = theme('colors');
+  addUtility('brand-bg', `background-color: ${colors.brand};`);
+});
+// Use the plugin
+windrunner({
+  autoStart: true,
+  plugins: [myPlugin]
+});
+```
+See [Plugin Examples](./examples/plugins/) for ready-to-use plugins:
+- **text-stroke** - Text outline effects
+- **glass-morphism** - Glassmorphism effects
+- **custom-variants** - parent-hover, loading, and more
+**Plugin API:**
+- `addUtility(pattern, handler)` - Add custom utility
+- `addUtilities(utilities)` - Add multiple utilities
+- `addVariant(name, handler)` - Add custom variant
+- `theme(key)` - Access theme values
+- `config()` - Access full configuration
+Full plugin documentation: [Plugin System Guide](./docs/guides/plugins.md) (coming soon)
+### `createWindrunner(options?)`
+Returns a runtime instance with manual control methods:
+| Method | Description |
+|---|---|
+| `start()` | Scan DOM + start observer (waits for DOMContentLoaded) |
+| `scan(root?)` | One-time scan of all `[class]` elements |
+| `observe(root?)` | Start MutationObserver |
+| `processClassName(cls)` | Compile + inject one class |
+| `processClassList(str)` | Compile + inject space-separated classes |
+| `processElement(el)` | Compile all classes on a DOM element |
+| `flush()` | Force-flush pending element queue |
+| `disconnect()` | Stop observer, cleanup |
+| `getCacheSize()` | Number of compiled classes in cache |
+| `getInsertedRuleCount()` | Number of CSS rules injected |
+### `compileClass(className, options?)`
+Compile a single class name to a CSS rule string. Works in Node.js too.
+```js
+compileClass("hover:text-blue-500")
+// → '.hover\\:text-blue-500:hover { color: oklch(0.623 0.214 259.8); }'
+```
+### `parseClass(className, screens?, containers?)`
+Parse a class name into its parts:
+```js
+parseClass("md:hover:mt-4", { md: "768px" })
+// → { original: "md:hover:mt-4", baseToken: "mt-4", variants: ["hover"],
+//     breakpoint: "md", containerBreakpoint: null, important: false, starting: false }
+```
+## Supported utilities
+Full Tailwind v4 coverage including:
+- **Layout** — display, position, overflow, z-index, visibility, float, clear, aspect-ratio, columns, isolation, object-fit/position
+- **Spacing** — margin, padding, gap, space (with negative values)
+- **Sizing** — width, height, min/max-w/h, size-*
+- **Flexbox** — flex, grow, shrink, basis, direction, wrap, align, justify, place
+- **Grid** — grid-cols/rows, col/row-span, grid-flow, auto-cols/rows, place-*
+- **Typography** — font-size, font-weight, line-height, letter-spacing, text-align, text-color, text-decoration, text-transform, text-overflow, whitespace, word-break, list-style
+- **Colors** — all OKLCH P3 Tailwind v4 palette + mauve/olive/mist/taupe, opacity modifier (`bg-blue-500/50`)
+- **Backgrounds** — bg-color, bg-linear-to-* (v4), gradient stops (from/via/to), bg-size/position/repeat/attachment/clip/origin
+- **Borders** — border-width/style/color/radius (all sides + logical)
+- **Effects** — shadow, opacity, inset-shadow-* (v4), ring, inset-ring-* (v4)
+- **Transforms** — rotate, scale, translate (2D + 3D), skew, origin, perspective, backface, transform-style
+- **Filters** — blur, brightness, contrast, grayscale, hue-rotate, invert, saturate, sepia, drop-shadow, all backdrop-* variants
+- **Transitions** — transition, duration, delay, ease
+- **Animations** — animate-spin/ping/pulse/bounce
+- **Interactivity** — cursor, select, resize, outline, pointer-events, appearance, touch-action, scroll-behavior, scroll-margin/padding, will-change
+- **v4 New** — field-sizing-*, mask-*, @container, @container breakpoints (@sm: @md: etc.)
+- **Variants** — hover, focus, focus-visible, active, visited, disabled, dark, group-hover/focus, peer-*, not-hover/focus/disabled, in-hover, starting: (@starting-style), first/last/odd/even, before/after, placeholder
+## Custom theme
+```js
+windrunner({
+  autoStart: true,
+  theme: {
+    extend: {
+      colors: {
+        brand: {
+          50: "oklch(0.97 0.01 200)",
+          500: "oklch(0.55 0.18 200)",
+          900: "oklch(0.25 0.10 200)",
+        }
+      },
+      spacing: {
+        18: "4.5rem",
+        128: "32rem",
+      }
+    }
+  }
+});
+```
+## Preventing FOUC
+Because windrunner compiles CSS at runtime, browsers may briefly render unstyled content before styles are injected (Flash of Unstyled Content). The recommended fix:
+```html
+<head>
+  <!-- 1. Hide the page before styles are ready -->
+  <style>html { opacity: 0; transition: opacity 0.2s ease; }</style>
+  <!-- 2. Reveal after windrunner finishes its first scan -->
+  <script type="module">
+    import { windrunner } from "windrunner";
+    windrunner({
+      autoStart: true,
+      onReady: () => document.documentElement.style.opacity = "1",
+    });
+  </script>
+</head>
+```
+The `onReady` callback fires after the initial DOM scan completes and CSS rules are injected, ensuring the page is fully styled before it becomes visible. The `transition` gives a smooth 200ms fade-in instead of an abrupt pop.
+## Preflight
+windrunner injects a CSS reset (based on Tailwind's preflight) automatically. To opt out:
+```js
+windrunner({ autoStart: true, preflight: false });
+```
+## vs Tailwind Play CDN
+| | windrunner | Tailwind Play CDN |
+|---|---|---|
+| Size | ~78 KB min | ~350 KB |
+| Dependencies | 0 | 0 |
+| Tailwind version | v4 | v4 |
+| Works in Node.js | ✓ (compile only) | ✗ |
+| Custom theme | ✓ | ✓ |
+| Arbitrary values | ✓ | ✓ |
+| Preflight | ✓ | ✓ |
+| FOUC prevention | ✓ (onReady) | ✗ |
+| Plugins | ✗ | ✓ |
+| Full utility coverage | ✓ | ✓ |
+## 📚 Documentation
+**New to Windrunner?** Start here:
+- **[Quick Start Guide](./docs/getting-started/quick-start.md)** - Get running in 5 minutes
+- **[React Integration](./docs/frameworks/react.md)** - Best practices for React apps
+- **[FOUC Prevention](./docs/guides/fouc-prevention.md)** - 5 strategies to prevent flash of unstyled content
+- **[Full Documentation](./docs/)** - Complete guides, API reference, and recipes
+### Example Projects
+Learn by example with our sample applications:
+1. **[Landing Page](./examples/landing.html)** - Modern marketing page with animations
+2. **[Todo App](./examples/todo-app/)** - React app with dark mode and local storage
+3. **[Coverage Demo](./examples/coverage/)** - Showcase of utility class coverage
+## When to Use Windrunner
+✅ **Perfect for:**
+- Rapid prototyping and MVPs
+- Landing pages and marketing sites
+- Internal tools and dashboards
+- No-code platforms (Webflow, WordPress, etc.)
+- Projects without build tooling
+- Learning Tailwind v4
+⚠️ **Consider traditional Tailwind for:**
+- Large production apps with strict performance budgets
+- SEO-critical pages (requires FOUC prevention)
+- Projects already using PostCSS/build tools
+- Enterprise applications requiring battle-tested solutions
+See the [documentation](./docs/) for detailed use case analysis and migration guides.
+## Contributing
+Contributions are welcome! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
+Found a bug? Have a feature request? [Open an issue](https://github.com/Bigetion/windrunner/issues/new).
+## License
+ISC