packages/core/src/field/validity/FieldValidity.vue (1)

27-31: Consider excluding state from the spread to match the declared type.

The FieldValidityState interface omits state from FieldValidityData, but the spread of combinedFieldValidityData includes it at runtime. While TypeScript hides the state property from consumers, the runtime object will have both state and validity (with identical values).

♻️ Proposed fix to ensure runtime matches type

 const fieldValidityState = computed<FieldValidityState>(() => ({
-  ...combinedFieldValidityData.value,
+  error: combinedFieldValidityData.value.error,
+  errors: combinedFieldValidityData.value.errors,
+  value: combinedFieldValidityData.value.value,
+  initialValue: combinedFieldValidityData.value.initialValue,
   validity: combinedFieldValidityData.value.state,
   transitionStatus: transitionStatus.value,
 }))

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/core/src/field/validity/FieldValidity.vue` around lines 27 - 31,
fieldValidityState is currently created by spreading
combinedFieldValidityData.value which at runtime still includes the `state`
property even though FieldValidityState expects `validity` and not `state`;
update the construction in the computed to omit `state` from the spread (e.g.,
destructure combinedFieldValidityData.value to remove `state` and spread the
rest), then set `validity` explicitly from the removed `state` so the runtime
object matches the FieldValidityState shape (refer to fieldValidityState,
combinedFieldValidityData, FieldValidityState, and FieldValidityData).

packages/core/src/field/root/FieldRoot.test.ts (1)

663-695: Missing blank line before describe block.

Minor formatting nit: Line 663 should have a blank line before it to separate from the previous describe block, consistent with the rest of the file.

✨ Proposed fix

     })
   })
+
   describe('component ref', () => {

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/core/src/field/root/FieldRoot.test.ts` around lines 663 - 695, Add a
blank line before the describe('component ref', ...) block to match the file's
formatting convention; locate the describe block in FieldRoot.test.ts (the block
that contains the "validates the field when the `validate` action is called" it
test and references createApp, fieldRef, handleValidate) and insert one empty
line above it so it is separated from the previous describe block.

packages/core/src/labelable-provider/useAriaLabelledBy.ts (2)

62-76: Side effect in getter function may cause unexpected behavior.

getAriaLabelledBy mutates the DOM by assigning label.id (line 72), which is unexpected for a function prefixed with "get". This side effect could cause issues if called multiple times or in SSR contexts.

Consider extracting the ID assignment into the calling watchEffect or renaming the function to reflect its mutating behavior (e.g., resolveOrAssignLabelId).

♻️ Proposed refactor to separate concerns

