@jskit-ai/http-web 0.1.1

package/src/client/composables/useCrudListParentTitle.js

@@ -0,0 +1,151 @@
+import { computed, proxyRefs } from "vue";
+import { useRoute } from "vue-router";
+import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+import { inferCrudLookupJsonApiTransport } from "./crud/crudJsonApiTransportSupport.js";
+import {
+  resolveRouteParamsSource,
+  toRouteParamValue
+} from "./support/routeTemplateHelpers.js";
+import { useView } from "./records/useView.js";
+import {
+  resolveCrudListParentDescriptor,
+  resolveCrudListParentRecordTitle,
+  resolveCrudListParentTitleFromItems
+} from "./internal/crudListParentTitleSupport.js";
+
+function normalizeQueryKeyPrefix(value = []) {
+  if (Array.isArray(value)) {
+    return value
+      .map((entry) => normalizeText(entry))
+      .filter(Boolean);
+  }
+
+  const normalizedValue = normalizeText(value);
+  return normalizedValue ? [normalizedValue] : [];
+}
+
+function useCrudListParentTitle({
+  listRuntime = null,
+  resource = {},
+  adapter = null,
+  recordIdParam = "recordId",
+  queryKeyPrefix = ["http-web", "crud-list-parent-title"],
+  placementSource = "http-web.crud-list-parent-title",
+  fallbackLoadError = "Unable to load parent record.",
+  notFoundMessage = "Parent record not found.",
+  route = null,
+  viewRuntimeFactory = useView
+} = {}) {
+  const sourceRoute = route && typeof route === "object" ? route : useRoute();
+  const parentDescriptor = computed(() => {
+    const descriptor = resolveCrudListParentDescriptor({
+      resource,
+      route: sourceRoute,
+      recordIdParam
+    });
+    if (!descriptor) {
+      return null;
+    }
+
+    const routeParams = resolveRouteParamsSource(sourceRoute?.params || {});
+    const routeParamValue = toRouteParamValue(routeParams[descriptor.routeParamKey]);
+    if (!routeParamValue) {
+      return null;
+    }
+
+    return Object.freeze({
+      ...descriptor,
+      routeParamValue
+    });
+  });
+
+  const initialParentDescriptor = parentDescriptor.value || {};
+  const parentTransport = (() => {
+    const baseTransport = inferCrudLookupJsonApiTransport({
+      namespace: initialParentDescriptor.relationNamespace
+    });
+    if (!baseTransport) {
+      return null;
+    }
+
+    return Object.freeze({
+      ...baseTransport,
+      responseKind: "record"
+    });
+  })();
+  const normalizedQueryKeyPrefix = normalizeQueryKeyPrefix(queryKeyPrefix);
+  const shouldLoadParentRecord = computed(() => {
+    const descriptor = parentDescriptor.value;
+    if (!descriptor?.apiUrlTemplate) {
+      return false;
+    }
+    if (Boolean(listRuntime?.isInitialLoading) || normalizeText(listRuntime?.loadError)) {
+      return false;
+    }
+
+    const items = Array.isArray(listRuntime?.items) ? listRuntime.items : [];
+    if (items.length < 1) {
+      return true;
+    }
+
+    const listTitle = resolveCrudListParentTitleFromItems(items, descriptor);
+    return !listTitle;
+  });
+
+  const parentView = viewRuntimeFactory({
+    adapter,
+    apiUrlTemplate: normalizeText(initialParentDescriptor.apiUrlTemplate),
+    transport: parentTransport,
+    readEnabled: shouldLoadParentRecord,
+    recordIdParam: normalizeText(initialParentDescriptor.routeParamKey) || "recordId",
+    includeRecordIdInQueryKey: true,
+    queryKeyFactory: (surfaceId = "", scopeParamValue = "") => [
+      ...normalizedQueryKeyPrefix,
+      normalizeText(initialParentDescriptor.relationNamespace),
+      normalizeText(initialParentDescriptor.routeParamKey),
+      String(surfaceId || ""),
+      String(scopeParamValue || "")
+    ],
+    placementSource,
+    fallbackLoadError,
+    notFoundMessage
+  });
+
+  const title = computed(() => {
+    const descriptor = parentDescriptor.value;
+    if (!descriptor) {
+      return "";
+    }
+
+    const parentRecordTitle = resolveCrudListParentRecordTitle(parentView?.record || {}, descriptor);
+    if (parentRecordTitle && shouldLoadParentRecord.value) {
+      return parentRecordTitle;
+    }
+
+    const listTitle = resolveCrudListParentTitleFromItems(listRuntime?.items, descriptor);
+    if (listTitle) {
+      return listTitle;
+    }
+
+    if (parentRecordTitle) {
+      return parentRecordTitle;
+    }
+
+    if (descriptor.routeParamValue) {
+      return `${descriptor.entityLabel} #${descriptor.routeParamValue}`;
+    }
+
+    return descriptor.entityLabel;
+  });
+
+  return proxyRefs({
+    title,
+    descriptor: parentDescriptor,
+    shouldLoadParentRecord,
+    record: computed(() => parentView?.record || null),
+    isLoading: computed(() => Boolean(parentView?.isLoading)),
+    loadError: computed(() => normalizeText(parentView?.loadError))
+  });
+}
+
+export { useCrudListParentTitle };

