@gxp-dev/mod-ui 2.0.0

package/src/engine/CardRenderer.vue

@@ -0,0 +1,228 @@
+<script setup lang="ts">
+/**
+ * Renders a single DisplayCard by dispatching its JSON definition into
+ * the matching composition under `components/compositions/cards/`.
+ *
+ * The renderer is the bridge layer:
+ *   - resolves the composition by `card.cardType` via the registry
+ *   - evaluates the card's visibility (`shouldRender`)
+ *   - applies responsive layout + classList chrome at the wrapper level
+ *   - resolves ID-referenced child lists against the page-level
+ *     `elements` / `cards` maps:
+ *       - `card.elementList: string[]` → pass as `elements: CardElement[]`
+ *       - `card.cardList: string[]`    → pass as `cards: DisplayCard[]`
+ *       - `card.tabList: string[]`     → pass as `tabs: DisplayCard[]`
+ *       - `card.elementId: string`     → pass as `element: CardElement`
+ *   - strips schema-only keys (cardType, conditionParams, columns*, ...)
+ *     and passes the rest through as Vue props
+ *
+ * Compositions don't know about the page-level maps or the JSON schema —
+ * they receive resolved children + display props and emit normal Vue
+ * events. They're directly mountable in any app.
+ */
+import { computed } from "vue"
+import type { CardElement } from "@/definitions/elements"
+import type { DisplayCard } from "@/definitions/cards"
+import { cn } from "@/lib/utils"
+import { getCardComponent } from "./useCardLoader"
+import {
+  shouldRender,
+  type EvaluationContext,
+} from "./useDisplayConditions"
+
+interface Props {
+  card: DisplayCard
+  item?: Record<string, unknown>
+  /** Page-level element registry: id → CardElement JSON. */
+  elements?: Record<string, CardElement>
+  /** Page-level card registry: id → DisplayCard JSON (for nested cards). */
+  cards?: Record<string, DisplayCard>
+  evaluationContext?: EvaluationContext
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  item: () => ({}),
+  elements: () => ({}),
+  cards: () => ({}),
+  evaluationContext: () => ({}),
+})
+
+const visible = computed(() =>
+  shouldRender(props.card, props.item, props.evaluationContext),
+)
+
+const resolved = computed(() => getCardComponent(props.card.cardType))
+
+/**
+ * Keys that live on every DisplayCard and are NOT meant to flow
+ * through to the composition as props. These are either consumed by
+ * this renderer (`columns*`, `conditionParams`, `cardType`, ...) or
+ * resolved into their concrete child arrays below.
+ */
+const STRIPPED_KEYS = new Set<string>([
+  "cardType",
+  "conditionParams",
+  "conditionGroupLogic",
+  "condition",
+  "features",
+  "permissions",
+  "columns",
+  "columnsSm",
+  "columnsMd",
+  "columnsLg",
+  "columnsXl",
+  "columnsXxl",
+  "wrapperClassList",
+  "columnClassList",
+  "order",
+  // ID-referenced child lists — resolved below into concrete arrays.
+  "elementList",
+  "cardList",
+  "tabList",
+  "elementId",
+])
+
+/**
+ * Compute the props object to pass to the resolved composition.
+ *
+ * - Strips schema-only keys (`cardType`, `conditionParams`, ...).
+ * - Resolves `elementList` / `cardList` / `tabList` / `elementId` against
+ *   the page-level registries and exposes them as concrete arrays /
+ *   objects under composition-facing prop names.
+ * - Forwards `item` as-is for child renderers to use.
+ */
+const compositionProps = computed<Record<string, unknown>>(() => {
+  const c = props.card as unknown as Record<string, unknown>
+  const result: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(c)) {
+    if (!STRIPPED_KEYS.has(key)) {
+      result[key] = value
+    }
+  }
+
+  // Pass through the data model.
+  result.item = props.item
+
+  // Resolve `elementList: string[]` → `elements: CardElement[]`.
+  if (Array.isArray((c as { elementList?: unknown }).elementList)) {
+    const ids = (c as { elementList: string[] }).elementList
+    const out: CardElement[] = []
+    for (const id of ids) {
+      const el = props.elements[id]
+      if (el) {
+        out.push(el)
+      }
+    }
+    result.elements = out
+  }
+
+  // Resolve `cardList: string[]` → `cards: DisplayCard[]`.
+  if (Array.isArray((c as { cardList?: unknown }).cardList)) {
+    const ids = (c as { cardList: string[] }).cardList
+    const out: DisplayCard[] = []
+    for (const id of ids) {
+      const child = props.cards[id]
+      if (child) {
+        out.push(child)
+      }
+    }
+    result.cards = out
+  }
+
+  // Resolve `tabList: string[]` → `tabs: DisplayCard[]`.
+  if (Array.isArray((c as { tabList?: unknown }).tabList)) {
+    const ids = (c as { tabList: string[] }).tabList
+    const out: DisplayCard[] = []
+    for (const id of ids) {
+      const child = props.cards[id]
+      if (child) {
+        out.push(child)
+      }
+    }
+    result.tabs = out
+  }
+
+  // For GridViewCard: resolve element refs that appear inside
+  // `gridLayout[breakpoint][n].i` against the page-level elements
+  // map. Card refs at the same position already work because the
+  // composition resolves them against `cards` (resolved above).
+  // Elements need a separate `gridElements` array on the composition.
+  if (
+    props.card.cardType === "grid-view" &&
+    typeof (c as { gridLayout?: unknown }).gridLayout === "object" &&
+    (c as { gridLayout?: unknown }).gridLayout !== null
+  ) {
+    const layout = (c as { gridLayout: Record<string, unknown> }).gridLayout
+    const elementIds = new Set<string>()
+    for (const breakpoint of Object.values(layout)) {
+      if (Array.isArray(breakpoint)) {
+        for (const item of breakpoint) {
+          if (item && typeof item === "object" && "i" in item) {
+            const id = (item as { i: unknown }).i
+            if (typeof id === "string" && props.elements[id]) {
+              elementIds.add(id)
+            }
+          }
+        }
+      }
+    }
+    if (elementIds.size > 0) {
+      result.gridElements = Array.from(elementIds)
+        .map((id) => props.elements[id]!)
+        .filter(Boolean)
+    }
+  }
+
+  // Resolve `elementId: string` → `element: CardElement`.
+  const elementId = (c as { elementId?: unknown }).elementId
+  if (typeof elementId === "string" && elementId.length > 0) {
+    const el = props.elements[elementId]
+    if (el) {
+      result.element = el
+    }
+  }
+
+  return result
+})
+
+const wrapperClass = computed(() =>
+  cn(
+    "gxp-card",
+    `gxp-card--${props.card.cardType}`,
+    columnClass("col", props.card.columns),
+    columnClass("col-sm", props.card.columnsSm),
+    columnClass("col-md", props.card.columnsMd),
+    columnClass("col-lg", props.card.columnsLg),
+    columnClass("col-xl", props.card.columnsXl),
+    normalizeClasses(props.card.wrapperClassList),
+  ),
+)
+
+function columnClass(prefix: string, n?: number): string | undefined {
+  if (typeof n !== "number") {
+    return undefined
+  }
+  const pct = Math.max(0, Math.min(12, n)) / 12
+  return prefix === "col"
+    ? `basis-[${(pct * 100).toFixed(4)}%]`
+    : `${prefix}:basis-[${(pct * 100).toFixed(4)}%]`
+}
+
+function normalizeClasses(value: string | string[] | undefined): string {
+  if (!value) {
+    return ""
+  }
+  return Array.isArray(value) ? value.join(" ") : value
+}
+</script>
+
+<template>
+  <div
+    v-if="visible"
+    :class="wrapperClass"
+    :data-card-id="card.id"
+    :data-card-type="card.cardType"
+  >
+    <component :is="resolved" v-bind="compositionProps" />
+  </div>
+</template>

