Considering turning Svelte-Embla as an offically supported embla package

[Yofou]

The Idea

as you may know, a while back I mentioned I had made a Embla adapters for Svelte earlier this year called svelte-embla in #307 , after some significant life changes between the period of when I posted that issue and now I've been quite busy adjusting to them. however now I have finally settled down and ready to commit some time to discuss about turning my svelte adapter for embla into an official supported package.

things to note, this is a really small adapter, the adapter it's self fit's nicely in one file here, which should making the task if so to happen of moving it to the official repository a breeze.

feel free to go explore the package and tell me what you think, maybe there should be some improvement that need to be made before moving it over

[davidjerleke]

Hi @Yofou,

Thank you for your work so far. It's highly appreciated 👍. Your Svelte wrapper is well aligned with the Embla Carousel vision: A bare bones library that does the heavy lifting and enables users to extend it to their liking with its highly flexible API. I'm going to suggest a few additions and small adjustments that I hope will make sense to you:

• Only dispatch an init event and let users hook on to other Embla events by exposing the carousel API. The main advantage with this approach is that we don't need to re-define Embla events in the Svelte wrapper. This won't cause the Svelte wrapper to get out of sync with the core package if events were to change in the core package in the future (code).
• The action update method should re-initialize the carousel if options or plugins were to change. But, the update method should only re-initialize Embla if options or plugins actually change, and not on every reassignment (code).

Here's a simple CodeSandbox that demonstrates the changes above.

🚨 Note!

I didn't have much time to create my CodeSandbox example so it's not using TypeScript. But the Svelte package will be written in TypeScript once we agree on its contents.

Let me know what you think and thank you for your time!

Cheers,
David

[Yofou]

Hi @davidjerleke

I really appreciate you checkout out the library and looking for things to improves, It looks like things are getting off at a great start 😄 .

"Only dispatch an init event"

so let's start off with your first point about just dispatching init, I got alot to say about this so prepare yourself haha, I agree I think we should try solving the events from ever going out of sync as much as possible from version to version, however I think we should maybe look at what we can add/change in the base Emba-carousel code to help with keeping the wrapper(s) in sync before considering removing features from the wrapper. so I spent my sunday morning and bit of my afternoon (I got really invested haha) and I came up with this plan and I got a working prototype here. so if you flick through you'll notice there's a emblaEventType which is the bread and butter of this idea. which we can iterate and dispatch automatically and... I beilive this idea can fit into the internal Embla-carousel lib quite nicely here.

so rather than having

export type EmblaEventType =
  | 'init'
  | 'pointerDown'
  | 'pointerUp'
  | 'scroll'
  | 'select'
  | 'settle'
  | 'destroy'
  | 'reInit'
  | 'resize'

we actually have two exports like this

export const emblaEventType = [
	"init",
	"pointerDown",
	"pointerUp",
	"scroll",
	"select",
	"settle",
	"destroy",
	"reInit",
	"resize",
] as const;

export type EmblaEventType = typeof emblaEventType[number]  // this gets the union literal types as before (ie  "init" | "pointerDown" | "pointerUp" | ...)

this keeps the code dry & type safe and let's me (or anyone else making an embla wrapper in the future) have the option of automatically dispatching events while not having to worry about maintaining there own derived list.

I think this creates a best of both worlds, let me know what you think.

also another bullet point to make is if you go to Svelte-Embla docs right now you'll notice there's a svelte writable-store (which if you don't know is a built-in supported observable in svelte it'self) that you can pass in currently to cut out the middle man of grabbing the embla client through the init event, Which I believe is alot nicer & the more "sveltier" way of going around it, but I still believe we should have the init event details pass the client though to not hinder anyone's options on how they would like to grab the embla client.

"The action update method should re-initialize the carousel if options or plugins were to change"

100%, that is a really good catch which I have already added to the proposal branch on my repo with the typescript types added for you 👍🏻

📔 Note

In that proposal branch I also experimented with the idea of also automatically telling svelte (LSP) to add type completion for the embla events on the element, which went some-what successful, there is no way for me to inform typescript to only give the type completion if the embla action has been added to the element it'self which means those embla events alway popup & I can't seem to get jsdocs comments to show up to inform the user either to add the action, which is little bit of a bummer. but it is very convenient to have these type annotations pop up while developing (futher more supporting why I think we should keep them).

