@remit/ui 0.0.61 → 0.0.62

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/ui",
-  "version": "0.0.61",
+  "version": "0.0.62",
   "type": "module",
   "files": [
     "src"

package/src/components/blocked-reason.render.test.ts

@@ -0,0 +1,44 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { createElement } from "react";
+import { renderToString } from "react-dom/server";
+import { BlockedReason } from "./blocked-reason.js";
+
+const REASON = "Pick a destination first.";
+
+/**
+ * Nothing disables (#477 1.7), so a dimmed control has to say what it is missing
+ * two ways: a description that is there for as long as the block is, and an
+ * announcement that happens when the control is pressed.
+ *
+ * They are separate elements because a live region announces what is written
+ * into it. One element that already holds the reason and gains `role="status"`
+ * on the press has nothing written into it, so nothing is announced — which is
+ * how a wizard comes to have a visual-only answer to "why can't I continue".
+ */
+describe("BlockedReason", () => {
+	it("describes the control before anything is pressed, silently", () => {
+		const html = renderToString(
+			createElement(BlockedReason, { id: "reason", reason: REASON }),
+		);
+		assert.match(html, /<p id="reason"[^>]*sr-only/);
+		assert.match(html, new RegExp(REASON));
+		// The live region is mounted and empty: there is nothing to announce yet.
+		assert.match(html, /role="status"[^>]*><\/span>/);
+	});
+
+	it("shows and announces the same reason once it has been pressed", () => {
+		const html = renderToString(
+			createElement(BlockedReason, {
+				id: "reason",
+				reason: REASON,
+				nudged: true,
+				className: "text-warning",
+			}),
+		);
+		assert.doesNotMatch(html, /role="status"[^>]*><\/span>/);
+		assert.match(html, new RegExp(`role="status"[^>]*>${REASON}`));
+		assert.doesNotMatch(html, /<p id="reason"[^>]*sr-only/);
+		assert.match(html, /text-warning/);
+	});
+});

package/src/components/blocked-reason.tsx

@@ -0,0 +1,41 @@
+import { cn } from "../lib/cn.js";
+
+export interface BlockedReasonProps {
+	/** What `aria-describedby` on the dimmed control points at. */
+	id: string;
+	reason: string;
+	/** The control was pressed while blocked, so the reason comes on screen. */
+	nudged?: boolean;
+	className?: string;
+}
+
+/**
+ * What a dimmed control is still missing (#477 1.7). Nothing disables, so the
+ * reason has to reach the user two ways, and they are not the same element.
+ *
+ * The description carries the reason for as long as it applies, so anything
+ * reading the control through the accessibility tree finds it without pressing
+ * anything; the press is what unhides it.
+ *
+ * The announcement is a live region that is mounted with the block and empty
+ * until the press, because a live region announces what is written into it and
+ * not what it was already holding. Marking the description live at the moment
+ * it becomes visible announces nothing.
+ */
+export function BlockedReason({
+	id,
+	reason,
+	nudged,
+	className,
+}: BlockedReasonProps) {
+	return (
+		<>
+			<p id={id} className={cn(className, !nudged && "sr-only")}>
+				{reason}
+			</p>
+			<span role="status" aria-live="polite" className="sr-only">
+				{nudged ? reason : ""}
+			</span>
+		</>
+	);
+}

package/src/components/filter-rule.ts

@@ -261,6 +261,16 @@ export const ruleBlockedCopy = {
 	recounting: "Recounting matches — save once the count settles.",
 } as const;
 
+/**
+ * What the count region says when there is no count to be had. The vector-free
+ * matcher will not read message bodies, so a `HasWords` clause cannot be counted
+ * before it is saved — which is a different answer from a count of zero, and
+ * the only one that keeps an empty sample from reading as "this matches
+ * nothing".
+ */
+export const UNCOUNTABLE_PREDICATE_REASON =
+	"Can't count matches — “has the words” reads message bodies, which only a saved rule does.";
+
 /**
  * Why the count on screen is not yet the count that will be applied, or
  * `undefined` once it has settled. This is what makes RFC 038's

package/src/components/mobile-search-view.stories.tsx

@@ -186,7 +186,7 @@ function Harness({
 	sections,
 	preset,
 	scope,
-	makeFilterDisabledReason,
+	makeFilterBlockedReason,
 	suggestions = [],
 }: {
 	initialValue?: string;
@@ -196,7 +196,7 @@ function Harness({
 	preset: Preset;
 	scope?: SearchScope;
 	/** Renders the conversion inert with a reason; it is offered either way. */
-	makeFilterDisabledReason?: string;
+	makeFilterBlockedReason?: string;
 	/** Completions for the term being typed. */
 	suggestions?: Suggestion[];
 }) {
@@ -282,7 +282,7 @@ function Harness({
 			scope={scope}
 			makeFilter={{
 				onClick: () => undefined,
-				disabledReason: makeFilterDisabledReason,
+				blockedReason: makeFilterBlockedReason,
 			}}
 			suggest={{
 				comboboxProps: suggest.comboboxProps,
@@ -343,9 +343,9 @@ export const ScopedSearch: Story = {
 };
 
 /**
- * A query with nothing a filter could match on: the conversion is offered inert
- * with the reason, rather than withheld and leaving the row to appear and vanish
- * as the user types.
+ * A query with nothing a filter could match on: the conversion stays offered and
+ * dimmed, rather than withheld and leaving the row to appear and vanish as the
+ * user types. Pressing it puts the reason on screen.
  */
 export const NothingToConvert: Story = {
 	render: () => (
@@ -353,7 +353,7 @@ export const NothingToConvert: Story = {
 			initialValue="has:attachment"
 			sections={resultSections}
 			preset="inbox"
-			makeFilterDisabledReason="Add a sender or words to filter on"
+			makeFilterBlockedReason="Add a sender or words to filter on"
 		/>
 	),
 };

package/src/components/search-results.render.test.ts

@@ -99,16 +99,17 @@ describe("SearchResults", () => {
 		assert.doesNotMatch(html, /disabled=""/);
 	});
 
-	it("disables the filter offer with its reason when nothing converts", () => {
+	it("keeps the filter offer pressable when nothing converts, carrying its reason", () => {
 		const html = renderToString(
 			createElement(SearchResults, {
 				value: "has:attachment",
 				sections: [{ id: "results", label: "Results", results: [] }],
-				makeFilter: { onClick: noop, disabledReason: "Add a sender or words" },
+				makeFilter: { onClick: noop, blockedReason: "Add a sender or words" },
 			}),
 		);
 		assert.match(html, /Make this a filter/);
-		assert.match(html, /disabled/);
+		assert.doesNotMatch(html, /disabled/);
+		assert.match(html, /aria-describedby/);
 		assert.match(html, /Add a sender or words/);
 	});
 

package/src/components/search-results.stories.tsx

@@ -190,15 +190,18 @@ export const WithMakeFilter: Story = {
 	),
 };
 
-/** The filter offer disabled — a search of only non-clause facets has nothing to convert. */
-export const MakeFilterDisabled: Story = {
+/**
+ * The filter offer dimmed — a search of only non-clause facets has nothing to
+ * convert. It stays pressable, and pressing it puts the reason on screen.
+ */
+export const MakeFilterBlocked: Story = {
 	render: () => (
 		<Harness
 			value="has:attachment"
 			sections={resultSections}
 			makeFilter={{
 				onClick: () => {},
-				disabledReason: "Add a sender or words to filter on",
+				blockedReason: "Add a sender or words to filter on",
 			}}
 		/>
 	),

package/src/components/search-results.tsx

@@ -1,6 +1,7 @@
 import { ChevronDown, Clock, Filter } from "lucide-react";
-import { useState } from "react";
+import { useId, useState } from "react";
 import { cn } from "../lib/cn.js";
+import { BlockedReason } from "./blocked-reason.js";
 import type { FolderRole } from "./folder-role.js";
 import { type SearchResult, SearchResultRow } from "./search-result-row.js";
 import { SearchTokenChips } from "./search-token-chip.js";
@@ -86,21 +87,22 @@ export interface SearchResultsProps {
 	scope?: SearchScope;
 	/**
 	 * "Make this a filter" (RFC 038 D5) — offered above the results while a query
-	 * is active, converting the search to a pre-filled rule. Omit to drop the
-	 * affordance; a `disabledReason` renders it inert with the reason (a search of
-	 * only non-clause facets has nothing to convert).
+	 * is active, opening the selection wizard on clauses derived from it. Omit to
+	 * drop the affordance; a `blockedReason` dims it and states what is missing (a
+	 * search of only non-clause facets has nothing to convert).
 	 */
 	makeFilter?: MakeFilterActionProps;
 }
 
 export interface MakeFilterActionProps {
 	onClick: () => void;
-	/** Renders the action inert and states why, e.g. nothing in the query converts. */
-	disabledReason?: string;
+	/** What the query is still missing. Dims the action; never disables it. */
+	blockedReason?: string;
 }
 
 /**
- * "Make this a filter" — the conversion entry offered while a search is active.
+ * "Make this a filter" — the wizard's second entry, offered while a search is
+ * active.
  *
  * A standalone row rather than a part of the results body, because a search is
  * shown in more than one way: the read-only `SearchResults` panel, and a list
@@ -108,34 +110,47 @@ export interface MakeFilterActionProps {
  * not to either rendering, so the caller mounts it above whichever body is up and
  * it stays put when the body swaps. `SearchResults` renders it inline as a
  * convenience for callers that show only the panel.
+ *
+ * Nothing disables (#477 1.7). A query with nothing to convert dims the action
+ * and leaves it pressable — pressing it is what brings the reason on screen,
+ * which `disabled` would take away along with the control itself.
  */
 export function MakeFilterAction({
 	onClick,
-	disabledReason,
+	blockedReason,
 }: MakeFilterActionProps) {
-	const disabled = disabledReason !== undefined;
+	const reasonId = useId();
+	const [nudged, setNudged] = useState(false);
 	return (
 		<div className="border-b border-line px-row-inset py-1.5">
 			<button
 				type="button"
-				onClick={onClick}
-				disabled={disabled}
-				title={disabledReason}
+				onClick={() => {
+					if (blockedReason) {
+						setNudged(true);
+						return;
+					}
+					onClick();
+				}}
+				aria-describedby={blockedReason ? reasonId : undefined}
 				className={cn(
 					"flex w-full items-center gap-1.5 rounded-md px-2 py-1.5 text-left text-xs font-medium transition-colors",
-					disabled
-						? "cursor-not-allowed text-fg-subtle"
+					blockedReason
+						? "text-fg-subtle opacity-55"
 						: "text-accent hover:bg-surface-sunken",
 				)}
 			>
 				<Filter className="size-3.5 shrink-0" aria-hidden="true" />
 				<span>Make this a filter</span>
-				{disabled && (
-					<span className="ml-auto truncate text-2xs font-normal text-fg-subtle">
-						{disabledReason}
-					</span>
-				)}
 			</button>
+			{blockedReason && (
+				<BlockedReason
+					id={reasonId}
+					reason={blockedReason}
+					nudged={nudged}
+					className="px-2 pt-1 text-2xs text-warning"
+				/>
+			)}
 		</div>
 	);
 }
@@ -286,12 +301,7 @@ export function SearchResults({
 	const chips = tokens && tokens.length > 0 && (
 		<SearchTokenChips tokens={tokens} />
 	);
-	const filterAction = makeFilter && (
-		<MakeFilterAction
-			onClick={makeFilter.onClick}
-			disabledReason={makeFilter.disabledReason}
-		/>
-	);
+	const filterAction = makeFilter && <MakeFilterAction {...makeFilter} />;
 
 	if (loading) {
 		return (

package/src/components/selection-wizard.render.test.ts

@@ -4,7 +4,10 @@ import { createElement } from "react";
 import { renderToString } from "react-dom/server";
 import type { MatchCount, StepId, WizardDraft } from "../lib/wizard-steps.js";
 import { stepsFor } from "../lib/wizard-steps.js";
-import type { RuleClause } from "./filter-rule.js";
+import {
+	type RuleClause,
+	UNCOUNTABLE_PREDICATE_REASON,
+} from "./filter-rule.js";
 import {
 	FolderStepBody,
 	MatchStepBody,
@@ -172,6 +175,23 @@ describe("SelectionSample", () => {
 		assert.match(html, /Nothing matches this yet/);
 	});
 
+	// A count that could not be taken is not a count of zero. A body-text clause
+	// is the case that makes the difference load-bearing: it matches, once a
+	// saved rule is what runs it, so "nothing matches this yet" is wrong rather
+	// than merely unexplained (#477 3.5).
+	it("says a count could not be taken instead of that nothing matched", () => {
+		const html = renderToString(
+			createElement(SelectionSample, {
+				messages: [],
+				count: { status: "error", reason: UNCOUNTABLE_PREDICATE_REASON },
+				label: "What this matches",
+				emptyReason: "noMatch",
+			}),
+		);
+		assert.match(text(html), /only a saved rule does/);
+		assert.doesNotMatch(html, /Nothing matches this yet/);
+	});
+
 	it("says the total is unknown when the match has not run", () => {
 		const html = renderToString(
 			createElement(SelectionSample, {
@@ -665,33 +685,35 @@ describe("SelectionWizard", () => {
 		assert.doesNotMatch(html, /<button[^>]*disabled=""/);
 	});
 
-	it("carries the blocked reason on the control before it is pressed, and shows it after", () => {
+	it("carries the blocked reason on the control before it is pressed, and announces it after", () => {
+		const reason = "Add a property to match on.";
 		const quiet = renderToString(
 			createElement(
 				SelectionWizard,
-				wizardProps({
-					step: "properties",
-					blockedReason: "Add a property to match on.",
-				}),
+				wizardProps({ step: "properties", blockedReason: reason }),
 			),
 		);
-		// Described, so it is heard on the control; not on screen until pressed.
+		// Described, so it is heard on the control; not on screen and nothing
+		// announced until the control is pressed.
 		assert.match(quiet, /aria-describedby="/);
-		assert.match(quiet, /sr-only/);
-		assert.doesNotMatch(quiet, /role="status"/);
+		assert.match(quiet, /<p id="[^"]*"[^>]*sr-only/);
+		assert.match(quiet, /role="status"[^>]*><\/span>/);
 
 		const nudged = renderToString(
 			createElement(
 				SelectionWizard,
 				wizardProps({
 					step: "properties",
-					blockedReason: "Add a property to match on.",
+					blockedReason: reason,
 					nudged: true,
 				}),
 			),
 		);
-		assert.match(nudged, /role="status"/);
-		assert.doesNotMatch(nudged, /sr-only/);
+		// The reason is written into the live region, which is what a screen
+		// reader announces — marking the description live would announce nothing.
+		assert.doesNotMatch(nudged, /role="status"[^>]*><\/span>/);
+		assert.match(nudged, new RegExp(`role="status"[^>]*>${reason}`));
+		assert.doesNotMatch(nudged, /<p id="[^"]*"[^>]*sr-only/);
 	});
 
 	it("commits under the scope's own label, in the verb's own tone", () => {

package/src/components/selection-wizard.tsx

@@ -42,6 +42,7 @@ import {
 	type WizardDraft,
 } from "../lib/wizard-steps.js";
 import { Badge } from "./badge.js";
+import { BlockedReason } from "./blocked-reason.js";
 import { Button } from "./button.js";
 import { FieldLabel } from "./field-label.js";
 import {
@@ -279,6 +280,25 @@ const sampleFooter = (count: MatchCount, shown: number): string => {
 	return previewCountSummary(count);
 };
 
+/**
+ * What an empty sample says. A count that could not be taken says so; only a
+ * count that came back empty may say nothing matches (#477 3.5).
+ *
+ * A body-text clause is the case that makes the difference load-bearing: the
+ * vector-free matcher refuses to evaluate it, so there is no count and no rows,
+ * and "nothing matches this yet" is not merely unexplained but wrong — the rule
+ * matches, once a saved rule is what runs it.
+ */
+const sampleEmptyLine = (
+	count: MatchCount,
+	emptyReason: SampleEmptyReason | undefined,
+	loading: boolean | undefined,
+): string => {
+	if (loading) return "Fetching the messages this covers…";
+	if (count.status === "error") return count.reason;
+	return sampleEmptyCopy(emptyReason ?? "noMatch");
+};
+
 /**
  * The members of the match, closing every screen that names one. A named match
  * with no members shown is an unseen bulk action, so the rows scroll in their own
@@ -298,9 +318,7 @@ export function SelectionSample({
 			</h2>
 			{messages.length === 0 ? (
 				<p className="px-3 py-4 text-xs text-fg-muted">
-					{loading
-						? "Fetching the messages this covers…"
-						: sampleEmptyCopy(emptyReason ?? "noMatch")}
+					{sampleEmptyLine(count, emptyReason, loading)}
 				</p>
 			) : (
 				<>
@@ -345,9 +363,8 @@ export interface FooterNavProps {
 /**
  * Nothing disables (#477 1.7). A Continue with an answer still missing is dimmed
  * and stays pressable — and stays pressable to assistive technology too, which
- * `aria-disabled` would have taken away along with the reason. The reason is on
- * the control the whole time it applies, through `aria-describedby`; pressing it
- * is what brings the reason on screen.
+ * `aria-disabled` would have taken away along with the reason. `BlockedReason`
+ * carries the two ways that reason reaches the user.
  */
 export function FooterNav({
 	backLabel = "Back",
@@ -362,13 +379,12 @@ export function FooterNav({
 	return (
 		<div className="space-y-2">
 			{blockedReason && (
-				<p
+				<BlockedReason
 					id={reasonId}
-					role={nudged ? "status" : undefined}
-					className={cn("px-1 text-2xs text-warning", !nudged && "sr-only")}
-				>
-					{blockedReason}
-				</p>
+					reason={blockedReason}
+					nudged={nudged}
+					className="px-1 text-2xs text-warning"
+				/>
 			)}
 			<div className="flex items-center gap-3">
 				<Button

package/src/index.ts

@@ -67,6 +67,10 @@ export {
 	type BannerTone,
 	type BannerVariant,
 } from "./components/banner.js";
+export {
+	BlockedReason,
+	type BlockedReasonProps,
+} from "./components/blocked-reason.js";
 export {
 	BottomSheet,
 	type BottomSheetProps,
@@ -174,6 +178,7 @@ export {
 	type RuleWiden,
 	ruleBlockedCopy,
 	scopeLabel,
+	UNCOUNTABLE_PREDICATE_REASON,
 	unreadableBodyClauses,
 	widenChipLabel,
 } from "./components/filter-rule.js";
@@ -628,11 +633,11 @@ export {
 } from "./lib/roving-focus.js";
 export { type RuleNameParts, suggestRuleName } from "./lib/rule-name.js";
 export {
-	buildSearchRule,
 	type DroppedFacet,
 	type DroppedFacetType,
 	isConvertible,
 	type SearchConversion,
+	searchConversionNotice,
 } from "./lib/search-rule.js";
 export {
 	collapsibleDomain,

package/src/lib/search-rule.test.ts

@@ -1,9 +1,9 @@
 import assert from "node:assert/strict";
 import { describe, it } from "node:test";
 import {
-	buildSearchRule,
 	isConvertible,
 	type SearchConversion,
+	searchConversionNotice,
 } from "./search-rule.js";
 
 const conversion = (
@@ -43,31 +43,32 @@ describe("isConvertible", () => {
 	});
 });
 
-describe("buildSearchRule", () => {
-	it("builds a standing rule with stable clause ids, no widen, empty name", () => {
-		const rule = buildSearchRule(
+describe("searchConversionNotice", () => {
+	it("names the folder the search was scoped to and every facet dropped", () => {
+		const notice = searchConversionNotice(
 			conversion({
-				clauses: [
-					{ field: "From", value: "a@b.com" },
-					{ field: "HasWords", value: "nightly" },
-				],
+				clauses: [{ field: "HasWords", value: "npm" }],
+				keptTerms: true,
+				scopedOut: { mailboxId: "mbx-archive", label: "Archive" },
+				droppedFacets: [{ type: "isUnread", label: "Unread" }],
+				droppedSemantic: true,
 			}),
 		);
-		assert.equal(rule.scope, "standing");
-		assert.equal(rule.widen, undefined);
-		assert.equal(rule.name, "");
-		assert.deepEqual(
-			rule.clauses.map((clause) => clause.id),
-			["search-0", "search-1"],
-		);
+		assert.deepEqual(notice, {
+			scopedOutFolder: "Archive",
+			droppedFacets: ["Unread"],
+			droppedSemantic: true,
+		});
 	});
 
-	it("honors an explicit scope and move target", () => {
-		const rule = buildSearchRule(
-			conversion({ clauses: [{ field: "HasWords", value: "nightly" }] }),
-			{ scope: "once", moveMailboxId: "mbx-archive" },
+	it("states nothing for a conversion that carried everything", () => {
+		const notice = searchConversionNotice(
+			conversion({ clauses: [{ field: "From", value: "a@b.com" }] }),
 		);
-		assert.equal(rule.scope, "once");
-		assert.equal(rule.moveMailboxId, "mbx-archive");
+		assert.deepEqual(notice, {
+			scopedOutFolder: undefined,
+			droppedFacets: [],
+			droppedSemantic: false,
+		});
 	});
 });

package/src/lib/search-rule.ts

@@ -1,16 +1,12 @@
 /**
- * What a search converts to, and the rule built from it (RFC 038 D5). The shape
- * carries the clauses alongside everything the search held that a filter cannot,
- * so a conversion can never drop a facet without saying so; `search-conversion.ts`
- * beside it owns the copy that states it.
+ * What a search converts to (RFC 038 D5). The shape carries the clauses
+ * alongside everything the search held that a filter cannot, so a conversion can
+ * never drop a facet without saying so; `search-conversion.ts` beside it owns
+ * the copy that states it.
  */
 
-import type {
-	ClauseField,
-	FilterRule,
-	MatchOperator,
-	RuleScope,
-} from "../components/filter-rule.js";
+import type { ClauseField, MatchOperator } from "../components/filter-rule.js";
+import type { SearchConversionNotice } from "../components/search-conversion.js";
 
 /**
  * A search facet a filter has no clause for. Attachment, read state, starred,
@@ -68,29 +64,15 @@ export interface SearchConversion {
 export const isConvertible = (conversion: SearchConversion): boolean =>
 	conversion.clauses.length > 0;
 
-interface BuildRuleOptions {
-	scope?: RuleScope;
-	moveMailboxId?: string;
-}
-
 /**
- * The rule the editor opens on, from a conversion. A search-derived rule defaults
- * to a standing filter — "make this a filter" is a request to keep applying it —
- * and the editor lets the user drop it back to a one-time apply. It carries no
- * widen: a free-text query has no message anchor, so the semantic chip is not
- * offered on this surface (its loss is stated in the conversion notice instead).
+ * The conversion as the notice reads it. One mapping, beside both shapes, so
+ * every surface that opens on a converted search states the same losses in the
+ * same words.
  */
-export const buildSearchRule = (
+export const searchConversionNotice = (
 	conversion: SearchConversion,
-	{ scope = "standing", moveMailboxId }: BuildRuleOptions = {},
-): FilterRule => ({
-	clauses: conversion.clauses.map((clause, index) => ({
-		id: `search-${index}`,
-		field: clause.field,
-		value: clause.value,
-	})),
-	matchOperator: conversion.matchOperator,
-	moveMailboxId,
-	scope,
-	name: "",
+): SearchConversionNotice => ({
+	scopedOutFolder: conversion.scopedOut?.label,
+	droppedFacets: conversion.droppedFacets.map((facet) => facet.label),
+	droppedSemantic: conversion.droppedSemantic,
 });