paper 0.15.0 → 0.17.0

package/CHANGELOG.md

@@ -1,5 +1,163 @@
 # Change Log
 
+## `0.17.0`
+
+### Added
+
+- Add `PathItem#offset(distance, options)`, which grows, shrinks or offsets
+  paths and compound paths with miter, round or bevel corners (#371).
+- Add `PathItem#outline(options)`, which turns the stroke of a path item into a
+  filled path item, with its joins, caps and dashes (#371).
+- Add `PathItem#dash(options)`, which cuts a stroke into its dashes as the
+  canvas draws them, as a group of open paths.
+- Add stroke profiles, `Path#strokeProfile`: stops along a path that change
+  the width, aspect and angle of the pen that draws its stroke, see
+  `StrokeProfileStop`. Not yet supported: compound paths, `strokeScaling` off,
+  and `offset()`, boolean operations, `interpolate()` and SVG (#2505, #2506,
+  #2507).
+- Add live effects, `Item#effects`, which change what an item draws without
+  changing the item, starting with `offset` and `outline`. `Effect` defines new
+  ones, and `Item#previewBounds` measures what they draw.
+- Add pattern colors from a `PatternDefinition`, which tiles a raster or any
+  other item, for fills and strokes, also in SVG and JSON (#829).
+- Add `Color#aspect` for elliptical radial gradients, and transform gradients
+  exactly with their items, also when these scale unevenly or shear (#1744).
+- Add `Group#buffered`, which keeps a group's drawing in a canvas until the
+  group changes, for large groups that rarely do (#377).
+- Add `Item#onDraw` and `Item#onDrawSelection`, which draw beneath an item or
+  its selection, or replace them, also as class-level handlers such as
+  `Path.onDraw`.
+- Add `PathItem#arcAround(center, angle)` and `PathItem#arcTowards(to)`
+  (#1052).
+- Support `options` in `PathItem#simplify()`, with `tolerance` and a range of
+  segments through `from` and `to`, as in `PathItem#smooth()` (#2501).
+- Export and import the names and data of segments in SVG, as a
+  `data-paper-segments` attribute (#2398).
+- Add `Project#onActivate` and `Project#onDeactivate`, also as
+  `Project.onActivate` and `Project.onDeactivate` for all projects.
+- Pass the import attributes of `import … with { … }` in PaperScript on to the
+  loader in `options.load` of `PaperScript.execute()`.
+- Hosted projects, see `Project#host`:
+  - Share symbol and pattern definitions between items, referred to by their
+    keys in JSON, and let scripts create new ones.
+  - Load the pixels of rasters from the host on first access.
+  - Load items in full when they move into a project with another host.
+  - Call `Item#onDraw` and `Item#onDrawSelection`, through `Project#draw()`.
+
+### Changed
+
+- Run the library in strict mode, which makes `Path#getNearestPoint()` about
+  14% and `Item#hitTest()` about 6% faster. PaperScript still runs in sloppy
+  mode.
+- Draw items with opacity, blend modes or shadows about twice as fast (#377).
+- Make `PaperScope#project` an accessor, so that PaperScript's `project`
+  follows the active project, as `view` does.
+- Emit `deactivate` when the active project or tool is removed.
+- Write the definition of symbol items to JSON as `definition` instead of
+  `symbol`, which still loads.
+- Let hosted linked text that moves into a project with another host bring a
+  copy of its story along (#2462, #2463).
+
+### Fixed
+
+- Fix boolean operations that could lose areas or whole results, at straight
+  curves, near-coincident crossings, curves running back and forth along a
+  line, shallow crossings and merged vertices.
+- Measure curve lengths precisely near cusps, where `Curve#getLength()` and
+  `Path#getPointAt()` were off by up to 6%.
+- Find the nearest point on curves that cover a lot of ground between their
+  samples, in `#getNearestPoint()` and the methods using it.
+- Fix `PathItem#smooth()` with a negative `to` on closed paths, which threw.
+- Fix `PathItem#arcTo()` with tiny arcs, which missed their end point.
+- Keep the attributes of compound paths in `CompoundPath#reduce()` when a
+  single child is left.
+- Return `false` from `CompoundPath#simplify()` without children.
+- Keep the stripes of linear gradients across them when transforming them
+  unevenly (#1744).
+- Export the gradients of items that keep their matrix to SVG in the
+  coordinates of their elements (#2410).
+- Honor the `bounds` and `matrix` options of `Item#exportSVG()`.
+- Keep `Group#isolated` and `Group#buffered` in clones.
+- Keep the content of rasters when setting `Raster#size`.
+- Load `new Raster(source)` from a string where there is no document, as in
+  workers.
+- Draw the segments of selected paths again by default (#1899).
+- Count the duration of `Item#tween()` from the first frame.
+- PaperScript: compile `++` and `--` correctly wherever they appear, keep
+  keywords apart from replaced expressions in minified code, report the right
+  lines in stack traces on V8, and return an object from `compile()` for empty
+  code.
+- Hosted projects: leave items that moved away out of `Project#takeChanges()`,
+  and turn off `View#autoUpdate` when setting `Project#host`.
+- Let Angular's esbuild builder bundle Paper.js for browsers (#2035).
+
+## `0.16.0`
+
+### Added
+
+- Add the `processNode` option to `#exportSVG()` and the `processItem` option
+  to `#importSVG()`: callbacks that receive `{ item, node }` for each exported
+  item with its SVG node and each imported SVG element with its item, and can
+  return a replacement, e.g. to keep the SVG `class` attribute in `Item#data`
+  (#1843).
+- Let `Rectangle#scale()` take a center point to scale from, as
+  `Item#scale()` does, and normalize rectangles scaled by negative amounts
+  (#1352).
+- Add `Segment#name` and `Segment#data`, stored in JSON but not in SVG. Named
+  segments can be accessed by name through `Path#segments`, as named items
+  through `Item#children` (#1459).
+- Add `Style#paintOrder` and `Item#paintOrder`: `'stroke'` paints the stroke
+  before the fill of paths, shapes and text, as in SVG's `paint-order`, which
+  is exported and imported (#1731).
+- Lay out right-to-left text in the order it reads: the pieces of the lines of
+  paragraphs whose `direction` is `'rtl'` are placed, hit and exported from the
+  right, path text runs from the path's end towards its start, and canvas
+  measures and draws text in its paragraph's direction (#2389).
+- Export layers to SVG with a `data-paper-layer` attribute, and import the
+  groups that carry it as `Layer` items again, inside the imported group
+  (#483).
+- Add `SymbolItem#embed()`, which replaces a symbol item with a copy of its
+  definition's item, transformed by the symbol item's matrix and combined with
+  its opacity, visibility, blend mode and other attributes (#953).
+- `Project#currentTextStyle` in hosted projects: the style new text items take
+  in place of `Project#currentStyle` when the host sets one, for hosts whose
+  new text has defaults of its own, such as a black fill without a stroke.
+- Add `Point#values`, `Size#values` and `Rectangle#values`, which give their
+  numbers as an array, as `Matrix#values` does.
+- Add `options.evaluate` to `PaperScript.execute()`, for hosts whose engine
+  doesn't name code from `Function()` in stack traces, such as JavaScriptCore.
+
+### Changed
+
+- Apply the `data-*` attributes of imported SVG elements to `Item#data` before
+  calling the `processItem` callback of `#importSVG()`, so that it can extend
+  the data, instead of after it, which replaced the data that it stored. Items
+  that the callback returns as replacements no longer receive the data.
+
+### Deprecated
+
+- The undocumented `onExport(item, node, options)` and
+  `onImport(node, item, options)` options of `#exportSVG()` and
+  `#importSVG()`, replaced by `processNode` and `processItem`.
+
+### Fixed
+
+- Only call the import callback of `#importSVG()` for SVG elements, not also
+  for the document of SVG strings, which received the item of its root element
+  a second time.
+- Leave out the item itself and its ancestors when inserting children, which
+  created a cycle in the scene graph and overflowed the stack, e.g. in
+  `new Group({ children: [new Layer()] })`, and return `null` from
+  `Item#insertChildren()` when none of the items can be inserted (#2406).
+- Keep the text path of hosted `PathText` and `AreaText` items when the host
+  changes them: `Project#invalidate()` loads its new geometry into the path
+  that scripts hold, which it replaced before.
+- Hit-test the strokes of shapes as those of their paths, which `Shape` only
+  approximated for ellipses and rounded corners, and for non-scaling strokes
+  under non-uniform matrices (#2334).
+- Name PaperScript's url in stack traces also without source maps, and in the
+  location of its syntax errors.
+
 ## `0.15.0`
 
 ### Added

package/README.md

@@ -277,28 +277,36 @@ Your docs will then be located at `dist/docs`.
 
 ### Testing
 
-Paper.js was developed and tested from day 1 using proper unit testing through
-jQuery's [Qunit](https://qunitjs.com/). To run the tests after any
-change to the library's source, simply open `index.html` inside the `test`
-folder in your web browser. There should be a green bar at the top, meaning all
-tests have passed. If the bar is red, some tests have not passed. These will be
-highlighted and become visible when scrolling down.
-
-If you are testing on Chrome, some of the tests will fail due to the browser's
-CORS restrictions. In order to run the browser based tests on Chrome, you need
-to run a local web-server through Gulp.js. The following command will handle it
-for you, and will also open the browser at the right address straight away:
+The tests run with [Vitest](https://vitest.dev/), on Node.js and in Chromium
+through [Playwright](https://playwright.dev/), against the library built from
+the sources:
 
+    pnpm test
+
+To run them only on Node.js, or only in the browser:
+
+    pnpm test:node
     pnpm test:browser
 
-To run them in headless Chrome instead, as CI does, and report the result in the
-terminal:
+The browser tests need Chromium for Playwright, which this installs once:
 
-    pnpm test:chrome
+    pnpm exec playwright install chromium
 
-To test the Node.js version of Paper.js, use this command:
+Once the library is built in `dist`, the tests run against that instead. Select
+another build than `paper-full.js` with `PAPER_BUILD`, e.g.
+`PAPER_BUILD=hosted pnpm test:node`. Vitest also runs single files, and watches
+for changes with `pnpm exec vitest`.
 
-    pnpm test
+The screenshot tests in `test/screenshots` compare what the library draws with
+reference images. Rendering differs between systems, so they run in Playwright's
+Docker image, which needs [Docker](https://www.docker.com/):
+
+    pnpm test:screenshots
+
+To write new reference images, after adding a test or changing what it draws,
+and review them in `test/screenshots/__screenshots__` before committing:
+
+    pnpm test:screenshots --update
 
 ### Contributing [![Open Source Helpers](https://www.codetriage.com/paperjs/paper.js/badges/users.svg)](https://www.codetriage.com/paperjs/paper.js)