regor 1.4.4 → 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.
@@ -566,10 +598,13 @@ var IfBinder = class {
   }
   __bindAll(element) {
     const isIfElement = element.hasAttribute(this.__if);
-    const elements = findElements(element, this.__ifSelector);
-    for (const el of elements) {
-      this.__bind(el);
-    }
+    if (isIfElement) this.__bind(element);
+    this.__binder.__componentBinder.__forEachBindableDescendant(
+      element,
+      (el) => {
+        if (el.hasAttribute(this.__if)) this.__bind(el);
+      }
+    );
     return isIfElement;
   }
   __isProcessedOrMark(el) {
@@ -1361,8 +1396,16 @@ var ComponentBinder = class {
     }
     return false;
   }
+  __isNamedSlotTemplateShortcut(node) {
+    if (!isTemplate(node)) return false;
+    const attributeNames = node.getAttributeNames();
+    if (node.hasAttribute("name")) return true;
+    return attributeNames.some((x) => x.startsWith("#"));
+  }
+  __isDefaultSlotTemplateShortcut(node) {
+    return isTemplate(node) && node.getAttributeNames().length === 0;
+  }
   __unwrapComponents(element) {
-    var _a;
     const binder = this.__binder;
     const parser = binder.__parser;
     const registeredComponents = binder.__config.__components;
@@ -1371,16 +1414,9 @@ var ComponentBinder = class {
       return;
     }
     const contextComponents = parser.__getComponents();
-    const contextComponentSelectors = parser.__getComponentSelectors();
-    const registeredSelector = this.__getRegisteredComponentSelector(registeredComponents);
-    const selector = [
-      ...registeredSelector ? [registeredSelector] : [],
-      ...contextComponentSelectors,
-      ...contextComponentSelectors.map(hyphenate)
-    ].join(",");
+    const selector = this.__getComponentSelector();
     if (isNullOrWhitespace(selector)) return;
-    const list = element.querySelectorAll(selector);
-    const components = ((_a = element.matches) == null ? void 0 : _a.call(element, selector)) ? [element, ...list] : list;
+    const components = this.__collectTopLevelComponentHosts(element, selector);
     for (const component of components) {
       if (component.hasAttribute(binder.__pre)) continue;
       const parent = component.parentNode;
@@ -1454,7 +1490,7 @@ var ComponentBinder = class {
       };
       const capturedContext = [...parser.__capture()];
       const createComponentCtx = () => {
-        var _a2;
+        var _a;
         const props = getProps(component, capturedContext);
         const head2 = new ComponentHead(
           props,
@@ -1464,8 +1500,8 @@ var ComponentBinder = class {
           endOfComponent
         );
         const componentCtx2 = useScope(() => {
-          var _a3;
-          return (_a3 = registeredComponent.context(head2)) != null ? _a3 : {};
+          var _a2;
+          return (_a2 = registeredComponent.context(head2)) != null ? _a2 : {};
         }).context;
         if (head2.autoProps) {
           for (const [key, propsValue] of Object.entries(props)) {
@@ -1489,7 +1525,7 @@ var ComponentBinder = class {
               }
             } else componentCtx2[key] = propsValue;
           }
-          (_a2 = head2.onAutoPropsAssigned) == null ? void 0 : _a2.call(head2);
+          (_a = head2.onAutoPropsAssigned) == null ? void 0 : _a.call(head2);
         }
         return { componentCtx: componentCtx2, head: head2 };
       };
@@ -1498,6 +1534,7 @@ var ComponentBinder = class {
       const len = childNodes.length;
       const isEmptyComponent = component.childNodes.length === 0;
       const expandSlot = (slot) => {
+        var _a;
         const parent2 = slot.parentElement;
         let name = slot.name;
         if (isNullOrWhitespace(name)) {
@@ -1527,9 +1564,12 @@ var ComponentBinder = class {
           `template[name='${name}'], template[\\#${name}]`
         );
         if (!compTemplate && name === "default") {
-          compTemplate = component.querySelector("template:not([name])");
-          if (compTemplate && compTemplate.getAttributeNames().filter((x) => x.startsWith("#")).length > 0)
-            compTemplate = null;
+          const unnamedTemplates = component.querySelectorAll(
+            "template:not([name])"
+          );
+          compTemplate = (_a = [...unnamedTemplates].find(
+            (x) => this.__isDefaultSlotTemplateShortcut(x)
+          )) != null ? _a : null;
         }
         const createSwitchContext = (childNodes2) => {
           if (!head.enableSwitch) return;
@@ -1565,7 +1605,7 @@ var ComponentBinder = class {
             return;
           }
           const childNodes2 = [...getChildNodes(component)].filter(
-            (x) => !isTemplate(x)
+            (x) => !this.__isNamedSlotTemplateShortcut(x)
           );
           for (const slotChild of childNodes2) {
             parent2.insertBefore(slotChild, slot);
@@ -1651,6 +1691,65 @@ var ComponentBinder = class {
       parser.__scoped(capturedContext, bindComponent);
     }
   }
+  __getComponentSelector() {
+    const binder = this.__binder;
+    const parser = binder.__parser;
+    const registeredComponents = binder.__config.__components;
+    const contextComponentSelectors = parser.__getComponentSelectors();
+    const registeredSelector = this.__getRegisteredComponentSelector(registeredComponents);
+    return [
+      ...registeredSelector ? [registeredSelector] : [],
+      ...contextComponentSelectors,
+      ...contextComponentSelectors.map(hyphenate)
+    ].join(",");
+  }
+  __collectTopLevelComponentHosts(root, selector) {
+    var _a;
+    const result = [];
+    if (isNullOrWhitespace(selector)) return result;
+    if ((_a = root.matches) == null ? void 0 : _a.call(root, selector)) return [root];
+    const stack = this.__getChildElements(root).reverse();
+    while (stack.length > 0) {
+      const current = stack.pop();
+      if (current.matches(selector)) {
+        result.push(current);
+        continue;
+      }
+      stack.push(...this.__getChildElements(current).reverse());
+    }
+    return result;
+  }
+  __forEachBindableDescendant(root, action) {
+    const selector = this.__getComponentSelector();
+    const stack = this.__getChildElements(root).reverse();
+    while (stack.length > 0) {
+      const current = stack.pop();
+      action(current);
+      if (!isNullOrWhitespace(selector) && current.matches(selector)) continue;
+      stack.push(...this.__getChildElements(current).reverse());
+    }
+  }
+  __getChildElements(root) {
+    const children = root == null ? void 0 : root.children;
+    if ((children == null ? void 0 : children.length) != null) {
+      const result = [];
+      for (let i = 0; i < children.length; ++i) {
+        const child = children[i];
+        if (isElement(child)) result.push(child);
+      }
+      return result;
+    }
+    const childNodes = root == null ? void 0 : root.childNodes;
+    if ((childNodes == null ? void 0 : childNodes.length) != null) {
+      const result = [];
+      for (let i = 0; i < childNodes.length; ++i) {
+        const child = childNodes[i];
+        if (isElement(child)) result.push(child);
+      }
+      return result;
+    }
+    return [];
+  }
 };
 
 // src/bind/DirectiveCollector.ts
@@ -1743,10 +1842,10 @@ var DirectiveCollector = class {
     };
     processNode(element);
     if (!isRecursive || !element.firstElementChild) return map;
-    const nodes = element.querySelectorAll("*");
-    for (const node of nodes) {
-      processNode(node);
-    }
+    this.__binder.__componentBinder.__forEachBindableDescendant(
+      element,
+      processNode
+    );
     return map;
   }
 };
@@ -1764,17 +1863,19 @@ var DynamicBinder = class {
   constructor(binder) {
     __publicField(this, "__binder");
     __publicField(this, "__is");
-    __publicField(this, "__isSelector");
     this.__binder = binder;
     this.__is = binder.__config.__builtInNames.is;
-    this.__isSelector = toSelector(this.__is) + ", [is]";
   }
   __bindAll(element) {
     const isComponentElement = element.hasAttribute(this.__is);
-    const elements = findElements(element, this.__isSelector);
-    for (const el of elements) {
-      this.__bind(el);
-    }
+    if (isComponentElement || element.hasAttribute("is"))
+      this.__bind(element);
+    this.__binder.__componentBinder.__forEachBindableDescendant(
+      element,
+      (el) => {
+        if (el.hasAttribute(this.__is) || el.hasAttribute("is")) this.__bind(el);
+      }
+    );
     return isComponentElement;
   }
   __bind(el) {
@@ -2251,10 +2352,13 @@ var _ForBinder = class _ForBinder {
   }
   __bindAll(element) {
     const isForElement = element.hasAttribute(this.__for);
-    const elements = findElements(element, this.__forSelector);
-    for (const el of elements) {
-      this.__bindFor(el);
-    }
+    if (isForElement) this.__bindFor(element);
+    this.__binder.__componentBinder.__forEachBindableDescendant(
+      element,
+      (el) => {
+        if (el.hasAttribute(this.__for)) this.__bindFor(el);
+      }
+    );
     return isForElement;
   }
   __isProcessedOrMark(el) {
@@ -2931,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);
   }
 };
 
@@ -3185,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();
@@ -3215,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 {
@@ -4530,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;
@@ -4561,7 +4665,7 @@ var Jsep = class {
           callee: node
         };
       } else {
-        if (optional) {
+        if (optional2) {
           this.__index--;
         }
         this.__gobbleSpaces();
@@ -4572,7 +4676,7 @@ var Jsep = class {
           property: this.__gobbleIdentifier()
         };
       }
-      if (optional) {
+      if (optional2) {
         node.optional = true;
       }
       this.__gobbleSpaces();
@@ -6102,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() {