refactor: make the public read port async so a network adapter can implement it

`PublicContentQueries` returned arrays, not promises. That signature is only
implementable by something already in memory, so the port could hold exactly
one adapter — the bundled fixture — and no amount of configuration could put
the public site on the backend. Turning it async is the change that makes a
second adapter possible; the adapter itself follows.

The markup is untouched. Every page reads a value and hands it to a
presentational component, so the shape those components receive is mapped at
the adapter boundary and nothing below the page changes.

Screens load through one query, not one per read. Several pages read in a loop
— the home timeline walks every project for its activity, the explore filter
walks search results to resolve titles — and a hook per read would mean a
variable number of hooks per render, which React forbids. `usePublicContent`
takes the whole screen's reads as one loader, where a loop is a loop and
`Promise.all` is available; the loops that used to be N sequential lookups now
issue together.

Two places deliberately do not show the loading surface. The explore filter
sits inside a page that already renders one, so a second skeleton would move
the layout under it — it keeps its structure and fills its options in when they
arrive. The search dialog is a type-ahead: re-querying per keystroke would
replace the results with a skeleton on every key, so it loads the catalog once
and applies the same predicate locally.

`usePublicContent` requires an object because `undefined` is how the query
layer says "no result yet". A loader returning the record itself would make a
missing slug indistinguishable from a request in flight, and the page would sit
on a skeleton instead of rendering its not-found route.

Studio's `resolvePublishedLabel` stays synchronous. It is called from inside
the public renderer, so making it async would push awaits through the render
tree; the shell loads the catalog once and the callback remains a lookup.

The component tests now assemble the query providers the running app assembles.
Without them the render throws "No QueryClient set" — not a harness quirk, but
the same failure the app would produce if it were mounted without its query
layer.
This commit is contained in:
DongHyeonka
2026-08-20 16:53:51 +09:00
parent c362ec6100
commit 4566f2d7a8
31 changed files with 564 additions and 202 deletions
@@ -165,17 +165,31 @@ export type SearchablePublicEntity = {
* The application-facing boundary for the immutable source Public catalog.
* Method signatures intentionally retain the source query argument and return shapes.
*/
/**
* The public read surface.
*
* Every method is async because one of the two adapters behind this port is a
* network client. The other reads a bundled fixture and could answer
* synchronously, but a port has one shape: if the fixture adapter kept the
* synchronous signature, the HTTP adapter could not implement the same port
* and callers written against the fixture would not compile against the
* network.
*
* Failures throw rather than resolving to a Result. That matches the Studio
* gateways, and it lets `useApplicationQuery` classify a rejection once at the
* boundary instead of every caller unwrapping.
*/
export type PublicContentQueries = Readonly<{
listRecords(filters?: RecordFilters): PublicRecord[];
listRecords(filters?: RecordFilters): Promise<PublicRecord[]>;
getRecord<K extends RecordKind>(
kind: K,
slug: string,
): Extract<PublicRecord, { kind: K }> | undefined;
getProject(slug: string): Project | undefined;
getRelease(version: string): Release | undefined;
getProjectRecords(projectSlug: string): PublicRecord[];
getProjectDecisions(projectSlug: string): ProjectDecision[];
getProjectActivity(projectSlug: string): ProjectActivity[];
getHomeFocusItems(): HomeFocusItem[];
searchPublicContent(query: string): SearchablePublicEntity[];
): Promise<Extract<PublicRecord, { kind: K }> | undefined>;
getProject(slug: string): Promise<Project | undefined>;
getRelease(version: string): Promise<Release | undefined>;
getProjectRecords(projectSlug: string): Promise<PublicRecord[]>;
getProjectDecisions(projectSlug: string): Promise<ProjectDecision[]>;
getProjectActivity(projectSlug: string): Promise<ProjectActivity[]>;
getHomeFocusItems(): Promise<HomeFocusItem[]>;
searchPublicContent(query: string): Promise<SearchablePublicEntity[]>;
}>;