SquibView Programmer’s Guide

This guide provides detailed documentation for developers using SquibView in their applications.

Table of Contents

Installation

NPM

npm install squibview

CDN

<!-- Latest version --><scriptsrc="https://unpkg.com/squibview/dist/squibview.standalone.min.js"></script><linkrel="stylesheet"href="https://unpkg.com/squibview/dist/squibview.css">

Build Formats

SquibView is available in multiple formats:

ESM (ES Modules) - Default Build (v1.0.15+)

<!-- Optional dependencies for advanced features --><scriptsrc="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.5.1/highlight.min.js"></script><scriptsrc="https://unpkg.com/mermaid/dist/mermaid.min.js"></script><!-- SquibView (markdown-it is now bundled!) --><linkrel="stylesheet"href="../dist/squibview.css"><scripttype="module">importSquibViewfrom'../dist/squibview.esm.min.js';
  const editor = newSquibView('#editor');
</script>

ESM-Lean (Advanced Users)

<!-- Import map for external dependencies --><scripttype="importmap">
{
  "imports": {
    "markdown-it": "https://esm.sh/markdown-it@14.1.0",
    "tiny-emitter": "https://esm.sh/tiny-emitter@2.1.0",
    "diff-match-patch": "https://esm.sh/diff-match-patch@1.0.5"
  }
}
</script><!-- Optional dependencies --><scriptsrc="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.5.1/highlight.min.js"></script><!-- SquibView lean build --><scripttype="module">importSquibViewfrom'../dist/squibview.esm-lean.min.js';
  const editor = newSquibView('#editor');
</script>

UMD (Universal Module Definition) - Default Build (v1.0.15+)

<!-- Optional dependencies for advanced features --><scriptsrc="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.5.1/highlight.min.js"></script><scriptsrc="https://unpkg.com/mermaid/dist/mermaid.min.js"></script><!-- SquibView (markdown-it is now bundled!) --><linkrel="stylesheet"href="../dist/squibview.css"><scriptsrc="../dist/squibview.umd.min.js"></script><script>const editor = newSquibView('#editor');
</script>

UMD-Lean (Advanced Users)

<!-- Required dependencies --><scriptsrc="https://cdnjs.cloudflare.com/ajax/libs/markdown-it/14.1.0/markdown-it.min.js"></script><scriptsrc="https://unpkg.com/tiny-emitter@2.1.0/dist/tinyemitter.min.js"></script><scriptsrc="https://unpkg.com/diff-match-patch@1.0.5/index.js"></script><!-- Optional dependencies --><scriptsrc="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.5.1/highlight.min.js"></script><!-- SquibView lean build --><scriptsrc="../dist/squibview.umd-lean.min.js"></script><script>const editor = newSquibView('#editor');
</script>

Standalone (All Dependencies Bundled)

<!-- SquibView --><linkrel="stylesheet"href="../dist/squibview.css"><scriptsrc="../dist/squibview.standalone.min.js"></script><script>const editor = newSquibView('#editor');
</script>

Basic Usage

Creating an Instance

const editor = newSquibView('#editorContainer', {
  // Configuration options
});

Setting Content

// Set Markdown content
editor.setContent('# Hello World\n\nThis is a test.', 'md');

// Set HTML content
editor.setContent('<h1>Hello World</h1><p>This is a test.</p>', 'html');

// Set CSV content
editor.setContent('name,age\nJohn,30\nJane,25', 'csv');

Changing Views

// Switch to source view
editor.setView('src');

// Switch to rendered view
editor.setView('html');

// Switch to split view
editor.setView('split');

Configuration Options

Basic Options

const editor = newSquibView('#editorContainer', {
  initialContent: '',           // Initial content to loadinputContentType: 'md',       // Type of content ('md', 'html', 'reveal', 'csv', 'tsv')showControls: true,          // Whether to show control buttonstitleShow: false,            // Whether to show the title sectiontitleContent: '',            // Content for the title sectioninitialView: 'split',        // Initial view mode ('src', 'html', 'split')baseClass: 'squibview',      // Base CSS class for styling
});

Image Handling

