feat(dashboard): add preview-only snapshot picker

This commit is contained in:
ZTatman 2026-11-20 10:53:06 -05:00
parent c39385546e
commit d04219a36c
6 changed files with 696 additions and 5 deletions

View file

@ -199,3 +199,51 @@ This file is the single source of truth for codebase obstacles, oddities, and th
**Obstacle:** Calculating the next page from the requested limit stops pagination early when Forgejo's configured page-size cap is lower.
**Solution/Workaround:** Preserve the `next` relation from Forgejo's `Link` header as `RepoPage.has_next_page` and use it directly on the dashboard.
**Preference:** Use upstream pagination links rather than assuming the requested page size was honored.
### Picker listing endpoints omit pagination metadata
**Area:** web/app/routers/repositories.py, web/app/templates/snapshot_picker.html
**Obstacle:** Branch and commit client helpers return plain lists; a short page cannot prove there are no further results because Forgejo may cap page sizes.
**Solution/Workaround:** The picker-specific HTML route follows repository pagination metadata and walks branch pages until empty. Commit requests stop at an empty page or 30 recent commits. JSON listing responses are unchanged.
**Preference:** Paginate automatically without guessing from page length or changing existing API consumers.
### Branch refs need URL query encoding
**Area:** web/app/clients/forgejo.py
**Obstacle:** Interpolating a branch ref into the Forgejo commits query can corrupt names containing characters such as `&` or `#`.
**Solution/Workaround:** Build query strings with `httpx.QueryParams` and quote owner and repository path components.
**Preference:** Encode URL components at the HTTP client boundary.
### Duplicate element IDs silently broke the snapshot picker
**Area:** web/app/templates/dashboard.html, web/app/static/js/snapshot-picker.js
**Obstacle:** The selected-snapshot summary cells reused `snapshot-branch` and `snapshot-commit`, colliding with the picker's `<select>` IDs. `getElementById` returned the hidden summary cell, so `closest(".picker-step")` was `null` and the click handler threw before `showModal()` — the dialog never opened and no visible error appeared.
**Solution/Workaround:** Prefix summary IDs with `snapshot-selected-` and check the rendered template for duplicate IDs.
**Preference:** Keep picker control IDs and display IDs distinct; treat a dialog that fails to open as a JavaScript error first and check the console.
### Appending picker options can change the selected value
**Area:** web/app/templates/snapshot_picker.html
**Obstacle:** A temporary `<select>` wrapper auto-selects its first option before HTMX moves it into the live select, overriding the user's choice.
**Solution/Workaround:** The old paginated UI appended through an inert `<template>` with a neutral wrapper. The current picker renders complete option sets and no longer appends options.
**Preference:** Avoid swapping from a temporary `<select>` when appending to a live one.
### Cached snapshot script broke the new dialog markup
**Area:** web/app/templates/dashboard.html, web/app/static/js/snapshot-picker.js
**Obstacle:** During the HTMX migration, the browser could reuse the old picker script against the new HTML and fail before opening the dialog.
**Solution/Workaround:** The script URL was versioned during the migration. The current picker uses native dialog commands and no longer includes a custom script.
**Preference:** Keep the HTML and its script in sync without requiring users to hard-refresh.
### Forgejo commit listing has no message search
**Area:** web/app/routers/repositories.py, web/app/templates/snapshot_picker.html
**Obstacle:** Filtering just the first page misses commits; scanning an entire branch on each search can slow large repositories.
**Solution/Workaround:** The picker previously filtered up to 100 commits by message or SHA prefix. At the user's request, it now only lists up to 30 recent commits in the dropdown.
**Preference:** Keep the picker dropdown-only; don't scan the entire commit history.
### Snapshot picker changes shifted the modal frame
**Area:** web/app/static/css/input.css, web/app/templates/dashboard.html
**Obstacle:** The dialog only had a maximum height, HTMX loading removed fields from layout, and locking root overflow could remove the page scrollbar.
**Solution/Workaround:** Use a viewport-capped fixed dialog size, a scrolling body with a stable scrollbar gutter, and a grid overlay for loading. Contain scroll chaining on the dialog and its backdrop rather than changing root overflow.
**Preference:** Keep the shell and field space stable without JavaScript.
### djLint reports empty native selectedcontent as an error
**Area:** web/app/templates/snapshot_picker.html
**Obstacle:** djLint H020 flags the empty element even though the browser fills it from the selected option.
**Solution/Workaround:** Suppress H020 in the picker fragment and leave its native select markup intact.
**Preference:** Keep customizable-select styling behind feature queries, with the native picker as the fallback.

