match: Rename Match to MatchTag and add MatchValue

thetarnav · thetarnav · commit be5e956c1265 · 2025-06-12T20:20:59.000+02:00
diff --git a/packages/match/README.md b/packages/match/README.md
@@ -8,7 +8,7 @@
 [![version](https://img.shields.io/npm/v/@solid-primitives/match?style=for-the-badge)](https://www.npmjs.com/package/@solid-primitives/match)
 [![stage](https://img.shields.io/endpoint?style=for-the-badge&url=https%3A%2F%2Fraw.githubusercontent.com%2Fsolidjs-community%2Fsolid-primitives%2Fmain%2Fassets%2Fbadges%2Fstage-0.json)](https://github.com/solidjs-community/solid-primitives#contribution-process)
 
-Control-flow component for matching discriminated union (tagged union) members.
+Control-flow components for matching discriminated union (tagged union) members and union literals.
 
 ## Installation
 
@@ -20,10 +20,10 @@ yarn add @solid-primitives/match
 pnpm add @solid-primitives/match
 ```
 
-## `Match`
+## `MatchTag`
 
 Control-flow component for matching discriminated union (tagged union) members.
- 
+
 ### How to use it
 
 ```tsx
@@ -37,7 +37,7 @@ type MyUnion = {
 
 const [value, setValue] = createSignal<MyUnion>({type: "foo", foo: "foo-value"})
 
-<Match on={value()} case={{
+<MatchTag on={value()} case={{
   foo: v => <>{v().foo}</>,
   bar: v => <>{v().bar}</>,
 }} />
@@ -56,7 +56,7 @@ type MyUnion = {
   bar:  "bar-value",
 }
  
-<Match on={value()} tag="kind" case={{
+<MatchTag on={value()} tag="kind" case={{
   foo: v => <>{v().foo}</>,
   bar: v => <>{v().bar}</>,
 }} />
@@ -67,7 +67,7 @@ type MyUnion = {
 Use the `partial` prop to only handle some of the union members:
 
 ```tsx
-<Match partial on={value()} case={{
+<MatchTag partial on={value()} case={{
   foo: v => <>{v().foo}</>,
   // bar case is not handled
 }} />
@@ -78,12 +78,51 @@ Use the `partial` prop to only handle some of the union members:
 Provide a fallback element when no match is found or the value is `null`/`undefined`:
 
 ```tsx
-<Match on={value()} case={{
+<MatchTag on={value()} case={{
   foo: v => <>{v().foo}</>,
   bar: v => <>{v().bar}</>,
 }} fallback={<div>No match found</div>} />
 ```
 
+## `MatchValue`
+
+Control-flow component for matching union literals.
+
+### How to use it
+
+```tsx
+type MyUnion = "foo" | "bar";
+
+const [value, setValue] = createSignal<MyUnion>("foo");
+
+<MatchValue on={value()} case={{
+  foo: () => <p>foo</p>,
+  bar: () => <p>bar</p>,
+}} />
+```
+
+### Partial matching
+
+Use the `partial` prop to only handle some of the union members:
+
+```tsx
+<MatchValue partial on={value()} case={{
+  foo: () => <p>foo</p>,
+  // bar case is not handled
+}} />
+```
+
+### Fallback
+
+Provide a fallback element when no match is found or the value is `null`/`undefined`:
+
+```tsx
+<MatchValue on={value()} case={{
+  foo: () => <p>foo</p>,
+  bar: () => <p>bar</p>,
+}} fallback={<div>No match found</div>} />
+```
+
 ## Demo
 
 [Deployed example](https://primitives.solidjs.community/playground/match) | [Source code](https://github.com/solidjs-community/solid-primitives/tree/main/packages/match/dev)
diff --git a/packages/match/dev/index.tsx b/packages/match/dev/index.tsx
@@ -1,5 +1,5 @@
 import { Component, createSignal } from "solid-js";
-import { Match } from "../src/index.js"
+import { MatchTag, MatchValue } from "../src/index.js";
 
 type AnimalDog = {type: 'dog', breed: string};
 type AnimalCat = {type: 'cat', lives: number};
@@ -75,7 +75,7 @@ const App: Component = () => {
             <h2 class="text-xl font-semibold mb-1">Complete Match</h2>
             <p class="text-sm mb-4">Handles all union members with fallback</p>
             <div class="border border-gray-500 border-2 rounded p-4 min-h-[100px] flex items-center justify-center">
-              <Match on={animal()} case={{
+              <MatchTag on={animal()} case={{
                 dog: v => <DogDisplay animal={v()} />,
                 cat: v => <CatDisplay animal={v()} />,
                 bird: v => <BirdDisplay animal={v()} />,
@@ -87,13 +87,25 @@ const App: Component = () => {
             <h2 class="text-xl font-semibold mb-1">Partial Match</h2>
             <p class="text-sm mb-4">Only handles dogs and cats</p>
             <div class="border border-gray-500 border-2 rounded p-4 min-h-[100px] flex items-center justify-center">
-              <Match partial on={animal()} case={{
+              <MatchTag partial on={animal()} case={{
                 dog: v => <DogDisplay animal={v()} />,
                 cat: v => <CatDisplay animal={v()} />,
               }} fallback={<FallbackDisplay />} />
             </div>
           </div>
         </div>
+
+        <div class="mt-8 border border-gray-500 border-2 rounded-lg p-6">
+          <h2 class="text-xl font-semibold mb-1">Value Match</h2>
+          <p class="text-sm mb-4">Match on union literals</p>
+          <div class="border border-gray-500 border-2 rounded p-4 min-h-[100px] flex items-center justify-center">
+            <MatchValue on={animal()?.type} case={{
+              dog:  () => <p>🐕</p>,
+              cat:  () => <p>🐱</p>,
+              bird: () => <p>🐦</p>,
+            }} fallback={<FallbackDisplay />} />
+          </div>
+        </div>
       </div>
     </div>
   );
diff --git a/packages/match/src/index.ts b/packages/match/src/index.ts
@@ -21,43 +21,75 @@ import { type Accessor, type JSX, createMemo } from "solid-js"
  * }} />
  * ```
  */
-export function Match<
-	T extends {[k in Tag]: PropertyKey},
-	Tag extends PropertyKey,
+export function MatchTag<
+  T extends {[k in Tag]: PropertyKey},
+  Tag extends PropertyKey,
 >(props: {
-	on:   T | null | undefined,
-	tag:  Tag,
-	case: {[K in T[Tag]]: (v: Accessor<T & {[k in Tag]: K}>) => JSX.Element},
+  on:        T | null | undefined,
+  tag:       Tag,
+  case:      {[K in T[Tag]]: (v: Accessor<T & {[k in Tag]: K}>) => JSX.Element},
   fallback?: JSX.Element,
-  partial?: false,
+  partial?:  false,
 }): JSX.Element
-export function Match<
-	T extends {type: PropertyKey},
+export function MatchTag<
+  T extends {type: PropertyKey},
 >(props: {
-	on:   T | null | undefined,
-	case: {[K in T['type']]: (v: Accessor<T & {[k in 'type']: K}>) => JSX.Element},
+  on:        T | null | undefined,
+  case:      {[K in T['type']]: (v: Accessor<T & {[k in 'type']: K}>) => JSX.Element},
   fallback?: JSX.Element,
-  partial?: false,
+  partial?:  false,
 }): JSX.Element
-export function Match<
-	T extends {[k in Tag]: PropertyKey},
-	Tag extends PropertyKey,
+export function MatchTag<
+  T extends {[k in Tag]: PropertyKey},
+  Tag extends PropertyKey,
 >(props: {
-	on:   T | null | undefined,
-	tag:  Tag,
-	case: {[K in T[Tag]]?: (v: Accessor<T & {[k in Tag]: K}>) => JSX.Element},
+  on:        T | null | undefined,
+  tag:       Tag,
+  case:      {[K in T[Tag]]?: (v: Accessor<T & {[k in Tag]: K}>) => JSX.Element},
   fallback?: JSX.Element,
-  partial: true,
+  partial:   true,
 }): JSX.Element
-export function Match<
-	T extends {type: PropertyKey},
+export function MatchTag<
+  T extends {type: PropertyKey},
 >(props: {
-	on:   T | null | undefined,
-	case: {[K in T['type']]?: (v: Accessor<T & {[k in 'type']: K}>) => JSX.Element},
+  on:        T | null | undefined,
+  case:      {[K in T['type']]?: (v: Accessor<T & {[k in 'type']: K}>) => JSX.Element},
   fallback?: JSX.Element,
-  partial: true,
+  partial:   true,
 }): JSX.Element
-export function Match(props: any): any {
-	const kind = createMemo(() => props.on?.[props.tag ?? 'type'])
-	return createMemo(() => props.case[kind()]?.(() => props.on) ?? props.fallback)
+export function MatchTag(props: any): any {
+  const kind = createMemo(() => props.on?.[props.tag ?? 'type'])
+  return createMemo(() => props.case[kind()]?.(() => props.on) ?? props.fallback)
+}
+
+/**
+ * Control-flow component for matching union literals.
+ * 
+ * @example
+ * ```tsx
+ * type MyUnion = 'foo' | 'bar'
+ *
+ * const [value, setValue] = createSignal<MyUnion>('foo')
+ *
+ * <Match on={value()} case={{
+ *   foo: () => <p>foo</p>,
+ *   bar: () => <p>bar</p>,
+ * }} />
+ * ```
+ */
+export function MatchValue<T extends PropertyKey>(props: {
+  on:        T | null | undefined,
+  case:      {[K in T]: (v: K) => JSX.Element},
+  fallback?: JSX.Element,
+  partial?:  false,
+}): JSX.Element
+export function MatchValue<T extends PropertyKey>(props: {
+  on:        T | null | undefined,
+  case:      {[K in T]?: (v: K) => JSX.Element},
+  fallback?: JSX.Element,
+  partial:   true,
+}): JSX.Element
+export function MatchValue(props: any): any {
+  const kind = createMemo(() => props.on)
+  return createMemo(() => props.case[kind()]?.(kind()) ?? props.fallback)
 }
diff --git a/packages/match/test/index.test.tsx b/packages/match/test/index.test.tsx
@@ -1,6 +1,6 @@
 import * as v from "vitest";
 import * as s from "solid-js";
-import { Match } from "../src/index.js";
+import { MatchTag, MatchValue } from "../src/index.js";
 
 v.describe("Match", () => {
   v.test("match on type field", () => {
@@ -19,7 +19,7 @@ v.describe("Match", () => {
       return {
         dispose,
         result: s.children(() => <>
-          <Match on={value()} case={{
+          <MatchTag on={value()} case={{
             foo: v => <>{v().foo}</>,
             bar: v => <>{v().bar}</>,
           }} />
@@ -54,7 +54,7 @@ v.describe("Match", () => {
       return {
         dispose,
         result: s.children(() => <>
-          <Match on={value()} tag='kind' case={{
+          <MatchTag on={value()} tag='kind' case={{
             foo: v => <>{v().foo}</>,
             bar: v => <>{v().bar}</>,
           }} />
@@ -89,7 +89,7 @@ v.describe("Match", () => {
       return {
         dispose,
         result: s.children(() => <>
-          <Match partial on={value()} case={{
+          <MatchTag partial on={value()} case={{
             foo: v => <>{v().foo}</>,
           }} />
         </>)
@@ -123,7 +123,7 @@ v.describe("Match", () => {
       return {
         dispose,
         result: s.children(() => <>
-          <Match on={value()} case={{
+          <MatchTag on={value()} case={{
             foo: v => <>{v().foo}</>,
             bar: v => <>{v().bar}</>,
           }} fallback={<>fallback</>} />
@@ -142,3 +142,64 @@ v.describe("Match", () => {
     data.dispose();
   });
 });
+
+v.describe("MatchValue", () => {
+  v.test("match on union literal", () => {
+    type MyUnion = 'foo' | 'bar'
+    const [value, setValue] = s.createSignal<MyUnion>()
+    const data = s.createRoot(dispose => ({
+      dispose,
+      result: s.children(() => <>
+        <MatchValue on={value()} case={{
+          foo: () => <p>foo</p>,
+          bar: () => <p>bar</p>,
+        }} />
+      </>)
+    }))
+    v.expect(data.result()).toEqual(undefined)
+    setValue('foo')
+    v.expect(data.result()).toEqual(<><p>foo</p></>)
+    setValue('bar')
+    v.expect(data.result()).toEqual(<><p>bar</p></>)
+    data.dispose()
+  })
+
+  v.test("partial match", () => {
+    type MyUnion = 'foo' | 'bar'
+    const [value, setValue] = s.createSignal<MyUnion>()
+    const data = s.createRoot(dispose => ({
+      dispose,
+      result: s.children(() => <>
+        <MatchValue partial on={value()} case={{
+          foo: () => <p>foo</p>,
+        }} />
+      </>)
+    }))
+    v.expect(data.result()).toEqual(undefined)
+    setValue('foo')
+    v.expect(data.result()).toEqual(<><p>foo</p></>)
+    setValue('bar')
+    v.expect(data.result()).toEqual(undefined)
+    data.dispose()
+  })
+
+  v.test("fallback", () => {
+    type MyUnion = 'foo' | 'bar'
+    const [value, setValue] = s.createSignal<MyUnion>()
+    const data = s.createRoot(dispose => ({
+      dispose,
+      result: s.children(() => <>
+        <MatchValue on={value()} case={{
+          foo: () => <p>foo</p>,
+          bar: () => <p>bar</p>,
+        }} fallback={<p>fallback</p>} />
+      </>)
+    }))
+    v.expect(data.result()).toEqual(<><p>fallback</p></>)
+    setValue('foo')
+    v.expect(data.result()).toEqual(<><p>foo</p></>)
+    setValue(undefined)
+    v.expect(data.result()).toEqual(<><p>fallback</p></>)
+    data.dispose()
+  })
+})
