builder/lib/tasks/generateThemeDesignerResources.js

  1. import posixPath from "node:path/posix";
  2. import {getLogger} from "@ui5/logger";
  3. const log = getLogger("builder:tasks:generateThemeDesignerResources");
  4. import libraryLessGenerator from "../processors/libraryLessGenerator.js";
  5. import {updateLibraryDotTheming} from "./utils/dotTheming.js";
  6. import ReaderCollectionPrioritized from "@ui5/fs/ReaderCollectionPrioritized";
  7. import Resource from "@ui5/fs/Resource";
  8. import fsInterface from "@ui5/fs/fsInterface";
  10. /**
  11.  * Returns a relative path from the given themeFolder to the root namespace.
  12.  *
  13.  * When combining the given themeFolder with the returned relative path it
  14.  * resolves to "/resources/". However the "/resources/" part is not important
  15.  * here as it doesn't exist within the theming engine environment where the
  16.  * UI5 resources are part of a "UI5" folder (e.g. "UI5/sap/ui/core/") that
  17.  * is next to a "Base" folder.
  18.  *
  19.  * @example
  20.  * getPathToRoot("/resources/sap/ui/foo/themes/base")
  21.  * > "../../../../../"
  22.  *
  23.  * @param {string} themeFolder Virtual path including /resources/
  24.  * @returns {string} Relative path to root namespace
  25.  */
  26. function getPathToRoot(themeFolder) {
  27. 	// -2 for initial "/"" and "resources/"
  28. 	return "../".repeat(themeFolder.split("/").length - 2);
  29. }
  31. /**
  32.  * Generates an less import statement for the given <code>filePath</code>
  33.  *
  34.  * @param {string} filePath The path to the desired file
  35.  * @returns {string} The less import statement
  36.  */
  37. function lessImport(filePath) {
  38. 	return `@import "${filePath}";\n`;
  39. }
  41. function generateLibraryDotTheming({namespace, version, hasThemes}) {
  42. 	const dotTheming = {
  43. 		sEntity: "Library",
  44. 		sId: namespace,
  45. 		sVersion: version
  46. 	};
  48. 	// Note that with sap.ui.core version 1.127.0 the .theming file has been put into
  49. 	// the library sources so that "aFiles" can be maintained from there.
  50. 	// The below configuration is still needed for older versions of sap.ui.core which do not
  51. 	// contain the file.
  52. 	if (namespace === "sap/ui/core") {
  53. 		dotTheming.aFiles = [
  54. 			"library",
  55. 			"global", // Additional entry compared to UI5 root .theming
  56. 			"css_variables",
  57. 		];
  58. 	}
  59. 	if (!hasThemes) {
  60. 		// Set ignore flag when there are no themes at all
  61. 		// This is important in case a library used to contain themes that have been removed
  62. 		// in a later version of the library.
  63. 		dotTheming.bIgnore = true;
  64. 	}
  66. 	return new Resource({
  67. 		path: `/resources/${namespace}/.theming`,
  68. 		string: JSON.stringify(dotTheming, null, 2)
  69. 	});
  70. }
  72. async function generateThemeDotTheming({workspace, combo, themeFolder}) {
  73. 	const themeName = posixPath.basename(themeFolder);
  74. 	const libraryMatchPattern = /^\/resources\/(.*)\/themes\/[^/]*$/i;
  75. 	const libraryMatch = libraryMatchPattern.exec(themeFolder);
  76. 	let libraryName;
  77. 	if (libraryMatch) {
  78. 		libraryName = libraryMatch[1].replace(/\//g, ".");
  79. 	} else {
  80. 		throw new Error(`Failed to extract library name from theme folder path: ${themeFolder}`);
  81. 	}
  83. 	const dotThemingTargetPath = posixPath.join(themeFolder, ".theming");
  84. 	if (libraryName === "sap.ui.core") {
  85. 		// sap.ui.core should always have a .theming file for all themes
  87. 		if (await workspace.byPath(dotThemingTargetPath)) {
  88. 			// .theming file present, skip further processing
  89. 			return;
  90. 		} else {
  91. 			throw new Error(`.theming file for theme ${themeName} missing in sap.ui.core library source`);
  92. 		}
  93. 	}
  95. 	let newDotThemingResource;
  96. 	const coreDotThemingResource = await combo.byPath(`/resources/sap/ui/core/themes/${themeName}/.theming`);
  98. 	if (coreDotThemingResource) {
  99. 		// Copy .theming file from core
  100. 		newDotThemingResource = await coreDotThemingResource.clone();
  101. 		newDotThemingResource.setPath(dotThemingTargetPath);
  102. 	} else {
  103. 		// No core .theming file found for this theme => Generate a .theming file
  104. 		const dotTheming = {
  105. 			sEntity: "Theme",
  106. 			sId: themeName,
  107. 			sVendor: "SAP"
  108. 		};
  110. 		if (themeName !== "base") {
  111. 			dotTheming.oExtends = "base";
  112. 		}
  114. 		newDotThemingResource = new Resource({
  115. 			path: dotThemingTargetPath,
  116. 			string: JSON.stringify(dotTheming, null, 2)
  117. 		});
  118. 	}
  119. 	return newDotThemingResource;
  120. }
  122. async function createCssVariablesLessResource({workspace, combo, themeFolder}) {
  123. 	const pathToRoot = getPathToRoot(themeFolder);
  124. 	const cssVariablesSourceLessFile = "css_variables.source.less";
  125. 	const cssVariablesLessFile = "css_variables.less";
  127. 	// posix as it is a virtual path (separated with /)
  128. 	const themeName = posixPath.basename(themeFolder);
  129. 	// The "base" theme of the baseLib is called "baseTheme"
  130. 	const baseLibThemeName = themeName === "base" ? "baseTheme" : themeName;
  132. 	// Some themes do not have a base.less file (e.g. sap_hcb)
  133. 	const hasBaseLess = !!(await combo.byPath(`/resources/sap/ui/core/themes/${themeName}/base.less`));
  135. 	let cssVariablesLess =
  136. `/* NOTE: This file was generated as an optimized version of "${cssVariablesSourceLessFile}" \
  137. for the Theme Designer. */\n\n`;
  139. 	if (themeName !== "base") {
  140. 		const cssVariablesSourceLessResource = await workspace.byPath(
  141. 			posixPath.join(themeFolder, cssVariablesSourceLessFile)
  142. 		);
  144. 		if (!cssVariablesSourceLessResource) {
  145. 			throw new Error(`Could not find file "${cssVariablesSourceLessFile}" in theme "${themeFolder}"`);
  146. 		}
  148. 		const cssVariablesSourceLess = await cssVariablesSourceLessResource.getString();
  150. 		cssVariablesLess += lessImport(`../base/${cssVariablesLessFile}`);
  151. 		cssVariablesLess += `
  152. /* START "${cssVariablesSourceLessFile}" */
  153. ${cssVariablesSourceLess}
  154. /* END "${cssVariablesSourceLessFile}" */
  156. `;
  157. 	}
  159. 	if (hasBaseLess) {
  160. 		cssVariablesLess += lessImport(`${pathToRoot}../Base/baseLib/${baseLibThemeName}/base.less`);
  161. 	}
  162. 	cssVariablesLess += lessImport(`${pathToRoot}sap/ui/core/themes/${themeName}/global.less`);
  164. 	return new Resource({
  165. 		path: posixPath.join(themeFolder, cssVariablesLessFile),
  166. 		string: cssVariablesLess
  167. 	});
  168. }
  170. async function generateCssVariablesLess({workspace, combo, namespace}) {
  171. 	let cssVariablesSourceLessResourcePattern;
  172. 	if (namespace) {
  173. 		// In case of a library only check for themes directly below the namespace
  174. 		cssVariablesSourceLessResourcePattern = `/resources/${namespace}/themes/*/css_variables.source.less`;
  175. 	} else {
  176. 		// In case of a theme-library check for all "themes"
  177. 		cssVariablesSourceLessResourcePattern = `/resources/**/themes/*/css_variables.source.less`;
  178. 	}
  180. 	const cssVariablesSourceLessResource = await workspace.byGlob(cssVariablesSourceLessResourcePattern);
  182. 	const hasCssVariables = cssVariablesSourceLessResource.length > 0;
  184. 	if (hasCssVariables) {
  185. 		await Promise.all(
  186. 			cssVariablesSourceLessResource.map(async (cssVariableSourceLess) => {
  187. 				const themeFolder = posixPath.dirname(cssVariableSourceLess.getPath());
  188. 				log.verbose(`Generating css_variables.less for theme ${themeFolder}`);
  189. 				const r = await createCssVariablesLessResource({
  190. 					workspace, combo, themeFolder
  191. 				});
  192. 				return await workspace.write(r);
  193. 			})
  194. 		);
  195. 	}
  196. }
  198. /**
  199.  * @public
  200.  * @module @ui5/builder/tasks/generateThemeDesignerResources
  201.  */
  203. /* eslint "jsdoc/check-param-names": ["error", {"disableExtraPropertyReporting":true}] */
  204. /**
  205.  * Generates resources required for integration with the SAP Theme Designer.
  206.  *
  207.  * @public
  208.  * @function default
  209.  * @static
  210.  *
  211.  * @param {object} parameters Parameters
  212.  * @param {@ui5/fs/DuplexCollection} parameters.workspace DuplexCollection to read and write files
  213.  * @param {@ui5/fs/AbstractReader} parameters.dependencies Reader or Collection to read dependency files
  214.  * @param {object} parameters.options Options
  215.  * @param {string} parameters.options.projectName Project name
  216.  * @param {string} parameters.options.version Project version
  217.  * @param {string} [parameters.options.projectNamespace] If the project is of type <code>library</code>,
  218.  * 														 provide its namespace.
  219.  * Omit for type <code>theme-library</code>
  220.  * @returns {Promise<undefined>} Promise resolving with <code>undefined</code> once data has been written
  221.  */
  222. export default async function({workspace, dependencies, options}) {
  223. 	const {projectName, version} = options;
  224. 	// Backward compatibility: "namespace" option got renamed to "projectNamespace"
  225. 	const namespace = options.projectNamespace || options.namespace;
  227. 	// Skip sap.ui.documentation since it is not intended to be available in SAP Theme Designer to create custom themes
  228. 	if (namespace === "sap/ui/documentation") {
  229. 		return;
  230. 	}
  232. 	let librarySourceLessPattern;
  233. 	if (namespace) {
  234. 		// In case of a library only check for themes directly below the namespace
  235. 		librarySourceLessPattern = `/resources/${namespace}/themes/*/library.source.less`;
  236. 	} else {
  237. 		// In case of a theme-library check for all "themes"
  238. 		librarySourceLessPattern = `/resources/**/themes/*/library.source.less`;
  239. 	}
  241. 	const librarySourceLessResources = await workspace.byGlob(librarySourceLessPattern);
  243. 	const hasThemes = librarySourceLessResources.length > 0;
  245. 	// library .theming file
  246. 	// Only for type "library". Type "theme-library" does not provide a namespace
  247. 	// Also needs to be created in case a library does not have any themes (see bIgnore flag)
  248. 	if (namespace) {
  249. 		let libraryDotThemingResource;
  251. 		// Do not generate a .theming file for the sap.ui.core library
  252. 		if (namespace === "sap/ui/core") {
  253. 			// Check if the .theming file already exists
  254. 			libraryDotThemingResource = await workspace.byPath(`/resources/${namespace}/.theming`);
  255. 			if (libraryDotThemingResource) {
  256. 				// Update the existing .theming resource
  257. 				log.verbose(`Updating .theming for namespace ${namespace}`);
  258. 				await updateLibraryDotTheming({
  259. 					resource: libraryDotThemingResource,
  260. 					namespace,
  261. 					version,
  262. 					hasThemes
  263. 				});
  264. 			}
  265. 		}
  267. 		if (!libraryDotThemingResource) {
  268. 			log.verbose(`Generating .theming for namespace ${namespace}`);
  269. 			libraryDotThemingResource = generateLibraryDotTheming({
  270. 				namespace,
  271. 				version,
  272. 				hasThemes
  273. 			});
  274. 		}
  276. 		await workspace.write(libraryDotThemingResource);
  277. 	}
  279. 	if (!hasThemes) {
  280. 		// Skip further processing as there are no themes
  281. 		return;
  282. 	}
  284. 	const combo = new ReaderCollectionPrioritized({
  285. 		name: `generateThemeDesignerResources - prioritize workspace over dependencies: ${projectName}`,
  286. 		readers: [workspace, dependencies]
  287. 	});
  289. 	// theme .theming files
  290. 	const themeDotThemingFiles = await Promise.all(
  291. 		librarySourceLessResources.map((librarySourceLess) => {
  292. 			const themeFolder = posixPath.dirname(librarySourceLess.getPath());
  293. 			log.verbose(`Generating .theming for theme ${themeFolder}`);
  294. 			return generateThemeDotTheming({
  295. 				workspace, combo, themeFolder
  296. 			});
  297. 		})
  298. 	);
  299. 	await Promise.all(
  300. 		themeDotThemingFiles.map(async (resource) => {
  301. 			if (resource) {
  302. 				await workspace.write(resource);
  303. 			}
  304. 		})
  305. 	);
  307. 	// library.less files
  308. 	const libraryLessResources = await libraryLessGenerator({
  309. 		resources: librarySourceLessResources,
  310. 		fs: fsInterface(combo),
  311. 	});
  312. 	await Promise.all(
  313. 		libraryLessResources.map((resource) => workspace.write(resource))
  314. 	);
  316. 	// css_variables.less
  317. 	await generateCssVariablesLess({workspace, combo, namespace});
  318. }