@gxp-dev/mod-ui 2.0.0

package/src/definitions/shared/base.ts

@@ -0,0 +1,184 @@
+import type { Conditional, ConditionParam } from "./conditions"
+import type { ResponsiveColumns } from "./responsive"
+
+/**
+ * Union of every CardElement category — the prefix half of an
+ * element's dot-notation `type` discriminator. Each value here
+ * corresponds to one file under `definitions/elements/` and one folder
+ * under `elements/`.
+ */
+export type ElementCategory =
+  | "action"
+  | "boolean"
+  | "builder"
+  | "card"
+  | "code"
+  | "components"
+  | "configuration-block"
+  | "display"
+  | "editor"
+  | "file"
+  | "input"
+  | "option-select"
+  | "picker"
+
+/**
+ * Dot-notation discriminator: `"<category>.<style>"`. Combines what
+ * previously lived in two fields (`type` + `style`) into a single
+ * string so it doesn't collide with Vue's HTML `style` attribute
+ * fallthrough behaviour.
+ *
+ * Each per-category interface narrows this to its own valid styles —
+ * e.g. `InputElement["type"]` is `\`input.${InputStyle}\``.
+ */
+export type ElementType = `${ElementCategory}.${string}`
+
+/**
+ * Properties common to every CardElement (input, picker, display, etc.).
+ *
+ * `type` is a `"category.style"` string. The engine's registry resolves
+ * it directly to a Vue renderer path. `name` is the form-data key for
+ * input-bearing elements.
+ */
+export interface BaseElement<TType extends ElementType = ElementType>
+  extends Conditional,
+    ResponsiveColumns {
+  /** Stable identifier. Required by the engine; FormBuilder generates UUIDs. */
+  id: string
+  type: TType
+  /** Form-data key. Required for input-bearing elements. */
+  name?: string | null
+  label?: string
+  /** Hide the label while keeping the element labelled for screen readers. */
+  hideLabel?: boolean
+  defaultValue?: unknown
+  required?: boolean
+  readonly?: boolean
+  disabled?: boolean
+  placeholder?: string
+  helpText?: string
+  tooltip?: string
+  tooltipOptions?: {
+    maxWidth?: string
+    direction?: "top" | "right" | "bottom" | "left"
+  }
+  /** Extra classes applied to the element's root. */
+  classList?: string[] | string
+  /** Classes on the wrapper around the element + label. */
+  wrapperClassList?: string[] | string
+  /** Classes on the column wrapper. */
+  columnClassList?: string[] | string
+  /** Classes on the label element. */
+  labelClassList?: string[] | string
+  /** If true, the element renders in display-only preview mode. */
+  previewMode?: boolean
+  /** Ordering used by builders. */
+  order?: number
+}
+
+/**
+ * Union of every DisplayCard type. Mirrors the existing v2 schema.
+ */
+export type CardType =
+  | "card-list"
+  | "tab-list"
+  | "info-card"
+  | "grid-view"
+  | "element-list"
+  | "element-display"
+  | "datatable"
+
+/**
+ * Properties common to every DisplayCard (fields_list, data_table, etc.).
+ *
+ * Cards form the layout tree — they contain elements and/or other cards
+ * via `cardList` / `tabList` / `elementList` depending on `cardType`.
+ */
+export interface BaseCard<TType extends string = CardType>
+  extends Conditional,
+    ResponsiveColumns {
+  id: string
+  /** Discriminator used by the engine to pick a renderer. */
+  cardType: TType
+  title?: string
+  subtitle?: string
+  /** Show the surrounding chrome (border, padding). */
+  showCard?: boolean
+  /** Wrap the card body in a Collapse with a heading. */
+  collapse?: {
+    heading?: string
+    showingByDefault?: boolean
+  }
+  /** Optional footer button. */
+  footerButton?: {
+    text: string
+    route?: string
+    icon?: string
+  }
+  classList?: string[] | string
+  wrapperClassList?: string[] | string
+  order?: number
+}
+
+/**
+ * Metadata used by builders / pickers to surface this element category
+ * in lists and palettes. `elementCategory` matches the prefix half of
+ * an element's dot-notation `type`.
+ */
+export interface ElementMetadata {
+  icon: string
+  displayLabel: string
+  elementCategory: ElementCategory
+  description: string
+}
+
+/**
+ * A single field in an EditConfig — describes how the FormBuilder
+ * inspector should render the corresponding property. It is structurally
+ * identical to a CardElement (recursive), but typed loosely here to
+ * avoid a circular reference. Stronger typing lives on the concrete
+ * inspector field shapes inside each category's file.
+ */
+export interface EditConfigField {
+  type: ElementType | string
+  style?: string
+  label?: string
+  defaultValue?: unknown
+  columns?: number
+  columnsMd?: number
+  columnsLg?: number
+  section?: "configuration" | "layout" | "advanced" | "conditions" | string
+  selectOptions?: ReadonlyArray<unknown>
+  conditionParams?: ConditionParam[]
+  // Per-type extras are permitted; renderers narrow further.
+  [key: string]: unknown
+}
+
+export type EditConfig = Record<string, EditConfigField>
+
+/**
+ * Split a dot-notation `type` back into `{ category, style }`. Useful
+ * for inspectors / debug badges that want to display the style suffix
+ * without re-parsing inline.
+ */
+export function splitElementType(type: string): {
+  category: ElementCategory | string
+  style: string
+} {
+  const dot = type.indexOf(".")
+  if (dot < 0) {
+    return { category: type, style: "" }
+  }
+  return {
+    category: type.slice(0, dot) as ElementCategory,
+    style: type.slice(dot + 1),
+  }
+}
+
+/** Build a `BaseElement["type"]` from a `(category, style)` pair. */
+export function joinElementType(
+  category: ElementCategory | string,
+  style: string,
+): ElementType {
+  return `${category}.${style}` as ElementType
+}

