Skip to content

Commit

Permalink
Issue #34: Stubbing out API and documentation for enhancement of "att…
Browse files Browse the repository at this point in the history 
…ributes" option, allowing ability to forward all attributes in a v1 compatible fashion.
  • Loading branch information
@patricknelson
patricknelson committed Dec 5, 2023
1 parent a7400fa commit 5987e0b
Show file tree
Hide file tree
Showing 2 changed files with 26 additions and 15 deletions.
18 changes: 9 additions & 9 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,7 @@ svelteRetag({
tagname: 'hello-world',

// Optional:
attributes: ['greetperson'], // Changes to these attributes will be reactively forwarded to your component
attributes: true, // Forward all attributes to your component, or set to explicit list of attributes, e.g. ['greetperson'] or leave empty
shadow: false, // Use the light DOM
href: '/your/stylesheet.css', // Only necessary if shadow is true
});
Expand All @@ -100,6 +100,7 @@ the [Lit-style naming convention](https://lit.dev/docs/components/properties/#ob
on your component would be automatically made available as `greetperson` on your custom element.

```html

<hello-world greetperson="Cris"></hello-world>
```

Expand All @@ -108,13 +109,13 @@ the [Hello World demo](https://github.com/patricknelson/svelte-retag/tree/main/d

### Options 🛠

| Option | Default | Description |
|--------------|:------------:|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `component` | _(required)_ | The constructor for your Svelte component (from `import`) |
| `tagname` | _(required)_ | The custom element tag name to use ([must contain a dash](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements)) |
| `attributes` | `[]` | Optional. List of attributes to reactively forward to your component (does not reflect changes inside the component). <br><br> **Important:** Attributes must be the lowercase version of your Svelte component props ([similar to Lit](https://lit.dev/docs/components/properties/#observed-attributes)). |
| `shadow` | `false` | Optional. Indicates if this component should use shadow DOM. <br/><br/> **Note:** Only basic support for shadow DOM is currently provided. See https://github.com/patricknelson/svelte-retag/issues/6. |
| `href` | `''` | Optional. URL to your stylesheet. Allows you to ensure your styles are included in the shadow DOM. This option is only useful when `shadow` is set to `true`. |
| Option | Default | Description |
|--------------|:------------:|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `component` | _(required)_ | The constructor for your Svelte component (from `import`) |
| `tagname` | _(required)_ | The custom element tag name to use ([must contain a dash](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements)) |
| `attributes` | `[]` | `Array` (legacy): Explicit list of attributes to reactively forward to your component. Attributes must be the lowercase version of your Svelte component props ([similar to Lit](https://lit.dev/docs/components/properties/#observed-attributes)). <br><br> `Boolean` (recommended): If set to `true`, will automatically forward all attributes to your component props. If `false`, will not forward anything. <br><br> **Note:** In v2, this option will be removed and all attributes will be forwarded by default (for consistency with Svelte 4's custom elements). |
| `shadow` | `false` | Optional. Indicates if this component should use shadow DOM. <br/><br/> **Note:** Only basic support for shadow DOM is currently provided. See https://github.com/patricknelson/svelte-retag/issues/6. |
| `href` | `''` | Optional. URL to your stylesheet. Allows you to ensure your styles are included in the shadow DOM. This option is only useful when `shadow` is set to `true`. |

**Note:** For portability, `svelte-retag`'s API is fully backward compatible
with [`svelte-tag@^1.0.0`](https://github.com/crisward/svelte-tag).
Expand Down Expand Up @@ -158,7 +159,6 @@ See the **[milestones page](https://github.com/patricknelson/svelte-retag/milest
versions. Please be aware that until the version is officially released, the features slated for a particular version
are subject to change!


## Support & Contribution

**Features:** The API for this package is intentionally minimal and features that are outside of the scope of the core
Expand Down
23 changes: 17 additions & 6 deletions index.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -50,11 +50,11 @@ function renderElements(timestamp) {
*
* @param {object} opts Custom element options
*
* @param {any} opts.component Svelte component instance to incorporate into your custom element.
* @param {string} opts.tagname Name of the custom element tag you'd like to define.
* @param {string[]?} opts.attributes Optional array of attributes that should be reactively forwarded to the component when modified.
* @param {boolean?} opts.shadow Indicates if we should build the component in the shadow root instead of in the regular ("light") DOM.
* @param {string?} opts.href URL to the CSS stylesheet to incorporate into the shadow DOM (if enabled).
* @param {any} opts.component Svelte component instance to incorporate into your custom element.
* @param {string} opts.tagname Name of the custom element tag you'd like to define.
* @param {string[]|boolean|undefined} opts.attributes Optional array of attributes that should be reactively forwarded to the component when modified. Set to true to automatically watch all attributes.
* @param {boolean?} opts.shadow Indicates if we should build the component in the shadow root instead of in the regular ("light") DOM.
* @param {string?} opts.href URL to the CSS stylesheet to incorporate into the shadow DOM (if enabled).
*
* Experimental:
* @param {boolean?} opts.hydratable Light DOM slot hydration (specific to svelte-retag): Enables pre-rendering of the
Expand Down Expand Up @@ -133,7 +133,12 @@ export default function svelteRetag(opts) {
* @returns string[]
*/
static get observedAttributes() {
return opts.attributes || [];
if (Array.isArray(opts.attributes)) {
// User defined an explicit list or nothing at all.
return opts.attributes;
} else {
return [];
}
}

/**
Expand Down Expand Up @@ -473,6 +478,12 @@ export default function svelteRetag(opts) {
// in the shadow DOM.
this.componentInstance = new opts.component({ target: this._root, props: props, context });

if (opts.attributes === true) {
// TODO: ISSUE-34: Check to see if this.propMap contains entries and, if so, setup the mutation observer ensuring
// that 'attributefilter' is passed to .observe().
}


this._debug('renderSvelteComponent(): completed');
}

Expand Down

0 comments on commit 5987e0b

Please sign in to comment.