Merge pull request #20 from jimjam-slam/dev

v1.0:

- Big 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.

.github/workflows/check.yml

@@ -22,20 +22,30 @@ jobs:
       GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Install Quarto
         uses: quarto-dev/quarto-actions/setup@v2
+        with:
+          version: 1.5.25
 
       - name: Install Node
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v4
         with:
-          node-version: "latest"
+          node-version: 20
 
       - name: Install Sverto docs npm dependencies
         run: npm install
         working-directory: ./docs
 
+      - name: Create docs _extensions folder
+        run: mkdir docs/_extensions
+        shell: bash
+
+      - name: Copy Sverto extension into docs 
+        run: cp -rf _extensions/sverto docs/_extensions/sverto
+        shell: bash
+
       - name: Render sverto docs
         uses: quarto-dev/quarto-actions/render@v2
         with:

.gitignore

@@ -18,4 +18,7 @@
 # rendered documentation site
 /docs/_site/
 /docs/.quarto/
-/docs/.sverto/
+/docs/.sverto/
+
+# sverto extension in docs site (we get it from project root on render)
+/docs/_extensions/sverto

.quartoignore

@@ -1,6 +1,9 @@
 README.md
 NEWS.md
 LICENSE
+.luarc.json
+package-lock.json
 docs/
 .quarto/
-!.gitignore
+.github/
+!.gitignore

Circles.svelte

@@ -16,15 +16,15 @@
 
 </script>
 
-<!-- we use svelte's in/out transitions for entering and leaving dom elements,
+<!-- we use svelte's in/out transitions for entering and exiting dom elements,
      and vanilla css transitions for retained elements that change. the
      #each block means we create an svg <circle> for each element of data -->
 <svg>
   {#each data as d, i (i)}
     <circle
       in:fly="{{y: 100}}" out:fly="{{y: 100}}"
       style={"transition: all 1s ease-out"}
-      cx={15 * i + "%"} cy="50%" r={d}
+      cx={(15 * i + 10) + "%"} cy="50%" r={d}
       fill="black"
        />
   {/each}

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

@@ -4,14 +4,6 @@
 
 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.
 
-## 💭 Why Sverto?
-
-[Quarto](https://quarto.org) helps users 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. It makes interactive visualisations intuitive to write, but animated visuals 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).
-
-[Svelte](https://svelte.dev) is a framework for building web visualisations and apps in JavaScript. Svelte goes out of its way to make writing self-contained components, like charts, comfortable and intuitive. It 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.
-
-_Sverto aims to make it as easy to use Svelte components in Quarto documents as it is to work on them in the Svelte REPL: just write a `.svelte` file, add it to a Quarto document, and Sverto should take care of the rest._
-
 ## 📋 Prerequisites
 
 You'll need to install two things to run Sverto:
@@ -35,31 +27,66 @@ npm install
 
 This will add the extension itself (which includes some project scripts) to the `_extension` folder, as well as a few other files.
 
-> **Note:** Sverto depends on running [project pre-render scripts](https://quarto.org/docs/projects/scripts.html#pre-and-post-render), so you can't currently use it with single documents.
+### 📦 What's in the box?
+
+When you use the Sverto template in a project, it creates some files for you:
+
+* [`example.qmd`](./example.qmd): an example Quarto doc that uses a Svelte component
+* [`Circles.svelte`](./Circles.svelte): an example Svelte visualisation
+* [`package.json`](./package.json): this is used to keep track of the dependencies of your Svelte components. **You should add this to version control.**
+* `package-lock.json` is created once you run `npm install`. You should add this to version control.
+* `node_modules/`: This folder is created once you rum `npm install`. Don't add it to version control.
 
 ## 🎉 Use
 
-Here's the short way to add Svelte component you've written to a Quarto doc:
+### Step 1: add Svelte to your document
+
+In the document frontmatter, add `sverto` to `filters`, and add one or more `.svelte` files to `sverto.use`:
+
+```yaml
+---
+title: "My document"
+filters: ["sverto"]
+sverto:
+  use:
+    - example.svelte
+---
+```
+
+### Step 2: bring your Svelte component to life
+
+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")
+})
+```
+
+:::{#chart}
+:::
+````
 
-1. Add a magic placeholder block to your document with a [Quarto include](https://quarto.org/docs/authoring/includes.html) to the path to your Quarto doc, prefixed with `/.sverto/`. For example:
+- 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
 
-    ```
-    :::{}
-    {{< include /.sverto/example.qmd >}}
-    :::
-    ```
+### Step 3: make your component reactive 
 
-2. Import your Svelte component in OJS with `Component = import_svelte("Component.svelte")`
-3. Add a target block for your visual using `:::` and give it an `#id`
-4. Instantiate the Svelte component with `myVisual = Component.default()` using some default props and your target block
-5. Update the instantiated component with `myVisual.propName`
-6. Render your Quarto website as usual with `quarto render` or `quarto preview`.
+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.
 
-**To see this all in practice, check out [`example.qmd`](./example.qmd).**
+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:
 
-> **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.
+````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.
 > 
-> If you want to quickly iterate on the Svelte component and you aren't too concerned about the rest of your Quarto doc, you might find the [Svelte Preview](https://marketplace.visualstudio.com/items?itemName=RafaelMartinez.svelte-preview) extension for VSCode handy.
+> 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.
 
 ## 📦 What's in the box?
 
@@ -79,14 +106,20 @@ As well as the project format, Sverto ships with document formats (the default i
 If you want to refer to other JavaScript libraries in your Svelte component (like d3, for example), add them to the project using `npm install package1 [package2 ...]`. For example:
 
 ```
-npm install d3-scale
+npm install d3
 ```
 
-## Use pre-compiled Svelte components
+# 💭 Why Sverto?
+
+[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.
+
+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).
+
+[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.
 
-If you'd prefer to compile your own Svelte components instead of letting this extension do it, you can skip steps 1 and 2 and simply refer to the compiled bundle with, for example, `Component = import("Component.js")` in an OJS block.
+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.
 
-> **Note:** you must compile the Svelte component to an ES6 bundle, and you must enable accessors when compiling if you want to be able to update them from OJS. Refer to `_extensions/sverto/rollup.config.js` for guidance on configuring Rollup to do this.
+_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._
 
 ## ❓ Issues
 

_extensions/sverto/_extension.yml

@@ -1,20 +1,11 @@
 title: Sverto
-author: 360info
-version: 0.0.2
-quarto-version: ">=1.3.0"
+author: James Goldie
+version: 1.0.0
+quarto-version: ">=1.4.0"
 contributes:
+  filters:
+    - sverto.lua
   project:
     project:
       type: website
-      pre-render:
-        - refresh.ts
-        - create-imports.lua
-        - compile-imports.ts
-    format: sverto-html
-  formats:
-    html:
-      filters:
-        - cleanup-transform.lua
-    revealjs:
-      filters:
-        - cleanup-transform.lua
+      pre-render: sverto-prerender.lua