@gxp-dev/mod-ui 2.0.0

package/src/adapters/cardTypeMap.ts

@@ -0,0 +1,48 @@
+import type { CardType } from "@/definitions/shared/base"
+
+/**
+ * v1 → v2 card type mapping. The v1 docs schema uses snake_case
+ * (`fields_list`, `data_table`, ...) while v2's internal `cardType`
+ * is kebab-case (`element-list`, `datatable`, ...).
+ *
+ * Two v1 card types don't map to v2 cards at all:
+ *   - `button_group` — in v2 this is an `action` ELEMENT with
+ *     style=`button-group`, not a card. The adapter rewrites these
+ *     into a one-element `element-list` card with the button-group
+ *     element inside.
+ *   - `form_builder`  — in v2 this is a `builder` ELEMENT with
+ *     style=`form-builder`. Same rewrite as button_group.
+ */
+export const V1_TO_V2_CARD_TYPE: Record<string, CardType> = {
+  fields_list: "element-list",
+  data_table: "datatable",
+  card_list: "card-list",
+  tabs_list: "tab-list",
+  info_card: "info-card",
+  grid_view: "grid-view",
+  component: "element-display",
+  // Also pass through the v2 names so callers can mix-and-match.
+  "element-list": "element-list",
+  datatable: "datatable",
+  "card-list": "card-list",
+  "tab-list": "tab-list",
+  "info-card": "info-card",
+  "grid-view": "grid-view",
+  "element-display": "element-display",
+}
+
+export const V2_TO_V1_CARD_TYPE: Record<CardType, string> = {
+  "element-list": "fields_list",
+  datatable: "data_table",
+  "card-list": "card_list",
+  "tab-list": "tabs_list",
+  "info-card": "info_card",
+  "grid-view": "grid_view",
+  "element-display": "component",
+}
+
+/** v1 card types that map to an element wrapped in an element-list, not a card. */
+export const V1_ELEMENT_AS_CARD: ReadonlySet<string> = new Set([
+  "button_group",
+  "form_builder",
+])

package/src/adapters/conditionMap.ts

