[Plugin] INC-12: row counts, designed empty states, Clear filters

Every list says how many, and a filter narrowed to nothing says so and
offers the way back — Orders, Pricing & inventory and Coupons.

THE INTRO LINE CARRIES THE COUNT, pluralized through `Intl.PluralRules`
on the console's one pinned locale (the constant the date dialect
already uses), so `1 order` / `17 orders` come from one place.

AND IT IS HONEST ABOUT WHAT IT COUNTED. Every list port answers
`{items, nextCursor}` and no screen has a total, so `17 orders` renders
only when the page IS the set — first page of its filter, no next
cursor. Everywhere else the same count reads `25 orders on this page`.
Page 3 of 3 knows nothing about pages 1 and 2 (keyset paging carries no
running offset and the scaffold does not accumulate one across
stateless interactions), so it stays page-scoped too. A whole-store
total needs the service to return one; a number an operator would
reconcile against is not invented in a renderer.

ZERO RENDERS NO COUNT — never `0 orders`. The state below says it in
words, and a count line repeating it is "unknown rendered as 0".

TWO ZERO STATES THAT NO LONGER READ ALIKE. An empty collection is not
the operator's doing and is not addressed as though it were. A filter
narrowed to nothing is a different event and now gets a heading, body
copy and a `Clear filters` button where it used to get one line of
`empty_text` under a table that was not rendered. The undo is attached
to the state that needs it and to no other.

THE WHOLE-COLLECTION WORDING IS GATED ON `firstPage`, exactly as the
count is. "No orders yet" is a claim about the collection and page 2 of
a scan has no standing to make one — page 1 had rows. Reachable in a
live store, not only in theory: the look-ahead read that minted the
cursor and the read that follows it straddle a concurrent delete, and
the second comes back empty. A non-first-page zero falls through to
page-scoped wording, offering nothing to click since nothing was
filtered.

