svgedit/docs/versions/3.0.0.md

# Version 3.0.0

3.0.0 offers a number of changes since 2.8.1, including many refactoring
ones meant to make the code more maintainable and leverage current standards
for more readable and semantic code, as well as a good number of fixes and
enhancements.

Please see the CHANGES file (or the Git history or Github tracker) for more
detailed descriptions of individual changes than that provided by the
below summaries.

Concomitant with switching to npm (semantic) versioning, future releases
should be added for any changes on a more frequent schedule.

## Breaking changes

There were also the following breaking changes. Not included among these are
those handful of breaking changes which only applied to those adopting
3.0.0 pre-release versions and which are marked as
"Breaking change (prerelease)" in CHANGES).

### Modularization-related breaking changes

A number of changes were made to improve modularization.

#### Source code converted to ES6 Modules

If you were modifying source files directly, the module format has now changed
to ES6 Modules. This allows us to specify, in a standard fashion, all of
the external dependencies of a file, without any "magic" variables appearing
in the code with no indication of their source (unless they are browser
globals which should be well-known). Use of modules also avoids the need
to keep track of dependencies non-contextually within the HTML and allows us
to avoid polluting our HTML with additional script tags.

File names were also changed. See "Other breaking changes" for these.

Note that compilation no longer occurs with a Makefile but is handled by
Rollup, a library for bundling ES6 Modules. Our Rollup routine also
handles applying Babel and minification.

Note that while the number of script tags in the HTML has been reduced,
certain polyfill files (dom-polyfill and @babel/polyfill) have now been
added and are required for older browsers. They could be dropped in the
future once browser support is available or if you are only targeting
browser versions that have no need of them.

For ES6 Modules being available as a distribution option, see "Enhancements".

##### Design choices for applying modules (Technical)

The jQuery files have not been added in ES6 Modules format, however, because
they do not have such a distribution and adding an import in source which
converts them to ES6 Modules through plugin would require compilation
whereas we'd prefer that at least the modular editor file be able to work
without compilation for faster debugging (note, however, that rather than
importing our external npm dependencies directly from `node_modules`, we
have a `copy-deps` script for copying these files into our repository, so
experimenting on these files should probably be done within the
`editor/external` directory and such changes must not be committed unless
the source packages are also updated and the `copy-deps` routine brings them
in).

The file `redirect-on-lacking-support.js` has not been bundled with the main
`svgedit-config-es.js` script so that browsers not supporting SVG are
redirected faster (and, in the same vein as polyfills, it may be more
logically consistent to add this external to the main code anyways).

The file `redirect-on-no-module-support.js`, which redirects when module
support is not available, is not bundled for the same type of reason.

#### JavaScript config file breaking changes

Unlike version 2.8.1 which had a `config-sample.js` file which needed
to be copied to `config.js` in the same `editor` directory, in version 3.0.0,
things work out of the box by pointing to the pre-built config files (also
an advantage for our use of Github-based project hosts like
raw.githack.com), but these config files have been moved out of the
`editor` folder and are looked for in the parent directory (project root
if using the editor within our repository).

These files also now have different names (`svgedit-config-es.js`
for `svg-editor-es.html` and `svgedit-config-iife.js` for `svg-editor.html`)
for a measure of namespacing.

This move is intended to allow config to be stored semi-independently
of editor files.

Also note that while the config file was optional in 2.8.1, the config
file in 3.* includes (or for, the ES version, imports) all of the main
SVG-Edit code, so the file (or one like it) cannot be omitted. This has
the advantage of avoiding an extra script tag and for the non-ES version,
an extra HTTP request. But if you are working with the non-modular HTML
and are not running the build routines to compile ES to non-modular
JavaScript, you will be required to directly modify your config within
the large non-modular, bundled JavaScript config file that includes most
of the SVG codebase.

The build routines include `npm run build-config` (renamed in 5.0 to
`build-by-config`) to convert the JavaScript config to non-modular form
(including the main svgedit application code which the config files import),
`npm run rollup` to convert the other source files to non-modular form, and
`npm run build-html` to build the non-modular HTML out of the modular HTML
(all of these are run during `npm run test-prep`, or if you want to run the
tests, also as a part of `npm test` and `npm run browser-test`).

