@multiplatform.one/theme 6.0.0

package/src/theme/resolveKnobs.spec.ts

@@ -0,0 +1,571 @@
+import { describe, expect, it } from "vitest";
+import { defaultKnobs, emptyStateKnobs, Space, Size } from "./knobs";
+import type { Knobs } from "./knobs";
+import type { KnobProps } from "./recipes";
+import { resolveKnobs } from "./resolveKnobs";
+import {
+  normalizeToHex,
+  relativeLuminance,
+  contrastRatio,
+  findReadableStep,
+  semanticGroups,
+} from "./colorRules";
+
+function knobsWith(overrides: Partial<Knobs>): Knobs {
+  return { ...defaultKnobs, ...overrides };
+}
+
+const expectedKnobPropKeys: (keyof KnobProps)[] = [
+  "borderRadius",
+  "borderRadiusOuter",
+  "elevation",
+  "surface",
+  "inputSurface",
+  "panelPadding",
+  "gap",
+  "gapLg",
+  "sizeToken",
+  "heading",
+  "body",
+  "textWeight",
+  "transition",
+  "outlined",
+  "pointy",
+  "textAccent",
+  "textAccentColor",
+  "inputBackground",
+  "space",
+  "size",
+];
+
+// ── colorRules unit tests ────────────────────────────────────
+
+describe("colorRules", () => {
+  describe("luminance utilities", () => {
+    it("normalizeToHex handles hex, short hex, hsl, and named colors", () => {
+      expect(normalizeToHex("#626262")).toBe("#626262");
+      expect(normalizeToHex("#fff")).toBe("#ffffff");
+      expect(normalizeToHex("white")).toBe("#ffffff");
+      expect(normalizeToHex("black")).toBe("#000000");
+      expect(normalizeToHex("hsl(0, 0%, 50%)")).toBe("#808080");
+    });
+
+    it("contrastRatio of black vs white ≈ 21", () => {
+      const lBlack = relativeLuminance("#000000");
+      const lWhite = relativeLuminance("#ffffff");
+      expect(contrastRatio(lBlack, lWhite)).toBeCloseTo(21, 0);
+    });
+
+    it("findReadableStep picks a step meeting MIN_CONTRAST_RATIO", () => {
+      const grayDark = [
+        "#050505",
+        "#151515",
+        "#191919",
+        "#232323",
+        "#282828",
+        "#323232",
+        "#424242",
+        "#494949",
+        "#545454",
+        "#626262",
+        "#a5a5a5",
+        "#ffffff",
+      ];
+      const bg = relativeLuminance(grayDark[9]);
+      const fg = relativeLuminance(grayDark[5]);
+      expect(contrastRatio(bg, fg)).toBeLessThan(3);
+
+      const readable = findReadableStep(grayDark, 10, 6, -1);
+      const readableLum = relativeLuminance(grayDark[readable - 1]);
+      expect(contrastRatio(bg, readableLum)).toBeGreaterThanOrEqual(3);
+    });
+  });
+
+  describe("semantic groups", () => {
+    it("covers all 12 steps without gaps", () => {
+      const covered = new Set<number>();
+      for (const g of semanticGroups) {
+        for (let s = g.from; s <= g.to; s++) {
+          covered.add(s);
+        }
+      }
+      for (let i = 1; i <= 12; i++) {
+        expect(covered.has(i)).toBe(true);
+      }
+    });
+  });
+});
+
+// ── resolveKnobs tests ───────────────────────────────────────
+
+describe("resolveKnobs", () => {
+  it("produces all knobProps keys from defaultKnobs", () => {
+    const { knobProps } = resolveKnobs(defaultKnobs);
+    for (const key of expectedKnobPropKeys) {
+      expect(knobProps).toHaveProperty(key);
+    }
+  });
+
+  it("is deterministic (same input → same output)", () => {
+    const a = resolveKnobs(defaultKnobs);
+    const b = resolveKnobs(defaultKnobs);
+    expect(a).toEqual(b);
+  });
+
+  it("matches snapshot for defaultKnobs", () => {
+    const resolved = resolveKnobs(defaultKnobs);
+    expect(resolved).toMatchSnapshot();
+  });
+
+  // ── T1.1g — expectedKnobPropKeys includes "size" ────────
+  it('expectedKnobPropKeys includes "size"', () => {
+    expect(expectedKnobPropKeys).toContain("size");
+  });
+
+  // ── borderRadius ──────────────────────────────────────────
+
+  describe("borderRadius knob", () => {
+    it('maps "none" → "$0"', () => {
+      const { knobProps } = resolveKnobs(knobsWith({ borderRadius: "none" }));
+      expect(knobProps.borderRadius.borderRadius).toBe("$0");
+    });
+
+    it('maps "small" → "$2"', () => {
+      const { knobProps } = resolveKnobs(knobsWith({ borderRadius: "small" }));
+      expect(knobProps.borderRadius.borderRadius).toBe("$2");
+    });
+
+    it('maps "medium" → "$4"', () => {
+      const { knobProps } = resolveKnobs(knobsWith({ borderRadius: "medium" }));
+      expect(knobProps.borderRadius.borderRadius).toBe("$4");
+    });
+
+    it('maps "large" → "$6"', () => {
+      const { knobProps } = resolveKnobs(knobsWith({ borderRadius: "large" }));
+      expect(knobProps.borderRadius.borderRadius).toBe("$6");
+    });
+
+    it('maps "full" → "$12"', () => {
+      const { knobProps } = resolveKnobs(knobsWith({ borderRadius: "full" }));
+      expect(knobProps.borderRadius.borderRadius).toBe("$12");
+    });
+  });
+
+  // ── borderWidth ───────────────────────────────────────────
+
+  describe("borderWidth knob", () => {
+    it('maps "none" → 0', () => {
+      const { knobProps } = resolveKnobs(knobsWith({ borderWidth: "none" }));
+      expect(knobProps.borderRadius.borderWidth).toBe(0);
+    });
+
+    it('maps "large" → 2', () => {
+      const { knobProps } = resolveKnobs(knobsWith({ borderWidth: "large" }));
+      expect(knobProps.borderRadius.borderWidth).toBe(2);
+    });
+
+    it("propagates to surface", () => {
+      const { knobProps } = resolveKnobs(knobsWith({ borderWidth: "large" }));
+      expect(knobProps.surface.borderWidth).toBe(2);
+    });
+  });
+
+  // ── elevation ──────────────────────────────────────────────
+
+  describe("elevation knob", () => {
+    it('maps "none" → undefined', () => {
+      expect(resolveKnobs(knobsWith({ elevation: "none" })).knobProps.elevation).toBeUndefined();
+    });
+
+    it('maps "small" → "$1"', () => {
+      expect(resolveKnobs(knobsWith({ elevation: "small" })).knobProps.elevation).toBe("$1");
+    });
+
+    it('maps "medium" → "$2"', () => {
+      expect(resolveKnobs(knobsWith({ elevation: "medium" })).knobProps.elevation).toBe("$2");
+    });
+
+    it('maps "large" → "$4"', () => {
+      expect(resolveKnobs(knobsWith({ elevation: "large" })).knobProps.elevation).toBe("$4");
+    });
+  });
+
+  // ── interaction state overrides ──────────────────────────────
+
+  describe("interaction state overrides", () => {
+    it("hover.elevation maps to elevation.hoverKnobProps.elevation", () => {
+      const { elevation } = resolveKnobs(knobsWith({ hover: { elevation: "medium" } }));
+      expect(elevation.hoverKnobProps?.elevation).toBe("$2");
+    });
+
+    it("press.elevation maps to elevation.pressKnobProps.elevation", () => {
+      const { elevation } = resolveKnobs(knobsWith({ press: { elevation: "large" } }));
+      expect(elevation.pressKnobProps?.elevation).toBe("$4");
+    });
+
+    it("hover.borderWidth maps to control.hoverKnobProps.borderWidth", () => {
+      const { control } = resolveKnobs(knobsWith({ hover: { borderWidth: "large" } }));
+      expect(control.hoverKnobProps?.borderWidth).toBe(2);
+    });
+
+    it("hover.borderRadius maps to control.hoverKnobProps.borderRadius", () => {
+      const { control } = resolveKnobs(knobsWith({ hover: { borderRadius: "full" } }));
+      expect(control.hoverKnobProps?.borderRadius).toBe("$12");
+    });
+
+    it("empty state overrides produce undefined", () => {
+      const { control } = resolveKnobs(defaultKnobs);
+      expect(control.hoverKnobProps).toBeUndefined();
+      expect(control.pressKnobProps).toBeUndefined();
+      expect(control.focusKnobProps).toBeUndefined();
+      expect(control.focusVisibleKnobProps).toBeUndefined();
+    });
+
+    it("focus.elevation maps to elevation.focusKnobProps.elevation", () => {
+      const { elevation } = resolveKnobs(knobsWith({ focus: { elevation: "small" } }));
+      expect(elevation.focusKnobProps?.elevation).toBe("$1");
+    });
+
+    it("focusVisible.borderWidth maps to control.focusVisibleKnobProps.borderWidth", () => {
+      const { control } = resolveKnobs(knobsWith({ focusVisible: { borderWidth: "medium" } }));
+      expect(control.focusVisibleKnobProps?.borderWidth).toBe(1);
+    });
+  });
+
+  // ── space ──────────────────────────────────────────────
+
+  describe("space knob", () => {
+    it('maps panelPadding "small" → "$3"', () => {
+      const { knobProps } = resolveKnobs(knobsWith({ space: "small" }));
+      expect(knobProps.panelPadding.padding).toBe("$3");
+    });
+
+    it('maps gap "large" → "$4"', () => {
+      const { knobProps } = resolveKnobs(knobsWith({ space: "large" }));
+      expect(knobProps.gap.gap).toBe("$4");
+    });
+
+    it("passes space value through to knobProps", () => {
+      const { knobProps } = resolveKnobs(knobsWith({ space: "large" }));
+      expect(knobProps.space).toBe("large");
+    });
+
+    // T2.1a — space "large" no longer changes sizeToken
+    it("space does not affect sizeToken", () => {
+      const { knobProps } = resolveKnobs(knobsWith({ space: "large", size: "medium" }));
+      expect(knobProps.sizeToken).toBe("$4");
+    });
+
+    // T2.1b — space "small" still maps panelPadding regardless of size
+    it('space "small" maps panelPadding → "$3" regardless of size', () => {
+      const { knobProps } = resolveKnobs(knobsWith({ space: "small", size: "large" }));
+      expect(knobProps.panelPadding.padding).toBe("$3");
+    });
+
+    // T2.1c — space "large" still maps gapLg → "$5" regardless of size
+    it('space "large" maps gapLg → "$5" regardless of size', () => {
+      const { knobProps } = resolveKnobs(knobsWith({ space: "large", size: "small" }));
+      expect(knobProps.gapLg.gap).toBe("$5");
+    });
+  });
+
+  // ── size ──────────────────────────────────────────────────
+
+  describe("size knob", () => {
+    // T1.1b — size "large" maps sizeToken → "$5"
+    it('maps sizeToken "large" → "$5"', () => {
+      const { knobProps } = resolveKnobs(knobsWith({ size: "large" }));
+      expect(knobProps.sizeToken).toBe("$5");
+    });
+
+    // T1.1c — size "small" maps sizeToken → "$3"
+    it('maps sizeToken "small" → "$3"', () => {
+      const { knobProps } = resolveKnobs(knobsWith({ size: "small" }));
+      expect(knobProps.sizeToken).toBe("$3");
+    });
+
+    // T1.1e — knobProps.size passthrough
+    it("passes size value through to knobProps", () => {
+      for (const val of Object.values(Size)) {
+        const { knobProps } = resolveKnobs(knobsWith({ size: val }));
+        expect(knobProps.size).toBe(val);
+      }
+    });
+
+    // T1.1f — independent axes: size "large" + space "small"
+    it('size "large" + space "small" → sizeToken "$5" AND gap "$2"', () => {
+      const { knobProps } = resolveKnobs(knobsWith({ size: "large", space: "small" }));
+      expect(knobProps.sizeToken).toBe("$5");
+      expect(knobProps.gap.gap).toBe("$2");
+    });
+
+    // T2.1e — changing size does NOT affect panelPadding, gap, or gapLg
+    it("changing size does not affect panelPadding, gap, or gapLg", () => {
+      const baseline = resolveKnobs(knobsWith({ size: "medium", space: "medium" }));
+      for (const sizeVal of Object.values(Size)) {
+        const { knobProps } = resolveKnobs(knobsWith({ size: sizeVal, space: "medium" }));
+        expect(knobProps.panelPadding).toEqual(baseline.knobProps.panelPadding);
+        expect(knobProps.gap).toEqual(baseline.knobProps.gap);
+        expect(knobProps.gapLg).toEqual(baseline.knobProps.gapLg);
+      }
+    });
+
+    // T2.1f — default knobs produce identical output to prior default
+    it("default knobs (size+space both medium) produce consistent output", () => {
+      const resolved = resolveKnobs(defaultKnobs);
+      expect(resolved.knobProps.sizeToken).toBe("$4");
+      expect(resolved.knobProps.gap.gap).toBe("$3");
+      expect(resolved.knobProps.panelPadding.padding).toBe("$4");
+      expect(resolved.knobProps.gapLg.gap).toBe("$4");
+    });
+  });
+
+  // ── fillStyle ─────────────────────────────────────────────
+
+  describe("fillStyle knob", () => {
+    it("filled → outlined is false", () => {
+      const { knobProps } = resolveKnobs(knobsWith({ fillStyle: "filled" }));
+      expect(knobProps.outlined).toBe(false);
+    });
+
+    it("outlined → outlined is true", () => {
+      const { knobProps } = resolveKnobs(knobsWith({ fillStyle: "outlined" }));
+      expect(knobProps.outlined).toBe(true);
+    });
+  });
+
+  // ── pointy ────────────────────────────────────────────────
+
+  describe("pointy derivation", () => {
+    it('is true when borderRadius is "none"', () => {
+      const { knobProps } = resolveKnobs(knobsWith({ borderRadius: "none" }));
+      expect(knobProps.pointy).toBe(true);
+    });
+
+    it('is false when borderRadius is "small"', () => {
+      const { knobProps } = resolveKnobs(knobsWith({ borderRadius: "small" }));
+      expect(knobProps.pointy).toBe(false);
+    });
+
+    it('is false when borderRadius is "medium"', () => {
+      const { knobProps } = resolveKnobs(knobsWith({ borderRadius: "medium" }));
+      expect(knobProps.pointy).toBe(false);
+    });
+
+    it('is false when borderRadius is "full"', () => {
+      const { knobProps } = resolveKnobs(knobsWith({ borderRadius: "full" }));
+      expect(knobProps.pointy).toBe(false);
+    });
+
+    it("is false for default knobs", () => {
+      const { knobProps } = resolveKnobs(defaultKnobs);
+      expect(knobProps.pointy).toBe(false);
+    });
+  });
+
+  // ── textAccent ────────────────────────────────────────────
+
+  describe("textAccent knob", () => {
+    it("passes through to knobProps", () => {
+      const high = resolveKnobs(knobsWith({ textAccent: "high" }));
+      expect(high.knobProps.textAccent).toBe("high");
+
+      const medium = resolveKnobs(knobsWith({ textAccent: "medium" }));
+      expect(medium.knobProps.textAccent).toBe("medium");
+
+      const low = resolveKnobs(knobsWith({ textAccent: "low" }));
+      expect(low.knobProps.textAccent).toBe("low");
+    });
+  });
+
+  // ── typography knobs ────────────────────────────────────────
+
+  describe("typography knobs", () => {
+    it("heading font maps correctly", () => {
+      expect(
+        resolveKnobs(knobsWith({ headingFont: "sans-serif" })).knobProps.heading.fontFamily,
+      ).toBe("$heading");
+      expect(resolveKnobs(knobsWith({ headingFont: "serif" })).knobProps.heading.fontFamily).toBe(
+        "$serif",
+      );
+      expect(resolveKnobs(knobsWith({ headingFont: "mono" })).knobProps.heading.fontFamily).toBe(
+        "$mono",
+      );
+      expect(resolveKnobs(knobsWith({ headingFont: "slab" })).knobProps.heading.fontFamily).toBe(
+        "$slab",
+      );
+      expect(resolveKnobs(knobsWith({ headingFont: "pixel" })).knobProps.heading.fontFamily).toBe(
+        "$pixel",
+      );
+    });
+
+    it("body font maps correctly", () => {
+      expect(resolveKnobs(knobsWith({ bodyFont: "sans-serif" })).knobProps.body.fontFamily).toBe(
+        "$body",
+      );
+      expect(resolveKnobs(knobsWith({ bodyFont: "serif" })).knobProps.body.fontFamily).toBe(
+        "$serif",
+      );
+      expect(resolveKnobs(knobsWith({ bodyFont: "mono" })).knobProps.body.fontFamily).toBe("$mono");
+      expect(resolveKnobs(knobsWith({ bodyFont: "slab" })).knobProps.body.fontFamily).toBe("$slab");
+      expect(resolveKnobs(knobsWith({ bodyFont: "pixel" })).knobProps.body.fontFamily).toBe(
+        "$pixel",
+      );
+    });
+
+    it("fontWeight maps correctly", () => {
+      expect(resolveKnobs(knobsWith({ fontWeight: "regular" })).knobProps.heading.fontWeight).toBe(
+        "400",
+      );
+      expect(resolveKnobs(knobsWith({ fontWeight: "bold" })).knobProps.heading.fontWeight).toBe(
+        "700",
+      );
+    });
+  });
+
+  // ── animation ─────────────────────────────────────────────
+
+  describe("animation knob", () => {
+    it('"none" → transition is undefined', () => {
+      const { knobProps } = resolveKnobs(knobsWith({ animation: "none" }));
+      expect(knobProps.transition).toBeUndefined();
+    });
+
+    it('"bouncy" → transition is "bouncy"', () => {
+      const { knobProps } = resolveKnobs(knobsWith({ animation: "bouncy" }));
+      expect(knobProps.transition).toBe("bouncy");
+    });
+
+    it('"quick" → transition is "quick"', () => {
+      const { knobProps } = resolveKnobs(knobsWith({ animation: "quick" }));
+      expect(knobProps.transition).toBe("quick");
+    });
+  });
+
+  // ── override callback ─────────────────────────────────────
+
+  describe("override callback", () => {
+    it("merges partial knobProps overrides on top", () => {
+      const { knobProps } = resolveKnobs(defaultKnobs, () => ({
+        elevation: "$4",
+      }));
+      expect(knobProps.elevation).toBe("$4");
+    });
+
+    it("does not mutate original knobProps", () => {
+      const baseline = resolveKnobs(defaultKnobs);
+      const overridden = resolveKnobs(defaultKnobs, () => ({
+        elevation: "$4",
+      }));
+      expect(baseline.knobProps.elevation).toBeUndefined();
+      expect(overridden.knobProps.elevation).toBe("$4");
+    });
+
+    // T4.1g — override callback receives knobProps with both size and space
+    it("override callback receives knobProps with both size and space", () => {
+      let receivedProps: KnobProps | undefined;
+      resolveKnobs(knobsWith({ size: "large", space: "small" }), (props) => {
+        receivedProps = props;
+        return {};
+      });
+      expect(receivedProps).toBeDefined();
+      expect(receivedProps!.size).toBe("large");
+      expect(receivedProps!.space).toBe("small");
+    });
+  });
+
+  // ── Group 4: Gap review tests ─────────────────────────────
+
+  describe("gap review", () => {
+    const sizeTokenMap: Record<string, string> = {
+      small: "$3",
+      medium: "$4",
+      large: "$5",
+    };
+
+    const gapMap: Record<string, string> = {
+      small: "$2",
+      medium: "$3",
+      large: "$4",
+    };
+
+    const panelPaddingMap: Record<string, string> = {
+      small: "$3",
+      medium: "$4",
+      large: "$6",
+    };
+
+    const gapLgMap: Record<string, string> = {
+      small: "$3",
+      medium: "$4",
+      large: "$5",
+    };
+
+    // T4.1a — every Size enum value produces a valid sizeToken
+    it("every Size enum value produces a valid sizeToken", () => {
+      for (const sizeVal of Object.values(Size)) {
+        const { knobProps } = resolveKnobs(knobsWith({ size: sizeVal }));
+        expect(knobProps.sizeToken).toBe(sizeTokenMap[sizeVal]);
+      }
+    });
+
+    // T4.1b — every Space enum value produces valid panelPadding, gap, gapLg
+    it("every Space enum value produces valid panelPadding, gap, gapLg", () => {
+      for (const spaceVal of Object.values(Space)) {
+        const { knobProps } = resolveKnobs(knobsWith({ space: spaceVal }));
+        expect(knobProps.panelPadding.padding).toBe(panelPaddingMap[spaceVal]);
+        expect(knobProps.gap.gap).toBe(gapMap[spaceVal]);
+        expect(knobProps.gapLg.gap).toBe(gapLgMap[spaceVal]);
+      }
+    });
+
+    // T4.1c — all 9 combinations of size × space
+    it("all 9 size × space combinations produce expected sizeToken and gap pairs", () => {
+      for (const sizeVal of Object.values(Size)) {
+        for (const spaceVal of Object.values(Space)) {
+          const { knobProps } = resolveKnobs(knobsWith({ size: sizeVal, space: spaceVal }));
+          expect(knobProps.sizeToken).toBe(sizeTokenMap[sizeVal]);
+          expect(knobProps.gap.gap).toBe(gapMap[spaceVal]);
+          expect(knobProps.panelPadding.padding).toBe(panelPaddingMap[spaceVal]);
+          expect(knobProps.gapLg.gap).toBe(gapLgMap[spaceVal]);
+        }
+      }
+    });
+
+    // T4.1e — knobProps.space still equals knobs.space
+    it("knobProps.space equals knobs.space", () => {
+      for (const spaceVal of Object.values(Space)) {
+        const { knobProps } = resolveKnobs(knobsWith({ space: spaceVal }));
+        expect(knobProps.space).toBe(spaceVal);
+      }
+    });
+
+    // T4.1f — knobProps.size equals knobs.size
+    it("knobProps.size equals knobs.size", () => {
+      for (const sizeVal of Object.values(Size)) {
+        const { knobProps } = resolveKnobs(knobsWith({ size: sizeVal }));
+        expect(knobProps.size).toBe(sizeVal);
+      }
+    });
+
+    // T4.1h — defaultKnobs has both size and space set to "medium"
+    it('defaultKnobs has both size and space set to "medium"', () => {
+      expect(defaultKnobs.size).toBe("medium");
+      expect(defaultKnobs.space).toBe("medium");
+    });
+
+    // T4.1i — emptyStateKnobs is still valid
+    it("emptyStateKnobs is still valid (no required size field breaks it)", () => {
+      const knobs = knobsWith({ hover: emptyStateKnobs });
+      const { control } = resolveKnobs(knobs);
+      expect(control.hoverKnobProps).toBeUndefined();
+    });
+
+    // T4.1j — size "large" does not change borderRadius
+    it('size "large" does not change borderRadius', () => {
+      const baseline = resolveKnobs(knobsWith({ size: "medium" }));
+      const large = resolveKnobs(knobsWith({ size: "large" }));
+      expect(large.knobProps.borderRadius).toEqual(baseline.knobProps.borderRadius);
+    });
+  });
+});