View file

@ -1,6 +1,8 @@
from typing import Annotated
from itertools import count
from typing import Annotated, Literal
from fastapi import APIRouter, Depends, HTTPException, Path, Query, status
from fastapi import APIRouter, Depends, HTTPException, Path, Query, Request, status
from fastapi.responses import HTMLResponse, Response
from sqlalchemy import select
from sqlalchemy.ext.asyncio import AsyncSession
@ -12,6 +14,7 @@ from app.models.app_settings import AppSettings
from app.models.session import Session as UserBrowserSession
from app.models.user import LinkedIdentity
from app.settings import get_app_settings, get_fernet
from app.templating import templates
router = APIRouter(prefix="/links", tags=["repositories"])
@ -122,3 +125,139 @@ async def get_repository_commits(
app_settings, access_token, owner, repo, ref=ref, limit=limit, page=page
)
return commits
RECENT_COMMITS = 30
PICKER_PAGE_SIZE = 50
@router.get(
"/snapshot-picker/preview", response_class=HTMLResponse, include_in_schema=False
)
async def preview_snapshot(
request: Request,
_session: Annotated[UserBrowserSession, Depends(get_current_session)],
repo: Annotated[str, Query(max_length=255)] = "",
ref: Annotated[str, Query(max_length=1024)] = "",
commit: Annotated[str, Query(pattern=r"^(?:[a-f0-9]{40}|[a-f0-9]{64})?$")] = "",
) -> Response:
"""Render a display-only preview, or clear it when no snapshot is supplied."""
confirmed = bool(repo and ref and commit)
return templates.TemplateResponse(
request,
"snapshot_preview.html",
{"repo": repo, "ref": ref, "commit": commit, "confirmed": confirmed},
headers={"Cache-Control": "no-store"},
block_name="preview_confirmation" if confirmed else "selected_snapshot",
)
@router.get(
"/snapshot-picker/{step}", response_class=HTMLResponse, include_in_schema=False
)
async def get_snapshot_picker_step(
request: Request,
step: Literal["repository", "branch", "commit"],
app_settings: Annotated[AppSettings, Depends(get_app_settings)],
session: Annotated[UserBrowserSession, Depends(get_current_session)],
db: Annotated[AsyncSession, Depends(get_db)],
repo: Annotated[str, Query(max_length=255)] = "",
ref: Annotated[str, Query(max_length=1024)] = "",
) -> Response:
"""Load dependent picker options without changing the JSON listing API."""
if step != "repository" and (repo in {".", ".."} or "/" in repo or "\\" in repo):
raise HTTPException(status_code=400, detail="Invalid repository name.")
options: list[tuple[str, str]] = []
error = False
message = ""
try:
if step == "repository" or (repo and (step == "branch" or ref)):
access_token = await get_forgejo_token(session)
owner = await get_forgejo_owner(session, db)
options = await _snapshot_options(
step, app_settings, access_token, owner, repo, ref
)
if not options:
message = {
"repository": "No repositories found.",
"branch": "No branches found.",
"commit": "No commits found.",
}[step]
except HTTPException as exc:
if exc.status_code not in {403, 502, 503}:
raise
error = True
message = str(exc.detail)
return templates.TemplateResponse(
request,
"snapshot_picker.html",
{
"step": step,
"options": options,
"message": message,
"error": error,
"repo": repo,
"ref": ref,
},
headers={"Cache-Control": "no-store"},
block_name={
"repository": "picker_steps",
"branch": "branch_steps",
"commit": "commit_step",
}[step],
)
async def _snapshot_options(
step: Literal["repository", "branch", "commit"],
app_settings: AppSettings,
access_token: str,
owner: str,
repo: str,
ref: str,
) -> list[tuple[str, str]]:
options: list[tuple[str, str]] = []
for page in count(1):
if step == "repository":
result = await forgejo.get_repos(
app_settings,
access_token,
owner=owner,
page=page,
limit=PICKER_PAGE_SIZE,
)
options.extend((item.repo_name, item.repo_name) for item in result.repos)
if not result.has_next_page or not result.repos:
break
elif step == "branch":
branches = await forgejo.get_branches(
app_settings,
access_token,
owner,
repo,
page=page,
limit=PICKER_PAGE_SIZE,
)
if not branches:
break
options.extend((item.name, item.name) for item in branches)
else:
commits = await forgejo.get_commits(
app_settings,
access_token,
owner,
repo,
ref=ref,
page=page,
limit=RECENT_COMMITS,
)
if not commits:
break
for item in commits[: RECENT_COMMITS - len(options)]:
subject = item.message.partition("\n")[0]
options.append((item.id, f"{item.id[:7]} — {subject}"))
if len(options) == RECENT_COMMITS:
break
return options

