From b014b2906004495f2b6d48882111d1a78a549741 Mon Sep 17 00:00:00 2001
From: Daniel Sheffield <Daniel.Sheffield@first-watch.co.nz>
Date: Mon, 24 Jun 2024 09:34:23 +1200
Subject: [PATCH 01/15] #435: WIP - show spinner indicating page is loading

---
 examples/show-progress/README.md              |  3 +
 examples/show-progress/index.sql              | 17 +++++
 examples/show-progress/sqlpage/sqlpage.yml    |  3 +
 frontend/src/sqlpage.css                      | 63 +++++++++++++++++++
 sqlpage/templates/spinner-progress.handlebars |  7 +++
 sqlpage/templates/spinner-start.handlebars    |  2 +
 sqlpage/templates/spinner-stop.handlebars     |  2 +
 7 files changed, 97 insertions(+)
 create mode 100644 examples/show-progress/README.md
 create mode 100644 examples/show-progress/index.sql
 create mode 100644 examples/show-progress/sqlpage/sqlpage.yml
 create mode 100644 sqlpage/templates/spinner-progress.handlebars
 create mode 100644 sqlpage/templates/spinner-start.handlebars
 create mode 100644 sqlpage/templates/spinner-stop.handlebars

diff --git a/examples/show-progress/README.md b/examples/show-progress/README.md
new file mode 100644
index 000000000..fb4c73480
--- /dev/null
+++ b/examples/show-progress/README.md
@@ -0,0 +1,3 @@
+# SQLPage display progress
+
+This is a very simple example of a page that shows a spinner to indicate page is loading.
\ No newline at end of file
diff --git a/examples/show-progress/index.sql b/examples/show-progress/index.sql
new file mode 100644
index 000000000..be5cd8aeb
--- /dev/null
+++ b/examples/show-progress/index.sql
@@ -0,0 +1,17 @@
+SELECT 'spinner-start' AS component;
+SELECT 'spinner-progress' AS component,
+  '0' AS percent,
+  'Sleeping 3 seconds' AS stage; 
+SELECT sqlpage.exec('sleep', '3');
+
+SELECT 'spinner-progress' AS component,
+  '30' AS percent,
+  'Sleeping 5 seconds' AS stage; 
+SELECT sqlpage.exec('sleep', '5');
+
+/* stage property is optional */
+SELECT 'spinner-progress' AS component,
+  '80' AS percent;
+SELECT sqlpage.exec('sleep', '1');
+
+SELECT 'spinner-stop' AS component;
diff --git a/examples/show-progress/sqlpage/sqlpage.yml b/examples/show-progress/sqlpage/sqlpage.yml
new file mode 100644
index 000000000..d38d9a202
--- /dev/null
+++ b/examples/show-progress/sqlpage/sqlpage.yml
@@ -0,0 +1,3 @@
+allow_exec: True
+compress_responses: False
+database_url: "sqlite://:memory:"
diff --git a/frontend/src/sqlpage.css b/frontend/src/sqlpage.css
index ed65bc902..2d093cb95 100644
--- a/frontend/src/sqlpage.css
+++ b/frontend/src/sqlpage.css
@@ -198,3 +198,66 @@ See https://github.com/tabler/tabler/issues/2404
   color: inherit;
   text-decoration: underline;
 }
