@remit/ui 0.0.44 → 0.0.46

package/package.json

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

package/src/components/filter-rule-editor.tsx

@@ -37,6 +37,12 @@ export interface FilterRuleEditorProps {
 	rule: FilterRule;
 	folders: FolderOption[];
 	preview: PreviewCount;
+	/**
+	 * Content rendered above the clause chips — the filter-from-search conversion
+	 * notice (RFC 038 D5) uses it to state what the search carried that the rule
+	 * cannot. Absent on the Organize surface, which converts nothing.
+	 */
+	notice?: ReactNode;
 	/**
 	 * Whether the deployment can serve the semantic widen (RFC 038 D4). When
 	 * false the "…and anything similar" chip is never offered — an already-present
@@ -93,6 +99,7 @@ export function FilterRuleEditor({
 	rule,
 	folders,
 	preview,
+	notice,
 	semanticAvailable = false,
 	clauseFields,
 	lifecycleLocked = false,
@@ -131,6 +138,7 @@ export function FilterRuleEditor({
 			</div>
 
 			<div className="min-h-0 flex-1 space-y-5 overflow-y-auto px-5 py-4">
+				{notice}
 				<section className="space-y-3">
 					<div className="flex flex-wrap items-center gap-1.5">
 						{rule.clauses.map((clause, index) => (

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

@@ -46,6 +46,8 @@ export interface MobileSearchViewProps {
 	onRemoveChip?: (id: string) => void;
 	/** What the search covers; see `SearchResultsProps`. Defaults to global. */
 	scope?: SearchScope;
+	/** "Make this a filter" affordance; see `SearchResultsProps`. */
+	makeFilter?: { onClick: () => void; disabledReason?: string };
 }
 
 /**
@@ -77,6 +79,7 @@ export function MobileSearchView({
 	chips,
 	onRemoveChip,
 	scope,
+	makeFilter,
 }: MobileSearchViewProps) {
 	const body = (
 		<SearchResults
@@ -88,6 +91,7 @@ export function MobileSearchView({
 			onSelectResult={onSelectResult}
 			tokens={tokens}
 			scope={scope}
+			makeFilter={makeFilter}
 		/>
 	);
 

package/src/components/search-conversion-notice.stories.tsx

@@ -0,0 +1,41 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { SearchConversionNoticeView } from "./search-conversion-notice.js";
+
+const meta = {
+	title: "Filters/Search conversion notice",
+	component: SearchConversionNoticeView,
+	parameters: { layout: "centered" },
+} satisfies Meta<typeof SearchConversionNoticeView>;
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+/** A folder-scoped search: the filter cannot be pinned to the folder. */
+export const FolderScopedOut: Story = {
+	args: { notice: { scopedOutFolder: "Archive" } },
+};
+
+/** Attribute facets that are not filter conditions, named rather than dropped silently. */
+export const DroppedFacets: Story = {
+	args: {
+		notice: {
+			droppedFacets: ["Has attachment", "Unread", "Before 2026-01-01"],
+		},
+	},
+};
+
+/** A deployment that cannot match by meaning — literal words kept, no similarity claim. */
+export const DroppedSemantic: Story = {
+	args: { notice: { droppedSemantic: true } },
+};
+
+/** Everything a rich search carried that the filter cannot. */
+export const Everything: Story = {
+	args: {
+		notice: {
+			scopedOutFolder: "Archive",
+			droppedFacets: ["Has attachment", "Before 2026-01-01"],
+			droppedSemantic: true,
+		},
+	},
+};

package/src/components/search-conversion-notice.tsx

