@featherk/composables 0.8.1 → 0.9.0

package/README.md

@@ -18,6 +18,12 @@ Vue 3 composables that improve Kendo UI for Vue behavior and accessibility.
   - Guide: [docs/trap/usePopupTrap.md](https://github.com/NantHealth/featherk/blob/integration/packages/composables/docs/trap/usePopupTrap.md)
 - **Address**: `useZipTextBox` — Dynamic multi-mask ZIP code input (5-digit and ZIP+4) for Kendo Vue `TextBox`, with caret preservation, submit-gated validation, and focus-on-error support.
   - Guide: [docs/address/useZipTextBox.md](https://github.com/NantHealth/featherk/blob/integration/packages/composables/docs/address/useZipTextBox.md)
+- **Address**: `useUSAddress` — Orchestrates full US address form behavior, including delayed validation (via `useFieldsetValidationKit`), state options, ZIP integration, and normalized submit payloads.
+  - Guide: [docs/address/useUSAddress.md](https://github.com/NantHealth/featherk/blob/integration/packages/composables/docs/address/useUSAddress.md)
+- **Form**: `useFieldsetValidationKit` — Delayed fieldset validation kit with submit/touch gating, field helpers, invalid-focus targeting, and reset handling.
+  - Guide: [docs/form/useFieldsetValidationKit.md](https://github.com/NantHealth/featherk/blob/integration/packages/composables/docs/form/useFieldsetValidationKit.md)
+- **Form (Low-level)**: `useFieldsetTouchTracker` — Primitive focus-leave touch tracker that powers the validation kit.
+  - Guide: [docs/form/useFieldsetTouchTracker.md](https://github.com/NantHealth/featherk/blob/integration/packages/composables/docs/form/useFieldsetTouchTracker.md)
 
 ## Importing Composables
 
@@ -42,7 +48,10 @@ import { useMaskedTimeInput, type TimeChangePayload } from '@featherk/composable
 import { usePopupTrap } from '@featherk/composables/trap';
 
 // Address utilities
-import { useZipTextBox } from '@featherk/composables/address';
+import { useZipTextBox, useUSAddress, type USAddressSubmitPayload } from '@featherk/composables/address';
+
+// Form utilities
+import { useFieldsetValidationKit, useFieldsetTouchTracker } from '@featherk/composables/form';
 ```
 
 Root imports (types are aliased to avoid name collisions):
@@ -59,6 +68,9 @@ import {
   type TimeChangePayload,
   usePopupTrap,
   useZipTextBox,
+  useUSAddress,
+  useFieldsetValidationKit,
+  useFieldsetTouchTracker,
 } from '@featherk/composables';
 ```
 

package/dist/address/_useUSAddressFormData.d.ts

@@ -0,0 +1,29 @@
+export interface USAddressFormData {
+    address1: string;
+    address2: string;
+    city: string;
+    state: string | null;
+    zip: string;
+}
+/**
+ * Manages the form data model for a US address.
+ *
+ * Note: this is internal UI data state, not just the US "state" (AL, CA, etc.) field.
+ * @returns An object containing form data and field event handlers.
+ */
+export declare function useUSAddressFormData(): {
+    formData: {
+        address1: string;
+        address2: string;
+        city: string;
+        state: string | null;
+        zip: string;
+    };
+    onAddress1Input: (...args: unknown[]) => void;
+    onAddress2Input: (...args: unknown[]) => void;
+    onCityInput: (...args: unknown[]) => void;
+    onStateChange: (event: {
+        value: string | null;
+    }) => void;
+    resetFormData: () => void;
+};

package/dist/address/_useUSAddressFormData.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/address/_useUSAddressValidation.d.ts

@@ -0,0 +1,19 @@
+import { type MaybeRefOrGetter } from "vue";
+import type { USAddressFormData } from "./_useUSAddressFormData";
+interface UseUSAddressValidationOptions {
+    formData: USAddressFormData;
+    isZipValid: MaybeRefOrGetter<boolean>;
+}
+/**
+ * Manages the validation state for a US address.
+ * @param options - The options object containing form data and ZIP code validity.
+ * @returns An object containing validation state for each field and the overall address.
+ */
+export declare function useUSAddressValidation(options: UseUSAddressValidationOptions): {
+    strictAddress1Valid: import("vue").ComputedRef<boolean>;
+    strictCityValid: import("vue").ComputedRef<boolean>;
+    strictStateValid: import("vue").ComputedRef<boolean>;
+    strictZipValid: import("vue").ComputedRef<boolean>;
+    strictAddressValid: import("vue").ComputedRef<boolean>;
+};
+export {};

package/dist/address/_useUSAddressValidation.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/address/_useUSAddressZip.d.ts

@@ -0,0 +1,13 @@
+import type { USAddressFormData } from "./_useUSAddressFormData";
+/**
+ * Manages the ZIP code field for a US address.
+ * @param formData - The form data object containing the ZIP code.
+ * @returns An object containing ZIP code display, validity, wrapper class, input handler, and reset function.
+ */
+export declare function useUSAddressZip(formData: USAddressFormData): {
+    zipDisplay: import("vue").Ref<string, string>;
+    isZipValid: import("vue").ComputedRef<boolean>;
+    zipWrapperClass: string;
+    onZipInput: (...args: unknown[]) => void;
+    resetZip: () => void;
+};

package/dist/address/_useUSAddressZip.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/address/index.d.ts

@@ -1,2 +1,4 @@
 export { useZipTextBox } from "./useZipTextBox";
 export type { ZipPayload, UseZipTextBoxOptions, UseZipTextBoxState, UseZipTextBoxBindings, UseZipTextBoxDerived, UseZipTextBoxActions, UseZipTextBoxApi, } from "./useZipTextBox";
+export { useUSAddress } from "./useUSAddress";
+export type { USAddressSubmitPayload } from "./useUSAddress";

package/dist/address/usStates.d.ts

@@ -0,0 +1,5 @@
+export type UsStateOption = {
+    label: string;
+    value: string;
+};
+export declare const US_STATES_BY_ABBREVIATION: UsStateOption[];

package/dist/address/useUSAddress.d.ts

@@ -0,0 +1,62 @@
+import { type Ref } from "vue";
+interface UseUSAddressOptions {
+    formRef: Ref<HTMLFormElement | null>;
+    fieldsetRef: Ref<HTMLFieldSetElement | null>;
+}
+export interface USAddressSubmitPayload {
+    address1: string;
+    address2: string;
+    city: string;
+    state: string;
+    zip: string;
+}
+/**
+ * Composable for managing a US address form.
+ * @param options - The options object containing form and fieldset references.
+ * @returns An object containing form state, validation state, and handlers.
+ */
+export declare function useUSAddress(options: UseUSAddressOptions): {
+    formData: {
+        address1: string;
+        address2: string;
+        city: string;
+        state: string | null;
+        zip: string;
+    };
+    submitted: Ref<boolean, boolean>;
+    touched: Ref<boolean, boolean>;
+    addressValidate: import("vue").ComputedRef<boolean>;
+    address1Valid: import("vue").ComputedRef<boolean>;
+    cityValid: import("vue").ComputedRef<boolean>;
+    stateValid: import("vue").ComputedRef<boolean>;
+    zipValid: import("vue").ComputedRef<boolean>;
+    addressValid: import("vue").ComputedRef<boolean>;
+    stateDefaultItem: {
+        value: any;
+        label: string;
+    };
+    stateOptions: {
+        label: string;
+        value: string;
+    }[];
+    zipDisplay: Ref<string, string>;
+    zipWrapperClass: string;
+    onAddress1Input: (...args: unknown[]) => void;
+    onAddress2Input: (...args: unknown[]) => void;
+    onCityInput: (...args: unknown[]) => void;
+    onStateChange: (event: {
+        value: string | null;
+    }) => void;
+    onZipInput: (...args: unknown[]) => void;
+    onFieldsetFocusout: (event: FocusEvent) => void;
+    normalizedPayload: import("vue").ComputedRef<USAddressSubmitPayload>;
+    submit: () => Promise<{
+        isValid: false;
+        payload: any;
+    } | {
+        isValid: true;
+        payload: USAddressSubmitPayload;
+    }>;
+    reset: () => void;
+};
+export {};

package/dist/address/useUSAddress.test.d.ts

@@ -0,0 +1 @@
+export {};