next-style 1.1.1 → 1.1.2

package/README.md

@@ -1,227 +1,285 @@
-# 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.
+
+---
+
+## 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 `StyleProvider`
+
+Because of this design:
+- `new NextStyle()` must be created inside the page or component scope
+- `StyleProvider` must be rendered **on every page where styles are used**
 
 ---
 
 ## 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
+- Global styles (page-scoped)
+- `@keyframes` support
+- `@font-face` support
+- PostCSS + Autoprefixer integration
+- Automatic rule deduplication (within a page)
+- Single `<style>` injection per page
+- 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)
+
+Create a `NextStyle` instance **inside the page or component**.  
+You may optionally provide a **custom prefix** to control generated class names.
 
-```tsx
-export default function App() {
+```ts
+import { NextStyle } from "next-style"
+
+export default function Page() {
+    const style = new NextStyle("home")
+    const button = style.css({
+        padding: "8px 16px",
+        backgroundColor: "black",
+        color: "white",
+        borderRadius: 6
+    })
     return (
         <>
-            <div className={className}>
-                Hello NextStyle
-            </div>
-            <style.Provider />
+            <style.StyleProvider />
+            <button className={ button }>Click me</button>
         </>
     )
 }
 ```
 
----
+Generated class names will look like:
 
-## Style Object API
+```txt
+home_ab12cd3
+```
 
-### Base Properties
+Notes:
+- The prefix is optional
+- If omitted, the default prefix is used
+- Prefixes help identify styles per page or component
+- Each page or component should create its own `NextStyle` instance
 
-All standard CSS properties are supported and fully typed:
 
-```ts
-{
-    margin: "8px",
-    fontSize: "14px",
-    backgroundColor: "#000"
-}
-```
+## Why StyleProvider Is Required Per Page
 
-Types are derived from `csstype`, ensuring correctness and editor autocomplete.
+`next-style` does not use a global style registry.
+
+Each `NextStyle` instance:
+- Collects styles locally
+- Injects a single `<style>` tag
+- Is destroyed when the page/component unmounts
+
+This ensures:
+- No stale CSS after route changes
+- No style conflicts between pages
+- Predictable SSR and CSR behavior
 
 ---
 
-### Pseudo Selectors
+## Pseudo Selectors
 
-Use underscored keys for pseudo selectors:
+Pseudo selectors are defined using keys prefixed with `_`.
 
 ```ts
-{
+const card = style.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
-
-NextStyle provides built-in responsive keys:
+## Responsive Styles (Media Queries)
 
-| Key   | Media Query |
-|------|-------------|
-| `_sm` | `(min-width: 640px)` |
-| `_md` | `(min-width: 768px)` |
-| `_lg` | `(min-width: 1024px)` |
-| `_xl` | `(min-width: 1280px)` |
-| `_xxl` | `(min-width: 1536px)` |
+Built-in breakpoints:
 
-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 = style.css({
+    width: 100,
+    _md: {
+        width: 200
+    },
     _lg: {
-        fontSize: "18px"
+        width: 300
     }
-}
+})
 ```
 
----
-
-## `<style.Provider />`
+Media queries can be nested and are automatically merged.
 
-The `Provider` component injects all generated CSS rules into a `<style>` tag.
+---
 
-Important notes:
+## Global Styles (Page Scoped)
 
-- 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
+Global styles are **scoped to the current page**.
 
-```tsx
-<style.Provider />
+```ts
+style.global("body", {
+    margin: 0,
+    fontFamily: "Inter, sans-serif"
+})
 ```
 
+These styles are removed automatically when the page unmounts.
+
 ---
 
-## Hashing Strategy
+## Keyframes
 
-Class names are generated using a deterministic hash based on the style object:
+Create animations using `keyframes()`:
 
