@gxp-dev/mod-ui 2.0.0

package/src/engine/useDisplayConditions.ts

@@ -0,0 +1,218 @@
+import type {
+  ConditionGroupLogic,
+  ConditionLogic,
+  ConditionParam,
+  Conditional,
+} from "@/definitions/shared/conditions"
+
+/**
+ * Evaluator for the v2 condition contract.
+ *
+ * Accepts a `Conditional` (anything with `condition`, `conditionParams`,
+ * `features`, or `permissions`) and a data model. Returns true if the
+ * element/card should render.
+ *
+ * Precedence:
+ *   1. `condition` function (if provided) — short-circuits everything.
+ *   2. `features` / `permissions` — checked against the optional
+ *      `availableFeatures` / `availablePermissions` lists in `ctx`.
+ *   3. `conditionParams` — every entry must pass (default AND); the
+ *      group logic is overridden by `conditionGroupLogic`.
+ *
+ * `subCondition: true` entries are themselves groups with their own
+ * `conditionParams` and `conditionGroupLogic`.
+ */
+export interface EvaluationContext {
+  /** Feature flags currently enabled for the consumer. */
+  availableFeatures?: ReadonlyArray<string>
+  /** Permissions held by the current user. */
+  availablePermissions?: ReadonlyArray<string>
+}
+
+export function shouldRender(
+  cfg: Conditional | undefined,
+  item: Record<string, unknown>,
+  ctx: EvaluationContext = {},
+): boolean {
+  if (!cfg) {
+    return true
+  }
+
+  if (typeof cfg.condition === "function") {
+    return Boolean(cfg.condition(item))
+  }
+
+  if (cfg.features?.length) {
+    const available = ctx.availableFeatures ?? []
+    if (!cfg.features.every((f) => available.includes(f))) {
+      return false
+    }
+  }
+
+  if (cfg.permissions?.length) {
+    const available = ctx.availablePermissions ?? []
+    if (!cfg.permissions.every((p) => available.includes(p))) {
+      return false
+    }
+  }
+
+  if (!cfg.conditionParams?.length) {
+    return true
+  }
+
+  return evaluateConditionGroup(
+    cfg.conditionParams,
+    cfg.conditionGroupLogic ?? "AND",
+    item,
+  )
+}
+
+function evaluateConditionGroup(
+  params: ReadonlyArray<ConditionParam>,
+  logic: ConditionGroupLogic,
+  item: Record<string, unknown>,
+): boolean {
+  if (params.length === 0) {
+    return true
+  }
+  const results = params.map((p) => evaluateCondition(p, item))
+  return logic === "OR" ? results.some(Boolean) : results.every(Boolean)
+}
+
+function evaluateCondition(
+  param: ConditionParam,
+  item: Record<string, unknown>,
+): boolean {
+  if (param.subCondition) {
+    return evaluateConditionGroup(
+      param.conditionParams ?? [],
+      param.conditionGroupLogic ?? "AND",
+      item,
+    )
+  }
+  const left = readPath(item, param.name)
+  const right =
+    param.valueType === "model"
+      ? readPath(item, String(param.value ?? ""))
+      : param.value
+  return applyLogic(param.logic, left, right)
+}
+
+function applyLogic(
+  logic: ConditionLogic,
+  left: unknown,
+  right: unknown,
+): boolean {
+  switch (logic) {
+    case "==":
+      // eslint-disable-next-line eqeqeq
+      return left == right
+    case "!=":
+      // eslint-disable-next-line eqeqeq
+      return left != right
+    case ">":
+      return toNumber(left) > toNumber(right)
+    case ">=":
+      return toNumber(left) >= toNumber(right)
+    case "<":
+      return toNumber(left) < toNumber(right)
+    case "<=":
+      return toNumber(left) <= toNumber(right)
+    case "in-array":
+      return Array.isArray(right) ? right.includes(left as never) : false
+    case "not-in-array":
+      return Array.isArray(right) ? !right.includes(left as never) : true
+    case "contains":
+      return String(left ?? "").includes(String(right ?? ""))
+    case "not-contains":
+      return !String(left ?? "").includes(String(right ?? ""))
+    case "starts-with":
+      return String(left ?? "").startsWith(String(right ?? ""))
+    case "ends-with":
+      return String(left ?? "").endsWith(String(right ?? ""))
+    case "matches":
+      try {
+        return new RegExp(String(right ?? "")).test(String(left ?? ""))
+      } catch {
+        return false
+      }
+    case "is-odd":
+      return toNumber(left) % 2 !== 0
+    case "is-even":
+      return toNumber(left) % 2 === 0
+    case "is-truthy":
+      return Boolean(left)
+    case "is-falsy":
+      return !left
+    case "is-null":
+      return left === null || left === undefined
+    case "is-not-null":
+      return left !== null && left !== undefined
+    case "g0length":
+      return lengthOf(left) > 0
+    case "n0length":
+      return lengthOf(left) === 0
+    case "zero-length":
+      return lengthOf(left) === 0
+    case "length-eq-value":
+      return lengthOf(left) === toNumber(right)
+    case "length-gt-value":
+      return lengthOf(left) > toNumber(right)
+    case "length-lt-value":
+      return lengthOf(left) < toNumber(right)
+    default:
+      return false
+  }
+}
+
+function readPath(item: Record<string, unknown>, path: string): unknown {
+  if (!path) {
+    return undefined
+  }
+  const parts = path.split(".")
+  let current: unknown = item
+  for (const part of parts) {
+    if (current && typeof current === "object" && part in (current as object)) {
+      current = (current as Record<string, unknown>)[part]
+    } else {
+      return undefined
+    }
+  }
+  return current
+}
+
+function toNumber(value: unknown): number {
+  if (typeof value === "number") {
+    return value
+  }
+  if (typeof value === "string" && value.trim() !== "") {
+    const n = Number(value)
+    return Number.isFinite(n) ? n : NaN
+  }
+  return NaN
+}
+
+function lengthOf(value: unknown): number {
+  if (value == null) {
+    return 0
+  }
+  if (Array.isArray(value) || typeof value === "string") {
+    return value.length
+  }
+  if (typeof value === "object") {
+    return Object.keys(value as object).length
+  }
+  return 0
+}
+
+/**
+ * Internal exports used by tests and the engine package only.
+ */
+export const __testing = {
+  applyLogic,
+  evaluateCondition,
+  evaluateConditionGroup,
+  lengthOf,
+  readPath,
+  toNumber,
+}

