next-style 1.1.1 → 1.1.3

package/README.md

@@ -1,227 +1,303 @@
-# NextStyle
+# next-style
 
-A lightweight runtime CSS-in-JS engine designed for React and Next.js.  
-It supports nested pseudo selectors, responsive media queries, and automatic vendor prefixing via PostCSS — all at runtime with zero build-time CSS extraction.
+**next-style** is a lightweight runtime CSS-in-JS engine designed for React, Next.js, and Bun.
 
-NextStyle focuses on **runtime flexibility**, **type safety**, and **minimal abstraction**, making it suitable for design systems, theming, and dynamic UI styling.
+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.
+
+---
+
+## 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
+
+Because of this design:
+- `new NextStyle()` must be created inside the page or component scope
+- Styles must be injected manually using `ns.StyleText`
 
 ---
 
 ## Features
 
-- Runtime CSS generation
-- Strongly typed style objects (powered by `csstype`)
+- Object-based styling with strong TypeScript support
+- Deterministic hashing (same styles always produce the same class name)
 - Nested pseudo selectors (`_hover`, `_focus`, `_active`)
-- Responsive media queries (`_sm`, `_md`, `_lg`, `_xl`, `_xxl`)
-- Automatic vendor prefixing (PostCSS + Autoprefixer)
-- Deterministic hashed class names
-- React `<style>` provider component
-- No bundler or build-step CSS required
+- Built-in responsive media queries
+- Page-scoped 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`)
 
 ---
 
 ## Installation
 
-Install the package along with its peer dependencies:
+### npm
 
-```bash
-npm install next-style postcss autoprefixer react
+```sh
+npm install next-style
 ```
 
-or with Bun:
+### Bun
 
-```bash
-bun add next-style postcss autoprefixer react
+```sh
+bun add next-style
 ```
 
 ---
 
-## Basic Usage
+## Peer Dependencies
 
-```tsx
-import { NextStyle } from "next-style"
+For most **Next.js applications**, you **do not need to install these manually**.
 
-const style = new NextStyle('home') // output className = home_{hash} default "next_{hash}"
+- **React** is already included with Next.js
+- **PostCSS** and **Autoprefixer** are bundled and used internally by Next.js
 
-const className = style.css({
-    display: "flex",
-    alignItems: "center",
-    padding: "12px",
-    backgroundColor: "#111",
-    color: "white",
-    _hover: {
-        backgroundColor: "#222"
-    },
-    _md: {
-        padding: "16px"
-    }
-})
+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
+
+If required, install them manually:
+
+```sh
+npm install react postcss autoprefixer
 ```
 
-Apply the generated class name to your component:
+---
+
+## Basic Usage (Page Scoped)
 
-```tsx
-export default function App() {
+Create a `NextStyle` instance **inside the page or component**.  
+You may optionally provide a **custom prefix** to control generated class names.
+
+```ts
+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"
+    })
     return (
         <>
-            <div className={className}>
-                Hello NextStyle
-            </div>
-            <style.Provider />
+            <style>{ ns.StyleText }</style>
+            <button className={ btn }>Click me</button>
         </>
     )
 }
 ```
 
----
+Generated class names will look like:
 
-## Style Object API
-
-### Base Properties
-
-All standard CSS properties are supported and fully typed:
-
-```ts
-{
-    margin: "8px",
-    fontSize: "14px",
-    backgroundColor: "#000"
-}
+```txt
+home_ab12cd3
 ```
 
-Types are derived from `csstype`, ensuring correctness and editor autocomplete.
+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
 
 ---
 
-### Pseudo Selectors
+## Pseudo Selectors
 
-Use underscored keys for pseudo selectors:
+Pseudo selectors are defined using keys prefixed with `_`.
 
 ```ts
-{
+const card = ns.css({
+    backgroundColor: "#fff",
+    transition: "0.2s ease",
     _hover: {
-        opacity: 0.8
-    },
-    _focus: {
-        outline: "2px solid blue"
+        backgroundColor: "#f5f5f5"
     },
     _active: {
         transform: "scale(0.98)"
     }
-}
+})
 ```
 
-Supported pseudos:
+Supported pseudo selectors:
 - `_hover`
 - `_focus`
 - `_active`
 
 ---
 
-### Responsive Media Queries
+## Responsive Styles (Media Queries)
 
-NextStyle provides built-in responsive keys:
+Built-in breakpoints:
 
-| Key   | Media Query |
-|------|-------------|
-| `_sm` | `(min-width: 640px)` |
-| `_md` | `(min-width: 768px)` |
-| `_lg` | `(min-width: 1024px)` |
-| `_xl` | `(min-width: 1280px)` |
-| `_xxl` | `(min-width: 1536px)` |
-
-Example:
+- `_sm` → min-width: 640px
+- `_md` → min-width: 768px
+- `_lg` → min-width: 1024px
+- `_xl` → min-width: 1280px
+- `_xxl` → min-width: 1536px
 
 ```ts
-{
-    fontSize: "14px",
+const box = ns.css({
+    width: 100,
+    _md: {
+        width: 200
+    },
     _lg: {
-        fontSize: "18px"
+        width: 300
     }
-}
+})
 ```
 
