sveltekit-discriminated-fields 0.1.2 → 0.3.0

package/README.md

@@ -2,16 +2,36 @@
 
 Type-safe discriminated union support for SvelteKit remote function form fields.
 
-## The Problem
+This library provides two complementary tools for working with discriminated unions in SvelteKit forms:
 
-When using SvelteKit's remote function `form()` with discriminated union schemas (e.g., Zod's `z.discriminatedUnion`), the generated `fields` object is a **union of field objects**. TypeScript only allows access to properties that exist on ALL variants - meaning variant-specific fields are completely inaccessible.
+- **`discriminated()`** - A wrapper function that enables proper TypeScript type narrowing on form field objects
+- **`FieldVariants`** - A component that renders variant-specific form sections with CSS-only visibility, supporting progressive enhancement (works without JavaScript)
 
-Given a typical SvelteKit setup:
+The implementation prioritises:
+
+- **Static type safety** - Catch errors at compile time with clear error messages
+- **Progressive enhancement** - Forms work identically with or without JavaScript
+- **Minimal boilerplate** - Simple API that stays out of your way
+- **Flexibility** - Use as much or as little as you need
+
+This library exposes existing SvelteKit form behaviour with improved typing for discriminated unions. Runtime overhead is minimal - just a thin proxy wrapper.
+
+## Installation
+
+```bash
+npm install sveltekit-discriminated-fields
+```
+
+## FieldVariants Component
+
+The `FieldVariants` component provides declarative variant rendering with **full progressive enhancement support**. It uses CSS-only visibility toggling via `form:has()` selectors, so forms work identically with or without JavaScript enabled.
+
+Given a SvelteKit remote function using Zod (this library also works with [Valibot](./test/src/routes/valibot-form) or other validation libraries):
 
 ```typescript
 // data.remote.ts
 import { z } from "zod";
-import { form } from "$app/server/remote";
+import { form } from "$app/server";
 
 const shapeSchema = z.discriminatedUnion("kind", [
   z.object({ kind: z.literal("circle"), radius: z.number() }),
@@ -24,152 +44,327 @@ const shapeSchema = z.discriminatedUnion("kind", [
 ]);
 
 export const shapeForm = form(shapeSchema, async (data) => {
-  // handle form submission
+  // handle submission
 });
 ```
 
+Use `FieldVariants` to render variant-specific fields:
+
 ```svelte
-<!-- +page.svelte (without this library) -->
 <script lang="ts">
-  import { shapeForm } from './data.remote.ts';
+  import { shapeForm } from './data.remote';
+  import { FieldVariants } from 'sveltekit-discriminated-fields';
+</script>
+
+<form {...shapeForm}>
+  <select {...shapeForm.fields.kind.as('select')}>
+    <option value="">Select a shape...</option>
+    <option value="circle">Circle</option>
+    <option value="rectangle">Rectangle</option>
+    <option value="point">Point</option>
+  </select>
+
+  <FieldVariants fields={shapeForm.fields} key="kind">
+    {#snippet fallback(props)}
+      <p {...props}>Please select a shape type above.</p>
+    {/snippet}
+
+    {#snippet circle(v)}
+      <label {...v}>
+        Radius: <input {...v.fields.radius.as('number')} />
+      </label>
+    {/snippet}
+
+    {#snippet rectangle(v)}
+      <div {...v}>
+        <input {...v.fields.width.as('number')} placeholder="Width" />
+        <input {...v.fields.height.as('number')} placeholder="Height" />
+      </div>
+    {/snippet}
+
+    {#snippet point(v)}
+      <p {...v}>Point has no additional fields.</p>
+    {/snippet}
+  </FieldVariants>
+
+  <button type="submit">Submit</button>
+</form>
+```
+
+### Snippet Parameters
+
+Each variant snippet receives a single argument that mirrors how forms work in SvelteKit:
+
+- **Spread for CSS targeting**: `{...v}` - Adds the `data-fv` attribute for CSS visibility
+- **Access fields**: `v.fields.radius` - Provides the variant-specific form fields
+
+This pattern is consistent with how you use forms: `<form {...form}>` + `form.fields.x`.
+
+### Snippets and Fields
+
+Each snippet receives correctly narrowed fields for that variant - TypeScript knows `v.fields.radius` exists in the `circle` snippet but not in `rectangle`. Only valid discriminator values are accepted.
 
-  const form = shapeForm();
-  const shape = form.fields;
+Snippets only receive fields **specific to that variant**. Fields common to all variants (same name and type) should be rendered outside `FieldVariants` to prevent accidental duplicate inputs. Fields shared by some but not all variants, or with differing types across variants, produce compile-time errors.
+
+### Radio Buttons
+
+For radio button discriminators, you must use the `discriminated()` wrapper. The raw SvelteKit field object's `.as("radio", value)` method doesn't work with discriminated unions (causes a static error). The wrapped version is type-safe - only valid discriminator values are accepted:
+
+```svelte
+<script lang="ts">
+  import { shapeForm } from './data.remote';
+  import { discriminated, FieldVariants } from 'sveltekit-discriminated-fields';
+
+  const shape = $derived(discriminated('kind', shapeForm.fields));
 </script>
 
-<select {...shape.kind.as('select')}>
-  <option value="circle">Circle</option>
-  <option value="rectangle">Rectangle</option>
+<form {...shapeForm}>
+  <fieldset>
+    <label><input {...shape.kind.as("radio", "circle")} /> Circle</label>
+    <label><input {...shape.kind.as("radio", "rectangle")} /> Rectangle</label>
+    <label><input {...shape.kind.as("radio", "point")} /> Point</label>
+  </fieldset>
+
+  <FieldVariants fields={shape} key="kind">
+    {#snippet fallback(props)}
+      <p {...props}>Select a shape type</p>
+    {/snippet}
+
+    {#snippet circle(v)}
+      <label {...v}>
+        Radius: <input {...v.fields.radius.as('number')} />
+      </label>
+    {/snippet}
+
+    <!-- other snippets -->
+  </FieldVariants>
+</form>
+```
+
+See the [radio-form example](./test/src/routes/radio-form) for a complete working example.
+
+### Select Options
+
+For select elements, you can use `.as("option", value)` for type-safe option values. This is optional - you can still use `value="..."` directly if you prefer:
+
+```svelte
+<select {...shape.kind.as("select")}>
+  <!-- Type-safe: typos caught at compile time -->
+  <option {...shape.kind.as("option")}>Select a shape...</option>
+  <option {...shape.kind.as("option", "circle")}>Circle</option>
+  <option {...shape.kind.as("option", "rectangle")}>Rectangle</option>
+
+  <!-- Also works: standard HTML (no type checking) -->
   <option value="point">Point</option>
 </select>
+```
 
