@featherk/composables 0.11.1 → 0.12.0

package/docs/observer/useIntersectionObserver.md

@@ -0,0 +1,95 @@
+# useIntersectionObserver
+
+[Back to Composables README](https://github.com/NantHealth/featherk/blob/integration/packages/composables/README.md)
+
+Observes a reactive DOM target against a lazily resolved scroll container. It is useful for grid cells, virtualized rows, and other elements that must react after they leave their visible viewport.
+
+## Grid Containers
+
+When observing an element rendered in a Kendo Grid, explicitly provide the grid's scrolling content element through `root`. The composable cannot infer the correct viewport from the Grid wrapper because a grid may be nested in additional scrolling layouts.
+
+```ts
+root: () => cellRef.value?.closest(".k-grid-content") ?? null,
+```
+
+Do not use the outer Grid component element unless it is the element that actually scrolls. For standard Kendo Grid layouts, use `.k-grid-content`.
+
+## Native Tables
+
+The composable works the same way with a regular HTML table. Place the table in a scrolling wrapper and use that wrapper as `root`; the `<tr>` is the observed target.
+
+```vue
+<template>
+  <div ref="tableViewportRef" class="table-viewport">
+    <table>
+      <tbody>
+        <tr ref="rowRef">
+          <td>Product row</td>
+        </tr>
+      </tbody>
+    </table>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ref } from "vue";
+import { useIntersectionObserver } from "@featherk/composables";
+
+// Step 1: bind refs to the native scroll wrapper and target table row.
+const tableViewportRef = ref<HTMLElement | null>(null);
+const rowRef = ref<HTMLTableRowElement | null>(null);
+
+// Step 2: use the scrolling wrapper as root and react in consumer state.
+useIntersectionObserver({
+  target: rowRef,
+  root: () => tableViewportRef.value,
+  threshold: 0,
+  onChange: (entry) => {
+    if (!entry.isIntersecting) closeMenu();
+  },
+});
+</script>
+
+<style>
+.table-viewport {
+  height: 400px;
+  overflow: auto;
+}
+</style>
+```
+
+## Quick Start
+
+1. Create a ref for the element to observe.
+2. Pass a lazy `root` resolver for its clipping container.
+3. Handle intersection changes in the consuming component; the composable does not own menu or application state.
+
+```ts
+import { ref } from "vue";
+import { useIntersectionObserver } from "@featherk/composables";
+
+// Step 1: bind this ref to the target element.
+const cellRef = ref<Element | null>(null);
+
+// Step 2: resolve the scroll root only after the target is mounted.
+// Step 3: keep application-specific visibility behavior in the consumer.
+useIntersectionObserver({
+  target: cellRef,
+  root: () => cellRef.value?.closest(".k-grid-content") ?? null,
+  threshold: 0,
+  onChange: (entry) => {
+    if (!entry.isIntersecting) closeMenu();
+  },
+});
+```
+
+## Threshold
+
+`threshold` accepts one number or an array of numbers in the inclusive interval $[0, 1]$. Values outside that range are invalid according to the browser `IntersectionObserver` API. It defaults to `1`.
+
+- `0`: callback runs when the target enters the root and again when it fully leaves. Use this to dismiss a popup only after its trigger has fully scrolled out of view.
+- `0.5`: callback runs as the visible portion crosses $50\%$.
+- `1`: callback runs when the target becomes fully visible or stops being fully visible. This is the default.
+- `[0, 0.5, 1]`: callback runs when the target crosses any listed visibility boundary.
+
+`entry.isIntersecting` becomes `false` only after the target leaves the root entirely, regardless of the configured threshold. The composable disconnects automatically on component unmount and re-observes when `target` changes.

package/docs/registry/useActiveIdRegistry.md

@@ -0,0 +1,136 @@
+# useActiveIdRegistry
+
+[Back to Composables README](https://github.com/NantHealth/featherk/blob/integration/packages/composables/README.md)
+
+Tracks a single active id across a list of rendered elements (grid rows, tabs, action buttons, etc.) while also resolving that id back to its mounted DOM element.
+
+This helper is for shared-instance patterns where one popup/menu instance is reused across many triggers, but only a single item should be active/open at a time.
+
+## Why use it
+
+When a popup or menu instance is shared across a grid or list, a simple boolean per item is not enough to coordinate the active target. `useActiveIdRegistry` keeps two things in sync:
+
+- the active id for the list
+- the mounted element for that active id
+
+This lets consumers derive both `isOpen` and `triggerRef` from the same registry, rather than re-implementing one-off bookkeeping in each view.
+
+## Quick Start
+
+1. Create a registry instance at the shared list boundary so one active id drives the whole set of triggers.
+2. Register each mounted element by id as it appears or re-renders, including Kendo/Vue component refs via `$el`.
+3. Bind the registry's `isActive`/`activeElement` to the shared popup/menu instance and activate the item that should open.
+4. Deactivate when the item closes so the previously active trigger is demoted and the next item can become active.
+
+```ts
+// Step 1: one registry manages the list-wide active id
+const registry = useActiveIdRegistry<number>();
+
+// Step 2: register each element as it mounts or re-renders
+registry.register(1, rowElement); // Step 2
+registry.register(2, buttonElement); // Step 2
+
+// Step 3: connect the registry to a shared popup/menu instance
+const isOpen = registry.isActive;
+const triggerRef = registry.activeElement;
+
+// Step 4: activate/deactivate when the current item opens or closes
+registry.activate(2);
+
+if (registry.isIdActive(2)) {
+  // active row/button is selected
+}
+
+registry.deactivate();
+```
+
+## Basic Usage
+
+```ts
+const rowRegistry = useActiveIdRegistry<number>();
+
+const rowMenu = usePopupMenu({
+  isOpen: rowRegistry.isActive,
+  triggerRef: rowRegistry.activeElement,
+  menuRef: rowMenuRef,
+  triggerMode: "row",
+  requestShow: () => {
+    // parent-owned open state is handled by registry activation
+  },
+  requestHide: () => rowRegistry.deactivate(),
+});
+
+const toggleRowMenu = (id: number) => {
+  if (rowRegistry.isIdActive(id)) {
+    rowRegistry.deactivate();
+    return;
+  }
+
+  rowRegistry.activate(id);
+};
+```
+
+This pattern is designed for one shared popup/menu instance across many rendered items. The active id stays in sync with the mounted DOM element, so the popup opens against the correct trigger without a per-item boolean for every row.
+
+## API
+
+```ts
+const registry = useActiveIdRegistry<number>();
+
+registry.register(1, rowElement);
+registry.register(2, buttonElement);
+
+registry.activate(2);
+
+const isOpen = registry.isActive;
+const triggerRef = registry.activeElement;
+
+if (registry.isIdActive(2)) {
+  // active row/button is selected
+}
+
+registry.deactivate();
+```
+
+## Return shape
+
+- `activeId`: readonly current id or `null`
+- `isActive`: computed `true` when an id is active
+- `activeElement`: computed DOM element for the active id
+- `register(id, el)`: stores or removes the element for a given id
+- `resolve(id)`: returns the registered DOM element for `id`
+- `activate(id)`: sets the active id
+- `deactivate()`: clears the active id
+- `isIdActive(id)`: checks whether a given id is the current active id
+
+## Shared-instance popup usage
+
+```ts
+const rowRegistry = useActiveIdRegistry<number>();
+
+const rowMenu = usePopupMenu({
+  isOpen: rowRegistry.isActive,
+  triggerRef: rowRegistry.activeElement,
+  menuRef: rowMenuRef,
+  triggerMode: "row",
+  requestShow: () => {
+    // parent-owned open state is handled by activation logic
+  },
+  requestHide: () => rowRegistry.deactivate(),
+});
+
+const toggleRowMenu = (id: number) => {
+  if (rowRegistry.isIdActive(id)) {
+    rowRegistry.deactivate();
+    return;
+  }
+
+  rowRegistry.activate(id);
+};
+```
+
+## Notes
+
+- Accepts both raw DOM elements and Vue/Kendo component refs exposing `$el`.
+- Works well with virtualized or keyed re-renders because the registry re-resolves the current active element when the underlying DOM node changes.
+- This helper is intentionally generic; it does not own popup behavior or ARIA attributes itself.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@featherk/composables",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "main": "dist/featherk-composables.umd.js",
   "module": "dist/featherk-composables.es.js",
   "types": "dist/index.d.ts",
@@ -40,6 +40,16 @@
       "import": "./dist/featherk-composables.es.js",
       "require": "./dist/featherk-composables.umd.js"
     },
+    "./observer": {
+      "types": "./dist/observer/index.d.ts",
+      "import": "./dist/featherk-composables.es.js",
+      "require": "./dist/featherk-composables.umd.js"
+    },
+    "./registry": {
+      "types": "./dist/registry/index.d.ts",
+      "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",
@@ -49,6 +59,11 @@
       "types": "./dist/address/index.d.ts",
       "import": "./dist/featherk-composables.es.js",
       "require": "./dist/featherk-composables.umd.js"
+    },
+    "./id": {
+      "types": "./dist/id/index.d.ts",
+      "import": "./dist/featherk-composables.es.js",
+      "require": "./dist/featherk-composables.umd.js"
     }
   },
   "files": [