next-style 1.2.0 → 2.0.0

package/README.md

@@ -1,532 +1,323 @@
-# NextStyle
+# Next Style
 
-A lightweight **runtime CSS-in-JS engine** for React with deterministic class names, nested pseudo selectors, media queries, global styles, keyframes, and font-face support.
+> **Zero-Runtime CSS-in-JS** for Next.js with Turbopack support
 
-Designed for **page-scoped and component-scoped usage** without build-time tooling.
+A lightweight CSS-in-JS library that extracts styles at build time, resulting in zero runtime overhead. Write styles in JavaScript with full TypeScript support while shipping only pure CSS.
 
----
-
-## Package Information
-
-- **Name:** next-style
-- **Version:** 1.1.5
-- **License:** MIT
-- **Author:** kingslimes  
-  https://github.com/kingslimes
-- **Repository:**  
-  https://github.com/kingslimes/next-style
-- **Issue Tracker:**  
-  https://github.com/kingslimes/next-style/issues
-
----
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-## Features
+## Why next-style?
 
-- Object-based styling (TypeScript friendly)
-- Deterministic class names (same style → same class)
-- Pseudo selectors (`:hover`, `:focus`, `:active`)
-- Responsive media queries (`sm` → `xxl`)
-- Global styles
-- `@keyframes` support
-- `@font-face` support
-- Built-in PostCSS + Autoprefixer
-- Zero DOM dependency
-- Tree-shakeable (`sideEffects: false`)
-- Copy–paste friendly API
+- **Zero Runtime** — All style extraction happens at build time. Ship pure CSS, not JavaScript.
+- **Turbopack Ready** — Optimized for Next.js 15+ and Turbopack without additional configuration.
+- **Type Safe** — Full TypeScript support powered by [csstype](https://github.com/frenic/csstype) for intelligent autocomplete on every CSS property and value.
+- **Automatic Deduplication** — Identical style objects always produce the same class name.
+- **Responsive First** — Built-in shorthand breakpoints (`@sm`, `@md`, `@lg`, `@xl`, `@2xl`), sorted mobile-first automatically.
+- **Developer Experience** — Simple API. Just `css({})` and go.
 
----
+## Quick Start
 
-## Installation
+### Installation
 
-``` bash
-npm install next-style
-# or
+```bash
 bun add next-style
 ```
 
----
-
-## Peer Dependencies
-
-NextStyle relies on the following peer dependencies:
-
-``` txt
-react >= 18
-postcss ^8
-autoprefixer ^10
-```
-
-Make sure they are installed in your project.
-
----
+### Setup
 
-## Recommended Usage Pattern (Scoped)
+#### 1. Configure PostCSS
 
-The **recommended and official pattern** is to scope styles per page or per component using destructuring.
+Create `postcss.config.js` in your project root:
 
-``` ts
-const { css, StyleProvider } = new NextStyle("home")
+```js
+export default {
+  plugins: {
+    "next-style/plugin": {}
+  }
+}
 ```
 
-Why this works well:
-- Clear scope ownership
-- No global side effects
-- Easy to copy and reuse
-- Matches React’s mental model
-
----
+If you already have `postcss.config.js` (e.g. with Tailwind), add next-style first:
 
-## Basic Example (Page Scoped)
-
-``` tsx
-import { NextStyle } from "next-style"
-
-export default function HomePage() {
-    const { css, StyleProvider } = new NextStyle("home")
-
-    const title = css({
-        fontSize: "32px",
-        fontWeight: 700,
-        marginBottom: "16px"
-    })
-
-    const button = css({
-        padding: "10px 20px",
-        borderRadius: "8px",
-        backgroundColor: "#2563eb",
-        color: "#fff",
-
-        _hover: {
-            backgroundColor: "#1d4ed8"
-        }
-    })
-
-    return (
-        <>
-            <StyleProvider />
-            <h1 className={title}>Home</h1>
-            <button className={button}>Click me</button>
-        </>
-    )
+```js
+export default {
+  plugins: {
+    "next-style/plugin": {},
+    tailwindcss: {},
+    autoprefixer: {}
+  }
 }
 ```
 
----
-
-## Styling API
-
-### `css(style): string`
+> **Order matters** — next-style must come before other plugins.
 
-Creates a class name from a style object.
+#### 2. Import styles in `globals.css`
 
-``` ts
-const className = css({
-    color: "red",
-    fontSize: "16px"
-})
+```css
+@import "next-style";
+/* your other imports/rules */
 ```
 
-- Automatically converts camelCase → kebab-case
-- Deduplicates styles using hashing
-- Returns a stable class name
+The PostCSS plugin replaces this `@import` with the compiled CSS at build time.
 
----
+#### 3. Use in components
 
-## Pseudo Selectors
+```tsx
+import { css } from "next-style"
 
-Supported pseudo keys:
-
-| Key | CSS Output |
-|----|-----------|
-| `_hover` | `:hover` |
-| `_focus` | `:focus` |
-| `_active` | `:active` |
-
-Example:
-
-``` ts
-css({
-    color: "black",
-    _hover: {
-        color: "red"
-    }
+const title = css({
+  fontSize: "32px",
+  fontWeight: 500,
+  "@md": { fontSize: "40px" },
+  ":hover": { color: "#7F77DD" }
 })
-```
-
----
-
-## Relation Selector API
 
-`next-style` provides a **relation-based selector API** that allows you to define styles based on the state of one element affecting another element, without manually writing complex CSS selectors.
-
-This API is designed to be:
-- Declarative and readable  
-- Type-safe (no string selectors)  
-- Fully compatible with runtime CSS-in-JS  
-
----
-
-### Basic Usage
-
-``` ts
-const { css, when } = new NextStyle()
-
-const container = css({})
-const button = css({})
-
-when(container)
-  .hover()
-  .adjacent(button, {
-    backgroundColor: "red"
-  })
-```
-Equivalent CSS:
-
-``` css
-.container:hover + .button {
-  background-color: red;
+export default function App() {
+  return <h1 className={title}>Hello World</h1>
 }
 ```
 
----
-
-## Supported States
-
-You can define relationships based on the following pseudo states:
-
-- `hover()` → `:hover`
-- `focus()` → `:focus`
-- `active()` → `:active`
-
-Example:
+## Features
 
-``` ts
-when(input)
-  .focus()
-  .sibling(label, {
-    color: "blue"
-  })
-```
-Equivalent CSS:
+| Feature | Status | Details |
+|---------|--------|---------|
+| Zero Runtime | ✅ | Styles extracted at build time |
+| Turbopack | ✅ | Native support for Next.js 15+ |
+| Type Safety | ✅ | Powered by csstype — full property + value autocomplete |
+| Responsive Breakpoints | ✅ | `@sm` `@md` `@lg` `@xl` `@2xl` |
+| Arbitrary Media Queries | ✅ | `'@media (min-width: 900px)'` |
+| Pseudo-classes | ✅ | `:hover` `:focus` `:active` `:disabled` `:focus-visible` … |
+| Pseudo-elements | ✅ | `::before` `::after` `::first-letter` … |
+| Keyframe Animations | ✅ | `'@keyframes name'` inline with the style object |
+| Container Queries | ✅ | `'@container sidebar (min-width: 300px)'` |
+| `@supports` | ✅ | `'@supports (display: grid)'` |
+| `@layer` | ✅ | `'@layer utilities'` |
+| CSS Variables | ✅ | `var(--token)` as values |
+| Deduplication | ✅ | Same object → same class, always |
+| Global Styles | ✅ | `global()` for resets and base rules |
+
+## API
+
+### `css(styles: CSSObject): string`
+
+Converts a style object into a unique, stable class name. Identical objects always return the same class (deduplication). Styles are collected at build time — zero cost at runtime.
+
+```tsx
+const button = css({
+  padding: "8px 16px",
+  borderRadius: "6px",
+  backgroundColor: "#7F77DD",
+  color: "#fff",
+  cursor: "pointer",
+  ":hover": { backgroundColor: "#534AB7" },
+  "@md": { padding: "10px 20px" }
+})
 
-``` css
-input:focus ~ label {
-  color: blue;
+export function Button() {
+  return <button className={button}>Click me</button>
 }
 ```
 
----
-
-## Supported Relationships
+### `global(styles: Record<string, CSSObject>): void`
 
-### Adjacent Sibling (`+`)
+Registers global CSS rules applied directly to selectors — no scoped class. Useful for resets, base typography, and third-party element overrides.
 
-Applies styles to the **immediately following sibling**.
+```tsx
+import { global } from "next-style"
 
-``` ts
-when(div)
-  .hover()
-  .adjacent(p, {
-    color: "red"
-  })
+global({
+  "*": { boxSizing: "border-box", margin: "0" },
+  "body": { fontFamily: "Inter, sans-serif", lineHeight: "1.6" },
+  "h1, h2, h3": { fontWeight: 500, lineHeight: "1.2" }
+})
 ```
-CSS equivalent:
 
-``` css
-div:hover + p {
-  color: red;
-}
-```
+## Examples
 
----
+### Responsive design
 
-### General Sibling (`~`)
+Breakpoints expand to standard `min-width` media queries and are sorted mobile-first automatically.
 
-Applies styles to **all following siblings**.
+| Shorthand | Expands to |
+|-----------|-----------|
+| `@sm` | `@media (min-width: 640px)` |
+| `@md` | `@media (min-width: 768px)` |
+| `@lg` | `@media (min-width: 1024px)` |
+| `@xl` | `@media (min-width: 1280px)` |
+| `@2xl` | `@media (min-width: 1536px)` |
 
-``` ts
-when(div)
-  .hover()
-  .sibling(p, {
-    color: "red"
-  })
-```
-CSS equivalent:
-
-``` css
-div:hover ~ p {
-  color: red;
-}
+```tsx
+const container = css({
+  width: "100%",
+  padding: "16px",
+  "@md": { width: "768px", padding: "24px" },
+  "@lg": { width: "1024px", padding: "32px" }
+})
 ```
 
----
-
-### Child (`>`)
-
-Applies styles to **direct children only**.
+Arbitrary media queries are also supported:
 
-``` ts
-when(card)
-  .hover()
-  .child(icon, {
-    transform: "scale(1.1)"
-  })
-```
-CSS equivalent:
-
-``` css
-card:hover > icon {
-  transform: scale(1.1);
-}
+```tsx
+const sidebar = css({
+  display: "none",
+  "@media (min-width: 900px)": { display: "block" }
+})
 ```
 
----
-
-### Descendant (space)
+### Interactive states
 
-Applies styles to **any nested element**.
-
-``` ts
-when(menu)
-  .hover()
-  .descendant(item, {
-    backgroundColor: "#eee"
-  })
-```
-CSS equivalent:
-
-``` css
-menu:hover item {
-  background-color: #eee;
-}
+```tsx
+const link = css({
+  color: "#3b82f6",
+  textDecoration: "none",
+  transition: "color 0.2s",
+  ":hover": { color: "#1e40af" },
+  ":focus-visible": { outline: "2px solid #3b82f6", outlineOffset: "2px" },
+  ":active": { color: "#1e3a8a" }
+})
 ```
 
----
+### Keyframe animations
 
-## Why Use `when()` Instead of `global()`?
+Declare `@keyframes` inline alongside the style that uses them:
 
-While `global()` allows full control over raw selectors, `when()` provides:
+```tsx
+const spinner = css({
+  animationName: "spin",
+  animationDuration: "1s",
+  animationTimingFunction: "linear",
+  animationIterationCount: "infinite",
+  "@keyframes spin": {
+    to: { transform: "rotate(360deg)" }
+  }
+})
+```
 
-- Clear intent and better readability  
-- No need to manually concatenate class names  
-- Safer refactoring (class tokens, not strings)  
-- IDE autocomplete and JSDoc support  
+### Container queries
 
-Comparison:
+```tsx
+const card = css({
+  fontSize: "14px",
+  "@container sidebar (min-width: 300px)": { fontSize: "16px" }
+})
+```
 
-``` ts
-// global selector
-global(`.${a}:hover + .${b}`, { color: "red" })
+### CSS variables
 
-// relation API
-when(a).hover().adjacent(b, { color: "red" })
+```tsx
+const card = css({
+  backgroundColor: "var(--bg-primary)",
+  color: "var(--text-primary)",
+  padding: "var(--spacing-4)",
+  borderRadius: "var(--radius-lg)"
+})
 ```
 
----
+## TypeScript
 
-## Notes
+All CSS properties and values are fully typed via [csstype](https://github.com/frenic/csstype). Typos in property names are caught at compile time and your editor will autocomplete valid values.
 
-- `when()` works with class names generated by `css()`
-- Relation rules are injected via the same internal pipeline as `global()`
-- Media queries and nested styles are fully supported inside relation styles
+```tsx
+import { css, type CSSObject } from "next-style"
 
----
+const myStyles: CSSObject = {
+  fontSize: "16px",       // ✅ typed
+  colour: "red",          // ❌ compile error — unknown property
+  "@md": { fontSize: "20px" },
+  ":hover": { opacity: 0.8 }
+}
 
-## Example With Media Query
-
-``` ts
-when(container)
-  .hover()
-  .sibling(text, {
-    color: "red",
-    _md: {
-      color: "blue"
-    }
-  })
+const title = css(myStyles)
 ```
 
----
-
-This API is intentionally minimal and composable, allowing you to express complex UI relationships without leaking CSS selector syntax into your application code.
+### Exported types
 
----
+| Type | Description |
+|------|-------------|
+| `CSSObject` | Style object accepted by `css()` and `global()` |
+| `CSSProperties` | CSS properties only (no at-rules or pseudos) — backed by csstype |
 
-## Responsive Media Queries
+## Advanced: `createTransformer`
 
-Built-in breakpoints:
+For SWC/Babel transforms and test harnesses that need an isolated collector independent of the shared runtime instance:
 
-| Key | Media Query |
-|----|-------------|
-| `_sm` | `(min-width: 640px)` |
-| `_md` | `(min-width: 768px)` |
-| `_lg` | `(min-width: 1024px)` |
-| `_xl` | `(min-width: 1280px)` |
-| `_xxl` | `(min-width: 1536px)` |
+```ts
+import { createTransformer } from "next-style"
 
-Example:
-
-``` ts
-css({
-    fontSize: "14px",
-    _lg: {
-        fontSize: "18px"
-    }
-})
+const { collector, transformCssCall } = createTransformer()
+const className = transformCssCall({ color: "red" }) // "ns-abc123"
+const css = collector.getAllStyles()                   // ".ns-abc123 { color: red; }"
 ```
 
-Media queries can be nested and merged automatically.
+## Development
 
----
+```bash
+# Install dependencies
+bun install
 
-## Global Styles
+# Build
+bun run build
 
-### `global(selector, style)`
+# Watch for changes
+bun run dev
 
-Apply styles globally without generating a class.
+# Type-check only
+bunx tsc --noEmit
 
-``` ts
-const { global, StyleProvider } = new NextStyle("global")
+# Lint
+bun run lint
 
-global("body", {
-    margin: 0,
-    fontFamily: "system-ui"
-})
-
-global("a", {
-    color: "inherit",
-    _hover: {
-        textDecoration: "underline"
-    }
-})
+# Format
+bun run format
 ```
 
----
-
-## Animations
-
-### `keyframes(frames): string`
-
-Creates a `@keyframes` rule and returns its name.
-
-``` ts
-const fadeIn = keyframes({
-    from: { opacity: 0 },
-    to: { opacity: 1 }
-})
+### Project structure
 
-css({
-    animation: `${fadeIn} 300ms ease-in`
-})
 ```
-
----
-
-## Fonts
-
-### `fontFace(font)`
-
-Registers a `@font-face` rule.
-
-``` ts
-fontFace({
-    fontFamily: "MyFont",
-    src: "url(/fonts/myfont.woff2)",
-    fontWeight: 400,
-    fontStyle: "normal",
-    fontDisplay: "swap"
-})
+src/
+├── runtime/          # css() · global() · CSSObject type
+├── postcss-plugin/   # @import "next-style" → compiled CSS
+├── compiler/         # StyleCollector · createTransformer
+└── utils/            # camelToKebab · generateClassHash · BREAKPOINTS
 ```
 
----
-
-## Rendering Styles
+## Performance
 
-### `<StyleProvider />`
+- **Bundle size** — ~2 KB minified + gzipped
+- **Runtime cost** — 0 bytes (styles extracted at build time)
+- **Build overhead** — negligible
 
-Injects all generated CSS into a `<style>` tag.
+## Browser support
 
-``` tsx
-<>
-    <StyleProvider />
-    <App />
-</>
-```
-
-- Returns `null` if no styles exist
-- Should be rendered **once per scope**
-
----
+All modern browsers (Chrome, Firefox, Safari, Edge).
 
-### `toTextCss(): string | null`
+## Troubleshooting
 
-Returns all generated CSS as a string.
+### Styles not appearing
 
-Useful for:
-- Server-side rendering (SSR)
-- Manual injection
-- Debugging
+1. Confirm `postcss.config.js` includes `"next-style/plugin": {}`
+2. Confirm `@import "next-style";` is present in `globals.css`
+3. Restart the dev server — PostCSS config changes require a restart
+4. Clear the Next.js cache: `rm -rf .next` then restart
 
-``` ts
-const cssText = toTextCss()
-```
+### Using alongside Tailwind / Autoprefixer
 
----
+next-style must be listed **first** in the plugins object:
 
-## Component Scoped Example
-
-Reusable, self-contained component.
-
-``` tsx
-import { NextStyle } from "next-style"
-
-export function Card({ title, children }) {
-    const { css, StyleProvider } = new NextStyle("card")
-
-    const root = css({
-        padding: "16px",
-        borderRadius: "12px",
-        backgroundColor: "#fff",
-        boxShadow: "0 10px 25px rgba(0,0,0,.1)"
-    })
-
-    const heading = css({
-        fontSize: "18px",
-        fontWeight: 600,
-        marginBottom: "8px"
-    })
-
-    return (
-        <>
-            <StyleProvider />
-            <div className={root}>
-                <div className={heading}>{title}</div>
-                {children}
-            </div>
-        </>
-    )
+```js
+export default {
+  plugins: {
+    "next-style/plugin": {},   // ← first
+    tailwindcss: {},
+    autoprefixer: {}
+  }
 }
 ```
 
----
-
-## Best Practices
-
-- Create **one NextStyle instance per page or component**
-- Do **not** share instances globally
-- Render `StyleProvider` only once per scope
-- Use meaningful prefixes (`home`, `card`, `profile`)
-
----
-
-## Design Intentions
+## License
 
-- No descendant selectors (`& > div`)
-- No arbitrary selector nesting
-- Predictable output over expressiveness
-- Optimized for runtime and SSR safety
+MIT © [TiwPhiraphan](https://github.com/TiwPhiraphan)
 
 ---
 
-## License
-
-MIT © kingslimes
+**Made with ❤️ for Next.js developers**