@frontmcp/uipack 0.6.1

package/utils/escape-html.d.ts

@@ -0,0 +1,58 @@
+/**
+ * HTML Escaping Utilities
+ *
+ * Functions for escaping strings to prevent XSS attacks in HTML output.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Escape HTML special characters to prevent XSS.
+ *
+ * Handles null/undefined by returning empty string.
+ * Converts non-string values to string before escaping.
+ *
+ * @param str - Value to escape (will be converted to string)
+ * @returns Escaped string safe for HTML content
+ *
+ * @example
+ * ```typescript
+ * escapeHtml('<script>alert("xss")</script>')
+ * // Returns: '&lt;script&gt;alert(&quot;xss&quot;)&lt;/script&gt;'
+ *
+ * escapeHtml(null)  // Returns: ''
+ * escapeHtml(123)   // Returns: '123'
+ * ```
+ */
+export declare function escapeHtml(str: unknown): string;
+/**
+ * Escape string for use in HTML attributes.
+ *
+ * Lighter version that only escapes & and " characters,
+ * suitable for attribute values that are already quoted.
+ *
+ * @param str - String to escape
+ * @returns Escaped string safe for HTML attributes
+ *
+ * @example
+ * ```typescript
+ * escapeHtmlAttr('value with "quotes" & ampersand')
+ * // Returns: 'value with &quot;quotes&quot; &amp; ampersand'
+ * ```
+ */
+export declare function escapeHtmlAttr(str: string): string;
+/**
+ * Escape string for use in JavaScript string literals.
+ *
+ * Escapes characters that could break out of a JS string context.
+ *
+ * @param str - String to escape
+ * @returns Escaped string safe for JS string literals
+ *
+ * @example
+ * ```typescript
+ * escapeJsString("it's a \"test\"")
+ * // Returns: "it\\'s a \\\"test\\\""
+ * ```
+ */
+export declare function escapeJsString(str: string): string;
+//# sourceMappingURL=escape-html.d.ts.map

package/utils/escape-html.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"escape-html.d.ts","sourceRoot":"","sources":["../../src/utils/escape-html.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAc/C;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAElD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAUlD"}

package/utils/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @frontmcp/ui Utilities
+ *
+ * Common utility functions for UI operations.
+ *
+ * @packageDocumentation
+ */
+export { safeStringify } from './safe-stringify';
+export { escapeHtml, escapeHtmlAttr, escapeJsString } from './escape-html';
+//# sourceMappingURL=index.d.ts.map

package/utils/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC"}

package/utils/index.js

@@ -0,0 +1,70 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// libs/uipack/src/utils/index.ts
+var utils_exports = {};
+__export(utils_exports, {
+  escapeHtml: () => escapeHtml,
+  escapeHtmlAttr: () => escapeHtmlAttr,
+  escapeJsString: () => escapeJsString,
+  safeStringify: () => safeStringify
+});
+module.exports = __toCommonJS(utils_exports);
+
+// libs/uipack/src/utils/safe-stringify.ts
+function safeStringify(value, space) {
+  const seen = /* @__PURE__ */ new WeakSet();
+  try {
+    return JSON.stringify(
+      value,
+      (_key, val) => {
+        if (typeof val === "object" && val !== null) {
+          if (seen.has(val)) return "[Circular]";
+          seen.add(val);
+        }
+        return val;
+      },
+      space
+    );
+  } catch {
+    return JSON.stringify({ error: "Output could not be serialized" });
+  }
+}
+
+// libs/uipack/src/utils/escape-html.ts
+function escapeHtml(str) {
+  if (str === null || str === void 0) {
+    return "";
+  }
+  const s = String(str);
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;").replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029");
+}
+function escapeHtmlAttr(str) {
+  return str.replace(/&/g, "&amp;").replace(/"/g, "&quot;");
+}
+function escapeJsString(str) {
+  return str.replace(/\\/g, "\\\\").replace(/'/g, "\\'").replace(/"/g, '\\"').replace(/\n/g, "\\n").replace(/\r/g, "\\r").replace(/\t/g, "\\t").replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029");
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  escapeHtml,
+  escapeHtmlAttr,
+  escapeJsString,
+  safeStringify
+});

package/utils/safe-stringify.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @file safe-stringify.ts
+ * @description Safe JSON stringification utility that handles circular references and edge cases.
+ *
+ * This prevents tool calls from failing due to serialization errors when
+ * the output contains circular references or non-serializable values.
+ */
+/**
+ * Safely stringify a value, handling circular references and other edge cases.
+ *
+ * @param value - The value to stringify
+ * @param space - Optional indentation for pretty-printing (passed to JSON.stringify)
+ * @returns JSON string representation of the value
+ *
+ * @example
+ * ```typescript
+ * // Normal object
+ * safeStringify({ name: 'test' }); // '{"name":"test"}'
+ *
+ * // Circular reference
+ * const obj = { name: 'test' };
+ * obj.self = obj;
+ * safeStringify(obj); // '{"name":"test","self":"[Circular]"}'
+ *
+ * // Pretty print
+ * safeStringify({ name: 'test' }, 2); // '{\n  "name": "test"\n}'
+ * ```
+ */
+export declare function safeStringify(value: unknown, space?: number): string;
+//# sourceMappingURL=safe-stringify.d.ts.map

