Update documentation

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,7 +27,15 @@ 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
 
@@ -83,9 +83,10 @@ 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.
+> ![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?
 
@@ -105,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
 

docs/_quarto.yml

@@ -15,7 +15,7 @@ website:
         menu:
           - text: "Simple bar chart"
             file: examples/barchart/index.qmd
-          - text: "Time series"
+          - text: "Time series chart"
             file: examples/time-series/index.qmd
       - text: Changelog
         file: news.qmd
@@ -26,7 +26,8 @@ website:
 
 format:
   html:
-    title-block-banner: "#e1e4e6"
-    theme: default
+    # title-block-banner: "#e1e4e6"
+    title-block-banner: true
+    theme: [default, style.scss]
     linkcolor: "#36a7e9"
 

docs/examples/barchart/index.qmd

@@ -152,11 +152,10 @@ How did we get this chart going again?
 1. Add `filters: ["sverto"]` to our frontmatter, plus the name of our Svelte file to `sverto.use`
 2. Created the chart with `myBarChart = new BarChart.default()`, giving it a `target` to place the chart in
 3. We created the `target` with a Pandoc div: `:::{#mybarchart}`
-4. We customised the bar chart with `myBarChart.propName`
+4. We customised the bar chart by assigning to `myBarChart.propName`
 
 # Challenges
 
-
 Here's the code in the Svelte file:
 
 :::{.callout-note appearance="simple" collapse="true" title="BarChart.svelte"}
@@ -165,7 +164,7 @@ Here's the code in the Svelte file:
 ```
 :::
 
-if you'd like to start practising your Svelte, start with [the official tutorial](https://learn.svelte.dev/tutorial/welcome-to-svelte). Sverto is designed to make using Svelte components in Quarto as easy as working in the tutorial.
+If you'd like to start practising your Svelte, start with [the official tutorial](https://learn.svelte.dev/tutorial/welcome-to-svelte). Sverto is designed to make using Svelte components in Quarto as easy as working in the tutorial.
 
 This Svelte component's pretty basic, though. What else is it missing?
 
@@ -188,4 +187,10 @@ The bars are all the same colour. We could write a function that converts each b
 `d3` is included with OJS, but if you want to use `d3-scale-chromatic` (or any other part of d3) in your Svelte components, you'll have to add it yourself by:
 
 - running `npm install d3-scale-chromatic` in the terminal, then
-- adding `import XXXX from "d3-scale-chromatic"`, where `XXXX` is the name of the thing you want to import (or `*`).
+- adding `import XXXX from "d3-scale-chromatic"`, where `XXXX` is the name of the thing you want to import (or `*`).
+
+### A more complex example
+
+If you'd like to see an example that addresses some of these shortcomings, check out the [time series chart example](../time-series), which automatically resizes and adds axes that transition!
+
+[See the time series chart →]((../time-series)){.btn .btn-success}

docs/index.qmd

@@ -1,32 +1,22 @@
 ---
 title: Sverto
 description: "**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."
-author: James Goldie
-date: last-modified
 format:
     html:
       toc: true
       toc-location: left
 ---
 
-Your Svelte components can seamlessly react to your ObservableJS code, making it quick and easy to build bespoke visuals that animate in response to [user inputs](https://observablehq.com/@observablehq/inputs?collection=@observablehq/inputs) or other changing data in your document.
+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/@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 animated Svelte charts 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
+# 📋 Prerequisites
 
 You'll need to install two things to run Sverto:
 
 - [Quarto](https://quarto.org)
 - [Node and the Node Package Manager (npm)](https://nodejs.org)
 
-## ⚙️ Installation
+# ⚙️ Installation
 
 Install the project extension using:
 
@@ -42,15 +32,21 @@ npm install
 
 This will add the extension itself (which includes some project scripts) to the `_extension` folder, as well as a few other files.
 
-:::{.callout-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:
 
-## 🎉 Use
+* [`example.qmd`](./example.qmd): an example Quarto doc that uses a Svelte component. If you're adding Sverto to an existing document, you can delete this.
+* [`Circles.svelte`](./Circles.svelte): an example Svelte visualisation. If you have a Svelte component that you want to use instead, you can delete this.
+* [`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.
 
-Here's the quick guide to add Svelte component you've written to a Quarto doc:
+# 🎉 Use
 
-### Step 1: add Svelte to your document
+Here's the quick guide to add a 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`:
 
@@ -60,21 +56,18 @@ title: "My document"
 filters: ["sverto"]
 sverto:
   use:
-    example.svelte
+    - example.svelte
 ---
 ```
 
-### Step 2: bring your Svelte component to life
+## Step 2: bring your Svelte component to life
 
 Use an [Observable JS](https://quarto.org/docs/interactive/ojs/) chunk to _instantiate_ your Svelte component.
 
 ````js
 ```{ojs}
 myChart = new example.default({
   target: document.querySelector("#chart")
-  props: {
-    chartData: {}
-  }
 })
 ```
 
@@ -83,10 +76,10 @@ 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!
+- `example` is the file name of your Svelte component, without the file extension (so if your file is called `example.svelte` call `example.default()`)
+- if your Svelte component has any `props` that don't have defaults built in, supply default values here for them 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 visual 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.
 
@@ -96,36 +89,45 @@ For example, if we have a dataset called `myData` in OJS, and a year slider call
 myChart.chartData = myData.filter(d => d.year == selectedYear)
 ````
 
-**To see this all in practice, check out [`example.qmd`](https://github.com/jimjam-slam/sverto/blob/main/example.qmd).**
+If you're writing a single document, you're done! Run `quarto render` and see your hard work.
 
-:::{.callout-tip}
-If you're using a [Quarto project](https://quarto.org/docs/projects/quarto-projects.html) and you have documents that share Quarto components, add project `project.type: sverto`. All of the Svelte components in your project will be built together, avoiding duplication.
-:::
+**To see this all in practice, check out the [simple bar chart example](examples/barchart).**
 
-:::{.callout-note}
+## Step 4 (for websites): set the project type
+
+If you're using a [Quarto website](https://quarto.org/docs/projects/quarto-projects.html), change the `project.type` in `_quarto.yml` from `website` to `sverto`.
+
+This way, your website pages can share Sverto components when you're rendering the whole website.
+
+:::{.callout-tip appearance="simple" title="Hot reloads"}
 The `quarto preview` command 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 a Svelte component you're building, you might find the [Svelte Preview](https://marketplace.visualstudio.com/items?itemName=RafaelMartinez.svelte-preview) extension for VSCode handy.
 :::
 
+# Advanced use
+
 ## 🛍 Use other libraries in your Svelte component
 
 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:
 
 ```sh
-npm install d3-scale
+npm install d3
 ```
+# 💭 Why Sverto?
 
-## 🔨 Use pre-compiled Svelte components
+[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.
 
-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.
+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).
 
-:::{.callout-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`](https://github.com/jimjam-slam/sverto/blob/firstrelease/_extensions/sverto/rollup.config.js) for guidance on configuring Rollup to do this.
-:::
+[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.
+
+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.
+
+_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
+# ❓ Issues
 
-If you have any problems with the extension, please feel free to [create an issue](https://github.com/jimjam-slam/sverto)!
+If you have any problems with Sverto, please feel free to [create an issue](https://github.com/jimjam-slam/sverto)!
 
 Special thanks to [Carlos Scheidegger](https://github.com/cscheid) from [Posit](https://posit.co) for his time and advice!

docs/news.qmd

@@ -2,21 +2,17 @@
 title: News
 author: James Goldie
 date: last-modified
-format:
-    html:
-      title-block-banner: "#e1e4e6"
-      linkcolor: "#36a7e9"
 ---
 
-## (Unreleased) Sverto 1.0.0
+## 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
+- 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.
+- **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
 

docs/style.scss

@@ -0,0 +1,9 @@
+/*-- scss:defaults --*/
+
+/*-- scss:rules --*/
+
+.btn {
+  box-shadow:
+    0 .2em .8em .2em rgba(0,0,0,.05),
+    0 .2em .6em .1em rgba(0,0,0,.025);
+}