jmapcloud-ng-core-types 2.0.13-qa.6 → 2.0.13-qa.7

package/index.d.ts

@@ -25,7 +25,7 @@ export type {
   JUIState,
   JUserState
 } from "./public/state.d.ts"
-export type { JAppConfirmMessage, JAppMessage, JAppMessageOptions, JAppMessageService, JAppMessageState, JAppOverlayMessage } from "./public/jmap/message.d.ts"
+export type { JAppConfirmMessage, JAppMessage, JAppMessageOptions, JAppMessageService, JAppMessageState, JAppOverlayMessage, JAppRenderableMessage } from "./public/jmap/message.d.ts"
 export type { JAppUserAction } from "./public/jmap/user.d.ts"
 
 export interface JCoreService extends JCoreMainService {

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "jmapcloud-ng-core-types",
-  "version": "2.0.13-qa.6",
+  "version": "2.0.13-qa.7",
   "description": "JMap Cloud specific version of JMap Cloud NG Core types and interfaces",
   "main": "index.js",
   "types": "ambient.d.ts",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1",
-    "update-types-bridge": "node build/codemod-export-globals.js && node build/auto-add-imports.js && node build/generate-ambient.js && npx prettier --write public/global-aliases.d.ts ambient.d.ts",
+    "update-types-bridge": "node build/codemod-export-globals.js && node build/auto-add-imports.js && node build/generate-ambient.js && node ../../../node_modules/prettier/bin/prettier.cjs --write public/global-aliases.d.ts ambient.d.ts",
     "pub-github": "npm run update-types-bridge && node build/buildfile.js publish-github;",
     "doc-test": "npm run update-types-bridge && node build/buildfile.js doc-test;"
   },

package/public/global-aliases.d.ts

@@ -364,6 +364,7 @@ declare global {
   /** @internal */ const MESSAGE_ACTION_TYPES: typeof message.MESSAGE_ACTION_TYPES
   /** @internal */ type JAppMessage = message.JAppMessage
   /** @internal */ type JAppOverlayMessage = message.JAppOverlayMessage
+  /** @internal */ type JAppRenderableMessage = message.JAppRenderableMessage
   /** @internal */ type JAppConfirmMessage = message.JAppConfirmMessage
   /** @internal */ type JAppMessageOptions = message.JAppMessageOptions
   /** @internal */ type JAppMessageState = message.JAppMessageState

package/public/jmap/message.d.ts

@@ -1,4 +1,5 @@
 import type { JLOCALES } from "./language.d.ts"
+import type { ReactNode } from "react"
 export {}
 
 // ALL_APP_MESSAGE_SEVERITIES in all-enums.ts
@@ -33,8 +34,59 @@ export interface JAppOverlayMessage {
   text: string
 }
 
+/**
+ * Explicit message content modes for NG.
+ *
+ * Three explicit content modes are supported:
+ *
+ * 1. Plain text
+ *    `{ kind: "text", value: "Delete project foo?" }`
+ *    Render as inert text with no HTML interpretation.
+ *
+ * 2. Sanitized HTML
+ *    `{ kind: "html", value: "Delete <b>foo</b>?<br>Please confirm.", policy: "dialog" }`
+ *    Use only when intentionally rendering an HTML string. The renderer must
+ *    sanitize the string before display. This is especially useful for
+ *    translated rich messages, for example:
+ *    `{ kind: "html", value: JMap.Language.translate("project.delete.message", { projectName: "<b>My project</b>" }), policy: "dialog" }`
+ *
+ * 3. React node / JSX
+ *    `{ kind: "node", value: <>Delete <strong>{project.name}</strong>?</> }`
+ *    Preferred when formatting is needed, because React escapes interpolated
+ *    values automatically and avoids raw HTML string construction.
+ */
+export type JAppRenderableMessage =
+  | {
+      kind: "html"
+      policy?: "dialog" | "presentation"
+      value: string
+    }
+  | {
+      kind: "node"
+      value: ReactNode
+    }
+  | {
+      kind: "text"
+      value: string
+    }
+
 export interface JAppConfirmMessage {
-  message: string
+  /**
+   * Bare `string` means plain text by default.
+   *
+   * Explicit rich-content forms are:
+   * - `{ kind: "text", value }` for plain text
+   * - `{ kind: "html", value, policy }` for intentionally rich HTML that must
+   *   be sanitized by the renderer, for example a rich message produced by
+   *   `JMap.Language.translate(...)`
+   * - `{ kind: "node", value }` for JSX / ReactNode content
+   *
+   * Guidance:
+   * - default to plain text
+   * - prefer `node` when formatting is needed
+   * - use `html` only for legacy / translated HTML-string flows
+   */
+  message: JAppRenderableMessage | string
   title: string
   isInputMessage?: boolean
   isInputOptional?: boolean
@@ -58,6 +110,20 @@ export interface JAppMessageState {
 }
 
 export interface JAppMessageService {
+  /**
+   * Confirm message content supports three intended modes:
+   *
+   * - plain text:
+   *   `message: "Delete project foo?"`
+   *
+   * - sanitized HTML string:
+   *   `message: { kind: "html", value: "Delete <b>foo</b>?", policy: "dialog" }`
+   *
+   * - JSX / ReactNode:
+   *   `message: { kind: "node", value: <>Delete <strong>{project.name}</strong>?</> }`
+   *
+   * Plain text is the default.
+   */
   error(message: string, options?: JAppMessageOptions): void
   warning(message: string, options?: JAppMessageOptions): void
   info(message: string, options?: JAppMessageOptions): void