#### Stylesheet breaking changes

In version 2.8.1, one could place a `custom.css` file in the same directory
as the editor and it would be used.

The default is now looked for in the parent directory of the editor HTML
and is expected as `svgedit-custom.css`.

You may change the stylesheets which are loaded by changing the default
JavaScript stylesheet config (see the
"JavaScript config file breaking changes" section for the location of
these files). The default behavior is equivalent to this:

```js
svgEditor.setConfig({
  stylesheets: [ '@default', '../svgedit-custom.css' ]
})
```

...which indicates that all default stylesheets will be loaded and then
one's custom file. You may omit either of these and/or add your own.

See "Other breaking changes -> HTML" for removal of the "scoped"
attribute on a stylesheet within the HTML.

#### Base path breaking changes

With extensions and locales now also expressed as ES6 modules in source
(see their respective breaking changes section below), the non-modular
versions of these files have been compiled into the new `dist` directory,
and in order to avoid path resolution problems, the config properties
`extPath` and `langPath` now have different defaults, depending
on whether a module environment is detected or not.

The non-modular versions will now default to `../dist/extensions/` and
`../dist/locale/`, respectively, whereas the modular version will use the
old default paths (`extensions/` and `locale/`).

Also, since we have not copying extension icons over to `dist` and the path
resolution of extension icons would otherwise break, we have now added new
a config property, `extIconsPath`, distinct from `extPath`, which points
by default to `extensions/` for both modular and non-modular environments.

And because our dependencies canvg and jspdf are now building from module
and would break as a result of this move as well, we have added the config
`canvgPath` and `jspdfPath` which default respectively to `canvg/` and
`jspdf/` in modular loads and to `../dist/` for both path types within
non-modular loads.

(`imgPath` and `jGraduatePath` remain unchanged since they, as with
`extIconsPath`, are not looking for module-expressed files.)

#### Locale breaking changes

Locale files are now formatted as ES6 Module exports (rather than as
calls to `svgEditor.readLang`).

In order for their value to be discovered when compiled and loaded
in a non-modular context, in such contexts they will be auto-defined
as global variables (as "svgEditorLang_" followed by the
locale file name with any hyphens replaced as underscores).

In the spirit of modularization and only loading what is needed,
locale strings pertaining solely to extensions were moved to
`editor/extensons/ext-locale/<extension name>/<language code>.js`.

A new method, `importLocale`, is passed to extensions (see
"Summary of enhancements -> APIs") which can load locale files within
this hierarchy, requiring no arguments if relying on the detected locale.

The `npm run rollup` routine (also a part of `npm run test-prep` or
the full test routines) will build any properly named and formatted ES6
Modules locale file into a non-modular file within `dist/locale`.

#### Extension breaking changes

Extension files are now formatted as ES6 Module exports (rather than as
calls to `svgEditor.addExtension`). The latter may still be used, but
support for passing an object (with a `callback` method as an init function)
is not (`callback` may be present on the *return* object of extension `init`
method, however).

In order for their value to be discovered when compiled and loaded
in a non-modular context, in such contexts they will be auto-defined
as global variables (as "svgEditorExtension_" followed by the
extension file name with any hyphens replaced as underscores).

The name supplied as the first argument to `addExtension` should instead
be expressed as a property on an object exported by the extension (or
it can be omitted to default to a name derived from the file name; this is
only used as a unique identifier).

Any init function previously supplied as second argument to `addExtension`
should be expressed as an `init` method on the object exported by the
extension, and it should return what the init function had been returning.
Its `this` value will be set to the editor object.

For the object returned by `init`, invocation of any `callback` method
will also be invoked with the `this` value set to the editor object.

The `npm run rollup` routine (also a part of `npm run test-prep` or
the full test routines) will build any properly named and formatted ES6
Modules extension file into a non-modular file within `dist/extensions`.

See also "Locale breaking changes".

