@featherk/composables 0.8.1 → 0.9.0

package/docs/form/useFieldsetValidationKit.md

@@ -0,0 +1,150 @@
+# useFieldsetValidationKit
+
+[← Back to Composables README](https://github.com/NantHealth/featherk/blob/integration/packages/composables/README.md)
+
+Form orchestration composable for delayed fieldset validation UX.
+
+`useFieldsetValidationKit` composes `useFieldsetTouchTracker` and provides a kit-oriented API for:
+
+- delayed validation gate (`submitted || touched`)
+- field-level delayed validity wrappers
+- first-invalid focus targeting
+- reset behavior that avoids immediate re-trigger from reset-related focus transitions
+
+> `focusFirstInvalidField` is currently included as a convenience helper. It is
+> form-scoped rather than fieldset-scoped, so it does not cleanly belong to this
+> kit and is expected to move to a separate utility in a future release.
+
+## Prerequisites
+
+- Vue 3 Composition API
+
+## Quick Start
+
+```vue
+<script setup lang="ts">
+import { computed, ref } from "vue";
+import { useFieldsetValidationKit } from "@featherk/composables/form";
+
+const fieldsetRef = ref<HTMLFieldSetElement | null>(null);
+const formRef = ref<HTMLFormElement | null>(null);
+
+const submitted = ref(false);
+
+const firstName = ref("");
+const city = ref("");
+
+const firstNameValidRule = computed(() => firstName.value.trim().length >= 2);
+const cityValidRule = computed(() => city.value.trim().length >= 2);
+
+const isFieldsetValid = computed(
+  () => firstNameValidRule.value && cityValidRule.value,
+);
+
+const kit = useFieldsetValidationKit(fieldsetRef, {
+  submitted,
+  isValid: () => isFieldsetValid.value,
+});
+
+const { touched, fieldsetValidate, onFocusout, reset, focusFirstInvalidField } =
+  kit;
+
+const fieldValidations = kit.createFieldValidationsMap({
+  firstName: () => firstNameValidRule.value,
+  city: () => cityValidRule.value,
+});
+
+// fieldValidations.firstName and fieldValidations.city are ComputedRef<boolean>
+// values that stay true until fieldset validation is active.
+
+function onSubmit() {
+  submitted.value = true;
+  if (!isFieldsetValid.value) {
+    focusFirstInvalidField(formRef);
+  }
+}
+
+function onReset() {
+  submitted.value = false;
+  reset();
+}
+</script>
+
+<template>
+  <form ref="formRef" @submit.prevent="onSubmit" @reset.prevent="onReset">
+    <fieldset ref="fieldsetRef" @focusout="onFocusout">
+      <!-- controls bind to fieldsetValidate + fieldValidations -->
+    </fieldset>
+  </form>
+
+  <p>Touched: {{ touched }}</p>
+  <p>Validate: {{ fieldsetValidate }}</p>
+</template>
+```
+
+## What createFieldValidationsMap Returns
+
+You pass one object argument whose properties are the field rules:
+
+```ts
+const rules = {
+  firstName: () => firstNameValidRule.value,
+  city: () => cityValidRule.value,
+};
+```
+
+And the kit returns the same shape, but each field becomes a delayed
+`ComputedRef<boolean>`:
+
+```ts
+const fieldValidations = kit.createFieldValidationsMap(rules);
+
+fieldValidations.firstName.value;
+fieldValidations.city.value;
+```
+
+This is important because it lets you define field rules once, keep the field
+names intact, and apply the same delayed-validation gate consistently across
+the whole fieldset.
+
+## API
+
+### useFieldsetValidationKit(fieldsetRef, options)
+
+Creates delayed-validation behavior for a fieldset.
+
+#### Options
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `submitted` | `MaybeRefOrGetter<boolean>` | Yes | Consumer-owned submit state. Never mutated by the kit. |
+| `isValid` | `() => boolean` | Yes | Returns the entire fieldset's current true validity. |
+
+#### Returns
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `touched` | `Ref<boolean>` | Becomes `true` once focus leaves the fieldset. |
+| `fieldsetValidate` | `ComputedRef<boolean>` | Delayed validation gate: `submitted || touched`. |
+| `onFocusout` | `(event: FocusEvent) => void` | Bind to fieldset `focusout`. Handles touch tracking. |
+| `reset` | `() => void` | Clears touch state and suppresses one immediate post-reset focusout. |
+| `createFieldValidity` | `(isValid: MaybeRefOrGetter<boolean>) => ComputedRef<boolean>` | Wraps a field rule with delayed-validation gate behavior. |
+| `createFieldValidationsMap` | `<T>(isValidMap: T) => { [K in keyof T]: ComputedRef<boolean> }` | Accepts one object argument of named field rules and returns the same shape with delayed `ComputedRef<boolean>` values. |
+| `focusFirstInvalidField` | `(formRef: MaybeRefOrGetter<HTMLFormElement \| null>) => void` | Convenience helper that focuses the first invalid Kendo control in the form using `.k-invalid` selectors. This is expected to move out of the kit in a future release. |
+
+## Behavior Notes
+
+- Validation visibility is inactive until either:
+  - consumer sets `submitted = true`, or
+  - focus leaves the fieldset and marks `touched = true`.
+- `createFieldValidity` and `createFieldValidationsMap` return `true` while gated off, then expose real rule results once gated on.
+- `reset()` intentionally suppresses one immediate post-reset focusout to avoid reset-click focus churn re-arming validation immediately.
+- `reset()` also resets the underlying touch tracker to keep kit and tracker state synchronized.
+- `focusFirstInvalidField()` is available for now as a convenience, but it is a
+  form-level concern and not a natural fieldset-kit responsibility.
+
+## Recommended Usage
+
+For app forms, prefer this composable over `useFieldsetTouchTracker` directly.
+
+Use the touch tracker directly only when you need custom orchestration not covered by this kit.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@featherk/composables",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "main": "dist/featherk-composables.umd.js",
   "module": "dist/featherk-composables.es.js",
   "types": "dist/index.d.ts",
@@ -35,6 +35,11 @@
       "import": "./dist/featherk-composables.es.js",
       "require": "./dist/featherk-composables.umd.js"
     },
+    "./form": {
+      "types": "./dist/form/index.d.ts",
+      "import": "./dist/featherk-composables.es.js",
+      "require": "./dist/featherk-composables.umd.js"
+    },
     "./address": {
       "types": "./dist/address/index.d.ts",
       "import": "./dist/featherk-composables.es.js",
@@ -49,7 +54,7 @@
     "build": "vite build && npm run build:types",
     "build:types": "vue-tsc --emitDeclarationOnly --declaration --declarationDir dist",
     "test": "vitest --config vitest.config.ts",
-    "test:run": "vitest run --config vitest.config.ts",
+    "test:unit": "vitest run --config vitest.config.ts",
     "test:coverage": "vitest run --config vitest.config.ts --coverage",
     "clean": "rm -rf dist",
     "prepublishOnly": "npm run build"