next-style 1.1.5 → 1.1.6

package/README.md

@@ -155,6 +155,202 @@ css({
 
 ---
 
+## 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;
+}
+```
+
+---
+
+## Supported States
+
+You can define relationships based on the following pseudo states:
+
+- `hover()` → `:hover`
+- `focus()` → `:focus`
+- `active()` → `:active`
+
+Example:
+
+``` ts
+when(input)
+  .focus()
+  .sibling(label, {
+    color: "blue"
+  })
+```
+Equivalent CSS:
+
+``` css
+input:focus ~ label {
+  color: blue;
+}
+```
+
+---
+
+## Supported Relationships
+
+### Adjacent Sibling (`+`)
+
+Applies styles to the **immediately following sibling**.
+
+``` ts
+when(div)
+  .hover()
+  .adjacent(p, {
+    color: "red"
+  })
+```
+CSS equivalent:
+
+``` css
+div:hover + p {
+  color: red;
+}
+```
+
+---
+
+### General Sibling (`~`)
+
+Applies styles to **all following siblings**.
+
+``` ts
+when(div)
+  .hover()
+  .sibling(p, {
+    color: "red"
+  })
+```
+CSS equivalent:
+
+``` css
+div:hover ~ p {
+  color: red;
+}
+```
+
+---
+
+### Child (`>`)
+
+Applies styles to **direct children only**.
+
+``` ts
+when(card)
+  .hover()
+  .child(icon, {
+    transform: "scale(1.1)"
+  })
+```
+CSS equivalent:
+
+``` css
+card:hover > icon {
+  transform: scale(1.1);
+}
+```
+
+---
+
+### Descendant (space)
+
+Applies styles to **any nested element**.
+
+``` ts
+when(menu)
+  .hover()
+  .descendant(item, {
+    backgroundColor: "#eee"
+  })
+```
+CSS equivalent:
+
+``` css
+menu:hover item {
+  background-color: #eee;
+}
+```
+
+---
+
+## Why Use `when()` Instead of `global()`?
+
+While `global()` allows full control over raw selectors, `when()` provides:
+
+- Clear intent and better readability  
+- No need to manually concatenate class names  
+- Safer refactoring (class tokens, not strings)  
+- IDE autocomplete and JSDoc support  
+
+Comparison:
+
+``` ts
+// global selector
+global(`.${a}:hover + .${b}`, { color: "red" })
+
+// relation API
+when(a).hover().adjacent(b, { color: "red" })
+```
+
+---
+
+## Notes
+
+- `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
+
+---
+
+## Example With Media Query
+
+``` ts
+when(container)
+  .hover()
+  .sibling(text, {
+    color: "red",
+    _md: {
+      color: "blue"
+    }
+  })
+```
+
+---
+
+This API is intentionally minimal and composable, allowing you to express complex UI relationships without leaking CSS selector syntax into your application code.
+
+---
+
 ## Responsive Media Queries
 
 Built-in breakpoints:

package/dist/index.d.ts

@@ -24,12 +24,73 @@ type FontFaceObject = {
     fontDisplay?: string;
     unicodeRange?: string;
 };
+type PseudoState = "hover" | "focus" | "active";
+declare class RelationBuilder {
+    private ns;
+    private source;
+    private pseudo?;
+    constructor(ns: NextStyle, source: string, pseudo?: PseudoState | undefined);
+    /** :hover */
+    hover(): RelationBuilder;
+    /** :focus */
+    focus(): RelationBuilder;
+    /** :active */
+    active(): RelationBuilder;
+    /**
+     * Adjacent sibling selector
+     *
+     * CSS:
+     * div:hover + p
+     *
+     * @example
+     * when(div).hover().adjacent(p, { color: "red" })
+     */
+    adjacent(target: string, style: NextStyleProperties): void;
+    /**
+     * Child selector
+     *
+     * CSS:
+     * div:hover > p
+     *
+     * @example
+     * when(div).hover().child(p, { color: "red" })
+     */
+    child(target: string, style: NextStyleProperties): void;
+    /**
+     * General sibling selector
+     *
+     * CSS:
+     * div:hover ~ p
+     *
+     * @example
+     * when(div).hover().sibling(p, { color: "red" })
+     */
+    sibling(target: string, style: NextStyleProperties): void;
+    /**
+     * Descendant selector
+     *
+     * CSS:
+     * div:hover p
+     *
+     * @example
+     * when(div).hover().descendant(p, { color: "red" })
+     */
+    descendant(target: string, style: NextStyleProperties): void;
+    private emit;
+}
 export declare class NextStyle {
     private prefix;
     private rules;
     constructor(prefix?: string);
     css: (style: NextStyleProperties) => string;
     global: (selector: string, style: NextStyleProperties) => void;
+    /**
+     * Relation selector API
+     *
+     * @example
+     * when(container).hover().sibling(text)
+     */
+    when: (source: string) => RelationBuilder;
     keyframes: (frames: KeyframesObject) => string;
     fontFace: (font: FontFaceObject) => void;
     toTextCss: () => string | 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="",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+`
+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 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)}};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 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.5",
+	"version": "1.1.6",
 	"description": "Lightweight runtime CSS-in-JS engine with nested pseudo selectors, media queries, global styles, keyframes, and font-face support.",
 	"author": {
 		"name": "kingslimes",
@@ -62,4 +62,4 @@
 	"publishConfig": {
 		"access": "public"
 	}
-}
+}