@csszyx/runtime 0.10.2 → 0.10.4

package/dist/index.cjs

@@ -1313,8 +1313,112 @@ function omitSz(sz, selector) {
   return filterSz(flattenSz(sz, 0), selector, false, 0);
 }
 
+const AMBIGUOUS_PREFIXES = /* @__PURE__ */ new Set([
+  "flex",
+  // flex-1 (flex shorthand) vs flex-row (flex-direction)
+  "text",
+  // text-sm (font-size) vs text-red-500 (color)
+  "bg",
+  // bg-red-500 (color) vs bg-cover (size) vs bg-center (position)
+  "border",
+  // border-2 (width) vs border-red-500 (color) vs border-solid (style)
+  "divide",
+  // divide-x (width) vs divide-red-500 (color)
+  "ring",
+  // ring-2 (width) vs ring-red-500 (color)
+  "outline"
+  // outline-2 (width) vs outline-red-500 (color)
+]);
+function decodeToken(token) {
+  const decode = globalThis.__csszyx?.decode;
+  if (typeof decode === "function") {
+    return decode(token) ?? token;
+  }
+  return token;
+}
+const SHORTHAND_COVERAGE = {
+  p: ["p", "px", "py", "pt", "pr", "pb", "pl", "ps", "pe"],
+  px: ["px", "pl", "pr", "ps", "pe"],
+  py: ["py", "pt", "pb"],
+  m: ["m", "mx", "my", "mt", "mr", "mb", "ml", "ms", "me"],
+  mx: ["mx", "ml", "mr", "ms", "me"],
+  my: ["my", "mt", "mb"],
+  // inset (position) — physical sides only.
+  inset: ["inset", "inset-x", "inset-y", "top", "right", "bottom", "left"],
+  "inset-x": ["inset-x", "left", "right"],
+  "inset-y": ["inset-y", "top", "bottom"],
+  // border-radius — physical corners only (logical rounded-s*/e* stay keep-both).
+  rounded: [
+    "rounded",
+    "rounded-t",
+    "rounded-r",
+    "rounded-b",
+    "rounded-l",
+    "rounded-tl",
+    "rounded-tr",
+    "rounded-br",
+    "rounded-bl"
+  ],
+  "rounded-t": ["rounded-t", "rounded-tl", "rounded-tr"],
+  "rounded-r": ["rounded-r", "rounded-tr", "rounded-br"],
+  "rounded-b": ["rounded-b", "rounded-bl", "rounded-br"],
+  "rounded-l": ["rounded-l", "rounded-tl", "rounded-bl"]
+};
+function mergeClassify(token) {
+  const base = stripVariant(token);
+  const variant = token.slice(0, token.length - base.length);
+  const norm = normalizeBase(base);
+  if (!norm) {
+    return null;
+  }
+  if (BOX_ROLE_TOKENS.has(norm)) {
+    return null;
+  }
+  for (const [prefix] of BOX_ROLE_PREFIXES) {
+    if (norm === prefix || norm.startsWith(`${prefix}-`)) {
+      if (AMBIGUOUS_PREFIXES.has(prefix)) {
+        return null;
+      }
+      const coveredPrefixes = SHORTHAND_COVERAGE[prefix] ?? [prefix];
+      return {
+        key: `${variant} ${prefix}`,
+        covers: coveredPrefixes.map((p) => `${variant} ${p}`)
+      };
+    }
+  }
+  return null;
+}
+function szcn(...inputs) {
+  const order = [];
+  const byKey = /* @__PURE__ */ new Map();
+  for (const input of inputs) {
+    if (!input || typeof input !== "string") {
+      continue;
+    }
+    for (const token of input.split(/\s+/)) {
+      if (!token) {
+        continue;
+      }
+      const original = decodeToken(token);
+      const info = mergeClassify(original);
+      const key = info ? info.key : original;
+      for (const covered of info ? info.covers : [key]) {
+        if (byKey.delete(covered)) {
+          const at = order.indexOf(covered);
+          if (at !== -1) {
+            order.splice(at, 1);
+          }
+        }
+      }
+      byKey.set(key, token);
+      order.push(key);
+    }
+  }
+  return order.map((key) => byKey.get(key)).join(" ");
+}
+
 const warned$1 = /* @__PURE__ */ new Set();
