@remit/ui 0.0.104 → 0.0.105

package/package.json

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

package/src/components/brief-sections.tsx

@@ -90,7 +90,9 @@ export function matchesBriefFilters(
  * The attribute chips are either this component's own or entirely the
  * consumer's. A consumer narrowing the same rows on a second surface (the phone
  * search takeover) holds the set so both surfaces answer to one selection, and
- * takes every control over it with the set.
+ * takes every control over it with the set. `onClearFilters` is then the whole
+ * of Clear, category scope included — one handler reading one state, rather
+ * than two reading the same one and racing to write it.
  */
 export type BriefFilterControl =
 	| {
@@ -236,11 +238,11 @@ export function BriefSections({
 	const sheetFilters = briefFilterChips;
 
 	const clearFilters = () => {
-		onSelectBriefCategory?.("all");
 		if (onClearFilters) {
 			onClearFilters();
 			return;
 		}
+		onSelectBriefCategory?.("all");
 		setOwnFilters(new Set());
 	};
 

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

@@ -353,7 +353,7 @@ export const NothingToConvert: Story = {
 			initialValue="has:attachment"
 			sections={resultSections}
 			preset="inbox"
-			makeFilterBlockedReason="Add a sender or words to filter on"
+			makeFilterBlockedReason="Has attachment isn't a filter condition — add a sender or words to filter on"
 		/>
 	),
 };

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

@@ -6,6 +6,7 @@ import {
 	DROPPED_SEMANTIC_COPY,
 	droppedFacetsCopy,
 	hasConversionNotice,
+	makeFilterBlockedCopy,
 	scopedOutCopy,
 } from "./search-conversion.js";
 import { SearchConversionNoticeView } from "./search-conversion-notice.js";
@@ -48,6 +49,29 @@ describe("search-conversion copy", () => {
 		assert.equal(hasConversionNotice({ droppedFacets: ["Unread"] }), true);
 		assert.equal(hasConversionNotice({ droppedSemantic: true }), true);
 	});
+
+	it("names the facets a chip-composed query is made of, not just the gap", () => {
+		const copy = makeFilterBlockedCopy(["Unread", "Category: Newsletter"]);
+		assert.match(
+			copy,
+			/Unread and Category: Newsletter aren't filter conditions/,
+		);
+		assert.match(copy, /add a sender or words to filter on/);
+	});
+
+	it("reads singular for one facet", () => {
+		assert.match(
+			makeFilterBlockedCopy(["Unread"]),
+			/^Unread isn't a filter condition — /,
+		);
+	});
+
+	it("asks for what is missing when no facet is what is in the way", () => {
+		assert.equal(
+			makeFilterBlockedCopy([]),
+			"Add a sender or words to filter on",
+		);
+	});
 });
 
 describe("SearchConversionNoticeView", () => {

package/src/components/search-conversion.ts

@@ -50,6 +50,24 @@ export function droppedFacetsCopy(facets: string[]): string {
 	} left out — the filter still matches everything else you searched for.`;
 }
 
+/** What a query needs before there is a rule to open on. */
+const NEEDS_A_CLAUSE = "add a sender or words to filter on";
+
+/**
+ * Why the current query has no filter in it. A query narrowed only by chips —
+ * ticked in the brief's filter panel, which writes them into the query as terms
+ * — is all attribute facets and no clause, so the reason names the facets that
+ * cannot be one instead of asking for something the user just supplied.
+ */
+export function makeFilterBlockedCopy(droppedFacets: string[]): string {
+	if (droppedFacets.length === 0)
+		return `${NEEDS_A_CLAUSE[0].toUpperCase()}${NEEDS_A_CLAUSE.slice(1)}`;
+	const verb = droppedFacets.length === 1 ? "isn't" : "aren't";
+	const noun =
+		droppedFacets.length === 1 ? "a filter condition" : "filter conditions";
+	return `${joinFacets(droppedFacets)} ${verb} ${noun} — ${NEEDS_A_CLAUSE}`;
+}
+
 /**
  * States the filter is literal-only, so the search's similar-mail reach is not
  * carried (RFC 038 D5). Shown only where that reach existed — a capable search

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

@@ -1,5 +1,6 @@
 import type { Decorator, Meta, StoryObj } from "@storybook/react";
 import { useState } from "react";
+import { makeFilterBlockedCopy } from "./search-conversion.js";
 import type { SearchResult } from "./search-result-row.js";
 import { type SearchResultSection, SearchResults } from "./search-results.js";
 
@@ -201,7 +202,7 @@ export const MakeFilterBlocked: Story = {
 			sections={resultSections}
 			makeFilter={{
 				onClick: () => {},
-				blockedReason: "Add a sender or words to filter on",
+				blockedReason: makeFilterBlockedCopy(["Has attachment"]),
 			}}
 		/>
 	),

package/src/index.ts

@@ -502,6 +502,7 @@ export {
 	DROPPED_SEMANTIC_COPY,
 	droppedFacetsCopy,
 	hasConversionNotice,
+	makeFilterBlockedCopy,
 	type SearchConversionNotice,
 	scopedOutCopy,
 } from "./components/search-conversion.js";
@@ -678,6 +679,17 @@ export {
 	formatByteSize,
 	sanitizeAttachmentFilename,
 } from "./lib/attachment-file.js";
+export {
+	briefChipCategory,
+	briefChipFilters,
+	briefFilterHasTerm,
+	briefQueryCategory,
+	briefQueryFilters,
+	briefQueryIsActive,
+	clearBriefFiltersInQuery,
+	setBriefCategoryInQuery,
+	toggleBriefFilterInQuery,
+} from "./lib/brief-filter-query.js";
 export {
 	buildCidResolver,
 	type CidResolvableBodyPart,
@@ -775,6 +787,14 @@ export {
 	useRovingFocus,
 } from "./lib/roving-focus.js";
 export { type RuleNameParts, suggestRuleName } from "./lib/rule-name.js";
+export {
+	quoteSearchTokenValue,
+	type SearchQueryWord,
+	type SearchTermParts,
+	searchTokenTerm,
+	splitSearchTerm,
+	splitSearchWords,
+} from "./lib/search-query-words.js";
 export {
 	type DroppedFacet,
 	type DroppedFacetType,

package/src/lib/brief-filter-query.test.ts

@@ -0,0 +1,200 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import type { BriefFilterId } from "../components/brief-sections.js";
+import {
+	briefChipCategory,
+	briefChipFilters,
+	briefFilterHasTerm,
+	briefQueryCategory,
+	briefQueryFilters,
+	clearBriefFiltersInQuery,
+	setBriefCategoryInQuery,
+	toggleBriefFilterInQuery,
+} from "./brief-filter-query.js";
+
+const ids = (filters: ReadonlySet<BriefFilterId>): BriefFilterId[] =>
+	[...filters].sort();
+
+describe("ticking a chip while a search is on", () => {
+	it("writes its term into the query, where it can be read", () => {
+		assert.equal(
+			toggleBriefFilterInQuery("Odido", "unread"),
+			"Odido is:unread",
+		);
+	});
+
+	it("writes the attachment term the same way", () => {
+		assert.equal(
+			toggleBriefFilterInQuery("Odido", "attachment"),
+			"Odido has:attachment",
+		);
+	});
+
+	it("takes the term back out when the chip is unticked", () => {
+		assert.equal(
+			toggleBriefFilterInQuery("Odido is:unread", "unread"),
+			"Odido",
+		);
+	});
+
+	it("leaves a chips-only query behind once the words are deleted", () => {
+		assert.equal(toggleBriefFilterInQuery("", "unread"), "is:unread");
+	});
+
+	it("says a chip has no term rather than writing one that means nothing", () => {
+		assert.equal(toggleBriefFilterInQuery("Odido", "contacts"), undefined);
+		assert.equal(toggleBriefFilterInQuery("Odido", "today"), undefined);
+		assert.equal(briefFilterHasTerm("contacts"), false);
+		assert.equal(briefFilterHasTerm("today"), false);
+	});
+});
+
+describe("scoping to a category while a search is on", () => {
+	it("writes the category term", () => {
+		assert.equal(
+			setBriefCategoryInQuery("Odido", "newsletter"),
+			"Odido category:newsletter",
+		);
+	});
+
+	it("swaps one category for another rather than stacking them", () => {
+		assert.equal(
+			setBriefCategoryInQuery("Odido category:newsletter", "marketing"),
+			"Odido category:marketing",
+		);
+	});
+
+	it("takes the term out again when the scope goes back to all", () => {
+		assert.equal(
+			setBriefCategoryInQuery("Odido category:newsletter", "all"),
+			"Odido",
+		);
+	});
+});
+
+describe("a term edited or deleted by hand", () => {
+	it("ticks the chip it names", () => {
+		assert.deepEqual(ids(briefQueryFilters("Odido is:unread")), ["unread"]);
+	});
+
+	it("reads the same whatever case it is typed in", () => {
+		assert.deepEqual(ids(briefQueryFilters("Odido IS:Unread")), ["unread"]);
+	});
+
+	it("unticks the chip once it is deleted", () => {
+		assert.deepEqual(ids(briefQueryFilters("Odido")), []);
+	});
+
+	it("scopes the category the term names, alias included", () => {
+		assert.equal(briefQueryCategory("Odido category:newsletter"), "newsletter");
+		assert.equal(
+			briefQueryCategory("Odido category:unclassified"),
+			"uncategorized",
+		);
+	});
+
+	it("leaves the scope alone for a category nobody has", () => {
+		assert.equal(briefQueryCategory("Odido category:nonsense"), "all");
+	});
+
+	it("never reads its own word as a category", () => {
+		assert.equal(briefQueryCategory("category:all"), "all");
+	});
+
+	it("keeps the words the query is otherwise made of", () => {
+		assert.equal(
+			clearBriefFiltersInQuery(
+				"Odido is:unread category:newsletter from:a@b.c",
+			),
+			"Odido from:a@b.c",
+		);
+	});
+});
+
+/**
+ * Terms are cut the way the parser cuts them. A splitter that broke on
+ * whitespace alone read a facet inside a quoted value as a facet of its own,
+ * and missed a quoted one that the parser applies — so the chip row disagreed
+ * with the rows on screen, and editing reached inside what the user typed.
+ */
+describe("a quoted value", () => {
+	it("keeps a facet spelled inside it out of the chips", () => {
+		assert.deepEqual(ids(briefQueryFilters('subject:"a is:unread b"')), []);
+	});
+
+	it("is left whole when a chip is ticked beside it", () => {
+		assert.equal(
+			toggleBriefFilterInQuery('subject:"a is:unread b"', "unread"),
+			'subject:"a is:unread b" is:unread',
+		);
+	});
+
+	it("ticks the chip when it is the facet's own value", () => {
+		assert.deepEqual(ids(briefQueryFilters('is:"unread"')), ["unread"]);
+	});
+
+	it("is removed by unticking rather than joined by a second term", () => {
+		assert.equal(toggleBriefFilterInQuery('is:"unread"', "unread"), "");
+	});
+
+	it("scopes the category it names", () => {
+		assert.equal(briefQueryCategory('category:"Newsletter"'), "newsletter");
+	});
+
+	// Two category terms AND to nothing (`matchesSearchTokens`), so a category
+	// pill that left the old one behind emptied the list on a click.
+	it("leaves one category term behind when another is picked", () => {
+		assert.equal(
+			setBriefCategoryInQuery('category:"Newsletter"', "marketing"),
+			"category:marketing",
+		);
+	});
+
+	it("is cleared with the rest of the chip terms", () => {
+		assert.equal(
+			clearBriefFiltersInQuery('Odido is:"unread" category:"Newsletter"'),
+			"Odido",
+		);
+	});
+});
+
+describe("the chips the panel shows ticked", () => {
+	it("are the panel's own while nothing is being searched", () => {
+		assert.deepEqual(
+			ids(briefChipFilters({ query: "", ownFilters: new Set(["unread"]) })),
+			["unread"],
+		);
+		assert.equal(
+			briefChipCategory({ query: "", ownCategory: "newsletter" }),
+			"newsletter",
+		);
+	});
+
+	it("are the query's terms while a search is on", () => {
+		assert.deepEqual(
+			ids(
+				briefChipFilters({
+					query: "Odido has:attachment",
+					ownFilters: new Set(["unread"]),
+				}),
+			),
+			["attachment"],
+		);
+		assert.equal(
+			briefChipCategory({ query: "Odido", ownCategory: "newsletter" }),
+			"all",
+		);
+	});
+
+	it("carry the chips the vocabulary cannot spell across a search", () => {
+		assert.deepEqual(
+			ids(
+				briefChipFilters({
+					query: "Odido is:unread",
+					ownFilters: new Set(["today", "contacts"]),
+				}),
+			),
+			["contacts", "today", "unread"],
+		);
+	});
+});

package/src/lib/brief-filter-query.ts

@@ -0,0 +1,173 @@
+/**
+ * The brief's chips as terms of the search query (#460).
+ *
+ * While something is being searched, a chip and a typed term are the same
+ * thing: ticking "Unread" over `Odido` leaves `Odido is:unread` in the field,
+ * which the user can read, edit and delete, and deleting it unticks the chip.
+ * The vocabulary is the one the search field already parses — `is:unread`,
+ * `has:attachment`, `category:<id>` — so a chip writes a term the engines
+ * already honour rather than a second, invisible filter stack over the same
+ * rows.
+ *
+ * Two of the brief's chips have no term in that vocabulary: "From contacts"
+ * matches on sender trust, which no facet names, and "Today" is a relative
+ * window where the vocabulary carries only absolute `before:`/`after:` dates.
+ * Those two keep narrowing from the panel's own state, which is why
+ * {@link briefChipFilters} carries them across a search rather than dropping
+ * them.
+ *
+ * Terms are cut and read with `search-query-words.ts`, the splitter the token
+ * parser itself uses, so a chip ticks for exactly what the parser applies:
+ * `is:"unread"` is the unread facet, and an `is:unread` inside a quoted value
+ * belongs to that value.
+ */
+
+import {
+	type BriefCategoryFilter,
+	isBriefCategory,
+} from "../components/app-shell-types.js";
+import type { BriefFilterId } from "../components/brief-sections.js";
+import {
+	searchTokenTerm,
+	splitSearchTerm,
+	splitSearchWords,
+} from "./search-query-words.js";
+
+interface FilterTerm {
+	id: BriefFilterId;
+	name: string;
+	value: string;
+}
+
+const FILTER_TERMS: readonly FilterTerm[] = [
+	{ id: "unread", name: "is", value: "unread" },
+	{ id: "attachment", name: "has", value: "attachment" },
+];
+
+const CATEGORY_TERM_NAME = "category";
+
+/** Category spellings beyond the ids themselves, as the token parser reads them. */
+const CATEGORY_ALIASES: Record<string, BriefCategoryFilter> = {
+	unclassified: "uncategorized",
+};
+
+const words = (query: string): string[] =>
+	splitSearchWords(query).map((word) => word.raw);
+
+const rejoin = (kept: string[]): string => kept.join(" ");
+
+/**
+ * The chip a term names, read the way the parser reads it: `is:"unread"` is the
+ * unread facet, and an `is:unread` sitting inside a quoted value is not a term
+ * at all.
+ */
+const filterOfWord = (word: string): BriefFilterId | undefined => {
+	const parts = splitSearchTerm(word);
+	if (!parts) return undefined;
+	return FILTER_TERMS.find(
+		(term) =>
+			term.name === parts.name && term.value === parts.value.toLowerCase(),
+	)?.id;
+};
+
+const categoryOfWord = (word: string): BriefCategoryFilter | undefined => {
+	const parts = splitSearchTerm(word);
+	if (!parts || parts.name !== CATEGORY_TERM_NAME) return undefined;
+	const value = parts.value.toLowerCase();
+	const alias = CATEGORY_ALIASES[value];
+	if (alias) return alias;
+	if (!isBriefCategory(value) || value === "all") return undefined;
+	return value;
+};
+
+const termFor = (id: BriefFilterId): FilterTerm | undefined =>
+	FILTER_TERMS.find((term) => term.id === id);
+
+/** Whether a chip is one the search vocabulary can express. */
+export const briefFilterHasTerm = (id: BriefFilterId): boolean =>
+	termFor(id) !== undefined;
+
+/** The chips a query's own terms tick. */
+export const briefQueryFilters = (
+	query: string,
+): ReadonlySet<BriefFilterId> => {
+	const ticked = new Set<BriefFilterId>();
+	for (const word of words(query)) {
+		const id = filterOfWord(word);
+		if (id) ticked.add(id);
+	}
+	return ticked;
+};
+
+/** The category a query is scoped to by its own terms, `"all"` when none is. */
+export const briefQueryCategory = (query: string): BriefCategoryFilter => {
+	let category: BriefCategoryFilter = "all";
+	for (const word of words(query)) {
+		const named = categoryOfWord(word);
+		if (named) category = named;
+	}
+	return category;
+};
+
+/**
+ * The query with a chip's term written in or taken out, or `undefined` when the
+ * chip has no term — the caller narrows the same rows from the panel's own
+ * state instead, rather than pressing a control that writes nothing.
+ */
+export const toggleBriefFilterInQuery = (
+	query: string,
+	id: BriefFilterId,
+): string | undefined => {
+	const term = termFor(id);
+	if (!term) return undefined;
+	const typed = words(query);
+	const kept = typed.filter((word) => filterOfWord(word) !== id);
+	if (kept.length < typed.length) return rejoin(kept);
+	return rejoin([...typed, searchTokenTerm(term.name, term.value)]);
+};
+
+/** The query scoped to one category, or with its category term taken out for `"all"`. */
+export const setBriefCategoryInQuery = (
+	query: string,
+	category: BriefCategoryFilter,
+): string => {
+	const kept = words(query).filter((word) => !categoryOfWord(word));
+	if (category === "all") return rejoin(kept);
+	return rejoin([...kept, searchTokenTerm(CATEGORY_TERM_NAME, category)]);
+};
+
+/** The query with every chip term taken out, leaving what was typed. */
+export const clearBriefFiltersInQuery = (query: string): string =>
+	rejoin(
+		words(query).filter((word) => !filterOfWord(word) && !categoryOfWord(word)),
+	);
+
+/** Whether a query is narrowing the list — the state in which chips are terms. */
+export const briefQueryIsActive = (query: string): boolean =>
+	query.trim().length > 0;
+
+/**
+ * The chips shown ticked. Under a query the terms are the whole answer for
+ * every chip that has one; the two that have none keep answering to the panel's
+ * own state, so a search never silently stops them narrowing.
+ */
+export const briefChipFilters = (input: {
+	query: string;
+	ownFilters: ReadonlySet<BriefFilterId>;
+}): ReadonlySet<BriefFilterId> => {
+	if (!briefQueryIsActive(input.query)) return input.ownFilters;
+	const ticked = new Set(briefQueryFilters(input.query));
+	for (const id of input.ownFilters) {
+		if (!briefFilterHasTerm(id)) ticked.add(id);
+	}
+	return ticked;
+};
+
+/** The category scope shown selected — the query's under a query, else the panel's. */
+export const briefChipCategory = (input: {
+	query: string;
+	ownCategory: BriefCategoryFilter;
+}): BriefCategoryFilter =>
+	briefQueryIsActive(input.query)
+		? briefQueryCategory(input.query)
+		: input.ownCategory;

package/src/lib/search-query-words.ts

@@ -0,0 +1,93 @@
+/**
+ * How a search query is cut into terms.
+ *
+ * One implementation, because two would disagree: the token parser
+ * (`web-client/src/lib/search-tokens.ts`) reads `in:"Sent Items"` as one term
+ * and the brief's chips write and remove terms of the same query
+ * (`brief-filter-query.ts`). A splitter that broke on whitespace alone would
+ * read `is:unread` inside a quoted value as a term of its own, and editing it
+ * would reach inside what the user typed between quotes.
+ *
+ * A value carrying whitespace is written in double quotes; an unterminated
+ * quote runs to the end of the input, so a value stays one term while it is
+ * still being typed.
+ */
+
+/** One whitespace-separated term of a query, with where it sits in the input. */
+export interface SearchQueryWord {
+	/** The term exactly as typed, quotes included. */
+	raw: string;
+	/** Index of the term's first character in the query. */
+	start: number;
+	/** Index just past the term's last character. */
+	end: number;
+}
+
+/** Split a query into terms on whitespace, except inside double quotes. */
+export function splitSearchWords(query: string): SearchQueryWord[] {
+	const words: SearchQueryWord[] = [];
+	let start = -1;
+	let quoted = false;
+	for (let i = 0; i < query.length; i++) {
+		const char = query[i] as string;
+		if (char === '"') {
+			quoted = !quoted;
+			if (start < 0) start = i;
+			continue;
+		}
+		if (!quoted && /\s/.test(char)) {
+			if (start >= 0) words.push({ raw: query.slice(start, i), start, end: i });
+			start = -1;
+			continue;
+		}
+		if (start < 0) start = i;
+	}
+	if (start >= 0) {
+		words.push({ raw: query.slice(start), start, end: query.length });
+	}
+	return words;
+}
+
+/** A term split at its first colon: the token name and the value as typed. */
+export interface SearchTermParts {
+	name: string;
+	/** The value with its quotes removed. */
+	value: string;
+	/** The value exactly as typed, quotes included. */
+	rawValue: string;
+}
+
+const unquote = (value: string): string => {
+	if (!value.startsWith('"')) return value;
+	const inner = value.slice(1);
+	return inner.endsWith('"') ? inner.slice(0, -1) : inner;
+};
+
+/**
+ * Split `name:value` at the first colon. A term with no colon, or one starting
+ * with a colon, is not a token attempt and returns `undefined`.
+ */
+export function splitSearchTerm(word: string): SearchTermParts | undefined {
+	const colon = word.indexOf(":");
+	if (colon <= 0) return undefined;
+	const rawValue = word.slice(colon + 1);
+	return {
+		name: word.slice(0, colon).toLowerCase(),
+		value: unquote(rawValue),
+		rawValue,
+	};
+}
+
+const needsQuotes = (value: string): boolean => /[\s"]/.test(value);
+
+/**
+ * A value as it is written in a query: quoted when it carries whitespace, bare
+ * otherwise. The inverse of the unquoting above, so a suggestion the user picks
+ * parses back to the value it was built from.
+ */
+export const quoteSearchTokenValue = (value: string): string =>
+	needsQuotes(value) ? `"${value.replace(/"/g, "")}"` : value;
+
+/** `name:value`, quoted as needed — the text a query carries for one token. */
+export const searchTokenTerm = (name: string, value: string): string =>
+	`${name}:${quoteSearchTokenValue(value)}`;