mintcss 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nexryai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,98 @@
-# Temporary Holding Version
+# mintcss
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Small, dependency-free CSS-in-JS for browser applications.
+
+## Install
+
+```sh
+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`.
+
+## Usage
+
+```ts
+import { css, globalCss, keyframes } from "mintcss";
+
+globalCss({
+    ":root": { "--accent": "#f4bd36" },
+    body: { margin: 0, fontFamily: "system-ui, sans-serif" },
+});
+
+const fade = keyframes({
+    from: { opacity: 0 },
+    to: { opacity: 1 },
+});
+
+const button = css({
+    backgroundColor: "var(--accent)",
+    borderRadius: 8,
+    padding: "8px 16px",
+    animation: `${fade} 150ms ease-out`,
+    "&:hover": { opacity: 0.8 },
+    "& > svg": { width: 16 },
+    "@media (width >= 40rem)": { padding: "12px 24px" },
+    "@supports (display: grid)": { display: "grid" },
+});
+
+document.querySelector("button")?.classList.add(button);
+```
+
+In React, pass the result to `className`:
+
+```tsx
+import { css } from "mintcss";
+
+const button = css({ backgroundColor: "#f4bd36", borderRadius: 8 });
+
+export function Button() {
+    return <button className={button}>Hello</button>;
+}
+```
+
+## API
+
+- `css(styles: CSSObject): string` inserts rules and returns a deterministic
+  `mint-…` class name. Object key order does not change that name.
+- `keyframes(frames: Record<string, CSSDeclarations>): string` inserts an
+  animation and returns its `mint-kf-…` name. Steps are `from`, `to`, or integer
+  percentages from `0%` through `100%`, emitted in numeric order.
+- `globalCss(rules: Record<string, CSSObject>): void` inserts global selector
+  rules. Top-level `@media` and `@supports` blocks contain selector objects.
+- Types `CSSObject`, `CSSDeclarations`, and `CSSValue` are exported. Properties
+  accept strings, numbers, and `undefined`; nested objects represent selectors
+  or supported conditional rules. These types do not validate property names
+  against a complete CSS specification.
+
+Properties use camelCase (`backgroundColor`, `WebkitAppearance`, `msOverflowStyle`)
+except CSS custom properties (`--accent`). Nonzero numeric values receive `px`
+unless they are custom properties or supported unitless properties, such as
+`opacity`, `lineHeight`, `fontWeight`, `flexGrow`, or `zIndex`. Zero stays `0`.
+Use strings for other units and numeric values that must remain unitless.
+`undefined` declarations are omitted.
+
+Nested selectors must include `&`, which is replaced by the parent selector.
+Only `@media` and `@supports` conditional rules are supported; use `keyframes`
+for animations. Declarations and nested keys are emitted in sorted order, so
+avoid mixing shorthand and longhand declarations that depend on insertion order.
+
+Rules are appended to a shared `<style data-mintcss>` element. Its DOM registry
+avoids duplicate insertion, including across module reloads. Global rules keep
+selector insertion order so their cascade is preserved. Generated identifiers
+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.
+
+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.

package/dist/core.d.ts

@@ -0,0 +1,9 @@
+export type CSSValue = string | number;
+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;
+export declare const __resetCssForTests: () => void;

package/dist/core.js

