@ui5/webcomponents-base 0.0.0-47cc17a26 → 0.0.0-49bade48d

package/AGENTS.md

@@ -0,0 +1,195 @@
+# AGENTS.md - UI5 Web Components Development Guide
+
+This file provides guidance for AI coding assistants when developing web components built on `@ui5/webcomponents-base`.
+
+> **Working in the ui5-webcomponents monorepo?** See the [root AGENTS.md](../../AGENTS.md) for repository commands, build flow, and commit guidelines.
+
+## Component Architecture
+
+Components use decorator-based definitions with Preact JSX templates:
+
+```typescript
+import UI5Element from "@ui5/webcomponents-base/dist/UI5Element.js";
+import { customElement, property, slot } from "@ui5/webcomponents-base/dist/decorators.js";
+import jsxRenderer from "@ui5/webcomponents-base/dist/renderer/JsxRenderer.js";
+
+@customElement({
+  tag: "my-button",
+  renderer: jsxRenderer,
+  template: MyButtonTemplate,
+  styles: myButtonCss,
+  languageAware: true,  // Re-render on language change
+  themeAware: true,     // Re-render on theme change
+})
+class MyButton extends UI5Element {
+  @property() design: `${ButtonDesign}` = "Default";
+  @property({ type: Boolean }) disabled = false;
+  @slot({ type: HTMLElement, "default": true }) content!: Array<HTMLElement>;
+}
+```
+
+**Recommended file structure for a component:**
+- `src/ComponentName.ts` - Component class with decorators
+- `src/ComponentNameTemplate.tsx` - JSX template
+- `src/themes/ComponentName.css` - Styles (use CSS variables for theming)
+- `src/i18n/messagebundle*.properties` - Translations (if language-aware)
+
+## Critical Development Rules
+
+### DOM Manipulation Anti-Pattern
+
+Accessing DOM elements via `@query` or `querySelector` is allowed only for calling methods like `.focus()`:
+
+```typescript
+@query("[ui5-input]")
+_input!: Input;
+
+// GOOD - calling methods
+this._input?.focus();
+
+// BAD - modifying properties directly
+this._input.value = "don't do this";
+```
+
+Always modify child component state through the template:
+
+```tsx
+// GOOD - use the template for state
+<Input value={this.inputValue} />
+```
+
+### Always Use Template Literal Types for Enums
+
+This pattern eliminates runtime overhead from enum objects:
+
+**Imports:**
+```typescript
+// BAD - imports the enum object (runtime overhead)
+import ButtonDesign from "./types/ButtonDesign.js";
+
+// GOOD - import type only (no runtime overhead)
+import type ButtonDesign from "./types/ButtonDesign.js";
+```
+
+**Property types:**
+```typescript
+// BAD - uses enum object at runtime
+design: ButtonDesign = ButtonDesign.Default;
+
+// GOOD - template literal type with string value
+design: `${ButtonDesign}` = "Default";
+```
+
+**Value comparisons:**
+```typescript
+// BAD - runtime enum access
+if (this.design !== ButtonDesign.Transparent) { }
+
+// GOOD - string comparison (IDE autocomplete + TS type safety)
+if (this.design !== "Transparent") { }
+```
+
+### Scoping-Safe Code (Required for Micro-Frontend Support)
+
+UI5 Web Components support tag name scoping for micro-frontend scenarios where multiple versions may coexist. Always use attribute selectors:
+
+**In TypeScript:**
+```typescript
+// BAD - hard-coded tag names break when scoped
+this.shadowRoot.querySelector("ui5-popover")
+element.tagName === "UI5-BUTTON"
+
+// GOOD - attribute selectors work with any scoping
+this.shadowRoot.querySelector("[ui5-popover]")
+```
+
+**In CSS:**
+```css
+/* BAD - tag selector breaks with scoping */
+ui5-button.accept-btn { color: green; }
+
+/* GOOD - attribute selector works with scoping */
+[ui5-button].accept-btn { color: green; }
+```
+
+### No `instanceof` Checks
+
+`instanceof` fails when multiple versions of the framework are loaded. Use duck-typing instead:
+
+```typescript
+// BAD - fails with multiple framework versions
+if (element instanceof Button) { }
+
+// BAD - tag name could be scoped (e.g., "UI5-BUTTON-F5331039")
+if (element.tagName === "UI5-BUTTON") { }
+
+// GOOD - use createInstanceChecker helper
+import createInstanceChecker from "@ui5/webcomponents-base/dist/util/createInstanceChecker.js";
+
+// In your component class:
+class MyItem extends UI5Element {
+  readonly isMyItem = true;  // Duck-typing marker
+}
+export const isInstanceOfMyItem = createInstanceChecker<MyItem>("isMyItem");
+
+// Usage:
+if (isInstanceOfMyItem(element)) {
+  // element is typed as MyItem
+}
+```
+
+### Property and Event Conventions
+
+- **Never change public properties programmatically** - only in response to user interaction
+- **Use `noAttribute: true`** for private/internal properties not used in CSS selectors
+- **Fire events for all user interactions** - applications rely on events for state management
+- **Import icons explicitly** - don't rely on bundled icon imports
+
+```typescript
+@property({ noAttribute: true })
+_internalState = false;  // Won't create HTML attribute
+
+// Fire events for user interactions
+this.fireDecoratorEvent("change", { value: this.value });
+```
+
+## Testing with Cypress
+
+Tests use Cypress component testing with JSX mounting:
+
+```typescript
+import MyButton from "../../src/MyButton.js";
+
+describe("MyButton", () => {
+  it("fires click event", () => {
+    cy.mount(<MyButton>Click me</MyButton>);
+
+    // Use attribute selector for scoping safety
+    cy.get("[my-button]").then(($btn) => {
+      $btn[0].addEventListener("click", cy.stub().as("clicked"));
+    });
+
+    // Use cypress-real-events for realistic interaction
+    cy.get("[my-button]").realClick();
+    cy.get("@clicked").should("have.been.called");
+  });
+});
+```
+
+**Key testing patterns:**
+- Use `cypress-real-events`: `realClick()`, `realPress()`, `realType()` instead of Cypress simulated events
+- Always use attribute selectors `[my-component]` not tag selectors `my-component`
+- Use `.only` to run a single test case when debugging, remove before committing
+
+## Summary of Rules
+
+| Rule | Bad | Good |
+|------|-----|------|
+| Enum imports | `import Enum from "..."` | `import type Enum from "..."` |
+| Enum types | `prop: Enum` | `prop: \`${Enum}\`` |
+| Enum values | `Enum.Value` | `"Value"` |
+| DOM queries | `querySelector("ui5-tag")` | `querySelector("[ui5-tag]")` |
+| CSS selectors | `ui5-tag { }` | `[ui5-tag] { }` |
+| Type checks | `instanceof Component` | `isInstanceOfComponent(el)` |
+| Tag comparison | `el.tagName === "UI5-TAG"` | Use instance checker |
+| DOM mutation | `this._ref.value = x` | `<Comp value={x} />` in template |

package/CHANGELOG.md

@@ -3,7 +3,368 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
-# [0.0.0-47cc17a26](https://github.com/UI5/webcomponents/compare/v2.17.0-rc.1...v0.0.0-47cc17a26) (2025-11-07)
+# [0.0.0-49bade48d](https://github.com/UI5/webcomponents/compare/v2.23.0-rc.1...v0.0.0-49bade48d) (2026-06-01)
+
+
+### Bug Fixes
+
+* **framework:** prevent language-aware components from rendering before CLDR data loads ([#13602](https://github.com/UI5/webcomponents/issues/13602)) ([441672b](https://github.com/UI5/webcomponents/commit/441672b62733b42f4fc1a12452711602ae6a1bb5))
+
+
+### Features
+
+* **ui5-*:** support `autofocus` attribute ([#12572](https://github.com/UI5/webcomponents/issues/12572)) ([b13a00a](https://github.com/UI5/webcomponents/commit/b13a00aed10f7c230f171551923af57a413a458a))
+
+
+
+
+
+# [2.23.0-rc.1](https://github.com/UI5/webcomponents/compare/v2.23.0-rc.0...v2.23.0-rc.1) (2026-05-28)
+
+**Note:** Version bump only for package @ui5/webcomponents-base
+
+
+
+
+
+# [2.23.0-rc.0](https://github.com/UI5/webcomponents/compare/v2.22.1-rc.0...v2.23.0-rc.0) (2026-05-23)
+
+**Note:** Version bump only for package @ui5/webcomponents-base
+
+
+
+
+
+## [2.22.1-rc.0](https://github.com/UI5/webcomponents/compare/v2.22.0-rc.6...v2.22.1-rc.0) (2026-05-21)
+
+**Note:** Version bump only for package @ui5/webcomponents-base
+
+
+
+
+
+# [2.22.0](https://github.com/UI5/webcomponents/compare/v2.22.0-rc.4...v2.22.0) (2026-05-11)
+
+
+### Bug Fixes
+
+* **OpenUI5Support:** css variables detection ([#13465](https://github.com/UI5/webcomponents/issues/13465)) ([a43e2de](https://github.com/UI5/webcomponents/commit/a43e2dec8dc09bd3955c4c5a0795e8b7a6534dc5))
+
+
+
+
+
+# [2.22.0-rc.4](https://github.com/UI5/webcomponents/compare/v2.22.0-rc.3...v2.22.0-rc.4) (2026-05-07)
+
+
+### Bug Fixes
+
+* validate correctly protocol relative urls ([#13447](https://github.com/UI5/webcomponents/issues/13447)) ([c765630](https://github.com/UI5/webcomponents/commit/c7656304d7a3ad74c2c58d6937163262c4f40177))
+
+
+
+
+
+# [2.22.0-rc.3](https://github.com/UI5/webcomponents/compare/v2.22.0-rc.2...v2.22.0-rc.3) (2026-04-30)
+
+**Note:** Version bump only for package @ui5/webcomponents-base
+
+
+
+
+
+# [2.22.0-rc.2](https://github.com/UI5/webcomponents/compare/v2.22.0-rc.1...v2.22.0-rc.2) (2026-04-23)
+
+**Note:** Version bump only for package @ui5/webcomponents-base
+
+
+
+
+
+# [2.22.0-rc.1](https://github.com/UI5/webcomponents/compare/v2.22.0-rc.0...v2.22.0-rc.1) (2026-04-16)
+
+**Note:** Version bump only for package @ui5/webcomponents-base
+
+
+
+
+
+# [2.22.0-rc.0](https://github.com/UI5/webcomponents/compare/v2.21.0...v2.22.0-rc.0) (2026-04-09)
+
+**Note:** Version bump only for package @ui5/webcomponents-base
+
+
+
+
+
+# [2.21.0](https://github.com/UI5/webcomponents/compare/v2.21.0-rc.4...v2.21.0) (2026-04-07)
+
+
+### Bug Fixes
+
+* **framework:** improve themeRoot validation ([#13354](https://github.com/UI5/webcomponents/issues/13354)) ([ba4a08b](https://github.com/UI5/webcomponents/commit/ba4a08bd516f1e0dbefe2dfc734a684c6af50bd8))
+
+
+### Features
+
+* **ui5-button:** introduce support for form attribute ([#13321](https://github.com/UI5/webcomponents/issues/13321)) ([c9d8f2a](https://github.com/UI5/webcomponents/commit/c9d8f2ac91d5b5320e37aeee5e60b571ff3ee07c)), closes [#7459](https://github.com/UI5/webcomponents/issues/7459)
+
+
+
+
+
+# [2.21.0-rc.4](https://github.com/UI5/webcomponents/compare/v2.21.0-rc.3...v2.21.0-rc.4) (2026-04-02)
+
+
+### Features
+
+* update sap/icons to v5.12 & 4.24 ([#13319](https://github.com/UI5/webcomponents/issues/13319)) ([0b16434](https://github.com/UI5/webcomponents/commit/0b164348069b96f5464eaea3425a4876097dc44d))
+
+
+
+
+
+# [2.21.0-rc.3](https://github.com/UI5/webcomponents/compare/v2.21.0-rc.2...v2.21.0-rc.3) (2026-03-26)
+
+
+### Features
+
+* **ui5-combobox:** add suggestion highlight of matching characters ([#13282](https://github.com/UI5/webcomponents/issues/13282)) ([05c1e08](https://github.com/UI5/webcomponents/commit/05c1e087cdf655f593101d7a549f5141cf9eb7cb))
+
+
+
+
+
+# [2.21.0-rc.2](https://github.com/UI5/webcomponents/compare/v2.21.0-rc.1...v2.21.0-rc.2) (2026-03-19)
+
+
+### Features
+
+* **base:** propagate theme and language changes across runtimes ([#13296](https://github.com/UI5/webcomponents/issues/13296)) ([5fe24d1](https://github.com/UI5/webcomponents/commit/5fe24d1e3557c85d557139371ac6d06c274bd5cb))
+
+
+
+
+
+# [2.21.0-rc.1](https://github.com/UI5/webcomponents/compare/v2.21.0-rc.0...v2.21.0-rc.1) (2026-03-19)
+
+**Note:** Version bump only for package @ui5/webcomponents-base
+
+
+
+
+
+# [2.21.0-rc.0](https://github.com/UI5/webcomponents/compare/v2.20.0...v2.21.0-rc.0) (2026-03-12)
+
+
+### Bug Fixes
+
+* **ui5-base:** scope all registered tags by default ([#13198](https://github.com/UI5/webcomponents/issues/13198)) ([ed08bf3](https://github.com/UI5/webcomponents/commit/ed08bf350b660c9d0a86468da03194a2c84a5622))
+
+
+### Features
+
+* **ui5-base:** store import.meta.url in runtime registration data ([#13235](https://github.com/UI5/webcomponents/issues/13235)) ([13b71d5](https://github.com/UI5/webcomponents/commit/13b71d5608f3e310684bae171f6255a0325ace62))
+
+
+
+
+
+# [2.20.0](https://github.com/UI5/webcomponents/compare/v2.20.0-rc.3...v2.20.0) (2026-03-05)
+
+**Note:** Version bump only for package @ui5/webcomponents-base
+
+
+
+
+
+# [2.20.0-rc.3](https://github.com/UI5/webcomponents/compare/v2.20.0-rc.2...v2.20.0-rc.3) (2026-03-05)
+
+
+### Features
+
+* **ui5-multi-combobox:** introduce selectedValues property ([#12987](https://github.com/UI5/webcomponents/issues/12987)) ([bbe792b](https://github.com/UI5/webcomponents/commit/bbe792bc3dad9b21fdca9cb7a588a473e2ebdfff))
+
+
+
+
+
+# [2.20.0-rc.2](https://github.com/UI5/webcomponents/compare/v2.20.0-rc.1...v2.20.0-rc.2) (2026-02-26)
+
+
+### Bug Fixes
+
+* CSS variables scoping to depend VersionInfo ([#13091](https://github.com/UI5/webcomponents/issues/13091)) ([d2e43ed](https://github.com/UI5/webcomponents/commit/d2e43ed692c63a0a36a9b14da59de354e2e7d0b0))
+* **DnD:** fix drag and drop in iOS Safari browser ([#13129](https://github.com/UI5/webcomponents/issues/13129)) ([849215f](https://github.com/UI5/webcomponents/commit/849215f36224f55416c8b291a7abe683dbcee44c))
+
+
+
+
+
+# [2.20.0-rc.1](https://github.com/UI5/webcomponents/compare/v2.20.0-rc.0...v2.20.0-rc.1) (2026-02-19)
+
+
+### Bug Fixes
+
+* **framework:** apply correct system css variables ([#13085](https://github.com/UI5/webcomponents/issues/13085)) ([123efed](https://github.com/UI5/webcomponents/commit/123efed9705ddde81aedf9f3571ce1e0b89e61c8))
+* **framework:** correct runtime compare ([#13105](https://github.com/UI5/webcomponents/issues/13105)) ([eb8cc19](https://github.com/UI5/webcomponents/commit/eb8cc1978db1f4f2352e2f0a77569d7216301c3e))
+
+
+
+
+
+# [2.20.0-rc.0](https://github.com/UI5/webcomponents/compare/v2.19.0...v2.20.0-rc.0) (2026-02-12)
+
+**Note:** Version bump only for package @ui5/webcomponents-base
+
+
+
+
+
+# [2.19.0](https://github.com/UI5/webcomponents/compare/v2.19.0-rc.3...v2.19.0) (2026-02-05)
+
+**Note:** Version bump only for package @ui5/webcomponents-base
+
+
+
+
+
+# [2.19.0-rc.3](https://github.com/UI5/webcomponents/compare/v2.19.0-rc.2...v2.19.0-rc.3) (2026-02-05)
+
+
+### Bug Fixes
+
+* **framework:** prevent redundant invalidations ([#12994](https://github.com/UI5/webcomponents/issues/12994)) ([b6c582c](https://github.com/UI5/webcomponents/commit/b6c582c93e5a260044fefc1612c8f037744aca97))
+* **input like:** correct form submission behaviour ([#12959](https://github.com/UI5/webcomponents/issues/12959)) ([cd02ead](https://github.com/UI5/webcomponents/commit/cd02ead56026bb69acc4661442d30b24ed81ff6c))
+
+
+
+
+
+# [2.19.0-rc.2](https://github.com/UI5/webcomponents/compare/v2.19.0-rc.1...v2.19.0-rc.2) (2026-01-22)
+
+**Note:** Version bump only for package @ui5/webcomponents-base
+
+
+
+
+
+# [2.19.0-rc.1](https://github.com/UI5/webcomponents/compare/v2.19.0-rc.0...v2.19.0-rc.1) (2026-01-15)
+
+
+### Bug Fixes
+
+* **framework:** call `appyTheme` on delayed theme registration after framework `boot` ([#12787](https://github.com/UI5/webcomponents/issues/12787)) ([42611e9](https://github.com/UI5/webcomponents/commit/42611e92c2e06504a2952ce0c6574891c4971d40))
+
+
+### Features
+
+* **framework:** detect dynamically loaded OpenUI5 ([#12235](https://github.com/UI5/webcomponents/issues/12235)) ([2292ffd](https://github.com/UI5/webcomponents/commit/2292ffd404da8a59229abdc24b1edb4bf428f7cf))
+
+
+
+
+
+# [2.19.0-rc.0](https://github.com/UI5/webcomponents/compare/v2.18.0...v2.19.0-rc.0) (2026-01-08)
+
+**Note:** Version bump only for package @ui5/webcomponents-base
+
+
+
+
+
+# [2.18.0](https://github.com/UI5/webcomponents/compare/v2.18.0-rc.3...v2.18.0) (2026-01-05)
+
+**Note:** Version bump only for package @ui5/webcomponents-base
+
+
+
+
+
+# [2.18.0-rc.3](https://github.com/UI5/webcomponents/compare/v2.18.0-rc.2...v2.18.0-rc.3) (2026-01-01)
+
+**Note:** Version bump only for package @ui5/webcomponents-base
+
+
+
+
+
+# [2.18.0-rc.2](https://github.com/UI5/webcomponents/compare/v2.18.0-rc.1...v2.18.0-rc.2) (2025-12-25)
+
+**Note:** Version bump only for package @ui5/webcomponents-base
+
+
+
+
+
+# [2.18.0-rc.1](https://github.com/UI5/webcomponents/compare/v2.18.0-rc.0...v2.18.0-rc.1) (2025-12-18)
+
+**Note:** Version bump only for package @ui5/webcomponents-base
+
+
+
+
+
+# [2.18.0-rc.0](https://github.com/UI5/webcomponents/compare/v2.17.0...v2.18.0-rc.0) (2025-12-11)
+
+
+### Bug Fixes
+
+* **ui5-popover:** render block layers in the correct order ([#12659](https://github.com/UI5/webcomponents/issues/12659)) ([43e545a](https://github.com/UI5/webcomponents/commit/43e545a4a5e486f19fb52ae18fe7c162680cf56e))
+
+
+
+
+
+# [2.17.0](https://github.com/UI5/webcomponents/compare/v2.17.0-rc.5...v2.17.0) (2025-12-05)
+
+
+### Reverts
+
+* Revert "feat(framework): scope theming css variables with component packages (#12491)" (#12775) ([3385623](https://github.com/UI5/webcomponents/commit/33856235e357a3d4d0b9391eab2a83a5b3010556)), closes [#12491](https://github.com/UI5/webcomponents/issues/12491) [#12775](https://github.com/UI5/webcomponents/issues/12775)
+* Revert "feat(framework): introduce loadBaseThemingCSSVariables configuration (#12699)" (#12767) ([db375d3](https://github.com/UI5/webcomponents/commit/db375d30b9f4a7e07961fabbdcefdcdc78a93f46)), closes [#12699](https://github.com/UI5/webcomponents/issues/12699) [#12767](https://github.com/UI5/webcomponents/issues/12767)
+
+
+
+
+
+# [2.17.0-rc.5](https://github.com/UI5/webcomponents/compare/v2.17.0-rc.4...v2.17.0-rc.5) (2025-12-04)
+
+
+### Bug Fixes
+
+* **OpenUI5Support:** fix closing of sap.m.Popover with esc key ([#12730](https://github.com/UI5/webcomponents/issues/12730)) ([fae0ab8](https://github.com/UI5/webcomponents/commit/fae0ab8289baa060d5d65024c47fd4dc34c7aac0))
+* **tools:** dependencies usage ([#12716](https://github.com/UI5/webcomponents/issues/12716)) ([89bb0dd](https://github.com/UI5/webcomponents/commit/89bb0dd62322598bd1ea7ce984eaf0618546a6f2))
+
+
+### Features
+
+* **framework:** introduce loadBaseThemingCSSVariables configuration ([#12699](https://github.com/UI5/webcomponents/issues/12699)) ([f01b2eb](https://github.com/UI5/webcomponents/commit/f01b2eb6256f2032bd802d0a60c4625b0d1af5fe))
+
+
+
+
+
+# [2.17.0-rc.4](https://github.com/UI5/webcomponents/compare/v2.17.0-rc.3...v2.17.0-rc.4) (2025-11-27)
+
+**Note:** Version bump only for package @ui5/webcomponents-base
+
+
+
+
+
+# [2.17.0-rc.3](https://github.com/UI5/webcomponents/compare/v2.17.0-rc.2...v2.17.0-rc.3) (2025-11-20)
+
+
+### Features
+
+* **framework:** scope theming css variables with component packages ([#12491](https://github.com/UI5/webcomponents/issues/12491)) ([43ff5de](https://github.com/UI5/webcomponents/commit/43ff5defaf6e08bac848df3d2d34943de15bee83))
+
+
+
+
+
+# [2.17.0-rc.2](https://github.com/UI5/webcomponents/compare/v2.17.0-rc.1...v2.17.0-rc.2) (2025-11-13)
 
 **Note:** Version bump only for package @ui5/webcomponents-base
 

package/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md