@@ -0,0 +1,182 @@
+import type {
+  ConditionLogic,
+  ConditionParam,
+  ConditionParamV1,
+} from "@/definitions/shared/conditions"
+import type { ResponsiveColumns, ResponsiveColumnsV1 } from "@/definitions/shared/responsive"
+
+/**
+ * v1 condition operator → v2 logic string.
+ *
+ * The v1 docs only documented `"equals"`; this table also covers
+ * common variants that show up in the wild (`"=="`, `"!="`, `"gt"`,
+ * `"lt"`, `"contains"`, ...). Unknown operators pass through verbatim
+ * — useful for forward-compat and easier to debug than a silent fallback.
+ */
+const V1_OPERATOR_TO_V2_LOGIC: Record<string, ConditionLogic> = {
+  equals: "==",
+  "=": "==",
+  "==": "==",
+  "===": "==",
+  not_equals: "!=",
+  "!=": "!=",
+  "!==": "!=",
+  greater_than: ">",
+  gt: ">",
+  ">": ">",
+  greater_than_or_equal: ">=",
+  gte: ">=",
+  ">=": ">=",
+  less_than: "<",
+  lt: "<",
+  "<": "<",
+  less_than_or_equal: "<=",
+  lte: "<=",
+  "<=": "<=",
+  in: "in-array",
+  in_array: "in-array",
+  "in-array": "in-array",
+  not_in: "not-in-array",
+  not_in_array: "not-in-array",
+  "not-in-array": "not-in-array",
+  contains: "contains",
+  not_contains: "not-contains",
+  "not-contains": "not-contains",
+  starts_with: "starts-with",
+  "starts-with": "starts-with",
+  ends_with: "ends-with",
+  "ends-with": "ends-with",
+  matches: "matches",
+  regex: "matches",
+  is_truthy: "is-truthy",
+  truthy: "is-truthy",
+  is_falsy: "is-falsy",
+  falsy: "is-falsy",
+  is_null: "is-null",
+  is_not_null: "is-not-null",
+  is_odd: "is-odd",
+  is_even: "is-even",
+  is_empty: "zero-length",
+  zero_length: "zero-length",
+  has_items: "g0length",
+  length_eq: "length-eq-value",
+  length_gt: "length-gt-value",
+  length_lt: "length-lt-value",
+}
+
+const V2_LOGIC_TO_V1_OPERATOR: Record<ConditionLogic, string> = {
+  "==": "equals",
+  "!=": "not_equals",
+  ">": "greater_than",
+  ">=": "greater_than_or_equal",
+  "<": "less_than",
+  "<=": "less_than_or_equal",
+  "in-array": "in",
+  "not-in-array": "not_in",
+  "starts-with": "starts_with",
+  "ends-with": "ends_with",
+  contains: "contains",
+  "not-contains": "not_contains",
+  matches: "matches",
+  "is-odd": "is_odd",
+  "is-even": "is_even",
+  "is-truthy": "is_truthy",
+  "is-falsy": "is_falsy",
+  "is-null": "is_null",
+  "is-not-null": "is_not_null",
+  g0length: "has_items",
+  n0length: "is_empty",
+  "length-eq-value": "length_eq",
+  "length-gt-value": "length_gt",
+  "length-lt-value": "length_lt",
+  "zero-length": "is_empty",
+}
+
+/** v1 `{field, operator, value}` → v2 `{name, logic, value}`. */
+export function v1ConditionParamToV2(
+  param: ConditionParamV1,
+): ConditionParam {
+  return {
+    name: param.field,
+    logic: (V1_OPERATOR_TO_V2_LOGIC[param.operator] ?? param.operator) as ConditionLogic,
+    value: param.value,
+  }
+}
+
+/** v2 `{name, logic, value}` → v1 `{field, operator, value}`. */
+export function v2ConditionParamToV1(
+  param: ConditionParam,
+): ConditionParamV1 {
+  return {
+    field: param.name,
+    operator: V2_LOGIC_TO_V1_OPERATOR[param.logic] ?? String(param.logic),
+    value: param.value,
+  }
+}
+
+/**
+ * Convert a v1 conditionParams array (or undefined) to a v2 array.
+ * Returns undefined when the input is empty so the converted JSON
+ * doesn't carry a useless empty array.
+ */
+export function v1ConditionParamsToV2(
+  params: ConditionParamV1[] | undefined,
+): ConditionParam[] | undefined {
+  if (!params || params.length === 0) {
+    return undefined
+  }
+  return params.map(v1ConditionParamToV2)
+}
+
+/** v1 `cols/colsSm/colsMd/...` → v2 `columns/columnsSm/columnsMd/...`. */
+export function v1ColumnsToV2(input: ResponsiveColumnsV1): ResponsiveColumns {
+  const out: ResponsiveColumns = {}
+  if (input.cols !== undefined) {
+    out.columns = input.cols
+  }
+  if (input.colsSm !== undefined) {
+    out.columnsSm = input.colsSm
+  }
+  if (input.colsMd !== undefined) {
+    out.columnsMd = input.colsMd
+  }
+  if (input.colsLg !== undefined) {
+    out.columnsLg = input.colsLg
+  }
+  if (input.colsXl !== undefined) {
+    out.columnsXl = input.colsXl
+  }
+  if (input.colsXxl !== undefined) {
+    out.columnsXxl = input.colsXxl
+  }
+  return out
+}
+
+/** v2 → v1 reverse for the columns shape. */
+export function v2ColumnsToV1(input: ResponsiveColumns): ResponsiveColumnsV1 {
+  const out: ResponsiveColumnsV1 = {}
+  if (input.columns !== undefined) {
+    out.cols = input.columns
+  }
+  if (input.columnsSm !== undefined) {
+    out.colsSm = input.columnsSm
+  }
+  if (input.columnsMd !== undefined) {
+    out.colsMd = input.columnsMd
+  }
+  if (input.columnsLg !== undefined) {
+    out.colsLg = input.columnsLg
+  }
+  if (input.columnsXl !== undefined) {
+    out.colsXl = input.columnsXl
+  }
+  if (input.columnsXxl !== undefined) {
+    out.colsXxl = input.columnsXxl
+  }
+  return out
+}
+
+export const __testing = {
+  V1_OPERATOR_TO_V2_LOGIC,
+  V2_LOGIC_TO_V1_OPERATOR,
+}

