@number10/jsx-core 5.0.0

package/dist/layout/utils/size-resolver.cjs

@@ -0,0 +1,280 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const devConfig = require("../../dev-config.cjs");
+const parseSizeCache = /* @__PURE__ */ new Map();
+const warnedSizes = /* @__PURE__ */ new Set();
+function parseCalcOperand(operand) {
+  const trimmed = operand.trim();
+  const percentMatch = trimmed.match(/^(\d+(?:\.\d+)?)%$/);
+  if (percentMatch && percentMatch[1]) {
+    return { type: "percent", value: parseFloat(percentMatch[1]) };
+  }
+  const vwMatch = trimmed.match(/^(\d+(?:\.\d+)?)vw$/);
+  if (vwMatch && vwMatch[1]) {
+    return { type: "vw", value: parseFloat(vwMatch[1]) };
+  }
+  const vhMatch = trimmed.match(/^(\d+(?:\.\d+)?)vh$/);
+  if (vhMatch && vhMatch[1]) {
+    return { type: "vh", value: parseFloat(vhMatch[1]) };
+  }
+  const pixelMatch = trimmed.match(/^(-?\d+(?:\.\d+)?)(?:px)?$/);
+  if (pixelMatch && pixelMatch[1]) {
+    return { type: "fixed", value: parseFloat(pixelMatch[1]) };
+  }
+  throw new Error(`[Size] Invalid calc operand: "${operand}"`);
+}
+function parseCalcExpression(expr) {
+  expr = expr.replace(/\s+/g, "");
+  function parseExpression(str) {
+    str = str.trim();
+    if (str.startsWith("(") && str.endsWith(")")) {
+      return parseExpression(str.slice(1, -1));
+    }
+    try {
+      return parseCalcOperand(str);
+    } catch {
+    }
+    const operators = ["+", "-", "*", "/"];
+    let parenDepth = 0;
+    let lastOpIndex = -1;
+    let lastOp = "";
+    for (let i = str.length - 1; i >= 0; i--) {
+      const char = str.charAt(i);
+      if (char === ")") parenDepth++;
+      else if (char === "(") parenDepth--;
+      else if (parenDepth === 0 && operators.includes(char)) {
+        if (char === "*" || char === "/" || lastOp !== "*" && lastOp !== "/") {
+          lastOpIndex = i;
+          lastOp = char;
+          if (char === "+" || char === "-") break;
+        }
+      }
+    }
+    if (lastOpIndex === -1) {
+      throw new Error(`[Size] No valid operator found in calc expression: "${str}"`);
+    }
+    const leftStr = str.slice(0, lastOpIndex);
+    const rightStr = str.slice(lastOpIndex + 1);
+    if (!leftStr || !rightStr) {
+      throw new Error(`[Size] Invalid calc expression: "${str}"`);
+    }
+    return {
+      left: parseExpression(leftStr),
+      operator: lastOp,
+      right: parseExpression(rightStr)
+    };
+  }
+  return parseExpression(expr);
+}
+function parseSize(size) {
+  const cached = parseSizeCache.get(size);
+  if (cached !== void 0) {
+    return cached;
+  }
+  const result = parseSizeInternal(size);
+  parseSizeCache.set(size, result);
+  return result;
+}
+function parseSizeInternal(size) {
+  if (size === void 0) {
+    return { type: "auto" };
+  }
+  if (typeof size === "number") {
+    return { type: "fixed", value: size };
+  }
+  if (size === "auto") {
+    return { type: "auto" };
+  }
+  if (size === "fill") {
+    return { type: "fill" };
+  }
+  const calcMatch = size.match(/^calc\((.+)\)$/);
+  if (calcMatch && calcMatch[1]) {
+    return { type: "calc", calc: parseCalcExpression(calcMatch[1]) };
+  }
+  const percentMatch = size.match(/^(\d+(?:\.\d+)?)%$/);
+  if (percentMatch && percentMatch[1]) {
+    const value = parseFloat(percentMatch[1]);
+    if (value < 0 || value > 100) {
+      const warnKey = `percent:${value}`;
+      if (!warnedSizes.has(warnKey)) {
+        warnedSizes.add(warnKey);
+        devConfig.DebugLogger.warn("Size", `Percentage value ${value}% is outside valid range (0-100%)`);
+      }
+    }
+    return { type: "percent", value };
+  }
+  const vwMatch = size.match(/^(\d+(?:\.\d+)?)vw$/);
+  if (vwMatch && vwMatch[1]) {
+    return { type: "vw", value: parseFloat(vwMatch[1]) };
+  }
+  const vhMatch = size.match(/^(\d+(?:\.\d+)?)vh$/);
+  if (vhMatch && vhMatch[1]) {
+    return { type: "vh", value: parseFloat(vhMatch[1]) };
+  }
+  throw new Error(
+    `[Size] Invalid size format: "${size}". Supported formats: number, "X%", "XvW", "Xvh", "calc(...)", "auto", "fill", undefined`
+  );
+}
+function resolveCalcOperand(operand, parentSize, viewportSize) {
+  if ("type" in operand) {
+    if (operand.type === "fixed") {
+      return operand.value;
+    }
+    if (operand.type === "percent") {
+      if (parentSize === void 0) {
+        return 0;
+      }
+      return parentSize * operand.value / 100;
+    }
+    if (operand.type === "vw") {
+      const viewport = viewportSize || { width: 0 };
+      if (!viewport) {
+        devConfig.DebugLogger.warn("Size", "Cannot resolve vw without viewport size. Using 0.");
+        return 0;
+      }
+      return viewport.width * operand.value / 100;
+    }
+    if (operand.type === "vh") {
+      const viewport = viewportSize || { height: 0 };
+      if (!viewport) {
+        devConfig.DebugLogger.warn("Size", "Cannot resolve vh without viewport size. Using 0.");
+        return 0;
+      }
+      return viewport.height * operand.value / 100;
+    }
+    return 0;
+  } else {
+    return resolveCalcExpression(operand, parentSize, viewportSize);
+  }
+}
+function resolveCalcExpression(calc, parentSize, viewportSize) {
+  const left = resolveCalcOperand(calc.left, parentSize, viewportSize);
+  const right = resolveCalcOperand(calc.right, parentSize, viewportSize);
+  switch (calc.operator) {
+    case "+":
+      return left + right;
+    case "-":
+      return left - right;
+    case "*":
+      return left * right;
+    case "/":
+      if (right === 0) {
+        devConfig.DebugLogger.error("Size", "Division by zero in calc expression");
+        return 0;
+      }
+      return left / right;
+    default:
+      devConfig.DebugLogger.error("Size", `Unknown calc operator: ${calc.operator}`);
+      return 0;
+  }
+}
+function resolveSize(parsed, parentSize, contentSize, parentPadding, viewportSize) {
+  switch (parsed.type) {
+    case "fixed":
+      return parsed.value ?? 100;
+    case "percent":
+      if (parentSize === void 0) {
+        if (contentSize === void 0) {
+          devConfig.DebugLogger.warn(
+            "Size",
+            "Cannot resolve percentage without parent size and no content fallback."
+          );
+          return 100;
+        }
+        return contentSize;
+      }
+      return parentSize * (parsed.value ?? 0) / 100;
+    case "vw": {
+      const viewport = viewportSize || { width: 0 };
+      if (!viewport) {
+        devConfig.DebugLogger.warn("Size", "Cannot resolve vw without viewport size. Using fallback 100px");
+        return 100;
+      }
+      return viewport.width * (parsed.value ?? 0) / 100;
+    }
+    case "vh": {
+      const viewport = viewportSize || { height: 0 };
+      if (!viewport) {
+        devConfig.DebugLogger.warn("Size", "Cannot resolve vh without viewport size. Using fallback 100px");
+        return 100;
+      }
+      return viewport.height * (parsed.value ?? 0) / 100;
+    }
+    case "calc":
+      if (!parsed.calc) {
+        devConfig.DebugLogger.error("Size", "Calc type without calc expression");
+        return 100;
+      }
+      return resolveCalcExpression(parsed.calc, parentSize, viewportSize);
+    case "auto":
+      if (contentSize === void 0) {
+        devConfig.DebugLogger.warn("Size", "Auto size without content size, using fallback 100px");
+        return 100;
+      }
+      return contentSize;
+    case "fill": {
+      if (parentSize === void 0) {
+        return 0;
+      }
+      if (parentPadding !== void 0 && parentPadding > 0) {
+        return Math.max(0, parentSize - parentPadding);
+      }
+      return parentSize;
+    }
+    default:
+      devConfig.DebugLogger.error("Size", `Unknown size type: ${parsed.type}`);
+      return 100;
+  }
+}
+function clearSizeCaches() {
+  parseSizeCache.clear();
+  warnedSizes.clear();
+}
+function calcRequiresParent(calc) {
+  const checkOperand = (op) => {
+    if ("type" in op) {
+      return op.type === "percent";
+    } else {
+      return calcRequiresParent(op);
+    }
+  };
+  return checkOperand(calc.left) || checkOperand(calc.right);
+}
+function requiresParent(parsed) {
+  if (parsed.type === "percent" || parsed.type === "fill") {
+    return true;
+  }
+  if (parsed.type === "calc" && parsed.calc) {
+    return calcRequiresParent(parsed.calc);
+  }
+  return false;
+}
+function isExplicit(parsed) {
+  return parsed.type === "fixed" || parsed.type === "percent" || parsed.type === "vw" || parsed.type === "vh" || parsed.type === "calc" || parsed.type === "fill";
+}
+function clampSize(size, minSize, maxSize, parentSize, fallbackSize, parentPadding) {
+  let clamped = size;
+  if (minSize !== void 0) {
+    const parsedMin = parseSize(minSize);
+    const resolvedMin = resolveSize(parsedMin, parentSize, fallbackSize, parentPadding);
+    if (clamped < resolvedMin) {
+      clamped = resolvedMin;
+    }
+  }
+  if (maxSize !== void 0) {
+    const parsedMax = parseSize(maxSize);
+    const resolvedMax = resolveSize(parsedMax, parentSize, fallbackSize, parentPadding);
+    if (clamped > resolvedMax) {
+      clamped = resolvedMax;
+    }
+  }
+  return clamped;
+}
+exports.clampSize = clampSize;
+exports.clearSizeCaches = clearSizeCaches;
+exports.isExplicit = isExplicit;
+exports.parseSize = parseSize;
+exports.requiresParent = requiresParent;
+exports.resolveSize = resolveSize;
+//# sourceMappingURL=size-resolver.cjs.map

