@gxp-dev/mod-ui 2.0.0

package/package.json

@@ -0,0 +1,130 @@
+{
+  "name": "@gxp-dev/mod-ui",
+  "version": "2.0.0",
+  "description": "JSON-driven Vue 3 module UI component library for the GxP platform. Provides shadcn-vue primitives, a templating engine (IndexPage / ShowPage), card/element renderers, and a FormBuilder.",
+  "type": "module",
+  "packageManager": "pnpm@9.15.0",
+  "files": [
+    "dist",
+    "src",
+    ".storybook",
+    "tsconfig.json"
+  ],
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./styles": "./dist/styles/index.css",
+    "./styles/themes/*": "./dist/styles/themes/*"
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "lint": "eslint src --ext .ts,.vue",
+    "typecheck": "vue-tsc --noEmit",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:ui": "vitest --ui",
+    "storybook": "storybook dev -p 6006",
+    "storybook:build": "storybook build -o storybook-static && pnpm manifest",
+    "manifest": "node scripts/build-library-manifest.mjs",
+    "manifest:pretty": "node scripts/build-library-manifest.mjs --pretty",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "pinia": "^2.2.0 || ^3.0.0",
+    "reka-ui": "^2.8.0",
+    "vue": "^3.4.0"
+  },
+  "peerDependenciesMeta": {
+    "reka-ui": {
+      "optional": false
+    }
+  },
+  "dependencies": {
+    "@ericblade/quagga2": "^1.12.1",
+    "@fix-webm-duration/fix": "^1.0.1",
+    "@internationalized/date": "^3.12.1",
+    "@tiptap/starter-kit": "3.23.2",
+    "@tiptap/vue-3": "3.23.2",
+    "@types/leaflet": "1.9.21",
+    "@vee-validate/zod": "^4.15.1",
+    "@vueuse/core": "^14.2.0",
+    "axios": "^1.9.0",
+    "chart.js": "4.5.1",
+    "class-variance-authority": "^0.7.0",
+    "clsx": "^2.1.0",
+    "embla-carousel-vue": "8.6.0",
+    "jsbarcode": "^3.12.1",
+    "leaflet": "1.9.4",
+    "lucide-vue-next": "^0.344.0",
+    "qrcode": "^1.5.4",
+    "tailwind-merge": "^2.5.0",
+    "tw-animate-css": "^1.2.0",
+    "vee-validate": "^4.15.1",
+    "vue-chartjs": "5.3.3",
+    "vue-sonner": "^2.0.9",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@storybook/addon-a11y": "^9.1.20",
+    "@storybook/addon-docs": "^9.1.20",
+    "@storybook/addon-themes": "^9.1.20",
+    "@storybook/addon-vitest": "^9.1.20",
+    "@storybook/vue3": "^9.1.20",
+    "@storybook/vue3-vite": "^9.1.20",
+    "@tailwindcss/typography": "^0.5.19",
+    "@tailwindcss/vite": "^4.1.0",
+    "@types/node": "^22.0.0",
+    "@types/qrcode": "^1.5.6",
+    "@vitejs/plugin-vue": "^5.2.0",
+    "@vitest/coverage-v8": "^3.2.4",
+    "@vitest/ui": "^3.2.4",
+    "@vue/test-utils": "^2.4.6",
+    "eslint": "^9.0.0",
+    "eslint-plugin-storybook": "^10.1.4",
+    "jsdom": "^26.0.0",
+    "pinia": "^3.0.0",
+    "storybook": "^9.1.20",
+    "tailwindcss": "^4.1.0",
+    "typescript": "^5.6.0",
+    "vite": "^6.0.0",
+    "vite-plugin-dts": "^4.5.0",
+    "vitest": "^3.2.4",
+    "vue": "^3.5.0",
+    "vue-tsc": "^2.2.0"
+  },
+  "keywords": [
+    "vue",
+    "vue3",
+    "components",
+    "ui",
+    "shadcn",
+    "tailwind",
+    "tailwindcss",
+    "json-driven",
+    "form-builder",
+    "admin-ui",
+    "gxp"
+  ],
+  "author": "GxP Dev",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/GramercyTech/gx-adminkit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/gxp-dev/uikit/issues"
+  },
+  "homepage": "https://github.com/gxp-dev/uikit#readme",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/src/adapters/__tests__/showPageV1.test.ts

