sveltekit-discriminated-fields 0.2.0 → 0.4.0

package/README.md

@@ -4,8 +4,8 @@ Type-safe discriminated union support for SvelteKit remote function form fields.
 
 This library provides two complementary tools for working with discriminated unions in SvelteKit forms:
 
-- **`discriminatedFields()`** - A wrapper function that enables proper TypeScript type narrowing on form field objects
-- **`UnionVariants`** - A component that renders variant-specific form sections with CSS-only visibility, supporting progressive enhancement (works without JavaScript)
+- **`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)
 
 The implementation prioritises:
 
@@ -22,9 +22,9 @@ This library exposes existing SvelteKit form behaviour with improved typing for
 npm install sveltekit-discriminated-fields
 ```
 
-## UnionVariants Component
+## FieldVariants Component
 
-The `UnionVariants` component provides declarative variant rendering with **full progressive enhancement support**. It uses CSS-only visibility toggling via `:has()` selectors, so forms work identically with or without JavaScript enabled.
+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):
 
@@ -34,8 +34,12 @@ import { z } from "zod";
 import { form } from "$app/server";
 
 const shapeSchema = z.discriminatedUnion("kind", [
-  z.object({ kind: z.literal("circle"), radius: z.coerce.number() }),
-  z.object({ kind: z.literal("rectangle"), width: z.coerce.number(), height: z.coerce.number() }),
+  z.object({ kind: z.literal("circle"), radius: z.number() }),
+  z.object({
+    kind: z.literal("rectangle"),
+    width: z.number(),
+    height: z.number(),
+  }),
   z.object({ kind: z.literal("point") }),
 ]);
 
@@ -44,12 +48,12 @@ export const shapeForm = form(shapeSchema, async (data) => {
 });
 ```
 
-Use `UnionVariants` to render variant-specific fields:
+Use `FieldVariants` to render variant-specific fields:
 
 ```svelte
 <script lang="ts">
   import { shapeForm } from './data.remote';
-  import { UnionVariants } from 'sveltekit-discriminated-fields';
+  import { FieldVariants } from 'sveltekit-discriminated-fields';
 </script>
 
 <form {...shapeForm}>
@@ -60,79 +64,123 @@ Use `UnionVariants` to render variant-specific fields:
     <option value="point">Point</option>
   </select>
 
