regor 1.4.6 → 1.4.7

package/README.md

@@ -105,7 +105,7 @@ This is opt-in and local to the component author:
 
 - it does not change `defineComponent(...)`
 - it validates only the keys you list
-- it throws immediately on the first invalid prop
+- it follows `config.propValidationMode`
 - it does not coerce values
 - it does not mutate `head.props`
 
@@ -156,6 +156,7 @@ pval.oneOf(['create', 'edit'] as const)
 pval.arrayOf(pval.isString)
 pval.shape({ title: pval.isString, count: pval.isNumber })
 pval.refOf(pval.isString)
+pval.fail('title', 'expected non-empty string')
 ```
 
 ### Dynamic bindings and refs
@@ -199,11 +200,11 @@ head.validateProps({
 Users can provide their own validators as long as they match the `PropValidator<T>` signature:
 
 ```ts
-import { type PropValidator } from 'regor'
+import { pval, type PropValidator } from 'regor'
 
 const isNonEmptyString: PropValidator<string> = (value, name) => {
   if (typeof value !== 'string' || value.trim() === '') {
-    throw new Error(`Invalid prop "${name}": expected non-empty string.`)
+    pval.fail(name, 'expected non-empty string')
   }
 }
 
@@ -218,11 +219,34 @@ Custom validators can also use the third `head` argument:
 const startsWithPrefix: PropValidator<string> = (value, name, head) => {
   const ctx = head.requireContext(AppServices)
   if (typeof value !== 'string' || !value.startsWith(ctx.prefix)) {
-    throw new Error(`Invalid prop "${name}": expected prefixed value.`)
+    pval.fail(name, 'expected prefixed value')
   }
 }
 ```
 
+### Validation mode
+
+Validation behavior is controlled through `RegorConfig.propValidationMode`:
+
+```ts
+import { RegorConfig } from 'regor'
+
+const config = new RegorConfig()
+config.propValidationMode = 'warn'
+```
+
+Available modes:
+
+- `'throw'` (default): throw immediately on invalid prop
+- `'warn'`: report through `warningHandler.warning(...)` and continue
+- `'off'`: skip runtime prop validation entirely
+
+Pass the config into `createApp(...)` when you want app-level control:
+
+```ts
+createApp(appContext, template, config)
+```
+
 ## Table Templates and Components
 
 Regor preprocesses table-related templates to keep markup valid when using

package/dist/regor.d.ts

@@ -33,15 +33,23 @@ export type InferPropValidationSchema<TSchema extends Record<string, unknown>> =
 /**
  * Built-in prop-validator namespace used with `head.validateProps(...)`.
  *
+ * This namespace includes both ready-made validators and composition helpers.
+ * Custom validators can also use `pval.fail(...)` to produce the same
+ * structured failure shape as Regor's built-in validators.
+ *
  * Example:
  * ```ts
  * head.validateProps({
  *   title: pval.isString,
  *   count: pval.optional(pval.isNumber),
+ *   meta: pval.shape({
+ *     slug: pval.isString,
+ *   }),
  * })
  * ```
  */
 export declare const pval: {
+	readonly fail: (name: string, message: string) => never;
 	readonly isString: PropValidator<string>;
 	readonly isNumber: PropValidator<number>;
 	readonly isBoolean: PropValidator<boolean>;
@@ -53,6 +61,26 @@ export declare const pval: {
 	readonly shape: <TSchema extends ValidationSchemaLike>(schema: TSchema) => PropValidator<InferPropValidationSchema<TSchema>>;
 	readonly refOf: <TValue>(validator: PropValidator<TValue>) => PropValidator<AnyRef>;
 };
+export type PropValidationMode = "throw" | "warn" | "off";
+export declare class RegorConfig {
+	static getDefault(): RegorConfig;
+	forGrowThreshold: number;
+	globalContext: Record<string, unknown>;
+	useInterpolation: boolean;
+	/**
+	 * 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: PropValidationMode;
+	constructor(globalContext?: Record<string, unknown>);
+	addComponent<TContext extends IRegorContext | object = IRegorContext>(...components: Array<Component<TContext>>): void;
+	setDirectives(prefix: string): void;
+	updateDirectives(updater: (directiveMap: Record<string, Directive>, builtInNames: Record<string, string>) => void): void;
+}
 export type ContextClass<TValue extends object> = abstract new (...args: never[]) => TValue;
 /**
  * Runtime metadata passed to a component's `context(head)` factory.
@@ -164,7 +192,12 @@ export declare class ComponentHead<TContext extends IRegorContext | object = IRe
 	 * Useful when post-assignment normalization is needed.
 	 */
 	onAutoPropsAssigned?: () => void;
-	constructor(props: TContext, element: Element, ctx: IRegorContext[], start: Comment, end: Comment);
+	/**
+	 * Runtime behavior used when `validateProps(...)` encounters invalid input.
+	 * Defaults to `'throw'`.
+	 */
+	__propValidationMode: PropValidationMode;
+	constructor(props: TContext, element: Element, ctx: IRegorContext[], start: Comment, end: Comment, propValidationMode: PropValidationMode);
 	/**
 	 * Emits a custom DOM event from the component host element.
 	 *
@@ -233,7 +266,8 @@ export declare class ComponentHead<TContext extends IRegorContext | object = IRe
 	 * known prop names while still allowing you to validate only a subset.
 	 *
 	 * Validators typically come from `pval`, but custom user validators are also
-	 * supported.
+	 * 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
@@ -243,6 +277,15 @@ export declare class ComponentHead<TContext extends IRegorContext | object = IRe
 	 * })
 	 * ```
 	 *