-function getAriaLabelledBy(
+function resolveAriaLabelledBy(
   labelSource?: LabelSource | null,
   generatedLabelId?: string,
 ): string | undefined {
   const label = findAssociatedLabel(labelSource)
   if (!label) {
     return undefined
   }
 
   if (!label.id && generatedLabelId) {
     label.id = generatedLabelId
   }
 
   return label.id || undefined
 }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/core/src/labelable-provider/useAriaLabelledBy.ts` around lines 62 -
76, The function getAriaLabelledBy mutates DOM state (assigns label.id) which is
unexpected for a getter; remove the side effect from getAriaLabelledBy (keep it
pure: return label.id || generatedLabelId || undefined) and move the assignment
of generatedLabelId to the caller (the watchEffect that calls getAriaLabelledBy)
where you can set label.id = generatedLabelId if needed; alternatively, if you
prefer keeping current behavior, rename getAriaLabelledBy to a mutating name
like resolveOrAssignLabelId to signal the side effect; use the existing helper
findAssociatedLabel and the generatedLabelId parameter to locate the label and
perform the assignment in the watchEffect or rename the function accordingly.

---

88-93: Next-sibling label lookup only checks immediate sibling.

The fallback at lines 90-93 only checks nextElementSibling. If the <label> is not immediately adjacent (e.g., separated by a wrapper or other elements), it won't be found. This may be intentional for simplicity, but consider documenting this limitation.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/core/src/labelable-provider/useAriaLabelledBy.ts` around lines 88 -
93, The current fallback in useAriaLabelledBy only checks the immediate
nextElementSibling (via labelSource and controlId) so a nearby <label> separated
by wrappers is missed; update the logic in useAriaLabelledBy to walk subsequent
siblings (looping over nextElementSibling) and return the first element that is
an HTMLLabelElement whose htmlFor equals controlId (or alternatively use
parentElement.querySelector(`label[for="${controlId}"]`) if broader search is
desired); update the references to labelSource, controlId and nextSibling
accordingly and add a brief comment documenting the behavior.

packages/core/src/field/error/FieldError.vue (1)

73-90: Potential redundant cleanup in onUnmounted.

The watch at lines 73-84 removes the ID when rendered becomes false, and onUnmounted at lines 86-90 also removes the ID. This means if the component is unmounted while rendered is false, the ID is filtered twice.

While harmless (filtering a non-existent ID is a no-op), the onUnmounted cleanup is only necessary if the component unmounts while rendered is true. Consider adding a guard:

♻️ Proposed guard in onUnmounted

 onUnmounted(() => {
-  if (id) {
+  if (id && rendered.value) {
     setMessageIds(ids => ids.filter(item => item !== id))
   }
 })

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/core/src/field/error/FieldError.vue` around lines 73 - 90, The
onUnmounted cleanup is redundant when rendered is already false; change the
onUnmounted handler to only remove the id if both id and rendered.value are
truthy. Update the onUnmounted callback (which currently calls setMessageIds(ids
=> ids.filter(...))) to guard with rendered.value (and id) before calling
setMessageIds so it only runs when the message was still considered rendered;
keep the existing watch and setMessageIds logic unchanged.

packages/core/src/form/FormContext.ts (1)

49-55: Default context uses mock refs - ensure read-only usage.

The defaultContext uses plain objects cast as Ref types (lines 50-54). This works for read-only fallback scenarios but will silently fail if any consuming code attempts to mutate these values (e.g., submitAttempted.value = true).

This is a common pattern for default injection values, but consider adding a comment to clarify that these are intentionally non-reactive fallbacks for when no FormContext is provided.

📝 Proposed documentation

+/**
+ * Default context used when no Form provider is present.
+ * These are non-reactive stubs; writes will have no effect.
+ */
 const defaultContext: FormContext = {
   errors: { value: EMPTY_OBJECT as FormErrors } as Ref<FormErrors>,

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/core/src/form/FormContext.ts` around lines 49 - 55, The
defaultContext object uses plain objects cast to Ref/ShallowRef types
(defaultContext with fields errors, clearErrors, formRef, validationMode,
submitAttempted) which are non-reactive and will break if mutated; add a clear
inline comment above defaultContext stating these are intentional read-only,
non-reactive fallbacks for injection consumers and warn that consumers must not
assign to .value (or alternatively replace these with proper readonly refs if
mutation is required); update the comment to mention the specific symbols
(defaultContext, errors, clearErrors, formRef, validationMode, submitAttempted)
so future maintainers know the intended read-only usage.

packages/core/src/field/control/FieldControl.vue (1)

105-113: labelSourceId is not reactive.

Passing controlId.value as labelSourceId captures the value at call time. If controlId could change after mount (e.g., if props.id changes), useAriaLabelledBy won't receive the updated value.

If controlId is guaranteed to be stable after mount, this is acceptable. Otherwise, consider passing the computed ref or making labelSourceId reactive in the hook options.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/core/src/field/control/FieldControl.vue` around lines 105 - 113, The
current call to useAriaLabelledBy captures a non-reactive snapshot by passing
controlId.value into labelSourceId; change it to pass a reactive ref (e.g.,
controlId or a computed wrapper) so useAriaLabelledBy receives updates when
controlId changes. Update the call site where labelSourceId is set (the
useAriaLabelledBy invocation referencing controlId.value) to provide a
ref/computed instead, keeping the other args (ariaLabelledByAttr, labelId,
inputElementRef, enableFallback) unchanged.

packages/core/src/form/Form.vue (1)

12-12: Empty interface serves no purpose.

As flagged by static analysis, FormState is equivalent to {}. If this is a placeholder for future state properties, consider adding a TODO comment or defining at least one property. Otherwise, remove it.

♻️ Option 1: Add TODO comment

-export interface FormState {}
+// TODO: Add form-level state properties (e.g., submitting, validating)
+export interface FormState {}

♻️ Option 2: Remove if unused

If FormState is not consumed anywhere, consider removing it entirely and using Record<string, never> or object where needed.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@packages/core/src/form/Form.vue` at line 12, Remove or clarify the empty
FormState interface: either delete the export interface FormState {} and replace
its usages with Record<string, never> or object where appropriate, or keep it
but add a TODO comment and at least one placeholder property (e.g., // TODO: add
form state fields) so it's not equivalent to {}. Update any references to
FormState in the codebase (components, props, or types) to the chosen
alternative (Record<string, never>/object or the new placeholder property) and
ensure type imports/exports that referenced FormState are adjusted accordingly.

docs/content/docs/components/form.md (1)

31-31: Minor: Consider using "third-party" with hyphen.

For grammatical correctness when used as a compound adjective, "third-party APIs" is preferred over "3rd party APIs".

📝 Suggested fix

-You can use the `@form-submit` event instead of the native `submit` event to access form values as a JavaScript object. This is useful when you need to transform the values before submission, or integrate with 3rd party APIs. When used, `preventDefault` is called on the native submit event.
+You can use the `@form-submit` event instead of the native `submit` event to access form values as a JavaScript object. This is useful when you need to transform the values before submission, or integrate with third-party APIs. When used, `preventDefault` is called on the native submit event.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/content/docs/components/form.md` at line 31, Update the documentation
text that references "3rd party APIs" to read "third-party APIs" (hyphenated)
for grammatical correctness; the reference occurs in the sentence describing the
`@form-submit` event so edit that sentence to replace "3rd party APIs" with
"third-party APIs".