Add stacked toast notification component

CHANGELOG.md

@@ -3,6 +3,7 @@
 ## unreleased
 
  - AWS Lambda builds and documentation now use the supported Amazon Linux 2023 custom runtime instead of the end-of-life Amazon Linux 2 runtime. Release artifacts include the configuration directory required on Lambda's read-only filesystem.
+ - Added a `toast` component with plain-text or Markdown content, icons, colors, six screen placements, configurable auto-dismiss timing, optional manual dismissal, URL-fragment triggers, and automatic stacking of queued notifications.
  - `sqlpage.send_mail` now supports rich email bodies. Use `body_html` for a caller-provided HTML alternative, or `body_md` to render Markdown as HTML. Messages retain a plain-text alternative; `body` may be omitted when `body_md` is used, and `body_md` and `body_html` cannot be combined.
  - Form `options_source` URLs now preserve existing query parameters when adding the dynamic `search` parameter.
 

examples/CRUD - Authentication/www/currencies_item_form.sql

@@ -279,12 +279,11 @@ SELECT                                                  -- DELETE button
 -- =============================================================================
 
 SELECT
-    'alert'          AS component,
+    'toast'          AS component,
     'green'          AS color,
     'check'          AS icon,
     'Success'        AS title,
-    $info            AS description,
-    True             AS dismissible
+    $info            AS description
 WHERE $info IS NOT NULL;
 
 -- =============================================================================

examples/CRUD - Authentication/www/currencies_list.sql

@@ -24,12 +24,11 @@ set _item_form = 'currencies_item_form.sql';
 -- =============================================================================
 
 SELECT
-    'alert'         AS component,
+    'toast'         AS component,
     'green'         AS color,
     'check'         AS icon,
     'Success'       AS title,
-    $info           AS description,
-    TRUE            AS dismissible
+    $info           AS description
 WHERE $info IS NOT NULL;
 
 -- =============================================================================

examples/custom form component/form_action.sql

@@ -15,7 +15,10 @@ from json_table(
     '$[*]' columns (id int path '$')
 ) as submitted_items;
 
-select 'alert' as component, 'Group members successfully updated !' as title, 'success' as color;
+select 'toast' as component,
+    'Group members successfully updated !' as title,
+    'green' as color,
+    'check' as icon;
 
 select 'list' as component, 'Users in this group' as title;
 
@@ -25,4 +28,4 @@ join group_members on users.id = group_members.user_id
 where group_members.group_id = 1;
 
 select 'button' as component;
-select 'Go back' as title, 'index.sql' as link;
+select 'Go back' as title, 'index.sql' as link;

examples/multiple-choice-question/admin.sql

@@ -1,7 +1,9 @@
 select 'dynamic' as component, sqlpage.read_file_as_text('website_header.json') as properties;
 
-select 'alert' as component, 'Saved' as title, 'success' as color where $saved is not null;
-select 'alert' as component, 'Deleted' as title, 'danger' as color where $deleted is not null;
+-- Successful actions are transient feedback, so they use toasts instead of occupying page content.
+select 'toast' as component, 'Saved' as title, 'green' as color, 'check' as icon where $saved is not null;
+select 'toast' as component, 'Deleted' as title, 'green' as color, 'trash' as icon where $deleted is not null;
+-- A failed deletion needs the user's attention and remains an inline alert.
 select 'alert' as component, 'This option cannot be deleted' as title, 'danger' as color, 'If an option has already been chosen by at least one respondant, then it cannot be deleted' as description where $cannot_delete is not null;
 
 select 'dynamic' as component,
@@ -33,4 +35,4 @@ select 'dynamic' as component,
 from dog_lover_profiles;
 
 select 'button' as component, 'center' as justify;
-select 'Create new question' as title, 'create_question.sql' as link;
+select 'Create new question' as title, 'create_question.sql' as link;

examples/official-site/sqlpage/migrations/76_toast.sql

