John O'Keefe
89fc479bdb
First page of the admin tree, written to the new admin tier (what the
click actually does). Documents every scan surface with its verified
semantics: Force Rescan All Libraries (dashboard, force, all libraries,
one job each with skip-on-active), the per-library Scan button (ALSO a
force scan — hx-vals force:true since the button's birth commit 706be09d,
which corrects the owner's stated 'other scan buttons are shallow'
belief; flagged to the owner), Scan this folder (shallow, single-folder
scope, archive pass skipped for partial scans, podcast roots refused),
Auto-Scan + Scan Interval (the watcher + poll + startup triggers, all
shallow, default 60s range 1-3600), Processing Issues retry (per-item
sequential, deliberately not a library scan), and book-level Rescan /
Reset to Scanned. Plus the standing rules: one scan per library
(coalescing), background jobs with the dashboard progress panel, and
the two-consecutive-scans archive rule.
Glossary gains Scan and Scan this folder (same-commit rule for controls
cited in prose). The real-tree nav test's Administration assertion now
pins shape (Admin Guide, Libraries prefix + usabilityOrder subsequence)
instead of an exact slice, so pages landing one at a time don't churn it.
245 lines
8.8 KiB
Markdown
245 lines
8.8 KiB
Markdown
<!-- 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 & 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 & 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: Force Rescan All Libraries
|
|
where: /admin dashboard → Quick Actions
|
|
does: Force-rescans every library — re-reads each file, re-extracts metadata with original-scan semantics, and recomputes hash identifiers. Unlike the shallow per-library and per-folder scans, nothing unchanged is skipped; this is the admin's backfill tool.
|
|
also: Scan All Libraries
|
|
note: renamed 2026-11-02 — the old label under-promised a heavy operation
|
|
|
|
label: Scan
|
|
where: Admin → Libraries → a library's card row
|
|
does: Force-rescans that one library (same semantics as Force Rescan All Libraries, scoped to a single library).
|
|
|
|
label: Scan this folder
|
|
where: Admin → Libraries → a library's panel → a folder row
|
|
does: Shallow-scans only that folder's subtree — unchanged files are skipped, and items in the library's other folders are never marked missing by a partial scan.
|
|
|
|
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"
|
|
```
|