package/src/definitions/shared/conditions.ts

@@ -0,0 +1,83 @@
+/**
+ * Condition / visibility evaluation contract.
+ *
+ * Matches the existing v2 Mod schema:
+ *   conditionParams: [{ name: "first_name", logic: "!=", value: "" }]
+ *
+ * The engine ANDs (default) or ORs (per `conditionGroupLogic`) every
+ * entry. Nested groups are expressed by passing `subCondition: true`
+ * and providing a nested `conditionParams` array on that entry.
+ *
+ * The v1 schema used `{field, operator, value}` — the v1 adapter
+ * renames those keys before handing the element to the engine.
+ */
+export type ConditionLogic =
+  | "=="
+  | "!="
+  | ">"
+  | ">="
+  | "<"
+  | "<="
+  | "in-array"
+  | "not-in-array"
+  | "starts-with"
+  | "ends-with"
+  | "contains"
+  | "not-contains"
+  | "matches"
+  | "is-odd"
+  | "is-even"
+  | "is-truthy"
+  | "is-falsy"
+  | "is-null"
+  | "is-not-null"
+  | "g0length"
+  | "n0length"
+  | "length-eq-value"
+  | "length-gt-value"
+  | "length-lt-value"
+  | "zero-length"
+
+export type ConditionGroupLogic = "AND" | "OR"
+
+export interface ConditionParam {
+  /** Dot-path into the data model. e.g. `"user.role"`. */
+  name: string
+  logic: ConditionLogic
+  /** Comparison value. Optional for unary operators. */
+  value?: unknown
+  /** Type hint for `value` — "string" (literal) or "model" (data path). */
+  valueType?: "string" | "model"
+  /** When true, this entry is itself a nested group with its own params. */
+  subCondition?: boolean
+  /** Logic for the nested group (only meaningful when subCondition). */
+  conditionGroupLogic?: ConditionGroupLogic
+  /** Nested params (only meaningful when subCondition). */
+  conditionParams?: ConditionParam[]
+}
+
+export type ConditionFn<TItem = Record<string, unknown>> = (
+  item: TItem,
+) => boolean
+
+export interface Conditional<TItem = Record<string, unknown>> {
+  /** Function predicate. Wins over `conditionParams` when both are set. */
+  condition?: ConditionFn<TItem>
+  /** Declarative predicates, AND-combined unless `conditionGroupLogic` says OR. */
+  conditionParams?: ConditionParam[]
+  conditionGroupLogic?: ConditionGroupLogic
+  /** Feature flags required for this element/card to render. */
+  features?: string[]
+  /** Permissions required for this element/card to render. */
+  permissions?: string[]
+}
+
+/**
+ * Aliases accepted by the v1 adapter. v1 JSON used `field`/`operator`;
+ * the adapter renames before evaluation.
+ */
+export interface ConditionParamV1 {
+  field: string
+  operator: string
+  value?: unknown
+}

