From 06c53d613e20daffdfbebaa09d4c120bddaff977 Mon Sep 17 00:00:00 2001
From: Mikael Siidorow <mikael.siidorow@teamspective.com>
Date: Mon, 7 Apr 2025 16:19:12 +0300
Subject: [PATCH 1/2] feat(macro): make select macro choices strictly typed

---
 .../src/macroJsAst.test.ts                    | 29 ++++++++++++++++
 .../src/macroJsAst.ts                         |  2 ++
 .../src/macroJsx.test.ts                      | 28 +++++++++++++++
 .../babel-plugin-lingui-macro/src/macroJsx.ts |  2 ++
 .../core/macro/__typetests__/index.test-d.tsx | 34 ++++++++++++++++++-
 packages/core/macro/index.d.ts                | 19 ++++++++---
 .../macro/__typetests__/index.test-d.tsx      | 19 +++++++++--
 packages/react/macro/index.d.ts               | 25 +++++++++++---
 8 files changed, 144 insertions(+), 14 deletions(-)

diff --git a/packages/babel-plugin-lingui-macro/src/macroJsAst.test.ts b/packages/babel-plugin-lingui-macro/src/macroJsAst.test.ts
index 3bf9464ab..850038a82 100644
--- a/packages/babel-plugin-lingui-macro/src/macroJsAst.test.ts
+++ b/packages/babel-plugin-lingui-macro/src/macroJsAst.test.ts
@@ -372,5 +372,34 @@ describe("js macro", () => {
         },
       })
     })
+
+    it("select without other", () => {
+      const exp = parseExpression(
+        `select(gender, {
+          male: "he",
+          female: "she",
+        })`
+      )
+      const tokens = tokenizeChoiceComponent(
+        (exp as NodePath<CallExpression>).node,
+        JsMacroName.select,
+        createMacroCtx()
+      )
+      expect(tokens).toMatchObject({
+        format: "select",
+        name: "gender",
+        options: expect.objectContaining({
+          female: "she",
+          male: "he",
+          offset: undefined,
+          other: "", // <- other should be filled with empty string
+        }),
+        type: "arg",
+        value: {
+          name: "gender",
+          type: "Identifier",
+        },
+      })
+    })
   })
 })
diff --git a/packages/babel-plugin-lingui-macro/src/macroJsAst.ts b/packages/babel-plugin-lingui-macro/src/macroJsAst.ts
index f1bad5ba7..2baf7581d 100644
--- a/packages/babel-plugin-lingui-macro/src/macroJsAst.ts
+++ b/packages/babel-plugin-lingui-macro/src/macroJsAst.ts
@@ -180,6 +180,8 @@ export function tokenizeChoiceComponent(
     format: format,
     options: {
       offset: undefined,
+      /** Default to fill other with empty value for compatibility with ICU spec */
+      other: "",
     },
   }
 
diff --git a/packages/babel-plugin-lingui-macro/src/macroJsx.test.ts b/packages/babel-plugin-lingui-macro/src/macroJsx.test.ts
index a3a746396..6116775ea 100644
--- a/packages/babel-plugin-lingui-macro/src/macroJsx.test.ts
+++ b/packages/babel-plugin-lingui-macro/src/macroJsx.test.ts
@@ -322,5 +322,33 @@ describe("jsx macro", () => {
         },
       })
     })
+
+    it("Select without other", () => {
+      const macro = createMacro()
+      const exp = parseExpression(
+        `<Select
+          value={gender}
+          male="he"
+          one="heone"
+          female="she"
+        />`
+      )
+      const tokens = macro.tokenizeNode(exp)
+      expect(tokens[0]).toMatchObject({
+        format: "select",
+        name: "gender",
+        options: {
+          female: "she",
+          male: "he",
+          offset: undefined,
+          other: "", // <- other should be filled with empty string
+        },
+        type: "arg",
+        value: {
+          name: "gender",
+          type: "Identifier",
+        },
+      })
+    })
   })
 })
diff --git a/packages/babel-plugin-lingui-macro/src/macroJsx.ts b/packages/babel-plugin-lingui-macro/src/macroJsx.ts
index 61fbfac84..37bb06d78 100644
--- a/packages/babel-plugin-lingui-macro/src/macroJsx.ts
+++ b/packages/babel-plugin-lingui-macro/src/macroJsx.ts
@@ -297,6 +297,8 @@ export class MacroJSX {
       value: undefined,
       options: {
         offset: undefined,
+        /** Default to fill other with empty value for compatibility with ICU spec */
+        other: "",
       },
     }
 
