From 0ffc3fde3d75cce2b532f589b3d5d97e65e076ef Mon Sep 17 00:00:00 2001 From: mwiegand Date: Mon, 18 May 2026 23:53:51 +0200 Subject: [PATCH] docs(overlays): create-modal + workshop-section redesign spec Specifies the create-overlay modal redesign (field reorder, custom radio-list, switch instead of checkbox, drop legacy path hint) and the workshop-items section restructure (drop input-mode radio in favor of autodetected items-vs-collections via batched GetCollectionDetails). Co-Authored-By: Claude Opus 4.7 (1M context) --- ...ate-modal-and-workshop-section-redesign.md | 191 ++++++++++++++++++ 1 file changed, 191 insertions(+) create mode 100644 docs/superpowers/specs/2026-05-18-create-modal-and-workshop-section-redesign.md diff --git a/docs/superpowers/specs/2026-05-18-create-modal-and-workshop-section-redesign.md b/docs/superpowers/specs/2026-05-18-create-modal-and-workshop-section-redesign.md new file mode 100644 index 0000000..9fe7530 --- /dev/null +++ b/docs/superpowers/specs/2026-05-18-create-modal-and-workshop-section-redesign.md @@ -0,0 +1,191 @@ +# Create Overlay Modal + Workshop Items Section — Redesign + +## Context + +Two UI surfaces still wear the pre-redesign vocabulary even though the global +stylesheet was reworked from first principles in `308fa4e`: + +1. **Create-overlay modal** (`templates/overlays.html`, `components.css:114-166`) + — uses the old `.modal*` class names, a `
` with a native `` + border around the Type radios (looks notched and archaic), native checkbox + markup that wraps the input on its own line above the label, and a field + order that buries the most-important field (Name) under the most-cluttered + one (Type). The "path is generated automatically" hint at the bottom is + stale copy from an earlier version where users picked their own paths; + paths are now derived from the internal id, so the hint describes behavior + the user can no longer influence. + +2. **Workshop items section** on the overlay detail page + (`templates/overlay_detail.html:43-67`) — same fieldset-border issue on the + Items/Collection radios, two right-aligned buttons (`Add`, `Refresh from + Steam`) overlapping with no margin (visual regression), and a forced + choice between "items" and "collection" input modes that exists purely to + tell the backend which Steam API endpoint to call. The dual mode is also a + silent footgun: a user pasting a collection URL into the items field today + produces a broken overlay with no warning. + +The goal is to bring both surfaces in line with the redesigned stylesheet +*and*, while we're in there, simplify the workshop form structurally (drop the +Input-mode radio entirely — see decision rationale below). + +## Decisions + +### Create modal + +- **Field order:** Name → Type → System-wide. Name is the most-typed field + and the simplest input; it goes first. Type is the bigger decision but + benefits from the user having committed to *something* before they confront + three options. +- **No fieldset border.** Type label becomes a regular `.field-label` (small + uppercase or semibold, matches Name's label). +- **Radios become a stacked custom-styled list.** Each row: a circular dot + control (outer ring with a colored inner dot when selected), bold label on + the right, muted second-line description below the label. All descriptions + are visible at once — users can compare options without clicking. + Considered and rejected: segmented control — breaks down past 3-4 options + (the codebase is plausibly heading toward more overlay types: git, zip, + mirror). Considered and rejected: full selectable cards — too much vertical + space for what is ultimately a single radio group. +- **System-wide checkbox becomes a switch.** Switch sits left-aligned in the + row (same left edge as the radio dots), with bold label + muted second-line + description to the right — visually consistent with the radio rows above. + Switch is conceptually distinct from the type radios (binary on/off vs. + one-of-three), so the different control shape reinforces the hierarchy. +- **Drop the "path is generated automatically" paragraph.** Legacy copy. +- **Buttons keep their current placement** (Cancel + Create, right-aligned in + a bordered footer with a slightly muted background) — that part of the + current modal already works. + +### Workshop items section + +- **Drop the Input-mode fieldset entirely.** Single textarea accepts any mix + of item IDs, item URLs, and collection URLs. Backend autodetects. +- **Autodetect strategy** (verified against live Steam API during + brainstorming): + 1. Parse pasted input into a list of IDs (existing helper: + `steam_workshop.parse_workshop_input()`). + 2. **One batched call** to `ISteamRemoteStorage/GetCollectionDetails/v1/` + with all parsed IDs. Steam returns one entry per ID: + - `result: 1` + `children: [...]` → it's a collection, expand to + children IDs. + - `result: 9` (k_EResultFileNotFound) → not a collection, keep ID + as-is. + 3. **One batched call** to + `ISteamRemoteStorage/GetPublishedFileDetails/v1/` with the flat list + of final item IDs (collection-children + non-collection IDs). + 4. Persist. + + Cost: one extra Steam round-trip on submission (~150 ms), regardless of + input size. This is **simpler than today's code**, which has two + separate handler branches in `routes/workshop_routes.py:36-99`. The + unified flow deletes the `if input_mode == "items" / elif input_mode == + "collection"` branching. + +- **"Refresh from Steam" relocates to a controls row below the items + table** (not inside the table). The table ends with its last data row. + Below the table sits a single row containing: + - Left: a summary hint (`{n} items · {total_size} total` or `0 items` + when empty). + - Right: a normal-styled `↻ Refresh from Steam` button (disabled when + the table is empty). +- **Add button placement.** Right-aligned in its own row immediately below + the textarea, with proper top margin (today's "no margin" overlap with + Refresh is the bug being fixed by moving Refresh). +- **Textarea uses monospace font** since pasted content is IDs and URLs. +- **Header copy stays** as `Workshop items` (page has other sections — + `Files`, `Used by` — and section headers aid scanning). +- **Helper text under the label:** "Paste Steam Workshop IDs, item URLs, or + collection URLs — one per line. Collections expand automatically." The + last sentence is load-bearing — it tells the user they don't need to + pre-classify their input. + +## Implementation surface + +### Files to modify + +| Path | Change | +|---|---| +| `l4d2web/l4d2web/templates/overlays.html` | Reorder fields (Name → Type → System-wide); replace native fieldset+radios+checkbox with new `.field` / `.radio-row` / `.switch-row` markup; drop the path-hint `