+	 * 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<TSchema extends PropValidationSchemaFor<TContext>>(schema: TSchema): asserts this is ComponentHead<TContext & InferPropValidationSchema<TSchema>>;
@@ -252,16 +295,6 @@ export declare class ComponentHead<TContext extends IRegorContext | object = IRe
 	 */
 	unmount(): void;
 }
-export declare class RegorConfig {
-	static getDefault(): RegorConfig;
-	forGrowThreshold: number;
-	globalContext: Record<string, unknown>;
-	useInterpolation: boolean;
-	constructor(globalContext?: Record<string, unknown>);
-	addComponent<TContext extends IRegorContext | object = IRegorContext>(...components: Array<Component<TContext>>): void;
-	setDirectives(prefix: string): void;
-	updateDirectives(updater: (directiveMap: Record<string, Directive>, builtInNames: Record<string, string>) => void): void;
-}
 export type IsNull<T> = [
 	T
 ] extends [

package/dist/regor.es2015.cjs.js

@@ -246,9 +246,184 @@ var callUnmounted = (context) => {
   (_b = context.unmounted) == null ? void 0 : _b.call(context);
 };
 
+// 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 {
+  constructor(propPath, detail) {
+    super(detail);
+    __publicField(this, "propPath");
+    __publicField(this, "detail");
+    this.name = "PropValidationError";
+    this.propPath = propPath;
+    this.detail = detail;
+  }
+};
+var fail = (name, message) => {
+  throw new PropValidationError(name, `${message}.`);
+};
+var describeValue = (value) => {
+  var _a;
+  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 = (_a = value == null ? void 0 : value.constructor) == null ? void 0 : _a.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) => {
+  var _a, _b;
+  const tagName = ((_b = (_a = element.tagName) == null ? void 0 : _a.toLowerCase) == null ? void 0 : _b.call(_a)) || "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 {
-  constructor(props, element, ctx, start, end) {
+  constructor(props, element, ctx, start, end, propValidationMode) {
     /**
      * Values provided by parent for this component instance.
      *
@@ -335,6 +510,11 @@ var ComponentHead = class {
      * @internal
      */
     __publicField(this, "__element");
+    /**
+     * Runtime behavior used when `validateProps(...)` encounters invalid input.
+     * Defaults to `'throw'`.
+     */
+    __publicField(this, "__propValidationMode");
     /**
      * Emits a custom DOM event from the component host element.
      *
@@ -358,6 +538,7 @@ var ComponentHead = class {
     this.ctx = ctx;
     this.start = start;
     this.end = end;
+    this.__propValidationMode = propValidationMode;
   }
   /**
    * Finds a parent context instance by constructor type from the captured
@@ -429,7 +610,8 @@ var ComponentHead = class {
    * known prop names while still allowing you to validate only a subset.
    *
    * Validators typically come from `pval`, but custom user validators are also
-   * supported.
+   * 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
@@ -439,15 +621,38 @@ var ComponentHead = class {
    * })
    * ```
    *
+   * 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;
-      validateProp(props[name], name, this);
+      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;
+      }
     }
   }
   /**
@@ -483,33 +688,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 = {};
@@ -915,16 +1093,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,
@@ -1497,7 +1665,8 @@ var ComponentBinder = class {
           component,
           capturedContext,
           startOfComponent,
-          endOfComponent
+          endOfComponent,
+          binder.__config.propValidationMode
         );
         const componentCtx2 = useScope(() => {
           var _a2;
@@ -3925,6 +4094,15 @@ var _RegorConfig = class _RegorConfig {
     __publicField(this, "forGrowThreshold", 10);
     __publicField(this, "globalContext");
     __publicField(this, "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.
+     */
+    __publicField(this, "propValidationMode", "throw");
     this.setDirectives("r-");
     if (globalContext) {
       this.globalContext = globalContext;
@@ -6206,113 +6384,6 @@ var defineComponent = (template, options = {}) => {
   };
 };
 
-// src/app/propValidators.ts
-var fail = (name, message) => {
-  throw new Error(`Invalid prop "${name}": ${message}.`);
-};
-var describeValue = (value) => {
-  var _a;
-  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 = (_a = value == null ? void 0 : value.constructor) == null ? void 0 : _a.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 = {
-  isString: isString2,
-  isNumber,
-  isBoolean,
-  isClass,
-  optional,
-  nullable,
-  oneOf,
-  arrayOf,
-  shape,
-  refOf
-};
-
 // src/composition/ContextRegistry.ts
 var ContextRegistry = class {
   constructor() {