anyway, I hope you have a great day & that I haven't given you to much eye strain from long comment. 👋

[davidjerleke]

Hi @Yofou,

With all there is to do with the upcoming v7, the time to response is not quite what I would like it to be. Thank you for your patience 🙂.

Events

however I think we should maybe look at what we can add/change in the base Emba-carousel code to help with keeping the wrapper(s) in sync before considering removing features from the wrapper.

I don't agree with this. Mainly because if we were to change the Embla core for every framework wrapper that was introduced, it will make a mess out of the core in the long run. I think the main goal with a framework wrapper should be to get rid of the main friction using the library together with a framework. It shouldn't add duplicate layers of logic and a middle hand, but rather act as a bridge and expose the native library API as is. There are important benefits with this approach:

• No need for duplicate logic which will prevent the wrapper and library to get out of sync. You mentioned that you had busy a period in your life and I have it too sometimes. We want to avoid doing unnecessary work.

• Types will work as expected because Embla, its wrappers and plugins are all written in TypeScript. As you mentioned in your response it wasn't straightforward to add event types to the element.

You can easily use the Embla API in the CodeSandbox I provided and adding event hooks will work great with autocomplete:

A limitation with adding a duplicate event layer to the Svelte wrapper is that Embla allows for adding multiple event listeners that listens to the same event:

// Add event listeners individually
embla.on('select', togglePrevNextButtonsActive)
embla.on('select', toggleDotButtonActive)

And it also gives you full control over removing events individually:

embla.off('select', toggleDotButtonActive) // Remove event listener toggleDotButtonActive, but togglePrevNextButtonsActive will remain active

This feature would be lost when creating the Svelte event layer.

It's important that the Embla events remain a type definition and not an actual JavaScript object because plugins will extend the event list type when a TypeScript user installs and uses plugins. Adding events to the event object every time a plugin is initialized and removing them when the plugin is destroyed will get messy.

Additionally, your suggestion would result in TypeScript emitting actual code, an object literal for the events, which will increase the bundle size. People stare themselves blind on bundle sizes these days so I have to weigh that in every time I make changes to the core.

The embla-carousel-react wrapper has been around for some years and it exposes the raw Embla API. So speaking from experience, it has barely needed any maintenance really. It just works. And I just finished the embla-carousel-vue wrapper the other day which also successfully exposes the raw Embla API. Both these wrappers will automatically adapt to any changes made to the Embla API without the need of manual labour.

Store

also another bullet point to make is if you go to Svelte-Embla docs right now you'll notice there's a svelte writable-store (which if you don't know is a built-in supported observable in svelte it'self) that you can pass in currently to cut out the middle man of grabbing the embla client through the init event, Which I believe is alot nicer & the more "sveltier" way of going around it, but I still believe we should have the init event details pass the client though to not hinder anyone's options on how they would like to grab the embla client.

I'm not very experienced with Svelte. So I dived into this MDN guide hoping to understand stores better:

Moreover, when your app becomes complicated and your component hierarchy gets complex, it might become too difficult for components to relay data between each other. In that case, moving to a global data store might be a good option. If you've already worked with Redux or Vuex, then you'll be familiar with how this kind of store works. Svelte stores offer similar features for state management.

From my understanding, a store is basically a state management feature in Svelte. For a carousel component, it seems a bit overkill because in most cases the carousel instance will be local to the component and not used across components. At least it has been for me when I think about how I use it. Having said that, I understand that there might be cases where one would want the carousel instance to be accessible elsewhere.

But as I said I'm not very experienced with Svelte stores so I don't know the implications of a store, like how it affects performance and so on. If a user still has the possibility to assign their carousel variable with event.detail even when using the store, I guess it could be nice to offer users both choices. So I think your suggestion makes sense if this is the case.

Thank you for your time and let me know what you think.

Cheers,
David

[davidjerleke]

Hi @Yofou,

Not to stress you or anything but have you had the chance to read my response yet? I’m close to a stable v7 release so this will soon be the only thing left to do.

Best,
David

[davidjerleke]