package/dist/layout/utils/size-resolver.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"size-resolver.cjs","sources":["../../../src/layout/utils/size-resolver.ts"],"sourcesContent":["/**\n * Size resolution utilities for handling different size value types.\n * Supports fixed pixels, percentages, viewport units (vw/vh), auto sizing, and calc() expressions.\n * Renderer-neutral — viewport dimensions are passed as parameters.\n */\nimport { DebugLogger } from '../../dev-config'\nimport type { CalcExpression, CalcOperand, ParsedSize } from '../types'\n\n// Re-export for convenience\nexport type { ParsedSize } from '../types'\n\n/**\n * Cache for parseSize results to avoid repeated string parsing\n * Key: original size value, Value: parsed size object\n */\nconst parseSizeCache = new Map<unknown, ParsedSize>()\n\n/**\n * Set of size values that already triggered a warning\n * Prevents console spam from repeated warnings for the same invalid value\n */\nconst warnedSizes = new Set<string>()\n\n/**\n * Parse a calc operand (e.g., \"50%\" or \"20px\" or \"100vw\")\n * @param operand - String operand from calc expression\n * @returns Parsed operand\n */\nfunction parseCalcOperand(operand: string): CalcOperand {\n  const trimmed = operand.trim()\n\n  // Percentage: \"50%\"\n  const percentMatch = trimmed.match(/^(\\d+(?:\\.\\d+)?)%$/)\n  if (percentMatch && percentMatch[1]) {\n    return { type: 'percent', value: parseFloat(percentMatch[1]) }\n  }\n\n  // Viewport width: \"100vw\"\n  const vwMatch = trimmed.match(/^(\\d+(?:\\.\\d+)?)vw$/)\n  if (vwMatch && vwMatch[1]) {\n    return { type: 'vw', value: parseFloat(vwMatch[1]) }\n  }\n\n  // Viewport height: \"100vh\"\n  const vhMatch = trimmed.match(/^(\\d+(?:\\.\\d+)?)vh$/)\n  if (vhMatch && vhMatch[1]) {\n    return { type: 'vh', value: parseFloat(vhMatch[1]) }\n  }\n\n  // Fixed pixels: \"20px\" or \"20\"\n  const pixelMatch = trimmed.match(/^(-?\\d+(?:\\.\\d+)?)(?:px)?$/)\n  if (pixelMatch && pixelMatch[1]) {\n    return { type: 'fixed', value: parseFloat(pixelMatch[1]) }\n  }\n\n  throw new Error(`[Size] Invalid calc operand: \"${operand}\"`)\n}\n\n/**\n * Parse a calc() expression\n * @param expr - Calc expression string without \"calc(\" prefix\n * @returns Parsed calc expression\n */\nfunction parseCalcExpression(expr: string): CalcExpression {\n  // Remove spaces\n  expr = expr.replace(/\\s+/g, '')\n\n  // Simple recursive parser for calc expressions\n  function parseExpression(str: string): CalcExpression | CalcOperand {\n    str = str.trim()\n\n    // Handle parentheses\n    if (str.startsWith('(') && str.endsWith(')')) {\n      return parseExpression(str.slice(1, -1))\n    }\n\n    // Check if it's just an operand\n    try {\n      return parseCalcOperand(str)\n    } catch {\n      // Not an operand, continue parsing\n    }\n\n    // Find operators, respecting precedence: * / before + -\n    const operators = ['+', '-', '*', '/']\n    let parenDepth = 0\n    let lastOpIndex = -1\n    let lastOp = ''\n\n    for (let i = str.length - 1; i >= 0; i--) {\n      const char = str.charAt(i)\n      if (char === ')') parenDepth++\n      else if (char === '(') parenDepth--\n      else if (parenDepth === 0 && operators.includes(char)) {\n        // Check precedence: prefer * / over + -\n        if (char === '*' || char === '/' || (lastOp !== '*' && lastOp !== '/')) {\n          lastOpIndex = i\n          lastOp = char\n          if (char === '+' || char === '-') break // Lowest precedence, stop here\n        }\n      }\n    }\n\n    if (lastOpIndex === -1) {\n      throw new Error(`[Size] No valid operator found in calc expression: \"${str}\"`)\n    }\n\n    const leftStr = str.slice(0, lastOpIndex)\n    const rightStr = str.slice(lastOpIndex + 1)\n\n    if (!leftStr || !rightStr) {\n      throw new Error(`[Size] Invalid calc expression: \"${str}\"`)\n    }\n\n    return {\n      left: parseExpression(leftStr),\n      operator: lastOp as '+' | '-' | '*' | '/',\n      right: parseExpression(rightStr),\n    }\n  }\n\n  return parseExpression(expr) as CalcExpression\n}\n\n/**\n * Parse a size value into its components\n * Results are cached to avoid repeated string parsing during layout calculations\n * @param size - Size value (number, string, or undefined)\n * @returns Parsed size information\n * @throws Error if string format is invalid\n *\n * @example\n * parseSize(100)                    // { type: 'fixed', value: 100 }\n * parseSize('50%')                  // { type: 'percent', value: 50 }\n * parseSize('calc(100% - 40px)')    // { type: 'calc', calc: {...} }\n * parseSize(undefined)              // { type: 'auto' }\n * parseSize('auto')                 // { type: 'auto' }\n */\nexport function parseSize(size: number | string | undefined): ParsedSize {\n  // Debug: Track parseSize call frequency\n  // console.log('parseSize called:', size)\n\n  // Check cache first (huge performance win for repeated calls)\n  const cached = parseSizeCache.get(size)\n  if (cached !== undefined) {\n    return cached\n  }\n\n  // Parse the size value\n  const result = parseSizeInternal(size)\n\n  // Cache the result for future calls\n  parseSizeCache.set(size, result)\n\n  return result\n}\n\n/**\n * Internal parsing logic for size values\n * Separated to allow caching in parseSize()\n * @param size - Size value to parse\n * @returns Parsed size information\n */\nfunction parseSizeInternal(size: number | string | undefined): ParsedSize {\n  // undefined -> auto (dynamic based on content)\n  if (size === undefined) {\n    return { type: 'auto' }\n  }\n\n  // number -> fixed pixel value\n  if (typeof size === 'number') {\n    return { type: 'fixed', value: size }\n  }\n\n  // string -> parse format\n  if (size === 'auto') {\n    return { type: 'auto' }\n  }\n\n  if (size === 'fill') {\n    return { type: 'fill' }\n  }\n\n  // Calc expression: \"calc(100% - 40px)\"\n  const calcMatch = size.match(/^calc\\((.+)\\)$/)\n  if (calcMatch && calcMatch[1]) {\n    return { type: 'calc', calc: parseCalcExpression(calcMatch[1]) }\n  }\n\n  // Percentage format: \"50%\", \"75.5%\", \"100%\"\n  const percentMatch = size.match(/^(\\d+(?:\\.\\d+)?)%$/)\n  if (percentMatch && percentMatch[1]) {\n    const value = parseFloat(percentMatch[1])\n    if (value < 0 || value > 100) {\n      // Only warn once per unique invalid value to prevent console spam\n      const warnKey = `percent:${value}`\n      if (!warnedSizes.has(warnKey)) {\n        warnedSizes.add(warnKey)\n        DebugLogger.warn('Size', `Percentage value ${value}% is outside valid range (0-100%)`)\n      }\n    }\n    return { type: 'percent', value }\n  }\n\n  // Viewport width: \"100vw\", \"50vw\"\n  const vwMatch = size.match(/^(\\d+(?:\\.\\d+)?)vw$/)\n  if (vwMatch && vwMatch[1]) {\n    return { type: 'vw', value: parseFloat(vwMatch[1]) }\n  }\n\n  // Viewport height: \"100vh\", \"50vh\"\n  const vhMatch = size.match(/^(\\d+(?:\\.\\d+)?)vh$/)\n  if (vhMatch && vhMatch[1]) {\n    return { type: 'vh', value: parseFloat(vhMatch[1]) }\n  }\n\n  // Unknown format\n  throw new Error(\n    `[Size] Invalid size format: \"${size}\". Supported formats: number, \"X%\", \"XvW\", \"Xvh\", \"calc(...)\", \"auto\", \"fill\", undefined`\n  )\n}\n\n/**\n * Resolve a calc operand to pixel value\n * @param operand - Calc operand or sub-expression\n * @param parentSize - Parent dimension for percentage resolution\n * @param viewportSize - Viewport dimensions for vw/vh resolution\n * @returns Resolved pixel value\n */\nfunction resolveCalcOperand(\n  operand: CalcOperand | CalcExpression,\n  parentSize?: number,\n  viewportSize?: { width: number; height: number }\n): number {\n  if ('type' in operand) {\n    // It's a CalcOperand\n    if (operand.type === 'fixed') {\n      return operand.value\n    }\n\n    // Percentage\n    if (operand.type === 'percent') {\n      if (parentSize === undefined) {\n        return 0\n      }\n      return (parentSize * operand.value) / 100\n    }\n\n    // Viewport width\n    if (operand.type === 'vw') {\n      const viewport = viewportSize || { width: 0, height: 0 }\n      if (!viewport) {\n        DebugLogger.warn('Size', 'Cannot resolve vw without viewport size. Using 0.')\n        return 0\n      }\n      return (viewport.width * operand.value) / 100\n    }\n\n    // Viewport height\n    if (operand.type === 'vh') {\n      const viewport = viewportSize || { width: 0, height: 0 }\n      if (!viewport) {\n        DebugLogger.warn('Size', 'Cannot resolve vh without viewport size. Using 0.')\n        return 0\n      }\n      return (viewport.height * operand.value) / 100\n    }\n\n    return 0\n  } else {\n    // It's a CalcExpression\n    return resolveCalcExpression(operand, parentSize, viewportSize)\n  }\n}\n\n/**\n * Resolve a calc expression to pixel value\n * @param calc - Calc expression\n * @param parentSize - Parent dimension for percentage resolution\n * @param viewportSize - Viewport dimensions for vw/vh resolution\n * @returns Resolved pixel value\n */\nfunction resolveCalcExpression(\n  calc: CalcExpression,\n  parentSize?: number,\n  viewportSize?: { width: number; height: number }\n): number {\n  const left = resolveCalcOperand(calc.left, parentSize, viewportSize)\n  const right = resolveCalcOperand(calc.right, parentSize, viewportSize)\n\n  switch (calc.operator) {\n    case '+':\n      return left + right\n    case '-':\n      return left - right\n    case '*':\n      return left * right\n    case '/':\n      if (right === 0) {\n        DebugLogger.error('Size', 'Division by zero in calc expression')\n        return 0\n      }\n      return left / right\n    default:\n      DebugLogger.error('Size', `Unknown calc operator: ${calc.operator}`)\n      return 0\n  }\n}\n\n/**\n * Resolve a parsed size to actual pixel value\n * @param parsed - Parsed size information\n * @param parentSize - Parent dimension in pixels (required for percentage and calc)\n * @param contentSize - Content dimension in pixels (fallback for auto)\n * @param parentPadding - Parent padding in the relevant direction (for fill)\n * @param viewportSize - Viewport dimensions for vw/vh resolution\n * @returns Resolved size in pixels\n *\n * @example\n * resolveSize({ type: 'fixed', value: 100 }, 200)                    // 100\n * resolveSize({ type: 'percent', value: 50 }, 200)                   // 100 (50% of 200)\n * resolveSize({ type: 'vw', value: 100 }, undefined, undefined, undefined, viewport) // viewport.width\n * resolveSize({ type: 'vh', value: 50 }, undefined, undefined, undefined, viewport)  // viewport.height * 0.5\n * resolveSize({ type: 'calc', calc: {...} }, 200)                    // calc result\n * resolveSize({ type: 'auto' }, 200, 150)                            // 150 (content size)\n * resolveSize({ type: 'fill' }, 200, undefined, 40)                  // 160 (200 - 40)\n */\nexport function resolveSize(\n  parsed: ParsedSize,\n  parentSize?: number,\n  contentSize?: number,\n  parentPadding?: number,\n  viewportSize?: { width: number; height: number }\n): number {\n  switch (parsed.type) {\n    case 'fixed':\n      return parsed.value ?? 100\n\n    case 'percent':\n      if (parentSize === undefined) {\n        // Only warn if we also don't have a fallback content size\n        if (contentSize === undefined) {\n          DebugLogger.warn(\n            'Size',\n            'Cannot resolve percentage without parent size and no content fallback.'\n          )\n          return 100\n        }\n        // Parent size will be available in next layout pass - use content size for now\n        return contentSize\n      }\n      return (parentSize * (parsed.value ?? 0)) / 100\n\n    case 'vw': {\n      const viewport = viewportSize || { width: 0, height: 0 }\n      if (!viewport) {\n        DebugLogger.warn('Size', 'Cannot resolve vw without viewport size. Using fallback 100px')\n        return 100\n      }\n      return (viewport.width * (parsed.value ?? 0)) / 100\n    }\n\n    case 'vh': {\n      const viewport = viewportSize || { width: 0, height: 0 }\n      if (!viewport) {\n        DebugLogger.warn('Size', 'Cannot resolve vh without viewport size. Using fallback 100px')\n        return 100\n      }\n      return (viewport.height * (parsed.value ?? 0)) / 100\n    }\n\n    case 'calc':\n      if (!parsed.calc) {\n        DebugLogger.error('Size', 'Calc type without calc expression')\n        return 100\n      }\n      return resolveCalcExpression(parsed.calc, parentSize, viewportSize)\n\n    case 'auto':\n      if (contentSize === undefined) {\n        DebugLogger.warn('Size', 'Auto size without content size, using fallback 100px')\n        return 100\n      }\n      return contentSize\n\n    case 'fill': {\n      if (parentSize === undefined) {\n        // this would be possible at startup before parent sizes are known, therefore just return 0\n        // DebugLogger.warn('Size', 'Fill size without parent size, using fallback 0px')\n        return 0\n      }\n      // Fill = parent size minus padding (content-area)\n      if (parentPadding !== undefined && parentPadding > 0) {\n        return Math.max(0, parentSize - parentPadding)\n      }\n      // No padding or already content-area\n      return parentSize\n    }\n\n    default:\n      // Should never happen with proper typing\n      DebugLogger.error('Size', `Unknown size type: ${(parsed as ParsedSize).type}`)\n      return 100\n  }\n}\n\n/**\n * Clear the parseSize cache and warning deduplication set\n * Useful for testing or memory management in long-running applications\n *\n * @example\n * ```typescript\n * // Clear caches after major UI rebuild\n * clearSizeCaches()\n * ```\n */\nexport function clearSizeCaches(): void {\n  parseSizeCache.clear()\n  warnedSizes.clear()\n}\n\n/**\n * Check if a calc expression requires parent context\n * @param calc - Calc expression\n * @returns True if expression contains percentages\n */\nfunction calcRequiresParent(calc: CalcExpression): boolean {\n  const checkOperand = (op: CalcOperand | CalcExpression): boolean => {\n    if ('type' in op) {\n      return op.type === 'percent'\n    } else {\n      return calcRequiresParent(op)\n    }\n  }\n  return checkOperand(calc.left) || checkOperand(calc.right)\n}\n\n/**\n * Check if a size needs parent context to resolve\n * @param parsed - Parsed size information\n * @returns True if size requires parent dimension\n */\nexport function requiresParent(parsed: ParsedSize): boolean {\n  if (parsed.type === 'percent' || parsed.type === 'fill') {\n    return true\n  }\n\n  // Calc expressions might contain percentages\n  if (parsed.type === 'calc' && parsed.calc) {\n    return calcRequiresParent(parsed.calc)\n  }\n\n  return false\n}\n\n/**\n * Check if a size can be determined without content measurement\n * @param parsed - Parsed size information\n * @returns True if size is explicitly defined (not auto)\n */\nexport function isExplicit(parsed: ParsedSize): boolean {\n  return (\n    parsed.type === 'fixed' ||\n    parsed.type === 'percent' ||\n    parsed.type === 'vw' ||\n    parsed.type === 'vh' ||\n    parsed.type === 'calc' ||\n    parsed.type === 'fill'\n  )\n}\n\n/**\n * Clamp a size value to min/max constraints\n * Min/max constraints can be SizeValue (pixels, percentage, viewport units, calc)\n * They are resolved relative to the same parent/viewport context as the size itself\n *\n * @param size - Resolved size in pixels\n * @param minSize - Minimum size constraint (SizeValue or undefined = no constraint)\n * @param maxSize - Maximum size constraint (SizeValue or undefined = no constraint)\n * @param parentSize - Parent dimension for percentage resolution in constraints\n * @param fallbackSize - Fallback size for auto constraints (not typically used for min/max)\n * @param parentPadding - Parent padding for fill constraints (not typically used for min/max)\n * @returns Clamped size in pixels\n *\n * @example\n * clampSize(150, 100, 200)  // 150 (within bounds)\n * clampSize(50, 100, 200)   // 100 (clamped to min)\n * clampSize(300, 100, 200)  // 200 (clamped to max)\n * clampSize(150, undefined, \"80%\", 1000)  // 150 (max = 800px)\n * clampSize(1000, undefined, \"80%\", 1000) // 800 (clamped to 80% of parent)\n */\nexport function clampSize(\n  size: number,\n  minSize?: number | string,\n  maxSize?: number | string,\n  parentSize?: number,\n  fallbackSize?: number,\n  parentPadding?: number\n): number {\n  let clamped = size\n\n  // Resolve and apply minimum constraint\n  if (minSize !== undefined) {\n    const parsedMin = parseSize(minSize)\n    const resolvedMin = resolveSize(parsedMin, parentSize, fallbackSize, parentPadding)\n    if (clamped < resolvedMin) {\n      clamped = resolvedMin\n    }\n  }\n\n  // Resolve and apply maximum constraint\n  if (maxSize !== undefined) {\n    const parsedMax = parseSize(maxSize)\n    const resolvedMax = resolveSize(parsedMax, parentSize, fallbackSize, parentPadding)\n    if (clamped > resolvedMax) {\n      clamped = resolvedMax\n    }\n  }\n\n  return clamped\n}\n"],"names":["DebugLogger"],"mappings":"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"}