package/src/definitions/shared/connector.ts

@@ -0,0 +1,18 @@
+/**
+ * Shared connector shape used by the `integration-connector` element
+ * compositions (option-select + picker). Represents a single external
+ * integration endpoint the user can wire up — Slack workspace,
+ * Salesforce org, etc.
+ */
+export interface Connector {
+  /** Stable identifier returned by the host. */
+  id: string
+  /** Human-facing label shown in the option list / trigger. */
+  label: string
+  /** Optional lucide icon name (e.g. "plug", "slack", "salesforce"). */
+  icon?: string
+  /** Display hint for the integration family. */
+  type?: string
+  /** Current OAuth / connection status. */
+  status?: "connected" | "disconnected" | "error"
+}

package/src/definitions/shared/crud.ts

@@ -0,0 +1,47 @@
+import type { RouteRef } from "./route"
+
+/**
+ * CRUD configuration shared by IndexPage / ShowPage / FormPanel.
+ * Each operation is independently optional so a page can be read-only,
+ * create-only, etc.
+ */
+
+export interface CreateConfig<TItem = Record<string, unknown>> {
+  create: RouteRef
+  /**
+   * Transform the form payload before submission. Return value is what
+   * actually gets POST'd.
+   */
+  transform?: (data: TItem) => TItem | Record<string, unknown>
+  /** Fields to reload from the server after a successful create. */
+  fieldsForceReload?: string[]
+  /** Custom button text. */
+  buttonText?: string
+  /** Hide the create button from the UI while keeping the action wired. */
+  hideButton?: boolean
+}
+
+export interface UpdateConfig<TItem = Record<string, unknown>> {
+  update: RouteRef & {
+    /** Property on the row that identifies the record (default `"id"`). */
+    key?: string
+  }
+  /** Auto-save on field change instead of requiring an explicit save click. */
+  autoSave?: boolean
+  /** Show or hide the explicit save button. */
+  showSaveButton?: boolean
+  /** Run client-side validation before submitting. */
+  validation?: boolean
+  transform?: (data: TItem) => TItem | Record<string, unknown>
+  fieldsForceReload?: string[]
+}
+
+export interface DeleteConfig {
+  delete: RouteRef & {
+    key?: string
+  }
+  /** If true, prompt the user to type a confirmation string. */
+  requiresInputConfirmation?: boolean
+  /** Text the user must type to confirm. Default: row's display name. */
+  confirmationText?: string
+}

package/src/definitions/shared/index.ts

@@ -0,0 +1,33 @@
+export type {
+  BaseCard,
+  BaseElement,
+  CardType,
+  EditConfig,
+  EditConfigField,
+  ElementCategory,
+  ElementMetadata,
+  ElementType,
+} from "./base"
+export { joinElementType, splitElementType } from "./base"
+export type {
+  ConditionFn,
+  ConditionGroupLogic,
+  ConditionLogic,
+  ConditionParam,
+  ConditionParamV1,
+  Conditional,
+} from "./conditions"
+export type { Connector } from "./connector"
+export type { CreateConfig, DeleteConfig, UpdateConfig } from "./crud"
+export type {
+  ResponsiveColumns,
+  ResponsiveColumnsKey,
+  ResponsiveColumnsV1,
+} from "./responsive"
+export type { HttpMethod, RouteRef } from "./route"
+export type {
+  SelectOption,
+  SelectOptionLike,
+  SelectOptionsResolver,
+} from "./select-options"
+export type { ValidationConfig, ValidationRule } from "./validation"

package/src/definitions/shared/responsive.ts

@@ -0,0 +1,36 @@
+/**
+ * Bootstrap-style responsive grid props shared across every card and
+ * element. The numbers match a 12-column grid (`columns: 6` = half width).
+ *
+ * Naming mirrors the existing v2 Mod schema exactly so JSON authored
+ * against the experience-portal renders without translation.
+ */
+export interface ResponsiveColumns {
+  /** Default span (mobile-first, all breakpoints). */
+  columns?: number
+  /** Span at >= 576px. */
+  columnsSm?: number
+  /** Span at >= 768px. */
+  columnsMd?: number
+  /** Span at >= 992px. */
+  columnsLg?: number
+  /** Span at >= 1200px. */
+  columnsXl?: number
+  /** Span at >= 1400px. */
+  columnsXxl?: number
+}
+
+export type ResponsiveColumnsKey = keyof ResponsiveColumns
+
+/**
+ * Aliases accepted by the v1 adapter. v1 JSON uses `cols/colsMd/...`;
+ * the adapter maps these to the v2 keys above.
+ */
+export interface ResponsiveColumnsV1 {
+  cols?: number
+  colsSm?: number
+  colsMd?: number
+  colsLg?: number
+  colsXl?: number
+  colsXxl?: number
+}

