viur-ui 0.0.1

package/src/request/envelope.js

@@ -0,0 +1,211 @@
+// --------------------------------------------------------------------------- //
+// Envelope normalization — v1 → v2                                            //
+// --------------------------------------------------------------------------- //
+//
+// viur-ui works PRIMARILY on the viur-actions "envelope v2" response shape
+// (see sources/viur-actions/src/viur/actions/envelope.py). To also keep
+// supporting the classic v1 ViUR JSON protocol (`values` / `skellist` /
+// `structure` / `errors` / `action`), we normalize every response UP to the
+// canonical v2 envelope at the `.json()`/parse boundary.
+//
+// This is the exact inverse of vi-vue-utils, which normalizes v2 DOWN to v1.
+// There, v1 is canonical and v2 responses are adapted; here, v2 is canonical
+// and v1 responses are adapted.
+//
+// The normalization is transparent for bodies that are already v2 (they carry
+// the JSON number `version: 2`) and for non-ViUR payloads (skey arrays, the
+// version-agnostic `getStructure` map, custom endpoints) — those pass through
+// unchanged.
+//
+// By default the request layer hits the unversioned `/json/…` endpoint, which
+// the server aliases to the newest wire format (envelope v2). A specific
+// version can be pinned via the separate `version` parameter (`2`/`"v2"` for
+// v2, `1`/`"v1"` for classic v1) — see `create_url` in request.js. Either way,
+// this module guarantees viur-ui consumes a v2-shaped body.
+
+/**
+ * Canonical v2 envelope field set (see viur-actions envelope.py):
+ *   version, action, status, step, step_status, steps, follow,
+ *   datatype, module, structure, data, errors
+ * plus a list-only `meta: { cursor, orders }`.
+ */
+
+/** v1 actions whose selected value IS the url of the next step. */
+const SELECTION_ACTIONS = ["select_authentication_provider", "select_secondfactor_provider"]
+
+/**
+ * Target url of the next step in the CLASSIC v1 login.
+ *
+ * v2 (viur-actions) drives a multi-step action itself: every response carries
+ * the `follow` url of the next step. v1 has no such field — there the target IS
+ * the value the user picked: `/user/login` renders a single select whose option
+ * KEYS are the provider urls ("/vi/user/auth_userpassword/login", …), and a POST
+ * echoes the chosen key back in the body. So the selection doubles as the
+ * follow.
+ *
+ * The same shape appears twice in the flow: choosing the PRIMARY provider
+ * (`select_authentication_provider`) and choosing the SECOND FACTOR
+ * (`select_secondfactor_provider`).
+ *
+ * Only applied to a body that really is such a selection: one of those actions,
+ * a select bone, and a chosen value that is one of that bone's own option keys.
+ * Returns null otherwise.
+ *
+ * @param {*} body normalized (v2-shaped) body
+ * @returns {string|null}
+ */
+export function v1SelectionFollow(body) {
+  if (!body || typeof body !== "object" || !SELECTION_ACTIONS.includes(body["action"])) {
+    return null
+  }
+  const values = body["data"] ?? body["values"] ?? {}
+  const structure = body["structure"] ?? {}
+  for (const [name, bone] of Object.entries(structure)) {
+    if (!String(bone?.["type"] ?? "").startsWith("select")) continue
+    const chosen = values?.[name]
+    if (typeof chosen !== "string" || !/^(\/|https?:\/\/)/.test(chosen)) continue
+    // Nur wenn der Wert tatsächlich eine der angebotenen Ziel-URLs ist.
+    if (bone?.["values"] && Object.prototype.hasOwnProperty.call(bone["values"], chosen)) return chosen
+  }
+  return null
+}
+
+/**
+ * Normalize the `errors` array so consumers can rely on `fieldPath` being a
+ * LIST of path segments (that is how viur-core declares it and how the bones
+ * match errors to fields: `fieldPath[0] === boneName`).
+ *
+ * Some server paths hand a plain string instead — viur-core's userpassword
+ * login, for example, builds its "Invalid username or password provided" error
+ * with the bare bone name. A string would then be indexed character-wise and
+ * the error would silently never reach any field.
+ *
+ * @param {*} errors
+ * @returns {Array}
+ */
+function normalizeErrors(errors) {
+  if (!Array.isArray(errors)) return []
+  return errors.map((error) => {
+    if (!error || typeof error !== "object") return error
+    const fieldPath = error["fieldPath"]
+    if (fieldPath == null || Array.isArray(fieldPath)) return error
+    return { ...error, fieldPath: String(fieldPath).split(".").filter(Boolean) }
+  })
+}
+
+/**
+ * True if `data` is an already-parsed viur-actions envelope-v2 body.
+ * The wire carries `version` as the JSON number `2`; we also tolerate the
+ * string `"2"` defensively.
+ * @param {*} data
+ * @returns {boolean}
+ */
+export function isEnvelopeV2(data) {
+  return (
+    !!data && typeof data === "object" && !Array.isArray(data) && (data["version"] === 2 || data["version"] === "2")
+  )
+}
+
+/**
+ * Map a classic v1 `action` string (+ errors) to a v2 `(action, status)` pair.
+ * Inverse of vi-vue-utils' `v1ActionString`.
+ *
+ * - `addSuccess` / `editSuccess` / `cloneSuccess` / `deleteSuccess` / `moveSuccess` → the plain
+ *   verb with `status: "success"`.
+ * - `view` / `list` → the verb with `status: "success"` (a completed read).
+ * - any other verb (`add` / `edit` / `clone` / custom): `status: "rejected"`
+ *   when the response carries errors, else `status: "init"` (a freshly rendered
+ *   or in-flight form).
+ *
+ * @param {string|undefined} action v1 action string
+ * @param {Array|undefined} errors v1 errors array
+ * @returns {{ action: string, status: string }}
+ */
+function v2ActionStatus(action, errors) {
+  switch (action) {
+    case "addSuccess":
+      return { action: "add", status: "success" }
+    case "editSuccess":
+      return { action: "edit", status: "success" }
+    case "cloneSuccess":
+      return { action: "clone", status: "success" }
+    case "deleteSuccess":
+      return { action: "delete", status: "success" }
+    case "moveSuccess":
+      return { action: "move", status: "success" }
+  }
+
+  if (action === "view" || action === "list") {
+    return { action, status: "success" }
+  }
+
+  const status = Array.isArray(errors) && errors.length > 0 ? "rejected" : "init"
+  return { action: action ?? null, status }
+}
+
+/**
+ * Normalize a parsed response body to the canonical v2 envelope shape.
+ *
+ * - Bodies already in v2 pass through (only `errors`/`meta` are defensively
+ *   ensured).
+ * - Classic v1 bodies (carrying `skellist`, `values`, or a v1 `action`) are
+ *   lifted to v2: `data` (from `skellist`/`values`), `datatype`, `structure`,
+ *   `errors`, `follow`, `(action, status)` and — for lists — `meta`. The
+ *   original v1 fields are kept alongside, so the result is a superset and the
+ *   transform is idempotent.
+ * - Everything else (arrays, primitives, non-ViUR objects such as the skey list
+ *   or the `getStructure` map) passes through unchanged.
+ *
+ * @param {*} data parsed response body
+ * @returns {*} v2-shaped body (or the input unchanged)
+ */
+export function normalizeEnvelope(data) {
+  if (!data || typeof data !== "object" || Array.isArray(data)) {
+    return data
+  }
+
+  if (isEnvelopeV2(data)) {
+    const out = { ...data }
+    out["version"] = 2
+    out["errors"] = normalizeErrors(data["errors"])
+    if (data["datatype"] === "list" && !data["meta"]) {
+      out["meta"] = { cursor: data["cursor"] ?? null, orders: data["orders"] || [] }
+    }
+    return out
+  }
+
+  const isList = Array.isArray(data["skellist"])
+  const isEntity = "values" in data
+  const hasV1Action = typeof data["action"] === "string"
+
+  // Not a ViUR structured response (skey, getStructure map, custom payload):
+  // leave untouched.
+  if (!isList && !isEntity && !hasV1Action) {
+    return data
+  }
+
+  const out = { ...data }
+  out["version"] = 2
+  const { action, status } = v2ActionStatus(data["action"], data["errors"])
+  out["action"] = action
+  out["status"] = status
+  out["errors"] = normalizeErrors(data["errors"])
+  // Ziel des Schritts. v1 legt es je nach Stufe anderswo ab:
+  //   next_url          – vom Server gesetzt (z. B. Auswahl des zweiten Faktors)
+  //   params.action_url  – bei einem gerenderten Schritt, der selbst ein Ziel
+  //                        mitbringt (viur-core: der OTP-Schritt des zweiten
+  //                        Faktors kommt als `edit` mit action_url)
+  out["follow"] = data["follow"] ?? data["next_url"] ?? data["params"]?.["action_url"] ?? null
+  out["structure"] = data["structure"] ?? null
+
+  if (isList) {
+    out["datatype"] = "list"
+    out["data"] = data["skellist"]
+    out["meta"] = { cursor: data["cursor"] ?? null, orders: data["orders"] || [] }
+  } else {
+    out["datatype"] = "entity"
+    out["data"] = isEntity ? data["values"] : (data["data"] ?? null)
+  }
+
+  return out
+}

