@vitus-labs/styler 2.0.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023-present Vit Bokisch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,324 @@
+# @vitus-labs/styler
+
+A lightweight CSS-in-JS engine for React. Drop-in replacement for `styled-components` at a fraction of the size.
+
+**3.06 KB** gzipped | **React 18+** | **SSR ready** | **TypeScript strict**
+
+## Installation
+
+```bash
+npm install @vitus-labs/styler
+# or
+bun add @vitus-labs/styler
+```
+
+React 18+ is required as a peer dependency.
+
+## Quick Start
+
+```tsx
+import { styled, css, ThemeProvider } from '@vitus-labs/styler'
+
+const Button = styled('button')`
+  display: inline-flex;
+  align-items: center;
+  padding: 8px 16px;
+  border-radius: 4px;
+  background: ${({ theme }) => theme.colors.primary};
+  color: white;
+  cursor: pointer;
+
+  &:hover {
+    opacity: 0.9;
+  }
+`
+
+function App() {
+  return (
+    <ThemeProvider theme={{ colors: { primary: '#3b82f6' } }}>
+      <Button>Click me</Button>
+    </ThemeProvider>
+  )
+}
+```
+
+## API
+
+### `styled(tag)`
+
+Creates a styled React component from an HTML tag or another component.
+
+```tsx
+// HTML tag
+const Box = styled('div')`
+  display: flex;
+`
+
+// Shorthand (via Proxy)
+const Box = styled.div`
+  display: flex;
+`
+
+// Wrapping a component
+const StyledLink = styled(Link)`
+  color: blue;
+  text-decoration: none;
+`
+```
+
+#### Dynamic interpolations
+
+Function interpolations receive all props plus the current `theme`:
+
+```tsx
+const Text = styled('p')`
+  color: ${({ theme }) => theme.colors.text};
+  font-size: ${(props) => props.$size || '16px'};
+`
+```
+
+#### Polymorphic `as` prop
+
+Render as a different element at runtime:
+
+```tsx
+const Box = styled('div')`padding: 16px;`
+
+<Box as="section">Renders as a &lt;section&gt;</Box>
+```
+
+#### Ref forwarding
+
+All styled components forward refs via `React.forwardRef`:
+
+```tsx
+const Input = styled('input')`border: 1px solid #ccc;`
+
+const ref = useRef<HTMLInputElement>(null)
+<Input ref={ref} />
+```
+
+#### Transient props
+
+Props prefixed with `$` are not forwarded to the DOM:
+
+```tsx
+const Box = styled('div')`
+  color: ${(p) => p.$active ? 'blue' : 'gray'};
+`
+
+// $active is used for styling but won't appear on the <div>
+<Box $active />
+```
+
+#### Custom prop filtering
+
+```tsx
+const Box = styled('div', {
+  shouldForwardProp: (prop) => prop !== 'size',
+})`
+  font-size: ${(p) => p.size}px;
+`
+```
+
+### `css`
+
+Tagged template for composable CSS fragments:
+
+```tsx
+const flexCenter = css`
+  display: flex;
+  align-items: center;
+  justify-content: center;
+`
+
+const Card = styled('div')`
+  ${flexCenter};
+  padding: 16px;
+`
+```
+
+Supports conditional patterns:
+
+```tsx
+const Box = styled('div')`
+  display: flex;
+  ${(props) => props.$bordered && css`
+    border: 1px solid #e0e0e0;
+    border-radius: 4px;
+  `};
+`
+```
+
+### `keyframes`
+
+Creates `@keyframes` animations:
+
+```tsx
+const fadeIn = keyframes`
+  from { opacity: 0; }
+  to { opacity: 1; }
+`
+
+const FadeBox = styled('div')`
+  animation: ${fadeIn} 300ms ease-in;
+`
+```
+
+### `createGlobalStyle`
+
+Injects global CSS rules (not scoped to a class):
+
+```tsx
+const GlobalStyle = createGlobalStyle`
+  *, *::before, *::after {
+    box-sizing: border-box;
+  }
+
+  body {
+    margin: 0;
+    font-family: ${({ theme }) => theme.font};
+  }
+`
+
+// Renders nothing, injects CSS when mounted
+<GlobalStyle />
+```
+
+### `ThemeProvider` & `useTheme`
+
+Provides a theme object to all nested styled components via React context:
+
+```tsx
+const theme = {
+  colors: { primary: '#3b82f6', text: '#111' },
+  spacing: (n: number) => `${n * 4}px`,
+}
+
+<ThemeProvider theme={theme}>
+  <App />
+</ThemeProvider>
+```
+
+Access the theme from any component:
+
+```tsx
+const MyComponent = () => {
+  const theme = useTheme()
+  return <div style={{ color: theme.colors.primary }} />
+}
+```
+
+#### TypeScript theme augmentation
+
+Extend `DefaultTheme` for strict typing across your app:
+
+```ts
+declare module '@vitus-labs/styler' {
+  interface DefaultTheme {
+    colors: { primary: string; text: string }
+    spacing: (n: number) => string
+  }
+}
+```
+
+### `sheet` & `createSheet`
+
+The singleton `sheet` manages CSS rule injection. For SSR, use `createSheet` for per-request isolation:
+
+```tsx
+import { createSheet } from '@vitus-labs/styler'
+
+// Server-side rendering
+const sheet = createSheet()
+const html = renderToString(<App />)
+const styleTags = sheet.getStyleTag()  // <style data-vl="">...</style>
+sheet.reset()
+```
+
+#### `@layer` support
+
+Wrap all scoped rules in a CSS Cascade Layer:
+
+```tsx
+import { createSheet } from '@vitus-labs/styler'
+
+const sheet = createSheet({ layer: 'components' })
+```
+
+#### HMR cleanup
+
+```tsx
+if (import.meta.hot) {
+  import.meta.hot.accept(() => {
+    sheet.clearAll()
+  })
+}
+```
+
+## How It Works
+
+### Static path (zero runtime cost)
+
+Templates with no function interpolations are resolved **once at component creation time**. The CSS class is computed and injected immediately, and the React component is a thin `forwardRef` wrapper with no hooks.
+
+```tsx
+// Class computed once at import time, not on every render
+const Box = styled('div')`
+  display: flex;
+  padding: 16px;
+`
+```
+
+### Dynamic path
+
+Templates with function interpolations resolve on every render. The engine caches the last CSS string and skips re-hashing and re-injection when props haven't changed. Style injection uses `useInsertionEffect` for concurrent-mode safety.
+
+### CSS Nesting
+
+Native CSS nesting is supported out of the box. The engine passes CSS through without transformation, so `&:hover`, `&::before`, nested selectors, and `@media` queries work as-is in all modern browsers.
+
+```tsx
+const Card = styled('div')`
+  padding: 16px;
+
+  &:hover {
+    box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
+  }
+
+  & > h2 {
+    margin: 0 0 8px;
+  }
+
+  @media (min-width: 768px) {
+    padding: 24px;
+  }
+`
+```
+
+## Migrating from styled-components
+
+The API is intentionally compatible. Most code works by changing the import:
+
+```diff
+- import styled, { css, keyframes, createGlobalStyle, ThemeProvider } from 'styled-components'
++ import { styled, css, keyframes, createGlobalStyle, ThemeProvider } from '@vitus-labs/styler'
+```
+
+Key differences:
+
+| Feature | styled-components | @vitus-labs/styler |
+|---------|------------------|-------------------|
+| Bundle size | ~16 KB gz | **3.06 KB gz** |
+| `styled.div` shorthand | Yes | Yes |
+| `as` prop | Yes | Yes |
+| Ref forwarding | Yes | Yes |
+| Transient `$` props | Yes | Yes |
+| `shouldForwardProp` | `.withConfig()` | Second argument |
+| SSR | `ServerStyleSheet` | `createSheet()` |
+| CSS nesting | Preprocessed | Native (no transform) |
+| `attrs()` | Yes | Use `@vitus-labs/attrs` |
+
+## License
+
+MIT

package/lib/index.d.ts

@@ -0,0 +1,160 @@
+import * as react from "react";
+import { ComponentType, FC, ReactNode } from "react";
+
+//#region src/resolve.d.ts
+/**
+ * Interpolation resolver: converts tagged template strings + values into a
+ * final CSS string. Handles nested CSSResults, arrays, functions, and
+ * primitive values.
+ */
+type Interpolation = string | number | boolean | null | undefined | CSSResult | Interpolation[] | ((props: any) => Interpolation);
+/**
+ * Lazy representation of a `css` tagged template. Stores the raw template
+ * strings and interpolation values without resolving them. Resolution is
+ * deferred until a styled component renders (or until explicitly resolved).
+ */
+declare class CSSResult {
+  readonly strings: TemplateStringsArray;
+  readonly values: Interpolation[];
+  constructor(strings: TemplateStringsArray, values: Interpolation[]);
+  /** Resolve with empty props — useful for static templates, testing, and debugging. */
+  toString(): string;
+}
+//#endregion
+//#region src/css.d.ts
+/**
+ * Tagged template function for CSS. Captures the template strings and
+ * interpolation values as a lazy CSSResult — resolution is deferred
+ * until a styled component renders.
+ *
+ * Works as both a tagged template (`css\`...\``) and a regular function
+ * call (`css(...args)`) since tagged templates are syntactic sugar for
+ * function calls with (TemplateStringsArray, ...values).
+ */
+declare const css: (strings: TemplateStringsArray, ...values: Interpolation[]) => CSSResult;
+//#endregion
+//#region src/globalStyle.d.ts
+declare const createGlobalStyle: (strings: TemplateStringsArray, ...values: Interpolation[]) => {
+  (props: Record<string, any>): null;
+  displayName: string;
+};
+//#endregion
+//#region src/keyframes.d.ts
+declare class KeyframesResult {
+  readonly name: string;
+  constructor(strings: TemplateStringsArray, values: Interpolation[]);
+  /** Returns the animation name when used in string context. */
+  toString(): string;
+}
+declare const keyframes: (strings: TemplateStringsArray, ...values: Interpolation[]) => KeyframesResult;
+//#endregion
+//#region src/sheet.d.ts
+interface StyleSheetOptions {
+  /** Maximum number of cached rules before eviction (default: 10000). */
+  maxCacheSize?: number;
+  /** CSS @layer name to wrap scoped rules in. */
+  layer?: string;
+}
+declare class StyleSheet {
+  private cache;
+  private sheet;
+  private ssrBuffer;
+  private isSSR;
+  private maxCacheSize;
+  private layer;
+  constructor(options?: StyleSheetOptions);
+  private mount;
+  /** Parse existing rules from SSR-rendered <style> tag into cache. */
+  private hydrateFromTag;
+  /** Evict oldest entries when cache exceeds max size. */
+  private evictIfNeeded;
+  /**
+   * Compute a className from CSS text without injecting (pure function for render phase).
+   * Used with useInsertionEffect pattern: compute class during render, inject in effect.
+   */
+  getClassName(cssText: string): string;
+  /**
+   * Insert a CSS rule. Returns the class name (deterministic, hash-based).
+   * Deduplicates: same CSS text always produces the same class name and
+   * the rule is only injected once.
+   */
+  insert(cssText: string): string;
+  /** Insert a @keyframes rule. Deduplicates by animation name. */
+  insertKeyframes(name: string, body: string): void;
+  /** Insert a global CSS rule (no wrapper selector). Deduplicates by hash. */
+  insertGlobal(cssText: string): void;
+  /** Returns collected CSS for SSR as a complete `<style>` tag string. */
+  getStyleTag(): string;
+  /** Returns collected CSS rules as a raw string (useful for streaming SSR). */
+  getStyles(): string;
+  /** Reset SSR buffer (for concurrent server requests). */
+  reset(): void;
+  /** Clear the dedup cache. Useful for HMR / dev-time reloads. */
+  clearCache(): void;
+  /**
+   * Full cleanup: clear cache and remove all CSS rules from the DOM.
+   * Intended for HMR / dev-time reloads where stale styles must be purged.
+   *
+   *   if (import.meta.hot) {
+   *     import.meta.hot.accept(() => sheet.clearAll())
+   *   }
+   */
+  clearAll(): void;
+  /** Check if a className is already in the cache. O(1) Map lookup. */
+  has(className: string): boolean;
+  /** Current number of cached rules. */
+  get cacheSize(): number;
+}
+/** Default singleton sheet for client-side use. */
+declare const sheet: StyleSheet;
+/**
+ * Factory for creating isolated StyleSheet instances.
+ * Use in SSR to get per-request isolation:
+ *
+ *   const sheet = createSheet()
+ *   // render with this sheet...
+ *   const html = sheet.getStyleTag()
+ *   sheet.reset()
+ */
+declare const createSheet: (options?: StyleSheetOptions) => StyleSheet;
+//#endregion
+//#region src/styled.d.ts
+type Tag = string | ComponentType<any>;
+interface StyledOptions {
+  /** Custom prop filter. Return true to forward the prop to the DOM element. */
+  shouldForwardProp?: (prop: string) => boolean;
+}
+/** Factory function: styled(tag) returns a tagged template function. */
+declare const styledFactory: (tag: Tag, options?: StyledOptions) => (strings: TemplateStringsArray, ...values: Interpolation[]) => react.ForwardRefExoticComponent<Omit<Record<string, any>, "ref"> & react.RefAttributes<unknown>>;
+/**
+ * Main styled export. Supports both calling conventions:
+ * - `styled('div')` or `styled(Component)` → returns tagged template function
+ * - `styled('div', { shouldForwardProp })` → with custom prop filtering
+ * - `styled.div` → shorthand via Proxy (no options)
+ */
+declare const styled: typeof styledFactory & Record<string, (strings: TemplateStringsArray, ...values: Interpolation[]) => any>;
+//#endregion
+//#region src/ThemeProvider.d.ts
+/**
+ * Extensible theme interface. Consumers can augment this via module
+ * declaration merging for full strict types:
+ *
+ *   declare module '@vitus-labs/styler' {
+ *     interface DefaultTheme {
+ *       colors: { primary: string; secondary: string }
+ *       spacing: (n: number) => string
+ *     }
+ *   }
+ */
+type DefaultTheme = {};
+type Theme = DefaultTheme & Record<string, unknown>;
+/** Hook to read the current theme from the nearest ThemeProvider. */
+declare const useTheme: <T extends Theme = Theme>() => T;
+/** Provides a theme object to all nested styled components via React context. */
+declare const ThemeProvider: FC<{
+  theme: Theme;
+  children: ReactNode;
+}>;
+//#endregion
+export { type CSSResult, type DefaultTheme, type Interpolation, type StyleSheetOptions, type StyledOptions, ThemeProvider, createGlobalStyle, createSheet, css, keyframes, sheet, styled, useTheme };
+//# sourceMappingURL=index2.d.ts.map

