🎫 Jira Ticket Quality Rewriter

CustomerList: Add multi-filter support (plan tier + signup date)

Title

CustomerList: Add multi-filter support for plan tier and signup date

User Story

As a sales team member, I want to filter the Customers list by plan tier and signup date (combined or independently), so I can find specific customer cohorts in <30 seconds instead of scrolling.

Background / Why

Sales team feedback (see PRD-892): currently spending 5+ minutes/day scrolling Customers to find specific accounts for outreach. Plan-tier filter is most-requested (segment by Pro/Business customers); signup-date filter enables cohort-based outreach (e.g., 'reach out to all Q1 2026 signups'). The Deals list (ENG-1245) already has multi-filter; we're following that pattern for consistency.

Acceptance Criteria

1. User can open the filter bar from the Customers list page header (consistent UI placement with Deals list).

2. User can filter by Plan Tier with multi-select: Free, Starter, Growth, Enterprise. At least one tier can be applied.

3. User can filter by Signup Date with: 'Last 7 days,' 'Last 30 days,' 'Last 90 days,' 'This year,' 'Custom range' (with date pickers).

4. Filters can be combined (Plan Tier + Signup Date both applied = AND logic). Filters within a single field (e.g., Free + Starter) = OR logic.

5. Filter state persists in the URL query string (so links can be shared).

6. Customer list refreshes within 500ms of filter change (paginated; existing list pagination preserved).

7. Active filters show as chips above the list with 'remove' button per chip.

8. 'Clear all filters' button shows when 1+ filter is active.

9. Filter count badge displays on the filter button (e.g., '2' when 2 filter chips are active).

10. Empty result state: shows 'No customers match these filters' with 'Clear filters' CTA.

In Scope

• Filter UI on Customers list (Plan Tier + Signup Date only)
• URL query string sync
• Empty result state
• Filter chip display + remove
• Backend API support for these filters (likely small adjustment to existing /api/customers query)
• Tests (unit + integration)

Out of Scope

• Saved/named filter sets ('My Q1 Cohort' saved filter) — defer to future ticket
• Other filter dimensions (industry, company size, MRR, etc.) — defer
• Bulk actions on filtered results — separate ticket
• Filter on Deals list (already exists)
• CSV export of filtered customers — separate ticket if needed
• Mobile-specific filter UX optimization beyond responsive defaults

The 5 Questions Most PMs Forget

1. Empty state

When the filter set returns 0 customers: show 'No customers match these filters' message with a 'Clear filters' CTA button. Don't show the loading skeleton or 'no customers exist' (different from no-match).

2. Error state

If the filter API call fails: show toast/banner 'Couldn't apply filters. Please try again.' Customer list reverts to most recently successful filter state. Filter UI remains active so user can retry without losing their selections.

3. Mobile / responsive

Desktop (≥1024px): filter bar is a horizontal row with all filter buttons visible.

Tablet (640-1024px): filter bar wraps if needed; chip display below filters.

Mobile (<640px): filter button is a single 'Filter' button that opens a drawer/modal with the filter UI. Chips display below the customer list header.

4. Accessibility

• All filter controls are keyboard-navigable (Tab, Enter, Escape).
• Filter button has aria-expanded to indicate open/closed state.
• Filter chips have aria-label indicating what they filter and how to remove.
• Color contrast WCAG AA on all states (active chip, inactive button, etc.).
• Screen reader announces filter changes ('Filter applied: Plan Tier Pro. Showing 47 customers.').

5. Analytics / observability

Log these events:

• customer_list_filter_applied with properties: { plan_tiers: [...], signup_date_range: '...', total_results: N, user_id, timestamp }
• customer_list_filter_cleared
• customer_list_filter_combined (when 2+ filters active)

Monitor:

• Filter API call latency (p50, p95). Alert if p95 >800ms.
• Filter API error rate. Alert if >2%.

Technical Context

