Create Detector

Create Detector

This skill creates new MUI component detectors for the HTML parser.

When to Use

Use this skill when:

• Adding support for a new MUI component type
• The user provides HTML samples of a component to detect

Prerequisites

Gather from the user:

1. HTML sample - Real HTML of the MUI component (ideally both states if applicable)
2. Description - What the component does / represents in the form

Process

Step 1: Identify MUI Component

Analyze the HTML to identify which MUI component it is:

• Look for MUI class patterns: Mui{Component}-{part} (e.g., MuiSwitch-root, MuiAutocomplete-root)
• Common components: Switch, TextField, Autocomplete, Select, Checkbox, RadioGroup, DatePicker
• Determine the field kind from the MUI component name (e.g., MuiSwitch → "toggle", MuiAutocomplete → "autocomplete")

Step 2: Analyze Structure

Examine the HTML to identify:

• Root element: Tag, identifying classes, data-testid
• Nested structure: Required child elements that define the component
• Unique identifier: What makes each instance unique (typically input[name])
• State indicator: How to determine the current value (class presence, attribute, etc.)
• Portaled elements: Some MUI components render parts at document root (menus, modals, dialogs). Look for ID patterns linking component to portal (e.g., #menu-{fieldName}, #dialog-{id})

Step 3: Design Meta Fields

Determine what selectors are needed for page object interaction:

• What element(s) need to be located for reading state?
• What element(s) need to be located for writing/changing state?
• Meta fields can be relative (to path) or absolute (for portaled elements)
• For portaled content, use role-based selectors (e.g., [role="listbox"] [role="option"])

IMPORTANT - Meta Field Rules:

1. Meta fields are LOCATORS, not values - Never extract actual text/values, always provide selectors
2. NEVER use element IDs in locators - MUI generates dynamic IDs like :r4v: that change between renders
3. Prefer role-based selectors - Use [role="option"], [role="listbox"], etc. for accessibility elements
4. Prefer data-testid selectors - Use [data-testid="..."] when available
5. Prefer class-based selectors - Use .MuiComponent-part patterns as fallback

Step 4: Create Detector Folder

Create src/detectors/{kind}/ with files:

src/detectors/{kind}/
├── types.ts      # {Kind}Meta, {Kind}Node interfaces
├── validate.ts   # Validation function
├── detector.ts   # Detector implementation
├── index.ts      # Exports
└── doc.md        # Documentation

Use templates from references/templates.md.

Step 5: Implement Validation

In validate.ts:

• Check root element tag and attributes
• Validate nested structure exists
• Return false if any check fails
• Return true if all checks pass

Step 6: Implement Detector

In detector.ts:

• Call validate function
• Construct path selector that uniquely identifies the component
• Construct meta object with sub-element selectors
• Return DetectionResult with node and childContainers

Step 7: Document Meta Fields

In doc.md:

• Include example HTML (both states if applicable)
• Show example JSON output
• Document each meta field with description
• Explain value handling - be EXACT about state checking (e.g., which class indicates ON/OFF)

Step 8: Register Detector

Update src/detectors/index.ts:

1. Import the detector: import { {kind}Detector } from "./{kind}";
2. Add to detectors array
3. Re-export types: export type { {Kind}Meta, {Kind}Node } from "./{kind}";

Step 9: Create Tests

Create tests/detectors/{kind}.test.ts:

• Test valid detection with expected output
• Test rejection of invalid structures

Output Schema Reference

Every detector produces:

{
  type: "field" | "section",
  kind: string,                    // detector name
  path: string,                    // selector to locate root element
  meta: { [key: string]: string }  // selectors (relative to path, or absolute for portals)
}

Templates

See references/templates.md for file templates.

Converted and distributed by TomeVault — claim your Tome and manage your conversions.