### Other breaking changes

- **Usage** - Avoid zoom with scroll unless shift key pressed; checkbox
  for persisting choice of initial use storage approval in storage
  extension dialog is now turned on by default for convenience of
  most users (must still hit "ok" and users can still turn off the checkbox)
- **Process changes**:
  - Change PDF export to check `exportWindowName` for filename and change
    default from `download` to `svg.pdf`, distinguishing from other downloads
- **HTML changes**: Remove now obsolete `scoped` attribute from `style`
  and move tag to head
- **File renames/removal** - Files were renamed for greater clarity and
  consistency
  - **Minified file renaming/removal**
    - `jquery.js` to `jquery.min.js`
    - `extensions/mathjax/MathJax.js` to `extensions/mathjax/MathJax.min.js`
    - Remove minified jgraduate/spinbtn files (minified now within Rollup
      bundling)
  - Avoid **"SVG" in file names** except for main file, `svg-editor.js`,
    long-time core, `svgcanvas.js`, and polyfills with "SVG" in actual
    variable name ("pathseg.js" to "svgpathseg.js"); also make clear
    distinct file purpose ("svgedit.js" to "namespaces.js" and
    "svgutils.js" to "utilities.js")
  - Consistent **jQuery-based-file naming** (and reflect name of class):
    "jquery-svg.js" to "jQuery.attr.js"
    "jquery.contextMenu.js" to "jQuery.contextMenu.js",
    "jquery.jpicker.js" to "jQuery.jPicker.js",
    "JQuerySpinBtn.css" to "jQuery.SpinButton.css",
    "JQuerySpinBtn.js" to "jQuery.SpinButton.js",
    "jquery.svgicons.js" to "jQuery.svgIcons.js",
    "jquery.jgraduate.js" to "jQuery.jGraduate.js"
- **Method naming**:
  - Switch where feasible to **capitalized acronyms**
    (`addSvgElementFromJson()` to `addSVGElementFromJson`,
    `changeSvgContent()` to `changeSVGContent()`)
- **APIs**
  - **Modularity/removing globals**
    - Remove `window.svgCanvas` and `svgCanvas.ready` (use
      `svgEditor.canvas` and `svgEditor.ready` instead)
    - Avoid passing `canvg` to extensions (have them import)
    - As part of possible deprecation of "private" methods separate from public
      methods of SvgCanvas or svgEditor, avoid adding the following methods
      already available on canvas to `getPrivateMethods` which is passed to
      extensions: `assignAttributes`, `addSVGElementFromJson`,
      `call`, `copyElem`, `findDefs`, `getElem`, `getId`,
      `getIntersectionList`, `getMouseTarget`, `getNextId`, `getUrlFromAttr`,
      `hasMatrixTransform`, `matrixMultiply`,
      `recalculateAllSelectedDimensions`, `recalculateDimensions`,
      `remapElement`, `removeUnusedDefElems`, `round`, `runExtensions`,
      `sanitizeSvg`, `setGradient` `transformListToTransform` (and mistaken
      `toString` export)
  - **Other breaking API changes** - To allow extensions to add images without
    select image dialog, only "image" mode will trigger dialog; require `new`
    with `EmbeddedSVGEdit`; for `ext-imagelib`, change to an object-based
    encoding for namespacing of messages (though will keep stringifying/parsing
    internally until we remove IE9 support); the WebAppFind extension was
    modified to use its new API; `svgcanvas.setUiStrings` must now be called
    if not using `svg-editor.js` in order to get strings (for sake of i18n)
    (and if using `path.js` alone, it must also have its `setUiStrings`
    called); `RGBColor` must accept `new`; `readLang` no longer calls
    `setLang` (locales need not call this anymore anyways; it will be
    imported); the dropping of XML internal subsets (as a security fix
    for entity expansion) might cause breakage with documents using
    entities (though browser support for entity declarations has been
    low); remove `storagePromptClosed` state boolean in favor of
    `storagePromptState`
