@focus-reactive/payload-plugin-translator 0.9.1 → 0.10.0

package/README.md

@@ -16,6 +16,7 @@ It works at three levels — translate the **document** you're editing, **bulk-t
 - **Deep translation** — every localized leaf field at any nesting level (groups, arrays, blocks, tabs).
 - **Rich text** — full Lexical translation, preserving formatting and structure.
 - **Three surfaces** — a per-document popup, a bulk-collection dashboard, and a per-field control, toggled via `levels`.
+- **Single or multi target** — translate into one locale, or pick several at once, via `targetSelection`.
 - **Async or sync** — queue-based background jobs (Payload Jobs) by default, or run inline.
 - **Pluggable providers** — OpenAI built in, or implement your own.
 - **Strategies** — overwrite everything or skip locales that already have content.
@@ -143,6 +144,7 @@ Allowed on **`text`, `textarea`, and `richText`** fields (a compile error on oth
 | `levels`              | `TranslationLevel[]`  | No       | `[documentLevel(), collectionLevel()]` | Which surfaces to enable — see [Translation surfaces](#translation-surfaces-levels).                           |
 | `provenance`          | `boolean \| { slug?: string }` | No | `false` (disabled) | Opt in to recording a provenance record per translation. _Since v0.7.0._ See [Provenance](#provenance-opt-in) below. |
 | `lifecycle`           | `{ onQueued?, onCompleted?, onFailed? }` | No | `undefined` | Server-side callbacks fired around each task. _Since v0.7.0._ See [Lifecycle callbacks](#lifecycle-callbacks). |
+| `targetSelection`     | `'single' \| 'multi'` | No       | `'single'`                             | Let an editor pick several target locales in one run. _Since v0.10.0._ See [Target-language selection](#target-language-selection) below. |
 
 ```typescript
 translatorPlugin({
@@ -153,6 +155,29 @@ translatorPlugin({
 });
 ```
 
+### Target-language selection
+
+_Since v0.10.0._
+
+By default the translation forms (per-document panel and bulk dashboard) translate into **one**
+target locale per run. Set `targetSelection: 'multi'` to let an editor pick **several** target
+locales at once — the "To" field becomes a compact multi-select and the run fans out one translation
+per _(document × target locale)_.
+
+```typescript
+translatorPlugin({
+  collections: [Posts, Pages],
+  translationProvider: createOpenAIProvider({ apiKey: process.env.OPENAI_API_KEY }),
+  runner: createPayloadJobsRunner(),
+  targetSelection: "multi", // default is "single" (one target per run — unchanged)
+});
+```
+
+Fully backward-compatible and opt-in: the default `'single'` keeps today's behaviour exactly, and
+there is no schema or migration. Unknown or duplicate target locales are ignored, and the source
+locale is never translated into itself. The `/enqueue` endpoint accepts `target_lng` as either a
+single string or an array of strings, so existing API callers keep working.
+
 ### Provenance (opt-in)
 
 _Since v0.7.0._

package/dist/client/entities/translation/api/mutations/useQueueDocumentTranslation.d.ts

@@ -1,7 +1,7 @@
 type TranslationStrategy = "overwrite" | "skip_existing";
 type Variables = {
     source_lng: string;
-    target_lng: string;
+    target_lng: string | string[];
     collection_slug: string;
     collection_id: Array<string | number>;
     select_all?: boolean;

package/dist/client/entities/translation/ui/AutoTranslateMarker/AutoTranslateMarker.d.ts

@@ -5,10 +5,9 @@ type AutoTranslateMarkerProps = {
     sourceLocale: string;
 };
 /**
- * A quiet, off-to-the-side marker in the translation popups' header (document + collection): a single
- * muted icon that a collection is opted into auto-translate. The detail lives in the tooltip, not the
- * layout — this is ambient config the editor rarely needs, so it stays out of the popup's main vertical
- * flow (title / Translate / Status). Rendered only when auto-translate is enabled.
+ * A quiet, off-to-the-side marker in the translation popups' header that a collection is opted into
+ * auto-translate. The detail lives behind the icon (tap/click), not the layout — ambient config the
+ * editor rarely needs. Rendered only when auto-translate is enabled.
  */
 export declare function AutoTranslateMarker({ targets, sourceLocale }: AutoTranslateMarkerProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/client/entities/translation/ui/AutoTranslateMarker/AutoTranslateMarker.js

@@ -1,15 +1,17 @@
 "use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { AutoTranslateIcon } from "../../../../shared/lib/assets/icons/AutoTranslateIcon";
-import Tooltip from "../../../../shared/ui/Tooltip";
+import InfoPopover from "../../../../shared/ui/InfoPopover";
 import styles from "./styles.module.scss";
 /**
- * A quiet, off-to-the-side marker in the translation popups' header (document + collection): a single
- * muted icon that a collection is opted into auto-translate. The detail lives in the tooltip, not the
- * layout — this is ambient config the editor rarely needs, so it stays out of the popup's main vertical
- * flow (title / Translate / Status). Rendered only when auto-translate is enabled.
+ * A quiet, off-to-the-side marker in the translation popups' header that a collection is opted into
+ * auto-translate. The detail lives behind the icon (tap/click), not the layout — ambient config the
+ * editor rarely needs. Rendered only when auto-translate is enabled.
  */ export function AutoTranslateMarker({ targets, sourceLocale }) {
-    return /*#__PURE__*/ _jsx(Tooltip, {
+    return /*#__PURE__*/ _jsx(InfoPopover, {
+        label: "Auto-translate enabled",
+        className: styles.marker,
+        icon: /*#__PURE__*/ _jsx(AutoTranslateIcon, {}),
         content: /*#__PURE__*/ _jsxs("span", {
             className: styles.tip,
             children: [
@@ -21,12 +23,6 @@ import styles from "./styles.module.scss";
                 targets.join(" · "),
                 "."
             ]
-        }),
-        children: /*#__PURE__*/ _jsx("span", {
-            className: styles.marker,
-            tabIndex: 0,
-            "aria-label": "Auto-translate enabled",
-            children: /*#__PURE__*/ _jsx(AutoTranslateIcon, {})
         })
     });
 }

package/dist/client/entities/translation/ui/AutoTranslateMarker/styles.module.scss

@@ -1,24 +1,15 @@
-// A muted, low-emphasis header marker — no border, no fill; it sits at the edge of the title row and
-// carries all detail in its tooltip, so it never competes with the popup's main flow.
+// A muted, low-emphasis header marker at the edge of the title row; the detail lives behind the icon,
+// so it never competes with the popup's main flow. (Button reset + focus come from InfoPopover.)
 .marker {
-  display: inline-flex;
-  align-items: center;
   flex-shrink: 0;
   color: var(--theme-elevation-400, #a5a5a5);
   cursor: help;
-  outline: none;
 }
 
 .marker:hover {
   color: var(--theme-elevation-600, #6d6d6d);
 }
 
-.marker:focus-visible {
-  outline: 2px solid var(--theme-elevation-400, #a5a5a5);
-  outline-offset: 2px;
-  border-radius: 3px;
-}
-
 .tip {
   display: block;
   max-width: 15rem;
@@ -27,4 +18,4 @@
 
 .tip code {
   font-family: var(--font-mono, ui-monospace, monospace);
-}
+}

package/dist/client/features/collection-translation-form/model/schema.d.ts

@@ -1,20 +1,20 @@
 import { z } from "zod";
 export declare const validationSchema: z.ZodObject<{
     source_lng: z.ZodString;
-    target_lng: z.ZodString;
+    target_lng: z.ZodEffects<z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString, "many">]>, string | string[], string | string[]>;
     collection_slug: z.ZodString;
     strategy: z.ZodEnum<["overwrite", "skip_existing"]>;
     publish_on_translation: z.ZodDefault<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
     collection_slug: string;
     source_lng: string;
-    target_lng: string;
+    target_lng: string | string[];
     strategy: "overwrite" | "skip_existing";
     publish_on_translation: boolean;
 }, {
     collection_slug: string;
     source_lng: string;
-    target_lng: string;
+    target_lng: string | string[];
     strategy: "overwrite" | "skip_existing";
     publish_on_translation?: boolean | undefined;
 }>;

package/dist/client/features/collection-translation-form/model/schema.js

@@ -2,7 +2,14 @@ import { z } from "zod";
 import { FORM_FIELDS } from "./constants";
 export const validationSchema = z.object({
     [FORM_FIELDS.SOURCE_LNG]: z.string().nonempty(""),
-    [FORM_FIELDS.TARGET_LNG]: z.string().nonempty(""),
+    // Single mode binds a string, multi mode a string[]. Either empty shape ("" / []) is rejected with
+    // one human-readable message, so a target must always be chosen before submit (AC7).
+    [FORM_FIELDS.TARGET_LNG]: z.union([
+        z.string(),
+        z.array(z.string())
+    ]).refine((value)=>value.length > 0, {
+        message: "Select at least one language"
+    }),
     [FORM_FIELDS.HIDDEN_COLLECTION_SLUG]: z.string().nonempty(),
     [FORM_FIELDS.STRATEGY]: z.enum([
         "overwrite",

package/dist/client/features/collection-translation-form/ui/CollectionTranslationForm.d.ts

@@ -1,10 +1,12 @@
 import type { UseFormReturn } from "react-hook-form";
+import type { TargetSelectionMode } from "../../../../types/TargetSelection";
 import type { FormValues } from "../model/schema";
 type CollectionTranslationFormProps = {
     form: UseFormReturn<FormValues>;
     onSubmit: (values: FormValues) => Promise<void>;
     selectedCount: number;
     hasDrafts: boolean;
+    targetSelection: TargetSelectionMode;
 };
-export declare function CollectionTranslationForm({ form, onSubmit, selectedCount, hasDrafts, }: CollectionTranslationFormProps): import("react/jsx-runtime").JSX.Element;
+export declare function CollectionTranslationForm({ form, onSubmit, selectedCount, hasDrafts, targetSelection, }: CollectionTranslationFormProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/client/features/collection-translation-form/ui/CollectionTranslationForm.js

@@ -1,13 +1,34 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useMemo } from "react";
 import { FormProvider } from "react-hook-form";
 import { SendIcon } from "../../../shared/lib/assets/icons/SendIcon";
+import { pruneSourceFromTarget } from "../../../shared/lib/forms/pruneSourceFromTarget";
+import { useLocaleOptions } from "../../../shared/lib/payload/hooks/useLocaleOptions";
 import Button from "../../../shared/ui/Button";
-import FormSelectLocale from "../../../shared/ui/form/FormSelectLocale";
+import FormSelect from "../../../shared/ui/form/FormSelect";
+import FormMultiSelect from "../../../shared/ui/form/FormMultiSelect";
 import { FormSelectStrategy } from "../../../shared/ui/form/FormSelectStrategy";
 import { FormCheckboxPublish } from "../../../shared/ui/form/FormCheckboxPublish";
 import { FORM_FIELDS } from "../model/constants";
 import styles from "./styles.module.scss";
-export function CollectionTranslationForm({ form, onSubmit, selectedCount, hasDrafts }) {
+export function CollectionTranslationForm({ form, onSubmit, selectedCount, hasDrafts, targetSelection }) {
+    const localeOptions = useLocaleOptions();
+    const source = form.watch(FORM_FIELDS.SOURCE_LNG);
+    const targetOptions = useMemo(()=>localeOptions.filter((option)=>option.value !== source), [
+        localeOptions,
+        source
+    ]);
+    useEffect(()=>{
+        const pruned = pruneSourceFromTarget(form.getValues(FORM_FIELDS.TARGET_LNG), source);
+        if (pruned !== null) {
+            form.setValue(FORM_FIELDS.TARGET_LNG, pruned, {
+                shouldValidate: false
+            });
+        }
+    }, [
+        source,
+        form
+    ]);
     return /*#__PURE__*/ _jsx(FormProvider, {
         ...form,
         children: /*#__PURE__*/ _jsxs("fieldset", {
@@ -16,15 +37,24 @@ export function CollectionTranslationForm({ form, onSubmit, selectedCount, hasDr
                 /*#__PURE__*/ _jsxs("div", {
                     className: styles.row,
                     children: [
-                        /*#__PURE__*/ _jsx(FormSelectLocale, {
+                        /*#__PURE__*/ _jsx(FormSelect, {
                             size: "sm",
                             label: "From",
-                            name: FORM_FIELDS.SOURCE_LNG
+                            name: FORM_FIELDS.SOURCE_LNG,
+                            options: localeOptions,
+                            placeholder: "-"
                         }),
-                        /*#__PURE__*/ _jsx(FormSelectLocale, {
+                        targetSelection === "multi" ? /*#__PURE__*/ _jsx(FormMultiSelect, {
                             size: "sm",
                             label: "To",
-                            name: FORM_FIELDS.TARGET_LNG
+                            name: FORM_FIELDS.TARGET_LNG,
+                            options: targetOptions
+                        }) : /*#__PURE__*/ _jsx(FormSelect, {
+                            size: "sm",
+                            label: "To",
+                            name: FORM_FIELDS.TARGET_LNG,
+                            options: targetOptions,
+                            placeholder: "-"
                         })
                     ]
                 }),

package/dist/client/features/translate-document-form/model/schema.d.ts

@@ -1,7 +1,7 @@
 import { z } from "zod";
 export declare const validationSchema: z.ZodObject<{
     source_lng: z.ZodString;
-    target_lng: z.ZodString;
+    target_lng: z.ZodEffects<z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString, "many">]>, string | string[], string | string[]>;
     collection_id: z.ZodString;
     collection_slug: z.ZodString;
     strategy: z.ZodDefault<z.ZodEnum<["overwrite", "skip_existing"]>>;
@@ -10,14 +10,14 @@ export declare const validationSchema: z.ZodObject<{
     collection_slug: string;
     collection_id: string;
     source_lng: string;
-    target_lng: string;
+    target_lng: string | string[];
     strategy: "overwrite" | "skip_existing";
     publish_on_translation: boolean;
 }, {
     collection_slug: string;
     collection_id: string;
     source_lng: string;
-    target_lng: string;
+    target_lng: string | string[];
     strategy?: "overwrite" | "skip_existing" | undefined;
     publish_on_translation?: boolean | undefined;
 }>;

package/dist/client/features/translate-document-form/model/schema.js

@@ -2,7 +2,14 @@ import { z } from "zod";
 import { FORM_FIELDS } from "./constants";
 export const validationSchema = z.object({
     [FORM_FIELDS.SOURCE_LNG]: z.string().nonempty(),
-    [FORM_FIELDS.TARGET_LNG]: z.string().nonempty(),
+    // Single mode binds a string, multi mode a string[]. Either empty shape ("" / []) is rejected with
+    // one human-readable message, so a target must always be chosen before submit (AC7).
+    [FORM_FIELDS.TARGET_LNG]: z.union([
+        z.string(),
+        z.array(z.string())
+    ]).refine((value)=>value.length > 0, {
+        message: "Select at least one language"
+    }),
     [FORM_FIELDS.HIDDEN_COLLECTION_ID]: z.string().nonempty(),
     [FORM_FIELDS.HIDDEN_COLLECTION_SLUG]: z.string().nonempty(),
     [FORM_FIELDS.STRATEGY]: z.enum([

package/dist/client/features/translate-document-form/ui/DocumentTranslationForm.d.ts

@@ -1,9 +1,11 @@
 import type { UseFormReturn } from "react-hook-form";
+import type { TargetSelectionMode } from "../../../../types/TargetSelection";
 import type { FormValues } from "../model/schema";
 type DocumentTranslationFormProps = {
     form: UseFormReturn<FormValues>;
     onSubmit: (values: FormValues) => Promise<void>;
     hasDrafts?: boolean;
+    targetSelection: TargetSelectionMode;
 };
-export declare function DocumentTranslationForm({ form, onSubmit, hasDrafts, }: DocumentTranslationFormProps): import("react/jsx-runtime").JSX.Element;
+export declare function DocumentTranslationForm({ form, onSubmit, hasDrafts, targetSelection, }: DocumentTranslationFormProps): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/client/features/translate-document-form/ui/DocumentTranslationForm.js

@@ -1,13 +1,34 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useMemo } from "react";
 import { FormProvider } from "react-hook-form";
 import { SendIcon } from "../../../shared/lib/assets/icons/SendIcon";
+import { pruneSourceFromTarget } from "../../../shared/lib/forms/pruneSourceFromTarget";
+import { useLocaleOptions } from "../../../shared/lib/payload/hooks/useLocaleOptions";
 import Button from "../../../shared/ui/Button";
-import FormSelectLocale from "../../../shared/ui/form/FormSelectLocale";
+import FormSelect from "../../../shared/ui/form/FormSelect";
+import FormMultiSelect from "../../../shared/ui/form/FormMultiSelect";
 import { FormSelectStrategy } from "../../../shared/ui/form/FormSelectStrategy";
 import { FormCheckboxPublish } from "../../../shared/ui/form/FormCheckboxPublish";
 import { FORM_FIELDS } from "../model/constants";
 import styles from "./styles.module.scss";
-export function DocumentTranslationForm({ form, onSubmit, hasDrafts }) {
+export function DocumentTranslationForm({ form, onSubmit, hasDrafts, targetSelection }) {
+    const localeOptions = useLocaleOptions();
+    const source = form.watch(FORM_FIELDS.SOURCE_LNG);
+    const targetOptions = useMemo(()=>localeOptions.filter((option)=>option.value !== source), [
+        localeOptions,
+        source
+    ]);
+    useEffect(()=>{
+        const pruned = pruneSourceFromTarget(form.getValues(FORM_FIELDS.TARGET_LNG), source);
+        if (pruned !== null) {
+            form.setValue(FORM_FIELDS.TARGET_LNG, pruned, {
+                shouldValidate: false
+            });
+        }
+    }, [
+        source,
+        form
+    ]);
     return /*#__PURE__*/ _jsx(FormProvider, {
         ...form,
         children: /*#__PURE__*/ _jsxs("fieldset", {
@@ -16,15 +37,24 @@ export function DocumentTranslationForm({ form, onSubmit, hasDrafts }) {
                 /*#__PURE__*/ _jsxs("div", {
                     className: styles.row,
                     children: [
-                        /*#__PURE__*/ _jsx(FormSelectLocale, {
+                        /*#__PURE__*/ _jsx(FormSelect, {
                             size: "sm",
                             label: "From",
-                            name: FORM_FIELDS.SOURCE_LNG
+                            name: FORM_FIELDS.SOURCE_LNG,
+                            options: localeOptions,
+                            placeholder: "-"
                         }),
-                        /*#__PURE__*/ _jsx(FormSelectLocale, {
+                        targetSelection === "multi" ? /*#__PURE__*/ _jsx(FormMultiSelect, {
                             size: "sm",
                             label: "To",
-                            name: FORM_FIELDS.TARGET_LNG
+                            name: FORM_FIELDS.TARGET_LNG,
+                            options: targetOptions
+                        }) : /*#__PURE__*/ _jsx(FormSelect, {
+                            size: "sm",
+                            label: "To",
+                            name: FORM_FIELDS.TARGET_LNG,
+                            options: targetOptions,
+                            placeholder: "-"
                         })
                     ]
                 }),

package/dist/client/shared/lib/forms/pruneSourceFromTarget.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Remove the source locale from a target-field value so a target can never equal the source. Handles
+ * both the single (`string`) and multi (`string[]`) target shapes. Returns the pruned value, or `null`
+ * when nothing needed pruning — the caller then skips the form write to avoid a redundant update (and
+ * the re-render / validation it would trigger).
+ */
+export declare function pruneSourceFromTarget(value: string | string[], source: string): string | string[] | null;

package/dist/client/shared/lib/forms/pruneSourceFromTarget.js

@@ -0,0 +1,14 @@
+/**
+ * Remove the source locale from a target-field value so a target can never equal the source. Handles
+ * both the single (`string`) and multi (`string[]`) target shapes. Returns the pruned value, or `null`
+ * when nothing needed pruning — the caller then skips the form write to avoid a redundant update (and
+ * the re-render / validation it would trigger).
+ */ export function pruneSourceFromTarget(value, source) {
+    if (Array.isArray(value)) {
+        const filtered = value.filter((locale)=>locale !== source);
+        return filtered.length === value.length ? null : filtered;
+    }
+    return value === source ? "" : null;
+}
+
+//# sourceMappingURL=pruneSourceFromTarget.js.map

package/dist/client/shared/ui/InfoPopover/InfoPopover.d.ts

@@ -0,0 +1,21 @@
+import type { ReactNode } from "react";
+type InfoPopoverProps = {
+    /** The detail shown when the icon is activated. */
+    content: ReactNode;
+    /** Accessible name for the trigger button (the popover has no visible label). */
+    label: string;
+    /** Trigger glyph; defaults to a question mark. */
+    icon?: ReactNode;
+    side?: "top" | "bottom" | "left" | "right";
+    sideOffset?: number;
+    /** Extra class on the trigger button (icon slot styling). */
+    className?: string;
+};
+/**
+ * A click/tap info affordance: an icon button that toggles a small popover with the detail. Replaces
+ * hover-only tooltips for help text so it works on touch, is keyboard-operable, and never opens itself
+ * when a surrounding popover autofocuses it (a Popover, unlike a Tooltip, does not open on focus). For
+ * naming an icon *control*, use a Tooltip instead — this is for disclosing information.
+ */
+export default function InfoPopover({ content, label, icon, side, sideOffset, className, }: InfoPopoverProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/client/shared/ui/InfoPopover/InfoPopover.js

@@ -0,0 +1,45 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from "react";
+import * as Popover from "@radix-ui/react-popover";
+import { QuestionCircleIcon } from "../../lib/assets/icons/QuestionCircleIcon";
+import styles from "./styles.module.scss";
+/**
+ * A click/tap info affordance: an icon button that toggles a small popover with the detail. Replaces
+ * hover-only tooltips for help text so it works on touch, is keyboard-operable, and never opens itself
+ * when a surrounding popover autofocuses it (a Popover, unlike a Tooltip, does not open on focus). For
+ * naming an icon *control*, use a Tooltip instead — this is for disclosing information.
+ */ export default function InfoPopover({ content, label, icon, side = "top", sideOffset = 6, className }) {
+    const [open, setOpen] = useState(false);
+    return /*#__PURE__*/ _jsxs(Popover.Root, {
+        open: open,
+        onOpenChange: setOpen,
+        children: [
+            /*#__PURE__*/ _jsx(Popover.Trigger, {
+                asChild: true,
+                children: /*#__PURE__*/ _jsx("button", {
+                    type: "button",
+                    className: `${styles.trigger} ${className ?? ""}`,
+                    "aria-label": label,
+                    children: icon ?? /*#__PURE__*/ _jsx(QuestionCircleIcon, {})
+                })
+            }),
+            /*#__PURE__*/ _jsx(Popover.Portal, {
+                children: /*#__PURE__*/ _jsxs(Popover.Content, {
+                    className: styles.content,
+                    side: side,
+                    sideOffset: sideOffset,
+                    collisionPadding: 12,
+                    children: [
+                        content,
+                        /*#__PURE__*/ _jsx(Popover.Arrow, {
+                            className: styles.arrow
+                        })
+                    ]
+                })
+            })
+        ]
+    });
+}
+
+//# sourceMappingURL=InfoPopover.js.map

package/dist/client/shared/ui/InfoPopover/index.d.ts

@@ -0,0 +1 @@
+export { default } from "./InfoPopover";

package/dist/client/shared/ui/InfoPopover/index.js

@@ -0,0 +1,3 @@
+export { default } from "./InfoPopover";
+
+//# sourceMappingURL=index.js.map

package/dist/client/shared/ui/InfoPopover/styles.module.scss

@@ -0,0 +1,49 @@
+.trigger {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  padding: 0;
+  border: none;
+  background: none;
+  color: inherit;
+  line-height: 0;
+  // Cursor is chosen per usage (marker → pointer, `?` help icons → help) so it never loses to
+  // CSS-module source order.
+
+  &:focus-visible {
+    outline: 2px solid var(--theme-elevation-400);
+    outline-offset: 2px;
+    border-radius: 3px;
+  }
+}
+
+// Same bubble as the Tooltip, so help text looks identical whether hovered (elsewhere) or tapped here.
+.content {
+  max-width: 280px;
+  padding: 0.5rem 0.75rem;
+  border: 1px solid var(--theme-elevation-150);
+  border-radius: var(--style-radius-s);
+  background: var(--theme-elevation-50);
+  color: var(--theme-elevation-900);
+  font-size: 0.8125rem;
+  line-height: 1.4;
+  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1);
+  z-index: 9999;
+  animation: fadeIn 150ms ease-out;
+}
+
+.arrow {
+  fill: var(--theme-elevation-50);
+}
+
+@keyframes fadeIn {
+  from {
+    opacity: 0;
+    transform: translateY(2px);
+  }
+
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}

package/dist/client/shared/ui/MultiSelect/MultiSelect.d.ts

@@ -0,0 +1,40 @@
+import type { ComponentPropsWithRef } from "react";
+import type { MultiSelectOption } from "./multiSelectModel";
+export type { MultiSelectOption } from "./multiSelectModel";
+/**
+ * Props mirror the single `Select` (`ComponentPropsWithRef<"button">` + the same custom `$`-prefixed
+ * knobs), except `value`/`onChange` are omitted from the button props and redefined for a multi
+ * selection (a native `<button>` has a `string` value + a form `onChange`, incompatible with these).
+ */
+type MultiSelectProps = Omit<ComponentPropsWithRef<"button">, "value" | "onChange" | "onBlur"> & {
+    /** Selected option values (controlled). */
+    value: string[];
+    /** Next selection whenever the user toggles an option or "select all". */
+    onChange: (value: string[]) => void;
+    /**
+     * Fired when the popover CLOSES (the field is "done"), not when the trigger loses focus — opening
+     * the popover moves focus into it, and firing blur then would mark the field touched before the
+     * user has picked anything (premature `onTouched` validation).
+     */
+    onBlur?: () => void;
+    options: MultiSelectOption[];
+    /** Shown on the trigger when nothing is selected. */
+    placeholder?: string;
+    hasError?: boolean;
+    $size?: "sm" | "md" | "lg";
+    /** Stretch to fill the container (default). Set `false` to size to content. */
+    $fullWidth?: boolean;
+    /** Label for the "select all" row. */
+    selectAllLabel?: string;
+    /** Show a filter input in the popover once the option count exceeds this. */
+    filterThreshold?: number;
+};
+/**
+ * A controlled multi-select whose collapsed trigger is a `<button>` styled identically to the single
+ * `Select` (same border, chevron, focus ring, error + disabled states, size ramp). The multiplicity
+ * lives in a checkbox popover with a "select all" row and a progressive filter — the trigger shows a
+ * compact summary (`de, fr +2` / `All (N)`) and never grows with the selection. All decision logic
+ * lives in `./multiSelectModel`; the popover width tracks the trigger and grows to its content.
+ */
+declare const MultiSelect: import("react").ForwardRefExoticComponent<Omit<MultiSelectProps, "ref"> & import("react").RefAttributes<HTMLButtonElement>>;
+export default MultiSelect;