regor 1.4.5 → 1.4.7

package/dist/regor.es2022.iife.js

@@ -49,6 +49,7 @@ var Regor = (() => {
     onUnmounted: () => onUnmounted,
     pause: () => pause,
     persist: () => persist,
+    pval: () => pval,
     raw: () => raw,
     ref: () => ref,
     removeNode: () => removeNode,
@@ -205,7 +206,180 @@ var Regor = (() => {
     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.
@@ -293,12 +467,18 @@ var Regor = (() => {
      * @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.
@@ -377,6 +557,61 @@ var Regor = (() => {
         `${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.
@@ -410,33 +645,6 @@ var Regor = (() => {
     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 = {};
@@ -840,16 +1048,6 @@ var Regor = (() => {
     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,
@@ -1417,7 +1615,8 @@ var Regor = (() => {
             component,
             capturedContext,
             startOfComponent,
-            endOfComponent
+            endOfComponent,
+            binder.__config.propValidationMode
           );
           const componentCtx2 = useScope(() => {
             return registeredComponent.context(head2) ?? {};
@@ -2933,11 +3132,11 @@ var Regor = (() => {
       }
       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);
     }
   };
 
@@ -3187,7 +3386,7 @@ var Regor = (() => {
   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();
@@ -3217,7 +3416,7 @@ var Regor = (() => {
       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 {
@@ -3831,6 +4030,15 @@ var Regor = (() => {
     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) {
@@ -4522,12 +4730,12 @@ var Regor = (() => {
       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;
@@ -4553,7 +4761,7 @@ var Regor = (() => {
             callee: node
           };
         } else {
-          if (optional) {
+          if (optional2) {
             this.__index--;
           }
           this.__gobbleSpaces();
@@ -4564,7 +4772,7 @@ var Regor = (() => {
             property: this.__gobbleIdentifier()
           };
         }
-        if (optional) {
+        if (optional2) {
           node.optional = true;
         }
         this.__gobbleSpaces();