-```text
-next_x9k3a2m1
+```ts
+const fadeIn = style.keyframes({
+    from: { opacity: 0 },
+    to: { opacity: 1 }
+})
 ```
 
-This ensures:
-- Stable class names
-- No duplicates
-- Automatic caching of generated rules
+```ts
+const modal = style.css({
+    animation: `${ fadeIn } 0.3s ease-out`
+})
+```
+
+Keyframes are scoped to the current `NextStyle` instance.
 
 ---
 
-## Runtime Behavior
+## Font Face
 
-- 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
+Declare fonts using `fontFace()`:
 
----
+```ts
+style.fontFace({
+    fontFamily: "Inter",
+    src: "url(/fonts/inter.woff2) format('woff2')",
+    fontWeight: 400,
+    fontStyle: "normal",
+    fontDisplay: "swap"
+})
+```
 
-## Type Safety
+Font-face rules are injected only for the current page.
 
-NextStyle provides full TypeScript support:
+---
 
-- All CSS properties are typed
-- Invalid properties are caught at compile time
-- Media and pseudo keys are strictly controlled
+## Deterministic Hashing
 
-Types are generated via `.d.ts` and require no runtime dependency on `csstype`.
+- 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
 
 ---
 
-## Requirements
+## Performance
 
-### Peer Dependencies
+- CSS rules are generated and injected only once per page
+- PostCSS and Autoprefixer results are cached
+- One `<style>` tag per page
+- No global runtime mutation
 
-- React >= 18
-- PostCSS >= 8
-- Autoprefixer >= 10
+Ideal for:
+- Next.js App Router
+- Page-level isolation
+- Component-driven design systems
 
-### Runtime Environment
+---
 
-- Node.js >= 18
-- Bun >= 1.0.0
+## Package Information
 
----
+- Name: `next-style`
+- Version: `1.1.2`
+- License: MIT
+- Module type: ESM
+- Side effects: false
 
-## License
+Repository:  
+https://github.com/kingslimes/next-style
 
-MIT © kingslimes
+Issues:  
+https://github.com/kingslimes/next-style/issues
 
 ---
 
-## Philosophy
+## Roadmap
 
-NextStyle is intentionally minimal.
+- `&` selector nesting
+- `_dark` / `_light` helpers
+- `@layer` support
+- SSR collection utilities
+- Framework adapters (Solid, Preact)
 
-- No build-time CSS extraction
-- No global runtime side effects
-- No magic conventions
+---
 
-Just predictable runtime styling with strong types and explicit behavior.
+## License
+
+MIT © kingslimes

package/dist/index.d.ts

@@ -12,11 +12,25 @@ export type NextStyleProperties = {
     _xxl?: NextStyleObject;
 };
 type NextStyleObject = Omit<NextStyleProperties, "_sm" | "_md" | "_lg" | "_xl" | "_xxl">;
+type KeyframesObject = {
+    [step: string]: Properties<string | number>;
+};
+type FontFaceObject = {
+    fontFamily: string;
+    src: string;
+    fontWeight?: string | number;
+    fontStyle?: string;
+    fontDisplay?: string;
+    unicodeRange?: string;
+};
 export declare class NextStyle {
     private prefix;
     private rules;
     constructor(prefix?: string);
     css: (style: NextStyleProperties) => string;
-    Provider: () => import("react").JSX.Element | null;
+    global: (selector: string, style: NextStyleProperties) => void;
+    keyframes: (frames: KeyframesObject) => string;
+    fontFace: (font: FontFaceObject) => void;
+    StyleProvider: () => import("react").JSX.Element | null;
 }
 export {};

package/dist/index.jsx

@@ -13,6 +13,12 @@ function postcssTransform(cssText) {
   postcssCache.set(cssText, result);
   return result;
 }
+function stableStringify(value) {
+  if (value == null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
+  const keys = Object.keys(value).sort();
+  return `{${keys.map(k => `"${k}":${stableStringify(value[k])}`).join(",")}}`;
+}
 function createHashName(seed) {
   let hash = BigInt("0xcbf29ce484222325");
   const prime = BigInt("0x100000001b3");
@@ -33,6 +39,11 @@ const MEDIA_MAP = {
   _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 = "";
   let base = "";
@@ -43,14 +54,14 @@ function serializeNested(style, ctx) {
   }
   if (base) {
     const rule = `${ctx.selector}{${base}}`;
-    css += ctx.media ? `${ctx.media}{${rule}}` : rule;
+    css += ctx.media ? `@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)}`
+      selector: `${ctx.selector}:${pseudo.slice(1)}`,
+      media: ctx.media
     });
   }
   for (const key in MEDIA_MAP) {
@@ -58,8 +69,8 @@ function serializeNested(style, ctx) {
     const value = style[mediaKey];
     if (!value) continue;
     css += serializeNested(value, {
-      ...ctx,
-      media: `@media ${MEDIA_MAP[mediaKey]}`
+      selector: ctx.selector,
+      media: mergeMedia(ctx.media, MEDIA_MAP[mediaKey])
     });
   }
   return css;
@@ -70,18 +81,63 @@ export class NextStyle {
     this.prefix = prefix;
   }
   css = style => {
-    const hash = createHashName(JSON.stringify(style));
+    const seed = stableStringify(style);
+    const hash = createHashName(seed);
     const className = `${this.prefix}_${hash}`;
-    if (!this.rules.has(className)) {
+    const key = `class:${className}`;
+    if (!this.rules.has(key)) {
       const raw = serializeNested(style, {
         selector: `.${className}`
       });
       const cssText = postcssTransform(raw);
-      this.rules.set(className, cssText);
+      this.rules.set(key, cssText);
     }
     return className;
   };
-  Provider = () => {
+  global = (selector, style) => {
+    const key = `global:${selector}`;
+    if (!this.rules.has(key)) {
+      const raw = serializeNested(style, {
+        selector
+      });
+      const cssText = postcssTransform(raw);
+      this.rules.set(key, cssText);
+    }
+  };
+  keyframes = frames => {
+    const seed = stableStringify(frames);
+    const hash = createHashName(seed);
+    const name = `${this.prefix}_${hash}`;
+    const key = `@keyframes:${name}`;
+    if (!this.rules.has(key)) {
+      let body = "";
+      for (const step in frames) {
+        let props = "";
+        const frame = frames[step];
+        for (const prop in frame) {
+          props += `${toKebabCase(prop)}:${frame[prop]};`;
+        }
+        body += `${step}{${props}}`;
+      }
+      const cssText = postcssTransform(`@keyframes ${name}{${body}}`);
+      this.rules.set(key, cssText);
+    }
+    return name;
+  };
+  fontFace = font => {
+    const seed = stableStringify(font);
+    const hash = createHashName(seed);
+    const key = `@font-face:${hash}`;
+    if (!this.rules.has(key)) {
+      let body = "";
+      for (const prop in font) {
+        body += `${toKebabCase(prop)}:${font[prop]};`;
+      }
+      const cssText = postcssTransform(`@font-face{${body}}`);
+      this.rules.set(key, cssText);
+    }
+  };
+  StyleProvider = () => {
     if (this.rules.size === 0) return null;
     let cssText = "";
     for (const rule of this.rules.values()) {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "next-style",
-	"version": "1.1.1",
+	"version": "1.1.2",
 	"description": "Lightweight runtime CSS-in-JS engine with nested pseudo selectors, media queries, global styles, keyframes, and font-face support.",
 	"author": {
 		"name": "kingslimes",
@@ -26,12 +26,12 @@
 	},
 	"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",
@@ -57,7 +57,7 @@
 		"autoprefixer": "^10"
 	},
 	"devDependencies": {
-        "csstype": "^3"
+        "csstype": "latest"
 	},
 	"engines": {
 		"bun": ">=1.0.0",