@stylix/core 6.1.1 → 6.3.0

package/docs/performance.md

@@ -0,0 +1,291 @@
+# Performance Guide
+
+Stylix is a runtime CSS-in-JS library. This means styles are generated and injected into the DOM at runtime, rather than at build time. For most applications, this has negligible performance impact. However, understanding how Stylix works can help you avoid patterns that cause unnecessary work.
+
+---
+
+## How Stylix Works
+
+When a Stylix component renders:
+
+1. **Style props are collected** and combined with any `$css` prop
+2. **Styles are normalized** ("preprocessing" - minimal; falsy values are removed)
+3. **A cache key is created** by serializing the style object
+4. **If the key is new**, a className is generated, plugins process the styles into CSS (resolving media keywords, adding units, etc.), and the rules are stored
+5. **If the key exists**, the existing className is reused (no new CSS generated)
+6. **Reference counting** tracks how many components use each style
+7. **The stylesheet is updated** via `useInsertionEffect`, batching changes efficiently
+
+This means:
+- **Identical styles share a class name** — rendering 100 `<$.div color="red" />` elements creates only one CSS rule
+- **Style generation is cached** — the same styles produce the same class name
+- **Unused styles are cleaned up** — when no components reference a style, it's removed
+
+---
+
+## Do's
+
+### Do: Keep Style Objects Stable
+
+For extra high performance (100+ reuses of a component), define style objects outside the component:
+
+```tsx
+// Good: Object reference is stable
+const cardStyles = {
+  padding: 16,
+  borderRadius: 8,
+  '&:hover': { boxShadow: '0 4px 12px rgba(0,0,0,0.1)' }
+};
+
+function Card({ children }) {
+  return <$.div $css={cardStyles}>{children}</$.div>;
+}
+```
+
+Even if styles are only simple CSS properties, using `$css` with a stable object reference avoids unnecessary hashing work.
+
+### Do: Define Media Config at App Root
+
+Define breakpoints once, not in every component:
+
+```tsx
+// Good: Single definition at root
+<StylixProvider
+  media={{
+    mobile: styles => ({ '@media (max-width: 767px)': styles }),
+    tablet: styles => ({ '@media (max-width: 1023px)': styles }),
+  }}
+>
+  <App />
+</StylixProvider>
+```
+
+### Do: Use CSS Transitions for Animations
+
+For property changes, CSS transitions are more efficient than re-rendering:
+
+```tsx
+// Good: Browser handles the animation
+<$.div
+  opacity={isVisible ? 1 : 0}
+  transform={isVisible ? 'translateY(0)' : 'translateY(-10px)'}
+  transition="opacity 0.3s, transform 0.3s"
+/>
+```
+
+### Do: Use `useKeyframes` for Complex Animations
+
+Keyframes are hoisted and deduplicated automatically:
+
+```tsx
+const fadeIn = useKeyframes({
+  from: { opacity: 0 },
+  to: { opacity: 1 }
+});
+
+// The keyframes are only injected once, even if many components use them
+<$.div animation={`${fadeIn} 0.3s ease-out`} />
+```
+
+---
+
+## Don'ts
+
+### Don't: Create New Style Objects Every Render
+
+For extra high performance (100+ reuses of a component), don't use inline style objects, which are recreated on every render:
+
+```tsx
+// Avoid: New object every render
+function Card({ children }) {
+  return (
+    <$.div
+      $css={{  // New object reference every render
+        padding: 16,
+        '&:hover': { boxShadow: '...' }
+      }}
+    >
+      {children}
+    </$.div>
+  );
+}
+```
+
+**Why it matters:** While Stylix caches styles by content (so the CSS won't be regenerated), it still has to hash and compare the object each render. For frequently-rendered components, this adds up.
+
+**Fix:** Extract the styles or memoize them:
+
+```tsx
+// Better: Stable reference
+const cardStyles = {
+  padding: 16,
+  '&:hover': { boxShadow: '...' }
+};
+
+function Card({ children }) {
+  return <$.div $css={cardStyles}>{children}</$.div>;
+}
+```
+
+### Don't: Generate Many Unique Style Combinations Dynamically
+
+```tsx
+// Avoid: Potentially thousands of unique styles
+function DataCell({ value }) {
+  return (
+    <$.td
+      background={`hsl(${value * 3.6}, 70%, 50%)`}  // Unique for each value 0-100
+    />
+  );
+}
+
+// Used in a large table:
+{data.map((row, i) => (
+  <tr key={i}>
+    {row.map((value, j) => (
+      <DataCell key={j} value={value} />  // Could generate 100+ unique styles
+    ))}
+  </tr>
+))}
+```
+
+**Why it matters:** Each unique style combination creates a new CSS rule. Hundreds of rules slow down both generation and browser style calculation.
+
+**Fix:** Use the native `style` prop for truly dynamic values, or bucket values into ranges:
+
+```tsx
+// Better: Use style prop for per-cell values
+function DataCell({ value }) {
+  return (
+    <$.td style={{ background: `hsl(${value * 3.6}, 70%, 50%)` }} />
+  );
+}
+
+// Or: Bucket into classes
+function DataCell({ value }) {
+  const bucket = Math.floor(value / 10) * 10;  // 0, 10, 20, ... 100
+  return <$.td background={`var(--heat-${bucket})`} />;
+}
+```
+
+### Don't: Use Stylix for High-Frequency Updates
+
+```tsx
+// Avoid: Style changes 60 times per second
+function AnimatedElement({ progress }) {
+  return (
+    <$.div
+      transform={`translateX(${progress * 100}px)`}  // Changes every frame
+    />
+  );
+}
+```
+
+**Why it matters:** Generating and comparing styles on every animation frame adds overhead. Browsers are optimized for inline style updates, not class changes.
+
+**Fix:** Use the native `style` prop or CSS animations:
+
+```tsx
+// Better: Use style prop for frame-by-frame updates
+function AnimatedElement({ progress }) {
+  return (
+    <$.div
+      style={{ transform: `translateX(${progress * 100}px)` }}
+    />
+  );
+}
+
+// Best: Use CSS for the animation entirely
+function AnimatedElement() {
+  const slide = useKeyframes({
+    from: { transform: 'translateX(0)' },
+    to: { transform: 'translateX(100px)' }
+  });
+
+  return <$.div animation={`${slide} 1s ease-out forwards`} />;
+}
+```
+
+### Don't: Redefine Media Config in Multiple Places
+
+```tsx
+// Avoid: Inconsistent breakpoints
+function ComponentA() {
+  return (
+    <StylixProvider media={{ mobile: s => ({ '@media (max-width: 768px)': s }) }}>
+      ...
+    </StylixProvider>
+  );
+}
+
+function ComponentB() {
+  return (
+    <StylixProvider media={{ mobile: s => ({ '@media (max-width: 480px)': s }) }}>
+      ...  // Different breakpoint!
+    </StylixProvider>
+  );
+}
+```
+
+**Fix:** Define once at app root, use everywhere. This is less about performance and more about consistency.
+
+---
+
+## When to Use Native `style` Prop
+
+The native `style` prop bypasses Stylix entirely and applies styles inline. Use it for:
+
+1. **Values that change very frequently** (animations, drag position)
+2. **Truly unique values** that won't benefit from class sharing
+3. **Values from user input** (sliders, color pickers)
+
+```tsx
+<$.div
+  // Static styles via Stylix (cached, deduplicated)
+  padding={16}
+  border-radius={8}
+  background="white"
+  transition="transform 0.2s"
+
+  // Dynamic styles via style prop (no caching overhead)
+  style={{
+    transform: `translate(${x}px, ${y}px)`,
+    opacity: progress
+  }}
+/>
+```
+
+---
+
+## Performance Checklist
+
+Before shipping, verify:
+
+- [ ] Style objects are stable (not recreated every render) for frequently-rendered components
+- [ ] High-frequency animations use `style` prop or CSS animations
+- [ ] No components generate hundreds of unique style variations
+- [ ] Media configuration is defined once at app root
+- [ ] Large lists don't have unique styles per item (use `style` prop if needed)
+
+---
+
+## Measuring Performance
+
+If you suspect Stylix is causing performance issues:
+
+1. **Profile with React DevTools** — Look for components spending time in Stylix-related code during renders
+2. **Check `<style>` tag size** — In DevTools, inspect `<head>` and look at the Stylix `<style>` elements. Thousands of rules might indicate over-generation
+3. **Use React.memo** — Prevent unnecessary re-renders of styled components
+4. **Profile with Chrome DevTools** — The Performance panel shows style recalculation time
+
+---
+
+## The Reality
+
+For most applications, Stylix performance is not a concern. Problems typically only appear when:
+
+- Rendering large lists (1000+ items) with unique styles per item
+- Animating style props at 60fps
+- Generating styles in tight loops
+
+If you're building a typical UI with dozens or hundreds of elements, following basic React best practices (avoiding unnecessary re-renders) is usually sufficient.

package/docs/philosophy.md

@@ -0,0 +1,168 @@
+# Philosophy: Why Stylix?
+
+## The Short Version
+
+Stylix is a runtime CSS-in-JS library for React. If you know CSS and React, you already know how to use it—there's no new mental model to learn. You write CSS properties as JSX props, and Stylix handles generating class names and injecting styles.
+
+If you're working in a codebase that uses Stylix, this document explains why it exists, what problems it solves, and how to think about it.
+
+---
+
+## A Bit of History
+
+Stylix was created before the industry's shift away from runtime CSS-in-JS. At the time, libraries like styled-components and Emotion were dominant, and the idea of colocating styles with components was exciting and new.
+
+Stylix took a different approach than most CSS-in-JS libraries: instead of template literals or `css()` functions, it used props. The idea was simple—if you're already passing props to React elements, why not pass CSS the same way?
+
+```tsx
+// Instead of this (styled-components):
+const Box = styled.div`
+  color: red;
+  padding: 16px;
+`;
+
+// Or this (Emotion):
+<div css={{ color: 'red', padding: 16 }} />
+
+// Stylix does this:
+<$.div color="red" padding={16} />
+```
+
+The props-based approach felt more natural in React. No new syntax to learn, no tagged template literals, no special `css` prop to remember. Just props.
+
+---
+
+## The Industry Moved On (And That's Okay)
+
+Today, the prevailing wisdom favors zero-runtime solutions: Tailwind CSS, CSS Modules, vanilla-extract, and others that do their work at build time rather than runtime.
+
+The arguments are valid:
+- No runtime overhead for style generation
+- Better performance for initial page load
+- No style injection during hydration
+- Smaller bundle sizes
+
+If you're starting a new project today with performance as a top priority, a build-time solution is likely the better choice.
+
+**But here's the thing:** for many applications, runtime CSS-in-JS works just fine. The performance overhead is negligible for apps that aren't rendering thousands of unique styled elements per second. The developer experience benefits—colocation, dynamic styles, type safety—are real and meaningful.
+
+Stylix exists in production applications that serve real users without performance issues. If you're maintaining one of these codebases, you don't need to feel like you're working with "legacy" technology. You're working with a tool that made reasonable tradeoffs for its use case.
+
+---
+
+## What Stylix Is Good At
+
+### 1. Low Learning Curve
+
+If you know CSS, you know Stylix. There's no utility class vocabulary to memorize (like Tailwind), no new API to learn (like styled-components' template syntax), and no special build configuration required.
+
+```tsx
+// This is valid CSS knowledge directly applied:
+<$.div
+  display="flex"
+  justify-content="space-between"
+  padding={16}
+  border-radius={8}
+/>
+```
+
+### 2. Colocation
+
+Styles live with the component that uses them. When you read a component, you see exactly how it's styled without jumping to another file or searching for class names.
+
+### 3. Dynamic Styles Without Ceremony
+
+React's rendering model makes dynamic styles natural:
+
+```tsx
+<$.div
+  background={isActive ? 'blue' : 'gray'}
+  opacity={isDisabled ? 0.5 : 1}
+/>
+```
+
+No conditional class name logic, no ternary-heavy `className` strings, no separate "variant" definitions.
+
+### 4. Responsive Design Made Simple
+
+The media object pattern centralizes breakpoint definitions and makes responsive props readable:
+
+```tsx
+<$.div
+  font-size={{ default: 16, tablet: 14, mobile: 12 }}
+  flex-direction={{ default: 'row', mobile: 'column' }}
+/>
+```
+
+### 5. Type Safety
+
+TypeScript knows about CSS properties. You get autocomplete for valid properties and type errors for invalid values. This catches bugs that would otherwise only appear at runtime (or worse, silently fail).
+
+### 6. Gradual Adoption
+
+Stylix doesn't require you to style everything with it. You can use it alongside CSS Modules, Tailwind, or plain CSS. It's a tool, not a framework demanding total commitment.
+
+---
+
+## What Stylix Is Not
+
+### Not a Design System
+
+Stylix has no opinions about your design. No predefined colors, spacing scales, or component styles. You bring your own design decisions.
+
+### Not Zero-Runtime
+
+Stylix generates styles at runtime. For most applications, this is fine. For performance-critical applications with many unique style combinations, consider whether a build-time solution might be more appropriate.
+
+### Not for Every Use Case
+
+Some scenarios are genuinely better served by other approaches:
+
+- **Component libraries** intended for wide reuse benefit from static CSS that consumers can easily customize and override
+- **Highly dynamic UIs** with thousands of elements updating rapidly (think spreadsheets or data visualizations) may want to avoid runtime style generation
+- **Frame-rate-sensitive animations** should use CSS transitions, keyframe animations, or the native `style` attribute
+
+---
+
+## How to Think About Stylix
+
+Think of Stylix as the `style` prop, but better:
+
+| Feature | Native `style` prop | Stylix |
+|---------|---------------------|--------|
+| Pseudo-classes (`:hover`, `:focus`) | No | Yes |
+| Media queries | No | Yes |
+| Keyframe animations | No | Yes |
+| Selectors | No | Yes |
+| Server-side rendering | Inline only | Full support |
+| Deduplication | No | Yes |
+
+Stylix bridges the gap between the simplicity of inline styles and the power of CSS, without requiring you to context-switch to a separate styling language or file.
+
+---
+
+## For Those Inheriting a Stylix Codebase
+
+If you've joined a team that uses Stylix, here's what you need to know:
+
+1. **It's just CSS.** The props are CSS properties. The values are CSS values. If you're unsure what a prop does, MDN has the answer.
+
+2. **Look for the `$css` prop** when you see complex styles. That's where pseudo-classes, media queries, and nested selectors live.
+
+3. **Check the `<StylixProvider>`** at the app root to see if media keywords (like `mobile` or `tablet`) are defined. These are shortcuts you can use in style props.
+
+4. **Spreading `{...styles}` is intentional.** Components often accept style props and spread them onto an inner element. This is how parent components can customize children.
+
+5. **Performance is rarely an issue** unless you're generating many unique styles in a tight loop. Normal component rendering is fine.
+
+---
+
+## The Bottom Line
+
+Stylix is a straightforward tool: write CSS as props, get scoped styles. It made sense when it was built, and it continues to work well for the applications using it.
+
+The web development landscape constantly evolves. Today's best practice becomes tomorrow's legacy. What matters is whether a tool solves real problems for real users—and Stylix does that.
+
+If you're using Stylix, use it well. If you're evaluating it for a new project, understand the tradeoffs and choose what's right for your situation.
+
+Either way, you're writing CSS. That skill isn't going anywhere.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stylix/core",
-  "version": "6.1.1",
+  "version": "6.3.0",
   "description": "React, with style. Add styles to your React apps with props: the easy, natural, and low learning curve approach.",
   "keywords": [
     "react",
@@ -29,34 +29,37 @@
   },
   "author": "Alex Brombal",
   "license": "MIT",
