npm package: @indico-data/coral
Description: A simple canvas designed to display a single page (image) of a document and annotations for that page.
Author: Ethan Weiner
Latest version: 1.5.0

# Coral (Indico's Annotatable Document Viewer)

![Image](https://external-content.duckduckgo.com/iu/?u=http%3A%2F%2Fwww.deadlinenews.co.uk%2Fwp-content%2Fuploads%2F2020%2F09%2Fq-u-i-0G01UI1MQhg-unsplash-scaled.jpg&f=1&nofb=1&ipt=9cd5669a470e874d16ab40af75c600b5525cf36e5988403b05dd07e23a29793a)

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:

```tsx
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](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-eslint). 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](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-eslint#eslint-convention), 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](https://github.com/semantic-release/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](https://github.com/semantic-release/semantic-release?tab=readme-ov-file#commit-message-format) (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](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-eslint) 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](https://semantic-release.gitbook.io/semantic-release/support/faq#why-is-the-package.jsons-version-not-updated-in-my-repository). 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.