package/src/request/index.js

@@ -0,0 +1,35 @@
+export {
+  useAddFetch,
+  useCloneFetch,
+  usePreviewFetch,
+  useMoveFetch,
+  useListRootNodesFetch,
+  useDeleteFetch,
+  useEditFetch,
+  useListFetch,
+  useListFetchAll,
+  useTreeFetch,
+  useViewFetch,
+  useStructureFetch,
+  uploadFile,
+  downloadUrlFor,
+  serveUrlFor,
+  resetState,
+  HTTPError,
+  createControllerFetch,
+} from "./request.js"
+export { getCached, setCached, invalidateByKey, clearCache } from "./cache.js"
+export { skelDataToFormData, normalizeStructure } from "./skel.js"
+export { normalizeEnvelope, isEnvelopeV2, v1SelectionFollow } from "./envelope.js"
+export { useConfigStore, canAccessAdminConfig } from "./configStore.js"
+export {
+  buildModuleTree,
+  flattenModuleTree,
+  findModule,
+  visibleModuleTree,
+  hasModuleAccess,
+  handlerType,
+  normalizeModulePath,
+  baseModuleName,
+} from "./configStore.js"
+export { useMessageStore, getMessageStore, notify, requestMessage } from "./messageStore.js"

package/src/request/messageStore.js

