@stigmer/theme 3.10.0 → 3.11.1-dev.20260812192248

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stigmer/theme",
-  "version": "3.10.0",
+  "version": "3.11.1-dev.20260812192248",
   "description": "Design tokens, CSS custom properties, and utility functions for Stigmer UI components",
   "license": "Apache-2.0",
   "type": "module",

package/src/__tests__/cn-prefix-merge.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from "vitest";
+import { cn } from "../utils";
+
+/**
+ * Pins the #454 override contract: the `stg:` utility prefix must be
+ * TRANSPARENT for tailwind-merge conflict grouping, so a host's unprefixed
+ * `className` utilities still displace the SDK's prefixed defaults. If these
+ * pins fail, `cn("stg:p-2", hostClassName)` keeps both classes and the SDK's
+ * higher cascade layer silently wins — the documented override channel
+ * (DD-019) breaks without any visible error.
+ */
+describe("cn: stg: prefix is transparent for conflict grouping", () => {
+  it("host unprefixed utility displaces the SDK's prefixed default", () => {
+    expect(cn("stg:p-2", "p-4")).toBe("p-4");
+  });
+
+  it("SDK-internal merges keep the prefixed spelling", () => {
+    expect(cn("stg:p-2", "stg:p-4")).toBe("stg:p-4");
+  });
+
+  it("non-conflicting utilities from both spellings all survive", () => {
+    expect(cn("stg:flex stg:gap-2", "p-4")).toBe("stg:flex stg:gap-2 p-4");
+  });
+
+  it("variant conflicts resolve across spellings", () => {
+    expect(cn("stg:hover:bg-red-500", "hover:bg-blue-500")).toBe(
+      "hover:bg-blue-500",
+    );
+  });
+
+  it("SDK prefixed utility displaces an earlier host utility", () => {
+    // SDK call sites put the host className LAST (cn(base, className)), but
+    // the grouping must be symmetric.
+    expect(cn("p-4", "stg:p-2")).toBe("stg:p-2");
+  });
+
+  it("non-Tailwind classes pass through untouched", () => {
+    expect(cn("stg:p-2", "custom-class")).toBe("stg:p-2 custom-class");
+    expect(cn("stgm-thread-item-enter", "stg:opacity-50")).toBe(
+      "stgm-thread-item-enter stg:opacity-50",
+    );
+  });
+
+  it("conditional falsy inputs are dropped (clsx semantics)", () => {
+    expect(cn("stg:flex", false, undefined, null, "stg:gap-2")).toBe(
+      "stg:flex stg:gap-2",
+    );
+  });
+});

package/src/utils.ts

@@ -1,8 +1,48 @@
 import { type ClassValue, clsx } from "clsx";
-import { twMerge } from "tailwind-merge";
+import { extendTailwindMerge } from "tailwind-merge";
 
 export type { ClassValue };
 
+/**
+ * SDK utility class prefix (stigmer/stigmer#454).
+ *
+ * Every Tailwind utility authored inside the SDK carries this variant-style
+ * prefix (`stg:flex`), so the published stylesheet shares no class names with
+ * a host application's own Tailwind build. The prefix is deliberately NOT
+ * `stgm`: Tailwind v4 prefixes theme variables too, and a `stgm` prefix would
+ * collide with the `--stgm-*` token namespace (`--stgm-font-sans`,
+ * `--stgm-shadow-sm`) that `@stigmer/theme` already owns.
+ */
+export const UTILITY_PREFIX = "stg:";
+
+/**
+ * tailwind-merge configured so the `stg:` prefix is TRANSPARENT for conflict
+ * grouping. This preserves the SDK's `className` override contract: hosts
+ * pass their own unprefixed utilities (`p-4`), and they must still displace
+ * the SDK's prefixed defaults (`stg:p-2`) — the two spellings target the same
+ * CSS property, so they must resolve as the same conflict group even though
+ * their class names differ. Without this hook, both classes would survive the
+ * merge and the SDK's higher cascade layer would silently win, breaking the
+ * documented override channel (DD-019).
+ */
+const twMergeWithPrefix = extendTailwindMerge({
+  experimentalParseClassName: ({ className, parseClassName }) =>
+    parseClassName(
+      className.startsWith(UTILITY_PREFIX)
+        ? className.slice(UTILITY_PREFIX.length)
+        : className,
+    ),
+});
+
+/**
+ * Merge class values with Tailwind-aware conflict resolution.
+ *
+ * Later inputs win conflicts, across BOTH spellings of a utility: the SDK's
+ * prefixed form (`stg:p-2`) and a host's unprefixed form (`p-4`) are the same
+ * conflict group, so `cn("stg:p-2", className)` lets a host `className`
+ * override SDK defaults exactly as it did before the #454 prefix migration.
+ * Non-Tailwind classes pass through untouched.
+ */
 export function cn(...inputs: ClassValue[]) {
-  return twMerge(clsx(inputs));
+  return twMergeWithPrefix(clsx(inputs));
 }

package/utils.d.ts

@@ -1,4 +1,24 @@
 import { type ClassValue } from "clsx";
 export type { ClassValue };
