[Feat]: Add offset option for fine-tuned slide alignment

[marcusmichaels]

This PR follows on from #1301 and adds a new offset option (default: 0) that shifts all snap positions by a fixed pixel amount. Positive values shift slides in the start direction, negative values shift in the end direction.

All exsting functionality (alignment, containScroll, loop, drag, progress, SSR) remains unchanged. Includes tests for LTR, RTL, and vertical axes.

This addition allows us to fine-tune the placement without impacting the core functionality.

P.S. The majority of lines added are tests, the bore changes are relatively lightweight

• Closes: [Feat]: offset for fine tuned alignment of slides #1301.

[marcusmichaels]

@davidjerleke I've added this PR following on from #1301 – let me know what you think, it's a really helpful addition for our pixel-perfect design-focused team so I think it'll be a positive addition to the project.

[marcusmichaels]

Just wanted to add, since this can already be achieved with a custom align function, e.g. align: (viewSize, snapSize) => (viewSize - snapSize) / 2 + 20 for center with a 20px offset.

The reason I feel a dedicated offset option is worth it, is that it works easily with the existing align presets ("start", "center", "end") without users needing to reimplement any alignment math (and it works well with breakpoints).

The intent is immediately clear to anyone reading the config. But it's your shout anyway.

[davidjerleke]

Just wanted to add, since this can already be achieved with a custom align function, e.g. align: (viewSize, snapSize) => (viewSize - snapSize) / 2 + 20 for center with a 20px offset.

The reason I feel a dedicated offset option is worth it, is that it works easily with the existing align presets ("start", "center", "end") without users needing to reimplement any alignment math (and it works well with breakpoints).

The intent is immediately clear to anyone reading the config. But it's your shout anyway.

@marcusmichaels Thanks a lot for your contribution!

Do you see any advantages to what can be achieved with this offset option compared to the current align function? Can both accomplish the same outcomes, or is one approach more flexible/limiting than the other?

[marcusmichaels]

Hey @davidjerleke, thanks for looking at this. From my personal experience, one of the main benefits would have been discoverability around alignment options. I didn't initially realise the align options also took a function until I traced through the types.

For more real-world context, I ended up building a helper function using the current alignment options called alignWithOffset:

options={{
  loop: true,
  align: alignWithOffset("start", 70),
}}

This does a couple of things, it does the maths to calculate where "start" would be, and then nudges it over 70px. With the offset merged in, it would save on the boilerplate maths, and it's more composable against the existing alignment options:

options={{
  loop: true,
  align:  "start",
  offset: 70
}}

I kind of feel like align is about where a slide sits relative to the viewport, and offset is the fine-grained detail to get it sitting in a pixel perfect position. Keeping them separate means we don't have to drop out of the string presets to do something simple, and when offset is 0 (the default) nothing changes.