@neovici/cosmoz-queue 1.6.1 → 1.6.2

package/README.md

@@ -1,3 +1,510 @@
-# cosmoz-queue
+# @neovici/cosmoz-queue
 
-A pionjs component
+A hooks-based UI component library for building **master-detail views** with list, split, and queue navigation modes. Built on [`@pionjs/pion`](https://github.com/pionjs/pion) and [`lit-html`](https://lit.dev/docs/libraries/standalone-templates/).
+
+> **What is a "queue"?** Not a data structure -- a UI pattern. Users work through a list of items one-by-one, like processing a queue of tasks. The component provides three view modes: a data table, a side-by-side split, and a full-screen sequential navigator.
+
+## Installation
+
+```sh
+npm install @neovici/cosmoz-queue
+```
+
+Peer dependencies: `@pionjs/pion`, `lit-html`, `i18next`.
+
+## Quick start
+
+The `queue()` factory is the recommended high-level API. It composes all the internal hooks and renders the complete queue UI -- tabs, navigation, list, and detail view.
+
+```ts
+import { queue } from '@neovici/cosmoz-queue';
+import { spread } from '@open-wc/lit-helpers';
+import { component, useCallback } from '@pionjs/pion';
+import { html } from 'lit-html';
+import { ref } from 'lit-html/directives/ref.js';
+import { fetchOrderDetails$ } from './api';
+import type { OrderListItem } from './types';
+
+const OrderListQueue = ({ heading }: { heading: string }) =>
+  queue<OrderListItem>({
+    // Title displayed above the list
+    heading,
+
+    // Unique key for persisting table column settings
+    settingsId: 'order-list',
+
+    // URL hash parameter names (enables deep-linking and back/forward)
+    idHashParam: 'id',
+    tabHashParam: 'qtab',
+
+    // Async function that fetches full details for a list item.
+    // Results are memoized per item identity.
+    details: useCallback(
+      (item: OrderListItem) => fetchOrderDetails$(item.id),
+      [],
+    ),
+
+    // Render the list component. `thru` contains bindings that wire
+    // the omnitable events to queue state (items, selection, clicks).
+    // Spread them onto your list component.
+    list: (thru, { onRef }) =>
+      html`<order-list-core ${spread(thru)} ${ref(onRef)}></order-list-core>`,
+
+    // Render the detail view. `nav` contains prev/next buttons --
+    // place them in a slot or wherever navigation belongs in your view.
+    view: (thru, { nav }) =>
+      html`<order-view-core ${spread(thru)}>${nav}</order-view-core>`,
+
+    // Render a loading skeleton shown while `details` resolves.
+    loader: (thru, { nav }) =>
+      html`<order-view-skeleton ${spread(thru)}>${nav}</order-view-skeleton>`,
+  });
+
+customElements.define('order-list-queue', component(OrderListQueue));
+```
+
+### `queue()` props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `heading` | `string` | -- | Title displayed above the tabs |
+| `settingsId` | `string?` | -- | Key for persisting omnitable column settings |
+| `idHashParam` | `string` | `'qid'` | URL hash param for the selected item ID |
+| `tabHashParam` | `string` | `'qtab'` | URL hash param for the active tab |
+| `details` | `(item: I) => PromiseLike<D>` | -- | Fetches full details for a list item |
+| `api` | `(id: string, item: I) => string` | -- | Alternative to `details`: returns a URL, queue fetches JSON internally |
+| `list` | `(thru, props) => TemplateResult` | -- | Renders the list component |
+| `view` | `(thru, props) => TemplateResult` | -- | Renders the detail view |
+| `loader` | `(thru, props) => TemplateResult` | -- | Renders the loading skeleton |
+| `pagination` | `Pagination?` | -- | Server-side pagination config |
+| `fallback` | `string?` | -- | Default tab when none is set in URL hash |
+| `split` | `SplitOpts?` | -- | Split.js configuration (sizes, min sizes) |
+| `afterHeading` | `unknown?` | -- | Extra content rendered after the heading |
+
+Use **`details`** when you control the fetch (most common). Use **`api`** when you want the queue to handle fetching via URL.
+
+### The `thru` bindings
+
+The `list`, `view`, and `loader` render functions receive a `thru` object as their first argument. This object contains property and event bindings that wire the child component to queue state:
+
+**For `list`:**
+- `.settingsId`, `.exposedParts` -- table configuration
+- `@visible-items-changed`, `@selected-items-changed`, `@total-available-changed` -- sync items/selection back to queue
+- `@omnitable-item-click` -- item click handler
+- `@async-simple-action` -- action completion handler
+
+**For `view`:**
+- `.item` -- the current detail item (list item or resolved detail)
+- `.hideActions` -- whether to hide actions (true when items are selected in split mode)
+- `@async-simple-action` -- action completion handler
+
+Spread these onto your component with `${spread(thru)}` from `@open-wc/lit-helpers`.
+
+## View modes
+
+The queue provides three tab-based view modes:
+
+| Mode | Tab name | Behavior |
+|---|---|---|
+| **List** | `overview` | Full-width data table (`cosmoz-omnitable`). The default view. |
+| **Split** | `split` | Side-by-side: resizable list on the left, detail view on the right. Disabled on mobile. |
+| **Queue** | `queue` | Full-screen detail view with prev/next navigation and keyboard arrow keys. |
+
+The active tab is synced to the URL hash (e.g. `#qtab=split&id=abc-123`), enabling deep-linking and browser back/forward navigation.
+
+On mobile viewports, the split tab is disabled and falls back to queue mode automatically.
+
+## List module
+
+The `@neovici/cosmoz-queue/list` entry point provides a managed `cosmoz-omnitable` with built-in state management, data fetching, pagination, and action rendering.
+
+### `listCore()`
+
+The high-level factory that combines `useListCore()` + `renderListCore()`:
+
+```ts
+import { itemClick } from '@neovici/cosmoz-queue';
+import { column, listCore, style } from '@neovici/cosmoz-queue/list';
+import { component, html } from '@pionjs/pion';
+import { t } from 'i18next';
+import type { OrderListItem } from './types';
+
+interface Props {
+  exposedParts: string;
+  api: (params: { pathLocator: string }) => Promise<{
+    items: OrderListItem[];
+    metaData: { totalAvailable: number };
+  }>;
+}
+
+const OrderListCore = ({ exposedParts, api }: Props) => {
+  return listCore({
+    // Unique key for persisting column settings
+    settingsId: 'order-list-core',
+
+    // CSS parts to expose for external styling
+    exposedParts,
+
+    // When false, omnitable applies its own local filtering
+    noLocal: false,
+
+    // Column definitions. The tuple is [factory, deps] -- same pattern
+    // as useMemo. The factory returns an object where each key becomes
+    // a column name.
+    columns: [
+      () => ({
+        title: column({
+          render: ({ name }) =>
+            html`<cosmoz-omnitable-column
+              name="${name}"
+              title=${t('Title')}
+              flex="2"
+              .renderCell=${(
+                _col: unknown,
+                { item, index }: { item: OrderListItem; index: number },
+              ) =>
+                html`<a
+                  @click="${itemClick({
+                    index,
+                    activate: ['split', 'queue'],
+                  })}"
+                  >${item.title}</a
+                >`}
+            ></cosmoz-omnitable-column>`,
+        }),
+
+        status: column({
+          render: ({ name }) =>
+            html`<cosmoz-omnitable-column-autocomplete
+              name="${name}"
+              title=${t('Status')}
+              value-path="status.name"
+            ></cosmoz-omnitable-column-autocomplete>`,
+        }),
+
+        createdAt: column({
+          render: ({ name }) =>
+            html`<cosmoz-omnitable-column-date
+              name="${name}"
+              title=${t('Date created')}
+            ></cosmoz-omnitable-column-date>`,
+        }),
+      }),
+      [], // dependency array (empty = compute once)
+    ],
+
+    // Reactive query parameters. Recomputed when deps change,
+    // which triggers a new data fetch.
+    params: [() => ({ pathLocator: '/some/path' }), []],
+
+    // Data fetcher. Receives { params, page, pageSize }.
+    // Must return { items, total }.
+    list$: [
+      ({ params }) =>
+        api(params).then((r) => ({
+          items: r.items ?? [],
+          total: r.metaData?.totalAvailable ?? 0,
+        })),
+      [api],
+    ],
+
+    // Batch actions shown when items are selected
+    actions: [myAction()],
+  });
+};
+
+customElements.define(
+  'order-list-core',
+  component(OrderListCore, { styleSheets: [style] }),
+);
+```
+
+### `listCore()` props
+
+| Prop | Type | Description |
+|---|---|---|
+| `settingsId` | `string` | Persistence key for column settings |
+| `exposedParts` | `string?` | CSS `exportparts` value |
+| `noLocal` | `boolean` | Skip omnitable local filtering (default: `true`) |
+| `columns` | `[() => Columns, deps[]]` | Column definitions (memoized) |
+| `params` | `[(opts) => Params, deps[]]` | Query parameters (memoized). The `opts` include `{ filters, descending, sortOn, columns }` |
+| `list$` | `[(props) => Promise<{ items, total }>, deps[]]` | Data fetcher. Receives `{ params, page, pageSize }` |
+| `pageSize` | `number?` | Items per page for "load more" (default: `50`) |
+| `actions` | `Action[]?` | Batch actions |
+| `content` | `(opts) => Renderable` | Extra content inside the omnitable |
+| `hashParam` | `string?` | URL hash param for omnitable state |
+| `csvFilename` | `string?` | Filename for CSV export |
+| `enabledColumns` | `string[]?` | Initially visible columns |
+
+### `column()`
+
+Type-safe column definition helper:
+
+```ts
+import { column } from '@neovici/cosmoz-queue/list';
+
+const myColumn = column({
+  // Optional ordering hint
+  order: 1,
+
+  // Optional sort key
+  sort: 'name',
+
+  // Optional filter transform: receives the raw filter value,
+  // returns the value sent to the API
+  filter: (value: string) => ({ name: value }),
+
+  // Render function -- receives { name } where name is the object key
+  render: ({ name }) =>
+    html`<cosmoz-omnitable-column
+      name="${name}"
+      title="Name"
+    ></cosmoz-omnitable-column>`,
+});
+```
+
+### `useListCore()` / `useListCoreState()`
+
+For cases where you need more control over the list without `renderListCore()`:
+
+- **`useListCore(props)`** -- manages columns, params, data fetching, pagination, and form dialog state. Returns `{ data$, columns, loadMore, dialog, open, ...state }`.
+- **`useListCoreState(defaults?)`** -- lower-level state: `filters`, `sortOn`, `descending`, `groupOn`, `selectedItems`, plus their setters and `setTotalAvailable`.
+
+## Actions module
+
+The `@neovici/cosmoz-queue/actions` entry point provides a declarative system for defining user actions that open form dialogs.
+
+### Defining an action
+
+```ts
+import { action, Action, defaultButton } from '@neovici/cosmoz-queue/actions';
+import { t } from 'i18next';
+import { when } from 'lit-html/directives/when.js';
+
+// action() is an identity function that provides type inference
+export const approveOrder = action<OrderItem, ApproveFields>({
+  // Label shown on the button
+  title: () => t('Approve'),
+
+  // Optional: filter which items this action applies to.
+  // If provided, non-applicable items are excluded and the button
+  // shows a count badge like "Approve (3/5)".
+  applicable: (item) => item.status === 'pending',
+
+  // Optional: custom button renderer. Defaults to `defaultButton()`.
+  // Return `nothing` to hide the button conditionally.
+  button: (opts) =>
+    when(opts.items.length >= 1, () => defaultButton(opts)),
+
+  // Dialog configuration. Opens a `cosmoz-form` dialog.
+  // `items` contains only the applicable items.
+  dialog: ({ items, title }) => ({
+    heading: title,
+    description: t('Approve the selected orders'),
+    fields: [
+      // cosmoz-form field definitions
+    ],
+    initial: {},
+    onSave: async (values) => {
+      await approveOrders(items.map((i) => i.id), values);
+    },
+  }),
+});
+```
+
+### Rendering actions
+
+Actions are rendered automatically by `listCore()` when passed as the `actions` prop. For manual rendering (e.g. in a detail view's bottom bar):
+
+```ts
+import { renderActions } from '@neovici/cosmoz-queue/actions';
+import { approveOrder } from './actions';
+
+// In a view component:
+const bottomBar = renderActions({ items: [currentItem], open })([
+  approveOrder,
+]);
+```
+
+### Action types
+
+```ts
+interface Action<TItem, TDialog> {
+  title: () => string;
+  applicable?: (item: TItem) => boolean;
+  button?: (opts: Action & ActionOpts) => unknown;
+  dialog: (opts: DialogOpts) => Dialogable | Promise<Dialogable>;
+}
+
+interface ActionOpts<TItem> {
+  items: TItem[];
+  open: (dialog: Dialogable) => void;
+  slot?: string;
+}
+```
+
+## Advanced: composing with hooks
+
+When `queue()` is too opinionated, use the individual hooks directly.
+
+### `useQueue()` + `renderQueue()`
+
+```ts
+import { useQueue, renderQueue, renderNav } from '@neovici/cosmoz-queue';
+
+const MyQueue = ({ heading }: { heading: string }) => {
+  const {
+    index, mobile, tabnav, items, setItems,
+    setSelected, setTotalAvailable, totalAvailable,
+    onItemClick, nav,
+  } = useQueue<MyItem>({
+    idHashParam: 'id',
+    tabHashParam: 'tab',
+  });
+
+  return renderQueue({
+    heading,
+    mobile,
+    index,
+    items,
+    tabnav,
+    totalAvailable,
+    nav,
+    list: html`<my-list
+      @visible-items-changed=${updateWith(setItems)}
+      @selected-items-changed=${updateWith(setSelected)}
+      @total-available-changed=${updateWith(setTotalAvailable)}
+      @omnitable-item-click=${onItemClick}
+    ></my-list>`,
+    renderItem: ({ item, nav }) =>
+      html`<my-view .item=${item}>${nav}</my-view>`,
+    renderLoader: ({ item, nav }) =>
+      html`<my-skeleton .item=${item}>${nav}</my-skeleton>`,
+  });
+};
+```
+
+### Individual hooks
+
+| Hook | Import | Purpose |
+|---|---|---|
+| `useTabs({ items, hashParam, mobile, fallback })` | `@neovici/cosmoz-queue` | Manages overview/split/queue tabs. Returns `{ tabnav, activeTab }`. |
+| `useDataNav(items, opts)` | `@neovici/cosmoz-queue` | Item navigation with prev/next, URL hash sync. Returns `{ item, setItem, next, prev, forward, index }`. |
+| `useSplit({ activeTab, ...splitOpts })` | `@neovici/cosmoz-queue` | Initializes Split.js when in split mode. |
+| `useListState()` | `@neovici/cosmoz-queue` | Creates `items`, `selected`, `totalAvailable` state with setters. |
+| `useListSSE({ entity, params, list$ })` | `@neovici/cosmoz-queue` | Subscribes to Server-Sent Events (`cosmoz-${entity}-updated`) for real-time list updates. |
+| `useFetchActions({ pathLocator, selected, api })` | `@neovici/cosmoz-queue` | Fetches available actions for selected items from an API. Returns `{ actions, actionRows, actionsFetching }`. |
+| `useAsyncAction(nav)` | `@neovici/cosmoz-queue` | Handles async action completion with automatic item removal from the list. Returns `{ listRef, onAsyncSimpleAction }`. |
+| `usePagination()` | `@neovici/cosmoz-queue` | URL hash-based page state. Returns `{ page, onPage }`. |
+
+## Utilities
+
+### Fetch helpers (`@neovici/cosmoz-queue/util/fetch`)
+
+Pre-configured `fetch` wrapper with CORS and credentials:
+
+```ts
+import {
+  fetch,
+  setBaseInit,
+  handleJSON,
+  RequestError,
+} from '@neovici/cosmoz-queue/util/fetch';
+
+// Configure default headers (call once at app startup)
+setBaseInit({
+  headers: { 'X-Custom-Header': 'value' },
+  // Or use dynamic headers:
+  getHeaders: () => ({ Authorization: `Bearer ${getToken()}` }),
+});
+
+// fetch() includes mode: 'cors', credentials: 'include' by default
+const response = await fetch('/api/orders');
+const data = await handleJSON(response);
+```
+
+`RequestError` extends `Error` with `.response` and `.data` properties for structured error handling.
+
+### `itemClick()`
+
+Makes list cells clickable, dispatching `omnitable-item-click` events that the queue listens for:
+
+```ts
+import { itemClick } from '@neovici/cosmoz-queue';
+
+// In an omnitable cell renderer:
+html`<a @click="${itemClick({ index, activate: ['split', 'queue'] })}">
+  ${item.title}
+</a>`;
+```
+
+The `activate` option specifies which tab to switch to. The queue picks the first non-disabled tab from the array.
+
+### Other utilities
+
+| Function | Description |
+|---|---|
+| `getItems(items, selected)` | Returns `selected` if non-empty, otherwise `items` |
+| `touch(list, id)` | Forces an omnitable item refresh by replacing it with a shallow copy |
+
+## Architecture
+
+```
+queue() factory
+  |
+  +---> useQueue()                     State orchestration
+  |       |
+  |       +---> useListState()         items, selected, totalAvailable
+  |       +---> useTabs()              overview | split | queue
+  |       +---> useDataNav()           current item, prev/next, URL hash
+  |       +---> useKeyNav()            arrow key navigation
+  |       +---> useSplit()             Split.js initialization
+  |       +---> useUpdates()           list-item-remove events
+  |
+  +---> useAsyncAction()               Post-action item removal
+  |
+  +---> renderQueue()                  Template composition
+          |
+          +---> cosmoz-tabs-next       Tab bar (List / Split / Queue)
+          +---> renderStats()          "3-5 of 120"
+          +---> renderPagination()     Page prev/next
+          +---> <div.split>
+                 +---> list            cosmoz-omnitable (user-provided)
+                 +---> cosmoz-slider   Animated detail view
+                        +---> renderSlide() --> renderView()
+                                                  |
+                                                  +---> details()   Async fetch
+                                                  +---> renderItem  or renderLoader
+```
+
+## Entry points
+
+| Import path | Description |
+|---|---|
+| `@neovici/cosmoz-queue` | Main: `queue()`, `useQueue()`, `renderQueue()`, navigation hooks, SSE, utilities |
+| `@neovici/cosmoz-queue/actions` | `action()`, `renderActions()`, `defaultButton()`, `actionCount()` |
+| `@neovici/cosmoz-queue/list` | `listCore()`, `column()`, `useListCore()`, `useListCoreState()`, `renderListCore()` |
+| `@neovici/cosmoz-queue/list/more` | `useMore()` -- progressive "load more" pagination |
+| `@neovici/cosmoz-queue/list/more/render` | `renderLoadMore()` -- "Load more" button |
+| `@neovici/cosmoz-queue/util/fetch` | `fetch()`, `setBaseInit()`, `handleJSON()`, `RequestError` |
+
+## Deprecation notices
+
+### `api` property → `details`
+
+The `api` property on `useQueue()` / `queue()` is **deprecated** and will be
+removed in v2.0.0. Use `details` instead:
+
+```ts
+// Before (deprecated)
+queue({ api: (id, item) => apiUrl(`items/${id}`) })
+
+// After
+queue({ details: (item) => fetch(apiUrl(`items/${item.id}`)).then(r => r.json()) })
+```
+
+See [Migration guide](docs/migration-api-to-details.md) for more patterns.
+
+## License
+
+[Apache-2.0](LICENSE)

package/dist/queue/use-queue.d.ts

@@ -5,6 +5,25 @@ interface Opts<I> extends ReturnType<typeof useListState<I>>, Pick<UseTabsOption
     tabHashParam?: string;
     idHashParam?: string;
     onActivate?: (name: string) => void;
+    /**
+     * @deprecated Use the `details` property instead. The `api` property will be removed in v2.0.0.
+     *
+     * The `api` property uses deprecated utilities and is less flexible than `details`.
+     * With `details`, you have full control over the fetch operation and can return any Promise.
+     *
+     * Migration example:
+     * ```ts
+     * // Before:
+     * useQueue({
+     *   api: (id, item) => apiUrl(`api/items/${id}`)
+     * })
+     *
+     * // After:
+     * useQueue({
+     *   details: (item) => fetch(apiUrl(`api/items/${item.id}`)).then(res => res.json())
+     * })
+     * ```
+     */
     api?: (id: string, item: I) => string;
     id?: (i: I) => string;
     split?: SplitOpts;

package/dist/queue/use-queue.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-queue.d.ts","sourceRoot":"","sources":["../../src/queue/use-queue.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAiB,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAClD,OAAgB,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,YAAY,CAAC;AA8BhE,UAAU,IAAI,CAAC,CAAC,CACf,SACC,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC,CAAC,CAAC,EAClC,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,UAAU,CAAC;IACpC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACpC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,KAAK,MAAM,CAAC;IACtC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,SAAS,CAAC;CAClB;AAED,QAAA,MAAM,QAAQ,GAAI,CAAC,EAAE,8EASlB,IAAI,CAAC,CAAC,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBA2CH,KAAK;oBAtBA,MAAM;;;;;;;;;;;;;;;;;;CAkDjB,CAAC;AAEF,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI,IAAI,CAC7B,UAAU,CAAC,OAAO,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EACjC,MAAM,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC,CAAC,CAAC,CACxC,CAAC;yBAEc,CAAC,EAAE,MAAM,QAAQ,CAAC,CAAC,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAnC7B,KAAK;oBAtBA,MAAM;;;;;;;;;;;;;;;;;;;AAyDlB,wBACgD"}
+{"version":3,"file":"use-queue.d.ts","sourceRoot":"","sources":["../../src/queue/use-queue.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAiB,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAClD,OAAgB,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,YAAY,CAAC;AAwDhE,UAAU,IAAI,CAAC,CAAC,CACf,SACC,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC,CAAC,CAAC,EAClC,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,UAAU,CAAC;IACpC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACpC;;;;;;;;;;;;;;;;;;OAkBG;IACH,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,KAAK,MAAM,CAAC;IACtC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,SAAS,CAAC;CAClB;AAED,QAAA,MAAM,QAAQ,GAAI,CAAC,EAAE,8EASlB,IAAI,CAAC,CAAC,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBA2CH,KAAK;oBAtBA,MAAM;;;;;;;;;;;;;;;;;;CAkDjB,CAAC;AAEF,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI,IAAI,CAC7B,UAAU,CAAC,OAAO,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EACjC,MAAM,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC,CAAC,CAAC,CACxC,CAAC;yBAEc,CAAC,EAAE,MAAM,QAAQ,CAAC,CAAC,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAnC7B,KAAK;oBAtBA,MAAM;;;;;;;;;;;;;;;;;;;AAyDlB,wBACgD"}

package/dist/queue/use-queue.js

@@ -12,6 +12,17 @@ import useUpdates from './use-updates';
 import { getItems, normalizeHeaders } from './util';
 const _id = (item) => item['id'];
 const useQNav = ({ id, api, items, ...thru }) => {
+    // Deprecation warning
+    /* eslint-disable no-console, no-template-curly-in-string */
+    if (api && typeof console !== 'undefined' && console.warn) {
+        console.warn('[cosmoz-queue] DEPRECATED: The `api` property is deprecated and will be removed in v2.0.0. ' +
+            'Please migrate to the `details` property for better control and performance.\n\n' +
+            'Migration guide:\n' +
+            '  Before: api: (id, item) => apiUrl(\'api/items/${id}\')\n' +
+            '  After:  details: (item) => fetch(apiUrl(\'api/items/${item.id}\')).then(res => res.json())\n\n' +
+            'See: https://github.com/Neovici/cosmoz-queue#migration-from-api-to-details');
+    }
+    /* eslint-enable no-console, no-template-curly-in-string */
     const details = useMemo(() => api && memoize((item) => json(api(id(item), item))), [id, api]), pass = useDataNav(items, {
         ...thru,
         id,

package/dist/util/fetch/fetch.d.ts

@@ -26,7 +26,7 @@ export declare const setBaseInit: <T extends BaseInitOptions>(init: T) => Partia
     headers: {};
 };
 export declare const fetch: (url: string, opts?: RequestInit) => Promise<Response>;
-export declare const handleJSON: (res: Response) => Promise<any> | "";
+export declare const handleJSON: (res: Response) => "" | Promise<any>;
 /**
  * @deprecated
  */

package/dist/util/{test/path.test.d.ts.map → path.test.d.ts.map}

@@ -1 +1 @@
-{"version":3,"file":"path.test.d.ts","sourceRoot":"","sources":["../../../src/util/test/path.test.ts"],"names":[],"mappings":""}
+{"version":3,"file":"path.test.d.ts","sourceRoot":"","sources":["../../src/util/path.test.ts"],"names":[],"mappings":""}

package/dist/util/{test/path.test.js → path.test.js}

@@ -1,84 +1,79 @@
-import { assert } from '@open-wc/testing';
-import { get, normalize, split } from '../path';
+import { describe, expect, it } from 'vitest';
+import { get, normalize, split } from './path';
 describe('path', () => {
     describe('normalize', () => {
         it('returns string path as-is', () => {
-            assert.equal(normalize('foo.bar.0.baz'), 'foo.bar.0.baz');
+            expect(normalize('foo.bar.0.baz')).toBe('foo.bar.0.baz');
         });
         it('returns empty string as-is', () => {
-            assert.equal(normalize(''), '');
+            expect(normalize('')).toBe('');
         });
         it('converts array path to flattened string', () => {
-            assert.equal(normalize(['foo.bar', 0, 'baz']), 'foo.bar.0.baz');
+            expect(normalize(['foo.bar', 0, 'baz'])).toBe('foo.bar.0.baz');
         });
         it('handles array with single element', () => {
-            assert.equal(normalize(['foo']), 'foo');
+            expect(normalize(['foo'])).toBe('foo');
         });
         it('handles array with dotted strings and numbers', () => {
-            assert.equal(normalize(['a.b', 1, 'c.d', 2]), 'a.b.1.c.d.2');
+            expect(normalize(['a.b', 1, 'c.d', 2])).toBe('a.b.1.c.d.2');
         });
         it('handles empty array', () => {
-            assert.equal(normalize([]), '');
+            expect(normalize([])).toBe('');
         });
     });
     describe('split', () => {
         it('splits string path into array', () => {
-            assert.deepEqual(split('foo.bar.0.baz'), ['foo', 'bar', '0', 'baz']);
+            expect(split('foo.bar.0.baz')).toEqual(['foo', 'bar', '0', 'baz']);
         });
         it('splits array path into flat array', () => {
-            assert.deepEqual(split(['foo.bar', 0, 'baz']), [
-                'foo',
-                'bar',
-                '0',
-                'baz',
-            ]);
+            expect(split(['foo.bar', 0, 'baz'])).toEqual(['foo', 'bar', '0', 'baz']);
         });
         it('handles single segment string', () => {
-            assert.deepEqual(split('foo'), ['foo']);
+            expect(split('foo')).toEqual(['foo']);
         });
         it('handles array with single element', () => {
-            assert.deepEqual(split(['foo']), ['foo']);
+            expect(split(['foo'])).toEqual(['foo']);
         });
         it('handles empty string', () => {
-            assert.deepEqual(split(''), ['']);
+            expect(split('')).toEqual(['']);
         });
     });
     describe('get', () => {
         it('retrieves nested value with string path', () => {
             const obj = { foo: { bar: { baz: 'value' } } };
-            assert.equal(get(obj, 'foo.bar.baz'), 'value');
+            expect(get(obj, 'foo.bar.baz')).toBe('value');
         });
         it('retrieves nested value with array path', () => {
             const obj = { foo: { bar: { baz: 'value' } } };
-            assert.equal(get(obj, ['foo', 'bar', 'baz']), 'value');
+            expect(get(obj, ['foo', 'bar', 'baz'])).toBe('value');
         });
         it('retrieves nested value with dotted string in array path', () => {
             const obj = { foo: { bar: { baz: 'value' } } };
-            assert.equal(get(obj, ['foo.bar', 'baz']), 'value');
+            expect(get(obj, ['foo.bar', 'baz'])).toBe('value');
         });
         it('retrieves array element by index', () => {
             const obj = { items: ['a', 'b', 'c'] };
-            assert.equal(get(obj, 'items.1'), 'b');
+            expect(get(obj, 'items.1')).toBe('b');
         });
         it('retrieves array element with array path', () => {
             const obj = { items: ['a', 'b', 'c'] };
-            assert.equal(get(obj, ['items', 0]), 'a');
+            expect(get(obj, ['items', 0])).toBe('a');
         });
         it('returns undefined for non-existent path', () => {
             const obj = { foo: { bar: 'value' } };
-            assert.equal(get(obj, 'foo.baz.qux'), undefined);
+            expect(get(obj, 'foo.baz.qux')).toBeUndefined();
         });
         it('returns undefined when intermediate property is undefined', () => {
             const obj = { foo: undefined };
-            assert.equal(get(obj, 'foo.bar'), undefined);
+            expect(get(obj, 'foo.bar')).toBeUndefined();
         });
         it('returns undefined when intermediate property is null', () => {
             const obj = { foo: null };
-            assert.equal(get(obj, 'foo.bar'), undefined);
+            expect(get(obj, 'foo.bar')).toBeUndefined();
         });
         it('returns undefined with empty string path', () => {
             const obj = { foo: 'bar' };
-            assert.equal(get(obj, ''), undefined);
+            expect(get(obj, '')).toBeUndefined();
         });
         it('handles complex nested structure', () => {
             const obj = {
@@ -87,13 +82,13 @@ describe('path', () => {
                     { name: 'Bob', address: { city: 'LA' } },
                 ],
             };
-            assert.equal(get(obj, 'users.1.address.city'), 'LA');
+            expect(get(obj, 'users.1.address.city')).toBe('LA');
         });
         it('returns undefined for null root', () => {
-            assert.equal(get(null, 'foo'), undefined);
+            expect(get(null, 'foo')).toBeUndefined();
         });
         it('returns undefined for undefined root', () => {
-            assert.equal(get(undefined, 'foo'), undefined);
+            expect(get(undefined, 'foo')).toBeUndefined();
         });
     });
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neovici/cosmoz-queue",
-  "version": "1.6.1",
+  "version": "1.6.2",
   "description": "A reusable queue component for master-detail views with list, split, and queue modes",
   "keywords": [
     "web-components",
@@ -29,8 +29,10 @@
     "lint": "tsc && eslint --cache .",
     "build": "tsc -p tsconfig.build.json",
     "start": "wds",
-    "test": "wtr --coverage",
-    "test:watch": "wtr --watch",
+    "test": "vitest --run",
+    "test:unit": "vitest --project=unit --run",
+    "test:storybook": "vitest --project=storybook --run",
+    "test:watch": "vitest",
     "check:duplicates": "check-duplicate-components",
     "dev": "npm run storybook:start",
     "storybook:start": "storybook dev -p 8000",
@@ -91,26 +93,27 @@
     "@commitlint/config-conventional": "^20.0.0",
     "@eslint/eslintrc": "^2.0.0",
     "@neovici/cfg": "^2.8.0",
-    "@neovici/testing": "^2.0.0",
-    "@open-wc/testing": "^4.0.0",
-    "@open-wc/testing-helpers": "^3.0.1",
+    "@neovici/testing": "^2.2.0",
     "@semantic-release/changelog": "^6.0.0",
     "@semantic-release/git": "^10.0.0",
     "@storybook/addon-links": "^10.0.0",
+    "@storybook/addon-vitest": "^10.0.0",
     "@storybook/web-components": "^10.0.0",
     "@storybook/web-components-vite": "^10.0.0",
-    "@types/mocha": "^10.0.6",
     "@types/node": "^22.10.2",
+    "@types/react": "^19.2.13",
     "@types/split.js": "^1.6.0",
-    "@web/dev-server-esbuild": "^1.0.4",
-    "@web/test-runner-playwright": "^0.11.1",
+    "@vitest/browser": "^4.0.0",
+    "@vitest/browser-playwright": "^4.0.0",
     "esbuild": "^0.27.0",
     "http-server": "^14.1.1",
     "husky": "^9.0.11",
+    "jsdom": "^26.0.0",
+    "playwright": "^1.52.0",
     "semantic-release": "^25.0.0",
-    "sinon": "^19.0.0",
     "storybook": "^10.0.0",
-    "typescript": "^5.4.3"
+    "typescript": "^5.4.3",
+    "vitest": "^4.0.0"
   },
   "overrides": {
     "conventional-changelog-conventionalcommits": ">= 8.0.0",

package/dist/queue/test/__snapshots__/render.test.snap.d.ts

@@ -1,2 +0,0 @@
-export const snapshots: typeof snapshots;
-//# sourceMappingURL=render.test.snap.d.ts.map

package/dist/queue/test/__snapshots__/render.test.snap.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"render.test.snap.d.ts","sourceRoot":"","sources":["../../../../src/queue/test/__snapshots__/render.test.snap.js"],"names":[],"mappings":"AACA,yCAA4B"}

package/dist/queue/test/__snapshots__/render.test.snap.js

@@ -1,64 +0,0 @@
-/* @web/test-runner snapshot v1 */
-export const snapshots = {};
-snapshots['queue > render renderNav'] = `<button
-  class="button-nav prev"
-  disabled=""
-  slot="extra"
->
-</button>
-`;
-/* end snapshot queue > render renderNav */
-snapshots['queue > render renderPagination'] = `<div class="tabn-pagination">
-  <button class="button-page page-prev">
-  </button>
-  <button class="button-page page-next">
-  </button>
-</div>
-`;
-/* end snapshot queue > render renderPagination */
-snapshots['queue > render renderNav'] = `<button
-  class="button-nav prev"
-  disabled=""
-  name="Previous item"
-  slot="extra"
->
-</button>
-`;
-/* end snapshot queue > render renderNav */
-snapshots['queue > render renderPagination'] = `<div class="tabn-pagination">
-  <button
-    class="button-page page-prev"
-    name="Previous page"
-  >
-  </button>
-  <button
-    class="button-page page-next"
-    name="Next page"
-  >
-  </button>
-</div>
-`;
-/* end snapshot queue > render renderPagination */
-snapshots['queue > render renderNav'] = `<button
-  class="button-nav prev"
-  disabled=""
-  slot="extra"
-  title=""
->
-</button>
-`;
-/* end snapshot queue > render renderNav */
-snapshots['queue > render renderPagination'] = `<div class="tabn-pagination">
-  <button
-    class="button-page page-prev"
-    title=""
-  >
-  </button>
-  <button
-    class="button-page page-next"
-    title=""
-  >
-  </button>
-</div>
-`;
-/* end snapshot queue > render renderPagination */

package/dist/queue/test/item-click.test.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=item-click.test.d.ts.map

package/dist/queue/test/item-click.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"item-click.test.d.ts","sourceRoot":"","sources":["../../../src/queue/test/item-click.test.ts"],"names":[],"mappings":""}

package/dist/queue/test/item-click.test.js

@@ -1,28 +0,0 @@
-import { assert, oneEvent } from '@open-wc/testing';
-import { oneDefaultPreventedEvent } from '@open-wc/testing-helpers';
-import { itemClick } from '../item-click';
-describe('item-click', () => {
-    it('fires event', async () => {
-        const el = document.createElement('div');
-        el.addEventListener('click', itemClick({ index: 2, activate: 'queue' }));
-        setTimeout(() => el.click());
-        const { detail } = await oneEvent(el, 'omnitable-item-click');
-        assert.equal(detail.index, 2);
-        assert.equal(detail.activate, 'queue');
-    });
-    it('prevents default', async () => {
-        const el = document.createElement('div');
-        const ev = new MouseEvent('click');
-        el.addEventListener('click', itemClick({ index: 3, activate: 'list' }));
-        setTimeout(() => el.dispatchEvent(ev));
-        const { detail } = await oneDefaultPreventedEvent(el, 'omnitable-item-click');
-        assert.equal(detail.index, 3);
-        assert.equal(detail.activate, 'list');
-    });
-    it('does not fire event', async () => {
-        const el = document.createElement('div');
-        const ev = new MouseEvent('click', { ctrlKey: true });
-        el.addEventListener('click', itemClick({ index: 3, activate: 'list' }));
-        setTimeout(() => el.dispatchEvent(ev));
-    });
-});

package/dist/queue/test/render.test.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=render.test.d.ts.map

package/dist/queue/test/render.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"render.test.d.ts","sourceRoot":"","sources":["../../../src/queue/test/render.test.ts"],"names":[],"mappings":""}

package/dist/queue/test/render.test.js

@@ -1,27 +0,0 @@
-import { expect, fixture } from '@open-wc/testing';
-import { nothing } from 'lit-html';
-import { spy } from 'sinon';
-import { renderNav, renderPagination } from '../render';
-describe('queue > render', () => {
-    it('renderNav', async () => {
-        const el = await fixture(renderNav({}));
-        await expect(el).dom.to.equalSnapshot();
-    });
-    it('renderPagination nothing', async () => {
-        expect(renderPagination()).to.equal(nothing);
-    });
-    it('renderPagination', async () => {
-        const onPage = spy();
-        const el = await fixture(renderPagination({
-            totalPages: 10,
-            pageNumber: 3,
-            onPage,
-        }));
-        await expect(el).dom.to.equalSnapshot();
-        el.querySelector('.page-next')?.click();
-        expect(onPage).to.have.been.calledWith(4);
-        onPage.resetHistory();
-        el.querySelector('.page-prev')?.click();
-        expect(onPage).to.have.been.calledWith(2);
-    });
-});

package/dist/queue/test/use-pref.test.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=use-pref.test.d.ts.map

package/dist/queue/test/use-pref.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"use-pref.test.d.ts","sourceRoot":"","sources":["../../../src/queue/test/use-pref.test.ts"],"names":[],"mappings":""}

package/dist/queue/test/use-pref.test.js

@@ -1,16 +0,0 @@
-import { renderHook } from '@neovici/testing';
-import { assert } from '@open-wc/testing';
-import { usePref } from '../use-pref';
-describe('use-pref', () => {
-    it('default pref', async () => {
-        const { result } = await renderHook(() => usePref('some', 'asdad'));
-        assert.equal(result.current[0], 'asdad');
-    });
-    it('update pref', async () => {
-        const { result, nextUpdate } = await renderHook(() => usePref('somethingelse'));
-        assert.equal(result.current[0], undefined);
-        setTimeout(() => result.current[1]('dads'));
-        await nextUpdate();
-        assert.equal(result.current[0], 'dads');
-    });
-});