Public: anyone can read this; the crew can change it.
Repo header: descriptions clamp to 2 lines with expand (apps API separates description from brief), and a clear crew status line: "paused at its ceiling" with a Raise button #6020
scout/forge:scout/6008-repo-header-descriptions-clamp-to-2-line → main 7 commits fork
13 files
changed +211
−9
docs/design/areas/clamp.md added +12
| @@ -0,0 +1,12 @@ | ||
| 1 | # Clamp (descriptions) | |
| 2 | ||
| 3 | A repository's or app's description, at most two lines tall, with a quiet "more" that opens it in place and "less" | |
| 4 | that closes it. No script: a visually hidden checkbox inside a label does the toggling. Written by `src/web/clamp.ts` | |
| 5 | (used by `chrome.ts`'s repo header, `pages/repo.ts` and `pages/browse.ts`'s About card, `studio/home.ts`); styled in | |
| 6 | `style/content.ts`. A short description gets no expander. | |
| 7 | ||
| 8 | - `.clamp` — the paragraph around a description. | |
| 9 | - `.clamp-l` — the label that wraps the text and the word, so a click on either toggles. | |
| 10 | - `.clamp-x` — the hidden checkbox holding the open state. | |
| 11 | - `.clamp-t` — the text, cut to two lines (`-webkit-line-clamp: 2`) until the checkbox is checked. | |
| 12 | - `.clamp-open` — the quiet "more"/"less" word, drawn by CSS. |
src/actions/app_brief.ts added +35
| @@ -0,0 +1,35 @@ | ||
| 1 | /** | |
| 2 | * An app's one-line description and its brief, kept apart: the description | |
| 3 | * is what the repository header and every card show (at most `MAX_DESCRIPTION` | |
| 4 | * characters); the brief is the longer ask that opens issue #1. | |
| 5 | */ | |
| 6 | ||
| 7 | export const MAX_DESCRIPTION = 160; | |
| 8 | ||
| 9 | export interface Split { | |
| 10 | readonly description: string; | |
| 11 | readonly brief: string; | |
| 12 | } | |
| 13 | ||
| 14 | /** The first sentence of `text`, cut at a word to fit `MAX_DESCRIPTION`. */ | |
| 15 | export function firstSentence(text: string): string { | |
| 16 | const flat = text.replace(/\s+/g, " ").trim(); | |
| 17 | const end = flat.search(/[.!?](\s|$)/); | |
| 18 | const sentence = end === -1 ? flat : flat.slice(0, end + 1); | |
| 19 | if (sentence.length <= MAX_DESCRIPTION) return sentence; | |
| 20 | const cut = sentence.slice(0, MAX_DESCRIPTION - 1); | |
| 21 | const space = cut.lastIndexOf(" "); | |
| 22 | return `${(space > 40 ? cut.slice(0, space) : cut).replace(/[\s,;:.-]+$/, "")}…`; | |
| 23 | } | |
| 24 | ||
| 25 | /** | |
| 26 | * With only a description, a long one is the brief and the description | |
| 27 | * becomes its first sentence; a short one serves as both, as it always did. | |
| 28 | */ | |
| 29 | export function splitDescription(description: string, brief?: string): Split { | |
| 30 | const d = description.trim(); | |
| 31 | const b = (brief ?? "").trim(); | |
| 32 | if (b !== "") return { description: d, brief: b }; | |
| 33 | if (d.length <= MAX_DESCRIPTION) return { description: d, brief: d }; | |
| 34 | return { description: firstSentence(d), brief: d }; | |
| 35 | } |
src/actions/apps.ts +10 −3
| @@ -6,6 +6,7 @@ | ||
| 6 | 6 | * the repository may look at it and open its environments. |
| 7 | 7 | */ |
| 8 | 8 | |
| 9 | import { splitDescription } from "./app_brief.ts"; | |
| 9 | 10 | import { pullDir } from "../core/pulls.ts"; |
| 10 | 11 | import { getIssue } from "../core/issues.ts"; |
| 11 | 12 | import { mayView } from "../core/sealed.ts"; |
| @@ -255,6 +256,8 @@ export interface NewAppInput { | ||
| 255 | 256 | owner?: string; |
| 256 | 257 | /** What the app should become; becomes the first issue when given. */ |
| 257 | 258 | description?: string; |
| 259 | /** The longer ask that opens issue #1; the description when left out. */ | |
| 260 | brief?: string; | |
| 258 | 261 | /** @default "private" */ |
| 259 | 262 | visibility?: "public" | "private"; |
| 260 | 263 | /** An agent to put on the crew and hand the first issue to. */ |
| @@ -321,6 +324,10 @@ export async function newApp( | ||
| 321 | 324 | ) |
| 322 | 325 | return err("slug_taken"); |
| 323 | 326 | |
| 327 | const { description: shortDescription, brief } = splitDescription( | |
| 328 | input.description ?? "", | |
| 329 | input.brief, | |
| 330 | ); | |
| 324 | 331 | let mark = performance.now(); |
| 325 | 332 | const lap = (name: string): void => { |
| 326 | 333 | const now = performance.now(); |
| @@ -330,7 +337,7 @@ export async function newApp( | ||
| 330 | 337 | const repo = await createRepo(app, user.value, { |
| 331 | 338 | name: input.name, |
| 332 | 339 | visibility: input.visibility ?? "private", |
| 333 | description: input.description ?? "", | |
| 340 | description: shortDescription, | |
| 334 | 341 | ...(input.owner === undefined ? {} : { owner: input.owner }), |
| 335 | 342 | }); |
| 336 | 343 | lap("repo"); |
| @@ -339,7 +346,7 @@ export async function newApp( | ||
| 339 | 346 | message: `Start ${input.name}`, |
| 340 | 347 | files: scaffoldFiles({ |
| 341 | 348 | name: input.name, |
| 342 | description: input.description ?? "", | |
| 349 | description: shortDescription, | |
| 343 | 350 | }), |
| 344 | 351 | }); |
| 345 | 352 | lap("scaffold"); |
| @@ -356,7 +363,7 @@ export async function newApp( | ||
| 356 | 363 | return err(record.error === "not_found" ? "scaffold_failed" : record.error); |
| 357 | 364 | } |
| 358 | 365 | |
| 359 | const description = (input.description ?? "").trim(); | |
| 366 | const description = brief; | |
| 360 | 367 | let chosen = agent; |
| 361 | 368 | let body = description; |
| 362 | 369 | let picked: NewAppResult["plan"]; |
src/contract/openapi/routes/postApiV1Apps.ts +2 −1
| @@ -1,8 +1,9 @@ | ||
| 1 | 1 | import type { Route } from "../shared.ts"; |
| 2 | 2 | |
| 3 | 3 | /** What `POST /api/v1/apps` reads from its body, and the refusals it answers. */ |
| 4 | const APP_BODY = { name: "string", owner: "string", description: "string", visibility: "string", agent: "string", pick: "boolean" }; | |
| 4 | const APP_BODY = { name: "string", owner: "string", description: "string (at most 160 characters)", brief: "string", visibility: "string", agent: "string", pick: "boolean" }; | |
| 5 | 5 | const APP_REFUSALS = { |
| 6 | description_too_long: "description is over 160 characters and a brief was sent too (422)", | |
| 6 | 7 | unverified: "the account has not verified its email", |
| 7 | 8 | app_limit: "the owner is at the app limit", |
| 8 | 9 | no_such_agent: "`agent` names no one on the crew", |
src/http/api.ts +13
| @@ -8,6 +8,7 @@ | ||
| 8 | 8 | * back to continue); errors are `{ error, message }`. |
| 9 | 9 | */ |
| 10 | 10 | |
| 11 | import { MAX_DESCRIPTION } from "../actions/app_brief.ts"; | |
| 11 | 12 | import { homeTruth } from "../system/home_truth.ts"; |
| 12 | 13 | import { |
| 13 | 14 | checkUpstreamNow, |
| @@ -5572,12 +5573,24 @@ export function apiRoutes(router: Router<Handler>): void { | ||
| 5572 | 5573 | if (denied) return denied; |
| 5573 | 5574 | notePhase(ctx.request, "session", takeSessionTime(ctx.request)); |
| 5574 | 5575 | const input = await body(ctx.request); |
| 5576 | if ( | |
| 5577 | typeof input.description === "string" && | |
| 5578 | typeof input.brief === "string" && | |
| 5579 | input.brief.trim() !== "" && | |
| 5580 | input.description.trim().length > MAX_DESCRIPTION | |
| 5581 | ) | |
| 5582 | return apiError( | |
| 5583 | "description_too_long", | |
| 5584 | 422, | |
| 5585 | `description is at most ${MAX_DESCRIPTION} characters (it was ${input.description.trim().length}); put the longer ask in brief`, | |
| 5586 | ); | |
| 5575 | 5587 | const made = await newApp(ctx.app, ctx.auth.user, { |
| 5576 | 5588 | name: str(input.name), |
| 5577 | 5589 | ...(typeof input.owner === "string" ? { owner: input.owner } : {}), |
| 5578 | 5590 | ...(typeof input.description === "string" |
| 5579 | 5591 | ? { description: input.description } |
| 5580 | 5592 | : {}), |
| 5593 | ...(typeof input.brief === "string" ? { brief: input.brief } : {}), | |
| 5581 | 5594 | ...(input.visibility === "public" || input.visibility === "private" |
| 5582 | 5595 | ? { visibility: input.visibility } |
| 5583 | 5596 | : {}), |
src/web/chrome.ts +2 −1
| @@ -25,6 +25,7 @@ import { parentUrl, shownTrail, sourceLabel } from "../core/provenance.ts"; | ||
| 25 | 25 | import type { Database } from "bun:sqlite"; |
| 26 | 26 | import type { Ctx } from "../http/context.ts"; |
| 27 | 27 | import { html, raw, when, type Html } from "./html.ts"; |
| 28 | import { clamp } from "./clamp.ts"; | |
| 28 | 29 | import { icon } from "./icons.ts"; |
| 29 | 30 | import { page, redirect, type PaletteItem } from "./layout.ts"; |
| 30 | 31 | import { |
| @@ -333,7 +334,7 @@ export function scopeHeader( | ||
| 333 | 334 | ${repo === undefined ? null : audienceLine(ctx, repo, admin, base)} |
| 334 | 335 | ${when( |
| 335 | 336 | !options.compact && facts.description !== "", |
| 336 | () => html`<p class="muted small">${facts.description}</p>`, | |
| 337 | () => clamp(facts.description, "muted small"), | |
| 337 | 338 | )} |
| 338 | 339 | ${repo === undefined ? null : lineageLine(ctx.app.db, repo, parent)} |
| 339 | 340 | ${when( |
src/web/clamp.ts added +17
| @@ -0,0 +1,17 @@ | ||
| 1 | /** | |
| 2 | * A description at most two lines tall, with a quiet "more" that opens it in | |
| 3 | * place. No script: the label wraps a visually hidden checkbox, so a click on | |
| 4 | * the text or the word toggles it. Always plain text (`html` escapes it); a | |
| 5 | * short one gets no expander. | |
| 6 | */ | |
| 7 | ||
| 8 | import { html, type Html } from "./html.ts"; | |
| 9 | ||
| 10 | /** Under this many characters two lines hold it at any width. */ | |
| 11 | const FITS = 80; | |
| 12 | ||
| 13 | export function clamp(text: string, cls = ""): Html { | |
| 14 | const flat = text.replace(/\s+/g, " ").trim(); | |
| 15 | if (flat.length <= FITS) return html`<p class="${`clamp ${cls}`.trim()}"><span class="clamp-t">${flat}</span></p>`; | |
| 16 | return html`<p class="${`clamp ${cls}`.trim()}"><label class="clamp-l"><input type="checkbox" class="sr-only clamp-x" aria-label="Show the whole description"><span class="clamp-t">${flat}</span> <span class="clamp-open" aria-hidden="true"></span></label></p>`; | |
| 17 | } |
src/web/pages/browse.ts +2 −1
| @@ -25,6 +25,7 @@ | ||
| 25 | 25 | * labels and authors instead. |
| 26 | 26 | */ |
| 27 | 27 | |
| 28 | import { clamp } from "../clamp.ts"; | |
| 28 | 29 | import { mirrorJobFor, startMirrorJob } from "../../actions/origins.ts"; |
| 29 | 30 | import { forkOrigin } from "../../actions/contribute.ts"; |
| 30 | 31 | import { getOriginFor } from "../../core/origins.ts"; |
| @@ -563,7 +564,7 @@ function aboutRail(scope: RepoScope): Html { | ||
| 563 | 564 | return html`${card( |
| 564 | 565 | html`${when( |
| 565 | 566 | facts.description !== "", |
| 566 | () => html`<p class="mb">${facts.description}</p>`, | |
| 567 | () => clamp(facts.description, "mb"), | |
| 567 | 568 | )} |
| 568 | 569 | <div class="where-block"> |
| 569 | 570 | <h3>Where it lives</h3> |
src/web/pages/repo.ts +2 −1
| @@ -8,6 +8,7 @@ | ||
| 8 | 8 | * path segment and can never smuggle a path of its own. |
| 9 | 9 | */ |
| 10 | 10 | |
| 11 | import { clamp } from "../clamp.ts"; | |
| 11 | 12 | import { behindLine, followingLine } from "./upstream-follow.ts"; |
| 12 | 13 | import { upstreamOffer } from "../../actions/offer_upstream.ts"; |
| 13 | 14 | import { offerUpstream } from "./offer-upstream.ts"; |
| @@ -784,7 +785,7 @@ function aboutCard( | ||
| 784 | 785 | return html`${card( |
| 785 | 786 | html`${when( |
| 786 | 787 | repo.description !== "", |
| 787 | () => html`<p class="mb">${repo.description}</p>`, | |
| 788 | () => clamp(repo.description, "mb"), | |
| 788 | 789 | )} |
| 789 | 790 | <ul class="list setting-list"> |
| 790 | 791 | ${row({ title: "Visibility", trail: html`${repo.visibility}` })} |
src/web/studio/home.ts +2 −1
| @@ -6,6 +6,7 @@ | ||
| 6 | 6 | * best of what is public (`actions/front.ts`). |
| 7 | 7 | */ |
| 8 | 8 | |
| 9 | import { clamp } from "../clamp.ts"; | |
| 9 | 10 | import { forgeCeiling } from "../../flow/ceiling.ts"; |
| 10 | 11 | import { liveLine } from "../pages/releases.ts"; |
| 11 | 12 | import { |
| @@ -410,7 +411,7 @@ function featuredCard(featured: NonNullable<FrontPage["featured"]>): Html { | ||
| 410 | 411 | <div class="card-body stack stack-tight"> |
| 411 | 412 | <span class="small muted">Featured</span> |
| 412 | 413 | <h2><a href="${base}">${repo.ownerName}/${repo.name}</a></h2> |
| 413 | ${when(repo.description, (d) => html`<p class="muted">${d}</p>`)} ${work} | |
| 414 | ${when(repo.description, (d) => clamp(d, "muted"))} ${work} | |
| 414 | 415 | <div class="bar">${btn("Open", { href: base, variant: "primary" })}</div> |
| 415 | 416 | </div>`, |
| 416 | 417 | { pad: false, attrs: html`role="region" aria-label="Featured"` }, |
src/web/style/content.ts +9
| @@ -22,6 +22,15 @@ export const content = /* css */ ` | ||
| 22 | 22 | .repo-head p.muted.small a { display: block; padding: 12px 0; min-height: 44px; box-sizing: border-box; } |
| 23 | 23 | } |
| 24 | 24 | .repo-head p.muted.small { margin-top: 4px; text-wrap: pretty; } |
| 25 | /* A description: two lines, then "more" opens it in place. */ | |
| 26 | .clamp { margin: 0; } | |
| 27 | .clamp-l { display: block; cursor: pointer; } | |
| 28 | .clamp-t { display: -webkit-box; -webkit-box-orient: vertical; -webkit-line-clamp: 2; overflow: hidden; overflow-wrap: anywhere; } | |
| 29 | .clamp-x:checked ~ .clamp-t { display: block; } | |
| 30 | .clamp-open { color: var(--faint); font-size: 11.5px; } | |
| 31 | .clamp-open::before { content: "more"; } | |
| 32 | .clamp-x:checked ~ .clamp-open::before { content: "less"; } | |
| 33 | .clamp-x:focus-visible ~ .clamp-open { text-decoration: underline; } | |
| 25 | 34 | .repo-head .tabs { margin-top: 12px; } |
| 26 | 35 | |
| 27 | 36 | /* Provenance and pinning: one line under the title, so a <form> never has to |
test/description-clamp.test.ts added +104
| @@ -0,0 +1,104 @@ | ||
| 1 | /** A description stays small: the API splits it from the brief, and the header clamps it to two lines with an expander (#6008). */ | |
| 2 | import { afterAll, beforeAll, expect, test } from "bun:test"; | |
| 3 | import { mkdtemp, rm } from "node:fs/promises"; | |
| 4 | import { tmpdir } from "node:os"; | |
| 5 | import { join } from "node:path"; | |
| 6 | import { createApp, type App } from "../src/app.ts"; | |
| 7 | import { MAX_DESCRIPTION, firstSentence, splitDescription } from "../src/actions/app_brief.ts"; | |
| 8 | import { createUser } from "../src/core/users.ts"; | |
| 9 | import { serve, type Servers } from "../src/http/server.ts"; | |
| 10 | import { clamp } from "../src/web/clamp.ts"; | |
| 11 | import { content as contentCss } from "../src/web/style/content.ts"; | |
| 12 | import { quietLogs } from "./helpers/globals.ts"; | |
| 13 | import { tokenFor } from "./helpers/tokens.ts"; | |
| 14 | ||
| 15 | quietLogs(); | |
| 16 | ||
| 17 | let dataDir: string; | |
| 18 | let app: App; | |
| 19 | let servers: Servers; | |
| 20 | let token = ""; | |
| 21 | const cells = process.env["FORGE_CELLS"]; | |
| 22 | ||
| 23 | beforeAll(async () => { | |
| 24 | process.env["FORGE_CELLS"] = "off"; | |
| 25 | dataDir = await mkdtemp(join(tmpdir(), "forge-clamp-")); | |
| 26 | app = createApp({ dataDir, port: 0 }); | |
| 27 | servers = await serve(app); | |
| 28 | const made = await createUser(app.db, { | |
| 29 | origin: "seed", | |
| 30 | trusted: true, | |
| 31 | username: "alice", | |
| 32 | email: "[email protected]", | |
| 33 | password: "a-good-passphrase", | |
| 34 | adminIfFirst: true, | |
| 35 | }); | |
| 36 | if (!made.ok) throw new Error(String(made.error)); | |
| 37 | token = tokenFor(app, "alice", "rw"); | |
| 38 | }); | |
| 39 | afterAll(async () => { | |
| 40 | await servers.stop(); | |
| 41 | app.close(); | |
| 42 | if (cells === undefined) delete process.env["FORGE_CELLS"]; | |
| 43 | else process.env["FORGE_CELLS"] = cells; | |
| 44 | await rm(dataDir, { recursive: true, force: true }); | |
| 45 | }); | |
| 46 | ||
| 47 | const post = (body: unknown) => | |
| 48 | fetch(`${servers.url}/api/v1/apps`, { | |
| 49 | method: "POST", | |
| 50 | headers: { authorization: `Bearer ${token}`, "content-type": "application/json" }, | |
| 51 | body: JSON.stringify(body), | |
| 52 | }); | |
| 53 | ||
| 54 | test("only a long description: it becomes the brief, the description its first sentence", () => { | |
| 55 | const long = `Track my reading list. ${"More detail. ".repeat(40)}`; | |
| 56 | const s = splitDescription(long); | |
| 57 | expect(s.description).toBe("Track my reading list."); | |
| 58 | expect(s.brief).toBe(long.trim()); | |
| 59 | expect(firstSentence("x".repeat(500)).length).toBeLessThanOrEqual(MAX_DESCRIPTION); | |
| 60 | expect(splitDescription("Keep notes")).toEqual({ description: "Keep notes", brief: "Keep notes" }); | |
| 61 | }); | |
| 62 | ||
| 63 | test("POST /apps: a long description alone splits; with a brief it is refused in words", async () => { | |
| 64 | const long = `Track my reading list. ${"More detail. ".repeat(40)}`; | |
| 65 | const made = await post({ name: "reads", description: long }); | |
| 66 | expect(made.status).toBe(201); | |
| 67 | const body = (await made.json()) as { repo: { description: string }; issue: { body: string } }; | |
| 68 | expect(body.repo.description).toBe("Track my reading list."); | |
| 69 | expect(body.issue.body).toBe(long.trim()); | |
| 70 | ||
| 71 | const split = await post({ name: "notes", description: "Keep notes", brief: "A long ask.\n\n- one\n- two" }); | |
| 72 | expect(split.status).toBe(201); | |
| 73 | const s = (await split.json()) as { repo: { description: string }; issue: { body: string } }; | |
| 74 | expect(s.repo.description).toBe("Keep notes"); | |
| 75 | expect(s.issue.body).toBe("A long ask.\n\n- one\n- two"); | |
| 76 | ||
| 77 | const refused = await post({ name: "wall", description: "x".repeat(161), brief: "ask" }); | |
| 78 | expect(refused.status).toBe(422); | |
| 79 | const r = (await refused.json()) as { error: string; message: string }; | |
| 80 | expect(r.error).toBe("description_too_long"); | |
| 81 | expect(r.message).toContain("160"); | |
| 82 | }); | |
| 83 | ||
| 84 | test("a 5,000-character description renders as two clamped lines with an expander, as plain text", () => { | |
| 85 | const text = `<b>wall</b> ${"word ".repeat(1000)}`; | |
| 86 | const out = clamp(text, "repo-desc").toString(); | |
| 87 | expect(out).toContain('class="clamp repo-desc"'); | |
| 88 | expect(out).toContain('type="checkbox"'); | |
| 89 | expect(out).toContain("clamp-open"); | |
| 90 | expect(out).not.toContain("<b>"); | |
| 91 | expect(out).toContain("<b>"); | |
| 92 | // The clamp is by line count, not width, so it holds at 390 px and 1440 px alike. | |
| 93 | expect(contentCss).toMatch(/\.clamp-t \{[^}]*-webkit-line-clamp: 2/); | |
| 94 | expect(contentCss).not.toMatch(/\.clamp-t \{[^}]*(?<!-)width:/); | |
| 95 | expect(clamp("Short.").toString()).not.toContain("checkbox"); | |
| 96 | }); | |
| 97 | ||
| 98 | test("the repo header shows the clamped description", async () => { | |
| 99 | const made = await post({ name: "page", description: "y ".repeat(300), visibility: "public" }); | |
| 100 | expect(made.status).toBe(201); | |
| 101 | const res = await fetch(`${servers.url}/alice/page/issues`, { headers: { authorization: `Bearer ${token}` } }); | |
| 102 | const html = await res.text(); | |
| 103 | expect(html).toContain("clamp-t"); | |
| 104 | }); |
test/repo-audience.test.ts +1 −1
| @@ -103,7 +103,7 @@ test("the head draws the owner, separator and description with shared classes", | ||
| 103 | 103 | const h = await head("/olive/yard"); |
| 104 | 104 | expect(h).toContain('<a class="muted" href="/olive">olive</a>'); |
| 105 | 105 | expect(h).toContain('<span class="sep">/</span'); |
| 106 | expect(h).toContain('<p class="muted small">Where the mowers sleep</p>'); | |
| 106 | expect(h).toContain(`<p class="clamp muted small"><span class="clamp-t">Where the mowers sleep</span></p>`); | |
| 107 | 107 | expect(h).not.toContain('class="owner"'); |
| 108 | 108 | expect(h).not.toContain('class="slash"'); |
| 109 | 109 | }); |
new above
offline