notations-web

Web components for the Notations library - interactive notation blocks, editors, and viewers for Carnatic music notation.

Installation

npm install notations-web notations

Note: notations is a peer dependency and must be installed separately.

Components

NotationBlock

Interactive component for rendering <notation> tags with optional source code display.

Basic Usage

import { NotationBlock, NotationBlockConfig } from "notations-web";
import * as N from "notations";

// Define your viewer factory
function createViewer(container: HTMLDivElement): N.Carnatic.NotationView {
  const tableElement = document.createElement("table");
  tableElement.classList.add("notation-table");
  container.appendChild(tableElement);
  return new N.Carnatic.NotationView(tableElement);
}

// Configure the component
const config: NotationBlockConfig = {
  createViewer,
  cssClasses: {
    sourceContainer: "bg-gray-100",
    sourceCaption: "font-bold",
    sourceCode: "text-sm",
    outputContainer: "p-4",
  }
};

// Find and process all <notation> tags
document.addEventListener("DOMContentLoaded", () => {
  const notations = document.querySelectorAll("notation");
  notations.forEach(container => {
    new NotationBlock(container as HTMLElement, config);
  });
});

HTML Usage

<notation id="example1" showSource="true" caption="Basic Scale">
S R G M P D N S'
sa ri ga ma pa dha ni sa
</notation>

Attributes

• id (optional): Unique identifier, auto-generated if not provided
• caption (optional): Caption text for the source code block
• showSource (optional): Set to "true" to display source code (default: "false")
• sourceFrom (optional): ID of another element to read source from
• height (optional): Height constraint for the output

Configuration

interface NotationBlockConfig {
  createViewer: (container: HTMLDivElement) => N.Carnatic.NotationView;
  cssClasses?: {
    root?: string;              // Applied to root container
    sourceContainer?: string;   // Applied to source code container
    sourceCaption?: string;     // Applied to caption
    sourceCode?: string;        // Applied to code element
    outputLabel?: string;       // Applied to "Output:" label
    outputContainer?: string;   // Applied to notation output container
  };
}

Examples

With Tailwind CSS

const config: NotationBlockConfig = {
  createViewer,
  cssClasses: {
    sourceContainer: "bg-white dark:bg-gray-800 rounded-lg p-4",
    sourceCaption: "text-lg font-semibold text-gray-900 dark:text-gray-100",
    sourceCode: "text-sm font-mono text-gray-800 dark:text-gray-200",
    outputContainer: "overflow-auto bg-white dark:bg-gray-700",
  }
};

With Custom CSS

const config: NotationBlockConfig = {
  createViewer,
  cssClasses: {
    sourceContainer: "notation-source-custom",
    sourceCaption: "notation-caption-custom",
    outputContainer: "notation-output-custom",
  }
};

Development

This package is part of the Notations monorepo.

# Build the package
npm run build

# Watch for changes
npm run watch

SideBySideEditor

Editor and output components with synchronized scrolling.

import { SideBySideEditor, SideBySideEditorConfig } from "notations-web";

const config: SideBySideEditorConfig = {
  initialSource: "S R G M P",
  syncScroll: true,
  debounceDelay: 300,
  onSourceChange: (source) => console.log("Changed:", source),
  onNotationParsed: (notation, beatLayout) => console.log("Parsed"),
  onParseError: (errors) => console.error(errors),
};

const editor = new SideBySideEditor(config);

// Place elements in your layout
leftPanel.appendChild(editor.editorElement);
rightPanel.appendChild(editor.outputElement);

// Programmatic control
editor.source = "new source";
editor.render();

DockViewPlayground

Complete playground with resizable DockView panels (editor, output, console).

import { DockViewPlayground, DockViewPlaygroundConfig } from "notations-web";

const config: DockViewPlaygroundConfig = {
  initialSource: "S R G M P",
  showConsole: true,
  persistLayout: true,
  storageKey: "my-playground-layout",
  layoutVersion: 1,  // Increment to force layout reset
  syncScroll: true,
  markdownParser: (content) => marked.parse(content),
  onSourceChange: (source) => console.log("Changed"),
  onNotationParsed: (notation, beatLayout) => console.log("Parsed"),
  onParseError: (errors) => console.error(errors),
};

const playground = new DockViewPlayground(container, config);

// Console API
playground.log("Hello!", "info");
playground.showConsole();
playground.hideConsole();
playground.toggleConsole();
playground.clearConsole();

// Other methods
playground.source = "new source";
playground.render();
playground.resetLayout();

CSS Theming

DockViewPlayground uses CSS classes for theming. Define styles for:

/* Panel backgrounds */
.dvp-panel { background: #fff; color: #333; }
.dark .dvp-panel { background: #1e1e1e; color: #e0e0e0; }

/* Console elements */
.dvp-console-header { border-bottom: 1px solid #e0e0e0; }
.dvp-console-clear-btn { background: #fff; border: 1px solid #ddd; }
.dvp-console-output { /* styles */ }

License

ISC

Repository

https://github.com/panyam/notations