@@ -0,0 +1,67 @@
+import { FolderInput, Info, Sparkles } from "lucide-react";
+import {
+	DROPPED_SEMANTIC_COPY,
+	droppedFacetsCopy,
+	hasConversionNotice,
+	type SearchConversionNotice,
+	scopedOutCopy,
+} from "./search-conversion.js";
+
+export interface SearchConversionNoticeProps {
+	notice: SearchConversionNotice;
+}
+
+function NoticeRow({
+	icon,
+	children,
+}: {
+	icon: React.ReactNode;
+	children: React.ReactNode;
+}) {
+	return (
+		<li className="flex items-start gap-2">
+			<span className="mt-0.5 shrink-0 text-fg-subtle" aria-hidden="true">
+				{icon}
+			</span>
+			<span>{children}</span>
+		</li>
+	);
+}
+
+/**
+ * What converting a search to a filter left behind (RFC 038 D5). Rendered above
+ * the clause chips so the user sees, before touching the rule, every part of the
+ * search the filter cannot carry: a folder scope, non-clause facets, and the
+ * semantic reach a literal clause loses. Nothing to state renders nothing.
+ * Presentational and prop-driven.
+ */
+export function SearchConversionNoticeView({
+	notice,
+}: SearchConversionNoticeProps) {
+	if (!hasConversionNotice(notice)) return null;
+
+	return (
+		<div className="rounded-md border border-line bg-surface-sunken px-3 py-2.5">
+			<p className="text-2xs font-semibold uppercase tracking-wider text-fg-subtle">
+				From your search
+			</p>
+			<ul className="mt-1.5 space-y-1.5 text-xs text-fg-muted">
+				{notice.scopedOutFolder !== undefined && (
+					<NoticeRow icon={<FolderInput className="size-3.5" />}>
+						{scopedOutCopy(notice.scopedOutFolder)}
+					</NoticeRow>
+				)}
+				{notice.droppedFacets && notice.droppedFacets.length > 0 && (
+					<NoticeRow icon={<Info className="size-3.5" />}>
+						{droppedFacetsCopy(notice.droppedFacets)}
+					</NoticeRow>
+				)}
+				{notice.droppedSemantic && (
+					<NoticeRow icon={<Sparkles className="size-3.5" />}>
+						{DROPPED_SEMANTIC_COPY}
+					</NoticeRow>
+				)}
+			</ul>
+		</div>
+	);
+}

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

