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.

## Dashboard, profile & podcasts

```controls
label: Customize Dashboard
where: Library bar on the dashboard (button); opens the Customize Dashboard panel
does: Opens per-library shelf arrangement — drag order, show/hide switches, items per section.

label: Save Changes
where: Customize Dashboard panel → submit
does: Saves that library's shelf arrangement.

label: Refresh
where: Library bar on the dashboard (button)
does: Re-reads libraries without a full page reload.
note: icon button with a tooltip title

label: Create Custom Section
where: the custom-section builder page (/custom-section) → page title
does: Page where a dashboard shelf is defined by filter rules or hand-picked books.

label: Update Password
where: profile page → Change Password → submit
does: Saves the new password after live requirement checks.

label: Remove My Account
where: profile page → Danger Zone
does: Deletes the account and all personal data after confirmation; blocked for the last admin.

label: Add Feed
where: Podcasts page
does: Opens the Add Podcast Feed panel.

label: Add & Subscribe
where: Add Podcast Feed panel → submit
does: Subscribes the feed and starts watching it for new episodes.
also: Add &amp; Subscribe
note: templ source stores the ampersand entity; the rendered label reads "Add & Subscribe"

label: Download all episodes now
where: Add Podcast Feed panel
does: Grabs the feed's back catalog immediately on subscribe.

label: Player settings
where: audio player → settings control
does: Opens the per-player preferences — Autoplay on open, Default playback speed, Resume rewind.
also: title="Settings"

label: Shortcuts & interactions
where: audio player → the ? control
does: Lists every keyboard shortcut the player supports.
also: Shortcuts &amp; interactions
note: templ source stores the ampersand entity

label: Chapters
where: audio player → chapter-list control
does: Opens the chapter list and shows the current chapter position.
note: title attribute on the control

label: Bookmarks
where: audio player → bookmarks control
does: Opens your markers for this title; tap one to jump back.
note: title attribute on the control
```

## 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: Add Podcast Feed panel; podcast 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"
```