@@ -0,0 +1,49 @@
+INSERT INTO component(name, icon, description, introduced_in_version) VALUES
+    ('toast', 'notification', '
+Displays a brief notification above the page. Each top-level `toast` row creates one notification, and consecutive toasts at the same position are queued in a shared stack.
+
+Ordinary notifications use `role="status"` and `aria-live="polite"`. Colored variants retain a readable contrasting foreground. Automatic dismissal and the optional manual close control are configured independently.', '0.46.0');
+
+INSERT INTO parameter(component, name, description, type, top_level, optional) SELECT 'toast', * FROM (VALUES
+    ('title', 'Optional notification heading.', 'TEXT', TRUE, TRUE),
+    ('description', 'Escaped plain-text body. This is used only when `description_md` is not supplied.', 'TEXT', TRUE, TRUE),
+    ('description_md', 'Rich-text alternative to `description`, rendered as Markdown. When both properties are supplied, `description_md` takes precedence.', 'TEXT', TRUE, TRUE),
+    ('icon', 'Optional [Tabler icon](https://tabler.io/icons) name.', 'ICON', TRUE, TRUE),
+    ('color', 'Optional Tabler color. The default is the neutral toast appearance; colored variants use the matching contrasting foreground utility.', 'COLOR', TRUE, TRUE),
+    ('dismissible', 'Whether to render an accessible manual close button. Defaults to false and is independent of automatic dismissal.', 'BOOLEAN', TRUE, TRUE),
+    ('duration', 'Automatic dismissal delay in milliseconds. Defaults to 5000. Set to 0 to keep the toast visible until manually dismissed (when `dismissible` is true) or the page is left.', 'INTEGER', TRUE, TRUE),
+    ('position', 'Screen placement: `top-start`, `top-center`, `top-end`, `bottom-start`, `bottom-center`, or `bottom-end`. Defaults to `top-end`; invalid values safely fall back to that default.', 'TEXT', TRUE, TRUE),
+    ('trigger', 'Optional URL fragment that opens the toast without reloading the page, with or without the leading `#`. When set, the toast does not open on page load and can be opened repeatedly by a link or button whose target is that fragment. Multiple toasts can share a trigger to open as a stack.', 'TEXT', TRUE, TRUE),
+    ('id', 'Optional stable HTML ID for the toast.', 'TEXT', TRUE, TRUE),
+    ('class', 'Optional custom CSS class appended to the toast.', 'TEXT', TRUE, TRUE)
+) x;
+
+INSERT INTO example(component, description, properties) VALUES
+    ('toast', 'A “Changes saved” confirmation that disappears automatically after the default 5000 milliseconds.', json('[
+        {"component":"toast","id":"toast-auto","title":"Changes saved","description":"Your changes have been saved.","icon":"check","color":"green"}
+    ]')),
+    ('toast', 'A persistent error notification that disables automatic dismissal and requires the user to activate its close button.', json('[
+        {"component":"toast","id":"toast-dismissible","trigger":"persistent-error","title":"Could not save","description":"Review the highlighted fields and try again.","icon":"alert-triangle","color":"red","duration":0,"dismissible":true},
+        {"component":"toast","id":"toast-nondismissible","trigger":"persistent-status","title":"Connection unavailable","description":"This persistent notification has no manual close control.","duration":0,"dismissible":false},
+        {"component":"button"},
+        {"title":"Show dismissible error","link":"#persistent-error","color":"red"},
+        {"title":"Show non-dismissible status","link":"#persistent-status"}
+    ]')),
+    ('toast', 'A persistent rich Markdown notification. Markdown takes precedence over plain text and renders emphasis and a link as HTML, while plain-text content remains escaped.', json('[
+        {"component":"toast","id":"toast-markdown","trigger":"rich-notifications","title":"Release available","description":"<strong>This fallback stays escaped</strong>","description_md":"Version **2.0** is ready. [Read the notes](https://example.com/releases).","duration":0},
+        {"component":"toast","id":"toast-plain","trigger":"rich-notifications","description":"<strong>Plain text stays escaped</strong>","duration":0},
+        {"component":"button"},
+        {"title":"Show rich notifications","link":"#rich-notifications"}
+    ]')),
+    ('toast', 'Several persistent queued notifications. Toasts with the same position share a container and stack instead of overlapping.', json('[
+        {"component":"toast","id":"toast-stack-one","trigger":"queued-notifications","title":"Import started","description":"Preparing records.","duration":0},
+        {"component":"toast","id":"toast-stack-two","trigger":"queued-notifications","title":"Import running","description":"Processing records.","duration":0},
+        {"component":"toast","id":"toast-short","trigger":"queued-notifications","title":"Temporary update","description":"This message closes shortly.","duration":2000},
+        {"component":"button"},
+        {"title":"Show queued notifications","link":"#queued-notifications"}
+    ]')),
+    ('toast', 'A notification placed at the bottom center of the screen instead of the default top end.', json('[
+        {"component":"toast","id":"toast-bottom-center","trigger":"bottom-notification","title":"Download ready","description":"Your export is ready.","position":"bottom-center","duration":0},
+        {"component":"button"},
+        {"title":"Show bottom notification","link":"#bottom-notification"}
+    ]'));

examples/todo application (PostgreSQL)/batch.sql

@@ -45,14 +45,16 @@ with updated as (
     -- Return all updated rows for counting and potential further use
     returning *
 )
--- Generate an alert component to inform the user about the update result
+-- Generate a toast component to inform the user about the update result
 -- This provides immediate feedback on the operation's outcome
-select 'alert' as component,
+select 'toast' as component,
+    'green' as color,
+    'check' as icon,
     'Batch update' as title,    
     -- Create a dynamic message with the count of updated todos
     format('%s todos updated', (select count(*) from updated)) as description
--- Only display the alert if at least one todo was updated
--- This prevents showing unnecessary alerts for no-op updates
+-- Only display the toast if at least one todo was updated
+-- This prevents showing unnecessary toasts for no-op updates
 where exists (select * from updated);
 
 -- Create a form component for the batch update interface
@@ -95,4 +97,4 @@ select 'new_label' as name, 'New label' as label;
 
 -- Create a checkbox for optionally removing existing labels
 -- This gives users the choice to strip old labels before adding a new one
-select 'checkbox' as type, 'Remove previous labels' as label, 'remove_label' as name;
+select 'checkbox' as type, 'Remove previous labels' as label, 'remove_label' as name;

sqlpage/sqlpage.js

@@ -325,11 +325,127 @@ function add_init_fn(f) {
   if (document.readyState !== "loading") setTimeout(f, 0);
 }
 
+const toast_positions = {
+  "top-start": ["top-0", "start-0"],
+  "top-center": ["top-0", "start-50", "translate-middle-x"],
+  "top-end": ["top-0", "end-0"],
+  "bottom-start": ["bottom-0", "start-0"],
+  "bottom-center": ["bottom-0", "start-50", "translate-middle-x"],
+  "bottom-end": ["bottom-0", "end-0"],
+};
+const toast_instances = new WeakMap();
+
+function normalize_hash(hash) {
+  const normalized = hash?.replace(/^#/, "");
+  if (!normalized) return normalized;
+  try {
+    return decodeURIComponent(normalized);
+  } catch {
+    return normalized;
+  }
+}
+
+function restore_focus_after_toast(toast, container) {
+  if (!toast.contains(document.activeElement)) return;
+  const next_close = [
+    ...container.querySelectorAll('.toast.show [data-bs-dismiss="toast"]'),
+  ].find((button) => !toast.contains(button));
+  if (next_close) return next_close.focus();
+  const main = document.querySelector("main");
+  if (!main) return;
+  if (!main.hasAttribute("tabindex")) main.setAttribute("tabindex", "-1");
+  main.focus();
+}
+
+function open_toasts_for_hash() {
+  const hash = normalize_hash(window.location.hash);
+  if (!hash) return;
+  for (const toast of document.querySelectorAll("[data-toast-trigger]")) {
+    if (normalize_hash(toast.dataset.toastTrigger) === hash) {
+      toast_instances.get(toast)?.show();
+    }
+  }
+}
+
+function sqlpage_toast() {
+  const bootstrap = window.bootstrap || window.tabler?.bootstrap;
+  if (!bootstrap?.Toast) return;
+
+  for (const toast of document.querySelectorAll('[data-pre-init="toast"]')) {
+    const requested_position = toast.dataset.position;
+    const position = toast_positions[requested_position]
+      ? requested_position
+      : "top-end";
+    toast.dataset.position = position;
+
+    let container = document.querySelector(
+      `.toast-container[data-sqlpage-toast-position="${position}"]`,
+    );
+    if (!container) {
+      container = document.createElement("div");
+      container.classList.add(
+        "toast-container",
+        "position-fixed",
+        "p-3",
+        "mh-100",
+        "overflow-auto",
+        ...toast_positions[position],
+      );
+      container.dataset.sqlpageToastPosition = position;
+      container.dataset.sqlpageGenerated = "toast-container";
+      document.body.appendChild(container);
+    }
+
+    toast.removeAttribute("data-pre-init");
+    container.appendChild(toast);
+    const requested_duration = Number.parseInt(toast.dataset.duration, 10);
+    const duration =
+      Number.isFinite(requested_duration) && requested_duration >= 0
+        ? requested_duration
+        : 5000;
+    toast.dataset.duration = String(duration);
+    const instance = new bootstrap.Toast(toast, {
+      autohide: duration !== 0,
+      delay: duration > 0 ? duration : 5000,
+    });
+    toast_instances.set(toast, instance);
+    toast.addEventListener("hidden.bs.toast", () => {
+      restore_focus_after_toast(toast, container);
+      if (toast.dataset.toastTrigger) {
+        if (
+          normalize_hash(window.location.hash) ===
+          normalize_hash(toast.dataset.toastTrigger)
+        ) {
+          window.history.replaceState(window.history.state, "", "#");
+        }
+        return;
+      }
+      instance.dispose();
+      toast_instances.delete(toast);
+      toast.remove();
+      if (
+        container.dataset.sqlpageGenerated === "toast-container" &&
+        !container.querySelector(".toast")
+      ) {
+        container.remove();
+      }
+    });
+    if (toast.dataset.toastTrigger) {
+      open_toasts_for_hash();
+    } else {
+      instance.show();
+    }
+  }
+}
+
 add_init_fn(sqlpage_table);
 add_init_fn(sqlpage_map);
 add_init_fn(sqlpage_card);
 add_init_fn(sqlpage_form);
 add_init_fn(load_scripts);
+add_init_fn(sqlpage_toast);
+add_init_fn(open_toasts_for_hash);
+window.addEventListener("hashchange", open_toasts_for_hash);
 
 function init_bootstrap_components(event) {
   const bootstrap = window.bootstrap || window.tabler.bootstrap;

sqlpage/templates/toast.handlebars

@@ -0,0 +1,18 @@
+<div{{#if id}} id="{{id}}"{{/if}} class="toast{{#if color}} bg-{{color}} text-{{color}}-fg{{/if}}{{#if class}} {{class}}{{/if}}" role="status" aria-live="polite" aria-atomic="true" data-pre-init="toast" data-duration="{{default duration 5000}}" data-position="{{default position 'top-end'}}"{{#if trigger}} data-toast-trigger="{{trigger}}"{{/if}}>
+  <div class="toast-body d-flex align-items-start gap-2">
+    {{~#if icon~}}
+    <span class="flex-shrink-0" aria-hidden="true">{{~icon_img icon~}}</span>
+    {{~/if~}}
+    <div class="flex-fill overflow-auto">
+      {{~#if title~}}<div class="fw-bold mb-1">{{title}}</div>{{~/if~}}
+      {{~#if description_md~}}
+      <div class="toast-description toast-description-markdown">{{{markdown description_md}}}</div>
+      {{~else~}}
+      {{~#if description~}}<div class="toast-description">{{description}}</div>{{~/if~}}
+      {{~/if~}}
+    </div>
+    {{~#if dismissible~}}
+    <button type="button" class="btn p-0 border-0 bg-transparent text-reset flex-shrink-0" data-bs-dismiss="toast" aria-label="Close notification">{{icon_img "x"}}</button>
+    {{~/if~}}
+  </div>
+</div>

tests/end-to-end/official-site.spec.ts

@@ -41,6 +41,85 @@ test("map", async ({ page }) => {
   await expect(page.locator(".leaflet-marker-icon").first()).toBeVisible();
 });
 
+test("toast notifications initialize, stack, dismiss, and render safely", async ({
+  page,
+}) => {
+  await page.goto(`${BASE}/documentation.sql?component=toast#component`);
+
+  const automatic = page.locator("#toast-auto");
+  await expect(automatic).toBeVisible();
+  await expect(page.locator(".toast.show")).toHaveCount(1);
+
+  const stackOne = page.locator("#toast-stack-one");
+  const stackTwo = page.locator("#toast-stack-two");
+  await expect(stackOne).toBeHidden();
+  await page.getByRole("button", { name: "Show queued notifications" }).click();
+  await expect(stackOne).toBeVisible();
+  await expect(stackTwo).toBeVisible();
+  const temporary = page.locator("#toast-short");
+  await expect(temporary).toBeVisible();
+  const stackContainer = stackOne.locator("xpath=..");
+  await expect(stackContainer).toHaveAttribute(
+    "data-sqlpage-toast-position",
+    "top-end",
+  );
+  await expect(stackContainer).toHaveClass(/\bmh-100\b/);
+  await expect(stackContainer).toHaveClass(/\boverflow-auto\b/);
+  expect(
+    await stackTwo
+      .locator("xpath=..")
+      .getAttribute("data-sqlpage-toast-position"),
+  ).toBe("top-end");
+  const firstBox = await stackOne.boundingBox();
+  const secondBox = await stackTwo.boundingBox();
+  expect(firstBox).not.toBeNull();
+  expect(secondBox).not.toBeNull();
+  expect(secondBox?.y).toBeGreaterThanOrEqual(
+    (firstBox?.y ?? 0) + (firstBox?.height ?? 0),
+  );
+
+  await expect(temporary).toBeHidden({ timeout: 5000 });
+  await expect(stackOne).toBeVisible();
+
+  const dismissible = page.locator("#toast-dismissible");
+  await page.getByRole("button", { name: "Show dismissible error" }).click();
+  await expect(
+    dismissible.getByRole("button", { name: "Close notification" }),
+  ).toBeVisible();
+  await dismissible.getByRole("button", { name: "Close notification" }).click();
+  await expect(dismissible).toBeHidden();
+  await expect(page.locator("main")).toBeFocused();
+  await page.getByRole("button", { name: "Show dismissible error" }).click();
+  await expect(dismissible).toBeVisible();
+  await dismissible.getByRole("button", { name: "Close notification" }).click();
+  await page
+    .getByRole("button", { name: "Show non-dismissible status" })
+    .click();
+  await expect(
+    page.locator("#toast-nondismissible").getByRole("button"),
+  ).toHaveCount(0);
+
+  await page.getByRole("button", { name: "Show rich notifications" }).click();
+  await expect(page.locator("#toast-markdown strong")).toHaveText("2.0");
+  await expect(page.locator("#toast-markdown a")).toHaveAttribute(
+    "href",
+    "https://example.com/releases",
+  );
+  await expect(page.locator("#toast-plain strong")).toHaveCount(0);
+  await expect(page.locator("#toast-plain")).toContainText(
+    "<strong>Plain text stays escaped</strong>",
+  );
+
+  const bottomContainer = page.locator(
+    '[data-sqlpage-toast-position="bottom-center"]',
+  );
+  await page.getByRole("button", { name: "Show bottom notification" }).click();
+  await expect(page.locator("#toast-bottom-center")).toBeVisible();
+  await expect(bottomContainer).toHaveClass(/\bbottom-0\b/);
+  await expect(bottomContainer).toHaveClass(/\bstart-50\b/);
+  await expect(bottomContainer).toHaveClass(/\btranslate-middle-x\b/);
+});
+
 test("form example", async ({ page }) => {
   await page.goto(`${BASE}/examples/multistep-form`);
   // Single selection matching the value or label