Migrate to React 19, Typescript, Vite, and Vitest

.github/workflows/build_test.yml

@@ -1,36 +1,29 @@
-# This workflow will do a clean install of node dependencies, build the source code and run tests across different versions of node
-# For more information see: https://help.github.com/actions/language-and-framework-guides/using-nodejs-with-github-actions
-
+# Lint, type-check, test, and build across supported Node.js versions
 name: Node.js CI
 
 on:
   push:
-    branches: [ master ]
+    branches: [main]
   pull_request:
-    branches: [ master ]
+    branches: [main]
 
 jobs:
   build:
-
-    runs-on: ${{ matrix.platform }}
+    runs-on: ubuntu-latest
 
     strategy:
       matrix:
-        node-version: [10.x, 12.x, 14.x]
-        platform: [ubuntu-latest]
+        node-version: [22.x, 24.x, 26.x]
 
     steps:
-    - uses: actions/checkout@v2
-    - name: Use Node.js ${{ matrix.node-version }}
-      uses: actions/setup-node@v1
-      with:
-        node-version: ${{ matrix.node-version }}
-    - run: sudo apt-get update
-    - run: sudo apt-get install -y libgbm-dev
-    - run: npm ci
-    - run: npm run build
-    - run: npm test
-      env:
-        CI: true
-    - name: Upload coverage to Codecov
-      uses: codecov/codecov-action@v1
+      - uses: actions/checkout@v7
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v7
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: npm
+      - run: npm ci
+      - run: npm run lint
+      - run: npm run typecheck
+      - run: npm test
+      - run: npm run build

.github/workflows/npm_publish.yml

@@ -1,32 +1,23 @@
-# This workflow will run tests using node and then publish a package to GitHub Packages when a release is created
-# For more information see: https://help.github.com/actions/language-and-framework-guides/publishing-nodejs-packages
-
+# Test, build, and publish the package to npm when a release is created
 name: Node.js Package
 
 on:
   release:
     types: [created]
 
 jobs:
-  build:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-node@v1
-        with:
-          node-version: 12
-      - run: npm ci
-      - run: npm test
   publish-npm:
-    needs: build
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
-      - uses: actions/setup-node@v1
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v7
         with:
-          node-version: 12
+          node-version: 24
           registry-url: https://registry.npmjs.org/
+          cache: npm
       - run: npm ci
+      - run: npm test
+      # `prepack` builds dist/ before the tarball is created
       - run: npm publish
         env:
-          NODE_AUTH_TOKEN: ${{secrets.npm_token}}
+          NODE_AUTH_TOKEN: ${{secrets.npm_token}}

.gitlab-ci.yml

@@ -1,38 +1,15 @@
-image: node:10.1.0
+image: node:24
 
 stages:
-  - build
   - test
 
 before_script:
-- npm install
+  - npm ci
 
-build_node6144:
-  image: node:6.14.4
-  stage: build
-  script: npm run build
-
-build_node8120:
-  image: node:8.12.0
-  stage: build
-  script: npm run build
-
-build_node10110:
-  image: node:10.11.0
-  stage: build
-  script: npm run build
-
-test_node6144:
-  image: node:6.14.4
-  stage: test
-  script: npm test
-
-test_node8120:
-  image: node:8.12.0
-  stage: test
-  script: npm test
-
-test_node10110:
-  image: node:10.11.0
+test:
   stage: test
-  script: npm test
+  script:
+    - npm run lint
+    - npm run typecheck
+    - npm test
+    - npm run build

AGENTS.md