+Media queries can be nested and are automatically merged.
+
 ---
 
-## `<style.Provider />`
+## Global Styles (Page Scoped)
 
-The `Provider` component injects all generated CSS rules into a `<style>` tag.
+Global styles are scoped to the current page or component instance.
 
-Important notes:
+```ts
+ns.global("body", {
+    margin: 0,
+    fontFamily: "Inter, sans-serif"
+})
+```
 
-- It must be rendered **once per style instance**
-- It should be rendered **after** calling `css(...)`
-- It performs no side effects if no styles were generated
+These styles exist only for the lifetime of the page or component.
 
-```tsx
-<style.Provider />
+---
+
+## Keyframes
+
+Create animations using `keyframes()`:
+
+```ts
+const fadeIn = ns.keyframes({
+    from: { opacity: 0 },
+    to: { opacity: 1 }
+})
+```
+
+Use the animation in styles:
+
+```ts
+const modal = ns.css({
+    animation: `${ fadeIn } 0.3s ease-out`
+})
 ```
 
+Keyframes are scoped to the current `NextStyle` instance.
+
 ---
 
-## Hashing Strategy
+## Font Face
 
-Class names are generated using a deterministic hash based on the style object:
+Declare fonts using `fontFace()`:
 
-```text
-next_x9k3a2m1
+```ts
+ns.fontFace({
+    fontFamily: "Inter",
+    src: "url(/fonts/inter.woff2) format('woff2')",
+    fontWeight: 400,
+    fontStyle: "normal",
+    fontDisplay: "swap"
+})
 ```
 
-This ensures:
-- Stable class names
-- No duplicates
-- Automatic caching of generated rules
+Font-face rules are injected only for the current page or component.
 
 ---
 
-## Runtime Behavior
+## Deterministic Hashing
 
-- CSS is generated lazily on first usage
-- Rules are cached in memory
-- PostCSS transformation runs only once per unique rule
-- No DOM mutation outside React rendering
+- 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
 
 ---
 
-## Type Safety
+## Server-Side Rendering (SSR)
 
-NextStyle provides full TypeScript support:
+`next-style` is SSR-safe.
 
-- All CSS properties are typed
-- Invalid properties are caught at compile time
-- Media and pseudo keys are strictly controlled
+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
 
-Types are generated via `.d.ts` and require no runtime dependency on `csstype`.
+You can safely inject styles during SSR:
+
+```tsx
+<style>{ ns.StyleText }</style>
+```
+
+The same output will be produced on both the server and the client.
 
 ---
 
-## Requirements
+## Performance Characteristics
 
-### Peer Dependencies
+- 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
 
-- React >= 18
-- PostCSS >= 8
-- Autoprefixer >= 10
+Ideal for:
+- Next.js App Router
+- Page-level isolation
+- Component-driven design systems
+
+---
 
-### Runtime Environment
+## Common Gotchas
 
-- Node.js >= 18
-- Bun >= 1.0.0
+- 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
 
 ---
 
-## License
+## Package Information
 
-MIT © kingslimes
+- Name: `next-style`
+- Version: `1.1.2`
+- License: MIT
+- Module type: ESM
+- Side effects: false
+
+Repository:  
+https://github.com/kingslimes/next-style
+
+Issues:  
+https://github.com/kingslimes/next-style/issues
 
 ---
 
-## Philosophy
+## Roadmap
 
-NextStyle is intentionally minimal.
+- `&` selector nesting
+- `_dark` / `_light` helpers
+- `@layer` support
+- Optional React helpers
+- Dev-time warnings for incorrect usage
 
-- No build-time CSS extraction
-- No global runtime side effects
-- No magic conventions
+---
+
+## License
 
-Just predictable runtime styling with strong types and explicit behavior.
+MIT © kingslimes

package/dist/index.js

@@ -0,0 +1,2 @@
+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};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "next-style",
-	"version": "1.1.1",
+	"version": "1.1.3",
 	"description": "Lightweight runtime CSS-in-JS engine with nested pseudo selectors, media queries, global styles, keyframes, and font-face support.",
 	"author": {
 		"name": "kingslimes",
@@ -16,22 +16,22 @@
 		"LICENSE",
 		"README.md"
 	],
