diff --git a/package-lock.json b/package-lock.json
index 2c72a60..359d66c 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -31,6 +31,7 @@
"@types/react-dom": "^19.3.0",
"@vitejs/plugin-react": "^6.2.1",
"@vitest/coverage-v8": "^5.1.0",
+ "axe-core": "^4.14.0",
"eslint": "^10.14.0",
"eslint-plugin-react-hooks": "^7.1.1",
"eslint-plugin-react-refresh": "^0.5.7",
@@ -2389,6 +2390,16 @@
"dev": true,
"license": "MIT"
},
+ "node_modules/axe-core": {
+ "version": "4.14.0",
+ "resolved": "https://registry.npmjs.org/axe-core/-/axe-core-4.14.0.tgz",
+ "integrity": "sha512-9WTZxEjsZ7b13TH8JPmbV2z8CHbl80/2hm3XPEG4JgNdQLK81IBRXmSxHfMAOkSqQeRxT/0dwNDz2GOm3zzpcQ==",
+ "dev": true,
+ "license": "MPL-2.0",
+ "engines": {
+ "node": ">=4"
+ }
+ },
"node_modules/balanced-match": {
"version": "4.0.4",
"resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-4.0.4.tgz",
diff --git a/package.json b/package.json
index 3544a14..4676efc 100644
--- a/package.json
+++ b/package.json
@@ -2,7 +2,7 @@
"name": "pipdock",
"version": "1.4.0",
"private": true,
- "description": "A friendly dock for your Python environments \u2014 bulk inspect, install, update and clean up Python packages.",
+ "description": "A friendly dock for your Python environments — bulk inspect, install, update and clean up Python packages.",
"license": "GPL-3.0-only",
"type": "module",
"repository": {
@@ -49,6 +49,7 @@
"@types/react-dom": "^19.3.0",
"@vitejs/plugin-react": "^6.2.1",
"@vitest/coverage-v8": "^5.1.0",
+ "axe-core": "^4.14.0",
"eslint": "^10.14.0",
"eslint-plugin-react-hooks": "^7.1.1",
"eslint-plugin-react-refresh": "^0.5.7",
diff --git a/ui/src/a11y.test.tsx b/ui/src/a11y.test.tsx
new file mode 100644
index 0000000..0da4f91
--- /dev/null
+++ b/ui/src/a11y.test.tsx
@@ -0,0 +1,240 @@
+/**
+ * Every screen and the components with structure of their own, through axe — TESTING §2.
+ *
+ * The suite before this asserted roles one at a time, wherever a test happened to reach for
+ * `getByRole`. That holds what someone thought to check. This holds the rest: a `role="row"` whose
+ * child is not a cell, a tab without a panel, an `aria-selected` on something that cannot be
+ * selected. Each of those shipped, and each passed every test there was.
+ *
+ * Rendered through `
{row.name}
@@ -193,6 +198,7 @@ function Row({
onUninstall(row.name)
}}
data-action="uninstall"
+ data-destructive
aria-label={t('packages.actions.uninstall')}
title={t('packages.actions.uninstall')}
className="shrink-0 rounded-pd border border-border px-2 py-0.5 text-data text-text-dim"
diff --git a/ui/src/components/PdPackageTable.test.tsx b/ui/src/components/PdPackageTable.test.tsx
index f6fc9b7..16173ce 100644
--- a/ui/src/components/PdPackageTable.test.tsx
+++ b/ui/src/components/PdPackageTable.test.tsx
@@ -180,3 +180,51 @@ describe('keyboard', () => {
expect(onSelectAll).toHaveBeenCalledOnce()
})
})
+
+describe('grid structure', () => {
+ it('puts every control in a cell, and gives every cell a header', () => {
+ // A `role="row"` may own cells and nothing else. The checkbox was a direct child of the row,
+ // and the header had five column headers over six cells — so a screen reader moving by
+ // column read "Status" above the action buttons.
+ setup()
+ const [header, ...rows] = screen.getAllByRole('row')
+ if (header === undefined) throw new Error('no header row')
+ const headers = within(header).getAllByRole('columnheader')
+
+ for (const row of rows) {
+ expect([...row.children].map((c) => c.getAttribute('role'))).toEqual(
+ headers.map(() => 'gridcell'),
+ )
+ }
+ expect([...header.children].every((c) => c.getAttribute('role') === 'columnheader')).toBe(true)
+ // The two that have no visible heading are named for whoever cannot see the column.
+ expect(headers.map((h) => h.textContent)).toEqual([
+ 'Select',
+ 'Package',
+ 'Version',
+ 'Latest',
+ 'Size',
+ 'Status',
+ 'Actions',
+ ])
+ })
+
+ it('says more than one row can be selected', () => {
+ // `aria-selected` on a row means nothing to a reader unless the grid says selection exists.
+ setup()
+ expect(screen.getByRole('grid')).toHaveAttribute('aria-multiselectable', 'true')
+ })
+
+ it('says what a pin chip means in text, not only in a tooltip', () => {
+ // The meaning lived in `title` on a span that cannot take focus, so it was reachable with a
+ // mouse and with nothing else.
+ setup()
+ const pinned = screen
+ .getAllByRole('row')
+ .find((row) => row.getAttribute('data-pinned') === 'true')
+ if (pinned === undefined) throw new Error('the fixture has no pinned row')
+ expect(within(pinned).getByText(/kept at this version|left out of every update/)).toHaveClass(
+ 'sr-only',
+ )
+ })
+})
diff --git a/ui/src/components/PdPackageTable.tsx b/ui/src/components/PdPackageTable.tsx
index 74c16e0..9641061 100644
--- a/ui/src/components/PdPackageTable.tsx
+++ b/ui/src/components/PdPackageTable.tsx
@@ -78,6 +78,9 @@ export function PdPackageTable({
role="grid"
aria-label={t('packages.tableLabel')}
aria-rowcount={rows.length + 1}
+ // `aria-selected` on a row means nothing unless the grid says rows can be selected, and that
+ // more than one can.
+ aria-multiselectable="true"
// Focusable but not a tab stop: the rows are (Sonar S6852, the ARIA grid pattern).
tabIndex={-1}
// `@container`: the columns size against the table's width, not the window's (U22).
@@ -102,8 +105,12 @@ export function PdPackageTable({
aria-rowindex={1}
className={`${COLUMNS.row} shrink-0 overflow-hidden border-b border-border py-1 text-data text-text-dim [scrollbar-gutter:stable]`}
>
- {/* Aligns with the row checkbox, which has no header of its own. */}
-
+ {/* The checkbox and action columns have no visible heading, and are still columns: the
+ header had five headings over six cells, so moving by column read "Status" above the
+ action buttons. Named for whoever cannot see which column they are in. */}
+
+ {t('packages.column.select')}
+
{t('packages.column.name')}
@@ -119,7 +126,9 @@ export function PdPackageTable({
{t('packages.column.status')}
-
+
+ {t('packages.column.actions')}
+
diff --git a/ui/src/locales/en/common.json b/ui/src/locales/en/common.json
index 41c29f8..39db3bf 100644
--- a/ui/src/locales/en/common.json
+++ b/ui/src/locales/en/common.json
@@ -77,7 +77,9 @@
"version": "Version",
"latest": "Latest",
"size": "Size",
- "status": "Status"
+ "status": "Status",
+ "select": "Select",
+ "actions": "Actions"
},
"badge": {
"update": "UPDATE",
@@ -168,6 +170,7 @@
"confirm": "Confirm ({{count}} changes)",
"applyDecisions": "Apply choices",
"console": "Console",
+ "closeConsole": "Close console",
"progress": "{{done}} of {{total}} complete",
"executing": "Applying changes…",
"stop": "Stop",
@@ -307,13 +310,11 @@
"notRunYet": "not checked yet",
"notRunYetHint": "Press Run to check this folder.",
"notebooks": "Jupyter notebooks (.ipynb) are excluded from every report.",
- "tabLabel": {
- "deptry_one": "Dependencies, {{count}} finding",
- "deptry_other": "Dependencies, {{count}} findings",
- "vulture_one": "Dead code, {{count}} finding",
- "vulture_other": "Dead code, {{count}} findings",
- "ruff_one": "Lint, {{count}} finding",
- "ruff_other": "Lint, {{count}} findings"
+ "tabs": "Code Health tools",
+ "tabTopic": {
+ "deptry": "Dependencies",
+ "vulture": "Dead code",
+ "ruff": "Lint"
},
"declared": {
"pyproject": "Dependencies declared in pyproject.toml",
@@ -388,6 +389,8 @@
"placeholder": "Search PyPI…",
"warming": "Preparing the package index…",
"searching": "Searching…",
+ "resultCount_one": "{{count}} result",
+ "resultCount_other": "{{count}} results",
"indexMissing": "The package index has not been downloaded yet.",
"refreshIndex": "Download the index",
"refreshing": "Downloading…",
diff --git a/ui/src/locales/vi/common.json b/ui/src/locales/vi/common.json
index 0ac0d34..f54bcbd 100644
--- a/ui/src/locales/vi/common.json
+++ b/ui/src/locales/vi/common.json
@@ -76,7 +76,9 @@
"version": "Phiên bản",
"latest": "Mới nhất",
"size": "Dung lượng",
- "status": "Trạng thái"
+ "status": "Trạng thái",
+ "select": "Chọn",
+ "actions": "Thao tác"
},
"badge": {
"update": "UPDATE",
@@ -156,6 +158,7 @@
"confirm": "Xác nhận ({{count}} thay đổi)",
"applyDecisions": "Áp dụng lựa chọn",
"console": "Bảng điều khiển",
+ "closeConsole": "Đóng bảng điều khiển",
"progress": "Hoàn tất {{done}}/{{total}}",
"executing": "Đang áp dụng thay đổi…",
"stop": "Dừng",
@@ -280,10 +283,11 @@
"notRunYet": "chưa kiểm tra",
"notRunYetHint": "Nhấn Chạy để kiểm tra thư mục này.",
"notebooks": "Jupyter notebook (.ipynb) được loại khỏi mọi báo cáo.",
- "tabLabel": {
- "deptry_other": "Phụ thuộc, {{count}} phát hiện",
- "vulture_other": "Mã chết, {{count}} phát hiện",
- "ruff_other": "Lint, {{count}} phát hiện"
+ "tabs": "Công cụ Code Health",
+ "tabTopic": {
+ "deptry": "Phụ thuộc",
+ "vulture": "Mã chết",
+ "ruff": "Lint"
},
"declared": {
"pyproject": "Phụ thuộc được khai báo trong pyproject.toml",
@@ -345,6 +349,7 @@
"placeholder": "Tìm trên PyPI…",
"warming": "Đang chuẩn bị danh mục gói…",
"searching": "Đang tìm…",
+ "resultCount_other": "{{count}} kết quả",
"indexMissing": "Danh mục gói chưa được tải về.",
"refreshIndex": "Tải danh mục",
"refreshing": "Đang tải…",
diff --git a/ui/src/test/axe.ts b/ui/src/test/axe.ts
new file mode 100644
index 0000000..c935b1b
--- /dev/null
+++ b/ui/src/test/axe.ts
@@ -0,0 +1,44 @@
+/**
+ * axe-core against a rendered tree — TESTING §2's accessibility tier.
+ *
+ * axe is called directly rather than through a matcher package. The matcher packages are thin
+ * wrappers pinned to a test runner's major version, and `eslint-plugin-jsx-a11y` — the other usual
+ * gate — peers ESLint 9 at most while this repository is on 10. axe-core itself has no
+ * dependencies and no opinion about the runner.
+ *
+ * **What this cannot see, so that nobody reads a pass as more than it is:**
+ *
+ * - `color-contrast` is off. jsdom computes no layout and no real colours, so the rule would
+ * report "incomplete" for every node. Contrast is `tokens.test.ts`'s job, which computes it from
+ * the tokens themselves.
+ * - Nothing here knows what a screen reader *says*, what forced-colors draws, or where focus goes
+ * after a keypress. Those are the hand tier and the focus tests.
+ *
+ * It returns strings rather than asserting, so the failure message is the list of what is wrong
+ * and where — `expect(await violations()).toEqual([])` prints every rule and selector.
+ */
+
+import axe from 'axe-core'
+
+interface Options {
+ /**
+ * `region` asks that all content sit inside a landmark. True of the whole app, and meaningless
+ * for a component rendered alone into a bare ``.
+ */
+ page?: boolean
+}
+
+export async function violations(
+ root: Element = document.body,
+ { page = false }: Options = {},
+): Promise {
+ const results = await axe.run(root, {
+ rules: {
+ 'color-contrast': { enabled: false },
+ region: { enabled: page },
+ },
+ })
+ return results.violations.flatMap((violation) =>
+ violation.nodes.map((node) => `${violation.id}: ${violation.help} — ${node.target.join(' ')}`),
+ )
+}
diff --git a/ui/src/test/setup.ts b/ui/src/test/setup.ts
index 9de3ae5..5d5bc1d 100644
--- a/ui/src/test/setup.ts
+++ b/ui/src/test/setup.ts
@@ -97,4 +97,13 @@ if (typeof HTMLDialogElement !== 'undefined') {
}
}
+/**
+ * jsdom has no layout, so it has no `scrollIntoView` either — the method is simply absent, and a
+ * component that calls it throws. A no-op unless a test replaces it to watch what was scrolled.
+ */
+const element = Element.prototype as unknown as Record
+element['scrollIntoView'] ??= function scrollIntoView() {
+ /* nothing to scroll */
+}
+
export { VIEWPORT }