package/src/engine/ElementRenderer.vue

@@ -0,0 +1,174 @@
+<script setup lang="ts">
+/**
+ * Renders a single CardElement by dispatching its JSON definition into
+ * the matching composition under `components/compositions/elements/`.
+ *
+ * The renderer is the bridge layer:
+ *   - resolves the composition by `element.type` via the registry
+ *   - evaluates the element's visibility (`shouldRender`)
+ *   - applies responsive layout + classList chrome at the wrapper level
+ *   - binds `useFormData(element.name)` to the form-data store and
+ *     forwards `modelValue` + `errors` + the `@update:modelValue`
+ *     handler to the composition
+ *   - strips schema-only keys (type, conditionParams, columns*, ...)
+ *     and passes the rest through as Vue props
+ *
+ * Compositions don't know about the form-data store, the JSON schema,
+ * or this renderer's layout — they receive normal Vue props and emit
+ * `update:modelValue`. They're directly mountable in any app.
+ */
+import { computed } from "vue"
+import type { CardElement } from "@/definitions/elements"
+import { cn } from "@/lib/utils"
+import { getElementComponent } from "./useElementLoader"
+import {
+  shouldRender,
+  type EvaluationContext,
+} from "./useDisplayConditions"
+import { useFormData } from "./useFormData"
+import { applyLegacyRemaps } from "./legacyPropRemap"
+
+interface Props {
+  element: CardElement
+  item?: Record<string, unknown>
+  evaluationContext?: EvaluationContext
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  item: () => ({}),
+  evaluationContext: () => ({}),
+})
+
+const visible = computed(() =>
+  shouldRender(props.element, props.item, props.evaluationContext),
+)
+
+const resolved = computed(() => getElementComponent(props.element.type))
+
+const bindings = computed(() => useFormData(props.element.name ?? ""))
+
+/**
+ * Keys that live on every CardElement and are NOT meant to flow
+ * through to the composition as props. These are either consumed by
+ * this renderer (`columns*`, `conditionParams`, ...) or used only by
+ * the engine (`type`, `id` — well, `id` IS passed through, see below).
+ */
+const STRIPPED_KEYS = new Set<string>([
+  "type",
+  "conditionParams",
+  "conditionGroupLogic",
+  "condition",
+  "features",
+  "permissions",
+  "columns",
+  "columnsSm",
+  "columnsMd",
+  "columnsLg",
+  "columnsXl",
+  "columnsXxl",
+  "wrapperClassList",
+  "columnClassList",
+  "labelClassList",
+  "classList",
+  "previewMode",
+  "order",
+  "defaultValue",
+  "modelValue",
+])
+
+/**
+ * Compute the props object to pass to the resolved composition.
+ *
+ * - `modelValue` comes from the form-data store, falling back to
+ *   `item[element.name]`, then `element.defaultValue`. Compositions
+ *   declare `modelValue` and Vue picks it up.
+ * - `errors` comes from the form-data store.
+ * - All other element keys (label, placeholder, required, ...) are
+ *   passed through; Vue's prop validation silently drops anything the
+ *   composition doesn't declare.
+ */
+const compositionProps = computed<Record<string, unknown>>(() => {
+  const el = props.element as unknown as Record<string, unknown>
+  const result: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(el)) {
+    if (!STRIPPED_KEYS.has(key)) {
+      result[key] = value
+    }
+  }
+
+  // Resolve the effective modelValue.
+  const fieldName = props.element.name ?? ""
+  const storeValue = fieldName ? bindings.value.value.value : undefined
+  const itemValue = fieldName ? props.item[fieldName] : undefined
+  const defaultValue = (el as { defaultValue?: unknown }).defaultValue
+  if (storeValue !== undefined && storeValue !== null) {
+    result.modelValue = storeValue
+  } else if (itemValue !== undefined && itemValue !== null) {
+    result.modelValue = itemValue
+  } else if (defaultValue !== undefined && defaultValue !== null) {
+    result.modelValue = defaultValue
+  } else {
+    result.modelValue = ""
+  }
+
+  result.errors = bindings.value.errors.value
+
+  // Legacy JSON → new composition prop names + value aliases.
+  return applyLegacyRemaps(props.element.type, result)
+})
+
+function onUpdateModelValue(value: unknown): void {
+  if (!props.element.name) {
+    return
+  }
+  bindings.value.setValue(value)
+}
+
+const wrapperClass = computed(() =>
+  cn(
+    "gxp-element",
+    `gxp-element--${props.element.type.replace(/\./g, "-")}`,
+    columnClass("col", props.element.columns),
+    columnClass("col-sm", props.element.columnsSm),
+    columnClass("col-md", props.element.columnsMd),
+    columnClass("col-lg", props.element.columnsLg),
+    columnClass("col-xl", props.element.columnsXl),
+    normalizeClasses(props.element.columnClassList),
+    normalizeClasses(props.element.wrapperClassList),
+  ),
+)
+
+function columnClass(prefix: string, n?: number): string | undefined {
+  if (typeof n !== "number") {
+    return undefined
+  }
+  // 12-column grid — render width as a Tailwind percentage utility so
+  // we don't depend on Bootstrap's col-* classes.
+  const pct = Math.max(0, Math.min(12, n)) / 12
+  return prefix === "col"
+    ? `basis-[${(pct * 100).toFixed(4)}%]`
+    : `${prefix}:basis-[${(pct * 100).toFixed(4)}%]`
+}
+
+function normalizeClasses(value: string | string[] | undefined): string {
+  if (!value) {
+    return ""
+  }
+  return Array.isArray(value) ? value.join(" ") : value
+}
+</script>
+
+<template>
+  <div
+    v-if="visible"
+    :class="wrapperClass"
+    :data-element-id="element.id"
+    :data-element-type="element.type"
+  >
+    <component
+      :is="resolved"
+      v-bind="compositionProps"
+      @update:model-value="onUpdateModelValue"
+    />
+  </div>
+</template>

