@jskit-ai/users-web 0.1.81 → 0.1.83

package/src/client/composables/useCrudListScreen.js

@@ -0,0 +1,107 @@
+import { computed } from "vue";
+import { useCrudList } from "./records/useCrudList.js";
+import { useCrudListBulkActions } from "./useCrudListBulkActions.js";
+import { useCrudListFilters } from "./useCrudListFilters.js";
+
+function formatCrudListCardValue(value) {
+  if (value === null || value === undefined || value === "") {
+    return "-";
+  }
+  if (value === true) {
+    return "Yes";
+  }
+  if (value === false) {
+    return "No";
+  }
+  return value;
+}
+
+function useCrudListScreen({
+  adapter = null,
+  resource = null,
+  resourceNamespace = "resource",
+  apiSuffix = "",
+  recordIdParam = "recordId",
+  recordIdSelector = null,
+  titleFallbackFieldKey = "",
+  viewUrlTemplate = "",
+  editUrlTemplate = "",
+  newUrlTemplate = "",
+  recordChangedEvents = [],
+  listFilters = {},
+  listBulkActions = [],
+  routeQueryBlacklist = Object.freeze(["include", "cursor", "limit"]),
+  fallbackLoadError = "Unable to load records."
+} = {}) {
+  const filterRuntime = useCrudListFilters(listFilters);
+  const normalizedRecordChangedEvents = Array.isArray(recordChangedEvents)
+    ? recordChangedEvents
+    : [];
+  const normalizedResourceNamespace = String(resourceNamespace || "resource").trim() || "resource";
+  const records = useCrudList({
+    adapter: adapter || undefined,
+    resource,
+    apiSuffix,
+    queryKeyFactory: (surfaceId = "", workspaceSlug = "") => [
+      "ui-generator",
+      normalizedResourceNamespace,
+      "list",
+      String(surfaceId || ""),
+      String(workspaceSlug || "")
+    ],
+    search: {
+      enabled: true,
+      mode: "query"
+    },
+    queryParams: filterRuntime.queryParams,
+    syncToRoute: {
+      enabled: true,
+      mode: "replace",
+      search: true,
+      queryParams: true,
+      queryParamBlacklist: routeQueryBlacklist
+    },
+    placementSource: `ui-generator.${normalizedResourceNamespace}.list`,
+    fallbackLoadError,
+    recordIdParam,
+    recordIdSelector,
+    viewUrlTemplate,
+    editUrlTemplate,
+    realtime: normalizedRecordChangedEvents.length > 0
+      ? {
+          events: normalizedRecordChangedEvents
+        }
+      : null
+  });
+  const bulkActions = useCrudListBulkActions(listBulkActions, {
+    resolveRecordId: (record, index) => records.resolveRowKey(record, index),
+    resolveContext: () => ({
+      records,
+      reload: records.reload
+    })
+  });
+  const listPrimaryAction = computed(() =>
+    newUrlTemplate ? records.resolveParams(newUrlTemplate) : ""
+  );
+
+  function resolveRecordTitle(record) {
+    return records.resolveRecordTitle(record, {
+      fallbackKey: titleFallbackFieldKey,
+      defaultValue: "Record"
+    });
+  }
+
+  return Object.freeze({
+    records,
+    listFilters,
+    filterRuntime,
+    bulkActions,
+    listPrimaryAction,
+    hasViewUrl: Boolean(viewUrlTemplate),
+    hasEditUrl: Boolean(editUrlTemplate),
+    resolveRecordTitle,
+    formatListCardValue: formatCrudListCardValue
+  });
+}
+
+export { useCrudListScreen };

package/src/client/composables/useCrudViewScreen.js

