@thednp/dommatrix 3.0.3 → 3.0.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +87 -0
- package/CLAUDE.md +1 -0
- package/README.md +239 -98
- package/dist/dommatrix.cjs +867 -1
- package/dist/dommatrix.cjs.map +1 -1
- package/dist/dommatrix.d.ts +514 -361
- package/dist/dommatrix.js +871 -1
- package/dist/dommatrix.js.map +1 -1
- package/dist/dommatrix.mjs +787 -224
- package/dist/dommatrix.mjs.map +1 -1
- package/package.json +15 -18
package/AGENTS.md
ADDED
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
# AGENTS.md
|
|
2
|
+
|
|
3
|
+
Guidance for AI agents working on this repository.
|
|
4
|
+
|
|
5
|
+
## Project Overview
|
|
6
|
+
|
|
7
|
+
`@thednp/dommatrix` is a TypeScript shim for the native [DOMMatrix](https://developer.mozilla.org/en-US/docs/Web/API/DOMMatrix) interface. It ships a single default export, the `CSSMatrix` class, with a nearly identical API surface to native `DOMMatrix`, but works in **Node.js** and legacy browsers where `DOMMatrix` does not exist.
|
|
8
|
+
|
|
9
|
+
The library is intentionally small and dependency-free. There are no runtime dependencies; the `dist/` bundle is produced from `src/index.ts` alone.
|
|
10
|
+
|
|
11
|
+
## Tech Stack
|
|
12
|
+
|
|
13
|
+
- **Language**: TypeScript 7 (`typescript@^7`), `strict` mode, `moduleResolution: "Bundler"`
|
|
14
|
+
- **Package manager**: pnpm (`packageManager: pnpm@10.33.0`)
|
|
15
|
+
- **Build**: [tsdown](https://tsdown.dev) (rolldown-based), config in `tsdown.config.mts` — produces ESM (`dommatrix.mjs`), CJS (`dommatrix.cjs`), UMD (`dommatrix.js`, global `CSSMatrix`) and bundled types (`dommatrix.d.ts`) into `dist/`
|
|
16
|
+
- **JSR**: `deno.json` mirrors `package.json` (name, version, MIT license, keywords) and publishes the raw TypeScript source via `deno publish`. Keep `version` in sync between the two files
|
|
17
|
+
- **Tests**: Vitest 4 in **browser mode** only (Playwright + Chromium, headless), with istanbul coverage in `vitest.config.ts`
|
|
18
|
+
- **Lint/format**: [Deno](https://docs.deno.com/runtime/reference/cli/lint/) (`deno lint`, `deno fmt`) — not ESLint/Prettier
|
|
19
|
+
- **Runtime requirement**: Node >= 20, pnpm >= 8.6
|
|
20
|
+
|
|
21
|
+
## Commands
|
|
22
|
+
|
|
23
|
+
```sh
|
|
24
|
+
pnpm build # tsdown build + copy dist/dommatrix.js to docs/
|
|
25
|
+
pnpm test # vitest browser tests (headless Chromium) + coverage
|
|
26
|
+
pnpm test-ui # vitest browser tests with UI
|
|
27
|
+
pnpm lint # deno lint src + tsc --noEmit
|
|
28
|
+
pnpm lint:ts # deno lint src
|
|
29
|
+
pnpm check:ts # tsc --noEmit
|
|
30
|
+
pnpm fix:ts # deno lint src --fix
|
|
31
|
+
pnpm format # deno fmt src
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
Always run `pnpm lint` and `pnpm test` after making changes.
|
|
35
|
+
|
|
36
|
+
Deno equivalents: `deno task test`, `deno task lint`, `deno task check`, `deno task format` (also usable as bare `deno test`-style commands: `deno lint src`, `deno check src/index.ts`, `deno fmt src`, `deno doc src/index.ts`, `deno publish`).
|
|
37
|
+
|
|
38
|
+
## Project Structure
|
|
39
|
+
|
|
40
|
+
- `src/index.ts` — the entire library (single file, ~1200 lines). The `CSSMatrix` class plus module-level helper functions (`Translate`, `Rotate`, `fromString`, etc.). Heavily documented with JSDoc.
|
|
41
|
+
- `src/types.ts` — exported types (`JSONMatrix`, `Matrix`, `Matrix3d`, `PointTuple`)
|
|
42
|
+
- `test/dommatrix.test.ts` — the full test suite (Vitest, browser mode)
|
|
43
|
+
- `test/fixtures/` — test helpers and sample data
|
|
44
|
+
- `docs/` — GitHub Pages demo; `docs/dommatrix.js` is a build artifact copied from `dist/`
|
|
45
|
+
- `dist/` — build output, committed to the repo; regenerate with `pnpm build`, never edit by hand
|
|
46
|
+
- `experiments/` — archived Cypress experiments (not part of the build)
|
|
47
|
+
|
|
48
|
+
## Code Conventions
|
|
49
|
+
|
|
50
|
+
- **Single default export**: `export default class CSSMatrix` — there are no runtime named exports. The helper types (`Matrix`, `Matrix3d`, `JSONMatrix`, `PointTuple`, `CSSMatrixInput`) are re-exported from `./types.ts` as type-only exports (`export type { ... } from "./types.ts"`)
|
|
51
|
+
- **Style**: Deno-style — no semicolons, double quotes, 2-space indent, trailing commas. `deno lint` and `deno fmt src` enforce this; do not fight the formatter
|
|
52
|
+
- **No comments unless they are JSDoc** — the codebase uses JSDoc extensively on public API, matching the existing style
|
|
53
|
+
- **Naming**: `m11`-`m44` are the canonical 3D values; `a`-`f` are the 2D aliases (getters/setters sync both)
|
|
54
|
+
- **API design**: mirrors native `DOMMatrix` — immutable methods (`translate()`, `rotate()`, `scale()`, `skew()`, `multiply()`) return new matrices; `*Self` variants mutate and return `this`. Static helpers (`fromString`, `fromArray`, `fromMatrix`, `Translate`, `Rotate`, ...) live on the class as static properties
|
|
55
|
+
- **Error style**: throw `TypeError` with messages prefixed `CSSMatrix: ...` (tests assert on exact messages)
|
|
56
|
+
- **`is2D`/`isIdentity`** are computed getters (from matrix values), not construction-time flags
|
|
57
|
+
|
|
58
|
+
## Critical Rules (do not violate)
|
|
59
|
+
|
|
60
|
+
1. **No runtime references to browser-only globals** (`DOMMatrix`, `DOMPoint`, `CSSMatrix`) without a `typeof ... !== "undefined"` guard. The library must work in Node.js where these globals do not exist. The `instanceof` guards in `isCompatibleObject()` and `transformPoint()` are the canonical pattern:
|
|
61
|
+
```ts
|
|
62
|
+
typeof DOMMatrix !== "undefined" && object instanceof DOMMatrix
|
|
63
|
+
```
|
|
64
|
+
2. **Tests run in a browser, so a missing global guard will NOT fail tests on its own.** The test suite simulates Node.js with `vi.stubGlobal("DOMMatrix", undefined)` / `vi.stubGlobal("DOMPoint", undefined)` in the `"Node.js Environment Test"` describe block — keep that block covering any code path that touches these globals.
|
|
65
|
+
3. **Coverage must stay 100%** (statements, branches, functions, lines). The CI gate enforces it via istanbul. Every new branch needs a test.
|
|
66
|
+
4. **Do not edit `dist/` or `docs/dommatrix.js` directly** — they are build outputs; run `pnpm build`.
|
|
67
|
+
5. **Do not add runtime dependencies.** This is a zero-dependency library; `src/` must stay import-free.
|
|
68
|
+
6. **Do not change the dist file names** (`dommatrix.cjs/.js/.mjs/.d.ts` + maps) — package.json `exports`, `main`, `module`, and the docs copy script depend on them.
|
|
69
|
+
|
|
70
|
+
## Releasing (patch/minor/major)
|
|
71
|
+
|
|
72
|
+
1. Bump `version` in `package.json` **and** in `deno.json`
|
|
73
|
+
2. Add an entry to `CHANGELOG.md` (Keep a Changelog style, date-stamped)
|
|
74
|
+
3. Run `pnpm build && pnpm lint && pnpm test` and `deno publish --dry-run --allow-dirty`
|
|
75
|
+
4. Commit, then tag with the **bare version number** (no `v` prefix — existing tags are `1.0.0` ... `3.0.4`)
|
|
76
|
+
|
|
77
|
+
The GitHub Actions `publish.yml` workflow publishes to both npm and JSR on GitHub Release (JSR via OIDC when enabled on the scope, otherwise the `JSR_TOKEN` secret).
|
|
78
|
+
|
|
79
|
+
Note: `prepublishOnly` runs `pnpm up --latest` (updates all deps), `pnpm format`, `pnpm lint`, `pnpm build` — expect dependency bumps to land in the same commit if publishing.
|
|
80
|
+
|
|
81
|
+
## Gotchas
|
|
82
|
+
|
|
83
|
+
- The old `vite.config.ts` was replaced by `tsdown.config.mts` in 3.0.5 — `tsdown.config.mts` relies on: object-form `entry` for the chunk name (`dommatrix`), an `outputOptions` override for UMD (it must spread defaults, otherwise `sourcemap` is silently dropped), and `outExtensions` to keep the `.d.ts` filename. The `.mts` extension (not `.ts`) prevents Node's `MODULE_TYPELESS_PACKAGE_JSON` ESM-reparse warning — `package.json` deliberately has no `"type": "module"` because that would break Node `require()` of the UMD `dist/dommatrix.js`
|
|
84
|
+
- With `deno.json` present, `deno lint` enforces `verbatim-module-syntax` — type-only imports (like `import type CSSMatrix from "."` in `src/types.ts`) must use `import type`
|
|
85
|
+
- Vitest runs only in browser mode; any Node-only concern (globals, `require()`, `process`) needs the stubbed-global test pattern
|
|
86
|
+
- `rotateAxisAngle`/`rotateAxisAngleSelf` throw only when any of the 4 values is non-finite; zero-length vector returns a copy (or `this` for the `Self` variant)
|
|
87
|
+
- `deno lint` runs on `src/` only — the `tsconfig.json` `include` is `["src/*"]`, `noEmit: true`
|
package/CLAUDE.md
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
AGENTS.md
|
package/README.md
CHANGED
|
@@ -1,98 +1,239 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
[](https://coveralls.io/github/thednp/dommatrix)
|
|
4
|
+
[](https://www.npmjs.com/package/@thednp/dommatrix)
|
|
5
|
+
[](http://npm-stat.com/charts.html?@thednp/dommatrix)
|
|
6
|
+
[](https://github.com/thednp/dommatrix/actions/workflows/ci.yml)
|
|
7
|
+
[](https://www.jsdelivr.com/package/npm/@thednp/dommatrix)
|
|
8
|
+
|
|
9
|
+
A TypeScript sourced [DOMMatrix](https://developer.mozilla.org/en-US/docs/Web/API/DOMMatrix) shim for **Node.js** apps and legacy browsers.
|
|
10
|
+
|
|
11
|
+
## Table of Contents
|
|
12
|
+
|
|
13
|
+
- [Features](#features)
|
|
14
|
+
- [Demo](#demo)
|
|
15
|
+
- [Installation](#installation)
|
|
16
|
+
- [Quick Start](#quick-start)
|
|
17
|
+
- [API Reference](#api-reference)
|
|
18
|
+
- [CSSMatrix vs native DOMMatrix](#cssmatrix-vs-native-dommatrix)
|
|
19
|
+
- [Alternatives](#alternatives)
|
|
20
|
+
- [Thanks](#thanks)
|
|
21
|
+
- [History](#history)
|
|
22
|
+
- [License](#license)
|
|
23
|
+
|
|
24
|
+
## Features
|
|
25
|
+
|
|
26
|
+
- **Zero runtime dependencies** — the entire library is a single file
|
|
27
|
+
- **Node.js compatible** — no `DOMMatrix` / `DOMPoint` globals required, works in legacy browsers too
|
|
28
|
+
- **Full transform string parsing** — `matrix()`, `matrix3d()`, `translate*()`, `rotate*()`, `rotate3d()`, `scale*()`, `skew*()`, `perspective()` with `deg` / `rad` / `px` units, via `fromString()` or the constructor
|
|
29
|
+
- **2D & 3D** — the `m11`-`m44` / `a`-`f` properties, `matrix()` / `matrix3d()` string output
|
|
30
|
+
- **Immutable and mutable APIs** — `translate()` returns a new matrix, `translateSelf()` mutates in place, same as native `DOMMatrix`
|
|
31
|
+
- **TypeScript** — bundled type definitions, including the `Matrix`, `Matrix3d`, `JSONMatrix` and `PointTuple` types
|
|
32
|
+
- **Verified against native** — every method is tested side-by-side with the native `DOMMatrix` in real browsers, with **100% test coverage**
|
|
33
|
+
|
|
34
|
+
## Demo
|
|
35
|
+
|
|
36
|
+
See DOMMatrix shim in action, [click me](https://thednp.github.io/dommatrix) and start transforming.
|
|
37
|
+
|
|
38
|
+
## Installation
|
|
39
|
+
|
|
40
|
+
```sh
|
|
41
|
+
npm install @thednp/dommatrix
|
|
42
|
+
# pnpm add @thednp/dommatrix
|
|
43
|
+
# bun add @thednp/dommatrix
|
|
44
|
+
# deno add npm:@thednp/dommatrix
|
|
45
|
+
# deno add jsr:@thednp/dommatrix
|
|
46
|
+
# npx jsr add @thednp/dommatrix
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
Install from [JSR](https://jsr.io/@thednp/dommatrix) and import the raw TypeScript source:
|
|
50
|
+
|
|
51
|
+
```ts
|
|
52
|
+
import CSSMatrix from "jsr:@thednp/dommatrix";
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
Download the latest version and copy the `dist/dommatrix.js` file to your project assets folder, then load the file in your front-end:
|
|
56
|
+
|
|
57
|
+
```html
|
|
58
|
+
<script src="./assets/js/dommatrix.js"></script>
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
Alternatively you can load from CDN:
|
|
62
|
+
|
|
63
|
+
```html
|
|
64
|
+
<script src="https://cdn.jsdelivr.net/npm/@thednp/dommatrix/dist/dommatrix.js"></script>
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
## Quick Start
|
|
68
|
+
|
|
69
|
+
```js
|
|
70
|
+
import CSSMatrix from '@thednp/dommatrix';
|
|
71
|
+
|
|
72
|
+
// init from a transform string
|
|
73
|
+
const myMatrix = new CSSMatrix('matrix(1,0.25,-0.25,1,0,0)');
|
|
74
|
+
|
|
75
|
+
// mutating methods change the matrix in place
|
|
76
|
+
myMatrix.translateSelf(15, 20);
|
|
77
|
+
myMatrix.rotateSelf(15);
|
|
78
|
+
|
|
79
|
+
// apply to styling to target
|
|
80
|
+
element.style.transform = myMatrix.toString();
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
> **Immutable vs mutable** — like native `DOMMatrix`, the shim offers both styles. `translate()`, `rotate()`, `scale()`, `skew()` and `multiply()` return a **new** matrix and leave the original untouched; their `*Self()` counterparts mutate the matrix and return `this`. The example above uses `*Self()` because the returned value is discarded.
|
|
84
|
+
|
|
85
|
+
The constructor accepts the same inputs as the native interface, plus a couple more:
|
|
86
|
+
|
|
87
|
+
```js
|
|
88
|
+
// a valid CSS transform string
|
|
89
|
+
const fromString = new CSSMatrix('translate(10px, 20px) rotate(45deg)');
|
|
90
|
+
|
|
91
|
+
// an array of 6 (2D) or 16 (3D) numbers
|
|
92
|
+
const fromArray = new CSSMatrix([1, 0, 0, 1, 15, 25]);
|
|
93
|
+
|
|
94
|
+
// a JSON object (e.g. the result of another matrix's toJSON())
|
|
95
|
+
const fromJSON = new CSSMatrix({ a: 1, b: 0, c: 0, d: 1, e: 15, f: 25 });
|
|
96
|
+
|
|
97
|
+
// another CSSMatrix instance
|
|
98
|
+
const fromMatrix = new CSSMatrix(fromString);
|
|
99
|
+
|
|
100
|
+
console.log(fromString.toString()); // matrix(1, 0, 0, 1, 10, 20)
|
|
101
|
+
console.log(fromArray.toArray()); // [1, 0, 0, 1, 15, 25]
|
|
102
|
+
console.log(fromJSON.toJSON()); // { a, b, c, d, e, f, m11..m44, is2D, isIdentity }
|
|
103
|
+
console.log(fromMatrix.transformPoint({ x: 0, y: 0, z: 0, w: 1 })); // { x, y, z, w }
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
CommonJS works too, and in Node.js you can import the default as whatever name you want:
|
|
107
|
+
|
|
108
|
+
```js
|
|
109
|
+
// CommonJS
|
|
110
|
+
const CSSMatrix = require('@thednp/dommatrix');
|
|
111
|
+
|
|
112
|
+
// or alias it as a drop-in replacement
|
|
113
|
+
const DOMMatrix = CSSMatrix;
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
TypeScript users get the helper types from the package root:
|
|
117
|
+
|
|
118
|
+
```ts
|
|
119
|
+
import CSSMatrix from '@thednp/dommatrix';
|
|
120
|
+
import type { Matrix, Matrix3d, JSONMatrix, PointTuple } from '@thednp/dommatrix';
|
|
121
|
+
|
|
122
|
+
const values: Matrix = [1, 0, 0, 1, 15, 25];
|
|
123
|
+
const matrix = new CSSMatrix(values);
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
For the complete JavaScript API, check the [JavaScript API](https://github.com/thednp/DOMMatrix/wiki/JavaScript-API) section in our wiki.
|
|
127
|
+
|
|
128
|
+
## API Reference
|
|
129
|
+
|
|
130
|
+
### Static methods
|
|
131
|
+
|
|
132
|
+
| Method | Description |
|
|
133
|
+
| --- | --- |
|
|
134
|
+
| `fromString(source)` | Parses any valid CSS transform string |
|
|
135
|
+
| `fromArray(array)` | Creates a matrix from an array of 6/16 numbers, `Float32Array` or `Float64Array` |
|
|
136
|
+
| `fromMatrix(matrix)` | Creates a matrix from a `CSSMatrix` / `DOMMatrix` instance or a `toJSON()` object |
|
|
137
|
+
| `toArray(matrix, is2D?)` | Returns an *Array* of 6/16 values from any compatible matrix |
|
|
138
|
+
| `isCompatibleArray(array)` | Checks if a value is a compatible 6/16 number array |
|
|
139
|
+
| `isCompatibleObject(object)` | Checks if a value is a `CSSMatrix` / `DOMMatrix` / `JSONMatrix` object |
|
|
140
|
+
| `Translate(x, y, z)` | Returns a translation matrix (CSS `translate3d()`) |
|
|
141
|
+
| `Rotate(rx, ry, rz)` | Returns a rotation matrix (CSS `rotate3d()`) |
|
|
142
|
+
| `RotateAxisAngle(x, y, z, alpha)` | Returns a rotation matrix about a vector (CSS `rotate3d()` with 4 values) |
|
|
143
|
+
| `Scale(x, y, z)` | Returns a scale matrix (CSS `scale3d()`) |
|
|
144
|
+
| `Skew(angleX, angleY)` | Returns a skew matrix (CSS `skew()`) |
|
|
145
|
+
| `SkewX(angle)` | Returns a skew-X matrix (CSS `skewX()`) |
|
|
146
|
+
| `SkewY(angle)` | Returns a skew-Y matrix (CSS `skewY()`) |
|
|
147
|
+
| `Multiply(m1, m2)` | Returns the multiplication of two matrices |
|
|
148
|
+
|
|
149
|
+
### Instance methods
|
|
150
|
+
|
|
151
|
+
| Method | Description |
|
|
152
|
+
| --- | --- |
|
|
153
|
+
| `setMatrixValue(init)` | Returns a new matrix from the given string / array / object |
|
|
154
|
+
| `translate(x, y?, z?)` / `translateSelf(x, y?, z?)` | Applies a translation (CSS `translate3d()`) |
|
|
155
|
+
| `rotate(rx?, ry?, rz?)` / `rotateSelf(rx?, ry?, rz?)` | Applies a rotation; a single value rotates about the z-axis (CSS `rotate()`) |
|
|
156
|
+
| `rotateAxisAngle(x, y, z, angle)` / `rotateAxisAngleSelf(...)` | Applies a rotation about a vector (CSS `rotate3d()`) |
|
|
157
|
+
| `scale(x, y?, z?)` / `scaleSelf(x, y?, z?)` | Applies a scale; `y` defaults to `x`, `z` to `1` (CSS `scale3d()`) |
|
|
158
|
+
| `skew(angleX, angleY)` / `skewSelf(angleX, angleY)` | Applies a skew (CSS `skew()`) |
|
|
159
|
+
| `skewX(angle)` / `skewXSelf(angle)` | Applies a skew along the x-axis (CSS `skewX()`) |
|
|
160
|
+
| `skewY(angle)` / `skewYSelf(angle)` | Applies a skew along the y-axis (CSS `skewY()`) |
|
|
161
|
+
| `multiply(matrix)` / `multiplySelf(matrix)` | Post-multiplies by another matrix |
|
|
162
|
+
| `transformPoint(tuple)` | Transforms a `DOMPoint` or `{ x, y, z, w }` tuple |
|
|
163
|
+
| `toArray(is2D?)` | Returns an *Array* of 6/16 values |
|
|
164
|
+
| `toFloat32Array(is2D?)` / `toFloat64Array(is2D?)` | Returns a typed array of 6/16 values |
|
|
165
|
+
| `toString()` | Returns the `matrix()` / `matrix3d()` CSS syntax |
|
|
166
|
+
| `toJSON()` | Returns `{ a-f, m11-m44, is2D, isIdentity }` |
|
|
167
|
+
|
|
168
|
+
### Properties
|
|
169
|
+
|
|
170
|
+
| Property | Description |
|
|
171
|
+
| --- | --- |
|
|
172
|
+
| `a`-`f` / `m11`-`m44` | The 2D aliases and the canonical 3D values (kept in sync) |
|
|
173
|
+
| `is2D` | Getter — `true` when the matrix represents a 2D transform |
|
|
174
|
+
| `isIdentity` | Getter — `true` when the matrix is the identity matrix |
|
|
175
|
+
|
|
176
|
+
## CSSMatrix vs native DOMMatrix
|
|
177
|
+
|
|
178
|
+
The shim mirrors the native **DOMMatrix** API surface closely — the same `m11`-`m44` / `a`-`f` properties, the same `matrix()` / `matrix3d()` string output, and the same split between immutable methods (`translate()`, `rotate()`, `scale()`, `skew()`, `multiply()`) and their mutating `*Self()` counterparts. There are, however, some deliberate differences:
|
|
179
|
+
|
|
180
|
+
| Feature | CSSMatrix shim | Native DOMMatrix |
|
|
181
|
+
| --- | --- | --- |
|
|
182
|
+
| Environment | Works in **Node.js** and legacy browsers — no `DOMMatrix` / `DOMPoint` globals required | Browser only |
|
|
183
|
+
| String parsing | `CSSMatrix.fromString()` static, also via the constructor | Constructor only (`new DOMMatrix(transform)`) |
|
|
184
|
+
| Array / typed-array input | `CSSMatrix.fromArray()`, also via the constructor | `DOMMatrix.fromFloat64Array()` / `fromFloat32Array()` statics |
|
|
185
|
+
| Object input | `CSSMatrix.fromMatrix()` accepts another matrix or a `toJSON()` object | `DOMMatrix.fromMatrix()` accepts a `DOMMatrixInit` |
|
|
186
|
+
| `transformOrigin` argument | Not supported | Supported (`new DOMMatrix(init, transformOrigin)`) |
|
|
187
|
+
| `is2D` / `isIdentity` | Computed getters — always reflect the current values | `is2D` is a flag fixed at construction and can report stale results (e.g. after `rotateAxisAngle()`) |
|
|
188
|
+
| `transformPoint()` | Accepts a `DOMPoint` **or** a plain `{ x, y, z, w }` tuple; returns the same type it received | Accepts `DOMPointInit`, always returns a `DOMPoint` |
|
|
189
|
+
| `setMatrixValue()` | Returns a **new** matrix, the original is left unchanged | Mutates the matrix in place and returns `this` |
|
|
190
|
+
| `toArray()` | Plain `Array` of 6/16 values, alongside `toFloat32Array()` / `toFloat64Array()` | `toFloat32Array()` / `toFloat64Array()` only |
|
|
191
|
+
| `toJSON()` | `{ a-f, m11-m44, is2D, isIdentity }` | Same shape |
|
|
192
|
+
| TypeScript | Ships bundled type definitions, zero runtime dependencies | WebIDL-generated typings |
|
|
193
|
+
|
|
194
|
+
Methods of the `DOMMatrixReadOnly` prototype that are not part of this shim: `flipX()`, `flipY()`, `inverse()` and `rotateFromVector()` (`transpose()` is not part of the native interface either). Everything else — `translate*`, `rotate*`, `rotateAxisAngle*`, `scale*`, `skew*`, `multiply*`, `toString()`, `toFloat(32/64)Array()`, `transformPoint()` — is implemented with behavior verified against the native interface by the test suite.
|
|
195
|
+
|
|
196
|
+
## Alternatives
|
|
197
|
+
|
|
198
|
+
DOMMatrix shim is meant to be a light pocket tool for many things like [svg-path-commander](http://thednp.github.io/svg-path-commander). For a complete polyfill that fills in the missing `DOMMatrixReadOnly` methods (`inverse()`, `flipX()`, `flipY()`, ...), you might want to also consider [geometry-interfaces](https://github.com/trusktr/geometry-interfaces) and [geometry-polyfill](https://github.com/jarek-foksa/geometry-polyfill).
|
|
199
|
+
|
|
200
|
+
## Thanks
|
|
201
|
+
|
|
202
|
+
- Joe Pea for his [geometry-interfaces](https://github.com/trusktr/geometry-interfaces)
|
|
203
|
+
- Jarek Foksa for his [geometry-polyfill](https://github.com/jarek-foksa/geometry-polyfill)
|
|
204
|
+
- Arian Stolwijk for his [CSSMatrix](https://github.com/arian/CSSMatrix/)
|
|
205
|
+
|
|
206
|
+
## History
|
|
207
|
+
|
|
208
|
+
`@thednp/dommatrix` started as a fork of the [original CSSMatrix](https://github.com/arian/CSSMatrix/). In contrast with the original source there have been a series of changes to the prototype for consistency, performance as well as requirements to better accommodate the **DOMMatrix** interface:
|
|
209
|
+
|
|
210
|
+
- **changed** how the constructor determines if the matrix is 2D, based on a [more accurate method](https://github.com/jsidea/jsidea/blob/2b4486c131d5cca2334293936fa13454b34fcdef/ts/jsidea/geom/Matrix3D.ts#L788) which is actually checking the designated values of the 3D space; in contrast, the old *CSSMatrix* constructor sets the `afine` property at initialization only and based on the number of arguments or the type of the input CSS transform syntax;
|
|
211
|
+
- **fixed** the `translate()`, `scale()` and `rotate()` instance methods to work with one axis transformation, also inline with **DOMMatrix**;
|
|
212
|
+
- **changed** `toString()` instance method to utilize the new method `toArray()` described below;
|
|
213
|
+
- **changed** `setMatrixValue()` instance method to do all the heavy duty work with parameters;
|
|
214
|
+
- **added** `is2D` (*getter*) property;
|
|
215
|
+
- **added** `isIdentity` (*getter*) property;
|
|
216
|
+
- **added** `skew()` public method to work in line with native DOMMatrix;
|
|
217
|
+
- **added** `Skew()` static method to work with the above `skew()` instance method;
|
|
218
|
+
- **added** `fromMatrix` static method, not present in the constructor prototype;
|
|
219
|
+
- **added** `fromString` static method, not present in the constructor prototype;
|
|
220
|
+
- **added** `fromArray()` static method, not present in the constructor prototype, should also process *Float32Array* / *Float64Array* via `Array.from()`;
|
|
221
|
+
- **added** `toFloat64Array()` and `toFloat32Array()` instance methods, the updated `toString()` method makes use of them alongside `toArray`;
|
|
222
|
+
- **added** `toArray()` instance method, normalizes values and is used by the `toString()` instance method;
|
|
223
|
+
- **added** `toJSON()` instance method will generate a standard *Object* which includes `{a,b,c,d,e,f}` and `{m11,m12,m13,..m44}` properties as well as `is2D` & `isIdentity` properties;
|
|
224
|
+
- **added** `transformPoint()` instance method which works like the original;
|
|
225
|
+
- **added** `isCompatibleArray()` static method to check if an array is a compatible array of 6/16 numbers;
|
|
226
|
+
- **added** `isCompatibleObject()` static method to checks if an object is compatible with CSSMatrix, usually another CSSMatrix / DOMMatrix instance or the result of these instances `toJSON()` method call;
|
|
227
|
+
- *removed* `afine` property, it's a very old *WebKitCSSMatrix* defined property;
|
|
228
|
+
- *removed* `inverse()` instance method, will be re-added later for other implementations (probably going to be accompanied by `determinant()`, `transpose()` and others);
|
|
229
|
+
- *removed* `transform` instance method, not present in the native **DOMMatrix** prototype;
|
|
230
|
+
- *removed* `setIdentity()` instance method due to code rework for enabling better TypeScript definitions;
|
|
231
|
+
- *removed* `toFullString()` instance method, probably something also from *WebKitCSSMatrix*;
|
|
232
|
+
- *removed* `feedFromArray` static method, not present in the constructor prototype, `fromArray()` will cover that;
|
|
233
|
+
- *not supported* `fromFloat64Array()` and `fromFloat32Array()` static methods are not supported, our `fromArray()` should handle them just as well;
|
|
234
|
+
- *not supported* `flipX()` or `flipY()` instance methods of the *DOMMatrixReadOnly* prototype are not supported;
|
|
235
|
+
- *not supported* `scaleNonUniformSelf()` or `rotate3d()` with `{x, y, z}` transform origin parameters are not implemented.
|
|
236
|
+
|
|
237
|
+
## License
|
|
238
|
+
|
|
239
|
+
DOMMatrix shim is [MIT Licensed](https://github.com/thednp/DOMMatrix/blob/master/LICENSE).
|