# useFieldsetTouchTracker

[← Back to Composables README](https://github.com/NantHealth/featherk/blob/integration/packages/composables/README.md)

Low-level composable that tracks when focus leaves a fieldset and synchronizes the fieldset `aria-invalid` attribute from a provided validity function.

This is a primitive used by `useFieldsetValidationKit`. Most app-level form workflows should use the kit first and only use this composable directly for custom orchestration.

## Prerequisites

- Vue 3 Composition API

## Quick Start

```vue
<script setup lang="ts">
import { ref } from "vue";
import { useFieldsetTouchTracker } from "@featherk/composables/form";

const fieldsetRef = ref<HTMLFieldSetElement | null>(null);
const isValid = ref(false);

const { touched, onFocusout, reset } = useFieldsetTouchTracker(fieldsetRef, {
  isValid: () => isValid.value,
});
</script>

<template>
  <fieldset ref="fieldsetRef" @focusout="onFocusout">
    <!-- fields -->
  </fieldset>

  <button type="button" @click="reset">Reset Touch State</button>
  <p>Touched: {{ touched }}</p>
</template>
```

## API

### useFieldsetTouchTracker(fieldsetRef, options)

Tracks focus transitions for one fieldset.

#### Parameters

| Parameter | Type | Description |
|----------|------|-------------|
| `fieldsetRef` | `Ref<HTMLFieldSetElement \| null>` | Ref for the target fieldset. |
| `options.isValid` | `() => boolean` | Current validity function used to set `aria-invalid`. |

#### Returns

| Property | Type | Description |
|----------|------|-------------|
| `touched` | `Ref<boolean>` | Becomes `true` after a focus transition that leaves the fieldset. |
| `onFocusout` | `(event: FocusEvent) => void` | Focusout handler to bind on the fieldset. |
| `reset` | `() => void` | Sets `touched` back to `false`. |

## Behavior Notes

- `aria-invalid` is kept in sync with `!options.isValid()` via `watchEffect`.
- A focusout counts as "leaving" when the next focused element (`event.relatedTarget`) is not inside the fieldset.
- If `fieldsetRef.value` is `null`, the handler falls back to `event.currentTarget`.

## When to Use vs Validation Kit

Use `useFieldsetTouchTracker` when you want full control over delayed validation behavior.

Use `useFieldsetValidationKit` when you want:

- submit-or-touch gating (`submitted || touched`)
- delayed field-validity helpers
- focus-first-invalid helper
- reset handling for post-reset focus churn