Renderer Interface

A renderer is any object with a render(song) method. The method receives the parsed song tree and returns whatever output format the renderer targets.

class MyRenderer {
  render(song) {
    // Walk the song tree and produce output.
    // song.sections    — array of Section objects
    //   section.label  — e.g. "Verse", or null
    //   section.key    — key override for this section, or null
    //   section.rows   — array of Row objects (chords only, no comment lines)
    //     row.bars     — array of Bar objects
    //       bar.cells  — array of BeatCells (chord or dot)
    //       bar.closeBarline — closing barline descriptor
  }
}

There are no required base classes or interfaces to extend. Any object that responds to render(song) and returns the appropriate output is a valid renderer.

Song tree structure

Song

Section

rows is a filtered view of content — the same rows in the same order, with comment lines removed. Most renderers should use rows; use content only when comment lines matter to your output.

Row

Bar

Barline

type BarlineKind =
  | 'single'               // |
  | 'double'               // ||
  | 'final'                // ||.
  | 'startRepeat'          // ||:
  | 'endRepeat'            // :||
  | 'endRepeatStartRepeat' // :||:

BeatSlot

type BeatSlot =
  | { type: 'chord'; chord: Chord; loc?: SourceRange }
  | { type: 'dot';               loc?: SourceRange }  // . — hold/sustain

Chord

Quality

type Quality =
  | 'major'           //  (no suffix)
  | 'minor'           // m
  | 'dominant7'       // 7
  | 'maj7'            // maj7 or M7
  | 'min7'            // m7 or -
  | 'dim7'            // dim7
  | 'diminished'      // dim
  | 'halfDiminished'  // m7b5
  | 'dom7flat5'       // 7b5

TimeSignature

CommentLine

SourceRange

All AST nodes carry an optional loc property with 0-based LSP-style positions.

interface SourceRange {
  start: { line: number; character: number };
  end:   { line: number; character: number };
}

Custom element renderer

To implement a custom renderer as a Web Component that works with <grigson-chart>, implement the GrigsonRendererElement contract:

interface GrigsonRendererElement extends HTMLElement {
  renderChart(song: Song): Element;
}

<grigson-chart> calls renderChart() on every child element that implements this method, and places the returned element into its shadow root in DOM order. If no child renderer is present, it falls back to GrigsonHtmlRenderer automatically.

class MyCustomRenderer extends HTMLElement {
  renderChart(song) {
    const div = document.createElement('div');
    // … populate div from song …
    return div;
  }
}

customElements.define('my-custom-renderer', MyCustomRenderer);

<grigson-chart>
  <my-custom-renderer></my-custom-renderer>
  <template>| C | Am | F | G |</template>
</grigson-chart>

When your element's configuration changes and <grigson-chart> should re-render, dispatch a GrigsonRendererUpdateEvent:

import { GrigsonRendererUpdateEvent } from 'grigson';

this.dispatchEvent(new GrigsonRendererUpdateEvent());

<grigson-chart> also dispatches events you can listen to: