@jskit-ai/http-web 0.1.1

package/src/client/components/CrudViewScreen.vue

@@ -0,0 +1,197 @@
+<script setup>
+import { computed, unref } from "vue";
+
+const props = defineProps({
+  screen: {
+    type: Object,
+    required: true
+  },
+  resourceSingularTitle: {
+    type: String,
+    default: "Record"
+  },
+  resourcePluralTitle: {
+    type: String,
+    default: "Records"
+  },
+  description: {
+    type: String,
+    default: ""
+  },
+  unavailableTitle: {
+    type: String,
+    default: "Record unavailable"
+  }
+});
+
+const view = computed(() => props.screen?.view || {});
+const recordTitle = computed(() => unref(props.screen?.recordTitle) || props.resourceSingularTitle);
+const listLocation = computed(() => unref(props.screen?.listLocation) || null);
+const editLocation = computed(() => unref(props.screen?.editLocation) || null);
+const resolvedDescription = computed(() =>
+  String(props.description || `Review this ${props.resourceSingularTitle} record.`).trim()
+);
+</script>
+
+<template>
+  <section class="generated-ui-screen generated-ui-screen--operator ui-generator-view-element d-flex flex-column ga-4">
+    <header class="ui-generator-view-header">
+      <div class="ui-generator-view-header__copy">
+        <p class="text-overline text-medium-emphasis mb-1">{{ resourceSingularTitle }}</p>
+        <h1 class="ui-generator-view-header__title">{{ recordTitle }}</h1>
+        <p class="text-body-2 text-medium-emphasis mb-0">{{ resolvedDescription }}</p>
+      </div>
+      <div class="ui-generator-view-header__actions">
+        <v-btn
+          v-if="listLocation"
+          color="primary"
+          variant="outlined"
+          :to="listLocation"
+        >
+          Back to {{ resourcePluralTitle }}
+        </v-btn>
+        <slot name="actions" :screen="screen" :view="view" />
+        <v-btn
+          v-if="editLocation"
+          color="primary"
+          variant="flat"
+          :to="editLocation"
+        >
+          Edit
+        </v-btn>
+      </div>
+    </header>
+
+    <v-sheet rounded="lg" border class="ui-generator-view-panel">
+      <div v-if="view.loadError || view.isNotFound" class="ui-generator-view-state">
+        <h2 class="text-h6 mb-2">{{ unavailableTitle }}</h2>
+        <p class="text-body-2 text-medium-emphasis mb-4">
+          {{ view.loadError || `This ${resourceSingularTitle} could not be found.` }}
+        </p>
+        <div class="ui-generator-view-state__actions">
+          <v-btn
+            v-if="view.loadError"
+            color="primary"
+            variant="tonal"
+            :loading="view.isFetching"
+            @click="view.refresh"
+          >
+            Retry
+          </v-btn>
+          <v-btn
+            v-else-if="listLocation"
+            color="primary"
+            variant="tonal"
+            :to="listLocation"
+          >
+            Back to {{ resourcePluralTitle }}
+          </v-btn>
+        </div>
+      </div>
+
+      <template v-else-if="view.isLoading">
+        <div class="pa-4">
+          <v-skeleton-loader type="text@2, list-item-two-line@5" />
+        </div>
+      </template>
+
+      <template v-else>
+        <v-progress-linear v-if="view.isRefetching" indeterminate />
+        <div class="pa-4">
+          <slot name="before-fields" :view="view" />
+          <v-row class="ui-generator-view-fields">
+            <slot name="fields" :view="view" />
+          </v-row>
+          <slot name="after-fields" :view="view" />
+        </div>
+      </template>
+    </v-sheet>
+
+    <div v-if="$slots['supporting-content']" class="ui-generator-view-supporting-content">
+      <slot name="supporting-content" :view="view" />
+    </div>
+  </section>
+</template>
+
+<style scoped>
+.generated-ui-screen {
+  --generated-ui-screen-title-size: clamp(1.35rem, 2vw, 1.85rem);
+  --generated-ui-screen-state-padding: 2.5rem 1.25rem;
+}
+
+.generated-ui-screen--operator {
+  --generated-ui-screen-state-padding: 2rem 1rem;
+}
+
+.ui-generator-view-header {
+  align-items: flex-start;
+  display: flex;
+  gap: 1rem;
+  justify-content: space-between;
+}
+
+.ui-generator-view-header__copy {
+  min-width: 0;
+}
+
+.ui-generator-view-header__title {
+  font-size: var(--generated-ui-screen-title-size);
+  font-weight: 650;
+  letter-spacing: -0.02em;
+  line-height: 1.15;
+  margin: 0 0 0.35rem;
+  overflow-wrap: anywhere;
+}
+
+.ui-generator-view-header__actions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.5rem;
+  justify-content: flex-end;
+}
+
+.ui-generator-view-panel {
+  overflow: hidden;
+}
+
+.ui-generator-view-state {
+  margin-inline: auto;
+  max-width: 30rem;
+  padding: var(--generated-ui-screen-state-padding);
+  text-align: center;
+}
+
+.ui-generator-view-state__actions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.5rem;
+  justify-content: center;
+}
+
+.ui-generator-view-fields :deep(.v-col) {
+  min-width: 0;
+}
+
+.ui-generator-view-supporting-content {
+  min-width: 0;
+}
+
+@media (max-width: 960px) {
+  .ui-generator-view-header {
+    flex-direction: column;
+  }
+
+  .ui-generator-view-header__actions {
+    width: 100%;
+  }
+
+  .ui-generator-view-header__actions :deep(.v-btn) {
+    min-height: 48px;
+    flex: 1 1 10rem;
+  }
+
+  .ui-generator-view-state__actions :deep(.v-btn) {
+    min-height: 48px;
+  }
+}
+</style>

