@jskit-ai/http-web 0.1.1

package/test/useCrudListRowActions.test.js

@@ -0,0 +1,77 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+test("useCrudListRowActions manages per-record state and executes action context", async () => {
+  const { defineCrudListRowActions } = await import("@jskit-ai/http-web/client/rowActions");
+  const { useCrudListRowActions } = await import("@jskit-ai/http-web/client/composables/useCrudListRowActions");
+  const calls = [];
+  let finishRun = null;
+  const actions = defineCrudListRowActions([
+    {
+      key: "delete",
+      label: "Delete",
+      color: "error",
+      visible: ({ record }) => record.isOwnerRow !== true,
+      disabled: ({ record }) => record.locked === true,
+      loading: ({ record }) => record.pending === true,
+      async run(context) {
+        calls.push(context);
+        await new Promise((resolve) => {
+          finishRun = resolve;
+        });
+        return "deleted";
+      }
+    }
+  ]);
+  const runtime = useCrudListRowActions(actions, {
+    resolveRecordId: (record) => record.id,
+    resolveContext: () => ({
+      records: "records-token",
+      reload: "reload-token"
+    })
+  });
+
+  assert.equal(runtime.hasActions.value, true);
+  assert.equal(runtime.hasVisibleActionsFor({ id: "owner", isOwnerRow: true }, 0), false);
+  assert.equal(runtime.isActionDisabled("delete", { id: "locked", locked: true }, 1), true);
+  assert.equal(runtime.isActionLoading("delete", { id: "pending", pending: true }, 2), true);
+
+  const record = { id: "10", name: "Worker" };
+  assert.equal(runtime.isActionVisible("delete", record, 3), true);
+  assert.equal(runtime.isActionDisabled("delete", record, 3), false);
+
+  const result = runtime.execute("delete", record, 3);
+  assert.equal(runtime.isActionExecuting("delete", record, 3), true);
+  assert.equal(runtime.isActionLoading("delete", record, 3), true);
+  finishRun();
+
+  assert.equal(await result, "deleted");
+  assert.equal(runtime.isActionExecuting("delete", record, 3), false);
+  assert.equal(calls.length, 1);
+  assert.equal(calls[0].action.key, "delete");
+  assert.equal(calls[0].record, record);
+  assert.equal(calls[0].index, 3);
+  assert.equal(calls[0].recordId, "10");
+  assert.equal(calls[0].records, "records-token");
+  assert.equal(calls[0].reload, "reload-token");
+});
+
+test("defineCrudListRowActions skips malformed and duplicate actions", async () => {
+  const { defineCrudListRowActions } = await import("@jskit-ai/http-web/client/rowActions");
+
+  const actions = defineCrudListRowActions([
+    null,
+    { key: "delete", label: "Delete", color: "error" },
+    { key: "delete", label: "Delete again" },
+    { key: "missing-label" },
+    { label: "Generated key" }
+  ]);
+
+  assert.deepEqual(
+    actions.map((action) => [action.key, action.label, action.color]),
+    [
+      ["delete", "Delete", "error"],
+      ["action-5", "Generated key", "primary"]
+    ]
+  );
+});

package/test/useListRouteInitialization.test.js

