1 | # svelte-fragment-component
|
2 |
|
3 | > A [svelte](https:/svelte.dev) component that renders its children with lifecycle hooks.
|
4 |
|
5 | [![License](https://badgen.net/npm/license/svelte-fragment-component)](https://github.com/kenoxa/svelte-fragment-component/blob/main/LICENSE)
|
6 | [![Latest Release](https://badgen.net/npm/v/svelte-fragment-component)](https://www.npmjs.com/package/svelte-fragment-component)
|
7 | [![View changelog](https://badgen.net/badge/%E2%80%8B/Explore%20Changelog/green?icon=awesome)](https://changelogs.xyz/svelte-fragment-component)
|
8 |
|
9 | [![CI](https://github.com/kenoxa/svelte-fragment-component/workflows/CI/badge.svg)](https://github.com/kenoxa/svelte-fragment-component/actions?query=branch%3Amain+workflow%3ACI)
|
10 | [![Coverage Status](https://badgen.net/coveralls/c/github/kenoxa/svelte-fragment-component/main)](https://coveralls.io/github/kenoxa/svelte-fragment-component?branch=main)
|
11 | [![PRs Welcome](https://badgen.net/badge/PRs/welcome/purple)](http://makeapullrequest.com)
|
12 | [![Conventional Commits](https://badgen.net/badge/Conventional%20Commits/1.0.0/cyan)](https://conventionalcommits.org)
|
13 |
|
14 | ## What?
|
15 |
|
16 | Declarative version of [Svelte](https://svelte.dev) component inspired by [reach-ui/component-component](https://reacttraining.com/reach-ui/component-component/).
|
17 |
|
18 | ## Why?
|
19 |
|
20 | Because sometimes (within tests) you want a lifecycle or some state but don't want to create a new component.
|
21 |
|
22 | _This is most likely only useful for libraries like [svelte-jsx](https://www.npmjs.com/package/svelte-jsx) or [svelte-htm](https://www.npmjs.com/package/svelte-htm)._
|
23 |
|
24 | ## Installation
|
25 |
|
26 | ```sh
|
27 | npm install svelte-fragment-component
|
28 | ```
|
29 |
|
30 | And then import it:
|
31 |
|
32 | ```js
|
33 | // using es modules
|
34 | import Fragment from 'svelte-fragment-component'
|
35 |
|
36 | // common.js
|
37 | const Fragment = require('svelte-fragment-component')
|
38 | ```
|
39 |
|
40 | Or use script tags and globals ([UNPKG](https://unpkg.com/svelte-fragment-component/) | [jsDelivr](https://cdn.jsdelivr.net/npm/svelte-fragment-component/)).
|
41 |
|
42 | ```html
|
43 | <!-- UNPKG -->
|
44 | <script src="https://unpkg.com/svelte-fragment-component"></script>
|
45 |
|
46 | <!-- jsDelivr -->
|
47 | <script src="https://cdn.jsdelivr.net/npm/svelte-fragment-component"></script>
|
48 |
|
49 | <script>
|
50 | <!-- And then grab it off the global like so: -->
|
51 | const Fragment = svelteFragment
|
52 | </script>
|
53 | ```
|
54 |
|
55 | Hotlinking from unpkg: _(no build tool needed!)_
|
56 |
|
57 | ```js
|
58 | import Fragment from 'https://unpkg.com/svelte-fragment-component?module'
|
59 | ```
|
60 |
|
61 | ## Usage
|
62 |
|
63 | > The examples below are using [svelte-jsx](https://www.npmjs.com/package/svelte-jsx) for the jsx syntax support.
|
64 |
|
65 | ```js
|
66 | import Fragment from 'svelte-fragment-component'
|
67 |
|
68 | const Lifecycle = (
|
69 | <Fragment
|
70 | onCreate={() => {}}
|
71 | onMount={() => {}}
|
72 | beforeUpdate={() => {}}
|
73 | afterUpdate={() => {}}
|
74 | onDestroy={() => {}}
|
75 | >
|
76 | some content
|
77 | </Fragment>
|
78 | )
|
79 | ```
|
80 |
|
81 | This allows to simplify testing of [context API](https://svelte.dev/docs#setContext):
|
82 |
|
83 | ```js
|
84 | import Fragment from 'svelte-fragment-component'
|
85 | import { setContext } from 'svelte'
|
86 |
|
87 | const Lifecycle = (
|
88 | <Fragment
|
89 | onCreate={() => {
|
90 | setContext('some context key', theValue)
|
91 | }}
|
92 | >
|
93 | children can now access this context value
|
94 | </Fragment>
|
95 | )
|
96 |
|
97 | // or using the context property
|
98 | const Lifecycle = (
|
99 | <Fragment context={{ 'some context key': theValue }}>
|
100 | children can now access this context value
|
101 | </Fragment>
|
102 | )
|
103 | ```
|
104 |
|
105 | ## API
|
106 |
|
107 | The component renders only the default slot children.
|
108 |
|
109 | ### Properties
|
110 |
|
111 | > All properties are optional.
|
112 |
|
113 | - `context`: an key-value object where each pair is passed to [setContext](https://svelte.dev/docs#setContext)
|
114 |
|
115 | Except for `onCreate` these functions are passed to their corresponding svelte lifecycle method and have the same call signature `({ props }): void` where `props` are the `$$restProps`:
|
116 |
|
117 | - `onCreate`: called during component initialization
|
118 | - [onMount](https://svelte.dev/docs#onMount)
|
119 | - [beforeUpdate](https://svelte.dev/docs#beforeUpdate)
|
120 | - [afterUpdate](https://svelte.dev/docs#afterUpdate)
|
121 | - [onDestroy](https://svelte.dev/docs#onDestroy)
|
122 |
|
123 | ## Related Projects
|
124 |
|
125 | - [svelte-jsx] - write svelte components using [jsx]
|
126 | - [svelte-htm] - [**H**yperscript **T**agged **M**arkup](https://www.npmjs.com/package/htm) for svelte; a [jsx]-like [syntax](https://www.npmjs.com/package/htm#syntax-like-jsx-but-also-lit) using [Tagged Templates]
|
127 | - [@testing-library/svelte](https://testing-library.com/docs/svelte-testing-library/intro) - helps to test UI components in a user-centric way
|
128 |
|
129 | ## Support
|
130 |
|
131 | This project is free and open-source, so if you think this project can help you or anyone else, you may [star it on GitHub](https://github.com/kenoxa/svelte-fragment-component). Feel free to [open an issue](https://github.com/kenoxa/svelte-fragment-component/issues) if you have any idea, question, or you've found a bug.
|
132 |
|
133 | ## Contribute
|
134 |
|
135 | Thanks for being willing to contribute!
|
136 |
|
137 | **Working on your first Pull Request?** You can learn how from this _free_ series [How to Contribute to an Open Source Project on GitHub](https://egghead.io/series/how-to-contribute-to-an-open-source-project-on-github)
|
138 |
|
139 | We are following the [Conventional Commits](https://www.conventionalcommits.org) convention.
|
140 |
|
141 | ### Develop
|
142 |
|
143 | - `npm test`: Run test suite
|
144 | - `npm run build`: Generate bundles
|
145 | - `npm run lint`: Lints code
|
146 |
|
147 | ## NPM Statistics
|
148 |
|
149 | [![NPM](https://nodei.co/npm/svelte-fragment-component.png)](https://nodei.co/npm/svelte-fragment-component/)
|
150 |
|
151 | ## License
|
152 |
|
153 | `svelte-fragment-component` is open source software [licensed as MIT](https://github.com/kenoxa/svelte-fragment-component/blob/main/LICENSE).
|
154 |
|
155 | [tagged templates]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#Tagged_templates
|
156 | [jsx]: https://reactjs.org/docs/introducing-jsx.html
|
157 | [svelte-jsx]: https://www.npmjs.com/package/svelte-jsx
|
158 | [svelte-hyperscript]: https://www.npmjs.com/package/svelte-hyperscript
|
159 | [svelte-htm]: https://www.npmjs.com/package/svelte-htm
|