@@ -0,0 +1,158 @@
+const STYLE_ATTRIBUTE = "data-mintcss";
+let styleElement;
+const unitlessProperties = new Set([
+    "animationIterationCount",
+    "aspectRatio",
+    "columnCount",
+    "flex",
+    "flexGrow",
+    "flexShrink",
+    "fontWeight",
+    "gridArea",
+    "gridColumn",
+    "gridColumnEnd",
+    "gridColumnStart",
+    "gridRow",
+    "gridRowEnd",
+    "gridRowStart",
+    "lineHeight",
+    "opacity",
+    "order",
+    "orphans",
+    "scale",
+    "tabSize",
+    "widows",
+    "zIndex",
+    "zoom",
+]);
+const hyphenate = (property) => {
+    if (property.startsWith("--"))
+        return property;
+    return property.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`).replace(/^ms-/, "-ms-");
+};
+const assertSafe = (value, kind) => {
+    if (/[;{}]/.test(value) || /<\/style|\/\*|javascript:|expression\s*\(/i.test(value))
+        throw new Error(`Unsafe CSS ${kind}`);
+};
+const assertConditionalRule = (rule) => {
+    if (!/^@(media|supports)\s+[^;{}]+$/.test(rule))
+        throw new Error(`Invalid CSS at-rule: ${rule}`);
+    assertSafe(rule, "at-rule");
+};
+const declaration = (property, value) => {
+    if (!/^(--[a-zA-Z0-9_-]+|[a-zA-Z][a-zA-Z0-9]*)$/.test(property))
+        throw new Error(`Invalid CSS property: ${property}`);
+    const serialized = typeof value === "number" && value !== 0 && !property.startsWith("--") && !unitlessProperties.has(property) ? `${value}px` : String(value);
+    if (typeof value === "number" && !Number.isFinite(value))
+        throw new Error(`Invalid CSS number: ${value}`);
+    assertSafe(serialized, "value");
+    return `${hyphenate(property)}:${serialized};`;
+};
+const serializeRule = (selector, object) => {
+    let declarations = "";
+    let nested = "";
+    for (const key of Object.keys(object).sort()) {
+        const value = object[key];
+        if (value === undefined)
+            continue;
+        if (value === null)
+            throw new Error(`Invalid CSS object: ${key}`);
+        if (typeof value !== "object") {
+            declarations += declaration(key, value);
+            continue;
+        }
+        if (key.startsWith("@media") || key.startsWith("@supports")) {
+            assertConditionalRule(key);
+            nested += `${key}{${serializeRule(selector, value)}}`;
+            continue;
+        }
+        if (!key.includes("&"))
+            throw new Error(`Nested selector must contain &: ${key}`);
+        assertSafe(key, "selector");
+        nested += serializeRule(key.replaceAll("&", selector), value);
+    }
+    return `${declarations ? `${selector}{${declarations}}` : ""}${nested}`;
+};
+const canonicalize = (object) => Object.keys(object)
+    .sort()
+    .map((key) => {
+    const value = object[key];
+    return `${JSON.stringify(key)}:${typeof value === "object" && value !== null ? `{${canonicalize(value)}}` : JSON.stringify(value)}`;
+})
+    .join(",");
+const hash = (value) => {
+    let result = 2166136261;
+    for (let index = 0; index < value.length; index += 1) {
+        result ^= value.charCodeAt(index);
+        result = Math.imul(result, 16777619);
+    }
+    return (result >>> 0).toString(36);
+};
+const registry = () => {
+    if (typeof document === "undefined")
+        throw new Error("mintcss requires a browser document");
+    if (styleElement?.isConnected && styleElement.ownerDocument === document)
+        return styleElement;
+    const existing = document.head.querySelector(`style[${STYLE_ATTRIBUTE}]`);
+    styleElement = existing ?? document.createElement("style");
+    if (!existing) {
+        styleElement.setAttribute(STYLE_ATTRIBUTE, "");
+        document.head.append(styleElement);
+    }
+    return styleElement;
+};
+const insert = (id, rule) => {
+    const target = registry();
+    // The DOM is authoritative across module reloads and stylesheet replacement.
+    const registeredInDOM = new Set((target.dataset.mintcss ?? "").split(" ").filter(Boolean));
+    if (registeredInDOM.has(id))
+        return;
+    registeredInDOM.add(id);
+    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);
+};
+export const __resetCssForTests = () => {
+    document.head.querySelector(`style[${STYLE_ATTRIBUTE}]`)?.remove();
+    styleElement = undefined;
+};

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/testing.d.ts

@@ -0,0 +1 @@
+export { __resetCssForTests } from "#core";

package/dist/testing.js

@@ -0,0 +1 @@
+export { __resetCssForTests } from "#core";

package/package.json

@@ -1,6 +1,58 @@
 {
-  "name": "mintcss",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "name": "mintcss",
+    "version": "0.1.1",
+    "description": "Small, dependency-free CSS-in-JS for browser applications.",
+    "type": "module",
+    "license": "MIT",
+    "author": "nexryai",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/nexryai/mintcss.git"
+    },
+    "homepage": "https://github.com/nexryai/mintcss#readme",
+    "bugs": {
+        "url": "https://github.com/nexryai/mintcss/issues"
+    },
+    "keywords": ["css", "css-in-js", "styles", "typescript", "browser"],
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js"
+        },
+        "./testing": {
+            "types": "./dist/testing.d.ts",
+            "import": "./dist/testing.js"
+        },
+        "./package.json": "./package.json"
+    },
+    "files": ["dist", "README.md", "LICENSE"],
+    "sideEffects": false,
+    "publishConfig": {
+        "access": "public",
+        "registry": "https://registry.npmjs.org/"
+    },
+    "scripts": {
+        "build": "tsc -p tsconfig.json",
+        "check": "tsc -p tsconfig.check.json",
+        "lint": "biome check .",
+        "format": "biome check --write .",
+        "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"
+    },
+    "devDependencies": {
+        "@biomejs/biome": "2.5.11",
+        "@types/node": "^24.13.3",
+        "jsdom": "30.1.2",
+        "typescript": "~6.0.2",
+        "vitest": "^4.1.11"
+    },
+    "imports": {
+        "#core": "./dist/core.js",
+        "#mintcss": "./dist/index.js",
+        "#testing": "./dist/testing.js"
+    }
+}