package/src/definitions/shared/route.ts

@@ -0,0 +1,29 @@
+/**
+ * Route reference used by data-driven cards (DataTable, AsyncSelect, etc.)
+ * and CRUD config. Matches the Laravel-named-route convention used by the
+ * GxP platform: `{ route: 'api.users.index', params: {team: 'current'} }`.
+ */
+export type HttpMethod =
+  | "get"
+  | "post"
+  | "put"
+  | "patch"
+  | "delete"
+  | "GET"
+  | "POST"
+  | "PUT"
+  | "PATCH"
+  | "DELETE"
+
+export interface RouteRef {
+  /** Laravel-named route or a raw URL starting with `/`. */
+  route: string
+  /** Path / query params injected into the route. */
+  params?: Record<string, unknown>
+  /** HTTP verb; defaults to `get`. */
+  requestType?: HttpMethod
+  /** Override the body for POST-style routes. */
+  data?: Record<string, unknown>
+  /** Extra headers to merge into the request. */
+  headers?: Record<string, string>
+}

package/src/definitions/shared/select-options.ts

@@ -0,0 +1,30 @@
+/**
+ * Common option / choice shapes shared by every selectable element
+ * (option-select, picker, etc.). The shape mirrors the v2 schema so
+ * JSON authored against the platform deserialises cleanly.
+ */
+export interface SelectOption<TValue = unknown> {
+  label: string
+  value: TValue
+  /** Secondary text rendered beneath / beside the label. */
+  secondaryText?: string
+  /** Inline icon name (lucide). */
+  icon?: string
+  /** Optional Tailwind class or style hint. */
+  className?: string
+  disabled?: boolean
+  /** Free-form metadata consumers can use; ignored by the renderer. */
+  meta?: Record<string, unknown>
+}
+
+/** A plain string option is also accepted by the engine. */
+export type SelectOptionLike<TValue = unknown> = SelectOption<TValue> | string
+
+/**
+ * Functions that resolve options dynamically from the bound data model.
+ * Lets a select compute its options from sibling fields without a
+ * round-trip to the server.
+ */
+export type SelectOptionsResolver<TItem = Record<string, unknown>, TValue = unknown> = (
+  item: TItem,
+) => SelectOptionLike<TValue>[]

package/src/definitions/shared/validation.ts

@@ -0,0 +1,49 @@
+/**
+ * Validation contract used by every input-bearing element.
+ *
+ * Two layered shapes are supported:
+ *   - `rules`: Laravel-style rule strings ("required", "min:3", "email").
+ *     These are translated to the runtime validator inside the engine.
+ *   - `messages`: optional per-rule overrides keyed by rule name.
+ */
+export type ValidationRule =
+  | "required"
+  | "nullable"
+  | "email"
+  | "url"
+  | "uuid"
+  | "alpha"
+  | "alpha_num"
+  | "alpha_dash"
+  | "numeric"
+  | "integer"
+  | "boolean"
+  | "json"
+  | "date"
+  | "after"
+  | "before"
+  | "confirmed"
+  | "different"
+  | "same"
+  | "unique"
+  | "exists"
+  // Parameterised rules — caller appends a colon and the parameter:
+  // e.g. "min:3", "max:100", "between:1,10", "in:foo,bar,baz".
+  | `min:${number}`
+  | `max:${number}`
+  | `between:${number},${number}`
+  | `size:${number}`
+  | `gt:${number}`
+  | `gte:${number}`
+  | `lt:${number}`
+  | `lte:${number}`
+  | `regex:${string}`
+  | `in:${string}`
+  | `not_in:${string}`
+  // Escape hatch: any rule string not enumerated above.
+  | (string & {})
+
+export interface ValidationConfig {
+  rules?: ValidationRule[]
+  messages?: Record<string, string>
+}