View file

@ -275,6 +275,289 @@
.input-error {
@apply text-sm font-medium text-danger-foreground;
}
.snapshot-grid {
display: grid;
gap: 1px;
background: var(--color-border);
}
.snapshot-cell {
padding: 0.75rem 1.25rem;
background: var(--color-card);
}
.snapshot-value {
margin-top: 0.25rem;
font-family: var(--font-mono);
font-size: 0.75rem;
line-height: 1.5;
color: var(--color-foreground);
overflow-wrap: anywhere;
}
@media (min-width: 640px) {
.snapshot-grid {
grid-template-columns: repeat(3, minmax(0, 1fr));
}
}
.picker-dialog {
inline-size: min(34rem, calc(100dvw - 2rem));
block-size: min(37rem, calc(100dvh - 2rem));
max-inline-size: none;
max-block-size: none;
margin: auto;
padding: 0;
overflow: hidden;
overscroll-behavior: contain;
border: 1px solid var(--color-border);
border-radius: var(--radius-xl);
background: var(--color-card);
color: var(--color-card-foreground);
box-shadow: 0 24px 64px rgb(0 0 0 / 55%);
}
.picker-dialog::backdrop {
background: rgb(0 0 0 / 72%);
overflow: hidden;
overscroll-behavior: contain;
}
.picker-layout {
display: grid;
grid-template-rows: auto minmax(0, 1fr);
block-size: 100%;
}
.picker-header {
display: flex;
align-items: flex-start;
justify-content: space-between;
gap: 1rem;
padding: 1.25rem 1.5rem 1rem;
border-bottom: 1px solid var(--color-border);
background: var(--color-card);
}
.picker-title {
font-size: 1rem;
font-weight: 600;
}
.picker-description {
max-width: 42ch;
margin-top: 0.25rem;
font-size: 0.8125rem;
line-height: 1.45;
color: var(--color-muted-foreground);
}
.picker-close {
display: grid;
flex-shrink: 0;
place-items: center;
width: 2rem;
height: 2rem;
border: 1px solid transparent;
border-radius: var(--radius-md);
color: var(--color-muted-foreground);
transition: background-color 120ms ease, color 120ms ease;
}
.picker-close:hover {
background: var(--color-muted);
color: var(--color-foreground);
}
.picker-loaded {
display: flex;
flex-direction: column;
gap: 1rem;
}
.picker-steps {
padding: 1.25rem 1.5rem 1.5rem;
overflow: auto;
overscroll-behavior: contain;
scrollbar-gutter: stable;
}
.picker-step {
display: grid;
grid-template-columns: 1.5rem minmax(0, 1fr);
gap: 0.875rem;
}
.picker-step-index {
display: grid;
place-items: center;
width: 1.5rem;
height: 1.5rem;
margin-top: 0.125rem;
border: 1px solid var(--color-border);
border-radius: 9999px;
background: var(--color-muted);
font-family: var(--font-mono);
font-size: 0.6875rem;
color: var(--color-muted-foreground);
transition: border-color 120ms ease, background-color 120ms ease,
color 120ms ease;
}
.picker-step:has(select:required:valid:not(:disabled)) > .picker-step-index {
border-color: var(--color-success);
background: var(--color-success-muted);
color: var(--color-success-foreground);
}
.picker-step-label {
display: block;
font-size: 0.75rem;
font-weight: 600;
color: var(--color-muted-foreground);
}
.picker-select {
inline-size: 100%;
min-inline-size: 0;
min-height: 2.75rem;
margin-top: 0.5rem;
padding: 0.625rem 0.875rem;
border: 1px solid var(--color-border);
border-radius: var(--radius-lg);
background: var(--color-input);
color-scheme: dark;
font-family: var(--font-sans);
font-size: 0.875rem;
line-height: 1.5;
color: var(--color-foreground);
text-overflow: ellipsis;
transition: border-color 120ms ease, background-color 120ms ease;
}
.picker-select:hover:not(:disabled) {
border-color: var(--color-muted-foreground);
background: var(--color-muted);
}
.picker-select option {
background: var(--color-card);
color: var(--color-card-foreground);
}
.picker-select:focus-visible {
border-color: var(--color-ring);
outline: none;
box-shadow: 0 0 0 3px var(--color-ring-muted);
}
.picker-select:disabled {
cursor: not-allowed;
opacity: 0.45;
}
@supports (appearance: base-select) and selector(select::picker(select)) {
select.picker-select,
select.picker-select::picker(select) {
appearance: base-select;
}
select.picker-select > button {
flex: 1;
min-inline-size: 0;
text-align: start;
}
select.picker-select selectedcontent {
display: block;
overflow: hidden;
text-overflow: ellipsis;
white-space: nowrap;
}
select.picker-select::picker-icon {
flex: none;
margin-inline-start: auto;
padding-inline-start: 0.625rem;
color: var(--color-muted-foreground);
line-height: 1;
}
select.picker-select::picker(select) {
max-block-size: min(16rem, calc(50dvh - 2rem));
overflow: auto;
overscroll-behavior: contain;
border: 1px solid var(--color-border);
border-radius: var(--radius-lg);
background: var(--color-card);
color: var(--color-card-foreground);
box-shadow: 0 8px 24px rgb(0 0 0 / 35%);
}
select.picker-select option {
padding: 0.5rem 0.875rem;
overflow-wrap: anywhere;
white-space: normal;
}
select.picker-select option:is(:hover, :focus-visible, :checked) {
background: var(--color-muted);
}
@supports (position-area: block-end) and (inline-size: anchor-size(inline)) {
select.picker-select::picker(select) {
inset: auto;
margin: 0.25rem 0;
position-area: block-end;
position-try-fallbacks: flip-block;
inline-size: anchor-size(inline);
min-inline-size: 0;
}
}
}
.picker-status {
margin-top: 0.375rem;
font-size: 0.75rem;
line-height: 1.25rem;
color: var(--color-muted-foreground);
}
.picker-status[data-state="error"] {
color: var(--color-danger-foreground);
}
.picker-load-scope {
display: grid;
grid-template-columns: minmax(0, 1fr);
align-content: start;
}
.picker-load-scope > :is(.picker-loading, .picker-loaded) {
grid-area: 1 / 1;
}
.picker-loading,
.picker-load-scope.htmx-request > .picker-loaded {
visibility: hidden;
}
.picker-load-scope.htmx-request > .picker-loading {
visibility: visible;
}
.picker-close:focus-visible {
outline: 2px solid var(--color-ring);
outline-offset: 2px;
}
.picker-actions {
display: flex;
justify-content: flex-end;
gap: 0.5rem;
margin-top: 1rem;
}
}
@ -289,4 +572,4 @@
height: auto; /* Maintains aspect ratio */
display: block; /* Removes bottom whitespace common in inline images */
}
}
}