@@ -0,0 +1,337 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { QueryClient, VueQueryPlugin } from "@tanstack/vue-query";
+import {
+  computed,
+  createRenderer,
+  h,
+  unref
+} from "vue";
+import {
+  createMemoryHistory,
+  createRouter,
+  useRoute
+} from "vue-router";
+
+import { useList } from "../src/client/composables/records/useList.js";
+import { useCrudListFilters } from "../src/client/composables/useCrudListFilters.js";
+
+const CURRENTNESS_FILTERS = Object.freeze({
+  currentness: Object.freeze({
+    type: "enum",
+    defaultValue: "active",
+    options: Object.freeze([
+      Object.freeze({
+        label: "Active",
+        value: "active"
+      }),
+      Object.freeze({
+        label: "Archived",
+        value: "archived"
+      })
+    ])
+  })
+});
+
+async function waitFor(check, message = "Expected condition was not met.") {
+  for (let attempt = 0; attempt < 100; attempt += 1) {
+    if (check()) {
+      return;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 0));
+  }
+
+  assert.fail(message);
+}
+
+function createTestRenderer() {
+  function insert(child, parent, anchor = null) {
+    const siblings = parent.children || (parent.children = []);
+    const index = anchor ? siblings.indexOf(anchor) : -1;
+    if (index < 0) {
+      siblings.push(child);
+    } else {
+      siblings.splice(index, 0, child);
+    }
+    child.parent = parent;
+  }
+
+  function remove(child) {
+    const parent = child?.parent;
+    const index = parent?.children?.indexOf(child) ?? -1;
+    if (index >= 0) {
+      parent.children.splice(index, 1);
+    }
+    child.parent = null;
+  }
+
+  return createRenderer({
+    patchProp(element, key, _previousValue, nextValue) {
+      element.properties[key] = nextValue;
+    },
+    insert,
+    remove,
+    createElement(type) {
+      return {
+        type,
+        properties: {},
+        children: [],
+        parent: null
+      };
+    },
+    createText(text) {
+      return {
+        type: "text",
+        text,
+        parent: null
+      };
+    },
+    createComment(text) {
+      return {
+        type: "comment",
+        text,
+        parent: null
+      };
+    },
+    setText(node, text) {
+      node.text = text;
+    },
+    setElementText(element, text) {
+      element.children = [{
+        type: "text",
+        text,
+        parent: element
+      }];
+    },
+    parentNode(node) {
+      return node?.parent || null;
+    },
+    nextSibling(node) {
+      const parent = node?.parent;
+      const index = parent?.children?.indexOf(node) ?? -1;
+      return index >= 0 ? parent.children[index + 1] || null : null;
+    },
+    querySelector() {
+      return null;
+    },
+    setScopeId() {},
+    cloneNode(node) {
+      return {
+        ...node,
+        properties: {
+          ...node.properties
+        },
+        children: [...(node.children || [])],
+        parent: null
+      };
+    },
+    insertStaticContent(content, parent, anchor) {
+      const node = {
+        type: "static",
+        text: content,
+        parent: null
+      };
+      insert(node, parent, anchor);
+      return [node, node];
+    }
+  });
+}
+
+function createListTestAdapter() {
+  return Object.freeze({
+    useOperationScope() {
+      const route = useRoute();
+
+      return Object.freeze({
+        routeContext: Object.freeze({
+          route,
+          currentSurfaceId: computed(() => "admin")
+        }),
+        scopeParamValue: computed(() => ""),
+        normalizedOwnershipFilter: "none",
+        apiPath: computed(() => "/contacts"),
+        queryKey: computed(() => ["contacts"]),
+        queryCanRun(gate = true) {
+          return computed(() => Boolean(unref(gate)));
+        },
+        permissionGate() {
+          return computed(() => true);
+        },
+        loadError(error = "") {
+          return computed(() => String(unref(error) || ""));
+        },
+        isLoading(loading = false) {
+          return computed(() => Boolean(unref(loading)));
+        }
+      });
+    }
+  });
+}
+
+async function mountRouteSynchronizedList(initialLocation) {
+  const calls = [];
+  const client = {
+    async request(path, options) {
+      calls.push({
+        path,
+        options
+      });
+      return {
+        items: [],
+        nextCursor: null
+      };
+    }
+  };
+  const queryClient = new QueryClient({
+    defaultOptions: {
+      queries: {
+        retry: false
+      }
+    }
+  });
+  const router = createRouter({
+    history: createMemoryHistory(),
+    routes: [{
+      path: "/contacts",
+      component: {
+        render() {
+          return h("div");
+        }
+      }
+    }]
+  });
+  const renderer = createTestRenderer();
+  let filterRuntime = null;
+  const app = renderer.createApp({
+    setup() {
+      filterRuntime = useCrudListFilters(CURRENTNESS_FILTERS);
+      useList({
+        adapter: createListTestAdapter(),
+        client,
+        queryKeyFactory: () => ["contacts"],
+        queryParams: filterRuntime.queryParams,
+        routeQueryValueResolvers: filterRuntime.routeQueryValueResolvers,
+        syncToRoute: {
+          enabled: true,
+          search: false,
+          queryParams: true
+        }
+      });
+
+      return () => h("div");
+    }
+  });
+  app.use(router);
+  app.use(VueQueryPlugin, {
+    queryClient
+  });
+
+  await router.push(initialLocation);
+  await router.isReady();
+  app.mount({
+    type: "root",
+    children: []
+  });
+  await waitFor(
+    () => calls.length > 0,
+    `Expected a list request for ${JSON.stringify(initialLocation)}.`
+  );
+  await new Promise((resolve) => setImmediate(resolve));
+
+  return {
+    app,
+    calls,
+    filterRuntime,
+    queryClient,
+    router
+  };
+}
+
+test("route-synchronized lists make one initial request with the hydrated route filter", async () => {
+  const runtime = await mountRouteSynchronizedList({
+    path: "/contacts",
+    query: {
+      currentness: "archived"
+    }
+  });
+
+  assert.equal(runtime.calls.length, 1);
+  assert.deepEqual(runtime.calls[0], {
+    path: "/contacts",
+    options: {
+      method: "GET",
+      query: {
+        currentness: "archived",
+        limit: 20
+      }
+    }
+  });
+  runtime.app.unmount();
+  runtime.queryClient.clear();
+});
+
+test("route-synchronized lists make one initial request with a declarative default", async () => {
+  const runtime = await mountRouteSynchronizedList("/contacts");
+
+  assert.equal(runtime.calls.length, 1);
+  assert.equal(runtime.calls[0].options.query.currentness, "active");
+  runtime.app.unmount();
+  runtime.queryClient.clear();
+});
+
+test("invalid initial route filters fall back before the first list request", async () => {
+  const runtime = await mountRouteSynchronizedList({
+    path: "/contacts",
+    query: {
+      currentness: "not-a-valid-option"
+    }
+  });
+
+  assert.equal(runtime.calls.length, 1);
+  assert.equal(runtime.calls[0].options.query.currentness, "active");
+  runtime.app.unmount();
+  runtime.queryClient.clear();
+});
+
+test("route navigation rehydrates filters and a later clear stays cleared", async () => {
+  const runtime = await mountRouteSynchronizedList({
+    path: "/contacts",
+    query: {
+      currentness: "archived"
+    }
+  });
+
+  await runtime.router.push({
+    path: "/contacts",
+    query: {
+      currentness: "active"
+    }
+  });
+  await waitFor(() => runtime.filterRuntime.values.currentness === "active");
+  await waitFor(() => runtime.calls.length === 2);
+
+  runtime.router.back();
+  await waitFor(() => runtime.router.currentRoute.value.query.currentness === "archived");
+  await waitFor(() => runtime.filterRuntime.values.currentness === "archived");
+  await waitFor(() => runtime.calls.length === 3);
+
+  runtime.router.forward();
+  await waitFor(() => runtime.router.currentRoute.value.query.currentness === "active");
+  await waitFor(() => runtime.filterRuntime.values.currentness === "active");
+  await waitFor(() => runtime.calls.length === 4);
+
+  runtime.filterRuntime.clearFilter("currentness");
+  await waitFor(() => !Object.hasOwn(runtime.router.currentRoute.value.query, "currentness"));
+  await waitFor(
+    () => runtime.calls.length >= 5,
+    `Expected one request after clearing the filter; received ${runtime.calls.length}.`
+  );
+
+  assert.equal(runtime.calls.length, 5, JSON.stringify(runtime.calls, null, 2));
+  assert.equal(runtime.filterRuntime.values.currentness, "");
+  assert.deepEqual(runtime.calls.at(-1).options.query, {
+    limit: 20
+  });
+  runtime.app.unmount();
+  runtime.queryClient.clear();
+});

