next-style 1.1.4 → 1.1.5

package/README.md

@@ -1,56 +1,46 @@
-# next-style
+# NextStyle
 
-**next-style** is a lightweight runtime CSS-in-JS engine designed for React, Next.js, and Bun.
+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.
 
-It is intentionally designed to be **page-scoped and component-scoped**, ensuring predictable
-style isolation with zero global leakage between pages or routes.
-
-The library is framework-agnostic at its core and does not depend on React internally.
+Designed for **page-scoped and component-scoped usage** without build-time tooling.
 
 ---
 
-## Core Design Principles
-
-- Styles are scoped to a **single page or component**
-- No global singleton style registry
-- No cross-page or cross-route CSS leakage
-- Each page owns its own styles
-- Explicit style injection via a `<style>` tag
-- No implicit DOM side effects
+## Package Information
 
-Because of this design:
-- `new NextStyle()` must be created inside the page or component scope
-- Styles must be injected manually using `ns.StyleText`
+- **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
 
 ---
 
 ## Features
 
-- Object-based styling with strong TypeScript support
-- Deterministic hashing (same styles always produce the same class name)
-- Nested pseudo selectors (`_hover`, `_focus`, `_active`)
-- Built-in responsive media queries
-- Page-scoped global styles
+- 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
-- PostCSS + Autoprefixer integration
-- Automatic rule deduplication (per instance)
-- Single `<style>` injection per page or component
-- No side effects (`sideEffects: false`)
+- Built-in PostCSS + Autoprefixer
+- Zero DOM dependency
+- Tree-shakeable (`sideEffects: false`)
+- Copy–paste friendly API
 
 ---
 
 ## Installation
 
-### npm
-
-```sh
+``` bash
 npm install next-style
-```
-
-### Bun
-
-```sh
+# or
 bun add next-style
 ```
 
@@ -58,243 +48,286 @@ bun add next-style
 
 ## Peer Dependencies
 
-For most **Next.js applications**, you **do not need to install these manually**.
+NextStyle relies on the following peer dependencies:
+
+``` txt
+react >= 18
+postcss ^8
+autoprefixer ^10
+```
+
+Make sure they are installed in your project.
 
-- **React** is already included with Next.js
-- **PostCSS** and **Autoprefixer** are bundled and used internally by Next.js
+---
 
-This section mainly applies if you are using **next-style outside of Next.js**, such as:
-- Custom React setups
-- Bun + React
-- Vite or other non-Next runtimes
+## Recommended Usage Pattern (Scoped)
 
-If required, install them manually:
+The **recommended and official pattern** is to scope styles per page or per component using destructuring.
 
-```sh
-npm install react postcss autoprefixer
+``` ts
+const { css, StyleProvider } = new NextStyle("home")
 ```
 
----
+Why this works well:
+- Clear scope ownership
+- No global side effects
+- Easy to copy and reuse
+- Matches React’s mental model
 
-## Basic Usage (Page Scoped)
+---
 
-Create a `NextStyle` instance **inside the page or component**.  
-You may optionally provide a **custom prefix** to control generated class names.
+## Basic Example (Page Scoped)
 
-```ts
+``` tsx
 import { NextStyle } from "next-style"
 