-const RAW_SZ_WARNING = '[csszyx] A raw `sz` object reached the runtime and was dropped before it could leak to the DOM as sz="[object Object]".\nThis means the file was not compiled \u2014 its `sz` produces no CSS. If it lives in a workspace package, add that package to `compilePackages`; otherwise check that the bundler is not skipping the file.';
+const RAW_SZ_WARNING = '[csszyx] A raw `sz` object reached the runtime and was dropped before it could leak to the DOM as sz="[object Object]".\nThis means the file was not compiled \u2014 its `sz` produces no CSS. If it lives in a workspace package, add that package directory to `compileSources`; otherwise check that the bundler is not skipping the file.';
 function warnRawSz() {
   if (warned$1.has(RAW_SZ_WARNING)) return;
   warned$1.add(RAW_SZ_WARNING);
@@ -1567,6 +1671,7 @@ exports.splitBox = splitBox;
 exports.splitBoxSz = splitBoxSz;
 exports.startHydration = startHydration;
 exports.stripSzProps = stripSzProps;
+exports.szcn = szcn;
 exports.szv = szv;
 exports.validateHydrationClass = validateHydrationClass;
 exports.verifyAllTokens = verifyAllTokens;

package/dist/index.d.cts

@@ -598,6 +598,20 @@ declare function startHydration(): void;
  */
 declare function endHydration(): void;
 
+/**
+ * Merge className strings with last-wins override per utility, mangle-aware.
+ *
+ * Intended for the single resolution point in a layered design-system component
+ * (typically at the leaf Box): combine the component's default classes with the
+ * forwarded override so the override wins on a same-utility collision, while
+ * keeping production mangling intact (unlike npm tailwind-merge).
+ *
+ * @param inputs - Class strings; falsy inputs (`false`/`null`/`undefined`/`''`) are skipped.
+ * @returns The merged className string.
+ * @example szcn('gap-2 p-4', 'gap-8') // → 'p-4 gap-8'  (gap-8 overrides gap-2)
+ */
+declare function szcn(...inputs: (string | false | null | undefined)[]): string;
+
 /** Which side of the CSS box-model border a property acts on. */
 type BoxRole = 'outer' | 'inner';
 
@@ -768,7 +782,7 @@ declare function omitSz(sz: SzInput, selector: BoxSelector): SzObject;
  *
  * The compiler rewrites `sz` to `className` at build time, so a compiled
  * component never carries a leftover `sz` prop. But when a file is NOT compiled
- * — e.g. a workspace package missing from `compilePackages`, or any source the
+ * — e.g. a workspace package missing from `compileSources`, or any source the
  * bundler skipped — a hand-forwarded `sz` survives and React spreads it to the
  * DOM as `sz="[object Object]"`. `stripSzProps` removes `sz` from the forwarded
  * props so it never reaches the DOM, and in development warns once when the
@@ -947,5 +961,5 @@ declare function isRuntimeInitialized(): boolean;
  */
 declare function resetRuntime(): void;
 
-export { DEFAULT_RUNTIME_CONFIG, VERSION, _sz, _sz2, _sz3, _szMerge, abortHydration, attemptCSRRecovery, classify, classifySzKey, clearHydrationErrors, computeMangleChecksumAsync, disableCSRRecovery, enableCSRRecovery, endHydration, getAbortedSubtreeCount, getHydrationErrors, getRecoveryMode, getRuntimeConfig, getSSRContext, guardHydration, has, hasRecoveryToken, hasSz, initRuntime, isCSRRecoveryAllowed, isHydrating, isHydrationAborted, isRuntimeInitialized, isSSREnvironment, isValidMangleMap, isValidManifest, loadMangleMapFromDOM, loadManifestFromDOM, omit, omitSz, pick, pickSz, resetRuntime, splitBox, splitBoxSz, startHydration, stripSzProps, szv, validateHydrationClass, verifyAllTokens, verifyMangleChecksum, verifyMangleChecksumAsync, verifyMangleMapIntegrity, verifyRecoveryToken };
+export { DEFAULT_RUNTIME_CONFIG, VERSION, _sz, _sz2, _sz3, _szMerge, abortHydration, attemptCSRRecovery, classify, classifySzKey, clearHydrationErrors, computeMangleChecksumAsync, disableCSRRecovery, enableCSRRecovery, endHydration, getAbortedSubtreeCount, getHydrationErrors, getRecoveryMode, getRuntimeConfig, getSSRContext, guardHydration, has, hasRecoveryToken, hasSz, initRuntime, isCSRRecoveryAllowed, isHydrating, isHydrationAborted, isRuntimeInitialized, isSSREnvironment, isValidMangleMap, isValidManifest, loadMangleMapFromDOM, loadManifestFromDOM, omit, omitSz, pick, pickSz, resetRuntime, splitBox, splitBoxSz, startHydration, stripSzProps, szcn, szv, validateHydrationClass, verifyAllTokens, verifyMangleChecksum, verifyMangleChecksumAsync, verifyMangleMapIntegrity, verifyRecoveryToken };
 export type { BoxRole, BoxSelector, Classification, HydrationError, HydrationErrorType, MangleMap, RecoveryManifest, RecoveryMode, RuntimeConfig, SSRContext, SplitBoxOptions, SplitBoxResult, SplitBoxSzOptions, SplitBoxSzResult, SzInput, TokenData, VerificationResult };

package/dist/index.d.mts

@@ -598,6 +598,20 @@ declare function startHydration(): void;
  */
 declare function endHydration(): void;
 
+/**
+ * Merge className strings with last-wins override per utility, mangle-aware.
+ *
+ * Intended for the single resolution point in a layered design-system component
+ * (typically at the leaf Box): combine the component's default classes with the
+ * forwarded override so the override wins on a same-utility collision, while
+ * keeping production mangling intact (unlike npm tailwind-merge).
+ *
+ * @param inputs - Class strings; falsy inputs (`false`/`null`/`undefined`/`''`) are skipped.
+ * @returns The merged className string.
+ * @example szcn('gap-2 p-4', 'gap-8') // → 'p-4 gap-8'  (gap-8 overrides gap-2)
+ */
+declare function szcn(...inputs: (string | false | null | undefined)[]): string;
+
 /** Which side of the CSS box-model border a property acts on. */
 type BoxRole = 'outer' | 'inner';
 
@@ -768,7 +782,7 @@ declare function omitSz(sz: SzInput, selector: BoxSelector): SzObject;
  *
  * The compiler rewrites `sz` to `className` at build time, so a compiled
  * component never carries a leftover `sz` prop. But when a file is NOT compiled
- * — e.g. a workspace package missing from `compilePackages`, or any source the
+ * — e.g. a workspace package missing from `compileSources`, or any source the
  * bundler skipped — a hand-forwarded `sz` survives and React spreads it to the
  * DOM as `sz="[object Object]"`. `stripSzProps` removes `sz` from the forwarded
  * props so it never reaches the DOM, and in development warns once when the
@@ -947,5 +961,5 @@ declare function isRuntimeInitialized(): boolean;
  */
 declare function resetRuntime(): void;
 
-export { DEFAULT_RUNTIME_CONFIG, VERSION, _sz, _sz2, _sz3, _szMerge, abortHydration, attemptCSRRecovery, classify, classifySzKey, clearHydrationErrors, computeMangleChecksumAsync, disableCSRRecovery, enableCSRRecovery, endHydration, getAbortedSubtreeCount, getHydrationErrors, getRecoveryMode, getRuntimeConfig, getSSRContext, guardHydration, has, hasRecoveryToken, hasSz, initRuntime, isCSRRecoveryAllowed, isHydrating, isHydrationAborted, isRuntimeInitialized, isSSREnvironment, isValidMangleMap, isValidManifest, loadMangleMapFromDOM, loadManifestFromDOM, omit, omitSz, pick, pickSz, resetRuntime, splitBox, splitBoxSz, startHydration, stripSzProps, szv, validateHydrationClass, verifyAllTokens, verifyMangleChecksum, verifyMangleChecksumAsync, verifyMangleMapIntegrity, verifyRecoveryToken };
+export { DEFAULT_RUNTIME_CONFIG, VERSION, _sz, _sz2, _sz3, _szMerge, abortHydration, attemptCSRRecovery, classify, classifySzKey, clearHydrationErrors, computeMangleChecksumAsync, disableCSRRecovery, enableCSRRecovery, endHydration, getAbortedSubtreeCount, getHydrationErrors, getRecoveryMode, getRuntimeConfig, getSSRContext, guardHydration, has, hasRecoveryToken, hasSz, initRuntime, isCSRRecoveryAllowed, isHydrating, isHydrationAborted, isRuntimeInitialized, isSSREnvironment, isValidMangleMap, isValidManifest, loadMangleMapFromDOM, loadManifestFromDOM, omit, omitSz, pick, pickSz, resetRuntime, splitBox, splitBoxSz, startHydration, stripSzProps, szcn, szv, validateHydrationClass, verifyAllTokens, verifyMangleChecksum, verifyMangleChecksumAsync, verifyMangleMapIntegrity, verifyRecoveryToken };
 export type { BoxRole, BoxSelector, Classification, HydrationError, HydrationErrorType, MangleMap, RecoveryManifest, RecoveryMode, RuntimeConfig, SSRContext, SplitBoxOptions, SplitBoxResult, SplitBoxSzOptions, SplitBoxSzResult, SzInput, TokenData, VerificationResult };

package/dist/index.mjs

@@ -1311,8 +1311,112 @@ function omitSz(sz, selector) {
   return filterSz(flattenSz(sz, 0), selector, false, 0);
 }
 
+const AMBIGUOUS_PREFIXES = /* @__PURE__ */ new Set([
+  "flex",
+  // flex-1 (flex shorthand) vs flex-row (flex-direction)
+  "text",
+  // text-sm (font-size) vs text-red-500 (color)
+  "bg",
+  // bg-red-500 (color) vs bg-cover (size) vs bg-center (position)
+  "border",
+  // border-2 (width) vs border-red-500 (color) vs border-solid (style)
+  "divide",
+  // divide-x (width) vs divide-red-500 (color)
+  "ring",
+  // ring-2 (width) vs ring-red-500 (color)
+  "outline"
+  // outline-2 (width) vs outline-red-500 (color)
+]);
+function decodeToken(token) {
+  const decode = globalThis.__csszyx?.decode;
+  if (typeof decode === "function") {
+    return decode(token) ?? token;
+  }
+  return token;
+}
+const SHORTHAND_COVERAGE = {
+  p: ["p", "px", "py", "pt", "pr", "pb", "pl", "ps", "pe"],
+  px: ["px", "pl", "pr", "ps", "pe"],
+  py: ["py", "pt", "pb"],
+  m: ["m", "mx", "my", "mt", "mr", "mb", "ml", "ms", "me"],
+  mx: ["mx", "ml", "mr", "ms", "me"],
+  my: ["my", "mt", "mb"],
+  // inset (position) — physical sides only.
+  inset: ["inset", "inset-x", "inset-y", "top", "right", "bottom", "left"],
+  "inset-x": ["inset-x", "left", "right"],
+  "inset-y": ["inset-y", "top", "bottom"],
+  // border-radius — physical corners only (logical rounded-s*/e* stay keep-both).
+  rounded: [
+    "rounded",
+    "rounded-t",
+    "rounded-r",
+    "rounded-b",
+    "rounded-l",
+    "rounded-tl",
+    "rounded-tr",
+    "rounded-br",
+    "rounded-bl"
+  ],
+  "rounded-t": ["rounded-t", "rounded-tl", "rounded-tr"],
+  "rounded-r": ["rounded-r", "rounded-tr", "rounded-br"],
+  "rounded-b": ["rounded-b", "rounded-bl", "rounded-br"],
+  "rounded-l": ["rounded-l", "rounded-tl", "rounded-bl"]
+};
+function mergeClassify(token) {
+  const base = stripVariant(token);
+  const variant = token.slice(0, token.length - base.length);
+  const norm = normalizeBase(base);
+  if (!norm) {
+    return null;
+  }
+  if (BOX_ROLE_TOKENS.has(norm)) {
+    return null;
+  }
+  for (const [prefix] of BOX_ROLE_PREFIXES) {
+    if (norm === prefix || norm.startsWith(`${prefix}-`)) {
+      if (AMBIGUOUS_PREFIXES.has(prefix)) {
+        return null;
+      }
+      const coveredPrefixes = SHORTHAND_COVERAGE[prefix] ?? [prefix];
+      return {
+        key: `${variant} ${prefix}`,
+        covers: coveredPrefixes.map((p) => `${variant} ${p}`)
+      };
+    }
+  }
+  return null;
+}
+function szcn(...inputs) {
+  const order = [];
+  const byKey = /* @__PURE__ */ new Map();
+  for (const input of inputs) {
+    if (!input || typeof input !== "string") {
+      continue;
+    }
+    for (const token of input.split(/\s+/)) {
+      if (!token) {
+        continue;
+      }
+      const original = decodeToken(token);
+      const info = mergeClassify(original);
+      const key = info ? info.key : original;
+      for (const covered of info ? info.covers : [key]) {
+        if (byKey.delete(covered)) {
+          const at = order.indexOf(covered);
+          if (at !== -1) {
+            order.splice(at, 1);
+          }
+        }
+      }
+      byKey.set(key, token);
+      order.push(key);
+    }
+  }
+  return order.map((key) => byKey.get(key)).join(" ");
+}
+
 const warned$1 = /* @__PURE__ */ new Set();
-const RAW_SZ_WARNING = '[csszyx] A raw `sz` object reached the runtime and was dropped before it could leak to the DOM as sz="[object Object]".\nThis means the file was not compiled \u2014 its `sz` produces no CSS. If it lives in a workspace package, add that package to `compilePackages`; otherwise check that the bundler is not skipping the file.';
+const RAW_SZ_WARNING = '[csszyx] A raw `sz` object reached the runtime and was dropped before it could leak to the DOM as sz="[object Object]".\nThis means the file was not compiled \u2014 its `sz` produces no CSS. If it lives in a workspace package, add that package directory to `compileSources`; otherwise check that the bundler is not skipping the file.';
 function warnRawSz() {
   if (warned$1.has(RAW_SZ_WARNING)) return;
   warned$1.add(RAW_SZ_WARNING);
@@ -1521,4 +1625,4 @@ function resetRuntime() {
   runtimeState.initialized = false;
 }
 
-export { DEFAULT_RUNTIME_CONFIG, VERSION, _sz, _sz2, _sz3, _szMerge, abortHydration, attemptCSRRecovery, classify, classifySzKey, clearHydrationErrors, computeMangleChecksumAsync, disableCSRRecovery, enableCSRRecovery, endHydration, getAbortedSubtreeCount, getHydrationErrors, getRecoveryMode, getRuntimeConfig, getSSRContext, guardHydration, has, hasRecoveryToken, hasSz, initRuntime, isCSRRecoveryAllowed, isHydrating, isHydrationAborted, isRuntimeInitialized, isSSREnvironment, isValidMangleMap, isValidManifest, loadMangleMapFromDOM, loadManifestFromDOM, omit, omitSz, pick, pickSz, resetRuntime, splitBox, splitBoxSz, startHydration, stripSzProps, szv, validateHydrationClass, verifyAllTokens, verifyMangleChecksum, verifyMangleChecksumAsync, verifyMangleMapIntegrity, verifyRecoveryToken };
+export { DEFAULT_RUNTIME_CONFIG, VERSION, _sz, _sz2, _sz3, _szMerge, abortHydration, attemptCSRRecovery, classify, classifySzKey, clearHydrationErrors, computeMangleChecksumAsync, disableCSRRecovery, enableCSRRecovery, endHydration, getAbortedSubtreeCount, getHydrationErrors, getRecoveryMode, getRuntimeConfig, getSSRContext, guardHydration, has, hasRecoveryToken, hasSz, initRuntime, isCSRRecoveryAllowed, isHydrating, isHydrationAborted, isRuntimeInitialized, isSSREnvironment, isValidMangleMap, isValidManifest, loadMangleMapFromDOM, loadManifestFromDOM, omit, omitSz, pick, pickSz, resetRuntime, splitBox, splitBoxSz, startHydration, stripSzProps, szcn, szv, validateHydrationClass, verifyAllTokens, verifyMangleChecksum, verifyMangleChecksumAsync, verifyMangleMapIntegrity, verifyRecoveryToken };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@csszyx/runtime",
-  "version": "0.10.2",
+  "version": "0.10.4",
   "description": "Runtime helpers and hydration guards for csszyx",
   "keywords": [
     "csszyx",
@@ -49,8 +49,8 @@
     "dist"
   ],
   "dependencies": {
-    "@csszyx/compiler": "0.10.2",
-    "@csszyx/core": "0.10.2"
+    "@csszyx/compiler": "0.10.4",
+    "@csszyx/core": "0.10.4"
   },
   "devDependencies": {
     "@types/node": "^20.11.0",