- **Extensions**
  - **ext-arrows** - Change name from `Arrows` to `arrows`
    for sake of consistency with file path (not localized anyways; only
    used for unique identification)
  - **ext-overview-window** - Avoid setting global `overviewWindowGlobals`

## Deprecations and situational regressions

- While string based messaging continues to work with `ext-imagelib`, the
  **object-based messaging** should be used instead (as also used now in
  the embedded editor API and `ext-xdomain-messaging`)
  - The IAN image library, for which access is built-in to svgedit, has
    already adjusted to deploy our new recommended object-based messaging
    format. After more of their users migrate to version 3.\* of svgedit,
    we should then hopefully be able to avoid passing this site an argument,
    (`svgedit=3`) within their URL (a flag, if not present, which they are
    using to employ the old object messaging mode).
- **Situational regressions**: Remove Openclipart as its site's now setting of
  `X-Frame-Options` to `"sameorigin"` makes it unusable on our end
  for our cross-origin uses (even with an attempt to use their API). We
  did make and keep a file `openclipart-es.html` (and auto-converted file,
  `openclipart.html`) within `editor/extensions/imagelib` for a
  convenient browser of their library, but the SVG files it finds cannot
  be accessed cross-origin to integrate into SVG-Edit; see also
  Summary of Fixes (Embedded Editor -> Cross-origin issues and
  Browser/device-specific fixes).

## Summary of fixes

Since 2.8.1, there have been a number of fixes. Here is a summary (though
we do not include regressions made during the 3.0.0 prereleases which
have since been fixed; search CHANGES for "regression" for these):

- **Security fixes**:
  - **URL Config**: 'extPath', 'imgPath', 'langPath' were not being prevented
    from URL setting
  - **Imagelib extension**: Avoid XSS, prevent billion laughs attack, only
    allow `imgLibs` config origins for messaging
  - **xdomain HTML**: Namespace this file to avoid it being used to modify
    non-domain storage on the same domain
  - **Embedded API**: Avoid arbitrary property setting for trusted domains
  - **toXml**: Ensure all apostrophes are escaped for `toXml` utility
- **Localization/i18n**: French and German updates; adding simplified Chinese
  to pull-down; bad characters in Persian locale file; fix "lv" locale;
  clarify locale messages re: save as; fix `lang` and `dir` for locales
  (though not in use currently); allow language in settings to be properly
  set back to a different locale, ensure language changes are retained and
  available before settings dialog is closed; ensure `langReady` changes
  are available when dialog is closed and that its changes have occurred
  by extensions' first load to ensure extension loading complete and the
  updating of canvas at this time based on `storagePromptState` has seen
  `langReady` including the storage extension possibly having set a
  `storagePromptState` of "waiting"
- **Directly user-visible fixes**: center canvas properly on load;
  imported images with rubberband box placement and unattached dragtool;
  hidden font-size setting; resizing nullifying the stroke; layers panel;
  zoom centered on cursor when scrolled, avoiding when shift key is pressed;
  Document Properties dialog positioning; ensure repeated selection of same
  file overwrites with that file's contents
    - **Export fixes** - Alert if `exportWindow` blocked; avoid error
      if `URL` is not defined; polygon/polyline in PDF export; see also
      "browser-specific"
- **Keyboard/Command**: keypress double binding; text element not
  being triggered by input as well as keyup events; pasting lines with
  markers in certain cases; backspace key in Firefox navigating out of frame;
  ensure shift-key cycling through flyouts works with extension-added
  `includeWith` as well as toolbarbuttons; ensure line tool shows as
  selected when "L" key command is used
- **Processing fixes**: browser feature detection
  (`supportsPathInsertItemBefore` and `supportsPathReplaceItem`); layer fixes;
  multiple selection; cloning of path segments during moving; `convertPath`
  with complex paths; preserving `rx` and `ry` on ellipses to allow disabling
  of rendering; proper handling in `ext-connector` of 2 connecting elements
  with same y-coordinate; `removeFromSelection` length issues; avoid errors
  for `tspan` passed to `getGradient`; avoid race condition in applying arrows
  revealing flyouts and ensure this icon is cloned so can be applied to
  more than one extension; avoid setting `Math.precision` pseudo-global in
  jPicker; precision argument had not been passed in previously to jPicker;
  for image import, avoid race condition and avoid 0 width/height import
