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

Parked opened this in answer to
Closed without merging

scout/forge:scout/6008-repo-header-descriptions-clamp-to-2-line → main 7 commits fork

  • Closed without merging. Nothing was applied to main.

Review

Sign in to review this change.
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 @@
66 * the repository may look at it and open its environments.
77 */
88
9 import { splitDescription } from "./app_brief.ts";
910 import { pullDir } from "../core/pulls.ts";
1011 import { getIssue } from "../core/issues.ts";
1112 import { mayView } from "../core/sealed.ts";
@@ -255,6 +256,8 @@ export interface NewAppInput {
255256 owner?: string;
256257 /** What the app should become; becomes the first issue when given. */
257258 description?: string;
259 /** The longer ask that opens issue #1; the description when left out. */
260 brief?: string;
258261 /** @default "private" */
259262 visibility?: "public" | "private";
260263 /** An agent to put on the crew and hand the first issue to. */
@@ -321,6 +324,10 @@ export async function newApp(
321324 )
322325 return err("slug_taken");
323326
327 const { description: shortDescription, brief } = splitDescription(
328 input.description ?? "",
329 input.brief,
330 );
324331 let mark = performance.now();
325332 const lap = (name: string): void => {
326333 const now = performance.now();
@@ -330,7 +337,7 @@ export async function newApp(
330337 const repo = await createRepo(app, user.value, {
331338 name: input.name,
332339 visibility: input.visibility ?? "private",
333 description: input.description ?? "",
340 description: shortDescription,
334341 ...(input.owner === undefined ? {} : { owner: input.owner }),
335342 });
336343 lap("repo");
@@ -339,7 +346,7 @@ export async function newApp(
339346 message: `Start ${input.name}`,
340347 files: scaffoldFiles({
341348 name: input.name,
342 description: input.description ?? "",
349 description: shortDescription,
343350 }),
344351 });
345352 lap("scaffold");
@@ -356,7 +363,7 @@ export async function newApp(
356363 return err(record.error === "not_found" ? "scaffold_failed" : record.error);
357364 }
358365
359 const description = (input.description ?? "").trim();
366 const description = brief;
360367 let chosen = agent;
361368 let body = description;
362369 let picked: NewAppResult["plan"];
src/contract/openapi/routes/postApiV1Apps.ts +2 −1
@@ -1,8 +1,9 @@
11 import type { Route } from "../shared.ts";
22
33 /** 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" };
55 const APP_REFUSALS = {
6 description_too_long: "description is over 160 characters and a brief was sent too (422)",
67 unverified: "the account has not verified its email",
78 app_limit: "the owner is at the app limit",
89 no_such_agent: "`agent` names no one on the crew",
src/http/api.ts +13
@@ -8,6 +8,7 @@
88 * back to continue); errors are `{ error, message }`.
99 */
1010
11 import { MAX_DESCRIPTION } from "../actions/app_brief.ts";
1112 import { homeTruth } from "../system/home_truth.ts";
1213 import {
1314 checkUpstreamNow,
@@ -5572,12 +5573,24 @@ export function apiRoutes(router: Router<Handler>): void {
55725573 if (denied) return denied;
55735574 notePhase(ctx.request, "session", takeSessionTime(ctx.request));
55745575 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 );
55755587 const made = await newApp(ctx.app, ctx.auth.user, {
55765588 name: str(input.name),
55775589 ...(typeof input.owner === "string" ? { owner: input.owner } : {}),
55785590 ...(typeof input.description === "string"
55795591 ? { description: input.description }
55805592 : {}),
5593 ...(typeof input.brief === "string" ? { brief: input.brief } : {}),
55815594 ...(input.visibility === "public" || input.visibility === "private"
55825595 ? { visibility: input.visibility }
55835596 : {}),
src/web/chrome.ts +2 −1
@@ -25,6 +25,7 @@ import { parentUrl, shownTrail, sourceLabel } from "../core/provenance.ts";
2525 import type { Database } from "bun:sqlite";
2626 import type { Ctx } from "../http/context.ts";
2727 import { html, raw, when, type Html } from "./html.ts";
28 import { clamp } from "./clamp.ts";
2829 import { icon } from "./icons.ts";
2930 import { page, redirect, type PaletteItem } from "./layout.ts";
3031 import {
@@ -333,7 +334,7 @@ export function scopeHeader(
333334 ${repo === undefined ? null : audienceLine(ctx, repo, admin, base)}
334335 ${when(
335336 !options.compact && facts.description !== "",
336 () => html`<p class="muted small">${facts.description}</p>`,
337 () => clamp(facts.description, "muted small"),
337338 )}
338339 ${repo === undefined ? null : lineageLine(ctx.app.db, repo, parent)}
339340 ${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 @@
2525 * labels and authors instead.
2626 */
2727
28 import { clamp } from "../clamp.ts";
2829 import { mirrorJobFor, startMirrorJob } from "../../actions/origins.ts";
2930 import { forkOrigin } from "../../actions/contribute.ts";
3031 import { getOriginFor } from "../../core/origins.ts";
@@ -563,7 +564,7 @@ function aboutRail(scope: RepoScope): Html {
563564 return html`${card(
564565 html`${when(
565566 facts.description !== "",
566 () => html`<p class="mb">${facts.description}</p>`,
567 () => clamp(facts.description, "mb"),
567568 )}
568569 <div class="where-block">
569570 <h3>Where it lives</h3>
src/web/pages/repo.ts +2 −1
@@ -8,6 +8,7 @@
88 * path segment and can never smuggle a path of its own.
99 */
1010
11 import { clamp } from "../clamp.ts";
1112 import { behindLine, followingLine } from "./upstream-follow.ts";
1213 import { upstreamOffer } from "../../actions/offer_upstream.ts";
1314 import { offerUpstream } from "./offer-upstream.ts";
@@ -784,7 +785,7 @@ function aboutCard(
784785 return html`${card(
785786 html`${when(
786787 repo.description !== "",
787 () => html`<p class="mb">${repo.description}</p>`,
788 () => clamp(repo.description, "mb"),
788789 )}
789790 <ul class="list setting-list">
790791 ${row({ title: "Visibility", trail: html`${repo.visibility}` })}
src/web/studio/home.ts +2 −1
@@ -6,6 +6,7 @@
66 * best of what is public (`actions/front.ts`).
77 */
88
9 import { clamp } from "../clamp.ts";
910 import { forgeCeiling } from "../../flow/ceiling.ts";
1011 import { liveLine } from "../pages/releases.ts";
1112 import {
@@ -410,7 +411,7 @@ function featuredCard(featured: NonNullable<FrontPage["featured"]>): Html {
410411 <div class="card-body stack stack-tight">
411412 <span class="small muted">Featured</span>
412413 <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}
414415 <div class="bar">${btn("Open", { href: base, variant: "primary" })}</div>
415416 </div>`,
416417 { pad: false, attrs: html`role="region" aria-label="Featured"` },
src/web/style/content.ts +9
@@ -22,6 +22,15 @@ export const content = /* css */ `
2222 .repo-head p.muted.small a { display: block; padding: 12px 0; min-height: 44px; box-sizing: border-box; }
2323 }
2424 .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; }
2534 .repo-head .tabs { margin-top: 12px; }
2635
2736 /* 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("&lt;b&gt;");
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",
103103 const h = await head("/olive/yard");
104104 expect(h).toContain('<a class="muted" href="/olive">olive</a>');
105105 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>`);
107107 expect(h).not.toContain('class="owner"');
108108 expect(h).not.toContain('class="slash"');
109109 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs