paper 0.13.0 → 0.15.0

package/CHANGELOG.md

@@ -1,5 +1,342 @@
 # Change Log
 
+## `0.15.0`
+
+### Added
+
+- Load text items from the host of a hosted project, see `Project#host`, with
+  their stories, and the paths and settings of path and area text, and let
+  hosts lay them out as their documents do, through `host.layOut()`, given
+  their JSON as the script holds them, also before the host has its changes,
+  or `null` for text the script didn't change, which the host has as it is.
+- Add text ranges: `TextRange`, a part of a text whose style properties read
+  what its letters and paragraphs share and set them, from
+  `TextItem#range(start, end)`, `#runs`, `#paragraphs`, `#words`, `#letters`
+  and `#lines`, which ranges have too, and `#replace(content, start, end)`, and
+  `TextStory`, a text's content, runs and paragraphs, as `TextItem#story`.
+- Add text linking: `TextItem#link()`, `#unlink()`, `#isLinked()`,
+  `#nextTextItem`, `#previousTextItem` and `#visibleRange`, by which a story
+  flows through several text items, which `TextStory#textItems` lists.
+- Add `PathText`, text along a path between `startOffset` and `endOffset`, each
+  letter turned to the path, which it takes as `TextItem#textPath`.
+- Add `AreaText`, text inside any path as its `textPath`, holes too, in
+  columns and rows, with lines breaking between words and at soft hyphens,
+  `verticalAlign`, `fitHeight()`, and `lineWrap`, a paragraph property that
+  balances the lines.
+- Add `Item#textWrap`, by which items push aside the text of the area texts
+  below them in their layer, or let it flow inside them.
+- Export area text, text on paths and text with mixed styles to SVG: point text
+  keeps a `<tspan>` per line, with one per run where styles are mixed, and area
+  text and text on paths are placed piece by piece, as they are laid out.
+- Add character style properties: `fontStyle`, `lineHeight`, `letterKerning`,
+  `letterScaling`, `letterRotation`, `baselineShift`, `baselinePosition`,
+  `capitals`, `underline` and `strikethrough`, and `fontVariations` and
+  `features` for hosts.
+- Add paragraph style properties: `justifyLast`, `startIndent`, `endIndent`,
+  `firstLineIndent`, `spaceBefore`, `spaceAfter` and `direction`, the
+  justifications `'start'`, `'end'` and `'justify'`, and `justifySpacing`,
+  `hyphenation`, `composer` and `tabs` for hosts.
+- Let `Item#strokeBounds` be selected and set, as `Item#bounds` can:
+  `item.strokeBounds.selected` draws the stroke bounds and their handles,
+  independently of `item.bounds.selected`, and setting them scales the item so
+  its stroke bounds match, also where its stroke's extent changes with its
+  proportions, as with miters (#1030).
+- Import the `data-*` attributes of SVG elements into `item.data`, with their
+  names camelized as in `dataset`, next to `data-paper-data` (#1227).
+- Export shadows to SVG as SVG 1.1 filters, which both browsers and editors
+  such as Illustrator render, except for items without width or height, and
+  import them back, along with CSS `drop-shadow()` (#1003).
+- Import SVG masks as clip masks, which is exact for masks of solid white
+  shapes, or of opaque shapes with `mask-type="alpha"`, and warns that other
+  masks are approximated (#1916).
+- Add `Group#ungroup()`, which replaces a group with its children, applying its
+  matrix to them, and let `Item#replaceWith()` take several items (#1026).
+- Add `settings.segmentSize`, the size of the segments when drawing selections,
+  next to `settings.handleSize` for their handles, which it defaults to
+  (#1899).
+- Add `angleInRadians` to the object literals that create points, next to
+  `angle`, e.g. `new Point({ length: 10, angleInRadians: Math.PI / 2 })` (#562).
+- Add `Project#hasChanges()`, which tells whether changes were logged since the
+  last `Project#takeChanges()`, without taking them.
+- Add dynamic `import(specifier)` to PaperScript, which resolves to the module's
+  namespace through the loader in `options.load`, which may return a Promise.
+- Add static `import` to PaperScript, through a loader that hosts pass as
+  `options.load` to `PaperScript.execute()`, together with `export … from`. It
+  needs a current Acorn as `self.acorn`.
+- Add `Item.getBounds(items[, options])`, the bounds of a list of items in
+  project coordinates as if they were grouped, e.g. of the selection (#2252).
+- Add `ToolEvent#velocity` and `#elapsed`, the velocity of the mouse since the
+  last tool event in points per second, and the time since then in seconds,
+  which stay even when the system misses a mouse report.
+- Add `Event#time`, the time of the event in seconds, as frame events have it,
+  and `options.time` to `View#dispatchMouseEvent()` and `#dispatchKeyEvent()`.
+- Add a setter to `View#bounds`, which fits the view to the given rectangle, as
+  `View#fitBounds()` does.
+- Let `PathItem#unite()`, `#intersect()`, `#subtract()` and `#exclude()` take
+  an array of paths, which they combine in one call: unite, intersect and
+  subtract in a balanced tree, exclude in one even-odd pass. Uniting 500 paths
+  takes 0.22 s instead of 2.9 s chained, excluding them 0.45 s instead of
+  minutes (#2094, #2303, #2304).
+- Load hosted text that the host links into one story, which `host.getStory()`
+  gives once for all of its items, whichever of them loads first.
+
+### Changed
+
+- Lay out text by the ascent and descent of its fonts: the bounds of
+  `PointText` are its lines' line heights, with the leading split around their
+  ascent and descent, instead of 3/4 of the first above its baseline and 1/4 of
+  the last below.
+- Replace `leading` by `lineHeight`, `'auto'` (1.2) or another factor of the
+  font size, or a fixed length; `leading` still sets and reads a fixed line
+  height in pixels. Rename `tracking` to `letterTracking`, which `tracking`
+  still sets and reads.
+- Make `Style#getFontStyle()` return the CSS font style, `'normal'`,
+  `'italic'` or `'oblique'`, instead of the font as canvas takes it, and remove
+  `Style#getTrackingStyle()`.
+- Only go into the children that items show in `Item#getItems()`, and log the
+  changes of children that their parent doesn't show, such as a text's path, as
+  the parent's.
+- Make `Item#intersects()` check whether the items overlap, also when one
+  contains the other, as `Rectangle#intersects()` does, instead of only whether
+  their outlines cross, and use it in `getItems({ overlapping })` for items
+  whose bounds contain the rectangle (#1751).
+- Use `settings.hitTolerance` for the mouse events of items, such as
+  `mouseenter` and `click`, which always hit-tested with a tolerance of 0
+  (#1971).
+- Keep the named exports of PaperScript modules with a default export:
+  `export default x` now sets `module.exports.default` instead of replacing the
+  exports, and such modules are marked with `__esModule`. `import x` receives
+  the default export, or the whole exports of CommonJS-style modules, and
+  `import * as m` all exports, with CommonJS-style ones also as `m.default`.
+  So `PaperScript.execute()` returns `{ default: x }` for `export default x`.
+- Deprecate `Event#timeStamp` in milliseconds, and the `options.timeStamp` of
+  `View#dispatchMouseEvent()` and `#dispatchKeyEvent()`, for the new `time`
+  in seconds.
+- Rename the `paper-sourced.js` build to `paper-hosted.js`, and `Project#source`
+  to `Project#host`, to match `HostItem` and the host document that backs the
+  items.
+- Draw dashes with `setLineDash()`, which every canvas supports, and remove
+  the dash emulation for canvases without it, along with the undocumented
+  `paper.support.nativeDash` (#2350).
+- Trace the results of boolean operations through a planar graph of the
+  operands' curves, which each operation builds within one geometric
+  tolerance: intersections within it merge into one vertex, curves that pass
+  within it of a vertex are cut there, and coincident curves become one edge.
+  Results are correct to within about five times that tolerance, under a
+  thousandth of a unit on a drawing of 1,000 units, and stable under tiny
+  moves of the operands. They can differ from before in where their contours
+  start and how they are divided, but not in their areas. Holes come out
+  oriented opposite to their outlines, and islands like outlines (#2292).
+- `PathItem#resolveCrossings()` returns the filled outline of a path, without
+  the inner loops that its fill rule covers (#2292).
+- Make boolean operations faster than in 0.14.0 on all inputs measured, from
+  about 15% on small operations up to 5.7× on large polygons (#2293, #2296,
+  #2297, #2299, #2300, #2301, #2302, #2305).
+- Draw the CSS blend modes as `'normal'` in old browsers whose canvas doesn't
+  support them, such as Internet Explorer and the old Edge, instead of
+  emulating them pixel by pixel. Paper.js's own modes, such as `'add'`, are
+  still emulated (#2350).
+- Remove the undocumented statics `Curve.getBounds(values)`, a leftover of
+  old intersection code, and `Curve.getCurveLineIntersections()`, which
+  nothing in the library calls.
+- Drop the code for browsers without current DOM APIs, which only old IE, Edge
+  and WebKit needed: MS pointer events, `srcElement`, `toElement`,
+  `keyIdentifier`, `backingStorePixelRatio`, and the exception of
+  `getBoundingClientRect()` for nodes outside the DOM (#2350).
+
+### Fixed
+
+- Hit-test strokes with `'miter'` and `'bevel'` joins next to smooth segments,
+  which are joined round, as the stroke bounds already treat them (#2342).
+- Update `Item#strokeBounds` after changing the stroke of items without a
+  parent, such as shapes, texts, symbol items and groups, which kept the old
+  stroke bounds (#2343).
+- Fix `Path#handleBounds` of empty paths, which were infinite: they are an
+  empty rectangle, as their `bounds` (#2345).
+- Import the paragraphs of text items after their content, also from JSON that
+  lists them first, as JSON written by other tools may.
+- Keep gradients in the runs of text items through `#exportJSON()` and
+  `#importJSON()`, and round their style values and those of their paragraphs
+  to the `precision` of the export (#2348).
+- Keep what scripts write to hosted items before they load, such as their
+  `pivot` or an area text's `columns`, which loading replaced.
+- Fix the stroke bounds of non-scaling strokes under non-uniform matrices,
+  whose miters, bevels and square caps followed the untransformed angles.
+- Fix `Item#strokeBounds` after scaling items that apply their matrix, such
+  as paths and groups, when they were read before: the cached stroke bounds
+  were scaled along, including the width of the stroke, which doesn't scale.
+- Fix SVG export of `opacity` and `blendMode`, which aren't inherited, so
+  children with the same values as their group lost them, and the defaults
+  were written where the group differed.
+- Fix the shadows of items that are both filled and stroked, which only cast
+  the shadow of their fill, partly covered by the stroke (#892).
+- Fix the shadows of text items, which only text with both a fill and a
+  stroke drew (#2347).
+- Fix the points at offsets of `PathFlattener` on straight curves, such as
+  lines without handles, whose curve-time doesn't follow their length, which
+  placed them off everywhere but at the ends.
+- Fix SVG import of `<use>` elements, which now pass their styles and those of
+  their parents on to the referenced element, as in SVG, instead of the styles
+  of the place where it is defined, and skip circular references (#2090).
+- Divide the operands of boolean operations at all their intersections, also
+  where they only touch, which makes the results of near-coincident geometry
+  more stable, and ends the endless loop of #1849.
+- Fix `Curve#getTimeOf()` for points near the ends of straight curves, which it
+  solved to times far from the ends, as it only tested the ends exactly.
+- Fix boolean operations that backtracked while tracing their result, which could
+  give a curve of it the handle of a dead end and make it bulge.
+- Measure text in views without a canvas of their own, such as in workers, with a
+  canvas from `CanvasProvider`, e.g. an `OffscreenCanvas`, so `PointText` has
+  bounds there too.
+- Fix PaperScript's exported variable declarations without semicolons, such as
+  `export const a = 1`, which compiled to invalid code.
+- Fix `Curve#classify()` reporting points of inflection, cusps and loops at the
+  very ends of curves, which made boolean operations miss crossings at those
+  vertices (#1879, #1387).
+- Fix PaperScript's compound assignments of properties, such as
+  `array[index()] += 1`, which evaluated their object and key twice.
+- Fix PaperScript with a current Acorn provided as `self.acorn`, which parses
+  all current syntax now, and its exports: of functions and classes, of renamed
+  names (`export { a as b }`), of several declarations in a row, and of
+  variables, which stay usable in the script itself.
+- Fix intersections of curves and lines at the curves' ends, which were lost
+  when the curve touched the line there, e.g. at a zero-length handle (#1848).
+- Fix the orientation of the results of `PathItem#exclude()` and
+  `#subtract()`, whose parts of the second path kept its reversed orientation,
+  giving them negative areas (#2064).
+- Fix `PathItem#interiorPoint` returning points on the path itself, such as a
+  vertex shared with another path, which made boolean operations of paths that
+  only touch keep or drop the wrong parts (#1837, #1979).
+- Fix intersections and boolean operations of curves and paths that only touch,
+  at coordinates beyond 16384, where the tolerance of their bounds checks got
+  lost in floating point (#1940, #1882).
+- Fix boolean operations on open paths that end where they start, which lost
+  the curve between their ends (#1929, #1973, #1989, #2018).
+- Fix boolean operations with `{ trace: false }` on closed paths, which could
+  keep or drop the wrong parts depending on where the path started, and on
+  compound paths, which threw an error (#1540, #1541, #1746, #1998, #2046).
+- Document `Item#fullySelected`, which all items have, not only paths (#1687).
+- Type options objects from their documented options, such as those of
+  `Item#hitTest()`, `#exportSVG()` and `#rasterize()`, so misspelled options are
+  errors in TypeScript (#1666).
+- Type the setters of point, size, rectangle and color properties with the
+  values they accept, such as `item.position = [10, 20]` and
+  `item.fillColor = 'red'`. The typings now need TypeScript 4.3 (#1665).
+- Handle the mouse events of `View#dispatchMouseEvent()` also outside the
+  view's bounds, since the host decides which events belong to its drawing
+  surface.
+- Fix boolean operations on paths that touch or overlap along their edges,
+  run close to each other, or cross near their vertices, which lost or added
+  parts of their results (#1285, #1362, #1867, #1917, #1943, #1961, #2002,
+  #2036, #2096, #2099).
+- Fix `PathItem#resolveCrossings()` on paths with both overlaps and crossings,
+  which lost parts of their outlines (#2290).
+- Fix `Curve.getTimeOf()` at coordinates beyond about 2e8, where it didn't
+  recognize points on the curve (#2291).
+- Hit-test non-scaling strokes under non-uniform matrices where they're drawn,
+  also next to corners, joins and caps, and with skewed or rotated matrices
+  (#2334).
+- Fix `Curve#strokeBounds` of curves without a path, which threw: without a
+  path, there is no stroke, so they are the curve's bounds (#2344).
+- Give `View#dispatchKeyEvent()` the characters of space, enter and tab, as the
+  DOM's key events have them, instead of empty ones (#2346).
+- Fix `paper.support.nativeBlendModes`, which listed the blend modes canvas
+  accepted as `170` instead of `true`, and only knew the CSS blend modes where
+  a canvas was available when Paper.js loaded. It lists the canvas composite
+  modes and the CSS blend modes as native, and Paper.js's own modes as not,
+  without testing canvas (#2349).
+- Hit-test strokes at segments where the curves meet in the same direction,
+  such as where a line runs into a curve, whatever the join, also across
+  curves without length, as in rectangles rounded to half their height.
+- Calculate `Curve#getTimesWithTangent()`, `#length` and `Curve.getPeaks()`
+  precisely also far from the origin, from the curve's polynomial
+  coefficients, which take the differences of the points first.
+
+## `0.14.0`
+
+### Added
+
+- Add `options.handlers` to `PaperScript.execute()`, to export further global
+  handlers next to `onFrame`, `onResize` and the tool's, for hosts that call
+  them themselves, such as Scriptographer's `onStop`.
+- Add `Tool#eventInterval`, as Scriptographer had it, to fire `onMouseDrag` again
+  at an interval while the mouse button is held, also when the mouse doesn't
+  move.
+- Add `Project#scope`, `View#scope`, `Item#scope` and `Tool#scope`, to get from
+  each of them to its `PaperScope` (#1634).
+- Add `Group#isolated`, to draw a group or layer through a temporary canvas, so
+  that the blend modes of its children, such as `'destination-out'`, only apply
+  within it, like CSS's `isolation: isolate` (#474).
+- Add `View#dispatchMouseEvent()` and `View#dispatchKeyEvent()`, to feed mouse
+  and key events from hosts without a DOM, such as workers, through the same
+  handling as the DOM's events, for tools, items and views.
+- Add `settings.scaleStrokes`, to scale the stroke widths of paths and
+  compound paths along with their content when matrices are applied (#2098,
+  #1514).
+- Add the `paper-sourced.js` build, in which a project's items can be backed
+  by a host document through `Project#source`: items are created as light
+  shells from the host's records, and load their content and children from
+  the host on first access, so a script costs what it touches. Includes
+  `HostItem`, for the host's own kinds of nodes (#2203).
+- Add `Project#trackChanges` and `Project#takeChanges()`, to let hosts that
+  keep their own document update only the items that changed, and export
+  `ChangeFlag` (#2202).
+
+### Changed
+
+- `Path.RegularPolygon()` follows Illustrator: it stands on a flat bottom edge
+  for any number of sides, and its segments run counterclockwise from its top
+  vertex, or with an even number of sides, from the right end of its top edge.
+  This changes the segment order of all regular polygons, and turns those with
+  a multiple of 6 sides onto an edge (#1787).
+- Hit-test transparent fills, as in SVG: only items without a fill color are
+  not hit through their fill (#1157).
+- `paper.install()` keeps what the target scope has already, such as the
+  native `Event`, `MouseEvent` and `Symbol`, and PaperScript doesn't shadow
+  existing globals with Paper.js's classes of the same name either (#1832,
+  #1652).
+- `Item#importJSON()` into an existing item resets the fields that the JSON
+  leaves out, so the item ends up the same as a newly imported one, with its
+  place in the scene graph and its event handlers kept (#1425, #1324).
+- Canvases without `resize` get their CSS size from the view on every screen,
+  not only at pixel ratios other than 1, where the page's CSS won (#2088).
+- `#hitTestAll()` reports every segment and handle of a path within the
+  tolerance, closest first, followed by its stroke or fill hit, instead of only
+  the first hit per path (#1294).
+
+### Fixed
+
+- Create the tool in PaperScript for all of its global handlers, also for
+  scripts that only define `onActivate()` or `onDeactivate()`, and document
+  `Tool#onActivate` and `Tool#onDeactivate`.
+- Keep `Key.modifiers` in sync with the flags of mouse events, so modifier keys
+  pressed or released while the page didn't have the focus don't stay wrong
+  (#1140).
+- Keep Paper.js's own blend modes, which CSS doesn't have, such as
+  `'destination-out'`, through SVG export and import, in a
+  `data-paper-blend-mode` attribute (#1296).
+- Throw a clear error when creating an item without a project, instead of a
+  null access deep inside the constructor (#1889).
+- Free the pixels of temporary canvases when they're released, which their pool
+  kept allocated at their largest size for the life of the page.
+- Keep the size of rasters in JSON, so imported rasters have their size and
+  bounds before their image has loaded, or if it fails to load (#1598).
+- Fix the frame timer of workers and Node.js running forever after any script,
+  which kept hosts from seeing scripts end.
+- Fix touch scrolling over empty parts of a canvas whose items have mouse
+  handlers (#1930).
+- Fix mouse events reaching items and views through elements that cover the
+  canvas, such as menus. Drags still reach beyond them (#992).
+- Fix the points of `#hitTestAll()` results of items inside transformed
+  groups, which were in the items' own coordinates.
+- Support `strokeScaling: false` on text, exactly for uniform scaling (#1703).
+- Fix the view size of canvases inside elements with CSS transforms, which
+  only scale the canvas on screen.
+- Fix italic and oblique font weights in SVG export and import, which SVG
+  keeps in `font-style` (#937).
+- Fix `onFrame` in web workers, where views have no element (#2200).
+- Fix `PaperScope#execute()` in web workers (#2201).
+
 ## `0.13.0`
 
 ### Added

package/README.md

@@ -201,16 +201,14 @@ Paper.js uses [Gulp.js](https://gulpjs.com/) for building, and has a couple of
 dependencies as NPM modules. Read the chapter [Installing Node.js and
 NPM](#installing-nodejs-and-npm) if you still need to install these.
 
-Due to a conflict in Gulp 3 that could only be resolved using package
-resolution, we recently switched from NPM to `yarn` for development, which also
-needs to be installed now. See
-[Installing Yarn](https://classic.yarnpkg.com/en/docs/install/) for details.
+Development uses [pnpm](https://pnpm.io/), which needs to be installed too. See
+[Installing pnpm](https://pnpm.io/installation) for details.
 
 In order to be able to build Paper.js, after checking out the repository, paper
 has dependencies that need to be installed. Install them by issuing the
 following commands from the Paper.js directory:
 
-    yarn install
+    pnpm install
 
 ### Building the Library
 
@@ -218,7 +216,7 @@ The Paper.js sources are distributed across many separate files, organised in
 subfolders inside the `src` folder. To compile them all into distributable
 files, you can run the `build` task:
 
-    yarn build
+    pnpm build
 
 You will then find the built library files inside the `dist` folder, named
 `paper-full.js` and `paper-core.js`, along with their minified versions. Read
@@ -236,11 +234,11 @@ library.
 This means you can switch between loading from sources and loading a built
 library simply by running.
 
-    yarn load
+    pnpm load
 
 And to go back to a built library
 
-    yarn build
+    pnpm build
 
 Note that your PaperScripts examples do not need to change, they can keep
 loading `dist/paper-full.js`, which will always do the right thing. Note also
@@ -250,7 +248,7 @@ that `src/load.js` handles both browsers and Node.js, as supported by Prepro.js.
 
 Create a final zipped distribution file inside the `dist` folder:
 
-    yarn dist
+    pnpm dist
 
 ### Branch structure
 
@@ -261,7 +259,7 @@ only merged into [`main`](https://github.com/paperjs/paper.js/tree/main)
 when a new release occurs.
 
 As of version `0.9.26`, the `dist` folder is excluded on all branches, and the
-building is now part of the `yarn publish` process by way of the `prepublish`
+building is now part of the `pnpm publish` process by way of the `prepublish`
 script.
 
 We also offer prebuilt versions of the latest state of the `develop` branch on
@@ -273,7 +271,7 @@ and [`prebuilt/dist`](https://github.com/paperjs/paper.js/tree/prebuilt/dist).
 Similarly to building the library, you can run the `docs` task to build the
 documentation:
 
-    yarn docs
+    pnpm docs
 
 Your docs will then be located at `dist/docs`.
 
@@ -291,11 +289,16 @@ 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:
 
-    yarn test:browser
+    pnpm test:browser
+
+To run them in headless Chrome instead, as CI does, and report the result in the
+terminal:
+
+    pnpm test:chrome
 
 To test the Node.js version of Paper.js, use this command:
 
-    yarn test
+    pnpm test
 
 ### Contributing [![Open Source Helpers](https://www.codetriage.com/paperjs/paper.js/badges/users.svg)](https://www.codetriage.com/paperjs/paper.js)
 
@@ -347,7 +350,9 @@ As mentioned above, we prefer that you send a
    worry about the perfect name though -- you can change this name at any time
    later on.
 
-4. Hack! Make your changes, additions, etc., commit them then push them to your
+4. Hack! Make your changes, additions, etc., and describe them for the
+   changelog in a file of their own in `changelog/unreleased`, see its
+   [README](changelog/unreleased/README.md). Commit them then push them to your
    GitHub fork: `git push origin name-of-my-patch`
 
 5. Send a pull request to the upstream repository's owner by visiting your