Add toast notification component with JS init, template, examples, migration, and tests (#1360)

* Support hash-triggered toasts

* Address toast review feedback

* Render toast positioning in template

* Avoid reopening initialized toasts

* Fix white toast foreground color

* Configure toasts declaratively

* Simplify toast template styling

* Address toast accessibility reviews
This commit is contained in:
Ophir LOJKINE
2026-08-03 15:50:18 +02:00
committed by GitHub
parent ae3c3c874f
commit 7457370b8d
12 changed files with 392 additions and 17 deletions
+1
View File
@@ -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.
@@ -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;
-- =============================================================================
@@ -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;
-- =============================================================================
@@ -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;
+5 -3
View File
@@ -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;
@@ -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 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 true 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 toast that opens when the page loads and disappears automatically after the default 5000 milliseconds.', json('[
{"component":"toast","id":"toast-auto","title":"This is a SQLPage toast","description":"This toast will open automatically when the page loads.","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":"black","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).","color":"blue","duration":0},
{"component":"toast","id":"toast-plain","trigger":"rich-notifications","description":"<strong>Plain text stays escaped</strong>","color":"white","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"}
]'));
@@ -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;
+5
View File
@@ -191,3 +191,8 @@ See https://github.com/tabler/tabler/issues/2404
.text-black-fg {
color: var(--tblr-dark-fg) !important;
}
.toast-colored .toast-description a {
color: inherit;
text-decoration: underline;
}
+87
View File
@@ -325,11 +325,98 @@ function add_init_fn(f) {
if (document.readyState !== "loading") setTimeout(f, 0);
}
function normalize_hash(hash) {
const normalized = hash?.replace(/^#/, "");
try {
return decodeURIComponent(normalized);
} catch {
return normalized;
}
}
function open_toasts_for_hash(toasts) {
const Toast = (window.bootstrap || window.tabler?.bootstrap)?.Toast;
if (!Toast) return;
const hash = normalize_hash(window.location.hash);
if (!hash) return;
for (const toast of toasts) {
if (normalize_hash(toast.dataset.toastTrigger) === hash) {
Toast.getOrCreateInstance(toast).show();
}
}
}
function restore_focus_after_toast(toast, container) {
if (!toast.contains(document.activeElement)) return;
const next_close = container.querySelector(
'.toast.show [data-bs-dismiss="toast"]',
);
if (next_close) {
next_close.focus();
return;
}
const main = document.querySelector("main");
if (!main) return;
if (!main.hasAttribute("tabindex")) main.tabIndex = -1;
main.focus({ preventScroll: true });
}
function sqlpage_toast() {
const Toast = (window.bootstrap || window.tabler?.bootstrap)?.Toast;
if (!Toast) return;
const initialized_toasts = [];
for (const toast of document.querySelectorAll('[data-pre-init="toast"]')) {
const source_container = toast.parentElement;
const position = source_container.dataset.sqlpageToastPosition;
let container = document.querySelector(
`.toast-container[data-sqlpage-toast-position="${position}"]:not([data-pre-init])`,
);
if (!container) {
container = source_container;
container.removeAttribute("data-pre-init");
document.body.appendChild(container);
} else {
container.appendChild(toast);
source_container.remove();
}
toast.removeAttribute("data-pre-init");
const instance = Toast.getOrCreateInstance(toast);
initialized_toasts.push(toast);
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.remove();
if (!container.querySelector(".toast")) {
container.remove();
}
});
if (!toast.dataset.toastTrigger) {
instance.show();
}
}
open_toasts_for_hash(initialized_toasts);
}
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);
window.addEventListener("hashchange", () =>
open_toasts_for_hash(document.querySelectorAll("[data-toast-trigger]")),
);
function init_bootstrap_components(event) {
const bootstrap = window.bootstrap || window.tabler.bootstrap;
+31
View File
@@ -0,0 +1,31 @@
<div data-pre-init="toast-container" class="toast-container position-fixed p-3 mh-100 overflow-auto
{{~#if (eq position 'top-start')}} top-0 start-0" data-sqlpage-toast-position="top-start"
{{~else if (eq position 'top-center')}} top-0 start-50 translate-middle-x" data-sqlpage-toast-position="top-center"
{{~else if (eq position 'bottom-start')}} bottom-0 start-0" data-sqlpage-toast-position="bottom-start"
{{~else if (eq position 'bottom-center')}} bottom-0 start-50 translate-middle-x" data-sqlpage-toast-position="bottom-center"
{{~else if (eq position 'bottom-end')}} bottom-0 end-0" data-sqlpage-toast-position="bottom-end"
{{~else}} top-0 end-0" data-sqlpage-toast-position="top-end"{{/if}}>
<div
{{~#if id}} id="{{id}}"{{/if}}
{{~#if trigger}} data-toast-trigger="{{trigger}}"{{/if}} class="toast
{{~#if color}} toast-colored bg-{{color}} text-{{#if (eq color 'white')}}light{{else}}{{color}}{{/if}}-fg{{/if}}
{{~#if class}} {{class}}{{/if~}}
" role="status" aria-live="polite" aria-atomic="true" data-pre-init="toast" data-bs-delay="{{default duration 5000}}" data-bs-autohide="{{#if (eq duration 0)}}false{{else}}true{{/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 (default dismissible true)~}}
<button type="button" class="btn-close flex-shrink-0" data-bs-dismiss="toast" aria-label="Close notification"></button>
{{~/if~}}
</div>
</div>
</div>
+190 -1
View File
@@ -1,6 +1,6 @@
import { expect, type Page, test } from "@playwright/test";
const BASE = "http://localhost:8080/";
const BASE = process.env.SQLPAGE_TEST_BASE ?? "http://localhost:8080/";
test("Open documentation", async ({ page }) => {
await page.goto(BASE);
@@ -41,6 +41,195 @@ 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(automatic).toHaveAttribute("data-bs-delay", "5000");
await expect(automatic).toHaveAttribute("data-bs-autohide", "true");
await expect(
automatic.getByRole("button", { name: "Close notification" }),
).toBeVisible();
await expect(page.locator(".toast.show")).toHaveCount(1);
const automaticHandle = await automatic.elementHandle();
await automatic.getByRole("button", { name: "Close notification" }).click();
await expect(automatic).toBeHidden();
await expect(page.locator("main")).toBeFocused();
const stackOne = page.locator("#toast-stack-one");
const stackTwo = page.locator("#toast-stack-two");
await expect(stackOne).toBeHidden();
await page.evaluate(() => {
document.addEventListener("shown.bs.toast", (event) => {
const toast = event.target as HTMLElement;
toast.dataset.shownCount = String(
Number(toast.dataset.shownCount ?? 0) + 1,
);
});
});
await page.getByRole("button", { name: "Show queued notifications" }).click();
await expect(stackOne).toBeVisible();
await expect(stackTwo).toBeVisible();
await expect(stackOne).toHaveAttribute("data-shown-count", "1");
await expect(stackTwo).toHaveAttribute("data-shown-count", "1");
await expect(page.locator("#toast-short")).toHaveAttribute(
"data-shown-count",
"1",
);
await page.evaluate(() =>
document.dispatchEvent(new CustomEvent("fragment-loaded")),
);
await page.waitForTimeout(250);
await expect(page.locator("#toast-short")).toHaveAttribute(
"data-shown-count",
"1",
);
expect(decodeURIComponent(new URL(page.url()).hash)).toBe(
"#queued notifications",
);
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 stackContainer.evaluate(
(container) => container.parentElement === document.body,
),
).toBe(true);
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),
);
const temporary = page.locator("#toast-short");
await expect(temporary).toHaveAttribute("data-bs-delay", "2000");
await expect(temporary).toBeVisible();
await expect(temporary).toBeHidden({ timeout: 5000 });
await expect(stackOne).toBeVisible();
await expect(automatic).toBeHidden({ timeout: 7000 });
expect(
await automaticHandle?.evaluate((element) => {
const testWindow = window as Window & {
tabler: {
bootstrap: {
Toast: { getInstance(element: Element): unknown };
};
};
};
return testWindow.tabler.bootstrap.Toast.getInstance(element) === null;
}),
).toBe(true);
const dismissible = page.locator("#toast-dismissible");
await expect(dismissible).toHaveAttribute("data-bs-delay", "0");
await expect(dismissible).toHaveAttribute("data-bs-autohide", "false");
await page.getByRole("button", { name: "Show dismissible error" }).click();
const closeButton = dismissible.getByRole("button", {
name: "Close notification",
});
await expect(closeButton).toBeVisible();
const closeStyle = await closeButton.evaluate((button) => {
const style = getComputedStyle(button);
const toastStyle = getComputedStyle(
button.closest(".toast") as HTMLElement,
);
return {
backgroundColor: style.backgroundColor,
color: style.color,
filter: style.filter,
maskImage: style.maskImage,
toastColor: toastStyle.color,
};
});
expect(closeStyle.filter).toBe("none");
expect(closeStyle.maskImage).not.toBe("none");
expect(closeStyle.color).toBe(closeStyle.toastColor);
expect(closeStyle.backgroundColor).toBe(closeStyle.toastColor);
await page.evaluate(() => {
window.history.replaceState({ toastTest: true }, "", window.location.href);
});
await dismissible.getByRole("button", { name: "Close notification" }).click();
await expect(dismissible).toBeHidden();
expect(await page.evaluate(() => window.history.state)).toEqual({
toastTest: true,
});
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",
);
const linkStyle = await page
.locator("#toast-markdown a")
.evaluate((link) => ({
color: getComputedStyle(link).color,
parentColor: getComputedStyle(link.parentElement as HTMLElement).color,
textDecorationLine: getComputedStyle(link).textDecorationLine,
}));
expect(linkStyle.color).toBe(linkStyle.parentColor);
expect(linkStyle.textDecorationLine).toBe("underline");
await expect(page.locator("#toast-plain strong")).toHaveCount(0);
await expect(page.locator("#toast-plain")).toContainText(
"<strong>Plain text stays escaped</strong>",
);
const whiteToast = page.locator("#toast-plain");
const whiteToastStyle = await whiteToast.evaluate((toast) => {
const style = getComputedStyle(toast);
const closeStyle = getComputedStyle(
toast.querySelector(".btn-close") as HTMLElement,
);
const rgba = (color: string) => {
const canvas = document.createElement("canvas");
const context = canvas.getContext("2d");
if (!context) throw new Error("Canvas 2D context is unavailable");
context.fillStyle = color;
context.fillRect(0, 0, 1, 1);
return Array.from(context.getImageData(0, 0, 1, 1).data);
};
return {
backgroundColor: rgba(style.backgroundColor),
closeColor: rgba(closeStyle.backgroundColor),
color: rgba(style.color),
};
});
expect(whiteToastStyle.backgroundColor).toEqual([255, 255, 255, 255]);
expect(whiteToastStyle.color).toEqual([31, 41, 55, 255]);
expect(whiteToastStyle.closeColor).toEqual(whiteToastStyle.color);
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
@@ -0,0 +1,8 @@
SELECT 'toast' AS component, 'Default toast' AS title, 'It works !' AS description;
SELECT 'toast' AS component, 'Persistent' AS title, 'It works !' AS description, 0 AS duration, 1 AS dismissible;
SELECT 'toast' AS component, 'No close control' AS title, 'It works !' AS description, 0 AS duration, 0 AS dismissible;
SELECT 'toast' AS component, 'Colored' AS title, 'It works !' AS description, 'check' AS icon, 'green' AS color;
SELECT 'toast' AS component, '<strong>Escaped</strong> It works !' AS description;
SELECT 'toast' AS component, '**Markdown** [link](https://example.com) It works !' AS description_md;
SELECT 'toast' AS component, 'Alternate position' AS title, 'It works !' AS description, 'bottom-center' AS position;
SELECT 'toast' AS component, 'Hash-triggered' AS title, 'It works !' AS description, 'notice' AS id, 'notice' AS trigger;