Public: anyone can read this; the crew can change it.
Design: a migration's progress stages draw §5's row and badge, and stage-dot/stage-detail leave §5d #4231
mason/forge:mason/4082-design-a-migration-s-progress-stages-dra → main 12 commits fork 3 threads · 3 unresolved
8 files
changed +118
−26
docs/DESIGN.md +2 −2
| @@ -182,7 +182,7 @@ specification. | ||
| 182 | 182 | | **where strip** `whereStrip()` (`scope.ts`) | `.where > .where-place` | `data-state=reading\|present\|absent` — accent dot, success dot, faint dot — the dot is the place's `aria-hidden` glyph span, its aside `.muted` | three places, always in this order and these words; a place is a link where one exists, and the third is the pin toggle | `● codeberg.org · ● workbench · ◆ this machine` | |
| 183 | 183 | | **live-browse banner** `liveBanner()` | `.live-note` | — | only on a live browse, above the content, one sentence | one accent line under the tab row | |
| 184 | 184 | | **where-it-lives block** | `.where-block` | — | origin, last fetch, Sync now and where pushes land, as one block in the About rail | the same four lines under a rule | |
| 185 | | **mirror stages** `stageList()` | `.stages > li` | `data-state=done\|now\|failed\|todo` | the stage order is the markup order; a script updates it in place and goes to the mirror on done; without JavaScript the same markup renders and a `<noscript>` Reload link re-reads it. Nothing here refreshes itself: no `<meta refresh>`, no timer | a checklist with `●`/`◐`/`○` | | |
| 185 | | **mirror stages** `stageList()` | `.stages > li`, each a `stageRow()`: a `row` with the glyph as lead and a `badge` for the detail | `data-state=done\|now\|failed\|todo` | the stage order is the markup order; a script updates it in place and goes to the mirror on done; without JavaScript the same markup renders and a `<noscript>` Reload link re-reads it. Nothing here refreshes itself: no `<meta refresh>`, no timer | a checklist with `●`/`◐`/`○` | | |
| 186 | 186 | | **origin chip** (`chrome.ts`) | `.repo-origin > .origin-chip` | the forge's mark: `github` / `forgejo` / `gitea` | the older one-line form, still used off the repo header | one `mirrored from owner/name @ host` fact line | |
| 187 | 187 | | **origin state badge** `badge()` | `.badge` | `success` healthy · `danger` needs re-auth · `attn` error | the error message sits under the row, never inside the badge | the same three words beside the row | |
| 188 | 188 | | **imported author** `originTag()` | `.byline.origin-by` | the origin's mark instead of an avatar | never a link to `/name` — that would be a different person | `▲ login` | |
| @@ -395,7 +395,7 @@ gone, so this list only shrinks. | ||
| 395 | 395 | A `.field` directly inside a `.bar` drops its bottom margin and the bar aligns to the end, so a labelled input and its button share a baseline |
| 396 | 396 | - **`style/components.ts`** — parts of the §5 components that the table does not spell out — the palette's list, the menu's items, a dialog's head and foot, comments, the theme picker — and a few small helpers beside them: `.cat` `.clone` `.clone-text` `.comment` `.comment-body` `.comment-form` `.dash` `.dialog-body` `.dialog-foot` `.dialog-head` `.empty-title` `.error-note` `.field-row` `.form-actions` `.hex` `.ico` `.ico-loader` `.list` `.live-status` `.menu-item` `.menu-panel` `.menu-sep` `.menu-title` `.palette-empty` `.palette-foot` `.palette-group` `.palette-heading` `.palette-input` `.palette-item` `.palette-list` `.passkey` `.passkey-lead` `.passkey-note` `.passkey-off` `.passkey-on` `.preview` `.sep` `.split` `.sprite` `.swatch` `.table-scroll` `.tell-here` `.theme-apply` `.theme-option` `.tick` `.timeline` `.tl-dot` `.toast-body` `.topbar-search` |
| 397 | 397 | - **`style/components.ts`, settings rows** — a list whose rows are settings (limits, capacity): the `<ul class="list setting-list">` lets title and meta wrap instead of ellipsizing, and a row's controls take their own line under 640px. `.row-fields` is the form in that row's trail (input, Save, Default): always visible, never hover-gated, wrapping under the text before it would clip. Use both for any page whose rows show a name, a current value, and a control to change it; use `.row-actions` only for secondary actions (delete, wake, pin, revoke). Flags, telemetry, cloud, people, crew roles and subscription headroom/budget use `.row-fields`. Classes: `.row-fields` `.setting-list` |
| 398 | - **`style/content.ts`, page furniture** — what frames a page's content: page and repo heads, the merge box, the front page and its tiles, explore, backups, boards, the fleet chart's series colours, lineage: `.app-shelf` `.backups-drill` `.backups-error` `.backups-now` `.backups-restore` `.bform` `.bgrid` `.bmanage` `.boards-result` `.bp-h2` `.bp-h3` `.bp-w2` `.bp-w3` `.break` `.bt-bar` `.bt-grid` `.bt-group` `.bt-hist` `.bt-name` `.bt-procs` `.bt-row` `.bt-val` `.commit-body` `.commit-head` `.domain-records` `.explore-filters` `.explore-line` `.explore-main` `.explore-name` `.explore-row` `.fg-s0` `.fg-s1` `.fg-s2` `.fg-s3` `.fg-s4` `.fg-s5` `.fg-s6` `.fg-s7` `.filters` `.flag-form` `.front-admin` `.front-controls` `.front-crew` `.front-featured` `.front-featured-body` `.front-featured-look` `.front-issues` `.front-live` `.front-more` `.front-pick` `.front-pin-any` `.front-weights` `.frozen` `.frozen-form` `.frozen-sentence` `.headroom` `.issue-head` `.issue-meta` `.merge-box` `.merge-form` `.merge-headline` `.merge-sub` `.mirror-form` `.number` `.origin-link` `.origin-mark` `.origin-name` `.origin-row` `.owner` `.page-head` `.path-head` `.policy-line` `.qf` `.repo-actions` `.repo-audience` `.repo-desc` `.repo-layout` `.repo-lineage` `.repo-title` `.search` `.slash` `.stage-detail` `.stage-dot` `.steps` `.sub` `.sys-pair` `.table-wrap` `.terminal-line` `.tok` `.tree-row` `.tree-total` `.wall-cells` `.where-sep` | |
| 398 | - **`style/content.ts`, page furniture** — what frames a page's content: page and repo heads, the merge box, the front page and its tiles, explore, backups, boards, the fleet chart's series colours, lineage: `.app-shelf` `.backups-drill` `.backups-error` `.backups-now` `.backups-restore` `.bform` `.bgrid` `.bmanage` `.boards-result` `.bp-h2` `.bp-h3` `.bp-w2` `.bp-w3` `.break` `.bt-bar` `.bt-grid` `.bt-group` `.bt-hist` `.bt-name` `.bt-procs` `.bt-row` `.bt-val` `.commit-body` `.commit-head` `.domain-records` `.explore-filters` `.explore-line` `.explore-main` `.explore-name` `.explore-row` `.fg-s0` `.fg-s1` `.fg-s2` `.fg-s3` `.fg-s4` `.fg-s5` `.fg-s6` `.fg-s7` `.filters` `.flag-form` `.front-admin` `.front-controls` `.front-crew` `.front-featured` `.front-featured-body` `.front-featured-look` `.front-issues` `.front-live` `.front-more` `.front-pick` `.front-pin-any` `.front-weights` `.frozen` `.frozen-form` `.frozen-sentence` `.headroom` `.issue-head` `.issue-meta` `.merge-box` `.merge-form` `.merge-headline` `.merge-sub` `.mirror-form` `.number` `.origin-link` `.origin-mark` `.origin-name` `.origin-row` `.owner` `.page-head` `.path-head` `.policy-line` `.qf` `.repo-actions` `.repo-audience` `.repo-desc` `.repo-layout` `.repo-lineage` `.repo-title` `.search` `.slash` `.steps` `.sub` `.sys-pair` `.table-wrap` `.terminal-line` `.tok` `.tree-row` `.tree-total` `.wall-cells` `.where-sep` | |
| 399 | 399 | - **`style/content.ts`, code view** — the source view and the syntax-highlight token classes `highlight-html.ts` builds as `tok-${kind}`: `.blob-view` `.ln` `.tok-attribute` `.tok-comment` `.tok-constant` `.tok-decorator` `.tok-deleted` `.tok-emphasis` `.tok-function` `.tok-heading` `.tok-inserted` `.tok-keyword` `.tok-link` `.tok-meta` `.tok-number` `.tok-operator` `.tok-plain` `.tok-property` `.tok-punctuation` `.tok-regex` `.tok-string` `.tok-tag` `.tok-type` `.tok-variable` |
| 400 | 400 | - **`style/content.ts`, prose (markdown)** — table cell alignment, built by `markdown.ts` as `ta-${align}`: `.ta-c` `.ta-r` |
| 401 | 401 | - **`style/content.ts`, diff viewer** — the diff table: its gutters, line kinds, file head and inline review comments: `.add` `.del` `.dh` `.diff` `.diff-body` `.diff-head` `.diff-note` `.diff-path` `.diff-stat` `.diff-stub` `.diff-summary` `.diff-table` `.dl` `.dl-review` `.dn` `.dn-comment` `.nonl` `.rc-hidden` `.rc-resolve` `.rc-resolved` `.wd` |
src/web/client.ts +4 −3
| @@ -116,10 +116,11 @@ export const mirrorJs = /* js */ ` | ||
| 116 | 116 | : i === there ? (stage === 'done' ? 'done' : 'now') |
| 117 | 117 | : 'todo'; |
| 118 | 118 | li.setAttribute('data-state', state); |
| 119 | var dot = li.querySelector('.stage-dot'); | |
| 119 | var dot = li.querySelector('[data-stage-glyph]'); | |
| 120 | 120 | if (dot) dot.textContent = glyph[state]; |
| 121 | var note = li.querySelector('.stage-detail'); | |
| 122 | if (note) note.textContent = state === 'now' ? (detail || '') : ''; | |
| 121 | var note = li.querySelector('[data-stage-detail]'); | |
| 122 | var text = state === 'now' ? (detail || '') : ''; | |
| 123 | if (note) { note.hidden = !text; note.firstElementChild.textContent = text; } | |
| 123 | 124 | }); |
| 124 | 125 | } |
| 125 | 126 |
src/web/pages/browse.ts +2 −5
| @@ -68,6 +68,7 @@ import { | ||
| 68 | 68 | pager, |
| 69 | 69 | row, |
| 70 | 70 | seg, |
| 71 | stageRow, | |
| 71 | 72 | stateBadge, |
| 72 | 73 | time, |
| 73 | 74 | tlComment, |
| @@ -1037,11 +1038,7 @@ export function stageList(job: MirrorJob, streamUrl: string): Html { | ||
| 1037 | 1038 | > |
| 1038 | 1039 | ${STAGES.map((stage) => { |
| 1039 | 1040 | const state = stageState(stage.name, job.stage); |
| 1040 | return html`<li data-stage-name="${stage.name}" data-state="${state}"> | |
| 1041 | <span class="stage-dot" aria-hidden="true">${GLYPH[state]}</span> | |
| 1042 | <span class="stage-label">${stage.label}</span> | |
| 1043 | <span class="stage-detail">${state === "now" ? job.detail : ""}</span> | |
| 1044 | </li>`; | |
| 1041 | return stageRow(stage.name, stage.label, state, GLYPH[state], state === "now" ? job.detail : ""); | |
| 1045 | 1042 | })} |
| 1046 | 1043 | </ol>`; |
| 1047 | 1044 | } |
src/web/pages/migrate.ts +8 −7
| @@ -55,6 +55,7 @@ import { | ||
| 55 | 55 | icon, |
| 56 | 56 | row, |
| 57 | 57 | selectField, |
| 58 | stageRow, | |
| 58 | 59 | field as formField, |
| 59 | 60 | } from "../ui.ts"; |
| 60 | 61 | import { prefill, originHost } from "./migrate-prefill.ts"; |
| @@ -719,11 +720,7 @@ function stageRows(job: MirrorJob): Html { | ||
| 719 | 720 | ? "now" |
| 720 | 721 | : "todo"; |
| 721 | 722 | const glyph = state === "done" ? "●" : state === "now" ? "◐" : "○"; |
| 722 | return html`<li data-stage-name="${stage.name}" data-state="${state}"> | |
| 723 | <span class="stage-dot" aria-hidden="true">${glyph}</span> | |
| 724 | <span class="stage-label">${stage.label}</span> | |
| 725 | <span class="stage-detail">${state === "now" ? job.detail : ""}</span> | |
| 726 | </li>`; | |
| 723 | return stageRow(stage.name, stage.label, state, glyph, state === "now" ? job.detail : ""); | |
| 727 | 724 | })} |
| 728 | 725 | </ol>`; |
| 729 | 726 | } |
| @@ -742,6 +739,10 @@ const migrateJobJs = /* js */ ` | ||
| 742 | 739 | if (!job || typeof EventSource === 'undefined') return; |
| 743 | 740 | var order = ['creating', 'fetching', 'issues', 'pulls', 'crew', 'done']; |
| 744 | 741 | var source = new EventSource('/api/v1/migrate/' + encodeURIComponent(job) + '/stream'); |
| 742 | function stageDetail(note, text) { | |
| 743 | note.hidden = !text; | |
| 744 | note.firstElementChild.textContent = text; | |
| 745 | } | |
| 745 | 746 | function patch(e) { |
| 746 | 747 | var data; |
| 747 | 748 | try { data = JSON.parse(e.data); } catch (_) { return; } |
| @@ -753,8 +754,8 @@ const migrateJobJs = /* js */ ` | ||
| 753 | 754 | var state = data.stage === 'failed' ? 'todo' |
| 754 | 755 | : data.stage === 'done' || idx < at ? 'done' : idx === at ? 'now' : 'todo'; |
| 755 | 756 | row.setAttribute('data-state', state); |
| 756 | row.querySelector('.stage-dot').textContent = state === 'done' ? '\\u25cf' : state === 'now' ? '\\u25d0' : '\\u25cb'; | |
| 757 | row.querySelector('.stage-detail').textContent = state === 'now' && data.detail ? data.detail : ''; | |
| 757 | row.querySelector('[data-stage-glyph]').textContent = state === 'done' ? '\\u25cf' : state === 'now' ? '\\u25d0' : '\\u25cb'; | |
| 758 | stageDetail(row.querySelector('[data-stage-detail]'), state === 'now' && data.detail ? data.detail : ''); | |
| 758 | 759 | } |
| 759 | 760 | if (data.stage === 'done' || data.stage === 'failed') { source.close(); location.reload(); } |
| 760 | 761 | } |
src/web/style/content.ts +13 −9
| @@ -115,19 +115,23 @@ a.where-place:hover, button.where-place:hover { | ||
| 115 | 115 | /* A mirror in flight. One row per stage, in the order they happen; the row |
| 116 | 116 | says which of the three states it is in and nothing else moves. */ |
| 117 | 117 | .stages { list-style: none; margin: 0; padding: 0; } |
| 118 | .stages li { | |
| 119 | display: flex; align-items: center; gap: 10px; | |
| 120 | padding: 8px 0; font-size: 13px; color: var(--faint); | |
| 121 | } | |
| 118 | .stages li { font-size: 13px; color: var(--faint); } | |
| 122 | 119 | .stages li + li { border-top: 1px solid var(--border); } |
| 120 | /* A detail can be a sentence ("the origin has not finished making it; | |
| 121 | trying again in 5s"): the trail drops under the label and the badge | |
| 122 | wraps, so a 360px screen never scrolls sideways. */ | |
| 123 | .stages .row { padding: 8px 0; flex-wrap: wrap; } | |
| 124 | .stages .row-main { flex: 1 1 12rem; } | |
| 125 | .stages .row-trail { flex: 0 1 auto; min-width: 0; max-width: 100%; } | |
| 126 | .stages .badge { white-space: normal; overflow-wrap: anywhere; border-radius: var(--radius-sm); } | |
| 123 | 127 | .stages li[data-state="done"] { color: var(--muted-fg); } |
| 124 | .stages li[data-state="done"] .stage-dot { color: var(--success); } | |
| 128 | .stages li[data-state="done"] .row-lead { color: var(--success); } | |
| 125 | 129 | .stages li[data-state="now"] { color: var(--fg); font-weight: 560; } |
| 126 | .stages li[data-state="now"] .stage-dot { color: var(--accent); } | |
| 130 | .stages li[data-state="now"] .row-lead { color: var(--accent); } | |
| 127 | 131 | .stages li[data-state="failed"] { color: var(--danger); } |
| 128 | .stages li[data-state="failed"] .stage-dot { color: var(--danger); } | |
| 129 | .stage-dot { flex: none; width: 16px; text-align: center; } | |
| 130 | .stage-detail { margin-left: auto; color: var(--faint); font-size: 12.5px; font-weight: 400; } | |
| 132 | .stages li[data-state="failed"] .row-lead { color: var(--danger); } | |
| 133 | .stages .row-lead { width: 16px; justify-content: center; } | |
| 134 | .stages .row-title { font-weight: inherit; } | |
| 131 | 135 | .origin-chip { |
| 132 | 136 | display: inline-flex; align-items: center; gap: 6px; |
| 133 | 137 | max-width: 100%; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; |
src/web/ui.ts +19
| @@ -945,6 +945,25 @@ export function row(o: RowOptions): Html { | ||
| 945 | 945 | </li>`; |
| 946 | 946 | } |
| 947 | 947 | |
| 948 | /** One stage of a job in flight, for a `.stages` list: a `row` whose lead is | |
| 949 | * the stage's glyph and whose trail is a `badge` with the stage's detail, | |
| 950 | * hidden while there is none. A script finds the parts by `data-stage-name`, | |
| 951 | * `data-stage-glyph` and `data-stage-detail` and patches them in place. */ | |
| 952 | export function stageRow( | |
| 953 | name: string, | |
| 954 | label: string, | |
outdated
The glyph is aria-hidden and state shows only through colour and the glyph, so assistive tech cannot tell which stage is current. Next step: add a visually hidden state word, or aria-current on the active row. |
||
| 955 | state: "done" | "now" | "failed" | "todo", | |
| 956 | glyph: string, | |
| 957 | detail: string, | |
| 958 | ): Html { | |
| 959 | return row({ | |
| 960 | title: label, | |
| 961 | lead: html`<span data-stage-glyph aria-hidden="true">${glyph}</span>`, | |
| 962 | trail: html`<span data-stage-detail${detail === "" ? raw(" hidden") : null}>${badge(detail, { variant: "outline" })}</span>`, | |
Next: the detail badge changes in place with no announcement. Put aria-live="polite" on the .stages list (or role=status on this wrapper) so screen readers hear progress. |
||
| 963 | data: { "stage-name": name, state }, | |
| 964 | }); | |
| 965 | } | |
| 966 | ||
| 948 | 967 | // ---- navigation ---- |
| 949 | 968 | |
| 950 | 969 | export interface TabItem { |
test/migrate.test.ts +4
| @@ -1217,6 +1217,10 @@ describe("migrate", () => { | ||
| 1217 | 1217 | ).text(); |
| 1218 | 1218 | expect(page).not.toContain('http-equiv="refresh"'); |
| 1219 | 1219 | expect(page).toContain(`data-job="${job.id}"`); |
| 1220 | // The stages are §5 rows (#4082): the words stay, the old classes go. | |
| 1221 | expect(page).toContain("Creating the repository"); | |
| 1222 | expect(page).toContain('data-stage-name="creating"'); | |
| 1223 | expect(page).not.toMatch(/class="[^"]*\bstage-(dot|detail)\b/); | |
| 1220 | 1224 | expect(page).toContain("<noscript>"); |
| 1221 | 1225 | expect(page).toContain("Reload"); |
| 1222 | 1226 | const streamPath = `/api/v1/migrate/${job.id}/stream`; |
test/stage-rows.test.ts added +66
| @@ -0,0 +1,66 @@ | ||
| 1 | /** | |
| 2 | * A job's progress stages are §5's `row` and `badge` (#4082): no page-local | |
| 3 | * `.stage-dot`/`.stage-detail`, and the parts a script patches are found by | |
| 4 | * `data-*` attributes. | |
| 5 | */ | |
| 6 | import { expect, test } from "bun:test"; | |
| 7 | import type { MirrorJob } from "../src/origins/jobs.ts"; | |
| 8 | import { stageList } from "../src/web/pages/browse.ts"; | |
| 9 | import { content } from "../src/web/style/content.ts"; | |
| 10 | import { stageRow } from "../src/web/ui.ts"; | |
| 11 | ||
| 12 | const job = (stage: MirrorJob["stage"], detail: string): MirrorJob => ({ | |
| 13 | id: "j1", | |
| 14 | kind: "mirror", | |
| 15 | originId: "o1", | |
| 16 | fullName: "octo/widgets", | |
| 17 | stage, | |
| 18 | detail, | |
| 19 | startedAt: "2026-10-21T00:00:00Z", | |
| 20 | }); | |
| 21 | ||
| 22 | test("a stage is a row with its glyph as lead and its detail in a badge", () => { | |
| 23 | const out = stageRow("fetching", "Fetching <all>", "now", "◐", "61% & more").text; | |
| 24 | expect(out).toContain('data-stage-name="fetching"'); | |
| 25 | expect(out).toContain('data-state="now"'); | |
| 26 | expect(out).toContain('class="row"'); | |
| 27 | expect(out).toContain('<span class="row-lead"><span data-stage-glyph aria-hidden="true">◐</span>'); | |
| 28 | expect(out).toContain("Fetching <all>"); | |
| 29 | expect(out).toMatch(/<span data-stage-detail><span\s+class="badge"\s+data-variant="outline"\s*>61% & more<\/span/); | |
| 30 | }); | |
| 31 | ||
| 32 | test("a stage with no detail keeps its badge, hidden, for the script to fill", () => { | |
| 33 | const out = stageRow("labels", "Importing labels", "todo", "○", "").text; | |
| 34 | expect(out).toContain("<span data-stage-detail hidden>"); | |
| 35 | expect(out).toContain('class="badge"'); | |
| 36 | }); | |
| 37 | ||
| 38 | test("the mirror checklist carries the stage words and neither old class", () => { | |
| 39 | const out = stageList(job("fetching", "receiving 61%"), "/stream").text; | |
| 40 | expect(out).not.toMatch(/class="[^"]*\bstage-(dot|detail)\b/); | |
| 41 | for (const words of ["Creating the repository", "Fetching every branch and tag", "Done"]) { | |
| 42 | expect(out).toContain(words); | |
| 43 | } | |
| 44 | expect(out).toContain("receiving 61%"); | |
| 45 | expect(out.match(/data-stage-name=/g)?.length).toBe(7); | |
| 46 | }); | |
| 47 | ||
| 48 | test("a sentence-long detail wraps inside the row instead of widening it", () => { | |
| 49 | const out = stageRow( | |
| 50 | "fetching", | |
| 51 | "Fetching every branch and tag", | |
| 52 | "now", | |
| 53 | "◐", | |
| 54 | "the origin has not finished making it; trying again in 5s", | |
| 55 | ).text; | |
| 56 | expect(out).toContain("trying again in 5s"); | |
| 57 | // .badge and .row-trail are nowrap and flex: none in components.ts; the | |
| 58 | // stages list lifts both, or the badge pushes the page past a phone's width. | |
| 59 | const rule = (selector: string): string => | |
| 60 | content.match(new RegExp(`\\n${selector.replace(/\./g, "\\.")} \\{([^}]*)\\}`))?.[1] ?? ""; | |
| 61 | expect(rule(".stages .badge")).toContain("white-space: normal"); | |
| 62 | expect(rule(".stages .row")).toContain("flex-wrap: wrap"); | |
| 63 | expect(rule(".stages .row-trail")).toContain("flex: 0 1 auto"); | |
| 64 | expect(rule(".stages .row-trail")).toContain("min-width: 0"); | |
| 65 | expect(rule(".stages .row-trail")).toContain("max-width: 100%"); | |
| 66 | }); |
new above
offline
Next step: add aria-live="polite" on the data-stage-detail wrapper (or role=status on the list) so patched detail text reaches screen readers. Not blocking.