@frontmcp/uipack 0.6.1

package/validation/schema-paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-paths.d.ts","sourceRoot":"","sources":["../../src/validation/schema-paths.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,gCAAgC;IAChC,OAAO,EAAE,CAAC,CAAC,UAAU,CAAC;IACtB,oCAAoC;IACpC,QAAQ,EAAE,OAAO,CAAC;IAClB,oCAAoC;IACpC,QAAQ,EAAE,OAAO,CAAC;IAClB,uDAAuD;IACvD,WAAW,EAAE,OAAO,CAAC;IACrB,8CAA8C;IAC9C,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gDAAgD;IAChD,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,CAAC,CAAC,UAAU,EACpB,MAAM,SAAW,EACjB,OAAO,GAAE,mBAAwB,GAChC,UAAU,EAAE,CAkFd;AA8CD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,EAAE,MAAM,SAAW,GAAG,GAAG,CAAC,MAAM,CAAC,CAGzF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAqC7E;AAYD;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,CAAC,UAAU,GAAG,SAAS,CAc1F;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CActF;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,GAAG,MAAM,EAAE,CAQhE;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAK7E"}

package/validation/template-validator.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Template Validator
+ *
+ * Validates Handlebars templates against Zod schemas to catch
+ * references to non-existent fields.
+ *
+ * @packageDocumentation
+ */
+import { z } from 'zod';
+/**
+ * Validation error types.
+ */
+export type ValidationErrorType = 'missing_field' | 'invalid_path' | 'type_mismatch';
+/**
+ * Validation warning types.
+ */
+export type ValidationWarningType = 'optional_field' | 'array_access' | 'deep_path' | 'dynamic_path';
+/**
+ * A validation error for a missing or invalid field.
+ */
+export interface TemplateValidationError {
+    /** Error type */
+    type: ValidationErrorType;
+    /** The invalid path (e.g., "output.city") */
+    path: string;
+    /** The full Handlebars expression */
+    expression: string;
+    /** Line number in template */
+    line: number;
+    /** Column position */
+    column: number;
+    /** Human-readable error message */
+    message: string;
+    /** Suggested similar paths */
+    suggestions: string[];
+}
+/**
+ * A validation warning (non-blocking).
+ */
+export interface TemplateValidationWarning {
+    /** Warning type */
+    type: ValidationWarningType;
+    /** The path that triggered the warning */
+    path: string;
+    /** The full Handlebars expression */
+    expression: string;
+    /** Line number in template */
+    line: number;
+    /** Human-readable warning message */
+    message: string;
+}
+/**
+ * Result of template validation.
+ */
+export interface TemplateValidationResult {
+    /** Whether the template is valid (no errors) */
+    valid: boolean;
+    /** Validation errors (missing fields, etc.) */
+    errors: TemplateValidationError[];
+    /** Validation warnings (optional fields, etc.) */
+    warnings: TemplateValidationWarning[];
+    /** All paths found in the template */
+    templatePaths: string[];
+    /** All valid paths from the schema */
+    schemaPaths: string[];
+}
+/**
+ * Options for template validation.
+ */
+export interface ValidateTemplateOptions {
+    /** Schema for input.* paths (optional) */
+    inputSchema?: z.ZodTypeAny;
+    /** Warn when accessing optional fields without {{#if}} guard */
+    warnOnOptional?: boolean;
+    /** Suggest similar paths for typos */
+    suggestSimilar?: boolean;
+    /** Maximum Levenshtein distance for suggestions */
+    maxSuggestionDistance?: number;
+    /** Tool name for error messages */
+    toolName?: string;
+}
+/**
+ * Validate a Handlebars template against an output schema.
+ *
+ * @param template - The Handlebars template string
+ * @param outputSchema - Zod schema for the output
+ * @param options - Validation options
+ * @returns Validation result with errors and warnings
+ *
+ * @example
+ * ```typescript
+ * const result = validateTemplate(
+ *   '<div>{{output.temperature}} in {{output.city}}</div>',
+ *   z.object({ temperature: z.number() })
+ * );
+ *
+ * if (!result.valid) {
+ *   console.warn('Template has issues:', result.errors);
+ * }
+ * ```
+ */
+export declare function validateTemplate(template: string, outputSchema: z.ZodTypeAny, options?: ValidateTemplateOptions): TemplateValidationResult;
+/**
+ * Format validation result as console warnings.
+ *
+ * @param result - Validation result
+ * @param toolName - Tool name for context
+ * @returns Formatted warning string
+ */
+export declare function formatValidationWarnings(result: TemplateValidationResult, toolName: string): string;
+/**
+ * Log validation warnings to console in development mode.
+ *
+ * @param result - Validation result
+ * @param toolName - Tool name for context
+ */
+export declare function logValidationWarnings(result: TemplateValidationResult, toolName: string): void;
+/**
+ * Validate template and throw if invalid.
+ *
+ * @param template - The template to validate
+ * @param outputSchema - Output schema
+ * @param toolName - Tool name for error message
+ * @throws Error if template has validation errors
+ */
+export declare function assertTemplateValid(template: string, outputSchema: z.ZodTypeAny, toolName: string): void;
+/**
+ * Quickly check if a template is valid against a schema.
+ *
+ * @param template - The template to validate
+ * @param outputSchema - Output schema
+ * @returns true if valid, false otherwise
+ */
+export declare function isTemplateValid(template: string, outputSchema: z.ZodTypeAny): boolean;
+/**
+ * Get missing fields from a template.
+ *
+ * @param template - The template to check
+ * @param outputSchema - Output schema
+ * @returns Array of missing field paths
+ */
+export declare function getMissingFields(template: string, outputSchema: z.ZodTypeAny): string[];
+//# sourceMappingURL=template-validator.d.ts.map