package/src/engine/useElementLoader.ts

@@ -0,0 +1,118 @@
+import { type Component, defineAsyncComponent, h } from "vue"
+import { resolveElementPath } from "./registry"
+
+/**
+ * Vite glob entry point. Each value is a function returning a Promise
+ * that resolves to the .vue module. Vite turns each into its own chunk
+ * so the consumer only downloads the elements that get rendered.
+ */
+const elementModules = import.meta.glob("../components/compositions/elements/**/*.vue")
+
+/**
+ * Component cache so repeated lookups of the same (type, style) return
+ * the same `defineAsyncComponent` instance — important for Vue's
+ * keep-alive and for stability across re-renders.
+ */
+const componentCache = new Map<string, Component>()
+
+/**
+ * Resolves the Vue component for a given element type + style.
+ *
+ * Returns an async-wrapped component that lazy-loads the underlying
+ * .vue file on first render. If the (type, style) pair isn't
+ * registered or the file is missing, returns a Fallback component that
+ * renders a small warning instead of throwing — this lets a page with
+ * one bad element still render the rest.
+ */
+export function getElementComponent(type: string): Component {
+  const cached = componentCache.get(type)
+  if (cached) {
+    return cached
+  }
+
+  const path = resolveElementPath(type)
+  if (!path) {
+    const fallback = createMissingFallback("element", type)
+    componentCache.set(type, fallback)
+    return fallback
+  }
+
+  const importer = elementModules[`../components/compositions/elements/${path}.vue`]
+  if (!importer) {
+    const fallback = createMissingFallback("element", type, path)
+    componentCache.set(type, 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("element", type, path),
+    delay: 0,
+    suspensible: false,
+  })
+  componentCache.set(type, component)
+  return component
+}
+
+/**
+ * Eagerly preload an element module (e.g. for above-the-fold inputs).
+ * Returns a Promise that resolves when the chunk is loaded.
+ */
+export function preloadElement(type: string): Promise<unknown> {
+  const path = resolveElementPath(type)
+  if (!path) {
+    return Promise.resolve()
+  }
+  const importer = elementModules[`../components/compositions/elements/${path}.vue`]
+  return importer ? importer() : Promise.resolve()
+}
+
+/**
+ * Test-only: lets vitest reset the cache between cases.
+ */
+export function __clearElementCache(): void {
+  componentCache.clear()
+}
+
+function createMissingFallback(
+  kind: "element" | "card",
+  type: string,
+  path?: string,
+): Component {
+  return {
+    name: "MissingRendererFallback",
+    setup() {
+      return () =>
+        h(
+          "div",
+          {
+            class:
+              "rounded-md border border-dashed border-destructive/40 bg-destructive/5 px-3 py-2 text-sm text-destructive",
+            "data-testid": "missing-renderer",
+            "data-kind": kind,
+            "data-type": type,
+          },
+          [
+            h(
+              "strong",
+              { class: "font-semibold" },
+              `Unknown ${kind}: ${type}`,
+            ),
+            path
+              ? h(
+                  "div",
+                  { class: "text-xs opacity-70" },
+                  `Expected file at src/${kind === "element" ? "elements" : "cards"}/${path}.vue`,
+                )
+              : null,
+          ],
+        )
+    },
+  }
+}
+
+// Re-export so the card loader can use the same fallback signature.
+export { createMissingFallback as __createMissingFallback }

