@remit/ui 0.0.42 → 0.0.44

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/ui",
-  "version": "0.0.42",
+  "version": "0.0.44",
   "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.stories.tsx

@@ -227,6 +227,26 @@ export const DegradedStandingWiden: Story = {
 	},
 };
 
+/**
+ * Editing a persisted filter (RFC 038 D6): scope and expiry render read-only,
+ * with a note that they — and the semantic anchor — are fixed at creation. The
+ * name and the literal clauses stay editable; the widen chip is display-only.
+ */
+export const LifecycleLocked: Story = {
+	args: {
+		rule: {
+			...demoRule,
+			scope: "until",
+			until: "2027-09-01",
+			name: "Conference",
+		},
+		folders: demoFolders,
+		preview: READY(31),
+		semanticAvailable: false,
+		lifecycleLocked: true,
+	},
+};
+
 /** Nothing to match yet — the commit says why it is blocked. */
 export const BlockedEmpty: Story = {
 	args: {

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

@@ -43,6 +43,21 @@ 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[];
+	/**
+	 * Render the scope and expiry read-only (RFC 038 D6). A persisted filter's
+	 * scope, expiry, and semantic anchor are fixed at creation — the update
+	 * endpoint carries none of them — so editing a filter shows them as a static
+	 * summary with a note rather than live controls that would silently discard
+	 * the change (reader #266 tracks lifting this). The name and the literal
+	 * predicate stay editable.
+	 */
+	lifecycleLocked?: boolean;
 	/** The inline clause form, when adding or editing a clause. */
 	clauseEdit?: ClauseEditState;
 	onStartAddClause?: () => void;
@@ -79,6 +94,8 @@ export function FilterRuleEditor({
 	folders,
 	preview,
 	semanticAvailable = false,
+	clauseFields,
+	lifecycleLocked = false,
 	clauseEdit,
 	onStartAddClause,
 	onStartEditClause,
@@ -154,6 +171,7 @@ export function FilterRuleEditor({
 						<ClauseEditor
 							draft={clauseEdit.draft}
 							mode={clauseEdit.mode}
+							fields={clauseFields}
 							onChangeField={onChangeDraftField}
 							onChangeValue={onChangeDraftValue}
 							onSubmit={onSubmitClause}
@@ -203,14 +221,22 @@ export function FilterRuleEditor({
 
 				<section className="space-y-2">
 					<p className="text-xs font-medium text-fg-muted">How long</p>
-					<SegmentedControl
-						name="rule-scope"
-						size="sm"
-						aria-label="Rule scope"
-						options={scopeOptions}
-						value={rule.scope}
-						onChange={(value) => onChangeScope?.(value)}
-					/>
+					{lifecycleLocked ? (
+						<p className="text-xs text-fg">
+							{rule.scope === "until"
+								? `Until ${rule.until ?? ""}`
+								: "Always — runs on matching mail"}
+						</p>
+					) : (
+						<SegmentedControl
+							name="rule-scope"
+							size="sm"
+							aria-label="Rule scope"
+							options={scopeOptions}
+							value={rule.scope}
+							onChange={(value) => onChangeScope?.(value)}
+						/>
+					)}
 					{needsName && (
 						<Input
 							value={rule.name ?? ""}
@@ -220,7 +246,7 @@ export function FilterRuleEditor({
 							className="w-full"
 						/>
 					)}
-					{rule.scope === "until" && (
+					{!lifecycleLocked && rule.scope === "until" && (
 						<div className="flex items-center gap-2 text-xs text-fg-muted">
 							<span>Until</span>
 							<Input
@@ -232,6 +258,13 @@ export function FilterRuleEditor({
 							/>
 						</div>
 					)}
+					{lifecycleLocked && (
+						<p className="text-2xs text-fg-subtle">
+							{rule.widen
+								? "The scope, expiry, and similar-mail match are set when a filter is created."
+								: "The scope and expiry are set when a filter is created."}
+						</p>
+					)}
 				</section>
 
 				<div className="border-t border-line pt-3">

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", () => {
@@ -497,6 +554,37 @@ describe("FilterRuleEditor", () => {
 	it("shows the live preview region", () => {
 		assert.match(editor(), /47 messages match/);
 	});
+
+	it("renders scope and expiry read-only when the lifecycle is locked", () => {
+		const html = editor({
+			rule: { ...demoRule, scope: "until", until: "2027-09-01" },
+			lifecycleLocked: true,
+		});
+		// No live scope toggle, no editable date input — a static summary and a note.
+		assert.doesNotMatch(html, /aria-label="Rule scope"/);
+		assert.doesNotMatch(html, /aria-label="Expiry date"/);
+		assert.match(html, /Until 2027-09-01/);
+		assert.match(html, /set when a filter is created/);
+		// The name stays editable.
+		assert.match(html, /aria-label="Rule name"/);
+	});
+
+	it("names the similar-mail match in the locked note only when a widen is present", () => {
+		const withWiden = editor({
+			rule: { ...demoRule, widen: { anchorCount: 2 } },
+			lifecycleLocked: true,
+		});
+		assert.match(
+			withWiden,
+			/similar-mail match are set when a filter is created/,
+		);
+		const literal = editor({
+			rule: { ...demoRule, widen: undefined },
+			lifecycleLocked: true,
+		});
+		assert.match(literal, /scope and expiry are set when a filter is created/);
+		assert.doesNotMatch(literal, /similar-mail match/);
+	});
 });
 
 describe("FilterRuleDialog", () => {

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,