@@ -0,0 +1,67 @@
+import { computed, unref } from "vue";
+import { useRoute } from "vue-router";
+import { useCrudView } from "./records/useCrudView.js";
+
+function useCrudViewScreen({
+  adapter = null,
+  resource = null,
+  resourceNamespace = "resource",
+  apiUrlTemplate = "",
+  recordIdParam = "recordId",
+  titleFallbackFieldKey = "",
+  listUrlTemplate = "",
+  editUrlTemplate = "",
+  recordChangedEvent = "",
+  fallbackLoadError = "Unable to load record.",
+  notFoundMessage = "Record not found."
+} = {}) {
+  const route = useRoute();
+  const normalizedResourceNamespace = String(resourceNamespace || "resource").trim() || "resource";
+  const view = useCrudView({
+    adapter: adapter || undefined,
+    resource,
+    apiUrlTemplate,
+    recordIdParam,
+    includeRecordIdInQueryKey: true,
+    queryKeyFactory: (surfaceId = "", workspaceSlug = "") => [
+      "ui-generator",
+      normalizedResourceNamespace,
+      "view",
+      String(surfaceId || ""),
+      String(workspaceSlug || "")
+    ],
+    placementSource: `ui-generator.${normalizedResourceNamespace}.view`,
+    fallbackLoadError,
+    notFoundMessage,
+    listUrlTemplate,
+    editUrlTemplate,
+    realtime: recordChangedEvent
+      ? {
+          event: recordChangedEvent
+        }
+      : null
+  });
+  const recordTitle = computed(() =>
+    view.resolveRecordTitle(view.record, {
+      fallbackKey: titleFallbackFieldKey,
+      defaultValue: "Record"
+    })
+  );
+
+  function resolveRouteLocation(urlTemplate = "") {
+    const path = view.resolveParams(unref(urlTemplate));
+    return path ? { path, query: route.query } : null;
+  }
+
+  const listLocation = computed(() => resolveRouteLocation(listUrlTemplate));
+  const editLocation = computed(() => resolveRouteLocation(editUrlTemplate));
+
+  return Object.freeze({
+    view,
+    recordTitle,
+    listLocation,
+    editLocation
+  });
+}
+
+export { useCrudViewScreen };

package/src/client/composables/usePagedCollection.js

@@ -3,6 +3,7 @@ import { useInfiniteQuery, useQueryClient } from "@tanstack/vue-query";
 import { asPlainObject } from "./support/scopeHelpers.js";
 import { resolveEnabledRef } from "./support/refValueHelpers.js";
 import { toQueryErrorMessage } from "./support/errorMessageHelpers.js";