package/utils/safe-stringify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-stringify.d.ts","sourceRoot":"","sources":["../../src/utils/safe-stringify.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAiBpE"}

package/validation/error-box.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @file error-box.ts
+ * @description Validation error box component for displaying input validation failures.
+ *
+ * Renders a styled error card when component options fail Zod validation.
+ * Shows component name and invalid parameter without exposing internal details.
+ *
+ * @example
+ * ```typescript
+ * import { validationErrorBox } from '@frontmcp/ui';
+ *
+ * validationErrorBox({
+ *   componentName: 'Button',
+ *   invalidParam: 'variant',
+ * });
+ * ```
+ *
+ * @module @frontmcp/ui/validation/error-box
+ */
+/**
+ * Options for rendering a validation error box
+ */
+export interface ValidationErrorBoxOptions {
+    /** Name of the component that failed validation */
+    componentName: string;
+    /** Name of the invalid parameter (path notation for nested, e.g., "htmx.get") */
+    invalidParam: string;
+}
+/**
+ * Renders a validation error box for invalid component options
+ *
+ * This component is rendered in place of the actual component when
+ * validation fails. It shows:
+ * - The component name
+ * - The invalid parameter name
+ * - A styled error message
+ *
+ * It does NOT expose:
+ * - The actual invalid value
+ * - Internal Zod error messages
+ * - Schema structure details
+ *
+ * @param options - Error box configuration
+ * @returns HTML string for the error box
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * validationErrorBox({ componentName: 'Button', invalidParam: 'variant' });
+ *
+ * // Nested param
+ * validationErrorBox({ componentName: 'Button', invalidParam: 'htmx.get' });
+ * ```
+ */
+export declare function validationErrorBox(options: ValidationErrorBoxOptions): string;
+//# sourceMappingURL=error-box.d.ts.map

package/validation/error-box.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-box.d.ts","sourceRoot":"","sources":["../../src/validation/error-box.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAQH;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,mDAAmD;IACnD,aAAa,EAAE,MAAM,CAAC;IACtB,iFAAiF;IACjF,YAAY,EAAE,MAAM,CAAC;CACtB;AAaD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,yBAAyB,GAAG,MAAM,CAgB7E"}

package/validation/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Validation Module
+ *
+ * Component input validation and template validation against Zod schemas
+ * for FrontMCP UI widgets.
+ *
+ * @packageDocumentation
+ */
+export { validationErrorBox, type ValidationErrorBoxOptions } from './error-box';
+export { validateOptions, type ValidationConfig, type ValidationResult } from './wrapper';
+export { extractSchemaPaths, getSchemaPathStrings, isValidSchemaPath, getTypeAtPath, getPathInfo, getRootFieldNames, getTypeDescription, type SchemaPath, type ExtractPathsOptions, } from './schema-paths';
+export { validateTemplate, formatValidationWarnings, logValidationWarnings, assertTemplateValid, isTemplateValid, getMissingFields, type TemplateValidationResult, type TemplateValidationError, type TemplateValidationWarning, type ValidateTemplateOptions, type ValidationErrorType, type ValidationWarningType, } from './template-validator';
+//# sourceMappingURL=index.d.ts.map

package/validation/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/validation/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,OAAO,EAAE,kBAAkB,EAAE,KAAK,yBAAyB,EAAE,MAAM,aAAa,CAAC;AAEjF,OAAO,EAAE,eAAe,EAAE,KAAK,gBAAgB,EAAE,KAAK,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAM1F,OAAO,EACL,kBAAkB,EAClB,oBAAoB,EACpB,iBAAiB,EACjB,aAAa,EACb,WAAW,EACX,iBAAiB,EACjB,kBAAkB,EAClB,KAAK,UAAU,EACf,KAAK,mBAAmB,GACzB,MAAM,gBAAgB,CAAC;AAMxB,OAAO,EACL,gBAAgB,EAChB,wBAAwB,EACxB,qBAAqB,EACrB,mBAAmB,EACnB,eAAe,EACf,gBAAgB,EAChB,KAAK,wBAAwB,EAC7B,KAAK,uBAAuB,EAC5B,KAAK,yBAAyB,EAC9B,KAAK,uBAAuB,EAC5B,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,GAC3B,MAAM,sBAAsB,CAAC"}