#435: show spinner indicating page is loading

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.

examples/official-site/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.

examples/official-site/examples/show-progress/go.sql

@@ -0,0 +1,19 @@
+-- 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
+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.fetch('https://example.com');
+
+SELECT 'loader-stop' AS component;
+
+SELECT 'text' AS component, 'Processing complete.' AS contents;

examples/official-site/examples/show-progress/index.sql

@@ -0,0 +1,57 @@
+-- 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,
+  -- pick from the tabler spinners: https://tabler.io/docs/components/spinners
+  "spinner-border" spinner,
+  "sm" AS size,
+  "red" AS color;
+
+SELECT 'progress' AS component,
+  'sm' AS size,
+  'yellow' AS color,
+  '0' AS percent,
+  'Fething data' AS stage;
+SELECT sqlpage.fetch('https://example.com');
+
+/* percent property is optional */
+SELECT 'progress' AS component,
+  NULL AS percent,
+  'sm' AS size,
+  'yellow' AS color,
+  'Doing something' AS stage;
+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.fetch('https://example.com');
+
+/* multiple rows */
+SELECT 'progress' AS component, 'sm' AS size, 'yellow' AS color;
+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;
+
+SELECT 'loader-stop' AS component;
+
+SELECT 'text' AS component,
+  'It works!' AS title,
+  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, 'sm' AS size, 'Waiting for user' AS stage;

examples/official-site/sqlpage/migrations/01_documentation.sql

@@ -1461,6 +1461,70 @@ 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.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".
+Set to the empty string to disable the spinner - e.g. to display only progress
+updates.
+', '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;
+
+INSERT INTO component(name, icon, description, introduced_in_version) VALUES
+    ('loader-stop', 'refresh-off', '
+Hide the spinner displayed by the loader-start component.
+', '0.47.0');
+
+INSERT INTO component(name, icon, description, introduced_in_version) VALUES
+    ('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
+    ('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.
+
+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 component(name, icon, description) VALUES
     ('shell', 'layout-navbar', '
 Customize the overall layout, header and footer of the page.
@@ -1547,6 +1611,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": [

frontend/src/sqlpage.css

@@ -198,3 +198,49 @@ See https://github.com/tabler/tabler/issues/2404
   color: inherit;
   text-decoration: underline;
 }
+
+/* loader container */
+.sqlpage-loader-container {
+  position: fixed;
+  text-align: center;
+  left: 50vw;
+  top: 50vh;
+  margin-top: -5.5em;
+  margin-left: -87.5px;
+  padding-bottom: 2em;
+  height: 9em;
+  width: 175px;
+}
+.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 */
+
+/* progress container */
+.sqlpage-progress-container {
+  margin: 1em 0 1em;
+}
+div.sqlpage-progress-container:has(+ .sqlpage-progress-container) {
+  /* hide if followed by sqlpage-progress-container */
+  display: none;
+}
+.sqlpage-progress-container label {
+  text-align: left;
+  color: var(--tblr-text-primary);
+}
+.sqlpage-progress-container label:after {
+  content: "…";
+}
+/* end progress container */

sqlpage/templates/loader-start.handlebars

@@ -0,0 +1,6 @@
+<div {{#if id}}id="{{id}}"{{/if}} class="sqlpage-loader-start">
+  <div class="sqlpage-loader-container">
+    <span class="{{default spinner "spinner-border"}}
+      {{#if size}}spinner-border-{{size}}{{/if}}
+      {{#if color}}text-{{color}}{{/if}}">
+    </span>

sqlpage/templates/loader-stop.handlebars

@@ -0,0 +1,3 @@
+  </div>
+</div>
+<div class="sqlpage-loader-stop"></div>

sqlpage/templates/progress.handlebars

@@ -0,0 +1,42 @@
+<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>
+{{#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}}

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;

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/);
+});