package/lib/index.js

@@ -0,0 +1,691 @@
+import { Fragment, createContext, createElement, forwardRef, useContext, useInsertionEffect, useRef } from "react";
+import { jsx } from "react/jsx-runtime";
+
+//#region src/resolve.ts
+/**
+* Lazy representation of a `css` tagged template. Stores the raw template
+* strings and interpolation values without resolving them. Resolution is
+* deferred until a styled component renders (or until explicitly resolved).
+*/
+var CSSResult = class {
+	constructor(strings, values) {
+		this.strings = strings;
+		this.values = values;
+	}
+	/** Resolve with empty props — useful for static templates, testing, and debugging. */
+	toString() {
+		return resolve(this.strings, this.values, {});
+	}
+};
+/** Resolve a tagged template's strings + values into a final CSS string. */
+const resolve = (strings, values, props) => {
+	let result = strings[0] ?? "";
+	for (let i = 0; i < values.length; i++) result += resolveValue(values[i], props) + (strings[i + 1] ?? "");
+	return result;
+};
+/**
+* Normalize resolved CSS text for strict `insertRule` compatibility.
+* Removes double semicolons, empty declarations, and excess whitespace
+* that arise from template interpolation (conditional expressions,
+* empty CSSResult values, etc.).
+*/
+const normalizeCSS = (css) => {
+	let s = css.replace(/\s+/g, " ").trim();
+	while (s.includes("; ;") || s.includes(";;")) s = s.replace(/;(\s*;)+/g, ";");
+	s = s.replace(/\{\s*;/g, "{").replace(/}\s*;/g, "}");
+	s = s.replace(/^\s*;/, "").trim();
+	return s;
+};
+const resolveValue = (value, props) => {
+	if (value == null || value === false || value === true) return "";
+	if (typeof value === "function") return resolveValue(value(props), props);
+	if (value instanceof CSSResult) return resolve(value.strings, value.values, props);
+	if (Array.isArray(value)) {
+		let arrayResult = "";
+		for (let i = 0; i < value.length; i++) arrayResult += resolveValue(value[i], props);
+		return arrayResult;
+	}
+	return String(value);
+};
+
+//#endregion
+//#region src/css.ts
+/**
+* Tagged template function for CSS. Captures the template strings and
+* interpolation values as a lazy CSSResult — resolution is deferred
+* until a styled component renders.
+*
+* Works as both a tagged template (`css\`...\``) and a regular function
+* call (`css(...args)`) since tagged templates are syntactic sugar for
+* function calls with (TemplateStringsArray, ...values).
+*/
+const css = (strings, ...values) => new CSSResult(strings, values);
+
+//#endregion
+//#region src/shared.ts
+/**
+* Shared utilities used across multiple modules.
+*/
+/** Check if an interpolation value is dynamic (contains functions or nested dynamic CSSResults). */
+const isDynamic = (v) => {
+	if (typeof v === "function") return true;
+	if (Array.isArray(v)) return v.some(isDynamic);
+	if (v instanceof CSSResult) return v.values.some(isDynamic);
+	return false;
+};
+
+//#endregion
+//#region src/hash.ts
+/**
+* Fast FNV-1a non-cryptographic hash. Returns base-36 string for compact class names.
+*
+* 32-bit hash space → ~4.3 billion unique values. Collision probability is
+* negligible for typical applications (< 10,000 unique CSS rules). If a collision
+* did occur, two different CSS strings would share the same class name and only
+* the first would be injected (dedup). In practice this is a non-issue — CSS
+* strings are rarely similar enough to collide under FNV-1a's avalanche properties.
+*/
+/** FNV-1a offset basis — starting state for streaming hash. */
+const HASH_INIT = 2166136261;
+const FNV_PRIME = 16777619;
+/**
+* Feed a string segment into the running hash state.
+* Streaming: hashUpdate(hashUpdate(HASH_INIT, 'ab'), 'cd') === hash('abcd').
+*/
+const hashUpdate = (h, str) => {
+	for (let i = 0; i < str.length; i++) {
+		h ^= str.charCodeAt(i);
+		h = Math.imul(h, FNV_PRIME);
+	}
+	return h;
+};
+/** Finalize a hash state into a base-36 class name suffix. */
+const hashFinalize = (h) => (h >>> 0).toString(36);
+/** Hash a complete string in one shot. Returns base-36 string. */
+const hash = (str) => hashFinalize(hashUpdate(HASH_INIT, str));
+
+//#endregion
+//#region src/sheet.ts
+/**
+* StyleSheet manager. Handles CSS rule injection, hash-based deduplication,
+* SSR buffering, client-side hydration, bounded cache, and @layer support.
+*/
+const PREFIX = "vl";
+const ATTR = `data-${PREFIX}`;
+const DEFAULT_MAX_CACHE_SIZE = 1e4;
+var StyleSheet = class {
+	cache = /* @__PURE__ */ new Map();
+	sheet = null;
+	ssrBuffer = [];
+	isSSR;
+	maxCacheSize;
+	layer;
+	constructor(options = {}) {
+		this.maxCacheSize = options.maxCacheSize ?? DEFAULT_MAX_CACHE_SIZE;
+		this.layer = options.layer;
+		this.isSSR = typeof document === "undefined";
+		if (!this.isSSR) this.mount();
+	}
+	mount() {
+		const existing = document.querySelector(`style[${ATTR}]`);
+		if (existing) {
+			this.sheet = existing.sheet ?? null;
+			this.hydrateFromTag(existing);
+		} else {
+			const el = document.createElement("style");
+			el.setAttribute(ATTR, "");
+			document.head.appendChild(el);
+			this.sheet = el.sheet ?? null;
+		}
+		if (this.layer && this.sheet) try {
+			this.sheet.insertRule(`@layer ${this.layer};`, 0);
+		} catch {}
+	}
+	/** Parse existing rules from SSR-rendered <style> tag into cache. */
+	hydrateFromTag(el) {
+		const sheet = el.sheet;
+		if (!sheet) return;
+		for (let i = 0; i < sheet.cssRules.length; i++) {
+			const rule = sheet.cssRules[i];
+			if (rule instanceof CSSStyleRule) {
+				const className = rule.selectorText.slice(1);
+				this.cache.set(className, className);
+			}
+		}
+	}
+	/** Evict oldest entries when cache exceeds max size. */
+	evictIfNeeded() {
+		if (this.cache.size <= this.maxCacheSize) return;
+		const toDelete = Math.floor(this.maxCacheSize * .1);
+		let count = 0;
+		for (const key of this.cache.keys()) {
+			if (count >= toDelete) break;
+			this.cache.delete(key);
+			count++;
+		}
+	}
+	/**
+	* Compute a className from CSS text without injecting (pure function for render phase).
+	* Used with useInsertionEffect pattern: compute class during render, inject in effect.
+	*/
+	getClassName(cssText) {
+		return `${PREFIX}-${hash(cssText)}`;
+	}
+	/**
+	* Insert a CSS rule. Returns the class name (deterministic, hash-based).
+	* Deduplicates: same CSS text always produces the same class name and
+	* the rule is only injected once.
+	*/
+	insert(cssText) {
+		const className = `${PREFIX}-${hash(cssText)}`;
+		if (this.cache.has(className)) return className;
+		this.evictIfNeeded();
+		this.cache.set(className, className);
+		const baseRule = `.${className}{${cssText}}`;
+		const rule = this.layer ? `@layer ${this.layer}{${baseRule}}` : baseRule;
+		if (this.isSSR) this.ssrBuffer.push(rule);
+		else if (this.sheet) try {
+			this.sheet.insertRule(rule, this.sheet.cssRules.length);
+		} catch (e) {
+			if (process.env.NODE_ENV !== "production") console.warn(`[styler] Failed to insert CSS rule for .${className}:`, e.message, "\nCSS:", cssText.slice(0, 200));
+		}
+		return className;
+	}
+	/** Insert a @keyframes rule. Deduplicates by animation name. */
+	insertKeyframes(name, body) {
+		if (this.cache.has(name)) return;
+		this.evictIfNeeded();
+		this.cache.set(name, name);
+		const rule = `@keyframes ${name}{${body}}`;
+		if (this.isSSR) this.ssrBuffer.push(rule);
+		else if (this.sheet) try {
+			this.sheet.insertRule(rule, this.sheet.cssRules.length);
+		} catch (e) {
+			if (process.env.NODE_ENV !== "production") console.warn(`[styler] Failed to insert @keyframes "${name}":`, e.message);
+		}
+	}
+	/** Insert a global CSS rule (no wrapper selector). Deduplicates by hash. */
+	insertGlobal(cssText) {
+		const key = `global-${hash(cssText)}`;
+		if (this.cache.has(key)) return;
+		this.evictIfNeeded();
+		this.cache.set(key, key);
+		if (this.isSSR) this.ssrBuffer.push(cssText);
+		else if (this.sheet) try {
+			this.sheet.insertRule(cssText, this.sheet.cssRules.length);
+		} catch (e) {
+			if (process.env.NODE_ENV !== "production") console.warn("[styler] Failed to insert global CSS rule:", e.message, "\nCSS:", cssText.slice(0, 200));
+		}
+	}
+	/** Returns collected CSS for SSR as a complete `<style>` tag string. */
+	getStyleTag() {
+		return `<style ${ATTR}="">${this.ssrBuffer.join("")}</style>`;
+	}
+	/** Returns collected CSS rules as a raw string (useful for streaming SSR). */
+	getStyles() {
+		return this.ssrBuffer.join("");
+	}
+	/** Reset SSR buffer (for concurrent server requests). */
+	reset() {
+		this.ssrBuffer = [];
+	}
+	/** Clear the dedup cache. Useful for HMR / dev-time reloads. */
+	clearCache() {
+		this.cache.clear();
+	}
+	/**
+	* Full cleanup: clear cache and remove all CSS rules from the DOM.
+	* Intended for HMR / dev-time reloads where stale styles must be purged.
+	*
+	*   if (import.meta.hot) {
+	*     import.meta.hot.accept(() => sheet.clearAll())
+	*   }
+	*/
+	clearAll() {
+		this.cache.clear();
+		this.ssrBuffer = [];
+		if (this.sheet) while (this.sheet.cssRules.length > 0) this.sheet.deleteRule(0);
+	}
+	/** Check if a className is already in the cache. O(1) Map lookup. */
+	has(className) {
+		return this.cache.has(className);
+	}
+	/** Current number of cached rules. */
+	get cacheSize() {
+		return this.cache.size;
+	}
+};
+/** Default singleton sheet for client-side use. */
+const sheet = new StyleSheet();
+/**
+* Factory for creating isolated StyleSheet instances.
+* Use in SSR to get per-request isolation:
+*
+*   const sheet = createSheet()
+*   // render with this sheet...
+*   const html = sheet.getStyleTag()
+*   sheet.reset()
+*/
+const createSheet = (options) => new StyleSheet(options);
+
+//#endregion
+//#region src/ThemeProvider.tsx
+const ThemeContext = createContext({});
+/** Hook to read the current theme from the nearest ThemeProvider. */
+const useTheme = () => useContext(ThemeContext);
+/** Provides a theme object to all nested styled components via React context. */
+const ThemeProvider = ({ theme, children }) => /* @__PURE__ */ jsx(ThemeContext.Provider, {
+	value: theme,
+	children
+});
+
+//#endregion
+//#region src/globalStyle.ts
+/**
+* createGlobalStyle() — tagged template function that injects global CSS
+* rules (not scoped to a class name). Returns a React component that
+* injects styles when mounted and supports dynamic interpolations via
+* props/theme.
+*
+* Usage:
+*   const GlobalStyle = createGlobalStyle`
+*     body { margin: 0; font-family: ${({ theme }) => theme.font}; }
+*     *, *::before, *::after { box-sizing: border-box; }
+*   `
+*   // <GlobalStyle /> — renders nothing, injects global CSS
+*
+* Approach inspired by Goober's glob() + styled-components' API:
+* - Static templates: inject once at component creation (no React overhead)
+* - Dynamic templates: re-inject on prop/theme change via useInsertionEffect
+* - Hash-based dedup prevents duplicate injection
+*/
+const createGlobalStyle = (strings, ...values) => {
+	if (!values.some(isDynamic)) {
+		const cssText = normalizeCSS(resolve(strings, values, {}));
+		if (cssText.trim()) sheet.insertGlobal(cssText);
+		const StaticGlobal = () => null;
+		StaticGlobal.displayName = "GlobalStyle";
+		return StaticGlobal;
+	}
+	const DynamicGlobal = (props) => {
+		const theme = useTheme();
+		const cssText = normalizeCSS(resolve(strings, values, {
+			...props,
+			theme
+		}));
+		const prevCssRef = useRef("");
+		useInsertionEffect(() => {
+			if (cssText !== prevCssRef.current) {
+				prevCssRef.current = cssText;
+				if (cssText.trim()) sheet.insertGlobal(cssText);
+			}
+		});
+		return null;
+	};
+	DynamicGlobal.displayName = "GlobalStyle";
+	return DynamicGlobal;
+};
+
+//#endregion
+//#region src/keyframes.ts
+/**
+* keyframes() tagged template function. Creates a CSS @keyframes rule,
+* injects it into the stylesheet, and returns the generated animation name.
+*
+* Usage:
+*   const fadeIn = keyframes`
+*     from { opacity: 0; }
+*     to { opacity: 1; }
+*   `
+*   // fadeIn === "vl-kf-abc123" (deterministic, hash-based)
+*
+* Supports interpolation values (strings, numbers) but NOT function
+* interpolations — keyframes are static by nature.
+*/
+var KeyframesResult = class {
+	name;
+	constructor(strings, values) {
+		const body = normalizeCSS(resolve(strings, values, {}));
+		this.name = `vl-kf-${hash(body)}`;
+		sheet.insertKeyframes(this.name, body);
+	}
+	/** Returns the animation name when used in string context. */
+	toString() {
+		return this.name;
+	}
+};
+const keyframes = (strings, ...values) => new KeyframesResult(strings, values);
+
+//#endregion
+//#region src/forward.ts
+/**
+* HTML prop filtering. Prevents unknown props from being forwarded to DOM
+* elements (which causes React warnings). Props starting with `$` are
+* transient (styling-only) and are always filtered out.
+*/
+const HTML_PROPS = new Set([
+	"children",
+	"className",
+	"dangerouslySetInnerHTML",
+	"htmlFor",
+	"id",
+	"key",
+	"ref",
+	"style",
+	"tabIndex",
+	"role",
+	"onAbort",
+	"onAnimationEnd",
+	"onAnimationIteration",
+	"onAnimationStart",
+	"onBlur",
+	"onChange",
+	"onClick",
+	"onCompositionEnd",
+	"onCompositionStart",
+	"onCompositionUpdate",
+	"onContextMenu",
+	"onCopy",
+	"onCut",
+	"onDoubleClick",
+	"onDrag",
+	"onDragEnd",
+	"onDragEnter",
+	"onDragLeave",
+	"onDragOver",
+	"onDragStart",
+	"onDrop",
+	"onError",
+	"onFocus",
+	"onInput",
+	"onKeyDown",
+	"onKeyPress",
+	"onKeyUp",
+	"onLoad",
+	"onMouseDown",
+	"onMouseEnter",
+	"onMouseLeave",
+	"onMouseMove",
+	"onMouseOut",
+	"onMouseOver",
+	"onMouseUp",
+	"onPaste",
+	"onPointerCancel",
+	"onPointerDown",
+	"onPointerEnter",
+	"onPointerLeave",
+	"onPointerMove",
+	"onPointerOut",
+	"onPointerOver",
+	"onPointerUp",
+	"onScroll",
+	"onSelect",
+	"onSubmit",
+	"onTouchCancel",
+	"onTouchEnd",
+	"onTouchMove",
+	"onTouchStart",
+	"onTransitionEnd",
+	"onWheel",
+	"accept",
+	"acceptCharset",
+	"accessKey",
+	"action",
+	"allow",
+	"allowFullScreen",
+	"alt",
+	"as",
+	"async",
+	"autoCapitalize",
+	"autoComplete",
+	"autoCorrect",
+	"autoFocus",
+	"autoPlay",
+	"capture",
+	"cellPadding",
+	"cellSpacing",
+	"charSet",
+	"checked",
+	"cite",
+	"cols",
+	"colSpan",
+	"content",
+	"contentEditable",
+	"controls",
+	"controlsList",
+	"coords",
+	"crossOrigin",
+	"dateTime",
+	"decoding",
+	"default",
+	"defaultChecked",
+	"defaultValue",
+	"defer",
+	"dir",
+	"disabled",
+	"disablePictureInPicture",
+	"disableRemotePlayback",
+	"download",
+	"draggable",
+	"encType",
+	"enterKeyHint",
+	"fetchPriority",
+	"form",
+	"formAction",
+	"formEncType",
+	"formMethod",
+	"formNoValidate",
+	"formTarget",
+	"frameBorder",
+	"headers",
+	"height",
+	"hidden",
+	"high",
+	"href",
+	"hrefLang",
+	"httpEquiv",
+	"inputMode",
+	"integrity",
+	"is",
+	"label",
+	"lang",
+	"list",
+	"loading",
+	"loop",
+	"low",
+	"max",
+	"maxLength",
+	"media",
+	"method",
+	"min",
+	"minLength",
+	"multiple",
+	"muted",
+	"name",
+	"noModule",
+	"noValidate",
+	"nonce",
+	"open",
+	"optimum",
+	"pattern",
+	"placeholder",
+	"playsInline",
+	"poster",
+	"preload",
+	"readOnly",
+	"referrerPolicy",
+	"rel",
+	"required",
+	"reversed",
+	"rows",
+	"rowSpan",
+	"sandbox",
+	"scope",
+	"scoped",
+	"scrolling",
+	"selected",
+	"shape",
+	"size",
+	"sizes",
+	"slot",
+	"span",
+	"spellCheck",
+	"src",
+	"srcDoc",
+	"srcLang",
+	"srcSet",
+	"start",
+	"step",
+	"summary",
+	"target",
+	"title",
+	"translate",
+	"type",
+	"useMap",
+	"value",
+	"width",
+	"wrap"
+]);
+/**
+* Filters props for HTML elements. Keeps valid HTML attrs, data-*, aria-*.
+* Rejects unknown props and $-prefixed transient props.
+*/
+const filterProps = (props) => {
+	const filtered = {};
+	for (const key in props) {
+		if (key.charCodeAt(0) === 36) continue;
+		if (key === "as") continue;
+		if (key.startsWith("data-") || key.startsWith("aria-")) {
+			filtered[key] = props[key];
+			continue;
+		}
+		if (HTML_PROPS.has(key)) filtered[key] = props[key];
+	}
+	return filtered;
+};
+
+//#endregion
+//#region src/styled.ts
+/**
+* styled() component factory. Creates React components that inject CSS
+* class names from tagged template literals.
+*
+* Supports:
+* - styled('div')`...` and styled(Component)`...`
+* - styled.div`...` (via Proxy)
+* - `as` prop for polymorphic rendering
+* - forwardRef for ref forwarding
+* - $-prefixed transient props (not forwarded to DOM)
+* - Custom shouldForwardProp for per-component prop filtering
+* - Static path optimization (templates with no dynamic interpolations)
+* - useInsertionEffect for safe concurrent-mode style injection
+*
+* CSS nesting (`&` selectors) works natively — the resolver passes CSS
+* through without transformation, so `&:hover`, `&::before`, etc. work
+* as-is in browsers supporting CSS Nesting (all modern browsers).
+*/
+const IS_SERVER = typeof document === "undefined";
+const getDisplayName = (tag) => typeof tag === "string" ? tag : tag.displayName || tag.name || "Component";
+const mergeClassNames = (generated, user) => {
+	if (!user) return generated;
+	if (!generated) return user;
+	return `${generated} ${user}`;
+};
+const applyPropFilter = (props, customFilter) => {
+	if (customFilter) {
+		const filtered = {};
+		for (const key in props) if (customFilter(key)) filtered[key] = props[key];
+		return filtered;
+	}
+	return filterProps(props);
+};
+const createStyledComponent = (tag, strings, values, options) => {
+	const hasDynamicValues = values.some(isDynamic);
+	const customFilter = options?.shouldForwardProp;
+	if (!hasDynamicValues) {
+		const cssText = normalizeCSS(resolve(strings, values, {}));
+		const staticClassName = cssText.trim() ? sheet.insert(cssText) : "";
+		const staticRule = staticClassName ? `.${staticClassName}{${cssText}}` : "";
+		const StaticStyled = forwardRef(({ as: asProp, className: userCls, ...props }, ref) => {
+			const finalTag = asProp || tag;
+			const finalCls = mergeClassNames(staticClassName, userCls);
+			const el = createElement(finalTag, {
+				...typeof finalTag === "string" ? applyPropFilter(props, customFilter) : props,
+				className: finalCls || void 0,
+				ref
+			});
+			if (staticRule) return createElement(Fragment, null, createElement("style", {
+				"data-vl": "",
+				dangerouslySetInnerHTML: { __html: staticRule }
+			}), el);
+			return el;
+		});
+		StaticStyled.displayName = `styled(${getDisplayName(tag)})`;
+		return StaticStyled;
+	}
+	const DynamicStyled = forwardRef(({ as: asProp, className: userCls, ...props }, ref) => {
+		const theme = useTheme();
+		const cssText = normalizeCSS(resolve(strings, values, {
+			...props,
+			theme
+		}));
+		const lastCssRef = useRef("");
+		const lastClsRef = useRef("");
+		const insertedRef = useRef(false);
+		let className;
+		if (cssText === lastCssRef.current) className = lastClsRef.current;
+		else {
+			className = cssText.trim() ? sheet.getClassName(cssText) : "";
+			lastCssRef.current = cssText;
+			lastClsRef.current = className;
+			insertedRef.current = false;
+		}
+		if (IS_SERVER) {
+			if (!insertedRef.current && cssText.trim()) {
+				sheet.insert(cssText);
+				insertedRef.current = true;
+			}
+		}
+		const mountedRef = useRef(false);
+		useInsertionEffect(() => {
+			mountedRef.current = true;
+			if (!insertedRef.current && lastCssRef.current.trim()) {
+				sheet.insert(lastCssRef.current);
+				insertedRef.current = true;
+			}
+		});
+		const finalTag = asProp || tag;
+		const finalCls = mergeClassNames(className, userCls);
+		const el = createElement(finalTag, {
+			...typeof finalTag === "string" ? applyPropFilter(props, customFilter) : props,
+			className: finalCls || void 0,
+			ref
+		});
+		if (!mountedRef.current && className) return createElement(Fragment, null, createElement("style", {
+			"data-vl": "",
+			dangerouslySetInnerHTML: { __html: `.${className}{${cssText}}` }
+		}), el);
+		return el;
+	});
+	DynamicStyled.displayName = `styled(${getDisplayName(tag)})`;
+	return DynamicStyled;
+};
+/** Factory function: styled(tag) returns a tagged template function. */
+const styledFactory = (tag, options) => {
+	const templateFn = (strings, ...values) => createStyledComponent(tag, strings, values, options);
+	return templateFn;
+};
+/**
+* Main styled export. Supports both calling conventions:
+* - `styled('div')` or `styled(Component)` → returns tagged template function
+* - `styled('div', { shouldForwardProp })` → with custom prop filtering
+* - `styled.div` → shorthand via Proxy (no options)
+*/
+const styled = new Proxy(styledFactory, { get(_target, prop) {
+	if (prop === "prototype" || prop === "$$typeof") return void 0;
+	return (strings, ...values) => createStyledComponent(prop, strings, values);
+} });
+
+//#endregion
+export { ThemeProvider, createGlobalStyle, createSheet, css, keyframes, sheet, styled, useTheme };
+//# sourceMappingURL=index.js.map

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@vitus-labs/styler",
+  "version": "2.0.0-alpha.0",
+  "license": "MIT",
+  "author": "Vit Bokisch <vit@bokisch.cz>",
+  "maintainers": [
+    "Vit Bokisch <vit@bokisch.cz>"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    "source": "./src/index.ts",
+    "import": "./lib/index.js",
+    "types": "./lib/index.d.ts"
+  },
+  "types": "./lib/index.d.ts",
+  "files": [
+    "lib",
+    "!lib/**/*.map",
+    "!lib/analysis"
+  ],
+  "homepage": "https://github.com/vitus-labs/ui-system/tree/master/packages/styler",
+  "description": "Lightweight CSS-in-JS engine for vitus-labs packages",
+  "keywords": [
+    "vitus-labs",
+    "css-in-js",
+    "styled-components",
+    "css",
+    "styling"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vitus-labs/ui-system",
+    "directory": "packages/styler"
+  },
+  "bugs": {
+    "url": "https://github.com/vitus-labs/ui-system/issues"
+  },
+  "engines": {
+    "node": ">= 18"
+  },
+  "scripts": {
+    "prepublish": "bun run build",
+    "build": "bun run vl_rolldown_build",
+    "build:watch": "bun run vl_rolldown_build-watch",
+    "lint": "biome check src/",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "react": ">= 18"
+  },
+  "devDependencies": {
+    "@emotion/react": "^11.14.0",
+    "@emotion/styled": "^11.14.1",
+    "@vitus-labs/tools-rolldown": "^1.6.0",
+    "@vitus-labs/tools-typescript": "^1.6.0",
+    "goober": "^2.1.18",
+    "styled-components": "^6.3.9"
+  },
+  "gitHead": "f2221c6fe2db3e39bfe1c30dc7ff0c01e2c66dc5"
+}