You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: NEWS.md
+13-1Lines changed: 13 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,4 +1,16 @@
1
-
## (Unreleased) Sverto 1.0.0
1
+
## quarto-svelte 2.0.0
2
+
3
+
- Rename Sverto to quarto-svelte
4
+
-**Breaking:**`filters: ["sverto"]` is now `filters: ["quarto-svelte"]`
5
+
-**Breaking:**`sverto.use` is now `quarto-svelte.use`
6
+
- Repo name is now `jimjam-slam/quarto-svelte`, but `jimjam-slam/sverto` will continue to work
7
+
- Upgrade from Svelte 3 to Svelte 5
8
+
- For notes on rewriting existing Svelte components for Svelte 5, see the [Svelte 5 Migration Guide](https://svelte.dev/docs/svelte/v5-migration-guide)
9
+
- Now uses web components
10
+
-**Breaking:** in addition to general Svelte 5 migration, components for quarto-svelte need to have a [custom element option](https://svelte.dev/docs/svelte/custom-elements)
11
+
-**Breaking:** old instantiation syntax no longer works in Svelte 5. Instead, use an HTML template or JavaScript to create an element with the custom element name
12
+
13
+
## Sverto 1.0.0
2
14
3
15
- Significant refactor of Sverto makes it easier to use and more compatible with Quarto's other features
4
16
- Use Sverto in a Quarto document by adding `sverto` to `filters` in the document frontmatter
**Sverto** is an extension for [Quarto](https://quarto.org) that lets you seamlessly write and include [Svelte](https://svelte.dev) components, like charts and other visuals, in your Quarto website.
3
+
**quarto-svelte** is an extension for [Quarto](https://quarto.org) that lets you seamlessly write and include [Svelte](https://svelte.dev) components, like charts and other visuals, in your Quarto website.
4
4
5
-
Your Svelte components can seamlessly react to your ObservableJS code, making it quick and easy to build visuals that animate in response to [user inputs](https://observablehq.com/@observablehq/inputs?collection=@observablehq/inputs) or other changing data in your document.
5
+
Your Svelte components can seamlessly react to your [Observable JavaScript](https://quarto.org/docs/interactive/ojs/)code, making it quick and easy to build bespoke visuals that animate in response to [user inputs](https://observablehq.com/documentation/inputs/overview) or other changing data in your Quarto document.
6
6
7
-
## 📋 Prerequisites
7
+
Get going in four easy steps:
8
8
9
-
You'll need to install two things to run Sverto:
9
+
**Step 1: create a Svelte component**
10
10
11
-
-[Quarto](https://quarto.org)
12
-
-[Node and the Node Package Manager (npm)](https://nodejs.org)
13
-
14
-
## ⚙️ Installation
15
-
16
-
Install the project extension using:
17
-
18
-
```
19
-
quarto use template jimjam-slam/sverto
20
-
```
11
+
If you've never written Svelte before, don't worry! You can start learning quickly with the comprehensive [Svelte tutorial](https://svelte.dev/tutorial/svelte/welcome-to-svelte).
21
12
22
-
Then run:
13
+
quarto-svelte now uses a technique called [custom components](https://svelte.dev/docs/svelte/custom-elements) to bring Svelte into Quarto. So your Svelte component will need to start with a line like:
23
14
24
-
```
25
-
npm install
15
+
```html
16
+
<svelte:optionscustomElement="my-circles" />
26
17
```
27
18
28
-
This will add the extension itself (which includes some project scripts) to the `_extension` folder, as well as a few other files.
19
+
This name, `my-circles`, is what we'll use to place the component in our Quarto document. [It must be lowercase, and it must have at least one hyphen.](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements#registering_a_custom_element)
29
20
30
-
### 📦 What's in the box?
21
+
**Step 2: Add the Svelte file to your doc**
31
22
32
-
When you use the Sverto template in a project, it creates some files for you:
33
-
34
-
*[`example.qmd`](./example.qmd): an example Quarto doc that uses a Svelte component
35
-
*[`Circles.svelte`](./Circles.svelte): an example Svelte visualisation
36
-
*[`package.json`](./package.json): this is used to keep track of the dependencies of your Svelte components. **You should add this to version control.**
37
-
*`package-lock.json` is created once you run `npm install`. You should add this to version control.
38
-
*`node_modules/`: This folder is created once you rum `npm install`. Don't add it to version control.
39
-
40
-
## 🎉 Use
41
-
42
-
### Step 1: add Svelte to your document
43
-
44
-
In the document frontmatter, add `sverto` to `filters`, and add one or more `.svelte` files to `sverto.use`:
23
+
You can import your shiny new Svelte component into Quarto by adding the `quarto-svelte` filter and then including it (and any other Svelte files you want) as a list under `quarto-svelte.use`:
45
24
46
25
```yaml
47
26
---
48
-
title: "My document"
49
-
filters: ["sverto"]
50
-
sverto:
27
+
filters:
28
+
- quarto-svelte
29
+
quarto-svelte:
51
30
use:
52
-
- example.svelte
31
+
- Circles.svelte
53
32
---
54
33
```
55
34
56
-
### Step 2: bring your Svelte component to life
35
+
**Step 3: Place the Svelte component in your document**
57
36
58
-
Use an [Observable JS](https://quarto.org/docs/interactive/ojs/) chunk to _construct_ your Svelte component.
37
+
Remember the name at the top of your Svelte file? To place your Svelte component, you're going to use that name as if it were an HTML tag:
59
38
60
39
````js
61
40
```{ojs}
62
-
myChart = new example.default({
63
-
target: document.querySelector("#chart")
64
-
})
41
+
myCircles = html`<my-circles></my-circles>`
65
42
```
66
-
67
-
:::{#chart}
68
-
:::
69
43
````
70
44
71
-
- the `target` is where it will appear. This needs to be an existing part of the document — you can put a [Pandoc div](https://quarto.org/docs/authoring/markdown-basics.html#divs-and-spans) right after this code, or put one anywhere else on the page
72
-
-`example` is the file name of your Svelte component, without the file extension
73
-
74
-
### Step 3: make your component reactive
45
+
**Step 4: To update your Svelte component, use accessors to give it new props**
75
46
76
-
If your component has `props` that allow it to change or transition in response to other OJS code, you can update them by assigning the prop directly.
77
-
78
-
For example, if we have a dataset called `myData` in OJS, and a year slider called `selectedYear`, we might change a prop called `chartData` whenever the user selects a new year like:
47
+
If your Svelte component has [props](https://svelte.dev/tutorial/svelte/declaring-props) and you've assigned it to a variable in OJS, you can update the props on the fly! Let's update the data for our circles above:
> `quarto preview` won't "live reload" when you modify your Svelte component—but if you modify and save the Quarto doc that imports it, that will trigger a re-render. You may need to hard reload the page in your browser to see the updated Svelte component.
88
-
>
89
-
> If you want to quickly iterate on the Svelte component, you might find the [Svelte Preview](https://marketplace.visualstudio.com/items?itemName=RafaelMartinez.svelte-preview) extension for VSCode handy.
55
+
## ⚙️ Installation
56
+
57
+
You'll need to install two things to run quarto-svelte:
58
+
59
+
-[Quarto](https://quarto.org)
60
+
-[Node and the Node Package Manager (npm)](https://nodejs.org)
61
+
90
62
91
-
## 📦 What's in the box?
63
+
Install the extension and required files using:
92
64
93
-
When you use the Sverto template in a project, it creates some files for you:
65
+
```
66
+
quarto use template jimjam-slam/quarto-svelte
67
+
```
68
+
69
+
> [!NOTE]
70
+
> If you're running quarto-svelte in a Quarto project, be sure to install it from the root, or top-level, project folder.
71
+
>
72
+
> Do not use `quarto add`: quarto-svelte includes a `package.json` file that must sit in your project or document folder. `quarto use template` will copy this file for you.
73
+
74
+
Then run:
75
+
76
+
```
77
+
npm install
78
+
```
79
+
80
+
This will add the extension itself (which includes some project scripts) to the `_extension` folder, as well as a few other files.
81
+
82
+
### 📦 What's in the box?
83
+
84
+
When you use the quarto-svelte template in a project, it creates some files for you:
94
85
95
86
*[`example.qmd`](./example.qmd): an example Quarto doc that uses a Svelte component
96
87
*[`Circles.svelte`](./Circles.svelte): an example Svelte visualisation
97
-
*[`package.json`](./package.json): this is used to keep track of the dependencies of your Svelte components. You should add this to version control.
98
-
* Once you've run `npm install`, there'll also be a `package-lock.json` and a `.luarc.json`. You should version control these too (although you oughtn't need to edit them manually). You don't need to touch the `node_modules` folder, either.
88
+
*[`package.json`](./package.json): this is used to keep track of the dependencies of your Svelte components. **You should add this to version control.**
89
+
*`package-lock.json` is created once you run `npm install`. You should add this to version control.
90
+
*`node_modules/`: This folder is created once you rum `npm install`. Don't add it to version control.
99
91
100
-
See [`example.qmd`](./example.qmd) to learn how to add Svelte components to your documents and the [Svelte tutorial](https://svelte.dev/tutorial/basics) to learn how to create them.
92
+
> [!NOTE]
93
+
> `quarto preview` won't "live reload" when you modify your Svelte component—but if you modify and save the Quarto doc that imports it, that will trigger a re-render. You may need to hard reload the page in your browser to see the updated Svelte component.
94
+
>
95
+
> If you want to quickly iterate on the Svelte component, you might find the [Svelte Preview](https://marketplace.visualstudio.com/items?itemName=RafaelMartinez.svelte-preview) extension for VSCode handy.
101
96
102
-
As well as the project format, Sverto ships with document formats (the default is `sverto-html`). If you need to change document options that would normally go under `format: html`, use `format: sverto-html` or `format-sverto-revealjs` instead.
103
97
104
98
## 🛍 Use other libraries in your Svelte component
105
99
@@ -109,21 +103,21 @@ If you want to refer to other JavaScript libraries in your Svelte component (lik
109
103
npm install d3
110
104
```
111
105
112
-
# 💭 Why Sverto?
106
+
# 💭 Why quarto-svelte?
113
107
114
108
[Quarto](https://quarto.org) helps data scientists and analysts build beautiful documents regardless of their language of choice, and it encourages data analysts and scientists to explore web visualisation by making JavaScript accessible and easy to use.
115
109
116
110
Quarto makes interactive charts intuitive to write, but animated ones are still a challenge that require either dipping into a high-level JavaScript library or learning a lower-level one like [d3](https://d3js.org).
117
111
118
112
[Svelte](https://svelte.dev) is a framework for building charts, web visualisations and even apps in HTML, CSS and JavaScript. Svelte goes out of its way to make writing self-contained components, like charts, comfortable and intuitive.
119
113
120
-
Svelte has a great [playground environment](https://svelte.dev/repl/hello-world?version=3.55.1) for developing and testing components, but like many web frameworks, the experience is much more complex when you start developing locally.
114
+
Svelte has a great [playground environment](https://svelte.dev/repl) for developing and testing components, but like many web frameworks, the experience is much more complex when you start developing locally.
121
115
122
-
_Sverto aims to make it as easy to build and use animated Svelte charts in Quarto documents as it is to work on them in the Svelte playground: just write a `.svelte` file, add it to a Quarto document, and Sverto takes care of the rest._
116
+
_quarto-svelte aims to make it as easy to build and use animated Svelte charts in Quarto documents as it is to work on them in the Svelte playground: just write a `.svelte` file, add it to a Quarto document, and quarto-svelte takes care of the rest._
123
117
124
118
## ❓ Issues
125
119
126
-
If you have any problems with the extension, please feel free to [create an issue](https://github.com/jimjam-slam/sverto)!
120
+
If you have any problems with the extension, please feel free to [create an issue](https://github.com/jimjam-slam/quarto-svelte)!
127
121
128
-
Special thanks to [Carlos Scheidegger](https://github.com/cscheid) from [Posit](https://posit.co) for his time and guidance getting Sverto working!
122
+
Special thanks to [Carlos Scheidegger](https://github.com/cscheid) from [Posit](https://posit.co) for his time and guidance getting quarto-svelte working!
0 commit comments