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
Check · Review · Land · Live done — Landed and live in production.
scout/forge:scout/12316-explore-says-how-many-results-the-filter → main 10 commits fork 5 threads · 5 unresolved
8 files
changed +98
−19
docs/design/attention-budget.json +3 −2
| @@ -185,13 +185,14 @@ | ||
| 185 | 185 | "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." |
| 186 | 186 | }, |
| 187 | 187 | "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.", | |
| 188 | 189 | "390": { |
| 189 | "words": 39, | |
| 190 | "words": 42, | |
| 190 | 191 | "blocks": 9, |
| 191 | 192 | "colours": 0 |
| 192 | 193 | }, |
| 193 | 194 | "1280": { |
| 194 | "words": 39, | |
| 195 | "words": 42, | |
| 195 | 196 | "blocks": 9, |
| 196 | 197 | "colours": 0 |
| 197 | 198 | } |
src/actions/explore.ts +18 −7
| @@ -416,10 +416,13 @@ const NOUNS = { | ||
| 416 | 416 | app: ["app", "apps"], |
| 417 | 417 | person: ["person", "people"], |
| 418 | 418 | forge: ["forge", "forges"], |
| 419 | all: ["result", "results"], | |
| 419 | all: ["app or person", "apps and people"], | |
| 420 | 420 | } as const; |
| 421 | 421 | |
| 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 | */ | |
| 423 | 426 | export const exploreFiltered = (q: ExploreQuery): boolean => |
| 424 | 427 | q.kind !== "all" || |
| 425 | 428 | q.text !== "" || |
| @@ -428,12 +431,20 @@ export const exploreFiltered = (q: ExploreQuery): boolean => | ||
| 428 | 431 | q.owner !== undefined || |
| 429 | 432 | q.forks !== undefined || |
| 430 | 433 | q.ships !== undefined || |
| 431 | q.live === true; | |
| 434 | q.live === true || | |
| 435 | q.sort !== "score"; | |
| 432 | 436 | |
| 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) { | |
| 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]}`; | |
| 437 | 448 | } |
| 438 | 449 | |
| 439 | 450 | /** |
src/http/mcp/reads.ts +1 −1
| @@ -36,7 +36,7 @@ export async function exploreRun(ctx: Ctx, user: User | undefined, args: Args): | ||
| 36 | 36 | return good({ |
| 37 | 37 | query: exploreLine(query), |
| 38 | 38 | total: page.total, |
| 39 | line: exploreCount(query, page.total), | |
| 39 | line: exploreCount(query, page.total, user?.isAdmin === true), | |
| 40 | 40 | ...(exploreFiltered(query) ? { clear: { tool: "explore", arguments: {} } } : {}), |
| 41 | 41 | items: rowsWithWhy(ctx.app, query, page.items), |
| 42 | 42 | next_cursor: page.nextCursor, |
src/tui/screens/dashboard.ts +1 −1
| @@ -1282,7 +1282,7 @@ export function dashboardScreen(f: Session, ctx: Ctx): Screen { | ||
| 1282 | 1282 | const readAs = |
| 1283 | 1283 | read === undefined |
| 1284 | 1284 | ? 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. |
||
| 1286 | 1286 | const reduced = readAs ?? (f.user?.isAdmin === true ? protectionNotice() : undefined); |
| 1287 | 1287 | const [box, warn, list] = split( |
| 1288 | 1288 | main, |
src/web/studio/explore.ts +4 −4
| @@ -180,14 +180,14 @@ function removable(query: ExploreQuery): { term: string; without: ExploreQuery } | ||
| 180 | 180 | * moves. Unfiltered and empty it is silent: "Nothing public yet" says it. |
| 181 | 181 | * A miss names each filter that can be dropped, beside Clear filters. |
| 182 | 182 | */ |
| 183 | function countLine(query: ExploreQuery, total: number): Html { | |
| 183 | function countLine(query: ExploreQuery, total: number, seesForges: boolean): Html { | |
| 184 | 184 | const on = exploreFiltered(query); |
| 185 | 185 | if (total === 0 && !on) return html``; |
| 186 | 186 | const drops = |
| 187 | total === 0 | |
| 187 | total === 0 && on | |
| 188 | 188 | ? removable(query).map((t) => html` · <a href="${href(t.without)}">Drop ${shorten(t.term)}</a>`) |
| 189 | 189 | : []; |
| 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}${ | |
| 191 | 191 | on ? html` · <a href="/explore" data-clear-filters>Clear filters</a>` : html`` |
| 192 | 192 | }</span>`; |
| 193 | 193 | } |
| @@ -289,7 +289,7 @@ export async function explorePage(ctx: Ctx): Promise<Response> { | ||
| 289 | 289 | aria-pressed="${query.archived ? "true" : "false"}" |
| 290 | 290 | >Show archived</a |
| 291 | 291 | > |
| 292 | ${countLine(query, page0?.total ?? 0)} | |
| 292 | ${countLine(query, page0?.total ?? 0, ctx.auth.user?.isAdmin === true)} | |
| 293 | 293 | </div> |
| 294 | 294 | ${rows.length === 0 |
| 295 | 295 | ? emptyState(ctx, query) |
test/explore-count.test.ts +27 −2
| @@ -42,9 +42,9 @@ afterAll(async () => { | ||
| 42 | 42 | const get = async (path: string) => (await fetch(`${servers.url}${path}`)).text(); |
| 43 | 43 | const count = (html: string) => html.match(/data-hits[^>]*>([^<]*)/)?.[1]?.trim(); |
| 44 | 44 | |
| 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 () => { | |
| 46 | 46 | const html = await get("/explore"); |
| 47 | expect(count(html)).toBe("66 results"); | |
| 47 | expect(count(html)).toBe("66 apps and people"); | |
| 48 | 48 | expect(html).not.toContain("data-clear-filters"); |
| 49 | 49 | }); |
| 50 | 50 | |
| @@ -80,3 +80,28 @@ test("the count is the whole filtered list on a page after a cursor", async () = | ||
| 80 | 80 | expect(count(second)).toMatch(/^62 apps/); |
| 81 | 81 | expect(second).toContain("data-clear-filters"); |
| 82 | 82 | }); |
| 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"; | ||
| 4 | 4 | import { tmpdir } from "node:os"; |
| 5 | 5 | import { join } from "node:path"; |
| 6 | 6 | 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"; | |
| 8 | 8 | import { createRepo } from "../src/actions/repos.ts"; |
| 9 | 9 | import { createApp as insertApp } from "../src/core/apps.ts"; |
| 10 | 10 | import { createToken } from "../src/core/tokens.ts"; |
| @@ -64,12 +64,32 @@ test("a filter with none: the miss sentence and clear", async () => { | ||
| 64 | 64 | const r = await explore({ q: "zzzznothing" }); |
| 65 | 65 | expect(r.total).toBe(0); |
| 66 | 66 | expect(r.line).toBe(exploreCount(readExploreLine("zzzznothing").query, 0)); |
| 67 | expect(r.line).toBe("Nothing matches"); | |
| 67 | 68 | expect(r.clear).toBeDefined(); |
| 68 | 69 | }); |
| 69 | 70 | |
| 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 | ||
| 70 | 90 | test("no filter: a count and no clear", async () => { |
| 71 | 91 | const r = await explore({}); |
| 72 | 92 | expect(r.total).toBeGreaterThan(1); |
| 73 | expect(r.line).toBe(`${r.total} results`); | |
| 93 | expect(r.line).toBe(`${r.total} apps and people`); | |
| 74 | 94 | expect(r.clear).toBeUndefined(); |
| 75 | 95 | }); |
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 | ||
| 220 | 220 | const answer = await typed("kind:app live:maybe"); |
| 221 | 221 | expect(answer).toContain("live:maybe is not an answer"); |
| 222 | 222 | }); |
| 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 | }); |
new above
offline
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.