@gxp-dev/mod-ui 2.0.0

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

@@ -0,0 +1,166 @@
+import { describe, expect, it } from "vitest"
+import type { Conditional } from "@/definitions/shared/conditions"
+import { shouldRender, __conditionsTesting } from "@/engine"
+
+const { applyLogic, readPath, lengthOf, toNumber } = __conditionsTesting
+
+describe("shouldRender", () => {
+  it("returns true when cfg is undefined", () => {
+    expect(shouldRender(undefined, {})).toBe(true)
+  })
+
+  it("short-circuits on a `condition` function", () => {
+    const cfg: Conditional = { condition: (item) => item.value === 42 }
+    expect(shouldRender(cfg, { value: 42 })).toBe(true)
+    expect(shouldRender(cfg, { value: 1 })).toBe(false)
+  })
+
+  it("gates on features", () => {
+    const cfg: Conditional = { features: ["beta"] }
+    expect(shouldRender(cfg, {}, { availableFeatures: ["beta"] })).toBe(true)
+    expect(shouldRender(cfg, {}, { availableFeatures: [] })).toBe(false)
+  })
+
+  it("gates on permissions", () => {
+    const cfg: Conditional = { permissions: ["admin"] }
+    expect(
+      shouldRender(cfg, {}, { availablePermissions: ["admin"] }),
+    ).toBe(true)
+    expect(shouldRender(cfg, {}, { availablePermissions: ["user"] })).toBe(
+      false,
+    )
+  })
+
+  it("AND-combines conditionParams by default", () => {
+    const cfg: Conditional = {
+      conditionParams: [
+        { name: "status", logic: "==", value: "active" },
+        { name: "score", logic: ">", value: 10 },
+      ],
+    }
+    expect(shouldRender(cfg, { status: "active", score: 20 })).toBe(true)
+    expect(shouldRender(cfg, { status: "active", score: 5 })).toBe(false)
+    expect(shouldRender(cfg, { status: "draft", score: 20 })).toBe(false)
+  })
+
+  it("ORs when conditionGroupLogic is OR", () => {
+    const cfg: Conditional = {
+      conditionGroupLogic: "OR",
+      conditionParams: [
+        { name: "status", logic: "==", value: "active" },
+        { name: "score", logic: ">", value: 10 },
+      ],
+    }
+    expect(shouldRender(cfg, { status: "active", score: 5 })).toBe(true)
+    expect(shouldRender(cfg, { status: "draft", score: 20 })).toBe(true)
+    expect(shouldRender(cfg, { status: "draft", score: 5 })).toBe(false)
+  })
+
+  it("supports nested groups via subCondition", () => {
+    const cfg: Conditional = {
+      conditionGroupLogic: "AND",
+      conditionParams: [
+        { name: "status", logic: "==", value: "active" },
+        {
+          name: "_group",
+          logic: "==",
+          subCondition: true,
+          conditionGroupLogic: "OR",
+          conditionParams: [
+            { name: "role", logic: "==", value: "admin" },
+            { name: "tier", logic: ">=", value: 3 },
+          ],
+        },
+      ],
+    }
+    expect(shouldRender(cfg, { status: "active", role: "admin", tier: 1 })).toBe(true)
+    expect(shouldRender(cfg, { status: "active", role: "user", tier: 3 })).toBe(true)
+    expect(shouldRender(cfg, { status: "active", role: "user", tier: 1 })).toBe(false)
+    expect(shouldRender(cfg, { status: "draft", role: "admin", tier: 3 })).toBe(false)
+  })
+
+  it("supports nested-path lookups", () => {
+    const cfg: Conditional = {
+      conditionParams: [{ name: "user.role", logic: "==", value: "admin" }],
+    }
+    expect(shouldRender(cfg, { user: { role: "admin" } })).toBe(true)
+    expect(shouldRender(cfg, { user: { role: "user" } })).toBe(false)
+  })
+
+  it("resolves model-typed values from the data path", () => {
+    const cfg: Conditional = {
+      conditionParams: [
+        { name: "owner_id", logic: "==", valueType: "model", value: "current_user.id" },
+      ],
+    }
+    expect(
+      shouldRender(cfg, { owner_id: 7, current_user: { id: 7 } }),
+    ).toBe(true)
+    expect(
+      shouldRender(cfg, { owner_id: 7, current_user: { id: 99 } }),
+    ).toBe(false)
+  })
+})
+
+describe("applyLogic operators", () => {
+  it("handles arithmetic comparisons", () => {
+    expect(applyLogic(">", 5, 3)).toBe(true)
+    expect(applyLogic(">=", 5, 5)).toBe(true)
+    expect(applyLogic("<", 5, 3)).toBe(false)
+    expect(applyLogic("<=", 5, 5)).toBe(true)
+  })
+
+  it("handles array containment", () => {
+    expect(applyLogic("in-array", "x", ["x", "y"])).toBe(true)
+    expect(applyLogic("not-in-array", "x", ["y", "z"])).toBe(true)
+  })
+
+  it("handles string matchers", () => {
+    expect(applyLogic("starts-with", "hello", "he")).toBe(true)
+    expect(applyLogic("ends-with", "hello", "lo")).toBe(true)
+    expect(applyLogic("contains", "hello world", "lo w")).toBe(true)
+    expect(applyLogic("matches", "abc123", "^abc")).toBe(true)
+    expect(applyLogic("matches", "abc", "[")).toBe(false) // invalid regex => false
+  })
+
+  it("handles parity + nullability", () => {
+    expect(applyLogic("is-odd", 3, null)).toBe(true)
+    expect(applyLogic("is-even", 4, null)).toBe(true)
+    expect(applyLogic("is-truthy", "x", null)).toBe(true)
+    expect(applyLogic("is-falsy", "", null)).toBe(true)
+    expect(applyLogic("is-null", null, null)).toBe(true)
+    expect(applyLogic("is-not-null", "x", null)).toBe(true)
+  })
+
+  it("handles length-based logic", () => {
+    expect(applyLogic("g0length", "abc", null)).toBe(true)
+    expect(applyLogic("zero-length", "", null)).toBe(true)
+    expect(applyLogic("length-gt-value", [1, 2, 3], 2)).toBe(true)
+    expect(applyLogic("length-lt-value", [1], 2)).toBe(true)
+    expect(applyLogic("length-eq-value", [1, 2], 2)).toBe(true)
+  })
+})
+
+describe("helpers", () => {
+  it("readPath traverses dot paths", () => {
+    expect(readPath({ a: { b: { c: 1 } } }, "a.b.c")).toBe(1)
+    expect(readPath({ a: 1 }, "missing")).toBeUndefined()
+    expect(readPath({}, "")).toBeUndefined()
+  })
+
+  it("lengthOf handles strings, arrays, and objects", () => {
+    expect(lengthOf("abc")).toBe(3)
+    expect(lengthOf([1, 2])).toBe(2)
+    expect(lengthOf({ a: 1, b: 2 })).toBe(2)
+    expect(lengthOf(null)).toBe(0)
+    expect(lengthOf(undefined)).toBe(0)
+    expect(lengthOf(42)).toBe(0)
+  })
+
+  it("toNumber coerces strings and ignores garbage", () => {
+    expect(toNumber("12")).toBe(12)
+    expect(toNumber(7)).toBe(7)
+    expect(toNumber("")).toBeNaN()
+    expect(toNumber("abc")).toBeNaN()
+  })
+})

