meno-core 1.0.54 → 1.1.1

package/lib/shared/utilityClassMapper.ts

@@ -4,7 +4,8 @@
  * Uses centralized configuration from utilityClassConfig.ts
  */
 
-import type { ResponsiveStyleObject, StyleObject, StyleMapping } from './types';
+import type { ResponsiveStyleObject, StyleObject, StyleMapping, StyleValue } from './types';
+import { isResponsiveStyle } from './styleUtils';
 import {
   propertyMap,
   propertyOrder,
@@ -18,6 +19,8 @@ import {
   shadowPresets,
   gradientPresets,
   borderPresets,
+  SPACING_SCALE_ROOTS,
+  SPACING_SCALE_REVERSE,
 } from './utilityClassConfig';
 import {
   camelToKebab,
@@ -26,11 +29,13 @@ import {
   parseUtilityClass,
   splitVariantPrefix,
   breakpointClassPrefix,
+  normalizeBreakpointVariant,
   resolveRootProperty,
   ROOT_CAMEL_OVERRIDES,
-  isColorValue,
+  isBareColorTokenName,
 } from './utilityClassNames';
 import { registerStyleValue, registerDynamicStyle, getStyleValue, getDynamicStyle } from './styleValueRegistry';
+import { THEME_SCALE_BY_CSSVAR } from './tailwindThemeScale';
 import {
   SCALABLE_CSS_PROPERTIES,
   buildFluidClampWithExplicitMin,
@@ -63,22 +68,29 @@ function shortHash(input: string): string {
 }
 
 /**
- * True for a bare Meno color token (e.g. `primary`, `background-light`) that
- * should resolve to `var(--token)`. Named CSS colors, hex/function colors and
- * values starting with digits are NOT tokens.
+ * Whether the natural `root-(--x)` / `root-[value]` form would round-trip to a DIFFERENT property
+ * than `prop`. Roots shared by a shorthand and a color/width longhand (`border` → border/borderColor,
+ * `outline` → outline/outlineWidth/outlineColor) are disambiguated on parse by value type via
+ * `resolveRootProperty` — so a color-looking value (notably any opaque `var(--x)`) bound to the
+ * SHORTHAND reads back as the color longhand. Callers fall back to the explicit arbitrary-property
+ * form (`[border:var(--x)]`) when this returns true.
+ *
+ * Mirrors the inverse parser's property derivation EXACTLY (`classToStyle`): `ROOT_CAMEL_OVERRIDES`
+ * wins first (px → paddingInline, …), else `resolveRootProperty`. Comparing kebab CSS names instead
+ * would false-positive on those overridden roots (`px` resolves to `padding`, not `padding-inline`).
  */
-function isBareColorToken(value: string): boolean {
-  if (!/^[a-zA-Z][\w-]*$/.test(value)) return false;
-  if (isColorValue(value)) return false; // named colors / transparent / currentColor
-  return true;
+function rootFormMisresolves(root: string, prop: string, value: string): boolean {
+  const parsedProp = ROOT_CAMEL_OVERRIDES[root] ?? cssPropertyToCamel(resolveRootProperty(root, value));
+  return parsedProp !== prop;
 }
 
 /**
  * Converts a CSS property value to a Tailwind-style utility class name.
  * Examples:
- *   { prop: "padding", value: "10px" }        → "p-[10px]"
+ *   { prop: "padding", value: "16px" }        → "p-4"   (exact scale step)
+ *   { prop: "padding", value: "13px" }        → "p-[13px]" (off-scale → arbitrary)
  *   { prop: "display", value: "flex" }        → "flex"
- *   { prop: "color", value: "primary" }       → "text-(--primary)"
+ *   { prop: "color", value: "primary" }       → "text-primary"
  *   { prop: "width", value: "100%" }          → "w-full"
  *   { prop: "textOverflow", value: "ellipsis" } → "[text-overflow:ellipsis]"
  *
@@ -88,6 +100,19 @@ function isBareColorToken(value: string): boolean {
 function propertyValueToClass(prop: string, value: string | number): string | null {
   let stringValue = String(value);
 
+  // Tailwind theme token: a `var(--token)` value (or a legacy `var(--token, …)` with fallback)
+  // whose token is a known Tailwind scale var (and whose property matches) emits the compact class —
+  // `var(--text-lg)` → `text-lg`. Runs before the fontFamily comma-split below (which would shred a
+  // multi-family `var()` fallback). The parser reconstructs the value from the class, so no registry
+  // entry is needed.
+  const varRef = stringValue.match(/^var\((--[\w-]+)(?:\s*,[\s\S]*)?\)$/);
+  if (varRef) {
+    const entry = THEME_SCALE_BY_CSSVAR.get(varRef[1] ?? '');
+    if (entry && entry.property === camelToKebab(prop)) {
+      return entry.className;
+    }
+  }
+
   // Strip outer quotes from fontFamily values (e.g. "Space Grotesk" → Space Grotesk)
   if (prop === 'fontFamily') {
     stringValue = stringValue
@@ -110,19 +135,22 @@ function propertyValueToClass(prop: string, value: string | number): string | nu
   }
 
   // Preset values (e.g., boxShadow: "2" → shadow-2)
-  if (prop === 'boxShadow' && shadowPresets[stringValue]) {
+  const shadowPreset = shadowPresets[stringValue];
+  if (prop === 'boxShadow' && shadowPreset) {
     const className = `shadow-${stringValue}`;
-    registerStyleValue(className, shadowPresets[stringValue]);
+    registerStyleValue(className, shadowPreset);
     return className;
   }
-  if ((prop === 'background' || prop === 'backgroundImage') && gradientPresets[stringValue]) {
+  const gradientPreset = gradientPresets[stringValue];
+  if ((prop === 'background' || prop === 'backgroundImage') && gradientPreset) {
     const className = `bg-gradient-${stringValue}`;
-    registerStyleValue(className, gradientPresets[stringValue]);
+    registerStyleValue(className, gradientPreset);
     return className;
   }
-  if (prop === 'border' && borderPresets[stringValue]) {
+  const borderPreset = borderPresets[stringValue];
+  if (prop === 'border' && borderPreset) {
     const className = `border-preset-${stringValue}`;
-    registerStyleValue(className, borderPresets[stringValue]);
+    registerStyleValue(className, borderPreset);
     return className;
   }
 
@@ -170,6 +198,30 @@ function propertyValueToClass(prop: string, value: string | number): string | nu
     }
   }
 
+  // Named spacing scale (Tailwind steps): padding 16px → p-4, gap 24px → gap-6.
+  // Only EXACT steps; off-scale values fall through to the arbitrary form below.
+  // Keyword values (w-full, m-auto) are matched above, so they still win.
+  if (!className && SPACING_SCALE_ROOTS.has(root)) {
+    const step = SPACING_SCALE_REVERSE[stringValue];
+    if (step !== undefined) {
+      className = `${root}-${step}`;
+    }
+  }
+
+  // Tailwind grid track scale: gridTemplateColumns "repeat(3, minmax(0, 1fr))" → grid-cols-3
+  // (and gridTemplateRows → grid-rows-N, plus the none/subgrid keywords). Keeps grid-cols-N that
+  // came in from hand/AI-authored class strings round-tripping to the compact form rather than
+  // expanding to grid-cols-[repeat(3,_minmax(0,_1fr))]. Other track values ("1fr 1fr 1fr",
+  // "repeat(3, 1fr)") have no compact Tailwind spelling and stay arbitrary.
+  if (!className && (root === 'grid-cols' || root === 'grid-rows')) {
+    const repeatMatch = stringValue.match(/^repeat\(\s*([1-9]\d*)\s*,\s*minmax\(\s*0\s*,\s*1fr\s*\)\s*\)$/);
+    if (repeatMatch) {
+      className = `${root}-${repeatMatch[1]}`;
+    } else if (stringValue === 'none' || stringValue === 'subgrid') {
+      className = `${root}-${stringValue}`;
+    }
+  }
+
   // CSS variables: var(--x) → root-(--x). The `font-*` root is shared by font-weight and
   // font-family and is disambiguated by value type — but a `var(--x)` value is ambiguous, so
   // weight/size vars carry a Tailwind data-type hint (`number:` / `length:`) the parser reads
@@ -178,22 +230,41 @@ function propertyValueToClass(prop: string, value: string | number): string | nu
   if (!className) {
     const varMatch = stringValue.match(/^var\((--[\w-]+)\)$/);
     if (varMatch) {
+      const varName = (varMatch[1] ?? '').slice(2); // strip the leading `--`
       if (prop === 'fontSize') className = `text-(length:${varMatch[1]})`;
       else if (prop === 'fontWeight') className = `font-(number:${varMatch[1]})`;
-      else className = `${root}-(${varMatch[1]})`;
+      // The `border`/`outline` roots are shared by a shorthand and a color longhand
+      // (`border` vs `borderColor`). The inverse parser disambiguates by value type, but a
+      // `var(--x)` value is opaque and reads as a color — so `border-(--x)` would round-trip
+      // to `borderColor`. When the prop is the shorthand/width longhand, fall back to the
+      // unambiguous arbitrary-property form (`[border:var(--x)]`), which names it explicitly.
+      else if (rootFormMisresolves(root, prop, stringValue)) {
+        className = `[${camelToKebab(prop)}:${stringValue}]`;
+      }
+      // A `var(--token)` on a color-token prop IS a Meno token reference → emit the bare token
+      // form (`bg-muted`), matching the bare-value path so `var(--muted)` and `muted` agree.
+      // (Token-aware inverse recovers it; palette-shaped names fall through to the var shorthand.)
+      else if (colorTokenProps.has(prop) && isBareColorTokenName(varName)) {
+        className = `${root}-${varName}`;
+      } else className = `${root}-(${varMatch[1]})`;
     }
   }
 
-  // Bare color tokens (Meno convention): color: "primary" → text-(--primary)
-  if (!className && colorTokenProps.has(prop) && isBareColorToken(stringValue)) {
-    className = `${root}-(--${stringValue})`;
+  // Bare color tokens (Meno convention): color: "primary" → text-primary
+  if (!className && colorTokenProps.has(prop) && isBareColorTokenName(stringValue)) {
+    className = `${root}-${stringValue}`;
   }
 
   // Arbitrary value (Tailwind bracket syntax): padding: "92px 0" → p-[92px_0]
   if (!className) {
     const encoded = encodeArbitraryValue(stringValue);
     if (encoded != null) {
-      className = `${root}-[${encoded}]`;
+      // Same shorthand/longhand guard as the var branch: a bare color value bound to the
+      // `border`/`outline` shorthand would parse back as the color longhand, so name the
+      // property explicitly via the arbitrary-property form instead of `root-[…]`.
+      className = rootFormMisresolves(root, prop, stringValue)
+        ? `[${camelToKebab(prop)}:${encoded}]`
+        : `${root}-[${encoded}]`;
     }
   }
 
@@ -235,6 +306,7 @@ export function stylesToClasses(styles: StyleObject | Record<string, string | nu
   const classes: string[] = [];
   for (const prop of sortedProps) {
     const value = styles[prop];
+    if (value === undefined) continue;
     // Skip StyleMapping values - they are resolved at render time, not converted to classes
     if (isStyleMapping(value)) continue;
     const className = propertyValueToClass(prop, value);
@@ -395,7 +467,10 @@ export function responsiveStylesToClasses(
  * Parse a utility class back to CSS property and value
  * Example: "p-[10px]" → { prop: "padding", value: "10px" }
  */
-export function classToStyle(className: string): { prop: string; value: string } | null {
+export function classToStyle(
+  className: string,
+  knownTokens?: ReadonlySet<string>,
+): { prop: string; value: string } | null {
   // Remove responsive variant prefix for parsing (tablet:p-[10px] → p-[10px])
   const { base: cleanClass } = splitVariantPrefix(className);
 
@@ -407,7 +482,7 @@ export function classToStyle(className: string): { prop: string; value: string }
     return presetClassReverse[cleanClass];
   }
 
-  const parsed = parseUtilityClass(cleanClass);
+  const parsed = parseUtilityClass(cleanClass, knownTokens);
 
   if (!parsed) {
     // Dynamic (arbitrary-property hash) classes registered for unknown roots
@@ -451,20 +526,26 @@ export function classToStyle(className: string): { prop: string; value: string }
  * Convert utility classes back to a style object
  * Example: ["p-[10px]", "tablet:p-[24px]"] → { base: { padding: "10px" }, tablet: { padding: "24px" } }
  */
-export function classesToStyles(classes: string[]): ResponsiveStyleObject | null {
+export function classesToStyles(classes: string[], knownTokens?: ReadonlySet<string>): ResponsiveStyleObject | null {
   const styles: ResponsiveStyleObject = { base: {}, tablet: {}, mobile: {} };
 
   for (const className of classes) {
     const { breakpoint: variant, base: cleanClass } = splitVariantPrefix(className);
-    const breakpoint: 'base' | 'tablet' | 'mobile' =
-      variant === 'tablet' ? 'tablet' : variant === 'mobile' ? 'mobile' : 'base';
+    // Accept both the current desktop-first form (`max-tablet:`) and the legacy bare form (`tablet:`).
+    const bp = normalizeBreakpointVariant(variant);
+    const breakpoint: 'base' | 'tablet' | 'mobile' = bp === 'tablet' ? 'tablet' : bp === 'mobile' ? 'mobile' : 'base';
 
-    const styleEntry = classToStyle(cleanClass);
+    const styleEntry = classToStyle(cleanClass, knownTokens);
     if (styleEntry) {
       if (!styles[breakpoint]) {
         styles[breakpoint] = {};
       }
       styles[breakpoint]![styleEntry.prop] = styleEntry.value;
+      // `size-*` is width AND height (no CSS shorthand) — restore both so the editor doesn't
+      // drop height on the next save. classToStyle returns the width half; mirror it to height.
+      if (cleanClass.startsWith('size-') && styleEntry.prop === 'width') {
+        styles[breakpoint]!.height = styleEntry.value;
+      }
     }
   }
 
@@ -472,5 +553,88 @@ export function classesToStyles(classes: string[]): ResponsiveStyleObject | null
   if (Object.keys(styles.tablet || {}).length === 0) delete styles.tablet;
   if (Object.keys(styles.mobile || {}).length === 0) delete styles.mobile;
 
-  return Object.keys(styles.base || {}).length > 0 ? styles : null;
+  // Return the object when ANY breakpoint carries a declaration — not only base. A class string
+  // can legitimately style just a narrower breakpoint (e.g. "tablet:p-[16px]"), and dropping it to
+  // null there would lose class-string styling for that node (class-styling adapter, §11).
+  const hasAny =
+    Object.keys(styles.base || {}).length > 0 ||
+    Object.keys(styles.tablet || {}).length > 0 ||
+    Object.keys(styles.mobile || {}).length > 0;
+  return hasAny ? styles : null;
+}
+
+/**
+ * Whether a single style value can be stored as a STATIC utility class. Static strings (no
+ * `{{template}}`) and numbers can; template-bearing strings and `_mapping` objects cannot — a
+ * template would mint a broken `p-[{{x}}px]`, and a mapping is prop-driven. The latter must stay in
+ * the `style` object (rendered via the runtime var-bridge / `class:list`). This is the boundary that
+ * lets styling default to class storage while keeping dynamic values correct.
+ */
+export function isClassableStyleValue(value: unknown): boolean {
+  if (typeof value === 'number') return true;
+  if (typeof value === 'string') return !value.includes('{{');
+  return false;
+}
+
+function splitStyleBucket(bucket: StyleObject): {
+  classable: StyleObject;
+  residual: StyleObject;
+} {
+  const classable: StyleObject = {};
+  const residual: StyleObject = {};
+  for (const [k, v] of Object.entries(bucket)) {
+    if (isClassableStyleValue(v)) classable[k] = v as string | number;
+    else residual[k] = v as StyleMapping;
+  }
+  return { classable, residual };
+}
+
+/**
+ * Split a style value into the part storable as a utility-class string (static values) and the
+ * residual that must stay in the `style` object (templates + `_mapping`s). Preserves the responsive
+ * shape; a flat object is treated as `base`. Either side is null when it has no declarations. The
+ * canonical home (shared by the studio persistence boundary and the project-wide migration) for the
+ * "what can be a class" decision.
+ */
+export function splitStyleByClassability(style: StyleValue | null | undefined): {
+  classable: ResponsiveStyleObject | null;
+  residual: ResponsiveStyleObject | null;
+} {
+  if (!style || typeof style !== 'object') return { classable: null, residual: null };
+
+  if (isResponsiveStyle(style)) {
+    const classable: ResponsiveStyleObject = {};
+    const residual: ResponsiveStyleObject = {};
+    for (const [bp, bucket] of Object.entries(style)) {
+      if (!bucket || typeof bucket !== 'object') continue;
+      const split = splitStyleBucket(bucket);
+      if (Object.keys(split.classable).length > 0) classable[bp] = split.classable;
+      if (Object.keys(split.residual).length > 0) residual[bp] = split.residual;
+    }
+    return {
+      classable: Object.keys(classable).length > 0 ? classable : null,
+      residual: Object.keys(residual).length > 0 ? residual : null,
+    };
+  }
+
+  const split = splitStyleBucket(style as StyleObject);
+  return {
+    classable: Object.keys(split.classable).length > 0 ? { base: split.classable } : null,
+    residual: Object.keys(split.residual).length > 0 ? { base: split.residual } : null,
+  };
+}
+
+/**
+ * Whether a style value contains at least one prop `_mapping` (in any breakpoint) — flat or
+ * responsive. Prop-driven styling can't be a static utility class, so callers that gate class
+ * conversion (the studio panel, the project migration) check this. Single source of truth.
+ */
+export function styleHasMapping(style: StyleValue | null | undefined): boolean {
+  if (!style || typeof style !== 'object') return false;
+  const buckets = isResponsiveStyle(style) ? Object.values(style) : [style as Record<string, unknown>];
+  for (const bucket of buckets) {
+    if (!bucket || typeof bucket !== 'object') continue;
+    for (const v of Object.values(bucket)) if (isStyleMapping(v)) return true;
+  }
+  return false;
 }

package/lib/shared/utilityClassNames.test.ts

@@ -0,0 +1,38 @@
+import { describe, test, expect } from 'bun:test';
+import { encodeArbitraryValue, decodeArbitraryValue } from './utilityClassNames';
+
+describe('encodeArbitraryValue / decodeArbitraryValue', () => {
+  describe('reversible (decode ∘ encode === identity)', () => {
+    const cases: Array<[string, string]> = [
+      ['single token', '24px'],
+      ['spaces → underscores', '92px 0'],
+      ['multi-token shorthand', '1px solid red'],
+      ['literal underscore escaped', 'slide_in'],
+      ['underscore + spaces', 'fade_in 2s ease'],
+      ['underscore inside url() preserved', 'url(a_b.png)'],
+      ['calc with spaces', 'calc(100% - 24px)'],
+    ];
+    for (const [name, value] of cases) {
+      test(name, () => {
+        const encoded = encodeArbitraryValue(value);
+        expect(encoded).not.toBeNull();
+        // no raw spaces / quotes leak into the class token
+        expect(encoded!).not.toMatch(/[\s"']/);
+        expect(decodeArbitraryValue(encoded!)).toBe(value);
+      });
+    }
+
+    test('literal underscore encodes via the \\_ escape', () => {
+      expect(encodeArbitraryValue('slide_in')).toBe('slide\\_in');
+      expect(encodeArbitraryValue('fade_in 2s ease')).toBe('fade\\_in_2s_ease');
+    });
+  });
+
+  describe('un-encodable → null (defer to side-channel)', () => {
+    for (const value of ['"a a"', "'x'", '[grid]', 'a\\b', 'url("a b.png")']) {
+      test(JSON.stringify(value), () => {
+        expect(encodeArbitraryValue(value)).toBeNull();
+      });
+    }
+  });
+});