Coral (Indico's Annotatable Document Viewer)

A simple canvas designed to display a single page (image) of a document and annotations for that page.

Some of its perks:

• Responsive
• Zoomability
• Common out-of-the-box annotation types
  • Character-aware highlights
  • Coordinate-aware zones
• Custom annotation types (coming soon)
• Listeners for common on-document interactions (coming soon)

See the Storybook documentation for more information.

Installation

To install Coral, run yarn add @indico-data/coral or npm install @indico-data/coral.

To include the document viewer in a React component, import the component and minified CSS:

import { AnnotatableDocViewer } from '@indico-data/coral';
import '@indico-data/coral/dist/coral.css';

Available Scripts

Development

• yarn dev - Start Storybook development server on port 6006

Building

• yarn build - Build the library (Vite build + Typescript declaration fails)
• yarn build-storybook - Build the Storybook static site

Linting

• yarn lint - Run ESLint on TypeScript and JavaScript files in the src directory

Commit Hygiene

This repository follows a slightly modified version of the ESLint Commit Message Format. This repository uses the PR title to configure the contents of the commit message of the squashed commit associated with the PR: In general, a PR should use the following structure:

Title

The title should have the following format: <Tag>: <Short description>

The <Tag> should be Fix, Update, New, or Breaking for controlling releases.

If the PR need not be associated with a new release, choose any other <Tag> from the ESLint commit convention tags, such as Docs (documentation), Build (build process), Upgrade (dependency upgrade), or Chore (non-user-facing tasks).

Examples:

• Update: zoom value adjustment
• New: [SNC-222] virtual scroll

If your PR title does not follow these commit conventions, merging will be blocked.

See below for more information on how commit structure affects releases.

Releasing

This repository uses Semantic Release to control versioning and releases. Semantic Release's prime purpose is to remove developers from the version numbering process, and this repository embraces that philosophy.

Automatic Releases

Two things primarily determine how a new release is versioned:

1. The commit history leading up to the commit being released (to determine the base version from which to bump)
2. The message of the commit being released (to determine the version incrementation amount)

To release a new version as part of a pull request, use a semantic commit message (prefixes like Fix, Update, New, or Breaking) in the title of your pull request. This repo uses a slightly modified version of the ESLint conventional changelog to describe commit conventions.

• Fix or Update: Initiate a patch release
• New: Initiate a minor release
• Breaking: Initiate a major release

If your PR title does not follow these commit conventions, merging will be blocked.

Under the hood, Semantic Release controls the npm release process entirely by way of managed Git tags. Updating the package.json version number is unnecessary and discouraged.

Releasing a Non-Latest Version

To release a patch version on a previous major version:

• Checkout a new branch off the old version you'd like to release from: git checkout -b <branch-name> <tag-name> (e.g. git checkout -b ethan/patch-fix v2.0.2)
• Commit as normally, using the PR Title conventions outlined above
• Semantic Release will take care of the versioning

Tracking Releases

If you want to view the latest version of the Design System, you have a few options:

• From this repository, run yarn latest-release
• From outside this repository, run npm dist-tags ls @indico-data/design-system

If you want to see all releases:

• From this repository, run yarn all-releases
• From outside this repository, run npm view @indico-data/design-system versions
• View the git tags at https://github.com/IndicoDataSolutions/permafrost for specific information about each release
• Consult the npm registry at https://www.npmjs.com/package/@indico-data/design-system

Do NOT use the version attribute of package.json to track or initiate releases because:

• Semantic Release does not rely on this attribute to trigger releases: https://semantic-release.gitbook.io/semantic-release/support/faq
• Adding an additional commit to update the version number adds complexity to the CI process and clutters commit history

Manual Releases

Do not manually release Coral to npm, as it may cause issues with the Semantic Release pipeline.

Technical Decisions

1. The page image is displayed as a background image on the canvas instead of being drawn on the canvas, because it:
   • Avoids jaggedness and bluriness resulting from downscaling the image to the canvas dimensions, as modern browsers handle image scaling and anti-aliasing via CSS better than using canvas.
   • Appears to be less computationally expensive.
   • Still allows single-layer (single canvas) management of zoom and scroll containers.
   • The document viewer does not have any need to manipulate image pixels themselves.