+
+/* spinner container */
+div.sqlpage-spinner-start {
+  /* TODO: center this */
+  position: absolute;
+  left: 50vw;
+  top: 50vh;
+  margin-top: -5.5em;
+  margin-left: -87.5px;
+  padding-bottom: 2em;
+  height: 9em;
+  width: 175px;
+}
+div.sqlpage-spinner-start:not(:has(+ .sqlpage-spinner-stop)) {
+  /* only display if not followed by sqlpage-spinner-stop */
+  display: block;
+}
+.sqlpage-spinner-start:not(:last-child) {
+  /* firefox doesn't support :has
+     so hide the spinner if is no longer the last element */
+  display: none;
+}
+
+/* default indeterminate loader */
+.sqlpage-loader {
+  width: 48px;
+  height: 48px;
+  border: 5px solid var(--tblr-body-color);
+  border-bottom-color: transparent;
+  border-radius: 50%;
+  display: inline-block;
+  box-sizing: border-box;
+  animation: sqlpage-loader-rotation 1s linear infinite;
+}
+
+@keyframes sqlpage-loader-rotation {
+  0% {
+      transform: rotate(0deg);
+  }
+  100% {
+      transform: rotate(360deg);
+  }
+}
+
+/* progress indicator container */
+div.sqlpage-spinner-progress {
+  margin: 1em 0 1em;
+}
+div.sqlpage-spinner-progress:not(:has(+ .sqlpage-spinner-progress)) {
+  /* only display if not followed by progress update */
+  display: block;
+}
+.sqlpage-spinner-progress:not(:last-child) {
+  /* firefox doesn't support :has
+     so hide the spinner if is no longer the last element */
+  display: none;
+}
+.sqlpage-spinner-progress label {
+  text-align:left;
+}
+.sqlpage-spinner-progress label:after {
+  content: "...";
+}
diff --git a/sqlpage/templates/spinner-progress.handlebars b/sqlpage/templates/spinner-progress.handlebars
new file mode 100644
index 000000000..1550d12b2
--- /dev/null
+++ b/sqlpage/templates/spinner-progress.handlebars
@@ -0,0 +1,7 @@
+<div class="sqlpage-spinner-progress">
+  <progress id="sqlpage-loading-{{default stage "progress"}}" value="{{percent}}" max="100"></progress>
+  {{#if stage}}
+  <br/>
+  <label for="sqlpage-loading-{{stage}}">{{stage}}</label>
+  {{/if}}
+</div>
\ No newline at end of file
diff --git a/sqlpage/templates/spinner-start.handlebars b/sqlpage/templates/spinner-start.handlebars
new file mode 100644
index 000000000..a0fa1bf67
--- /dev/null
+++ b/sqlpage/templates/spinner-start.handlebars
@@ -0,0 +1,2 @@
+<div {{#if id}}id="{{id}}"{{/if}} class="sqlpage-spinner-start">
+  <span class="{{default spinner "sqlpage-loader"}}"></span>
\ No newline at end of file
diff --git a/sqlpage/templates/spinner-stop.handlebars b/sqlpage/templates/spinner-stop.handlebars
new file mode 100644
index 000000000..32ef9574e
--- /dev/null
+++ b/sqlpage/templates/spinner-stop.handlebars
@@ -0,0 +1,2 @@
+</div>
+<div class="sqlpage-spinner-stop" />
\ No newline at end of file

From 8d88bd15cd8f825112f0a7336fda456d86f30871 Mon Sep 17 00:00:00 2001
From: Daniel Sheffield <Daniel.Sheffield@first-watch.co.nz>
Date: Mon, 24 Jun 2024 09:58:37 +1200
Subject: [PATCH 02/15] center the spinner

---
 examples/show-progress/index.sql | 25 +++++++++++++++++++------
 frontend/src/sqlpage.css         |  4 ++--
 2 files changed, 21 insertions(+), 8 deletions(-)

diff --git a/examples/show-progress/index.sql b/examples/show-progress/index.sql
index be5cd8aeb..7b76c5e4f 100644
--- a/examples/show-progress/index.sql
+++ b/examples/show-progress/index.sql
@@ -1,17 +1,30 @@
 SELECT 'spinner-start' AS component;
 SELECT 'spinner-progress' AS component,
   '0' AS percent,
-  'Sleeping 3 seconds' AS stage; 
-SELECT sqlpage.exec('sleep', '3');
+  'Sleeping 1 second' AS stage;
+SELECT sqlpage.exec('sleep', '1');
 
 SELECT 'spinner-progress' AS component,
-  '30' AS percent,
-  'Sleeping 5 seconds' AS stage; 
-SELECT sqlpage.exec('sleep', '5');
+  '20' AS percent,
+  'Sleeping 1 more second' AS stage;
+SELECT sqlpage.exec('sleep', '1');
 
 /* stage property is optional */
 SELECT 'spinner-progress' AS component,
-  '80' AS percent;
+  '40' AS percent;
 SELECT sqlpage.exec('sleep', '1');
 
+SELECT 'spinner-progress' AS component,
+  '60' AS percent,
+  'Sleeping 2 seconds' AS stage;
+SELECT sqlpage.exec('sleep', '2');
+
+SELECT 'spinner-progress' AS component,
+  '100' AS percent;
+
 SELECT 'spinner-stop' AS component;
+
+SELECT 'text' AS component,
+  'It works!' AS title,
+  TRUE AS center,
+  'Page is loaded.' AS contents;
diff --git a/frontend/src/sqlpage.css b/frontend/src/sqlpage.css
index 2d093cb95..bcd14a42a 100644
--- a/frontend/src/sqlpage.css
+++ b/frontend/src/sqlpage.css
@@ -201,8 +201,8 @@ See https://github.com/tabler/tabler/issues/2404
 
 /* spinner container */
 div.sqlpage-spinner-start {
-  /* TODO: center this */
-  position: absolute;
+  position: fixed;
+  text-align: center;
   left: 50vw;
   top: 50vh;
   margin-top: -5.5em;

From 2f86194943d8edda69ff70223fabf8cf6eac1f9d Mon Sep 17 00:00:00 2001
From: Daniel Sheffield <Daniel.Sheffield@first-watch.co.nz>
Date: Mon, 24 Jun 2024 10:04:28 +1200
Subject: [PATCH 03/15] use tabler spinner by default

---
 examples/show-progress/index.sql           |  4 +++-
 frontend/src/sqlpage.css                   | 21 ---------------------
 sqlpage/templates/spinner-start.handlebars |  2 +-
 3 files changed, 4 insertions(+), 23 deletions(-)

diff --git a/examples/show-progress/index.sql b/examples/show-progress/index.sql
index 7b76c5e4f..35b268086 100644
--- a/examples/show-progress/index.sql
+++ b/examples/show-progress/index.sql
@@ -1,4 +1,6 @@
-SELECT 'spinner-start' AS component;
+SELECT 'spinner-start' AS component,
+  -- default is "spinner-border"
+  "spinner-grow text-red" AS spinner;
 SELECT 'spinner-progress' AS component,
   '0' AS percent,
   'Sleeping 1 second' AS stage;
diff --git a/frontend/src/sqlpage.css b/frontend/src/sqlpage.css
index bcd14a42a..407887f39 100644
--- a/frontend/src/sqlpage.css
+++ b/frontend/src/sqlpage.css
@@ -221,27 +221,6 @@ div.sqlpage-spinner-start:not(:has(+ .sqlpage-spinner-stop)) {
   display: none;
 }
 
-/* default indeterminate loader */
-.sqlpage-loader {
-  width: 48px;
-  height: 48px;
-  border: 5px solid var(--tblr-body-color);
-  border-bottom-color: transparent;
-  border-radius: 50%;
-  display: inline-block;
-  box-sizing: border-box;
-  animation: sqlpage-loader-rotation 1s linear infinite;
-}
-
-@keyframes sqlpage-loader-rotation {
-  0% {
-      transform: rotate(0deg);
-  }
-  100% {
-      transform: rotate(360deg);
-  }
-}
-
 /* progress indicator container */
 div.sqlpage-spinner-progress {
   margin: 1em 0 1em;
diff --git a/sqlpage/templates/spinner-start.handlebars b/sqlpage/templates/spinner-start.handlebars
index a0fa1bf67..2f0e02e00 100644
--- a/sqlpage/templates/spinner-start.handlebars
+++ b/sqlpage/templates/spinner-start.handlebars
@@ -1,2 +1,2 @@
 <div {{#if id}}id="{{id}}"{{/if}} class="sqlpage-spinner-start">
-  <span class="{{default spinner "sqlpage-loader"}}"></span>
\ No newline at end of file
+  <span class="{{default spinner "spinner-border"}}"></span>
\ No newline at end of file

From 2679ec43c85f874b5b1473b5a037eae7f67024c6 Mon Sep 17 00:00:00 2001
From: Daniel Sheffield <Daniel.Sheffield@first-watch.co.nz>
Date: Mon, 24 Jun 2024 10:05:14 +1200
Subject: [PATCH 04/15] fix whitespace

---
 sqlpage/templates/spinner-progress.handlebars | 2 +-
 sqlpage/templates/spinner-start.handlebars    | 2 +-
 sqlpage/templates/spinner-stop.handlebars     | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/sqlpage/templates/spinner-progress.handlebars b/sqlpage/templates/spinner-progress.handlebars
index 1550d12b2..f2bf9ac39 100644
--- a/sqlpage/templates/spinner-progress.handlebars
+++ b/sqlpage/templates/spinner-progress.handlebars
@@ -4,4 +4,4 @@
   <br/>
   <label for="sqlpage-loading-{{stage}}">{{stage}}</label>
   {{/if}}
-</div>
\ No newline at end of file
+</div>
diff --git a/sqlpage/templates/spinner-start.handlebars b/sqlpage/templates/spinner-start.handlebars
index 2f0e02e00..e37cb561d 100644
--- a/sqlpage/templates/spinner-start.handlebars
+++ b/sqlpage/templates/spinner-start.handlebars
@@ -1,2 +1,2 @@
 <div {{#if id}}id="{{id}}"{{/if}} class="sqlpage-spinner-start">
-  <span class="{{default spinner "spinner-border"}}"></span>
\ No newline at end of file
+  <span class="{{default spinner "spinner-border"}}"></span>
diff --git a/sqlpage/templates/spinner-stop.handlebars b/sqlpage/templates/spinner-stop.handlebars
index 32ef9574e..4f1b3527d 100644
--- a/sqlpage/templates/spinner-stop.handlebars
+++ b/sqlpage/templates/spinner-stop.handlebars
@@ -1,2 +1,2 @@
 </div>
-<div class="sqlpage-spinner-stop" />
\ No newline at end of file
+<div class="sqlpage-spinner-stop" />

From b63c35becb15774ba9b1683fa6fa7099e6a45383 Mon Sep 17 00:00:00 2001
From: Daniel Sheffield <Daniel.Sheffield@first-watch.co.nz>
Date: Mon, 24 Jun 2024 12:18:18 +1200
Subject: [PATCH 05/15] add example of progress on it's own

---
 examples/show-progress/index.sql              | 43 ++++++++++++------
 frontend/src/sqlpage.css                      | 33 +++++++-------
 sqlpage/templates/loader-start.handlebars     |  2 +
 sqlpage/templates/loader-stop.handlebars      |  2 +
 sqlpage/templates/progress.handlebars         | 44 +++++++++++++++++++
 sqlpage/templates/spinner-progress.handlebars |  7 ---
 sqlpage/templates/spinner-start.handlebars    |  2 -
 sqlpage/templates/spinner-stop.handlebars     |  2 -
 8 files changed, 96 insertions(+), 39 deletions(-)
 create mode 100644 sqlpage/templates/loader-start.handlebars
 create mode 100644 sqlpage/templates/loader-stop.handlebars
 create mode 100644 sqlpage/templates/progress.handlebars
 delete mode 100644 sqlpage/templates/spinner-progress.handlebars
 delete mode 100644 sqlpage/templates/spinner-start.handlebars
 delete mode 100644 sqlpage/templates/spinner-stop.handlebars

diff --git a/examples/show-progress/index.sql b/examples/show-progress/index.sql
index 35b268086..7d86f1e30 100644
--- a/examples/show-progress/index.sql
+++ b/examples/show-progress/index.sql
@@ -1,32 +1,49 @@
-SELECT 'spinner-start' AS component,
+SELECT 'shell' AS component,
+  'dark' AS theme;
+
+SELECT 'loader-start' AS component,
   -- default is "spinner-border"
   "spinner-grow text-red" AS spinner;
-SELECT 'spinner-progress' AS component,
+
+SELECT 'progress' AS component,
+  'sm' AS size,
+  'yellow' AS color,
   '0' AS percent,
   'Sleeping 1 second' AS stage;
 SELECT sqlpage.exec('sleep', '1');
 
-SELECT 'spinner-progress' AS component,
-  '20' AS percent,
-  'Sleeping 1 more second' AS stage;
+/* percent property is optional */
+SELECT 'progress' AS component,
+  NULL AS percent,
+  'sm' AS size,
+  'yellow' AS color,
+  'Doing something' AS stage;
 SELECT sqlpage.exec('sleep', '1');
 
 /* stage property is optional */
-SELECT 'spinner-progress' AS component,
+SELECT 'progress' AS component,
+  'sm' AS size,
+  'yellow' AS color,
   '40' AS percent;
 SELECT sqlpage.exec('sleep', '1');
 
-SELECT 'spinner-progress' AS component,
-  '60' AS percent,
-  'Sleeping 2 seconds' AS stage;
-SELECT sqlpage.exec('sleep', '2');
+/* multiple rows */
+SELECT 'progress' AS component, 'sm' AS size, 'yellow' AS color;
+SELECT '70' AS percent, 'Sleeping 1 second' AS stage
+SELECT sqlpage.exec('sleep', '1');
+SELECT '80' AS percent, 'Sleeping 1 more second' AS stage;
+SELECT sqlpage.exec('sleep', '1');
+SELECT '90' AS percent, 'Sleeping 1 second again' AS stage;
+SELECT sqlpage.exec('sleep', '1');
 
-SELECT 'spinner-progress' AS component,
-  '100' AS percent;
+SELECT '100' AS percent;
 
-SELECT 'spinner-stop' AS component;
+SELECT 'loader-stop' AS component;
 
 SELECT 'text' AS component,
   'It works!' AS title,
   TRUE AS center,
   'Page is loaded.' AS contents;
+
+-- can use progress on it's own
+SELECT 'progress' AS component, 'Waiting for user' AS stage;
\ No newline at end of file
diff --git a/frontend/src/sqlpage.css b/frontend/src/sqlpage.css
index 407887f39..6f8edcf32 100644
--- a/frontend/src/sqlpage.css
+++ b/frontend/src/sqlpage.css
@@ -199,8 +199,8 @@ See https://github.com/tabler/tabler/issues/2404
   text-decoration: underline;
 }
 
-/* spinner container */
-div.sqlpage-spinner-start {
+/* loader container */
+div.sqlpage-loader-start {
   position: fixed;
   text-align: center;
   left: 50vw;
@@ -211,32 +211,35 @@ div.sqlpage-spinner-start {
   height: 9em;
   width: 175px;
 }
-div.sqlpage-spinner-start:not(:has(+ .sqlpage-spinner-stop)) {
-  /* only display if not followed by sqlpage-spinner-stop */
+div.sqlpage-loader-start:not(:has(+ .sqlpage-loader-stop)) {
+  /* only display if not followed by sqlpage-loader-stop */
   display: block;
 }
-.sqlpage-spinner-start:not(:last-child) {
+.sqlpage-loader-start:not(:last-child) {
   /* firefox doesn't support :has
-     so hide the spinner if is no longer the last element */
+     so hide the loader if it is no longer the last element */
   display: none;
 }
+/* end loader container */
 
-/* progress indicator container */
-div.sqlpage-spinner-progress {
+/* progress container */
+.sqlpage-progress-container {
   margin: 1em 0 1em;
 }
-div.sqlpage-spinner-progress:not(:has(+ .sqlpage-spinner-progress)) {
-  /* only display if not followed by progress update */
+div.sqlpage-progress-container:not(:has(+ .sqlpage-progress-container)) {
+  /* only display if not followed by sqlpage-progress-container */
   display: block;
 }
-.sqlpage-spinner-progress:not(:last-child) {
+.sqlpage-progress-container:not(:last-child) {
   /* firefox doesn't support :has
-     so hide the spinner if is no longer the last element */
+     so hide the loader if it is no longer the last element */
   display: none;
 }
-.sqlpage-spinner-progress label {
+.sqlpage-progress-container label {
   text-align:left;
+  color: var(--tblr-text-primary);
 }
-.sqlpage-spinner-progress label:after {
-  content: "...";
+.sqlpage-progress-container label:after {
+  content: "…";
 }
+/* end progress container */
\ No newline at end of file
diff --git a/sqlpage/templates/loader-start.handlebars b/sqlpage/templates/loader-start.handlebars
new file mode 100644
index 000000000..17d311a57
--- /dev/null
+++ b/sqlpage/templates/loader-start.handlebars
@@ -0,0 +1,2 @@
+<div {{#if id}}id="{{id}}"{{/if}} class="sqlpage-loader-start">
+  <span class="{{default spinner "spinner-border"}}"></span>
diff --git a/sqlpage/templates/loader-stop.handlebars b/sqlpage/templates/loader-stop.handlebars
new file mode 100644
index 000000000..791b7b848
--- /dev/null
+++ b/sqlpage/templates/loader-stop.handlebars
@@ -0,0 +1,2 @@
+</div>
+<div class="sqlpage-loader-stop" />
diff --git a/sqlpage/templates/progress.handlebars b/sqlpage/templates/progress.handlebars
new file mode 100644
index 000000000..64f83eb72
--- /dev/null
+++ b/sqlpage/templates/progress.handlebars
@@ -0,0 +1,44 @@
+{{#if (or percent stage)}}
+  <div class="sqlpage-progress-container">
+    <div class="progress {{~#if size}} progress-{{size}}{{/if}}">
+      <div
+        id="sqlpage-loading-{{default stage "progress"}}"
+        class="progress-bar
+        {{~#if (not percent)}} progress-bar-indeterminate{{/if}}
+        {{~#if color}} bg-{{color}}{{/if}}"
+        role="progressbar"
+        aria-valuenow="{{percent}}"
+        {{~#if percent}}style="width: {{percent}}%; display: block"{{/if}} 
+        aria-valuemin="0" aria-valuemax="100"
+        {{~#if stage}}aria-label="{{stage}}"{{/if}}>
+      </div>
+    </div>
+    {{~#if stage}}
+      <br>
+      <label for="sqlpage-loading-{{default stage "progress"}}">{{stage}}</label>
+    {{/if}}
+  </div>
+{{/if}}
+{{#each_row}}
+{{#if (or percent stage)}}
+  <div class="sqlpage-progress-container">
+    <div class="progress {{~#if ../size}} progress-{{../size}}{{/if}}">
+      <div
+        id="sqlpage-loading-{{default stage "progress"}}"
+        class="progress-bar
+        {{~#if (not percent)}} progress-bar-indeterminate{{/if}}
+        {{~#if ../color}} bg-{{../color}}{{/if}}"
+        role="progressbar"
+        aria-valuenow="{{percent}}"
+        {{~#if percent}}style="width: {{percent}}%; display: block"{{/if}} 
+        aria-valuemin="0" aria-valuemax="100"
+        {{~#if stage}}aria-label="{{stage}}"{{/if}}>
+      </div>
+    </div>
+    {{~#if stage}}
+      <br>
+      <label for="sqlpage-loading-{{default stage "progress"}}">{{stage}}</label>
+    {{/if}}
+  </div>
+{{/if}}
+{{/each_row}}
diff --git a/sqlpage/templates/spinner-progress.handlebars b/sqlpage/templates/spinner-progress.handlebars
deleted file mode 100644
index f2bf9ac39..000000000
--- a/sqlpage/templates/spinner-progress.handlebars
+++ /dev/null
@@ -1,7 +0,0 @@
-<div class="sqlpage-spinner-progress">
-  <progress id="sqlpage-loading-{{default stage "progress"}}" value="{{percent}}" max="100"></progress>
-  {{#if stage}}
-  <br/>
-  <label for="sqlpage-loading-{{stage}}">{{stage}}</label>
-  {{/if}}
-</div>
diff --git a/sqlpage/templates/spinner-start.handlebars b/sqlpage/templates/spinner-start.handlebars
deleted file mode 100644
index e37cb561d..000000000
--- a/sqlpage/templates/spinner-start.handlebars
+++ /dev/null
@@ -1,2 +0,0 @@
-<div {{#if id}}id="{{id}}"{{/if}} class="sqlpage-spinner-start">
-  <span class="{{default spinner "spinner-border"}}"></span>
diff --git a/sqlpage/templates/spinner-stop.handlebars b/sqlpage/templates/spinner-stop.handlebars
deleted file mode 100644
index 4f1b3527d..000000000
--- a/sqlpage/templates/spinner-stop.handlebars
+++ /dev/null
@@ -1,2 +0,0 @@
-</div>
-<div class="sqlpage-spinner-stop" />

From 5a7379d33bbfe82f3d511d4a3b367f3bf2d44ddf Mon Sep 17 00:00:00 2001
From: Daniel Sheffield <Daniel.Sheffield@first-watch.co.nz>
Date: Mon, 24 Jun 2024 12:19:04 +1200
Subject: [PATCH 06/15] fix whitespace

---
 examples/show-progress/index.sql | 2 +-
 frontend/src/sqlpage.css         | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/examples/show-progress/index.sql b/examples/show-progress/index.sql
index 7d86f1e30..8fa76191a 100644
--- a/examples/show-progress/index.sql
+++ b/examples/show-progress/index.sql
@@ -46,4 +46,4 @@ SELECT 'text' AS component,
   'Page is loaded.' AS contents;
 
 -- can use progress on it's own
-SELECT 'progress' AS component, 'Waiting for user' AS stage;
\ No newline at end of file
+SELECT 'progress' AS component, 'Waiting for user' AS stage;
diff --git a/frontend/src/sqlpage.css b/frontend/src/sqlpage.css
index 6f8edcf32..a7a046ab6 100644
--- a/frontend/src/sqlpage.css
+++ b/frontend/src/sqlpage.css
@@ -242,4 +242,4 @@ div.sqlpage-progress-container:not(:has(+ .sqlpage-progress-container)) {
 .sqlpage-progress-container label:after {
   content: "…";
 }
-/* end progress container */
\ No newline at end of file
+/* end progress container */

From b9091596f78b2b53874bf160c0263ea08fd34314 Mon Sep 17 00:00:00 2001
From: Daniel Sheffield <Daniel.Sheffield@first-watch.co.nz>
Date: Mon, 24 Jun 2024 12:34:01 +1200
Subject: [PATCH 07/15] add example of loader without spinner

---
 examples/show-progress/go.sql    | 13 +++++++++++++
 examples/show-progress/index.sql |  3 +++
 2 files changed, 16 insertions(+)
 create mode 100644 examples/show-progress/go.sql

diff --git a/examples/show-progress/go.sql b/examples/show-progress/go.sql
new file mode 100644
index 000000000..c571eead8
--- /dev/null
+++ b/examples/show-progress/go.sql
@@ -0,0 +1,13 @@
+-- can disable the spinner to show only progress bar
+SELECT 'loader-start' AS component,  'non-existent-class' AS spinner;
+
+SELECT 'progress' AS component,
+  NULL AS percent,
+  'sm' AS size,
+  'yellow' AS color,
+  'Working on it' AS stage;
+SELECT sqlpage.exec('sleep', '3');
+
+SELECT 'loader-stop' AS component,  NULL AS spinner;
+
+SELECT 'text' AS component, 'Processing complete.' AS contents;
\ No newline at end of file
diff --git a/examples/show-progress/index.sql b/examples/show-progress/index.sql
index 8fa76191a..383232907 100644
--- a/examples/show-progress/index.sql
+++ b/examples/show-progress/index.sql
@@ -45,5 +45,8 @@ SELECT 'text' AS component,
   TRUE AS center,
   'Page is loaded.' AS contents;
 
+SELECT 'button' AS component;
+SELECT 'Go' AS title, '/go.sql' AS link;
+
 -- can use progress on it's own
 SELECT 'progress' AS component, 'Waiting for user' AS stage;

From 63627f58291b60915211422d374ae31798d3f6ee Mon Sep 17 00:00:00 2001
From: Daniel Sheffield <Daniel.Sheffield@first-watch.co.nz>
Date: Mon, 24 Jun 2024 12:34:49 +1200
Subject: [PATCH 08/15] fix whitespace

---
 examples/show-progress/go.sql | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/examples/show-progress/go.sql b/examples/show-progress/go.sql
index c571eead8..f76924efb 100644
--- a/examples/show-progress/go.sql
+++ b/examples/show-progress/go.sql
@@ -10,4 +10,4 @@ SELECT sqlpage.exec('sleep', '3');
 
 SELECT 'loader-stop' AS component,  NULL AS spinner;
 
-SELECT 'text' AS component, 'Processing complete.' AS contents;
\ No newline at end of file
+SELECT 'text' AS component, 'Processing complete.' AS contents;

From c0544458fdc6ddc4d1afb7bcab90deda83b9c547 Mon Sep 17 00:00:00 2001
From: Daniel Sheffield <Daniel.Sheffield@first-watch.co.nz>
Date: Mon, 24 Jun 2024 13:43:22 +1200
Subject: [PATCH 09/15] no spinner if not specified

---
 examples/show-progress/go.sql             | 6 ++++--
 examples/show-progress/index.sql          | 9 ++++-----
 sqlpage/templates/loader-start.handlebars | 2 +-
 3 files changed, 9 insertions(+), 8 deletions(-)

diff --git a/examples/show-progress/go.sql b/examples/show-progress/go.sql
index f76924efb..3c2d8e2db 100644
--- a/examples/show-progress/go.sql
+++ b/examples/show-progress/go.sql
@@ -1,5 +1,7 @@
+SELECT 'shell' AS component, 'light' AS theme;
+
 -- can disable the spinner to show only progress bar
-SELECT 'loader-start' AS component,  'non-existent-class' AS spinner;
+SELECT 'loader-start' AS component,  NULL AS spinner;
 
 SELECT 'progress' AS component,
   NULL AS percent,
@@ -8,6 +10,6 @@ SELECT 'progress' AS component,
   'Working on it' AS stage;
 SELECT sqlpage.exec('sleep', '3');
 
-SELECT 'loader-stop' AS component,  NULL AS spinner;
+SELECT 'loader-stop' AS component;
 
 SELECT 'text' AS component, 'Processing complete.' AS contents;
diff --git a/examples/show-progress/index.sql b/examples/show-progress/index.sql
index 383232907..00d018fea 100644
--- a/examples/show-progress/index.sql
+++ b/examples/show-progress/index.sql
@@ -1,9 +1,8 @@
-SELECT 'shell' AS component,
-  'dark' AS theme;
+SELECT 'shell' AS component, 'dark' AS theme;
 
 SELECT 'loader-start' AS component,
-  -- default is "spinner-border"
-  "spinner-grow text-red" AS spinner;
+  -- pick from the tabler spinners: https://tabler.io/docs/components/spinners
+  "spinner-border spinner-border-sm text-red" AS spinner;
 
 SELECT 'progress' AS component,
   'sm' AS size,
@@ -49,4 +48,4 @@ SELECT 'button' AS component;
 SELECT 'Go' AS title, '/go.sql' AS link;
 
 -- can use progress on it's own
-SELECT 'progress' AS component, 'Waiting for user' AS stage;
+SELECT 'progress' AS component, 'sm' AS size, 'Waiting for user' AS stage;
diff --git a/sqlpage/templates/loader-start.handlebars b/sqlpage/templates/loader-start.handlebars
index 17d311a57..c121b02ef 100644
--- a/sqlpage/templates/loader-start.handlebars
+++ b/sqlpage/templates/loader-start.handlebars
@@ -1,2 +1,2 @@
 <div {{#if id}}id="{{id}}"{{/if}} class="sqlpage-loader-start">
-  <span class="{{default spinner "spinner-border"}}"></span>
+  {{#if spinner}}<span class="{{spinner}}"></span>{{/if}}

From ec4707c94acd0d38de3f3bfde1c904df12235606 Mon Sep 17 00:00:00 2001
From: Daniel Sheffield <Daniel.Sheffield@first-watch.co.nz>
Date: Wed, 26 Jun 2024 17:21:54 +1200
Subject: [PATCH 10/15] improve top-level params of spinner component and add
 documentation

---
 .../examples}/show-progress/README.md         |  0
 .../examples}/show-progress/go.sql            |  4 +-
 .../examples}/show-progress/index.sql         | 26 ++++----
 .../sqlpage/migrations/01_documentation.sql   | 64 +++++++++++++++++++
 examples/official-site/sqlpage/sqlpage.yaml   |  3 +
 examples/show-progress/sqlpage/sqlpage.yml    |  3 -
 sqlpage/templates/loader-start.handlebars     |  4 +-
 7 files changed, 86 insertions(+), 18 deletions(-)
 rename examples/{ => official-site/examples}/show-progress/README.md (100%)
 rename examples/{ => official-site/examples}/show-progress/go.sql (76%)
 rename examples/{ => official-site/examples}/show-progress/index.sql (62%)
 delete mode 100644 examples/show-progress/sqlpage/sqlpage.yml

diff --git a/examples/show-progress/README.md b/examples/official-site/examples/show-progress/README.md
similarity index 100%
rename from examples/show-progress/README.md
rename to examples/official-site/examples/show-progress/README.md
diff --git a/examples/show-progress/go.sql b/examples/official-site/examples/show-progress/go.sql
similarity index 76%
rename from examples/show-progress/go.sql
rename to examples/official-site/examples/show-progress/go.sql
index 3c2d8e2db..4fe5af94a 100644
--- a/examples/show-progress/go.sql
+++ b/examples/official-site/examples/show-progress/go.sql
@@ -1,14 +1,14 @@
 SELECT 'shell' AS component, 'light' AS theme;
 
 -- can disable the spinner to show only progress bar
-SELECT 'loader-start' AS component,  NULL AS spinner;
+SELECT 'loader-start' AS component,  '' AS spinner;
 
 SELECT 'progress' AS component,
   NULL AS percent,
   'sm' AS size,
   'yellow' AS color,
   'Working on it' AS stage;
-SELECT sqlpage.exec('sleep', '3');
+SELECT sqlpage.fetch('https://example.com');
 
 SELECT 'loader-stop' AS component;
 
diff --git a/examples/show-progress/index.sql b/examples/official-site/examples/show-progress/index.sql
similarity index 62%
rename from examples/show-progress/index.sql
rename to examples/official-site/examples/show-progress/index.sql
index 00d018fea..07dbb6d49 100644
--- a/examples/show-progress/index.sql
+++ b/examples/official-site/examples/show-progress/index.sql
@@ -2,14 +2,16 @@ SELECT 'shell' AS component, 'dark' AS theme;
 
 SELECT 'loader-start' AS component,
   -- pick from the tabler spinners: https://tabler.io/docs/components/spinners
-  "spinner-border spinner-border-sm text-red" AS spinner;
+  "spinner-border" spinner,
+  "sm" AS size,
+  "red" AS color;
 
 SELECT 'progress' AS component,
   'sm' AS size,
   'yellow' AS color,
   '0' AS percent,
-  'Sleeping 1 second' AS stage;
-SELECT sqlpage.exec('sleep', '1');
+  'Fething data' AS stage;
+SELECT sqlpage.fetch('https://example.com');
 
 /* percent property is optional */
 SELECT 'progress' AS component,
@@ -17,23 +19,23 @@ SELECT 'progress' AS component,
   'sm' AS size,
   'yellow' AS color,
   'Doing something' AS stage;
-SELECT sqlpage.exec('sleep', '1');
+SELECT sqlpage.fetch('https://example.com');
 
 /* stage property is optional */
 SELECT 'progress' AS component,
   'sm' AS size,
   'yellow' AS color,
   '40' AS percent;
-SELECT sqlpage.exec('sleep', '1');
+SELECT sqlpage.fetch('https://example.com');
 
 /* multiple rows */
 SELECT 'progress' AS component, 'sm' AS size, 'yellow' AS color;
-SELECT '70' AS percent, 'Sleeping 1 second' AS stage
-SELECT sqlpage.exec('sleep', '1');
-SELECT '80' AS percent, 'Sleeping 1 more second' AS stage;
-SELECT sqlpage.exec('sleep', '1');
-SELECT '90' AS percent, 'Sleeping 1 second again' AS stage;
-SELECT sqlpage.exec('sleep', '1');
+SELECT '70' AS percent, 'Fetching data' AS stage
+SELECT sqlpage.fetch('https://example.com');
+SELECT '80' AS percent, 'Fetching more data' AS stage;
+SELECT sqlpage.fetch('https://example.com');
+SELECT '90' AS percent, 'Fetching again' AS stage;
+SELECT sqlpage.fetch('https://example.com');
 
 SELECT '100' AS percent;
 
@@ -45,7 +47,7 @@ SELECT 'text' AS component,
   'Page is loaded.' AS contents;
 
 SELECT 'button' AS component;
-SELECT 'Go' AS title, '/go.sql' AS link;
+SELECT 'Go' AS title, './go.sql' AS link;
 
 -- can use progress on it's own
 SELECT 'progress' AS component, 'sm' AS size, 'Waiting for user' AS stage;
diff --git a/examples/official-site/sqlpage/migrations/01_documentation.sql b/examples/official-site/sqlpage/migrations/01_documentation.sql
index ce61b247a..0b6be64bb 100644
--- a/examples/official-site/sqlpage/migrations/01_documentation.sql
+++ b/examples/official-site/sqlpage/migrations/01_documentation.sql
@@ -1461,6 +1461,69 @@ GROUP BY name;
 ```
 ', NULL);
 
+INSERT INTO component(name, icon, description, introduced_in_version) VALUES
+    ('loader-start', 'refresh', 'Display a spinner to indicate page is loading.', '0.25.0');
+
+INSERT INTO parameter(component, name, description_md, type, top_level, optional) SELECT 'loader-start', * FROM (VALUES
+    ('spinner', '
+The name of a [spinner](https://tabler.io/docs/components/spinners) (from tabler.io).
+Default is "spinner-border".
+Set to the empty string to disable the spinner - e.g. to display only progress
+updates.
+', 'TEXT', TRUE, TRUE),
+    ('size', 'Size of the spinner eg. sm, lg', 'TEXT', TRUE, TRUE),
+    ('color', 'Color of the spinner', 'COLOR', TRUE, TRUE)
+) x;
+
+INSERT INTO component(name, icon, description, introduced_in_version) VALUES
+    ('loader-stop', 'refresh-off', '
+Hide the spinner displayed by the loader-start component.
+', '0.25.0');
+
+INSERT INTO component(name, icon, description, introduced_in_version) VALUES
+    ('progress', 'time-duration-15', 'Display a progress bar.', '0.25.0');
+
+INSERT INTO example(component, description, properties) VALUES
+    ('loader-start', '
+Will be displayed until [loader-stop](/documentation.sql?component=loader-stop) is selected.
+
+See the [live example](/examples/show-progress/).
+
+Source is [here](https://github.com/lovasoa/SQLpage/tree/main/examples/official-site/examples/show-progress)
+', NULL),
+    ('loader-stop', '
+Hide the spinner displayed by the [loader-start](/documentation.sql?component=loader-start) component.
+
+See the [live example](/examples/show-progress/).
+
+Source is [here](https://github.com/lovasoa/SQLpage/tree/main/examples/official-site/examples/show-progress)
+', NULL),
+    ('progress', '
+Can be used on it''s own (will persist on the page) or with
+[loader-start](/documentation.sql?component=loader-start) and
+[loader-stop](/documentation.sql?component=loader-stop) to hide the progress bar once processing
+is complete.
+
+Subsequent uses of this component and/or any rows will
+update the progress bar.
+
+See the [live example](/examples/show-progress/).
+
+Source is [here](https://github.com/lovasoa/SQLpage/tree/main/examples/official-site/examples/show-progress)
+', NULL)
+;
+
+INSERT INTO parameter(component, name, description_md, type, top_level, optional) SELECT 'progress', * FROM (VALUES
+    -- top-level
+    ('percent', 'Number between 0 and 100.', 'INTEGER', TRUE, TRUE),
+    ('stage', 'A message to display under the progress bar to indicate which stage the process is at.', 'TEXT', TRUE, TRUE),
+    ('color', 'The fill color of the progress bar', 'COLOR', TRUE, TRUE),
+    ('size', 'The size of the progress bar [see here](https://tabler.io/docs/components/progress)', 'TEXT', TRUE, TRUE),
+    -- item-level
+    ('percent', 'Number between 0 and 100.', 'INTEGER', FALSE, TRUE),
+    ('stage', 'A message to display under the progress bar to indicate which stage the process is at.', 'TEXT', FALSE, TRUE)
+) x;
+
 INSERT INTO component(name, icon, description) VALUES
     ('shell', 'layout-navbar', '
 Customize the overall layout, header and footer of the page.
@@ -1547,6 +1610,7 @@ You see the [page layouts demo](./examples/layouts.sql) for a live example of th
                     {"link": "/examples/multistep-form", "title": "Forms", "icon": "edit"},
                     {"link": "/examples/handle_picture_upload.sql", "title": "File uploads", "icon": "upload"},
                     {"link": "/examples/authentication/", "title": "Password protection", "icon": "password-user"},
+                    {"link": "/examples/show-progress/", "title": "Tracking progress of background tasks", "icon": "loader-2"},
                     {"link": "//github.com/sqlpage/SQLPage/blob/main/examples/", "title": "All examples & demos", "icon": "code"}
                 ]},
                 {"title": "Community", "submenu": [
diff --git a/examples/official-site/sqlpage/sqlpage.yaml b/examples/official-site/sqlpage/sqlpage.yaml
index 8d0cfbeb4..15ee360de 100644
--- a/examples/official-site/sqlpage/sqlpage.yaml
+++ b/examples/official-site/sqlpage/sqlpage.yaml
@@ -5,3 +5,6 @@ database_url: "sqlite::memory:?cache=shared"
 max_uploaded_file_size: 256000
 
 database_connection_acquire_timeout_seconds: 30
+
+# For the show-progress example to work, we have to disable compression
+compress_responses: False
diff --git a/examples/show-progress/sqlpage/sqlpage.yml b/examples/show-progress/sqlpage/sqlpage.yml
deleted file mode 100644
index d38d9a202..000000000
--- a/examples/show-progress/sqlpage/sqlpage.yml
+++ /dev/null
@@ -1,3 +0,0 @@
-allow_exec: True
-compress_responses: False
-database_url: "sqlite://:memory:"
diff --git a/sqlpage/templates/loader-start.handlebars b/sqlpage/templates/loader-start.handlebars
index c121b02ef..3538b3ad0 100644
--- a/sqlpage/templates/loader-start.handlebars
+++ b/sqlpage/templates/loader-start.handlebars
@@ -1,2 +1,4 @@
 <div {{#if id}}id="{{id}}"{{/if}} class="sqlpage-loader-start">
-  {{#if spinner}}<span class="{{spinner}}"></span>{{/if}}
+  {{#if spinner}}<span class="{{default spinner "spinner-border"}}
+    {{#if size}}spinner-border-{{size}}{{/if}}
+    {{#if color}}text-{{color}}{{/if}}"></span>{{/if}}

From f6e47299cc6af367bd631710f99c3f919835f4c5 Mon Sep 17 00:00:00 2001
From: Daniel Sheffield <d.j.yotta@gmail.com>
Date: Wed, 26 Jun 2024 18:48:25 +1200
Subject: [PATCH 11/15] use http_header component instead of disabling
 compression everywhere

---
 .../examples/show-progress/go.sql             |  4 ++++
 .../examples/show-progress/index.sql          |  4 ++++
 .../sqlpage/migrations/01_documentation.sql   | 24 +++++++++----------
 examples/official-site/sqlpage/sqlpage.yaml   |  3 ---
 4 files changed, 20 insertions(+), 15 deletions(-)

diff --git a/examples/official-site/examples/show-progress/go.sql b/examples/official-site/examples/show-progress/go.sql
index 4fe5af94a..5510ad097 100644
--- a/examples/official-site/examples/show-progress/go.sql
+++ b/examples/official-site/examples/show-progress/go.sql
@@ -1,3 +1,7 @@
+-- Disable actix-web compression middleware:
+--    https://github.com/actix/actix-web/issues/3410
+SELECT 'http_header' AS component, 'Identity' AS "Content-Encoding";
+
 SELECT 'shell' AS component, 'light' AS theme;
 
 -- can disable the spinner to show only progress bar
diff --git a/examples/official-site/examples/show-progress/index.sql b/examples/official-site/examples/show-progress/index.sql
index 07dbb6d49..94bee5e0e 100644
--- a/examples/official-site/examples/show-progress/index.sql
+++ b/examples/official-site/examples/show-progress/index.sql
@@ -1,3 +1,7 @@
+-- Disable actix-web compression middleware:
+--    https://github.com/actix/actix-web/issues/3410
+SELECT 'http_header' AS component, 'Identity' AS "Content-Encoding";
+
 SELECT 'shell' AS component, 'dark' AS theme;
 
 SELECT 'loader-start' AS component,
diff --git a/examples/official-site/sqlpage/migrations/01_documentation.sql b/examples/official-site/sqlpage/migrations/01_documentation.sql
index 0b6be64bb..732c1d326 100644
--- a/examples/official-site/sqlpage/migrations/01_documentation.sql
+++ b/examples/official-site/sqlpage/migrations/01_documentation.sql
@@ -1471,7 +1471,7 @@ Default is "spinner-border".
 Set to the empty string to disable the spinner - e.g. to display only progress
 updates.
 ', 'TEXT', TRUE, TRUE),
-    ('size', 'Size of the spinner eg. sm, lg', 'TEXT', TRUE, TRUE),
+    ('size', 'Size of the spinner (e.g. sm, lg) [see here](https://tabler.io/docs/components/progress)', 'TEXT', TRUE, TRUE),
     ('color', 'Color of the spinner', 'COLOR', TRUE, TRUE)
 ) x;
 
@@ -1483,6 +1483,17 @@ Hide the spinner displayed by the loader-start component.
 INSERT INTO component(name, icon, description, introduced_in_version) VALUES
     ('progress', 'time-duration-15', 'Display a progress bar.', '0.25.0');
 
+INSERT INTO parameter(component, name, description_md, type, top_level, optional) SELECT 'progress', * FROM (VALUES
+    -- top-level
+    ('percent', 'Number between 0 and 100.', 'INTEGER', TRUE, TRUE),
+    ('stage', 'A message to display under the progress bar to indicate which stage the process is at.', 'TEXT', TRUE, TRUE),
+    ('color', 'The fill color of the progress bar', 'COLOR', TRUE, TRUE),
+    ('size', 'The size of the progress bar (e.g. sm, lg) [see here](https://tabler.io/docs/components/progress)', 'TEXT', TRUE, TRUE),
+    -- item-level
+    ('percent', 'Number between 0 and 100.', 'INTEGER', FALSE, TRUE),
+    ('stage', 'A message to display under the progress bar to indicate which stage the process is at.', 'TEXT', FALSE, TRUE)
+) x;
+
 INSERT INTO example(component, description, properties) VALUES
     ('loader-start', '
 Will be displayed until [loader-stop](/documentation.sql?component=loader-stop) is selected.
@@ -1513,17 +1524,6 @@ Source is [here](https://github.com/lovasoa/SQLpage/tree/main/examples/official-
 ', NULL)
 ;
 
-INSERT INTO parameter(component, name, description_md, type, top_level, optional) SELECT 'progress', * FROM (VALUES
-    -- top-level
-    ('percent', 'Number between 0 and 100.', 'INTEGER', TRUE, TRUE),
-    ('stage', 'A message to display under the progress bar to indicate which stage the process is at.', 'TEXT', TRUE, TRUE),
-    ('color', 'The fill color of the progress bar', 'COLOR', TRUE, TRUE),
-    ('size', 'The size of the progress bar [see here](https://tabler.io/docs/components/progress)', 'TEXT', TRUE, TRUE),
-    -- item-level
-    ('percent', 'Number between 0 and 100.', 'INTEGER', FALSE, TRUE),
-    ('stage', 'A message to display under the progress bar to indicate which stage the process is at.', 'TEXT', FALSE, TRUE)
-) x;
-
 INSERT INTO component(name, icon, description) VALUES
     ('shell', 'layout-navbar', '
 Customize the overall layout, header and footer of the page.
diff --git a/examples/official-site/sqlpage/sqlpage.yaml b/examples/official-site/sqlpage/sqlpage.yaml
index 15ee360de..8d0cfbeb4 100644
--- a/examples/official-site/sqlpage/sqlpage.yaml
+++ b/examples/official-site/sqlpage/sqlpage.yaml
@@ -5,6 +5,3 @@ database_url: "sqlite::memory:?cache=shared"
 max_uploaded_file_size: 256000
 
 database_connection_acquire_timeout_seconds: 30
-
-# For the show-progress example to work, we have to disable compression
-compress_responses: False

From 416240bf33b18fd2bc64c7f6bd4714e4bba643dc Mon Sep 17 00:00:00 2001
From: Daniel Sheffield <d.j.yotta@gmail.com>
Date: Wed, 26 Jun 2024 19:14:48 +1200
Subject: [PATCH 12/15] fix styling when errors while loading and simplify css

---
 frontend/src/sqlpage.css                  | 31 ++++++++++++-----------
 sqlpage/templates/loader-start.handlebars |  1 +
 sqlpage/templates/loader-stop.handlebars  |  3 ++-
 3 files changed, 19 insertions(+), 16 deletions(-)

diff --git a/frontend/src/sqlpage.css b/frontend/src/sqlpage.css
index a7a046ab6..18a775089 100644
--- a/frontend/src/sqlpage.css
+++ b/frontend/src/sqlpage.css
@@ -200,7 +200,7 @@ See https://github.com/tabler/tabler/issues/2404
 }
 
 /* loader container */
-div.sqlpage-loader-start {
+.sqlpage-loader-container {
   position: fixed;
   text-align: center;
   left: 50vw;
@@ -211,13 +211,19 @@ div.sqlpage-loader-start {
   height: 9em;
   width: 175px;
 }
-div.sqlpage-loader-start:not(:has(+ .sqlpage-loader-stop)) {
-  /* only display if not followed by sqlpage-loader-stop */
-  display: block;
-}
-.sqlpage-loader-start:not(:last-child) {
-  /* firefox doesn't support :has
-     so hide the loader if it is no longer the last element */
+.sqlpage-loader-container:has(.status) {
+  position: inherit;
+  text-align: inherit;
+  left: inherit;
+  top: inherit;
+  margin-top: inherit;
+  margin-left: inherit;
+  padding-bottom: inherit;
+  height: inherit;
+  width: inherit;
+}
+div.sqlpage-loader-start:has(+ .sqlpage-loader-stop) {
+  /* hide if followed by sqlpage-loader-stop */
   display: none;
 }
 /* end loader container */
@@ -226,13 +232,8 @@ div.sqlpage-loader-start:not(:has(+ .sqlpage-loader-stop)) {
 .sqlpage-progress-container {
   margin: 1em 0 1em;
 }
-div.sqlpage-progress-container:not(:has(+ .sqlpage-progress-container)) {
-  /* only display if not followed by sqlpage-progress-container */
-  display: block;
-}
-.sqlpage-progress-container:not(:last-child) {
-  /* firefox doesn't support :has
-     so hide the loader if it is no longer the last element */
+div.sqlpage-progress-container:has(+ .sqlpage-progress-container) {
+  /* hide if followed by sqlpage-progress-container */
   display: none;
 }
 .sqlpage-progress-container label {
diff --git a/sqlpage/templates/loader-start.handlebars b/sqlpage/templates/loader-start.handlebars
index 3538b3ad0..1b4ebc552 100644
--- a/sqlpage/templates/loader-start.handlebars
+++ b/sqlpage/templates/loader-start.handlebars
@@ -1,4 +1,5 @@
 <div {{#if id}}id="{{id}}"{{/if}} class="sqlpage-loader-start">
+  <div class="sqlpage-loader-container">
   {{#if spinner}}<span class="{{default spinner "spinner-border"}}
     {{#if size}}spinner-border-{{size}}{{/if}}
     {{#if color}}text-{{color}}{{/if}}"></span>{{/if}}
diff --git a/sqlpage/templates/loader-stop.handlebars b/sqlpage/templates/loader-stop.handlebars
index 791b7b848..d7b5b010b 100644
--- a/sqlpage/templates/loader-stop.handlebars
+++ b/sqlpage/templates/loader-stop.handlebars
@@ -1,2 +1,3 @@
+  </div>
 </div>
-<div class="sqlpage-loader-stop" />
+<div class="sqlpage-loader-stop"></div>

From ed03b1eadde4ba57b049f1cd2474fa0c2cef3d71 Mon Sep 17 00:00:00 2001
From: Daniel Sheffield <d.j.yotta@gmail.com>
Date: Wed, 26 Jun 2024 20:07:34 +1200
Subject: [PATCH 13/15] Update loader-start.handlebars

Fix spinner defaults
---
 sqlpage/templates/loader-start.handlebars | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/sqlpage/templates/loader-start.handlebars b/sqlpage/templates/loader-start.handlebars
index 1b4ebc552..84d8873f3 100644
--- a/sqlpage/templates/loader-start.handlebars
+++ b/sqlpage/templates/loader-start.handlebars
@@ -1,5 +1,6 @@
 <div {{#if id}}id="{{id}}"{{/if}} class="sqlpage-loader-start">
   <div class="sqlpage-loader-container">
-  {{#if spinner}}<span class="{{default spinner "spinner-border"}}
-    {{#if size}}spinner-border-{{size}}{{/if}}
-    {{#if color}}text-{{color}}{{/if}}"></span>{{/if}}
+    <span class="{{default spinner "spinner-border"}}
+      {{#if size}}spinner-border-{{size}}{{/if}}
+      {{#if color}}text-{{color}}{{/if}}">
+    </span>

From 0a680b4c06bf88e4561cd9a763dbeb99990e1ca9 Mon Sep 17 00:00:00 2001
From: Daniel Sheffield <d.j.yotta@gmail.com>
Date: Thu, 27 Jun 2024 01:10:53 +1200
Subject: [PATCH 14/15] always show progress bar at top-level component

---
 sqlpage/templates/progress.handlebars | 36 +++++++++++++--------------
 1 file changed, 17 insertions(+), 19 deletions(-)

diff --git a/sqlpage/templates/progress.handlebars b/sqlpage/templates/progress.handlebars
index 64f83eb72..24214c98a 100644
--- a/sqlpage/templates/progress.handlebars
+++ b/sqlpage/templates/progress.handlebars
@@ -1,24 +1,22 @@
-{{#if (or percent stage)}}
-  <div class="sqlpage-progress-container">
-    <div class="progress {{~#if size}} progress-{{size}}{{/if}}">
-      <div
-        id="sqlpage-loading-{{default stage "progress"}}"
-        class="progress-bar
-        {{~#if (not percent)}} progress-bar-indeterminate{{/if}}
-        {{~#if color}} bg-{{color}}{{/if}}"
-        role="progressbar"
-        aria-valuenow="{{percent}}"
-        {{~#if percent}}style="width: {{percent}}%; display: block"{{/if}} 
-        aria-valuemin="0" aria-valuemax="100"
-        {{~#if stage}}aria-label="{{stage}}"{{/if}}>
-      </div>
+<div class="sqlpage-progress-container">
+  <div class="progress {{~#if size}} progress-{{size}}{{/if}}">
+    <div
+      id="sqlpage-loading-{{default stage "progress"}}"
+      class="progress-bar
+      {{~#if (not percent)}} progress-bar-indeterminate{{/if}}
+      {{~#if color}} bg-{{color}}{{/if}}"
+      role="progressbar"
+      aria-valuenow="{{percent}}"
+      {{~#if percent}}style="width: {{percent}}%; display: block"{{/if}} 
+      aria-valuemin="0" aria-valuemax="100"
+      {{~#if stage}}aria-label="{{stage}}"{{/if}}>
     </div>
-    {{~#if stage}}
-      <br>
-      <label for="sqlpage-loading-{{default stage "progress"}}">{{stage}}</label>
-    {{/if}}
   </div>
-{{/if}}
+  {{~#if stage}}
+    <br>
+    <label for="sqlpage-loading-{{default stage "progress"}}">{{stage}}</label>
+  {{/if}}
+</div>
 {{#each_row}}
 {{#if (or percent stage)}}
   <div class="sqlpage-progress-container">

From 0bd66fb82be06cb91677effb88e0b5bd508dbeca Mon Sep 17 00:00:00 2001
From: Ophir LOJKINE <lovasoa@users.noreply.github.com>
Date: Sun, 27 Sep 2026 06:48:23 +0000
Subject: [PATCH 15/15] Validate loader and progress components on current
 frontend

---
 CHANGELOG.md                                      |  1 +
 .../sqlpage/migrations/01_documentation.sql       |  7 ++++---
 frontend/src/sqlpage.css                          |  2 +-
 sqlpage/templates/progress.handlebars             |  4 ++--
 tests/end-to-end/fixtures/progress/index.sql      |  9 +++++++++
 tests/end-to-end/fixtures/progress/test.ts        | 15 +++++++++++++++
 6 files changed, 32 insertions(+), 6 deletions(-)
 create mode 100644 tests/end-to-end/fixtures/progress/index.sql
 create mode 100644 tests/end-to-end/fixtures/progress/test.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index df2786e9b..707560fa6 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,6 +1,7 @@
 # CHANGELOG.md
 
 ## v0.47.0 (unreleased)
+- Added loading indicators and progress bars for pages that stream results while queries run.
 - **Mac users:** the downloadable `sqlpage-macos.tgz` now runs natively on Apple silicon (M-series Macs) and no longer runs on Intel Macs. Homebrew remains the recommended and easiest installation method. On an Intel Mac, [install Homebrew](https://brew.sh/) if needed, then run `brew install sqlpage` (or `brew update` followed by `brew upgrade sqlpage` if you already installed it with Homebrew). Open Terminal in your existing website folder and run `sqlpage` instead of `./sqlpage.bin`; keep your SQL files, database, and `sqlpage` configuration folder in place. Intel installations may build from source and take longer; see the [macOS installation guide](https://sql-page.com/your-first-sql-website/?os=macos#download) for setup and older macOS requirements.
 - Updated sqlx-oldapi to v0.6.57 to fix SQL Server fallback expressions such as `ISNULL($missing, 'default')` truncating defaults or failing for date values when the bound variable is `NULL`.
 - Fixed MSSQL `JSON_OBJECT('key': value)` expressions being rejected by SQLPage's parser, including when used in `SET` statements or nested in `sqlpage.*` function calls.
diff --git a/examples/official-site/sqlpage/migrations/01_documentation.sql b/examples/official-site/sqlpage/migrations/01_documentation.sql
index 732c1d326..2c3b306c7 100644
--- a/examples/official-site/sqlpage/migrations/01_documentation.sql
+++ b/examples/official-site/sqlpage/migrations/01_documentation.sql
@@ -1462,9 +1462,10 @@ GROUP BY name;
 ', NULL);
 
 INSERT INTO component(name, icon, description, introduced_in_version) VALUES
-    ('loader-start', 'refresh', 'Display a spinner to indicate page is loading.', '0.25.0');
+    ('loader-start', 'refresh', 'Display a spinner to indicate page is loading.', '0.47.0');
 
 INSERT INTO parameter(component, name, description_md, type, top_level, optional) SELECT 'loader-start', * FROM (VALUES
+    ('id', 'HTML identifier for the loading container.', 'TEXT', TRUE, TRUE),
     ('spinner', '
 The name of a [spinner](https://tabler.io/docs/components/spinners) (from tabler.io).
 Default is "spinner-border".
@@ -1478,10 +1479,10 @@ updates.
 INSERT INTO component(name, icon, description, introduced_in_version) VALUES
     ('loader-stop', 'refresh-off', '
 Hide the spinner displayed by the loader-start component.
-', '0.25.0');
+', '0.47.0');
 
 INSERT INTO component(name, icon, description, introduced_in_version) VALUES
-    ('progress', 'time-duration-15', 'Display a progress bar.', '0.25.0');
+    ('progress', 'time-duration-15', 'Display a progress bar.', '0.47.0');
 
 INSERT INTO parameter(component, name, description_md, type, top_level, optional) SELECT 'progress', * FROM (VALUES
     -- top-level
diff --git a/frontend/src/sqlpage.css b/frontend/src/sqlpage.css
index 18a775089..edb06bf1a 100644
--- a/frontend/src/sqlpage.css
+++ b/frontend/src/sqlpage.css
@@ -237,7 +237,7 @@ div.sqlpage-progress-container:has(+ .sqlpage-progress-container) {
   display: none;
 }
 .sqlpage-progress-container label {
-  text-align:left;
+  text-align: left;
   color: var(--tblr-text-primary);
 }
 .sqlpage-progress-container label:after {
diff --git a/sqlpage/templates/progress.handlebars b/sqlpage/templates/progress.handlebars
index 24214c98a..d7340c3a0 100644
--- a/sqlpage/templates/progress.handlebars
+++ b/sqlpage/templates/progress.handlebars
@@ -7,7 +7,7 @@
       {{~#if color}} bg-{{color}}{{/if}}"
       role="progressbar"
       aria-valuenow="{{percent}}"
-      {{~#if percent}}style="width: {{percent}}%; display: block"{{/if}} 
+      {{~#if percent}}style="width: {{percent}}%; display: block"{{/if}}
       aria-valuemin="0" aria-valuemax="100"
       {{~#if stage}}aria-label="{{stage}}"{{/if}}>
     </div>
@@ -28,7 +28,7 @@
         {{~#if ../color}} bg-{{../color}}{{/if}}"
         role="progressbar"
         aria-valuenow="{{percent}}"
-        {{~#if percent}}style="width: {{percent}}%; display: block"{{/if}} 
+        {{~#if percent}}style="width: {{percent}}%; display: block"{{/if}}
         aria-valuemin="0" aria-valuemax="100"
         {{~#if stage}}aria-label="{{stage}}"{{/if}}>
       </div>
diff --git a/tests/end-to-end/fixtures/progress/index.sql b/tests/end-to-end/fixtures/progress/index.sql
new file mode 100644
index 000000000..39f57c33f
--- /dev/null
+++ b/tests/end-to-end/fixtures/progress/index.sql
@@ -0,0 +1,9 @@
+SELECT 'shell' AS component, 'Progress test' AS title;
+
+SELECT 'loader-start' AS component, 'completed-loader' AS id;
+SELECT 'loader-stop' AS component;
+
+SELECT 'progress' AS component, 25 AS percent, 'blue' AS color;
+SELECT 100 AS percent;
+
+SELECT 'loader-start' AS component, 'active-loader' AS id, 'red' AS color;
diff --git a/tests/end-to-end/fixtures/progress/test.ts b/tests/end-to-end/fixtures/progress/test.ts
new file mode 100644
index 000000000..12c134d26
--- /dev/null
+++ b/tests/end-to-end/fixtures/progress/test.ts
@@ -0,0 +1,15 @@
+import { expect, test } from "../../fixture";
+
+test("stops completed loaders and shows only the latest progress", async ({
+  page,
+}) => {
+  await expect(page.locator("#completed-loader")).toBeHidden();
+  await expect(page.locator("#active-loader .spinner-border")).toBeVisible();
+  await expect(
+    page.locator(".sqlpage-progress-container").first(),
+  ).toBeHidden();
+  const progress = page.getByRole("progressbar");
+  await expect(progress).toHaveCount(1);
+  await expect(progress).toHaveAttribute("aria-valuenow", "100");
+  await expect(progress).toHaveClass(/bg-blue/);
+});