@featherk/composables 0.4.11 → 0.5.0

package/README.md

@@ -1,153 +1,93 @@
 # `@featherk/composables`
 
-> This package provides Vue 3 composables intended to augment and improve Kendo UI for Vue (Telerik) component behavior.
->
-> *This package is not affiliated with or approved by Telerik.*
+Vue 3 composables that improve Kendo UI for Vue behavior and accessibility.
 
-## useGridA11y — Integration Quick Reference
-
-### BIG DISCLAIMER
-
-> This package is experimental and **NOT READY FOR PRODUCTION**.  Do not use this package in production environments. The API, types, and build output are unstable. Tests and documentation are incomplete. You may encounter breaking changes, missing features, or rough edges. Use only for local experimentation or as a reference.
-
-### Compatibility
-
-> The current version of `useGridA11y` composable was developed targeting Kendo UI for Vue version 6.4.1.
->*Use of Kendo UI for Vue Grid requires a paid [license](https://www.telerik.com/purchase/kendo-ui) from Telerik.*
->
->See [Kendo UI for Vue Grid Documentation](https://www.telerik.com/kendo-vue-ui/components/grid)
-
-### Notes
+## Importing Composables
 
-- The composable expects a Grid ref (a Vue ref to the Grid component).
-- For row-level navigation, disable the Grid's cell-level dynamic tabindex behavior (omit or set `navigatable="false"` on the Grid).
-- The composable returns helpers for keyboard handling, focus management, initialization (new `initA11y()`), and sort/filter interactions.
+You can import directly from subpaths or from the package root.
 
-### Styling and the `.fk-grid` class
+Subpath imports (recommended for clarity):
 
-- The composable will add the CSS class `.fk-grid` to the Grid's root element (see `setupGridStyling()` in the source). The composable itself does NOT include any CSS (no inline styles or stylesheet).
-- The `.fk-grid` class is a hook used by the FeatherK stylesheet to apply visual styles. To see visual indicators (for example, the active/filtered status), you must include the appropriate FeatherK stylesheet for Kendo in your application.
-- Ensure you are using the matching FeatherK styling release for correct visuals — e.g. `featherk-q3-2024-v#.css` (replace `#` with the patch version you are using).
-
-### Prerequisites
-
-- Vue 3 (script setup)
-- `@progress/kendo-vue-grid` installed
-- `@featherk/composables` installed
-
-Install (if needed)
-
-```bash
-npm install @featherk/composables
-```
+```ts
+// Date input
+import { useMaskedDateInput, DateChangePayload } from '@featherk/composables/date';
 
-### 1) Minimal import + setup
+// Date range input
+import { useMaskedDateRangeInput, RangeChangePayload } from '@featherk/composables/range';
 
-Place inside a `<script setup lang="ts">` block. Provide a Grid ref and call the composable.
+// Time input
+import { useMaskedTimeInput, TimeChangePayload } from '@featherk/composables/time';
 
-```ts
-import { ref, onMounted, watch } from 'vue';
-import { useGridA11y } from '@featherk/composables';
-
-const gridRef = ref(null);
-const dataResult = ref({ data: [] }); // example data container
-
-const {
-  activeFilterButton,
-  handleGridKeyDown,
-  handleSortChange,
-  initA11y // NEW: must be called after Grid + data are present in DOM
-} = useGridA11y(gridRef);
+// Popup focus trap utilities
+import { usePopupTrap } from '@featherk/composables/trap';
 ```
 
-### 2) Initialize accessibility after Grid mounts and data is available
-
-Call `initA11y()` once the Grid element is in the DOM and the initial (non-empty) data set is ready. If data loads async, watch it. `initA11y()` performs initial attribute setup, internal bookkeeping, and prepares focus targets.
+Root imports (types are aliased to avoid name collisions):
 
 ```ts
-onMounted(() => {
-  // Adjust source as needed for your data state
-  watch(
-    () => dataResult.value.data,
-    (rows) => {
-      if (rows && rows.length && gridRef.value) {
-        initA11y();        // safe to call again; will no-op after first successful init
-      }
-    },
-    { immediate: true }
-  );
-});
+import {
+  useMaskedDateInput,
+  DateChangePayload,
+  useMaskedDateRangeInput,
+  RangeChangePayload,
+  useMaskedTimeInput,
+  TimeChangePayload,
+  usePopupTrap,
+} from '@featherk/composables';
 ```
 
-If data can change from empty to non-empty multiple times, the composable guards against redundant full initialization.
-
-### 3) Wire keyboard handler on the Grid
+## useGridA11y — Integration Quick Reference
 
-Template snippet showing essential bindings (keep other `Grid` props as required by your app):
+## Composables Overview
 
-```html
-<Grid
-  ref="gridRef"
-  :dataItems="dataResult.data"
-  :dataItemKey="'id'"
-  :rowRender="renderRow"            // optional: aria-label for screen reader
-  @keydown="handleGridKeyDown"      // keyboard navigation
-  @sortchange="handleSortChange"    // composable-aware sort handling
-  navigatable="false"               // turn off cell to cell navigation
-/>
-```
+- **Grid**: `useGridA11y` — Accessible row-level navigation and column menu keyboard support.
+  - Guide: [docs/grid/useGridA11y.md](./docs/grid/useGridA11y.md)
+- **Date**: `useMaskedDateInput` — Masked single-date input with steppers and validation.
+  - Guide: [docs/date/useMaskedDateInput.md](./docs/date/useMaskedDateInput.md)
+- **Range**: `useMaskedDateRangeInput` — Masked date range input with validation, clamp, and optional popup coordination.
+  - Guide: [docs/range/useMaskedDateRangeInput.md](./docs/range/useMaskedDateRangeInput.md)
+- **Time**: `useMaskedTimeInput` — Masked single-time input with AM/PM conveniences and bounds.
+  - Guide: [docs/time/useMaskedTimeInput.md](./docs/time/useMaskedTimeInput.md)
+- **Trap**: `usePopupTrap` — Focus trap + Escape/Outside click close behavior for popups.
+  - Guide: [docs/trap/usePopupTrap.md](./docs/trap/usePopupTrap.md)
 
-### 4) Provide an accessible row renderer (`aria-label`)
+## Importing
 
-> Not part of `@featherk/composable`, but good practice
-
-Kendo Grid `rowRender` allows you to add an `aria-label` so screen readers announce row contents.
+Subpath imports (recommended):
 
 ```ts
-const renderRow = (h: any, trElement: any, defaultSlots: any, props: any) => {
-  const ariaLabel = `Name: ${props.dataItem.name}, Price: ${props.dataItem.price}`;
-  const merged = { ...trElement.props, 'aria-label': ariaLabel };
-  return h('tr', merged, defaultSlots);
-};
+import { useGridA11y } from '@featherk/composables/grid';
+import { useMaskedDateInput } from '@featherk/composables/date';
+import { useMaskedDateRangeInput } from '@featherk/composables/range';
+import { useMaskedTimeInput } from '@featherk/composables/time';
+import { usePopupTrap } from '@featherk/composables/trap';
 ```
 
-### 5) Focus the active filter button after filter changes
+Root import (types are aliased to avoid collisions):
 
 ```ts
-import { nextTick } from 'vue';
-
-function onFilterChange(event: any) {
-  // update filter state + reload data
-  nextTick(() => {
-    if (activeFilterButton.value) {
-      activeFilterButton.value.focus();
-    }
-  });
-}
+import {
+  useGridA11y,
+  useMaskedDateInput,
+  useMaskedDateRangeInput,
+  useMaskedTimeInput,
+  usePopupTrap,
+} from '@featherk/composables';
 ```
 
-### 6) Custom sort handling with composable helper
+## Peer Dependencies
 
-```ts
-const optionalCustomSort = (event: any) => {
-  loader.value = true;
-  setTimeout(() => {
-    loader.value = false;
-    // apply sort state and reload data
-  }, 200);
-};
-
-function onSortChange(event: any) {
-  handleSortChange(event, optionalCustomSort);
-}
+- Required: `vue`
+- Optional (for `usePopupTrap`): `@vueuse/core`, `@vueuse/integrations`, `focus-trap`
+
+```bash
+npm install vue
+# If you use usePopupTrap
+npm install @vueuse/core @vueuse/integrations focus-trap
 ```
 
-### 7) Summary checklist
+> 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
 
-- Import and call `useGridA11y(gridRef)`
-- Wait for Grid mount + data, then call `initA11y()`
-- Bind returned keyboard handler to `Grid` `@keydown`
-- Bind returned sort handler to `Grid` `@sortchange` (optionally pass a custom callback)
-- Use returned `activeFilterButton` to manage focus after filter updates
-- Provide a `rowRender` that adds a descriptive `aria-label` for each row
-- Set `navigatable="false"` on the `Grid` to prefer row-level navigation
+- 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.

package/dist/date/index.d.ts

@@ -0,0 +1 @@
+export * from "./useMaskedDateInput";

package/dist/date/useMaskedDateInput.d.ts

@@ -0,0 +1,33 @@
+import { type Ref } from "vue";
+export type ChangePayload = {
+    value: Date | null;
+    event: any;
+};
+export declare function useMaskedDateInput(args: {
+    id: string;
+    onChange: (p: ChangePayload) => void;
+    onShowCalendar: (e: KeyboardEvent) => void;
+    externalValue?: Ref<string | Date | null | undefined>;
+    minDate?: Ref<Date | null | undefined>;
+    maxDate?: Ref<Date | null | undefined>;
+    dateFormat?: string;
+    debug?: boolean;
+}): {
+    raw: Ref<string, string>;
+    cursorPos: Ref<number, number>;
+    debugEnabled: Ref<boolean, boolean>;
+    debugLines: import("vue").ComputedRef<string[][]>;
+    placeholder: Ref<string, string>;
+    isValid: import("vue").ComputedRef<boolean>;
+    validationMessage: import("vue").ComputedRef<string>;
+    digitsOnly: import("vue").ComputedRef<string>;
+    month: Readonly<Ref<string, string>>;
+    day: Readonly<Ref<string, string>>;
+    year: Readonly<Ref<string, string>>;
+    datePart: (pos: number) => "mm" | "dd" | "yyyy";
+    handleChange: (event: any) => void;
+    handleKeyDown: (event: KeyboardEvent) => void;
+    handleWheel: (event: WheelEvent) => void;
+    handleKeyUp: (event: KeyboardEvent) => void;
+    handleClick: (event: MouseEvent) => void;
+};