`Clear filters` IS ONE ACT WITH ONE BUILDER — ACROSS THE THREE SCREENS
THIS TOUCHES. The summary section's accessory and the new zero-state
button come from one builder, so the label, the verb and the payload
cannot drift on Orders, Pricing & inventory and Coupons. tax-page.ts
and shipping-page.ts still hand-roll a byte-identical button and are
deliberately untouched here (one PR, one thing) — they are the
next-touch consolidation onto `clearFiltersButton`. The builder fires a
BARE apply-filter (no values ⇒ the level's default filter) and carries
the drill path in the button's own `value`, which keeps the re-render
on the level the operator was standing on.

A PAGE WITH ANOTHER PAGE BEHIND IT NEVER CLAIMS TO BE THE END. The
pinned renderer collapses a zero-row table carrying `empty_text` to a
bare <p> and takes "Load more" with it, so a mid-scan zero page keeps a
headers-only table plus a note. Established for the low-stock filter;
now the shared rule for every screen.

BUILT ONCE: `listResult` in `scaffold/list-detail.ts` decides which
outcome a render is in and the three screens supply wording only. The
list level's `render` also receives `firstPage`, the one fact neither
the honest-count rule nor the whole-collection gate can be derived
without.

TWO CONTAINMENT FIXES CARRIED ALONG. A cursor minted before the
products filter grew its page-context wrapper arrived as a bare filter
form and threw on the way into `render`; it now self-heals — the bare
shape IS the form, so the operator's filter survives the deploy, and an
unreadable one degrades to "no filter set" rather than to an exception
(G5). And the cursor encoding is documented for what it carries:
`fetchPage` and `render` share one filter object, so page context
written during the fetch rides the next-page cursor too.

Gate: full run green at the pre-review tree (180 files, 3179 tests,
SQLite). Review take-its re-gated delta-scoped — lint, typecheck,
format:check, and the three page suites plus four scaffold suites
(7 files, 342 tests) all green.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Uq2ju7XBMf2rJsXBxSjE74

Author: vedanshujain

.changeset/list-counts-and-empty-states.md

@@ -0,0 +1,80 @@
+---
+"@otta-sh/plugin": patch
+---
+
+Every list says how many, and a filter narrowed to nothing says so and offers
+the way back — on Orders, Pricing & inventory and Coupons.
+
+**The intro line carries the count.** `17 orders · Filter, open an order, and
+move it through its status flow.` The count is pluralized through
+`Intl.PluralRules` on the console's one pinned locale — the same constant the
+date dialect uses — so `1 order` and `17 orders` come from one place and a
+future viewer locale moves one knob.
+
+**The count is honest about what it counted, because the wire is thin.** Every
+list port answers `{items, nextCursor}` — a page and a way to ask for the next
+one — and no screen has a total. So `17 orders` renders only when the page IS
+the set: the first page of its filter, with no next cursor. Everywhere else the
+same count reads `25 orders on this page`, which is the smaller claim and the
+true one. Page 3 of 3 knows nothing about pages 1 and 2 (keyset paging carries
+no running offset, and the scaffold deliberately does not accumulate one across
+stateless interactions), so it stays page-scoped too. A whole-store total needs
+the service to return one alongside `nextCursor`; until it does, a number an
+operator would reconcile against must not be invented here.
+
+**Zero renders no count at all.** Never `0 orders` — at zero the state below
+says it in words, and a count line repeating it is "unknown rendered as 0" in a
+costume.
+
+**Two zero states, and they no longer read alike.** A collection that is simply
+empty is not the operator's doing and is not addressed as though it were:
+`No orders yet — Orders appear here as buyers check out.` A filter narrowed to
+nothing is a different event and now gets a designed state of its own —
+heading, body copy, and a **Clear filters** button — where it used to get one
+line of `empty_text` under a table that was not rendered. The undo is attached
+to the state that needs it and to no other: an empty catalog offers nothing to
+clear, because there is no filter to blame.
+
+**The whole-collection wording is gated on `firstPage`, exactly as the count
+is.** "No orders yet" is a claim about the collection, and page 2 of a scan has
+no standing to make one — page 1 had rows. It is reachable in a live store, not
+only in theory: the look-ahead read that minted the cursor and the read that
+follows it straddle a concurrent delete, and the second comes back empty. A
+non-first-page zero falls through to page-scoped wording (`Nothing on this
+page`) offering nothing to click, since nothing was filtered.
+
+**`Clear filters` is one act with one builder — across the three screens this
+touches.** It was already the accessory on the active-filter summary section;
+that call site and the new zero-state button now come from the same builder, so
+the label, the verb and the payload cannot drift apart *on Orders, Pricing &
+inventory and Coupons*. `tax-page.ts:620` and `shipping-page.ts:1102` still
+hand-roll a byte-identical button of their own and are deliberately untouched
+here (one PR, one thing); they are the next-touch consolidation onto
+`clearFiltersButton`. The builder fires a BARE `apply-filter` — no values, so
+the scaffold rebuilds the level's default filter — and carries the drill path in
+the button's own `value`, which is what keeps the re-render on the level the
+operator was standing on rather than bouncing them to the root.
+
+**A page with another page behind it never claims to be the end.** The pinned
+renderer short-circuits a zero-row table carrying `empty_text` to a bare `<p>`
+and takes the "Load more" button with it, so a mid-scan page narrowed to zero
+must keep a headers-only table and say the scan can continue. That was
+established for the low-stock filter and is now the shared rule for every
+screen, in one place, rather than something each list has to rediscover.
+
+**It is built once.** `listResult` in `scaffold/list-detail.ts` decides which
+outcome a render is in; the three screens supply their own wording and nothing
+else. The list level's `render` now also receives `firstPage`, which is the one
+fact neither the honest-count rule nor the whole-collection gate can be derived
+without.
+
+**Two containment fixes carried along.** A keyset cursor minted before the
+products filter grew its page-context wrapper used to arrive as a bare filter
+form and throw on the way into `render` — this screen's fail-closed banner in
+place of the page asked for. It now self-heals: the bare shape IS the form, so
+the operator's filter survives the deploy instead of being dropped, and an
+unreadable one degrades to "no filter set" rather than to an exception. And the
+cursor encoding is documented for what it actually carries: `fetchPage` and
+`render` share one filter object, so page context written during the fetch rides
+the next-page cursor too — which is fine while it is overwritten on every fetch,
+and a stale value on screen the moment it is merged instead.

packages/plugin/src/admin/coupons-page.ts

@@ -30,16 +30,18 @@ import {
 	asRecord,
 	backButton,
 	carriedForm,
+	clearFiltersButton,
 	createListDetailHandler,
 	customAction,
 	decodePath,
-	emptyState,
 	encodePath,
 	failClosedResponse,
 	filterPanel,
 	filterSummary,
 	leafLevel,
+	listIntroLine,
 	listLevel,
+	listResult,
 	noticeBanner,
 	PATH_FIELD,
 	readAdminTokens,
@@ -372,13 +374,18 @@ function couponsListLevel() {
 			});
 			return { items: page.coupons, nextCursor: page.nextCursor };
 		},