- **API fixes**: Trigger `svgEditorReady` when canvas is ready and via
  iframe; properly default `rasterExport` without `imgType`
- **Embedded editor**:
  - Do not add parent URL to iframe src URL when query string is empty.
  - **Cross-origin issues**: Due to Chrome having applied more restrictions
    on cross-origin iframes, the embedded editor broke in some contexts.
    We now avoid errors for same-origin checking, and avoid or recover
    from exceptions with cross-origin `localStorage` or `contentDocument`
    access; apparently works with `Access-Control-Allow-Origin` header and
    locally set with `allowedOrigins` with `*` or the given origin(s)
    (such as in the xdomain editor); however, `localStorage`, as is
    needed for clipboard and saving in storage, does not work regardless;
    we should allow a listener in the parent frame (made configurable
    through the embedded API), so it can get and set its own storage in
    response to SVG-Edit events. We are also still throwing for some
    `localStorage` access (e.g., context menu cut).
- **Browser/device-specific fixes** impacting Overview Panel performance;
  multiselect with zoom; multiple element selection; `getInsectionList`;
  pathseg; `supportsNativeTransformLists` detection; save/export;
  removing identity matrices; recover from `tspan` having no `getBBox`
  image export; `supportsGoodTextCharPos`; force PDF download in Chrome
  (dropped dataURI with window opening); map extension click events to
  "mousedown" so they can be received on touch devices
- **Extension fixes**: ForeignObject editor dialog had not been opening; fix
  `name` for moinsave; error during resize with MathML; add images
  for fallback and referenced relative to new `extIconsPath`; extension
  `includeWith` flyout button conflicts; avoid erring if `inradius` is `NaN`
  in Star extension. A fix was added to allow `mouseup` triggering for
  extensions in "zoom" and "select" modes, but was reverted in 3.0.1.
- **Linting-discovered fixes**: Inadvertent global assignments; bad variable
  scope declarations including within `jquery.jgraduate.js`
- **Minor fixes** such as broken links and switching to `https`, adding of
  ignore files, etc.

## Summary of enhancements

- **Directly user-visible changes**: If adding a new image, delete that image
  upon dialog cancel
- **i18n**: i18nize `path.js` strings and canvas notifications; more i18n
  of extensions; have general locales load first so extensions may use;
  placeholders for picking stroke and fill paint opacity and
  `popupWindowBlocked`; update `saveFromBrowser`
- **Configuration**: Configure text font and stroke; add StackBlur to
  canvg by default; allow path config for canvg and jspdf (not needed
  for built-in)
- **Security**: Link placeholder defaults to `https`
- **APIs**: Current zoom level; `addSvgElementFromJson` capabilities;
  ability to set SVG drawings without adding to the undo stack; add
  to methods passed to extensions; allow `addSvgElementFromJson` to
  accept non-SVG namespaces as well with explicit `namespace` property;
  add `extensions_added` event; make `setStrings` public on editor for
  late setting; add `message` event to relay messages; return promise
  for `rasterExport`, `exportPDF`, and `embedImage`; add
  `pointsAdded` canvas event; supply `importLocale` to `init`,
  `langReady` and `addLangData` for extension locale loading; allow
  avoiding "name" in extension export
- **Optimizations**: `getBBox` and loading time; remove unused scripts,
  compress images; for `setSvgString`, return `false` earlier if element
  content is not SVG; avoid rewriting `points` attribute for free-hand path
- **Error handling**: Extension loading error logging and recovery
- **Keys/Commands**: Clipboard works across tabs and windows, "Escape"
  to work with hotkeys within text boxes such as source textarea;
  allow 'a' also with meta key to select all; global escape key listener
  to clear the selection
- **Publishing options**: npm, `packagist.org`; `unpkg.com` and
  `raw.githack.com`; for Github.io, add `latest` directory for hosting
  latest release