package/test/useListSearchSupport.test.js

@@ -0,0 +1,61 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+  normalizeListSearchConfig,
+  matchesLocalSearch
+} from "../src/client/composables/support/listSearchSupport.js";
+
+test("normalizeListSearchConfig defaults to disabled query search", () => {
+  const config = normalizeListSearchConfig();
+  assert.equal(config.enabled, false);
+  assert.equal(config.mode, "query");
+  assert.equal(config.queryParam, "q");
+  assert.equal(config.label, "Search");
+  assert.equal(config.minLength, 1);
+});
+
+test("normalizeListSearchConfig accepts query mode and fields", () => {
+  const config = normalizeListSearchConfig({
+    enabled: true,
+    mode: "query",
+    queryParam: "search",
+    fields: ["name", "name", "email"]
+  });
+  assert.equal(config.enabled, true);
+  assert.equal(config.mode, "query");
+  assert.equal(config.queryParam, "search");
+  assert.deepEqual(config.fields, ["name", "email"]);
+});
+
+test("normalizeListSearchConfig accepts explicit local mode", () => {
+  const config = normalizeListSearchConfig({
+    enabled: true,
+    mode: "local"
+  });
+  assert.equal(config.mode, "local");
+});
+
+test("matchesLocalSearch checks configured fields", () => {
+  const result = matchesLocalSearch(
+    {
+      firstName: "Ana",
+      surname: "Marin",
+      phone: "0400"
+    },
+    "mar",
+    ["surname"]
+  );
+  assert.equal(result, true);
+});
+
+test("matchesLocalSearch scans scalar values when fields are not configured", () => {
+  const result = matchesLocalSearch(
+    {
+      firstName: "Ana",
+      surname: "Marin",
+      count: 42
+    },
+    "42"
+  );
+  assert.equal(result, true);
+});

