martijnversluis · martijnversluis · Jan 21, 2025 · Jan 19, 2025
diff --git a/src/formatter/formatter.ts b/src/formatter/formatter.ts
@@ -7,22 +7,22 @@ class Formatter {
   configuration: Configuration;
 
   /**
-     * Instantiate
-     * @param {Object} [configuration={}] options
-     * @param {boolean} [configuration.evaluate=false] Whether or not to evaluate meta expressions.
-     * For more info about meta expressions, see: https://bit.ly/2SC9c2u
-     * @param {object} [configuration.metadata={}]
-     * @param {string} [configuration.metadata.separator=", "] The separator to be used when rendering a
-     * metadata value that has multiple values. See: https://bit.ly/2SC9c2u
-     * @param {Key|string} [configuration.key=null] The key to use for rendering. The chord sheet will be
-     * transposed from the song's original key (as indicated by the `{key}` directive) to the specified key.
-     * Note that transposing will only work if the original song key is set.
-     * @param {boolean} [configuration.expandChorusDirective=false] Whether or not to expand `{chorus}` directives
-     * by rendering the last defined chorus inline after the directive.
-     * @param {boolean} [configuration.useUnicodeModifiers=false] Whether or not to use unicode flat and sharp
-     * symbols.
-     * @param {boolean} [configuration.normalizeChords=true] Whether or not to automatically normalize chords
-     */
+   * Instantiate
+   * @param {Object} [configuration={}] options
+   * @param {boolean} [configuration.evaluate=false] Whether or not to evaluate meta expressions.
+   * For more info about meta expressions, see: https://bit.ly/2SC9c2u
+   * @param {object} [configuration.metadata={}]
+   * @param {string} [configuration.metadata.separator=", "] The separator to be used when rendering a
+   * metadata value that has multiple values. See: https://bit.ly/2SC9c2u
+   * @param {Key|string} [configuration.key=null] The key to use for rendering. The chord sheet will be
+   * transposed from the song's original key (as indicated by the `{key}` directive) to the specified key.
+   * Note that transposing will only work if the original song key is set.
+   * @param {boolean} [configuration.expandChorusDirective=false] Whether or not to expand `{chorus}` directives
+   * by rendering the last defined chorus inline after the directive.
+   * @param {boolean} [configuration.useUnicodeModifiers=false] Whether or not to use unicode flat and sharp
+   * symbols.
+   * @param {boolean} [configuration.normalizeChords=true] Whether or not to automatically normalize chords
+   */
   constructor(configuration: ConfigurationProperties = {}) {
     this.configuration = configure(configuration);
   }

diff --git a/src/formatter/html_div_formatter.ts b/src/formatter/html_div_formatter.ts
@@ -1,36 +1,35 @@
-import HtmlFormatter, { CSS, Template } from './html_formatter';
+import HtmlFormatter, { CSS, HtmlTemplateCssClasses, Template } from './html_formatter';
 import template from './templates/html_div_formatter';
-import { scopeCss } from '../utilities';
 
-const defaultCss: CSS = {
-  '.chord:not(:last-child)': {
-    paddingRight: '10px',
-  },
-
-  '.paragraph': {
-    marginBottom: '1em',
-  },
-
-  '.row': {
-    display: 'flex',
-  },
-
-  '.chord:after': {
-    content: '\'\\200b\'',
-  },
-
-  '.lyrics:after': {
-    content: '\'\\200b\'',
-  },
-};
-
-/**
- * Generates basic CSS, scoped within the provided selector, to use with output generated by {@link HtmlTableFormatter}
- * @param scope the CSS scope to use, for example `.chordSheetViewer`
- * @returns {string} the CSS string
- */
-export function scopedCss(scope: string): string {
-  return scopeCss(defaultCss, scope);
+function defaultCss(cssClasses: HtmlTemplateCssClasses): CSS {
+  const {
+    chord,
+    lyrics,
+    paragraph,
+    row,
+  } = cssClasses;
+
+  return {
+    [`.${chord}:not(:last-child)`]: {
+      paddingRight: '10px',
+    },
+
+    [`.${paragraph}`]: {
+      marginBottom: '1em',
+    },
+
+    [`.${row}`]: {
+      display: 'flex',
+    },
+
+    [`.${chord}:after`]: {
+      content: '\'\\200b\'',
+    },
+
+    [`.${lyrics}:after`]: {
+      content: '\'\\200b\'',
+    },
+  };
 }
 
 /**
@@ -42,7 +41,7 @@ class HtmlDivFormatter extends HtmlFormatter {
   }
 
   get defaultCss(): CSS {
-    return defaultCss;
+    return defaultCss(this.cssClasses);
   }
 }
 

diff --git a/src/formatter/html_formatter.ts b/src/formatter/html_formatter.ts
@@ -1,23 +1,98 @@
 import Formatter from './formatter';
-import Configuration from './configuration';
+import Configuration, { ConfigurationProperties } from './configuration';
 import Song from '../chord_sheet/song';
 import { scopeCss } from '../utilities';
 import Paragraph from '../chord_sheet/paragraph';
 
+export interface HtmlTemplateCssClasses {
+  annotation: string,
+  chord: string,
+  chordSheet: string,
+  column: string,
+  comment: string,
+  emptyLine: string,
+  label: string,
+  labelWrapper: string,
+  line: string,
+  literal: string,
+  literalContents: string,
+  lyrics: string,
+  paragraph: string,
+  row: string,
+  subtitle: string,
+  title: string,
+}
+
 export interface HtmlTemplateArgs {
   configuration: Configuration;
   song: Song;
   renderBlankLines?: boolean;
   bodyParagraphs: Paragraph[],
+  cssClasses: HtmlTemplateCssClasses,
 }
 
 export type Template = (_args: HtmlTemplateArgs) => string;
 export type CSS = Record<string, Record<string, string>>;
 
+export const defaultCssClasses: HtmlTemplateCssClasses = {
+  annotation: 'annotation',
+  chord: 'chord',
+  chordSheet: 'chord-sheet',
+  column: 'column',
+  comment: 'comment',
+  emptyLine: 'empty-line',
+  label: 'label',
+  labelWrapper: 'label-wrapper',
+  line: 'line',
+  literal: 'literal',
+  literalContents: 'contents',
+  lyrics: 'lyrics',
+  paragraph: 'paragraph',
+  row: 'row',
+  subtitle: 'subtitle',
+  title: 'title',
+};
+
 /**
  * Acts as a base class for HTML formatters
  */
 abstract class HtmlFormatter extends Formatter {
+  cssClasses: HtmlTemplateCssClasses;
+
+  /**
+   * Instantiate the formatter. For all options see {@link Formatter}
+   * @param {Object} [configuration={}] options
+   * @param {object} [configuration.cssClasses={}] CSS classes to use in the HTML output. The default classes are
+   * defined in {@link defaultCssClasses}. You can override them by providing your own classes here:
+   * @example
+   * ```javascript
+   * {
+   *    cssClasses: {
+   *      annotation: 'my-annotation',
+   *      chord: 'my-chord',
+   *      chordSheet: 'my-chord-sheet',
+   *      column: 'my-column',
+   *      comment: 'my-comment',
+   *      emptyLine: 'my-empty-line',
+   *      label: 'my-label',
+   *      labelWrapper: 'my-label-wrapper',
+   *      line: 'my-line',
+   *      literal: 'my-literal',
+   *      literalContents: 'my-contents',
+   *      lyrics: 'my-lyrics',
+   *      paragraph: 'my-paragraph',
+   *      row: 'my-row',
+   *      subtitle: 'my-subtitle',
+   *      title: 'my-title',
+   *    }
+   *  }
+   *  ```
+   */
+  constructor(configuration: ConfigurationProperties & { cssClasses?: Partial<HtmlTemplateCssClasses> } = {}) {
+    super(configuration);
+    this.cssClasses = { ...defaultCssClasses, ...configuration.cssClasses };
+  }
+
   /**
    * Formats a song into HTML.
    * @param {Song} song The song to be formatted
@@ -31,6 +106,7 @@ abstract class HtmlFormatter extends Formatter {
         song,
         configuration: this.configuration,
         bodyParagraphs: this.configuration.expandChorusDirective ? expandedBodyParagraphs : bodyParagraphs,
+        cssClasses: this.cssClasses,
       },
     );
   }
@@ -48,7 +124,7 @@ abstract class HtmlFormatter extends Formatter {
    * @returns {string} the CSS string
    */
   cssString(scope = ''): string {
-    return scopeCss(this.defaultCss, scope);
+    return scopeCss(this.cssObject, scope);
   }
 
   /**

diff --git a/src/formatter/html_table_formatter.ts b/src/formatter/html_table_formatter.ts
@@ -1,36 +1,43 @@
-import HtmlFormatter, { Template, CSS } from './html_formatter';
+import HtmlFormatter, { Template, CSS, HtmlTemplateCssClasses } from './html_formatter';
 import template from './templates/html_table_formatter';
-import { scopeCss } from '../utilities';
 
-const defaultCss: CSS = {
-  'h1': {
-    fontSize: '1.5em',
-  },
-  'h2': {
-    fontSize: '1.1em',
-  },
-  'table': {
-    borderSpacing: '0',
-    color: 'inherit',
-  },
-  'td': {
-    padding: '3px 0',
-  },
-  '.chord:not(:last-child)': {
-    paddingRight: '10px',
-  },
-  '.paragraph': {
-    marginBottom: '1em',
-  },
-};
+function defaultCss(cssClasses: HtmlTemplateCssClasses): CSS {
+  const {
+    annotation,
+    chord,
+    comment,
+    labelWrapper,
+    line,
+    literal,
+    literalContents,
+    lyrics,
+    paragraph,
+    row,
+    subtitle,
+    title,
+  } = cssClasses;
 
-/**
- * Generates basic CSS, scoped within the provided selector, to use with output generated by {@link HtmlTableFormatter}
- * @param scope the CSS scope to use, for example `.chordSheetViewer`
- * @returns {string} the CSS string
- */
-export function scopedCss(scope: string): string {
-  return scopeCss(defaultCss, scope);
+  return {
+    [`.${title}`]: {
+      fontSize: '1.5em',
+    },
+    [`.${subtitle}`]: {
+      fontSize: '1.1em',
+    },
+    [`.${row}, .${line}, .${literal}`]: {
+      borderSpacing: '0',
+      color: 'inherit',
+    },
+    [`.${annotation}, .${chord}, .${comment}, .${literalContents}, .${labelWrapper}, .${literal}, .${lyrics}`]: {
+      padding: '3px 0',
+    },
+    [`.${chord}:not(:last-child)`]: {
+      paddingRight: '10px',
+    },
+    [`.${paragraph}`]: {
+      marginBottom: '1em',
+    },
+  };
 }
 
 /**
@@ -43,7 +50,7 @@ class HtmlTableFormatter extends HtmlFormatter {
   }
 
   get defaultCss(): CSS {
-    return defaultCss;
+    return defaultCss(this.cssClasses);
   }
 }
 

diff --git a/src/formatter/templates/html_div_formatter.ts b/src/formatter/templates/html_div_formatter.ts
@@ -31,35 +31,36 @@ export default (
       metadata,
     },
     bodyParagraphs,
+    cssClasses: c,
   }: HtmlTemplateArgs,
 ): string => stripHTML(`
-  ${ when(title, () => `<h1>${ title }</h1>`) }
-  ${ when(subtitle, () => `<h2>${ subtitle }</h2>`) }
+  ${ when(title, () => `<h1 class="${ c.title }">${ title }</h1>`) }
+  ${ when(subtitle, () => `<h2 class="${ c.subtitle }">${ subtitle }</h2>`) }
 
-  <div class="chord-sheet">
+  <div class="${ c.chordSheet }">
     ${ each(bodyParagraphs, (paragraph) => `
-      <div class="${ paragraphClasses(paragraph) }">
+      <div class="${ paragraphClasses(paragraph, c) }">
         ${ when(paragraph.isLiteral(), () => `
           ${ when(isPresent(paragraph.label), () => `
-            <div class="row">
-              <h3 class="label">${ paragraph.label }</h3>
+            <div class="${ c.row }">
+              <h3 class="${ c.label }">${ paragraph.label }</h3>
             </div>
           `) }
 
-          <div class="row">
-            <div class="literal">${ newlinesToBreaks(renderSection(paragraph, configuration)) }</div>
+          <div class="${ c.row }">
+            <div class="${ c.literal }">${ newlinesToBreaks(renderSection(paragraph, configuration)) }</div>
           </div>
         `).else(() => `
           ${ each(paragraph.lines, (line) => `
             ${ when(renderBlankLines || lineHasContents(line), () => `
-              <div class="${ lineClasses(line) }">
+              <div class="${ lineClasses(line, c) }">
                 ${ each(line.items, (item) => `
                   ${ when(isChordLyricsPair(item), () => `
-                    <div class="column">
+                    <div class="${ c.column }">
                      ${ when(item.annotation).then(() => `
-                       <div class="annotation"${ fontStyleTag(line.chordFont) }>${ item.annotation }</div>
+                       <div class="${ c.annotation }"${ fontStyleTag(line.chordFont) }>${ item.annotation }</div>
                      `).else(() => `
-                        <div class="chord"${ fontStyleTag(line.chordFont) }>
+                        <div class="${ c.chord }"${ fontStyleTag(line.chordFont) }>
                           ${ renderChord(
                             item.chords,
                             line,
@@ -73,20 +74,20 @@ export default (
                           ) }
                         </div>
                      `) }
-                      <div class="lyrics"${ fontStyleTag(line.textFont) }>${ item.lyrics }</div>
+                      <div class="${ c.lyrics }"${ fontStyleTag(line.textFont) }>${ item.lyrics }</div>
                     </div>
                   `).elseWhen(isTag(item), () => `
                     ${ when(isComment(item), () => `
-                      <div class="comment">${ item.value }</div>
+                      <div class="${ c.comment }">${ item.value }</div>
                     `) }
 
                     ${ when(item.hasRenderableLabel(), () => `
-                      <h3 class="label">${ item.label }</h3>
+                      <h3 class="${ c.label }">${ item.label }</h3>
                     `) }
                   `).elseWhen(isEvaluatable(item), () => `
-                    <div class="column">
-                      <div class="chord"></div>
-                      <div class="lyrics"${ fontStyleTag(line.textFont) }>
+                    <div class="${ c.column }">
+                      <div class="${ c.chord }"></div>
+                      <div class="${ c.lyrics }"${ fontStyleTag(line.textFont) }>
                         ${ evaluate(item, metadata, configuration) }
                       </div>
                     </div>