@cssints/gradient 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexei Accio
+
+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,94 @@
-# Temporary Holding Version
+# @cssints/gradient
 
-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.
+Eased gradients for [cssints](../../README.md): a gradient from one colour to another along an easing curve, expanded into
+colour stops at build time, so the fade has no hard edge where a two-stop gradient shows one. It is one value member of
+`cssints/plugin` `scope()` and returns an `<image>`, so it goes where an image goes (`backgroundImage`, `maskImage`,
+`borderImageSource`). No runtime.
+
+```ts
+import { backgroundImage, createTokens } from "cssints" with { type: "cssints" };
+import { gradient } from "@cssints/gradient" with { type: "cssints" };
+
+const t = createTokens({ color: { $type: "color", ink: { $value: "#111111" } } });
+
+// gradient(kind, direction, from, to, easing?, stops?)
+export const fade = backgroundImage(
+  gradient("linear", "to bottom", "#000", "transparent", "ease-in-out", 5),
+);
+export const glow = backgroundImage(
+  gradient("radial", "circle at top", "red", "blue", "cubic-bezier(0.5, 0, 0.5, 1)", 4),
+);
+export const ink = backgroundImage(
+  gradient("linear", "to right", t.color.ink, "white", "ease-in", 4),
+);
+```
+
+```css
+._4we9ve {
+  background-image: linear-gradient(
+    to bottom,
+    #000,
+    #000000d7 27.44%,
+    #00000080 50%,
+    #00000028 72.56%,
+    transparent
+  );
+}
+._ba8wye {
+  background-image: radial-gradient(circle at top, red, #c44a6f 37.04%, #5348d0 62.96%, blue);
+}
+._1l9gl59 {
+  background-image: linear-gradient(
+    to right,
+    var(--color-ink),
+    color-mix(in oklab, var(--color-ink), white 25.93%) 44.59%,
+    color-mix(in oklab, var(--color-ink), white 74.07%) 83.41%,
+    white
+  );
+}
+```
+
+## Rules
+
+- **Arguments**, each its own string: `kind` is `linear`, `radial` or `conic`; `direction` is that function's first
+  argument, required (`"to bottom"`, `"45deg"`, `"circle at top"`, `"at center"`, `"from 90deg"`); `from` and `to` are
+  colours or colour tokens; `easing` is `linear`, `ease`, `ease-in`, `ease-out`, `ease-in-out` (the default) or
+  `cubic-bezier(x1, y1, x2, y2)`; `stops` is 2 to 64 (13 by default). They are checked in the types and again at build
+  time, against one grammar.
+- **Stops** are placed as postcss-easing-gradients places them: the curve's parameter `t` is sampled evenly, `x(t)` is the
+  position of a stop and `y(t)` the share of `to` in it. A curve that overshoots (`y` outside 0 to 1) is clamped to the two
+  colours.
+- **Colours** are mixed in oklab with premultiplied alpha, as CSS mixes them, so `transparent` fades the other colour's hue
+  and does not grey it. The endpoints are printed as written; the stops between them are sRGB hex (`#rrggbbaa` when not
+  opaque). Positions and shares have two decimals at most, so the output is the same on every build.
+- **Tokens and `currentColor`.** A token arrives as `var(--name)` and `currentColor` is the element's: neither can be read at
+  build time. When an endpoint cannot be, every stop is `color-mix(in oklab, from, to N%)` at the same positions, and the
+  browser mixes them. `color-mix()` needs Chrome 111, Safari 16.2, Firefox 113: for older targets the build warns, as it
+  does for any value.
+- **Errors**, at the call: a part outside the grammar (`gradient: unexpected "steps(4" in "linear to bottom red blue
+steps(4)", expected linear | <cubic-bezier-easing-function> | <integer> | end of value`), arguments in the wrong order
+  (`cssints: gradient(): "blue" is not an easing (the arguments are kind, direction, from, to, easing?, stops?)`), and a
+  gradient where an image does not go (`css.color(gradient(…))`, an error in the types and at build time).
+
+## Limits
+
+- A stop between two literal colours is clamped to sRGB: a wide-gamut endpoint (`color(display-p3 …)`, a vivid `oklch()`)
+  keeps its own value at the end, but the colours between are the nearest sRGB ones. Give it as a token to keep the gamut:
+  the stops are then `color-mix()`.
+- `steps()` and `linear()` easings are not taken, nor an easing token (there is no easing token type), nor a number token
+  for `stops`; a `repeating-*` gradient, more than two colours and a colour interpolation method (`in oklch`) are not
+  either.
+- The parts are joined with a space for the grammar (see "Functions" in the API reference), so `"to", "bottom"` as two
+  arguments passes the grammar and is caught only by the argument check; write the direction as one string.
+
+```bash
+cd packages/gradient && bun run test        # the stop math, fixtures through the engine (output, errors)
+cd packages/gradient && bun run typecheck   # and the type test, test/types/gradient.ts
+```
+
+## Credits
+
+The stops follow [postcss-easing-gradients](https://github.com/larsenwork/postcss-easing-gradients) and
+[easing-coordinates](https://github.com/larsenwork/easing-coordinates) (MIT, Andreas Larsen): the easing curve sampled
+into colour stops. The code is written here; no code is copied. Colours are mixed with [culori](https://culorijs.org)
+(MIT, Dan Burzo), a dependency.

package/dist/index.d.mts

@@ -0,0 +1,20 @@
+import { CSSImageValue } from "cssints";
+//#region src/index.d.ts
+declare const eased: import("cssints/plugin").Scope<"gradient", {
+  readonly linear: "linear [ <angle> | to <side-or-corner> ]";
+  readonly radial: "radial [ [ <radial-shape> || <radial-size> ] [ at <position> ]? | at <position> ]";
+  readonly conic: "conic [ from <angle> [ at <position> ]? | at <position> ]";
+  readonly ends: "<color> <color> [ linear | <cubic-bezier-easing-function> ]? <integer [2,64]>?";
+  readonly gradient: {
+    readonly args: "[ <linear> | <radial> | <conic> ] <ends>";
+    readonly value: ([kind, direction, from, to, easing, stops]: string[]) => CSSImageValue;
+  };
+}>;
+/**
+ * `gradient(kind, direction, from, to, easing?, stops?)`: a `linear`, `radial` or `conic` gradient from one colour to
+ * another along an easing (`ease-in-out` by default; `linear`, `ease*` or `cubic-bezier()`), as `stops` colour stops (13 by
+ * default, 2 to 64). The direction is the gradient's own (`"to bottom"`, `"45deg"`, `"circle at top"`, `"from 90deg"`). The
+ * stops are computed at build time in oklab; a token or `currentColor` endpoint gives `color-mix()` stops instead. An `<image>`.
+ */
+export declare const gradient: ReturnType<typeof eased.export>["gradient"];
+//#endregion

package/dist/index.mjs

@@ -0,0 +1,96 @@
+import { CSSImageValue } from "cssints";
+import { scope } from "cssints/plugin";
+import { formatHex, formatHex8, interpolateWithPremultipliedAlpha, parse } from "culori";
+//#region src/stops.ts
+const NAMED = /* @__PURE__ */ new Map([
+	["linear", [
+		0,
+		0,
+		1,
+		1
+	]],
+	["ease", [
+		.25,
+		.1,
+		.25,
+		1
+	]],
+	["ease-in", [
+		.42,
+		0,
+		1,
+		1
+	]],
+	["ease-out", [
+		0,
+		0,
+		.58,
+		1
+	]],
+	["ease-in-out", [
+		.42,
+		0,
+		.58,
+		1
+	]]
+]);
+const curve = (easing) => {
+	const named = NAMED.get(easing);
+	if (named) return named;
+	const n = /^cubic-bezier\((.*)\)$/.exec(easing)?.[1]?.split(",").map(Number);
+	if (n?.length === 4 && n.every(Number.isFinite)) return n;
+	throw new Error(`cssints: gradient(): "${easing}" is not an easing (the arguments are kind, direction, from, to, easing?, stops?)`);
+};
+const bezier = (t, p1, p2) => 3 * (1 - t) ** 2 * t * p1 + 3 * (1 - t) * t ** 2 * p2 + t ** 3;
+/**
+* A share or a position as CSS text, two decimals at most (the build output is the same on every machine).
+* @param {number} n a percentage
+* @returns {string} its text
+*/
+const fixed = (n) => String(+n.toFixed(2));
+/**
+* The curve's parameter sampled evenly, as postcss-easing-gradients does.
+* @param {string} easing `linear`, `ease`, `ease-in`, `ease-out`, `ease-in-out` or `cubic-bezier(x1, y1, x2, y2)`
+* @param {number} stops the number of colour stops, both ends included
+* @returns {{ x: number, y: number }[]} per stop `x`, its position, and `y`, the share of the second colour (clamped to 0..1), both 0..1
+*/
+const samples = (easing, stops) => {
+	const [x1, y1, x2, y2] = curve(easing);
+	return Array.from({ length: stops }, (_, i) => {
+		const t = i / (stops - 1);
+		return {
+			x: bezier(t, x1, x2),
+			y: Math.min(1, Math.max(0, bezier(t, y1, y2)))
+		};
+	});
+};
+/**
+* `gradient(kind, direction, from, to, easing?, stops?)`: a `linear`, `radial` or `conic` gradient from one colour to
+* another along an easing (`ease-in-out` by default; `linear`, `ease*` or `cubic-bezier()`), as `stops` colour stops (13 by
+* default, 2 to 64). The direction is the gradient's own (`"to bottom"`, `"45deg"`, `"circle at top"`, `"from 90deg"`). The
+* stops are computed at build time in oklab; a token or `currentColor` endpoint gives `color-mix()` stops instead. An `<image>`.
+*/
+const gradient = scope("gradient", {
+	linear: "linear [ <angle> | to <side-or-corner> ]",
+	radial: "radial [ [ <radial-shape> || <radial-size> ] [ at <position> ]? | at <position> ]",
+	conic: "conic [ from <angle> [ at <position> ]? | at <position> ]",
+	ends: "<color> <color> [ linear | <cubic-bezier-easing-function> ]? <integer [2,64]>?",
+	gradient: {
+		args: "[ <linear> | <radial> | <conic> ] <ends>",
+		value: ([kind, direction, from = "", to = "", easing = "ease-in-out", stops = "13"]) => {
+			const points = samples(easing, Number(stops));
+			const a = parse(from);
+			const b = parse(to);
+			const mix = a && b ? interpolateWithPremultipliedAlpha([a, b], "oklab") : void 0;
+			const color = (y) => {
+				if (!mix) return `color-mix(in oklab, ${from}, ${to} ${fixed(y * 100)}%)`;
+				const c = mix(y);
+				return c.alpha === void 0 || c.alpha >= 1 ? formatHex(c) : formatHex8(c);
+			};
+			const list = points.map(({ x, y }, i) => i === 0 ? from : i === points.length - 1 ? to : `${color(y)} ${fixed(x * 100)}%`);
+			return new CSSImageValue(`${kind}-gradient(${direction}, ${list.join(", ")})`);
+		}
+	}
+}).export().gradient;
+//#endregion
+export { gradient };

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "@cssints/gradient",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Eased gradients for cssints: an easing curve expanded into colour stops (mixed in oklab) at build time",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alexeiaccio/css-in-ts-compiler.git",
+    "directory": "packages/gradient"
+  },
+  "homepage": "https://cssints.dev",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "dependencies": {
+    "culori": "^4.0.2"
+  },
+  "peerDependencies": {
+    "cssints": "^0.2.0"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}