package/test/usePagedCollection.test.js

@@ -0,0 +1,53 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { trimInfinitePagesToFirst } from "../src/client/composables/usePagedCollection.js";
+
+test("trimInfinitePagesToFirst leaves non-object payloads untouched", () => {
+  assert.equal(trimInfinitePagesToFirst(null), null);
+  assert.equal(trimInfinitePagesToFirst(""), "");
+  assert.equal(trimInfinitePagesToFirst(12), 12);
+});
+
+test("trimInfinitePagesToFirst leaves single-page payload unchanged", () => {
+  const payload = Object.freeze({
+    pages: Object.freeze([{ items: [1, 2] }]),
+    pageParams: Object.freeze([null])
+  });
+
+  assert.equal(trimInfinitePagesToFirst(payload), payload);
+});
+
+test("trimInfinitePagesToFirst truncates to the first page and first pageParam", () => {
+  const payload = {
+    pages: [
+      { items: [1, 2] },
+      { items: [3, 4] },
+      { items: [5, 6] }
+    ],
+    pageParams: [null, "cursor-1", "cursor-2"],
+    extra: true
+  };
+
+  assert.deepEqual(
+    trimInfinitePagesToFirst(payload),
+    {
+      pages: [{ items: [1, 2] }],
+      pageParams: [null],
+      extra: true
+    }
+  );
+});
+
+test("trimInfinitePagesToFirst injects null pageParam when missing", () => {
+  const payload = {
+    pages: [{ items: [1] }, { items: [2] }]
+  };
+
+  assert.deepEqual(
+    trimInfinitePagesToFirst(payload),
+    {
+      pages: [{ items: [1] }],
+      pageParams: [null]
+    }
+  );
+});

package/test/useViewRequestQueryParams.test.js

@@ -0,0 +1,20 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { buildRequestQueryObject } from "../src/client/composables/support/requestQueryRuntimeSupport.js";
+
+test("buildRequestQueryObject preserves repeated keys as arrays deterministically", () => {
+  assert.deepEqual(
+    buildRequestQueryObject([
+      { key: "include", values: ["vetId", "linkedUserId", "pets", "pets.breedId"] },
+      { key: "limit", values: ["10"] }
+    ]),
+    {
+      include: ["vetId", "linkedUserId", "pets", "pets.breedId"],
+      limit: "10"
+    }
+  );
+});
+
+test("buildRequestQueryObject returns an empty object when no request params are active", () => {
+  assert.deepEqual(buildRequestQueryObject([]), {});
+});

package/test/viewCoreLoading.test.js

@@ -0,0 +1,44 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { ref } from "vue";
+import { useViewCore } from "../src/client/composables/runtime/useViewCore.js";
+
+test("useViewCore prefers resource isInitialLoading/isFetching signals when provided", () => {
+  const resource = {
+    data: ref({ id: 42 }),
+    isInitialLoading: ref(false),
+    isFetching: ref(true),
+    query: {
+      isPending: ref(true),
+      isFetching: ref(true),
+      error: ref(null)
+    },
+    loadError: ref("")
+  };
+
+  const view = useViewCore({
+    resource
+  });
+
+  assert.equal(view.isLoading.value, false);
+  assert.equal(view.isFetching.value, true);
+});
+
+test("useViewCore falls back to query pending/fetching when resource-level loading refs are absent", () => {
+  const resource = {
+    data: ref(null),
+    query: {
+      isPending: ref(true),
+      isFetching: ref(false),
+      error: ref(null)
+    },
+    loadError: ref("")
+  };
+
+  const view = useViewCore({
+    resource
+  });
+
+  assert.equal(view.isLoading.value, true);
+  assert.equal(view.isFetching.value, false);
+});

