Skip to content

A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.

feat(file-browser): keyboard and screen-reader accessibility for mo.ui.file_browser (#10005)

Kiran Gadhavea8092917648c
diff --git a/frontend/src/plugins/impl/FileBrowserPlugin.tsx b/frontend/src/plugins/impl/FileBrowserPlugin.tsx
index fb48c6ba32..5bc4b90038 100644
--- a/frontend/src/plugins/impl/FileBrowserPlugin.tsx
+++ b/frontend/src/plugins/impl/FileBrowserPlugin.tsx
@@ -1,7 +1,7 @@
/* Copyright 2026 Marimo. All rights reserved. */
import { type LucideIcon, CornerLeftUp } from "lucide-react";
-import { type JSX, useEffect, useState } from "react";
+import { type JSX, useEffect, useLayoutEffect, useRef, useState } from "react";
import { z } from "zod";
import {
FILE_ICON as FILE_TYPE_ICONS,
@@ -129,6 +129,7 @@ interface FileBrowserProps extends Data, PluginFunctions {
}
interface CheckboxOrIconProps {
+ name: string;
isSelected: boolean;
canSelect: boolean;
Icon: LucideIcon;
@@ -136,6 +137,7 @@ interface CheckboxOrIconProps {
}
function CheckboxOrIcon({
+ name,
isSelected,
canSelect,
Icon,
@@ -146,17 +148,21 @@ function CheckboxOrIcon({
<>
<Checkbox
checked={isSelected}
+ aria-label={`Select ${name}`}
+ tabIndex={-1}
onClick={(e) => {
onSelect();
e.stopPropagation();
}}
- className={cn({ "hidden group-hover:flex": !isSelected })}
+ className={cn({
+ "hidden group-hover:flex group-focus:flex": !isSelected,
+ })}
/>
<Icon
size={16}
className={cn("mr-2", {
hidden: isSelected,
- "group-hover:hidden": !isSelected,
+ "group-hover:hidden group-focus:hidden": !isSelected,
})}
/>
</>
@@ -165,6 +171,18 @@ function CheckboxOrIcon({
return <Icon size={16} className="mr-2" />;
}
+interface RowModel {
+ key: string;
+ name: string;
+ Icon: LucideIcon;
+ isSelected: boolean;
+ canSelect: boolean;
+ /** Enter and mouse-click action. */
+ onPrimary: () => void;
+ /** Space action; null when the row has nothing to toggle. */
+ onToggleSelect: (() => void) | null;
+}
+
/**
* File browser component.
*
@@ -184,6 +202,13 @@ export const FileBrowser = ({
const [path, setPath] = useInternalStateWithSync(initialPath);
const [isUpdatingPath, setIsUpdatingPath] = useState(false);
const [showLoadingOverlay, setShowLoadingOverlay] = useState(false);
+ const [activeIndex, setActiveIndex] = useState(0);
+ const rowRefs = useRef<(HTMLTableRowElement | null)[]>([]);
+ const gridRef = useRef<HTMLTableElement | null>(null);
+ // Set when navigation is triggered from within the grid, so focus can follow
+ // to the parent row after the new listing renders instead of falling to the
+ // body when the previously focused row unmounts.
+ const refocusParentRef = useRef(false);
// HACK: use the random-id of the host element to force a re-render
// when the random-id changes, this means the cell was re-rendered
@@ -210,6 +235,22 @@ export const FileBrowser = ({
};
}, [isPending]);
+ // Reset the roving tabindex whenever the listing reloads (a new path or a
+ // same-path refresh) so activeIndex never points past the current rows.
+ const listingKey = `${path}::${randomId}`;
+ const [prevListingKey, setPrevListingKey] = useState(listingKey);
+ if (prevListingKey !== listingKey) {
+ setPrevListingKey(listingKey);
+ setActiveIndex(0);
+ }
+
+ useLayoutEffect(() => {
+ if (refocusParentRef.current) {
+ refocusParentRef.current = false;
+ rowRefs.current[0]?.focus();
+ }
+ }, [listingKey]);
+
const files = data?.files ?? [];
const selectedPaths = new Set(value.map((x) => x.path));
const canSelectDirectories =
@@ -269,6 +310,8 @@ export const FileBrowser = ({
return;
}
+ refocusParentRef.current =
+ gridRef.current?.contains(document.activeElement) ?? false;
setPath(newPath);
setIsUpdatingPath(false);
}
@@ -333,78 +376,90 @@ export const FileBrowser = ({
setValue([...value, ...filesInView]);
}
- // Create rows for directories and files
- const fileRows: React.ReactNode[] = [];
-
- // Parent directory ".." row button
- fileRows.push(
- <TableRow
- className="hover:bg-accent select-none"
- key={"Parent directory"}
- onClick={() => setNewPath(PARENT_DIRECTORY)}
- >
- <TableCell className="w-[50px] pl-4">
- <CornerLeftUp size={16} />
- </TableCell>
- <TableCell>{PARENT_DIRECTORY}</TableCell>
- </TableRow>,
- );
+ const rowModels: RowModel[] = [
+ {
+ key: "parent",
+ name: PARENT_DIRECTORY,
+ Icon: CornerLeftUp,
+ isSelected: false,
+ canSelect: false,
+ onPrimary: () => setNewPath(PARENT_DIRECTORY),
+ onToggleSelect: null,
+ },
+ ...files.map((file): RowModel => {
+ let filePath = file.path;
+ if (filePath.startsWith("//")) {
+ filePath = filePath.slice(1) as FilePath;
+ }
- for (const file of files) {
- let filePath = file.path;
+ const canSelect =
+ (canSelectDirectories && file.is_directory) ||
+ (canSelectFiles && !file.is_directory);
+ const isSelected = selectedPaths.has(filePath);
+ const fileType: FileType = file.is_directory
+ ? "directory"
+ : guessFileType(file.name);
+
+ const toggle = () =>
+ handleSelection({
+ path: filePath,
+ name: file.name,
+ isDirectory: file.is_directory,
+ });
+
+ return {
+ key: file.id,
+ name: file.name,
+ Icon: FILE_TYPE_ICONS[fileType],
+ isSelected,
+ canSelect,
+ onPrimary: file.is_directory
+ ? () => setNewPath(filePath)
+ : canSelect
+ ? toggle
+ : () => {},
+ onToggleSelect: canSelect ? toggle : null,
+ };
+ }),
+ ];
- if (filePath.startsWith("//")) {
- filePath = filePath.slice(1) as FilePath;
- }
+ function focusRow(index: number) {
+ setActiveIndex(index);
+ rowRefs.current[index]?.focus();
+ }
- // Click handler
- const handleClick = file.is_directory
- ? ({ path }: { path: string }) => setNewPath(path)
- : handleSelection;
-
- // Icon
- const fileType: FileType = file.is_directory
- ? "directory"
- : guessFileType(file.name);
-
- const Icon = FILE_TYPE_ICONS[fileType];
-
- const isSelected = selectedPaths.has(filePath);
-
- fileRows.push(
- <TableRow
- key={file.id}
- className={cn("hover:bg-accent group select-none", {
- "bg-primary/25 hover:bg-primary/35": isSelected,
- })}
- onClick={() =>
- handleClick({
- path: filePath,
- name: file.name,
- isDirectory: file.is_directory,
- })
- }
- >
- <TableCell className="w-[50px] pl-4">
- <CheckboxOrIcon
- isSelected={isSelected}
- canSelect={
- (canSelectDirectories && file.is_directory) ||
- (canSelectFiles && !file.is_directory)
- }
- Icon={Icon}
- onSelect={() =>
- handleSelection({
- path: filePath,
- name: file.name,
- isDirectory: file.is_directory,
- })
- }
- />
- </TableCell>
- <TableCell>{file.name}</TableCell>
- </TableRow>,
- );
+ function handleRowKeyDown(
+ e: React.KeyboardEvent<HTMLTableRowElement>,
+ index: number,
+ ) {
+ const lastIndex = rowModels.length - 1;
+ switch (e.key) {
+ case "ArrowDown":
+ e.preventDefault();
+ focusRow(Math.min(index + 1, lastIndex));
+ break;
+ case "ArrowUp":
+ e.preventDefault();
+ focusRow(Math.max(index - 1, 0));
+ break;
+ case "Home":
+ e.preventDefault();
+ focusRow(0);
+ break;
+ case "End":
+ e.preventDefault();
+ focusRow(lastIndex);
+ break;
+ case "Enter":
+ e.preventDefault();
+ rowModels[index].onPrimary();
+ break;
+ // Space is select-only; preventDefault stops the list from scrolling.
+ case " ":
+ e.preventDefault();
+ rowModels[index].onToggleSelect?.();
+ break;
+ }
}
// Get list of parent directories.
@@ -490,8 +545,44 @@ export const FileBrowser = ({
<span>Listing files...</span>
</div>
)}
- <Table className="cursor-pointer table-fixed">
- <TableBody>{fileRows}</TableBody>
+ <Table
+ ref={gridRef}
+ className="cursor-pointer table-fixed"
+ role="grid"
+ aria-label="File browser"
+ aria-multiselectable={multiple}
+ >
+ <TableBody>
+ {rowModels.map((row, index) => (
+ <TableRow
+ key={row.key}
+ role="row"
+ ref={(el) => {
+ rowRefs.current[index] = el;
+ }}
+ tabIndex={index === activeIndex ? 0 : -1}
+ onFocus={() => setActiveIndex(index)}
+ onKeyDown={(e) => handleRowKeyDown(e, index)}
+ className={cn(
+ "hover:bg-accent group select-none focus-visible:outline-hidden focus-visible:ring-1 focus-visible:ring-ring focus-visible:ring-inset",
+ { "bg-primary/25 hover:bg-primary/35": row.isSelected },
+ )}
+ aria-selected={row.canSelect ? row.isSelected : undefined}
+ onClick={row.onPrimary}
+ >
+ <TableCell role="gridcell" className="w-[50px] pl-4">
+ <CheckboxOrIcon
+ name={row.name}
+ isSelected={row.isSelected}
+ canSelect={row.canSelect}
+ Icon={row.Icon}
+ onSelect={() => row.onToggleSelect?.()}
+ />
+ </TableCell>
+ <TableCell role="gridcell">{row.name}</TableCell>
+ </TableRow>
+ ))}
+ </TableBody>
</Table>
</div>
<div className="mt-4">
diff --git a/frontend/src/plugins/impl/__tests__/FileBrowserPlugin.test.tsx b/frontend/src/plugins/impl/__tests__/FileBrowserPlugin.test.tsx
new file mode 100644
index 0000000000..f16b2c21a4
--- /dev/null
+++ b/frontend/src/plugins/impl/__tests__/FileBrowserPlugin.test.tsx
@@ -0,0 +1,314 @@
+/* Copyright 2026 Marimo. All rights reserved. */
+
+import { fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { beforeAll, describe, expect, it, vi } from "vitest";
+import { SetupMocks } from "@/__mocks__/common";
+import { initialModeAtom } from "@/core/mode";
+import { store } from "@/core/state/jotai";
+import type { IPluginProps } from "../../types";
+import { FileBrowserPlugin } from "../FileBrowserPlugin";
+
+interface MockFile {
+ id: string;
+ path: string;
+ name: string;
+ is_directory: boolean;
+}
+
+const FILES: MockFile[] = [
+ { id: "1", path: "/home/user/docs", name: "docs", is_directory: true },
+ { id: "2", path: "/home/user/a.txt", name: "a.txt", is_directory: false },
+ { id: "3", path: "/home/user/b.txt", name: "b.txt", is_directory: false },
+];
+
+type Value = MockFile[];
+
+function mockListDirectory(files: MockFile[]) {
+ return vi.fn().mockResolvedValue({
+ files,
+ total_count: files.length,
+ is_truncated: false,
+ });
+}
+
+function makeProps(
+ overrides: {
+ selectionMode?: string;
+ multiple?: boolean;
+ value?: Value;
+ setValue?: (v: Value) => void;
+ files?: MockFile[];
+ list_directory?: ReturnType<typeof vi.fn>;
+ host?: HTMLElement;
+ } = {},
+): IPluginProps<Value, Record<string, unknown>> {
+ const files = overrides.files ?? FILES;
+ const list_directory = overrides.list_directory ?? mockListDirectory(files);
+ return {
+ data: {
+ initialPath: "/home/user",
+ filetypes: [],
+ selectionMode: overrides.selectionMode ?? "all",
+ multiple: overrides.multiple ?? true,
+ label: null,
+ restrictNavigation: false,
+ },
+ value: overrides.value ?? [],
+ setValue: overrides.setValue ?? vi.fn(),
+ host: overrides.host ?? document.createElement("div"),
+ functions: {
+ list_directory,
+ },
+ } as unknown as IPluginProps<Value, Record<string, unknown>>;
+}
+
+function renderBrowser(overrides: Parameters<typeof makeProps>[0] = {}) {
+ const listDirectory =
+ overrides.list_directory ?? mockListDirectory(overrides.files ?? FILES);
+ const result = render(
+ FileBrowserPlugin.render(
+ makeProps({ ...overrides, list_directory: listDirectory }) as Parameters<
+ typeof FileBrowserPlugin.render
+ >[0],
+ ),
+ );
+ return { ...result, listDirectory };
+}
+
+beforeAll(() => {
+ SetupMocks.resizeObserver();
+ store.set(initialModeAtom, "edit");
+});
+
+describe("FileBrowserPlugin keyboard accessibility", () => {
+ it("renders a row per file plus the parent row", async () => {
+ renderBrowser();
+ expect(await screen.findByText("docs")).toBeInTheDocument();
+ // parent "..", docs, a.txt, b.txt
+ expect(screen.getAllByRole("row")).toHaveLength(4);
+ });
+
+ it("marks the list as a multiselectable grid", async () => {
+ renderBrowser({ multiple: true });
+ await screen.findByText("docs");
+ const grid = screen.getByRole("grid");
+ expect(grid).toHaveAttribute("aria-multiselectable", "true");
+ });
+
+ it("does not select a non-selectable file on click (mode=directory)", async () => {
+ const setValue = vi.fn();
+ renderBrowser({ selectionMode: "directory", setValue });
+ const fileCell = await screen.findByText("a.txt");
+ fireEvent.click(fileCell.closest('[role="row"]')!);
+ expect(setValue).not.toHaveBeenCalled();
+ });
+
+ it("labels each selectable checkbox with the file name", async () => {
+ renderBrowser({ selectionMode: "all" });
+ await screen.findByText("docs");
+ expect(
+ screen.getByRole("checkbox", { name: "Select a.txt" }),
+ ).toBeInTheDocument();
+ expect(
+ screen.getByRole("checkbox", { name: "Select docs" }),
+ ).toBeInTheDocument();
+ });
+
+ it("keeps checkboxes out of the tab order", async () => {
+ renderBrowser({ selectionMode: "all" });
+ await screen.findByText("docs");
+ expect(
+ screen.getByRole("checkbox", { name: "Select a.txt" }),
+ ).toHaveAttribute("tabindex", "-1");
+ });
+
+ it("places exactly one row in the tab order", async () => {
+ renderBrowser();
+ await screen.findByText("docs");
+ const rows = screen.getAllByRole("row");
+ const tabbable = rows.filter((r) => r.getAttribute("tabindex") === "0");
+ expect(tabbable).toHaveLength(1);
+ // the parent row is first and starts active
+ expect(rows[0]).toHaveAttribute("tabindex", "0");
+ });
+
+ it("resets the active row to the parent row after navigating", async () => {
+ renderBrowser({ selectionMode: "all" });
+ const docs = await screen.findByText("docs");
+ const docsRow = docs.closest('[role="row"]')!;
+ fireEvent.keyDown(docsRow, { key: "ArrowDown" }); // move active off the parent
+ fireEvent.click(docs); // navigate into "docs"
+ await screen.findByText("docs"); // listing reloads (mock returns same files)
+ const rows = screen.getAllByRole("row");
+ expect(rows[0]).toHaveAttribute("tabindex", "0");
+ // the focused row must match the only tabbable row
+ expect(rows[0]).toHaveFocus();
+ });
+
+ it("resets the active row when the listing refreshes in place", async () => {
+ // The cell's random-id changes when the cell re-renders, refetching the
+ // same path. A shrinking listing must not leave activeIndex out of bounds.
+ const parent = document.createElement("div");
+ parent.setAttribute("random-id", "a");
+ const host = document.createElement("div");
+ parent.append(host);
+ document.body.append(parent);
+
+ const list_directory = vi
+ .fn()
+ .mockResolvedValueOnce({
+ files: FILES,
+ total_count: FILES.length,
+ is_truncated: false,
+ })
+ .mockResolvedValue({
+ files: [FILES[0]],
+ total_count: 1,
+ is_truncated: false,
+ });
+
+ const props = () =>
+ FileBrowserPlugin.render(
+ makeProps({ host, list_directory }) as Parameters<
+ typeof FileBrowserPlugin.render
+ >[0],
+ );
+ const { rerender } = render(props());
+ await screen.findByText("a.txt");
+
+ // Move the active row to the last row, then trigger a same-path refresh.
+ fireEvent.keyDown(screen.getAllByRole("row")[0], { key: "End" });
+ expect(screen.getAllByRole("row").at(-1)).toHaveAttribute("tabindex", "0");
+
+ parent.setAttribute("random-id", "b");
+ rerender(props());
+
+ await waitFor(() =>
+ // parent ".." plus the single remaining file
+ expect(screen.getAllByRole("row")).toHaveLength(2),
+ );
+ const rows = screen.getAllByRole("row");
+ const tabbable = rows.filter((r) => r.getAttribute("tabindex") === "0");
+ expect(tabbable).toHaveLength(1);
+ expect(rows[0]).toHaveAttribute("tabindex", "0");
+ });
+
+ it("syncs the tabbable row to whichever row gains focus", async () => {
+ renderBrowser();
+ await screen.findByText("docs");
+ const rows = screen.getAllByRole("row"); // [.., docs, a.txt, b.txt]
+ expect(rows[0]).toHaveAttribute("tabindex", "0");
+
+ fireEvent.focus(rows[2]); // e.g. focus from a mouse click, not arrow keys
+ expect(rows[2]).toHaveAttribute("tabindex", "0");
+ expect(rows[0]).toHaveAttribute("tabindex", "-1");
+ });
+
+ it("moves focus to the parent row after navigating from within the grid", async () => {
+ // Navigating into a directory unmounts the focused row; focus must follow
+ // to the parent row instead of falling back to the document body.
+ const list_directory = vi
+ .fn()
+ .mockResolvedValueOnce({
+ files: FILES,
+ total_count: FILES.length,
+ is_truncated: false,
+ })
+ .mockResolvedValue({
+ files: [
+ {
+ id: "99",
+ path: "/home/user/docs/inner.txt",
+ name: "inner.txt",
+ is_directory: false,
+ },
+ ],
+ total_count: 1,
+ is_truncated: false,
+ });
+ renderBrowser({ selectionMode: "all", list_directory });
+ await screen.findByText("docs");
+
+ const rows = screen.getAllByRole("row"); // [.., docs, a.txt, b.txt]
+ fireEvent.keyDown(rows[0], { key: "ArrowDown" }); // focus the docs row
+ expect(rows[1]).toHaveFocus();
+ fireEvent.keyDown(rows[1], { key: "Enter" }); // navigate into docs
+
+ await screen.findByText("inner.txt");
+ expect(screen.getAllByRole("row")[0]).toHaveFocus();
+ });
+
+ it("moves focus with arrows and clamps at the ends", async () => {
+ renderBrowser();
+ await screen.findByText("docs");
+ const rows = screen.getAllByRole("row"); // [.., docs, a.txt, b.txt]
+
+ fireEvent.keyDown(rows[0], { key: "ArrowDown" });
+ expect(rows[1]).toHaveFocus();
+ expect(rows[1]).toHaveAttribute("tabindex", "0");
+
+ fireEvent.keyDown(rows[1], { key: "ArrowUp" });
+ expect(rows[0]).toHaveFocus();
+
+ fireEvent.keyDown(rows[0], { key: "ArrowUp" }); // clamp at top
+ expect(rows[0]).toHaveFocus();
+
+ fireEvent.keyDown(rows[0], { key: "End" });
+ expect(rows[3]).toHaveFocus();
+
+ fireEvent.keyDown(rows[3], { key: "ArrowDown" }); // clamp at bottom
+ expect(rows[3]).toHaveFocus();
+
+ fireEvent.keyDown(rows[3], { key: "Home" });
+ expect(rows[0]).toHaveFocus();
+ });
+
+ it("Enter navigates into a directory", async () => {
+ const setValue = vi.fn();
+ const { listDirectory } = renderBrowser({
+ selectionMode: "all",
+ setValue,
+ });
+ await screen.findByText("docs");
+ fireEvent.keyDown(rowFor("docs"), { key: "Enter" });
+ await waitFor(() =>
+ expect(listDirectory).toHaveBeenCalledWith({ path: "/home/user/docs" }),
+ );
+ // navigation does not mutate value
+ expect(setValue).not.toHaveBeenCalled();
+ });
+
+ it("Enter toggles selection on a selectable file", async () => {
+ const setValue = vi.fn();
+ renderBrowser({ selectionMode: "all", multiple: true, setValue });
+ await screen.findByText("a.txt");
+ fireEvent.keyDown(rowFor("a.txt"), { key: "Enter" });
+ expect(setValue).toHaveBeenCalledWith([
+ expect.objectContaining({ path: "/home/user/a.txt" }),
+ ]);
+ });
+
+ it("Space toggles selection and never navigates", async () => {
+ const setValue = vi.fn();
+ renderBrowser({ selectionMode: "all", multiple: true, setValue });
+ await screen.findByText("docs");
+ // Space on a selectable directory selects it (does not navigate)
+ fireEvent.keyDown(rowFor("docs"), { key: " " });
+ expect(setValue).toHaveBeenCalledWith([
+ expect.objectContaining({ path: "/home/user/docs" }),
+ ]);
+ });
+
+ it("Space on the parent row is a no-op", async () => {
+ const setValue = vi.fn();
+ renderBrowser({ selectionMode: "all", setValue });
+ await screen.findByText("docs");
+ const parentRow = screen.getAllByRole("row")[0];
+ fireEvent.keyDown(parentRow, { key: " " });
+ expect(setValue).not.toHaveBeenCalled();
+ });
+});
+
+function rowFor(name: string): HTMLElement {
+ return screen.getByText(name).closest('[role="row"]') as HTMLElement;
+}