@ui5/webcomponents-tools 2.28.1 → 2.29.0-rc.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md
CHANGED
|
@@ -3,6 +3,25 @@
|
|
|
3
3
|
All notable changes to this project will be documented in this file.
|
|
4
4
|
See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
|
|
5
5
|
|
|
6
|
+
# [2.29.0-rc.1](https://github.com/UI5/webcomponents/compare/v2.29.0-rc.0...v2.29.0-rc.1) (2026-11-10)
|
|
7
|
+
|
|
8
|
+
**Note:** Version bump only for package @ui5/webcomponents-tools
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
# [2.29.0-rc.0](https://github.com/UI5/webcomponents/compare/v2.28.1...v2.29.0-rc.0) (2026-10-30)
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
### Reverts
|
|
18
|
+
|
|
19
|
+
* Revert "chore(tools): remove postcss workaround for CSS container style queries" (#14203) ([aeaa29a](https://github.com/UI5/webcomponents/commit/aeaa29a82718aaad1fd7d6493f0b0e2fdc4ff670)), closes [#14203](https://github.com/UI5/webcomponents/issues/14203)
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
|
|
6
25
|
## [2.28.1](https://github.com/UI5/webcomponents/compare/v2.28.0...v2.28.1) (2026-10-21)
|
|
7
26
|
|
|
8
27
|
**Note:** Version bump only for package @ui5/webcomponents-tools
|
|
@@ -181,6 +181,7 @@ const getScripts = (options) => {
|
|
|
181
181
|
generateCEM: `ui5nps-script "${LIB}cem/cem.js" analyze --config "${LIB}cem/custom-elements-manifest.config.mjs"`,
|
|
182
182
|
validateCEM: `ui5nps-script "${LIB}cem/validate.js"`,
|
|
183
183
|
mergeCEM: `ui5nps-script "${LIB}cem/merge.mjs"`,
|
|
184
|
+
generateLLMs: `ui5nps-script "${LIB}cem/llms.mjs"`,
|
|
184
185
|
},
|
|
185
186
|
};
|
|
186
187
|
|
package/lib/cem/llms.mjs
ADDED
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
import path from "node:path";
|
|
2
|
+
import { pathToFileURL } from "node:url";
|
|
3
|
+
import { readFile, writeFile } from "node:fs/promises";
|
|
4
|
+
|
|
5
|
+
const packageNotes = {
|
|
6
|
+
"@ui5/webcomponents": "Primary components for forms, data display, navigation, and layouts.",
|
|
7
|
+
"@ui5/webcomponents-fiori": "SAP Fiori components such as ShellBar, DynamicPage, and SideNavigation. Use @ui5/webcomponents for primary controls.",
|
|
8
|
+
"@ui5/webcomponents-ai": "Components for AI-related interactions. This package is experimental and supports Horizon themes only; check the installed API before use.",
|
|
9
|
+
"@ui5/webcomponents-compat": "Deprecated since 2.12.0. For new applications, use Table from @ui5/webcomponents. Do not mix the main and compatibility Table implementations: they use overlapping tag names.",
|
|
10
|
+
};
|
|
11
|
+
|
|
12
|
+
const examples = {
|
|
13
|
+
"@ui5/webcomponents": ["Button", "ui5-button", "Save"],
|
|
14
|
+
"@ui5/webcomponents-fiori": ["ShellBar", "ui5-shellbar", ""],
|
|
15
|
+
"@ui5/webcomponents-ai": ["Button", "ui5-ai-button", "Generate"],
|
|
16
|
+
"@ui5/webcomponents-compat": ["Table", "ui5-table", ""],
|
|
17
|
+
};
|
|
18
|
+
|
|
19
|
+
function summarize(description = "") {
|
|
20
|
+
const paragraph = description.replace(/^#+[^\n]*$/gm, "").trim().split(/\n\s*\n/)[0];
|
|
21
|
+
const text = paragraph.replace(/<[^>]*>/g, "").replace(/`/g, "").replace(/\s+/g, " ").trim();
|
|
22
|
+
const summary = text.length > 240 ? `${text.slice(0, 240).replace(/\s+\S*$/, "")}…` : text;
|
|
23
|
+
return summary.replace(/\|/g, "\\|");
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
const main = async () => {
|
|
27
|
+
const packageJSON = JSON.parse(await readFile("package.json", "utf8"));
|
|
28
|
+
// Only the component packages opting into this task receive consumer guidance.
|
|
29
|
+
const note = packageNotes[packageJSON.name];
|
|
30
|
+
if (!note) {
|
|
31
|
+
throw new Error(`No consumer guidance configured for ${packageJSON.name}`);
|
|
32
|
+
}
|
|
33
|
+
const manifest = JSON.parse(await readFile(packageJSON.customElements, "utf8"));
|
|
34
|
+
const components = manifest.modules.flatMap(module => (module.declarations || [])
|
|
35
|
+
.filter(declaration => declaration.customElement && declaration.tagName)
|
|
36
|
+
.map(declaration => ({ ...declaration, module: module.path })))
|
|
37
|
+
.sort((a, b) => a.tagName.localeCompare(b.tagName));
|
|
38
|
+
if (!components.length) {
|
|
39
|
+
throw new Error(`No components found in ${packageJSON.customElements}`);
|
|
40
|
+
}
|
|
41
|
+
const [exampleModule, exampleTag, exampleText] = examples[packageJSON.name];
|
|
42
|
+
const rows = components.map(component =>
|
|
43
|
+
`| ${component.name} | \`${component.tagName}\` | \`${packageJSON.name}/${component.module}\` | ${summarize(component.description)}${component.deprecated ? " Deprecated; check the manifest for migration guidance." : ""} |`);
|
|
44
|
+
const content = `# ${packageJSON.name}
|
|
45
|
+
|
|
46
|
+
> Consumer guidance for applications using this npm package.
|
|
47
|
+
|
|
48
|
+
Version: ${packageJSON.version}
|
|
49
|
+
|
|
50
|
+
${note}
|
|
51
|
+
|
|
52
|
+
## Read the installed API
|
|
53
|
+
|
|
54
|
+
- [Public API manifest](./${packageJSON.customElements}): component tags, module paths, properties, attributes, events, slots, methods, CSS parts, and deprecations.
|
|
55
|
+
- [Package metadata](./package.json): installed version, dependencies, and exports.
|
|
56
|
+
- [Package README](./README.md): assets and package-specific setup.
|
|
57
|
+
- TypeScript declarations next to each component in dist provide additional type information.
|
|
58
|
+
- [Online documentation and examples](https://ui5.github.io/webcomponents/): check that examples apply to the installed version. Prefer the local manifest and declarations when versions differ.
|
|
59
|
+
|
|
60
|
+
Read the relevant component declaration before writing code. Do not invent properties, event names, slots, or methods. This index lists components in this package; inspect the corresponding installed package for other components.
|
|
61
|
+
|
|
62
|
+
## Usage conventions
|
|
63
|
+
|
|
64
|
+
- Import a component's JavaScript module to register its custom element, using the /dist/ paths below. Import child components used in your markup explicitly rather than assuming they are registered transitively.
|
|
65
|
+
- These are native web components. JSX wrappers from @ui5/webcomponents-react have a separate API and package; do not substitute wrapper props for native APIs.
|
|
66
|
+
- HTML attributes and JavaScript properties can have different names (for example, accessible-name and accessibleName). Use the manifest's attribute mapping. Boolean attributes are true when present; remove them for false rather than writing disabled="false". Assign arrays and objects through JavaScript properties or your framework's property binding.
|
|
67
|
+
- Use addEventListener with the documented DOM event name; read documented custom event payloads from event.detail. In frameworks, check their custom-element event binding syntax.
|
|
68
|
+
- Place children in the documented default or named slots. Use slot="name" for a named slot and the documented child component types.
|
|
69
|
+
- Import icons separately, for example import "@ui5/webcomponents-icons/dist/save.js" before using icon="save". Check the icon exists in the installed icon package.
|
|
70
|
+
- For themes and translations, follow the README's Assets.js setup and the application's bundler configuration.
|
|
71
|
+
- Use stable attribute selectors such as [ui5-button] in CSS and DOM queries to support tag-name scoping. Under scoping, create markup with the application's configured scoped tag names.
|
|
72
|
+
- Style with supported theme variables and documented CSS parts. Avoid depending on private shadow DOM structure.
|
|
73
|
+
- In TypeScript, use import type for component types when a separate side-effect import registers the element.
|
|
74
|
+
|
|
75
|
+
## Minimal registration example
|
|
76
|
+
|
|
77
|
+
\`\`\`js
|
|
78
|
+
import "${packageJSON.name}/dist/${exampleModule}.js";
|
|
79
|
+
\`\`\`
|
|
80
|
+
|
|
81
|
+
\`\`\`html
|
|
82
|
+
<${exampleTag}>${exampleText}</${exampleTag}>
|
|
83
|
+
\`\`\`
|
|
84
|
+
|
|
85
|
+
## Component index
|
|
86
|
+
|
|
87
|
+
Generated from the public manifest. Descriptions are abbreviated; consult the manifest for complete usage constraints and API details.
|
|
88
|
+
|
|
89
|
+
| Component | Tag | Import module | Purpose |
|
|
90
|
+
| --- | --- | --- | --- |
|
|
91
|
+
${rows.join("\n")}
|
|
92
|
+
|
|
93
|
+
## Discovering this file
|
|
94
|
+
|
|
95
|
+
Package documentation is not automatically loaded by every coding assistant. In your application's agent instructions, point to this installed package's llms.txt and ask the assistant to read it before using these components. Tools can resolve ${packageJSON.name}/llms.txt and read it as text.
|
|
96
|
+
|
|
97
|
+
Generated by @ui5/webcomponents-tools from the installed package metadata and public manifest. This file is a build artifact shipped in npm and ignored by Git. Maintainers: run yarn generateAPI from the repository root to refresh after API changes; edit packages/tools/lib/cem/llms.mjs for usage guidance.
|
|
98
|
+
`;
|
|
99
|
+
await writeFile("llms.txt", content, "utf8");
|
|
100
|
+
console.log(`Generated consumer guidance for ${packageJSON.name}`);
|
|
101
|
+
};
|
|
102
|
+
|
|
103
|
+
if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
|
|
104
|
+
main().catch(error => {
|
|
105
|
+
console.error(error);
|
|
106
|
+
process.exitCode = 1;
|
|
107
|
+
});
|
|
108
|
+
}
|
|
109
|
+
|
|
110
|
+
export default { _ui5mainFn: main };
|
|
@@ -5,6 +5,7 @@ import * as path from "path";
|
|
|
5
5
|
import { writeFile, mkdir } from "fs/promises";
|
|
6
6
|
import postcss from "postcss";
|
|
7
7
|
import combineDuplicatedSelectors from "../postcss-combine-duplicated-selectors/index.js"
|
|
8
|
+
import postcssPlugin from "./postcss-plugin.mjs";
|
|
8
9
|
import { writeFileIfChanged, getFileContent } from "./shared.mjs";
|
|
9
10
|
import scopeVariables from "./scope-variables.mjs";
|
|
10
11
|
import { mergeLightDark } from "./merge-light-dark.mjs";
|
|
@@ -74,7 +75,8 @@ const generate = async (argv) => {
|
|
|
74
75
|
const processComponentPackageFile = async (f) => {
|
|
75
76
|
if (CSS_VARIABLES_TARGET) {
|
|
76
77
|
const result = await postcss([
|
|
77
|
-
combineDuplicatedSelectors
|
|
78
|
+
combineDuplicatedSelectors,
|
|
79
|
+
postcssPlugin
|
|
78
80
|
]).process(f.text, { from: undefined });
|
|
79
81
|
|
|
80
82
|
return { css: result.css };
|
|
@@ -160,6 +162,7 @@ const generate = async (argv) => {
|
|
|
160
162
|
await esbuild.build(config);
|
|
161
163
|
}
|
|
162
164
|
}
|
|
165
|
+
|
|
163
166
|
/**
|
|
164
167
|
* Adds auto theme setup CSS: color-scheme declaration.
|
|
165
168
|
* @param {string} mergedCSS - The merged :root CSS from mergeLightDark()
|
|
@@ -0,0 +1,152 @@
|
|
|
1
|
+
|
|
2
|
+
import postcss from "postcss";
|
|
3
|
+
|
|
4
|
+
const hostVariables = new Map();
|
|
5
|
+
|
|
6
|
+
const SELECTOR = ":host";
|
|
7
|
+
|
|
8
|
+
const saveVariable = (variable, value, density) => {
|
|
9
|
+
if (!hostVariables.has(variable)) {
|
|
10
|
+
hostVariables.set(variable, {});
|
|
11
|
+
}
|
|
12
|
+
hostVariables.get(variable)[density] = value;
|
|
13
|
+
}
|
|
14
|
+
|
|
15
|
+
/**
|
|
16
|
+
* PostCSS plugin for handling CSS variables across density modes (cozy and compact).
|
|
17
|
+
*
|
|
18
|
+
* The plugin scans CSS for `:host` rules that define density-specific custom properties.
|
|
19
|
+
* Variables declared in a root-level `:host` rule are treated as **cozy** values, while
|
|
20
|
+
* variables declared inside `@ui5-compact-size` `:host` rules are treated as **compact** values.
|
|
21
|
+
*
|
|
22
|
+
* All discovered variables are merged into a single root `:host` rule. For variables that
|
|
23
|
+
* exist in both modes, the plugin generates a value that uses CSS variable fallbacks to
|
|
24
|
+
* dynamically switch between compact and cozy values based on the active density.
|
|
25
|
+
*
|
|
26
|
+
* Variables that exist in only one mode are preserved, with appropriate fallbacks added
|
|
27
|
+
* when needed.
|
|
28
|
+
*
|
|
29
|
+
* Example input:
|
|
30
|
+
*
|
|
31
|
+
* ```css
|
|
32
|
+
* :host {
|
|
33
|
+
* --my-variable: cozy-value;
|
|
34
|
+
* --cozy-only-variable: cozy-only-value;
|
|
35
|
+
* }
|
|
36
|
+
*
|
|
37
|
+
* @ui5-compact-size {
|
|
38
|
+
* :host {
|
|
39
|
+
* --my-variable: compact-value;
|
|
40
|
+
* --compact-only-variable: compact-only;
|
|
41
|
+
* }
|
|
42
|
+
* }
|
|
43
|
+
* ```
|
|
44
|
+
*
|
|
45
|
+
* Output:
|
|
46
|
+
*
|
|
47
|
+
* ```css
|
|
48
|
+
* :host {
|
|
49
|
+
* --my-variable: var(--_ui5-compact-size, compact-value) var(--_ui5-cozy-size, cozy-value);
|
|
50
|
+
* --compact-only-variable: var(--_ui5-compact-size, compact-only) var(--_ui5-cozy-size, initial);
|
|
51
|
+
* --cozy-only-variable: cozy-only-value;
|
|
52
|
+
* }
|
|
53
|
+
* ```
|
|
54
|
+
*
|
|
55
|
+
* This enables seamless runtime switching between density modes using CSS variables alone.
|
|
56
|
+
*/
|
|
57
|
+
|
|
58
|
+
export default function postcssPlugin() {
|
|
59
|
+
return {
|
|
60
|
+
postcssPlugin: 'postcss-content-density-variables',
|
|
61
|
+
Once(root) {
|
|
62
|
+
let hasRootHost = false;
|
|
63
|
+
let hostRule;
|
|
64
|
+
|
|
65
|
+
root.walkRules((rule) => {
|
|
66
|
+
// Only process :host rules
|
|
67
|
+
if (rule.selector !== SELECTOR) {
|
|
68
|
+
return;
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
// Handle root-level :host rules (cozy)
|
|
72
|
+
if (rule.parent.type === "root") {
|
|
73
|
+
if (!hasRootHost) {
|
|
74
|
+
hasRootHost = true;
|
|
75
|
+
hostRule = rule;
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
rule.walkDecls((decl) => {
|
|
79
|
+
if (decl.prop.startsWith('--')) {
|
|
80
|
+
saveVariable(decl.prop, decl.value, 'cozy');
|
|
81
|
+
decl.remove();
|
|
82
|
+
}
|
|
83
|
+
});
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
// Handle :host rules inside @ui5-compact-size (compact)
|
|
87
|
+
if (rule.parent.type === "atrule") {
|
|
88
|
+
if (rule.parent.name === "ui5-compact-size") {
|
|
89
|
+
rule.walkDecls((decl) => {
|
|
90
|
+
if (decl.prop.startsWith('--')) {
|
|
91
|
+
saveVariable(decl.prop, decl.value, 'compact');
|
|
92
|
+
decl.remove();
|
|
93
|
+
}
|
|
94
|
+
});
|
|
95
|
+
}
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
let current = rule;
|
|
99
|
+
// Remove up empty rules
|
|
100
|
+
while (current) {
|
|
101
|
+
if (current.nodes.length === 0) {
|
|
102
|
+
const parent = current.parent;
|
|
103
|
+
current.remove();
|
|
104
|
+
current = parent;
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
if (current.type === "root") {
|
|
108
|
+
break;
|
|
109
|
+
}
|
|
110
|
+
}
|
|
111
|
+
});
|
|
112
|
+
|
|
113
|
+
if (!hasRootHost) {
|
|
114
|
+
hostRule = postcss.rule({ selector: SELECTOR });
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
// Construct merged variable declarations depending on available modes
|
|
118
|
+
for (const [variable, variableData] of hostVariables) {
|
|
119
|
+
if (variableData.cozy && variableData.compact) {
|
|
120
|
+
hostRule.append({
|
|
121
|
+
prop: variable,
|
|
122
|
+
value: `var(--_ui5-compact-size, ${variableData.compact}) var(--_ui5-cozy-size, ${variableData.cozy})`,
|
|
123
|
+
});
|
|
124
|
+
} else if (variableData.compact) {
|
|
125
|
+
|
|
126
|
+
// Use a non-existent variable to always trigger the fallback.
|
|
127
|
+
// Because this variable is never defined, the fallback is used
|
|
128
|
+
// in all cases.
|
|
129
|
+
|
|
130
|
+
// Using `initial` as a fallback can work only for properties
|
|
131
|
+
// that treat it as an invalid value. To avoid this inconsistency,
|
|
132
|
+
// we intentionally reference an undefined variable, which is
|
|
133
|
+
// always considered invalid and undefined.
|
|
134
|
+
hostRule.append({
|
|
135
|
+
prop: variable,
|
|
136
|
+
value: `var(--_ui5-compact-size, ${variableData.compact}) var(--_ui5-cozy-size, var(--_ui5-f2d95f8))`,
|
|
137
|
+
});
|
|
138
|
+
} else {
|
|
139
|
+
hostRule.append({
|
|
140
|
+
prop: variable,
|
|
141
|
+
value: variableData.cozy,
|
|
142
|
+
});
|
|
143
|
+
}
|
|
144
|
+
}
|
|
145
|
+
|
|
146
|
+
root.prepend(hostRule);
|
|
147
|
+
hostVariables.clear();
|
|
148
|
+
}
|
|
149
|
+
}
|
|
150
|
+
}
|
|
151
|
+
|
|
152
|
+
postcssPlugin.postcss = true;
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@ui5/webcomponents-tools",
|
|
3
|
-
"version": "2.
|
|
3
|
+
"version": "2.29.0-rc.1",
|
|
4
4
|
"description": "UI5 Web Components: webcomponents.tools",
|
|
5
5
|
"author": "SAP SE (https://www.sap.com)",
|
|
6
6
|
"license": "Apache-2.0",
|
|
@@ -82,5 +82,5 @@
|
|
|
82
82
|
"esbuild": "^0.25.0",
|
|
83
83
|
"yargs": "^17.5.1"
|
|
84
84
|
},
|
|
85
|
-
"gitHead": "
|
|
85
|
+
"gitHead": "87edd7e1a7e71ff6b967b6102d5b31ae9c2b8287"
|
|
86
86
|
}
|