Troubleshooting Guide

Common issues and solutions when working with the Dial system.

CLI Issues

Properties Not Appearing in Schema

Problem: Some properties don't show up in the generated schema.

Cause: Properties without any @dial annotations are excluded by default.

Solution: Add at least one @dial annotation to include the property:

// ❌ Won't appear in schema
interface Props {
  /**
   * This property has no dial annotations
   */
  className: string;
}

// ✅ Will appear in schema
interface Props {
  /**
   * @dial styling
   */
  className: string;

  // Or just add a dtype
  /**
   * @dial-dtype string
   */
  name: string;
}

Inherited Properties Missing

Problem: Properties from parent interfaces aren't included.

Cause: Base type not found or import issues.

Solutions:

1. Ensure base type is properly exported:

// base.ts
export interface BaseProps {
  /** @dial common */
  id: string;
}

2. Check import paths are correct:

// component.tsx
import { BaseProps } from './base'; // Correct path

interface Props extends BaseProps {
  /** @dial specific */
  name: string;
}

3. Run with verbose mode to debug:

dial-cli Component.tsx --verbose

Wrong Data Type Inferred

Problem: CLI infers incorrect dtype for a property.

Solution: Explicitly specify the dtype:

// ❌ Might infer as "string"
interface Props {
  /** @dial appearance */
  color: string;
}

// ✅ Explicitly set as color picker
interface Props {
  /**
   * @dial appearance
   * @dial-dtype color
   */
  color: string;
}

CLI Command Not Found

Problem: dial-cli: command not found error.

Solutions:

1. Install globally:

npm install -g @vuer-ai/dial-cli

2. Or use npx:

npx @vuer-ai/dial-cli Component.tsx

3. Check global npm/pnpm bin is in PATH:

echo $PATH
npm config get prefix

Files Not Being Processed

Problem: CLI doesn't find or process files.

Solutions:

1. Use absolute paths:

dial-cli /absolute/path/to/Component.tsx

2. Check working directory:

pwd
ls src/components/*.tsx

3. Use proper glob patterns:

# Correct
dial-cli "src/**/*.tsx"

# Wrong (shell might expand incorrectly)
dial-cli src/**/*.tsx

Circular Dependencies

Problem: "Maximum call stack exceeded" or circular reference errors.

Solution: Avoid circular type references:

// ❌ Circular reference
interface A {
  b: B;
}
interface B {
  a: A;
}

// ✅ Break the cycle
interface A {
  b: Partial<B>;
}
interface B {
  // Don't reference A directly
  id: string;
}

UI Component Issues

DialPanel Not Rendering

Problem: Controls don't appear in the UI.

Checklist:

1. Wrap with DialProvider:

// ❌ Missing provider
<DialPanel schemas={schemas} />

// ✅ With provider
<DialProvider schemas={schemas}>
  <DialPanel schemas={schemas} />
</DialProvider>

2. Check schemas are valid:

console.log('Schemas:', schemas);
// Should be an array of schema objects

3. Ensure schemas have required fields:

// Minimum required schema
const schema: DialSchema = {
  name: 'myProp',
  dtype: 'number'
};

Values Not Updating

Problem: Control changes don't trigger updates.

Solution: Provide onValueChange handler:

const handleValueChange = (name: string, value: DialValue) => {
  console.log('Change:', name, value);
  setState(prev => ({ ...prev, [name]: value }));
};

<DialProvider
  schemas={schemas}
  onValueChange={handleValueChange} // Required for updates
>
  <DialPanel schemas={schemas} />
</DialProvider>

Controls Appear Disabled

Problem: All controls are grayed out/disabled.

Causes and Solutions:

1. Check disabled prop:

<DialProvider
  schemas={schemas}
  disabled={false} // Ensure not disabled
>

2. Check individual schema:

const schema = {
  name: 'prop',
  dtype: 'number',
  disabled: false // Not disabled
};

Wrong Control Type Rendered

Problem: Property shows wrong control (e.g., text input instead of slider).

Solution: Check dtype is correctly set:

// ❌ Will show text input
{
  name: 'opacity',
  // Missing dtype
}

// ✅ Will show slider
{
  name: 'opacity',
  dtype: 'number', // Correct dtype
  min: 0,
  max: 1
}

Group Layout Issues

Problem: Properties not grouping correctly.

Solutions:

1. Ensure grouping property matches group name:

const schema = {
  name: 'position',
  grouping: 'transform' // Must match group.name
};

const groups = [
  { name: 'transform' } // Matching name
];

2. Check group configuration:

const groups = [
  {
    name: 'transform',
    layout: 'grid',
    gridCols: 3 // Proper layout config
  }
];

Build & Configuration Issues

Cannot Import .dial Files

