@cssints/fluid 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,69 @@
-# Temporary Holding Version
+# @cssints/fluid
 
-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.
+Fluid lengths for [cssints](../../README.md): `fluid(min, max)` is a length that is `min` on a narrow viewport, `max` on a
+wide one, and grows linearly between. The `clamp()` is computed at build time, and a range that breaks text resizing
+(WCAG 1.4.4) fails the build. Two value members of `cssints/plugin` `scope()` (`fn({ args, value })`, positional
+arguments and an options object). No runtime.
+
+```ts
+import { fontSize, padding } from "cssints" with { type: "cssints" };
+import { fluid } from "@cssints/fluid" with { type: "cssints" };
+
+// fluid(min, max, { from?, to?, zoom? }): from and to are the widths, 20rem and 80rem when left out
+export const title = fontSize(fluid("1rem", "1.5rem"));
+export const lead = fontSize(fluid("16px", "24px", { from: "40rem", to: "90rem" }));
+// against the inline size of the nearest container instead of the viewport
+export const card = padding(fluid.container("1rem", "2rem", { to: "60rem" }));
+
+export const hero = fontSize(fluid("1rem", "4rem")); // build error: fails WCAG 1.4.4
+```
+
+```css
+._bkcdcr {
+  font-size: clamp(1rem, 0.8333vw + 0.8333rem, 1.5rem);
+}
+._1wkr2lu {
+  font-size: clamp(16px, 1vw + 0.6rem, 24px);
+}
+._ekb8uj {
+  padding: clamp(1rem, 2.5cqi + 0.5rem, 2rem);
+}
+```
+
+## Rules
+
+- **The math.** The slope is `(max - min) / (to - from)` and the intercept `min - slope × from`, written
+  `clamp(min, <slope × 100>vw + <intercept>rem, max)`, rounded to 4 decimals. The intercept is in rem, so the value follows
+  the user's font size. A `max` below `min` makes a value that shrinks: the bounds are sorted for `clamp()` and the slope is
+  negative.
+- **Units.** `min`, `max`, `from` and `to` are px or rem, at 16px to the rem; the bounds keep the unit you wrote. Other
+  units (`em`, `vw`, `%`, `calc()`, tokens) cannot be computed at build time: the build rejects them (the types check a
+  non-negative `<length>`, and a grammar cannot name units).
+- **WCAG 1.4.4.** The check of [fluid-tailwind](https://github.com/barvian/fluid-tailwind): at 500% zoom the viewport is a
+  fifth as wide and the rem five times larger, and the value must still reach twice its size at 100%, or text cannot be
+  resized to 200%. It is checked at every width (at the four kinks of the two curves), and a failure is a build error at
+  the call that names the width: `cssints: fluid: 1rem to 4rem between 20rem and 80rem fails WCAG 1.4.4: at 80rem wide,
+500% zoom gives 5rem, under twice 4rem; narrow the range of sizes or widen the widths`. A ratio of `max` to `min` up to
+  about 2.5 passes with the default widths.
+- **A length.** The result is a Typed OM length (`CSSStyleValue<"length">`): it goes where a length goes, in the types,
+  and `color(fluid(...))` is an error. It can be an argument of `clamp()`, `min()` and `max()` of cssints.
+- **Build errors** (at the call): a unit that is not px or rem, `min` equal to `max`, `from` not below `to`, a failed
+  1.4.4 check, and the grammar of the arguments, by position (`fluid.container(2): unexpected "red" in "red", expected
+<length>`).
+
+## Limits
+
+- The 1.4.4 check runs on every call unless `{ zoom: false }` is passed, which is for lengths that are not text (a
+  padding, a gap): `padding(fluid("1rem", "4rem", { zoom: false }))`.
+- `fluid.container()` uses the same check with the container's width in place of the viewport's, which holds when the
+  container scales with the viewport.
+- No defaults from a token set, and no token as an argument: a token is a `var()`, which the build cannot compute with.
+
+```bash
+cd packages/fluid && bun run test   # fixtures through the engine (output, errors), and the type test via bun run typecheck
+```
+
+## Credits
+
+The WCAG 1.4.4 check follows [fluid-tailwind](https://github.com/barvian/fluid-tailwind) (MIT, Maxwell Barvian).
+The check is written here; no code is copied.

package/dist/index.d.mts

@@ -0,0 +1,40 @@
+import { CSSStyleValue } from "cssints";
+//#region src/index.d.ts
+/** What `fluid()` gives: a length, for any property that takes one. */
+export type Fluid = CSSStyleValue<"length">;
+declare class Clamp extends CSSStyleValue<"length"> {
+  readonly text: string;
+  constructor(text: string);
+  toString(): string;
+}
+declare const fluidScope: import("cssints/plugin").Scope<"fluid", {
+  readonly fluid: {
+    args: readonly ["<length [0,∞]>", "<length [0,∞]>", {
+      readonly "from?": "<length [0,∞]>";
+      readonly "to?": "<length [0,∞]>";
+      readonly "zoom?": import("cssints/plugin").Typed<boolean>;
+    }];
+    label?: undefined;
+    value(args: never): Clamp;
+  };
+  readonly fluidContainer: {
+    args: readonly ["<length [0,∞]>", "<length [0,∞]>", {
+      readonly "from?": "<length [0,∞]>";
+      readonly "to?": "<length [0,∞]>";
+      readonly "zoom?": import("cssints/plugin").Typed<boolean>;
+    }];
+    label?: "fluid.container" | undefined;
+    value(args: never): Clamp;
+  };
+}>;
+type Members = ReturnType<typeof fluidScope.export>;
+/**
+ * `fluid(min, max, { from?, to?, zoom? })`: a length that is `min` at the viewport width `from` (20rem), `max` at `to`
+ * (80rem), and grows linearly between, computed at build time into `clamp(min, <slope>vw + <intercept>rem, max)`. Lengths
+ * in px or rem. A range that fails WCAG 1.4.4 (500% zoom cannot reach twice the size) is a build error at the call, unless
+ * `zoom: false`. `fluid.container(...)` is the same against the width of the nearest container (`cqi`).
+ */
+export declare const fluid: Members["fluid"] & {
+  container: Members["fluidContainer"];
+};
+//#endregion

package/dist/index.mjs

@@ -0,0 +1,71 @@
+import { CSSStyleValue } from "cssints";
+import { arg, fn, scope } from "cssints/plugin";
+//#region src/index.ts
+var Clamp = class extends CSSStyleValue {
+	text;
+	constructor(text) {
+		super();
+		this.text = text;
+	}
+	toString() {
+		return this.text;
+	}
+};
+const rem = (label, text) => {
+	const m = /^(\d*\.?\d+)(px|rem)$/.exec(text);
+	if (!m) throw new Error(`cssints: ${label}: ${text} is not in px or rem: the slope is computed at build time`);
+	return m[2] === "px" ? Number(m[1]) / 16 : Number(m[1]);
+};
+const num = (n) => String(Number(n.toFixed(4)) + 0);
+const compute = (label, unit) => ([min, max, { from = "20rem", to = "80rem", zoom = true }]) => {
+	const [lo = 0, hi = 0, a = 0, b = 0] = [
+		min,
+		max,
+		from,
+		to
+	].map((t) => rem(label, t));
+	if (lo === hi) throw new Error(`cssints: ${label}: ${min} and ${max} are the same size: use the length itself`);
+	if (a >= b) throw new Error(`cssints: ${label}: from ${from} must be below to ${to}`);
+	const slope = (hi - lo) / (b - a);
+	const intercept = lo - slope * a;
+	const [low, high] = lo < hi ? [min, max] : [max, min];
+	const at = (w) => Math.min(Math.max(intercept + slope * w, Math.min(lo, hi)), Math.max(lo, hi));
+	const fails = zoom ? [
+		a,
+		b,
+		5 * a,
+		5 * b
+	].find((w) => 5 * at(w / 5) < 2 * at(w) - 1e-9) : void 0;
+	if (fails !== void 0) throw new Error(`cssints: ${label}: ${min} to ${max} between ${from} and ${to} fails WCAG 1.4.4: at ${num(fails)}rem wide, 500% zoom gives ${num(5 * at(fails / 5))}rem, under twice ${num(at(fails))}rem; narrow the range of sizes or widen the widths`);
+	const sign = intercept < 0 ? "-" : "+";
+	return new Clamp(`clamp(${low}, ${num(slope * 100)}${unit} ${sign} ${num(Math.abs(intercept))}rem, ${high})`);
+};
+const args = [
+	"<length [0,∞]>",
+	"<length [0,∞]>",
+	{
+		"from?": "<length [0,∞]>",
+		"to?": "<length [0,∞]>",
+		"zoom?": arg()
+	}
+];
+const members = scope("fluid", {
+	fluid: fn({
+		args,
+		value: compute("fluid", "vw")
+	}),
+	fluidContainer: fn({
+		args,
+		label: "fluid.container",
+		value: compute("fluid.container", "cqi")
+	})
+}).export();
+/**
+* `fluid(min, max, { from?, to?, zoom? })`: a length that is `min` at the viewport width `from` (20rem), `max` at `to`
+* (80rem), and grows linearly between, computed at build time into `clamp(min, <slope>vw + <intercept>rem, max)`. Lengths
+* in px or rem. A range that fails WCAG 1.4.4 (500% zoom cannot reach twice the size) is a build error at the call, unless
+* `zoom: false`. `fluid.container(...)` is the same against the width of the nearest container (`cqi`).
+*/
+const fluid = Object.assign(members.fluid, { container: members.fluidContainer });
+//#endregion
+export { fluid };

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "@cssints/fluid",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "fluid() for cssints: clamp() between two widths, computed at build time, with the WCAG 1.4.4 zoom check",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alexeiaccio/css-in-ts-compiler.git",
+    "directory": "packages/fluid"
+  },
+  "homepage": "https://cssints.dev",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "peerDependencies": {
+    "cssints": "^0.2.0"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}