package/src/adapters/detect.ts

@@ -0,0 +1,71 @@
+import type { V1PageConfig, V2PageConfig } from "./v1ToV2"
+import { v1ToV2 } from "./v1ToV2"
+
+/**
+ * Detect the schema version of a page config and normalise it to the
+ * v2 shape. ShowPage / IndexPage call this at the boundary so a
+ * consumer can pass either shape transparently.
+ *
+ * Detection heuristics (any one of these indicates v1):
+ *   - `cards` is an Array (v2 uses a Record<string, Card>).
+ *   - any tab's `cards[]` contains an object with a `type` string
+ *     instead of `cardType`.
+ *   - top-level `headers` / `options` exist without `cards` / `elements`
+ *     (the IndexPage shorthand).
+ *
+ * When `schemaVersion` is explicitly set on the config, the heuristic
+ * is bypassed — useful for force-routing legacy or new shapes.
+ */
+export function normalisePageConfig(
+  config: V1PageConfig | V2PageConfig | (V1PageConfig & { schemaVersion?: "v1" | "v2" }),
+): V2PageConfig {
+  const explicit = (config as { schemaVersion?: "v1" | "v2" }).schemaVersion
+  if (explicit === "v2") {
+    return ensureMaps(config as V2PageConfig)
+  }
+  if (explicit === "v1" || isLikelyV1(config)) {
+    return v1ToV2(config as V1PageConfig)
+  }
+  return ensureMaps(config as V2PageConfig)
+}
+
+function ensureMaps(config: V2PageConfig): V2PageConfig {
+  return {
+    ...config,
+    cards: config.cards ?? {},
+    elements: config.elements ?? {},
+  }
+}
+
+function isLikelyV1(config: V1PageConfig | V2PageConfig): boolean {
+  const c = config as Record<string, unknown>
+  // v2 always carries `cards` as a Record. An Array means v1.
+  if (Array.isArray(c.cards)) {
+    return true
+  }
+  // v1 IndexPage shorthand: top-level `headers` / `options` / `listKey`
+  // without a `cards`/`elements` map.
+  if (
+    (c.headers !== undefined || c.options !== undefined || c.listKey !== undefined) &&
+    !c.cards &&
+    !c.elements
+  ) {
+    return true
+  }
+  // v1 tabs: each tab's `cards` is an array of objects with `type`
+  // (string) rather than `cardType`.
+  const tabsList = c.tabsList as Array<Record<string, unknown>> | undefined
+  if (Array.isArray(tabsList)) {
+    for (const tab of tabsList) {
+      const tabCards = tab.cards as Array<Record<string, unknown>> | undefined
+      if (Array.isArray(tabCards)) {
+        for (const card of tabCards) {
+          if (typeof card.type === "string" && card.cardType === undefined) {
+            return true
+          }
+        }
+      }
+    }
+  }
+  return false
+}

package/src/adapters/fieldTypeMap.ts