package/src/engine/useFormData.ts

@@ -0,0 +1,52 @@
+import { computed, inject, provide, type ComputedRef, type InjectionKey } from "vue"
+import { useFormDataStore } from "@/stores/formDataStore"
+
+/**
+ * Vue inject key used by the page-level component (ShowPage / IndexPage
+ * / FormPanel) to advertise which formId child renderers should bind
+ * to. Avoids prop-drilling `formId` through every nested card/element.
+ */
+export const FORM_ID_KEY = Symbol("gxp-adminkit:formId") as InjectionKey<string>
+
+/**
+ * Provide a formId to descendants. Call once at the page boundary.
+ */
+export function provideFormId(formId: string): void {
+  provide(FORM_ID_KEY, formId)
+}
+
+export interface UseFormDataBindings {
+  /** Current value for `name` (undefined if unset). */
+  value: ComputedRef<unknown>
+  /** Errors for `name`. Empty array if no errors. */
+  errors: ComputedRef<string[]>
+  /** Whether the field has been touched since initialisation. */
+  touched: ComputedRef<boolean>
+  /** Set the field's value. */
+  setValue: (value: unknown) => void
+  /** Clear errors for this field. */
+  clearError: () => void
+}
+
+/**
+ * Bind an element's `name` to the form-data store. Returns reactive
+ * value, errors, and a setter. Renderers typically:
+ *
+ *   const { value, errors, setValue } = useFormData(props.element.name)
+ *   <input :value="value" @input="setValue(($event.target as HTMLInputElement).value)" />
+ */
+export function useFormData(name: string, formIdOverride?: string): UseFormDataBindings {
+  const formId =
+    formIdOverride ?? inject(FORM_ID_KEY, undefined) ?? "default"
+  const store = useFormDataStore()
+  // Ensure the form exists in the store before reading.
+  store.ensureForm(formId)
+
+  return {
+    value: computed(() => store.forms[formId]?.values[name]),
+    errors: computed(() => store.forms[formId]?.errors[name] ?? []),
+    touched: computed(() => Boolean(store.forms[formId]?.touched[name])),
+    setValue: (value: unknown) => store.setValue(formId, name, value),
+    clearError: () => store.clearErrors(formId, name),
+  }
+}