-{#if shape.kind.value() === 'circle'}
-  <!-- ERROR: Property 'radius' does not exist on type 'ShapeFields' -->
-  <input {...shape.radius.as('number')} />
-{:else if shape.kind.value() === 'rectangle'}
-  <!-- ERROR: Property 'width' does not exist on type 'ShapeFields' -->
-  <input {...shape.width.as('number')} />
-{/if}
+- `as("option")` returns `{ value: "" }` for the placeholder option
+- `as("option", "circle")` returns `{ value: "circle" }` with type checking
+
+### CSS-Based Visibility
+
+`FieldVariants` uses `form:has()` CSS selectors to show/hide variant sections based on the selected discriminator value. This works automatically for any layout - the discriminator input and variant sections can be anywhere within the same `<form>`.
+
+```svelte
+<form {...shapeForm}>
+  <div class="header">
+    <select {...shapeForm.fields.kind.as('select')}>
+      <!-- options -->
+    </select>
+  </div>
+
+  <div class="body">
+    <!-- Works regardless of DOM structure -->
+    <FieldVariants fields={shapeForm.fields} key="kind">
+      <!-- snippets -->
+    </FieldVariants>
+  </div>
+</form>
 ```
 
-The issue: `shape.kind.value() === 'circle'` doesn't narrow the type because method calls don't provide TypeScript control flow analysis. You're stuck - variant-specific fields are inaccessible, and there's no way to narrow to access them.
+See the [selector-form example](./test/src/routes/selector-form) for select elements or [selector-radio-form example](./test/src/routes/selector-radio-form) for radio buttons.
 
-## The Solution
+### Nested and Multiple Unions
 
-This library wraps your discriminated union fields to:
+The discriminated union doesn't need to be the top-level schema. It can be nested within a larger object:
 
-1. Make all variant fields accessible
-2. Add a `${key}Value` property that enables TypeScript narrowing
+```typescript
+const orderSchema = z.object({
+  orderId: z.string(),
+  shipping: z.discriminatedUnion("method", [
+    z.object({ method: z.literal("pickup"), store: z.string() }),
+    z.object({ method: z.literal("delivery"), address: z.string() }),
+  ]),
+});
+```
 
 ```svelte
-<!-- +page.svelte (with this library) -->
 <script lang="ts">
-  import { shapeForm } from './data.remote.ts';
-  import { discriminatedFields } from 'sveltekit-discriminated-fields';  // +
+  import { discriminated, FieldVariants } from 'sveltekit-discriminated-fields';
 
-  const form = shapeForm();
-  const shape = discriminatedFields('kind', form.fields);                 // changed
+  const shipping = $derived(discriminated('method', orderForm.fields.shipping));
 </script>
 
-<select {...shape.kind.as('select')}>
-  <option value="circle">Circle</option>
-  <option value="rectangle">Rectangle</option>
-  <option value="point">Point</option>
-</select>
+<FieldVariants fields={shipping} key="method">
+  {#snippet pickup(v)}
+    <input {...v} {...v.fields.store.as('text')} />
+  {/snippet}
 
-{#if shape.kindValue === 'circle'}<!-- changed -->
-  <input {...shape.radius.as('number')} /><!-- now works! -->
-{:else if shape.kindValue === 'rectangle'}<!-- changed -->
-  <input {...shape.width.as('number')} /><!-- now works! -->
-  <input {...shape.height.as('number')} />
-  <!-- ERROR: Property 'radius' does not exist - correctly rejected -->
-  <input {...shape.radius.as('number')} />
-{/if}
+  {#snippet delivery(v)}
+    <input {...v} {...v.fields.address.as('text')} />
+  {/snippet}
+</FieldVariants>
 ```
 
-The changes:
+You can also have multiple discriminated unions in the same form, or even a discriminated union nested within another discriminated union. See the [nested-form example](./test/src/routes/nested-form) for nested unions within objects, or [nested-union-form example](./test/src/routes/nested-union-form) for a union inside a union.
 
-1. Import `discriminatedFields` from this library
-2. Wrap `form.fields` with `discriminatedFields('kind', ...)`
-3. Use `shape.kindValue` instead of `shape.kind.value()` for narrowing
+### Partial Variants
 
-## Installation
+By default, `FieldVariants` requires a snippet for every variant - a compile error appears if one is missing, helping you avoid omissions. When you intentionally want to handle only some variants, use `partial={true}`:
 
-```bash
-npm install sveltekit-discriminated-fields
+```svelte
+<FieldVariants fields={shape} key="kind" partial={true}>
+  {#snippet circle(v)}
+    <input {...v} {...v.fields.radius.as('number')} />
+  {/snippet}
+
+  {#snippet rectangle(v)}
+    <input {...v} {...v.fields.width.as('number')} />
+  {/snippet}
+
+  <!-- point snippet omitted - nothing shown when point selected -->
+</FieldVariants>
 ```
 
-## Usage
+### Progressive Enhancement
+
+`FieldVariants` provides true progressive enhancement:
+
+1. **Before JavaScript loads**: All variant snippets are rendered, CSS handles visibility
+2. **After JavaScript hydrates**: Switches to conditional rendering, enabling Svelte transitions
+
+This means forms work without JavaScript, but once JS loads, you get full Svelte features:
 
 ```svelte
-<script lang="ts">
-  import { paymentForm } from './data.remote.ts';
-  import { discriminatedFields } from 'sveltekit-discriminated-fields';
+<FieldVariants fields={shape} key="kind">
+  {#snippet circle(v)}
+    <!-- Svelte transitions work after hydration -->
+    <div {...v} transition:slide>
+      <input {...v.fields.radius.as('number')} />
+    </div>
+  {/snippet}
+</FieldVariants>
+```
 
-  const form = paymentForm();
+### Disabling CSS
 
-  // Wrap fields with $derived for reactivity
-  // The first argument is your discriminator key (e.g., 'type', 'kind', 'channel')
-  const payment = $derived(discriminatedFields('type', form.fields));
+If you want to handle visibility yourself, disable CSS generation:
 
-  function setCardDefaults() {
-    // set() is type-safe - TypeScript enforces correct fields for each variant
-    payment.set({ type: 'card', cardNumber: '', cvv: '' });
-  }
-</script>
+```svelte
+<FieldVariants fields={shape} key="kind" css={false}>
+  <!-- snippets -->
+</FieldVariants>
+```
 
-<!-- typeValue is undefined until form is initialized -->
-{#if payment.typeValue === undefined}
-  <p>Loading...</p>
-{:else}
-  <select {...payment.type.as('select')}>
-    <option value="card">Card</option>
-    <option value="bank">Bank Transfer</option>
-  </select>
+## discriminated Function
+
+When using SvelteKit's remote function `form()` with discriminated union schemas, the generated `fields` object is a union of field objects. TypeScript only allows access to properties that exist on ALL variants - meaning variant-specific fields are inaccessible, and `.as("radio", value)` doesn't work.
+
+The `discriminated()` function wraps your form fields to:
 
-  <!-- Use typeValue (not type.value()) for type narrowing -->
-  {#if payment.typeValue === 'card'}
-    <input {...payment.cardNumber.as('string')} />
-    <input {...payment.cvv.as('string')} />
-  {:else if payment.typeValue === 'bank'}
-    <input {...payment.accountNumber.as('string')} />
-    <input {...payment.sortCode.as('string')} />
-  {/if}
+1. Make all variant fields accessible
+2. Add a `${key}Value` property that enables TypeScript narrowing
+3. Provide a type-safe `set()` method for programmatic updates
+4. Fix `.as("radio", value)` to accept only valid discriminator values
+
+The following example demonstrates conditionally rendering variant-specific fields with type-safe narrowing, without using `FieldVariants`. This approach requires JavaScript (unlike `FieldVariants` which works without JS):
+
+```svelte
+<script lang="ts">
+  import { shapeForm } from './data.remote';
+  import { discriminated } from 'sveltekit-discriminated-fields';
+
+  const shape = $derived(discriminated('kind', shapeForm.fields));
+</script>
+
+<!-- Use kindValue (not kind.value()) for type narrowing -->
+{#if shape.kindValue === 'circle'}
+  <input {...shape.radius.as('number')} /> <!-- TypeScript knows radius exists -->
+{:else if shape.kindValue === 'rectangle'}
+  <input {...shape.width.as('number')} />  <!-- TypeScript knows width exists -->
+  <input {...shape.height.as('number')} />
 {/if}
 ```
 
+See the [programmatic-form example](./test/src/routes/programmatic-form) for usage of `set()` and other programmatic features.
+
 ## API
 
-### `discriminatedFields(key, fields)`
+### `FieldVariants`
+
+A component for rendering variant-specific form sections with CSS-only visibility.
+
+**Props:**
+
+| Prop      | Type                  | Description                                               |
+| --------- | --------------------- | --------------------------------------------------------- |
+| `fields`  | `DiscriminatedFields` | Form fields (raw or wrapped with `discriminated()`)       |
+| `key`     | `string`              | The discriminator key (must match a field in the schema)  |
+| `partial` | `boolean` (optional)  | Allow missing snippets for some variants (default: false) |
+| `css`     | `boolean` (optional)  | Enable CSS visibility generation (default: true)          |
+
+**Snippets:**
+
+- `fallback(props)` - Rendered when no variant is selected. Spread `props` onto your element.
+- `{variantName}(v)` - One snippet per variant. Spread `v` onto your container, access fields via `v.fields`.
+
+### `discriminated(key, fields)`
 
 Wraps discriminated union form fields for type-safe narrowing.
 
 **Parameters:**
 
-- `key` - The discriminator key (e.g., `'type'`, `'kind'`, `'channel'`)
+- `key` - The discriminator key (must exist as a field in all variants)
 - `fields` - Form fields from a discriminated union schema
 
 **Returns:** A proxy object with:
 
 - All original fields passed through unchanged
 - `${key}Value` - The current discriminator value (for narrowing)
-- `set()` - Type-safe setter that infers variant from discriminator
+- `set(data)` - Type-safe setter that infers variant from discriminator
+- `allIssues()` - All validation issues for the discriminated fields
 
 ### `DiscriminatedData<T>`
 
 Type helper that extracts the underlying data type from wrapped fields:
 
 ```typescript
-const payment = discriminatedFields('type', form.fields);
+const payment = discriminated("type", form.fields);
 type Payment = DiscriminatedData<typeof payment>;
-// { type: 'card'; cardNumber: string; cvv: string } | { type: 'bank'; accountNumber: string; sortCode: string }
+// { type: 'card'; cardNumber: string; cvv: string } | { type: 'bank'; ... }
+```
+
+### `VariantSnippetArg<T>`
+
+Type for the argument passed to variant snippets:
+
+```typescript
+// v can be spread onto elements and has a .fields property
+type VariantSnippetArg<T> = VariantProps & { readonly fields: T };
 ```
 
-Useful when you need to reference the data type elsewhere, such as defining default values or passing data to other functions.
+## Migration from v0.1
 
-## Note on Runtime Behavior
+If upgrading from v0.1:
 
-Type narrowing is compile-time only. At runtime, `'width' in shape` will return `true` even when `kindValue === 'circle'`, because all variant fields exist on the underlying object.
+1. Rename `UnionVariants` to `FieldVariants`
+2. Rename `discriminatedFields()` to `discriminated()`
+3. Remove the `selector` prop (no longer needed - `form:has()` handles all layouts)
+4. Update snippet signatures:
+   - Old: `{#snippet circle(fields)} <input {...fields.radius.as('number')} />`
+   - New: `{#snippet circle(v)} <div {...v}><input {...v.fields.radius.as('number')} /></div>`
+5. Add `props` parameter to fallback and spread it: `{#snippet fallback(props)} <p {...props}>...</p>`
 
 ## License
 

package/dist/FieldVariants.svelte

@@ -0,0 +1,234 @@
+<script lang="ts" module>
+  import type { Snippet } from "svelte";
+  import type { RemoteFormField, RemoteFormFieldValue, RemoteFormFields } from "@sveltejs/kit";
+
+  // =============================================================================
+  // Core types - work with data type D instead of field object type T
+  // =============================================================================
+
+  // Extract data type from fields' set method
+  type Data<T> = T extends { set: (v: infer D) => unknown } ? D : never;
+
+  // Discriminator values from data (distributes over D)
+  type Values<K extends string, D> = D extends Record<K, infer V> ? (V extends string ? V : never) : never;
+
+  // Narrow D to variant where discriminator equals V
+  type NarrowData<K extends string, D, V> = D extends Record<K, V> ? D : never;
+
+  // Common keys (in EVERY variant) - for a union, keyof gives intersection
+  type CommonKeys<D> = keyof D;
+
+  // =============================================================================
+  // Validation - detect problematic field configurations
+  // =============================================================================
+
+  // Get all keys from ALL variants (distributes over union to collect all keys)
+  type AllDataKeys<D> = D extends D ? keyof D : never;
+
+  // Variants containing key P (distributes to filter union members)
+  // Checks if P is in keyof D (works for both required and optional properties)
+  type VariantsWithKey<D, P> = D extends D ? (P extends keyof D ? D : never) : never;
+
+  // Check if T is a union type (multiple members vs single type)
+  type IsUnion<T, U = T> = T extends T ? ([U] extends [T] ? false : true) : never;
+
+  // Key P is "partially shared" if:
+  // - NOT in all variants (not in CommonKeys)
+  // - In MORE THAN ONE variant (VariantsWithKey is a union)
+  // Keys in exactly 1 variant are fine (variant-specific)
+  type IsPartiallyShared<D, P> = P extends CommonKeys<D>
+    ? false // In all variants - OK (common field)
+    : IsUnion<VariantsWithKey<D, P>>; // true if 2+ variants have this key
+
+  // Find all partially shared keys (in 2 to N-1 variants, not variant-specific)
+  type PartiallySharedKeys<K extends string, D> = {
+    [P in Exclude<AllDataKeys<D>, K>]: IsPartiallyShared<D, P> extends true ? P : never;
+  }[Exclude<AllDataKeys<D>, K>];
+
+  // Check if types match across variants for a given key
+  type TypeAt<D, P extends PropertyKey> = D extends Record<P, infer V> ? V : never;
+
+  // For mixed type detection, check if the type varies across variants
+  type HasMixedTypes<D, P extends PropertyKey> = IsUnion<TypeAt<D, P>>;
+
+  // Common keys with different types across variants
+  type MixedTypeKeys<K extends string, D, CK extends PropertyKey = Exclude<CommonKeys<D>, K>> = CK extends CK
+    ? HasMixedTypes<D, CK> extends true
+      ? CK
+      : never
+    : never;
+
+  // Validation - check for both partially shared keys AND mixed types
+  type Validate<K extends string, D, T> = [PartiallySharedKeys<K, D>] extends [never]
+    ? [MixedTypeKeys<K, D>] extends [never]
+      ? T
+      : `Error: Field '${MixedTypeKeys<K, D> & string}' has different types across variants. Common fields must have the same type in all variants.`
+    : `Error: Field '${PartiallySharedKeys<K, D> & string}' exists in some variants but not all. Fields must be either unique to one variant or common to all variants.`;
+
+  // =============================================================================
+  // Snippet types - build field objects from data
+  // =============================================================================
+
+  // Reserved prop names
+  type Reserved = "fields" | "key" | "fallback" | "partial" | "css";
+
+  // Build field type - uses SvelteKit's RemoteFormFields for nested objects
+  // This correctly includes set(), value(), issues(), allIssues() on nested containers
+  type Field<V> = [V] extends [object]
+    ? RemoteFormFields<V>
+    : RemoteFormField<V & RemoteFormFieldValue>;
+
+  // Variant snippet fields: narrowed data → field object, excluding common fields
+  type SnippetFields<K extends string, D, V extends string, Narrow = NarrowData<K, D, V>> = {
+    readonly [P in Exclude<keyof Narrow, K | CommonKeys<D>>]: Field<Narrow[P & keyof Narrow]>;
+  } & {
+    readonly [P in K]: Field<V>;
+  };
+
+  // Props passed to variant snippets for CSS targeting (spread onto wrapper element)
+  export type VariantProps = { "data-fv"?: string };
+
+  // Combined variant snippet argument - spread for props, access .fields for variant data
+  // Mirrors form pattern: <form {...form}> + form.fields.x → <div {...v}> + v.fields.x
+  export type VariantSnippetArg<F> = VariantProps & { readonly fields: F };
+
+  // Snippet props - one snippet per variant, receives single arg with .fields property
+  type Snippets<K extends string, D, V extends string, IsPartial extends boolean> = IsPartial extends true
+    ? { [P in Exclude<V, Reserved>]?: Snippet<[VariantSnippetArg<SnippetFields<K, D, P>>]> }
+    : { [P in Exclude<V, Reserved>]: Snippet<[VariantSnippetArg<SnippetFields<K, D, P>>]> };
+
+  // =============================================================================
+  // Component props
+  // =============================================================================
+
+  export type FieldVariantsProps<
+    K extends string,
+    T extends { set: (v: never) => unknown } & Record<K, { value(): unknown }>,
+    V extends string = Values<K, Data<T>>,
+    IsPartial extends boolean = false,
+  > = {
+    fields: Validate<K, Data<T>, T>;
+    key: K;
+    /** Optional snippet shown when no variant is selected. Receives (props) for CSS targeting. */
+    fallback?: Snippet<[VariantProps]>;
+    /** When true, variant snippets are optional (default: false) */
+    partial?: IsPartial;
+    /** Set to false to disable CSS generation (default: true) */
+    css?: boolean;
+  } & Snippets<K, Data<T>, V, IsPartial>;
+</script>
+
+<script
+  lang="ts"
+  generics="K extends string, T extends { set: (v: never) => unknown } & Record<K, { value(): unknown }>, V extends string = Values<K, Data<T>>, IsPartial extends boolean = false"
+>
+  import { onMount } from "svelte";
+
+  type Props = FieldVariantsProps<K, T, V, IsPartial>;
+
+  let { fields, key, fallback, partial, css: cssEnabled = true, ...snippets }: Props = $props();
+
+  // Get all variant values from the snippet names
+  const variantValues = Object.keys(snippets) as V[];
+
+  // After hydration, switch from CSS-only to JS-based conditional rendering
+  // This enables Svelte transitions and other JS-dependent features
+  let hydrated = $state(false);
+  onMount(() => {
+    hydrated = true;
+  });
+
+  // Get the current discriminator value
+  const currentValue = $derived.by(() => {
+    const discriminatorField = (fields as Record<K, { value(): unknown }>)[key];
+    return discriminatorField?.value() as V | "" | undefined;
+  });
+
+  // Get the actual field name from the discriminator field (used for CSS selectors)
+  const fieldName = $derived.by(() => {
+    const discriminatorField = (fields as Record<K, { as(type: "select"): { name: string } }>)[key];
+    return discriminatorField?.as("select")?.name ?? key;
+  });
+
+  // Generate CSS for showing/hiding variants based on select or radio value
+  // Uses form:has() to scope to the containing form - works regardless of DOM structure
+  const css = $derived.by(() => {
+    if (!cssEnabled) return "";
+
+    const name = fieldName;
+    // Use .fieldName.variant format - the leading dot prevents collisions
+    const fv = (v: string) => `[data-fv=".${name}.${v}"]`;
+    const fvPrefix = `[data-fv^=".${name}."]`;
+
+    // form:has() scopes to the containing form, name-based targeting is precise
+    const sel = (v: string) => `form:has(select[name="${name}"] option[value="${v}"]:checked)`;
+    const rad = (v: string) => `form:has(input[name="${name}"][value="${v}"]:checked)`;
+
+    // Hide all variant sections by default (starts-with selector matches all variants for this field)
+    const hideAll = `form:has([name="${name}"]) ${fvPrefix}:not(${fv("fallback")}) { display: none; }\n`;
+
+    // Show the variant section that matches the selected value
+    const showVariants = variantValues
+      .map((v) => `${sel(v)} ${fv(v)},
+${rad(v)} ${fv(v)} { display: contents; }`)
+      .join("\n");
+
+    // Hide fallback when ANY value is selected (not just known variants)
+    // This checks for any non-empty option selected or any radio checked
+    const hideFallback = fallback
+      ? `form:has(select[name="${name}"] option:checked:not([value=""])) ${fv("fallback")},
+form:has(input[name="${name}"]:checked) ${fv("fallback")} { display: none; }\n`
+      : "";
+
+    return hideAll + showVariants + hideFallback;
+  });
+
+  // Props to add to wrapper elements when CSS is enabled - uses .fieldName.variant format
+  const wrapperProps = (variant: string): VariantProps =>
+    cssEnabled ? { "data-fv": `.${fieldName}.${variant}` } : {};
+
+  // Create snippet argument with non-enumerable fields property
+  // This allows {...v} to only spread the CSS props, while v.fields is still accessible
+  const createSnippetArg = (variant: string, variantFields: T): VariantSnippetArg<T> => {
+    const arg = { ...wrapperProps(variant) };
+    Object.defineProperty(arg, "fields", {
+      value: variantFields,
+      enumerable: false,
+      configurable: false,
+      writable: false,
+    });
+    return arg as VariantSnippetArg<T>;
+  };
+</script>
+
+<svelte:head>
+  {#if css && !hydrated}
+    <!-- CSS-only visibility before JS hydrates -->
+    {@html `<style>${css}</style>`}
+  {/if}
+</svelte:head>
+
+{#if hydrated}
+  <!-- After hydration: JS-based conditional rendering (enables transitions) -->
+  <!-- Fallback shows when no value is selected (empty string or undefined) -->
+  {#if !currentValue && fallback}
+    {@render fallback(wrapperProps("fallback"))}
+  {/if}
+
+  {#each variantValues as v (v)}
+    {#if currentValue === v}
+      {@const snippet = (snippets as unknown as Record<V, Snippet<[VariantSnippetArg<T>]>>)[v]}
+      {@render snippet(createSnippetArg(v, fields as T))}
+    {/if}
+  {/each}
+{:else}
+  <!-- Before hydration: render all, CSS handles visibility -->
+  {#if fallback}
+    {@render fallback(wrapperProps("fallback"))}
+  {/if}
+
+  {#each variantValues as v (v)}
+    {@const snippet = (snippets as unknown as Record<V, Snippet<[VariantSnippetArg<T>]>>)[v]}
+    {@render snippet(createSnippetArg(v, fields as T))}
+  {/each}
+{/if}

package/dist/FieldVariants.svelte.d.ts

@@ -0,0 +1,95 @@
+import type { Snippet } from "svelte";
+import type { RemoteFormField, RemoteFormFieldValue, RemoteFormFields } from "@sveltejs/kit";
+type Data<T> = T extends {
+    set: (v: infer D) => unknown;
+} ? D : never;
+type Values<K extends string, D> = D extends Record<K, infer V> ? (V extends string ? V : never) : never;
+type NarrowData<K extends string, D, V> = D extends Record<K, V> ? D : never;
+type CommonKeys<D> = keyof D;
+type AllDataKeys<D> = D extends D ? keyof D : never;
+type VariantsWithKey<D, P> = D extends D ? (P extends keyof D ? D : never) : never;
+type IsUnion<T, U = T> = T extends T ? ([U] extends [T] ? false : true) : never;
+type IsPartiallyShared<D, P> = P extends CommonKeys<D> ? false : IsUnion<VariantsWithKey<D, P>>;
+type PartiallySharedKeys<K extends string, D> = {
+    [P in Exclude<AllDataKeys<D>, K>]: IsPartiallyShared<D, P> extends true ? P : never;
+}[Exclude<AllDataKeys<D>, K>];
+type TypeAt<D, P extends PropertyKey> = D extends Record<P, infer V> ? V : never;
+type HasMixedTypes<D, P extends PropertyKey> = IsUnion<TypeAt<D, P>>;
+type MixedTypeKeys<K extends string, D, CK extends PropertyKey = Exclude<CommonKeys<D>, K>> = CK extends CK ? HasMixedTypes<D, CK> extends true ? CK : never : never;
+type Validate<K extends string, D, T> = [PartiallySharedKeys<K, D>] extends [never] ? [MixedTypeKeys<K, D>] extends [never] ? T : `Error: Field '${MixedTypeKeys<K, D> & string}' has different types across variants. Common fields must have the same type in all variants.` : `Error: Field '${PartiallySharedKeys<K, D> & string}' exists in some variants but not all. Fields must be either unique to one variant or common to all variants.`;
+type Reserved = "fields" | "key" | "fallback" | "partial" | "css";
+type Field<V> = [V] extends [object] ? RemoteFormFields<V> : RemoteFormField<V & RemoteFormFieldValue>;
+type SnippetFields<K extends string, D, V extends string, Narrow = NarrowData<K, D, V>> = {
+    readonly [P in Exclude<keyof Narrow, K | CommonKeys<D>>]: Field<Narrow[P & keyof Narrow]>;
+} & {
+    readonly [P in K]: Field<V>;
+};
+export type VariantProps = {
+    "data-fv"?: string;
+};
+export type VariantSnippetArg<F> = VariantProps & {
+    readonly fields: F;
+};
+type Snippets<K extends string, D, V extends string, IsPartial extends boolean> = IsPartial extends true ? {
+    [P in Exclude<V, Reserved>]?: Snippet<[VariantSnippetArg<SnippetFields<K, D, P>>]>;
+} : {
+    [P in Exclude<V, Reserved>]: Snippet<[VariantSnippetArg<SnippetFields<K, D, P>>]>;
+};
+export type FieldVariantsProps<K extends string, T extends {
+    set: (v: never) => unknown;
+} & Record<K, {
+    value(): unknown;
+}>, V extends string = Values<K, Data<T>>, IsPartial extends boolean = false> = {
+    fields: Validate<K, Data<T>, T>;
+    key: K;
+    /** Optional snippet shown when no variant is selected. Receives (props) for CSS targeting. */
+    fallback?: Snippet<[VariantProps]>;
+    /** When true, variant snippets are optional (default: false) */
+    partial?: IsPartial;
+    /** Set to false to disable CSS generation (default: true) */
+    css?: boolean;
+} & Snippets<K, Data<T>, V, IsPartial>;
+declare function $$render<K extends string, T extends {
+    set: (v: never) => unknown;
+} & Record<K, {
+    value(): unknown;
+}>, V extends string = Values<K, Data<T>>, IsPartial extends boolean = false>(): {
+    props: FieldVariantsProps<K, T, V, IsPartial>;
+    exports: {};
+    bindings: "";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<K extends string, T extends {
+    set: (v: never) => unknown;
+} & Record<K, {
+    value(): unknown;
+}>, V extends string = Values<K, Data<T>>, IsPartial extends boolean = false> {
+    props(): ReturnType<typeof $$render<K, T, V, IsPartial>>['props'];
+    events(): ReturnType<typeof $$render<K, T, V, IsPartial>>['events'];
+    slots(): ReturnType<typeof $$render<K, T, V, IsPartial>>['slots'];
+    bindings(): "";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <K extends string, T extends {
+        set: (v: never) => unknown;
+    } & Record<K, {
+        value(): unknown;
+    }>, V extends string = Values<K, Data<T>>, IsPartial extends boolean = false>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<K, T, V, IsPartial>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<K, T, V, IsPartial>['props']>, ReturnType<__sveltets_Render<K, T, V, IsPartial>['events']>, ReturnType<__sveltets_Render<K, T, V, IsPartial>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<K, T, V, IsPartial>['bindings']>;
+    } & ReturnType<__sveltets_Render<K, T, V, IsPartial>['exports']>;
+    <K extends string, T extends {
+        set: (v: never) => unknown;
+    } & Record<K, {
+        value(): unknown;
+    }>, V extends string = Values<K, Data<T>>, IsPartial extends boolean = false>(internal: unknown, props: ReturnType<__sveltets_Render<K, T, V, IsPartial>['props']> & {}): ReturnType<__sveltets_Render<K, T, V, IsPartial>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any, any, any, any>['bindings']>;
+}
+declare const FieldVariants: $$IsomorphicComponent;
+type FieldVariants<K extends string, T extends {
+    set: (v: never) => unknown;
+} & Record<K, {
+    value(): unknown;
+}>, V extends string = Values<K, Data<T>>, IsPartial extends boolean = false> = InstanceType<typeof FieldVariants<K, T, V, IsPartial>>;
+export default FieldVariants;

package/dist/discriminated.d.ts

@@ -0,0 +1,74 @@
+import type { RemoteFormField, RemoteFormFields, RemoteFormFieldType, RemoteFormFieldValue } from '@sveltejs/kit';
+export type DiscriminatedData<T> = T extends {
+    set: (v: infer D) => unknown;
+} ? D : never;
+type DiscriminatorValues<K extends string, D> = D extends Record<K, infer V> ? Exclude<V, undefined> : never;
+type RadioProps = RemoteFormField<string> extends {
+    as(type: 'radio', value: string): infer R;
+} ? R : never;
+type OptionProps = {
+    value: string;
+};
+type VariantDiscriminatorField<V extends string, AllV extends string> = Omit<RemoteFormField<V>, 'as'> & {
+    as(type: 'radio', value: AllV): RadioProps;
+    as(type: 'option'): OptionProps;
+    as(type: 'option', value: AllV): OptionProps;
+    as(type: Exclude<RemoteFormFieldType<V>, 'radio'>, ...args: unknown[]): ReturnType<RemoteFormField<V>['as']>;
+};
+type NestedField<V> = [V] extends [object] ? RemoteFormFields<V> : RemoteFormField<V & RemoteFormFieldValue>;
+type VariantFields<K extends string, D, AllV extends string> = D extends Record<K, infer V> ? {
+    readonly [P in `${K}Value`]: V;
+} & {
+    readonly [P in K]: VariantDiscriminatorField<V & string, AllV>;
+} & {
+    readonly [P in Exclude<keyof D, K>]: NestedField<D[P & keyof D]>;
+} : never;
+type UndefinedVariant<K extends string, D, AllV extends string> = {
+    readonly [P in `${K}Value`]: undefined;
+} & {
+    readonly [P in K]: VariantDiscriminatorField<AllV, AllV>;
+} & {
+    readonly [P in Exclude<keyof D, K>]: NestedField<D[P & keyof D]>;
+};
+type SetMethod<K extends string, D> = {
+    set: <V extends DiscriminatorValues<K, D>>(data: Extract<D, Record<K, V>>) => void;
+};
+type CommonMethods = RemoteFormFields<unknown> extends {
+    allIssues: infer M;
+} ? {
+    allIssues: M;
+} : never;
+type DiscriminatedFields<K extends string, D, AllV extends string = DiscriminatorValues<K, D> & string> = (VariantFields<K, D, AllV> | UndefinedVariant<K, D, AllV>) & SetMethod<K, D> & CommonMethods;
+/**
+ * Marks discriminated union form fields for type-safe narrowing.
+ * - All original fields pass through unchanged (type, issues, allIssues, etc.)
+ * - `set` is overridden with type-safe version
+ * - `${key}Value` is added for discriminator value (e.g., `reward.typeValue`)
+ * - Discriminator field `.as("radio", value)` is type-safe (only valid values allowed)
+ * - Discriminator field `.as("option", value?)` is type-safe for select options
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   const priority = $derived(discriminated("level", priorityForm.fields));
+ * </script>
+ *
+ * <input {...priority.level.as("radio", "high")} /> <!-- type-safe: only valid values allowed -->
+ *
+ * <select {...priority.level.as("select")}>
+ *   <option {...priority.level.as("option")}>Select...</option>
+ *   <option {...priority.level.as("option", "high")}>High</option>
+ * </select>
+ * ```
+ *
+ * @param key - Discriminator key (e.g. 'type')
+ * @param fields - Form fields from a discriminated union schema
+ * @returns Passthrough object with type-safe set(), ${key}Value, .as("radio", value), and .as("option", value?)
+ */
+export declare function discriminated<K extends string, T extends {
+    set: (v: never) => unknown;
+} & Record<K, {
+    value(): unknown;
+    as(type: 'radio', value: string): object;
+}>>(key: K, fields: T): DiscriminatedFields<K, DiscriminatedData<T>>;
+export {};

package/dist/discriminated.js

@@ -0,0 +1,62 @@
+// =============================================================================
+// Main function
+// =============================================================================
+/**
+ * Marks discriminated union form fields for type-safe narrowing.
+ * - All original fields pass through unchanged (type, issues, allIssues, etc.)
+ * - `set` is overridden with type-safe version
+ * - `${key}Value` is added for discriminator value (e.g., `reward.typeValue`)
+ * - Discriminator field `.as("radio", value)` is type-safe (only valid values allowed)
+ * - Discriminator field `.as("option", value?)` is type-safe for select options
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   const priority = $derived(discriminated("level", priorityForm.fields));
+ * </script>
+ *
+ * <input {...priority.level.as("radio", "high")} /> <!-- type-safe: only valid values allowed -->
+ *
+ * <select {...priority.level.as("select")}>
+ *   <option {...priority.level.as("option")}>Select...</option>
+ *   <option {...priority.level.as("option", "high")}>High</option>
+ * </select>
+ * ```
+ *
+ * @param key - Discriminator key (e.g. 'type')
+ * @param fields - Form fields from a discriminated union schema
+ * @returns Passthrough object with type-safe set(), ${key}Value, .as("radio", value), and .as("option", value?)
+ */
+export function discriminated(key, fields) {
+    // Wrap the discriminator field to intercept as("option", value?) calls
+    const wrapDiscriminatorField = (field) => {
+        return new Proxy(field, {
+            get(fieldTarget, fieldProp) {
+                if (fieldProp === 'as') {
+                    return (type, value) => {
+                        if (type === 'option') {
+                            return { value: value ?? '' };
+                        }
+                        return fieldTarget.as(type, value);
+                    };
+                }
+                return Reflect.get(fieldTarget, fieldProp);
+            }
+        });
+    };
+    const proxy = new Proxy(fields, {
+        get(target, prop) {
+            if (prop === `${key}Value`)
+                return target[key].value();
+            if (prop === 'set')
+                return (data) => target.set(data);
+            if (prop === key)
+                return wrapDiscriminatorField(target[key]);
+            return Reflect.get(target, prop);
+        },
+        has(target, prop) {
+            return prop === `${key}Value` || prop in target;
+        }
+    });
+    return proxy;
+}

package/dist/index.d.ts

@@ -1,39 +1,3 @@
-export type DiscriminatedData<T> = T extends {
-    set: (v: infer D) => unknown;
-} ? D : never;
-type Setter<K extends string, T, D = DiscriminatedData<T>> = {
-    set: <V extends D[K & keyof D]>(data: Extract<D, {
-        [P in K]: V;
-    }>) => void;
-};
-type Keys<T> = T extends unknown ? keyof T : never;
-type KeyValue<K extends string, V> = {
-    [P in `${K}Value`]: V;
-};
-type Fields<T> = {
-    [P in Keys<T>]: T extends Record<P, infer V> ? V : never;
-};
-type Variant<K extends string, T, V> = KeyValue<K, V> & Fields<T>;
-type Narrowed<K extends string, T> = T extends {
-    [P in K]: {
-        value(): infer V;
-    };
-} ? Variant<K, T, V> : never;
-type Union<K extends string, T> = Narrowed<K, T> | Variant<K, T, undefined>;
-type DiscriminatedFields<K extends string, T> = Setter<K, T> & Union<K, T>;
-/**
- * Wraps discriminated union form fields, adding ${key}Value for type narrowing.
- * - All original fields pass through unchanged (type, issues, allIssues, etc.)
- * - `set` is overridden with type-safe version
- * - `${key}Value` is added for discriminator value (e.g., `reward.typeValue`)
- *
- * @param key - Discriminator key (e.g. 'type')
- * @param fields - Form fields from a discriminated union schema
- * @returns Passthrough object with type-safe set() and ${key}Value for narrowing
- */
-export declare function discriminatedFields<K extends string, T extends {
-    set: (v: never) => unknown;
-} & Record<K, {
-    value(): unknown;
-}>>(key: K, fields: T): DiscriminatedFields<K, T>;
-export {};
+export { discriminated, type DiscriminatedData } from './discriminated.js';
+export { default as FieldVariants } from './FieldVariants.svelte';
+export type { FieldVariantsProps, VariantProps, VariantSnippetArg } from './FieldVariants.svelte';

package/dist/index.js

@@ -1,25 +1,4 @@
-/**
- * Wraps discriminated union form fields, adding ${key}Value for type narrowing.
- * - All original fields pass through unchanged (type, issues, allIssues, etc.)
- * - `set` is overridden with type-safe version
- * - `${key}Value` is added for discriminator value (e.g., `reward.typeValue`)
- *
- * @param key - Discriminator key (e.g. 'type')
- * @param fields - Form fields from a discriminated union schema
- * @returns Passthrough object with type-safe set() and ${key}Value for narrowing
- */
-export function discriminatedFields(key, fields) {
-    const proxy = new Proxy(fields, {
-        get(target, prop) {
-            if (prop === `${key}Value`)
-                return target[key].value();
-            if (prop === 'set')
-                return (data) => target.set(data);
-            return Reflect.get(target, prop);
-        },
-        has(target, prop) {
-            return prop === `${key}Value` || prop in target;
-        }
-    });
-    return proxy;
-}
+// Re-export discriminated function and types
+export { discriminated } from './discriminated.js';
+// Re-export FieldVariants component and its types
+export { default as FieldVariants } from './FieldVariants.svelte';

package/package.json

@@ -1,11 +1,14 @@
 {
 	"name": "sveltekit-discriminated-fields",
-	"version": "0.1.2",
+	"version": "0.3.0",
 	"description": "Type-safe discriminated union support for SvelteKit form fields",
 	"type": "module",
+	"svelte": "./dist/index.js",
+	"types": "./dist/index.d.ts",
 	"exports": {
 		".": {
 			"types": "./dist/index.d.ts",
+			"svelte": "./dist/index.js",
 			"default": "./dist/index.js"
 		}
 	},
@@ -13,11 +16,10 @@
 		"dist"
 	],
 	"scripts": {
-		"build": "tsc -p tsconfig.build.json",
-		"check": "tsc --noEmit",
-		"test:types": "tsc -p test/types/tsconfig.json",
-		"test:runtime": "npm run build && tsc -p test/runtime/tsconfig.json && npx tsx test/runtime/has.test.ts",
-		"test": "npm run test:types && npm run test:runtime",
+		"build": "svelte-package -i src -o dist",
+		"check": "svelte-check --tsconfig ./tsconfig.json",
+		"test:types": "npm run --prefix test build && svelte-check --tsconfig ./test/tsconfig.json",
+		"test": "npm run test:types && playwright test",
 		"prepublishOnly": "npm run test && npm run build"
 	},
 	"keywords": [
@@ -33,7 +35,18 @@
 		"type": "git",
 		"url": "https://github.com/robertadamsonsmith/sveltekit-discriminated-fields"
 	},
+	"peerDependencies": {
+		"@sveltejs/kit": "^2.27.0",
+		"svelte": "^5.0.0"
+	},
 	"devDependencies": {
+		"@playwright/test": "^1.57.0",
+		"@sveltejs/package": "^2.0.0",
+		"@types/node": "^25.0.3",
+		"@typescript-eslint/types": "^8.51.0",
+		"playwright": "^1.57.0",
+		"svelte": "^5.0.0",
+		"svelte-check": "^4.0.0",
 		"typescript": "^5.0.0"
 	}
 }