package/dist/layout/utils/size-resolver.d.ts

@@ -0,0 +1,84 @@
+import { ParsedSize } from '../types';
+export type { ParsedSize } from '../types';
+/**
+ * Parse a size value into its components
+ * Results are cached to avoid repeated string parsing during layout calculations
+ * @param size - Size value (number, string, or undefined)
+ * @returns Parsed size information
+ * @throws Error if string format is invalid
+ *
+ * @example
+ * parseSize(100)                    // { type: 'fixed', value: 100 }
+ * parseSize('50%')                  // { type: 'percent', value: 50 }
+ * parseSize('calc(100% - 40px)')    // { type: 'calc', calc: {...} }
+ * parseSize(undefined)              // { type: 'auto' }
+ * parseSize('auto')                 // { type: 'auto' }
+ */
+export declare function parseSize(size: number | string | undefined): ParsedSize;
+/**
+ * Resolve a parsed size to actual pixel value
+ * @param parsed - Parsed size information
+ * @param parentSize - Parent dimension in pixels (required for percentage and calc)
+ * @param contentSize - Content dimension in pixels (fallback for auto)
+ * @param parentPadding - Parent padding in the relevant direction (for fill)
+ * @param viewportSize - Viewport dimensions for vw/vh resolution
+ * @returns Resolved size in pixels
+ *
+ * @example
+ * resolveSize({ type: 'fixed', value: 100 }, 200)                    // 100
+ * resolveSize({ type: 'percent', value: 50 }, 200)                   // 100 (50% of 200)
+ * resolveSize({ type: 'vw', value: 100 }, undefined, undefined, undefined, viewport) // viewport.width
+ * resolveSize({ type: 'vh', value: 50 }, undefined, undefined, undefined, viewport)  // viewport.height * 0.5
+ * resolveSize({ type: 'calc', calc: {...} }, 200)                    // calc result
+ * resolveSize({ type: 'auto' }, 200, 150)                            // 150 (content size)
+ * resolveSize({ type: 'fill' }, 200, undefined, 40)                  // 160 (200 - 40)
+ */
+export declare function resolveSize(parsed: ParsedSize, parentSize?: number, contentSize?: number, parentPadding?: number, viewportSize?: {
+    width: number;
+    height: number;
+}): number;
+/**
+ * Clear the parseSize cache and warning deduplication set
+ * Useful for testing or memory management in long-running applications
+ *
+ * @example
+ * ```typescript
+ * // Clear caches after major UI rebuild
+ * clearSizeCaches()
+ * ```
+ */
+export declare function clearSizeCaches(): void;
+/**
+ * Check if a size needs parent context to resolve
+ * @param parsed - Parsed size information
+ * @returns True if size requires parent dimension
+ */
+export declare function requiresParent(parsed: ParsedSize): boolean;
+/**
+ * Check if a size can be determined without content measurement
+ * @param parsed - Parsed size information
+ * @returns True if size is explicitly defined (not auto)
+ */
+export declare function isExplicit(parsed: ParsedSize): boolean;
+/**
+ * Clamp a size value to min/max constraints
+ * Min/max constraints can be SizeValue (pixels, percentage, viewport units, calc)
+ * They are resolved relative to the same parent/viewport context as the size itself
+ *
+ * @param size - Resolved size in pixels
+ * @param minSize - Minimum size constraint (SizeValue or undefined = no constraint)
+ * @param maxSize - Maximum size constraint (SizeValue or undefined = no constraint)
+ * @param parentSize - Parent dimension for percentage resolution in constraints
+ * @param fallbackSize - Fallback size for auto constraints (not typically used for min/max)
+ * @param parentPadding - Parent padding for fill constraints (not typically used for min/max)
+ * @returns Clamped size in pixels
+ *
+ * @example
+ * clampSize(150, 100, 200)  // 150 (within bounds)
+ * clampSize(50, 100, 200)   // 100 (clamped to min)
+ * clampSize(300, 100, 200)  // 200 (clamped to max)
+ * clampSize(150, undefined, "80%", 1000)  // 150 (max = 800px)
+ * clampSize(1000, undefined, "80%", 1000) // 800 (clamped to 80% of parent)
+ */
+export declare function clampSize(size: number, minSize?: number | string, maxSize?: number | string, parentSize?: number, fallbackSize?: number, parentPadding?: number): number;
+//# sourceMappingURL=size-resolver.d.ts.map

package/dist/layout/utils/size-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"size-resolver.d.ts","sourceRoot":"","sources":["../../../src/layout/utils/size-resolver.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAA+B,UAAU,EAAE,MAAM,UAAU,CAAA;AAGvE,YAAY,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAmH1C;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,UAAU,CAiBvE;AA0JD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,UAAU,EAClB,UAAU,CAAC,EAAE,MAAM,EACnB,WAAW,CAAC,EAAE,MAAM,EACpB,aAAa,CAAC,EAAE,MAAM,EACtB,YAAY,CAAC,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC/C,MAAM,CAuER;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,IAAI,IAAI,CAGtC;AAkBD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAW1D;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAStD;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,SAAS,CACvB,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,EACzB,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,EACzB,UAAU,CAAC,EAAE,MAAM,EACnB,YAAY,CAAC,EAAE,MAAM,EACrB,aAAa,CAAC,EAAE,MAAM,GACrB,MAAM,CAsBR"}