package/src/client/composables/crud/crudBindingSupport.js

@@ -0,0 +1,75 @@
+import { unref } from "vue";
+import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+import { asPlainObject } from "../support/scopeHelpers.js";
+
+const CRUD_BINDING_MODE_ROUTE = "route";
+const CRUD_BINDING_MODE_MERGE = "merge";
+const CRUD_BINDING_MODE_EXPLICIT = "explicit";
+const CRUD_BINDING_MODE_NONE = "none";
+
+function normalizeCrudBindingMode(value = "") {
+  const normalizedValue = normalizeText(value).toLowerCase();
+  if (normalizedValue === CRUD_BINDING_MODE_MERGE) {
+    return CRUD_BINDING_MODE_MERGE;
+  }
+  if (normalizedValue === CRUD_BINDING_MODE_EXPLICIT) {
+    return CRUD_BINDING_MODE_EXPLICIT;
+  }
+  if (normalizedValue === CRUD_BINDING_MODE_NONE) {
+    return CRUD_BINDING_MODE_NONE;
+  }
+
+  return CRUD_BINDING_MODE_ROUTE;
+}
+
+function normalizeCrudBindingConfig(binding = {}) {
+  const source = asPlainObject(unref(binding));
+  return Object.freeze({
+    mode: normalizeCrudBindingMode(source.mode),
+    values: source.values ?? null
+  });
+}
+
+function resolveCrudBindingValues(values, context = {}) {
+  if (typeof values === "function") {
+    return asPlainObject(values(context));
+  }
+
+  return asPlainObject(unref(values));
+}
+
+function resolveCrudBoundValues({
+  binding = {},
+  routeValues = {},
+  context = {}
+} = {}) {
+  const normalizedBinding = normalizeCrudBindingConfig(binding);
+  const normalizedRouteValues = asPlainObject(routeValues);
+  const explicitValues = resolveCrudBindingValues(normalizedBinding.values, context);
+
+  if (normalizedBinding.mode === CRUD_BINDING_MODE_NONE) {
+    return {};
+  }
+  if (normalizedBinding.mode === CRUD_BINDING_MODE_EXPLICIT) {
+    return explicitValues;
+  }
+  if (normalizedBinding.mode === CRUD_BINDING_MODE_MERGE) {
+    return {
+      ...normalizedRouteValues,
+      ...explicitValues
+    };
+  }
+
+  return normalizedRouteValues;
+}
+
+export {
+  CRUD_BINDING_MODE_ROUTE,
+  CRUD_BINDING_MODE_MERGE,
+  CRUD_BINDING_MODE_EXPLICIT,
+  CRUD_BINDING_MODE_NONE,
+  normalizeCrudBindingMode,
+  normalizeCrudBindingConfig,
+  resolveCrudBindingValues,
+  resolveCrudBoundValues
+};

package/src/client/composables/crud/crudHttpClientSupport.js

@@ -0,0 +1,57 @@
+import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+import { getHttpWebClient } from "../../lib/httpClient.js";
+
+const CRUD_API_ACCESS_AUTHENTICATED = "authenticated";
+const CRUD_API_ACCESS_PUBLIC = "public";
+const CRUD_API_ACCESS_VALUES = Object.freeze([
+  CRUD_API_ACCESS_AUTHENTICATED,
+  CRUD_API_ACCESS_PUBLIC
+]);
+const publicCrudClients = new WeakSet();
+
+function normalizeCrudApiAccess(value = "") {
+  const normalized = normalizeText(value).toLowerCase() || CRUD_API_ACCESS_AUTHENTICATED;
+  if (CRUD_API_ACCESS_VALUES.includes(normalized)) {
+    return normalized;
+  }
+
+  throw new TypeError(
+    `CRUD resource apiAccess must be one of: ${CRUD_API_ACCESS_VALUES.join(", ")}. ` +
+      `Received: ${String(value || "") || "(empty)"}`
+  );
+}
+
+function resolveCrudHttpClient(resource = null, { client = null } = {}) {
+  const activeClient = client || getHttpWebClient();
+  if (!activeClient || typeof activeClient.request !== "function") {
+    throw new TypeError("resolveCrudHttpClient requires a client with request().");
+  }
+
+  if (normalizeCrudApiAccess(resource?.apiAccess) !== CRUD_API_ACCESS_PUBLIC) {
+    return activeClient;
+  }
+  if (publicCrudClients.has(activeClient)) {
+    return activeClient;
+  }
+
+  const publicClient = Object.freeze({
+    request(url, options = {}) {
+      const requestOptions = options && typeof options === "object" && !Array.isArray(options)
+        ? options
+        : {};
+      return activeClient.request(url, {
+        ...requestOptions,
+        csrf: false
+      });
+    }
+  });
+  publicCrudClients.add(publicClient);
+  return publicClient;
+}
+
+export {
+  CRUD_API_ACCESS_AUTHENTICATED,
+  CRUD_API_ACCESS_PUBLIC,
+  normalizeCrudApiAccess,
+  resolveCrudHttpClient
+};

package/src/client/composables/crud/crudJsonApiTransportSupport.js

@@ -0,0 +1,145 @@
+import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+import { normalizeCrudLookupNamespace } from "@jskit-ai/resource-crud-core/shared/crudLookup";
+
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function resolveSchemaFieldDefinitions(definition = null) {
+  const schema = definition?.schema;
+  if (!schema || typeof schema.getFieldDefinitions !== "function") {
+    return {};
+  }
+
+  const definitions = schema.getFieldDefinitions();
+  return isRecord(definitions) ? definitions : {};
+}
+
+function resolveLookupFieldMap(resource = null) {
+  const outputDefinition =
+    resource?.operations?.view?.output ||
+    resource?.operations?.create?.output ||
+    resource?.operations?.patch?.output ||
+    null;
+  const mapping = {};
+
+  for (const [fieldKey, fieldDefinition] of Object.entries(resolveSchemaFieldDefinitions(outputDefinition))) {
+    const normalizedFieldDefinition = isRecord(fieldDefinition) ? fieldDefinition : {};
+    if (!normalizeText(normalizedFieldDefinition.belongsTo)) {
+      continue;
+    }
+
+    const relationshipName = normalizeText(normalizedFieldDefinition.as, {
+      fallback: fieldKey
+    });
+    const normalizedFieldKey = normalizeText(fieldKey);
+    if (!normalizedFieldKey || !relationshipName) {
+      continue;
+    }
+
+    mapping[relationshipName] = normalizedFieldKey;
+  }
+
+  return Object.freeze(mapping);
+}
+
+function isJsonApiResourceTransport(transport = null) {
+  return normalizeText(transport?.kind).toLowerCase() === "jsonapi-resource";
+}
+
+function resolveCrudJsonApiResourceType(resource = null) {
+  return normalizeText(resource?.namespace);
+}
+
+function inferCrudLookupJsonApiTransport({ namespace = "", apiPath = "" } = {}) {
+  const resourceType =
+    normalizeCrudLookupNamespace(namespace) ||
+    normalizeCrudLookupNamespace(apiPath);
+  if (!resourceType) {
+    return null;
+  }
+
+  return Object.freeze({
+    kind: "jsonapi-resource",
+    responseType: resourceType,
+    responseKind: "collection"
+  });
+}
+
+function inferCrudJsonApiTransport(resource = null, { mode = "", operationName = "" } = {}) {
+  const resourceType = resolveCrudJsonApiResourceType(resource);
+  if (!resourceType) {
+    return null;
+  }
+
+  const normalizedMode = normalizeText(mode).toLowerCase();
+  const normalizedOperationName = normalizeText(operationName).toLowerCase();
+  if (normalizedMode === "list") {
+    return Object.freeze({
+      kind: "jsonapi-resource",
+      responseType: resourceType,
+      responseKind: "collection"
+    });
+  }
+
+  if (normalizedMode === "view") {
+    return Object.freeze({
+      kind: "jsonapi-resource",
+      responseType: resourceType,
+      responseKind: "record"
+    });
+  }
+
+  if (normalizedMode === "delete") {
+    return Object.freeze({
+      kind: "jsonapi-resource",
+      responseType: resourceType,
+      responseKind: "record"
+    });
+  }
+
+  if (normalizedMode === "add-edit") {
+    return Object.freeze({
+      kind: "jsonapi-resource",
+      ...(normalizedOperationName ? { requestType: resourceType } : {}),
+      responseType: resourceType,
+      responseKind: "record"
+    });
+  }
+
+  return null;
+}
+
+function resolveCrudJsonApiTransport(transport = null, resource = null, options = {}) {
+  if (transport != null) {
+    throw new TypeError(
+      "CRUD hooks do not accept explicit transport. Derive JSON:API transport from the shared resource."
+    );
+  }
+
+  const baseTransport = inferCrudJsonApiTransport(resource, options);
+  if (!isJsonApiResourceTransport(baseTransport)) {
+    return baseTransport;
+  }
+
+  const lookupFieldMap = resolveLookupFieldMap(resource);
+  const lookupContainerKey = normalizeText(resource?.contract?.lookup?.containerKey, {
+    fallback: "lookups"
+  });
+  if (Object.keys(lookupFieldMap).length < 1 && !lookupContainerKey) {
+    return baseTransport;
+  }
+
+  return Object.freeze({
+    ...baseTransport,
+    ...(Object.keys(lookupFieldMap).length > 0 ? { lookupFieldMap } : {}),
+    ...(lookupContainerKey ? { lookupContainerKey } : {})
+  });
+}
+
+export {
+  inferCrudJsonApiTransport,
+  inferCrudLookupJsonApiTransport,
+  resolveCrudJsonApiTransport,
+  resolveLookupFieldMap
+};

package/src/client/composables/crud/crudLookupFieldLabelSupport.js