const editor = newSquibView('#editorContainer', {
  preserveImageTags: true,     // Whether to keep original image URLs in source view// When true: images remain as <img> tags with original URLs// When false: images are converted to data URLs// Note: Images are always converted to data URLs when copying
});

Detailed Explanation of preserveImageTags:

The preserveImageTags option (boolean, defaults to true) controls how SquibView handles <img> tags when processing and displaying Markdown content, particularly in the source view and during copy operations.

When to Use Which Setting:

Text Selection

const editor = newSquibView('#editorContainer', {
  onReplaceSelectedText: (selectionData) => {
    // Handle text selectionreturn'replacement text';  // Return string to replace selection
  }
});

Content Types

Markdown (md)

HTML (html)

RevealJS (reveal)

CSV/TSV (csv, tsv)

API Reference

Core Methods

// Content Management
editor.setContent(content, contentType)  // Set content
editor.getContent()                      // Get current content
editor.getMarkdownSource()               // Get markdown source
editor.getHTMLSource()                   // Get HTML source// View Management
editor.setView(view)                     // Set view mode
editor.toggleView()                      // Toggle between views
editor.controlsShow(show)                // Show/hide controls
editor.titleShow(show)                   // Show/hide title
editor.titleSetContent(content)          // Set title content
editor.titleGetContent()                 // Get title content// Copy Operations
editor.copySource()                      // Copy source content
editor.copyHTML()                        // Copy rendered HTML// Revision History
editor.revisionUndo()                    // Undo last change
editor.revisionRedo()                    // Redo last change
editor.revisionSet(index)                // Set to specific revision
editor.revisionNumRevsions()             // Get number of revisions
editor.revisionGetCurrentIndex()         // Get current revision index// Diff Viewing (New in v1.0.13)
editor.getSourceDiff(options)            // Get diff data between revisions
editor.getSourceDiffHTML(options)        // Get side-by-side diff HTML
editor.getSourceDiffInline(options)      // Get inline diff HTML (blue/red)

Diff Viewing API

Compare different revisions of your content with visual diff displays.

getSourceDiff(options)

Returns raw diff data between two revisions.

// Get diff between current and previous revisionconst diffData = editor.getSourceDiff();

// Get diff between specific revisionsconst diffData = editor.getSourceDiff({ 
  fromIndex: 0,    // Starting revision (-1 for initial state)toIndex: 3// Ending revision
});

// Returns: { added, removed, changed, stats, patches }

getSourceDiffHTML(options)

Returns side-by-side diff visualization as HTML.

// Compare current vs previousconst diffHTML = editor.getSourceDiffHTML();

// Compare specific revisionsconst diffHTML = editor.getSourceDiffHTML({ 
  fromIndex: 1, 
  toIndex: 5,
  showLineNumbers: true// Optional
});

// Insert into pagedocument.getElementById('diff-view').innerHTML = diffHTML;

getSourceDiffInline(options)

Returns inline diff with blue additions and red strikethrough deletions.

// Get inline diffconst inlineHTML = editor.getSourceDiffInline({ 
  fromIndex: 0, 
  toIndex: -1// Compare against current
});

// Styling: additions in blue, deletions in red with strikethrough

Text Selection API

// Get current selectionconst selection = editor.getCurrentSelection();

// Replace selected text
editor.replaceSelectedText('new text', selection);

// Make selection editable/non-editable
editor.setSelectionEditable(true, selection);

// Toggle selection lock
editor.toggleSelectionLock(selection);

// Register selection callbackconst unsubscribe = editor.onTextSelected((selectionData) => {
  console.log('Selected:', selectionData.text);
});

React Integration

Basic Usage

import { SquibViewReact } from'squibview/react';

functionApp() {
  return (
    <SquibViewReactinitialContent="# Hello World"inputContentType="md"showControls={true}
    />
  );
}

Props

<SquibViewReact// Basic props
  initialContent=""
  inputContentType="md"
  showControls={true}
  titleShow={false}
  titleContent=""
  initialView="split"// Image handling
  preserveImageTags={true}
  
  // Event handlers
  onContentChange={(content, type) => {}}
  onViewChange={(view) => {}}
  onTextSelected={(selectionData) => {}}
/>

