next-style 2.2.1 → 2.2.3

package/dist/index.d.ts

@@ -1,9 +1,126 @@
 import { Properties, Pseudos } from 'csstype';
 
+/**
+ * The compiled representation of a single `css({})` call.
+ * Produced by `StyleCollector` and consumed by the PostCSS plugin.
+ */
+interface CompiledStyle {
+    /** Scoped class name, e.g. `"ns-1x2y3z"`. */
+    className: string;
+    /** Base CSS rule block for this class. */
+    css: string;
+    /** Map of normalized media query string → CSS rule block. */
+    mediaQueries: Record<string, string>;
+    /** Map of pseudo selector (e.g. `":hover"`) → CSS rule block. */
+    pseudoClasses: Record<string, string>;
+    /** Concatenated `@keyframes` blocks referenced by this style. */
+    keyframes: string;
+    /** Map of `@supports` condition → CSS rule block. */
+    supports: Record<string, string>;
+    /** Map of `@layer` name → CSS rule block. */
+    layers: Record<string, string>;
+}
+/**
+ * Collects, compiles, and deduplicates styles registered via `css()` and `global()`.
+ *
+ * A single shared instance is held by the runtime module. The PostCSS plugin
+ * calls `getAllStyles()` at build time to drain the collected CSS.
+ *
+ * @example
+ * const collector = new StyleCollector()
+ * const className = collector.addStyle({ color: 'red' }) // "ns-abc123"
+ * const css = collector.getAllStyles() // ".ns-abc123 { color: red; }"
+ */
+declare class StyleCollector {
+    private styles;
+    /**
+     * Compiles a style object and registers it in the collector.
+     * Returns the same class name for identical style objects (deduplication).
+     *
+     * @param styleObj - Raw style object from a `css({})` call.
+     * @returns Scoped class name string.
+     */
+    addStyle(styleObj: any): string;
+    /**
+     * Registers a global style rule (no scoped class).
+     * Subsequent calls with the same selector are ignored (idempotent).
+     *
+     * @param selector - CSS selector string, e.g. `"body"` or `"h1, h2"`.
+     * @param styleObj - Style properties to apply to the selector.
+     */
+    addGlobalStyle(selector: string, styleObj: any): void;
+    private compileStyle;
+    private parseStyles;
+    private buildDeclarations;
+    /**
+     * Serialises all collected styles into a single CSS string.
+     *
+     * Output order:
+     * 1. `@keyframes` blocks
+     * 2. Base class rules
+     * 3. Pseudo-class/element rules
+     * 4. `@layer` blocks
+     * 5. `@supports` blocks
+     * 6. Media queries (ascending `min-width`, mobile-first)
+     *
+     * @returns Full CSS string ready to be injected or written to a file.
+     */
+    getAllStyles(): string;
+    private extractMinWidth;
+    /**
+     * Writes all collected styles to a temp file so the PostCSS plugin
+     * (which runs in a separate process) can read them.
+     *
+     * Call this after all `css()` / `global()` calls have been evaluated,
+     * e.g. at the end of a build-time entry point.
+     *
+     * @param filePath - Destination file path. Defaults to `os.tmpdir()/next-style.css`.
+     */
+    flush(filePath?: string): void;
+    /**
+     * Returns the default cache file path, resolved at call-time from
+     * `process.cwd()` so it reflects the actual working directory of the
+     * running process rather than the directory at module-load time.
+     */
+    static defaultCacheFile(): string;
+    /**
+     * Returns a snapshot of the internal style map.
+     * Intended for inspection and testing — not for direct mutation.
+     */
+    getStyleMap(): Map<string, CompiledStyle>;
+}
+/**
+ * Creates an isolated `StyleCollector` paired with a transform helper.
+ *
+ * Primarily used by SWC/Babel transforms and test harnesses that need
+ * a fresh collector per file or per test, independent of the shared
+ * runtime instance.
+ *
+ * @example
+ * const { collector, transformCssCall } = createTransformer()
+ * const className = transformCssCall({ color: 'red' })
+ * const css = collector.getAllStyles()
+ */
+declare function createTransformer(): {
+    collector: StyleCollector;
+    /**
+     * Equivalent to calling `css()` against this transformer's isolated collector.
+     * @param styleObj - Raw style object.
+     * @returns Scoped class name string.
+     */
+    transformCssCall(styleObj: any): string;
+};
+
+/**
+ * CSS properties with full type safety and autocomplete via csstype.
+ * Accepts both string and number values (e.g. `fontSize: 16` or `fontSize: '16px'`).
+ */
 type CSSProperties = Properties<string | number>;
