@featherk/ui 0.11.1 → 0.12.0

package/docs/table/ActionCell.md

@@ -0,0 +1,118 @@
+# ActionCell
+
+[Back to UI README](https://github.com/NantHealth/featherk/blob/integration/packages/ui/README.md)
+
+`ActionCell` renders a configured set of repeatable Kendo action buttons. The parent owns one `useActiveIdRegistry`, one `usePopupMenu`, and one shared Kendo `Popup` and `Menu`; ActionCell registers every button with that parent-owned lifecycle.
+
+## Quick Start
+
+1. Define an `ActionCellConfig` with the triggers and item factories used by every row.
+2. Create one `useActiveIdRegistry` and one `usePopupMenu` in the parent.
+3. Pass a controller that creates deterministic trigger IDs and delegates button events to the shared popup lifecycle.
+4. Render one shared Popup/Menu from the parent using the registry's active element and active ID.
+
+```vue
+<template>
+  <table>
+    <tbody>
+      <tr v-for="row in rows" :key="row.id">
+        <td>
+          <!-- Step 3: repeat the trigger container for each data item. -->
+          <ActionCell
+            :data-item="row"
+            :config="config"
+            :menu-controller="menuController"
+          />
+        </td>
+      </tr>
+    </tbody>
+  </table>
+
+  <!-- Step 4: exactly one shared popup/menu for the collection. -->
+  <Popup :show="registry.isActive.value" :offset="popupMenu.offset.value">
+    <Menu ref="menuRef" :items="activeMenuItems" :vertical="true" />
+  </Popup>
+</template>
+
+<script setup lang="ts">
+import { computed, ref, type ComponentPublicInstance } from "vue";
+import { Popup } from "@progress/kendo-vue-popup";
+import { Menu } from "@progress/kendo-vue-layout";
+import {
+  useActiveIdRegistry,
+  usePopupMenu,
+} from "@featherk/composables";
+import {
+  ActionCell,
+  type ActionCellConfig,
+  type ActionCellMenuController,
+} from "@featherk/ui";
+
+type Row = { id: number; name: string };
+const rows = ref<Row[]>([]);
+
+// Step 1: describe every trigger rendered by a repeated ActionCell.
+const config: ActionCellConfig<Row> = {
+  triggers: [
+    {
+      key: "patient",
+      icon: patientIcon,
+      ariaLabel: "Patient actions",
+      items: (row) => [{ id: "view", text: `View ${row.name}` }],
+    },
+  ],
+};
+
+// Step 2: own one registry and popup lifecycle for the entire collection.
+const registry = useActiveIdRegistry<string>();
+const menuRef = ref<ComponentPublicInstance | null>(null);
+const popupMenu = usePopupMenu({
+  isOpen: registry.isActive,
+  triggerRef: registry.activeElement,
+  menuRef,
+  triggerMode: "button",
+  anchor: true,
+  requestShow: (id) => {
+    if (typeof id === "string") registry.activate(id);
+  },
+  requestHide: () => registry.deactivate(),
+});
+
+const menuController: ActionCellMenuController<Row> = {
+  registry,
+  getTriggerId: (trigger, row) => `${trigger.key}:${row.id}`,
+  handleTriggerClick: (id) => popupMenu.handleActionButtonClick(id),
+  handleTriggerKeydown: (id, ...args) =>
+    popupMenu.handleActionButtonKeydown(args[0] as KeyboardEvent, id),
+};
+
+const activeMenuItems = computed(() => []);
+</script>
+```
+
+`useCompositeId()` supplies component-local DOM IDs for ActionCell buttons. Do not use those IDs for the shared registry: `menuController.getTriggerId` must return a deterministic identity derived from the trigger and row, such as `patient:42`.
+
+## Keyboard Navigation
+
+`ActionCell` defaults each trigger button to `tabindex="-1"`, preserving the roving-focus
+model used by Kendo UI for Vue Grid with `useGridA11y`. When using `ActionCell` in a standard
+HTML table or another context where the action buttons should participate in sequential Tab
+navigation, pass `:tab-index="0"`:
+
+```vue
+<ActionCell
+  :data-item="row"
+  :tab-index="0"
+  :config="config"
+  :menu-controller="menuController"
+/>
+```
+
+This is a component-level focus policy and is intentionally separate from
+`ActionCellConfig`, which describes the actions themselves.
+
+## Types
+
+- `ActionCellConfig<TData>`: stable configuration object containing `triggers`.
+- `ActionCellTrigger<TData>`: defines `key`, `icon`, `ariaLabel`, optional `items(dataItem)`, and optional `disabled(dataItem)`.
+- `ActionCellMenuController<TData>`: parent-owned registry, trigger-ID resolver, and popup click/keyboard delegation contract.

package/docs/table/useActionCellMenu.md

@@ -0,0 +1,175 @@
+# useActionCellMenu
+
+[Back to UI README](https://github.com/NantHealth/featherk/blob/integration/packages/ui/README.md)
+
+Bundles the shared-popup wiring a parent needs to drive `ActionCell`: one `useActiveIdRegistry`,
+one `usePopupMenu`, and the derived active row/trigger/menu items. The parent still owns the
+`<Popup>`/`<Menu>` template elements and any business logic for the selected action.
+
+## Why This Lives in `@featherk/ui`, Not `@featherk/composables`
+
+Every other composable in `@featherk/composables` is generic: it improves or augments Kendo UI
+for Vue behavior without being tied to any specific `@featherk/ui` component. `useActionCellMenu`
+is the one exception, and deliberately so — it exists *only* to drive `ActionCell`. Its
+`actionCellProps` return value is shaped exactly as `ActionCell`'s props (`config`,
+`menuController`), and it has no purpose without that component.
+
+`useActionCellMenu` was first prototyped inside `@featherk/composables` (see
+[docs/design/action-cell-dx-follow-up.md](https://github.com/NantHealth/featherk/blob/integration/docs/design/action-cell-dx-follow-up.md)),
+because at the time `@featherk/composables` could not depend on `@featherk/ui` — the
+dependency direction is `@featherk/ui` → `@featherk/composables`, never the reverse. That meant
+the composable had to re-declare structurally-compatible `Like` types
+(`ActionCellConfigLike`/`ActionCellTriggerLike`/`ActionCellMenuControllerLike`) instead of
+importing `ActionCell`'s real `ActionCellConfig`/`ActionCellTrigger`/`ActionCellMenuController`
+types, relying on TypeScript's structural typing to keep them assignable. That duplication was a
+real maintenance risk: adding a field to the real type that this composable's logic needed to
+read did not fail to compile if the `Like` type wasn't updated to match — it would just silently
+be ignored.
+
+Moving `useActionCellMenu` here removes that risk entirely. `@featherk/ui` already depends on
+`@featherk/composables` (for `useActiveIdRegistry` and `usePopupMenu`), so this composable can
+import the real `ActionCellConfig`/`ActionCellTrigger`/`ActionCellMenuController`/
+`ActionCellMenuItem` types from [`./types`](https://github.com/NantHealth/featherk/blob/integration/packages/ui/src/table/types.ts)
+directly — no duplicated types, no drift risk, and the coupling to `ActionCell` is now explicit
+in the package boundary instead of implicit in a doc comment.
+
+`@featherk/composables` keeps `useActiveIdRegistry` and `usePopupMenu` as its own generic,
+component-agnostic building blocks; this composable is the `ActionCell`-specific convenience
+layer built on top of them, and belongs next to the component it drives.
+
+## Why use it
+
+`ActionCell` renders repeatable trigger buttons but intentionally owns no popup state itself
+— the parent supplies a `config` and a `menuController`. Wiring that controller by hand means
+authoring a `useActiveIdRegistry` registry, a `usePopupMenu` instance, `getTriggerId`, active row/trigger/menu-item
+computeds, click/keydown delegation, and menu select/escape handlers for every consumer.
+`useActionCellMenu` packages all of that into a single call, while still leaving the actual
+`<Popup>`/`<Menu>` markup and any row-specific business logic (`onActionSelected`) with the
+parent.
+
+This does not replace `useActiveIdRegistry` or `usePopupMenu` — it wraps them for the
+specific `ActionCell` shared-instance shape. Reach for the lower-level composables directly
+when driving a popup/menu that isn't backed by `ActionCell` (e.g. a row-level context menu).
+
+## Quick Start
+
+1. Define an `ActionCellConfig` and pass it, your row list, and a `getRowId` to
+   `useActionCellMenu`.
+2. Create a `menuRef` for the single shared Kendo `Menu` instance.
+3. Spread `actionCellProps` onto every `<ActionCell>` instance.
+4. Spread `popupProps`/`menuProps` onto the single shared `<Popup>`/`<Menu>`.
+5. Handle the selected action in `onActionSelected`, which already receives the resolved row
+   and trigger.
+
+```vue
+<template>
+  <!-- Step 3 -->
+  <ActionCell
+    v-for="row in rows"
+    :key="row.id"
+    :data-item="row"
+    v-bind="actionCellMenu.actionCellProps"
+  />
+
+  <!-- Step 4 -->
+  <Popup v-bind="actionCellMenu.popupProps.value">
+    <strong v-if="actionCellMenu.activeTitle.value">
+      {{ actionCellMenu.activeTitle.value }}
+    </strong>
+    <Menu ref="menuRef" v-bind="actionCellMenu.menuProps.value" />
+  </Popup>
+</template>
+
+<script setup lang="ts">
+import { ref } from "vue";
+import { ActionCell, useActionCellMenu, type ActionCellConfig } from "@featherk/ui";
+
+// Step 2
+const menuRef = ref(null);
+
+// Step 1
+const actionCellMenu = useActionCellMenu({
+  config: actionCellConfig, // ActionCellConfig<Row>
+  rows,
+  getRowId: (row) => row.id,
+  menuRef,
+  onActionSelected: (action, row, trigger) => {
+    // Step 5: row-specific business logic
+  },
+});
+</script>
+```
+
+## API
+
+| Option               | Required | Description                                                                                                                                       |
+| -------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `config`             | Yes      | `ActionCellConfig`-shaped trigger configuration, passed straight through to every `ActionCell`.                                                   |
+| `rows`               | Yes      | Current row list (ref, getter, or plain array); used to resolve the active row from its registry id.                                              |
+| `getRowId`           | Yes      | Derives a stable row id used to build the default `"<trigger.key>:<rowId>"` registry id.                                                          |
+| `getTriggerId`       | No       | Overrides registry ID formatting, but must preserve `<trigger.key>:<rowId>` semantics because active row and trigger resolution parse the ID.     |
+| `menuRef`            | Yes      | Ref to the single shared Kendo `Menu` instance.                                                                                                   |
+| `triggerMode`        | No       | Forwarded to `usePopupMenu`. Defaults to `"button"`.                                                                                              |
+| `anchor`             | No       | Forwarded to `usePopupMenu` for offset positioning. Defaults to `true` because the shared popup targets dynamically resolved ActionCell triggers. |
+| `resolveFocusTarget` | No       | Forwarded to `usePopupMenu` for keyboard-close focus restoration.                                                                                 |
+| `coexistsWith`       | No       | Sibling `useActiveIdRegistry` instances (e.g. a hand-rolled row-context menu) to deactivate whenever a trigger in this collection opens.          |
+| `onActionSelected`   | Yes      | Runs after a menu item is selected, with the resolved `(action, row, trigger)`.                                                                   |
+
+Each trigger in `config.triggers` may also define an optional `title?: (dataItem) => string`.
+When set, the resolved string is exposed via the returned `activeTitle` — it is *not* mixed
+into `menuProps.items`, since `useActionCellMenu` never renders markup and can't dictate how
+a consumer's `<Menu>` implementation would render a fake "title" item. Render `activeTitle`
+yourself as real markup (e.g. `<strong v-if="activeTitle">{{ activeTitle }}</strong>`) as a
+sibling of `<Menu>` inside the `<Popup>`.
+
+## Return shape
+
+| Property          | Description                                                                                                                            |
+| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `actionCellProps` | `{ config, menuController }` — spread onto every `<ActionCell>`.                                                                       |
+| `popupProps`      | Computed props (`show`, `offset`, `onClose`) — spread onto the shared `<Popup>`.                                                       |
+| `menuProps`       | Computed props (`items`, `vertical`, `onKeydown`, `onSelect`) — spread onto the shared `<Menu>`.                                       |
+| `activeRow`       | The row resolved from the currently active trigger, or `null`.                                                                         |
+| `activeTrigger`   | The trigger config resolved from the currently active trigger, or `null`.                                                              |
+| `activeTitle`     | Resolved `trigger.title(activeRow)`, or `null` when unset/nothing is active. Render it yourself — it is not part of `menuProps.items`. |
+
+### Trigger ID Constraint
+
+The default registry ID is `${trigger.key}:${getRowId(row)}`. A custom `getTriggerId` may
+change the formatting around that value, but it must preserve the same meaning: the first
+colon-separated segment must be the trigger key, and the remaining segments must reconstruct
+the row ID. `useActionCellMenu` parses the active ID to resolve `activeTrigger` and `activeRow`.
+
+For example, this is compatible:
+
+```ts
+getTriggerId: (trigger, row) => `${trigger.key}:row:${row.id}`
+```
+
+because the composable resolves `trigger.key` from the first segment and `row:${row.id}` as
+the row ID. An opaque format such as `action-${row.id}-${trigger.key}` is not compatible with
+the current implementation and will cause `activeRow`/`activeTrigger` to resolve to `null`.
+
+Supporting genuinely opaque custom IDs would require a future implementation change: maintain
+a lookup from each generated registry ID to its `{ row, trigger }` pair rather than deriving
+those values by parsing the ID. That would remove this formatting constraint, but would also
+require defining lookup lifecycle/re-render behavior before changing the public contract.
+
+## Notes
+
+- Reuses `@featherk/composables`'s `usePopupMenu`/`useActiveIdRegistry` mechanics as a
+  hand-rolled shared instance would; it does not introduce a new popup/menu implementation.
+- Only manages `ActionCell`'s button-mode triggers. A row-level context menu alongside an
+  `ActionCell` column still needs its own `useActiveIdRegistry` + `usePopupMenu` call with
+  `triggerMode: "row"` — see
+  [ActionCellGridDemo.vue](https://github.com/NantHealth/featherk/blob/integration/demos/src/views/ui/ActionCellGridDemo.vue)
+  for a worked example of the two coexisting.
+- **Coexisting with a sibling menu (e.g. a row-level context menu) does not give you mutual
+  exclusivity for free.** Each `usePopupMenu` instance only closes on outside clicks or its
+  own trigger; a click on this row's `ActionCell` button is *inside* a sibling row-menu's
+  ignored trigger element (the `<tr>`), so the sibling's own outside-click handling never
+  fires for it, and vice versa. Pass the sibling's registry via `coexistsWith` to close it
+  automatically whenever an `ActionCell` trigger opens — this covers one direction only. The
+  sibling must still deactivate *this* composable's registry (exposed via
+  `actionCellProps.menuController.registry`) when it activates; see `ActionCellGridDemo.vue`
+  linked above for that remaining call site.

package/package.json

@@ -1,9 +1,26 @@
 {
   "name": "@featherk/ui",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "main": "dist/featherk-ui.umd.js",
   "module": "dist/featherk-ui.es.js",
   "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/featherk-ui.es.js",
+      "require": "./dist/featherk-ui.umd.js"
+    },
+    "./table": {
+      "types": "./dist/table/index.d.ts",
+      "import": "./dist/featherk-ui.es.js",
+      "require": "./dist/featherk-ui.umd.js"
+    },
+    "./address": {
+      "types": "./dist/address/index.d.ts",
+      "import": "./dist/featherk-ui.es.js",
+      "require": "./dist/featherk-ui.umd.js"
+    }
+  },
   "files": [
     "dist",
     "docs"