feat(framework): Custom Illustrations Documentation & API Enhancement

[kgogov]

This PR adds comprehensive documentation for registering custom illustrations with ui5-illustrated-message and introduces a safer template-based registration method.

What's New

1. Safe Registration API (registerIllustration)

• Uses JSX template functions instead of raw SVG strings
• Prevents XSS vulnerabilities
• Note: Only works in projects scaffolded with npm init @ui5/webcomponents-package. Otherwise, use unsafeRegisterIllustration.

Example:

import { registerIllustration } from "@ui5/webcomponents-base/dist/asset-registries/Illustrations.js";

registerIllustration("MyCustomFigure", {
  sceneTemplate: () => (
    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 320 200">
      <rect width="320" height="200" rx="14" fill="var(--sapContent_Illustrative_Color7)" />
      <circle cx="160" cy="100" r="50" fill="var(--sapContent_Illustrative_Color1)" />
    </svg>
  ),
  dialogTemplate: () => (
    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 160 160">
      <circle cx="80" cy="80" r="50" fill="var(--sapContent_Illustrative_Color1)" />
      <path d="M60 70 Q80 50 100 70" stroke="var(--sapContent_Illustrative_Color3)" strokeWidth="3" fill="none" />
    </svg>
  ),
  spotTemplate: () => (
    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 120 120">
      <circle cx="60" cy="60" r="30" fill="var(--sapContent_Illustrative_Color1)" />
    </svg>
  ),
  dotTemplate: () => (
    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 60 60">
      <circle cx="30" cy="30" r="15" fill="var(--sapContent_Illustrative_Color1)" />
    </svg>
  ),
  title: "Custom Illustration",
  subtitle: "Registered with JSX templates",
  set: "custom"
});

2. Unsafe Registration API (unsafeRegisterIllustration)

• Accepts raw SVG strings (with security warnings)
• Use when JSX templates aren't available

Example:

import { unsafeRegisterIllustration } from "@ui5/webcomponents-base/dist/asset-registries/Illustrations.js";
import dialogSvg from "./assets/custom-Dialog-MyIllustration.js";
import sceneSvg from "./assets/custom-Scene-MyIllustration.js";
import spotSvg from "./assets/custom-Spot-MyIllustration.js";
import dotSvg from "./assets/custom-Dot-MyIllustration.js";

unsafeRegisterIllustration("MyIllustration", {
  dialogSvg,
  sceneSvg,
  spotSvg,
  dotSvg,
  title: "My Custom Title",
  subtitle: "My Custom Subtitle",
  set: "custom"
});

3. Documentation

• Step-by-step instructions for both registration methods
• Security guidelines and best practices
• Examples for overriding title/subtitle

4. Usage

Example:

<ui5-illustrated-message name="custom/MyCustomFigure">
  <ui5-button design="Emphasized">Primary Action</ui5-button>
</ui5-illustrated-message>

[cla-assistant]

All committers have signed the CLA.

[Copilot]

Pull Request Overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 3 comments.

[ui5-webcomponents-bot]

🧹 Preview deployment cleaned up: https://pr-12260--ui5-webcomponents.netlify.app