Add new CSS value creation functions and corresponding tests

Author: etienne-dldc

README.md

@@ -111,6 +111,61 @@ serialize(pow(2, 3)); // "pow(2,3)"
 serialize(pow("var(--base)", "2")); // "pow(var(--base),2)"
 ```
 
+#### `var(name, fallback?)`
+
+Creates a `var()` expression for CSS custom properties.
+
+```typescript
+import { add, var as cssVar } from "@dldc/css-builder";
+
+serialize(cssVar("--space")); // "var(--space)"
+serialize(cssVar("--gutter", add("8px", 2))); // "var(--gutter,8px + 2)"
+```
+
+#### `number(value)`
+
+Creates a numeric calc value.
+
+```typescript
+serialize(number(42)); // "42"
+serialize(number("3.14")); // "3.14"
+```
+
+#### `dimension(value, unit)`
+
+Creates a dimension calc value.
+
+```typescript
+serialize(dimension(10, "px")); // "10px"
+serialize(dimension("1.5", "rem")); // "1.5rem"
+```
+
+#### `percentage(value)`
+
+Creates a percentage calc value.
+
+```typescript
+serialize(percentage(50)); // "50%"
+serialize(percentage("12.5")); // "12.5%"
+```
+
+#### `raw(value)`
+
+Creates a raw calc value (no parsing).
+
+```typescript
+serialize(raw("var(--size)")); // "var(--size)"
+```
+
+#### `group(value)`
+
+Wraps a value or sum in parentheses, useful for preserving precedence in
+composed expressions.
+
+```typescript
+serialize(group(value("10px"))); // "(10px)"
+```
+
 #### `round(...)`
 
 Creates a `round()` expression. You can pass a rounding strategy as the first

src/builder.ts

@@ -404,3 +404,64 @@ export function value(value: string | number): Ast.CalcValue {
   }
   return create.calcValue.dimension(numberPart, unit);
 }
+
+/**
+ * Creates a CSS var() function expression.
+ * @param name - The custom property name (for example, '--spacing')
+ * @param fallback - Optional fallback value if the custom property is not defined
+ * @returns A Var AST node representing var(name[, fallback])
+ */
+function variable(name: string, fallback?: AnyExpression): Ast.Var {
+  return create.calcValue.var(
+    name,
+    fallback ? anyExprToCalcSum(fallback) : undefined,
+  );
+}
+
+export { variable as var };
+
+/**
+ * Creates a numeric CalcValue node.
+ * @param value - A number or numeric string
+ * @returns A CalcValue number node
+ */
+export function number(value: number | string): Ast.CalcValue {
+  return create.calcValue.number(value);
+}
+
+/**
+ * Creates a dimension CalcValue node.
+ * @param value - A number or numeric string
+ * @param unit - The dimension unit (for example, 'px', 'rem', 'vw')
+ * @returns A CalcValue dimension node
+ */
+export function dimension(value: number | string, unit: string): Ast.CalcValue {
+  return create.calcValue.dimension(value, unit);
+}
+
+/**
+ * Creates a percentage CalcValue node.
+ * @param value - A number or numeric string
+ * @returns A CalcValue percentage node
+ */
+export function percentage(value: number | string): Ast.CalcValue {
+  return create.calcValue.percentage(value);
+}
+
+/**
+ * Creates a raw/unprocessed CalcValue node.
+ * @param value - Raw CSS text to embed directly
+ * @returns A raw CalcValue node
+ */
+export function raw(value: string): Ast.CalcValue {
+  return create.calcValue.raw(value);
+}
+
+/**
+ * Groups a CalcSum in parentheses to preserve precedence.
+ * @param value - The CalcSum to group
+ * @returns A grouped CalcValue node
+ */
+export function group(value: Ast.CalcSum): Ast.CalcValue {
+  return create.calcValue.group(value);
+}

src/create.ts

@@ -238,7 +238,7 @@ export type CalcValueCreators = {
   /** Creates a raw/unprocessed CalcValue */
   raw(value: string): Ast.CalcValue;
   /** Creates a var() custom property CalcValue */
-  var(name: string, fallback?: Ast.CalcSum): Ast.CalcValue;
+  var(name: string, fallback?: Ast.CalcSum): Ast.Var;
 };
 
 /**
@@ -295,7 +295,7 @@ export const calcValue: CalcValueCreators = {
     };
   },
   /** @param name The custom property name (e.g., '--my-var') @param fallback Optional fallback value */
-  var(name: string, fallback?: Ast.CalcSum): Ast.CalcValue {
+  var(name: string, fallback?: Ast.CalcSum): Ast.Var {
     return {
       kind: "var",
       value: [

tests/builder.test.ts

@@ -428,3 +428,70 @@ Deno.test("value", async (t) => {
     expect(serialize(builder.value("var(--size)"))).toBe("var(--size)");
   });
 });
+
+Deno.test("var", async (t) => {
+  await t.step("creates var without fallback", () => {
+    const result = builder.var("--space");
+    expect(serialize(result)).toBe("var(--space)");
+  });
+
+  await t.step("creates var with primitive fallback", () => {
+    const result = builder.var("--gutter", "10px");
+    expect(serialize(result)).toBe("var(--gutter,10px)");
+  });
+
+  await t.step("creates var with calc fallback", () => {
+    const result = builder.var("--size", builder.add("8px", 2));
+    expect(serialize(result)).toBe("var(--size,8px + 2)");
+  });
+});
+
+Deno.test("number", async (t) => {
+  await t.step("creates number from numeric value", () => {
+    expect(serialize(builder.number(42))).toBe("42");
+  });
+
+  await t.step("creates number from string value", () => {
+    expect(serialize(builder.number("3.14"))).toBe("3.14");
+  });
+});
+
+Deno.test("dimension", async (t) => {
+  await t.step("creates dimension from numeric value", () => {
+    expect(serialize(builder.dimension(10, "px"))).toBe("10px");
+  });
+
+  await t.step("creates dimension from string value", () => {
+    expect(serialize(builder.dimension("1.5", "rem"))).toBe("1.5rem");
+  });
+});
+
+Deno.test("percentage", async (t) => {
+  await t.step("creates percentage from numeric value", () => {
+    expect(serialize(builder.percentage(50))).toBe("50%");
+  });
+
+  await t.step("creates percentage from string value", () => {
+    expect(serialize(builder.percentage("12.5"))).toBe("12.5%");
+  });
+});
+
+Deno.test("raw", async (t) => {
+  await t.step("creates raw value", () => {
+    expect(serialize(builder.raw("var(--size)"))).toBe("var(--size)");
+  });
+});
+
+Deno.test("group", async (t) => {
+  await t.step("groups a value", () => {
+    expect(serialize(builder.group(builder.value("10px")))).toBe("(10px)");
+  });
+
+  await t.step("groups a calc sum", () => {
+    const sum = create.calcSum(builder.value("10px"), [
+      "+",
+      builder.value("5px"),
+    ]);
+    expect(serialize(builder.group(sum))).toBe("(10px + 5px)");
+  });
+});