+import { mergeQueryMeta } from "./support/resourceLoadStateHelpers.js";
 
 function defaultSelectItems(page) {
   return Array.isArray(page?.items) ? page.items : [];
@@ -83,7 +84,11 @@ function usePagedCollection({
     queryFn,
     getNextPageParam: (lastPage, allPages, lastPageParam, allPageParams) =>
       getNextPageParam(lastPage, allPages, lastPageParam, allPageParams),
-    ...(asPlainObject(queryOptions))
+    ...mergeQueryMeta(asPlainObject(queryOptions), {
+      jskit: {
+        refreshOnPull: true
+      }
+    })
   });
 
   const pages = computed(() => {

package/src/client/composables/useRealtimeQueryInvalidation.js

@@ -14,6 +14,31 @@ function normalizeRealtimeOptions(value = {}) {
   return value;
 }
 
+function hasRealtimeEventConfig(value = {}) {
+  const source = normalizeRealtimeOptions(value);
+  return Object.hasOwn(source, "event") || Object.hasOwn(source, "events");
+}
+
+function resolveOperationRealtimeOptions({
+  realtime = undefined,
+  fallbackRealtime = null
+} = {}) {
+  if (realtime === false) {
+    return null;
+  }
+
+  const fallback = normalizeRealtimeOptions(fallbackRealtime);
+  const explicit = realtime == null ? {} : normalizeRealtimeOptions(realtime);
+  if (hasRealtimeEventConfig(explicit) || !hasRealtimeEventConfig(fallback)) {
+    return Object.keys(explicit).length > 0 ? explicit : null;
+  }
+
+  return Object.freeze({
+    ...fallback,
+    ...explicit
+  });
+}
+
 function resolveEnabled(value) {
   if (typeof value === "undefined") {
     return true;
@@ -125,6 +150,7 @@ function useOperationRealtime({
 }
 
 export {
+  resolveOperationRealtimeOptions,
   useRealtimeQueryInvalidation,
   useOperationRealtime
 };

package/src/client/filters.js

@@ -0,0 +1,15 @@
+export {
+  CRUD_LIST_FILTER_TYPE_FLAG,
+  CRUD_LIST_FILTER_TYPE_ENUM,
+  CRUD_LIST_FILTER_TYPE_ENUM_MANY,
+  CRUD_LIST_FILTER_TYPE_RECORD_ID,
+  CRUD_LIST_FILTER_TYPE_RECORD_ID_MANY,
+  CRUD_LIST_FILTER_TYPE_DATE,
+  CRUD_LIST_FILTER_TYPE_DATE_RANGE,
+  CRUD_LIST_FILTER_TYPE_NUMBER_RANGE,
+  CRUD_LIST_FILTER_TYPE_PRESENCE,
+  CRUD_LIST_FILTER_PRESENCE_PRESENT,
+  CRUD_LIST_FILTER_PRESENCE_MISSING,
+  CRUD_LIST_FILTER_PRESENCE_OPTIONS,
+  defineCrudListFilters
+} from "@jskit-ai/kernel/shared/support/crudListFilters";

package/src/client/index.js

@@ -2,6 +2,11 @@ import { UsersWebClientProvider } from "./providers/UsersWebClientProvider.js";
 
 export { UsersWebClientProvider } from "./providers/UsersWebClientProvider.js";
 export { default as AccountSettingsClientElement } from "./components/AccountSettingsClientElement.vue";
+export { default as CrudAddEditScreen } from "./components/CrudAddEditScreen.vue";
+export { default as CrudListBulkActionSurface } from "./components/CrudListBulkActionSurface.vue";
+export { default as CrudListFilterSurface } from "./components/CrudListFilterSurface.vue";
+export { default as CrudListScreen } from "./components/CrudListScreen.vue";
+export { default as CrudViewScreen } from "./components/CrudViewScreen.vue";
 
 const clientProviders = Object.freeze([UsersWebClientProvider]);
 

package/templates/src/components/account/settings/AccountSettingsNotificationsSection.vue

@@ -10,12 +10,11 @@ const notifications = props.runtime.notifications;
 </script>
 
 <template>
-  <v-card rounded="lg" elevation="0" border>
-    <v-card-item>
-      <v-card-title class="text-subtitle-1">Notifications</v-card-title>
-    </v-card-item>
-    <v-divider />
-    <v-card-text>
+  <v-sheet rounded="lg" border class="account-settings-section">
+    <header class="account-settings-section__header">
+      <h2 class="account-settings-section__title">Notifications</h2>
+    </header>
+    <div class="account-settings-section__body">
       <v-form @submit.prevent="notifications.submit" novalidate>
         <v-switch
           v-model="notifications.form.productUpdates"
@@ -50,6 +49,33 @@ const notifications = props.runtime.notifications;
           Save notification settings
         </v-btn>
       </v-form>
-    </v-card-text>
-  </v-card>
+    </div>
+  </v-sheet>
 </template>
+
+<style scoped>
+.account-settings-section {
+  overflow: hidden;
+}
+
+.account-settings-section__header {
+  padding: 1rem 1rem 0;
+}
+
+.account-settings-section__title {
+  font-size: 1rem;
+  font-weight: 650;
+  line-height: 1.2;
+  margin: 0;
+}
+
+.account-settings-section__body {
+  padding: 1rem;
+}
+
+@media (max-width: 640px) {
+  .account-settings-section__body :deep(.v-btn) {
+    min-height: 48px;
+  }
+}
+</style>

package/templates/src/components/account/settings/AccountSettingsPreferencesSection.vue

@@ -10,12 +10,11 @@ const preferences = props.runtime.preferences;
 </script>
 
 <template>
-  <v-card rounded="lg" elevation="0" border>
-    <v-card-item>
-      <v-card-title class="text-subtitle-1">Preferences</v-card-title>
-    </v-card-item>
-    <v-divider />
-    <v-card-text>
+  <v-sheet rounded="lg" border class="account-settings-section">
+    <header class="account-settings-section__header">
+      <h2 class="account-settings-section__title">Preferences</h2>
+    </header>
+    <div class="account-settings-section__body">
       <v-form @submit.prevent="preferences.submit" novalidate>
         <v-row>
           <v-col cols="12" md="4">
@@ -120,6 +119,33 @@ const preferences = props.runtime.preferences;
           Save preferences
         </v-btn>
       </v-form>
-    </v-card-text>
-  </v-card>
+    </div>
+  </v-sheet>
 </template>
+
+<style scoped>
+.account-settings-section {
+  overflow: hidden;
+}
+
+.account-settings-section__header {
+  padding: 1rem 1rem 0;
+}
+
+.account-settings-section__title {
+  font-size: 1rem;
+  font-weight: 650;
+  line-height: 1.2;
+  margin: 0;
+}
+
+.account-settings-section__body {
+  padding: 1rem;
+}
+
+@media (max-width: 640px) {
+  .account-settings-section__body :deep(.v-btn) {
+    min-height: 48px;
+  }
+}
+</style>

package/templates/src/components/account/settings/AccountSettingsProfileSection.vue

@@ -10,12 +10,11 @@ const profile = props.runtime.profile;
 </script>
 
 <template>
-  <v-card rounded="lg" elevation="0" border>
-    <v-card-item>
-      <v-card-title class="text-subtitle-1">Profile</v-card-title>
-    </v-card-item>
-    <v-divider />
-    <v-card-text>
+  <v-sheet rounded="lg" border class="account-settings-section">
+    <header class="account-settings-section__header">
+      <h2 class="account-settings-section__title">Profile</h2>
+    </header>
+    <div class="account-settings-section__body">
       <v-form @submit.prevent="profile.submit" novalidate>
         <v-row class="mb-2">
           <v-col cols="12" md="4" class="d-flex flex-column align-center justify-center">
@@ -89,6 +88,33 @@ const profile = props.runtime.profile;
           Save profile
         </v-btn>
       </v-form>
-    </v-card-text>
-  </v-card>
+    </div>
+  </v-sheet>
 </template>
+
+<style scoped>
+.account-settings-section {
+  overflow: hidden;
+}
+
+.account-settings-section__header {
+  padding: 1rem 1rem 0;
+}
+
+.account-settings-section__title {
+  font-size: 1rem;
+  font-weight: 650;
+  line-height: 1.2;
+  margin: 0;
+}
+
+.account-settings-section__body {
+  padding: 1rem;
+}
+
+@media (max-width: 640px) {
+  .account-settings-section__body :deep(.v-btn) {
+    min-height: 48px;
+  }
+}
+</style>

package/test/crudListBulkActionSurface.test.js

@@ -0,0 +1,27 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import path from "node:path";
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+
+const TEST_DIRECTORY = path.dirname(fileURLToPath(import.meta.url));
+const PACKAGE_DIR = path.resolve(TEST_DIRECTORY, "..");
+
+test("CrudListBulkActionSurface stays adaptive and runtime-owned", async () => {
+  const source = await readFile(
+    path.join(PACKAGE_DIR, "src", "client", "components", "CrudListBulkActionSurface.vue"),
+    "utf8"
+  );
+
+  assert.match(source, /defineProps/);
+  assert.match(source, /useDisplay/);
+  assert.match(source, /v-if="shouldRender"/);
+  assert.match(source, /selectedCount/);
+  assert.match(source, /hasActions/);
+  assert.match(source, /hasSelection/);
+  assert.match(source, /v-menu/);
+  assert.match(source, /Bulk actions/);
+  assert.match(source, /min-height:\s*48px/);
+  assert.doesNotMatch(source, /useCrudList\(/);
+  assert.doesNotMatch(source, /apiSuffix|repository|server/);
+});

package/test/crudListFilterSurface.test.js

@@ -0,0 +1,45 @@
+import assert from "node:assert/strict";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+
+const TEST_DIRECTORY = path.dirname(fileURLToPath(import.meta.url));
+const PACKAGE_DIR = path.resolve(TEST_DIRECTORY, "..");
+
+test("users-web exposes client-side CRUD list filter definition helpers", async () => {
+  const { defineCrudListFilters } = await import("@jskit-ai/users-web/client/filters");
+
+  const filters = defineCrudListFilters({
+    status: {
+      type: "enum",
+      label: "Status",
+      options: [
+        { value: "active", label: "Active" }
+      ]
+    }
+  });
+
+  assert.equal(filters.status.queryKey, "status");
+  assert.equal(filters.status.options[0].label, "Active");
+});
+
+test("CrudListFilterSurface provides adaptive controls without owning server semantics", async () => {
+  const source = await readFile(
+    path.join(PACKAGE_DIR, "src", "client", "components", "CrudListFilterSurface.vue"),
+    "utf8"
+  );
+
+  assert.match(source, /defineProps/);
+  assert.match(source, /useDisplay/);
+  assert.match(source, /v-if="shouldRender"/);
+  assert.match(source, /filterEntries/);
+  assert.match(source, /runtimeValues\[filter\.key\]/);
+  assert.match(source, /activeChips/);
+  assert.match(source, /clearChip/);
+  assert.match(source, /clearFilters/);
+  assert.match(source, /v-dialog/);
+  assert.match(source, /min-height:\s*48px/);
+  assert.doesNotMatch(source, /useCrudList\(/);
+  assert.doesNotMatch(source, /apiSuffix|server|repository/);
+});

package/test/crudScreenComponents.test.js

@@ -0,0 +1,62 @@
+import assert from "node:assert/strict";
+import path from "node:path";
+import test from "node:test";
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+
+const TEST_DIRECTORY = path.dirname(fileURLToPath(import.meta.url));
+const PACKAGE_DIR = path.resolve(TEST_DIRECTORY, "..");
+
+async function readComponent(name) {
+  return readFile(path.join(PACKAGE_DIR, "src", "client", "components", name), "utf8");
+}
+
+test("CRUD screen components own generated list/view/form chrome centrally", async () => {
+  const listSource = await readComponent("CrudListScreen.vue");
+  const viewSource = await readComponent("CrudViewScreen.vue");
+  const addEditSource = await readComponent("CrudAddEditScreen.vue");
+
+  assert.match(listSource, /CrudListBulkActionSurface/);
+  assert.match(listSource, /CrudListFilterSurface/);
+  assert.match(listSource, /ui-generator-list-cards d-md-none/);
+  assert.match(listSource, /ui-generator-list-table d-none d-md-block/);
+  assert.match(listSource, /class="ui-generator-list-fab d-md-none"/);
+  assert.match(listSource, /#activator[\s\S]*Actions/);
+  assert.match(listSource, /min-height:\s*48px/);
+  assert.match(listSource, /<slot[\s\S]*name="card-fields"/);
+  assert.match(listSource, /<slot name="table-header"/);
+  assert.match(listSource, /<slot name="table-row"/);
+
+  assert.match(viewSource, /generated-ui-screen generated-ui-screen--operator ui-generator-view-element/);
+  assert.match(viewSource, /ui-generator-view-panel/);
+  assert.match(viewSource, /@click="view\.refresh"/);
+  assert.match(viewSource, /<slot name="fields"/);
+
+  assert.match(addEditSource, /generated-ui-screen generated-ui-screen--operator ui-generator-add-edit-form/);
+  assert.match(addEditSource, /addEdit\.canRetryLoad/);
+  assert.match(addEditSource, /@click="addEdit\.refresh"/);
+  assert.match(addEditSource, /<slot[\s\S]*name="fields"/);
+});
+
+test("account settings load state exposes a local retry action", async () => {
+  const source = await readComponent("AccountSettingsClientElement.vue");
+
+  assert.match(source, /settingsLoadError/);
+  assert.match(source, /@click="runtime\.refreshSettings"/);
+});
+
+test("CRUD screen composables are importable package APIs", async () => {
+  const [
+    listModule,
+    viewModule,
+    addEditModule
+  ] = await Promise.all([
+    import("@jskit-ai/users-web/client/composables/useCrudListScreen"),
+    import("@jskit-ai/users-web/client/composables/useCrudViewScreen"),
+    import("@jskit-ai/users-web/client/composables/useCrudAddEditScreen")
+  ]);
+
+  assert.equal(typeof listModule.useCrudListScreen, "function");
+  assert.equal(typeof viewModule.useCrudViewScreen, "function");
+  assert.equal(typeof addEditModule.useCrudAddEditScreen, "function");
+});

package/test/errorIntentContract.test.js

@@ -0,0 +1,31 @@
+import assert from "node:assert/strict";
+import path from "node:path";
+import test from "node:test";
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+
+const TEST_DIRECTORY = path.dirname(fileURLToPath(import.meta.url));
+const PACKAGE_DIR = path.resolve(TEST_DIRECTORY, "..");
+
+async function readClientSource(relativePath) {
+  return readFile(path.join(PACKAGE_DIR, "src", "client", relativePath), "utf8");
+}
+
+test("users-web reports load errors as local resource-load intent by default", async () => {
+  const source = await readClientSource("composables/runtime/operationUiHelpers.js");
+
+  assert.match(source, /loadChannel = ""/);
+  assert.match(source, /notFoundChannel = ""/);
+  assert.match(source, /intent = "resource-load"/);
+  assert.match(source, /intent: "resource-load"/);
+  assert.doesNotMatch(source, /loadChannel = "banner"/);
+});
+
+test("users-web action feedback lets shell policy choose snackbar presentation", async () => {
+  const source = await readClientSource("composables/runtime/useUiFeedback.js");
+
+  assert.match(source, /successChannel = ""/);
+  assert.match(source, /errorChannel = ""/);
+  assert.match(source, /intent: "action-feedback"/);
+  assert.doesNotMatch(source, /errorChannel = "banner"/);
+});

package/test/exportsContract.test.js

@@ -16,7 +16,14 @@ test("users-web exports are explicit and aligned with production/template usage"
     requiredExports: [
       "./client",
       "./client/components/AccountSettingsClientElement",
+      "./client/components/CrudAddEditScreen",
+      "./client/components/CrudListBulkActionSurface",
+      "./client/components/CrudListFilterSurface",
+      "./client/components/CrudListScreen",
+      "./client/components/CrudViewScreen",
       "./client/account-settings/sections",
+      "./client/bulkActions",
+      "./client/filters",
       "./client/composables/useAddEdit",
       "./client/composables/useCommand",
       "./client/composables/useEndpointResource",
@@ -24,10 +31,14 @@ test("users-web exports are explicit and aligned with production/template usage"
       "./client/composables/usePaths",
       "./client/composables/useView",
       "./client/composables/useCrudAddEdit",
+      "./client/composables/useCrudAddEditScreen",
+      "./client/composables/useCrudListBulkActions",
       "./client/composables/useCrudListFilterLookups",
       "./client/composables/useCrudListFilters",
       "./client/composables/useCrudList",
+      "./client/composables/useCrudListScreen",
       "./client/composables/useCrudView",
+      "./client/composables/useCrudViewScreen",
       "./client/lib/httpClient"
     ]
   });