Add autoFocus support to FilterPanel search input

[cratis-direct]

The FilterPanel's inline search box would benefit from an autoFocus property on FilterDefinition to auto-focus the search input when a filter group is expanded.

This would enable UX patterns where users can open a filter facet and immediately start typing to search (e.g., in the Stagehand Backlog, the repository filter would auto-focus its search when opened).

Suggested implementation:

• Add optional autoFocus?: boolean to FilterDefinition interface
• When a filter with autoFocus=true is expanded, add autoFocus attribute to the OptionList's search input

[cratis-direct]

Investigation

Investigation summary — #244 (feature request, not a bug)

This is Source/Filter/FilterPanel.tsx (the standalone @cratis/components/Filter panel), specifically the per-group inline search box in the internal OptionList (.pv-filter-group-search input, FilterPanel.tsx:172-180), not the panel-level .pv-search box.

Evidence gathered by running code, not by reading it. I wrote a temporary probe spec against the real FilterPanel, ran it (3/3 passing), and deleted it. It established:

1. The group search input is in the DOM while the group is collapsed — collapsed content is hidden with max-height: 0; overflow: hidden; opacity: 0 (FilterPanel.css:262-275), not unmounted.
2. Nothing is focused when the panel opens.
3. Expanding a group does not remount OptionList: the input element is identity-equal (===) before and after, and text typed while collapsed survives the expand.

That falsifies the implementation sketched in the issue body ("add autoFocus attribute to the OptionList's search input"). React's autoFocus fires only on mount, and mount happens when the panel opens — so a static attribute would focus a visually hidden input at panel-open time and would never fire on expansion. Focus has to be driven by an effect keyed on expansion. The repo already has that pattern in Source/Chat/Kit/ChatComposer.tsx:170-173.

Working tree is clean; baseline Filter specs pass (55 files / 149 tests).

SUGGESTED-MODEL: sonnet

Plan

Settled — do not redo

• Target is the per-group search box, OptionList inside Source/Filter/FilterPanel.tsx, not the panel-level .pv-search input.
• Prop name is autoFocus?: boolean on FilterDefinition, as the issue asks. Don't rename it.
• A plain autoFocus attribute does not work — proven above. Use a useEffect + ref keyed on expansion.
• Framework profile repo (Cratis/Components): no vertical slices, no [Command]/proxy work. Specs use the plain Vitest + Chai + jsdom style already in Source/Filter/for_FilterPanel/.
• Source/PivotViewer/components/FilterPanel.tsx delegates to this panel but its PivotFilter type carries no searchable at all, so it never renders a group search box. Out of scope — no change needed there.
• No API snapshot / compat-manifest entry covers individual props; compat-manifest.json is package-version scope only, so nothing to regenerate.

Steps

1. Source/Filter/types.ts — add to FilterDefinition, next to searchable/searchPlaceholder:

   /** Focus this group's inline search box when the group is expanded. Requires `searchable`. */
   autoFocus?: boolean;

2. Source/Filter/FilterPanel.tsx —

   • Add isExpanded: boolean to OptionListProps and pass it at the call site (isExpanded is already computed in the filters.map callback).
   • In OptionList: add const searchInputRef = useRef<HTMLInputElement>(null);, put ref={searchInputRef} on the group search input, and

     useEffect(() => {
         if (!filter.autoFocus || !filter.searchable || !isExpanded) return;
         searchInputRef.current?.focus();
     }, [filter.autoFocus, filter.searchable, isExpanded]);

   • Keying on isExpanded makes it fire both on expand and on panel-open when expandedFilterKey already names that group. It must not fire while collapsed — that is the bug the naive attribute would introduce.
   • Optional refinement if the CSS max-height transition causes the panel body to jump: focus({ preventScroll: true }), or defer with requestAnimationFrame + cancelAnimationFrame cleanup (precedent: Source/Dialogs/DialogImplementation.tsx:93). Prefer the plain synchronous focus() first — it keeps specs simple; only reach for a deferral if a Storybook play test shows visible jank.

3. Specs — new Source/Filter/for_FilterPanel/when_a_filter_group_auto_focuses_its_search.tsx, modeled on when_a_filter_group_has_no_own_search_placeholder.tsx (same jsdom/createRoot/act harness). Cover:

   • group with autoFocus + searchable, rendered already expanded → its search input is document.activeElement;
   • group with autoFocus rendered collapsed → not focused (this is the regression guard for the naive-attribute implementation);
   • re-rendering with expandedFilterKey switched to that group → it becomes focused;
   • a searchable group without autoFocus → never focused, and a second, non-expanded autoFocus group does not steal focus from the expanded one.

4. Docs — Documentation/Filter/index.md. There is no FilterDefinition field table today and searchable is undocumented; add a short "Searchable filter groups" subsection covering searchable, searchPlaceholder and the new autoFocus (stating that autoFocus only applies when searchable is true, and fires when the group is expanded). Optionally add an autoFocus variant to Source/Filter/FilterPanel.stories.tsx, which already has an openFilterGroup play helper to assert focus with.

5. Gates (run from /workspace/Source): npx vitest run Filter, npx tsc -b, yarn lint (root: node ./run-task-on-workspaces.js lint). Note yarn install was needed — node_modules was absent — and Node here is 22 while engines asks for ≥23; the install and the Vitest run both worked anyway.

6. PR label: minor — a new, non-breaking public API addition on an exported type.

Needs a human decision (neither blocks implementation; default is "no")

• Return focus to the group's toggle button when the group collapses? An a11y nicety the issue doesn't ask for. Default: don't.
• Clear the group's search text on collapse? Today it persists across collapse/expand (proven in step 3 of the probe). Changing that is a behavior change beyond this issue. Default: leave as-is.

Suggested model for implementation: sonnet

---

Posted by Stagehand (AI) - an autonomous agent, not a person. Review accordingly.

[cratis-direct]

Thanks for opening this - it has been received and will be looked at.

---

Posted by Direct (AI) - an autonomous agent, not a person. Review accordingly.