Problem: TypeScript/bundler doesn't recognize .dial files.

Solutions:

1. Add type declaration:

// dial.d.ts
declare module '*.dial' {
  const schemas: any[];
  export default schemas;
}

2. Configure Vite:

// vite.config.js
import json from '@rollup/plugin-json';

export default {
  plugins: [
    json({
      include: ['**/*.json', '**/*.dial']
    })
  ]
};

3. Or rename to .json:

mv schema.dial schema.json

TypeScript Errors

Problem: Type errors when using Dial components.

Solution: Install types:

npm install @vuer-ai/vuer-uikit

Ensure tsconfig includes types:

{
  "compilerOptions": {
    "types": ["@vuer-ai/vuer-uikit"]
  }
}

Module Resolution Issues

Problem: Cannot resolve '@vuer-ai/vuer-uikit'.

Solutions:

1. Check installation:

npm list @vuer-ai/vuer-uikit

2. Clear cache and reinstall:

rm -rf node_modules package-lock.json
npm install

3. Check import path:

// Correct
import { DialProvider } from '@vuer-ai/vuer-uikit';

// Wrong
import { DialProvider } from 'vuer-uikit';

Performance Issues

Slow Schema Generation

Problem: CLI takes too long to generate schemas.

Solutions:

1. Use --ignore to skip unnecessary props:

dial-cli Component.tsx --ignore "on*,_*,className,style"

2. Process fewer files at once:

# Instead of
dial-cli src/**/*.tsx

# Process in batches
dial-cli src/components/*.tsx
dial-cli src/pages/*.tsx

3. Disable verbose mode:

dial-cli Component.tsx --quiet

UI Lag with Many Controls

Problem: Panel becomes slow with many properties.

Solutions:

1. Use React.memo:

const MemoizedPanel = React.memo(DialPanel);

2. Debounce updates:

import { debounce } from 'lodash';

const debouncedChange = debounce(handleValueChange, 300);

<DialProvider onValueChange={debouncedChange}>

3. Split into multiple panels:

// Instead of one large panel
<DialPanel schemas={allSchemas} />

// Split by groups
<DialPanel schemas={transformSchemas} />
<DialPanel schemas={appearanceSchemas} />

Common Error Messages

"Cannot read property 'schemas' of undefined"

Cause: Schema file not loaded or wrong structure.

Fix:

// Check schema structure
import schemas from './schema.dial';
console.log(schemas); // Should be array

// Access correctly
const componentSchema = schemas[0]; // First component
const { schemas: propSchemas } = componentSchema;

"Invalid dtype: undefined"

Cause: Missing or invalid dtype in schema.

Fix:

// Ensure dtype is set
const schema = {
  name: 'prop',
  dtype: 'number' // Required
};

"Dial context not found"

Cause: Using dial hooks outside provider.

Fix:

// ❌ Outside provider
function App() {
  const { values } = useDialContext(); // Error
}

// ✅ Inside provider
function App() {
  return (
    <DialProvider schemas={schemas}>
      <ChildComponent /> {/* Can use hooks here */}
    </DialProvider>
  );
}

Debug Techniques

Enable Verbose Logging

# CLI verbose mode
dial-cli Component.tsx --verbose

# Check debug output
ls metadata/
cat metadata/ComponentName-debug.json

Validate Generated Schema

// validate-schema.js
const schemas = require('./metadata/schema.json');

schemas.forEach(component => {
  console.log(`Component: ${component.component}`);

  component.schemas.forEach(schema => {
    if (!schema.name) {
      console.error('Missing name:', schema);
    }
    if (!schema.dtype) {
      console.warn('Missing dtype:', schema.name);
    }
  });
});

Test Individual Components

// Test single schema
const testSchema: DialSchema = {
  name: 'test',
  dtype: 'number',
  min: 0,
  max: 100
};

<DialProvider schemas={[testSchema]}>
  <DialPanel schemas={[testSchema]} />
</DialProvider>

Getting Help

Resources

• GitHub Issues
• Discord Community
• Stack Overflow

Reporting Issues

When reporting issues, include:

1. Environment:

   • OS and version
   • Node.js version
   • Package versions

2. Reproduction:

   • Minimal code example
   • Exact commands run
   • Expected vs actual behavior

3. Debug info:

   • Error messages
   • Console output
   • Generated schemas (if applicable)

Example issue template:

## Environment
- OS: macOS 14.0
- Node: 18.17.0
- dial-cli: 0.0.22
- @vuer-ai/vuer-uikit: 0.1.0

## Steps to Reproduce
1. Create Component.tsx with [code]
2. Run `dial-cli Component.tsx`
3. Error occurs

## Expected
Schema should include all properties

## Actual
Properties with inheritance missing

## Debug Output
[Include --verbose output]

Next Steps