diff --git a/packages/core/macro/__typetests__/index.test-d.tsx b/packages/core/macro/__typetests__/index.test-d.tsx
index d60346352..730a0f540 100644
--- a/packages/core/macro/__typetests__/index.test-d.tsx
+++ b/packages/core/macro/__typetests__/index.test-d.tsx
@@ -266,7 +266,9 @@ expectType<string>(
 //// Select
 ///////////////////
 
-const gender = "male"
+type Gender = "male" | "female"
+const gender = "male" as Gender // make the type less specific on purpose
+
 expectType<string>(
   select(gender, {
     // todo: here is inconsistency between jsx macro and js.
@@ -280,6 +282,36 @@ expectType<string>(
   })
 )
 
+expectType<string>(
+  // @ts-expect-error: missing required property and other is not supplied
+  select(gender, {
+    male: "he",
+  })
+)
+
+expectType<string>(
+  // missing required property is okay, if other is supplied as fallback
+  select(gender, {
+    male: "he",
+    other: "they",
+  })
+)
+
+expectType<string>(
+  select(gender, {
+    // @ts-expect-error extra properties are not allowed
+    incorrect: "",
+  })
+)
+
+expectType<string>(
+  select(gender, {
+    // @ts-expect-error extra properties are not allowed even with other fallback
+    incorrect: "",
+    other: "they",
+  })
+)
+
 expectType<string>(
   // @ts-expect-error value could be strings only
   select(5, {
diff --git a/packages/core/macro/index.d.ts b/packages/core/macro/index.d.ts
index 8a26aa185..81ef93d4d 100644
--- a/packages/core/macro/index.d.ts
+++ b/packages/core/macro/index.d.ts
@@ -154,12 +154,21 @@ export function selectOrdinal(
   options: ChoiceOptions
 ): string
 
-type SelectOptions = {
+type SelectOptionsExhaustive<T extends string = string> = {
+  [key in T]: string
+}
+
+type SelectOptionsNonExhaustive<T extends string = string> = {
   /** Catch-all option */
   other: string
-  [matches: string]: string
+} & {
+  [key in T]?: string
 }
 
+type SelectOptions<T extends string = string> =
+  | SelectOptionsExhaustive<T>
+  | SelectOptionsNonExhaustive<T>
+
 /**
  * Selects a translation based on a value
  *
@@ -180,9 +189,9 @@ type SelectOptions = {
  * @param value The key of choices to use
  * @param choices
  */
-export function select(
-  value: string | LabeledExpression<string>,
-  choices: SelectOptions
+export function select<T extends string = string>(
+  value: T | LabeledExpression<T>,
+  choices: SelectOptions<T>
 ): string
 
 /**
diff --git a/packages/react/macro/__typetests__/index.test-d.tsx b/packages/react/macro/__typetests__/index.test-d.tsx
index 49f5e96f3..c9de22513 100644
--- a/packages/react/macro/__typetests__/index.test-d.tsx
+++ b/packages/react/macro/__typetests__/index.test-d.tsx
@@ -11,7 +11,8 @@ import {
 import React from "react"
 import { ph } from "@lingui/core/macro"
 
-const gender = "male"
+type Gender = "male" | "female"
+const gender = "male" as Gender
 const user = {
   name: "John",
 }
@@ -126,8 +127,20 @@ m = (
 // @ts-expect-error: `value` could be string only
 m = <Select value={5} other={"string"} />
 
-// @ts-expect-error: `other` required
-m = <Select value={"male"} />
+// @ts-expect-error: `other` required unless exhaustive
+m = <Select value={gender} />
+
+// @ts-expect-error: `other` required unless exhaustive
+m = <Select value={gender} _male="..." />
+
+// @ts-expect-error: `other` required unless exhaustive
+m = <Select value={gender} _female="..." />
+
+// non-exhaustive okay if other is defined
+m = <Select value={gender} _female="..." other="..." />
+
+// exhaustive okay without other
+m = <Select value={gender} _male="..." _female="..." />
 
 // @ts-expect-error: `value` required
 m = <Select other={"male"} />
diff --git a/packages/react/macro/index.d.ts b/packages/react/macro/index.d.ts
index fb8e048ab..66452714b 100644
--- a/packages/react/macro/index.d.ts
+++ b/packages/react/macro/index.d.ts
@@ -32,12 +32,25 @@ type PluralChoiceProps = {
   [digit: `_${number}`]: ReactNode
 } & CommonProps
 
-type SelectChoiceProps = {
-  value: string | LabeledExpression<string | number>
+type SelectChoiceOptionsExhaustive<T extends string = string> = {
+  [key in T as `_${key}`]: ReactNode
+}
+
+type SelectChoiceOptionsNonExhaustive<T extends string = string> = {
   /** Catch-all option */
   other: ReactNode
-  [option: `_${string}`]: ReactNode
-} & CommonProps
+} & {
+  [key in T as `_${key}`]?: ReactNode
+}
+
+type SelectChoiceOptions<T extends string = string> =
+  | SelectChoiceOptionsExhaustive<T>
+  | SelectChoiceOptionsNonExhaustive<T>
+
+type SelectChoiceProps<T extends string = string> = {
+  value: T | LabeledExpression<T>
+} & SelectChoiceOptions<T> &
+  CommonProps
 
 /**
  * Trans is the basic macro for static messages,
@@ -105,7 +118,9 @@ export const SelectOrdinal: VFC<PluralChoiceProps>
  * />
  * ```
  */
-export const Select: VFC<SelectChoiceProps>
+export const Select: {
+  <T extends string = string>(props: SelectChoiceProps<T>): React.JSX.Element
+}
 
 declare function _t(descriptor: MacroMessageDescriptor): string
 declare function _t(

From 33c0e4d0593e3dd1e2b1564c53b9fe4797f65a5c Mon Sep 17 00:00:00 2001
From: Mikael Siidorow <mikael.siidorow@teamspective.com>
Date: Tue, 8 Apr 2025 11:33:20 +0300
Subject: [PATCH 2/2] docs(macro): add docs for exhaustive select macro

---
 website/docs/ref/macro.mdx | 49 ++++++++++++++++++++++++++++++--------
 1 file changed, 39 insertions(+), 10 deletions(-)

diff --git a/website/docs/ref/macro.mdx b/website/docs/ref/macro.mdx
index 25f46fe37..99cac6f24 100644
--- a/website/docs/ref/macro.mdx
+++ b/website/docs/ref/macro.mdx
@@ -323,7 +323,7 @@ const message = t({
 The `select` macro is used to handle different forms of a message based on a value.
 
 ```ts
-select(value: string | number, options: Object)
+select(value: string, options: Object)
 ```
 
 It works like a switch statement - it selects one of the forms provided in the `options` object based on the `value`:
@@ -349,6 +349,35 @@ const message = i18n._(
 );
 ```
 
+The `select` macro can be strictly exhaustive if the fallback `other` option is not provided and the input `value` is a union type.
+
+```ts
+import { select } from "@lingui/core/macro";
+
+type ValidationError =
+  | "missingValue"
+  | "invalidEmail"
+
+const message = select(validationError, {
+  missingValue: "This field is required",
+  invalidEmail: "Invalid email address",
+});
+
+// ↓ ↓ ↓ ↓ ↓ ↓
+
+import { i18n } from "@lingui/core";
+
+const message = i18n._(
+  /*i18n*/ {
+    id: "VRptzI",
+    message: "{validationError, select, missingValue {This field is required} invalidEmail {Invalid email address} other {}}",
+    values: { validationError },
+  }
+);
+```
+
+The `other` option is left empty, for compatibility with [ICU MessageFormat](/guides/message-format).
+
 :::tip
 Use `select` inside [`t`](#t) or [`defineMessage`](#definemessage) macro if you want to add custom `id`, `context` or `comment` for translators.
 
@@ -692,15 +721,15 @@ import { Select } from "@lingui/react/macro";
 
 Available Props:
 
-| Prop name | Type   | Description                                            |
-| --------- | ------ | ------------------------------------------------------ |
-| `value`   | number | _(required)_ Value determines which form is output     |
-| `other`   | number | _(required)_ Default, catch-all form                   |
-| `_<case>` | string | Form for specific case                                 |
-| `id`      | string | Custom message ID                                      |
-| `comment` | string | Comment for translators                                |
-| `context` | string | Allows to extract the same messages with different IDs |
-| `render`  | func   | Custom render callback to render translation           |
+| Prop name | Type   | Description                                                   |
+| --------- | ------ | ------------------------------------------------------------- |
+| `value`   | number | _(required)_ Value determines which form is output            |
+| `other`   | number | Default, catch-all form, required if cases are not exhaustive |
+| `_<case>` | string | Form for specific case                                        |
+| `id`      | string | Custom message ID                                             |
+| `comment` | string | Comment for translators                                       |
+| `context` | string | Allows to extract the same messages with different IDs        |
+| `render`  | func   | Custom render callback to render translation                  |
 
 The select cases except `other` should be prefixed with underscore: `_male` or `_female`.