# Search and filter

> Kwark lets people find things the way they would say them, keeps filters visible and easy to clear, and folds find, filter and sort into one labelled control on a phone.

Source: https://kwark.space/designSystem/patterns/search-and-filter

## The problem

A director preparing the night shoot wants every exterior scene at night with Mira in it. A writer wants to rename "Dev" to "Devraj" everywhere except where "Dev" is inside another word. A producer with forty stories in her library wants the two short films she is still drafting.

Search in a writing tool usually means typing an exact string. But people do not think "EXT." and "NIGHT" in capitals; they think "Mira, night, outside". And filters that hide themselves leave people believing their stories have disappeared: an empty list with a filter on looks exactly like an empty library.

## Kwark's answer

### Search the way you would say it

The screenplay's search (`ScriptSearch.tsx`) takes a sentence, not a pattern. Its hint says: "Ask it the way you would say it. A character's name, a time of day, inside or out, or the kind of line." The example placeholder is "mira night exteriors". Character names, day or night, interior or exterior and element types (dialogue, action) are understood from the script's own structure; everything else is matched as text.

Two plain switches refine it: **Whole word** ("Only whole words — 'art' not in 'party'") and **Match case** ("Match upper and lower case exactly"). **Replace with** and **Replace** sit underneath. Results are grouped by scene in script order, and text found before the first scene heading is labelled "Before the first scene". No result says: "Nothing in the script matches that."

Find is in Edit (Find and replace, ⌘F). On a phone it is in the Menu sheet near the top.

### Rename is not find and replace

Renaming a character is its own command, **Rename a character…** in Edit, because a character's name appears in cues, action, the cast list, the breakdown and the call sheet. One rename changes them all, consistently, and is undoable as one step. Find and replace is for text.

### Filters stay visible and clear in one step

On Home the library is found, filtered and sorted in one place:

- On desktop: **Find a story…** (search), **Filter by format** (All formats, Feature films, Short films, Series, Franchises), **Filter by status** (Any status, Draft, Pre-production, Shared), **Sort projects** (Last edited, Date created, Name) with its direction.
- On a phone: one labelled control, **Filter and sort**, opens a sheet holding the search field, sort and direction, format, status and **Clear filters** (Decision 0021). When a filter is on, the control's name says so: "Filter and sort, on". A second band with the search field appears only while searching.
- When nothing matches: "No stories found" / "Try a different title, format, or status." with **Clear filters**.

The same rules apply to comment filters (open or resolved, whose comments, newest or oldest first) and to the breakdown's department filters.

### Find within a module

Modules with many items have their own find, labelled with what it finds: the Outline's **Find a beat**, the screenplay's **Go to scene…** (⌘G) for jumping by number or heading. A series-wide find across every episode is on the later list, not built; do not promise it.

## Anatomy

| Part | Means |
|---|---|
| Search field | `type="search"`, labelled with its scope: "Search the screenplay", "Search projects" |
| Hint | How to ask, in one line |
| Refine switches | Whole word, Match case: chips with `aria-pressed` |
| Results | Grouped in the work's own order (scene order, not relevance), each with where it is |
| Count | "12 in this screenplay", in quiet text |
| Active filter indicator | The word "on" in the control's name, or a removable tag per filter |
| Clear filters | One action that removes every filter |
| No result | One sentence and, if filtered, Clear filters |

## Rules

- **Must** label every search field with its scope.
- **Must** keep active filters visible, and give one action that clears them all.
- **Must** distinguish "nothing matches" from "nothing here": a filtered-empty list never shows the welcome empty state.
- **Must** order results in the work's own order (scenes in script order, stories by the chosen sort), never by an unexplained relevance score.
- **Never** hide filters in a scrolling chip row with no cue (rejected in Decision 0021).
- **Never** search more than the person can see. Results respect access: a Reader's search never returns a module they cannot open.
- **Never** replace across the script without showing what will change; Replace works one at a time or shows the count before replacing all.
- **Always** keep the query and filters when the person opens a result and comes back.
- **Always** make search work for Indian scripts: match the text as typed, never transliterate the query silently.

## Edge cases