-export default function Page() {
-    const ns = new NextStyle("home")
-    const btn = ns.css({
-        padding: "8px 16px",
-        backgroundColor: "black",
-        color: "white",
-        borderRadius: "6px"
+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 (
         <>
-            <style>{ ns.StyleText }</style>
-            <button className={ btn }>Click me</button>
+            <StyleProvider />
+            <h1 className={title}>Home</h1>
+            <button className={button}>Click me</button>
         </>
     )
 }
 ```
 
-Generated class names will look like:
+---
+
+## Styling API
 
-```txt
-home_ab12cd3
+### `css(style): string`
+
+Creates a class name from a style object.
+
+``` ts
+const className = css({
+    color: "red",
+    fontSize: "16px"
+})
 ```
 
-Notes:
-- The prefix is optional
-- If omitted, a default prefix is used
-- Prefixes help identify styles per page or component
-- Each page or component should create its own `NextStyle` instance
+- Automatically converts camelCase → kebab-case
+- Deduplicates styles using hashing
+- Returns a stable class name
 
 ---
 
 ## Pseudo Selectors
 
-Pseudo selectors are defined using keys prefixed with `_`.
+Supported pseudo keys:
+
+| Key | CSS Output |
+|----|-----------|
+| `_hover` | `:hover` |
+| `_focus` | `:focus` |
+| `_active` | `:active` |
 
-```ts
-const card = ns.css({
-    backgroundColor: "#fff",
-    transition: "0.2s ease",
+Example:
+
+``` ts
+css({
+    color: "black",
     _hover: {
-        backgroundColor: "#f5f5f5"
-    },
-    _active: {
-        transform: "scale(0.98)"
+        color: "red"
     }
 })
 ```
 
-Supported pseudo selectors:
-- `_hover`
-- `_focus`
-- `_active`
-
 ---
 
-## Responsive Styles (Media Queries)
+## Responsive Media Queries
 
 Built-in breakpoints:
 
-- `_sm` → min-width: 640px
-- `_md` → min-width: 768px
-- `_lg` → min-width: 1024px
-- `_xl` → min-width: 1280px
-- `_xxl` → min-width: 1536px
-
-```ts
-const box = ns.css({
-    width: 100,
-    _md: {
-        width: 200
-    },
+| Key | Media Query |
+|----|-------------|
+| `_sm` | `(min-width: 640px)` |
+| `_md` | `(min-width: 768px)` |
+| `_lg` | `(min-width: 1024px)` |
+| `_xl` | `(min-width: 1280px)` |
+| `_xxl` | `(min-width: 1536px)` |
+
+Example:
+
+``` ts
+css({
+    fontSize: "14px",
     _lg: {
-        width: 300
+        fontSize: "18px"
     }
 })
 ```
 
-Media queries can be nested and are automatically merged.
+Media queries can be nested and merged automatically.
 
 ---
 
-## Global Styles (Page Scoped)
+## Global Styles
 
-Global styles are scoped to the current page or component instance.
+### `global(selector, style)`
 
-```ts
-ns.global("body", {
+Apply styles globally without generating a class.
+
+``` ts
+const { global, StyleProvider } = new NextStyle("global")
+
+global("body", {
     margin: 0,
-    fontFamily: "Inter, sans-serif"
+    fontFamily: "system-ui"
 })
-```
 
-These styles exist only for the lifetime of the page or component.
+global("a", {
+    color: "inherit",
+    _hover: {
+        textDecoration: "underline"
+    }
+})
+```
 
 ---
 
-## Keyframes
+## Animations
 
-Create animations using `keyframes()`:
+### `keyframes(frames): string`
 
-```ts
-const fadeIn = ns.keyframes({
+Creates a `@keyframes` rule and returns its name.
+
+``` ts
+const fadeIn = keyframes({
     from: { opacity: 0 },
     to: { opacity: 1 }
 })
-```
 
-Use the animation in styles:
-
-```ts
-const modal = ns.css({
-    animation: `${ fadeIn } 0.3s ease-out`
+css({
+    animation: `${fadeIn} 300ms ease-in`
 })
 ```
 
-Keyframes are scoped to the current `NextStyle` instance.
-
 ---
 
-## Font Face
+## Fonts
 
-Declare fonts using `fontFace()`:
+### `fontFace(font)`
 
-```ts
-ns.fontFace({
-    fontFamily: "Inter",
-    src: "url(/fonts/inter.woff2) format('woff2')",
+Registers a `@font-face` rule.
+
+``` ts
+fontFace({
+    fontFamily: "MyFont",
+    src: "url(/fonts/myfont.woff2)",
     fontWeight: 400,
     fontStyle: "normal",
     fontDisplay: "swap"
 })
 ```
 
-Font-face rules are injected only for the current page or component.
-
 ---
 
-## Deterministic Hashing
+## Rendering Styles
 
-- Styles are hashed using a stable algorithm
-- Object keys are sorted before hashing
-- Semantically identical styles always produce the same class name
-- Prevents unnecessary class regeneration
+### `<StyleProvider />`
 
----
+Injects all generated CSS into a `<style>` tag.
 
-## Server-Side Rendering (SSR)
+``` tsx
+<>
+    <StyleProvider />
+    <App />
+</>
+```
 
-`next-style` is SSR-safe.
+- Returns `null` if no styles exist
+- Should be rendered **once per scope**
 
-Because the core API only generates strings:
-- No JSX is exported from the library
-- No React runtime is required
-- No side effects occur during render
+---
 
-You can safely inject styles during SSR:
+### `toTextCss(): string | null`
 
-```tsx
-<style>{ ns.StyleText }</style>
-```
+Returns all generated CSS as a string.
 
-The same output will be produced on both the server and the client.
+Useful for:
+- Server-side rendering (SSR)
+- Manual injection
+- Debugging
 
----
+``` ts
+const cssText = toTextCss()
+```
 
-## Performance Characteristics
+---
 
-- CSS rules are generated and deduplicated per instance
-- PostCSS and Autoprefixer results are cached
-- Only one `<style>` tag is required per page or component
-- No global runtime mutations
+## Component Scoped Example
 
-Ideal for:
-- Next.js App Router
-- Page-level isolation
-- Component-driven design systems
+Reusable, self-contained component.
 
----
+``` tsx
+import { NextStyle } from "next-style"
 
-## Common Gotchas
+export function Card({ title, children }) {
+    const { css, StyleProvider } = new NextStyle("card")
 
-- Do not create a shared `NextStyle` instance across pages
-- Do not treat `next-style` as a global style manager
-- Always inject `ns.StyleText` before elements that use generated class names
-- Avoid calling `ns.css()` conditionally with different order between renders
+    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"
+    })
 
-## Package Information
+    return (
+        <>
+            <StyleProvider />
+            <div className={root}>
+                <div className={heading}>{title}</div>
+                {children}
+            </div>
+        </>
+    )
+}
+```
 
-- Name: `next-style`
-- Version: `1.1.2`
-- License: MIT
-- Module type: ESM
-- Side effects: false
+---
 
-Repository:  
-https://github.com/kingslimes/next-style
+## Best Practices
 
-Issues:  
-https://github.com/kingslimes/next-style/issues
+- 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`)
 
 ---
 
-## Roadmap
+## Design Intentions
 
-- `&` selector nesting
-- `_dark` / `_light` helpers
-- `@layer` support
-- Optional React helpers
-- Dev-time warnings for incorrect usage
+- No descendant selectors (`& > div`)
+- No arbitrary selector nesting
+- Predictable output over expressiveness
+- Optimized for runtime and SSR safety
 
 ---
 

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import type { Properties } from "csstype";
+import type { DetailedReactHTMLElement } from "react";
 export type NextStyleProperties = {
     [K in keyof Properties<string | number>]?: Properties<string | number>[K];
 } & {
@@ -31,6 +32,9 @@ export declare class NextStyle {
     global: (selector: string, style: NextStyleProperties) => void;
     keyframes: (frames: KeyframesObject) => string;
     fontFace: (font: FontFaceObject) => void;
-    get StyleText(): string | null;
+    toTextCss: () => string | null;
+    StyleProvider: () => DetailedReactHTMLElement<{
+        children: string;
+    }, HTMLStyleElement> | null;
 }
 export {};

package/dist/index.js

@@ -1,2 +1,3 @@
-import postcss from"postcss";import autoprefixer from"autoprefixer";var processor=postcss([autoprefixer({overrideBrowserslist:[">0.2%","not dead","not op_mini all"]})]),postcssCache=new Map;function postcssTransform(cssText){let cached=postcssCache.get(cssText);if(cached)return cached;let result=processor.process(cssText,{from:void 0}).css;return postcssCache.set(cssText,result),result}function stableStringify(value){if(value==null||typeof value!=="object")return JSON.stringify(value);if(Array.isArray(value))return`[${value.map(stableStringify).join(",")}]`;return`{${Object.keys(value).sort().map((k)=>`"${k}":${stableStringify(value[k])}`).join(",")}}`}function createHashName(seed){let hash=BigInt("0xcbf29ce484222325"),prime=BigInt("0x100000001b3");for(let i=0;i<seed.length;i++)hash^=BigInt(seed.charCodeAt(i)),hash*=prime,hash&=BigInt("0xffffffffffffffff");return hash.toString(36).slice(0,9)}function toKebabCase(prop){return prop.replace(/[A-Z]/g,(m)=>`-${m.toLowerCase()}`)}var MEDIA_MAP={_sm:"(min-width:640px)",_md:"(min-width:768px)",_lg:"(min-width:1024px)",_xl:"(min-width:1280px)",_xxl:"(min-width:1536px)"};function mergeMedia(parent,current){if(!parent)return current;if(!current)return parent;return`${parent} and ${current}`}function serializeNested(style,ctx){let css="",base="";for(let key in style){let value=style[key];if(value==null||typeof value==="object"||key.startsWith("_"))continue;base+=`${toKebabCase(key)}:${value};`}if(base){let rule=`${ctx.selector}{${base}}`;css+=ctx.media?`@media ${ctx.media}{${rule}}`:rule}for(let pseudo of["_hover","_focus","_active"]){let value=style[pseudo];if(!value)continue;css+=serializeNested(value,{selector:`${ctx.selector}:${pseudo.slice(1)}`,media:ctx.media})}for(let key in MEDIA_MAP){let mediaKey=key,value=style[mediaKey];if(!value)continue;css+=serializeNested(value,{selector:ctx.selector,media:mergeMedia(ctx.media,MEDIA_MAP[mediaKey])})}return css}class NextStyle{prefix;rules=new Map;constructor(prefix="next"){this.prefix=prefix}css=(style)=>{let seed=stableStringify(style),hash=createHashName(seed),className=`${this.prefix}_${hash}`,key=`class:${className}`;if(!this.rules.has(key)){let raw=serializeNested(style,{selector:`.${className}`}),cssText=postcssTransform(raw);this.rules.set(key,cssText)}return className};global=(selector,style)=>{let key=`global:${selector}`;if(!this.rules.has(key)){let raw=serializeNested(style,{selector}),cssText=postcssTransform(raw);this.rules.set(key,cssText)}};keyframes=(frames)=>{let seed=stableStringify(frames),hash=createHashName(seed),name=`${this.prefix}_${hash}`,key=`@keyframes:${name}`;if(!this.rules.has(key)){let body="";for(let step in frames){let props="",frame=frames[step];for(let prop in frame)props+=`${toKebabCase(prop)}:${frame[prop]};`;body+=`${step}{${props}}`}let cssText=postcssTransform(`@keyframes ${name}{${body}}`);this.rules.set(key,cssText)}return name};fontFace=(font)=>{let seed=stableStringify(font),key=`@font-face:${createHashName(seed)}`;if(!this.rules.has(key)){let body="";for(let prop in font)body+=`${toKebabCase(prop)}:${font[prop]};`;let cssText=postcssTransform(`@font-face{${body}}`);this.rules.set(key,cssText)}};get StyleText(){if(this.rules.size===0)return null;let cssText="";for(let rule of this.rules.values())cssText+=rule+`
-`;return cssText}}export{NextStyle};
+import postcss from"postcss";import{createElement}from"react";import autoprefixer from"autoprefixer";var processor=postcss([autoprefixer({overrideBrowserslist:[">0.2%","not dead","not op_mini all"]})]),postcssCache=new Map;function postcssTransform(cssText){let cached=postcssCache.get(cssText);if(cached)return cached;let result=processor.process(cssText,{from:void 0}).css;return postcssCache.set(cssText,result),result}function stableStringify(value){if(value==null||typeof value!=="object")return JSON.stringify(value);if(Array.isArray(value))return`[${value.map(stableStringify).join(",")}]`;return`{${Object.keys(value).sort().map((k)=>`"${k}":${stableStringify(value[k])}`).join(",")}}`}function createHashName(seed){let hash=BigInt("0xcbf29ce484222325"),prime=BigInt("0x100000001b3");for(let i=0;i<seed.length;i++)hash^=BigInt(seed.charCodeAt(i)),hash*=prime,hash&=BigInt("0xffffffffffffffff");return hash.toString(36).slice(0,9)}function toKebabCase(prop){return prop.replace(/[A-Z]/g,(m)=>`-${m.toLowerCase()}`)}var MEDIA_MAP={_sm:"(min-width:640px)",_md:"(min-width:768px)",_lg:"(min-width:1024px)",_xl:"(min-width:1280px)",_xxl:"(min-width:1536px)"};function mergeMedia(parent,current){if(!parent)return current;if(!current)return parent;return`${parent} and ${current}`}function serializeNested(style,ctx){let css="",base="";for(let key in style){let value=style[key];if(value==null||typeof value==="object"||key.startsWith("_"))continue;base+=`${toKebabCase(key)}:${value};`}if(base){let rule=`${ctx.selector}{${base}}`;css+=ctx.media?`@media ${ctx.media}{${rule}}`:rule}for(let pseudo of["_hover","_focus","_active"]){let value=style[pseudo];if(!value)continue;css+=serializeNested(value,{selector:`${ctx.selector}:${pseudo.slice(1)}`,media:ctx.media})}for(let key in MEDIA_MAP){let mediaKey=key,value=style[mediaKey];if(!value)continue;css+=serializeNested(value,{selector:ctx.selector,media:mergeMedia(ctx.media,MEDIA_MAP[mediaKey])})}return css}class NextStyle{prefix;rules=new Map;constructor(prefix="next"){this.prefix=prefix}css=(style)=>{let seed=stableStringify(style),hash=createHashName(seed),className=`${this.prefix}_${hash}`,key=`class:${className}`;if(!this.rules.has(key)){let raw=serializeNested(style,{selector:`.${className}`}),cssText=postcssTransform(raw);this.rules.set(key,cssText)}return className};global=(selector,style)=>{let key=`global:${selector}`;if(!this.rules.has(key)){let raw=serializeNested(style,{selector}),cssText=postcssTransform(raw);this.rules.set(key,cssText)}};keyframes=(frames)=>{let seed=stableStringify(frames),hash=createHashName(seed),name=`${this.prefix}_${hash}`,key=`@keyframes:${name}`;if(!this.rules.has(key)){let body="";for(let step in frames){let props="",frame=frames[step];for(let prop in frame)props+=`${toKebabCase(prop)}:${frame[prop]};`;body+=`${step}{${props}}`}let cssText=postcssTransform(`@keyframes ${name}{${body}}`);this.rules.set(key,cssText)}return name};fontFace=(font)=>{let seed=stableStringify(font),key=`@font-face:${createHashName(seed)}`;if(!this.rules.has(key)){let body="";for(let prop in font)body+=`${toKebabCase(prop)}:${font[prop]};`;let cssText=postcssTransform(`@font-face{${body}}`);this.rules.set(key,cssText)}};toTextCss=()=>{if(this.rules.size===0)return null;let cssText="";for(let rule of this.rules.values())cssText+=rule+`
+`;return cssText};StyleProvider=()=>{if(this.rules.size===0)return null;let cssText="";for(let rule of this.rules.values())cssText+=rule+`
+`;return createElement("style",{children:cssText})}}export{NextStyle};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "next-style",
-	"version": "1.1.4",
+	"version": "1.1.5",
 	"description": "Lightweight runtime CSS-in-JS engine with nested pseudo selectors, media queries, global styles, keyframes, and font-face support.",
 	"author": {
 		"name": "kingslimes",
@@ -52,15 +52,13 @@
 		"font-face"
 	],
 	"peerDependencies": {
+		"react": ">=18",
 		"postcss": "^8",
 		"autoprefixer": "^10"
 	},
 	"devDependencies": {
         "csstype": "latest"
 	},
-	"engines": {
-		"node": ">=18"
-	},
 	"publishConfig": {
 		"access": "public"
 	}