@@ -0,0 +1,201 @@
+import { defineStore, getActivePinia } from "pinia"
+import { reactive, computed } from "vue"
+
+// --------------------------------------------------------------------------- //
+// Message store — user feedback (toasts / notifications)                      //
+// --------------------------------------------------------------------------- //
+//
+// A UI-agnostic queue of feedback messages: "entry saved", "login failed",
+// "request failed (500)". The REQUEST LAYER feeds it automatically (see
+// `notify()` and request.js): a successful POST (add/edit/delete/clone/move/
+// login/…) pushes a success, a rejected envelope or a HTTP error pushes an
+// error. Components may push their own messages as well.
+//
+// Opt-in by existence: `notify()` only does something when a Pinia instance is
+// active (`getActivePinia()`), i.e. the app installed Pinia. Without Pinia the
+// request layer works exactly as before. A single form can switch it off via
+// `<ViForm :use-message-store="false">`, any request via `ctx.messages = false`.
+//
+// Messages carry a translation `code` (e.g. "messages.request.edit.success")
+// plus a generic `fallbackCode`, so the rendering component decides the text:
+//   const text = te(m.code) ? t(m.code, m.params) : t(m.fallbackCode, m.params)
+// Optional `text` holds a ready-made string (e.g. a server error message).
+
+const DEFAULT_TIMEOUTS = { success: 5000, info: 5000, warning: 8000, error: 0 } // 0 = sticky
+
+let _nextId = 1
+
+export const useMessageStore = defineStore("viurMessages", () => {
+  const state = reactive({
+    messages: [],
+    timeouts: { ...DEFAULT_TIMEOUTS },
+    // keep at most this many messages; the oldest are dropped
+    max: 50,
+  })
+  const _timers = new Map()
+
+  const latest = computed(() => state.messages.at(-1) ?? null)
+  const errors = computed(() => state.messages.filter((m) => m.type === "error"))
+  const count = computed(() => state.messages.length)
+
+  function configure({ timeouts, max } = {}) {
+    if (timeouts) state.timeouts = { ...state.timeouts, ...timeouts }
+    if (typeof max === "number") state.max = max
+  }
+
+  /**
+   * Add a message. Returns the stored message (with `id`).
+   * @param {object} message
+   * @param {"success"|"error"|"warning"|"info"} [message.type]
+   * @param {string} [message.code] translation key
+   * @param {string} [message.fallbackCode] generic translation key
+   * @param {string|null} [message.text] ready-made text (wins over code in UIs)
+   * @param {object} [message.params] translation params
+   * @param {string|null} [message.module] controller path ("user", "shop.order")
+   * @param {string|null} [message.action] envelope action / endpoint
+   * @param {string|null} [message.key] entity key
+   * @param {Array} [message.errors] envelope errors
+   * @param {number|null} [message.status] HTTP status
+   * @param {number} [message.timeout] ms until auto-dismiss (0 = sticky)
+   */
+  function push(message) {
+    const type = message.type ?? "info"
+    const entry = {
+      id: _nextId++,
+      type,
+      code: message.code ?? null,
+      fallbackCode: message.fallbackCode ?? `messages.request.default.${type}`,
+      text: message.text ?? null,
+      params: message.params ?? {},
+      module: message.module ?? null,
+      action: message.action ?? null,
+      key: message.key ?? null,
+      errors: message.errors ?? [],
+      status: message.status ?? null,
+      timeout: message.timeout ?? state.timeouts[type] ?? 0,
+      timestamp: Date.now(),
+    }
+    state.messages.push(entry)
+    while (state.messages.length > state.max) {
+      const dropped = state.messages.shift()
+      _clearTimer(dropped.id)
+    }
+    if (entry.timeout > 0 && typeof setTimeout === "function") {
+      _timers.set(
+        entry.id,
+        setTimeout(() => remove(entry.id), entry.timeout)
+      )
+    }
+    return entry
+  }
+
+  const _shortcut =
+    (type) =>
+    (codeOrMessage, extra = {}) =>
+      push(typeof codeOrMessage === "string" ? { type, code: codeOrMessage, ...extra } : { ...codeOrMessage, type })
+  const success = _shortcut("success")
+  const error = _shortcut("error")
+  const warning = _shortcut("warning")
+  const info = _shortcut("info")
+
+  function _clearTimer(id) {
+    const timer = _timers.get(id)
+    if (timer) {
+      clearTimeout(timer)
+      _timers.delete(id)
+    }
+  }
+
+  function remove(id) {
+    _clearTimer(id)
+    const index = state.messages.findIndex((m) => m.id === id)
+    if (index !== -1) state.messages.splice(index, 1)
+  }
+
+  function clear(type = null) {
+    const keep = type ? state.messages.filter((m) => m.type !== type) : []
+    for (const m of state.messages) if (!keep.includes(m)) _clearTimer(m.id)
+    state.messages = keep
+  }
+
+  return { state, latest, errors, count, configure, push, success, error, warning, info, remove, clear }
+})
+
+/**
+ * The message store IF the app installed Pinia — else null. This is what makes
+ * the feedback opt-in by existence.
+ * @returns {ReturnType<typeof useMessageStore>|null}
+ */
+export function getMessageStore() {
+  try {
+    if (!getActivePinia()) return null
+    return useMessageStore()
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Push a message when a store exists; no-op otherwise. Used by the request
+ * layer so it never depends on Pinia being installed.
+ * @returns {object|null} the stored message or null
+ */
+export function notify(message) {
+  const store = getMessageStore()
+  return store ? store.push(message) : null
+}
+
+/**
+ * Build the feedback message for a finished request from its normalized
+ * envelope (or a HTTP error). Returns null when nothing should be shown
+ * (GET reads, form renders, intermediate multistep steps).
+ *
+ * @param {{ method: string, endpoint: string, module: string|null, body?: any, error?: Error|null }} info
+ */
+export function requestMessage({ method, endpoint, module, body = undefined, error = null }) {
+  if (error) {
+    const status = error.statusCode ?? error.status ?? null
+    return {
+      type: "error",
+      code: `messages.request.${endpoint}.error`,
+      fallbackCode: "messages.request.default.error",
+      text: error.message && !/^\d{3}$/.test(error.message) ? error.message : null,
+      params: { status, module, action: endpoint },
+      module,
+      action: endpoint,
+      status,
+    }
+  }
+  if (method.toUpperCase() === "POST") {
+    const isObject = body && typeof body === "object"
+    const action = (isObject && body.action) || endpoint
+    // a non-envelope body on a POST (e.g. v1 delete answers the string "OKAY")
+    // counts as success
+    const status = isObject ? body.status : "success"
+    const key = isObject ? (body.data?.key ?? null) : null
+    if (status === "success") {
+      return {
+        type: "success",
+        code: `messages.request.${action}.success`,
+        fallbackCode: "messages.request.default.success",
+        params: { module, action },
+        module,
+        action,
+        key,
+      }
+    }
+    if (status === "rejected") {
+      return {
+        type: "error",
+        code: `messages.request.${action}.rejected`,
+        fallbackCode: "messages.request.default.rejected",
+        params: { module, action, count: body.errors?.length ?? 0 },
+        module,
+        action,
+        key,
+        errors: body.errors ?? [],
+      }
+    }
+  }
+  return null
+}