Adding New Blocks

Extending the Editor: Adding New Blocks

The Statusline Editor is designed to be modular. To add a new block (e.g., a CPU usage monitor or a Kubernetes context tracker), you need to update four key areas: the state definition, the settings UI, the preview renderer, and the bash script generator.

1. Define the Block State

Add your new block configuration to the DEFAULTS object in js/state.js. This defines the default values for the block when the editor is reset.

// js/state.js
const DEFAULTS = {
  // ... existing fields
  blocks: [
    { 
      id: 'my-new-block', 
      name: 'Custom Block', 
      enabled: false, 
      color: 208, // ANSI color code
      someOption: true 
    },
    // ...
  ]
};

If your block requires live data for the preview, add a key to the MOCK object in the same file:

const MOCK = {
  // ...
  myCustomValue: 'Running',
};

2. Create the Settings UI

The settings panel is dynamically rendered based on the selected block. Update js/settings.js to handle your new block's ID.

1. Add a case to the switch statement in renderSettings().
2. Implement a specific render function using the provided UI helpers (buildRow, buildAnsiPalette, buildToggle, buildSegment).

// js/settings.js
function renderSettings() {
  // ...
  switch (block.id) {
    case 'my-new-block': renderCustomSettings(content, block); break;
    // ...
  }
}

function renderCustomSettings(el, block) {
  el.appendChild(buildRow('Text Color',
    buildAnsiPalette(block.color, v => { block.color = v; render(); })
  ));

  el.appendChild(buildRow('Enable Feature',
    buildToggle(block.someOption, 'Active Status', v => { block.someOption = v; render(); })
  ));
}

3. Implement the Preview Renderer

The preview simulates the terminal output using CSS. Update js/preview.js to determine how your block appears in the browser.

// js/preview.js
function renderPreview() {
  // ... inside the for (const block of state.blocks) loop
  switch (block.id) {
    case 'my-new-block':
      parts.push(`<span style="color:${ansiToCSS(block.color)}">${MOCK.myCustomValue}</span>`);
      break;
    // ...
  }
}

4. Logic for Script Generation

The final step is defining how the block is translated into the Bash script in js/generator.js.

1. Add the logic to extract data from the JSON_INPUT (passed by Claude Code).
2. Update the loop that assembles the parts array to include your block’s formatted shell string.

// js/generator.js
function generateScript() {
  // 1. Add data extraction logic near the top
  lines.push('custom_val=$(echo "$JSON_INPUT" | jq -r \'.custom_field // "N/A"\')');

  // 2. Add formatting logic in the blocks loop
  for (const block of state.blocks) {
    if (!block.enabled) continue;
    
    // ... 
    
    switch (block.id) {
      case 'my-new-block':
        // Use ansiEscape(code) helper for Bash ANSI sequences
        const color = ansiEscape(block.color);
        const reset = '\\033[0m';
        parts.push(`"${color}\${custom_val}${reset}"`);
        break;
    }
  }
}

Available UI Helpers

When building the settings UI in js/settings.js, use these built-in components to maintain visual consistency:

| Helper | Purpose | |---|---| | buildRow(label, element) | Wraps a setting with a label. | | buildAnsiPalette(current, onChange) | Opens the 256-color ANSI picker. | | buildToggle(checked, text, onChange) | Creates a checkbox switch. | | buildSegment(options, current, onChange) | Creates a group of segmented buttons. | | buildCounter(value, min, max, onChange) | Creates a numeric +/- incrementer. |