Public: anyone can read this; the crew can change it.
Design: a repository's path head and its two-column layout use the design system, and path-head/repo-layout leave §5d #4450
scout/forge:scout/3944-design-a-repository-s-path-head-and-its → main 13 commits fork
6 files
changed +55
−30
docs/DESIGN.md +2 −2
| @@ -157,7 +157,7 @@ specification. | ||
| 157 | 157 | | **progress bar** `progress()` (`pages/milestones.ts`) | `progress` (element rule in `style/components.ts`; every `<progress>` on the site) | — | native `<progress max value>`, 4px, full width, an `aria-label` saying what is done; no width rule per value | `▓▓▓░░ 3 of 5` | |
| 158 | 158 | | **meter** `meter()` | `meter` | `data-tone=attn` when the share is a limit reached | native `<meter min=0 max=100>`, a whole percentage, an `aria-label` saying what it is a share of; no width rule per value, so no inline style | `▓▓▓░░ 62%` | |
| 159 | 159 | | **kbd** `kbd()` | `kbd` | — | — | a reverse-video key name | |
| 160 | | **card** `card()` / `listCard()` | `.card` (`.card-head`, `.card-links`, `.card-body`, `.card-foot`) | `data-tone=success\|danger\|merged\|attn` | — | a box with a title bar | | |
| 160 | | **card** `card()` / `listCard()` | `.card` (`.card-head`, `.card-links`, `.card-body`, `.card-foot`; `.card-open` lets a head's menu overflow the clip, `.card-pin` also sticks it under the topbar while a sibling body scrolls; `card(null, {head})` is the head-only bar, whose head drops its bottom rule) | `data-tone=success\|danger\|merged\|attn` | — | a box with a title bar | | |
| 161 | 161 | | **list row** `row()` | `.row` (`.row-lead`, `.row-main`, `.row-title`, `.row-meta`, `.row-trail`, `.row-actions`, `.row-children`; settings: `.setting-list`, `.row-fields`) | `data-state=open\|closed\|merged\|draft` — colours the **lead glyph**, so a list filtered by state carries no badge repeating the filter | hover, focus, `data-nav`; `fold` makes the row a `<details>`'s `<summary>`, its lead the caret turned when open (/map's lanes); `children` nests the rows under a row in a `<ul class="row-children">` inside its `<li>` — a tree (/family), a step in under a rule, real list nesting for assistive tech; `aria-current="true"` on the `<li>` (`current`) tints the row; `.row-meta` is one honest line: nowrap, ellipsis, `title` — except in a `.setting-list`, where it wraps | one line: glyph, title, right-aligned meta | |
| 162 | 162 | | **edit row** | `.edit-row` | — | one line on a desktop, stacked below 720px | a form line | |
| 163 | 163 | | **colour field** | `.color-field` | — | native `<input type=color>` plus its hex; works with no script | a hex entry | |
| @@ -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` `.policy-line` `.qf` `.repo-actions` `.repo-audience` `.repo-desc` `.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` | |
| 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/pages/repo.ts +11 −9
| @@ -746,8 +746,9 @@ export async function renderCode( | ||
| 746 | 746 | <span class="spacer"></span> |
| 747 | 747 | ${finderButton()} |
| 748 | 748 | </div>` |
| 749 | : html`<div class="path-head"> | |
| 750 | ${refMenu( | |
| 749 | : card(null, { | |
| 750 | extra: "card-open mt", | |
| 751 | head: html`${refMenu( | |
| 751 | 752 | o.refs, |
| 752 | 753 | ref, |
| 753 | 754 | (r) => `${base}/tree/${encodeURIComponent(r)}/${path}`, |
| @@ -760,14 +761,14 @@ export async function renderCode( | ||
| 760 | 761 | size: "sm", |
| 761 | 762 | variant: "outline", |
| 762 | 763 | icon: "history", |
| 763 | })} | |
| 764 | </div>`; | |
| 764 | })}`, | |
| 765 | }); | |
| 765 | 766 | const main = html`${bar} ${o.extra ?? null} |
| 766 | 767 | ${treeListing(base, ref, path, o.entries)} |
| 767 | 768 | <div class="mt">${readme}</div>`; |
| 768 | 769 | return o.rail === undefined |
| 769 | 770 | ? main |
| 770 | : html`<div class="repo-layout"> | |
| 771 | : html`<div class="split"> | |
| 771 | 772 | <div>${main}</div> |
| 772 | 773 | <aside aria-label="About">${o.rail}</aside> |
| 773 | 774 | </div>`; |
| @@ -850,8 +851,9 @@ export function renderBlob( | ||
| 850 | 851 | o.blob.kind === "too_large" ? "" : sizeWithTokens(o.blob.size, o.path); |
| 851 | 852 | const fileHref = `${base}/blob/${encoded}/${o.path}`; |
| 852 | 853 | return html`<div class="code-pane" id="code-pane" data-path="${o.path}"> |
| 853 | <div class="path-head"> | |
| 854 | ${refMenu( | |
| 854 | ${card(null, { | |
| 855 | extra: "card-pin mt", | |
| 856 | head: html`${refMenu( | |
| 855 | 857 | o.refs, |
| 856 | 858 | o.ref, |
| 857 | 859 | (r) => `${base}/blob/${encodeURIComponent(r)}/${o.path}`, |
| @@ -895,8 +897,8 @@ export function renderBlob( | ||
| 895 | 897 | variant: "outline", |
| 896 | 898 | icon: "history", |
| 897 | 899 | })} |
| 898 | ${editAction(scope, o.ref, o.path)} | |
| 899 | </div> | |
| 900 | ${editAction(scope, o.ref, o.path)}`, | |
| 901 | })} | |
| 900 | 902 | ${content} |
| 901 | 903 | </div>`; |
| 902 | 904 | } |
src/web/style/components.ts +10
| @@ -354,6 +354,16 @@ a.sha:hover { color: var(--accent); } | ||
| 354 | 354 | padding: 10px 14px; border-bottom: 1px solid var(--border); background: var(--muted); |
| 355 | 355 | } |
| 356 | 356 | .card-head h2, .card-head h3 { margin: 0; } |
| 357 | /* A head-only card (a bar) has nothing under it: no rule on the card's own border. */ | |
| 358 | .card-head:last-child { border-bottom: 0; } | |
| 359 | /* A card whose head opens a menu: the clip would cut the panel off. */ | |
| 360 | .card.card-open { overflow: visible; } | |
| 361 | /* ...and one that stays on screen while the body beside it scrolls (a file's | |
| 362 | location above long code). Opaque on purpose; it sticks within its parent. */ | |
| 363 | .card.card-pin { overflow: visible; position: sticky; top: calc(var(--topbar-h) - 1px); z-index: 6; } | |
| 364 | /* Without the clip the head's square ground would poke past the corners. */ | |
| 365 | :is(.card-open, .card-pin) > .card-head { border-radius: calc(var(--radius) - 1px) calc(var(--radius) - 1px) 0 0; } | |
| 366 | :is(.card-open, .card-pin) > .card-head:last-child { border-radius: calc(var(--radius) - 1px); } | |
| 357 | 367 | /* A card head's links: spaced apart, and each a 44px target on a thumb. */ |
| 358 | 368 | .card-links { display: inline-flex; align-items: center; gap: 10px; } |
| 359 | 369 | .card-links > a { color: inherit; } |
src/web/style/content.ts +1 −17
| @@ -191,12 +191,6 @@ a.origin-chip:hover { border-color: var(--border-strong); color: var(--fg); } | ||
| 191 | 191 | |
| 192 | 192 | .repo-actions { display: flex; align-items: center; gap: 6px; margin-left: auto; } |
| 193 | 193 | |
| 194 | .repo-layout { display: grid; gap: 16px; margin-top: 16px; align-items: start; } | |
| 195 | @media (min-width: 960px) { | |
| 196 | .repo-layout { grid-template-columns: minmax(0, 1fr) 280px; gap: 24px; } | |
| 197 | .repo-layout > aside { position: sticky; top: calc(var(--topbar-h) + 16px); } | |
| 198 | } | |
| 199 | ||
| 200 | 194 | .issue-head { margin: 20px 0 14px; } |
| 201 | 195 | .issue-head h1 { font-size: clamp(20px, 1rem + 1.4vw, 26px); letter-spacing: -0.025em; } |
| 202 | 196 | .issue-head h1 .number { font-weight: 400; color: var(--muted-fg); } |
| @@ -211,16 +205,6 @@ a.origin-chip:hover { border-color: var(--border-strong); color: var(--fg); } | ||
| 211 | 205 | .tree-total { margin: 6px 2px 0; text-align: right; } |
| 212 | 206 | .tok { white-space: nowrap; } |
| 213 | 207 | |
| 214 | /* The file's location stays on screen while its contents scroll past. Opaque | |
| 215 | on purpose: code sliding under a blur is noise, not depth. */ | |
| 216 | .path-head { | |
| 217 | position: sticky; top: calc(var(--topbar-h) - 1px); z-index: 6; | |
| 218 | display: flex; align-items: center; gap: 8px; flex-wrap: wrap; | |
| 219 | margin: 12px 0; padding: 8px 10px; | |
| 220 | background: var(--card); border: 1px solid var(--border); | |
| 221 | border-radius: var(--radius-sm); | |
| 222 | } | |
| 223 | ||
| 224 | 208 | .filters { display: flex; align-items: center; gap: 8px; flex-wrap: wrap; margin-bottom: 12px; } |
| 225 | 209 | .filters form { display: flex; align-items: center; gap: 8px; flex-wrap: wrap; } |
| 226 | 210 | .filters .search { min-width: 180px; flex: 1; max-width: 320px; } |
| @@ -433,7 +417,7 @@ form.inline { display: inline; margin-left: auto; } | ||
| 433 | 417 | *content*, so a column with a long unbreakable line pushes the page wider |
| 434 | 418 | than the phone rather than letting its own ellipsis do the work. A zero |
| 435 | 419 | min-width is what makes truncation inside a grid actually truncate. */ |
| 436 | .dash > *, .split > *, .repo-layout > * { min-width: 0; } | |
| 420 | .dash > *, .split > * { min-width: 0; } | |
| 437 | 421 | |
| 438 | 422 | /* The generic two-column page: content, then a sidebar that sticks. */ |
| 439 | 423 | .split { display: grid; gap: 16px; margin-top: 16px; align-items: start; } |
src/web/ui.ts +3 −2
| @@ -842,7 +842,8 @@ export interface CardOptions { | ||
| 842 | 842 | attrs?: Html; |
| 843 | 843 | } |
| 844 | 844 | |
| 845 | export function card(body: Html, o: CardOptions = {}): Html { | |
| 845 | /** A card is its body; pass `null` for a head-only bar (a file's location above its code). */ | |
| 846 | export function card(body: Html | null, o: CardOptions = {}): Html { | |
| 846 | 847 | return html`<div |
| 847 | 848 | class="card${o.extra ? ` ${o.extra}` : ""}" |
| 848 | 849 | ${o.id ? html`id="${o.id}"` : null} |
| @@ -850,7 +851,7 @@ export function card(body: Html, o: CardOptions = {}): Html { | ||
| 850 | 851 | ${o.tone && o.tone !== "default" ? html`data-tone="${o.tone}"` : null} |
| 851 | 852 | > |
| 852 | 853 | ${o.head ? html`<div class="card-head">${o.head}</div>` : null} |
| 853 | ${o.pad === false ? body : html`<div class="card-body">${body}</div>`} | |
| 854 | ${body === null ? null : o.pad === false ? body : html`<div class="card-body">${body}</div>`} | |
| 854 | 855 | ${o.foot ? html`<div class="card-foot">${o.foot}</div>` : null} |
| 855 | 856 | </div>`; |
| 856 | 857 | } |
test/web-code.test.ts +28
| @@ -180,6 +180,34 @@ describe("the code browser on the web", () => { | ||
| 180 | 180 | expect(html).toContain("the lamp"); |
| 181 | 181 | }); |
| 182 | 182 | |
| 183 | test("the path head and the code-plus-about layout wear the design system's classes", async () => { | |
| 184 | for (const path of [ | |
| 185 | "/alice/beacon/tree/main/src", | |
| 186 | "/alice/beacon/blob/main/src/lamp.ts", | |
| 187 | ]) { | |
| 188 | const html = await text(path); | |
| 189 | expect(html).not.toContain("path-head"); | |
| 190 | expect(html).not.toContain("repo-layout"); | |
| 191 | expect(html).toContain('class="card-head"'); | |
| 192 | expect(html).toContain('class="crumbs'); | |
| 193 | // The ref menu opens inside this card: it must not be clipped. | |
| 194 | expect(html).toMatch(/class="card card-(open|pin) mt"\s*>\s*<div class="card-head">\s*<[a-z]+[^>]*class="menu"/); | |
| 195 | } | |
| 196 | expect(await text("/alice/beacon/blob/main/src/lamp.ts")).toContain("card-pin"); | |
| 197 | }); | |
| 198 | ||
| 199 | test("a head-only card is a bar: no body, and its head drops the rule that would double the border", async () => { | |
| 200 | const { card } = await import("../src/web/ui.ts"); | |
| 201 | const { html: h } = await import("../src/web/html.ts"); | |
| 202 | const bar = String(card(null, { head: h`x`, extra: "card-open" })); | |
| 203 | expect(bar).toContain('class="card-head"'); | |
| 204 | expect(bar).not.toContain("card-body"); | |
| 205 | // The stylesheet half: the head that ends its card carries no bottom border. | |
| 206 | const { components } = await import("../src/web/style/components.ts"); | |
| 207 | const css = components.replace(/\s+/g, " "); | |
| 208 | expect(css).toContain(".card-head:last-child { border-bottom: 0; }"); | |
| 209 | }); | |
| 210 | ||
| 183 | 211 | /** Markup with its line breaks squeezed out, for asserting on structure. */ |
| 184 | 212 | const flat = (html: string): string => html.replace(/\s+/g, " "); |
| 185 | 213 |
new above
offline