-	"main": "./dist/index.jsx",
+	"main": "./dist/index.js",
 	"types": "./dist/index.d.ts",
 	"exports": {
 		".": {
-			"import": "./dist/index.jsx",
+			"import": "./dist/index.js",
 			"types": "./dist/index.d.ts"
 		}
 	},
 	"repository": {
 		"type": "git",
-		"url": "https://github.com/kingslimes/zed-style.git"
+		"url": "https://github.com/kingslimes/next-style.git"
 	},
 	"bugs": {
-		"url": "https://github.com/kingslimes/zed-style/issues"
+		"url": "https://github.com/kingslimes/next-style/issues"
 	},
-	"homepage": "https://github.com/kingslimes/zed-style#readme",
+	"homepage": "https://github.com/kingslimes/next-style#readme",
 	"keywords": [
 		"css",
 		"css-in-js",
@@ -52,15 +52,16 @@
 		"font-face"
 	],
 	"peerDependencies": {
-        "react": ">=18",
 		"postcss": "^8",
 		"autoprefixer": "^10"
 	},
 	"devDependencies": {
-        "csstype": "^3"
+        "csstype": "latest"
 	},
 	"engines": {
-		"bun": ">=1.0.0",
 		"node": ">=18"
+	},
+	"publishConfig": {
+		"access": "public"
 	}
 }

package/dist/index.d.ts

@@ -1,22 +0,0 @@
-import type { Properties } from "csstype";
-export type NextStyleProperties = {
-    [K in keyof Properties<string | number>]?: Properties<string | number>[K];
-} & {
-    _hover?: NextStyleObject;
-    _focus?: NextStyleObject;
-    _active?: NextStyleObject;
-    _sm?: NextStyleObject;
-    _md?: NextStyleObject;
-    _lg?: NextStyleObject;
-    _xl?: NextStyleObject;
-    _xxl?: NextStyleObject;
-};
-type NextStyleObject = Omit<NextStyleProperties, "_sm" | "_md" | "_lg" | "_xl" | "_xxl">;
-export declare class NextStyle {
-    private prefix;
-    private rules;
-    constructor(prefix?: string);
-    css: (style: NextStyleProperties) => string;
-    Provider: () => import("react").JSX.Element | null;
-}
-export {};

package/dist/index.jsx

@@ -1,92 +0,0 @@
-import postcss from "postcss";
-import autoprefixer from "autoprefixer";
-const processor = postcss([autoprefixer({
-  overrideBrowserslist: [">0.2%", "not dead", "not op_mini all"]
-})]);
-const postcssCache = new Map();
-function postcssTransform(cssText) {
-  const cached = postcssCache.get(cssText);
-  if (cached) return cached;
-  const result = processor.process(cssText, {
-    from: undefined
-  }).css;
-  postcssCache.set(cssText, result);
-  return result;
-}
-function createHashName(seed) {
-  let hash = BigInt("0xcbf29ce484222325");
-  const 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()}`);
-}
-const MEDIA_MAP = {
-  _sm: "( min-width: 640px )",
-  _md: "( min-width: 768px )",
-  _lg: "( min-width: 1024px )",
-  _xl: "( min-width: 1280px )",
-  _xxl: "( min-width: 1536px )"
-};
-function serializeNested(style, ctx) {
-  let css = "";
-  let base = "";
-  for (const key in style) {
-    const value = style[key];
-    if (value == null || typeof value === "object" || key.startsWith("_")) continue;
-    base += `${toKebabCase(key)}:${value};`;
-  }
-  if (base) {
-    const rule = `${ctx.selector}{${base}}`;
-    css += ctx.media ? `${ctx.media}{${rule}}` : rule;
-  }
-  for (const pseudo of ["_hover", "_focus", "_active"]) {
-    const value = style[pseudo];
-    if (!value) continue;
-    css += serializeNested(value, {
-      ...ctx,
-      selector: `${ctx.selector}:${pseudo.slice(1)}`
-    });
-  }
-  for (const key in MEDIA_MAP) {
-    const mediaKey = key;
-    const value = style[mediaKey];
-    if (!value) continue;
-    css += serializeNested(value, {
-      ...ctx,
-      media: `@media ${MEDIA_MAP[mediaKey]}`
-    });
-  }
-  return css;
-}
-export class NextStyle {
-  rules = new Map();
-  constructor(prefix = "next") {
-    this.prefix = prefix;
-  }
-  css = style => {
-    const hash = createHashName(JSON.stringify(style));
-    const className = `${this.prefix}_${hash}`;
-    if (!this.rules.has(className)) {
-      const raw = serializeNested(style, {
-        selector: `.${className}`
-      });
-      const cssText = postcssTransform(raw);
-      this.rules.set(className, cssText);
-    }
-    return className;
-  };
-  Provider = () => {
-    if (this.rules.size === 0) return null;
-    let cssText = "";
-    for (const rule of this.rules.values()) {
-      cssText += rule + "\n";
-    }
-    return <style>{cssText}</style>;
-  };
-}