package/src/env.d.ts

@@ -0,0 +1,8 @@
+/// <reference types="vite/client" />
+
+declare module "*.vue" {
+  import type { DefineComponent } from "vue"
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const component: DefineComponent<{}, {}, any>
+  export default component
+}

package/src/index.ts

@@ -0,0 +1,175 @@
+/**
+ * @gxp-dev/adminkit — public entry point.
+ *
+ * Layered exports:
+ *
+ *   - `definitions/`   TypeScript schema (types, defaults, metadata,
+ *                      EditConfig) for every element and card.
+ *   - `components/ui/` shadcn-vue primitives built on reka-ui.
+ *   - `engine/`        Runtime renderers, loaders, condition evaluator,
+ *                      form-data binding.
+ *   - `pages/`         IndexPage / ShowPage — top-level JSON consumers.
+ *   - `adapters/`      v1 ↔ v2 schema translation. ShowPage / IndexPage
+ *                      apply this automatically.
+ *   - `stores/`        Pinia stores (form data + form builder state).
+ *   - `lib/`           cn(), assertNever(), hasKey().
+ *
+ * Per-cardType DisplayCard components and per-(type, style) element
+ * renderers under `cards/` and `elements/` are NOT re-exported here —
+ * the engine resolves them dynamically via `import.meta.glob`, which
+ * is how consumers consume them. Direct sub-path imports work for
+ * advanced cases:
+ *
+ *   import Button from "@gxp-dev/adminkit/components/ui/button"
+ *   import TextInput from "@gxp-dev/adminkit/elements/input/TextInput.vue"
+ */
+
+// Definitions (types + metadata maps).
+export * from "./definitions"
+
+// shadcn-vue primitives (Button, Input, Dialog, etc.).
+export * from "./components/ui"
+
+// Engine (renderers, loaders, condition evaluator, form-data binding).
+export {
+  CardRenderer,
+  ElementRenderer,
+  FORM_ID_KEY,
+  cardRegistry,
+  elementDefaultStyle,
+  elementRegistry,
+  getCardComponent,
+  getElementComponent,
+  preloadCard,
+  preloadElement,
+  provideFormId,
+  resolveCardPath,
+  resolveElementPath,
+  shouldRender,
+  useFormData,
+  type CardPath,
+  type ElementPath,
+  type ElementRegistry,
+  type EvaluationContext,
+  type UseFormDataBindings,
+} from "./engine"
+
+// Pages (top-level templating consumers).
+export { default as IndexPage } from "./pages/IndexPage.vue"
+export type {
+  BreadCrumb as IndexPageBreadCrumb,
+  IndexPageConfig,
+  IndexPageProps,
+} from "./pages/IndexPage.vue"
+export { default as ShowPage } from "./pages/ShowPage.vue"
+export {
+  PAGE_EVENT_HANDLERS_KEY,
+  type BreadCrumb as ShowPageBreadCrumb,
+  type ShowPageConfig,
+  type ShowPageProps,
+  type TabConfig,
+} from "./pages/ShowPage.vue"
+
+// Stores (Pinia).
+export { useFormDataStore, type FormState } from "./stores/formDataStore"
+export {
+  useFormBuilderStore,
+  useFormBuilder,
+  __resetFormBuilderIdCounter,
+  type BuilderSchema,
+  type BuilderSelection,
+} from "./stores/formBuilderStore"
+export {
+  useObjectBuilderStore,
+  useObjectBuilder,
+  __resetObjectBuilderIdCounter,
+  defaultValueForType,
+  recordToSchema,
+  toRecord,
+  type ObjectBuilderEntry,
+  type ObjectBuilderEntryType,
+  type ObjectBuilderSchema,
+  type ObjectBuilderSelection,
+} from "./stores/objectBuilderStore"
+export {
+  useElementListBuilderStore,
+  useElementListBuilder,
+  __resetElementListBuilderIdCounter,
+  type ElementListBuilderSchema,
+  type ElementListBuilderSelection,
+} from "./stores/elementListBuilderStore"
+export {
+  useGridBuilderStore,
+  useGridBuilder,
+  __resetGridBuilderIdCounter,
+  type GridBuilderItem,
+  type GridBuilderSchema,
+  type GridBuilderSelection,
+} from "./stores/gridBuilderStore"
+export {
+  useQuizBuilderStore,
+  useQuizBuilder,
+  __resetQuizBuilderIdCounter,
+  type QuizBuilderSchema,
+  type QuizBuilderSelection,
+  type QuizOption,
+  type QuizQuestion,
+  type QuizQuestionType,
+} from "./stores/quizBuilderStore"
+export {
+  usePresetBuilderStore,
+  usePresetBuilder,
+  __resetPresetBuilderIdCounter,
+  type PresetBuilderSchema,
+  type PresetBuilderState,
+} from "./stores/presetBuilderStore"
+export {
+  useDependencyListBuilderStore,
+  useDependencyListBuilder,
+  __resetDependencyListBuilderIdCounter,
+  buildRuleFromTemplate,
+  type DependencyAction,
+  type DependencyActionType,
+  type DependencyCondition,
+  type DependencyListBuilderSchema,
+  type DependencyListBuilderSelection,
+  type DependencyOperator,
+  type DependencyRule,
+  type DependencyRuleTemplate,
+} from "./stores/dependencyListBuilderStore"
+export {
+  useReactiveCanvasBuilderStore,
+  useReactiveCanvasBuilder,
+  __resetReactiveCanvasBuilderIdCounter,
+  REACTIVE_CANVAS_BLOCK_TYPES,
+  type ReactiveCanvasBlock,
+  type ReactiveCanvasBlockType,
+  type ReactiveCanvasBuilderSchema,
+  type ReactiveCanvasBuilderSelection,
+} from "./stores/reactiveCanvasBuilderStore"
+
+// Schema adapters (v1 ↔ v2 JSON translation).
+export {
+  v1ToV2,
+  v2ToV1,
+  normalisePageConfig,
+  v1ConditionParamToV2,
+  v2ConditionParamToV1,
+  v1ConditionParamsToV2,
+  v1ColumnsToV2,
+  v2ColumnsToV1,
+  v2ToV1FieldType,
+  V1_TO_V2_CARD_TYPE,
+  V1_TO_V2_FIELD_TYPE,
+  V1_ELEMENT_AS_CARD,
+  V2_TO_V1_CARD_TYPE,
+  type V1PageConfig,
+  type V1TabConfig,
+  type V1CardConfig,
+  type V1FieldConfig,
+  type V2PageConfig,
+  type V2Discriminator,
+} from "./adapters"
+
+// Utilities.
+export { cn, assertNever, hasKey } from "./lib/utils"

package/src/lib/utils.ts

@@ -0,0 +1,33 @@
+import { clsx, type ClassValue } from "clsx"
+import { twMerge } from "tailwind-merge"
+
+/**
+ * Merges Tailwind class names with conflict resolution. The canonical
+ * helper used across every component in this library — passing
+ * conditional classes through `cn()` ensures later-applied utilities
+ * override earlier ones predictably.
+ */
+export function cn(...inputs: ClassValue[]): string {
+  return twMerge(clsx(inputs))
+}
+
+/**
+ * Compile-time + runtime assertion that a value is never reached.
+ * Useful in exhaustive `switch` statements over union discriminants
+ * (e.g. element / card type tags) so adding a new variant becomes a
+ * TypeScript error until every consumer handles it.
+ */
+export function assertNever(value: never, message?: string): never {
+  throw new Error(message ?? `Unexpected value: ${String(value)}`)
+}
+
+/**
+ * Type predicate for objects that have a `[key]` property — handy when
+ * narrowing untrusted JSON before reading from it.
+ */
+export function hasKey<K extends PropertyKey>(
+  obj: unknown,
+  key: K,
+): obj is Record<K, unknown> {
+  return typeof obj === "object" && obj !== null && key in obj
+}