# Natural Language Filters

## Objective

Let people describe what they want to see and turn it into filters they can inspect and edit.

A plain-language input on list views that produces the app's normal filter chips, shown for review before they apply.

## Before You Begin

This feature is being added to an application that already exists and already
works. Do not scaffold a new project, and do not assume a blank slate.

Inspect the codebase first and establish:

- The existing application structure and where code of this kind already lives.
- The framework and version in use.
- The existing design system — colours, spacing, typography, and component conventions.
- Existing UI components you can reuse instead of writing new ones.
- The existing database structure, if this feature needs to persist anything.
- The existing authentication and authorization system, if this feature is user-scoped.
- Dependencies already installed, so you don't add a library that duplicates one.
- The existing test setup and conventions.

Only start writing code once you understand the above. If the application
already implements part of this feature, extend it rather than replacing it.

## Implementation Instructions

1. Give the model a machine-readable description of the filterable fields, their types, their allowed operators, and their permitted values, derived from the app's existing filter definitions. It selects from that description and returns a structured filter set; it does not write query syntax.
2. Render the result as the app's ordinary filter controls, in the pending state, and require the user to apply them. Do not run the query on the model's output directly, and do not skip the review step even when confidence looks high.
3. Resolve relative expressions such as last week or this quarter against the user's time zone and the workspace's week and fiscal-year settings, and show the resolved absolute dates in the chip so the user can see what was assumed.
4. Run the resulting filters through the same permission and scoping layer the manual filters use. The natural language path must not be a second, weaker route to the same data.
5. This feature produces filters for an existing list. Building a report configuration with metrics, groupings, and aggregations belongs to Natural Language Report Builder, and free-form querying belongs to Natural Language Database Query. Share the field and glossary definitions across all three rather than maintaining three vocabularies.

## UI and UX Requirements

Match the application's existing design system exactly. Reuse its components,
spacing, and typography. This feature should look like it was always there.

## Responsive Requirements

Works on mobile, tablet, and desktop. Touch targets are large enough to hit on a
phone, and nothing overflows horizontally at 320px.

## Accessibility Requirements

- Fully keyboard navigable.
- Correct semantic elements and ARIA roles.
- Visible focus states.
- Meets WCAG AA contrast.
- Dynamic changes are announced to screen readers.
- Respects prefers-reduced-motion.

## Edge Cases

- A request naming a field or value the app does not support must fail visibly. Map only to declared fields and operators, and tell the user which part of their request could not be interpreted rather than quietly dropping it.
- Filters must always be shown before they are applied, so the user can see that high-value was read as a specific amount threshold and correct it. Applying silently teaches users to trust an interpretation they never saw.
- Relative dates resolved in the server's time zone will be off by a day for much of the world. Resolve in the user's zone and display the absolute range that was chosen.
- When a term maps plausibly to more than one field, ask rather than guess. Present the candidate interpretations and let the user pick.
- Generated filters must pass through row-level permissions exactly as manual ones do. A filter set that widens scope beyond what the user may see is a security defect, not a relevance problem.
- The user must be able to edit or remove any generated filter afterwards, and the chips must behave identically to manually added ones from that point on.
- If the model is unavailable, times out, or returns output that does not validate against the field definitions, the manual filter controls must remain fully usable and the input should say the interpretation failed.
- Free text typed by a user can contain instructions aimed at the model. Treat the input strictly as a filter request and validate the structured result rather than trusting it.

## Testing

Exercise the feature end to end in the running application. Cover every edge case
above, then run the existing test suite and confirm nothing regressed.

## Acceptance Criteria

- [ ] Generated filters reference only declared fields, operators, and value types, and anything unmappable is reported to the user.
- [ ] Filters are always displayed for review and require an explicit apply.
- [ ] Relative dates resolve in the user's time zone and the resolved absolute range is visible.
- [ ] An ambiguous term produces a clarification prompt rather than a silent choice.
- [ ] Generated filters pass through the same row-level permission checks as manual filters.
- [ ] Every generated filter can be edited or removed and behaves as a normal filter thereafter.
- [ ] Model failure or invalid output leaves the manual filter controls working and states that interpretation failed.
- [ ] The feature matches the existing design system.
- [ ] No existing functionality is broken.

## Adaptation Rules

- Match the existing design system. Do not introduce a new colour palette,
  spacing scale, or component library.
- Reuse existing components and utilities wherever they fit.
- Follow the naming, file layout, and code style already present.
- Do not upgrade, replace, or remove existing dependencies to make this
  feature fit. Adapt the feature to the app, not the app to the feature.
- Do not break existing functionality. If a change is genuinely required in
  existing code, make the smallest one that works and say so.
- If something in these instructions conflicts with how the application is
  built, follow the application and explain the deviation.

## Final Verification

Before you report the work as done:

1. Re-read the acceptance criteria above and check each one against what you
   actually built.
2. Run the application and exercise the feature end to end.
3. Run the existing test suite and confirm you have broken nothing.
4. Check the feature on mobile, tablet, and desktop widths.
5. Check keyboard navigation and focus handling.
6. Summarize what changed: files added, files modified, and anything you
   deliberately did differently because of how this application is built.

If any acceptance criterion is unmet, fix it before reporting completion.