package/src/engine/__tests__/ElementRenderer.test.ts

@@ -0,0 +1,94 @@
+import { beforeEach, describe, expect, it } from "vitest"
+import { flushPromises, mount } from "@vue/test-utils"
+import { defineComponent, h, Suspense } from "vue"
+import { createPinia, setActivePinia } from "pinia"
+import type { InputElement } from "@/definitions/elements/InputElement"
+import ElementRenderer from "@/engine/ElementRenderer.vue"
+import { useFormDataStore } from "@/stores/formDataStore"
+import { __clearElementCache, preloadElement } from "@/engine/useElementLoader"
+
+/**
+ * Helper: mount ElementRenderer inside a <Suspense> boundary so the
+ * inner async component fully resolves before assertions. The
+ * preload in beforeEach ensures the dynamic-import promise is settled
+ * before the first render tick.
+ */
+function mountWithSuspense(props: Record<string, unknown>) {
+  const Host = defineComponent({
+    setup() {
+      return () =>
+        h(Suspense, null, {
+          default: () =>
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            h(ElementRenderer as any, props),
+        })
+    },
+  })
+  return mount(Host)
+}
+
+describe("ElementRenderer", () => {
+  beforeEach(async () => {
+    setActivePinia(createPinia())
+    __clearElementCache()
+    await preloadElement("input.text")
+  })
+
+  it("lazy-loads a text input and renders it", async () => {
+    const element: InputElement = {
+      id: "first-name",
+      type: "input.text",
+      name: "first_name",
+      label: "First name",
+    }
+    const wrapper = mountWithSuspense({ element })
+    await flushPromises()
+
+    expect(wrapper.text()).toContain("First name")
+    expect(wrapper.find("input").exists()).toBe(true)
+  })
+
+  it("writes input edits into the formDataStore", async () => {
+    const element: InputElement = {
+      id: "first-name",
+      type: "input.text",
+      name: "first_name",
+      label: "First name",
+    }
+    const wrapper = mountWithSuspense({ element })
+    await flushPromises()
+
+    await wrapper.find("input").setValue("Stephen")
+
+    const store = useFormDataStore()
+    expect(store.forms.default?.values.first_name).toBe("Stephen")
+    expect(store.forms.default?.touched.first_name).toBe(true)
+    expect(store.forms.default?.dirty).toBe(true)
+  })
+
+  it("hides the element when conditionParams fail", () => {
+    const element: InputElement = {
+      id: "admin-field",
+      type: "input.text",
+      name: "secret",
+      label: "Secret",
+      conditionParams: [{ name: "role", logic: "==", value: "admin" }],
+    }
+    const wrapper = mount(ElementRenderer, {
+      props: { element, item: { role: "user" } },
+    })
+    expect(wrapper.html()).toBe("<!--v-if-->")
+  })
+
+  it("renders the missing-renderer fallback for an unregistered style", async () => {
+    const element = {
+      id: "bogus",
+      type: "input.bogus-style",
+      name: "x",
+      label: "X",
+    } as unknown as InputElement
+    const wrapper = mountWithSuspense({ element })
+    await flushPromises()
+    expect(wrapper.find("[data-testid='missing-renderer']").exists()).toBe(true)
+  })
+})