View file

@ -8,12 +8,60 @@
<p class=" text-2xl text-muted-foreground">{{ user.display_name or user.email }}.</p>
</div>
{% if pat_registered %}
<a href="/links/create" class="btn btn-primary w-fit">Create share link</a>
<button type="button"
id="open-snapshot-picker"
class="btn btn-primary w-fit"
commandfor="snapshot-picker"
command="show-modal"
hx-get="/links/snapshot-picker/repository"
hx-target="#snapshot-picker-body"
hx-swap="innerHTML"
hx-indicator="#snapshot-picker-scope"
hx-sync="#snapshot-picker:replace">Select snapshot</button>
{% else %}
<span class="btn btn-primary w-fit opacity-50 pointer-events-none"
aria-disabled="true">Create share link</span>
aria-disabled="true">Select snapshot</span>
{% endif %}
</section>
{% if pat_registered %}
{% include "snapshot_preview.html" %}
<dialog id="snapshot-picker"
class="picker-dialog"
aria-labelledby="snapshot-title"
aria-describedby="snapshot-description">
<div class="picker-layout">
<header class="picker-header">
<div>
<h2 id="snapshot-title" class="picker-title">Select a snapshot</h2>
<p id="snapshot-description" class="picker-description">
Choose a repository, then a branch and commit. Nothing is published until you create a link.
</p>
</div>
<button type="button"
class="picker-close"
aria-label="Close dialog"
commandfor="snapshot-picker"
command="close">
<svg width="16"
height="16"
viewBox="0 0 16 16"
fill="none"
stroke="currentColor"
stroke-width="1.5"
aria-hidden="true">
<path d="M4 4l8 8M12 4l-8 8" stroke-linecap="round" />
</svg>
</button>
</header>
<div id="snapshot-picker-scope" class="picker-steps picker-load-scope">
<p class="picker-status picker-loading" role="status">Loading selection…</p>
<div id="snapshot-picker-body" class="picker-loaded">
<p class="picker-status" role="status">Could not load repositories. Close the picker and try again.</p>
</div>
</div>
</div>
</dialog>
{% endif %}
<section class="grid gap-4 md:grid-cols-3">
<div class="p-4 card">
<p class="section-header-subtle">Active links</p>

