bookhoard/docs/developer/ui-controls.md

<!-- Gate-checked by TestUIControlLabels (internal/docs/ui_labels_test.go):
     every `controls` entry must exist as a literal in templates/*.templ
     (or web/src for source: ts). Renames fail make test. Entry text is the
     canonical spelling cited across the docs. -->

# UI controls glossary

The canonical spellings for controls cited across the UI documentation. Docs
quote the label exactly as this page lists it — one entry per control; two
spellings of one control is a defect. The `controls` block is machine-read:
when a doc first names a control, add its entry in the same commit; when a
rename lands, update the entry in the same commit and the gate goes green
again.

Entry fields:

- `label` — the exact rendered text users see
- `where` — semantic path (page → section/card), never spatial; see the
  [writing standard](writing-ui-docs.md)
- `does` — what interacting with it produces (the outcome)
- `source` — optional; default `templ` (`templates/*.templ`); `ts` searches `web/src`
- `also` — optional, pipe-separated extra literal fragments to search when
  the visible label is Alpine-composed rather than static (OR-checked with `label`)
- `note` — optional clarifier

Form-field labels inside a single modal (Name, Description…) are cited
inline in docs and not tracked here; this list carries the controls people
navigate by.

## Collections

```controls
label: New Collection
where: Collections page
does: Opens the create-collection modal.
note: the empty page offers the same action as "Create Your First Collection"

label: Create Your First Collection
where: Collections page, when no collections exist
does: Opens the create-collection modal.

label: Create Collection
where: create-collection modal → submit
does: Saves the new collection and returns to the Collections page.

label: Update Collection
where: edit-collection modal → submit
does: Saves your changes to the collection.

label: Static
where: create-collection modal → Type
does: Chooses a hand-picked collection — you add and remove items yourself.

label: ⚡ Smart
where: create-collection modal → Type; also shown as a badge on smart collections page and detail
does: Chooses a rules-matched collection — its membership stays current by itself.

label: Rules scope
where: create-collection modal, when Smart is chosen
does: Asks what the rules ask about — the two buttons below it.
also: 📚 Books|🎧 Podcast episodes
note: "Books" and "Podcast episodes" as the two scope buttons

label: Restore System
where: Collections page
does: Opens a pick-a-shelf modal to bring back a system collection you deleted.

label: Restore
where: Restore System Collection modal → submit
does: Brings the selected system collection back.

label: Edit Rules
where: collection detail page
does: Opens the smart-collection rules editor for this collection.

label: Filter tree
where: smart-collection rules editor
does: The area where the group and rules are built.
note: read/write rules — the how is the filter guide

label: Apply to Collection
where: smart-collection rules editor → save
does: Saves the filter tree and makes the collection match those rules from now on.

label: Add Items
where: collection detail page
does: Opens the item picker window.

label: Add Selected
where: item picker → footer
does: Adds everything checked in the picker to the collection.

label: Remove Selected
where: collection detail page
does: Opens a confirm dialog to remove the checked items from the collection.

label: Search within collection...
where: collection detail page → search box
does: Filters the displayed items — nothing is removed.

label: Play as Sequence
where: collection detail page (when it has a downloaded episode)
does: Plays the collection's episodes one after another in the listening order you pick.

label: Hide finished books (reading-queue mode)
where: edit-collection modal
does: Finished books disappear from the collection's shelf.

label: Show Up Next strip
where: edit-collection modal
does: Adds this collection's Up Next strip to the podcast page.
```

## Everywhere else

```controls
label: Filters
where: All Books / Podcasts page → toolbar
does: Opens the filter drawer for building and applying rules.

label: Register Device
where: Devices page
does: Submits a device registration request for the pending-approval flow.

label: Download All
where: Podcast page → episodes area
does: Queues every episode of the feed for download.

label: Download order
where: Podcast page → feed settings
does: Sets the ordering used when feed episodes are downloaded.

label: Match ALL / Group ANY header
where: filter drawer → group header (also smart collections → Rules and dashboard sections)
does: Sets how the group combines its rules; clicking the header flips ALL/ANY.
also: ? 'Match' : 'Group'|? 'ANY' : 'ALL'
note: label is Alpine-composed — 'Match' for the whole builder, 'Group' for nested; docs write it as MATCH ALL / MATCH ANY

label: Reset to Scanned
where: book detail → edit modal → scan information area
does: Restores scanner-extracted metadata over manual edits.

label: Auto-Scan
where: Settings page → Scanning section
does: Enables automatic periodic library scanning on the interval below it.

label: Scan Interval (seconds)
where: Settings page → Scanning section
does: Sets the seconds between automatic scans.

label: Resume rewind
where: audio player → player settings; profile settings
does: Rewinds playback a configured few seconds when you resume.
also: Resume Rewind
note: profile page spells it capitalized

label: Reading Direction
where: book detail → edit modal
does: Chooses the direction pages advance (publisher convention — e.g. manga).

label: Scan Info
where: book detail page → info block
does: Displays scanner-supplied notes attached to the item.
also: Scan Information
note: the editable form label in the modal reads "Scan Information"
```