svg.rx.js v0.0.4

svg.rx.js

What is it?

svg.rx.js binds RxJS together with SVG graphics.

It currently uses svg.js for dealing with the SVG elements, but this dependency may later be relaxed (so that any such library could be used, or none at all, leaving it an application decision).

With svg.rx.js, user interactions such as touch and mouse events can be modeled as RX.Observables, tremendously simplifying the code concerned.

The intention is that also animations would be modeled to use Rx.Observables, instead of SVG-specific constructs that have a learning curve, and limitations.

The end game is to get a simple programming paradigm for making SVG-only animated, interactive applications that run fast in the browser.

The reasons why this isn't already practical lie within the SVG details. It doesn't seem easy to make a group out of SVG elements that can be dragged and interacted with. We're intending to fix these shortcomings, with the gx object.

tbd. In the mean time (2017-19), Svelte 3 emerged. Looking at integration with it, now.

Design goals

• simplicity of API over feature support
• every documented API must have unit tests
• touch and mouse should not seem very different
• touch first (treat mouse as a useable fallback 2nd class citizen)
• any touch is treated the same (enables multiuser touch on a big tablet/table)
• providing the bare mechanisms needed, instead of trying to cater for a certain kind of application
• value brewity of the code, and maintainability
• provide support for both desktop and touch use cases, equally

• embrace Svelte 3, as a development abstraction and toolchain

Platform scope

Scope of the project is SVG on modern browsers. That probably means no IE9..11 support (we can always add that later). In practice the code gets tested on:

• Latest Safari on macOS
• Latest Chrome on macOS
• Safari on iOS 13 (iPad Pro)
• Chrome on Android 9 (Sony Xperia phone)

If you find platforms where it doesn't work for you, issues and pull requests are the way to go.

Not supported

• Dragging of SVG.Nested and SVG.Text

  • there is special code for these in the svg.draggable.js project but since we don't have demos for these, we are currently not supporting them, at all

• Changing the draggable object's conversion matrix (scaling, rotation and translation) during a drag.

  • this is probably not needed in practical applications

Please send a PR if you need these - and provide a demo or test that proves when the support works.

Following Svelte conventions

The folder structure is derived from Svelte template. In particular:

|- public      # files to host
|   |- index.html
|   |- global.css
|   |- build      # output folder for the bundles
|       |- ...
|- src         # source files

We embrace Svelte as the building technology and wish to remain familiar in structure to developers using it, elsewhere.

Getting started

Install the tools and dependencies (needed for running demos):

$ npm install

Have PhantomJS installed, on the command line:

$ phantomjs --version
2.1.1

⚠️ PhantomJS is discontinued. Change tests to run with Puppeteer.

Demos

• sources
• online - may not be the latest versions

Note: The online demos are currently from an older branch (2015-16); they are not what the source creates. WIP

The demos work both as sample code and as manual tests.

$ npm run dev
...
  Your application is ready~! 🚀

  - Local:      http://0.0.0.0:5000
  - Network:    http://192.168.1.234:5000

────────────────── LOGS ──────────────────

This builds the demos and serves them. Changes to the code will be reflected in the browser, without need of refresh. 😏

Running on a mobile device

Open the mobile device's browser at http://192.168.1.234:5000 (IP mentioned by npm run dev).

This allows you to experiment with the demos.

For setting up remote debugging, see DEV-TIPS/Remote debugging.

Code

• src/svg.rx.js

Note: The code is currently using RxJS 5.

⚠️ RxJS is now at 6.5.3 and 7.0.0-alpha.0. Upgrade to 6.x.

Tests

All claimed features should have tests.

Run the tests:

$ npm test

Alternatively, you can run the tests in a browser:

$ open test/index.html

💔There are no tests at the moment. We'll tranfer the earlier ones to Puppeteer, at some point.

Usage

⚠️WARNING: This section is out-of-date. To be corrected once we have transitioned to Svelte, fully.

You can simply download the svg.rx.js file and place it in your project.

tbd. Make pulling dependencies a separate part. Here just API usage.

HTML

...tbd.

JavaScript API

The library extends SVGElement by:

.rx_draggable()		// () -> observable of observables of {x:int,y:int}

Sample

const outerObs = rect.rx_draggable();
    
outerObs.subscribe( function(dragObs) {
    console.log("Drag started");
    
    dragObs.subscribe( function(o) {       // {x:Int,y:Int}
        rect.move(o.x, o.y);
    },
    null, 	// no error handler
    function () {
        console.log("Drag ended");
	} );
} );

!!: The library does not move (drag) your object automatically. This is intentional and allows other kinds of dragging behaviour (e.g. constraints or circular following) to happen, instead of the usual 1:1 dragging.

Publish

The npm package is published under svg.rx.js@next^1:

^1: Once we reach stability with the new approach (no svg.js, RxJS 6), the @next tag will be omitted.

...

Help requested!!

See:

• TODO.md
• BUGS.md and
• GitHub Issues

for ways to help

References

Other dragging libraries

Presented for code comparisons. Their approach is the normal event capture (no Rx).

• svg.draggable.js
  • has been the basis for our touch event and coordinate translation handling. Thanks, Fuzzy!

Background info

• How to Use npm as a Build Tool - (blog, Dec 2014) by Keith Cirkel
• Phantomjs, Mocha and Chai for functional testing (blog, Aug 2014) by Thomas Clowes