package/src/engine/__tests__/legacyPropRemap.test.ts

@@ -0,0 +1,123 @@
+import { describe, expect, it } from "vitest"
+import { applyLegacyRemaps } from "@/engine/legacyPropRemap"
+
+describe("applyLegacyRemaps", () => {
+  describe("configuration-block prop renames", () => {
+    it("renames selectOptions → nestedElements", () => {
+      const result = applyLegacyRemaps("configuration-block.elements-block", {
+        selectOptions: [{ id: "a" }],
+        label: "Block",
+      })
+      expect(result.nestedElements).toEqual([{ id: "a" }])
+      expect(result.selectOptions).toBeUndefined()
+    })
+
+    it("renames triggerButtonLabel → triggerLabel", () => {
+      const result = applyLegacyRemaps("configuration-block.dialog", {
+        triggerButtonLabel: "Open",
+      })
+      expect(result.triggerLabel).toBe("Open")
+      expect(result.triggerButtonLabel).toBeUndefined()
+    })
+
+    it("renames dialogTitle / modalTitle → title", () => {
+      expect(
+        applyLegacyRemaps("configuration-block.dialog", {
+          dialogTitle: "X",
+        }).title,
+      ).toBe("X")
+      expect(
+        applyLegacyRemaps("configuration-block.modal", {
+          modalTitle: "Y",
+        }).title,
+      ).toBe("Y")
+    })
+
+    it("renames addOptionButtonLabel → addButtonLabel", () => {
+      const result = applyLegacyRemaps("configuration-block.repeatable", {
+        addOptionButtonLabel: "Add row",
+      })
+      expect(result.addButtonLabel).toBe("Add row")
+    })
+
+    it("does not overwrite a key the consumer already set in the new name", () => {
+      const result = applyLegacyRemaps("configuration-block.dialog", {
+        triggerLabel: "explicit",
+        triggerButtonLabel: "legacy",
+      })
+      expect(result.triggerLabel).toBe("explicit")
+    })
+  })
+
+  describe("action variant aliases", () => {
+    it.each([
+      ["primary", "default"],
+      ["danger", "destructive"],
+      ["outline-primary", "outline"],
+      ["outline-danger", "outline"],
+      ["btn-success", "success"],
+      ["light", "ghost"],
+      ["dark", "default"],
+    ])("aliases variant=%s → %s", (legacy, normalised) => {
+      const result = applyLegacyRemaps("action.button", { variant: legacy })
+      expect(result.variant).toBe(normalised)
+    })
+
+    it("passes unknown variants through unchanged", () => {
+      const result = applyLegacyRemaps("action.button", {
+        variant: "custom-thing",
+      })
+      expect(result.variant).toBe("custom-thing")
+    })
+
+    it("leaves non-string variant values alone", () => {
+      const result = applyLegacyRemaps("action.button", { variant: 42 })
+      expect(result.variant).toBe(42)
+    })
+  })
+
+  describe("display prop renames", () => {
+    it("renames icon → iconName", () => {
+      const result = applyLegacyRemaps("display.icon", { icon: "check" })
+      expect(result.iconName).toBe("check")
+      expect(result.icon).toBeUndefined()
+    })
+  })
+
+  describe("pass-through", () => {
+    it("returns a new object without changes for unknown categories", () => {
+      const input = { label: "x", required: true }
+      const result = applyLegacyRemaps("input.text", input)
+      // Same shape, but a different reference is acceptable.
+      expect(result).toEqual(input)
+    })
+
+    it("returns the input object reference when no remaps exist for the category", () => {
+      const input = { label: "x" }
+      const result = applyLegacyRemaps("input.text", input)
+      expect(result).toBe(input)
+    })
+
+    it("passes through props that don't match any remap key", () => {
+      const result = applyLegacyRemaps("configuration-block.dialog", {
+        label: "Title",
+        helpText: "Hint",
+      })
+      expect(result.label).toBe("Title")
+      expect(result.helpText).toBe("Hint")
+    })
+  })
+
+  describe("GridViewCard's gridLayout (legacy element refs)", () => {
+    it("passes the gridLayout through (resolution happens in CardRenderer)", () => {
+      // legacyPropRemap doesn't itself resolve grid layout element IDs —
+      // that lives in CardRenderer. This test documents that the remap
+      // doesn't accidentally strip the layout.
+      const layout = {
+        lg: [{ i: "el-1", x: 0, y: 0, w: 4, h: 4 }],
+      }
+      const result = applyLegacyRemaps("display.type", { gridLayout: layout })
+      expect(result.gridLayout).toBe(layout)
+    })
+  })
+})