-  <UnionVariants fields={shapeForm.fields} key="kind">
-    {#snippet fallback()}
-      <p>Please select a shape type above.</p>
+  <FieldVariants fields={shapeForm.fields} key="kind">
+    {#snippet fallback(props)}
+      <p {...props}>Please select a shape type above.</p>
     {/snippet}
 
-    {#snippet circle(s)}
-      <input {...s.radius.as('number')} placeholder="Radius" />
+    {#snippet circle(shape)}
+      <label {...shape}>
+        Radius: <input {...shape.fields.radius.as('number')} />
+      </label>
     {/snippet}
 
-    {#snippet rectangle(s)}
-      <input {...s.width.as('number')} placeholder="Width" />
-      <input {...s.height.as('number')} placeholder="Height" />
+    {#snippet rectangle(shape)}
+      <div {...shape}>
+        <input {...shape.fields.width.as('number')} placeholder="Width" />
+        <input {...shape.fields.height.as('number')} placeholder="Height" />
+      </div>
     {/snippet}
 
-    {#snippet point(_s)}
-      <p>Point has no additional fields.</p>
+    {#snippet point(shape)}
+      <p {...shape}>Point has no additional fields.</p>
     {/snippet}
-  </UnionVariants>
+  </FieldVariants>
 
   <button type="submit">Submit</button>
 </form>
 ```
 
-The optional `fallback` snippet is displayed when no variant is currently selected (i.e., when the discriminator field is empty).
+### Snippet Parameters
 
-Each snippet receives correctly narrowed fields for that variant - TypeScript knows `s.radius` exists in the `circle` snippet but not in `rectangle`. Only valid discriminator values are accepted.
+Each variant snippet receives a single argument that mirrors how forms work in SvelteKit:
 
-Snippets only receive fields **specific to that variant**. Fields common to all variants (same name and type) should be rendered outside `UnionVariants` to prevent accidental duplicate inputs. Fields shared by some but not all variants, or with differing types across variants, produce compile-time errors.
+- **Spread for CSS targeting**: `{...shape}` - Adds the `data-fv` attribute for CSS visibility
+- **Access fields**: `shape.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 `shape.fields.radius` exists in the `circle` snippet but not in `rectangle`. Only valid discriminator values are accepted.
+
+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 `discriminatedFields()` 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:
+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 { discriminatedFields, UnionVariants } from 'sveltekit-discriminated-fields';
+  import { discriminated, FieldVariants } from 'sveltekit-discriminated-fields';
 
-  const shape = $derived(discriminatedFields('kind', shapeForm.fields));
+  const shape = $derived(discriminated(shapeForm.fields, 'kind'));
 </script>
 
 <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>
+    <label><input {...shape.fields.kind.as("radio", "circle")} /> Circle</label>
+    <label><input {...shape.fields.kind.as("radio", "rectangle")} /> Rectangle</label>
+    <label><input {...shape.fields.kind.as("radio", "point")} /> Point</label>
   </fieldset>
 
-  <UnionVariants fields={shape} key="kind">
-    <!-- snippets work the same way -->
-  </UnionVariants>
+  <FieldVariants fields={shapeForm.fields} key="kind">
+    {#snippet fallback(props)}
+      <p {...props}>Select a shape type</p>
+    {/snippet}
+
+    {#snippet circle(shape)}
+      <label {...shape}>
+        Radius: <input {...shape.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.
 
-### Non-Sibling Layouts with `selector`
+### Select Options
 
-By default, `UnionVariants` expects the discriminator input (select or radios) to be a sibling element. For complex layouts where this isn't possible, use the `selector` prop:
+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
-<div class="header">
-  <select {...shape.kind.as('select')} id="shape-select">
-    <!-- options -->
-  </select>
-</div>
-
-<div class="body">
-  <!-- Not a sibling of the select! -->
-  <UnionVariants fields={shape} key="kind" selector="#shape-select">
-    <!-- snippets -->
-  </UnionVariants>
-</div>
+<select {...shape.fields.kind.as("select")}>
+  <!-- Type-safe: typos caught at compile time -->
+  <option {...shape.fields.kind.as("option")}>Select a shape...</option>
+  <option {...shape.fields.kind.as("option", "circle")}>Circle</option>
+  <option {...shape.fields.kind.as("option", "rectangle")}>Rectangle</option>
+
+  <!-- Also works: standard HTML (no type checking) -->
+  <option value="point">Point</option>
+</select>
+```
+
+- `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>
 ```
 
 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.
@@ -152,58 +200,100 @@ const orderSchema = z.object({
 ```
 
 ```svelte
-<UnionVariants fields={orderForm.fields.shipping} key="method">
-  <!-- snippets for pickup and delivery -->
-</UnionVariants>
+<script lang="ts">
+  import { discriminated, FieldVariants } from 'sveltekit-discriminated-fields';
+
+  const shipping = $derived(discriminated(orderForm.fields.shipping, 'method'));
+</script>
+
+<FieldVariants fields={orderForm.fields.shipping} key="method">
+  {#snippet pickup(shipping)}
+    <input {...shipping} {...shipping.fields.store.as('text')} />
+  {/snippet}
+
+  {#snippet delivery(shipping)}
+    <input {...shipping} {...shipping.fields.address.as('text')} />
+  {/snippet}
+</FieldVariants>
 ```
 
 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.
 
 ### Partial Variants
 
-By default, `UnionVariants` 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}`:
+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}`:
 
 ```svelte
-<UnionVariants fields={shape} key="kind" partial={true}>
-  {#snippet circle(s)}
-    <input {...s.radius.as('number')} />
+<FieldVariants fields={shapeForm.fields} key="kind" partial={true}>
+  {#snippet circle(shape)}
+    <input {...shape} {...shape.fields.radius.as('number')} />
+  {/snippet}
+
+  {#snippet rectangle(shape)}
+    <input {...shape} {...shape.fields.width.as('number')} />
   {/snippet}
 
-  {#snippet rectangle(s)}
-    <input {...s.width.as('number')} />
+  <!-- point snippet omitted - nothing shown when point selected -->
+</FieldVariants>
+```
+
+### 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
+<FieldVariants fields={shapeForm.fields} key="kind">
+  {#snippet circle(shape)}
+    <!-- Svelte transitions work after hydration -->
+    <div {...shape} transition:slide>
+      <input {...shape.fields.radius.as('number')} />
+    </div>
   {/snippet}
+</FieldVariants>
+```
+
+### Disabling CSS
+
+If you want to handle visibility yourself, disable CSS generation:
 
-  <!-- point snippet omitted - fallback shown when point selected -->
-</UnionVariants>
+```svelte
+<FieldVariants fields={shapeForm.fields} key="kind" css={false}>
+  <!-- snippets -->
+</FieldVariants>
 ```
 
-## discriminatedFields Function
+## 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 `discriminatedFields()` function wraps your form fields to:
+The `discriminated()` function wraps your form fields to:
 
-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
+1. Provide `.type` - the current discriminator value for TypeScript narrowing
+2. Provide `.fields` - all variant fields accessible with proper typing
+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 `UnionVariants`. This approach requires JavaScript (unlike `UnionVariants` which works without JS):
+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 { discriminatedFields } from 'sveltekit-discriminated-fields';
+  import { discriminated } from 'sveltekit-discriminated-fields';
 
-  const shape = $derived(discriminatedFields('kind', shapeForm.fields));
+  const shape = $derived(discriminated(shapeForm.fields, 'kind'));
 </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')} />
+<!-- Use .type for narrowing, .fields for field access -->
+{#if shape.type === 'circle'}
+  <input {...shape.fields.radius.as('number')} /> <!-- TypeScript knows radius exists -->
+{:else if shape.type === 'rectangle'}
+  <input {...shape.fields.width.as('number')} />  <!-- TypeScript knows width exists -->
+  <input {...shape.fields.height.as('number')} />
 {/if}
 ```
 
@@ -211,49 +301,59 @@ See the [programmatic-form example](./test/src/routes/programmatic-form) for usa
 
 ## API
 
-### `UnionVariants`
+### `FieldVariants`
 
 A component for rendering variant-specific form sections with CSS-only visibility.
 
 **Props:**
 
-| Prop       | Type                  | Description                                                 |
-| ---------- | --------------------- | ----------------------------------------------------------- |
-| `fields`   | `DiscriminatedFields` | The wrapped form fields from `discriminatedFields()`        |
-| `key`      | `string`              | The discriminator key (must match a field in the schema)    |
-| `selector` | `string` (optional)   | CSS selector for the discriminator input when not a sibling |
-| `partial`  | `boolean` (optional)  | Allow missing snippets for some variants                    |
+| Prop      | Type                 | Description                                               |
+| --------- | -------------------- | --------------------------------------------------------- |
+| `fields`  | `RemoteFormFields`   | Raw form fields from `form.fields` (not wrapped)          |
+| `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` - Rendered when no variant is selected
-- `{variantName}(fields)` - One snippet per variant, receives narrowed fields
+- `fallback(props)` - Rendered when no variant is selected. Spread `props` onto your element.
+- `{variantName}(variant)` - One snippet per variant. Spread `variant` onto your container, access fields via `variant.fields`.
 
-### `discriminatedFields(key, fields)`
+### `discriminated(fields, key)`
 
 Wraps discriminated union form fields for type-safe narrowing.
 
 **Parameters:**
 
-- `key` - The discriminator key (must exist as a field in all variants)
 - `fields` - Form fields from a discriminated union schema
+- `key` - The discriminator key (must exist as a field in all variants)
 
 **Returns:** A proxy object with:
 
-- All original fields passed through unchanged
-- `${key}Value` - The current discriminator value (for narrowing)
+- `type` - The current discriminator value (for narrowing)
+- `fields` - All form fields with proper variant typing
 - `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(form.fields, "type");
 type Payment = DiscriminatedData<typeof payment>;
 // { type: 'card'; cardNumber: string; cvv: string } | { type: 'bank'; ... }
 ```
 
+### `VariantSnippetArg<T>`
+
+Type for the argument passed to variant snippets:
+
+```typescript
+// variant can be spread onto elements and has a .fields property
+type VariantSnippetArg<T> = VariantProps & { readonly fields: T };
+```
+
 ## License
 
 MIT

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}