@@ -0,0 +1,238 @@
+import type { ElementType } from "@/definitions/shared/base"
+
+/**
+ * v1 field-type strings → v2 dot-notation `type` (with optional extras).
+ *
+ * v1's schema used a single string like `"text"`, `"select"`, `"date"`
+ * for the field type. v2 combines the category + variant into a
+ * dot-notation string like `"input.text"`, `"option-select.select"`,
+ * `"picker.date-picker"`. This table is the canonical map; the
+ * adapter consults it once per field.
+ *
+ * Some v1 types (the `heading-N` variants) map to a single v2 type
+ * (`display.type`) plus an extra `contentType` payload. Those entries
+ * carry an `extras` block that's spread onto the converted element.
+ */
+export interface V2Discriminator {
+  /** Dot-notation v2 type, e.g. `"input.text"`. */
+  type: ElementType
+  /** Extra fields to merge into the converted element. */
+  extras?: Record<string, unknown>
+}
+
+export const V1_TO_V2_FIELD_TYPE: Record<string, V2Discriminator> = {
+  // --- Text inputs ---
+  text: { type: "input.text" },
+  number: { type: "input.number" },
+  email: { type: "input.email" },
+  password: { type: "input.password" },
+  url: { type: "input.url" },
+  tel: { type: "input.tel" },
+  phone_number: { type: "input.tel" },
+  search: { type: "input.search" },
+  textarea: { type: "input.textarea" },
+  range: { type: "input.range-slider" },
+  barcode: { type: "input.barcode-scanner" },
+
+  // --- Selection ---
+  select: { type: "option-select.select" },
+  multi_select: { type: "option-select.select-multiple" },
+  pill_select: { type: "option-select.pill-select" },
+  radio: { type: "option-select.radio" },
+  autocomplete: { type: "option-select.autocomplete" },
+  list_select: { type: "option-select.list" },
+  asyncSelect: { type: "option-select.async-select" },
+  async_select: { type: "option-select.async-select" },
+  integration_connector: { type: "option-select.integration-connector" },
+
+  // --- Boolean ---
+  checkbox: { type: "boolean.checkbox" },
+  switch: { type: "boolean.switch" },
+  boolean: { type: "boolean.switch" },
+  boolean_icon: { type: "boolean.icon-toggle" },
+  radio_boolean: { type: "boolean.radio" },
+
+  // --- Pickers ---
+  date: { type: "picker.date-picker" },
+  datetime: { type: "picker.datetime-picker" },
+  time: { type: "picker.time-picker" },
+  timezone: { type: "picker.timezone-picker" },
+  timezone_picker: { type: "picker.timezone-picker" },
+  colorPicker: { type: "picker.color-picker" },
+  color_picker: { type: "picker.color-picker" },
+  icon_picker: { type: "picker.icon-picker" },
+  map_picker: { type: "picker.map-picker" },
+  map_coordinates: { type: "picker.map-picker" },
+  data_model: { type: "picker.data-model" },
+
+  // --- File ---
+  file: { type: "file.upload" },
+  dropzone: { type: "file.dropzone" },
+  asset_picker: { type: "file.asset-picker" },
+  "asset-picker": { type: "file.asset-picker" },
+
+  // --- Editors ---
+  codeEditor: { type: "editor.code-editor" },
+  code_editor: { type: "editor.code-editor" },
+  htmlEditor: { type: "editor.html-editor" },
+  html_editor: { type: "editor.html-editor" },
+  markdownEditor: { type: "editor.markdown-editor" },
+  markdown_editor: { type: "editor.markdown-editor" },
+  imageEditor: { type: "editor.image-editor" },
+  image_editor: { type: "editor.image-editor" },
+  richTextEditor: { type: "editor.rich-text-editor" },
+
+  // --- Display (headings collapse to display.type with contentType extra) ---
+  heading: { type: "display.type", extras: { contentType: "heading-2" } },
+  "heading-1": { type: "display.type", extras: { contentType: "heading-1" } },
+  "heading-large": { type: "display.type", extras: { contentType: "heading-1" } },
+  "heading-2": { type: "display.type", extras: { contentType: "heading-2" } },
+  "heading-3": { type: "display.type", extras: { contentType: "heading-3" } },
+  "heading-4": { type: "display.type", extras: { contentType: "heading-4" } },
+  "heading-5": { type: "display.type", extras: { contentType: "heading-5" } },
+  "heading-6": { type: "display.type", extras: { contentType: "heading-6" } },
+  "small-heading": { type: "display.type", extras: { contentType: "heading-5" } },
+  description: { type: "display.type", extras: { contentType: "paragraph" } },
+  paragraph: { type: "display.type", extras: { contentType: "paragraph" } },
+  blockquote: { type: "display.type", extras: { contentType: "quote" } },
+  caption: { type: "display.type", extras: { contentType: "caption" } },
+  banner: { type: "display.banner" },
+  icon: { type: "display.icon" },
+  sprite: { type: "display.sprite" },
+  image: { type: "display.image" },
+  video: { type: "display.video" },
+  iframe: { type: "display.iframe" },
+  carousel: { type: "display.carousel" },
+  chart: { type: "display.chart" },
+  qr_code: { type: "display.qrcode" },
+  qrcode: { type: "display.qrcode" },
+  barcode_display: { type: "display.barcode" },
+  progress_bar: { type: "display.progress-bar" },
+  reactive_canvas: { type: "display.reactive-canvas" },
+  html: { type: "display.html" },
+  "html-block": { type: "display.html" },
+  "live-html": { type: "display.html" },
+  markdown: { type: "display.markdown" },
+  render_markdown: { type: "display.markdown" },
+
+  // --- Actions (single button, button group, link) ---
+  button: { type: "action.button" },
+  button_group: { type: "action.button-group" },
+  external_link: { type: "action.link" },
+  internal_link: { type: "action.link" },
+  link: { type: "action.link" },
+
+  // --- Builders (renders nested forms / objects / canvases) ---
+  form_builder: { type: "builder.form-builder" },
+  "form-builder": { type: "builder.form-builder" },
+  object_builder: { type: "builder.object-builder" },
+  preset_builder: { type: "builder.preset-builder" },
+  reactive_canvas_builder: { type: "builder.reactive-canvas-builder" },
+  element_list_builder: { type: "builder.element-list-builder" },
+  quiz_builder: { type: "builder.quiz-builder" },
+  dependency_list_builder: { type: "builder.dependency-list-builder" },
+  grid_builder: { type: "builder.grid-builder" },
+
+  // --- Components (icon badges, inline pickers) ---
+  icon_badge: { type: "components.icon-badge" },
+  icon_picker_inline: { type: "components.icon-picker" },
+
+  // --- Configuration blocks (nested element groups) ---
+  elements_block: { type: "configuration-block.elements-block" },
+  repeatable: { type: "configuration-block.repeatable" },
+  dialog: { type: "configuration-block.dialog" },
+  modal: { type: "configuration-block.modal" },
+}
+
+/**
+ * v2 dot-notation `type` → v1 single-string field type. Picks the
+ * canonical v1 name when multiple existed (e.g. `editor.code-editor`
+ * → `"codeEditor"`).
+ */
+export function v2ToV1FieldType(type: string): string {
+  return V2_TO_V1_FIELD_TYPE[type] ?? type
+}
+
+const V2_TO_V1_FIELD_TYPE: Record<string, string> = {
+  // input
+  "input.text": "text",
+  "input.number": "number",
+  "input.email": "email",
+  "input.password": "password",
+  "input.url": "url",
+  "input.tel": "tel",
+  "input.search": "search",
+  "input.textarea": "textarea",
+  "input.range-slider": "range",
+  "input.barcode-scanner": "barcode",
+  // option-select
+  "option-select.select": "select",
+  "option-select.select-multiple": "multi_select",
+  "option-select.pill-select": "pill_select",
+  "option-select.radio": "radio",
+  "option-select.autocomplete": "autocomplete",
+  "option-select.list": "list_select",
+  "option-select.async-select": "asyncSelect",
+  "option-select.integration-connector": "integration_connector",
+  // boolean
+  "boolean.checkbox": "checkbox",
+  "boolean.switch": "switch",
+  "boolean.icon-toggle": "boolean_icon",
+  "boolean.radio": "radio_boolean",
+  // picker
+  "picker.date-picker": "date",
+  "picker.datetime-picker": "datetime",
+  "picker.time-picker": "time",
+  "picker.timezone-picker": "timezone_picker",
+  "picker.color-picker": "colorPicker",
+  "picker.icon-picker": "icon_picker",
+  "picker.map-picker": "map_picker",
+  "picker.data-model": "data_model",
+  // file
+  "file.upload": "file",
+  "file.dropzone": "dropzone",
+  "file.asset-picker": "asset_picker",
+  // editor
+  "editor.code-editor": "codeEditor",
+  "editor.html-editor": "htmlEditor",
+  "editor.markdown-editor": "markdownEditor",
+  "editor.image-editor": "imageEditor",
+  "editor.rich-text-editor": "richTextEditor",
+  // display
+  "display.type": "description",
+  "display.markdown": "render_markdown",
+  "display.html": "html",
+  "display.iframe": "iframe",
+  "display.image": "image",
+  "display.video": "video",
+  "display.banner": "banner",
+  "display.chart": "chart",
+  "display.carousel": "carousel",
+  "display.barcode": "barcode_display",
+  "display.qrcode": "qr_code",
+  "display.icon": "icon",
+  "display.progress-bar": "progress_bar",
+  "display.sprite": "sprite",
+  "display.reactive-canvas": "reactive_canvas",
+  // action
+  "action.button": "button",
+  "action.button-group": "button_group",
+  "action.link": "external_link",
+  // builder
+  "builder.form-builder": "form_builder",
+  "builder.object-builder": "object_builder",
+  "builder.preset-builder": "preset_builder",
+  "builder.reactive-canvas-builder": "reactive_canvas_builder",
+  "builder.element-list-builder": "element_list_builder",
+  "builder.quiz-builder": "quiz_builder",
+  "builder.dependency-list-builder": "dependency_list_builder",
+  "builder.grid-builder": "grid_builder",
+  // components
+  "components.icon-badge": "icon_badge",
+  "components.icon-picker": "icon_picker_inline",
+  // configuration-block
+  "configuration-block.elements-block": "elements_block",
+  "configuration-block.repeatable": "repeatable",
+  "configuration-block.dialog": "dialog",
+  "configuration-block.modal": "modal",
+}

