juxscript 1.0.88 → 1.0.90

package/bin/cli.js

@@ -3,124 +3,275 @@
 import path from 'path';
 import fs from 'fs';
 import { fileURLToPath } from 'url';
+import { spawn } from 'child_process';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
-const command = process.argv[2];
+const PACKAGE_ROOT = path.resolve(__dirname, '..');
 
-function scaffoldProject(targetDir, packageRoot) {
+const [, , command, ...args] = process.argv;
+
+// ═══════════════════════════════════════════════════════════════
+// COMMAND: create <project-name>
+// Creates a new JUX project from the template
+// ═══════════════════════════════════════════════════════════════
+async function createProject(projectName) {
+  if (!projectName) {
+    console.error('❌ Usage: jux create <project-name>');
+    process.exit(1);
+  }
+
+  const targetDir = path.join(process.cwd(), projectName);
+
+  if (fs.existsSync(targetDir)) {
+    console.error(`❌ Directory "${projectName}" already exists.`);
+    process.exit(1);
+  }
+
+  console.log(`\n📦 Creating JUX project: ${projectName}\n`);
+
+  // 1. Create project directory
+  fs.mkdirSync(targetDir, { recursive: true });
+
+  // 2. Copy template from /create folder
+  const templateDir = path.join(PACKAGE_ROOT, 'create');
+  if (fs.existsSync(templateDir)) {
+    copyDirRecursive(templateDir, path.join(targetDir, 'jux'));
+    console.log('   ✓ Copied template files');
+  } else {
+    // Fallback: create minimal starter
+    const juxDir = path.join(targetDir, 'jux');
+    fs.mkdirSync(juxDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(juxDir, 'index.jux'),
+      `import { Element } from 'juxscript';\n\nElement('welcome', { tagName: 'h1' })\n    .text('Welcome to JUX!')\n    .render('app');\n`
+    );
+    console.log('   ✓ Created starter file');
+  }
+
+  // 3. Copy example config
+  const configSrc = path.join(PACKAGE_ROOT, 'juxconfig.example.js');
+  const configDest = path.join(targetDir, 'juxconfig.js');
+  if (fs.existsSync(configSrc)) {
+    fs.copyFileSync(configSrc, configDest);
+    console.log('   ✓ Created juxconfig.js');
+  }
+
+  // 4. Create package.json
+  const pkg = {
+    name: projectName,
+    version: '0.1.0',
+    type: 'module',
+    scripts: {
+      dev: 'jux serve --hot',
+      build: 'jux build',
+      start: 'jux serve'
+    },
+    dependencies: {
+      juxscript: 'latest'
+    }
+  };
+  fs.writeFileSync(path.join(targetDir, 'package.json'), JSON.stringify(pkg, null, 2));
+  console.log('   ✓ Created package.json');
+
+  // 5. Create .gitignore
+  fs.writeFileSync(
+    path.join(targetDir, '.gitignore'),
+    `.jux-dist/\nnode_modules/\n.DS_Store\n.env\n*.log\n`
+  );
+  console.log('   ✓ Created .gitignore');
+
+  // 6. Install dependencies
+  console.log('\n📥 Installing dependencies...\n');
+  try {
+    const { execSync } = await import('child_process');
+    execSync('npm install', { cwd: targetDir, stdio: 'inherit' });
+  } catch (err) {
+    console.warn('⚠️  npm install failed. Run it manually.');
+  }
+
+  console.log(`
+✅ Project created successfully!
+
+   cd ${projectName}
+   npm run dev
+
+`);
+}
+
+// ═══════════════════════════════════════════════════════════════
+// COMMAND: init
+// Initializes JUX in an existing project
+// ═══════════════════════════════════════════════════════════════
+function initProject() {
+  const targetDir = process.cwd();
+
+  console.log('\n📦 Initializing JUX in current directory\n');
+
+  // 1. Copy template to ./jux
+  const templateDir = path.join(PACKAGE_ROOT, 'create');
   const juxDir = path.join(targetDir, 'jux');
-  if (!fs.existsSync(juxDir)) fs.mkdirSync(juxDir, { recursive: true });
-  const presetDir = path.join(packageRoot, 'create');
-  let copied = 0;
-  if (fs.existsSync(presetDir)) {
-    fs.readdirSync(presetDir).forEach(file => {
-      if (file.startsWith('.')) return;
-      if (fs.statSync(path.join(presetDir, file)).isFile()) {
-        fs.copyFileSync(path.join(presetDir, file), path.join(juxDir, file));
-        copied++;
-      }
-    });
+
+  if (!fs.existsSync(juxDir)) {
+    fs.mkdirSync(juxDir, { recursive: true });
   }
-  if (copied === 0 && !fs.existsSync(path.join(juxDir, 'index.jux'))) {
-    fs.writeFileSync(path.join(juxDir, 'index.jux'), `import { Element } from 'juxscript';\nElement('welcome', { tag: 'h1' }).text('Welcome to JUX!').render('app');\n`);
+
+  if (fs.existsSync(templateDir)) {
+    copyDirRecursive(templateDir, juxDir);
+    console.log('   ✓ Copied template files to ./jux');
+  } else {
+    fs.writeFileSync(
+      path.join(juxDir, 'index.jux'),
+      `import { Element } from 'juxscript';\n\nElement('welcome', { tagName: 'h1' })\n    .text('Welcome to JUX!')\n    .render('app');\n`
+    );
+    console.log('   ✓ Created starter file');
   }
-  const configSrc = path.join(packageRoot, 'juxconfig.example.js');
+
+  // 2. Copy config if not exists
   const configDest = path.join(targetDir, 'juxconfig.js');
-  if (fs.existsSync(configSrc) && !fs.existsSync(configDest)) fs.copyFileSync(configSrc, configDest);
-  const gitIgnore = path.join(targetDir, '.gitignore');
-  if (!fs.existsSync(gitIgnore)) fs.writeFileSync(gitIgnore, `.jux-dist/\nnode_modules/\n.DS_Store\n.env\n*.log\n`);
+  if (!fs.existsSync(configDest)) {
+    const configSrc = path.join(PACKAGE_ROOT, 'juxconfig.example.js');
+    if (fs.existsSync(configSrc)) {
+      fs.copyFileSync(configSrc, configDest);
+      console.log('   ✓ Created juxconfig.js');
+    }
+  }
+
+  // 3. Update package.json scripts if exists
   const pkgPath = path.join(targetDir, 'package.json');
   if (fs.existsSync(pkgPath)) {
     try {
       const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
       pkg.scripts = pkg.scripts || {};
       let modified = false;
-      if (!pkg.scripts.dev) { pkg.scripts.dev = 'jux serve'; modified = true; }
+
+      if (!pkg.scripts.dev) { pkg.scripts.dev = 'jux serve --hot'; modified = true; }
       if (!pkg.scripts.build) { pkg.scripts.build = 'jux build'; modified = true; }
-      if (modified) fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2));
-    } catch (e) { }
+      if (!pkg.scripts.start) { pkg.scripts.start = 'jux serve'; modified = true; }
+
+      if (modified) {
+        fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2));
+        console.log('   ✓ Updated package.json scripts');
+      }
+    } catch (e) {
+      console.warn('   ⚠️  Could not update package.json');
+    }
   }
