arc-humans-interface-db/docs/RETOOL_USAGE.md

How to Use ARC Renderer in Retool

Setup Instructions

Step 1: Add the JavaScript Code

1. In Retool, create a new JavaScript Query (or Code Block)
2. Copy the entire contents of arcRender.js
3. Paste it into the JavaScript Query
4. Name it something like arcRenderFunctions

Step 2: Create HTML Component for Main Puzzle Display

1. Add an HTML Component to your Retool app
2. In the HTML content field, use the following:

{{ renderArcPuzzle(query1.data) }}

Replace query1.data with your actual data source (could be from an API query, transformer, etc.)

Step 3: Create HTML Component for Test Output (Optional)

1. Add another HTML Component for the test output answer
2. Use:

{{ renderTestOutput(query1.data.test[0].output) }}

3. You can control visibility with a Toggle component or Button

Usage Examples

Example 1: Basic Usage with API Query

// In your HTML component:
{{ renderArcPuzzle(arcPuzzleQuery.data) }}

Example 2: With JSON Transformer

If your data needs transformation:

// In a Transformer:
return {
  train: transformedTrainData,
  test: transformedTestData
};

// In HTML component:
{{ renderArcPuzzle(transformer1.value) }}

Example 3: Toggle Test Output

Setup:

1. Add a Toggle component (name it showTestOutput)
2. Add an HTML component with conditional rendering:

{{ showTestOutput.value ? renderTestOutput(arcPuzzleQuery.data.test[0].output) : '' }}

Example 4: With Local JSON Data

// In a JavaScript Query, define your data:
const puzzleData = {
  "train": [
    {
      "input": [[0, 1, 2], [3, 4, 5]],
      "output": [[1, 2, 3], [4, 5, 6]]
    }
  ],
  "test": [
    {
      "input": [[0, 0, 0], [1, 1, 1]],
      "output": [[2, 2, 2], [3, 3, 3]]
    }
  ]
};

return puzzleData;

// In HTML component:
{{ renderArcPuzzle(jsQuery1.data) }}

Data Structure Requirements

Your JSON data must follow this structure:

{
  "train": [
    {
      "input": [[0, 1, 2], [3, 4, 5], [6, 7, 8]],
      "output": [[1, 2, 3], [4, 5, 6], [7, 8, 9]]
    }
  ],
  "test": [
    {
      "input": [[0, 1], [2, 3]],
      "output": [[1, 2], [3, 4]]
    }
  ]
}

• train: Array of training examples
• test: Array of test examples
• Each example has input and output as 2D arrays
• Values are integers 0-9 representing colors

Troubleshooting

"Invalid JSON data" Error

• Check that your data source is properly formatted
• Verify the JSON structure matches the required format
• Try parsing manually: JSON.parse(yourDataSource)

Grids Not Displaying

• Ensure the HTML component has sufficient height/width
• Check browser console for JavaScript errors
• Verify data is being passed correctly with {{ query1.data }}

Colors Look Wrong

• Verify your grid values are 0-9
• Check the color mapping in the code matches ARC standard

Customization

To modify styling, edit these values in arcRender.js:

• Cell size: Change cellSize = 20 (line 27)
• Grid border: Change border: 2px solid #000000 (line 38)
• Cell borders: Change border: 1px solid #DDDDDD (line 48)
• Spacing: Modify the spacing divs (lines 77, 91)
• Colors: Edit the ARC_COLORS object (lines 8-19)

Functions Available

renderArcPuzzle(jsonData)

• Purpose: Renders complete puzzle with training pairs and test input
• Input: ARC puzzle JSON object or string
• Output: HTML string
• Displays: All training INPUT-OUTPUT pairs + Test INPUT only

renderTestOutput(testOutputGrid)

• Purpose: Renders only the test output grid (the answer)
• Input: 2D array representing test output
• Output: HTML string
• Use case: For showing/hiding the puzzle answer

Performance Notes

• Fixed 20px cells work well for grids up to ~30×30
• Larger grids may require scrolling in the HTML component
• Consider adding overflow:auto to the HTML component for large puzzles