+/** @internal Mapped type for pseudo-classes/elements — avoids index signature limitation */
 type PseudoStyles = {
     [P in Pseudos]?: CSSProperties;
 };
+/** @internal At-rule keys (@media, @container, @supports, @layer, @keyframes) */
 type AtRuleStyles = {
     '@sm'?: CSSProperties;
     '@md'?: CSSProperties;
@@ -28,33 +145,119 @@ type AtRuleStyles = {
  * - Feature queries: `'@supports (display: grid)'`
  * - Keyframe animations: `'@keyframes fadeIn'`
  * - Cascade layers: `'@layer utilities'`
+ *
+ * @example
+ * const style: CSSObject = {
+ *   fontSize: '16px',
+ *   '@md': { fontSize: '20px' },
+ *   ':hover': { color: 'blue' },
+ *   '@keyframes spin': { to: { transform: 'rotate(360deg)' } },
+ * }
  */
 type CSSObject = CSSProperties & PseudoStyles & AtRuleStyles & {
     [key: string]: any;
 };
 /**
  * Converts a style object into a unique CSS class name.
+ *
  * Styles are collected at build time by the PostCSS plugin and emitted as
  * a single static CSS file — there is zero runtime overhead in production.
+ * Identical style objects always return the same class name (deduplication).
+ *
+ * @param styles - A `CSSObject` describing the styles for this element.
+ * @returns A stable class name string (e.g. `"ns-1x2y3z"`).
  *
  * @example
  * const button = css({
  *   padding: '8px 16px',
+ *   borderRadius: '6px',
  *   backgroundColor: '#7F77DD',
  *   ':hover': { backgroundColor: '#534AB7' },
  *   '@md': { padding: '10px 20px' },
  * })
+ *
+ * export function Button() {
+ *   return <button className={button}>Click me</button>
+ * }
  */
 declare function css(styles: CSSObject): string;
 /**
  * Registers global CSS styles applied directly to selectors (no scoped class).
  *
+ * Useful for CSS resets, base typography, and third-party element overrides.
+ * Like `css()`, styles are extracted at build time — no runtime cost.
+ *
+ * @param styles - A record mapping CSS selectors to `CSSObject` style definitions.
+ *
  * @example
  * global({
  *   '*': { boxSizing: 'border-box', margin: '0' },
  *   'body': { fontFamily: 'Inter, sans-serif', lineHeight: '1.6' },
+ *   'h1, h2, h3': { fontWeight: 500 },
  * })
  */
 declare function global(styles: Record<string, CSSObject>): void;
 
-export { type CSSObject, css, global };
+declare const collector: StyleCollector;
+
+/**
+ * Converts a camelCase CSS property name to kebab-case.
+ *
+ * @param str - camelCase string, e.g. `"backgroundColor"`.
+ * @returns kebab-case string, e.g. `"background-color"`.
+ *
+ * @example
+ * camelToKebab('fontSize')        // "font-size"
+ * camelToKebab('borderTopWidth')  // "border-top-width"
+ */
+declare function camelToKebab(str: string): string;
+/**
+ * Generates a short, stable hash string from a style object or string.
+ * Used to produce unique class name suffixes (e.g. `"ns-1x2y3z"`).
+ *
+ * @param styles - Style object or pre-serialised string.
+ * @returns Base-36 hash string.
+ */
+declare function generateClassHash(styles: any): string;
+/**
+ * Shorthand breakpoint aliases mapped to their full `@media` query strings.
+ *
+ * | Key    | Expands to                          |
+ * |--------|-------------------------------------|
+ * | `@sm`  | `@media (min-width: 640px)`  |
+ * | `@md`  | `@media (min-width: 768px)`  |
+ * | `@lg`  | `@media (min-width: 1024px)` |
+ * | `@xl`  | `@media (min-width: 1280px)` |
+ * | `@2xl` | `@media (min-width: 1536px)` |
+ */
+declare const BREAKPOINTS: Record<string, string>;
+/**
+ * Resolves a breakpoint shorthand to its full `@media` query string.
+ * Passes through unrecognised strings unchanged.
+ *
+ * @param query - Shorthand key (e.g. `"@md"`) or an arbitrary media query.
+ * @returns Full media query string (e.g. `"@media (min-width: 768px)"`).
+ *
+ * @example
+ * normalizeMediaQuery('@md')                        // "@media (min-width: 768px)"
+ * normalizeMediaQuery('@media (max-width: 600px)')  // "@media (max-width: 600px)"
+ */
+declare function normalizeMediaQuery(query: string): string;
+/**
+ * Returns `true` if the value is a valid CSS property value that can be
+ * serialised to a declaration (string, number, or nested object).
+ *
+ * @param _key - CSS property name (unused, reserved for future validation).
+ * @param value - Value to check.
+ */
+declare function validateCSSProperty(_key: string, value: any): boolean;
+/**
+ * Removes duplicate entries from a style map, keeping the first occurrence.
+ * Two entries are considered duplicates when their serialised values are identical.
+ *
+ * @param styles - Map of class name → style data.
+ * @returns New map with duplicates removed.
+ */
+declare function deduplicateStyles(styles: Map<string, any>): Map<string, any>;
+
+export { BREAKPOINTS, type CSSObject, type CSSProperties, type CompiledStyle, StyleCollector, camelToKebab, createTransformer, css, deduplicateStyles, generateClassHash, global, normalizeMediaQuery, collector as styleCollector, validateCSSProperty };

package/dist/index.js

@@ -1,31 +1,31 @@
-var b=(n=>typeof require<"u"?require:typeof Proxy<"u"?new Proxy(n,{get:(e,s)=>(typeof require<"u"?require:e)[s]}):n)(function(n){if(typeof require<"u")return require.apply(this,arguments);throw Error('Dynamic require of "'+n+'" is not supported')});function E(n){return n.replace(/[A-Z]/g,e=>`-${e.toLowerCase()}`)}function C(n){let e=typeof n=="string"?n:JSON.stringify(n),s=2166136261;for(let r=0;r<e.length;r++)s^=e.charCodeAt(r),s=s*16777619>>>0;return s.toString(36)}var R={"@sm":"@media (min-width: 640px)","@md":"@media (min-width: 768px)","@lg":"@media (min-width: 1024px)","@xl":"@media (min-width: 1280px)","@2xl":"@media (min-width: 1536px)"};function w(n){return R[n]??n}var u=class n{constructor(){this.styles=new Map}addStyle(e){let r=`ns-${C(e)}`;if(this.styles.has(r))return r;let t=this.compileStyle(e);return this.styles.set(r,t),r}addGlobalStyle(e,s){let r=`global:${e}`;if(this.styles.has(r))return;let t=this.buildDeclarations(s);t&&this.styles.set(r,{className:r,css:`${e} {
-${t}}`,mediaQueries:{},pseudoClasses:{},keyframes:"",supports:{},layers:{}})}compileStyle(e){let{mediaQueries:s,pseudoClasses:r,normalStyles:t,keyframes:l,supports:y,container:f,layer:g}=this.parseStyles(e),o=`ns-${C(e)}`,$=this.buildDeclarations(t),A=`.${o} {
-${$}}`,p={};Object.entries(s).forEach(([c,d])=>{let a=w(c),m=this.buildDeclarations(d,"    ");if(p[a]){let D=p[a].split(`
+import A from"fs";import D from"path";function P(n){return n.replace(/[A-Z]/g,e=>`-${e.toLowerCase()}`)}function b(n){let e=typeof n=="string"?n:JSON.stringify(n),t=0;for(let r=0;r<e.length;r++){let s=e.charCodeAt(r);t=(t<<5)-t+s,t=t&t}return Math.abs(t).toString(36)}var C={"@sm":"@media (min-width: 640px)","@md":"@media (min-width: 768px)","@lg":"@media (min-width: 1024px)","@xl":"@media (min-width: 1280px)","@2xl":"@media (min-width: 1536px)"};function O(n){return C[n]??n}function W(n,e){return typeof e=="string"||typeof e=="number"||typeof e=="object"&&!Array.isArray(e)}function T(n){let e=new Map,t=new Set;return n.forEach((r,s)=>{let l=JSON.stringify(r);t.has(l)||(t.add(l),e.set(s,r))}),e}var y=class n{constructor(){this.styles=new Map}addStyle(e){let r=`ns-${b(e)}`;if(this.styles.has(r))return r;let s=this.compileStyle(e);return this.styles.set(r,s),r}addGlobalStyle(e,t){let r=`global:${e}`;if(this.styles.has(r))return;let s=this.buildDeclarations(t);s&&this.styles.set(r,{className:r,css:`${e} {
+${s}}`,mediaQueries:{},pseudoClasses:{},keyframes:"",supports:{},layers:{}})}compileStyle(e){let{mediaQueries:t,pseudoClasses:r,normalStyles:s,keyframes:l,supports:m,container:f,layer:h}=this.parseStyles(e),o=`ns-${b(e)}`,$=this.buildDeclarations(s),N=`.${o} {
+${$}}`,p={};Object.entries(t).forEach(([c,d])=>{let a=O(c),S=this.buildDeclarations(d,"    ");if(p[a]){let Q=p[a].split(`
 `).slice(2,-2).join(`
 `);p[a]=`${a} {
   .${o} {
-${D}
-${m}  }
+${Q}
+${S}  }
 }`}else p[a]=`${a} {
   .${o} {
-${m}  }
+${S}  }
 }`}),Object.entries(f).forEach(([c,d])=>{let a=this.buildDeclarations(d,"    ");p[c]=`${c} {
   .${o} {
 ${a}  }
-}`});let x={};Object.entries(r).forEach(([c,d])=>{let a=this.buildDeclarations(d);x[c]=`.${o}${c} {
-${a}}`});let h="";Object.entries(l).forEach(([c,d])=>{h+=`@keyframes ${c} {
-`,Object.entries(d).forEach(([a,m])=>{let O=this.buildDeclarations(m,"    ");h+=`  ${a} {
-${O}  }
-`}),h+=`}
-`});let P={};Object.entries(y).forEach(([c,d])=>{let a=this.buildDeclarations(d,"    ");P[c]=`@supports ${c} {
+}`});let j={};Object.entries(r).forEach(([c,d])=>{let a=this.buildDeclarations(d);j[c]=`.${o}${c} {
+${a}}`});let u="";Object.entries(l).forEach(([c,d])=>{u+=`@keyframes ${c} {
+`,Object.entries(d).forEach(([a,S])=>{let M=this.buildDeclarations(S,"    ");u+=`  ${a} {
+${M}  }
+`}),u+=`}
+`});let E={};Object.entries(m).forEach(([c,d])=>{let a=this.buildDeclarations(d,"    ");E[c]=`@supports ${c} {
   .${o} {
 ${a}  }
-}`});let j={};return Object.entries(g).forEach(([c,d])=>{let a=this.buildDeclarations(d,"  ");j[c]=`@layer ${c} {
-${a}}`}),{className:o,css:A,mediaQueries:p,pseudoClasses:x,keyframes:h,supports:P,layers:j}}parseStyles(e){let s={},r={},t={},l={},y={},f={},g={};return Object.entries(e).forEach(([i,o])=>{if(i.startsWith("@keyframes "))l[i.slice(11)]=o;else if(i==="@keyframes"&&typeof o=="object")Object.assign(l,o);else if(i.startsWith("@supports")){let $=i.slice(0,9)==="@supports"?i.slice(9).trim():i;y[$]=o}else i.startsWith("@container")?f[i]=o:i.startsWith("@layer")?g[i.slice(7)||"default"]=o:i in R||i.startsWith("@media")?r[i]=o:i.startsWith(":")||i.startsWith("::")?t[i]=o:s[i]=o}),{normalStyles:s,mediaQueries:r,pseudoClasses:t,keyframes:l,supports:y,container:f,layer:g}}buildDeclarations(e,s="  "){let r="";return Object.entries(e).forEach(([t,l])=>{(typeof l=="string"||typeof l=="number")&&(r+=`${s}${E(t)}: ${l};
-`)}),r}getAllStyles(){let e="";return this.styles.forEach(s=>{s.keyframes&&(e+=`${s.keyframes}
-`),s.css&&(e+=`${s.css}
-`),Object.values(s.pseudoClasses).forEach(t=>{e+=`${t}
-`}),Object.values(s.layers).forEach(t=>{e+=`${t}
-`}),Object.values(s.supports).forEach(t=>{e+=`${t}
-`}),Object.entries(s.mediaQueries).sort(([t],[l])=>this.extractMinWidth(t)-this.extractMinWidth(l)).forEach(([,t])=>{e+=`${t}
-`})}),e}extractMinWidth(e){let s=e.match(/min-width:\s*(\d+)px/);return s?parseInt(s[1],10):0}flush(e){if(!(typeof window<"u"))try{let s=b("fs"),r=b("path"),t=e??n.defaultCacheFile();s.mkdirSync(r.dirname(t),{recursive:!0}),s.writeFileSync(t,this.getAllStyles(),"utf-8")}catch(s){console.error("[next-style] Failed to flush styles to cache file:",s)}}static defaultCacheFile(){return b("path").join(process.cwd(),"node_modules",".cache","next-style","styles.css")}getStyleMap(){return new Map(this.styles)}};function W(n){let e=S.addStyle(n);return typeof window>"u"&&S.flush(),e}function M(n){Object.entries(n).forEach(([e,s])=>{S.addGlobalStyle(e,s)}),typeof window>"u"&&S.flush()}var S=new u;export{W as css,M as global};
+}`});let w={};return Object.entries(h).forEach(([c,d])=>{let a=this.buildDeclarations(d,"  ");w[c]=`@layer ${c} {
+${a}}`}),{className:o,css:N,mediaQueries:p,pseudoClasses:j,keyframes:u,supports:E,layers:w}}parseStyles(e){let t={},r={},s={},l={},m={},f={},h={};return Object.entries(e).forEach(([i,o])=>{if(i.startsWith("@keyframes "))l[i.slice(11)]=o;else if(i==="@keyframes"&&typeof o=="object")Object.assign(l,o);else if(i.startsWith("@supports")){let $=i.slice(0,9)==="@supports"?i.slice(9).trim():i;m[$]=o}else i.startsWith("@container")?f[i]=o:i.startsWith("@layer")?h[i.slice(7)||"default"]=o:i in C||i.startsWith("@media")?r[i]=o:i.startsWith(":")||i.startsWith("::")?s[i]=o:t[i]=o}),{normalStyles:t,mediaQueries:r,pseudoClasses:s,keyframes:l,supports:m,container:f,layer:h}}buildDeclarations(e,t="  "){let r="";return Object.entries(e).forEach(([s,l])=>{(typeof l=="string"||typeof l=="number")&&(r+=`${t}${P(s)}: ${l};
+`)}),r}getAllStyles(){let e="";return this.styles.forEach(t=>{t.keyframes&&(e+=`${t.keyframes}
+`),t.css&&(e+=`${t.css}
+`),Object.values(t.pseudoClasses).forEach(s=>{e+=`${s}
+`}),Object.values(t.layers).forEach(s=>{e+=`${s}
+`}),Object.values(t.supports).forEach(s=>{e+=`${s}
+`}),Object.entries(t.mediaQueries).sort(([s],[l])=>this.extractMinWidth(s)-this.extractMinWidth(l)).forEach(([,s])=>{e+=`${s}
+`})}),e}extractMinWidth(e){let t=e.match(/min-width:\s*(\d+)px/);return t?parseInt(t[1],10):0}flush(e){try{let t=e??n.defaultCacheFile();A.mkdirSync(D.dirname(t),{recursive:!0}),A.writeFileSync(t,this.getAllStyles(),"utf-8")}catch(t){console.error("Failed to flush styles to cache file:",t)}}static defaultCacheFile(){return D.join(process.cwd(),"node_modules",".cache","next-style","styles.css")}getStyleMap(){return new Map(this.styles)}};function K(){let n=new y;return{collector:n,transformCssCall(e){return n.addStyle(e)}}}function z(n){let e=g.addStyle(n);return g.flush(),e}function F(n){Object.entries(n).forEach(([e,t])=>{g.addGlobalStyle(e,t)}),g.flush()}var g=new y;export{C as BREAKPOINTS,y as StyleCollector,P as camelToKebab,K as createTransformer,z as css,T as deduplicateStyles,b as generateClassHash,F as global,O as normalizeMediaQuery,g as styleCollector,W as validateCSSProperty};