+
+  console.log('\n✅ Initialized. Run: npm run dev\n');
 }
 
-if (command === 'create') {
-  const projectName = process.argv[3] || 'my-jux-app';
-  const projectPath = path.join(process.cwd(), projectName);
-  if (fs.existsSync(projectPath)) { console.error(`❌ Directory "${projectName}" already exists.`); process.exit(1); }
-  try {
-    const { execSync } = await import('child_process');
-    fs.mkdirSync(projectPath, { recursive: true });
-    process.chdir(projectPath);
-    const pkg = { name: projectName, version: '0.1.0', type: 'module', scripts: { dev: 'jux serve', build: 'jux build' }, dependencies: { juxscript: 'latest' } };
-    fs.writeFileSync('package.json', JSON.stringify(pkg, null, 2));
-    const packageRoot = path.resolve(__dirname, '..');
-    scaffoldProject(projectPath, packageRoot);
-    try { execSync('npm install', { stdio: 'inherit' }); } catch (err) { }
-    console.log(`\n✅ Project created! Run: cd ${projectName} && npm run dev\n`);
-  } catch (err) { console.error(`\n❌ Failed:`, err.message); process.exit(1); }
-  process.exit(0);
+// ═══════════════════════════════════════════════════════════════
+// COMMAND: build
+// Delegates to machinery/build3.js
+// ═══════════════════════════════════════════════════════════════
+function runBuild() {
+  const buildScript = path.join(PACKAGE_ROOT, 'machinery', 'build3.js');
+
+  if (!fs.existsSync(buildScript)) {
+    console.error('❌ Build script not found:', buildScript);
+    process.exit(1);
+  }
+
+  const child = spawn('node', [buildScript, ...args], {
+    cwd: process.cwd(),
+    stdio: 'inherit',
+    env: process.env
+  });
+
+  child.on('close', (code) => process.exit(code || 0));
 }
 
-import { copyLibToOutput, copyProjectAssets, transpileProjectTypeScript, copyPresetsToOutput, bundleJuxFilesToRouter, generateIndexHtml } from '../machinery/compiler.js';
-import { verifyStaticBuild } from '../machinery/verifier.js';
-import { resolveConfig } from '../machinery/config.js';
-import { start } from '../machinery/server.js';
+// ═══════════════════════════════════════════════════════════════
+// COMMAND: serve [--hot]
+// Delegates to machinery/serve.js
+// ═══════════════════════════════════════════════════════════════
+function runServe() {
+  const serveScript = path.join(PACKAGE_ROOT, 'machinery', 'serve.js');
+
+  if (!fs.existsSync(serveScript)) {
+    console.error('❌ Serve script not found:', serveScript);
+    process.exit(1);
+  }
+
+  // Pass through all args (including --hot)
+  const child = spawn('node', [serveScript, ...args], {
+    cwd: process.cwd(),
+    stdio: 'inherit',
+    env: process.env
+  });
 
-async function loadUserConfig(projectRoot) {
-  const configPath = path.join(projectRoot, 'juxconfig.js');
-  let rawConfig = {};
-  if (fs.existsSync(configPath)) { try { const module = await import(configPath); rawConfig = module.default || module.config || {}; } catch (err) { } }
-  return resolveConfig(rawConfig, projectRoot);
+  child.on('close', (code) => process.exit(code || 0));
 }
 
-(async () => {
-  const projectRoot = process.cwd();
-  const config = await loadUserConfig(projectRoot);
-  const PATHS = {
-    packageRoot: path.resolve(__dirname, '..'),
-    projectRoot: projectRoot,
-    get juxSource() { return path.join(this.projectRoot, config.directories?.source || 'jux'); },
-    get juxLib() { return path.resolve(this.packageRoot, 'lib'); },
-    get frontendDist() { return path.join(this.projectRoot, config.directories?.distribution || '.jux-dist'); }
-  };
+// ═══════════════════════════════════════════════════════════════
+// UTILITIES
+// ═══════════════════════════════════════════════════════════════
+function copyDirRecursive(src, dest) {
+  if (!fs.existsSync(dest)) {
+    fs.mkdirSync(dest, { recursive: true });
+  }
 
-  async function buildProject(isServe = false, wsPort = 3001) {
-    if (!fs.existsSync(PATHS.juxSource)) { console.error(`❌ Source not found: ${PATHS.juxSource}`); process.exit(1); }
-    if (fs.existsSync(PATHS.frontendDist)) fs.rmSync(PATHS.frontendDist, { recursive: true, force: true });
-    fs.mkdirSync(PATHS.frontendDist, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    if (entry.name.startsWith('.')) continue; // Skip hidden files
 
-    // ✅ Clean Log
-    process.stdout.write('🔨 Building JUX... ');
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
 
-    try {
-      await copyLibToOutput(PATHS.juxLib, PATHS.frontendDist);
-      await copyPresetsToOutput(PATHS.packageRoot, PATHS.frontendDist);
-      await copyProjectAssets(PATHS.juxSource, PATHS.frontendDist);
-      await transpileProjectTypeScript(PATHS.juxSource, PATHS.frontendDist);
-      const bundleResult = await bundleJuxFilesToRouter(PATHS.juxSource, PATHS.frontendDist, { routePrefix: '', config });
-      generateIndexHtml(PATHS.frontendDist, bundleResult, { isDev: isServe, wsPort: isServe ? wsPort : undefined });
-      if (!verifyStaticBuild(PATHS.frontendDist)) { console.error('🛑 Critical Build Failure.'); process.exit(1); }
-
-      const fileCount = fs.readdirSync(PATHS.juxSource).filter(f => f.endsWith('.jux')).length; // Approximate check
-      console.log(`✅ Done. (${fileCount} files, ${(fs.statSync(path.join(PATHS.frontendDist, 'main.js')).size / 1024).toFixed(1)}KB)`);
-    } catch (err) {
-      console.log('❌ Failed.');
-      console.error(err.message);
-      process.exit(1);
+    if (entry.isDirectory()) {
+      copyDirRecursive(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
     }
   }
+}
 
-  if (command === 'init' || command === 'install') {
-    scaffoldProject(PATHS.projectRoot, PATHS.packageRoot);
-    console.log('✅ Initialized. Next: npm run dev');
-  } else if (command === 'build') {
-    await buildProject(false);
-  } else if (command === 'serve') {
-    const httpPort = parseInt(process.argv[3]) || config.defaults?.httpPort || 3000;
-    const wsPort = parseInt(process.argv[4]) || config.defaults?.wsPort || 3001;
-    await buildProject(true, wsPort);
-    await start(httpPort, wsPort, PATHS.frontendDist, config);
-  } else {
-    console.log(`Usage: npx jux [create|init|build|serve]`);
-  }
-})();
+function showHelp() {
+  console.log(`
+JUX CLI
+
+Usage:
+  jux create <name>    Create a new JUX project
+  jux init             Initialize JUX in current directory
+  jux build            Build for production
+  jux serve            Start production server
+  jux serve --hot      Start dev server with hot reload
+
+Options:
+  --help, -h           Show this help message
+`);
+}
+
+// ═══════════════════════════════════════════════════════════════
+// MAIN ROUTER
+// ═══════════════════════════════════════════════════════════════
+switch (command) {
+  case 'create':
+    createProject(args[0]);
+    break;
+
+  case 'init':
+  case 'install':
+    initProject();
+    break;
+
+  case 'build':
+    runBuild();
+    break;
+
+  case 'serve':
+  case 'dev':
+    runServe();
+    break;
+
+  case '--help':
+  case '-h':
+  case undefined:
+    showHelp();
+    break;
+
+  default:
+    console.error(`❌ Unknown command: ${command}`);
+    showHelp();
+    process.exit(1);
+}

package/index.js

@@ -0,0 +1,21 @@
+/**
+ * JUX - JavaScript UX Authorship Platform
+ * 
+ * Main entry point for the juxscript package.
+ * Re-exports all public components and utilities.
+ */
+
+// Core Components
+export { Element } from './lib/componentsv2/element/component.js';
+export { Grid } from './lib/componentsv2/grid/component.js';
+export { Input } from './lib/componentsv2/input/component.js';
+export { List } from './lib/componentsv2/list/component.js';
+
+// Base Classes (for extension)
+export { BaseEngine, BaseState } from './lib/componentsv2/base/BaseEngine.js';
+export { BaseSkin } from './lib/componentsv2/base/BaseSkin.js';
+export { State } from './lib/componentsv2/base/State.js';
+export { GlobalBus } from './lib/componentsv2/base/GlobalBus.js';
+
+// Utilities
+export { validateOptions } from './lib/componentsv2/base/OptionsContract.js';

package/lib/componentsv2/base/BaseEngine.d.ts

@@ -1,3 +1,4 @@
+import { OptionsContractSchema, ValidationResult } from './OptionsContract.js';
 export interface JuxServiceContract<TEngine = any> {
     name: string;
     version?: string;
@@ -24,6 +25,15 @@ type EventListener<T = any> = (data: T) => void;
 export declare abstract class BaseEngine<TState extends BaseState, TOptions = any> {
     #private;
     constructor(id: string, options: TOptions);
+    /**
+     * CONTRACT: Override to define the valid options schema for this engine.
+     * Enables option validation with helpful error messages.
+     */
+    protected get optionsSchema(): OptionsContractSchema | null;
+    /**
+     * Access validation results (warnings, errors, normalized options)
+     */
+    get validation(): ValidationResult | null;
     /**
      * CONTRACT: Must transform input options into the initial State.
      * This separates "mapping logic" from "construction/startup logic".

package/lib/componentsv2/base/BaseEngine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BaseEngine.d.ts","sourceRoot":"","sources":["BaseEngine.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"BaseEngine.d.ts","sourceRoot":"","sources":["BaseEngine.ts"],"names":[],"mappings":"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"}

package/lib/componentsv2/base/BaseEngine.js

@@ -1,17 +1,18 @@
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
 var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
     if (kind === "m") throw new TypeError("Private method is not writable");
     if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
     if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
     return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
 };
-var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
-    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
-    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
-    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
-};
-var _BaseEngine_state, _BaseEngine_listeners, _BaseEngine_cleanupListeners, _BaseEngine_plugins, _BaseEngine_emitHistory, _BaseEngine_debugMode;
+var _BaseEngine_state, _BaseEngine_listeners, _BaseEngine_cleanupListeners, _BaseEngine_plugins, _BaseEngine_emitHistory, _BaseEngine_debugMode, _BaseEngine_validationResult;
 import { State } from './State.js';
 import { GlobalBus } from './GlobalBus.js';
+import { validateOptions } from './OptionsContract.js';
 /**
  * THE ENGINE AGREEMENT
  *
@@ -27,10 +28,30 @@ export class BaseEngine {
         _BaseEngine_plugins.set(this, new Map());
         _BaseEngine_emitHistory.set(this, []);
         _BaseEngine_debugMode.set(this, false);
+        _BaseEngine_validationResult.set(this, null);
+        // Validate options if schema is defined
+        const schema = this.optionsSchema;
+        if (schema) {
+            __classPrivateFieldSet(this, _BaseEngine_validationResult, validateOptions(this.constructor.name, options, schema, __classPrivateFieldGet(this, _BaseEngine_debugMode, "f")), "f");
+            options = __classPrivateFieldGet(this, _BaseEngine_validationResult, "f").normalized;
+        }
         // Enforce the Contract: Child must define how state is born from options
         const initialState = this.prepareState(id, options);
         __classPrivateFieldSet(this, _BaseEngine_state, new State(initialState), "f");
     }
+    /**
+     * CONTRACT: Override to define the valid options schema for this engine.
+     * Enables option validation with helpful error messages.
+     */
+    get optionsSchema() {
+        return null; // Override in child classes
+    }
+    /**
+     * Access validation results (warnings, errors, normalized options)
+     */
+    get validation() {
+        return __classPrivateFieldGet(this, _BaseEngine_validationResult, "f");
+    }
     get state() {
         return __classPrivateFieldGet(this, _BaseEngine_state, "f").value;
     }
@@ -254,5 +275,5 @@ export class BaseEngine {
         return this;
     }
 }
-_BaseEngine_state = new WeakMap(), _BaseEngine_listeners = new WeakMap(), _BaseEngine_cleanupListeners = new WeakMap(), _BaseEngine_plugins = new WeakMap(), _BaseEngine_emitHistory = new WeakMap(), _BaseEngine_debugMode = new WeakMap();
+_BaseEngine_state = new WeakMap(), _BaseEngine_listeners = new WeakMap(), _BaseEngine_cleanupListeners = new WeakMap(), _BaseEngine_plugins = new WeakMap(), _BaseEngine_emitHistory = new WeakMap(), _BaseEngine_debugMode = new WeakMap(), _BaseEngine_validationResult = new WeakMap();
 //# sourceMappingURL=BaseEngine.js.map

package/lib/componentsv2/base/BaseEngine.js.map

@@ -1 +1 @@
-{"version":3,"file":"BaseEngine.js","sourceRoot":"","sources":["BaseEngine.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"BaseEngine.js","sourceRoot":"","sources":["BaseEngine.ts"],"names":[],"mappings":"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"}

package/lib/componentsv2/base/BaseEngine.ts

@@ -1,5 +1,6 @@
 import { State } from './State.js';
 import { GlobalBus } from './GlobalBus.js';
+import { validateOptions, OptionsContractSchema, ValidationResult } from './OptionsContract.js';
 
 
 export interface JuxServiceContract<TEngine = any> {
@@ -35,13 +36,41 @@ export abstract class BaseEngine<TState extends BaseState, TOptions = any> {
     #plugins = new Map<string, JuxServiceContract>();
     #emitHistory: string[] = [];
     #debugMode = false;
+    #validationResult: ValidationResult | null = null;
 
     constructor(id: string, options: TOptions) {
+        // Validate options if schema is defined
+        const schema = this.optionsSchema;
+        if (schema) {
+            this.#validationResult = validateOptions(
+                this.constructor.name,
+                options as Record<string, any>,
+                schema,
+                this.#debugMode
+            );
+            options = this.#validationResult.normalized as TOptions;
+        }
+
         // Enforce the Contract: Child must define how state is born from options
         const initialState = this.prepareState(id, options);
         this.#state = new State(initialState);
     }
 
+    /**
+     * CONTRACT: Override to define the valid options schema for this engine.
+     * Enables option validation with helpful error messages.
+     */
+    protected get optionsSchema(): OptionsContractSchema | null {
+        return null; // Override in child classes
+    }
+
+    /**
+     * Access validation results (warnings, errors, normalized options)
+     */
+    get validation(): ValidationResult | null {
+        return this.#validationResult;
+    }
+
     /**
      * CONTRACT: Must transform input options into the initial State.
      * This separates "mapping logic" from "construction/startup logic".

package/lib/componentsv2/base/OptionsContract.d.ts

@@ -0,0 +1,20 @@
+export interface OptionDefinition {
+    type: 'string' | 'number' | 'boolean' | 'array' | 'object' | 'function';
+    required?: boolean;
+    default?: any;
+    description?: string;
+    aliases?: string[];
+}
+export type OptionsContractSchema = Record<string, OptionDefinition>;
+export interface ValidationResult {
+    valid: boolean;
+    warnings: string[];
+    errors: string[];
+    normalized: Record<string, any>;
+}
+/**
+ * Validates user-provided options against a defined contract schema.
+ * Emits warnings for unknown/misnamed options and errors for type mismatches.
+ */
+export declare function validateOptions<T extends Record<string, any>>(componentName: string, userOptions: Record<string, any>, schema: OptionsContractSchema, debugMode?: boolean): ValidationResult;
+//# sourceMappingURL=OptionsContract.d.ts.map

package/lib/componentsv2/base/OptionsContract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OptionsContract.d.ts","sourceRoot":"","sources":["OptionsContract.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,gBAAgB;IAC7B,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,GAAG,QAAQ,GAAG,UAAU,CAAC;IACxE,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,GAAG,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,MAAM,MAAM,qBAAqB,GAAG,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;AAErE,MAAM,WAAW,gBAAgB;IAC7B,KAAK,EAAE,OAAO,CAAC;IACf,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CACnC;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EACzD,aAAa,EAAE,MAAM,EACrB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAChC,MAAM,EAAE,qBAAqB,EAC7B,SAAS,GAAE,OAAe,GAC3B,gBAAgB,CAqElB"}