• Reuse: <FilterBar> component from /components/FilterBar (built in ENG-1245). Add customer-list mode to existing variants. Don't build new.
• Backend: /api/customers currently supports query params for pagination. Extend to accept plan_tiers[] and signup_after, signup_before query params. Existing query is in services/customer-list.ts:fetchCustomers().
• State management: existing list uses URL-state (via Next.js router query). Filter state goes in same place.
• Pattern to follow: see ENG-1245 implementation, especially the chip-display logic and the URL-sync hook.
• Database: Customers table has plan_tier (enum) and signup_at (timestamp) — both already indexed. No migration required.
• Caching: existing list uses SWR with stale-while-revalidate. Filter changes invalidate cache for the new filter combo, so first-time filters may be slower.

Edge Cases

1. No plan tier selected, just date filter active: valid; shows all tiers within date range.

2. Custom date range with end < start: disable Apply button + show inline 'End date must be after start.' validation.

3. Custom date range with future end date: allow it (returns 0 results since no customers signed up in future). Don't auto-clamp to today.

4. Filter applied while list is mid-loading: cancel pending request, fire new one with new filter.

5. Browser back-forward with filters in URL: restore filter state from URL on navigation.

6. All 4 plan tiers selected: equivalent to no plan-tier filter; behave identically (or auto-clear filter to indicate no filtering).

7. Very long custom date range (5+ years): allow but warn 'This may load slowly' (>10K results).

Test Cases

1. Apply Pro tier filter: customer list shows only Pro tier customers; URL updates with `?plan_tiers=pro`.

2. Apply Last 30 days filter: customer list shows only customers who signed up in last 30 days.

3. Combine Pro + Last 30 days: list shows Pro customers from last 30 days only.

4. Apply 2 tiers (Pro + Growth): list shows OR — both Pro and Growth customers.

5. Apply filter that returns 0 customers: empty state visible with 'Clear filters' CTA. Click CTA → filters clear, full list returns.

6. Share URL with filter: open URL in new browser → filter is pre-applied, list shows filtered results.

7. Mobile viewport: filter button opens drawer; UX is functional with touch.

8. Keyboard nav: Tab to filter button → Enter → Tab through filter options → Enter to apply.

9. API error simulation (network mocked failure): error toast appears; filter UI remains; retry works.

10. Performance (~10K customers): filter applies in <500ms p95.

Definition of Done

• [ ] Code merged to main
• [ ] Unit tests added and passing (FilterBar variant tests, API query tests)
• [ ] Integration test added (Cypress or Playwright) covering ACs 1-5 + 10
• [ ] Code review completed by 1 reviewer
• [ ] Deployed to staging
• [ ] Manual smoke test by PM on staging
• [ ] Analytics events verified firing in staging
• [ ] Accessibility check passed (axe-core or manual screen reader test)
• [ ] Documentation updated if any new patterns introduced
• [ ] Sales team Slack notified when shipped to prod

Estimate

Medium (5 story points / 3-5 days). Reasoning:

• FilterBar component reuse drops UI work to ~1 day
• Backend query extension is ~0.5 day
• URL sync + chip display + empty state: ~1 day
• Tests + a11y verification: ~1 day
• Buffer: ~0.5 day

Caveats: if the FilterBar component needs significant refactoring to support the customer-list variant (which we don't yet know), estimate could grow to Large (8 points).

Open Questions

• None for v1 scope. All 5 'PM forgets' answered above.

Suggested Sub-Tasks

1. Backend: extend /api/customers to accept plan_tiers + signup_at filter params (0.5 day)

2. Frontend: add customer-list variant to FilterBar component (1 day)

3. Frontend: add chip display + URL sync for customer list (1 day)

4. Empty state + error state UI (0.5 day)

5. Tests + a11y verification (1 day)

6. Analytics events + observability (0.5 day)

The PM/eng-lead can decide whether to break this into actual Jira sub-tasks or keep as one ticket with internal task tracking.