package/src/engine/__tests__/registry.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, it } from "vitest"
+import {
+  cardRegistry,
+  elementDefaultStyle,
+  elementRegistry,
+  resolveCardPath,
+  resolveElementPath,
+} from "@/engine/registry"
+import { CardElementMetadataMap, DisplayCardMetadataMap } from "@/definitions"
+
+describe("elementRegistry", () => {
+  it("covers every ElementType from the metadata map", () => {
+    for (const key of Object.keys(CardElementMetadataMap)) {
+      expect(
+        (elementRegistry as unknown as Record<string, unknown>)[key],
+      ).toBeDefined()
+    }
+  })
+
+  it("declares a default style for every type", () => {
+    for (const key of Object.keys(CardElementMetadataMap)) {
+      expect(elementDefaultStyle[key as keyof typeof elementDefaultStyle]).toBeTruthy()
+    }
+  })
+})
+
+describe("resolveElementPath", () => {
+  it("returns the registered path for an exact (type, style) match", () => {
+    expect(resolveElementPath("input.text")).toBe("input/TextInput")
+    expect(resolveElementPath("display.image")).toBe("display/ImageDisplay")
+    expect(resolveElementPath("picker.date-picker")).toBe("picker/DatePicker")
+  })
+
+  it("falls back to the default style when style is omitted", () => {
+    expect(resolveElementPath("input")).toBe("input/TextInput")
+    expect(resolveElementPath("boolean")).toBe("boolean/CheckboxBoolean")
+  })
+
+  it("returns null for unknown type / style", () => {
+    expect(resolveElementPath("bogus")).toBeNull()
+    expect(resolveElementPath("input.bogus")).toBeNull()
+  })
+
+  it("accepts the `buttongroup` v2 alias", () => {
+    expect(resolveElementPath("action.buttongroup")).toBe(
+      "action/ButtonGroupAction",
+    )
+    expect(resolveElementPath("action.button-group")).toBe(
+      "action/ButtonGroupAction",
+    )
+  })
+})
+
+describe("cardRegistry", () => {
+  it("covers every cardType from the metadata map", () => {
+    for (const key of Object.keys(DisplayCardMetadataMap)) {
+      expect((cardRegistry as Record<string, unknown>)[key]).toBeDefined()
+    }
+  })
+})
+
+describe("resolveCardPath", () => {
+  it("returns the registered path", () => {
+    expect(resolveCardPath("element-list")).toBe("ElementListCard")
+    expect(resolveCardPath("datatable")).toBe("DataTableCard")
+  })
+
+  it("returns null for unknown cardType", () => {
+    expect(resolveCardPath("bogus")).toBeNull()
+  })
+})