-		render({ actions, path, filter, items, nextToken, notice, renderState }) {
-			return couponsBlocks(actions, path, filter, items, nextToken, notice, renderState);
+		render({ actions, path, filter, items, nextToken, firstPage, notice, renderState }) {
+			return couponsBlocks(actions, path, filter, items, nextToken, firstPage, notice, renderState);
 		},
 		onError: () => couponsFailClosed(),
 	});
 }
 
+/** The standing half of the list's intro line — the row count goes in front of
+ *  it ({@link listIntroLine}). 78 chars; the longest count line this screen can
+ *  produce (`25 coupons on this page`) puts the whole line at 104 ≤ 140 (X-11). */
+const LIST_INTRO = "Search a coupon and open it. Discounts apply to the cart subtotal at checkout.";
+
 function toClientFilter(form: CouponsFilterForm): CouponsListFilter {
 	return form.search !== undefined ? { search: form.search } : {};
 }
@@ -407,23 +414,46 @@ function couponsBlocks(
 	filter: CouponsFilterForm,
 	coupons: CouponSummaryWire[],
 	nextToken: string | undefined,
+	firstPage: boolean,
 	notice: Notice | undefined,
 	renderState: CouponsRenderState | undefined,
 ): Block[] {
 	if (renderState?.kind === "new-coupon") return newCouponScreen(renderState.draft, notice);
+	// ONE part for the screen's one authored filter field (L-3).
+	const activeFilters = [filter.search !== undefined && `code: ${filter.search}`];
+	const summary = filterSummary(activeFilters);
+	const result = listResult({
+		actions,
+		path,
+		count: coupons.length,
+		filtered: summary !== undefined,
+		firstPage,
+		nextToken,
+		noun: { one: "coupon", other: "coupons" },
+		empty: {
+			title: "No coupons yet",
+			description: "Create one to start discounting carts.",
+			blockId: "coupons:empty",
+			// E-2's way IN: the SAME verb and the SAME words as the promoted button
+			// above, because they are the same act and reach the same screen.
+			actions: [{ type: "button", action_id: ACTION_NEW, label: "New coupon", value: {} }],
+		},
+		noMatch: {
+			title: "No coupon matches that code",
+			// The way IN is already on screen (the promoted "New coupon" button sits
+			// above), so this state offers only the undo — one act per state.
+			description: "Nothing came back for that search. Clear it to go back to every coupon.",
+			blockId: "coupons:no-match",
+			emptyText: "No coupon matches that code.",
+		},
+	});
 	const blocks: Block[] = [
 		{ type: "header", text: "Coupons", block_id: "coupons:hdr" },
-		{
-			type: "context",
-			// 78 chars ≤ 140 (§1).
-			text: "Search a coupon and open it. Discounts apply to the cart subtotal at checkout.",
-		},
+		listIntroLine(result.countLine, LIST_INTRO),
 		createCouponButton(),
 	];
 	if (notice !== undefined) blocks.push(noticeBanner(notice));
 
-	// ONE part for the screen's one authored filter field (L-3).
-	const activeFilters = [filter.search !== undefined && `code: ${filter.search}`];
 	blocks.push(
 		filterPanel({
 			form: searchForm(actions, path, filter),
@@ -433,40 +463,25 @@ function couponsBlocks(
 			// accordion (L-2).
 		}),
 	);
-	const summary = filterSummary(activeFilters);
 	if (summary !== undefined) {
 		blocks.push({
 			type: "section",
 			text: summary,
 			// The path rides in `value`, NOT `block_id` — a button echoes no
 			// `block_id` (L-6, B-1).
-			accessory: {
-				type: "button",
-				action_id: actions.applyFilter,
-				label: "Clear filters",
-				value: { [PATH_FIELD]: encodePath(path) },
-			},
+			accessory: clearFiltersButton(actions, path),
 			block_id: "coupons:filter-summary",
 		});
 	}
 
-	const filtered = summary !== undefined;
-	if (coupons.length === 0 && !filtered) {
-		// E-2: the primary collection at its TRUE zero state. The table is
-		// OMITTED and `empty` renders in its place, with the create affordance in
-		// `empty.actions` — the SAME verb and the SAME words as the button above,
-		// because they are the same act and now reach the same screen.
-		blocks.push(
-			emptyState({
-				title: "No coupons yet",
-				description: "Create one to start discounting carts.",
-				size: "base",
-				actions: [{ type: "button", action_id: ACTION_NEW, label: "New coupon", value: {} }],
-				blockId: "coupons:empty",
-			}),
-		);
+	// E-2: at zero the table is OMITTED and `empty` renders in its place. WHICH
+	// state this is — no coupons at all, or a search that matched none with its own
+	// undo attached — was decided once, in `listResult`.
+	if (result.emptyBlock !== undefined) {
+		blocks.push(result.emptyBlock);
 	} else {
-		blocks.push(couponsTable(coupons, nextToken));
+		blocks.push(couponsTable(coupons, nextToken, result.emptyText));
+		if (result.scanNote !== undefined) blocks.push(result.scanNote);
 	}
 	if (coupons.length > 0) blocks.push(openCouponForm(actions, path, coupons));
 	return blocks;
@@ -541,7 +556,11 @@ function newCouponScreen(draft: CouponDraft | undefined, notice: Notice | undefi
  * per-value control the renderer does not have, and belongs to the
  * console-wide badge policy rather than to this screen alone.
  */
-function couponsTable(coupons: CouponSummaryWire[], nextToken: string | undefined): TableBlock {
+function couponsTable(
+	coupons: CouponSummaryWire[],
+	nextToken: string | undefined,
+	emptyText: string | undefined,
+): TableBlock {
 	// ONE instant for the whole response, so no two rows of one table can be
 	// judged against different clocks (see `couponStatus`).
 	const now = new Date().toISOString();
@@ -569,7 +588,10 @@ function couponsTable(coupons: CouponSummaryWire[], nextToken: string | undefine
 		})),
 		page_action_id: COUPON_ACTIONS.page,
 		...(nextToken !== undefined ? { next_cursor: nextToken } : {}),
-		empty_text: "No coupon matches that code.",
+		// OMITTED when another page remains behind a zero-row one: the renderer
+		// short-circuits such a table to a bare `<p>` and takes `Load more` with it
+		// (see `listResult`, outcome 3).
+		...(emptyText !== undefined ? { empty_text: emptyText } : {}),
 	};
 }