npm package: @featherk/composables
Description: Vue 3 composables that improve Kendo UI for Vue behavior and accessibility.
Latest version: 0.6.12

# `@featherk/composables`

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

## Composables Overview

- **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)
- **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)
- **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)
- **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 } 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';
```

Root imports (types are aliased to avoid name collisions):

```ts
import {
  useMaskedDateInput,
  type DateChangePayload,
  useMaskedDateRangeInput,
  type RangeChangePayload,
  useMaskedTimeInput,
  type TimeChangePayload,
  usePopupTrap,
} from '@featherk/composables';
```

> I am getting build failures requesting libraries @vueuse/core @vueuse/integrations and focus-trap, when using only useGridA11y composable.
> useGridA11y currently does not use useFocusTrap composable, but has its own internal method for maintaining focus trap.  useGridA11y does not require the @vueuse or focus-trap libraries.

**Why this happens:**

- If a dependency is imported or required anywhere in the package entry points (even if not used by your code), your bundler or Node will try to resolve it.
- In index.ts, all composables are exported from a single file, so importing from `@featherk/composables` pulls in all submodules, including those that import `@vueuse/core`, `@vueuse/integrations`, and `focus-trap`.

**Workarounds:**

1. **Use subpath imports**

   Import only what you need, e.g.:

   ```ts
   import { useGridA11y } from '@featherk/composables/grid';
   ```

   This avoids loading the popup/focus-trap code.

2. **Install the dependencies**
   If you must use the root import, you need to install all peer dependencies:

   ```bash
   npm install @vueuse/core @vueuse/integrations focus-trap
   ```

**Recommendation:**
Prefer subpath imports for tree-shaking and to avoid unnecessary dependencies, as described in the README.

If you think this should be improved, consider opening an issue or PR to make `focus-trap` and VueUse truly optional by moving their imports inside the `usePopupTrap` function or using dynamic imports.

## Peer Dependencies

- Required: `vue`
- Optional (for `usePopupTrap`): `@vueuse/core`, `@vueuse/integrations`, `focus-trap`

```bash
npm install vue
# If you use usePopupTrap, or any of the date/time based composables
npm install @vueuse/core @vueuse/integrations focus-trap
```

> Note: VueUse and focus-trap are declared as optional peer dependencies so apps that don’t use `usePopupTrap` aren’t forced to install them. They are present as devDependencies in this repo to enable local type-checking and builds.

## Notes

- The runtime file `useGridA11y.ts` currently lives at the package root for compatibility. It may move to `src/grid` in a future release, but root exports will remain to avoid breaking imports.