Plugin System

Creating a Plugin

const myPlugin = {
  name: 'myPlugin',
  init: (editor) => {
    // Plugin initialization
  },
  destroy: () => {
    // Cleanup
  }
};

// Register plugin
editor.registerPlugin(myPlugin);

Custom Renderers

editor.registerRenderer('custom', {
  render: (source) => {
    // Render source to HTMLreturn html;
  },
  sourceToOutput: (source) => {
    // Convert source to output formatreturn output;
  },
  outputToSource: (output) => {
    // Convert output back to sourcereturn source;
  },
  operations: {
    customOp: (source) => {
      // Custom operationreturn modifiedSource;
    }
  },
  buttons: [
    {
      label: 'Custom',
      action: 'customOp',
      title: 'Custom operation'
    }
  ]
});

Event System

Available Events

editor.events.on('content:change', (content, type) => {});
editor.events.on('view:change', (view) => {});
editor.events.on('text:selected', (selectionData) => {});
editor.events.on('markdown:rendered', (markdown, html) => {});
editor.events.on('html:rendered', (html) => {});
editor.events.on('revision:undo', (content, type) => {});
editor.events.on('revision:redo', (content, type) => {});
editor.events.on('revision:set', (index, content, type) => {});
editor.events.on('controls:visibility', (show) => {});
editor.events.on('title:visibility', (show) => {});
editor.events.on('title:content', (content) => {});
editor.events.on('layout:change', (view, dimensions) => {});
editor.events.on('renderer:registered', (type, config) => {});

Examples

Basic Markdown Editor

const editor = newSquibView('#editor', {
  initialContent: '# Hello World\n\nThis is a test.',
  inputContentType: 'md',
  showControls: true,
  initialView: 'split'
});

CSV Viewer

const editor = newSquibView('#editor', {
  initialContent: 'name,age\nJohn,30\nJane,25',
  inputContentType: 'csv',
  showControls: true,
  initialView: 'html'
});

RevealJS Presentation

const editor = newSquibView('#editor', {
  initialContent: '# Slide 1\n\nContent\n\n---\n\n# Slide 2\n\nMore content',
  inputContentType: 'reveal',
  showControls: true,
  initialView: 'html'
});

React Component with Image Handling

import { SquibViewReact } from'squibview/react';

functionApp() {
  return (
    <SquibViewReactinitialContent="# Image Example\n\n![Test](./test.png)"inputContentType="md"preserveImageTags={true}onContentChange={(content,type) => {
        console.log('Content changed:', content);
      }}
    />
  );
}

Development and Testing

This section provides information for developers contributing to SquibView or setting up a local development environment.

Version Bumping and Testing Script

For local development, a convenient script dev-bump-build-test.sh is provided in the root of the repository. This script automates several common tasks:

  1. Bumps the Patch Version: It increments the patch version number of the library (e.g., from 0.0.38 to 0.0.39).
  2. Sets a Prerelease Identifier: It then sets a development prerelease identifier (e.g., 0.0.39-dev.0). This uses npm version prepatch --preid dev internally.
  3. Updates src/version.js: The script runs tools/updateVersion.js to propagate the new version from package.json to src/version.js, ensuring the library reports the correct version at runtime.
  4. Builds the Library: It performs a full build of SquibView.
  5. Runs Tests: It executes all unit and integration tests.
  6. Logs Output: All output from the script (build and test logs) is displayed in the terminal and also saved to tests/log.out for easier debugging.

Usage:

To run the script, navigate to the root of the SquibView repository in your terminal and execute:

./dev-bump-build-test.sh

This script is particularly useful for quickly testing changes with an updated version number in a development context without creating git tags.

For more comprehensive information on the development workflow, versioning strategy, running tests, and debugging, please refer to the CONTRIBUTING.md file.

For browser environments, you can use a <script> tag pointing to a CDN:

<scriptsrc="https://unpkg.com/squibview/dist/squibview.standalone.umd.min.js"></script>

Or, if you have it locally:

<scriptsrc="../dist/squibview.standalone.umd.min.js"></script>

Basic Instantiation

const editor = newSquibView('#editorContainer', {
  // Configuration options
});