@@ -0,0 +1,151 @@
+import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+import { normalizeCrudLookupContainerKey } from "@jskit-ai/resource-crud-core/shared/crudLookup";
+import { asPlainObject } from "../support/scopeHelpers.js";
+
+const LOOKUP_LABEL_COMPOSITION_CANDIDATES = Object.freeze([
+  Object.freeze(["name", "surname"]),
+  Object.freeze(["name", "lastName"]),
+  Object.freeze(["firstName", "surname"]),
+  Object.freeze(["firstName", "lastName"]),
+  Object.freeze(["name"]),
+  Object.freeze(["firstName"])
+]);
+const DEFAULT_RECORD_TITLE = "-";
+
+function hasDisplayValue(value) {
+  if (value == null) {
+    return false;
+  }
+  if (typeof value === "string") {
+    return normalizeText(value).length > 0;
+  }
+
+  return true;
+}
+
+function resolveComposedLabel(source = {}, candidates = LOOKUP_LABEL_COMPOSITION_CANDIDATES) {
+  for (const candidate of candidates) {
+    const parts = [];
+    for (const key of candidate) {
+      const part = normalizeText(source[key]);
+      if (!part) {
+        parts.length = 0;
+        break;
+      }
+      parts.push(part);
+    }
+    if (parts.length === candidate.length) {
+      return parts.join(" ");
+    }
+  }
+
+  return "";
+}
+
+function resolveLookupItemLabel(item = {}, labelKey = "") {
+  const source = asPlainObject(item);
+  const composedLabel = resolveComposedLabel(source);
+  if (composedLabel) {
+    return composedLabel;
+  }
+
+  const normalizedLabelKey = normalizeText(labelKey);
+  if (!normalizedLabelKey) {
+    return "";
+  }
+
+  return normalizeText(source[normalizedLabelKey]);
+}
+
+function resolveRecordTitle(record = {}, { fallbackKey = "", defaultValue = DEFAULT_RECORD_TITLE } = {}) {
+  const source = asPlainObject(record);
+  const composedLabel = resolveComposedLabel(source);
+  if (composedLabel) {
+    return composedLabel;
+  }
+
+  const normalizedFallbackKey = normalizeText(fallbackKey);
+  if (normalizedFallbackKey) {
+    const fallbackValue = normalizeText(source[normalizedFallbackKey]);
+    if (fallbackValue) {
+      return fallbackValue;
+    }
+  }
+
+  const normalizedDefaultValue = normalizeText(defaultValue);
+  return normalizedDefaultValue || DEFAULT_RECORD_TITLE;
+}
+
+function resolveLookupFieldDescriptor(field = {}, relationKind = "", valueKey = "", labelKey = "") {
+  if (typeof field === "string") {
+    return {
+      key: normalizeText(field),
+      relation: {
+        kind: normalizeText(relationKind).toLowerCase(),
+        valueKey: normalizeText(valueKey) || "id",
+        labelKey: normalizeText(labelKey),
+        containerKey: ""
+      }
+    };
+  }
+
+  const sourceField = asPlainObject(field);
+  const relation = asPlainObject(sourceField.relation);
+  return {
+    key: normalizeText(sourceField.key),
+    relation: {
+      kind: normalizeText(relation.kind).toLowerCase(),
+      valueKey: normalizeText(relation.valueKey) || "id",
+      labelKey: normalizeText(relation.labelKey),
+      containerKey: normalizeText(relation.containerKey)
+    }
+  };
+}
+
+function resolveFallbackLookupKey(key = "") {
+  const normalizedKey = normalizeText(key);
+  if (!normalizedKey.endsWith("Id") || normalizedKey.length <= 2) {
+    return "";
+  }
+
+  return normalizedKey.slice(0, -2);
+}
+
+function resolveLookupFieldDisplayValue(record = {}, field = {}, relationKind = "", valueKey = "", labelKey = "") {
+  const sourceRecord = asPlainObject(record);
+  const descriptor = resolveLookupFieldDescriptor(field, relationKind, valueKey, labelKey);
+  const key = descriptor.key;
+  if (!key) {
+    return "";
+  }
+
+  if (descriptor.relation.kind !== "lookup") {
+    return sourceRecord[key];
+  }
+
+  const lookupContainerKey = normalizeCrudLookupContainerKey(descriptor.relation.containerKey, {
+    context: `lookup relation "${key}" containerKey`
+  });
+  const sourceLookups = asPlainObject(sourceRecord[lookupContainerKey]);
+  let lookupRecord = asPlainObject(sourceLookups[key]);
+  if (Object.keys(lookupRecord).length < 1) {
+    lookupRecord = asPlainObject(sourceLookups[resolveFallbackLookupKey(key)]);
+  }
+  const lookupLabel = resolveLookupItemLabel(lookupRecord, descriptor.relation.labelKey);
+  if (lookupLabel) {
+    return lookupLabel;
+  }
+
+  const lookupValue = lookupRecord[descriptor.relation.valueKey];
+  if (hasDisplayValue(lookupValue)) {
+    return lookupValue;
+  }
+
+  return sourceRecord[key];
+}
+
+export {
+  resolveLookupItemLabel,
+  resolveLookupFieldDisplayValue,
+  resolveRecordTitle
+};