@lenne.tech/nuxt-extensions 1.12.0 → 1.13.0

package/CLAUDE.md

@@ -76,6 +76,10 @@ export default defineNuxtConfig({
       enabled: true,
       basePath: '/ai',               // Must match the nest-server AI controller
     },
+    formLabelAssociation: {
+      enabled: true,                 // repair <label for> broken by an SSR/client useId() divergence
+      maxRepairMs: 1500,             // how long to keep repairing deferred subtrees
+    },
     preHydrationInput: {
       enabled: true,                 // keep text typed before hydration instead of losing it
       maxRestoreMs: 1500,            // how long to keep repairing deferred subtrees
@@ -175,6 +179,32 @@ export default defineNuxtRouteMiddleware((to) => {
 });
 ```
 
+## Form Label Repair
+
+**The defect:** Nuxt UI's `FormField` derives the label's `for` and the control's `id` from one
+`useId()` call. When `useId()` diverges between server and client, the control's `id` is
+force-patched on hydration (vuejs/core#9083) while the label's `for` — a prop on reka-ui's
+`Label` component — is not. The label keeps the stale value and the association breaks.
+
+**What this module adds:** `runtime/plugins/form-label-association.client.ts` re-points
+dangling Nuxt UI field labels at the control in their own field, at `app:mounted` and for a
+bounded window afterwards (`maxRepairMs`, default 1500 ms).
+
+**What this means when you debug a consuming project:**
+
+- **A `for` attribute that changes after mount is this plugin, not a bug.** It logs a
+  `console.warn` in development naming how many labels it repaired.
+- **It refuses to guess.** The repair only fires when the field holds exactly one eligible
+  control. Radio and checkbox groups, hidden form-value proxies, `aria-hidden`/`disabled`
+  controls and button-only fields are skipped on purpose — binding a group caption to its
+  first option would submit a value the user never chose.
+- **Only Nuxt UI's own field labels are touched** (`label[data-slot="label"][for]`). Labels
+  your application wrote are never rewritten.
+- **Do not "fix" a skipped group by loosening the rule.** Inert beats wrong here; the correct
+  fix for a group is an SSR-stable id at the source.
+- This is a **stopgap** for a framework-level divergence. Opt out with
+  `ltExtensions.formLabelAssociation.enabled: false`.
+
 ## Pre-Hydration Input Preservation
 
 **The defect:** until Vue hydrates a server-rendered `<input>`, it carries no framework

package/README.md

@@ -42,6 +42,7 @@ npm install tus-js-client
 - **i18n Support** - English and German translations (works without i18n too)
 - **Auto-imports** - All composables and components are auto-imported
 - **Pre-hydration input preservation** - text typed before hydration is kept, not erased
+- **Form label repair** - restores `<label for>` associations that hydration breaks
 
 ## Environment Variables
 
@@ -157,6 +158,77 @@ export default defineNuxtConfig({
 });
 ```
 
+## Form Label Repair
+
+Restores `<label for>` associations that hydration breaks. Active by default.
+
+### The problem
+
+Nuxt UI's `FormField` derives the label's `for` and the control's `id` from a single
+`useId()` call, so they cannot disagree — unless `useId()` itself returns different values on
+server and client, which happens when the two walk a different number of async boundaries.
+
+Measured against `@nuxt/ui` 4.11.x:
+
+| | label `for` | control `id` |
+|---|---|---|
+| SSR payload | `v-0-4-2` | `v-0-4-2` |
+| after hydration | `v-0-4-2` | `v-0-1-2` |
+
+Vue 3.5.39 did not cause this, it exposed it
+([vuejs/core#9083](https://github.com/vuejs/core/pull/9083) force-patches an element's
+dynamic props on hydration). The control's `id` is such a prop; the label's `for`, passed
+through reka-ui's `Label` component, is not — so only the label keeps the stale value.
+
+### What it costs when it breaks
+
+The control loses its programmatic label. Without a placeholder it has no accessible name at
+all and a screen reader announces "edit text, blank"; **with** a placeholder that becomes the
+name instead, so the visible label is no longer part of it and speech input stops working.
+Clicking the label focuses nothing either — which on a checkbox or radio is the primary hit
+target, not a convenience. Tests using `getByRole('textbox', { name })` stop finding fields.
+
+### What the repair does
+
+After mount, and for a bounded window afterwards, every Nuxt UI field label whose target does
+not resolve is re-pointed at the control in its own field.
+
+**It refuses to guess.** A repair that fires where it should not is worse than the defect: a
+dangling label is inert and visible, a mis-pointed one is confidently wrong and silent, and
+on a radio or checkbox a click on the caption would change a value the user never chose. So
+the repair only fires when the field contains exactly **one** eligible control. Skipped
+deliberately:
+
+| Case | Why |
+|------|-----|
+| Radio / checkbox groups | One field root, many controls — binding every caption to the first option would submit a value nobody picked |
+| Hidden form-value proxies, `aria-hidden`, `disabled` | Not the user's control; pointing at one restores neither the name nor the click |
+| Fields whose only visible control is a `button` | Nothing safe to point at |
+| Labels your application wrote | Only Nuxt UI's own field labels (`data-slot="label"`) are touched |
+
+`for` is repaired rather than `aria-labelledby` added, because `for` carries **both** the
+accessible name and click-to-focus.
+
+**This is a repair, not a cure.** The real fix is for the id not to diverge; this exists
+because the divergence sits in the framework stack rather than in any one application.
+
+### Opting out
+
+```ts
+export default defineNuxtConfig({
+  ltExtensions: {
+    formLabelAssociation: {
+      enabled: false,
+      // or keep it on and only change how long deferred subtrees are waited for:
+      // maxRepairMs: 3000,
+    },
+  },
+});
+```
+
+Two real reasons to: your application assigns `for` itself and depends on those exact values,
+or your tests assert on literal `for` / `id` strings rather than on the accessible name.
+
 ## Pre-Hydration Input Preservation
 
 Text typed before a page has hydrated is kept instead of being silently thrown away.

package/dist/module.d.mts

@@ -3,7 +3,7 @@ import { LtExtensionsModuleOptions } from '../dist/runtime/types/index.js';
 export * from '../dist/runtime/types/index.js';
 
 declare const name = "@lenne.tech/nuxt-extensions";
-declare const version = "1.12.0";
+declare const version = "1.13.0";
 declare const configKey = "ltExtensions";
 declare const DEFAULT_LT_AUTH_STATE_COOKIE = "lt-auth-state";
 declare const DEFAULT_LT_JWT_TOKEN_COOKIE = "lt-jwt-token";

package/dist/module.json

@@ -1,7 +1,7 @@
 {
   "configKey": "ltExtensions",
   "name": "@lenne.tech/nuxt-extensions",
-  "version": "1.12.0",
+  "version": "1.13.0",
   "builder": {
     "@nuxt/module-builder": "1.0.3",
     "unbuild": "3.6.1"

package/dist/module.mjs

@@ -1,7 +1,7 @@
 import { defineNuxtModule, createResolver, tryResolveModule, addImports, addComponent, addPlugin, addRouteMiddleware } from '@nuxt/kit';
 
 const name = "@lenne.tech/nuxt-extensions";
-const version = "1.12.0";
+const version = "1.13.0";
 const configKey = "ltExtensions";
 const DEFAULT_LT_AUTH_STATE_COOKIE = "lt-auth-state";
 const DEFAULT_LT_JWT_TOKEN_COOKIE = "lt-jwt-token";
@@ -36,6 +36,9 @@ const defaultOptions = {
     enabled: true,
     defaultLocale: "de"
   },
+  formLabelAssociation: {
+    enabled: true
+  },
   i18n: {
     autoMerge: true
   },
@@ -66,6 +69,7 @@ const module$1 = defineNuxtModule({
         systemSetup: { ...defaultOptions.auth.systemSetup, ...options.auth?.systemSetup }
       },
       errorTranslation: { ...defaultOptions.errorTranslation, ...options.errorTranslation },
+      formLabelAssociation: { ...defaultOptions.formLabelAssociation, ...options.formLabelAssociation },
       i18n: { ...defaultOptions.i18n, ...options.i18n },
       preHydrationInput: { ...defaultOptions.preHydrationInput, ...options.preHydrationInput },
       tus: { ...defaultOptions.tus, ...options.tus }
@@ -124,6 +128,10 @@ const module$1 = defineNuxtModule({
         enabled: resolvedOptions.errorTranslation?.enabled ?? true,
         defaultLocale: resolvedOptions.errorTranslation?.defaultLocale || "de"
       },
+      formLabelAssociation: {
+        enabled: resolvedOptions.formLabelAssociation?.enabled ?? true,
+        maxRepairMs: resolvedOptions.formLabelAssociation?.maxRepairMs ?? 1500
+      },
       preHydrationInput: {
         enabled: resolvedOptions.preHydrationInput?.enabled ?? true,
         maxRestoreMs: resolvedOptions.preHydrationInput?.maxRestoreMs ?? 1500
@@ -219,6 +227,9 @@ const module$1 = defineNuxtModule({
     if (resolvedOptions.preHydrationInput.enabled !== false) {
       addPlugin(resolve("./runtime/plugins/pre-hydration-input.client"));
     }
+    if (resolvedOptions.formLabelAssociation.enabled !== false) {
+      addPlugin(resolve("./runtime/plugins/form-label-association.client"));
+    }
     nuxt.options.build.transpile.push(resolve("./runtime"));
     nuxt.options.build.transpile.push("tus-js-client");
     console.log(`[${name}] Module loaded with config:`, {

package/dist/runtime/plugins/form-label-association.client.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Repair `<label for>` associations that hydration leaves pointing at nothing.
+ *
+ * ## The defect
+ *
+ * Nuxt UI's `FormField` generates ONE id with `useId()` and uses it for both halves of
+ * the association: `<Label :for="id">` and, via `provide`/`inject`, the control's `id`.
+ * One source, so the two cannot disagree — unless `useId()` itself returns different
+ * values on the server and on the client.
+ *
+ * It does. Measured on a Nuxt 4 app page (SVL, DEV-3093), against `@nuxt/ui` 4.11.x:
+ *
+ * | | label `for` | control `id` |
+ * | -- | -- | -- |
+ * | SSR payload | `v-0-4-2` | `v-0-4-2` |
+ * | after hydration | `v-0-4-2` | `v-0-1-2` |
+ *
+ * The middle segment is Vue's per-branch id prefix, which is extended at every async
+ * boundary. Server and client walked a different number of them, so the ids diverge.
+ *
+ * **Vue >= 3.5.39 did not cause this — it exposed it.** "force patch dynamic props when
+ * hydrating" (vuejs/core#9083, merged 2026-06-25) makes a hydrated element adopt its
+ * freshly computed client value, where previously the server value simply stayed.
+ *
+ * Note WHY only the label is left behind, because it points at the real fix: the control's
+ * `id` is a compiled element binding (`<input :id="id">`), so it is in the element's
+ * `dynamicProps` and gets force-patched. The label's `for` is a PROP on reka-ui's `Label`
+ * component and arrives at the `<label>` through `$attrs`, which is not part of that set.
+ * The asymmetry is the component boundary, not the id generation. Fixing the divergence
+ * upstream — or having `FormField` pass an SSR-stable id — removes the need for this file.
+ *
+ * ## Why it is worth a plugin
+ *
+ * A control whose label does not resolve loses its programmatic label: the visible text is
+ * no longer its accessible name (WCAG 1.3.1). Where the field has no placeholder it has no
+ * accessible name at all and a screen reader announces "edit text, blank" (4.1.2). Where it
+ * has one, the placeholder becomes the name instead — which is arguably worse, because the
+ * name no longer contains the visible label and speech input stops working (2.5.3 Label in
+ * Name). Clicking the label also no longer focuses the control, and for a checkbox or radio
+ * that is not a convenience but the primary hit target.
+ *
+ * And any test that addresses fields the way assistive technology does
+ * (`getByRole('textbox', { name })`, the recommended Playwright locator) stops finding
+ * them, which is how this surfaced: 39 specs at once.
+ *
+ * ## What this does, and what it deliberately does not
+ *
+ * After mount — and for a bounded window afterwards — every Nuxt UI field label whose
+ * target does not resolve is re-pointed at the control inside its own field.
+ *
+ * It **refuses to guess**, which is the rule that matters most here. A repair that fires
+ * where it should not is worse than the defect: a dangling label is inert and visible, a
+ * mis-pointed one is confidently wrong and silent, and on a radio or checkbox a click on
+ * the caption would then change a value the user never chose. So the repair only happens
+ * when the field contains exactly ONE eligible control. A group of radios or checkboxes
+ * shares one field root and is therefore skipped, not guessed at.
+ *
+ * `for` is repaired rather than `aria-labelledby` added, because `for` carries BOTH the
+ * accessible name and click-to-focus. Adding `aria-labelledby` would restore the name
+ * and leave the label dead to the mouse.
+ *
+ * This is a repair, not a cure: the right fix is for the id not to diverge in the first
+ * place (see the component-boundary note above). It is applied here because the divergence
+ * sits in the framework stack rather than in any one application, and because a nameless
+ * form is not something to leave in place while that is resolved upstream.
+ *
+ * Default on; opt out with `ltExtensions.formLabelAssociation.enabled: false`.
+ */
+/**
+ * Re-point every dangling field label at the control in its own field.
+ *
+ * Exported for the unit test: it runs against a DOM fixture rather than a live app, so the
+ * pairing rules stay verifiable without a browser. Not part of the package's public API.
+ *
+ * @param root Where to look. Ids are resolved against the owning document regardless, since
+ *   `id` is document-scoped — so a scoped root narrows which labels are visited, not which
+ *   ids count as resolvable.
+ * @returns how many labels were repaired.
+ */
+export declare function repairDanglingLabels(root: Document | ParentNode): number;
+declare const _default: import("nuxt/app").Plugin<Record<string, unknown>> & import("nuxt/app").ObjectPlugin<Record<string, unknown>>;
+export default _default;

package/dist/runtime/plugins/form-label-association.client.js

@@ -0,0 +1,67 @@
+import { defineNuxtPlugin, useRuntimeConfig } from "#imports";
+const COMPONENT_ROOT = '[data-slot="root"]';
+const FIELD_LABEL = 'label[data-slot="label"][for]';
+const CONTROL = "input, textarea, select";
+const NOT_A_USER_CONTROL = '[type="hidden"], [hidden], [aria-hidden="true"], [disabled]';
+function findControlForLabel(field) {
+  const eligible = [...field.querySelectorAll(CONTROL)].filter((control) => !control.matches(NOT_A_USER_CONTROL));
+  return eligible.length === 1 && eligible[0].id !== "" ? eligible[0] : null;
+}
+export function repairDanglingLabels(root) {
+  let repaired = 0;
+  for (const label of root.querySelectorAll(FIELD_LABEL)) {
+    const field = label.closest(COMPONENT_ROOT);
+    if (field === null) {
+      continue;
+    }
+    const target = label.ownerDocument.getElementById(label.htmlFor);
+    if (target !== null && field.contains(target)) {
+      continue;
+    }
+    const control = findControlForLabel(field);
+    if (control === null || control.id === label.htmlFor) {
+      continue;
+    }
+    label.htmlFor = control.id;
+    repaired += 1;
+  }
+  return repaired;
+}
+export default defineNuxtPlugin({
+  // After the app's own plugins, so a page that assigns ids itself has already run.
+  enforce: "post",
+  name: "lt-form-label-association",
+  setup(nuxtApp) {
+    const options = useRuntimeConfig().public.ltExtensions?.formLabelAssociation;
+    if (options?.enabled === false) {
+      return;
+    }
+    const maxRepairMs = options?.maxRepairMs ?? 1500;
+    let sweeping = null;
+    const sweep = () => {
+      const repaired = repairDanglingLabels(document);
+      if (repaired > 0 && import.meta.dev) {
+        console.warn(
+          `[@lenne.tech/nuxt-extensions] repaired ${repaired} form label association(s) broken by an SSR/client useId() divergence. This is a stopgap \u2014 see runtime/plugins/form-label-association.client.ts.`
+        );
+      }
+    };
+    const sweepFor = () => {
+      sweep();
+      if (maxRepairMs <= 0 || sweeping !== null) {
+        return;
+      }
+      sweeping = setInterval(sweep, 250);
+      setTimeout(() => {
+        if (sweeping !== null) {
+          clearInterval(sweeping);
+          sweeping = null;
+        }
+      }, maxRepairMs);
+    };
+    nuxtApp.hook("app:mounted", sweepFor);
+    nuxtApp.hook("page:finish", () => {
+      requestAnimationFrame(sweepFor);
+    });
+  }
+});

package/dist/runtime/types/index.d.ts

@@ -1,5 +1,5 @@
 export type { LtAuthClientConfig, LtAuthMode, LtAuthResponse, LtAuthState, LtPasskeyAuthResult, LtPasskeyRegisterResult, LtUser, UseLtAuthReturn } from './auth.js';
 export type { LtFileInfo, LtUploadItem, LtUploadOptions, LtUploadProgress, LtUploadStatus, UseLtFileReturn, UseLtTusUploadReturn } from './upload.js';
-export type { LtAiModuleOptions, LtAuthCookieNamesOptions, LtAuthModuleOptions, LtErrorTranslationModuleOptions, LtExtensionsModuleOptions, LtExtensionsPublicRuntimeConfig, LtI18nModuleOptions, LtPreHydrationInputOptions, LtSystemSetupModuleOptions, LtTusModuleOptions, } from './module.js';
+export type { LtAiModuleOptions, LtAuthCookieNamesOptions, LtAuthModuleOptions, LtErrorTranslationModuleOptions, LtExtensionsModuleOptions, LtExtensionsPublicRuntimeConfig, LtFormLabelAssociationOptions, LtI18nModuleOptions, LtPreHydrationInputOptions, LtSystemSetupModuleOptions, LtTusModuleOptions, } from './module.js';
 export type { LtErrorTranslationResponse, LtParsedError, UseLtErrorTranslationReturn } from './error.js';
 export type { LtAiAction, LtAiAvailableConnection, LtAiBudgetLimit, LtAiBudgetSummary, LtAiConnection, LtAiConnectionInput, LtAiConnectionPreference, LtAiEffectiveSlot, LtAiInteraction, LtAiMessage, LtAiMode, LtAiPlaceholder, LtAiPrompt, LtAiPromptHint, LtAiPromptHintInput, LtAiPromptInput, LtAiPromptRunInput, LtAiResponse, LtAiSlot, LtAiSlotInput, LtAiStreamEvent, LtAiStreamHandlers, LtAiUsage, LtAiUsageInfo, LtAiUsageScope, UseLtAiAdminReturn, UseLtAiChatOptions, UseLtAiChatReturn, UseLtAiConnectionsReturn, UseLtAiPlaceholdersReturn, UseLtAiPromptsReturn, UseLtAiReturn, UseLtAiUsageReturn, } from './ai.js';

package/dist/runtime/types/module.d.ts

@@ -127,6 +127,8 @@ export interface LtExtensionsModuleOptions {
     auth?: LtAuthModuleOptions;
     /** Error translation configuration */
     errorTranslation?: LtErrorTranslationModuleOptions;
+    /** Form label association repair configuration */
+    formLabelAssociation?: LtFormLabelAssociationOptions;
     /** i18n configuration */
     i18n?: LtI18nModuleOptions;
     /** Pre-hydration input preservation configuration */
@@ -134,6 +136,57 @@ export interface LtExtensionsModuleOptions {
     /** TUS upload module configuration */
     tus?: LtTusModuleOptions;
 }
+/**
+ * Repair of `<label for>` associations broken by an SSR/client `useId()` divergence.
+ *
+ * Nuxt UI's `FormField` derives the label's `for` and the control's `id` from ONE `useId()`
+ * call, so they cannot disagree — unless `useId()` itself returns different values on server
+ * and client, which it does whenever the two walk a different number of async boundaries.
+ * The label then keeps the server value while the control adopts the client one.
+ *
+ * The control loses its programmatic label. Without a placeholder it has no accessible name
+ * at all and a screen reader announces "edit text, blank"; with one, the placeholder becomes
+ * the name instead, so the visible label is no longer part of it and speech input stops
+ * working. Either way clicking the label focuses nothing — which on a checkbox or radio is
+ * the primary hit target, not a convenience.
+ *
+ * Vue >= 3.5.39 did not cause this, it exposed it: vuejs/core#9083 force-patches an element's
+ * dynamic props during hydration, and the control's `id` is one while the label's `for` —
+ * passed through reka-ui's `Label` component and `$attrs` — is not.
+ *
+ * The repair refuses to guess: it only fires when the field contains exactly one eligible
+ * control, so a radio or checkbox group is skipped rather than having every caption bound to
+ * its first option.
+ *
+ * @example
+ * ```ts
+ * export default defineNuxtConfig({
+ *   ltExtensions: {
+ *     formLabelAssociation: { enabled: false },
+ *   },
+ * });
+ * ```
+ */
+export interface LtFormLabelAssociationOptions {
+    /**
+     * Enable the repair. Defaults to `true`.
+     *
+     * Turn it off only with a reason. Two real ones: an application that assigns `for` itself
+     * and depends on those exact values, or a test suite asserting on literal `for` / `id`
+     * strings rather than on the accessible name. The alternative is a form whose fields carry
+     * no programmatic label.
+     */
+    enabled?: boolean;
+    /**
+     * How long after mount to keep repairing, in milliseconds. Defaults to `1500`; `0` sweeps
+     * once and stops.
+     *
+     * Most fields are repaired in the first pass. The window exists for server-rendered
+     * subtrees whose hydration is deferred — `hydrate-on-visible`, an unresolved `<Suspense>`,
+     * an island — which carry the same divergence but hydrate after `app:mounted`.
+     */
+    maxRepairMs?: number;
+}
 /**
  * Pre-hydration input preservation.
  *
@@ -219,6 +272,10 @@ export interface LtExtensionsPublicRuntimeConfig {
             enabled: boolean;
             defaultLocale: string;
         };
+        formLabelAssociation: {
+            enabled: boolean;
+            maxRepairMs: number;
+        };
         preHydrationInput: {
             enabled: boolean;
             maxRestoreMs: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nuxt-extensions",
-  "version": "1.12.0",
+  "version": "1.13.0",
   "description": "Reusable Nuxt 4 composables, components, and Better-Auth integration for lenne.tech projects",
   "repository": {
     "type": "git",