Skip to content

feat(files): give the empty capped tree a search next step - #21018

Merged
bolichen97 merged 1 commit into
mainfrom
fix/empty-capped-tree-next-step-20554
Oct 16, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
fix/empty-capped-tree-next-step-20554

Conversation

@bolichen97

@bolichen97 bolichen97 commented Oct 16, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: When a project is too big to list and the tree has no rows, the folder panel and the Files rail each show one next step that works there.

The empty capped tree says "Workspace too large to list: limit of 10,000 items reached" and stops. It names what happened but not what to do. The same tree is shown by the folder panel and by the Files rail, and on both the search box above it can already find files past the limit (#20523 and #20495), but nothing points the user there.

Why it matters

A user on a very large project sees an empty panel with no way forward, even though the search a few pixels up would find their file. This is a follow-up deferred from the UX Review of #20495.

Not a goal

  • Changing the 10,000-item cap or how the server lists the tree.
  • Changing the search boxes, their placeholders, or the Content (grep) mode.
  • Any other empty state of the tree (empty workspace, hidden-only root, unreadable root).

What changed (motivation → approach → change)

The empty capped tree had no next step. Both places that show the tree, the folder panel and the Files rail, put a box above it whose name query already goes past the cap (#20495, #20523). So the tree itself can point there.

  • The tree (website/src/pierre/PierreWorkspaceTreeImpl.tsx) adds one line under the limit message when the tree is capped and has no rows: "Type a file name in the box above to find it." It says "box", not "search box", because the rail's box is labelled "Filter files…".
  • New string components.workspaceTree.root_truncated_search_hint in en.manual.json, all 12 translated catalogs and the regenerated en-XA pseudolocale.

Earlier heads used a focus button, then a host flag; review showed the button read as a copy of the box and the flag guarded a host that does not exist, so both are gone.

Backwards compatibility

Compatible: one new line of text in one empty state; no prop, API or behaviour changes.

Removes nothing: the diff only adds a line of text and a catalog key.

Tests

  • PierreWorkspaceTreeImpl.test.tsx: the empty capped tree shows the hint line under the limit message.

Local gates: that file plus FolderPanel.tree.test.tsx, FileBrowserRail.test.tsx and PierreWorkspaceTree.lazy.test.tsx pass (251 tests), tsc -p tsconfig.app.json, eslint on the changed files and npm run i18n:check are clean. The clone has no git hooks installed, so no commit hook ran.

Manual verification

Driven in Chromium (scripted Playwright, real FolderPanel, real FileBrowserRail, real Pierre tree and catalogs, /api/project/tree stubbed to an empty capped payload and /api/file-search to two hits), light and dark. On each surface the hint line shows under the limit message with the box directly above (asserted by its text); typing "invoice" in that box then lists the server's matches past the limit. The temporary capture entry was not committed.

Screenshots / video

Folder panel, empty capped tree, then after typing in its search box:

Folder panel: empty capped tree with the search hint (light)
Folder panel: search results past the limit (light)

Files rail, same steps:

Files rail: empty capped tree with the search hint (dark)
Files rail: name search results past the limit (dark)

Other theme

Folder panel empty capped tree (dark)
Folder panel search (dark)
Files rail empty capped tree (light)
Files rail search (light)

Related Issues

Closes #20554

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

@bolichen97
bolichen97 requested review from a team and KiroCrewCaptain as code owners October 16, 2026 00:25
@bolichen97
bolichen97 requested a review from buluoray October 16, 2026 00:25
@bolichen97
bolichen97 enabled auto-merge (squash) October 16, 2026 00:25
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 16, 2026
@github-actions

github-actions Bot commented Oct 16, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 5e52e970b939f97fb2d900a26401b1199a19a9e3 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Nothing to check.

[DESIGN-REVIEWED] 5e52e97

Description read

[DESCRIPTION-READ] 2b67a8774687c55aea161c0c280840f9914cd4761a455bdc78b344675317af49

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 16, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 5e52e970b939f97fb2d900a26401b1199a19a9e3 — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

First-Principles-Verdict: PASS

Before merge, check that the box above the tree is still on screen when the capped tree is empty, in both the folder panel and the Files rail.

What this change ships

Inventory (2 items) — 2 justified

Intent: when a project is too big to list, a user looking at the empty file tree learns that the box above it can still find their file. ADDITION.

  1. The empty capped tree now shows a line under the limit message: "Type a file name in the box above to find it." — justified
  2. That line is translated into 12 languages and added to the en-XA pseudolocale — justified

[FIRST-PRINCIPLES-REVIEWED] 5e52e97

Description read

[DESCRIPTION-READ] 80b3ecc8f02a51a3f0dfca375853b8a1f3f2fe11e054ae2bdeb69a017adc7dac

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Oct 16, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ✅ PASS

UX-level review of 5e52e970b939f97fb2d900a26401b1199a19a9e3 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

UX-Verdict: PASS

Check the hint line wrapping in the narrow Files rail: shot-03 shows the hint ending with "it." alone on its own line.

[UX-REVIEWED] 5e52e97

Description read

[DESCRIPTION-READ] 528cc8fdd531a8976a35bfeb2d2cc0c2a24b2dd1782142da8c2a5a2f307c7f06

That sha256 names everything this verdict read: the PR description, plus the 11 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 16, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 5e52e970b939f97fb2d900a26401b1199a19a9e3 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 5e52e97

Verdict parsed from the review's SHA-scoped output markers for commit 5e52e970b939f97fb2d900a26401b1199a19a9e3.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 5e52e970b939f97fb2d900a26401b1199a19a9e3: <one-sentence reason>

@github-actions

github-actions Bot commented Oct 16, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 5e52e970b939f97fb2d900a26401b1199a19a9e3 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 5e52e97

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 5e52e970b939f97fb2d900a26401b1199a19a9e3: <one-sentence reason>

@bolichen97
bolichen97 force-pushed the fix/empty-capped-tree-next-step-20554 branch from bcf8633 to c2d9672 Compare October 16, 2026 00:39
@bolichen97

bolichen97 commented Oct 16, 2026 •

Copy link
Copy Markdown
Contributor Author
  • span=0614b5e405d4 The button's job is unclear.

Fixed in c2d9672: the label is now "Find a file by name" in all 13 catalogs, an invitation to type rather than a promise that a search runs. The click still focuses the surface's own search box, the one place that reaches files past the limit on each surface. Screenshots re-captured with the new label.

@bolichen97

bolichen97 commented Oct 16, 2026 •

Copy link
Copy Markdown
Contributor Author
  • span=1397c107dea6 The limit message doesn't say whether something is broken.

Deferred: the limit sentence itself is #20495's copy, and rewording it is outside this PR's goal (a next step under the message). The button now sits right under it, so the message is no longer a dead end; a follow-up issue tracks the wording.

@bolichen97

bolichen97 commented Oct 16, 2026 •

Copy link
Copy Markdown
Contributor Author
  • span=f1ad4f792cc1 Put the next step into the message, or rename the button.

Taken in part: the button is renamed to "Find a file by name", which is the suggestion's second half. Folding the step into the limit sentence is deferred with the wording follow-up, since it rewrites #20495's string.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • Neither host omits onFindFiles, so the button-less branch runs only in tests.

Kept on purpose: the tree is a shared component and the prop is optional, so a future host with no search box must not inherit a button that goes nowhere. The branch is one conditional, and PierreWorkspaceTreeImpl.test.tsx pins it.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 16, 2026
@bolichen97
bolichen97 force-pushed the fix/empty-capped-tree-next-step-20554 branch from c2d9672 to 41970ca Compare October 16, 2026 00:51
@bolichen97

Copy link
Copy Markdown
Contributor Author
  • span=e3654af2e4ee The button doesn't say why it's there.

Fixed in 41970ca: the label is now "Search all files by name" in all 13 catalogs, so it says the search reaches files the capped list does not show. Screenshots re-captured.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • span=6f3ae8ac5a78 Change root_truncated_find to say the search goes past the limit.

Taken as suggested: "Search all files by name".

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • Is the folder panel's Search files box visible and enabled wherever the button shows?

Yes. The box is rendered unconditionally above the body in FolderPanel and is never disabled; the tree (and so the button) only mounts in tree mode at the project root, under that box. FolderPanel.tree.test.tsx asserts the click lands focus on it.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • Does the label fit the Files rail, whose box says Filter files…?

Yes. The empty capped state only renders when the payload is truncated, and in that state the rail's name query goes to the server filename search (nameSearch = truncated && Name mode && 2+ chars), so the box does search all files there. The placeholder is out of this PR's goal (Not a goal: changing the search boxes or their placeholders).

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 16, 2026
@bolichen97
bolichen97 force-pushed the fix/empty-capped-tree-next-step-20554 branch from 41970ca to e230e8b Compare October 16, 2026 01:04
@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in website/src/i18n/locales/* since this head went green (818b437 -> 5ddd790); CI re-running.

@bolichen97

Copy link
Copy Markdown
Contributor Author

self-added: no
mechanism: the empty capped tree's next step is a host-gated hint line, not a focus button

  • span=e89d9fcaff91 The button promises a search but only moves focus.

Fixed in e230e8b by removing the button: a third round showed any focus-only button reads as a copy of the box above it. The tree now shows the line "Type a file name in the search box above to find it." under the limit message, only on hosts whose box reaches past the cap (folder panel, Files rail). Retrospective this round: remove the button mechanism, smaller replacement keeps the goal.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • span=2e038fc5711e Describe what the button does and point at the box.

Taken: the step now names the box ("Type a file name in the search box above to find it."), as plain text rather than a button.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • span=be7ad723809a Put the hint in the search box placeholder.

Not taken: the placeholders belong to the two hosts and are outside this PR's goal (Not a goal: changing the search boxes or their placeholders). The hint line under the limit message points at the box on both surfaces instead.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • The truncated-but-non-empty tree still has no route to search.

Agreed it is outside the frozen goal, which covers the tree with no rows. That state already shows rows plus the existing "Some items not shown" markers, and the same search box sits above it; a hint there is a separate change for its own issue.

@bolichen97
bolichen97 force-pushed the fix/empty-capped-tree-next-step-20554 branch from e230e8b to 8042033 Compare October 16, 2026 01:17
@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in website/src/i18n/locales/* since this head went green (5ddd790 -> 5d899b0); CI re-running.

@bolichen97

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: removed the searchHint host flag

  • span=6fe2f85c36a5 One consumer, generalized: both hosts pass searchHint.

Fixed in 8042033: the prop is removed from the tree, its lazy wrapper and both hosts. The tree shows the line on its own; a code comment at the line names the two hosts and the invariant (a new host without a past-cap box must not mount this state). Diff is now one source file, one test and the catalogs.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • span=e0abd61d09bf The hint names the box differently from the rail.

Fixed in 8042033: the line is now "Type a file name in the box above to find it.", which fits both the folder panel's "Search files" and the rail's "Filter files…" box. Screenshots re-captured.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • span=fab79fb1d28b Drop the clashing word.

Taken as suggested, with the 12 translated catalogs and en-XA regenerated.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • Check the box the hint names sits directly above the empty capped tree.

Yes in both re-captured frames: the folder panel's "Search files" box sits right above the tree body, and the rail's "Filter files…" box sits above it with only the Name/Content toggle between.

@bolichen97

bolichen97 commented Oct 16, 2026 •

Copy link
Copy Markdown
Contributor Author
  • The code comment is the only thing keeping the hint true.

Accepted as the trade-off: last round's review removed the host flag that enforced it in code, because no third host exists. Both hosts today render a past-cap box above the tree; a future host is a reviewed change that will touch this file's empty state.

@bolichen97
bolichen97 force-pushed the fix/empty-capped-tree-next-step-20554 branch from 8042033 to 4ffc297 Compare October 16, 2026 01:36
@bolichen97

Copy link
Copy Markdown
Contributor Author
  • Does the rail's hint make sense in Content mode?

It never shows there: in Content mode FileBrowserRail renders ContentResults in place of the tree (contentMode ? <ContentResults …/> : …), so the empty capped state and its hint only mount in Name mode, where the box searches names past the cap.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • In the Files rail the hint wraps and leaves "it." alone on a line.

Will balance the wrap (text-balance on the hint line) in the next push, which this PR needs anyway to rebase onto main.

@bolichen97
bolichen97 force-pushed the fix/empty-capped-tree-next-step-20554 branch from 4ffc297 to 5e52e97 Compare October 16, 2026 02:31
@bolichen97

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in website/src/i18n/locales/* since this head went green (5d899b0 -> 04904e2); CI re-running. Also folds in text-balance on the hint line (the UX wrap note on 4ffc297).

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • Is the box above the tree still on screen when the capped tree is empty?

Yes on both surfaces: the folder panel's search row and the rail's header row render unconditionally above the tree body, and the re-captured frames (empty state, light and dark, both surfaces) show the box above the hint.

@bolichen97

Copy link
Copy Markdown
Contributor Author
  • The hint wraps with "it." alone in the narrow rail.

Fixed in this head (text-balance on the hint line); the screenshots were re-captured on it and now show the rail hint as two even lines ("Type a file name in the / box above to find it.").

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Oct 16, 2026
@bolichen97
bolichen97 disabled auto-merge October 16, 2026 07:16
@bolichen97
bolichen97 merged commit 5af145e into main Oct 16, 2026
112 of 113 checks passed
@bolichen97
bolichen97 deleted the fix/empty-capped-tree-next-step-20554 branch October 16, 2026 07:16
@github-actions github-actions Bot removed readiness: passed Eligible automated validation passed for the current revision labels Oct 16, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Empty capped project tree: a next step that works on each surface

2 participants