package/test/viewUiRuntime.test.js

@@ -0,0 +1,95 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { ref } from "vue";
+import { createViewUiRuntime } from "../src/client/composables/runtime/viewUiRuntime.js";
+
+test("createViewUiRuntime resolves api/list/edit paths with nested params", () => {
+  const runtime = createViewUiRuntime({
+    recordIdParam: "addressId",
+    routeParams: ref({
+      userId: "user-7",
+      addressId: "addr-42"
+    }),
+    routePath: ref("/users/user-7/addresses/addr-42"),
+    apiUrlTemplate: "/crud/users/:userId/addresses/:addressId",
+    listUrlTemplate: "..",
+    editUrlTemplate: "./edit"
+  });
+
+  assert.equal(runtime.recordId.value, "addr-42");
+  assert.equal(runtime.apiSuffix.value, "/crud/users/user-7/addresses/addr-42");
+  assert.equal(runtime.listUrl.value, "/users/user-7/addresses");
+  assert.equal(runtime.editUrl.value, "/users/user-7/addresses/addr-42/edit");
+  assert.equal(runtime.resolveParams("./edit"), "/users/user-7/addresses/addr-42/edit");
+});
+
+test("createViewUiRuntime resolves view links from the record pathname when route is nested", () => {
+  const runtime = createViewUiRuntime({
+    recordIdParam: "contactId",
+    routeParams: ref({
+      workspaceSlug: "dogandgroom",
+      contactId: "541841",
+      petId: "715528"
+    }),
+    routeParamNames: ref(["workspaceSlug", "contactId", "petId"]),
+    routePath: ref("/w/dogandgroom/admin/contacts/541841/pets/715528"),
+    listUrlTemplate: "..",
+    editUrlTemplate: "./edit"
+  });
+
+  assert.equal(runtime.listUrl.value, "/w/dogandgroom/admin/contacts");
+  assert.equal(runtime.editUrl.value, "/w/dogandgroom/admin/contacts/541841/edit");
+  assert.equal(runtime.resolveParams("./edit"), "/w/dogandgroom/admin/contacts/541841/edit");
+});
+
+test("createViewUiRuntime uses route param order when repeated values are present", () => {
+  const runtime = createViewUiRuntime({
+    recordIdParam: "contactId",
+    routeParams: ref({
+      workspaceSlug: "123",
+      contactId: "123",
+      petId: "123"
+    }),
+    routeParamNames: ref(["workspaceSlug", "contactId", "petId"]),
+    routePath: ref("/w/123/admin/contacts/123/pets/123"),
+    editUrlTemplate: "./edit"
+  });
+
+  assert.equal(runtime.editUrl.value, "/w/123/admin/contacts/123/edit");
+});
+
+test("createViewUiRuntime uses explicit routeRecordId when route params do not include id", () => {
+  const runtime = createViewUiRuntime({
+    recordIdParam: "addressId",
+    routeParams: ref({
+      userId: "user-7"
+    }),
+    routeRecordId: ref("new-id"),
+    apiUrlTemplate: "/crud/users/:userId/addresses/:addressId"
+  });
+
+  assert.equal(runtime.recordId.value, "new-id");
+  assert.equal(runtime.apiSuffix.value, "/crud/users/user-7/addresses/new-id");
+});
+
+test("createViewUiRuntime returns empty api suffix when required params are missing", () => {
+  const runtime = createViewUiRuntime({
+    recordIdParam: "addressId",
+    routeParams: ref({
+      addressId: "42"
+    }),
+    apiUrlTemplate: "/crud/users/:userId/addresses/:addressId"
+  });
+
+  assert.equal(runtime.apiSuffix.value, "");
+});
+
+test("createViewUiRuntime validates route parameter names", () => {
+  assert.throws(
+    () =>
+      createViewUiRuntime({
+        recordIdParam: "record-id"
+      }),
+    /recordIdParam "record-id" is invalid/
+  );
+});