+/**
+ * SDK utility class prefix (stigmer/stigmer#454).
+ *
+ * Every Tailwind utility authored inside the SDK carries this variant-style
+ * prefix (`stg:flex`), so the published stylesheet shares no class names with
+ * a host application's own Tailwind build. The prefix is deliberately NOT
+ * `stgm`: Tailwind v4 prefixes theme variables too, and a `stgm` prefix would
+ * collide with the `--stgm-*` token namespace (`--stgm-font-sans`,
+ * `--stgm-shadow-sm`) that `@stigmer/theme` already owns.
+ */
+export declare const UTILITY_PREFIX = "stg:";
+/**
+ * Merge class values with Tailwind-aware conflict resolution.
+ *
+ * Later inputs win conflicts, across BOTH spellings of a utility: the SDK's
+ * prefixed form (`stg:p-2`) and a host's unprefixed form (`p-4`) are the same
+ * conflict group, so `cn("stg:p-2", className)` lets a host `className`
+ * override SDK defaults exactly as it did before the #454 prefix migration.
+ * Non-Tailwind classes pass through untouched.
+ */
 export declare function cn(...inputs: ClassValue[]): string;
 //# sourceMappingURL=utils.d.ts.map

package/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,UAAU,EAAQ,MAAM,MAAM,CAAC;AAG7C,YAAY,EAAE,UAAU,EAAE,CAAC;AAE3B,wBAAgB,EAAE,CAAC,GAAG,MAAM,EAAE,UAAU,EAAE,UAEzC"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,UAAU,EAAQ,MAAM,MAAM,CAAC;AAG7C,YAAY,EAAE,UAAU,EAAE,CAAC;AAE3B;;;;;;;;;GASG;AACH,eAAO,MAAM,cAAc,SAAS,CAAC;AAqBrC;;;;;;;;GAQG;AACH,wBAAgB,EAAE,CAAC,GAAG,MAAM,EAAE,UAAU,EAAE,UAEzC"}

package/utils.js

@@ -1,6 +1,41 @@
 import { clsx } from "clsx";
-import { twMerge } from "tailwind-merge";
+import { extendTailwindMerge } from "tailwind-merge";
+/**
+ * SDK utility class prefix (stigmer/stigmer#454).
+ *
+ * Every Tailwind utility authored inside the SDK carries this variant-style
+ * prefix (`stg:flex`), so the published stylesheet shares no class names with
+ * a host application's own Tailwind build. The prefix is deliberately NOT
+ * `stgm`: Tailwind v4 prefixes theme variables too, and a `stgm` prefix would
+ * collide with the `--stgm-*` token namespace (`--stgm-font-sans`,
+ * `--stgm-shadow-sm`) that `@stigmer/theme` already owns.
+ */
+export const UTILITY_PREFIX = "stg:";
+/**
+ * tailwind-merge configured so the `stg:` prefix is TRANSPARENT for conflict
+ * grouping. This preserves the SDK's `className` override contract: hosts
+ * pass their own unprefixed utilities (`p-4`), and they must still displace
+ * the SDK's prefixed defaults (`stg:p-2`) — the two spellings target the same
+ * CSS property, so they must resolve as the same conflict group even though
+ * their class names differ. Without this hook, both classes would survive the
+ * merge and the SDK's higher cascade layer would silently win, breaking the
+ * documented override channel (DD-019).
+ */
+const twMergeWithPrefix = extendTailwindMerge({
+    experimentalParseClassName: ({ className, parseClassName }) => parseClassName(className.startsWith(UTILITY_PREFIX)
+        ? className.slice(UTILITY_PREFIX.length)
+        : className),
+});
+/**
+ * Merge class values with Tailwind-aware conflict resolution.
+ *
+ * Later inputs win conflicts, across BOTH spellings of a utility: the SDK's
+ * prefixed form (`stg:p-2`) and a host's unprefixed form (`p-4`) are the same
+ * conflict group, so `cn("stg:p-2", className)` lets a host `className`
+ * override SDK defaults exactly as it did before the #454 prefix migration.
+ * Non-Tailwind classes pass through untouched.
+ */
 export function cn(...inputs) {
-    return twMerge(clsx(inputs));
+    return twMergeWithPrefix(clsx(inputs));
 }
 //# sourceMappingURL=utils.js.map

package/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,IAAI,EAAE,MAAM,MAAM,CAAC;AAC7C,OAAO,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAIzC,MAAM,UAAU,EAAE,CAAC,GAAG,MAAoB;IACxC,OAAO,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;AAC/B,CAAC"}
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,IAAI,EAAE,MAAM,MAAM,CAAC;AAC7C,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAIrD;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,MAAM,CAAC;AAErC;;;;;;;;;GASG;AACH,MAAM,iBAAiB,GAAG,mBAAmB,CAAC;IAC5C,0BAA0B,EAAE,CAAC,EAAE,SAAS,EAAE,cAAc,EAAE,EAAE,EAAE,CAC5D,cAAc,CACZ,SAAS,CAAC,UAAU,CAAC,cAAc,CAAC;QAClC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,cAAc,CAAC,MAAM,CAAC;QACxC,CAAC,CAAC,SAAS,CACd;CACJ,CAAC,CAAC;AAEH;;;;;;;;GAQG;AACH,MAAM,UAAU,EAAE,CAAC,GAAG,MAAoB;IACxC,OAAO,iBAAiB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;AACzC,CAAC"}