package/src/adapters/index.ts

@@ -0,0 +1,50 @@
+/**
+ * v1 ↔ v2 schema adapters.
+ *
+ * Lets consumers feed legacy v1 (docs-format) JSON directly into the
+ * library's pages without code changes, and round-trip back to the
+ * v1 shape when integrating with legacy backend endpoints.
+ *
+ * Typical usage:
+ *
+ *   import { v1ToV2 } from "@gxp-dev/adminkit"
+ *   const config = v1ToV2(legacyJson)
+ *   // pass `config` to <ShowPage :config="config" :item="item" />
+ *
+ * The IndexPage and ShowPage components ALSO accept the v1 shape
+ * directly — they detect it via duck-typing and apply v1ToV2 at
+ * the boundary, so most consumers don't need to call this themselves.
+ */
+
+export { v1ToV2, __resetIdCounter } from "./v1ToV2"
+export type {
+  V1PageConfig,
+  V1TabConfig,
+  V1CardConfig,
+  V1FieldConfig,
+  V2PageConfig,
+} from "./v1ToV2"
+
+export { v2ToV1 } from "./v2ToV1"
+
+export { normalisePageConfig } from "./detect"
+
+export {
+  v1ConditionParamToV2,
+  v2ConditionParamToV1,
+  v1ConditionParamsToV2,
+  v1ColumnsToV2,
+  v2ColumnsToV1,
+} from "./conditionMap"
+
+export {
+  V1_TO_V2_CARD_TYPE,
+  V2_TO_V1_CARD_TYPE,
+  V1_ELEMENT_AS_CARD,
+} from "./cardTypeMap"
+
+export {
+  V1_TO_V2_FIELD_TYPE,
+  v2ToV1FieldType,
+  type V2Discriminator,
+} from "./fieldTypeMap"