next-style 1.1.8 → 1.2.0

package/dist/index.d.ts

@@ -1,7 +1,23 @@
 import type { Properties } from "csstype";
 import type { DetailedReactHTMLElement } from "react";
 /**
- * Style object supported by next-style
+ * Style object used by NextStyle.
+ *
+ * Supports:
+ * - Standard CSS properties (camelCase)
+ * - Pseudo states via `_hover`, `_focus`, `_active`
+ * - Responsive media queries via `_sm` ~ `_xxl`
+ *
+ * Example:
+ * ```ts
+ * const button = css({
+ *   padding: "8px 16px",
+ *   backgroundColor: "black",
+ *   color: "white",
+ *   _hover: { opacity: 0.8 },
+ *   _md: { padding: "12px 20px" }
+ * })
+ * ```
  */
 export type NextStyleProperties = {
     [K in keyof Properties<string | number>]?: Properties<string | number>[K];
@@ -28,37 +44,252 @@ type FontFaceObject = {
     unicodeRange?: string;
 };
 type PseudoState = "hover" | "focus" | "active";
+/**
+ * Builder for defining relations starting from a generated class name.
+ *
+ * This builder should only be created via `NextStyle.when(...)`.
+ */
 declare class RelationBuilder {
     private ns;
     private source;
     private pseudo?;
+    /**
+     * @internal
+     * @param ns NextStyle instance
+     * @param source Source class name generated by `css()`
+     * @param pseudo Optional pseudo state applied to the source
+     */
     constructor(ns: NextStyle, source: string, pseudo?: PseudoState | undefined);
+    /**
+     * Apply `:hover` pseudo state to the source selector.
+     *
+     * All subsequent relations will be scoped under `:hover`.
+     *
+     * @returns RelationBuilder
+     *
+     * Example:
+     * ```ts
+     * when(card)
+     *   .hover()
+     *   .child(icon, { opacity: 1 })
+     * ```
+     */
     hover(): RelationBuilder;
+    /**
+     * Apply `:focus` pseudo state to the source selector.
+     *
+     * @returns RelationBuilder
+     */
     focus(): RelationBuilder;
+    /**
+     * Apply `:active` pseudo state to the source selector.
+     *
+     * @returns RelationBuilder
+     */
     active(): RelationBuilder;
+    /**
+     * Define styles for an adjacent sibling selector.
+     *
+     * CSS equivalent:
+     * `.source + .target`
+     *
+     * @param target Target class name generated by `css()`
+     * @param style Style applied to the target element
+     *
+     * Example:
+     * ```ts
+     * when(input)
+     *   .focus()
+     *   .adjacent(label, { color: "red" })
+     * ```
+     */
     adjacent(target: string, style: NextStyleProperties): void;
+    /**
+     * Define styles for a direct child selector.
+     *
+     * CSS equivalent:
+     * `.source > .target`
+     *
+     * @param target Target class name generated by `css()`
+     * @param style Style applied to the target element
+     */
     child(target: string, style: NextStyleProperties): void;
+    /**
+     * Define styles for a general sibling selector.
+     *
+     * CSS equivalent:
+     * `.source ~ .target`
+     *
+     * @param target Target class name generated by `css()`
+     * @param style Style applied to the target element
+     */
     sibling(target: string, style: NextStyleProperties): void;
+    /**
+     * Define styles for a descendant selector.
+     *
+     * CSS equivalent:
+     * `.source .target`
+     *
+     * @param target Target class name generated by `css()`
+     * @param style Style applied to the target element
+     */
     descendant(target: string, style: NextStyleProperties): void;
+    /**
+     * @internal
+     * Emit a global relational rule.
+     */
     private emit;
 }
 /**
- * NextStyle runtime CSS-in-JS engine
+ * NextStyle
+ *
+ * Lightweight runtime CSS-in-JS engine with deterministic class names.
+ *
+ * Features:
+ * - Scoped class generation
+ * - Nested pseudo selectors
+ * - Responsive media queries
+ * - Global styles
+ * - Keyframes and font-face support
+ *
+ * Example:
+ * ```ts
+ * const ns = new NextStyle("app")
+ * ```
  */
 export declare class NextStyle {
     private prefix;
     private rules;
+    private globalStore;
     constructor(prefix?: string);
+    /**
+     * Generate a scoped class name from a style object.
+     *
+     * The returned value is a branded class name and is intended
+     * to be used with `when(...)` and relational APIs.
+     *
+     * @param style Style definition object
+     * @returns Scoped class name
+     *
+     * Example:
+     * ```ts
+     * const button = css({ padding: 8 })
+     * ```
+     */
     css: (style: NextStyleProperties) => string;
+    /**
+     * Define a global CSS selector.
+     *
+     * Styles are merged at property level instead of overwritten.
+     *
+     * @param selector CSS selector
+     * @param style Style definition
+     *
+     * Example:
+     * ```ts
+     * global("body", {
+     *   fontFamily: "Kanit, sans-serif"
+     * })
+     * ```
+     */
     global: (selector: string, style: NextStyleProperties) => void;
     /**
-     * Apply default global CSS reset
+     * Apply default browser reset styles
+     * ```css
+     * html, body {
+     *     max-width: 100vw;
+     *     overflow-x: hidden;
+     * }
+     * body {
+     *     color: "black";
+     *     background: "white";
+     *     -moz-osx-font-smoothing: grayscale;
+     *     -webkit-font-smoothing: antialiased;
+     *     font-family: "Arial, Helvetica, sans-serif"
+     * }
+     * *,
+     * *::before,
+     * *::after {
+     *     margin: 0;
+     *     padding: 0;
+     *     box-sizing: border-box;
+     * }
+     * a {
+     *     color: inherit;
+     *     text-decoration: none
+     * }
+     * ```
+     */
+    resetStyle: () => this;
+    /**
+     * Create relational selectors based on a class generated by `css(...)`.
+     *
+     * ⚠️ This method only accepts class names returned from `css`.
+     *
+     * @param source Class name generated by `css`
+     *
+     * Example:
+     * ```ts
+     * const card = css({ ... })
+     *
+     * when(card)
+     *   .hover()
+     *   .child("icon", { opacity: 1 })
+     * ```
      */
-    resetBrowserStyle: () => void;
     when: (source: string) => RelationBuilder;
+    /**
+     * Register keyframes animation.
+     *
+     * @param frames Keyframes definition
+     * @returns Generated animation name
+     *
+     * Example:
+     * ```ts
+     * const fadeIn = keyframes({
+     *   from: { opacity: 0 },
+     *   to: { opacity: 1 }
+     * })
+     * ```
+     */
     keyframes: (frames: KeyframesObject) => string;
+    /**
+     * Register a `@font-face` rule.
+     *
+     * Each unique definition is injected only once.
+     *
+     * @param font Font-face definition
+     *
+     * Example:
+     * ```ts
+     * fontFace({
+     *   fontFamily: "Kanit",
+     *   src: "url(/kanit.woff2) format('woff2')",
+     *   fontWeight: 400
+     * })
+     * ```
+     */
     fontFace: (font: FontFaceObject) => void;
+    /**
+     * Serialize all generated CSS into a single string.
+     *
+     * Intended for:
+     * - Manual `<style>` injection
+     * - SSR environments
+     *
+     * @returns CSS text or `null` if no styles exist
+     */
     toTextCss: () => string | null;
+    /**
+     * React component that injects generated CSS into a `<style>` tag.
+     *
+     * Returns `null` if no styles are registered.
+     *
+     * Example:
+     * ```tsx
+     * <StyleProvider />
+     * ```
+     */
     StyleProvider: () => DetailedReactHTMLElement<{
         children: string;
     }, HTMLStyleElement> | null;

package/dist/index.js

@@ -1,3 +1,3 @@
-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="",declarations=[];for(let key in style){let value=style[key];if(value==null||typeof value==="object"||key.startsWith("_"))continue;declarations.push(`${toKebabCase(key)}:${value}`)}if(declarations.length){let rule=`${ctx.selector}{ ${declarations.join("; ")} }`;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 RelationBuilder{ns;source;pseudo;constructor(ns,source,pseudo){this.ns=ns;this.source=source;this.pseudo=pseudo}hover(){return new RelationBuilder(this.ns,this.source,"hover")}focus(){return new RelationBuilder(this.ns,this.source,"focus")}active(){return new RelationBuilder(this.ns,this.source,"active")}adjacent(target,style){this.emit("+",target,style)}child(target,style){this.emit(">",target,style)}sibling(target,style){this.emit("~",target,style)}descendant(target,style){this.emit(" ",target,style)}emit(combinator,target,style){let pseudo=this.pseudo?`:${this.pseudo}`:"",selector=`.${this.source}${pseudo}${combinator}.${target}`;this.ns.global(selector,style)}}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)}};resetBrowserStyle=()=>{this.global("html,body",{maxWidth:"100vw",overflowX:"hidden"}),this.global("body",{color:"black",background:"white",fontFamily:"Arial, Helvetica, sans-serif",WebkitFontSmoothing:"antialiased",MozOsxFontSmoothing:"grayscale"}),this.global("*",{boxSizing:"border-box",padding:0,margin:0}),this.global("a",{color:"inherit",textDecoration:"none"})};when=(source)=>{return new RelationBuilder(this,source)};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 declarations=[],frame=frames[step];for(let prop in frame)declarations.push(`${toKebabCase(prop)}:${frame[prop]}`);body+=`${step}{ ${declarations.join("; ")} }`}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 declarations=[];for(let prop in font)declarations.push(`${toKebabCase(prop)}:${font[prop]}`);let cssText=postcssTransform(`@font-face{ ${declarations.join("; ")} }`);this.rules.set(key,cssText)}};toTextCss=()=>{if(this.rules.size===0)return null;let cssText="";for(let rule of this.rules.values())cssText+=rule+`
+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="",declarations=[];for(let key in style){let value=style[key];if(value==null||typeof value==="object"||key.startsWith("_"))continue;declarations.push(`${toKebabCase(key)}:${value}`)}if(declarations.length){let rule=`${ctx.selector}{${declarations.join(";")}}`;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 RelationBuilder{ns;source;pseudo;constructor(ns,source,pseudo){this.ns=ns;this.source=source;this.pseudo=pseudo}hover(){return new RelationBuilder(this.ns,this.source,"hover")}focus(){return new RelationBuilder(this.ns,this.source,"focus")}active(){return new RelationBuilder(this.ns,this.source,"active")}adjacent(target,style){this.emit("+",target,style)}child(target,style){this.emit(">",target,style)}sibling(target,style){this.emit("~",target,style)}descendant(target,style){this.emit(" ",target,style)}emit(combinator,target,style){let pseudo=this.pseudo?`:${this.pseudo}`:"",selector=`.${this.source}${pseudo}${combinator}.${target}`;this.ns.global(selector,style)}}class NextStyle{prefix;rules=new Map;globalStore=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}`,merged={...this.globalStore.get(key)??{},...style};this.globalStore.set(key,merged);let raw=serializeNested(merged,{selector}),cssText=postcssTransform(raw);if(this.rules.has(key))this.rules.delete(key);this.rules.set(key,cssText)};resetStyle=()=>{return this.global("html,body",{maxWidth:"100vw",overflowX:"hidden"}),this.global("body",{color:"black",background:"white",MozOsxFontSmoothing:"grayscale",WebkitFontSmoothing:"antialiased",fontFamily:"Arial, Helvetica, sans-serif"}),this.global("*,*::before,*::after",{margin:0,padding:0,boxSizing:"border-box"}),this.global("a",{color:"inherit",textDecoration:"none"}),this};when=(source)=>new RelationBuilder(this,source);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 declarations=[],frame=frames[step];for(let prop in frame)declarations.push(`${toKebabCase(prop)}:${frame[prop]}`);body+=`${step}{ ${declarations.join(";")} }`}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 declarations=[];for(let prop in font)declarations.push(`${toKebabCase(prop)}:${font[prop]}`);let cssText=postcssTransform(`@font-face{ ${declarations.join(";")} }`);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.8",
+	"version": "1.2.0",
 	"description": "Lightweight runtime CSS-in-JS engine with nested pseudo selectors, media queries, global styles, keyframes, and font-face support.",
 	"author": {
 		"name": "kingslimes",