From 13652fea76c005eba84675e52d88ad9a352e44b7 Mon Sep 17 00:00:00 2001
From: Julien Wajsberg <jwajsberg@mozilla.com>
Date: Thu, 9 Jul 2026 14:33:10 +0200
Subject: [PATCH] [docs] Update `when` directive docs to reflect v3 API

The `when` directive passes the type-narrowed condition value to both
case functions since lit#4310, but the docs still showed the old
signature and example. Update the signature box and example accordingly.

Fixes #1480
---
 .../site/docs/v3/templates/directives.md           | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/packages/lit-dev-content/site/docs/v3/templates/directives.md b/packages/lit-dev-content/site/docs/v3/templates/directives.md
index 0cff6100c..2e1e518d0 100644
--- a/packages/lit-dev-content/site/docs/v3/templates/directives.md
+++ b/packages/lit-dev-content/site/docs/v3/templates/directives.md
@@ -474,11 +474,11 @@ import {when} from 'lit/directives/when.js';
 <td class="wide-cell">
 
 ```ts
-when<T, F>(
-  condition: boolean,
-  trueCase: () => T,
-  falseCase?: () => F
-)
+when<C, T, F = undefined>(
+  condition: C,
+  trueCase: (c: Exclude<C, Falsy>) => T,
+  falseCase?: (c: Extract<C, Falsy>) => F
+): C extends Falsy ? F : T
 ```
 </td>
 </tr>
@@ -493,7 +493,7 @@ Any
 </tbody>
 </table>
 
-When `condition` is true, returns the result of calling `trueCase()`, else returns the result of calling `falseCase()` if `falseCase` is defined.
+When `condition` is truthy, returns the result of calling `trueCase()`, else returns the result of calling `falseCase()` if `falseCase` is defined. The (type-narrowed) `condition` value is passed to both case functions.
 
 This is a convenience wrapper around a ternary expression that makes it a
 little nicer to write an inline conditional without an else.
@@ -502,7 +502,7 @@ little nicer to write an inline conditional without an else.
 class MyElement extends LitElement {
   render() {
     return html`
-      ${when(this.user, () => html`User: ${this.user.username}`, () => html`Sign In...`)}
+      ${when(this.user, (user) => html`User: ${user.username}`, () => html`Sign In...`)}
     `;
   }
 }