Documentation?

[VanHoutte]

Hi

I'm trying to use your library but some properties are not clear for me what they do.
I did read software-mansion/react-native-svg#374 where some properties are explained but I don't understand them all.

• vbWidth/vbHeight, i know that vb stands for viewbox but not sure how these values are translated to the canvas. I tried to edit them but not sure what to expect
• meetOrSlice: not sure what both options do
• constraints - combine: 'dynamic', // and all other properties here
• constraints - scaleExtent
• constraints - translateExtent

Could you elaborate a bit more on what the above properties do?

Thanks in advance!

[msand]

Regarding the vb{Width,Height} and meetOrSlice they are the default viewbox width and height values, and the preserveAspectRatio value respectively.

zoomable-svg/index.js

Line 212 in 0f756a1

vbRect = { width: vbWidth || width, height: vbHeight || height },

If you want to provide a complete viewBox, then you can give a {left, top, width,height} object to the vbRect property:

zoomable-svg/index.js

Lines 43 to 47 in 0f756a1

	// Let vb-x, vb-y, vb-width, vb-height be the min-x, min-y, width and height values of the viewBox attribute respectively.
	const vbX = vbRect.left || 0;
	const vbY = vbRect.top || 0;
	const vbWidth = vbRect.width;
	const vbHeight = vbRect.height;

To learn how the viewbox preserveAspectRatio attributes affect the appearance I can recommend these:
https://www.sarasoueidan.com/blog/svg-coordinate-systems/
https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/viewBox
https://svgwg.org/svg2-draft/coords.html#ExampleViewBox
https://svgwg.org/svg2-draft/coords.html#ExamplePreserveAspectRatio

Regarding the constraints, e.g. these values:

constrain={{
  scaleExtent: [0.5, 5],
  translateExtent: [[-10, -10], [110, 110]],
}}

Means that the zoom is constrained to 0.5 i.e., half size, and 5 i.e., 5 times larger than original.
And, that one can move 10 units to each direction from the viewBox.

const constraintCombinations = [
  'none', // Demonstrates no constraints
  'dynamic', // Adjusts translate extent according to zoom level and extent (Default and backwards compatible option)
  'static', // Statically translate if scale extent allows zooming beyond a translate extent (same behaviour as d3.zoom)
  'union', // Take the union of the zoom and translate extent
  'intersect', // Take the intersection of zoom and translate extent
];

If the provided viewBox, preserveAspectRatio and constraints in combination with some interaction / touch event makes one of the constraints fail but not the other, then the constraintCombinations property decides how to handle it. None ignores all constraints. dynamic gives the best ux in my experience, it allows moving the object within the natural free space, when zoomed out beyond its viewBox in one dimension. Static forces the viewBox into the top left corner when zooming out beyond either dimension constraint. Union allowing moving as long as at least one constraint doesn't forbid it. Intersection requires that all constraints are satisfied.

Hope this helps! Any help in simplifying this description would be a very useful PR 😄

[VanHoutte]

Just what I wanted, thanks for the information!