package/src/engine/index.ts

@@ -0,0 +1,51 @@
+/**
+ * Engine — the runtime layer that turns JSON definitions into rendered
+ * Vue trees. Consumers typically use `IndexPage` / `ShowPage` rather
+ * than these low-level pieces directly.
+ *
+ * Public surface:
+ *   - `ElementRenderer`, `CardRenderer`         : the <component :is> wrappers
+ *   - `getElementComponent`, `getCardComponent` : lower-level resolvers
+ *   - `preloadElement`, `preloadCard`           : eager chunk preload helpers
+ *   - `shouldRender`                            : condition evaluator
+ *   - `useFormData`, `provideFormId`            : form-state binding
+ *   - registry constants for advanced use cases
+ */
+export { default as ElementRenderer } from "./ElementRenderer.vue"
+export { default as CardRenderer } from "./CardRenderer.vue"
+
+export {
+  getElementComponent,
+  preloadElement,
+  __clearElementCache,
+} from "./useElementLoader"
+
+export {
+  getCardComponent,
+  preloadCard,
+  __clearCardCache,
+} from "./useCardLoader"
+
+export {
+  shouldRender,
+  type EvaluationContext,
+  __testing as __conditionsTesting,
+} from "./useDisplayConditions"
+
+export {
+  useFormData,
+  provideFormId,
+  FORM_ID_KEY,
+  type UseFormDataBindings,
+} from "./useFormData"
+
+export {
+  cardRegistry,
+  elementDefaultStyle,
+  elementRegistry,
+  resolveCardPath,
+  resolveElementPath,
+  type CardPath,
+  type ElementPath,
+  type ElementRegistry,
+} from "./registry"