package/src/client/composables/useCrudListRowActions.js

@@ -0,0 +1,144 @@
+import { computed, ref } from "vue";
+import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+import { defineCrudListRowActions } from "../rowActions.js";
+
+function normalizeRowActionKey(actionOrKey = "") {
+  return normalizeText(
+    actionOrKey && typeof actionOrKey === "object"
+      ? actionOrKey.key
+      : actionOrKey
+  );
+}
+
+function normalizeRowId(value = "") {
+  return normalizeText(value);
+}
+
+function createExecutionKey(actionKey = "", recordId = "", index = 0) {
+  return [
+    actionKey,
+    recordId || `index-${index}`
+  ].join(":");
+}
+
+function asContextObject(value = null) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+
+function useCrudListRowActions(actions = [], {
+  resolveRecordId = null,
+  resolveContext = null
+} = {}) {
+  const normalizedActions = defineCrudListRowActions(actions);
+  const executingKeys = ref([]);
+  const hasActions = computed(() => normalizedActions.length > 0);
+
+  function getRecordId(record = {}, index = 0) {
+    const resolvedId = typeof resolveRecordId === "function"
+      ? resolveRecordId(record, index)
+      : record?.id ?? record?.attributes?.id ?? index;
+    return normalizeRowId(resolvedId);
+  }
+
+  function createActionContext(action = {}, record = {}, index = 0) {
+    const baseContext = typeof resolveContext === "function" ? resolveContext() : {};
+    return {
+      ...asContextObject(baseContext),
+      action,
+      record,
+      index,
+      recordId: getRecordId(record, index)
+    };
+  }
+
+  function findAction(actionOrKey = "") {
+    const actionKey = normalizeRowActionKey(actionOrKey);
+    return normalizedActions.find((action) => action.key === actionKey) || null;
+  }
+
+  function resolveActionFlag(action = {}, flagKey = "", record = {}, index = 0, fallback = false) {
+    const flag = action?.[flagKey];
+    if (typeof flag === "function") {
+      return Boolean(flag(createActionContext(action, record, index)));
+    }
+    if (flag === undefined || flag === null) {
+      return fallback;
+    }
+    return Boolean(flag);
+  }
+
+  function isActionVisible(actionOrKey = "", record = {}, index = 0) {
+    const action = findAction(actionOrKey);
+    return action ? resolveActionFlag(action, "visible", record, index, true) : false;
+  }
+
+  function isActionExecuting(actionOrKey = "", record = {}, index = 0) {
+    const action = findAction(actionOrKey);
+    if (!action) {
+      return false;
+    }
+
+    const executionKey = createExecutionKey(action.key, getRecordId(record, index), index);
+    return executingKeys.value.includes(executionKey);
+  }
+
+  function isActionLoading(actionOrKey = "", record = {}, index = 0) {
+    const action = findAction(actionOrKey);
+    if (!action) {
+      return false;
+    }
+
+    return isActionExecuting(action, record, index) ||
+      resolveActionFlag(action, "loading", record, index, false);
+  }
+
+  function isActionDisabled(actionOrKey = "", record = {}, index = 0) {
+    const action = findAction(actionOrKey);
+    if (!action || !isActionVisible(action, record, index) || !action.run) {
+      return true;
+    }
+
+    return isActionLoading(action, record, index) ||
+      resolveActionFlag(action, "disabled", record, index, false);
+  }
+
+  function visibleActionsFor(record = {}, index = 0) {
+    return normalizedActions.filter((action) => isActionVisible(action, record, index));
+  }
+
+  function hasVisibleActionsFor(record = {}, index = 0) {
+    return visibleActionsFor(record, index).length > 0;
+  }
+
+  async function execute(actionOrKey = "", record = {}, index = 0) {
+    const action = findAction(actionOrKey);
+    if (!action || typeof action.run !== "function" || isActionDisabled(action, record, index)) {
+      return null;
+    }
+
+    const executionKey = createExecutionKey(action.key, getRecordId(record, index), index);
+    executingKeys.value = [...executingKeys.value, executionKey];
+    try {
+      return await action.run(createActionContext(action, record, index));
+    } finally {
+      executingKeys.value = executingKeys.value.filter((key) => key !== executionKey);
+    }
+  }
+
+  return Object.freeze({
+    actions: normalizedActions,
+    hasActions,
+    executingKeys,
+    getRecordId,
+    findAction,
+    isActionVisible,
+    isActionDisabled,
+    isActionLoading,
+    isActionExecuting,
+    visibleActionsFor,
+    hasVisibleActionsFor,
+    execute
+  });
+}
+
+export { useCrudListRowActions };