-  "homepage": "https://stylix.dev/",
+  "homepage": "https://github.com/brombal/stylix",
   "bugs": "https://github.com/brombal/stylix/issues",
-  "repository": "https://github.com/brombal/stylix",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/brombal/stylix.git"
+  },
   "peerDependencies": {
     "react": ">=18.0.0",
     "react-dom": ">=18.0.0"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.0.5",
+    "@biomejs/biome": "^2.4.4",
     "@rollup/plugin-json": "^6.1.0",
-    "@rollup/plugin-typescript": "^12.1.3",
-    "@testing-library/dom": "^10.4.0",
-    "@testing-library/jest-dom": "^6.6.3",
-    "@testing-library/react": "^16.3.0",
+    "@rollup/plugin-typescript": "^12.3.0",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
     "@types/jest": "^30.0.0",
-    "@types/node": "^24.0.4",
-    "@types/react": "^19.1.8",
-    "@types/react-dom": "^19.1.6",
-    "csstype": "^3.1.3",
+    "@types/node": "^25.3.2",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "csstype": "^3.2.3",
     "husky": "^9.1.7",
-    "jest": "^30.0.2",
-    "jest-environment-jsdom": "^30.0.2",
-    "mdn-data": "^2.21.0",
-    "rollup": "^4.44.0",
-    "rollup-plugin-dts": "^6.2.1",
-    "ts-jest": "^29.4.0",
+    "jest": "^30.2.0",
+    "jest-environment-jsdom": "^30.2.0",
+    "mdn-data": "^2.27.1",
+    "rollup": "^4.59.0",
+    "rollup-plugin-dts": "^6.3.0",
+    "ts-jest": "^29.4.6",
     "tslib": "^2.8.1",
-    "tsx": "^4.20.3",
-    "typescript": "^5.8.3"
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
   }
 }