265 lines
11 KiB
Markdown
265 lines
11 KiB
Markdown
<!-- Edited with Claude Code -->
|
||
# KonCad UI redesign — design
|
||
|
||
Refresh the KonCad web UI with a "Soft Slate" visual style (GitHub / Notion-dark
|
||
inspired), light/dark via `prefers-color-scheme`, lightweight inline syntax
|
||
highlighting for the Caddyfile editors, and a handful of small UX wins. No
|
||
backend changes; same single-file PHP structure.
|
||
|
||
## Goals
|
||
|
||
- A modern, calm, information-dense look that fits a homelab tool you open
|
||
occasionally.
|
||
- Auto-respect the OS color-scheme preference (no manual toggle).
|
||
- Make the Caddyfile editors readable at a glance with simple syntax colors.
|
||
- Add a small set of polish improvements that the new look invites — without
|
||
changing what the app does or its data flow.
|
||
|
||
## Non-goals
|
||
|
||
- No changes to PHP backend logic (parser, save handler, upstream check, auth
|
||
model).
|
||
- No new dependencies. Stays a single-file PHP tool — no CDN, no build step.
|
||
- No structural rework — header / global panel / list of sites stays.
|
||
- No new features (no draft staging, no diff view, no per-directive forms,
|
||
no bulk site operations, no manual theme toggle).
|
||
- No editor features beyond highlighting (no line numbers, no bracket matching,
|
||
no autocomplete).
|
||
|
||
## Visual system
|
||
|
||
CSS custom properties on `:root` for dark, overridden inside
|
||
`@media (prefers-color-scheme: light)`. Both auth screens and the main page
|
||
use the same token set.
|
||
|
||
| Token | Dark | Light | Used for |
|
||
|---|---|---|---|
|
||
| `--bg` | `#0d1117` | `#f6f8fa` | page background |
|
||
| `--surface` | `#161b22` | `#ffffff` | panels, cards |
|
||
| `--surface-2` | `#0d1117` | `#f6f8fa` | editor / nested surfaces |
|
||
| `--border` | `#21262d` | `#d0d7de` | every divider |
|
||
| `--text` | `#e6edf3` | `#1f2328` | primary text |
|
||
| `--muted` | `#7d8590` | `#656d76` | labels, subtle text |
|
||
| `--accent` | `#58a6ff` | `#0969da` | links, focus, addresses |
|
||
| `--accent-bg` | `rgba(88,166,255,0.12)` | `rgba(9,105,218,0.1)` | accent backgrounds, focus ring |
|
||
| `--ok` | `#3fb950` | `#1a7f37` | success status |
|
||
| `--warn` | `#d29922` | `#9a6700` | warnings |
|
||
| `--error` | `#f85149` | `#cf222e` | errors |
|
||
|
||
**Type:** Inter via system stack
|
||
(`-apple-system, "Segoe UI", "Inter", system-ui, sans-serif`); JetBrains Mono
|
||
for code (with monospace fallback). Sizes: 13px base, 12px secondary, 11px
|
||
labels/badges.
|
||
|
||
**Geometry:** 8px radius on inputs/buttons, 10px on panels. 1px borders
|
||
throughout — no drop shadows. Focus ring: `0 0 0 3px var(--accent-bg)` on
|
||
inputs and buttons. Spacing on a 4px grid.
|
||
|
||
## Layout
|
||
|
||
Same three regions as today.
|
||
|
||
### Header (sticky)
|
||
|
||
- Left: a small (18×18) gradient square logo mark + "KonCad" word in 700
|
||
weight, `-0.01em` letter-spacing.
|
||
- Center: a status pill — `● Caddy ready` (green) on success,
|
||
`● Caddy unreachable` (red) when the admin API is down, `● Deploying…`
|
||
(amber, with a 1.4s pulse animation) during a deploy. Pill background uses
|
||
a tinted version of its color.
|
||
- Right: primary `Deploy` button (green, GitHub-style primary) and a quiet
|
||
`Log out` ghost button when auth is enabled.
|
||
|
||
### Main column
|
||
|
||
- `max-width: 960px` centered, 1.5rem horizontal padding.
|
||
- **Global Options panel** — surface card with a header strip
|
||
(`Global Options` title + a small grey badge counting non-blank,
|
||
non-comment lines, e.g. `2 directives`). Body holds the highlighted editor.
|
||
- **Sites section** — section title `Sites` with a `+ Add site` ghost button on
|
||
the right, then a vertical list of site cards.
|
||
|
||
### Site card
|
||
|
||
- **Collapsed**: chevron, address (mono, `--accent` color), a one-line summary
|
||
chip (`→ host:port` if the body has a `reverse_proxy` line, else
|
||
`N directives`), and a `Remove` ghost-danger button visible on hover.
|
||
- **Expanded**: address bar, the highlighted editor, and any
|
||
`upstream-warnings` rendering area (existing slot, restyled).
|
||
|
||
### Empty state for sites
|
||
|
||
A dashed-border placeholder card replacing the current grey one-liner: small
|
||
icon (`⊕` or similar), heading `No sites yet`, and an inline primary
|
||
`+ Add site` button.
|
||
|
||
### Auth screens (setup / login)
|
||
|
||
Same centered-card pattern, retoned to the new tokens. Logo mark + "KonCad"
|
||
header, subtitle (`Create your login credentials` / `Sign in to continue`),
|
||
form with one username + one password input and a primary submit button.
|
||
Inline error message uses `--error`.
|
||
|
||
### Modals & toasts
|
||
|
||
- **Upstream warning modal**: same content, retoned. Dark-mode backdrop gets
|
||
`backdrop-filter: blur(4px)`.
|
||
- **Toasts**: same triggers, restyled. Slide in with
|
||
`transform: translateY(8px) → 0`, fade. Auto-dismiss at 5s (unchanged).
|
||
|
||
## Highlighted editor
|
||
|
||
Textarea-overlay technique. Native cursor, undo, IME, copy/paste behavior is
|
||
preserved; the highlighted layer is purely decorative.
|
||
|
||
### Markup per editor
|
||
|
||
```html
|
||
<div class="editor-wrap">
|
||
<pre class="editor-hl" aria-hidden="true"></pre>
|
||
<textarea class="editor-input" spellcheck="false">…</textarea>
|
||
</div>
|
||
```
|
||
|
||
### Mechanics
|
||
|
||
- `<pre>` and `<textarea>` are absolutely positioned in the same box, share
|
||
identical font, font-size, line-height, padding, border, and box-sizing.
|
||
- Textarea has `color: transparent; caret-color: var(--text)` so the user
|
||
sees the painted `<pre>` text and a real caret.
|
||
- On every `input` and `scroll`: read `textarea.value`, run `tokenize()`, write
|
||
`<pre>.innerHTML`, copy `scrollTop`/`scrollLeft` from textarea to `<pre>`.
|
||
- A trailing newline is appended before tokenizing so the last line renders.
|
||
|
||
### Tokenizer
|
||
|
||
Pure-JS, regex-based, ~60 LOC. Tokenization runs per-line, in this priority
|
||
order so earlier rules win:
|
||
|
||
1. Leading whitespace — preserved as-is.
|
||
2. Comment — `#` to end of line.
|
||
3. String — `"…"` and `'…'` (escape-aware: `\\` and `\"`).
|
||
4. Placeholder — `\{[^{}\n]*\}` matching `{$VAR}`, `{http.…}`, `{args.0}`,
|
||
etc. Bare `{` or `}` outside this pattern fall through to the brace rule.
|
||
5. Brace — lone `{` or `}`.
|
||
6. Number — `:\d+` (port-like) and standalone integers.
|
||
7. Directive — first non-whitespace word of the line, only if it's in the
|
||
known directive list.
|
||
8. Default — any other character class falls through to plain text.
|
||
|
||
Known directives (initial list): `reverse_proxy`, `root`, `file_server`,
|
||
`encode`, `tls`, `header`, `redir`, `respond`, `route`, `handle`,
|
||
`handle_path`, `import`, `log`, `email`, `admin`, `auto_https`, `php_fastcgi`,
|
||
`basicauth`, `try_files`, `rewrite`, `uri`, `request_body`, `templates`,
|
||
`map`, `metrics`, `acme_dns`, `acme_ca`. Easy to extend later by appending
|
||
to the list.
|
||
|
||
### Token classes & colors
|
||
|
||
| Class | Dark | Light |
|
||
|---|---|---|
|
||
| `c` comment | `#7d8590` | `#6e7781` |
|
||
| `d` directive | `#ff7b72` | `#cf222e` |
|
||
| `s` string | `#a5d6ff` | `#0a3069` |
|
||
| `p` placeholder | `#d2a8ff` | `#8250df` |
|
||
| `n` number | `#79c0ff` | `#0550ae` |
|
||
| `b` brace | `#7d8590` | `#6e7781` |
|
||
|
||
These live as CSS variables (`--tok-c`, `--tok-d`, …) under both the dark and
|
||
light blocks.
|
||
|
||
### Tab handling
|
||
|
||
Existing `handleTab()` behavior preserved (Tab inserts 4 spaces, no
|
||
focus-jump). The overlay re-tokenizes on the resulting `input` event.
|
||
|
||
### Scope
|
||
|
||
The two existing editor types — global options + each site body. Both render
|
||
through a single `mountEditor(textarea)` helper. No line numbers, no
|
||
bracket matching, no autocomplete.
|
||
|
||
## Small UX polish
|
||
|
||
- **Header status pill** wired to the existing `check_admin` result and to
|
||
deploy state.
|
||
- **Site card summary chip** (collapsed only): scan the body for the first
|
||
`reverse_proxy` line and show `→ host:port` (truncated to ~28 chars). If
|
||
none, show `N directives` (non-blank, non-comment lines). Updated on
|
||
every collapse and on `change` of the textarea.
|
||
- **Directive count badge** on the Global Options header: count of non-blank,
|
||
non-comment lines. Updated on `input`, debounced 200ms.
|
||
- **Remove site → 1-step inline confirm**: first click flips the button into
|
||
a red `Confirm remove?` for ~3 seconds; second click within that window
|
||
deletes. Click outside / 3s timeout reverts.
|
||
- **Deploy keyboard shortcut**: `Cmd/Ctrl+S` triggers `preDeploy()`. Listener
|
||
`preventDefault`s only when focus is inside the app (any element under
|
||
`<main>` or `<header>`), not globally — and only when the deploy button
|
||
is enabled. Button gets a `title` hint.
|
||
- **Disabled state** when admin API is unreachable: existing logic, plus a
|
||
visual change — disabled inputs get `0.5` opacity and a subtle striped
|
||
background (`repeating-linear-gradient`). The status pill shows the
|
||
reason text.
|
||
|
||
## Files touched
|
||
|
||
- **`app/index.php`** — only file modified.
|
||
|
||
### Sections being rewritten
|
||
|
||
- Auth-page HTML + `<style>` (currently lines ~239–275): retoned to the new
|
||
tokens, same form fields and POST behavior.
|
||
- Main page `<style>` block (currently lines ~282–550): replaced.
|
||
- Main page HTML (currently lines ~552–600): minor structural tweaks for the
|
||
status pill, summary chip, badge, empty state.
|
||
- `<script>` (currently lines ~602–886): adds `mountEditor()`, `tokenize()`,
|
||
`summaryFor()`, `directiveCount()`, `armRemove()`, and a global
|
||
keyboard-shortcut listener. Updates `renderSites()` to emit the new
|
||
markup. All other functions unchanged.
|
||
|
||
### Untouched
|
||
|
||
- All PHP above the auth-page HTML (config, session/auth, helpers, parser,
|
||
`caddyLoad`, `checkUpstream`, every `?action=…` handler).
|
||
- Existing JS: `init()`, `preDeploy()`, `doDeploy()`, `extractUpstreams()`,
|
||
`collectSites()`, `addSite()`, `removeSite()` core, `togglePanel()`,
|
||
`toggleSite()`, `setEditable()`, `setStatus()`, `setDeployBtn()`,
|
||
`toast()`, `esc()`, `logout()`, `handleTab()`. All keep their current
|
||
signatures and behavior.
|
||
|
||
## Risks & mitigations
|
||
|
||
- **Overlay desync** (highlighted layer drifting from textarea on paste, IME,
|
||
resize, or scroll): the textarea remains the source of truth; the `<pre>`
|
||
is rebuilt from `textarea.value` on every `input` and `scroll`. Identical
|
||
font metrics + a trailing-newline trick handle the last-line case.
|
||
- **`removeSite` two-click** is a behavior change. Acceptable: deleting a
|
||
configured site has a real blast radius, and a 3s armed window is friction
|
||
light.
|
||
- **Global `Cmd/Ctrl+S` capture** could surprise users in a textarea. Mitigated
|
||
by only `preventDefault`ing when the deploy button is enabled and focus is
|
||
inside the app shell.
|
||
- **Light-mode regression**: every color must come from a token — no hex
|
||
literals in component CSS. Manual test: flip OS theme and confirm both
|
||
palettes render correctly on every screen (auth, main, modal, toast,
|
||
disabled state).
|
||
|
||
## Manual test plan
|
||
|
||
1. Load with the existing Caddyfile — global + sites populate correctly,
|
||
highlighting renders for both editors.
|
||
2. Edit each editor — highlight tracks input, scroll syncs, Tab indents
|
||
without focus loss, paste of multi-line content highlights correctly.
|
||
3. Flip OS theme dark↔light — every screen (auth, main, modal, toast,
|
||
disabled state) re-themes without a reload.
|
||
4. Add site, remove site (verify 2-click confirm), collapse/expand cards,
|
||
summary chip updates after edits.
|
||
5. Deploy success → green pill + green toast. Deploy with bad config → red
|
||
pill + error toast with Caddy's message.
|
||
6. Stop the Caddy admin API → reload page → unreachable disabled state
|
||
renders, deploy button disabled, status pill red with reason.
|
||
7. `Cmd/Ctrl+S` triggers deploy when admin is reachable; does nothing when
|
||
disabled.
|
||
8. Setup screen (scratch container with `/data/.auth` removed) and login
|
||
screen both look right in both color schemes.
|