package/src/engine/legacyPropRemap.ts

@@ -0,0 +1,100 @@
+/**
+ * Legacy-JSON → composition-prop remapping.
+ *
+ * The composition layer was refactored to use shadcn-style normalised
+ * prop names, but plenty of JSON in the wild still uses the old v2
+ * names (`triggerButtonLabel` instead of `triggerLabel`, GxP variant
+ * aliases like `"primary"` instead of `"default"`, etc).
+ *
+ * This module is consulted by `ElementRenderer` after stripping
+ * schema-only keys and before spreading the result onto the resolved
+ * composition. It's a thin compatibility layer — every entry here is
+ * a known legacy form. Renderers themselves stay schema-agnostic.
+ *
+ * Adding a new alias:
+ *   - For a prop-name rename, add to `PROP_RENAMES[<category>]`.
+ *   - For a value-only alias (e.g. variant strings), add to
+ *     `VALUE_ALIASES[<category>].<prop>`.
+ */
+
+/**
+ * Per-category prop-name renames. The string on the left is the legacy
+ * JSON key; the string on the right is the new composition prop name.
+ *
+ * Matched against the element's category prefix (`element.type` split
+ * at the dot). `*` is a wildcard that applies to every element.
+ */
+export const PROP_RENAMES: Record<string, Record<string, string>> = {
+  "configuration-block": {
+    selectOptions: "nestedElements",
+    triggerButtonLabel: "triggerLabel",
+    dialogTitle: "title",
+    modalTitle: "title",
+    addOptionButtonLabel: "addButtonLabel",
+  },
+  display: {
+    icon: "iconName",
+  },
+}
+
+/**
+ * Per-(category, prop) value aliases. Used when a prop's accepted value
+ * union changed and we want legacy JSON to still resolve. Lookups are
+ * case-sensitive; unknown values pass through untouched.
+ */
+export const VALUE_ALIASES: Record<string, Record<string, Record<string, string>>> = {
+  action: {
+    variant: {
+      primary: "default",
+      danger: "destructive",
+      "outline-primary": "outline",
+      "outline-danger": "outline",
+      "outline-secondary": "outline",
+      "btn-success": "success",
+      "btn-warning": "warning",
+      "btn-info": "info",
+      light: "ghost",
+      dark: "default",
+    },
+  },
+  boolean: {
+    variant: {
+      // Boolean controls don't have variant aliases yet — reserved.
+    },
+  },
+}
+
+/**
+ * Apply prop renames + value aliases for an element. Returns a NEW
+ * object — never mutates input. Pass the result through `v-bind`.
+ */
+export function applyLegacyRemaps(
+  type: string,
+  props: Record<string, unknown>,
+): Record<string, unknown> {
+  const dot = type.indexOf(".")
+  const category = dot < 0 ? type : type.slice(0, dot)
+  const renames = PROP_RENAMES[category]
+  const aliases = VALUE_ALIASES[category]
+  if (!renames && !aliases) {
+    return props
+  }
+
+  const out: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(props)) {
+    const renamedKey = renames?.[key] ?? key
+    // Don't overwrite a key the consumer already provided in the new name.
+    if (renamedKey !== key && renamedKey in props) {
+      continue
+    }
+    const aliasMap = aliases?.[renamedKey]
+    const aliased =
+      typeof value === "string" && aliasMap && aliasMap[value] !== undefined
+        ? aliasMap[value]
+        : value
+    out[renamedKey] = aliased
+  }
+  return out
+}
+
+export const __testing = { PROP_RENAMES, VALUE_ALIASES }