@@ -0,0 +1,179 @@
+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 ShowPage from "@/pages/ShowPage.vue"
+import { __clearElementCache, preloadElement } from "@/engine/useElementLoader"
+import { __clearCardCache, preloadCard } from "@/engine/useCardLoader"
+import { __resetIdCounter } from "@/adapters"
+
+/**
+ * End-to-end smoke: feed ShowPage a config in the legacy v1 shape and
+ * assert that it renders correctly, exercising:
+ *   - v1 detection at the boundary (no schemaVersion: "v1" hint)
+ *   - card type translation (fields_list → element-list)
+ *   - field type translation (text → input/text, select → option-select/select)
+ *   - column key translation (colsMd → columnsMd)
+ *   - condition param translation (field/operator → name/logic)
+ */
+function mountInSuspense(component: unknown, props: Record<string, unknown>) {
+  const Host = defineComponent({
+    setup() {
+      return () =>
+        h(Suspense, null, {
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          default: () => h(component as any, props),
+        })
+    },
+  })
+  return mount(Host)
+}
+
+describe("ShowPage with v1 JSON config", () => {
+  beforeEach(async () => {
+    setActivePinia(createPinia())
+    __clearElementCache()
+    __clearCardCache()
+    __resetIdCounter()
+    await preloadCard("element-list")
+    await preloadElement("input.text")
+    await preloadElement("option-select.select")
+  })
+
+  it("renders a fields_list with v1 field types into the engine", async () => {
+    const v1Config = {
+      title: "Profile",
+      tabsList: [
+        {
+          title: "Details",
+          tabId: "details",
+          cards: [
+            {
+              type: "fields_list",
+              title: "Personal information",
+              fieldsList: [
+                {
+                  type: "text",
+                  name: "first_name",
+                  label: "First name",
+                  required: true,
+                  cols: 12,
+                  colsMd: 6,
+                },
+                {
+                  type: "text",
+                  name: "last_name",
+                  label: "Last name",
+                  colsMd: 6,
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    }
+
+    const wrapper = mountInSuspense(ShowPage, {
+      config: v1Config,
+      item: { first_name: "Stephen", last_name: "Peek" },
+    })
+    await flushPromises()
+    await flushPromises()
+
+    expect(wrapper.text()).toContain("Profile")
+    expect(wrapper.text()).toContain("First name")
+    expect(wrapper.text()).toContain("Last name")
+    expect(wrapper.text()).toContain("Personal information")
+    expect(wrapper.findAll("input").length).toBeGreaterThanOrEqual(2)
+  })
+
+  it("translates v1 conditionParams (field/operator) to v2 logic", async () => {
+    const v1Config = {
+      title: "Conditional",
+      tabsList: [
+        {
+          title: "Tab",
+          tabId: "t",
+          cards: [
+            {
+              type: "fields_list",
+              fieldsList: [
+                {
+                  type: "text",
+                  name: "always_visible",
+                  label: "Always",
+                },
+                {
+                  type: "text",
+                  name: "admin_only",
+                  label: "Admin only",
+                  conditionParams: [
+                    { field: "role", operator: "equals", value: "admin" },
+                  ],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    }
+
+    const userWrapper = mountInSuspense(ShowPage, {
+      config: v1Config,
+      item: { role: "user" },
+    })
+    await flushPromises()
+    await flushPromises()
+    expect(userWrapper.text()).toContain("Always")
+    expect(userWrapper.text()).not.toContain("Admin only")
+
+    const adminWrapper = mountInSuspense(ShowPage, {
+      config: v1Config,
+      item: { role: "admin" },
+    })
+    await flushPromises()
+    await flushPromises()
+    expect(adminWrapper.text()).toContain("Always")
+    expect(adminWrapper.text()).toContain("Admin only")
+  })
+
+  it("accepts a v2 config unchanged (no adapter applied)", async () => {
+    const v2Config = {
+      title: "Profile",
+      tabsList: [
+        {
+          title: "Details",
+          tabId: "details",
+          cards: [
+            {
+              id: "card-1",
+              cardType: "element-list",
+              title: "Personal information",
+              elementList: ["el-1"],
+            },
+          ],
+        },
+      ],
+      cards: {
+        "card-1": {
+          id: "card-1",
+          cardType: "element-list",
+          title: "Personal information",
+          elementList: ["el-1"],
+        },
+      },
+      elements: {
+        "el-1": {
+          id: "el-1",
+          type: "input.text",
+          name: "first_name",
+          label: "First name",
+        },
+      },
+    }
+    const wrapper = mountInSuspense(ShowPage, { config: v2Config, item: {} })
+    await flushPromises()
+    await flushPromises()
+    expect(wrapper.text()).toContain("First name")
+  })
+})

package/src/adapters/__tests__/v1ToV2.test.ts

@@ -0,0 +1,352 @@
+import { beforeEach, describe, expect, it } from "vitest"
+import {
+  v1ToV2,
+  v2ToV1,
+  __resetIdCounter,
+  v1ConditionParamToV2,
+  v2ConditionParamToV1,
+  v1ColumnsToV2,
+  v2ColumnsToV1,
+} from "@/adapters"
+import type { V1PageConfig } from "@/adapters"
+
+beforeEach(() => {
+  __resetIdCounter()
+})
+
+describe("v1ConditionParamToV2", () => {
+  it("renames field→name and operator→logic", () => {
+    expect(
+      v1ConditionParamToV2({ field: "role", operator: "equals", value: "admin" }),
+    ).toEqual({ name: "role", logic: "==", value: "admin" })
+  })
+
+  it("maps common operator aliases", () => {
+    expect(
+      v1ConditionParamToV2({ field: "n", operator: "gt", value: 0 }),
+    ).toEqual({ name: "n", logic: ">", value: 0 })
+    expect(
+      v1ConditionParamToV2({ field: "tags", operator: "in", value: ["a"] }),
+    ).toEqual({ name: "tags", logic: "in-array", value: ["a"] })
+  })
+
+  it("passes unknown operators through unchanged", () => {
+    expect(
+      v1ConditionParamToV2({ field: "x", operator: "fuzzy", value: 1 }),
+    ).toEqual({ name: "x", logic: "fuzzy", value: 1 })
+  })
+
+  it("round-trips with v2→v1", () => {
+    const v1 = { field: "status", operator: "starts_with", value: "act" }
+    expect(v2ConditionParamToV1(v1ConditionParamToV2(v1))).toEqual(v1)
+  })
+})
+
+describe("v1ColumnsToV2 / v2ColumnsToV1", () => {
+  it("renames cols/colsSm/... → columns/columnsSm/...", () => {
+    expect(v1ColumnsToV2({ cols: 12, colsMd: 6, colsLg: 4 })).toEqual({
+      columns: 12,
+      columnsMd: 6,
+      columnsLg: 4,
+    })
+  })
+
+  it("round-trips", () => {
+    const v1 = { cols: 12, colsSm: 12, colsMd: 6, colsLg: 4, colsXl: 3 }
+    expect(v2ColumnsToV1(v1ColumnsToV2(v1))).toEqual(v1)
+  })
+
+  it("ignores unset keys", () => {
+    expect(v1ColumnsToV2({})).toEqual({})
+    expect(v2ColumnsToV1({})).toEqual({})
+  })
+})
+
+describe("v1ToV2 — fields_list with mixed elements", () => {
+  it("converts a fields_list card into element-list + element entries", () => {
+    const v1: V1PageConfig = {
+      title: "User Profile",
+      tabsList: [
+        {
+          title: "Profile",
+          tabId: "profile",
+          cards: [
+            {
+              type: "fields_list",
+              title: "Basic Info",
+              fieldsList: [
+                {
+                  type: "text",
+                  name: "name",
+                  label: "Full Name",
+                  required: true,
+                  cols: 12,
+                  colsMd: 6,
+                },
+                {
+                  type: "email",
+                  name: "email",
+                  label: "Email",
+                  colsMd: 6,
+                },
+                {
+                  type: "select",
+                  name: "role",
+                  label: "Role",
+                  options: [
+                    { value: "user", text: "User" },
+                    { value: "admin", text: "Administrator" },
+                  ],
+                  colsMd: 4,
+                },
+                {
+                  type: "checkbox",
+                  name: "is_active",
+                  label: "Active",
+                  default: true,
+                },
+                {
+                  type: "date",
+                  name: "start_date",
+                  label: "Start Date",
+                  colsMd: 6,
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    }
+
+    const v2 = v1ToV2(v1)
+
+    expect(v2.title).toBe("User Profile")
+    expect(v2.tabsList).toHaveLength(1)
+    expect(v2.tabsList?.[0]?.tabId).toBe("profile")
+    expect(v2.tabsList?.[0]?.cards).toHaveLength(1)
+
+    const card = v2.tabsList?.[0]?.cards[0]!
+    expect(card.cardType).toBe("element-list")
+    expect(card.title).toBe("Basic Info")
+
+    const elementIds = (card as unknown as { elementList: string[] }).elementList
+    expect(elementIds).toHaveLength(5)
+
+    const name = v2.elements[elementIds[0]!]!
+    expect(name.type).toBe("input.text")
+    expect(name.label).toBe("Full Name")
+    expect(name.required).toBe(true)
+    expect(name.columns).toBe(12)
+    expect(name.columnsMd).toBe(6)
+
+    const email = v2.elements[elementIds[1]!]!
+    expect(email.type).toBe("input.email")
+
+    const role = v2.elements[elementIds[2]!]!
+    expect(role.type).toBe("option-select.select")
+    expect((role as unknown as Record<string, unknown>).selectOptions).toEqual([
+      { value: "user", text: "User", label: "User" },
+      { value: "admin", text: "Administrator", label: "Administrator" },
+    ])
+
+    const checkbox = v2.elements[elementIds[3]!]!
+    expect(checkbox.type).toBe("boolean.checkbox")
+    expect(checkbox.defaultValue).toBe(true)
+
+    const date = v2.elements[elementIds[4]!]!
+    expect(date.type).toBe("picker.date-picker")
+  })
+})
+
+describe("v1ToV2 — data_table card", () => {
+  it("preserves headers, options, listKey, and createConfig", () => {
+    const v1: V1PageConfig = {
+      title: "Users",
+      cards: [
+        {
+          type: "data_table",
+          tableTitle: "All Users",
+          listKey: "items",
+          headers: [
+            { text: "Name", value: "name", sortable: true },
+            { text: "Email", value: "email" },
+          ],
+          options: { paginated: true, perPage: 25 },
+          createConfig: { create: { route: "users.store" } },
+        },
+      ],
+    }
+    const v2 = v1ToV2(v1)
+    const card = Object.values(v2.cards)[0]!
+    expect(card.cardType).toBe("datatable")
+    expect((card as unknown as Record<string, unknown>).tableTitle).toBe("All Users")
+    expect((card as unknown as Record<string, unknown>).listKey).toBe("items")
+    expect((card as unknown as Record<string, unknown>).headers).toHaveLength(2)
+    expect((card as unknown as Record<string, unknown>).options).toEqual({
+      paginated: true,
+      perPage: 25,
+    })
+  })
+})
+
+describe("v1ToV2 — IndexPage shorthand", () => {
+  it("synthesises a datatable card when top-level headers + options are present", () => {
+    const v1: V1PageConfig = {
+      title: "Users",
+      breadCrumbs: [{ title: "Admin" }],
+      headers: [{ text: "Name", value: "name", sortable: true }],
+      options: { paginated: true, perPage: 25 },
+      listKey: "items",
+      createConfig: { create: { route: "users.store" } },
+    }
+    const v2 = v1ToV2(v1)
+    expect(v2.title).toBe("Users")
+    expect(v2.breadCrumbs).toEqual([{ title: "Admin" }])
+    expect(v2.createConfig).toBeDefined()
+    const cards = Object.values(v2.cards)
+    expect(cards).toHaveLength(1)
+    expect(cards[0]!.cardType).toBe("datatable")
+    expect((cards[0] as unknown as Record<string, unknown>).tableTitle).toBe(
+      "Users",
+    )
+  })
+})
+
+describe("v1ToV2 — button_group is wrapped as an element-list", () => {
+  it("emits a one-element element-list card with an action/button-group element inside", () => {
+    const v1: V1PageConfig = {
+      cards: [
+        {
+          type: "button_group",
+          buttons: [
+            { type: "button", text: "Save", color: "primary" },
+            { type: "button", text: "Cancel" },
+          ],
+        },
+      ],
+    }
+    const v2 = v1ToV2(v1)
+    const cards = Object.values(v2.cards)
+    expect(cards).toHaveLength(1)
+    expect(cards[0]!.cardType).toBe("element-list")
+
+    const elementId = (cards[0] as unknown as { elementList: string[] })
+      .elementList[0]!
+    const element = v2.elements[elementId]!
+    expect(element.type).toBe("action.button-group")
+  })
+})
+
+describe("v1ToV2 — card_list with nested fields_list", () => {
+  it("flattens nested cards into the v2 cards map and references them by id", () => {
+    const v1: V1PageConfig = {
+      cards: [
+        {
+          type: "card_list",
+          cards: [
+            {
+              type: "fields_list",
+              title: "Card A",
+              fieldsList: [{ type: "text", name: "a", label: "A" }],
+            },
+            {
+              type: "fields_list",
+              title: "Card B",
+              fieldsList: [{ type: "text", name: "b", label: "B" }],
+            },
+          ],
+        },
+      ],
+    }
+    const v2 = v1ToV2(v1)
+    const root = Object.values(v2.cards).find(
+      (c) => c.cardType === "card-list",
+    )!
+    expect(root).toBeDefined()
+    const cardList = (root as unknown as { cardList: string[] }).cardList
+    expect(cardList).toHaveLength(2)
+    for (const id of cardList) {
+      const child = v2.cards[id]!
+      expect(child.cardType).toBe("element-list")
+    }
+  })
+})
+
+describe("v1ToV2 — conditionParams translation", () => {
+  it("translates a field's conditionParams from v1 shape to v2", () => {
+    const v1: V1PageConfig = {
+      cards: [
+        {
+          type: "fields_list",
+          fieldsList: [
+            {
+              type: "text",
+              name: "secret",
+              label: "Secret",
+              conditionParams: [
+                { field: "role", operator: "equals", value: "admin" },
+              ],
+            },
+          ],
+        },
+      ],
+    }
+    const v2 = v1ToV2(v1)
+    const element = Object.values(v2.elements)[0]!
+    expect(element.conditionParams).toEqual([
+      { name: "role", logic: "==", value: "admin" },
+    ])
+  })
+})
+
+describe("v2ToV1 — round-trip", () => {
+  it("renders a fields_list / element-list pair losslessly enough for re-conversion", () => {
+    const original: V1PageConfig = {
+      title: "Round-Trip Test",
+      tabsList: [
+        {
+          title: "Tab A",
+          tabId: "a",
+          cards: [
+            {
+              type: "fields_list",
+              title: "Form",
+              fieldsList: [
+                {
+                  type: "text",
+                  name: "first_name",
+                  label: "First name",
+                  required: true,
+                },
+                {
+                  type: "select",
+                  name: "country",
+                  label: "Country",
+                  options: [
+                    { value: "us", text: "United States" },
+                    { value: "uk", text: "United Kingdom" },
+                  ],
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    }
+    const v2 = v1ToV2(original)
+    const back = v2ToV1(v2)
+    expect(back.title).toBe("Round-Trip Test")
+    expect(back.tabsList?.[0]?.title).toBe("Tab A")
+    const card = back.tabsList?.[0]?.cards?.[0]!
+    expect(card.type).toBe("fields_list")
+    expect(card.fieldsList).toHaveLength(2)
+    expect(card.fieldsList?.[0]?.type).toBe("text")
+    expect(card.fieldsList?.[0]?.required).toBe(true)
+    expect(card.fieldsList?.[1]?.type).toBe("select")
+    // options.text preserved for v1 consumers.
+    const opts = card.fieldsList?.[1]?.options as unknown as Array<
+      Record<string, unknown>
+    >
+    expect(opts[0]?.text).toBe("United States")
+  })
+})