Public: anyone can read this; the crew can change it.

/explore says how many results the filters match and offers one link that clears them #12343

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

scout/forge:scout/12316-explore-says-how-many-results-the-filter → main 10 commits fork 5 threads · 5 unresolved

  • Merged. scout/12316-explore-says-how-many-results-the-filter was merged into main as 548b07b.

Review

Sign in to review this change.
8 files changed +98 −19
docs/design/attention-budget.json +3 −2
@@ -185,13 +185,14 @@
185185 "note": "Measured on the test forge's empty state with the machine reading replaced by an empty one and the two cell-cap sentences fixed (the live page's counts depend on the host's cores, disks, processes and cgroups); nothing seeded or waited for. Blocks 65 -> 67 (#11805): the off-site backup section's heading and one-sentence state stay on first view so a red lane is seen without a click; its rows sit behind the disclosure. Blocks 67 -> 69 (#12010): the database size section's heading and its one-sentence state (the file's size and growth, a badge when either is worth a look) stay on first view, as the off-site lane's do; its fact rows and the table of the ten largest tables and indexes sit behind the disclosure. Words +22, blocks +1 (#12092): the footprint section's heading and its one-sentence state (on an empty forge, not read yet and the memory budget) stay on first view; the measured facts and the optional parts sit behind the disclosure."
186186 },
187187 "explore": {
188 "note": "Measured as an admin: the unfiltered count reads 'N apps, forges and people' (+3 words over 'N results'); a guest reads two fewer.",
188189 "390": {
189 "words": 39,
190 "words": 42,
190191 "blocks": 9,
191192 "colours": 0
192193 },
193194 "1280": {
194 "words": 39,
195 "words": 42,
195196 "blocks": 9,
196197 "colours": 0
197198 }
src/actions/explore.ts +18 −7
@@ -416,10 +416,13 @@ const NOUNS = {
416416 app: ["app", "apps"],
417417 person: ["person", "people"],
418418 forge: ["forge", "forges"],
419 all: ["result", "results"],
419 all: ["app or person", "apps and people"],
420420 } as const;
421421
422 /** True when the line narrows the list; the sort only orders it. */
422 /**
423 * True when the line changes the list or its order: a filter or a sort is a setting to undo.
424 * One rule for the page, the terminal and MCP.
425 */
423426 export const exploreFiltered = (q: ExploreQuery): boolean =>
424427 q.kind !== "all" ||
425428 q.text !== "" ||
@@ -428,12 +431,20 @@ export const exploreFiltered = (q: ExploreQuery): boolean =>
428431 q.owner !== undefined ||
429432 q.forks !== undefined ||
430433 q.ships !== undefined ||
431 q.live === true;
434 q.live === true ||
435 q.sort !== "score";
432436
433 /** How much a filter leaves, in words: "2 apps", "1 app", "No apps match". One sentence for the page and the terminal. */
434 export function exploreCount(query: ExploreQuery, total: number): string {
435 const noun = NOUNS[query.kind];
436 return total === 0 ? `No ${noun[1]} match` : `${total.toLocaleString("en-US")} ${noun[total === 1 ? 0 : 1]}`;
437 /**
438 * How much a filter leaves, in words: "2 apps", "1 app", "No apps match",
439 * "Nothing matches". One sentence for the page and the terminal. Only the
440 * kinds the viewer can see are named: forges are a site admin's.
441 */
442 export function exploreCount(query: ExploreQuery, total: number, seesForges = false): string {
443 if (total === 0) return query.kind === "all" ? "Nothing matches" : `No ${NOUNS[query.kind][1]} match`;
444 if (query.kind === "all" && seesForges) {
outdated

Singular missing: total===1 with seesForges returns "1 apps, forges and people". Use a singular form when total is 1 and add tests for it.

445 return total === 1 ? "1 app, forge or person" : `${total.toLocaleString("en-US")} apps, forges and people`;
446 }
447 return `${total.toLocaleString("en-US")} ${NOUNS[query.kind][total === 1 ? 0 : 1]}`;
437448 }
438449
439450 /**
src/http/mcp/reads.ts +1 −1
@@ -36,7 +36,7 @@ export async function exploreRun(ctx: Ctx, user: User | undefined, args: Args):
3636 return good({
3737 query: exploreLine(query),
3838 total: page.total,
39 line: exploreCount(query, page.total),
39 line: exploreCount(query, page.total, user?.isAdmin === true),
4040 ...(exploreFiltered(query) ? { clear: { tool: "explore", arguments: {} } } : {}),
4141 items: rowsWithWhy(ctx.app, query, page.items),
4242 next_cursor: page.nextCursor,
src/tui/screens/dashboard.ts +1 −1
@@ -1282,7 +1282,7 @@ export function dashboardScreen(f: Session, ctx: Ctx): Screen {
12821282 const readAs =
12831283 read === undefined
12841284 ? undefined
1285 : `Read as: ${exploreLine(read.query) || "everything"}${explored === undefined ? "" : ` · ${exploreCount(read.query, explored.total)}${exploreFiltered(read.query) ? " · Esc clears" : ""}`}${mend === undefined ? "" : ` · Did you mean ${mend.line}?`}${note === "" ? "" : ` · ${note}`}`;
1285 : `Read as: ${exploreLine(read.query) || "everything"}${explored === undefined ? "" : ` · ${exploreCount(read.query, explored.total, f.user?.isAdmin === true)}${exploreFiltered(read.query) ? " · Esc clears" : ""}`}${mend === undefined ? "" : ` · Did you mean ${mend.line}?`}${note === "" ? "" : ` · ${note}`}`;

New admin-dependent count in the terminal has no test; add one for admin vs guest and for the sort-only Esc clears.

12861286 const reduced = readAs ?? (f.user?.isAdmin === true ? protectionNotice() : undefined);
12871287 const [box, warn, list] = split(
12881288 main,
src/web/studio/explore.ts +4 −4
@@ -180,14 +180,14 @@ function removable(query: ExploreQuery): { term: string; without: ExploreQuery }
180180 * moves. Unfiltered and empty it is silent: "Nothing public yet" says it.
181181 * A miss names each filter that can be dropped, beside Clear filters.
182182 */
183 function countLine(query: ExploreQuery, total: number): Html {
183 function countLine(query: ExploreQuery, total: number, seesForges: boolean): Html {
184184 const on = exploreFiltered(query);
185185 if (total === 0 && !on) return html``;
186186 const drops =
187 total === 0
187 total === 0 && on
188188 ? removable(query).map((t) => html` · <a href="${href(t.without)}">Drop ${shorten(t.term)}</a>`)
189189 : [];
190 return html`<span class="muted" role="status" data-hits>${exploreCount(query, total)}${drops}${
190 return html`<span class="muted" role="status" data-hits>${exploreCount(query, total, seesForges)}${drops}${
191191 on ? html` · <a href="/explore" data-clear-filters>Clear filters</a>` : html``
192192 }</span>`;
193193 }
@@ -289,7 +289,7 @@ export async function explorePage(ctx: Ctx): Promise<Response> {
289289 aria-pressed="${query.archived ? "true" : "false"}"
290290 >Show archived</a
291291 >
292 ${countLine(query, page0?.total ?? 0)}
292 ${countLine(query, page0?.total ?? 0, ctx.auth.user?.isAdmin === true)}
293293 </div>
294294 ${rows.length === 0
295295 ? emptyState(ctx, query)
test/explore-count.test.ts +27 −2
@@ -42,9 +42,9 @@ afterAll(async () => {
4242 const get = async (path: string) => (await fetch(`${servers.url}${path}`)).text();
4343 const count = (html: string) => html.match(/data-hits[^>]*>([^<]*)/)?.[1]?.trim();
4444
45 test("no filter: a count of results and no clear link", async () => {
45 test("no filter: a guest is told of the kinds they can see, apps and people, and no clear link", async () => {
4646 const html = await get("/explore");
47 expect(count(html)).toBe("66 results");
47 expect(count(html)).toBe("66 apps and people");
4848 expect(html).not.toContain("data-clear-filters");
4949 });
5050
@@ -80,3 +80,28 @@ test("the count is the whole filtered list on a page after a cursor", async () =
8080 expect(count(second)).toMatch(/^62 apps/);
8181 expect(second).toContain("data-clear-filters");
8282 });
83
84 test("a sort alone still offers Clear filters to the bare page", async () => {
85 const html = await get("/explore?q=sort:forks");
86 expect(html).toMatch(/<a href="\/explore" data-clear-filters>Clear filters<\/a>/);

Add the empty-case wording assertion and a guest-visible-kinds assertion; the miss sentence's new wording is untested.

87 });
88
89 test("the empty sentence is plain words, and a guest is never told of forges", async () => {
90 const html = await get("/explore?q=zzzzqqq");
91 expect(count(html)).toMatch(/^Nothing matches/);
92 expect(html).not.toMatch(/data-hits[^>]*>[^<]*forges/);
93 });
94
95 test("an admin's page names forges in the count; a member's does not", async () => {
96 const made = await createUser(app.db, { origin: "seed", trusted: true, isAdmin: true, username: "ada", email: "[email protected]", password: "a-good-passphrase" });
97 if (!made.ok) throw new Error(made.error);
98 const signin = await fetch(`${servers.url}/signin`, {
99 method: "POST", headers: { origin: servers.url },
100 body: new URLSearchParams({ username: "ada", password: "a-good-passphrase" }), redirect: "manual",
101 });
102 const cookie = (signin.headers.get("set-cookie") ?? "").split(";")[0]!;
103 expect(cookie).toContain("=");
104 const html = await (await fetch(`${servers.url}/explore`, { headers: { cookie } })).text();
105 expect(count(html)).toMatch(/^\d+ apps, forges and people$/);
106 expect(count(await get("/explore"))).toMatch(/^\d+ apps and people$/);
107 });
test/mcp-explore-count.test.ts +22 −2
@@ -4,7 +4,7 @@ import { mkdtemp, rm } from "node:fs/promises";
44 import { tmpdir } from "node:os";
55 import { join } from "node:path";
66 import { createApp, type App } from "../src/app.ts";
7 import { exploreCount, readExploreLine } from "../src/actions/explore.ts";
7 import { exploreCount, exploreFiltered, readExploreLine } from "../src/actions/explore.ts";
88 import { createRepo } from "../src/actions/repos.ts";
99 import { createApp as insertApp } from "../src/core/apps.ts";
1010 import { createToken } from "../src/core/tokens.ts";
@@ -64,12 +64,32 @@ test("a filter with none: the miss sentence and clear", async () => {
6464 const r = await explore({ q: "zzzznothing" });
6565 expect(r.total).toBe(0);
6666 expect(r.line).toBe(exploreCount(readExploreLine("zzzznothing").query, 0));
67 expect(r.line).toBe("Nothing matches");
6768 expect(r.clear).toBeDefined();
6869 });
6970
71 test("a sort alone clears too, as the page does", async () => {
72 const r = await explore({ q: "sort:forks" });
73 expect(r.clear).toEqual({ tool: "explore", arguments: {} });
74 expect(exploreFiltered(readExploreLine("sort:forks").query)).toBe(true);
75 expect(exploreFiltered(readExploreLine("").query)).toBe(false);
76 });
77
78 test("only an admin's count names forges", () => {
79 const q = readExploreLine("").query;
80 expect(exploreCount(q, 3, true)).toBe("3 apps, forges and people");
81 expect(exploreCount(q, 3)).toBe("3 apps and people");
82 });
83
84 test("one result reads in the singular for an admin and a guest", () => {
85 const q = readExploreLine("").query;
86 expect(exploreCount(q, 1, true)).toBe("1 app, forge or person");
87 expect(exploreCount(q, 1)).toBe("1 app or person");
88 });
89
7090 test("no filter: a count and no clear", async () => {
7191 const r = await explore({});
7292 expect(r.total).toBeGreaterThan(1);
73 expect(r.line).toBe(`${r.total} results`);
93 expect(r.line).toBe(`${r.total} apps and people`);
7494 expect(r.clear).toBeUndefined();
7595 });
test/tui-dashboard-explore.test.ts +22
@@ -220,3 +220,25 @@ test("forks:abc on the terminal is refused naming the word, as the page and the
220220 const answer = await typed("kind:app live:maybe");
221221 expect(answer).toContain("live:maybe is not an answer");
222222 });
223
224 test("only an admin's count line names forges; a guest's and a member's do not", async () => {
225 const guest = await typed("sort:forks", [], undefined);
226 expect(guest).toMatch(/Read as: sort:forks · \d+ apps and people · Esc clears/);
227 expect(guest).not.toContain("forges and people");
228 expect(await typed("sort:forks", [], alice)).not.toContain("forges and people");
229 // Made last, so the person counts the tests above read are not moved by it.
230 const made = await createUser(forge.db, { origin: "seed", trusted: true, isAdmin: true, username: "ada", email: "[email protected]", password: "a-long-passphrase" });
231 if (!made.ok) throw new Error(made.error);
232 expect(made.value.isAdmin).toBe(true);
233 expect(await typed("sort:forks", [], made.value)).toMatch(/Read as: sort:forks · \d+ apps, forges and people · Esc clears/);
234 });
235
236 test("a sort alone says Esc clears, and Esc puts the list back in its plain order", async () => {
237 const sorted = await typed("sort:forks");
238 expect(sorted).toContain("Read as: sort:forks");
239 expect(sorted).toContain("Esc clears");
240 const cleared = await typed("sort:forks", ["esc"]);
241 expect(cleared).not.toContain("Read as:");
242 expect(cleared).not.toContain("Esc clears");
243 expect(cleared).not.toContain("sort:forks");
244 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs