Further update docs and example template

Author: James Goldie

NEWS.md

@@ -1,3 +1,17 @@
+## (Unreleased) Sverto 1.0.0
+
+- Significant refactor of Sverto makes it easier to use and more compatible with Quarto's other features
+- Use Sverto in a Quarto document by adding `sverto` to `filters` in the document frontmatter
+- Add Svelte files to a document using the frontmatter key `sverto.use`
+- No need for magic blocks anymore!
+- When working in a website project, optionally use the `sverto` project type to cut down on duplicate Svelte compilation Quarto documents
+- Works properly with Quarto includes
+- Requires Quarto pre-release 1.5.25 or higher on Windows, but should work fine on Quarto 1.4 on macOS and Linux.
+
+## Sverto 0.0.3
+
+- Migrated from [`360-info/sverto`](https://github.comn/360-info/sverto) to [`jimjam-slam/sverto`](htps://github.com/jimjam-slam/sverto). Old GitHub links are maintained.
+
 ## Sverto 0.0.2
 
 - Bump minimum Quarto version to 1.3.0.
@@ -7,6 +21,6 @@
   1. avoid copying the `docs` folder in with the project template; and
   2. include the `.gitignore` with the template
 
-## 0.0.1
+## Sverto 0.0.1
 
 - Initial release

README.md

@@ -49,21 +49,18 @@ title: "My document"
 filters: ["sverto"]
 sverto:
   use:
-    example.svelte
+    - example.svelte
 ---
 ```
 
 ### Step 2: bring your Svelte component to life
 
-Use an [Observable JS](https://quarto.org/docs/interactive/ojs/) chunk to _instantiate_ your Svelte component.
+Use an [Observable JS](https://quarto.org/docs/interactive/ojs/) chunk to _construct_ your Svelte component.
 
 ````js
 ```{ojs}
 myChart = new example.default({
   target: document.querySelector("#chart")
-  props: {
-    chartData: {}
-  }
 })
 ```
 
@@ -73,16 +70,17 @@ myChart = new example.default({
 
 - 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
 - `example` is the file name of your Svelte component, without the file extension
-- if your Svelte component has any `props`, add default values here too. Don't put reactive OJS code in here; we'll update the props separately!
 
-### Step 3: make your visual reactive 
+### Step 3: make your component reactive 
 
-If your visual has `props` that allow it to change or transition in response to other OJS code, you can update it by assigning the prop directly.
+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.
 
-For example, if we have a dataset called `myData` in OJS, and a year slider called `selectedYear`, we can change a prop called `chartData` whenever the user selects a new year like:
+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:
 
 ````js
+```{ojs}
 myChart.chartData = myData.filter(d => d.year == selectedYear)
+```
 ````
 
 > **Note:** `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.

example.qmd

@@ -1,97 +1,31 @@
 ---
-title: Svelte example
-author: James Goldie, 360info
+title: Sverto example
 date: last-modified
 filters:
   - sverto
 sverto:
   use:
     - Circles.svelte
-    - Test.svelte
 ---
 
-Here's an example of how to use the included example Svelte component, `Circles.svelte`. There are six steps:
+Here's an example of how to use the included example Svelte component, `Circles.svelte`.
 
-### 1. Install Sverto
-
-```bash
-quarto add jimjam-slam/sverto
-```
-
-### 2. Add Sverto to your document
-
-In the document frontmatter:
-
-```yaml
----
-# filters:
-#   - sverto
----
-```
-
-#### (For projects only: use the sverto project type)
-
-In `_quarto.yml`:
-
-
-```yaml
-project:
-  type: sverto
-```
-
-### 3. Create a place for your visual to live
-
-We need to create an instance of our imported component, but---unlike a typical OJS block---Svelte components put the visual itself somewhere else in the document.
-
-Create an empty div in your document and give it an #id with the hashtag. This will be the "target" in the next step, when we bring the component to life, or _instantiate_ it:
-
-```markdown
-:::{#mycircles}
-:::
-```
-
-:::{#mycircles}
-:::
-
-:::{.callout-tip}
-This block can go anywhere in your document! Feel free to put it well after the following steps, where you actually want your visualisation to appear.
-:::
-
-:::{.callout-tip}
-If you know how how to use CSS, you can target `#mycircles` to position or size your visualisation as you'd like.
-:::
-
-### 4. Instantiate your component
-
-Bring your component to life by creating an instance of it with `new [Component Name].default()`. This function takes an object as an argument with two properties:
-
-- `target` is the place your visual will go. Use the `document.querySelector` to point it to the empty block we just made above, `#mycricles`.
-- `props`: is an object where we pass props, or properties, to the component. This will vary depending on how the component is written: the one included as an example with this package, `Circles.svelte`, requires a prop called `data`.
-
-Here's how we instantiate `Circles.svelte`:
+Create one using `fileName.default()`, where `fileName` is the file name without `.svelte`:
 
 ```{ojs}
 myCircles = new Circles.default({
-  target: document.querySelector("#mycircles"),
-  props: {
-    data: [5, 15, 25, 17, 8]
-  }
+  target: document.querySelector("#mycircles")
 });
 ```
 
-::: {.callout-important}
-If you're creating a visual that will react in response to changing OJS (for example, some data that you've calculated in your document, or the value of an Observable Input), **do not put that data here.**
+It will appear in a [div](https://quarto.org/docs/authoring/markdown-basics.html#divs-and-spans) called `#mycircles`, which I've added directly below:
 
-If you put changing data here, the Svelte component will rebuild from scratch every time the data changes, and it will not animate.
-
-Instead, we're going to take advantage of Svelte's own reactivity in the next step.
+:::{#mycircles}
 :::
 
-### 5. Update your component
-
-Now the fun part - updating our visual when our document changes. It's as simple as referring to the prop using `componentInstance.propName =`.
+Now the fun part - updating our visual when our document changes. It's as simple as changing the prop using `componentName.propName =`.
 
-For example, here are three datasets and an Observable Inputs dropdown menu that lets you select one of three datasets:
+For example, here are three datasets and an [Observable Inputs](https://observablehq.com/documentation/inputs/overview) dropdown menu that lets you select one of three datasets:
 
 ```{ojs}
 // here are some datasets...
@@ -113,22 +47,6 @@ Now we can update the prop `data` of the visual `myCircles` using:
 myCircles.data = selectedDataset
 ```
 
-You can't see anything here, but if we scroll back up to where we added the empty `#mycircles` block, you can see it transition whenever we select a new dataset!
-
-:::{.callout-tip}
-You can put `#mycircles` wherever you want in the document - it doesn't have to be in order!
-:::
-
-### 6. Render the project
-
-Render your Quarto project as you normally would, with commands like `quarto run` and `quarto preview`.
-
-:::{.callout-note}
-You'll probably get the warning `OJS block count mismatch. Line number reporting is likely to be wrong` when rendering.
- 
-That's because of what we're doing under the hood to bring the Svelte files in. It won't stop your project from working, but be aware of it if you are referring to line numbers in code blocks!
-:::
-
 And there you go! 🚀
 
 For more help writing Svelte components, check out the [Svelte tutorial](https://svelte.dev/tutorial/basics).