meno-core 1.0.53 → 1.0.54

package/lib/shared/utilityClassNames.ts

@@ -0,0 +1,326 @@
+/**
+ * Tailwind-style utility class name parsing & value encoding.
+ *
+ * Shared by the forward mapper (utilityClassMapper.ts) and the CSS generator
+ * (cssGeneration.ts) so class names encode and decode identically everywhere.
+ *
+ * Class name grammar (after stripping an optional `breakpoint:` variant):
+ *   - static utilities:      `flex`, `hidden`, `justify-center`, `uppercase`, …
+ *   - presets:               `shadow-2`, `bg-gradient-1`, `border-preset-0`
+ *   - arbitrary values:      `p-[40px]`, `w-[50%]`, `m-[92px_0]` (spaces → `_`)
+ *   - CSS variables:         `bg-(--primary)`, `text-(length:--font-size-lg)`
+ *   - named keywords:        `w-full`, `h-screen`, `m-auto`, `rounded-full`
+ *   - bare numbers:          `z-10`, `order-2`, `opacity-50` (= 0.5)
+ *   - arbitrary properties:  `[clip-path:circle(50%)]`, `[background:…]`
+ *   - hash fallback:         `pt-h1y9pr6i` (value lives in the style-value registry)
+ */
+
+import {
+  prefixToCSSProperty,
+  staticUtilityReverse,
+  presetClassReverse,
+  keywordValues,
+  genericKeywordRoots,
+  integerValueRoots,
+  propertyOrder,
+} from './utilityClassConfig';
+import { isCssNamedColor } from './cssNamedColors';
+
+/** Class roots sorted longest-first so `border-t-…` wins over `border-…`. */
+export const SORTED_ROOTS: readonly string[] = Object.keys(prefixToCSSProperty).sort((a, b) => b.length - a.length);
+
+/** Convert a camelCase style property to its kebab-case CSS name. */
+export function camelToKebab(prop: string): string {
+  return prop.replace(/([A-Z])/g, '-$1').toLowerCase();
+}
+
+// kebab-case CSS property → camelCase style property, for all known properties.
+const kebabToCamelMap: Record<string, string> = (() => {
+  const map: Record<string, string> = {};
+  for (const prop of propertyOrder) {
+    map[camelToKebab(prop)] = prop;
+  }
+  return map;
+})();
+
+/** Convert a kebab-case CSS property back to its camelCase style property. */
+export function cssPropertyToCamel(property: string): string {
+  return kebabToCamelMap[property] ?? property.replace(/-([a-z])/g, (_, c: string) => c.toUpperCase());
+}
+
+/**
+ * Roots that decode to a different camelCase property than their kebab CSS
+ * property suggests (px → paddingInline, not padding).
+ */
+export const ROOT_CAMEL_OVERRIDES: Record<string, string> = {
+  px: 'paddingInline',
+  py: 'paddingBlock',
+  mx: 'marginInline',
+  my: 'marginBlock',
+};
+
+// ---------------------------------------------------------------------------
+// Arbitrary value encoding (Tailwind bracket convention: spaces → underscores)
+// ---------------------------------------------------------------------------
+
+/**
+ * Apply `transform` to every part of `input` that is NOT inside a `url(...)`
+ * segment. Tailwind preserves underscores inside url() — so do we, in both
+ * encode and decode directions.
+ */
+function transformOutsideUrl(input: string, transform: (segment: string) => string): string {
+  let result = '';
+  let i = 0;
+  const lower = input.toLowerCase();
+  while (i < input.length) {
+    const idx = lower.indexOf('url(', i);
+    if (idx === -1) {
+      result += transform(input.slice(i));
+      break;
+    }
+    result += transform(input.slice(i, idx));
+    // Copy the url(...) segment verbatim up to its matching close paren
+    let depth = 0;
+    let j = idx + 3; // position of '('
+    for (; j < input.length; j++) {
+      if (input[j] === '(') depth++;
+      else if (input[j] === ')') {
+        depth--;
+        if (depth === 0) {
+          j++;
+          break;
+        }
+      }
+    }
+    result += input.slice(idx, j);
+    i = j;
+  }
+  return result;
+}
+
+/**
+ * Encode a CSS value for a Tailwind arbitrary-value class: spaces become
+ * underscores (`92px 0` → `92px_0`). Returns null when the value can't be
+ * encoded reversibly (literal underscores outside url(), quotes, brackets,
+ * backslashes, or whitespace inside url()) — callers fall back to a
+ * hash class + style-value registry entry.
+ */
+export function encodeArbitraryValue(value: string): string | null {
+  let ok = true;
+  const encoded = transformOutsideUrl(value, (segment) => {
+    if (/[_"'\\[\]]/.test(segment)) ok = false;
+    return segment.replace(/\s+/g, '_');
+  });
+  if (!ok) return null;
+  // Whitespace/quotes surviving here can only come from inside url(...) —
+  // they would break the class attribute or the decode round-trip.
+  if (/[\s"'\\[\]]/.test(encoded.replace(/^\[|\]$/g, ''))) return null;
+  return encoded;
+}
+
+/** Decode a Tailwind arbitrary value: underscores → spaces (except inside url()). */
+export function decodeArbitraryValue(encoded: string): string {
+  return transformOutsideUrl(encoded, (segment) => segment.replace(/_/g, ' '));
+}
+
+// ---------------------------------------------------------------------------
+// Value-type classification (for roots shared by several properties)
+// ---------------------------------------------------------------------------
+
+const FONT_SIZE_KEYWORDS = new Set([
+  'xx-small',
+  'x-small',
+  'small',
+  'medium',
+  'large',
+  'x-large',
+  'xx-large',
+  'xxx-large',
+  'larger',
+  'smaller',
+]);
+
+/** True when a value reads as a color (hex, color function, named color, var()). */
+export function isColorValue(value: string): boolean {
+  if (value.startsWith('#') || value.startsWith('var(')) return true;
+  if (/^(rgb|rgba|hsl|hsla|oklch|oklab|lab|lch|hwb|color|color-mix)\(/i.test(value)) return true;
+  if (value === 'transparent' || value === 'currentColor' || value === 'currentcolor') return true;
+  return isCssNamedColor(value);
+}
+
+/** True when a `text-…` value reads as a font-size (length/number/keyword). */
+function isFontSizeValue(value: string): boolean {
+  if (/^[\d.+-]/.test(value)) return true;
+  if (/^(calc|clamp|min|max)\(/i.test(value)) return true;
+  return FONT_SIZE_KEYWORDS.has(value);
+}
+
+/** True when a `font-…` value reads as a font-weight (numeric). */
+function isFontWeightValue(value: string): boolean {
+  return /^\d+(\.\d+)?$/.test(value);
+}
+
+/** True when a `bg-…` value reads as a background-image (url()/gradients). */
+function isImageValue(value: string): boolean {
+  return /^(url|linear-gradient|radial-gradient|conic-gradient|repeating-linear-gradient|repeating-radial-gradient|repeating-conic-gradient|image-set|cross-fade|element)\(/i.test(
+    value,
+  );
+}
+
+/** True for a single length token like `2px`, `0.5rem`, `-4px`. */
+function isLengthValue(value: string): boolean {
+  return /^-?[\d.]+[a-z%]*$/i.test(value);
+}
+
+/**
+ * Resolve the CSS property for a class root, disambiguating Tailwind's shared
+ * roots by value type (`text-[14px]` → font-size, `text-[#fff]` → color, …).
+ */
+export function resolveRootProperty(root: string, value: string): string {
+  switch (root) {
+    case 'text':
+      return isFontSizeValue(value) ? 'font-size' : 'color';
+    case 'font':
+      return isFontWeightValue(value) ? 'font-weight' : 'font-family';
+    case 'bg':
+      return isImageValue(value) ? 'background-image' : 'background-color';
+    case 'border':
+      return !value.includes(' ') && isColorValue(value) ? 'border-color' : 'border';
+    case 'outline': {
+      if (value.includes(' ') || value === 'none') return 'outline';
+      if (isColorValue(value)) return 'outline-color';
+      if (isLengthValue(value)) return 'outline-width';
+      return 'outline';
+    }
+    default:
+      return prefixToCSSProperty[root] ?? root;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Breakpoint variant prefix (`tablet:p-[24px]`)
+// ---------------------------------------------------------------------------
+
+/**
+ * Split an optional `breakpoint:` variant prefix off a class name.
+ * Arbitrary-property classes (`[grid-area:hero]`) never match — their colon
+ * sits inside brackets, and the prefix segment must be a bare identifier.
+ */
+export function splitVariantPrefix(className: string): { breakpoint: string | null; base: string } {
+  const match = className.match(/^([a-z][a-z0-9_-]*):(.+)$/);
+  if (match) {
+    return { breakpoint: match[1], base: match[2] };
+  }
+  return { breakpoint: null, base: className };
+}
+
+/** Build the class variant prefix for a breakpoint name: `tablet` → `tablet:`. */
+export function breakpointClassPrefix(breakpointName: string): string {
+  return `${breakpointName.toLowerCase()}:`;
+}
+
+// ---------------------------------------------------------------------------
+// Class name parsing
+// ---------------------------------------------------------------------------
+
+export interface ParsedUtilityClass {
+  /** kebab-case CSS property the class targets */
+  property: string;
+  /** Decoded CSS value; null for hash classes (resolve via style-value registry) */
+  value: string | null;
+  /** The class root (`p`, `text`, `bg`, …); null for statics/presets/arbitrary properties */
+  root: string | null;
+  kind: 'static' | 'preset' | 'arbitrary' | 'var' | 'keyword' | 'numeric' | 'hash' | 'arbitrary-property';
+}
+
+const HASH_VALUE_RE = /^h[0-9a-z]+$/;
+
+/**
+ * Parse a single (unprefixed) utility class name into its CSS property and
+ * decoded value. Returns null for class names that aren't Meno utilities.
+ */
+export function parseUtilityClass(className: string): ParsedUtilityClass | null {
+  const stat = staticUtilityReverse[className];
+  if (stat) {
+    return { property: camelToKebab(stat.prop), value: stat.value, root: null, kind: 'static' };
+  }
+
+  const preset = presetClassReverse[className];
+  if (preset) {
+    return { property: camelToKebab(preset.prop), value: preset.value, root: null, kind: 'preset' };
+  }
+
+  // Arbitrary property: [clip-path:circle(50%)], [background:linear-gradient(…)]
+  const arbProp = className.match(/^\[([a-z-]+):(.+)\]$/);
+  if (arbProp) {
+    return {
+      property: arbProp[1],
+      value: decodeArbitraryValue(arbProp[2]),
+      root: null,
+      kind: 'arbitrary-property',
+    };
+  }
+
+  for (const root of SORTED_ROOTS) {
+    if (!className.startsWith(`${root}-`)) continue;
+    const rest = className.slice(root.length + 1);
+    if (!rest) continue;
+    const parsed = parseRootValue(root, rest);
+    if (parsed) return parsed;
+  }
+
+  return null;
+}
+
+function parseRootValue(root: string, rest: string): ParsedUtilityClass | null {
+  // Arbitrary value: root-[value]
+  if (rest.startsWith('[') && rest.endsWith(']') && rest.length > 2) {
+    const value = decodeArbitraryValue(rest.slice(1, -1));
+    return { property: resolveRootProperty(root, value), value, root, kind: 'arbitrary' };
+  }
+
+  // CSS variable: root-(--name) / root-(length:--name)
+  const varMatch = rest.match(/^\((?:([a-z-]+):)?(--[\w-]+)\)$/);
+  if (varMatch) {
+    const hint = varMatch[1];
+    const value = `var(${varMatch[2]})`;
+    let property: string;
+    if (root === 'text') {
+      property = hint === 'length' ? 'font-size' : 'color';
+    } else if (root === 'font') {
+      // `font-*` is shared by font-weight and font-family; a var value is ambiguous, so the
+      // emitter tags weight vars with a `number:` hint (see utilityClassMapper). Default to
+      // font-family (the original behavior for an un-hinted var like `font-(--l-ff)`).
+      property = hint === 'number' ? 'font-weight' : 'font-family';
+    } else {
+      property = resolveRootProperty(root, value);
+    }
+    return { property, value, root, kind: 'var' };
+  }
+
+  // Named keyword: w-full, m-auto, rounded-full
+  const keyword = keywordValues[root]?.[rest];
+  if (keyword !== undefined) {
+    return { property: resolveRootProperty(root, keyword), value: keyword, root, kind: 'keyword' };
+  }
+
+  // Generic keyword roots: cursor-pointer, align-middle, origin-center, …
+  if (genericKeywordRoots.has(root) && /^[a-z][a-z-]*$/.test(rest)) {
+    return { property: resolveRootProperty(root, rest), value: rest, root, kind: 'keyword' };
+  }
+
+  // Bare numbers: z-10, order-2, flex-2; opacity uses Tailwind's 0–100 scale
+  if (integerValueRoots.has(root) && /^-?\d+$/.test(rest)) {
+    return { property: prefixToCSSProperty[root], value: rest, root, kind: 'numeric' };
+  }
+  if (root === 'opacity' && /^\d{1,3}$/.test(rest)) {
+    return { property: 'opacity', value: String(Number(rest) / 100), root, kind: 'numeric' };
+  }
+
+  // Hash fallback: value lives in the style-value registry
+  if (HASH_VALUE_RE.test(rest)) {
+    return { property: prefixToCSSProperty[root], value: null, root, kind: 'hash' };
+  }
+
+  return null;
+}

package/lib/shared/utils.test.ts

@@ -244,18 +244,10 @@ describe('utils', () => {
 
     test('should handle complex children array', () => {
       const node = {
-        children: [
-          { element: 'div' },
-          { element: 'span' },
-          'text',
-        ],
+        children: [{ element: 'div' }, { element: 'span' }, 'text'],
       };
       normalizeChildrenArray(node);
-      expect(node.children).toEqual([
-        { element: 'div' },
-        { element: 'span' },
-        'text',
-      ]);
+      expect(node.children).toEqual([{ element: 'div' }, { element: 'span' }, 'text']);
     });
   });
 });

package/lib/shared/utils.ts

@@ -20,7 +20,7 @@ export function deepClone<T>(obj: T): T {
  * @param ms - Milliseconds to wait
  */
 export function wait(ms: number): Promise<void> {
-  return new Promise(resolve => setTimeout(resolve, ms));
+  return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
 /**
@@ -50,7 +50,20 @@ export function isEditableElement(): boolean {
   // For inputs, only block shortcuts for text-accepting types
   if (activeElement.tagName === 'INPUT') {
     const inputType = (activeElement as HTMLInputElement).type.toLowerCase();
-    const textInputTypes = ['text', 'password', 'email', 'number', 'search', 'tel', 'url', 'date', 'time', 'datetime-local', 'month', 'week'];
+    const textInputTypes = [
+      'text',
+      'password',
+      'email',
+      'number',
+      'search',
+      'tel',
+      'url',
+      'date',
+      'time',
+      'datetime-local',
+      'month',
+      'week',
+    ];
     // Allow shortcuts for: checkbox, radio, button, submit, reset, color, file, range, hidden
     return textInputTypes.includes(inputType);
   }
@@ -59,10 +72,7 @@ export function isEditableElement(): boolean {
   // This handles rich text editors where focus may be on an internal element
   let element: Element | null = activeElement;
   while (element) {
-    if (
-      element.hasAttribute('contenteditable') ||
-      (element as HTMLElement).isContentEditable
-    ) {
+    if (element.hasAttribute('contenteditable') || (element as HTMLElement).isContentEditable) {
       return true;
     }
     element = element.parentElement;
@@ -75,7 +85,7 @@ export function isEditableElement(): boolean {
  * Extract the parent path from a tree path
  * Example: root_0_children_0 -> root_0, root_0_children_0_children_1 -> root_0_children_0
  * Also accepts array paths: [0,0] -> "root_0", [0,0,1] -> "root_0_children_0"
- * 
+ *
  * @param treePath - The tree path (string or Path array)
  * @param rootPath - The root path constant (default: 'root_0')
  * @returns The parent path, or rootPath if no parent found
@@ -83,12 +93,12 @@ export function isEditableElement(): boolean {
 export function getParentPathFromTreePath(treePath: string | Path, rootPath: string = ROOT_0_STRING): string {
   // Convert to array if needed
   const pathArray = typeof treePath === 'string' ? stringToPath(treePath) : treePath;
-  
+
   // Handle root paths
   if (isRootPathArray(pathArray)) {
     return rootPath;
   }
-  
+
   // Use array operations to get parent path
   const parentArray = getParentPath(pathArray);
   return pathToLegacyString(parentArray);
@@ -109,4 +119,3 @@ export function normalizeChildrenArray(node: { children?: any[] | any }): void {
   }
   // If already an array, no change needed
 }
-

package/lib/shared/validation/cmsValidators.ts

@@ -14,7 +14,8 @@ export const CMS_COLLECTION_ID_REGEX = /^[a-zA-Z0-9_-]+$/;
 /**
  * Zod schema for CMS collection ID validation
  */
-export const CMSCollectionIdSchema = z.string()
+export const CMSCollectionIdSchema = z
+  .string()
   .min(1, 'Collection ID is required')
   .regex(CMS_COLLECTION_ID_REGEX, 'Collection ID must contain only letters, numbers, underscores, and hyphens');
 

package/lib/shared/validation/commentValidators.test.ts

@@ -0,0 +1,53 @@
+import { describe, test, expect } from 'bun:test';
+import { validateComment } from './commentValidators';
+
+/** A minimal valid comment; callers override `anchor` to exercise schema variants. */
+function baseComment(anchor: Record<string, unknown>): Record<string, unknown> {
+  return {
+    _id: 'c1',
+    _filename: 'c1.json',
+    _pagePath: 'index',
+    _seq: 1,
+    _createdAt: '2026-01-01T00:00:00.000Z',
+    _updatedAt: '2026-01-01T00:00:00.000Z',
+    _commitSha: null,
+    anchor,
+    status: 'open',
+    thread: [
+      {
+        id: 't1',
+        author: { login: 'local' },
+        createdAt: '2026-01-01T00:00:00.000Z',
+        text: 'hi',
+        statusChange: null,
+      },
+    ],
+  };
+}
+
+const pageLevelAnchor = {
+  nodePath: [0, 1],
+  nodeIdentity: { kind: 'node', name: 'div' },
+  offsetXPercent: 0.5,
+  offsetYPercent: 0.5,
+};
+
+describe('validateComment — element anchor identity', () => {
+  test('accepts a comment WITHOUT a cmsItemIndexPath (element not in a list)', () => {
+    const result = validateComment(baseComment(pageLevelAnchor));
+    expect(result.valid).toBe(true);
+    if (result.valid) expect(result.data.anchor.cmsItemIndexPath).toBeUndefined();
+  });
+
+  test('accepts and round-trips a comment WITH a cmsItemIndexPath', () => {
+    const cmsItemIndexPath = [0, 2];
+    const result = validateComment(baseComment({ ...pageLevelAnchor, cmsItemIndexPath }));
+    expect(result.valid).toBe(true);
+    if (result.valid) expect(result.data.anchor.cmsItemIndexPath).toEqual(cmsItemIndexPath);
+  });
+
+  test('rejects a malformed cmsItemIndexPath (non-number entries)', () => {
+    const result = validateComment(baseComment({ ...pageLevelAnchor, cmsItemIndexPath: ['a', 'b'] }));
+    expect(result.valid).toBe(false);
+  });
+});

package/lib/shared/validation/commentValidators.ts

@@ -23,8 +23,19 @@ export const CommentNodeIdentitySchema = z.object({
   label: z.string().optional(),
 });
 
+export const CommentNodeRefSegmentSchema = z.object({
+  kind: z.enum(['component', 'node']),
+  name: z.string().min(1),
+  nth: z.number().int().nonnegative(),
+});
+
 export const CommentAnchorSchema = z.object({
+  // Type + occurrence path (move-resilient source of truth). Must be declared
+  // (z.object strips unknown keys) so it round-trips to disk.
+  nodeRef: z.array(CommentNodeRefSegmentSchema).optional(),
   nodePath: z.array(z.number().int().nonnegative()),
+  // CMS-list item path disambiguating which list copy the element belongs to.
+  cmsItemIndexPath: z.array(z.number().int().nonnegative()).optional(),
   nodeIdentity: CommentNodeIdentitySchema,
   offsetXPercent: z.number().min(0).max(1),
   offsetYPercent: z.number().min(0).max(1),
@@ -53,7 +64,7 @@ export const CommentSchema = z.object({
 });
 
 function zodToValidationErrors(zodError: ZodError): ValidationError[] {
-  return zodError.errors.map(err => ({
+  return zodError.errors.map((err) => ({
     path: err.path.join('.') || 'root',
     message: err.message,
     code: 'INVALID_TYPE' as const,

package/lib/shared/validation/propValidator.test.ts

@@ -14,9 +14,9 @@ describe('Prop Validator', () => {
         title: { type: 'string', default: 'Hello' },
       };
       const passedProps = { title: 'World' };
-      
+
       const result = validateComponentProps(propDefs, passedProps);
-      
+
       expect(result.valid).toBe(true);
       expect(result.props.title).toBe('World');
     });
@@ -26,9 +26,9 @@ describe('Prop Validator', () => {
         count: { type: 'number', default: 0 },
       };
       const passedProps = { count: 42 };
-      
+
       const result = validateComponentProps(propDefs, passedProps);
-      
+
       expect(result.valid).toBe(true);
       expect(result.props.count).toBe(42);
     });
@@ -38,9 +38,9 @@ describe('Prop Validator', () => {
         enabled: { type: 'boolean', default: false },
       };
       const passedProps = { enabled: true };
-      
+
       const result = validateComponentProps(propDefs, passedProps);
-      
+
       expect(result.valid).toBe(true);
       expect(result.props.enabled).toBe(true);
     });
@@ -54,9 +54,9 @@ describe('Prop Validator', () => {
         },
       };
       const passedProps = { variant: 'secondary' };
-      
+
       const result = validateComponentProps(propDefs, passedProps);
-      
+
       expect(result.valid).toBe(true);
       expect(result.props.variant).toBe('secondary');
     });
@@ -68,9 +68,9 @@ describe('Prop Validator', () => {
         title: { type: 'string', default: 'Hello' },
       };
       const passedProps = { title: 123 };
-      
+
       const result = validateComponentProps(propDefs, passedProps);
-      
+
       // Coercion makes this valid (123 -> "123")
       expect(result.valid).toBe(true);
       expect(result.props.title).toBe('123');
@@ -121,9 +121,9 @@ describe('Prop Validator', () => {
         count: { type: 'number', default: 0 },
       };
       const passedProps = { count: '123' };
-      
+
       const result = validateComponentProps(propDefs, passedProps);
-      
+
       expect(result.valid).toBe(true);
       expect(result.props.count).toBe(123);
       expect(typeof result.props.count).toBe('number');
@@ -134,9 +134,9 @@ describe('Prop Validator', () => {
         enabled: { type: 'boolean', default: false },
       };
       const passedProps = { enabled: 'true' };
-      
+
       const result = validateComponentProps(propDefs, passedProps);
-      
+
       expect(result.valid).toBe(true);
       expect(result.props.enabled).toBe(true);
       expect(typeof result.props.enabled).toBe('boolean');
@@ -243,9 +243,9 @@ describe('Prop Validator', () => {
         unknownProp: 'allowed',
         anotherUnknown: 123,
       };
-      
+
       const result = validateComponentProps(propDefs, passedProps);
-      
+
       // Should be valid (unknown props don't fail validation)
       expect(result.valid).toBe(true);
       // Unknown props should be preserved
@@ -259,14 +259,12 @@ describe('Prop Validator', () => {
         count: { type: 'number', default: 42 },
       };
       const passedProps = {};
-      
+
       const result = validateComponentProps(propDefs, passedProps);
-      
+
       expect(result.valid).toBe(true);
       expect(result.props.title).toBe('Hello');
       expect(result.props.count).toBe(42);
     });
   });
 });
-
-