Hi @Yofou,

Maybe you're having your vacation or maybe you're very busy. I couldn't wait for the v7 release any longer so I created a simple Svelte wrapper that was published with the release. I'm here if you want to continue this conversation and still waiting for a response on my last comment. No need to hurry, just wanted to be clear.

Best,
David

[ecker00]

The store approach would make this much more usable. 👍 I tried both the original package vs the one integrated now, and would not use this one in it's current state. I got both of them working, but the current approach throws TypeScript warnings when you put <div on:init={…}>, as div's don't have this signature.

Also the store approach would making porting the documentation over much easier. Currently there is very little usable documentation and took a lot of experimentation to get it working.

[ecker00]

Don't need to do anything more than it does today, just how the basic functions are exposed would make it more friendly to integrate and interact with.

There are multiple ways to approach it, and maybe a good example would be the Svelte-Embla that already exist:
https://svelte-embla.vercel.app/guides/options

Another way would be something like this (I'm just writing from top of my head):

<script>
  import Embla, { createEmbla } from 'embla';
  const embla = createEmbla({ /* options */ });
  
  // Now possible to interact with the API like:
  setTimeout(() => {
    embla.scrollNext();
  }, 1000);
</script>
<div>
  <Embla {embla}>
    <!-- Content -->
  </Embla>
</div>

[davidjerleke]

Seems like I'm misunderstanding you @ecker00. The current way of accessing the Embla API is like so:

<script lang="ts">
  import emblaCarouselSvelte, { EmblaCarouselType } from 'embla-carousel-svelte'

  let emblaApi: EmblaCarouselType

  const onInit = (event) => (emblaApi = event.detail) // Assign Embla API when ready
  const scrollPrev = () => emblaApi?.scrollPrev() // Make use of the Embla API
  const scrollNext = () => emblaApi?.scrollNext() // Make use of the Embla API
</script>

<div class="embla" use:emblaCarouselSvelte on:init={onInit}>
  <div class="embla__container">
    <div class="embla__slide">Slide 1</div>
    <div class="embla__slide">Slide 2</div>
    <div class="embla__slide">Slide 3</div>
  </div>
</div>

<button on:click={scrollPrev}>Scroll prev</button>
<button on:click={scrollNext}>Scroll next</button>

And Svelte-Embla like so:

<script lang="ts">
  import embla from "svelte-embla"
  import type { EmblaCarouselType } from "embla-carousel";
  import { writable } from "svelte/store";

  const emblaApi = writable<EmblaCarouselType>();
  const scrollPrev = () => $emblaApi?.scrollPrev(); // Make use of the Embla API
  const scrollNext = () => $emblaApi?.scrollNext(); // Make use of the Embla API
</script>

<div class="embla" use:embla={{ store: emblaApi }}> <!-- Assign Embla API when ready -->
  <div class="embla__container">
    <div class="embla__slide">Slide 1</div>
    <div class="embla__slide">Slide 2</div>
    <div class="embla__slide">Slide 3</div>
  </div>
</div>

<button on:click={scrollPrev}>Scroll prev</button>
<button on:click={scrollNext}>Scroll next</button>

What bothers you here is the assignment with the onInit event? Or am I missing other things you have in mind that aren't present in these examples (like what stores can do or similar)? I'm just looking to understand you better.

Thanks for your time.

Best,
David

[ecker00]

Yeah, you hit the nail on the head there. 👍 Sorry for making it a round about conversation. So many ways to achieve similar results, but a setup that's fully type safe and documented to work is plenty. Custom component was just an idea to encapsulate some of the default setup steps, not important.

[davidjerleke]

Got it working in the end (just guessing the documentation), but was the typing issue which you do suggest a solution to, but saying HTML props have oninit is kind of just a band-aid.

@ecker00 the problem with the types for the init event was just me missing to include it in ActionReturn<Parameter, Attribute>. This pull request enables the tooling to pickup the correct types. So the following band aid in the d.ts file will no longer be necessary:

declare namespace svelte.JSX {
    interface HTMLProps<T> {
        oninit?: (e: CustomEvent) => void;
    }
}

Best,
David

[davidjerleke]

I've just released the bug fix with v8.0.0-rc02.