# Code maintenance AGILE-375 - Unify filter controls and submission behavior

Project: Stream agile
Status: in development
URL: https://community.openproject.org/work_packages/AGILE-375

## OPEN POINTS

_No work packages_

## Subtasks

| ID | Subject | Type | Status | Assignee | Project | Target versions |
| --- | --- | --- | --- | --- | --- | --- |
| AGILE-450 | Modify the bucket_ids and sprint_ids filter format to align it with the other backlog filters | Feature | merged |  | Stream agile | 18.0.0 |

## Details

| Attribute | Value |
| --- | --- |
| Assignee | Alexander Coles |
| Accountable |  |
| Designer |  |
| Developers | Alexander Coles |
| Requires doc change | No |
| Date |  |
| Priority | Medium |
| Target versions |  |
| Sprint |  |
| Backlog bucket |  |
| Module |  |
| Accessibility | No |
| List |  |
| Labels |  |

## Estimates and progress

| Attribute | Value |
| --- | --- |
| Work |  |
| Remaining work |  |

## Description

### Goal

Unify filter controls and submission behavior across Backlogs and Meetings, reduce duplicated logic, and split the existing filter form controller into smaller parts with explicit Stimulus responsibilities.

### Context and delivery

The earlier backlog-only implementation in [PR <mention class="mention" data-id="23820" data-type="work_package" data-text="#23820">#23820</mention>](https://github.com/opf/openproject/pull/23820) is closed. It remains useful historical work, but its scope and branch name no longer match this task. The replacement will use a fresh branch from current dev and a new PR after specification review and implementation planning.

The work-package filter bar from <mention class="mention" data-id="AGILE-219" data-type="work_package" data-text="#AGILE-219">#AGILE-219</mention> has already landed. This work integrates with that filter bar; it is no longer a prerequisite for introducing it.

### Agreed scope

  - A reusable, query-independent wrapper around Primer SelectPanel, shared by Backlogs, Meetings and all existing quick-filter consumers. Supports local and asynchronously loaded options, accessible interaction, and existing single-select links.
  - One multi-select interaction contract: Apply commits the draft; Clear immediately requests removal of that filter; Escape, close, or click-away discards unsubmitted panel edits. Pending edits elsewhere in the advanced filter form are preserved when submitting.
  - Shared pure helpers for filter composition, existing expression/JSON serialization, and URL changes. Keep compact backlog container URLs, with client and server compatibility for legacy array links. Clear and Apply remove stale parameter aliases without dropping unrelated filters.
  - A dedicated filter navigation coordinator for existing frame, stream, Turbo Drive and hard full-page behavior. Separate submission intent from navigation and preserve hidden-input form embedding.
  - Per-filter row controllers for operator/value state, visibility, widget adaptation and focus. The form controller coordinates rows, owned/unowned filters, counters and submission. Use Stimulus actions, targets and outlets rather than manual cross-controller lookup.

### Recovery and consistency

The previous accepted limitation requiring a page reload after a failed visit is superseded. Failed filter requests must retain applied state, allow retry, and preserve the draft where the panel remains open. Duplicate submissions and stale responses must not overwrite newer results or browser history. Owned timers and requests must be cleaned up correctly, distinguishing page disconnection from replacement of a panel by a successful request.

The specification details no-op behavior, asynchronous option loading, pending form edits, split-view routing, browser history and component replacement/morphing. Independent review and browser characterization have identified transport/lifecycle gaps; the detailed recovery contracts remain design targets pending the decisions below.

### Future LiveComponent suitability

Keep state serializable and component boundaries replaceable, informed by [POC <mention class="mention" data-id="24442" data-type="work_package" data-text="#24442">#24442</mention>](https://github.com/opf/openproject/pull/24442). A later LiveComponent adoption may replace state/render coordination as well as transport. Do not add LiveComponent dependencies or infrastructure in this task.

### Verification and documentation

Cover shared behavior with pure helper tests, real Primer interaction tests, component specs and Backlogs/Meetings integration scenarios. Include legacy links, combined filters, async options, failure/retry, out-of-order responses, split views, history and lazy forms. Provide Lookbook examples for the shared wrapper and integrated filter experience.

Manual acceptance scenarios inherited from the <mention class="mention" data-id="AGILE-432" data-type="work_package" data-text="#AGILE-432">#AGILE-432</mention> follow-up (<https://github.com/opf/openproject/pull/25519>); each must still hold after the row/coordinator split:

1.  Meetings index, "Past" quick filter: add "Meeting status" without picking a value → the row stays after the list re-renders, the list is unchanged, and the URL carries no `state` filter.
2.  Pick a status → the list narrows; the "Meeting status" option in "Add filter" stays disabled; removing the row re-enables it.
3.  Add a text row (e.g. Title), type a value, navigate away before it submits, then go Back → the row is gone; re-adding "Title" shows an empty field and sends no request.
4.  Projects index: add "Created on" with "between" and no dates → the list stays complete and the URL carries no `created_at` filter; picking both dates narrows it; a one-sided range is still submitted.

### Scope boundaries

Retain existing expression and JSON formats; container visibility stays separate from work-package attribute filtering. The broader serialization proposal remains <mention class="mention" data-id="AGILE-381" data-type="work_package" data-text="#AGILE-381">#AGILE-381</mention>. Do not redesign the query language, replace Angular inputs, or refactor unrelated request consumers.

### Related request infrastructure

<mention class="mention" data-id="OP-20147" data-type="work_package" data-text="#OP-20147">#OP-20147</mention> ([PR <mention class="mention" data-id="25273" data-type="work_package" data-text="#25273">#25273</mention>](https://github.com/opf/openproject/pull/25273)) owns the framework-independent Turbo request module, lifecycle scopes and shared progress accounting. Align filter submission with that foundation rather than introducing a competing request layer. <mention class="mention" data-id="OP-20194" data-type="work_package" data-text="#OP-20194">#OP-20194</mention> already includes migrating `filters-form.controller.ts`; coordinate ownership and sequencing to avoid duplicate migration work.

The current proposed shared request helper automatically renders successful/422 streams before returning. Browser characterization confirms that a check immediately before stream dispatch is also insufficient: actions can run after a newer intent starts. Filter stale-response protection needs ownership checks at action execution and a defined completion contract; a check after awaiting the request is insufficient. Shared scope/progress tracking alone does not implement latest-request-wins or filter retry behavior. <mention class="mention" data-id="AGILE-393" data-type="work_package" data-text="#AGILE-393">#AGILE-393</mention> owns general error-response policy and <mention class="mention" data-id="OP-13356" data-type="work_package" data-text="#OP-13356">#OP-13356</mention> owns broader frame/stream failure feedback; this ticket owns filter-specific applied/draft state and retry behavior.

### Current state

Architecture, common interaction semantics, retryable recovery and LiveComponent migration constraints are agreed. Independent specification review and initial Chromium characterization are complete. The probes used installed Turbo/Primer with controlled fixtures, not the full application test suite. They confirmed destructive frame failure behavior, failed frame src retention, history effects during recovery/overlap, Primer selection divergence after morphing, and stale stream actions after dispatch. No production remedy is validated yet.

<mention class="mention" data-id="OP-20147" data-type="work_package" data-text="#OP-20147">#OP-20147</mention> is already a formal predecessor. Agreed sequencing: Backlogs retains Turbo Frames and shared recovery comes first. <mention class="mention" data-id="OP-13356" data-type="work_package" data-text="#OP-13356">#OP-13356</mention> is required before frame-recovery delivery, coordinated with <mention class="mention" data-id="AGILE-393" data-type="work_package" data-text="#AGILE-393">#AGILE-393</mention>. The formal predecessor link remains to be added. <mention class="mention" data-id="OP-20223" data-type="work_package" data-text="#OP-20223">#OP-20223</mention> remains a conditional dependency: require it if the shared solution depends on removing the global successful frame-missing fallback. The non-success failure probes alone do not establish that requirement. No additional formal predecessor links have been created by this update.

[PR <mention class="mention" data-id="25417" data-type="work_package" data-text="#25417">#25417</mention>](https://github.com/opf/openproject/pull/25417) / <mention class="mention" data-id="OP-20215" data-type="work_package" data-text="#OP-20215">#OP-20215</mention> was a release-branch reload-loop guard, not the permanent frame failure solution. Avoid introducing a competing filter-local failure policy.

Backlogs transport and sequencing are decided: retain Turbo Frames and deliver shared recovery first. This does not relax the required concurrency/history guarantees; the shared design must establish them. Remaining decisions are whether Meetings panels move from Drive to streams and recovery scope for the other quick-filter consumers. Preserve the agreed consistency goals until those decisions are explicit. The specification is not ready for implementation planning. The old branch remains historical assessment work; no shared-filter implementation has started.

### Interim behavior from <mention class="mention" data-id="AGILE-432" data-type="work_package" data-text="#AGILE-432">#AGILE-432</mention> to carry over

<https://github.com/opf/openproject/pull/25519> (follow-up to <mention class="mention" data-id="AGILE-432" data-type="work_package" data-text="#AGILE-432">#AGILE-432</mention>, on dev) gives the current `filters-form.controller.ts` client-side draft state for an added row that carries no value yet: the row is marked `data-filter-pending`; a `turbo:before-morph-attribute` guard keeps the marked row visible and its add-filter option taken through a morph of the form (Meetings morphs its subheader); on `connect()` a stale marker hides the row again and resets its controls to server defaults, because Turbo's snapshot keeps typed values. An empty date range (`"-"` as rendered by the picker, or `""`) parses as no value; one-sided ranges are still submitted. The empty row never reaches the request, URL or history.

The row-controller split and the navigation coordinator must preserve those outcomes: an added value-less row is draft, not applied state; it survives in-place morphs and is dropped on cached-page restore, controls included; pagination/expansion keys reset only when a filter with a value changes. The marker is the interim carrier of that draft and is replaced by the row controller's own model. `sendForm()` now starts by releasing submitted pending rows; <mention class="mention" data-id="OP-20194" data-type="work_package" data-text="#OP-20194">#OP-20194</mention> PR B rebases over it.