package/validation/template-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-validator.d.ts","sourceRoot":"","sources":["../../src/validation/template-validator.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAoBxB;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG,eAAe,GAAG,cAAc,GAAG,eAAe,CAAC;AAErF;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG,gBAAgB,GAAG,cAAc,GAAG,WAAW,GAAG,cAAc,CAAC;AAErG;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,iBAAiB;IACjB,IAAI,EAAE,mBAAmB,CAAC;IAC1B,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,qCAAqC;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,8BAA8B;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,sBAAsB;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,mCAAmC;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,8BAA8B;IAC9B,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,mBAAmB;IACnB,IAAI,EAAE,qBAAqB,CAAC;IAC5B,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,qCAAqC;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,8BAA8B;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,qCAAqC;IACrC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,gDAAgD;IAChD,KAAK,EAAE,OAAO,CAAC;IACf,+CAA+C;IAC/C,MAAM,EAAE,uBAAuB,EAAE,CAAC;IAClC,kDAAkD;IAClD,QAAQ,EAAE,yBAAyB,EAAE,CAAC;IACtC,sCAAsC;IACtC,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,sCAAsC;IACtC,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,0CAA0C;IAC1C,WAAW,CAAC,EAAE,CAAC,CAAC,UAAU,CAAC;IAC3B,gEAAgE;IAChE,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,sCAAsC;IACtC,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,mDAAmD;IACnD,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,mCAAmC;IACnC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAMD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,CAAC,CAAC,UAAU,EAC1B,OAAO,GAAE,uBAA4B,GACpC,wBAAwB,CAsG1B;AA4HD;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,wBAAwB,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CA0CnG;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,wBAAwB,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAK9F;AAMD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC,CAAC,UAAU,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAOxG;AAMD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC,CAAC,UAAU,GAAG,OAAO,CAGrF;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC,CAAC,UAAU,GAAG,MAAM,EAAE,CAGvF"}

package/validation/wrapper.d.ts

@@ -0,0 +1,97 @@
+/**
+ * @file wrapper.ts
+ * @description Validation wrapper utilities for component input validation.
+ *
+ * Provides functions to validate component options against Zod schemas
+ * and return either the validated data or an error box HTML string.
+ *
+ * @example
+ * ```typescript
+ * import { validateOptions } from '@frontmcp/ui';
+ * import { z } from 'zod';
+ *
+ * const schema = z.object({ variant: z.enum(['primary', 'secondary']) });
+ *
+ * const result = validateOptions(options, {
+ *   componentName: 'Button',
+ *   schema,
+ * });
+ *
+ * if (!result.success) return result.error; // Returns error box HTML
+ *
+ * // Use result.data safely
+ * ```
+ *
+ * @module @frontmcp/ui/validation/wrapper
+ */
+import { type ZodSchema } from 'zod';
+/**
+ * Configuration for validation
+ */
+export interface ValidationConfig {
+    /** Name of the component being validated */
+    componentName: string;
+    /** Zod schema to validate against */
+    schema: ZodSchema;
+}
+/**
+ * Result of validation - either success with data or failure with error HTML
+ */
+export type ValidationResult<T> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    error: string;
+};
+/**
+ * Validates input against a Zod schema
+ *
+ * Returns either:
+ * - `{ success: true, data: T }` with validated/parsed data
+ * - `{ success: false, error: string }` with error box HTML
+ *
+ * @param options - The options object to validate
+ * @param config - Validation configuration (component name and schema)
+ * @returns ValidationResult with either data or error HTML
+ *
+ * @example
+ * ```typescript
+ * const result = validateOptions({ variant: 'invalid' }, {
+ *   componentName: 'Button',
+ *   schema: ButtonOptionsSchema,
+ * });
+ *
+ * if (!result.success) {
+ *   return result.error; // Error box HTML
+ * }
+ *
+ * // result.data is typed and validated
+ * ```
+ */
+export declare function validateOptions<T>(options: unknown, config: ValidationConfig): ValidationResult<T>;
+/**
+ * Higher-order function to wrap a component function with validation
+ *
+ * Creates a new function that validates the options before calling the
+ * original component. If validation fails, returns the error box HTML
+ * instead of calling the component.
+ *
+ * @param componentFn - The original component function
+ * @param config - Validation configuration
+ * @returns Wrapped function that validates before calling
+ *
+ * @example
+ * ```typescript
+ * const buttonImpl = (text: string, opts: ButtonOptions) => `<button>...</button>`;
+ *
+ * const button = withValidation(buttonImpl, {
+ *   componentName: 'Button',
+ *   schema: ButtonOptionsSchema,
+ * });
+ *
+ * // button() now validates options before rendering
+ * ```
+ */
+export declare function withValidation<TInput, TOptions>(componentFn: (input: TInput, options: TOptions) => string, config: ValidationConfig): (input: TInput, options: unknown) => string;
+//# sourceMappingURL=wrapper.d.ts.map

package/validation/wrapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wrapper.d.ts","sourceRoot":"","sources":["../../src/validation/wrapper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,KAAK,CAAC;AAOrC;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,4CAA4C;IAC5C,aAAa,EAAE,MAAM,CAAC;IACtB,qCAAqC;IACrC,MAAM,EAAE,SAAS,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAAI;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,CAAC,CAAA;CAAE,GAAG;IAAE,OAAO,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAiBjG;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,gBAAgB,GAAG,gBAAgB,CAAC,CAAC,CAAC,CAiBlG;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,QAAQ,EAC7C,WAAW,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,KAAK,MAAM,EACzD,MAAM,EAAE,gBAAgB,GACvB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,KAAK,MAAM,CAU7C"}