package/src/engine/registry.ts

@@ -0,0 +1,249 @@
+/**
+ * Static registry mapping the JSON discriminators (`type` + `style`,
+ * or `cardType`) to a relative path under `src/elements/` or
+ * `src/cards/`. The path is what `import.meta.glob` uses to resolve a
+ * lazy component loader at build time.
+ *
+ * Adding a new element style:
+ *   1. Add it to the element's `Style` union in `definitions/elements/`.
+ *   2. Add the matching path here.
+ *   3. Create the Vue file at `src/elements/<path>.vue`.
+ *
+ * The registry is dense and exhaustive on purpose: TypeScript will fail
+ * to compile if a style enum value is missing from the map, which keeps
+ * the JSON contract and the runtime renderers in lock-step.
+ */
+import type { CardType, ElementCategory } from "@/definitions/shared/base"
+import type { ActionStyle } from "@/definitions/elements/ActionElement"
+import type { BooleanStyle } from "@/definitions/elements/BooleanElement"
+import type { BuilderStyle } from "@/definitions/elements/BuilderElement"
+import type { CardStyle } from "@/definitions/elements/CardLayoutElement"
+import type { CodeStyle } from "@/definitions/elements/CodeElement"
+import type { ComponentsStyle } from "@/definitions/elements/ComponentsElement"
+import type { ConfigurationBlockStyle } from "@/definitions/elements/ConfigurationBlockElement"
+import type { DisplayStyle } from "@/definitions/elements/DisplayElement"
+import type { EditorStyle } from "@/definitions/elements/EditorElement"
+import type { FileStyle } from "@/definitions/elements/FileElement"
+import type { InputStyle } from "@/definitions/elements/InputElement"
+import type { OptionSelectStyle } from "@/definitions/elements/OptionSelectElement"
+import type { PickerStyle } from "@/definitions/elements/PickerElement"
+
+/**
+ * A path under `src/elements/`, without the `./` prefix or the `.vue`
+ * extension. e.g. `"input/TextInput"` resolves to
+ * `src/elements/input/TextInput.vue`.
+ */
+export type ElementPath = string
+
+/**
+ * A path under `src/cards/`. e.g. `"ElementListCard"` resolves to
+ * `src/cards/ElementListCard.vue`.
+ */
+export type CardPath = string
+
+/**
+ * Per-type map of style → path. Each top-level key is an ElementType;
+ * the inner object covers every style variant for that type.
+ *
+ * Using `Record<Style, ElementPath>` here means TS errors if a new
+ * style is added to the definitions but not given a renderer path.
+ */
+export interface ElementRegistry {
+  action: Record<ActionStyle, ElementPath>
+  boolean: Record<BooleanStyle, ElementPath>
+  builder: Record<BuilderStyle, ElementPath>
+  card: Record<CardStyle, ElementPath>
+  code: Record<CodeStyle, ElementPath>
+  components: Record<ComponentsStyle, ElementPath>
+  "configuration-block": Record<ConfigurationBlockStyle, ElementPath>
+  display: Record<DisplayStyle, ElementPath>
+  editor: Record<EditorStyle, ElementPath>
+  file: Record<FileStyle, ElementPath>
+  input: Record<InputStyle, ElementPath>
+  "option-select": Record<OptionSelectStyle, ElementPath>
+  picker: Record<PickerStyle, ElementPath>
+}
+
+export const elementRegistry: ElementRegistry = {
+  card: {
+    list: "card/ListCard",
+    tab: "card/TabCard",
+    datatable: "card/DatatableCard",
+    grid: "card/GridCard",
+    info: "card/InfoCard",
+  },
+  action: {
+    button: "action/ButtonAction",
+    "button-group": "action/ButtonGroupAction",
+    // v2 alias — same file, accepted for backwards compat.
+    buttongroup: "action/ButtonGroupAction",
+    link: "action/LinkAction",
+  },
+  boolean: {
+    checkbox: "boolean/CheckboxBoolean",
+    switch: "boolean/SwitchBoolean",
+    radio: "boolean/RadioBoolean",
+    "icon-toggle": "boolean/IconToggleBoolean",
+  },
+  builder: {
+    "form-builder": "builder/FormBuilder",
+    "object-builder": "builder/ObjectBuilder",
+    "preset-builder": "builder/PresetBuilder",
+    "reactive-canvas-builder": "builder/ReactiveCanvasBuilder",
+    "element-list-builder": "builder/ElementListBuilder",
+    "quiz-builder": "builder/QuizBuilder",
+    "dependency-list-builder": "builder/DependencyListBuilder",
+    "grid-builder": "builder/GridBuilder",
+  },
+  code: {
+    "git-editor": "code/GitCodeEditor",
+    "file-tree": "code/FileTree",
+    "pull-requests-list": "code/PullRequestsList",
+    "build-status": "code/BuildStatus",
+    "chat-message": "code/ChatMessage",
+  },
+  components: {
+    "icon-badge": "components/IconBadge",
+    "icon-picker": "components/IconPickerInline",
+  },
+  "configuration-block": {
+    "elements-block": "configuration-block/ElementsBlock",
+    repeatable: "configuration-block/RepeatableBlock",
+    dialog: "configuration-block/DialogBlock",
+    modal: "configuration-block/ModalBlock",
+  },
+  display: {
+    type: "display/TypeDisplay",
+    markdown: "display/MarkdownDisplay",
+    html: "display/HtmlDisplay",
+    iframe: "display/IframeDisplay",
+    image: "display/ImageDisplay",
+    video: "display/VideoPlayerDisplay",
+    banner: "display/BannerDisplay",
+    chart: "display/ChartDisplay",
+    carousel: "display/CarouselDisplay",
+    barcode: "display/BarcodeDisplay",
+    qrcode: "display/QrCodeDisplay",
+    icon: "display/IconDisplay",
+    "progress-bar": "display/ProgressBarDisplay",
+    sprite: "display/SpriteDisplay",
+    "reactive-canvas": "display/ReactiveCanvasDisplay",
+  },
+  editor: {
+    "code-editor": "editor/CodeEditor",
+    "markdown-editor": "editor/MarkdownEditor",
+    "html-editor": "editor/HtmlEditor",
+    "image-editor": "editor/ImageEditor",
+    "rich-text-editor": "editor/RichTextEditor",
+  },
+  file: {
+    upload: "file/UploadFile",
+    dropzone: "file/DropzoneFile",
+    "asset-picker": "file/AssetPickerFile",
+  },
+  input: {
+    text: "input/TextInput",
+    number: "input/NumberInput",
+    email: "input/EmailInput",
+    password: "input/PasswordInput",
+    url: "input/UrlInput",
+    tel: "input/TelInput",
+    search: "input/SearchInput",
+    textarea: "input/TextareaInput",
+    "range-slider": "input/RangeSliderInput",
+    "barcode-scanner": "input/BarcodeScannerInput",
+  },
+  "option-select": {
+    select: "option-select/SelectOption",
+    "select-multiple": "option-select/SelectMultipleOption",
+    radio: "option-select/RadioOption",
+    checkbox: "option-select/CheckboxOption",
+    autocomplete: "option-select/AutoCompleteOption",
+    list: "option-select/ListOption",
+    "pill-select": "option-select/PillSelectOption",
+    "async-select": "option-select/AsyncSelectOption",
+    "integration-connector": "option-select/IntegrationConnectorOption",
+  },
+  picker: {
+    "date-picker": "picker/DatePicker",
+    "datetime-picker": "picker/DateTimePicker",
+    "time-picker": "picker/TimePicker",
+    "timezone-picker": "picker/TimezonePicker",
+    "color-picker": "picker/ColorPicker",
+    "icon-picker": "picker/IconPicker",
+    icon: "picker/IconPicker",
+    "map-picker": "picker/MapPicker",
+    "async-select": "picker/AsyncSelectPicker",
+    "data-model": "picker/DataModelPicker",
+    "integration-connector": "picker/IntegrationConnectorPicker",
+  },
+}
+
+/**
+ * Per-cardType map. Cards have no style discriminator — `cardType`
+ * alone resolves the renderer.
+ */
+export const cardRegistry: Record<CardType, CardPath> = {
+  "card-list": "CardListCard",
+  "tab-list": "TabListCard",
+  "element-list": "ElementListCard",
+  "element-display": "ElementDisplayCard",
+  datatable: "DataTableCard",
+  "info-card": "InfoCard",
+  "grid-view": "GridViewCard",
+}
+
+/**
+ * Default style picked when an element JSON omits the dot suffix
+ * (e.g. `type: "input"` is normalised to `"input.text"`). Each
+ * ElementCategory must have a default registered.
+ */
+export const elementDefaultStyle: Record<ElementCategory, string> = {
+  action: "button",
+  boolean: "checkbox",
+  builder: "form-builder",
+  card: "list",
+  code: "git-editor",
+  components: "icon-badge",
+  "configuration-block": "repeatable",
+  display: "type",
+  editor: "code-editor",
+  file: "upload",
+  input: "text",
+  "option-select": "select",
+  picker: "date-picker",
+}
+
+/**
+ * Returns the relative element path for a given dot-notation `type`
+ * (e.g. `"input.text"`), or `null` when the type isn't registered.
+ *
+ * A bare category (e.g. `"input"`) is auto-completed using the
+ * category's default style. The loader uses the returned path to look
+ * up a Vue component module from `import.meta.glob`.
+ */
+export function resolveElementPath(type: string): ElementPath | null {
+  const dot = type.indexOf(".")
+  const category = (dot < 0 ? type : type.slice(0, dot)) as ElementCategory
+  const style =
+    dot < 0
+      ? elementDefaultStyle[category] ?? ""
+      : type.slice(dot + 1)
+  const typeBucket = (elementRegistry as unknown as Record<string, Record<string, string>>)[category]
+  if (!typeBucket) {
+    return null
+  }
+  if (!style) {
+    const fallback = Object.keys(typeBucket)[0]
+    return fallback ? typeBucket[fallback]! : null
+  }
+  return typeBucket[style] ?? null
+}
+
+/**
+ * Returns the relative card path for a given `cardType`, or `null` if
+ * unregistered.
+ */
+export function resolveCardPath(cardType: string): CardPath | null {
+  return (cardRegistry as Record<string, string>)[cardType] ?? null
+}