`; rename `.modal*` → `.dialog*` if aligning with the redesign plan. | +| `l4d2web/l4d2web/templates/overlay_detail.html:43-67` | Delete the `

` block; keep textarea but rewrite its surrounding markup as a `.field` block with label + helper text; move `Refresh from Steam` out of its own `
` and put it in a single `.table-actions` row below the items table; add a summary span on the left of that row. | +| `l4d2web/l4d2web/templates/_overlay_item_table.html` | Verify whether per-row actions exist (e.g., remove-item). Out of scope to change today, but flag for the implementation session: the design preserves whatever per-row actions are there. | +| `l4d2web/l4d2web/static/css/components.css` | Add the new component CSS (see below). Existing `.modal*` rules either stay (if we keep old class names) or get renamed to `.dialog*`. Remove `.workshop-input-mode` (no rules to remove — fieldset class has zero CSS today anyway). | +| `l4d2web/l4d2web/routes/workshop_routes.py:36-99` | Delete the input-mode branching; unify the handler to (1) parse input, (2) batch-resolve collections, (3) batch-fetch metadata. Existing helpers `parse_workshop_input()`, `resolve_collection()`, `fetch_metadata_batch()` all get reused. | +| `l4d2web/l4d2web/steam/steam_workshop.py` | Add (or refactor): a `partition_collections_and_items(ids)` helper that does one `GetCollectionDetails` batch call and returns `(item_ids, collection_id_to_children)`. The exact shape can mirror existing module conventions. | + +### Component CSS to add + +These should live in `components.css` and be reusable beyond just these two +surfaces — they form a small set of primitives the rest of the app can adopt +as it migrates. + +- `.field` (existing pattern, may already partially exist) — grid container + with `gap: var(--space-xs)`; children are `.field-label`, optional + `.field-hint`, and the control. +- `.radio-row` — flex row, gap `var(--space-s)`, custom radio dot via + `::after`; `.radio-row.is-selected` colors the inner dot. +- `.radio-list` — grid container for a vertical stack of `.radio-row`s with + `gap: var(--space-xs)`. Replaces the `
` pattern. +- `.switch` + `.switch-row` — pill-shaped toggle, on-state uses + `--color-button-primary`. Left-aligned in its row, consistent with + `.radio-row` left edge. +- `.table-actions` — flex row with `justify-content: space-between`, + `align-items: center`, top margin `var(--space-m)`. Sits below a + `.table-wrap`. + +Existing tokens (already in `tokens.css`) are sufficient. No new color or +spacing tokens needed. + +### Things explicitly **not** changing + +- The `` open/close JavaScript (`data-inline-modal-close` handlers) + stays as-is. +- The overlay detail page's `Files` and `Used by` sections. +- The `Delete overlay` / `Rename` actions at the bottom of the page. +- The Steam-side caching/refresh logic — only the UI placement of the + refresh button is moving. + +## Verification + +End-to-end checks for the implementation session: + +1. **Dev server**: `python scripts/dev-server.py` (not plain `flask run` — + the latter misroutes `LEFT4ME_ROOT` on macOS). +2. **Create modal**: open the overlays list page, click "Create overlay". + - Verify field order: Name → Type → System-wide. + - Verify no fieldset border around Type. + - Verify custom radio dots fill with accent color on selection. + - Verify switch toggles state and visually animates. + - Verify no "path is generated automatically" copy anywhere. + - Submit with each of the three types in turn; verify the overlay is + created with the correct type each time. +3. **Workshop section**: + - Create a workshop overlay; navigate to its detail page. + - Verify only one textarea + one `Add` button (no input-mode radio). + - Paste a single item ID (e.g. `3726529483`); click Add. Item appears. + - Paste a collection URL (e.g. + `https://steamcommunity.com/sharedfiles/filedetails/?id=3724125665`); + click Add. The 6 children appear, not the collection itself. + - Paste a mix of items and a collection in one submission; verify all + resolve correctly. + - Verify items table ends at its last row (no internal footer bar). + - Verify summary + `↻ Refresh from Steam` sit below the table as a + single row. + - Click Refresh from Steam; verify metadata refresh fires. +4. **Stale-content sweep**: `grep -rn "path is generated automatically" + l4d2web/` should return no matches after the change. +5. **i18n check** (if applicable): if the project uses i18n strings for + these screens, verify the removed/changed strings are cleaned up. + +## Open follow-ups (out of scope) + +- Once the new component CSS (`.radio-row`, `.switch-row`, `.field`, + `.table-actions`) lands, sweep the rest of the templates for fieldsets + and native checkboxes that could adopt the same vocabulary. Don't do + this in the same commit — surface it as a follow-up so the diff for this + change stays scoped. +- The `superpowers:brainstorming` skill's companion server has an + owner-PID detection bug that kills the server when launched via + `Bash(run_in_background: true)` on macOS. Workaround during this + brainstorm was launching `node server.cjs` directly with + `BRAINSTORM_OWNER_PID=1`. Small upstream PR opportunity, unrelated to + this codebase.