geneviewer-js 0.0.0-stage → 0.3.0

package/LICENSE-THIRD-PARTY.md

@@ -0,0 +1,19 @@
+# Third-party material
+
+## Font Awesome Free icons
+
+The toolbar's default icons (download, rotate-left, rotate-right, house,
+magnifying-glass-minus) are glyphs of Font Awesome Free 6.5.2 (solid), by
+Fonticons, Inc., https://fontawesome.com. They are drawn as inline SVG paths,
+in `src/lib/icons.js` and the built files in `dist/`.
+
+The icons are licensed under the Creative Commons Attribution 4.0
+International license (CC BY 4.0):
+https://creativecommons.org/licenses/by/4.0/. Font Awesome's licence notice:
+https://fontawesome.com/license/free.
+
+## D3
+
+`geneviewer.min.js` and `geneviewer.standalone.mjs` include D3 7.8.5,
+https://d3js.org, copyright Mike Bostock, under the ISC license:
+https://github.com/d3/d3/blob/main/LICENSE.

package/LICENSE.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2023 geneviewer authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,221 @@
-# Temporary Holding Version
+# geneviewer
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Interactive gene cluster, transcript and genome alignment charts in the
+browser, drawn with D3. The same library draws the charts of the
+[geneviewer R package](https://github.com/nvelden/geneviewer) and its Shiny
+app.
+
+**Docs and examples:** https://nvelden.github.io/geneviewer-js/
+
+## Install
+
+```sh
+npm install geneviewer-js
+```
+
+Or load it from a CDN, with D3 included:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/geneviewer-js@0.3/dist/geneviewer.min.js"></script>
+```
+
+## A first chart
+
+```html
+<div id="chart" style="width: 800px; height: 300px"></div>
+<script src="https://cdn.jsdelivr.net/npm/geneviewer-js@0.3/dist/geneviewer.min.js"></script>
+<script>
+  const chart = geneviewer.newChart("#chart", {
+    version: 1,
+    data: [
+      { cluster: "A", name: "geneA", start: 100, end: 900, class: "kinase" },
+      { cluster: "A", name: "geneB", start: 1200, end: 2000, class: "transporter" },
+      { cluster: "B", name: "geneA", start: 300, end: 1100, class: "kinase" },
+    ],
+    fields: { cluster: "cluster", group: "class" },
+    labels: { label: "name" },
+    title: { title: "Two clusters" },
+  });
+  chart.on("click", (event) => console.log(event.detail));
+</script>
+```
+
+With a bundler (Vite, webpack, ...), import the ES module; it imports `d3`
+from npm:
+
+```js
+import { newChart } from "geneviewer-js";
+
+const chart = newChart(document.getElementById("chart"), spec);
+chart.update({ title: { title: "New title" } });
+```
+
+The chart spec has one key per part of the chart (`genes`, `labels`,
+`links`, `scale`, `theme`, ...); see the API reference on the docs site and
+`dist/spec.d.ts`. The library adds its stylesheet to the page; on pages
+whose Content-Security-Policy blocks that, pass `{ injectStyles: false }`
+and load `geneviewer-js/geneviewer.css`.
+
+## Files
+
+| File | For |
+|------|-----|
+| `dist/geneviewer.min.js` | Script tag, global `geneviewer`, D3 included |
+| `dist/geneviewer.mjs` | ES module for bundlers (`import ... from "geneviewer-js"`), imports `d3` |
+| `dist/geneviewer.standalone.mjs` | ES module with D3 included (`geneviewer-js/standalone`) |
+| `dist/geneviewer.core.js` | Script tag using the page's `d3`, not minified (the R package) |
+| `dist/geneviewer.css` | The stylesheet, when styles cannot be added by script |
+| `dist/geneviewer.d.ts`, `dist/spec.d.ts` | Types |
+
+# Development
+
+## Source
+
+| File | What it is |
+|------|------------|
+| `src/lib/index.js` | Entry of the bundle: the public API, what the global `geneviewer` holds |
+| `src/lib/chart.js` | `geneviewer.newChart()`: the chart, with its toolbar, zoom, selection, drag and undo/redo |
+| `src/lib/container.js` | The container of one chart part; `components/*.js` add a method to it for each part drawn (genes, labels, legend, ...) |
+| `src/lib/*.js` | Shared helpers: `util`, `style`, `text`, `color`, `scale`, `links` (and colour bar), `export` (SVG/PNG, save menu) |
+| `src/styles.css` | Chart styles |
+| `src/htmlwidgets/geneviewerwidget.js` | htmlwidgets binding used by the R package: calls `newChart` and sends events to Shiny |
+
+The sources are ES modules, bundled by esbuild (`scripts/files.mjs`). The
+code uses `d3` as a global; the ES module and bundled builds import it from
+the `d3` package instead (`src/d3.js`).
+
+## Build
+
+```sh
+npm run check   # syntax-check the sources
+npm run build   # write dist/ and dist/SHA256SUMS
+```
+
+`npm run build` needs the dev dependencies (`npm ci`). It writes the four
+builds (see "Files" above), `geneviewer.css`, `themes.json`, the R binding,
+the type definitions and `SHA256SUMS`. `geneviewer.core.js` is not
+minified, so the R package can ship readable source, as CRAN expects;
+esbuild does drop the comments.
+
+## Chart spec schema
+
+`schema/spec-v1.schema.json` (JSON Schema 2020-12) defines the chart spec:
+one top-level key per `GC_*` function of the R package, one property per
+argument, in camelCase. `schema/NAMING.md` lists every R argument and its
+spec name; the names were approved for spec v1, which is frozen at 1.0.0.
+
+```sh
+npm run schema:check   # validate the schema, NAMING.md and schema/examples/
+npm run spec:check     # validate the spec.json R recorded for each fixture
+```
+
+## Types
+
+`npm run build` also writes `dist/geneviewer.d.ts`, from the JSDoc in
+`src/lib/`, and `dist/spec.d.ts`, from the schema. The source stays plain
+JavaScript.
+
+```sh
+npm run types:test   # compile test/types/ against the .d.ts files (in npm test)
+npm run types:src    # type-check src/lib/ (jsconfig.json); some errors remain
+```
+
+## Tests
+
+```sh
+npm test               # all tests, in Docker
+npm run test:update    # write new baselines (only when output should change)
+npm run test:smoke     # the packed package in a plain page, a Vite project and TypeScript
+Rscript scripts/export-fixtures.R   # re-export fixtures from the R package
+Rscript test/coverage.R             # update test/coverage.md
+```
+
+- **Fixtures** (`test/fixtures/`): 206 charts exported from the R package:
+  its help-page examples, its vignettes and `test/charts.R`. Each has the
+  R code, the spec R recorded, the payload R sends to the browser, and
+  `render.txt`, a canonical listing of the drawn chart. `npm test` draws
+  every fixture and compares.
+- **compile()** (`npm run test:compile`, in `npm test`): `compile(spec)`
+  equals R's payload for every fixture, apart from the approved exceptions
+  (docs/roadmap.md).
+- **Interaction tests** (`test/interaction/`): scripted zoom, selection,
+  drag and undo/redo, with the chart and its events recorded after each
+  step.
+- **Three modes:** fixtures and interaction tests run against the same
+  baselines through the R binding, as R draws charts, with
+  `geneviewer.newChart()` and R's payload, and with `newChart()` and the
+  spec (`test/harness/mount.js`); the fixtures also with the min build.
+- **Chart methods** (`test/methods.mjs`): `select()`, `getSelection()`,
+  `undo()`, `redo()` and `download()`.
+- **Save, two-chart and site checks** (`test/save.cjs`,
+  `test/two-charts.cjs`, `test/site.cjs`): the save menu downloads a valid
+  SVG and PNG; two charts on a page keep their own selection and undo
+  history; every chart on the docs site draws without errors.
+- **Coverage** (`test/coverage.md`): every documented argument of the `GC_*`
+  chart functions is used by at least one fixture.
+- **Fixed environment:** the tests run in a Docker image (`docker/`) with
+  pinned Chromium (Playwright) and fonts, because chart layout depends on
+  text measures. The image runs natively on arm64: on Apple silicon
+  locally, and on GitHub's `ubuntu-24.04-arm` runners in CI. Chrome under
+  amd64 emulation misreads numbers, so emulation is not supported.
+
+## Trying a change in the Shiny app
+
+```sh
+npm run try-app               # build, start the app, run the app's tests
+npm run try-app -- --no-tests # build and start the app only
+npm run try-app -- --r-tests  # also run the R package's tests on the copy
+```
+
+This runs the [geneviewer Shiny app](https://github.com/nvelden/geneviewer-shinylive)
+with the JavaScript from this repo:
+
+- **Isolated:** the R package is copied to a temporary folder and the built
+  files replace its JavaScript there, so neither the R repo nor your R library
+  changes.
+- **Tests:** the app starts at <http://127.0.0.1:4849/> and the app's
+  `tests/testthat` and `tests/browser` suites run against it. The browser
+  tests need `puppeteer`.
+- **Left running:** the app stays up afterwards so you can try it by hand; the
+  script prints the command that stops it.
+
+Set the two repo locations in a `.try-app.env` file (ignored by git):
+
+```sh
+GENEVIEWER_R_DIR="/path/to/geneviewer"
+GENEVIEWER_APP_DIR="/path/to/geneviewer-shinylive"
+```
+
+Set `PORT` to use a port other than 4849.
+
+## Releases
+
+1. Bump `version` in `package.json` and `src/lib/chart.js` (`npm run check`
+   compares them).
+2. Commit, then tag and push: `git tag v0.3.1 && git push origin main v0.3.1`.
+
+The publish workflow tests and builds, publishes to npm with provenance,
+and attaches `dist/` to a GitHub release.
+
+## Using a release in the R package
+
+The R package vendors a release: its copies of the files are stored in the R
+repo and shipped inside the package, so users never download JavaScript
+separately. A maintainer pulls a new release with:
+
+```sh
+curl -sSLO https://github.com/nvelden/geneviewer-js/releases/download/v0.3.0/{geneviewer.core.js,geneviewer.css,themes.json,geneviewerwidget.js,SHA256SUMS}
+shasum -a 256 -c SHA256SUMS --ignore-missing
+```
+
+They then copy the files into `inst/htmlwidgets/`. Do not edit those copies in
+the R repo; make changes here and cut a new release.
+
+## Roadmap
+
+See [docs/roadmap.md](docs/roadmap.md).
+
+## Licence
+
+MIT. Copyright (c) 2023 geneviewer authors. The toolbar icons are Font
+Awesome Free (CC BY 4.0); see LICENSE-THIRD-PARTY.md.

package/dist/SHA256SUMS

@@ -0,0 +1,11 @@
+e78728da421c9b7bf3002d853fecd4497e27d8be4331fb391caab93722b4b724  geneviewer.core.js
+d96c80adea1ce9ebe5323e153e4f1e014816ef37d502c849741d68f7b3fa6575  geneviewer.css
+3a363a3b443504da4589aaf3102b00d8f488df77b6f358721f640f7befbf6c28  geneviewer.d.ts
+45815b9a041648042911b03214c71412e02c2a79192ec581100ceea08d3572bd  geneviewer.min.js
+f8541286b4ed988290501a507a70633a714cf243181569526c219fa7c868d331  geneviewer.min.js.map
+039077a86bff0ba3dbbec37578f468ee4f71c54c44a2f9126ae691e83d5b7f91  geneviewer.mjs
+cf000dfc911a3e3302f2007f3e1fee132da4dfafd2f94dcc9c884fa772a23975  geneviewer.standalone.mjs
+1025a3defe0032717b7fdd571dfc0f90df9696846066818f8a94079e103a8b23  geneviewer.standalone.mjs.map
+0bc331bce739358f3150af8b1ad3851a4c4cbbf6763cc122fe3b41008b230020  geneviewerwidget.js
+3d9a1611127c02a515da15b88c46f9da30e0f8ade676919e7502244aef4dd000  spec.d.ts
+65ebaa72b864ba74fabc06aa02d858a0a621e5579dadc0c5d9d7add1ba48f246  themes.json