package/src/client/composables/useCrudListScreen.js

@@ -0,0 +1,237 @@
+import { computed, unref } from "vue";
+import { useCrudList } from "./records/useCrudList.js";
+import { useCrudListBulkActions } from "./useCrudListBulkActions.js";
+import { useCrudListFilters } from "./useCrudListFilters.js";
+import { useCrudListRowActions } from "./useCrudListRowActions.js";
+import { resolveCrudHttpClient } from "./crud/crudHttpClientSupport.js";
+
+function buildCrudListActionContext(records, client) {
+  return Object.freeze({
+    records,
+    reload: records.reload,
+    client
+  });
+}
+
+function formatCrudListCardValue(value) {
+  if (value === null || value === undefined || value === "") {
+    return "-";
+  }
+  if (value === true) {
+    return "Yes";
+  }
+  if (value === false) {
+    return "No";
+  }
+  return value;
+}
+
+function asList(value = []) {
+  const resolved = unref(value);
+  if (resolved == null) {
+    return [];
+  }
+  return Array.isArray(resolved) ? resolved : [resolved];
+}
+
+function hasSyntheticRowGroups(value = null) {
+  const source = unref(value);
+  return Boolean(
+    source &&
+      typeof source === "object" &&
+      !Array.isArray(source) &&
+      (Object.hasOwn(source, "prepend") || Object.hasOwn(source, "append"))
+  );
+}
+
+function normalizeSyntheticDisplayRow(source = null, index = 0, placement = "prepend") {
+  const rawRow = unref(source);
+  if (!rawRow || typeof rawRow !== "object" || Array.isArray(rawRow)) {
+    return null;
+  }
+
+  const hasWrappedRecord = Object.hasOwn(rawRow, "record");
+  const record = hasWrappedRecord ? unref(rawRow.record) : rawRow;
+  if (!record || typeof record !== "object" || Array.isArray(record)) {
+    return null;
+  }
+
+  const keySource = hasWrappedRecord
+    ? rawRow.key
+    : record.id ?? record.attributes?.id;
+  const recordKey = String(keySource || `synthetic-${placement}-${index + 1}`).trim();
+
+  return Object.freeze({
+    key: `synthetic:${placement}:${recordKey}`,
+    recordKey,
+    record,
+    index: hasWrappedRecord && Number.isInteger(rawRow.index) ? rawRow.index : -1,
+    synthetic: true,
+    selectable: rawRow.selectable === true,
+    placement
+  });
+}
+
+function normalizeSyntheticDisplayRows(value = [], placement = "prepend") {
+  return asList(value)
+    .map((row, index) => normalizeSyntheticDisplayRow(row, index, placement))
+    .filter(Boolean);
+}
+
+function normalizeSyntheticDisplayRowGroups(syntheticRows = null) {
+  const source = unref(syntheticRows);
+  if (hasSyntheticRowGroups(source)) {
+    return Object.freeze({
+      prepend: normalizeSyntheticDisplayRows(source.prepend, "prepend"),
+      append: normalizeSyntheticDisplayRows(source.append, "append")
+    });
+  }
+
+  return Object.freeze({
+    prepend: normalizeSyntheticDisplayRows(source, "prepend"),
+    append: []
+  });
+}
+
+function createCrudListDisplayRow(record = {}, index = 0, records = {}) {
+  const resolveRowKey = typeof records.resolveRowKey === "function"
+    ? records.resolveRowKey
+    : (_record, fallbackIndex) => fallbackIndex;
+  const recordKey = String(resolveRowKey(record, index) || index);
+  return Object.freeze({
+    key: `record:${recordKey}`,
+    recordKey,
+    record,
+    index,
+    synthetic: false,
+    selectable: true,
+    placement: "records"
+  });
+}
+
+function useCrudListScreen({
+  adapter = null,
+  client = null,
+  resource = null,
+  resourceNamespace = "resource",
+  apiSuffix = "",
+  recordIdParam = "recordId",
+  recordIdSelector = null,
+  titleFallbackFieldKey = "",
+  viewUrlTemplate = "",
+  editUrlTemplate = "",
+  newUrlTemplate = "",
+  recordChangedEvents = [],
+  listFilters = {},
+  listBulkActions = [],
+  listRowActions = [],
+  syntheticRows = null,
+  routeQueryBlacklist = Object.freeze(["include", "cursor", "limit"]),
+  requestQueryParams = null,
+  requestFieldsets = null,
+  readEnabled = true,
+  requestRecoveryLabel = "Records",
+  fallbackLoadError = "Unable to load records."
+} = {}) {
+  const crudHttpClient = resolveCrudHttpClient(resource, { client });
+  const filterRuntime = useCrudListFilters(listFilters);
+  const normalizedRecordChangedEvents = Array.isArray(recordChangedEvents)
+    ? recordChangedEvents
+    : [];
+  const normalizedResourceNamespace = String(resourceNamespace || "resource").trim() || "resource";
+  const records = useCrudList({
+    adapter: adapter || undefined,
+    client: crudHttpClient,
+    resource,
+    apiSuffix,
+    queryKeyFactory: (surfaceId = "", workspaceSlug = "") => [
+      "ui-generator",
+      normalizedResourceNamespace,
+      "list",
+      String(surfaceId || ""),
+      String(workspaceSlug || "")
+    ],
+    search: {
+      enabled: true,
+      mode: "query"
+    },
+    queryParams: filterRuntime.queryParams,
+    routeQueryValueResolvers: filterRuntime.routeQueryValueResolvers,
+    syncToRoute: {
+      enabled: true,
+      mode: "replace",
+      search: true,
+      queryParams: true,
+      queryParamBlacklist: routeQueryBlacklist
+    },
+    placementSource: `ui-generator.${normalizedResourceNamespace}.list`,
+    requestQueryParams,
+    requestFieldsets,
+    readEnabled,
+    requestRecoveryLabel,
+    fallbackLoadError,
+    recordIdParam,
+    recordIdSelector,
+    viewUrlTemplate,
+    editUrlTemplate,
+    realtime: normalizedRecordChangedEvents.length > 0
+      ? {
+          events: normalizedRecordChangedEvents
+        }
+      : null
+  });
+  const displayRows = computed(() => {
+    const syntheticRowGroups = normalizeSyntheticDisplayRowGroups(syntheticRows);
+    const recordRows = (Array.isArray(records.items) ? records.items : [])
+      .map((record, index) => createCrudListDisplayRow(record, index, records));
+
+    return [
+      ...syntheticRowGroups.prepend,
+      ...recordRows,
+      ...syntheticRowGroups.append
+    ];
+  });
+  const selectableRows = computed(() =>
+    displayRows.value.filter((row) => row.selectable !== false)
+  );
+  const bulkActions = useCrudListBulkActions(listBulkActions, {
+    resolveRecordId: (record, index) => records.resolveRowKey(record, index),
+    resolveContext: () => buildCrudListActionContext(records, crudHttpClient)
+  });
+  const rowActions = useCrudListRowActions(listRowActions, {
+    resolveRecordId: (record, index) => records.resolveRowKey(record, index),
+    resolveContext: () => buildCrudListActionContext(records, crudHttpClient)
+  });
+  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,
+    listRowActions,
+    rowActions,
+    displayRows,
+    selectableRows,
+    listPrimaryAction,
+    hasViewUrl: Boolean(viewUrlTemplate),
+    hasEditUrl: Boolean(editUrlTemplate),
+    resolveRecordTitle,
+    formatListCardValue: formatCrudListCardValue
+  });
+}
+
+const __testables = Object.freeze({
+  buildCrudListActionContext
+});
+
+export { __testables, useCrudListScreen };