@@ -0,0 +1,77 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { createElement } from "react";
+import { renderToString } from "react-dom/server";
+import {
+	DROPPED_SEMANTIC_COPY,
+	droppedFacetsCopy,
+	hasConversionNotice,
+	scopedOutCopy,
+} from "./search-conversion.js";
+import { SearchConversionNoticeView } from "./search-conversion-notice.js";
+
+/** SSR splits interpolations with comment markers; sentences read across them. */
+const render = (element: Parameters<typeof renderToString>[0]) =>
+	renderToString(element).replaceAll("<!-- -->", "");
+
+describe("search-conversion copy", () => {
+	it("names the folder a scoped search is kept out of the filter for", () => {
+		assert.match(scopedOutCopy("Archive"), /limited to Archive/);
+		assert.match(scopedOutCopy("Archive"), /any folder/i);
+	});
+
+	it("names one dropped facet in the singular", () => {
+		const copy = droppedFacetsCopy(["Has attachment"]);
+		assert.match(copy, /Has attachment isn't a filter condition/);
+		assert.match(copy, /left out/);
+	});
+
+	it("joins several dropped facets and reads plural", () => {
+		const copy = droppedFacetsCopy(["Has attachment", "Unread", "Before 2026"]);
+		assert.match(copy, /Has attachment, Unread and Before 2026 aren't/);
+	});
+
+	it("states the filter is literal-only and the reach is not carried", () => {
+		assert.match(DROPPED_SEMANTIC_COPY, /matches these words literally/i);
+		// Never claims the filter itself matches by meaning.
+		assert.match(DROPPED_SEMANTIC_COPY, /a filter can't carry that/i);
+	});
+
+	it("has nothing to say when nothing was dropped", () => {
+		assert.equal(hasConversionNotice({}), false);
+		assert.equal(hasConversionNotice({ droppedSemantic: false }), false);
+		assert.equal(hasConversionNotice({ droppedFacets: [] }), false);
+	});
+
+	it("has something to say for any single drop", () => {
+		assert.equal(hasConversionNotice({ scopedOutFolder: "Archive" }), true);
+		assert.equal(hasConversionNotice({ droppedFacets: ["Unread"] }), true);
+		assert.equal(hasConversionNotice({ droppedSemantic: true }), true);
+	});
+});
+
+describe("SearchConversionNoticeView", () => {
+	it("renders every drop the conversion recorded", () => {
+		const html = render(
+			createElement(SearchConversionNoticeView, {
+				notice: {
+					scopedOutFolder: "Archive",
+					droppedFacets: ["Has attachment"],
+					droppedSemantic: true,
+				},
+			}),
+		);
+		assert.match(html, /From your search/);
+		assert.match(html, /limited to Archive/);
+		assert.match(html, /Has attachment/);
+		assert.match(html, /left out/);
+		assert.match(html, /matches these words literally/i);
+	});
+
+	it("renders nothing when there is nothing to state", () => {
+		const html = render(
+			createElement(SearchConversionNoticeView, { notice: {} }),
+		);
+		assert.equal(html, "");
+	});
+});

package/src/components/search-conversion.ts

@@ -0,0 +1,59 @@
+/**
+ * The honest copy for turning a search into a filter (RFC 038 D5).
+ *
+ * A search carries reach a filter's clauses cannot: a folder it was limited to,
+ * attribute facets that are not clauses, and — where the deployment can embed a
+ * query at request time — semantic similarity. The conversion never drops any of
+ * that silently. This module is the vocabulary the conversion notice renders; the
+ * web-client computes which parts apply and feeds the notice.
+ */
+
+export interface SearchConversionNotice {
+	/** The folder the search was limited to, kept OUT of the filter. */
+	scopedOutFolder?: string;
+	/** Facet labels with no clause equivalent (e.g. "Has attachment", "Before 2026-01-01"). */
+	droppedFacets?: string[];
+	/**
+	 * Free text was kept as a literal `HasWords` clause, and the search had
+	 * surfaced similar mail by meaning that the literal filter cannot reproduce
+	 * (RFC 038 D5) — the "similar mail" reach is not part of the filter.
+	 */
+	droppedSemantic?: boolean;
+}
+
+/** True when the conversion left something behind worth stating. */
+export function hasConversionNotice(notice: SearchConversionNotice): boolean {
+	return (
+		notice.scopedOutFolder !== undefined ||
+		(notice.droppedFacets?.length ?? 0) > 0 ||
+		notice.droppedSemantic === true
+	);
+}
+
+/** Never silently turn a folder-scoped search into a filter that matches everywhere. */
+export function scopedOutCopy(folder: string): string {
+	return `Your search was limited to ${folder}. This filter matches these messages in any folder — it can't be pinned to one.`;
+}
+
+const joinFacets = (facets: string[]): string => {
+	if (facets.length === 1) return facets[0];
+	if (facets.length === 2) return `${facets[0]} and ${facets[1]}`;
+	return `${facets.slice(0, -1).join(", ")} and ${facets[facets.length - 1]}`;
+};
+
+/** Name each attribute facet a filter cannot express, rather than dropping it unremarked. */
+export function droppedFacetsCopy(facets: string[]): string {
+	const noun = facets.length === 1 ? "a filter condition" : "filter conditions";
+	const verb = facets.length === 1 ? "isn't" : "aren't";
+	return `${joinFacets(facets)} ${verb} ${noun}, so ${
+		facets.length === 1 ? "it was" : "they were"
+	} left out — the filter still matches everything else you searched for.`;
+}
+
+/**
+ * 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
+ * that surfaced similar mail — so it never claims a reach the filter had.
+ */
+export const DROPPED_SEMANTIC_COPY =
+	"The filter matches these words literally. Your search also found similar mail by meaning — a filter can't carry that, so it won't catch mail that means the same thing without these words.";

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

@@ -86,6 +86,42 @@ describe("SearchResults", () => {
 		);
 		assert.doesNotMatch(html, /Remove filter/);
 	});
+
+	it("offers 'Make this a filter' above active results", () => {
+		const html = renderToString(
+			createElement(SearchResults, {
+				value: "invoice",
+				sections,
+				makeFilter: { onClick: noop },
+			}),
+		);
+		assert.match(html, /Make this a filter/);
+		assert.doesNotMatch(html, /disabled=""/);
+	});
+
+	it("disables the filter offer with its reason when nothing converts", () => {
+		const html = renderToString(
+			createElement(SearchResults, {
+				value: "has:attachment",
+				sections: [{ id: "results", label: "Results", results: [] }],
+				makeFilter: { onClick: noop, disabledReason: "Add a sender or words" },
+			}),
+		);
+		assert.match(html, /Make this a filter/);
+		assert.match(html, /disabled/);
+		assert.match(html, /Add a sender or words/);
+	});
+
+	it("never offers the filter on the empty-query recent-searches view", () => {
+		const html = renderToString(
+			createElement(SearchResults, {
+				value: "",
+				recentSearches: ["invoice"],
+				makeFilter: { onClick: noop },
+			}),
+		);
+		assert.doesNotMatch(html, /Make this a filter/);
+	});
 });
 
 const spamResult: SearchResult = {

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

@@ -167,6 +167,31 @@ export const NoResults: Story = {
 	render: () => <Harness value="asdfqwer" sections={emptySections} />,
 };
 
+/** "Make this a filter" offered above active results (RFC 038 D5). */
+export const WithMakeFilter: Story = {
+	render: () => (
+		<Harness
+			value="invoice"
+			sections={resultSections}
+			makeFilter={{ onClick: () => {} }}
+		/>
+	),
+};
+
+/** The filter offer disabled — a search of only non-clause facets has nothing to convert. */
+export const MakeFilterDisabled: Story = {
+	render: () => (
+		<Harness
+			value="has:attachment"
+			sections={resultSections}
+			makeFilter={{
+				onClick: () => {},
+				disabledReason: "Add a sender or words to filter on",
+			}}
+		/>
+	),
+};
+
 /** Results still loading. */
 export const Loading: Story = {
 	render: () => <Harness value="invoice" loading />,

package/src/components/search-results.tsx

@@ -1,4 +1,4 @@
-import { ChevronDown, Clock } from "lucide-react";
+import { ChevronDown, Clock, Filter } from "lucide-react";
 import { useState } from "react";
 import { cn } from "../lib/cn.js";
 import type { FolderRole } from "./folder-role.js";
@@ -84,6 +84,48 @@ export interface SearchResultsProps {
 	tokens?: { label: string; onRemove: () => void }[];
 	/** What the search covers. Defaults to the unscoped, global search. */
 	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).
+	 */
+	makeFilter?: { onClick: () => void; disabledReason?: string };
+}
+
+/** "Make this a filter" — the conversion entry offered above active search results. */
+function MakeFilterButton({
+	onClick,
+	disabledReason,
+}: {
+	onClick: () => void;
+	disabledReason?: string;
+}) {
+	const disabled = disabledReason !== undefined;
+	return (
+		<div className="border-b border-line px-row-inset py-1.5">
+			<button
+				type="button"
+				onClick={onClick}
+				disabled={disabled}
+				title={disabledReason}
+				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"
+						: "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>
+		</div>
+	);
 }
 
 /**
@@ -195,6 +237,7 @@ export function SearchResults({
 	onSelectResult,
 	tokens,
 	scope = GLOBAL_SCOPE,
+	makeFilter,
 }: SearchResultsProps) {
 	const hasQuery = value.trim().length > 0;
 
@@ -231,10 +274,17 @@ export function SearchResults({
 	const chips = tokens && tokens.length > 0 && (
 		<SearchTokenChips tokens={tokens} />
 	);
+	const filterAction = makeFilter && (
+		<MakeFilterButton
+			onClick={makeFilter.onClick}
+			disabledReason={makeFilter.disabledReason}
+		/>
+	);
 
 	if (loading) {
 		return (
 			<div className="flex flex-col">
+				{filterAction}
 				{chips}
 				<div className="flex flex-col gap-3 px-row-inset py-4">
 					{[0, 1, 2, 3].map((row) => (
@@ -286,6 +336,7 @@ export function SearchResults({
 	if (!hasResults) {
 		return (
 			<div className="flex flex-col">
+				{filterAction}
 				{chips}
 				{spamOffer}
 				<div className="px-row-inset py-10 text-center">
@@ -302,6 +353,7 @@ export function SearchResults({
 
 	return (
 		<div className="flex flex-col">
+			{filterAction}
 			{chips}
 			{spamOffer}
 			{visibleSections

package/src/components/self-update-section.tsx

@@ -1,5 +1,6 @@
 import {
 	CheckCircle2,
+	Clock,
 	CloudOff,
 	Download,
 	ExternalLink,
@@ -152,6 +153,39 @@ export function SelfUpdateSection({
 					</SectionRow>
 				);
 
+			case "neverChecked":
+				return (
+					<SectionRow>
+						<div className="flex flex-col gap-3 sm:flex-row sm:items-center sm:justify-between">
+							<div className="flex min-w-0 items-start gap-2">
+								<Clock
+									className="mt-0.5 size-4 shrink-0 text-fg-subtle"
+									aria-hidden
+								/>
+								<p className="text-sm text-fg-muted">
+									No update check has run yet. Remit checks for updates on its
+									own in the background.
+									{state.lastCheckedAt !== undefined && (
+										<span className="text-fg-subtle">
+											{" "}
+											Last checked{" "}
+											{formatRelativeCheck(state.lastCheckedAt, now)}.
+										</span>
+									)}
+								</p>
+							</div>
+							<Button
+								variant="secondary"
+								size="sm"
+								className="shrink-0"
+								onClick={handleCheck}
+							>
+								Check now
+							</Button>
+						</div>
+					</SectionRow>
+				);
+
 			case "checkFailed":
 				return (
 					<SectionRow>

package/src/components/self-update.render.test.ts

@@ -165,6 +165,25 @@ describe("SelfUpdateSection", () => {
 		assert.doesNotMatch(html, /disabled=/);
 	});
 
+	it("states a never-checked instance without a spinner or an alert", () => {
+		// The version is the literal the backend emits before any check has run —
+		// no state file, so no authoritative version yet.
+		const html = section({ status: "neverChecked", version: "unknown" });
+		assert.match(html, /No update check has run yet/);
+		assert.match(html, /Check now/);
+		assert.doesNotMatch(html, /animate-spin/);
+		assert.doesNotMatch(html, /role="alert"/);
+	});
+
+	it("shows the last-checked time on a never-checked state when one is known", () => {
+		const html = section({
+			status: "neverChecked",
+			version: "unknown",
+			lastCheckedAt: NOW - 3_600_000,
+		});
+		assert.match(html, /Last checked/);
+	});
+
 	it("renders a failed rollback verbatim and never claims a version is running", () => {
 		const html = section({
 			status: "rollbackFailed",

package/src/components/self-update.stories.tsx

@@ -52,6 +52,16 @@ export const Checking: Story = {
 	args: withState({ status: "checking", version: CURRENT }),
 };
 
+/**
+ * A fresh, configured instance before its first automatic check has landed. The
+ * honest resting state, not a spinner: it says a check has not run and that Remit
+ * checks on its own, and offers a manual check. This is what every install shows
+ * until the updater writes its first result.
+ */
+export const NeverChecked: Story = {
+	args: withState({ status: "neverChecked", version: "unknown" }),
+};
+
 /**
  * An update exists. It is stated — version, date, one line of what changes, a
  * link to the full notes — and then it waits. Nothing here follows the user

package/src/components/self-update.ts

@@ -28,6 +28,12 @@ export type UpdateRunId = string;
 export type SelfUpdateState =
 	| { status: "upToDate"; version: string; checkedAt: number }
 	| { status: "checking"; version: string }
+	/**
+	 * A configured instance whose first automatic check has not landed yet. It is
+	 * its own resting state, never a spinner: the updater checks on a cadence, and
+	 * this is the honest account of the gap before the first result arrives.
+	 */
+	| { status: "neverChecked"; version: string; lastCheckedAt?: number }
 	| {
 			status: "checkFailed";
 			version: string;

package/src/index.ts

@@ -390,6 +390,17 @@ export {
 	SearchChipInput,
 	type SearchChipInputProps,
 } from "./components/search-chip-input.js";
+export {
+	DROPPED_SEMANTIC_COPY,
+	droppedFacetsCopy,
+	hasConversionNotice,
+	type SearchConversionNotice,
+	scopedOutCopy,
+} from "./components/search-conversion.js";
+export {
+	type SearchConversionNoticeProps,
+	SearchConversionNoticeView,
+} from "./components/search-conversion-notice.js";
 export {
 	type SearchResult,
 	SearchResultRow,