mintcss 0.1.0 → 0.2.0

package/README.md

@@ -1,8 +1,6 @@
 # mintcss
 
-Small, dependency-free CSS-in-JS for browser applications. Extracted from
-[Salvia](https://github.com/nexryai/rosmarinus/tree/main/salvia), with no React
-runtime or type dependency. MIT licensed.
+Small, dependency-free CSS-in-JS with optional Next.js App Router integration.
 
 ## Install
 
@@ -12,7 +10,8 @@ npm install mintcss
 
 mintcss is an ESM package with bundled TypeScript declarations. It targets modern
 browsers with `String.replaceAll` support. Importing it does not touch the DOM;
-calling its styling functions requires a browser `document` with a `head`.
+the top-level styling functions require a browser `document` with a `head`.
+For server rendering, use `createStyleRegistry` or the Next.js integration below.
 
 ## Usage
 
@@ -55,6 +54,96 @@ export function Button() {
 }
 ```
 
+## Next.js App Router
+
+The optional `mintcss/next` entry point supports Next.js 14–16 with React 18.2 or
+19. React and Next.js are optional peer dependencies; the core entry point does
+not import either framework.
+
+Wrap the app in `MintStyleRegistry` in your root layout. The layout can remain a
+Server Component:
+
+```tsx
+// app/layout.tsx
+import type { ReactNode } from "react";
+import { MintStyleRegistry } from "mintcss/next";
+
+export default function RootLayout({ children }: { children: ReactNode }) {
+    return (
+        <html lang="en">
+            <body>
+                <MintStyleRegistry>{children}</MintStyleRegistry>
+            </body>
+        </html>
+    );
+}
+```
+
+In Client Components, obtain the styling functions from `useMintcss` and call
+them during rendering:
+
+```tsx
+// app/button.tsx
+"use client";
+
+import { useMintcss } from "mintcss/next";
+
+export function Button() {
+    const { css, globalCss, keyframes } = useMintcss();
+    globalCss({ body: { margin: 0 } });
+    const fade = keyframes({ from: { opacity: 0 }, to: { opacity: 1 } });
+    const button = css({
+        backgroundColor: "#f4bd36",
+        borderRadius: 8,
+        animation: `${fade} 150ms ease-out`,
+        "&:hover": { opacity: 0.8 },
+    });
+    return <button type="button" className={button}>Hello</button>;
+}
+```
+
+The registry collects CSS separately for each server render and uses Next.js's
+[`useServerInsertedHTML`](https://nextjs.org/docs/app/guides/css-in-js) integration
+to emit new rules as content streams. The browser reuses those rules during
+hydration and inserts new rules for subsequent renders and navigation. The same
+styles produce the same identifiers on the server and client.
+
+Use the hook inside Client Components under the registry. Module-level calls to
+the browser-only `css`, `globalCss`, or `keyframes` exports still require a DOM,
+even in files with `"use client"`, because Next.js also renders Client Components
+on the server. Style objects can be declared at module scope, then passed to the
+hook's functions during rendering. Server Components cannot use `useMintcss`.
+The automatic integration targets the App Router; Pages Router applications
+need their own SSR collection using the API below.
+
+For a nonce-based CSP, pass the request's nonce as
+`<MintStyleRegistry nonce={nonce}>`. It is applied to server-generated style tags
+and new browser style tags. Configure the corresponding CSP in your app.
+
+## Server rendering
+
+`createStyleRegistry({ nonce? })` provides `css`, `globalCss`, and `keyframes`
+without requiring a DOM. Create a separate registry for every server render and
+use its functions throughout that render; do not share a mutable registry
+between requests.
+
+```ts
+import { createStyleRegistry } from "mintcss";
+
+const registry = createStyleRegistry();
+const button = registry.css({ color: "red" });
+const styles = registry.getStyles();
+// styles: { ids: string[], css: string }
+// Render a <style data-mintcss={styles.ids.join(" ")}> containing styles.css
+// in the document head alongside the HTML using button as its class name.
+```
+
+`getStyles()` returns all collected rules in insertion order. `flush()` returns
+only the rules collected since the previous flush, retaining deduplication for
+later streaming chunks. Include `data-mintcss` with the emitted identifiers so
+browser calls can reuse the SSR styles. In the browser, registry styling calls
+also insert rules into the document head.
+
 ## API
 
 - `css(styles: CSSObject): string` inserts rules and returns a deterministic
@@ -88,60 +177,12 @@ are implementation details and should not be persisted or hard-coded.
 
 ## Limits
 
-This is a browser runtime library: there is no SSR stylesheet collection,
-hydration API, build-time extraction, automatic vendor prefixing, or CSP nonce
-configuration. Styles accumulate for the lifetime of the document; prefer
-reusing stable style objects and CSS variables for continuously changing values.
-Strict CSP deployments must permit the generated inline stylesheet.
+There is no build-time extraction or automatic vendor prefixing. Styles accumulate
+for the lifetime of the document; prefer reusing stable style objects and CSS
+variables for continuously changing values. Strict CSP deployments must permit
+the generated inline stylesheet, for example with the registry nonce option.
 
 The serializer rejects malformed properties and rules, non-finite numeric
 values, and certain injection-like strings. It is **not an untrusted-input
 sanitizer**: pass application-authored styles and validate external data before
 using it, particularly URLs. It does not enforce an external URL policy.
-
-## Tests
-
-Tests with a DOM environment can reset the shared stylesheet between cases:
-
-```ts
-import { afterEach } from "vitest";
-import { __resetCssForTests } from "mintcss/testing";
-
-afterEach(__resetCssForTests);
-```
-
-This helper removes all mintcss rules in the current document. Use it only in tests.
-
-## Development and publishing
-
-Use Node.js 22.12 or later:
-
-```sh
-npm ci
-npm run lint
-npm run check
-npm test
-npm run test:package
-```
-
-`test:package` builds a real npm tarball, installs it into a temporary consumer,
-and checks its ESM exports, TypeScript declarations, and shipped files without
-React. CI runs these checks on Node.js 22 and 24. The Biome configuration and
-version are copied from Salvia; package-internal `#` imports keep the same rule
-against relative imports.
-
-For the first release, verify the package name is still available and sign in
-to an npm account authorized to publish it:
-
-```sh
-npm view mintcss
-npm login
-npm publish --dry-run
-npm publish
-```
-
-The initial version is `0.1.0`. `prepack` builds `dist`; `prepublishOnly` runs the
-checks before publishing. Only compiled JavaScript, declarations, README,
-LICENSE, and package metadata are shipped. Later releases must increment the
-version before publishing. Publishing is manual; a successful CI run does not
-publish a release.

package/dist/core.d.ts

@@ -3,7 +3,24 @@ export type CSSObject = {
     [key: string]: CSSValue | CSSObject | undefined;
 };
 export type CSSDeclarations = Record<string, CSSValue | undefined>;
-export declare const css: (object: CSSObject) => string;
-export declare const keyframes: (frames: Record<string, CSSDeclarations>) => string;
-export declare const globalCss: (rules: Record<string, CSSObject>) => void;
+declare const createStyleApi: (insert: (id: string, rule: string) => void) => {
+    css: (object: CSSObject) => string;
+    keyframes: (frames: Record<string, CSSDeclarations>) => string;
+    globalCss: (rules: Record<string, CSSObject>) => void;
+};
+export declare const css: (object: CSSObject) => string, keyframes: (frames: Record<string, CSSDeclarations>) => string, globalCss: (rules: Record<string, CSSObject>) => void;
+export type StyleSnapshot = {
+    ids: string[];
+    css: string;
+};
+export type StyleApi = ReturnType<typeof createStyleApi>;
+export type StyleRegistry = StyleApi & {
+    getStyles: () => StyleSnapshot;
+    flush: () => StyleSnapshot;
+};
+/** Create a registry per server render. Browser calls also insert into the DOM. */
+export declare const createStyleRegistry: (options?: {
+    nonce?: string;
+}) => StyleRegistry;
 export declare const __resetCssForTests: () => void;
+export {};

package/dist/core.js

@@ -49,6 +49,7 @@ const declaration = (property, value) => {
     return `${hyphenate(property)}:${serialized};`;
 };
 const serializeRule = (selector, object) => {
+    assertSafe(selector, "selector");
     let declarations = "";
     let nested = "";
     for (const key of Object.keys(object).sort()) {
@@ -88,7 +89,7 @@ const hash = (value) => {
     }
     return (result >>> 0).toString(36);
 };
-const registry = () => {
+const registry = (nonce) => {
     if (typeof document === "undefined")
         throw new Error("mintcss requires a browser document");
     if (styleElement?.isConnected && styleElement.ownerDocument === document)
@@ -97,12 +98,21 @@ const registry = () => {
     styleElement = existing ?? document.createElement("style");
     if (!existing) {
         styleElement.setAttribute(STYLE_ATTRIBUTE, "");
+        if (nonce !== undefined)
+            styleElement.nonce = nonce;
         document.head.append(styleElement);
     }
     return styleElement;
 };
-const insert = (id, rule) => {
-    const target = registry();
+const insert = (id, rule, nonce) => {
+    if (typeof document === "undefined")
+        throw new Error("mintcss requires a browser document; use createStyleRegistry for SSR or useMintcss in Next.js");
+    // Streaming SSR can emit several style elements. Consult all of them.
+    for (const element of document.head.querySelectorAll(`style[${STYLE_ATTRIBUTE}]`)) {
+        if ((element.dataset.mintcss ?? "").split(" ").includes(id))
+            return;
+    }
+    const target = registry(nonce);
     // The DOM is authoritative across module reloads and stylesheet replacement.
     const registeredInDOM = new Set((target.dataset.mintcss ?? "").split(" ").filter(Boolean));
     if (registeredInDOM.has(id))
@@ -111,46 +121,75 @@ const insert = (id, rule) => {
     target.dataset.mintcss = [...registeredInDOM].join(" ");
     target.append(document.createTextNode(rule));
 };
-export const css = (object) => {
-    const id = `mint-${hash(canonicalize(object))}`;
-    insert(id, serializeRule(`.${id}`, object));
-    return id;
-};
-export const keyframes = (frames) => {
-    const object = frames;
-    const name = `mint-kf-${hash(canonicalize(object))}`;
-    const body = Object.entries(object)
-        .sort(([left], [right]) => {
-        const position = (step) => (step === "from" ? 0 : step === "to" ? 100 : Number.parseInt(step, 10));
-        return position(left) - position(right);
-    })
-        .map(([step, properties]) => {
-        if (!/^(from|to|(?:\d|[1-9]\d|100)%)$/.test(step))
-            throw new Error(`Invalid keyframe step: ${step}`);
-        return serializeRule(step, properties);
-    })
-        .join("");
-    insert(name, `@keyframes ${name}{${body}}`);
-    return name;
-};
-export const globalCss = (rules) => {
-    const output = Object.entries(rules)
-        .map(([selector, object]) => {
-        if (selector.startsWith("@media") || selector.startsWith("@supports")) {
-            assertConditionalRule(selector);
-            return `${selector}{${Object.entries(object)
-                .map(([nestedSelector, nestedObject]) => {
-                assertSafe(nestedSelector, "selector");
-                return serializeRule(nestedSelector, nestedObject);
-            })
-                .join("")}}`;
-        }
-        assertSafe(selector, "selector");
-        return serializeRule(selector, object);
-    })
-        .join("");
-    const id = `mint-global-${hash(output)}`;
-    insert(id, output);
+const createStyleApi = (insert) => ({
+    css: (object) => {
+        const id = `mint-${hash(canonicalize(object))}`;
+        insert(id, serializeRule(`.${id}`, object));
+        return id;
+    },
+    keyframes: (frames) => {
+        const object = frames;
+        const name = `mint-kf-${hash(canonicalize(object))}`;
+        const body = Object.entries(object)
+            .sort(([left], [right]) => {
+            const position = (step) => (step === "from" ? 0 : step === "to" ? 100 : Number.parseInt(step, 10));
+            return position(left) - position(right);
+        })
+            .map(([step, properties]) => {
+            if (!/^(from|to|(?:\d|[1-9]\d|100)%)$/.test(step))
+                throw new Error(`Invalid keyframe step: ${step}`);
+            return serializeRule(step, properties);
+        })
+            .join("");
+        insert(name, `@keyframes ${name}{${body}}`);
+        return name;
+    },
+    globalCss: (rules) => {
+        const output = Object.entries(rules)
+            .map(([selector, object]) => {
+            if (selector.startsWith("@media") || selector.startsWith("@supports")) {
+                assertConditionalRule(selector);
+                return `${selector}{${Object.entries(object)
+                    .map(([nestedSelector, nestedObject]) => {
+                    assertSafe(nestedSelector, "selector");
+                    return serializeRule(nestedSelector, nestedObject);
+                })
+                    .join("")}}`;
+            }
+            assertSafe(selector, "selector");
+            return serializeRule(selector, object);
+        })
+            .join("");
+        const id = `mint-global-${hash(output)}`;
+        insert(id, output);
+    },
+});
+export const { css, keyframes, globalCss } = createStyleApi(insert);
+/** Create a registry per server render. Browser calls also insert into the DOM. */
+export const createStyleRegistry = (options = {}) => {
+    const rules = new Map();
+    const pending = new Map();
+    const snapshot = (entries) => ({
+        ids: [...entries.keys()],
+        // Rules are validated by the serializer, including closing style tags.
+        css: [...entries.values()].join(""),
+    });
+    return {
+        ...createStyleApi((id, rule) => {
+            if (typeof document !== "undefined")
+                insert(id, rule, options.nonce);
+            if (rules.has(id))
+                return;
+            rules.set(id, rule);
+            pending.set(id, rule);
+        }),
+        getStyles: () => snapshot(rules),
+        flush: () => {
+            const styles = snapshot(pending);
+            pending.clear();
+            return styles;
+        },
+    };
 };
 export const __resetCssForTests = () => {
     document.head.querySelector(`style[${STYLE_ATTRIBUTE}]`)?.remove();

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export type { CSSDeclarations, CSSObject, CSSValue } from "#core";
-export { css, globalCss, keyframes } from "#core";
+export type { CSSDeclarations, CSSObject, CSSValue, StyleApi, StyleRegistry, StyleSnapshot } from "#core";
+export { createStyleRegistry, css, globalCss, keyframes } from "#core";

package/dist/index.js

@@ -1 +1 @@
-export { css, globalCss, keyframes } from "#core";
+export { createStyleRegistry, css, globalCss, keyframes } from "#core";

package/dist/next.d.ts

@@ -0,0 +1,10 @@
+import { type ReactNode } from "react";
+import { type StyleApi, type StyleRegistry } from "#core";
+export type MintStyleRegistryProps = {
+    children?: ReactNode;
+    nonce?: string;
+};
+/** Collect styles for each server render and flush them before streamed content. */
+export declare function MintStyleRegistry({ children, nonce }: MintStyleRegistryProps): import("react").FunctionComponentElement<import("react").ProviderProps<StyleRegistry | null>>;
+/** Use inside a Client Component wrapped in MintStyleRegistry. */
+export declare function useMintcss(): StyleApi;

package/dist/next.js

@@ -0,0 +1,27 @@
+"use client";
+import { useServerInsertedHTML } from "next/navigation.js";
+import { createContext, createElement, useContext, useState } from "react";
+import { createStyleRegistry } from "#core";
+const MintContext = createContext(null);
+/** Collect styles for each server render and flush them before streamed content. */
+export function MintStyleRegistry({ children, nonce }) {
+    const [registry] = useState(() => createStyleRegistry({ nonce }));
+    useServerInsertedHTML(() => {
+        const styles = registry.flush();
+        if (!styles.ids.length)
+            return null;
+        return createElement("style", {
+            "data-mintcss": styles.ids.join(" "),
+            nonce,
+            dangerouslySetInnerHTML: { __html: styles.css },
+        });
+    });
+    return createElement(MintContext.Provider, { value: registry }, children);
+}
+/** Use inside a Client Component wrapped in MintStyleRegistry. */
+export function useMintcss() {
+    const registry = useContext(MintContext);
+    if (!registry)
+        throw new Error("useMintcss must be used inside MintStyleRegistry");
+    return registry;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "mintcss",
-    "version": "0.1.0",
-    "description": "Small, dependency-free CSS-in-JS for browser applications, extracted from Salvia.",
+    "version": "0.2.0",
+    "description": "Small, dependency-free CSS-in-JS styling library for React.",
     "type": "module",
     "license": "MIT",
     "author": "nexryai",
@@ -25,7 +25,11 @@
             "types": "./dist/testing.d.ts",
             "import": "./dist/testing.js"
         },
-        "./package.json": "./package.json"
+        "./package.json": "./package.json",
+        "./next": {
+            "types": "./dist/next.d.ts",
+            "import": "./dist/next.js"
+        }
     },
     "files": ["dist", "README.md", "LICENSE"],
     "sideEffects": false,
@@ -41,18 +45,37 @@
         "test": "vitest run",
         "test:package": "node scripts/test-package.mjs",
         "prepack": "npm run build",
-        "prepublishOnly": "npm run lint && npm run check && npm test && npm run test:package"
+        "prepublishOnly": "npm run lint && npm run check && npm test && npm run test:package && npm run test:next",
+        "test:next": "node scripts/test-next.mjs"
     },
     "devDependencies": {
         "@biomejs/biome": "2.5.11",
         "@types/node": "^24.13.3",
+        "@types/react": "^19.3.0",
+        "@types/react-dom": "^19.3.0",
         "jsdom": "30.1.2",
+        "next": "^16.4.0",
+        "react": "^19.3.0",
+        "react-dom": "^19.3.0",
         "typescript": "~6.0.2",
         "vitest": "^4.1.11"
     },
     "imports": {
         "#core": "./dist/core.js",
         "#mintcss": "./dist/index.js",
-        "#testing": "./dist/testing.js"
+        "#testing": "./dist/testing.js",
+        "#next": "./dist/next.js"
+    },
+    "peerDependencies": {
+        "next": "^14.0.0 || ^15.0.0 || ^16.0.0",
+        "react": "^18.2.0 || ^19.0.0"
+    },
+    "peerDependenciesMeta": {
+        "next": {
+            "optional": true
+        },
+        "react": {
+            "optional": true
+        }
     }
 }