Skip to content

Commit 1d82146

Browse files
baseballyamabaseballyama
authored
chore: update README (#19)
1 parent f4f5ee1 commit 1d82146

File tree

1 file changed

+102
-21
lines changed

1 file changed

+102
-21
lines changed

‎README.md‎

Lines changed: 102 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -4,27 +4,27 @@
44
[![Build Status](https://github.com/baseballyama/svelte-preprocess-delegate-events/workflows/CI/badge.svg?branch=main)](https://github.com/baseballyama/svelte-preprocess-delegate-events/actions?query=workflow:ci)
55
[![Coverage Status](https://coveralls.io/repos/github/baseballyama/svelte-preprocess-delegate-events/badge.svg?branch=main)](https://coveralls.io/github/baseballyama/svelte-preprocess-delegate-events?branch=main)
66

7-
# You can delegate events by `on:*`🎉
7+
# Delegate events with `on:*` 🎉
88

9-
- 💡 Simple usage
10-
- ⚡️ No performance overhead
11-
- 🔑 No type error with [svelte-check](https://github.com/sveltejs/language-tools/tree/master/packages/svelte-check)
9+
- 💡 Easy to use
10+
- ⚡️ No performance impact
11+
- 🔑 No type errors with [svelte-check](https://github.com/sveltejs/language-tools/tree/master/packages/svelte-check)
1212

13-
## Try this on [Stackblitz](https://stackblitz.com/edit/sveltejs-kit-template-default-rwmhls?file=src%2Froutes%2F%2Bpage.svelte&terminal=dev) 🚀.
13+
## Try it on [Stackblitz](https://stackblitz.com/edit/sveltejs-kit-template-default-rwmhls?file=src%2Froutes%2F%2Bpage.svelte&terminal=dev) 🚀.
1414

15-
# What is it?
15+
# Overview
1616

17-
Since 2019, there is one of popular issue on Svelte GitHub repository which is delegating all events.<br>
17+
Since 2019, one popular issue on the Svelte GitHub repository has been delegating all events.<br>
1818
https://github.com/sveltejs/svelte/issues/2837
1919

20-
The goal of this repository is sovling this issue.
20+
This repository aims to solve this issue.
2121

2222
# Example
2323

2424
**Component.svelte**
2525

2626
```svelte
27-
<!-- You can delegate all events by `on:*` 🎉 -->
27+
<!-- Delegate all events with `on:*` 🎉 -->
2828
<input on:* />
2929
```
3030

@@ -35,7 +35,7 @@ The goal of this repository is sovling this issue.
3535
import Component from './Component.svelte';
3636
</script>
3737
38-
<!-- You can handle events whatever you want -->
38+
<!-- Handle events as desired -->
3939
<Component
4040
on:input="{(e) => console.log(e.target.value)}"
4141
on:blur="{() => console.log('blur')}"
@@ -50,26 +50,26 @@ npm install -D svelte-preprocess-delegate-events
5050

5151
# Usage
5252

53-
After install it, please add this as a Svelte preprocessor.
53+
After installation, add this as a Svelte preprocessor.
5454

5555
```js
5656
// svelte.config.js
5757
import delegateEvents from "svelte-preprocess-delegate-events/preprocess";
5858

5959
const config = {
60-
// Please add this preprocessor at the last of the array.
60+
// Add this preprocessor at the end of the array.
6161
preprocess: [delegateEvents()],
6262
};
6363

6464
export default config;
6565
```
6666

67-
# Use with `svelte-check`
67+
# Integration with svelte-check
6868

69-
If you want to use `svelte-check`, please create `svelte-jsx.d.ts` at project root.
69+
If you want to use `svelte-check`, create `svelte-jsx.d.ts` at the project root and update `[tj]sconfig.json`.
7070

71+
**svelte-jsx.d.ts**
7172
```ts
72-
// svelte-jsx.d.ts
7373
declare namespace svelteHTML {
7474
/**
7575
* base: https://github.com/sveltejs/language-tools/blob/651db67858d18ace44d000d263ac57ed5590ea05/packages/svelte2tsx/svelte-jsx.d.ts#L42
@@ -82,16 +82,97 @@ declare namespace svelteHTML {
8282
}
8383
```
8484

85-
# How it works?
85+
**[tj]sconfig.json**
86+
```diff
87+
{
88+
+ "include": ["./svelte-jsx.d.ts"]
89+
}
90+
```
91+
92+
# How the Preprocessor Works?
93+
94+
This chapter explains how the preprocessor functions. The preprocessor operates differently for Elements and Components.
95+
96+
## Element
8697

98+
Consider the following simple example:
8799

100+
```svelte
101+
<!-- Parant.svelte -->
102+
<script>
103+
import Child from './Child.svelte';
104+
</script>
105+
<Child on:click={() => console.log('clicked!')} />
106+
107+
<!-- Child.svelte -->
108+
<button on:*>Click Me</button>
109+
```
88110

89-
TBD...
111+
Svelte executes events registered in `component.$$.callbacks` when an event is triggered in a child component. In the example above, `component.$$.callbacks` is as follows:
112+
```js
113+
component.$$.callbacks = {
114+
click: () => console.log('clicked!')
115+
}
116+
```
117+
118+
This preprocessor adds a process to listen for events registered in `component.$$.callbacks` for elements with `on:*`. After preprocessing, Child.svelte looks like this:
119+
```svelte
120+
<!-- Child.svelte -->
121+
<script>
122+
import { boundElements, registerDelegatedEvents } from 'svelte-preprocess-delegate-events/runtime';
123+
import { get_current_component } from 'svelte/internal';
124+
let button = boundElements();
125+
const component = get_current_component();
126+
$: registerDelegatedEvents(button.bounds, component, (handler) => handler, {});
127+
</script>
128+
129+
<button bind:this={button.bounds}>Click Me</button>
130+
```
131+
NOTE: The reason for binding `<button>` to `button.bounds` instead of binding it to the `button` variable is to support cases where multiple elements exist, such as `<button>` in a `{#each}` block.
132+
133+
In this way, only events that are being listened to by the parent component are listened to, thus providing a mechanism with no performance overhead.
134+
135+
## Component
136+
137+
Component uses a different mechanism than Element. Consider the following simple example:
138+
```svelte
139+
<!-- Parant.svelte -->
140+
<script>
141+
import Child from './Child.svelte';
142+
</script>
143+
<Child on:click={() => console.log('clicked!')} />
144+
145+
<!-- Child.svelte -->
146+
<script>
147+
import GrandChild from './GrandChild.svelte';
148+
</script>
149+
<GrandChild on:* />
150+
151+
<!-- GrandChild.svelte -->
152+
<button on:click on:blur>Click Me</button>
153+
```
154+
155+
If you are using `on:*` in `Child.svelte`, you need to forward all events from `GrandChild` to `Parent`. However, `Child` does not know what events are coming from `GrandChild`, so you need to do something. Specifically, when `GrandChild` triggers an event, it will refer to `component.$$.callbacks` to run its event handlers. By proxying `component.$$.callbacks`, you will know which events have been forwarded. Forwarded events can be communicated to the parent component so that the `Parent` component can handle the event.
156+
157+
After preprocessing, it looks like this:
158+
```svelte
159+
<!-- Child.svelte -->
160+
<script>
161+
import { boundComponents, proxyCallbacks } from 'svelte-preprocess-delegate-events/runtime';
162+
import { get_current_component } from 'svelte/internal';
163+
import GrandChild from './GrandChild.svelte';
164+
165+
const GrandChild = boundComponents();
166+
const component = get_current_component();
167+
$: proxyCallbacks(component, GrandChild.bounds, false);
168+
</script>
169+
170+
<GrandChild bind:this={GrandChild.bounds} />
171+
```
90172

91173
# Note
92174

93-
`on:*` doesn't support event handling because I couldn't find useful usecase.
94-
If you have a useful usecase, please create a new issue.
175+
`on:*` does not support specifying event handlers directly because a useful use case could not be found. If you have a useful use case, please create a new issue.
95176

96177
```svelte
97178
<script>
@@ -101,9 +182,9 @@ If you have a useful usecase, please create a new issue.
101182
}
102183
</script>
103184
104-
<!-- Specifying event handler does not support -->
185+
<!-- Specifying event handler directly is not supported -->
105186
<input on:*="{handleEvent}" />
106187
107-
<!-- Specifying event handler does not support -->
188+
<!-- Specifying event handler directly is not supported -->
108189
<Component on:*="{handleEvent}" />
109190
```

0 commit comments

Comments
 (0)