Move to Svelte 4 style custom element API, support prop type coercion

[patricknelson]

trafficstars

Svelte 4.0.0 has been released: https://svelte.dev/blog/svelte-4.

Work can now be done to align svelte-retag's API to the new format in Svelte 4's <svelte:options customElement={…} /> (documented here). For example (copied from https://github.com/sveltejs/svelte/issues/8681#issuecomment-1583128649):

// String syntax:
svelteRetag(component, 'example-element');

// Object syntax:
svelteRetag(component, {
	tag: 'example-element',
	shadow: 'none',
	props: {
		greetPerson: { reflect: true, attribute: 'greet-person' },
	},
});

Propose passing in the component as the first required parameter and then allow for an easy direct copy/paste of the Svelte 4 style customElement options as a second parameter (with the same baseline requirements). This will be supported features only.

Important: Rolling into v2 milestone., since this syntax should replace the old component definition syntax. Doing so should make the API of svelte-retag overall easier to comprehend for others (a huge plus for a library). Plus it’s likely easier to implement/maintain.

Supported features

Due to the complexity of the API (at time of writing) it may be worthwhile to outline exactly what we want as “must have” vs. “nice to have” if possible in this ticket. Otherwise, implement the “must haves” and delegate the “nice to have” features to a separate issue for now.

Must have

• [ ] tag for tag name
• [ ] shadow for use of shadow DOM or not (must default to true, methinks)
• [ ] props where each key defines the property (e.g. greetName) with support for
  • [ ] attribute defines alternative attribute name
  • [ ] type to coerce to a particular type (instead of always being type String (per HTML attribute spec)

Nice to have

• [ ] props where each key defines the property (e.g. greetName) with support for
  • [ ] reflect to perform the inverse of the current reactive forwarding, i.e. watch for changes in the component and forward that to the attribute in the DOM. See #43
• [ ] extend add ability to pass main class constructor to provided callback so it can extend and then return the class to instantiate for the main customElements.define() call. See #42

[patricknelson]

Added explicit set of desired features in order of priority (must have vs. nice to have) to help explicitly call out desire to perform type coercion (as requested in #26 which is a dupe of this).

[patricknelson]

Quick note: Clarified that this will be for supported features only, i.e. either features that already exist or ones being added specifically in this ticket (e.g. custom attribute names and attribute type coercion).

This is worth calling out so that the expectation isn't set that we'll always 100% support all features of <svelte:options customElement={…} /> per se, but rather have an API that is very similar in order to support migration. This is not intended to be a drop-in but instead an alternative with the ability to enhance with additional features, where feasible. 🙂