# Newsletter Link Catalog UI Spec

## Goal

Create a clean, functional web UI for browsing the SQLite-backed newsletter catalog. The UI should feel like a focused database browser: fast to scan, easy to filter, and useful before visual polish.

## Layout

Use a two-pane catalog layout.

### Left Pane: Newsletter Navigation

- Narrow column on desktop.
- Contains a newsletter search field at the top.
- Shows a scrollable list of newsletters below the search.
- Each newsletter item should show:
  - Newsletter name.
  - Optional short description or source email when available.
  - Compact counts such as issues, links, and sponsored links.
- The currently selected newsletter should have a clear selected state.

### Right Pane: Newsletter Detail

- Shows details for the selected newsletter.
- Defaults to the most recent issue only to reduce cognitive load.
- Header should show:
  - Newsletter name.
  - Optional description/source email.
  - Latest issue date.
  - Counts for the displayed issue.
- Links should be displayed in a scannable table or grouped list.
- Link rows should include:
  - Title.
  - Category.
  - Description.
  - URL.
  - Also In, when available.
- Links should be clickable and open in a new tab using `target="_blank"` and `rel="noopener noreferrer"`.

## Issue Scope Controls

The right pane defaults to **Latest Issue**.

Provide a clear control to switch to **All Issues** for the selected newsletter. In All Issues mode:

- Show links from every issue for the selected newsletter.
- Include issue date on each row.
- Keep the same search/filter controls.
- Make it easy to return to Latest Issue mode.

## Global Navigation

Provide lightweight navigation for:

- Dashboard.
- Newsletters.
- All Links.
- Sponsored Links.
- Dead Links.
- Runs.

The Newsletter view should be the primary working screen.

## Search and Filters

- Newsletter search filters the left pane immediately.
- Link search filters the right pane within the selected newsletter and current issue scope.
- Category filtering should be available in the right pane.
- Date filtering is only needed in All Issues mode.
- Empty states should explain what is missing:
  - No newsletters imported yet.
  - No links for the selected newsletter.
  - No matches for the current search/filter.

## Theme and Responsiveness

- Dark mode should be the default visual direction.
- Respect system preference where practical.
- Provide a light mode option.
- Mobile layout should collapse the left pane into a drawer, dropdown, or stacked selector.
- The UI should remain usable on small screens without horizontal scrolling for core actions.

## Visual Style

- Clean, restrained, and operational.
- Avoid marketing-style hero sections.
- Prioritize readable tables/lists, clear selected states, and compact metadata.
- UI polish can remain minimal for the first implementation, but spacing, contrast, and text wrapping should be professional.