package/src/engine/useCardLoader.ts

@@ -0,0 +1,57 @@
+import { type Component, defineAsyncComponent } from "vue"
+import { resolveCardPath } from "./registry"
+import { __createMissingFallback } from "./useElementLoader"
+
+const cardModules = import.meta.glob("../components/compositions/cards/**/*.vue")
+
+const componentCache = new Map<string, Component>()
+
+/**
+ * Resolves the Vue component for a given DisplayCard `cardType`.
+ * Same lazy-loading + fallback semantics as `getElementComponent`.
+ */
+export function getCardComponent(cardType: string): Component {
+  const cached = componentCache.get(cardType)
+  if (cached) {
+    return cached
+  }
+
+  const path = resolveCardPath(cardType)
+  if (!path) {
+    const fallback = __createMissingFallback("card", cardType)
+    componentCache.set(cardType, fallback)
+    return fallback
+  }
+
+  const importer = cardModules[`../components/compositions/cards/${path}.vue`]
+  if (!importer) {
+    const fallback = __createMissingFallback("card", cardType, path)
+    componentCache.set(cardType, fallback)
+    return fallback
+  }
+
+  const component = defineAsyncComponent({
+    loader: async () => {
+      const mod = (await (importer as () => Promise<{ default: Component }>)())
+      return mod.default ?? (mod as unknown as Component)
+    },
+    errorComponent: __createMissingFallback("card", cardType, path),
+    delay: 0,
+    suspensible: false,
+  })
+  componentCache.set(cardType, component)
+  return component
+}
+
+export function preloadCard(cardType: string): Promise<unknown> {
+  const path = resolveCardPath(cardType)
+  if (!path) {
+    return Promise.resolve()
+  }
+  const importer = cardModules[`../components/compositions/cards/${path}.vue`]
+  return importer ? importer() : Promise.resolve()
+}
+
+export function __clearCardCache(): void {
+  componentCache.clear()
+}