regor 1.4.5 → 1.4.7

package/README.md

@@ -97,6 +97,156 @@ 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 follows `config.propValidationMode`
+- 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)
+pval.fail('title', 'expected non-empty string')
+```
+
+### 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 { pval, type PropValidator } from 'regor'
+
+const isNonEmptyString: PropValidator<string> = (value, name) => {
+  if (typeof value !== 'string' || value.trim() === '') {
+    pval.fail(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)) {
+    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
@@ -223,6 +373,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,86 @@
 // 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(...)`.
+ *
+ * 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>;
+	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 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.
@@ -111,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.
 	 *
@@ -170,22 +256,45 @@ 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. 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<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.
 	 */
 	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 [