- **Romanised query, Tamil script.** A writer types "meera" and the character is written in Tamil: match the cast name, which Kwark knows, not the characters on the page.
- **A query that is a scene number.** "12" offers Scene 12 first.
- **Very large scripts.** Search runs on the device, in the loaded script, with no cloud reads.
- **Filter by a status nobody uses.** Offer only statuses that exist in the library, plus Any status.
- **Shared with you.** The Shared tab has its own filters; the count shows only on the selected tab.

## Phone and desktop

On desktop, search and filters sit in the toolbar above the list, each a labelled control; screenplay search opens in the side panel beside the page. On a phone, Home's find, filter and sort is one labelled icon in the single bar, opening a sheet; screenplay search opens from the Menu sheet as a full-height sheet whose results scroll the page to each match.

## Writing

- Field labels: "Search the screenplay", "Search projects", "Find a story…", "Find a beat".
- Hints say how to ask, once.
- No result: "Nothing in the script matches that." / "No stories found".
- Clear: **Clear filters**, **Clear search**.

## Accessibility

- Search fields use `type="search"` with a visible label; the clear button is named "Clear search".
- The result count is announced politely as it changes.
- Refine chips are toggle buttons with `aria-pressed` and their full meaning in the accessible description.
- The filter sheet returns focus to the Filter and sort control; its name includes "on" when filters are active.

**Do:** "Ask it the way you would say it." and the example "mira night exteriors".

**Don't:** A search box that needs "EXT." and "NIGHT" typed exactly, with a regex option as the only power.

**Do:** "No stories found. Try a different title, format, or status." **Clear filters**, with "Filter and sort, on" in the toolbar.

**Don't:** An empty library and no sign that the Short films filter is still on.

## Demo

```html
<div style="display:flex;gap:8px;flex-wrap:wrap;align-items:center;width:100%">
<label class="kw-field" style="flex:1;min-width:200px"><span class="kw-visually-hidden">Search projects</span><input class="kw-input" type="search" placeholder="Find a story…"></label>
<select class="kw-select" aria-label="Filter by format" style="width:auto"><option>All formats</option><option selected>Short films</option><option>Feature films</option><option>Series</option></select>
<select class="kw-select" aria-label="Sort projects" style="width:auto"><option>Last edited</option><option>Date created</option><option>Name</option></select>
</div>
<div style="display:flex;gap:8px;flex-wrap:wrap"><span class="kw-badge kw-removable-tag">Short films <button type="button" class="kw-icon-button" aria-label="Remove Short films filter">×</button></span><button class="kw-text-button" type="button">Clear filters</button></div>
<div class="kw-empty" style="width:100%;max-width:440px"><h3>No stories found</h3><p>Try a different title, format, or status.</p><button class="kw-button" type="button">Clear filters</button></div>
<div class="kw-sheet" style="width:100%;max-width:360px"><div class="kw-sheet__grip" aria-hidden="true"></div><strong>Filter and sort</strong>
<label class="kw-field" style="margin-top:10px"><span class="kw-label">Search projects</span><input class="kw-input" type="search" placeholder="Find a story…"></label>
<div class="kw-segment" role="group" aria-label="Sort projects" style="margin-top:10px"><button type="button" aria-pressed="true">Last edited</button><button type="button" aria-pressed="false">Date created</button><button type="button" aria-pressed="false">Name</button></div>
<div style="margin-top:12px"><button class="kw-button" type="button">Clear filters</button></div></div>
```

## Related

[Search field](https://kwark.space/designSystem/components/search-field.md), [Removable tag](https://kwark.space/designSystem/components/removable-tag.md), [Chip](https://kwark.space/designSystem/components/chip.md), [Sheet](https://kwark.space/designSystem/components/sheet.md), [Empty states](https://kwark.space/designSystem/patterns/empty-states.md), [Phones](https://kwark.space/designSystem/patterns/phones.md).

## AI readiness test

**Task:** Add search and filters to the Breakdown's element list.

**Give the agent:** This page, Decision 0021, Empty states.

**Constraint:** On the device; no cloud reads per keystroke.

**A reliable answer:**
- Labels the field "Search the breakdown" and filters by department with visible removable tags
- Results in scene order with the scene shown
- Clear filters in one step
- filtered-empty is not the welcome empty state
- Phone folds it into one labelled Filter and sort sheet
