regor 1.4.5 → 1.4.7

package/dist/regor.es2022.esm.js

@@ -137,7 +137,180 @@ var callUnmounted = (context) => {
   context.unmounted?.();
 };
 
+// src/log/warnings.ts
+var warnings = {
+  [8 /* ModelRequiresRef */]: (el) => `Model binding requires a ref at ${el.outerHTML}`,
+  [7 /* ModelNotSupportOnElement */]: (el) => `Model binding is not supported on ${el.tagName} element at ${el.outerHTML}`,
+  [0 /* MissingBindingExpression */]: (name, el) => `${name} binding expression is missing at ${el.outerHTML}`,
+  [1 /* InvalidForExpression */]: (name, forPath, el) => `invalid ${name} expression: ${forPath} at ${el.outerHTML}`,
+  [2 /* BindingRequiresObjectExpressions */]: (name, el) => `${name} requires object expression at ${el.outerHTML}`,
+  [3 /* KeyIsEmpty */]: (name, el) => `${name} binder: key is empty on ${el.outerHTML}.`,
+  [4 /* PropertyAssignmentFailed */]: (key, tag, value, e) => ({
+    msg: `Failed setting prop "${key}" on <${tag.toLowerCase()}>: value ${value} is invalid.`,
+    args: [e]
+  }),
+  [5 /* MissingEventType */]: (name, el) => `${name} binding missing event type at ${el.outerHTML}`,
+  [6 /* ErrorLog */]: (msg, e) => ({ msg, args: [e] })
+};
+var warning = (type, ...args) => {
+  const msg = warnings[type];
+  const item = isFunction(msg) ? msg.call(warnings, ...args) : msg;
+  const handler = warningHandler.warning;
+  if (!handler) return;
+  if (isString(item)) handler(item);
+  else handler(item, ...item.args);
+};
+var warningHandler = {
+  warning: console.warn
+};
+
+// src/reactivity/refSymbols.ts
+var refSymbol = Symbol("ref");
+var srefSymbol = Symbol("sref");
+var rawSymbol = Symbol("raw");
+
+// src/reactivity/isRef.ts
+var isRef = (value) => {
+  return value != null && value[srefSymbol] === 1;
+};
+
+// src/app/propValidators.ts
+var PropValidationError = class extends Error {
+  propPath;
+  detail;
+  constructor(propPath, detail) {
+    super(detail);
+    this.name = "PropValidationError";
+    this.propPath = propPath;
+    this.detail = detail;
+  }
+};
+var fail = (name, message) => {
+  throw new PropValidationError(name, `${message}.`);
+};
+var describeValue = (value) => {
+  if (value === null) return "null";
+  if (value === void 0) return "undefined";
+  if (typeof value === "string") return "string";
+  if (typeof value === "number") return "number";
+  if (typeof value === "boolean") return "boolean";
+  if (typeof value === "bigint") return "bigint";
+  if (typeof value === "symbol") return "symbol";
+  if (typeof value === "function") return "function";
+  if (isArray(value)) return "array";
+  if (value instanceof Date) return "Date";
+  if (value instanceof RegExp) return "RegExp";
+  if (value instanceof Map) return "Map";
+  if (value instanceof Set) return "Set";
+  const ctorName = value?.constructor?.name;
+  return ctorName && ctorName !== "Object" ? ctorName : "object";
+};
+var formatLiteral = (value) => {
+  if (typeof value === "string") return `"${value}"`;
+  if (typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+  if (value === null) return "null";
+  if (value === void 0) return "undefined";
+  return describeValue(value);
+};
+var isString2 = (value, name) => {
+  if (typeof value !== "string") fail(name, "expected string");
+};
+var isNumber = (value, name) => {
+  if (typeof value !== "number") fail(name, "expected number");
+};
+var isBoolean = (value, name) => {
+  if (typeof value !== "boolean") fail(name, "expected boolean");
+};
+var isClass = (ctor) => {
+  return (value, name) => {
+    if (!(value instanceof ctor)) {
+      fail(name, `expected instance of ${ctor.name || "provided class"}`);
+    }
+  };
+};
+var optional = (validator) => {
+  return (value, name, head) => {
+    if (value === void 0) return;
+    validator(value, name, head);
+  };
+};
+var nullable = (validator) => {
+  return (value, name, head) => {
+    if (value === null) return;
+    validator(value, name, head);
+  };
+};
+var oneOf = (values) => {
+  return (value, name) => {
+    if (values.includes(value)) return;
+    fail(
+      name,
+      `expected one of ${values.map((x) => formatLiteral(x)).join(", ")}`
+    );
+  };
+};
+var arrayOf = (validator) => {
+  return (value, name, head) => {
+    if (!isArray(value)) fail(name, "expected array");
+    const items = value;
+    for (let i = 0; i < items.length; ++i) {
+      validator(items[i], `${name}[${i}]`, head);
+    }
+  };
+};
+var shape = (schema) => {
+  return (value, name, head) => {
+    if (!isObject(value)) fail(name, "expected object");
+    const record = value;
+    for (const key in schema) {
+      const validator = schema[key];
+      validator(record[key], `${name}.${key}`, head);
+    }
+  };
+};
+var refOf = (validator) => {
+  return (value, name, head) => {
+    if (!isRef(value)) fail(name, "expected ref");
+    const refValue = value;
+    validator(refValue(), `${name}.value`, head);
+  };
+};
+var pval = {
+  fail,
+  isString: isString2,
+  isNumber,
+  isBoolean,
+  isClass,
+  optional,
+  nullable,
+  oneOf,
+  arrayOf,
+  shape,
+  refOf
+};
+
 // src/app/ComponentHead.ts
+var formatComponentValidationError = (element, propName, error) => {
+  const tagName = element.tagName?.toLowerCase?.() || "unknown";
+  const finalPropName = error instanceof PropValidationError ? error.propPath : propName;
+  const detail = error instanceof PropValidationError ? error.detail : error instanceof Error ? error.message : String(error);
+  if (error instanceof Error) {
+    return new Error(
+      `Invalid prop "${finalPropName}" on <${tagName}>: ${detail}`,
+      {
+        cause: error
+      }
+    );
+  }
+  return new Error(
+    `Invalid prop "${finalPropName}" on <${tagName}>: ${detail}`,
+    {
+      cause: error
+    }
+  );
+};
 var ComponentHead = class {
   /**
    * Values provided by parent for this component instance.
@@ -225,12 +398,18 @@ var ComponentHead = class {
    * @internal
    */
   __element;
-  constructor(props, element, ctx, start, end) {
+  /**
+   * Runtime behavior used when `validateProps(...)` encounters invalid input.
+   * Defaults to `'throw'`.
+   */
+  __propValidationMode;
+  constructor(props, element, ctx, start, end, propValidationMode) {
     this.props = props;
     this.__element = element;
     this.ctx = ctx;
     this.start = start;
     this.end = end;
+    this.__propValidationMode = propValidationMode;
   }
   /**
    * Emits a custom DOM event from the component host element.
@@ -309,6 +488,61 @@ var ComponentHead = class {
       `${constructor} was not found in the context stack at occurrence ${occurrence}.`
     );
   }
+  /**
+   * Validates selected incoming props using assertion-style validators.
+   *
+   * Only keys listed in `schema` are checked. Validation throws immediately
+   * on the first invalid prop and does not mutate `head.props`.
+   *
+   * The schema is keyed from `head.props`, so editor completion can suggest
+   * known prop names while still allowing you to validate only a subset.
+   *
+   * Validators typically come from `pval`, but custom user validators are also
+   * supported. Custom validators may throw their own `Error`, though `pval.fail(...)`
+   * is recommended so nested validators can preserve the exact failing prop path.
+   *
+   * Example:
+   * ```ts
+   * head.validateProps({
+   *   title: pval.isString,
+   *   count: pval.optional(pval.isNumber),
+   * })
+   * ```
+   *
+   * Example with a custom validator:
+   * ```ts
+   * const isNonEmptyString: PropValidator<string> = (value, name) => {
+   *   if (typeof value !== 'string' || value.trim() === '') {
+   *     pval.fail(name, 'expected non-empty string')
+   *   }
+   * }
+   * ```
+   *
+   * @param schema - Validators to apply to selected incoming props.
+   */
+  validateProps(schema) {
+    if (this.__propValidationMode === "off") return;
+    const props = this.props;
+    for (const name in schema) {
+      const validator = schema[name];
+      if (!validator) continue;
+      const validateProp = validator;
+      try {
+        validateProp(props[name], name, this);
+      } catch (error) {
+        const enrichedError = formatComponentValidationError(
+          this.__element,
+          name,
+          error
+        );
+        if (this.__propValidationMode === "warn") {
+          warningHandler.warning(enrichedError.message, enrichedError);
+          continue;
+        }
+        throw enrichedError;
+      }
+    }
+  }
   /**
    * Unmounts this component instance by removing nodes between `start` and `end`
    * and calling unmount lifecycle handlers for captured contexts.
@@ -342,33 +576,6 @@ var addUnbinder = (node, unbinder) => {
   getBindData(node).unbinders.push(unbinder);
 };
 
-// src/log/warnings.ts
-var warnings = {
-  [8 /* ModelRequiresRef */]: (el) => `Model binding requires a ref at ${el.outerHTML}`,
-  [7 /* ModelNotSupportOnElement */]: (el) => `Model binding is not supported on ${el.tagName} element at ${el.outerHTML}`,
-  [0 /* MissingBindingExpression */]: (name, el) => `${name} binding expression is missing at ${el.outerHTML}`,
-  [1 /* InvalidForExpression */]: (name, forPath, el) => `invalid ${name} expression: ${forPath} at ${el.outerHTML}`,
-  [2 /* BindingRequiresObjectExpressions */]: (name, el) => `${name} requires object expression at ${el.outerHTML}`,
-  [3 /* KeyIsEmpty */]: (name, el) => `${name} binder: key is empty on ${el.outerHTML}.`,
-  [4 /* PropertyAssignmentFailed */]: (key, tag, value, e) => ({
-    msg: `Failed setting prop "${key}" on <${tag.toLowerCase()}>: value ${value} is invalid.`,
-    args: [e]
-  }),
-  [5 /* MissingEventType */]: (name, el) => `${name} binding missing event type at ${el.outerHTML}`,
-  [6 /* ErrorLog */]: (msg, e) => ({ msg, args: [e] })
-};
-var warning = (type, ...args) => {
-  const msg = warnings[type];
-  const item = isFunction(msg) ? msg.call(warnings, ...args) : msg;
-  const handler = warningHandler.warning;
-  if (!handler) return;
-  if (isString(item)) handler(item);
-  else handler(item, ...item.args);
-};
-var warningHandler = {
-  warning: console.warn
-};
-
 // src/bind/switch.ts
 var switches = {};
 var switchCounter = {};
@@ -772,16 +979,6 @@ var isScope = (value) => {
   return scopeSymbol2 in value;
 };
 
-// src/reactivity/refSymbols.ts
-var refSymbol = Symbol("ref");
-var srefSymbol = Symbol("sref");
-var rawSymbol = Symbol("raw");
-
-// src/reactivity/isRef.ts
-var isRef = (value) => {
-  return value != null && value[srefSymbol] === 1;
-};
-
 // src/directives/context.ts
 var contextDirective = {
   collectRefObj: true,
@@ -1349,7 +1546,8 @@ var ComponentBinder = class {
           component,
           capturedContext,
           startOfComponent,
-          endOfComponent
+          endOfComponent,
+          binder.__config.propValidationMode
         );
         const componentCtx2 = useScope(() => {
           return registeredComponent.context(head2) ?? {};
@@ -2865,11 +3063,11 @@ var patchAttribute = (el, key, value, previousKey) => {
     }
     return;
   }
-  const isBoolean = key in booleanAttributes;
-  if (isNullOrUndefined(value) || isBoolean && !includeBooleanAttr(value)) {
+  const isBoolean2 = key in booleanAttributes;
+  if (isNullOrUndefined(value) || isBoolean2 && !includeBooleanAttr(value)) {
     el.removeAttribute(key);
   } else {
-    el.setAttribute(key, isBoolean ? "" : value);
+    el.setAttribute(key, isBoolean2 ? "" : value);
   }
 };
 
@@ -3119,7 +3317,7 @@ var decimalSeparators = /[.,' ·٫]/;
 var handleInputAndTextArea = (el, flags, getModelRef, parsedValue) => {
   const isLazy = flags.lazy;
   const eventType = isLazy ? "change" : "input";
-  const isNumber = isNumberInput(el);
+  const isNumber2 = isNumberInput(el);
   const trimmer = () => {
     if (!flags.trim && !getFlags(parsedValue()[1]).trim) return;
     el.value = el.value.trim();
@@ -3149,7 +3347,7 @@ var handleInputAndTextArea = (el, flags, getModelRef, parsedValue) => {
     if (!target || target.composing) return;
     let value = target.value;
     const flags2 = getFlags(parsedValue()[1]);
-    if (isNumber || flags2.number || flags2.int) {
+    if (isNumber2 || flags2.number || flags2.int) {
       if (flags2.int) {
         value = parseInt(value);
       } else {
@@ -3763,6 +3961,15 @@ var RegorConfig = class _RegorConfig {
   forGrowThreshold = 10;
   globalContext;
   useInterpolation = true;
+  /**
+   * Controls how `head.validateProps(...)` behaves when a validator fails.
+   *
+   * - `'throw'` (default): rethrows the validation error immediately.
+   * - `'warn'`: forwards the validation error to `warningHandler.warning(...)`
+   *   and continues.
+   * - `'off'`: skips runtime prop validation entirely.
+   */
+  propValidationMode = "throw";
   constructor(globalContext) {
     this.setDirectives("r-");
     if (globalContext) {
@@ -4454,12 +4661,12 @@ var Jsep = class {
     this.__gobbleSpaces();
     let ch = this.__code;
     while (ch === PERIOD_CODE || ch === OBRACK_CODE || ch === OPAREN_CODE || ch === QUMARK_CODE) {
-      let optional;
+      let optional2;
       if (ch === QUMARK_CODE) {
         if (this.__expr.charCodeAt(this.__index + 1) !== PERIOD_CODE) {
           break;
         }
-        optional = true;
+        optional2 = true;
         this.__index += 2;
         this.__gobbleSpaces();
         ch = this.__code;
@@ -4485,7 +4692,7 @@ var Jsep = class {
           callee: node
         };
       } else {
-        if (optional) {
+        if (optional2) {
           this.__index--;
         }
         this.__gobbleSpaces();
@@ -4496,7 +4703,7 @@ var Jsep = class {
           property: this.__gobbleIdentifier()
         };
       }
-      if (optional) {
+      if (optional2) {
         node.optional = true;
       }
       this.__gobbleSpaces();
@@ -6350,6 +6557,7 @@ export {
   onUnmounted,
   pause,
   persist,
+  pval,
   raw,
   ref,
   removeNode,