CogappLabs · jonw-cogapp · Sep 18, 2023 · Aug 23, 2023 · Aug 23, 2023 · Aug 23, 2023
diff --git a/.husky/pre-commit b/.husky/pre-commit
@@ -0,0 +1,19 @@
+#!/usr/bin/env sh
+
+# Exit 0 for CI environments
+[ -n "$CI" ] && exit 0
+
+. "$(dirname -- "$0")/_/husky.sh"
+
+# Run lint-staged
+npx lint-staged
+
+# Check if any TypeScript files are staged for commit
+if git diff --cached --name-only --diff-filter=ACMRTUXB | grep -q '\.ts$'; then
+  # Run Typedoc and add the regenerated docs to the commit if any changes were made
+  npm run docs
+  git add docs/api/
+else
+  exit 0
+fi
+
diff --git a/.lintstagedrc b/.lintstagedrc
@@ -0,0 +1,8 @@
+{
+  "*.ts": [
+    "eslint --fix",
+    "prettier -w",
+    "bash -c 'npx tsc -p tsconfig.json --noEmit'"
+  ],
+  "!(docs/api/**/*)*.css": ["stylelint --fix", "prettier -w"]
+}
diff --git a/README.md b/README.md
@@ -4,11 +4,87 @@ Storiiies Viewer is an open source viewer for [Storiiies](https://www.cogapp.com
 
 ## Usage
 
-TODO
+### Adding the dependencies
+
+There are two options for adding StoriiiesViewer to your project:
+
+#### In the browser
+
+(This is the quickest and easiest way to get started)
+
+You can include the JavaScript and CSS in the HTML like so, using the [unpkg CDN](https://unpkg.com/):
+
+```HTML
+<head>
+  <!-- ... -->
+  <link rel="stylesheet" href="https://unpkg.com/browse/@cogapp/storiiiesviewer@latest/dist/storiiies-viewer.css">
+  <script src="https://unpkg.com/browse/@cogapp/storiiiesviewer@latest/dist/umd/storiiies-viewwer.js"></script>
+  <!-- ... -->
+</head>
+```
+
+Or you could save these files and serve them locally if you prefer.
+
+Including the JavaScript file this way will make `StoriiiesViewer` available globally in JavaScript.
+
+
+#### Using a bundler
+
+1. Install the dependecy with `npm install @cogapp/storiiiesviewer`
+2. Use `import StoriiiesViewer from '@cogapp/storiiiesviewer'` in your code to access the StoriiiesViewer constructor
+3. Depending on how your tooling handles importing CSS you might also be able to import the CSS file with `import @cogapp/storiiiesviewer/dist/storiiies-viewer.css` — but you could also use the method above, or copy the contents of the CSS file into your own src files.
+
+
+### Initialise a viewer
+In your HTML:
+```HTML
+<div id="storiiies-viewer"></div>
+```
+
+In your JavaScript
+```JS
+document.addEventListener('DOMContentLoaded', () => {
+  const myViewer = new StoriiiesViewer({
+    container: "#storiiies-viewer", // or document.querySelector("#storiiies-viewer")
+    manifestUrl: "https://path-to-your-storiiies-manifest",
+  });
+});
+```
 
 ## Customisation
 
-TODO
+To customize of appearance of StoriiiesViewer you have a few options:
+
+1. If you'd prefer to bring all your own styles, StoriiiesViewer can be styled from scratch without needing to include the default stylesheet
+2. To 'theme' StoriiiesViewer, you may find the custom properties provided by the default stylesheet to be sufficient
+3. Start with default stylesheet and expand or override these styles as you see fit
+
+
+
+## Supported manifest formats
+StoriiiesViewer supports a subset of the [IIIF presentation API v3](https://iiif.io/api/presentation/3.0/). Specifically, we target `annotationPages` which are included directly in the manifest ([like in this cookbook recipe](https://iiif.io/api/cookbook/recipe/0258-tagging-external-resource/)).
+
+Annotations themselves can either be `text/plain` or `text/html` denoted by the `format` field. For `text/plain` newline characters will be converted and output as `<br>` tags.
+
+StoriiiesViewer has no required fields (aside from those required by the presentation API), but it will render certain values from the manifest if provided. These are:
+
+- [A manifest `label`](https://iiif.io/api/presentation/3.0/#label), which is required by the presentation API and will be shown on a "title slide", before any annotations
+- [A manifest level `summary`](https://iiif.io/api/presentation/3.0/#summary), which will appear below the label if provided
+- [A manifest level `requiredStatement`](https://iiif.io/api/presentation/3.0/#requiredstatement), which will appear below the summary if provided
+
+> [!NOTE]<br>
+> Certain features which aren't currently supported include:
+>
+> - Externally referenced `annotationPages` ([as shown in this cookbook recipe](https://iiif.io/api/cookbook/recipe/0306-linking-annotations-to-manifests/))
+> - Multiple images
+> - Non-text based annotations (e.g. audio)
+> - Full multi-lingual support
+>
+> However, pathways exist to enable these features with further development.
+
+> [!WARNING]<br>
+> Manifest with a version lower than 3 may load images, but aren't guaranteed to work beyond this, and will display a warning in the console.
+
 
 ## Local development
 
@@ -18,9 +94,10 @@ TODO
 
 - [Node.js / npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)
 
-Although optional, we recommend using [nvm](https://github.com/nvm-sh/nvm) to match the version of Node used in this project before running the install command, or the npm scripts described below.
-
-If you encounter problems and aren't using the version of Node shown in the [.nvmrc](.nvmrc) file, you should try aligning your node version to this first. This represents a known compatibility with the code here and our dependencies.
+> [!IMPORTANT]<br>
+> Although optional, we recommend using [nvm](https://github.com/nvm-sh/nvm) to match the version of Node used in this project before running the install command, or the npm scripts described below.
+>
+> If you encounter problems and aren't using the version of Node shown in the [.nvmrc](.nvmrc) file, you should try aligning your node version to this first. This represents a known compatibility with the code here and our dependencies.
 
 #### Setup
 
@@ -32,23 +109,63 @@ npm ci
 
 ### Compiling and previewing changes
 
-| Command | Action |
-| --- | --- |
-| `npm run dev` | Watches files in the [`src`](./src) directory for changes and serves a preview at https://localhost:43110 with hot module replacement |
-| `npm run build` | Builds the package for use in production. See "[Usage](#usage)" for how this package can be used |
+<table width="100%">
+  <thead>
+    <tr>
+      <th width="300px">Command</th>
+      <th width="800px">Action</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>npm run dev</code></td>
+      <td>Watches files in the <a href="./src"><code>src</code></a> directory for changes and serves a preview at https://localhost:43110 with hot module replacement</td>
+    </tr>
+    <tr>
+      <td><code>npm run build</code></td>
+      <td>Builds the package for use in production. See "<a href="#usage">Usage</a> for how this package can be used</td>
+    </tr>
+  </tbody>
+</table>
 
-### Running the tests
 
-| Command | Action |
-| --- | --- |
-| `npm run test:gui` | Will start the local dev server and run the e2e tests with the interactive GUI |
-| `npm run test` | Starts the dev server as above, but instead runs the tests without the GUI |
+### Running the tests
 
-`npm run cypress:gui` and `npm run cypress` will also do the same as the above _without_ starting the dev server, if you already have it running.
+<table width="100%">
+  <thead>
+    <tr>
+      <th width="300px">Command</th>
+      <th width="800px">Action</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>npm run test:gui</code></td>
+      <td>Will start the local dev server and run the e2e tests with the interactive GUI</td>
+    </tr>
+    <tr>
+      <td><code>npm run test</code></td>
+      <td> Starts the dev server as above, but instead runs the tests without the GUI</td>
+    </tr>
+  </tbody>
+</table>
+
+> [!NOTE]<br>
+> `npm run cypress:gui` and `npm run cypress` will also do the same as the above _without_ starting the dev server, if you already have it running.
 
 ### Linting the code
 
-| Command | Action |
-| --- | --- |
-| `npm run lint` | Will lint (and fix where possible) all problems in the code |
-
+<table width="100%">
+  <thead>
+    <tr>
+      <th width="300px">Command</th>
+      <th width="800px">Action</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>npm run lint</code></td>
+      <td>Will lint (and fix where possible) all problems in the code</td>
+    </tr>
+  </tbody>
+</table>
diff --git a/cypress/e2e/index.html b/cypress/e2e/index.html
@@ -5,7 +5,7 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <link rel="stylesheet" href="/src/css/styles.css" />
     <script type="module">
-      import StoriiiesViewer from "/src/index.ts";
+      import StoriiiesViewer from "/src/StoriiiesViewer.ts";
       window.StoriiiesViewer = StoriiiesViewer;
     </script>
     <title>Basic viewer</title>

diff --git a/cypress/e2e/multi-viewer.html b/cypress/e2e/multi-viewer.html
@@ -5,7 +5,7 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <link rel="stylesheet" href="/src/css/styles.css" />
     <script type="module">
-      import StoriiiesViewer from "/src/index.ts";
+      import StoriiiesViewer from "/src/StoriiiesViewer.ts";
       window.StoriiiesViewer = StoriiiesViewer;
     </script>
     <title>Basic viewer</title>

diff --git a/cypress/support/utils.ts b/cypress/support/utils.ts
@@ -1,4 +1,4 @@
-import StoriiiesViewer from "../../src";
+import StoriiiesViewer from "../../src/StoriiiesViewer";
 import OpenSeadragon from "openseadragon";
 
 declare global {

diff --git a/docs/_config.yml b/docs/_config.yml
@@ -0,0 +1,2 @@
+plugins:
+  - jekyll-redirect-from
diff --git a/docs/api/.nojekyll b/docs/api/.nojekyll
@@ -0,0 +1 @@
+TypeDoc added this file to prevent GitHub Pages from using Jekyll. You can turn off this behavior by setting the `githubPages` option to false.
diff --git a/docs/api/assets/highlight.css b/docs/api/assets/highlight.css
@@ -0,0 +1,22 @@
+:root {
+    --light-code-background: #FFFFFF;
+    --dark-code-background: #1E1E1E;
+}
+
+@media (prefers-color-scheme: light) { :root {
+    --code-background: var(--light-code-background);
+} }
+
+@media (prefers-color-scheme: dark) { :root {
+    --code-background: var(--dark-code-background);
+} }
+
+:root[data-theme='light'] {
+    --code-background: var(--light-code-background);
+}
+
+:root[data-theme='dark'] {
+    --code-background: var(--dark-code-background);
+}
+
+pre, code { background: var(--code-background); }
diff --git a/docs/api/assets/main.js b/docs/api/assets/main.js
diff --git a/docs/api/assets/search.js b/docs/api/assets/search.js