- **Cross-origin option**: New and auto-generated `xdomain-svg-editor-es.html`
  and `xdomain-svg-editor.html` files are now available which possess default
  config which allows cross-origin use. It saves in a storage namespace
  distinct from the main editor so as to avoid potential data corruption
  or unauthorized retrieval of data created in the main editor by other
  domains.
- **Modular JavaScript**: ES6 modules distribution format and module-based
  `svg-editor-es.html` HTML (for modern browsers only; otherwise, use one of
  the UMD distributions or `svg-editor.html` file) and also separate versions
  for `xdomain-svg-editor-es.html`; make SpinButton plugin independent of
  svgedit (though still currently bundled)
- **JavaScript-only distribution files** - While SVG-Edit's JavaScript
  currently very much presumes a certain HTML structure, for anyone who
  wishes to copy and possibly modify that HTML file outside of the editor
  folder (bearing in mind that certain paths may need to be adjusted),
  they may reference the JavaScript builds within `dist`. There is an
  ES6 Module distribution (for modern browsers only) as well as a UMD
  distribution. In the `package.json` file, for the sake of minimizing
  config needed by any bundlers of SVG-Edit, the ES distribution is
  pointed to by the `module` property and the UMD distribution is pointed
  to by `main`.
- **Modular stylesheets** - Add `stylesheets` config for indicating custom
  stylesheets to load in parallel with any built-in; use `"@default"`
  within this array of stylesheet paths to indicate inclusion of default
  stylesheets (or omit `"@default"` to exclude them).
- **Process improvements**: Sort SVG attributes alphabetically

## Refactoring/Testing

- **ES6 Modules**: Use in source, including jQuery plugins, extensions,
  locales, tests; see "Breaking Changes"
- **Updates**: QUnit and jQuery version within imagelib extension; include
  Mathjax local copy
- **Other code refactoring**: `HistoryRecordingService`, `Command` base class,
  migration away from svgcanvas to separate files (e.g., `layer.js`); various
  clean-up, readability, simplification, and consistency changes; avoid
  inline listeners and styles; more ES5/ES6 usage (e.g., `class`,
  `includes`, destructuring, object shorthand, arrow functions), prefer
  `const` and then `let` and place closer to used block, add favicons;
  clearer and more camelCase variable names; throw error objects instead
  of strings; allow Promises; add polyfills for Babel and
  `ChildNode`/`ParentNode`; use new Event constructors
- **Linting**: Move to ESLint, using a derivative of the "standard" convention;
  80 char. lines; use LGTM
- **Testing**: Add skeleton support for UI and accessibility testing with
  TestCafe (along with ESLint plugin/rules for it); add a draw test file;
  separate JavaScript files out of HTML; use static server; fix timing of
  `all_tests.html` for iframe size; comment out unused jQuery SVG
  test while adding test1 and svgutils_performance_test to all tests page;
  fix inadequate mocking in Path test

## Non-code/meta changes

- **License**: Indicate license types and rename files to reflect
  type; rename/add license file name for jgraduate and screencast to reflect
  type (Apache 2.0)
- **npm**: SVG-Edit is now published on npm; add ESLint, uglify, start, and
  test scripts
- **Documentation**: Moved to JSDocs (with Markdown plugin, a custom template
  to support overflow, and an script to check for overly generic types)
  and added documentation for public module methods as well as adding mutual
  linking between JSDocs tutorial docs; included online at <https://svg-edit.github.io/svgedit/releases/svg-edit-3.0.0/docs/jsdoc/>
  (or for the latest release, use
  <https://svg-edit.github.io/svgedit/releases/latest/docs/jsdoc/>);
  update Release notes and add Contributing file, integrate Github wiki pages
  into docs, and copy over old docs. Begin "Editor" doc file to help general
  users
- **Demos**: Add svgcanvas demo (in using `svgcanvas.js` without an editor)
- **i18n**: Locales now use ES6 Modules and extension locales are now
  contained in separate files relative to the extensions directory (for
  the sake of true modularity); see "Breaking Changes"