Skip to content

armgit / Pulse

Public Imported from GitHub
0

Real-time monitoring dashboard for Proxmox VE, PBS, Docker, Kubernetes, TrueNAS and vSphere. Self-hosted, with alerts for failed backups, full disks, unhealthy containers and offline nodes.

Make platform sort headings usable from the keyboard

pulse-triage[bot]fa8a9b295b12
diff --git a/docs/release-control/v6/internal/subsystems/frontend-primitives.md b/docs/release-control/v6/internal/subsystems/frontend-primitives.md
index 4e16d71dcd..9287a89533 100644
--- a/docs/release-control/v6/internal/subsystems/frontend-primitives.md
+++ b/docs/release-control/v6/internal/subsystems/frontend-primitives.md
@@ -20,6 +20,24 @@
## Purpose
+### Platform sort headings are native keyboard controls
+
+The shared platform sort heading declares column scope and contains a native
+non-submitting button. Enter, Space and pointer activation use the same existing
+three-step sort cycle; the whole heading remains a pointer target. Only the
+active column has `aria-sort`, and its visual direction marker is hidden from
+the accessible name. Non-sortable headings have no focusable control. Responsive
+labels are resolved once so direction updates cannot replace their DOM or erase
+their text. Column alignment, visibility, missing-value ordering and per-table
+sort persistence are unchanged.
+
+`PlatformSortableTableHead.test.tsx` covers structure, stable responsive labels,
+focus, cycle/reset, active-only announcements and restored sorting. The real
+query/normalizer consuming TrueNAS completion tests retain the labelled control
+through filtering, an empty result and restoration, without inventing a finish
+for a running task. Native desktop keyboard and narrow touch behaviour require
+source-bound browser proof; component event dispatch alone is not that proof.
+
### Visible action text remains in accessible names (24 October 2026)
Infrastructure section shortcuts include their visible Add action and group
diff --git a/frontend-modern/src/components/shared/SharedPrimitives.guardrails.test.ts b/frontend-modern/src/components/shared/SharedPrimitives.guardrails.test.ts
index c934c09b2f..9d07110e6c 100644
--- a/frontend-modern/src/components/shared/SharedPrimitives.guardrails.test.ts
+++ b/frontend-modern/src/components/shared/SharedPrimitives.guardrails.test.ts
@@ -1560,6 +1560,21 @@ describe('shared primitive guardrails', () => {
expect(storagePoolsTableSource).not.toContain('HEADER_SORT_BUTTON');
});
+ it('keeps platform sort activation native and responsive labels stable at the shared boundary', () => {
+ const heading = sharedPlatformPageSource.split('export function PlatformSortableTableHead')[1]!
+ .split('export const formatPlatformTableTextValue')[0]!;
+ expect(heading).toContain('scope="col"');
+ expect(heading).toContain('children(() => props.children)');
+ expect(heading).toContain('<button');
+ expect(heading).toContain('type="button"');
+ expect(heading).toContain('focus-visible:ring-inset');
+ expect(heading).toContain('<span aria-hidden="true">');
+ // Native keyboard clicks bubble to the one cell handler. A second key
+ // handler would double-advance Enter or Space through the sort cycle.
+ expect(heading).not.toContain('onKeyDown=');
+ expect(heading.match(/onClick=/g)).toHaveLength(1);
+ });
+
it('keeps the retired summary chart-visibility toggle out of the shared toolbar', () => {
// The workload summary chart section this toggle controlled is deleted and
// no other page exposes a chart show/hide control. A returning summary
diff --git a/frontend-modern/src/components/shared/Table.tsx b/frontend-modern/src/components/shared/Table.tsx
index 49cec497d2..468e982f7e 100644
--- a/frontend-modern/src/components/shared/Table.tsx
+++ b/frontend-modern/src/components/shared/Table.tsx
@@ -193,7 +193,7 @@ const resolveTablePaddingClass = (vertical: TableAxisPadding, customClass?: stri
.join(' ');
};
-export type TableHeadProps = JSX.HTMLAttributes<HTMLTableCellElement> & {
+export type TableHeadProps = JSX.ThHTMLAttributes<HTMLTableCellElement> & {
colSpan?: number;
colspan?: number;
width?: string | number;
diff --git a/frontend-modern/src/features/platformPage/__tests__/PlatformSortableTableHead.test.tsx b/frontend-modern/src/features/platformPage/__tests__/PlatformSortableTableHead.test.tsx
new file mode 100644
index 0000000000..aac60f023b
--- /dev/null
+++ b/frontend-modern/src/features/platformPage/__tests__/PlatformSortableTableHead.test.tsx
@@ -0,0 +1,109 @@
+import { cleanup, fireEvent, render, screen, within } from '@solidjs/testing-library';
+import { For } from 'solid-js';
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { TableCell, TableRow } from '@/components/shared/Table';
+import {
+ PlatformResponsiveTableLabel,
+ PlatformSortableTableHead,
+ PlatformTableShell,
+ createPlatformTableSortState,
+} from '../sharedPlatformPage';
+
+function mountTable() {
+ return render(() => {
+ const sort = createPlatformTableSortState({
+ storageKey: 'accessibleHeaders',
+ sortKeys: ['name', 'completed'] as const,
+ descendingFirst: ['completed'],
+ });
+ const rows = [
+ { name: 'bravo', completed: 2 },
+ { name: 'alpha', completed: 1 },
+ { name: 'unknown', completed: null },
+ ];
+ return (
+ <PlatformTableShell
+ header={
+ <>
+ <PlatformSortableTableHead kind="name" sort={sort} sortKey="name">
+ Name
+ </PlatformSortableTableHead>
+ <PlatformSortableTableHead kind="numeric-value" sort={sort} sortKey="completed">
+ <PlatformResponsiveTableLabel compact="Finished" full="Completed" />
+ </PlatformSortableTableHead>
+ <PlatformSortableTableHead kind="text" sort={sort}>
+ Source
+ </PlatformSortableTableHead>
+ </>
+ }
+ body={
+ <For each={sort.sortRows(rows, (row, key) => row[key])}>
+ {(row) => (
+ <TableRow data-header-test-row={row.name}>
+ <TableCell>{row.name}</TableCell>
+ <TableCell>{row.completed ?? '-'}</TableCell>
+ <TableCell>TrueNAS</TableCell>
+ </TableRow>
+ )}
+ </For>
+ }
+ />
+ );
+ });
+}
+
+afterEach(() => {
+ cleanup();
+ localStorage.clear();
+});
+
+describe('PlatformSortableTableHead', () => {
+ it('uses scoped column headings and native, non-submitting sort controls only for sortable columns', () => {
+ mountTable();
+ const headings = screen.getAllByRole('columnheader');
+ expect(headings).toHaveLength(3);
+ for (const heading of headings) expect(heading).toHaveAttribute('scope', 'col');
+ for (const button of screen.getAllByRole('button')) {
+ expect(button).toHaveAttribute('type', 'button');
+ button.focus();
+ expect(button).toHaveFocus();
+ }
+ expect(screen.getAllByRole('button')).toHaveLength(2);
+ expect(within(headings[2]!).queryByRole('button')).not.toBeInTheDocument();
+ });
+
+ it('keeps responsive labels and focus stable through sorting, reset and persisted restoration', async () => {
+ const { unmount } = mountTable();
+ const heading = screen.getByRole('columnheader', { name: /Completed/ });
+ const control = within(heading).getByRole('button');
+ const label = heading.querySelector('.platform-table-label-full');
+ const names = () =>
+ [...document.querySelectorAll('[data-header-test-row]')].map((row) =>
+ row.getAttribute('data-header-test-row'),
+ );
+ control.focus();
+ for (const [direction, expected] of [
+ ['descending', ['bravo', 'alpha', 'unknown']],
+ ['ascending', ['alpha', 'bravo', 'unknown']],
+ [undefined, ['bravo', 'alpha', 'unknown']],
+ ] as const) {
+ await fireEvent.click(control);
+ if (direction) expect(heading).toHaveAttribute('aria-sort', direction);
+ else expect(heading).not.toHaveAttribute('aria-sort');
+ expect(names()).toEqual(expected);
+ expect(control).toHaveFocus();
+ expect(heading.querySelector('.platform-table-label-full')).toBe(label);
+ expect(control).toHaveAccessibleName(/Completed/);
+ expect(control).not.toHaveAccessibleName(/[▲▼]/);
+ }
+ await fireEvent.click(within(screen.getByRole('columnheader', { name: 'Name' })).getByRole('button'));
+ expect(heading).not.toHaveAttribute('aria-sort');
+ expect(screen.getByRole('columnheader', { name: /Name/ })).toHaveAttribute('aria-sort', 'ascending');
+ expect(localStorage.getItem('accessibleHeadersSortKey')).toBe('name');
+ unmount();
+ mountTable();
+ expect(screen.getByRole('columnheader', { name: 'Name' })).toHaveAttribute('aria-sort', 'ascending');
+ expect(names()).toEqual(['alpha', 'bravo', 'unknown']);
+ });
+});
diff --git a/frontend-modern/src/features/platformPage/__tests__/PlatformWindowedRows.test.tsx b/frontend-modern/src/features/platformPage/__tests__/PlatformWindowedRows.test.tsx
index b31f8466b2..47fef7e007 100644
--- a/frontend-modern/src/features/platformPage/__tests__/PlatformWindowedRows.test.tsx
+++ b/frontend-modern/src/features/platformPage/__tests__/PlatformWindowedRows.test.tsx
@@ -6,6 +6,11 @@ import { PlatformWindowedRows } from '../PlatformWindowedRows';
import { PlatformWindowedList } from '../PlatformWindowedList';
import platformWindowedItemsSource from '../usePlatformWindowedItems.ts?raw';
import { InlineDetailTableRow } from '@/components/shared/InlineDetailTableRow';
+import {
+ PlatformSortableTableHead,
+ PlatformTableShell,
+ createPlatformTableSortState,
+} from '../sharedPlatformPage';
describe('PlatformWindowedRows', () => {
afterEach(cleanup);
@@ -47,6 +52,47 @@ describe('PlatformWindowedRows', () => {
expect(container.querySelectorAll('[data-platform-window-spacer]')).toHaveLength(2);
});
+ it('keeps the native sort heading focused while reordering a bounded estate-sized table', async () => {
+ const { container } = render(() => {
+ const items = Array.from({ length: 1_000 }, (_, id) => ({ id }));
+ const sort = createPlatformTableSortState({
+ storageKey: 'windowedHeader',
+ sortKeys: ['id'] as const,
+ });
+ return (
+ <PlatformTableShell
+ header={
+ <PlatformSortableTableHead kind="numeric-value" sort={sort} sortKey="id">
+ ID
+ </PlatformSortableTableHead>
+ }
+ body={
+ <PlatformWindowedRows items={() => sort.sortRows(items, (item) => item.id)}>
+ {(item) => <tr data-row-id={item.id}><td>{item.id}</td></tr>}
+ </PlatformWindowedRows>
+ }
+ />
+ );
+ });
+ try {
+ const button = screen.getByRole('button', { name: 'ID' });
+ button.focus();
+ await fireEvent.click(button);
+ await fireEvent.click(button);
+ expect(screen.getByRole('columnheader', { name: 'ID' })).toHaveAttribute('scope', 'col');
+ expect(screen.getByRole('columnheader', { name: 'ID' })).toHaveAttribute('aria-sort', 'descending');
+ expect(button).toHaveFocus();
+ expect(container.querySelector('[data-row-id]')).toHaveAttribute('data-row-id', '999');
+ expect(container.querySelectorAll('[data-row-id]')).toHaveLength(140);
+ const spacers = container.querySelectorAll('[data-platform-window-spacer] > td');
+ expect(spacers).toHaveLength(2);
+ for (const spacer of spacers) expect(spacer).toHaveAttribute('colspan', '1');
+ } finally {
+ localStorage.removeItem('windowedHeaderSortKey');
+ localStorage.removeItem('windowedHeaderSortDirection');
+ }
+ });
+
it('spans spacer rows over the visible header cells only', () => {
// A wider span creates phantom fixed-layout columns that take the width a
// phone's visible column percentages leave over.
diff --git a/frontend-modern/src/features/platformPage/sharedPlatformPage.tsx b/frontend-modern/src/features/platformPage/sharedPlatformPage.tsx
index a255f84eba..d24804fb92 100644
--- a/frontend-modern/src/features/platformPage/sharedPlatformPage.tsx
+++ b/frontend-modern/src/features/platformPage/sharedPlatformPage.tsx
@@ -8,6 +8,7 @@ import TriangleAlertIcon from 'lucide-solid/icons/triangle-alert';
import {
For,
Show,
+ children,
createEffect,
createMemo,
createSignal,
@@ -643,13 +644,19 @@ export function PlatformSortableTableHead<SortKey extends string>(props: {
bandWidth?: number;
children: JSX.Element;
}) {
+ // Resolve once: sort changes must not recreate a responsive label's DOM
+ // while Solid is updating the direction marker beside it.
+ const label = children(() => props.children);
const isSorted = () => props.sortKey !== undefined && props.sort.sortKey() === props.sortKey;
+ // Keep the whole cell clickable. Native button activation (including Enter
+ // and Space) bubbles here once; do not add a second button/key handler.
const handleClick = () => {
const key = props.sortKey;
if (key !== undefined) props.sort.handleSort(key);
};
return (
<TableHead
+ scope="col"
class={`${getPlatformTableHeadClassForKind(props.kind)} ${
props.sortKey !== undefined ? 'cursor-pointer select-none hover:bg-surface-hover' : ''
} ${props.class ?? ''}`
@@ -659,8 +666,18 @@ export function PlatformSortableTableHead<SortKey extends string>(props: {
style={platformTableBandWidthStyle(props.bandWidth)}
onClick={handleClick}
>
- {props.children}
- {isSorted() ? ` ${getTableSortIndicator(true, props.sort.sortDirection())}` : null}
+ <Show when={props.sortKey !== undefined} fallback={label()}>
+ <button
+ type="button"
+ class="min-h-6 w-full min-w-0 cursor-pointer rounded-sm text-inherit focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-sky-400/70"
+ style={{ 'text-align': 'inherit' }}
+ >
+ {label()}
+ <span aria-hidden="true">
+ {isSorted() ? ` ${getTableSortIndicator(true, props.sort.sortDirection())}` : null}
+ </span>
+ </button>
+ </Show>
</TableHead>
);
}
diff --git a/frontend-modern/src/features/truenas/__tests__/TrueNASProtectionTable.completion.test.tsx b/frontend-modern/src/features/truenas/__tests__/TrueNASProtectionTable.completion.test.tsx
index 6618293be4..920276c6f3 100644
--- a/frontend-modern/src/features/truenas/__tests__/TrueNASProtectionTable.completion.test.tsx
+++ b/frontend-modern/src/features/truenas/__tests__/TrueNASProtectionTable.completion.test.tsx
@@ -149,4 +149,36 @@ describe('TrueNAS protection completion evidence', () => {
['/api/recovery/points?page=1&limit=200&platform=truenas'],
]);
});
+
+ it('keeps the completion sort control labelled through direction changes, filters and an empty result', async () => {
+ apiFetchJSON.mockResolvedValueOnce({
+ data: [
+ point('running', { outcome: 'running', completedAt }),
+ point('completed', { completedAt }),
+ ],
+ });
+ mountProtection();
+ await vi.waitFor(() => expect(row('completed')).not.toBeNull());
+ const heading = () => screen.getByRole('columnheader', { name: /Completed/ });
+ const button = () => within(heading()).getByRole('button', { name: /Completed/ });
+ for (let i = 0; i < 3; i++) {
+ button().focus();
+ await fireEvent.click(button());
+ expect(button()).toHaveFocus();
+ expect(heading()).toHaveAttribute('scope', 'col');
+ }
+
+ await fireEvent.click(screen.getByRole('button', { name: 'Running, 1' }));
+ expect(button()).toBeInTheDocument();
+ expect(rowIDs()).toEqual(['running']);
+ expect(completion('running')).toHaveTextContent(/^\s*-\s*$/);
+ const search = screen.getByPlaceholderText('Search snapshots or replication');
+ await fireEvent.input(search, { target: { value: 'not-a-dataset' } });
+ expect(screen.getByText('No protection events match current filters')).toBeInTheDocument();
+ await fireEvent.input(search, { target: { value: '' } });
+ expect(button()).toBeInTheDocument();
+ await fireEvent.click(button());
+ expect(heading()).toHaveAttribute('aria-sort', 'descending');
+ expect(apiFetchJSON).toHaveBeenCalledTimes(1);
+ });
});