maptastic 3.1.0 → 3.2.0

package/README.md

@@ -45,6 +45,8 @@ import { Maptastic } from 'maptastic';
 const map = new Maptastic("so-simple");
 ```
 
+TypeScript definitions are included in the package, so no `@types` package is needed.
+
 ## Controls
 
 Since the idea is to have a projector aimed all crazy-like, the controls are all keyboard and mouse based since any UI would either get in the way, or would be impossible to see in most cases anyway.
@@ -186,15 +188,20 @@ npx playwright install
 npm run test:browser
 ```
 
-`dist/` is committed; CI fails if it doesn't match a fresh `npm run build`.
+`dist/` is not committed. Run `npm run build` before opening the files in `example/`, which load `../dist/maptastic.js`.
 
 ### Releasing
 
-Releases are staged to npm from GitHub Actions ([`publish.yml`](.github/workflows/publish.yml)) via
-[trusted publishing](https://docs.npmjs.com/trusted-publishers), so no npm token is stored anywhere,
-and go live only after a maintainer approves them ([staged publishing](https://docs.npmjs.com/staged-publishing)).
-
-1. Bump the version: `npm version <patch|minor|major>` (commits and creates the `vX.Y.Z` tag).
-2. Push the commit and tag: `git push --follow-tags`.
-3. Once the workflow finishes, approve the release with 2FA: `npm stage list maptastic`, then
-   `npm stage approve <stage-id>` (or use the Staged Packages tab on npmjs.com).
+Releases are made by [semantic-release](https://github.com/semantic-release/semantic-release) from GitHub Actions
+([`publish.yml`](.github/workflows/publish.yml)). Commits build up on `master`; when you want a release, run the
+Publish workflow from the Actions tab (or `gh workflow run publish.yml`), optionally with `dry_run` checked to preview
+the next version first. Write commit messages in the
+[Conventional Commits](https://www.conventionalcommits.org/) format: `fix:` makes a patch release, `feat:` a minor
+release, and a `!` after the type (or a `BREAKING CHANGE:` footer) a major release. Other types, such as `docs:`,
+`test:`, and `ci:`, do not release. Do not bump the version in `package.json` by hand.
+
+When there are releasable commits since the last tag, the workflow commits the new version and `CHANGELOG.md` back to
+`master`, tags the release, creates the GitHub release (with the built `dist/maptastic.js` and its source map
+attached), and stages the package on npm via [trusted publishing](https://docs.npmjs.com/trusted-publishers), so no npm token is stored anywhere.
+The release goes live only after a maintainer approves it with 2FA ([staged publishing](https://docs.npmjs.com/staged-publishing)):
+run `npm stage list maptastic`, then `npm stage approve <stage-id>` (or use the Staged Packages tab on npmjs.com).

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "maptastic",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "main": "dist/maptastic.js",
+  "types": "types/maptastic.d.ts",
   "license": "SEE LICENSE IN license.txt",
   "author": "ben purdy (https://github.com/benpurdy)",
   "contributors": [
@@ -11,14 +12,16 @@
   "files": [
     "license.txt",
     "src/**/*",
-    "dist/**/*"
+    "dist/**/*",
+    "types/maptastic.d.ts"
   ],
   "scripts": {
     "build": "rollup --config",
     "clean": "rimraf dist",
     "prepublishOnly": "npm run clean && npm run build",
     "pretest": "npm run build",
-    "test": "node --test",
+    "test": "node --test \"test/**/*.test.js\"",
+    "test:types": "tsc -p types/test",
     "pretest:browser": "npm run build",
     "test:browser": "playwright test"
   },
@@ -28,9 +31,14 @@
     "@playwright/test": "^1.64.1",
     "@rollup/plugin-babel": "^7.1.0",
     "@rollup/plugin-terser": "^1.0.0",
+    "@semantic-release/changelog": "^7.0.0",
+    "@semantic-release/exec": "^7.1.0",
+    "@semantic-release/git": "^11.0.1",
     "jsdom": "^30.1.3",
     "rimraf": "^6.1.3",
-    "rollup": "^4.64.7"
+    "rollup": "^4.64.7",
+    "semantic-release": "^25.0.9",
+    "typescript": "^7.0.2"
   },
   "repository": {
     "type": "git",

package/types/maptastic.d.ts

@@ -0,0 +1,54 @@
+/** An `[x, y]` coordinate in pixels. */
+export type Point = [number, number];
+
+/** An element, or the ID of an element, to map. */
+export type Target = string | HTMLElement;
+
+/** The mapping of a single layer, as returned by `getLayout` and accepted by `setLayout`. */
+export interface Layout {
+  /** ID of the layer element. */
+  id: string;
+  /** Four corner points of the layer on screen. */
+  targetPoints: Point[];
+  /** Four corner points of the layer's original, unmapped rectangle. */
+  sourcePoints: Point[];
+}
+
+export interface Config {
+  /** Elements or element IDs to use as layers. */
+  layers?: Target[];
+  /** Called whenever the layout changes. */
+  onchange?: () => void;
+  /** Show crosshairs in edit mode. Default `false`. */
+  crosshairs?: boolean;
+  /** Show element IDs in edit mode. Default `true`. */
+  labels?: boolean;
+  /** Show the display bounds in edit mode. Default `false`. */
+  screenbounds?: boolean;
+  /** Save layer positions to local storage on change. Default `true`. */
+  autoSave?: boolean;
+  /** Load layer positions from local storage on creation. Default `true`. */
+  autoLoad?: boolean;
+}
+
+export class Maptastic {
+  constructor(config: Config, ...targets: Target[]);
+  constructor(...targets: Target[]);
+
+  /** Returns the current mapping of every layer. */
+  getLayout(): Layout[];
+
+  /** Applies a layout, adding layers for any IDs that are not mapped yet. */
+  setLayout(layout: Layout[]): void;
+
+  /** Maps a new element, optionally starting from the given corner points. */
+  addLayer(target: Target, targetPoints?: Point[]): void;
+
+  /** Stops mapping an element. The element is left in the page. */
+  removeLayer(element: HTMLElement): void;
+
+  /** Turns edit mode on or off. */
+  setConfigEnabled(enabled: boolean): void;
+}
+
+export as namespace maptastic;