package/src/client/composables/useCrudViewScreen.js

@@ -0,0 +1,77 @@
+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 = "",
+  requestQueryParams = null,
+  requestFieldsets = null,
+  readEnabled = true,
+  queryKeyFactory = null,
+  requestRecoveryLabel = "Record",
+  fallbackLoadError = "Unable to load record.",
+  notFoundMessage = "Record not found."
+} = {}) {
+  const route = useRoute();
+  const normalizedResourceNamespace = String(resourceNamespace || "resource").trim() || "resource";
+  const defaultQueryKeyFactory = (surfaceId = "", workspaceSlug = "") => [
+    "ui-generator",
+    normalizedResourceNamespace,
+    "view",
+    String(surfaceId || ""),
+    String(workspaceSlug || "")
+  ];
+  const view = useCrudView({
+    adapter: adapter || undefined,
+    resource,
+    apiUrlTemplate,
+    recordIdParam,
+    includeRecordIdInQueryKey: true,
+    queryKeyFactory: typeof queryKeyFactory === "function" ? queryKeyFactory : defaultQueryKeyFactory,
+    requestQueryParams,
+    requestFieldsets,
+    readEnabled,
+    placementSource: `ui-generator.${normalizedResourceNamespace}.view`,
+    requestRecoveryLabel,
+    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 };