Add discriminated union support with when clauses (#17)

Co-authored-by: Claude Haiku 4.5 <noreply@anthropic.com>

Author: tonyfromundefined

.changeset/upset-eels-ask.md

@@ -0,0 +1,7 @@
+---
+"urlspec-vscode-extension": minor
+"@urlspec/language": minor
+"@urlspec/builder": minor
+---
+
+feat: support discriminated union with `when` syntax in page parameter

packages/builder/src/index.ts

@@ -14,13 +14,15 @@ import {
   createTypeReference,
   createUnionType,
   createURLSpecDocument,
+  createWhenClause,
   type GlobalBlock,
   type PageDeclaration,
   type ParameterDeclaration,
   type ParamTypeDeclaration,
   print,
   type Type,
   type URLSpecDocument,
+  type WhenClause,
 } from "@urlspec/language";
 
 // Re-export AST types
@@ -37,6 +39,7 @@ export type {
   TypeReference,
   UnionType,
   URLSpecDocument,
+  WhenClause,
 } from "@urlspec/language";
 // Re-export AST builder functions for convenience
 export {
@@ -49,6 +52,7 @@ export {
   createTypeReference,
   createUnionType,
   createURLSpecDocument,
+  createWhenClause,
   parsePath,
 } from "@urlspec/language";
 
@@ -61,10 +65,21 @@ export interface ParameterDefinition {
   comment?: string;
 }
 
+export interface VariantDefinition {
+  value: string;
+  parameters?: ParameterDefinition[];
+}
+
+export interface DiscriminatedVariants {
+  discriminant: string;
+  variants: VariantDefinition[];
+}
+
 export interface PageDefinition {
   name: string;
   path: string;
   parameters?: ParameterDefinition[];
+  when?: DiscriminatedVariants;
   comment?: string;
 }
 
@@ -120,14 +135,24 @@ export class URLSpec {
     }
 
     // Build pages
-    const pages: PageDeclaration[] = this.pages.map((page) =>
-      createPageDeclaration(
+    const pages: PageDeclaration[] = this.pages.map((page) => {
+      const whenClauses: WhenClause[] = page.when
+        ? page.when.variants.map((v) =>
+            createWhenClause(
+              page.when!.discriminant,
+              v.value,
+              v.parameters?.map((p) => this.buildParameter(p)) ?? [],
+            ),
+          )
+        : [];
+      return createPageDeclaration(
         page.name,
         page.path,
         page.parameters?.map((p) => this.buildParameter(p)),
         page.comment,
-      ),
-    );
+        whenClauses.length > 0 ? whenClauses : undefined,
+      );
+    });
 
     return createURLSpecDocument({
       paramTypes,