regor 1.4.5 → 1.4.6

package/README.md

@@ -97,6 +97,132 @@ HTML:
 </div>
 ```
 
+## Component Props Validation
+
+Regor components can validate incoming props at runtime inside `context(head)`.
+
+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 does not coerce values
+- it does not mutate `head.props`
+
+Use `head.validateProps(...)` together with `pval`:
+
+```ts
+import { defineComponent, html, pval } from 'regor'
+
+type EditorCard = {
+  title: string
+  count?: number
+  mode: 'create' | 'edit'
+  summary?: string
+}
+
+const editorCard = defineComponent<EditorCard>(
+  html`<article>{{ summary }}</article>`,
+  {
+    props: ['title', 'count', 'mode'],
+    context: (head) => {
+      head.validateProps({
+        title: pval.isString,
+        count: pval.optional(pval.isNumber),
+        mode: pval.oneOf(['create', 'edit'] as const),
+      })
+
+      return {
+        ...head.props,
+        summary: `${head.props.title}:${head.props.mode}:${head.props.count ?? 'none'}`,
+      }
+    },
+  },
+)
+```
+
+### Built-in validators
+
+```ts
+import { pval } from 'regor'
+
+pval.isString
+pval.isNumber
+pval.isBoolean
+pval.isClass(MyClass)
+pval.optional(pval.isString)
+pval.nullable(pval.isNumber)
+pval.oneOf(['create', 'edit'] as const)
+pval.arrayOf(pval.isString)
+pval.shape({ title: pval.isString, count: pval.isNumber })
+pval.refOf(pval.isString)
+```
+
+### Dynamic bindings and refs
+
+Single-prop dynamic bindings like `:title="titleRef"` flow into component props as refs.
+When validating those runtime values, use `pval.refOf(...)`:
+
+```ts
+type CardProps = {
+  title: Ref<string>
+  summary?: string
+}
+
+const card = defineComponent<CardProps>(html`<h3>{{ summary }}</h3>`, {
+  props: ['title'],
+  context: (head) => {
+    head.validateProps({
+      title: pval.refOf(pval.isString),
+    })
+
+    return {
+      ...head.props,
+      summary: head.props.title(),
+    }
+  },
+})
+```
+
+For object-style `:context="{ ... }"` values, validate the plain runtime shape directly:
+
+```ts
+head.validateProps({
+  meta: pval.shape({
+    slug: pval.isString,
+  }),
+})
+```
+
+### Custom validators
+
+Users can provide their own validators as long as they match the `PropValidator<T>` signature:
+
+```ts
+import { 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.`)
+  }
+}
+
+head.validateProps({
+  title: isNonEmptyString,
+})
+```
+
+Custom validators can also use the third `head` argument:
+
+```ts
+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.`)
+  }
+}
+```
+
 ## Table Templates and Components
 
 Regor preprocesses table-related templates to keep markup valid when using
@@ -223,6 +349,7 @@ These directives empower you to create dynamic and interactive user interfaces,
 
 - **`createApp`** Similar to Vue's `createApp`, it initializes a Regor application instance.
 - **`defineComponent`** Creates a Regor component instance.
+- **`pval`** Built-in component prop validators used with `head.validateProps(...)`.
 - **`toFragment`** Converts a JSON template to a document fragment.
 - **`toJsonTemplate`** Converts a DOM element to a JSON template.
 

package/dist/regor.d.ts

@@ -1,5 +1,58 @@
 // Generated by dts-bundle-generator v9.5.1
 
+/**
+ * Assertion-style runtime validator used by `head.validateProps(...)`.
+ *
+ * A validator should throw when the value is invalid and return normally when
+ * the value satisfies the expected runtime contract.
+ *
+ * @typeParam TValue - Value type asserted by the validator when it succeeds.
+ * @param value - Raw incoming prop value.
+ * @param name - Prop name or nested path currently being validated.
+ * @param head - Current component head, useful for context-aware validation.
+ */
+export type PropValidator<TValue = unknown> = (value: unknown, name: string, head: ComponentHead<any>) => asserts value is TValue;
+export type ValidationSchemaLike = Record<string, PropValidator<any>>;
+/**
+ * Validation schema shape suggested by `ComponentHead<T>.props`.
+ *
+ * Every key is optional so component authors can validate only the subset they
+ * care about. Editor completion is still driven by the known prop keys.
+ */
+export type PropValidationSchemaFor<TProps extends object> = {
+	[TKey in keyof TProps]?: PropValidator<TProps[TKey]>;
+};
+/**
+ * Infers the asserted value types from a validation schema.
+ *
+ * Keys whose values are not validators are ignored.
+ */
+export type InferPropValidationSchema<TSchema extends Record<string, unknown>> = {
+	[TKey in keyof TSchema as TSchema[TKey] extends PropValidator<any> ? TKey : never]: TSchema[TKey] extends PropValidator<infer TValue> ? TValue : never;
+};
+/**
+ * Built-in prop-validator namespace used with `head.validateProps(...)`.
+ *
+ * Example:
+ * ```ts
+ * head.validateProps({
+ *   title: pval.isString,
+ *   count: pval.optional(pval.isNumber),
+ * })
+ * ```
+ */
+export declare const pval: {
+	readonly isString: PropValidator<string>;
+	readonly isNumber: PropValidator<number>;
+	readonly isBoolean: PropValidator<boolean>;
+	readonly isClass: <TValue extends object>(ctor: abstract new (...args: any[]) => TValue) => PropValidator<TValue>;
+	readonly optional: <TValue>(validator: PropValidator<TValue>) => PropValidator<TValue | undefined>;
+	readonly nullable: <TValue>(validator: PropValidator<TValue>) => PropValidator<TValue | null>;
+	readonly oneOf: <const TValue extends readonly unknown[]>(values: TValue) => PropValidator<TValue[number]>;
+	readonly arrayOf: <TValue>(validator: PropValidator<TValue>) => PropValidator<TValue[]>;
+	readonly shape: <TSchema extends ValidationSchemaLike>(schema: TSchema) => PropValidator<InferPropValidationSchema<TSchema>>;
+	readonly refOf: <TValue>(validator: PropValidator<TValue>) => PropValidator<AnyRef>;
+};
 export type ContextClass<TValue extends object> = abstract new (...args: never[]) => TValue;
 /**
  * Runtime metadata passed to a component's `context(head)` factory.
@@ -170,6 +223,29 @@ export declare class ComponentHead<TContext extends IRegorContext | object = IRe
 	 * @throws Error when no matching instance exists at the requested occurrence.
 	 */
 	requireContext<TValue extends object>(constructor: ContextClass<TValue>, occurrence?: number): TValue;
+	/**
+	 * 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.
+	 *
+	 * Example:
+	 * ```ts
+	 * head.validateProps({
+	 *   title: pval.isString,
+	 *   count: pval.optional(pval.isNumber),
+	 * })
+	 * ```
+	 *
+	 * @param schema - Validators to apply to selected incoming props.
+	 */
+	validateProps<TSchema extends PropValidationSchemaFor<TContext>>(schema: TSchema): asserts this is ComponentHead<TContext & InferPropValidationSchema<TSchema>>;
 	/**
 	 * Unmounts this component instance by removing nodes between `start` and `end`
 	 * and calling unmount lifecycle handlers for captured contexts.

package/dist/regor.es2015.cjs.js

@@ -87,6 +87,7 @@ __export(index_exports, {
   onUnmounted: () => onUnmounted,
   pause: () => pause,
   persist: () => persist,
+  pval: () => pval,
   raw: () => raw,
   ref: () => ref,
   removeNode: () => removeNode,
@@ -418,6 +419,37 @@ 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.
+   *
+   * Example:
+   * ```ts
+   * head.validateProps({
+   *   title: pval.isString,
+   *   count: pval.optional(pval.isNumber),
+   * })
+   * ```
+   *
+   * @param schema - Validators to apply to selected incoming props.
+   */
+  validateProps(schema) {
+    const props = this.props;
+    for (const name in schema) {
+      const validator = schema[name];
+      if (!validator) continue;
+      const validateProp = validator;
+      validateProp(props[name], name, this);
+    }
+  }
   /**
    * Unmounts this component instance by removing nodes between `start` and `end`
    * and calling unmount lifecycle handlers for captured contexts.
@@ -3003,11 +3035,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);
   }
 };
 
@@ -3257,7 +3289,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();
@@ -3287,7 +3319,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 {
@@ -4602,12 +4634,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;
@@ -4633,7 +4665,7 @@ var Jsep = class {
           callee: node
         };
       } else {
-        if (optional) {
+        if (optional2) {
           this.__index--;
         }
         this.__gobbleSpaces();
@@ -4644,7 +4676,7 @@ var Jsep = class {
           property: this.__gobbleIdentifier()
         };
       }
-      if (optional) {
+      if (optional2) {
         node.optional = true;
       }
       this.__gobbleSpaces();
@@ -6174,6 +6206,113 @@ 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() {