View file

@ -0,0 +1,125 @@
{# The browser fills selectedcontent when a native select option is chosen. #}
<!-- djlint:off H020 -->
{% block picker_steps %}
<div class="picker-step">
<span class="picker-step-index" aria-hidden="true">1</span>
<div>
<label for="snapshot-repository" class="picker-step-label">Repository</label>
<select id="snapshot-repository"
class="picker-select"
name="repo"
required
{% if not options %}disabled{% endif %}
hx-get="/links/snapshot-picker/branch"
hx-trigger="change"
hx-target="#snapshot-branch-content"
hx-swap="innerHTML"
hx-indicator="#snapshot-branch-scope"
hx-sync="#snapshot-picker:replace">
<button type="button"><selectedcontent></selectedcontent></button>
<option value="">Choose a repository</option>
{% for value, label in options %}<option value="{{ value }}">{{ label }}</option>{% endfor %}
</select>
<p class="picker-status" role="status" {% if error %}data-state="error"{% endif %}>{{ message }}</p>
</div>
</div>
<div id="snapshot-branch-scope" class="picker-load-scope">
<p class="picker-status picker-loading" role="status">Loading branches…</p>
<div id="snapshot-branch-content" class="picker-loaded">
{% block branch_steps %}
<div class="picker-step">
<span class="picker-step-index" aria-hidden="true">2</span>
<div>
<label for="snapshot-branch" class="picker-step-label">Branch</label>
<select id="snapshot-branch"
class="picker-select"
name="ref"
required
{% if step != "branch" or not options %}disabled{% endif %}
hx-get="/links/snapshot-picker/commit"
hx-trigger="change"
hx-include="#snapshot-repository"
hx-target="#snapshot-commit-content"
hx-swap="innerHTML"
hx-indicator="#snapshot-commit-scope"
hx-sync="#snapshot-picker:replace">
<button type="button"><selectedcontent></selectedcontent></button>
<option value="">Choose a branch</option>
{% if step == "branch" %}
{% for value, label in options %}<option value="{{ value }}">{{ label }}</option>{% endfor %}
{% endif %}
</select>
<p class="picker-status"
role="status"
{% if step == "branch" and error %}data-state="error"{% endif %}>
{% if step == "branch" and repo %}
{{ message }}
{% if error %}
<button type="button"
class="btn btn-xs btn-secondary"
hx-get="/links/snapshot-picker/branch"
hx-include="#snapshot-repository"
hx-target="#snapshot-branch-content"
hx-swap="innerHTML"
hx-indicator="#snapshot-branch-scope"
hx-sync="#snapshot-picker:replace">Retry</button>
{% endif %}
{% else %}
Choose a repository first.
{% endif %}
</p>
</div>
</div>
<div id="snapshot-commit-scope" class="picker-load-scope">
<p class="picker-status picker-loading" role="status">Loading commits…</p>
<div id="snapshot-commit-content" class="picker-loaded">
{% block commit_step %}
<div class="picker-step">
<span class="picker-step-index" aria-hidden="true">3</span>
<div>
<label for="snapshot-commit" class="picker-step-label">Commit</label>
{% if step == "commit" and repo and ref %}
<form hx-get="/links/snapshot-picker/preview"
hx-target="#snapshot-picker-body"
hx-swap="innerHTML"
hx-indicator="#snapshot-picker-scope"
hx-sync="#snapshot-picker:replace">
<input type="hidden" name="repo" value="{{ repo }}" />
<input type="hidden" name="ref" value="{{ ref }}" />
<select id="snapshot-commit"
class="picker-select"
name="commit"
required
{% if not options %}disabled{% endif %}>
<button type="button"><selectedcontent></selectedcontent></button>
<option value="">Choose a commit</option>
{% for value, label in options %}<option value="{{ value }}">{{ label }}</option>{% endfor %}
</select>
<p class="picker-status" role="status" {% if error %}data-state="error"{% endif %}>{{ message }}</p>
<div class="picker-actions">
<button type="button"
class="btn btn-sm btn-secondary"
commandfor="snapshot-picker"
command="close">Cancel</button>
<button type="submit"
class="btn btn-sm btn-primary"
{% if not options %}disabled{% endif %}>Select snapshot</button>
</div>
</form>
{% else %}
<select id="snapshot-commit" class="picker-select" disabled>
<button type="button"><selectedcontent></selectedcontent></button>
<option value="">Choose a commit</option>
</select>
<p class="picker-status" role="status">Choose a branch first.</p>
{% endif %}
</div>
</div>
{% endblock %}
</div>
</div>
{% endblock %}
</div>
</div>
{% endblock %}
<!-- djlint:on -->

View file

@ -0,0 +1,48 @@
{% if not confirmed %}
{% block selected_snapshot %}
<section id="selected-snapshot"
class="card overflow-hidden"
{% if confirmed %}hx-swap-oob="outerHTML"{% else %}hidden{% endif %}
aria-live="polite">
{% if confirmed %}
<div class="flex flex-wrap items-center justify-between gap-3 border-b border-border px-5 py-3">
<div class="flex flex-wrap items-center gap-2.5">
<span class="badge-success">Selected</span>
<span class="text-xs text-muted-foreground">Preview only — no share link has been created.</span>
</div>
<button type="button"
class="btn btn-xs btn-secondary"
hx-get="/links/snapshot-picker/preview"
hx-target="#selected-snapshot"
hx-swap="outerHTML">Clear</button>
</div>
<dl class="snapshot-grid">
<div class="snapshot-cell">
<dt class="section-header-subtle">Repository</dt>
<dd class="snapshot-value">{{ repo }}</dd>
</div>
<div class="snapshot-cell">
<dt class="section-header-subtle">Branch</dt>
<dd class="snapshot-value">{{ ref }}</dd>
</div>
<div class="snapshot-cell">
<dt class="section-header-subtle">Commit</dt>
<dd class="snapshot-value">{{ commit[:12] }}</dd>
</div>
</dl>
{% endif %}
</section>
{% endblock %}
{% else %}
{% block preview_confirmation %}
<p role="status">Snapshot selected. No share link has been created.</p>
<div class="picker-actions">
<button type="button"
class="btn btn-sm btn-primary"
commandfor="snapshot-picker"
command="close"
autofocus>Done</button>
</div>
{{ self.selected_snapshot() }}
{% endblock %}
{% endif %}