# `@featherk/composables`

Vue 3 composables that improve Kendo UI for Vue behavior and accessibility.

## Composables Overview

- **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)
- **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)
- **Date**: `useMaskedDateInput` — Masked single-date input with steppers and validation.
  - Guide: [docs/date/useMaskedDateInput.md](https://github.com/NantHealth/featherk/blob/integration/packages/composables/docs/date/useMaskedDateInput.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)
- **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)
- **Grid**: `useGridA11y` — Accessible row-level navigation and column menu keyboard support.
  - Guide: [docs/grid/useGridA11y.md](https://github.com/NantHealth/featherk/blob/integration/packages/composables/docs/grid/useGridA11y.md)
- **Grid**: `useGridActiveFilter` — Reactive header class resolver that marks filtered columns as `"active"`.
  - Guide: [docs/grid/useGridActiveFilter.md](https://github.com/NantHealth/featherk/blob/integration/packages/composables/docs/grid/useGridActiveFilter.md)
- **Grid**: `useGridRowAction` — Safe, accessible row click and keyboard activation handlers for grid rows with interaction and selection guards.
  - Guide: [docs/grid/useGridRowAction.md](https://github.com/NantHealth/featherk/blob/integration/packages/composables/docs/grid/useGridRowAction.md)
- **ID**: `useCompositeId` — SSR-safe component-scoped DOM ID generation for related controls and ARIA relationships.
  - Guide: [docs/id/useCompositeId.md](https://github.com/NantHealth/featherk/blob/integration/packages/composables/docs/id/useCompositeId.md)
- **Menu**: `usePopupMenu` — Accessible Kendo Popup + Menu action-menu toggling, selection modality, and contextual focus restoration.
  - Guide: [docs/menu/usePopupMenu.md](https://github.com/NantHealth/featherk/blob/integration/packages/composables/docs/menu/usePopupMenu.md)
- **Observer**: `useIntersectionObserver` — Reactive intersection observation with optional clipping-root tracking and SSR-safe no-op behavior.
  - Guide: [docs/observer/useIntersectionObserver.md](https://github.com/NantHealth/featherk/blob/integration/packages/composables/docs/observer/useIntersectionObserver.md)
- **Range**: `useMaskedDateRangeInput` — Masked date range input with validation, clamp, and optional popup coordination.
  - Guide: [docs/range/useMaskedDateRangeInput.md](https://github.com/NantHealth/featherk/blob/integration/packages/composables/docs/range/useMaskedDateRangeInput.md)
- **Registry**: `useActiveIdRegistry` — Shared active-id bookkeeping for single-open patterns across many grid rows/buttons.
  - Guide: [docs/registry/useActiveIdRegistry.md](https://github.com/NantHealth/featherk/blob/integration/packages/composables/docs/registry/useActiveIdRegistry.md)
- **Registry**: `useExclusiveGroup` — Lifecycle-managed mutual exclusivity for active-id registries.
  - Guide: [docs/registry/useExclusiveGroup.md](https://github.com/NantHealth/featherk/blob/integration/packages/composables/docs/registry/useExclusiveGroup.md)
- **Time**: `useMaskedTimeInput` — Masked single-time input with AM/PM conveniences and bounds.
  - Guide: [docs/time/useMaskedTimeInput.md](https://github.com/NantHealth/featherk/blob/integration/packages/composables/docs/time/useMaskedTimeInput.md)
- **Trap**: `usePopupTrap` — Focus trap + Escape/Outside click close behavior for popups.
  - Guide: [docs/trap/usePopupTrap.md](https://github.com/NantHealth/featherk/blob/integration/packages/composables/docs/trap/usePopupTrap.md)

## Importing Composables

You can import directly from subpaths or from the package root.

Subpath imports (recommended for clarity):

```ts
// Grid
import {
  useGridA11y,
  useGridActiveFilter,
  useGridRowAction,
  type RowActionContext,
} from "@featherk/composables/grid";

// Date input
import {
  useMaskedDateInput,
  type DateChangePayload,
} from "@featherk/composables/date";

// Date range input
import {
  useMaskedDateRangeInput,
  type RangeChangePayload,
} from "@featherk/composables/range";

// Time input
import {
  useMaskedTimeInput,
  type TimeChangePayload,
} from "@featherk/composables/time";

// Popup focus trap utilities
import { usePopupTrap } from "@featherk/composables/trap";

// Kendo Popup + Menu action-menu utilities
import {
  usePopupMenu,
  type KendoMenuSelectEvent,
} from "@featherk/composables/menu";

// Shared active-id bookkeeping for single-open grid or list patterns
import {
  useActiveIdRegistry,
  useExclusiveGroup,
} from "@featherk/composables/registry";

// Intersection observer utilities
import { useIntersectionObserver } from "@featherk/composables/observer";

// Component-scoped DOM ID utilities
import { useCompositeId } from "@featherk/composables/id";

// Address utilities
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):

```ts
import {
  useGridA11y,
  useGridActiveFilter,
  useGridRowAction,
  type RowActionContext,
  useMaskedDateInput,
  type DateChangePayload,
  useMaskedDateRangeInput,
  type RangeChangePayload,
  useMaskedTimeInput,
  type TimeChangePayload,
  usePopupTrap,
  usePopupMenu,
  type KendoMenuSelectEvent,
  useActiveIdRegistry,
  useExclusiveGroup,
  useIntersectionObserver,
  useCompositeId,
  useZipTextBox,
  useUSAddress,
  useFieldsetValidationKit,
  useFieldsetTouchTracker,
} from "@featherk/composables";
```

`usePopupTrap` depends on VueUse integrations and focus-trap internally. Those runtime packages are shipped as regular dependencies of `@featherk/composables`, so consumers do not need to install them separately.

## Peer Dependencies

- Required: `vue`

```bash
npm install vue
```

## Notes

- Every public feature area has a source `index.ts` barrel, is re-exported from the package root, and has a matching public package subpath. For example, import `useIntersectionObserver` from `@featherk/composables/observer`, `useCompositeId` from `@featherk/composables/id`, or either from the package root. Consumers should not import internal `dist` paths.
- The runtime files for `useGridA11y`, `useGridActiveFilter`, and `useGridRowAction` live in `src/grid/`. All three are re-exported from the package root and from `@featherk/composables/grid` — no import path changes are needed by consumers.

## Changelog

Release history for all `@featherk/*` packages is maintained in a single [CHANGELOG.md](https://github.com/NantHealth/featherk/blob/integration/CHANGELOG.md).