@@ -0,0 +1,124 @@
+# AGENTS.md
+
+Guidance for AI coding agents working in this repository. For the public API
+and user-facing docs, see [README.md](README.md).
+
+## Project
+
+react-sigplot is a React 19 wrapper for [sigplot](https://github.com/LGSInnovations/sigplot)
+3.x, written in TypeScript and built with Vite. `<SigPlot>` creates a sigplot
+`Plot` and provides it through React context. Layer and plugin components
+render no DOM (`return null`); they drive the plot imperatively from effects.
+
+## Commands
+
+```bash
+npm ci              # Install (CI uses npm ci; keep package-lock.json in sync)
+npm run lint        # Biome lint + format check
+npm run format      # Biome format --write
+npm run typecheck   # tsc --noEmit over src, __tests__, example, and configs
+npm test            # Vitest, once
+npx vitest run __tests__/ArrayLayer.test.tsx   # One file
+npm run build       # ESM + CJS bundles and .d.ts into dist/
+npm run dev         # Vite dev server for example/ (index.html)
+```
+
+Before finishing a change, run what CI runs: `lint`, `typecheck`, `test`, and
+`build`. CI tests on Node 22, 24, and 26.
+
+## Layout
+
+- `src/index.ts` — Public entry point. Anything exported here is public API.
+- `src/SigPlot.tsx` — Creates the `Plot`, applies size and option changes, and
+  tears it down on unmount.
+- `src/SigPlotContext.ts` — `SigPlotContext` and `usePlot()`.
+- `src/useLayer.ts` — Shared layer lifecycle: `create`, incremental `update`,
+  and `recreateOn` for props that replace the layer.
+- `src/*Layer.tsx`, `src/Plugin.tsx`, `src/BoxesPlugin.tsx` — Components.
+- `src/events.ts` — `usePlotListener` and the public `usePlotEvent` hook.
+- `src/plot.ts` — Typed facade over sigplot's `Plot` and the subset of its API
+  we use.
+- `src/options.ts` — `PlotOptions`, `DataHeader`, and `LayerOptions` types.
+- `src/utils.ts` — `copyOf` (deep copy for sigplot) and `propChanged`.
+- `src/types/sigplot.d.ts` — Ambient module so `import sigplot` resolves;
+  sigplot ships no types.
+- `__tests__/` — Vitest tests; `helpers.tsx` has shared fixtures and
+  `dat/` has sample data files.
+- `example/` — Demo app served by `npm run dev`.
+- `dist/` — Build output. Git-ignored; never commit it.
+
+## Code conventions
+
+- Formatting and linting are Biome (`biome.json`): 2-space indent, single
+  quotes, 80-column lines. Don't add ESLint or Prettier.
+- Relative imports inside `src/` use a `.js` extension
+  (`import { usePlot } from './SigPlotContext.js'`) so the NodeNext
+  declaration build resolves. Tests import from `'../src'` without one.
+- Use `import type` / `type` modifiers for type-only imports
+  (`verbatimModuleSyntax` is on).
+- Components are function components exported as `default` from their own
+  file and re-exported by name, with their `*Props` type, from `src/index.ts`.
+- `ref` is a regular prop (React 19); expose instances with
+  `useImperativeHandle`. Don't use `forwardRef`.
+- Every `biome-ignore` needs a reason, e.g. why an effect intentionally omits
+  dependencies.
+- Public props and types get TSDoc comments; editors surface them.
+
+## sigplot gotchas
+
+These are why the code looks the way it does. Keep them in mind when adding or
+changing a component.
+
+- **Import:** sigplot is CommonJS. Import its default export and read members
+  off it (`sigplot.Plot`), as `src/plot.ts` does. Named imports fail under
+  Node's ESM loader.
+- **sigplot mutates its inputs.** Pass every options, header, or layer
+  options object through `copyOf()` before handing it to sigplot.
+- **Change detection:** use `propChanged()`. Plain objects (options) are
+  compared by value, so inline `options={{ ... }}` isn't re-applied every
+  render. Data arrays, callbacks, and headers are compared by reference.
+- **Layer IDs are UUID strings.** `reload` and `push` throw if given a
+  number.
+- **Teardown:** sigplot has no `destroy()`. `SigPlot` calls
+  `disable_listeners()`, clears the element, and calls
+  `releaseDetachedContext()`. Don't `setState(null)` in unmount cleanups;
+  React keeps the queued update, and the `Plot`, alive.
+- **Creation-only vs. change-only settings:** some `PlotOptions` are read
+  only by the constructor and others only by `change_settings`. Mark new
+  options accordingly in `src/options.ts`.
+- **PipeLayer** sends the header with every `push`; sigplot only autoscales
+  on header-bearing pushes.
+- Prefer one `reload`/`push` with the header over a separate `headermod`.
+
+## Testing
+
+- Vitest with jsdom. `vitest.setup.ts` loads `vitest-canvas-mock` and patches
+  `measureText`; without that patch sigplot's font sizing loops forever.
+- Render layers with `renderWithPlot(createPlot(), <Layer />)` from
+  `__tests__/helpers.tsx`, or inside a real `<SigPlot>`.
+- Assert on sigplot's internal state (`plot._Gx.lyr`, `plot._Gx.plugins`) and
+  spy on `Plot.prototype` methods with `vi.spyOn`. Call
+  `vi.restoreAllMocks()` in `afterEach`.
+- Simulate sigplot events with `emit(plot, type, fields)`.
+- `__tests__/types.test.tsx` holds compile-time checks (`@ts-expect-error`,
+  `expectTypeOf`). Only `npm run typecheck` enforces them.
+- `__tests__/rerender.test.tsx` checks that re-rendering with equal props
+  makes no sigplot calls. Keep it passing when adding a component or prop.
+- Add tests for mount, update, and unmount (layers and plugins removed) for
+  any new component.
+
+## Docs and packaging
+
+- When public API or behavior changes, update the props tables and examples in
+  `README.md`, and the "Migrating from 0.x" section for breaking changes.
+- The package ships ESM and CJS with separate type declarations
+  (`dist/index.d.ts` and `dist/cjs/index.d.ts`). The `exports` map blocks deep
+  imports, so new public API must be exported from `src/index.ts`.
+- `react` and `react-dom` are peer dependencies; `sigplot` is a dependency.
+  Both are external to the bundle (`vite.config.ts`).
+- Publishing runs on GitHub release; `prepack` builds `dist/`.
+
+## Commits
+
+Use an imperative subject line. In the body, explain why the change is needed
+and include measurements for performance or memory changes.