@remit/ui 0.0.42 → 0.0.43

package/package.json

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

package/src/components/filter-clause-chip.tsx

@@ -3,6 +3,7 @@ import { cn } from "../lib/cn.js";
 import { Button } from "./button.js";
 import {
 	type ClauseField,
+	clauseFieldHint,
 	clauseFieldLabel,
 	clauseFieldOrder,
 	type RuleClause,
@@ -146,6 +147,12 @@ export interface ClauseEditorProps {
 	draft: ClauseDraft;
 	/** `add` seeds a new clause; `edit` amends an existing one. */
 	mode: "add" | "edit";
+	/**
+	 * The fields offered in the picker, in menu order. Defaults to the whole
+	 * vocabulary; a consumer narrows it to the fields its deployment can actually
+	 * match, so the editor never offers a clause the backend cannot evaluate.
+	 */
+	fields?: ClauseField[];
 	onChangeField?: (field: ClauseField) => void;
 	onChangeValue?: (value: string) => void;
 	onSubmit?: () => void;
@@ -160,52 +167,57 @@ export interface ClauseEditorProps {
 export function ClauseEditor({
 	draft,
 	mode,
+	fields = clauseFieldOrder,
 	onChangeField,
 	onChangeValue,
 	onSubmit,
 	onCancel,
 }: ClauseEditorProps) {
+	const hint = clauseFieldHint(draft.field);
 	return (
-		<div className="flex flex-wrap items-center gap-2 rounded-lg border border-accent-2 bg-surface p-2">
-			<Select
-				aria-label="Clause field"
-				value={draft.field}
-				onChange={(e) => onChangeField?.(e.target.value as ClauseField)}
-				className="h-8 w-32 shrink-0"
-			>
-				{clauseFieldOrder.map((field) => (
-					<option key={field} value={field}>
-						{clauseFieldLabel(field)}
-					</option>
-				))}
-			</Select>
-			<Input
-				aria-label="Clause value"
-				value={draft.value}
-				placeholder="value…"
-				onChange={(e) => onChangeValue?.(e.target.value)}
-				onKeyDown={(e) => {
-					if (e.key === "Enter") onSubmit?.();
-				}}
-				className="h-8 min-w-40 flex-1"
-			/>
-			<Button
-				variant="primary"
-				size="sm"
-				onClick={onSubmit}
-				disabled={draft.value.trim() === ""}
-				className="shrink-0"
-			>
-				{mode === "add" ? "Add" : "Save"}
-			</Button>
-			<Button
-				variant="ghost"
-				size="sm"
-				onClick={onCancel}
-				aria-label="Cancel clause edit"
-				icon={<X className="size-4" />}
-				className="shrink-0 px-2"
-			/>
+		<div className="space-y-1.5 rounded-lg border border-accent-2 bg-surface p-2">
+			<div className="flex flex-wrap items-center gap-2">
+				<Select
+					aria-label="Clause field"
+					value={draft.field}
+					onChange={(e) => onChangeField?.(e.target.value as ClauseField)}
+					className="h-8 w-32 shrink-0"
+				>
+					{fields.map((field) => (
+						<option key={field} value={field}>
+							{clauseFieldLabel(field)}
+						</option>
+					))}
+				</Select>
+				<Input
+					aria-label="Clause value"
+					value={draft.value}
+					placeholder="value…"
+					onChange={(e) => onChangeValue?.(e.target.value)}
+					onKeyDown={(e) => {
+						if (e.key === "Enter") onSubmit?.();
+					}}
+					className="h-8 min-w-40 flex-1"
+				/>
+				<Button
+					variant="primary"
+					size="sm"
+					onClick={onSubmit}
+					disabled={draft.value.trim() === ""}
+					className="shrink-0"
+				>
+					{mode === "add" ? "Add" : "Save"}
+				</Button>
+				<Button
+					variant="ghost"
+					size="sm"
+					onClick={onCancel}
+					aria-label="Cancel clause edit"
+					icon={<X className="size-4" />}
+					className="shrink-0 px-2"
+				/>
+			</div>
+			{hint && <p className="px-0.5 text-2xs text-fg-subtle">{hint}</p>}
 		</div>
 	);
 }

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

@@ -43,6 +43,12 @@ export interface FilterRuleEditorProps {
 	 * widen still renders, marked inactive.
 	 */
 	semanticAvailable?: boolean;
+	/**
+	 * The clause fields the add/edit picker offers, in menu order. Defaults to the
+	 * whole vocabulary; a consumer narrows it to the fields its deployment can
+	 * match, so the editor never offers a clause the backend cannot evaluate.
+	 */
+	clauseFields?: ClauseField[];
 	/** The inline clause form, when adding or editing a clause. */
 	clauseEdit?: ClauseEditState;
 	onStartAddClause?: () => void;
@@ -79,6 +85,7 @@ export function FilterRuleEditor({
 	folders,
 	preview,
 	semanticAvailable = false,
+	clauseFields,
 	clauseEdit,
 	onStartAddClause,
 	onStartEditClause,
@@ -154,6 +161,7 @@ export function FilterRuleEditor({
 						<ClauseEditor
 							draft={clauseEdit.draft}
 							mode={clauseEdit.mode}
+							fields={clauseFields}
 							onChangeField={onChangeDraftField}
 							onChangeValue={onChangeDraftValue}
 							onSubmit={onSubmitClause}

package/src/components/filter-rule.render.test.ts

@@ -11,6 +11,7 @@ import {
 import { FilterPreviewCount } from "./filter-preview-count.js";
 import {
 	type ClauseField,
+	clauseFieldHint,
 	clauseFieldLabel,
 	clauseFieldOrder,
 	commitBlockedReason,
@@ -306,6 +307,62 @@ describe("ClauseEditor", () => {
 		);
 		assert.match(html, />Save</);
 	});
+
+	it("offers only the fields a consumer allows, so it never proposes a clause the backend can't match", () => {
+		const html = render(
+			createElement(ClauseEditor, {
+				draft: { field: "From", value: "" },
+				mode: "add",
+				fields: ["From", "Subject", "HasWords"],
+			}),
+		);
+		assert.match(html, />From</);
+		assert.match(html, />Subject</);
+		assert.doesNotMatch(html, /value="ListId"/);
+		assert.doesNotMatch(html, /value="FromDomain"/);
+	});
+
+	it("shows the ListId hint — what it matches and the forward-only caveat", () => {
+		const html = render(
+			createElement(ClauseEditor, {
+				draft: { field: "ListId", value: "" },
+				mode: "add",
+			}),
+		);
+		assert.match(html, /List-Id/);
+		assert.match(html, /matched as it arrives/i);
+	});
+
+	it("shows the FromDomain hint — the registrable domain, look-alikes excluded", () => {
+		const html = render(
+			createElement(ClauseEditor, {
+				draft: { field: "FromDomain", value: "" },
+				mode: "add",
+			}),
+		);
+		assert.match(html, /registrable domain/i);
+	});
+
+	it("carries no hint for the self-evident fields", () => {
+		const html = render(
+			createElement(ClauseEditor, {
+				draft: { field: "Subject", value: "" },
+				mode: "add",
+			}),
+		);
+		assert.doesNotMatch(html, /registrable domain/i);
+		assert.doesNotMatch(html, /List-Id/);
+	});
+});
+
+describe("clauseFieldHint", () => {
+	it("explains ListId and FromDomain, and leaves the plain fields unexplained", () => {
+		assert.match(clauseFieldHint("ListId") ?? "", /List-Id/);
+		assert.match(clauseFieldHint("FromDomain") ?? "", /registrable domain/i);
+		assert.equal(clauseFieldHint("From"), undefined);
+		assert.equal(clauseFieldHint("Subject"), undefined);
+		assert.equal(clauseFieldHint("HasWords"), undefined);
+	});
 });
 
 describe("FilterPreviewCount", () => {

package/src/components/filter-rule.ts

@@ -96,6 +96,23 @@ export function clauseFieldLabel(field: ClauseField): string {
 	return clauseFieldLabels[field];
 }
 
+const clauseFieldHints: Partial<Record<ClauseField, string>> = {
+	ListId:
+		"The mailing list's List-Id header, matched exactly. New mail is matched as it arrives — mail delivered before this was set up may not carry it yet.",
+	FromDomain:
+		"The sender's registrable domain — matches anyone at it, subdomains included (a look-alike like example.com.evil.test never matches).",
+};
+
+/**
+ * A one-line explanation of what a field matches, for the fields whose semantics
+ * aren't self-evident from the label. `From`, `Subject`, and `HasWords` read
+ * plainly and carry none. Never leave a control unexplained where it could
+ * surprise (ux.md).
+ */
+export function clauseFieldHint(field: ClauseField): string | undefined {
+	return clauseFieldHints[field];
+}
+
 /** The fields a new clause can be added as, in menu order. */
 export const clauseFieldOrder: ClauseField[] = [
 	"From",

package/src/index.ts

@@ -138,6 +138,7 @@ export {
 } from "./components/filter-preview-count.js";
 export {
 	type ClauseField,
+	clauseFieldHint,
 	clauseFieldLabel,
 	clauseFieldOrder,
 	commitBlockedReason,