@dubai-design-system/components-js 5.2.0 → 5.3.1

package/CHANGELOG.md

@@ -4,6 +4,98 @@ All notable changes to the Dubai Design System packages are documented in this f
 All four published packages (`components-js`, `components-react`, `components-vue`,
 `components-angular`) share a version and release together.
 
+## 5.3.1 (2026-09-28)
+
+A patch release. It fixes the search text on the transparent header and brings back the banner scroll icon, `dda-scroll-icon`, and `dda-select` options with ids, as in 3.x.
+
+### Bug Fixes
+
+- **dda-header: typed search text is white on the transparent header.** 5.3.0 made only the placeholder white, so typed text was black on the dark banner. The typed text and the caret are now white at the top of the page, and dark again when the header turns white on scroll.
+- **dda-select: `main_aria_label` hid the label and the selected value.** `main_aria_label` set the trigger's `aria-label`, which replaces `aria-labelledby`, so screen readers announced only `main_aria_label`'s text, not the label or the current selection. `main_aria_label` now applies only when there is no `label`. With a `label`, the trigger keeps `aria-labelledby` and `main_aria_label` is ignored.
+- **dda-select: `selectChanged` dropped extra fields on object options.** For an `{ id, text }` option with extra fields (for example `{ id: 1, text: "Dubai", code: "DXB" }`), `selectChanged` now sends the full object, as 3.x did. String options are unaffected.
+- **dda-select: a false `selectionChange` when `selected` holds text or a differently-typed id.** Re-picking the already-selected option could still fire `selectionChange` when `selected` was matched by text, or set as a number where the option id is a string. It no longer fires in these cases.
+- **dda-select: `selectBlurred` fired when a keyboard open moved focus into the list.** Opening the list with Arrow Down/Up moves focus from the trigger into the list, which is not the user leaving the field. `selectBlurred` no longer fires for it.
+- **dda-select: `selectBlurred`'s `name` could be `undefined`.** It now falls back to the trigger's own id when neither `input_name` nor `button_id` is set.
+
+### Features
+
+- **dda-home-banner: the scroll icon is back.** The slide controls end with a decorative scroll icon, as in 3.x. It is hidden from assistive technology and at 992px and below. Add `show_scroll_icon_mobile` to show it at 992px and below too. Set `show_scroll_icon="false"` to remove it.
+- **dda-scroll-icon is back.** `scroll_icon_size` (`sm`, `lg`) and `scroll_icon_color` (`white`, `black`) work as in 3.x. The dot does not move when the user asks for reduced motion.
+- **dda-select: options with ids.** `options` also takes 3.x `{ id, text }` objects, and `selected` takes the id or the text. `placeholder`, `input_name` and `validation_type` work as in 3.x, `main_aria_label` is back (see Bug Fixes for its scope), and the 3.x events `selectChanged` and `selectBlurred` are back. `selectionChange` now also sends `id` and `text`. String options work as before.
+
+### Behaviour Changes
+
+- **dda-select: `selectionChange`'s `detail` has two new keys.** `detail` is now `{ value, id, text }`; `value` is unchanged. Code that deep-compares the whole `detail` object, rather than reading `detail.value`, sees the new `id` and `text` keys.
+- **dda-select: a `selected` value that matches no option shows the placeholder.** Earlier releases showed the raw `selected` text instead.
+
+## 5.3.0 (2026-09-24)
+
+A minor release. It brings back the 3.x attributes and components that sites built on 3.5 –
+3.12.10 use, so they can upgrade to 5.x. Most dda-header text can now be set. Read
+"From 3.5 – 3.12.10 to 5.3.0" in MIGRATION.md.
+
+### Features
+
+- **3.x attributes work again.** Versions 3.5 to 3.12.10 had attributes that 3.12.11 to 5.2.0
+  did not have. The ones below are back, under their 3.x names. "From 3.5 – 3.12.10 to 5.3.0"
+  in MIGRATION.md lists them. A page that uses only 5.x attributes can change in a small number of
+  places. "Behaviour Changes" below lists them.
+- **dda-header: the panel, toolbar and side-menu texts can be set.** The accessibility panel, the
+  tooltips, the search placeholder and the side-menu titles take attributes, so a page can show
+  them in its own language. An empty attribute removes that text. An empty `login-text` or
+  `language_text` removes the Login link or the language button, as in 3.x. A few close-button
+  labels (for example "Close Sidebar") stay fixed English text; they have no attribute.
+- **dda-header: the 3.x menu shape.** `quick-links` also accepts the 3.x shape (`type`,
+  `headerMenuLabel`, `url`, `children`). `dda_default_submenu` items open a dropdown list with a
+  second-level fly-out. In TypeScript, `quickLinks` has the type `string | QuickLinkItem[]`, so a
+  React, Vue or Angular page can set an array.
+- **dda-header: other menu, 3.x mobile search link, events.** New: `other-menu-items`,
+  `side-other-menu-title`, `hide-other-menu`, `mobile-menu-search-url`, and the
+  `accessibilitymenufunctionality` and `searchfunctionality` events.
+- **dda-sticky-footer: lists, dubai.ae and the more button.** `middle-link` takes any number of
+  logos. `right-link` takes text links with Material icons. `more-icon` adds a button that collects
+  the right links on phones. New: `dubaiae-icon-*`, `color-theme`, `*-icon-id`, `*-icon-src-dark`.
+- **dda-home-carousel and dda-banner-card are back.** The cards are links and use the same
+  scrolling row as the home-page quick links.
+
+### Bug Fixes
+
+- **dda-header: the side-menu ReadSpeaker link has its own id.** Both the desktop and the
+  side-menu ReadSpeaker links rendered `id="readspeaker_button1"`, a duplicate id. The side-menu
+  copy is now `readspeaker_button1Mobile`.
+- **dda-header: the `L` access key is only on the desktop ReadSpeaker link.** The side-menu copy
+  had it too, so pressing `Alt+Shift+L` (or the browser's access-key combination) could activate
+  the hidden side-menu link instead of the visible one.
+- **dda-segmented-tabs: the Dubai font, one-line labels, a scrollbar and a focus ring.** The
+  segments are buttons, so the browser showed them in its own font, not Dubai. A long label could
+  break onto two lines and go outside the segment's fixed height, and a group wider than its
+  container made the page wider. The segments had no visible focus ring. The segments now use the
+  page font and keep each label on one line, the group scrolls inside its container instead of
+  widening it, and a focus ring shows inside the selected segment.
+
+### Behaviour Changes
+
+These changes also apply to a page that uses only 5.x attributes. "From 5.2.x to 5.3.0" in
+MIGRATION.md tells you what to check.
+
+- **dda-header: an empty `login-text` removes the Login link.** In 5.2.0, an empty `login-text`
+  showed the default label "Login". Now it removes the Login link from the toolbar and the side
+  menu, as in 3.x. Remove the attribute to show "Login".
+- **dda-header: an empty `language_text` removes the language button.** In 5.2.0, an empty
+  `language_text` showed "العربية". Now it removes the language button, as in 3.x. Remove the
+  attribute to show "العربية".
+- **dda-header: a `quick-links` item without `href` links to `#`.** In 5.2.0, a 5.x item or a
+  mega-menu link without `href` rendered an `<a>` with no `href`. Now the link has `href="#"`.
+- **Home-page service cards show a focus style.** A `.quick-links .link-item` card now moves up
+  and shows an outline when it gets keyboard focus (`:focus-visible`). This also applies to the
+  plain-HTML cards of 5.2.0. If your own CSS styles this focus state, check that the two styles
+  agree.
+- **dda-sticky-footer: the middle logos show by default.** Before, they showed only with
+  `hide-middle-section="false"`. Now they show when at least one logo is set. Use
+  `hide-middle-section` to hide them.
+- **dda-sticky-footer: an item without an image is not rendered.** Before, every item rendered,
+  and an item without an image was an empty link.
+
 ## 5.2.0 (2026-09-23)
 
 A minor release. The home-page service cards become one scrolling row that stays on the banner at

package/MIGRATION.md

@@ -1,7 +1,7 @@
-# Upgrading to 5.2
+# Upgrading to 5.3
 
 This guide takes you from any earlier release of the Dubai Design System packages to
-**5.2.0**. It ships inside `@dubai-design-system/components-js` as `MIGRATION.md`, next to
+**5.3.0**. It ships inside `@dubai-design-system/components-js` as `MIGRATION.md`, next to
 `CHANGELOG.md`.
 
 All four packages share one version and must be upgraded together:
@@ -22,10 +22,12 @@ Then read the sections for your version, in this order:
 
 | You are on | Read |
 | --- | --- |
-| **5.1.x** (5.1.0 – 5.1.1) | [Every upgrade](#2-every-upgrade-checklist) → [5.1.x to 5.2.0](#3-from-51x-to-520) |
-| **5.0.x** (5.0.0 – 5.0.3) | [Every upgrade](#2-every-upgrade-checklist) → [5.0.x to 5.1.0](#4-from-50x-to-510) → [5.1.x to 5.2.0](#3-from-51x-to-520) |
-| **4.1.0** | [Every upgrade](#2-every-upgrade-checklist) → [From 4.1.0](#6-from-410) → [From 3.x](#7-from-3x-to-50) → [5.0.x to 5.1.0](#4-from-50x-to-510) → [5.1.x to 5.2.0](#3-from-51x-to-520) |
-| **3.x** (3.12.16 or earlier) | [Every upgrade](#2-every-upgrade-checklist) → [From 3.x](#7-from-3x-to-50) → [Notes from 5.0.1](#5-notes-from-501-fonts-and-the-stylesheet) → [5.0.x to 5.1.0](#4-from-50x-to-510) → [5.1.x to 5.2.0](#3-from-51x-to-520) |
+| **5.2.x** (5.2.0) | [Every upgrade](#2-every-upgrade-checklist) → [5.2.x to 5.3.0](#3-from-52x-to-530) |
+| **5.1.x** (5.1.0 – 5.1.1) | [Every upgrade](#2-every-upgrade-checklist) → [5.1.x to 5.2.0](#5-from-51x-to-520) → [5.2.x to 5.3.0](#3-from-52x-to-530) |
+| **5.0.x** (5.0.0 – 5.0.3) | [Every upgrade](#2-every-upgrade-checklist) → [5.0.x to 5.1.0](#6-from-50x-to-510) → [5.1.x to 5.2.0](#5-from-51x-to-520) → [5.2.x to 5.3.0](#3-from-52x-to-530) |
+| **4.1.0** | [Every upgrade](#2-every-upgrade-checklist) → [From 4.1.0](#8-from-410) → [From 3.x](#9-from-3x-to-50) → [Notes from 5.0.1](#7-notes-from-501-fonts-and-the-stylesheet) → [5.0.x to 5.1.0](#6-from-50x-to-510) → [5.1.x to 5.2.0](#5-from-51x-to-520) → [5.2.x to 5.3.0](#3-from-52x-to-530) |
+| **3.5 – 3.12.10** (for example 3.11.3) | [Every upgrade](#2-every-upgrade-checklist) → [From 3.5 – 3.12.10](#4-from-35--31210-to-530) → [From 3.x](#9-from-3x-to-50) → [Notes from 5.0.1](#7-notes-from-501-fonts-and-the-stylesheet) → [5.0.x to 5.1.0](#6-from-50x-to-510) → [5.1.x to 5.2.0](#5-from-51x-to-520) → [5.2.x to 5.3.0](#3-from-52x-to-530) |
+| **3.x** (3.12.16 or earlier) | [Every upgrade](#2-every-upgrade-checklist) → [From 3.x](#9-from-3x-to-50) → [Notes from 5.0.1](#7-notes-from-501-fonts-and-the-stylesheet) → [5.0.x to 5.1.0](#6-from-50x-to-510) → [5.1.x to 5.2.0](#5-from-51x-to-520) → [5.2.x to 5.3.0](#3-from-52x-to-530) |
 
 Most pages need only a few attribute changes. The changes that can break something
 **silently**, with no error in the console, are marked **Silent**. Search for those first.
@@ -39,14 +41,14 @@ Do these whatever version you start from.
 - [ ] **Install the same exact version of every DDA package.**
 
   ```bash
-  npm install @dubai-design-system/components-js@5.2.0
+  npm install @dubai-design-system/components-js@5.3.0
   # and, if you use a wrapper:
-  npm install @dubai-design-system/components-react@5.2.0   # or -vue / -angular
+  npm install @dubai-design-system/components-react@5.3.0   # or -vue / -angular
   ```
 
 - [ ] **Load `dda.css`.** It carries the global styles and the Dubai typeface. From npm:
   `import '@dubai-design-system/components-js/dist/dda/dda.css';`. From the CDN, see
-  [CDN users](#8-cdn-users).
+  [CDN users](#10-cdn-users).
 - [ ] **Load the icon fonts.** `dda.css` ships no icon font. Without these links, icons render
   as words such as `chevron_right`.
 
@@ -75,7 +77,138 @@ Do these whatever version you start from.
 
 ---
 
-## 3. From 5.1.x to 5.2.0
+## 3. From 5.2.x to 5.3.0
+
+5.3.0 adds attributes and does not remove any. A page that uses only 5.x attributes can still
+change in the places below. Examine each one.
+
+### Triage: run these first
+
+```bash
+# empty login-text or language_text attributes
+grep -rnE "(login-text|loginText|language_text)=(\"\"|'')" src/
+# your own focus styles for the home-page service cards
+grep -rn 'link-item:focus' src/
+```
+
+### Changes to check
+
+- **An empty `login-text` removes the Login link.** **Silent.** In 5.2.0, an empty `login-text`
+  showed the default label "Login". Now it removes the Login link from the toolbar and the side
+  menu. To show "Login", remove the attribute or set it to `Login`.
+- **An empty `language_text` removes the language button.** **Silent.** In 5.2.0, an empty
+  `language_text` showed "العربية". Now it removes the language button. To show "العربية",
+  remove the attribute.
+- **The `dda-sticky-footer` middle logos show by default.** In 5.2.0, they showed only with
+  `hide-middle-section="false"`. Now they show when at least one logo is set. To hide them, set
+  `hide-middle-section`.
+- **A `quick-links` item without `href` links to `#`.** In 5.2.0, a top-level item or a mega-menu
+  link without `href` had no `href` attribute. Now it has `href="#"`. Give each item a real
+  `href`.
+- **The home-page service cards show a focus style.** A `.quick-links .link-item` card now moves
+  up and shows an outline when it gets keyboard focus (`:focus-visible`). This applies to the
+  plain-HTML cards from 5.2.0 too. If your CSS styles this focus state, make sure the two styles
+  agree. Use the keyboard to examine the cards.
+
+---
+
+## 4. From 3.5 – 3.12.10 to 5.3.0
+
+Versions 3.5 to 3.12.10 had attributes and two components that 3.12.11 to 5.2.0 did not have.
+5.3.0 brings back the ones below under the same names, so most 3.x markup works without change.
+Read this section first. Then read these sections, in this order:
+[From 3.x to 5.0](#9-from-3x-to-50), [Notes from 5.0.1](#7-notes-from-501-fonts-and-the-stylesheet),
+[5.0.x to 5.1.0](#6-from-50x-to-510), [5.1.x to 5.2.0](#5-from-51x-to-520) and
+[5.2.x to 5.3.0](#3-from-52x-to-530).
+
+### Works again without change
+
+- **`dda-header`:** all accessibility-panel texts (`contrast_title`, `contrast_description`,
+  `contrast_noraml_text`, `contrast_color_blind_text`, `contrast_red_weakness_text`,
+  `contrast_green_weakness_text`, `screen_reader_title`, `screen_reader_description`,
+  `text_size_title`, `text_size_description`), `read_speaker_link`, `selected_contrast`,
+  `selected_text_size`, `accessibility_tooltip`, `accessibility_button_text`,
+  `accessibility_button_id`, `accessibility_button_icon_family`, `accessibility_button_icon_name`,
+  `search_tooltip`, `search_input_placeholder`, `language_tooltip`, `login_tooltip`,
+  `use-predesigned-accessibility-menu`, `side-main-menu-title`, `side-other-menu-title`,
+  `other-menu-items`, `hide-other-menu`, `mobile-menu-search-id`, `mobile-menu-search-url`, and
+  the 3.x `quick-links` shape (`type`, `headerMenuLabel`, `url`, `children`).
+- **`dda-header` events:** `accessibilitymenufunctionality` and `searchfunctionality`.
+- **`dda-sticky-footer`:** `middle-link`, `right-link`, `more-icon`, `more-icon-family`,
+  `dubaiae-icon-*`, `color-theme`, every `*-icon-id` and every `*-icon-src-dark`.
+- **Components:** `dda-home-carousel` and `dda-banner-card`.
+- **`dda-select`** (from 5.3.1): 3.x `{ id, text }` options, `placeholder`, `input_name`,
+  `validation_type`, and the `selectChanged` and `selectBlurred` events.
+- **`dda-scroll-icon` and the home banner's scroll icon** (from 5.3.1).
+
+### Changes that need action
+
+**The handler attributes never ran, and they do not run now.** **Silent.**
+Attributes such as `normalcontrast="() => …"`, `searchfunctionality="onSearch(this)"` and
+`languageswitch="…"` have no effect, in 3.x and in 5.x. The header sends events. Listen for them:
+
+```js
+const header = document.querySelector('dda-header');
+header.addEventListener('normalContrast', () => { /* … */ });
+header.addEventListener('searchfunctionality', event => onSearch(event.detail));
+header.addEventListener('accessibilitymenufunctionality', () => { /* … */ });
+```
+
+| Attribute in your markup | Event to listen for |
+| --- | --- |
+| `languageswitch` | `languageSwitch` |
+| `smtextsize`, `basetextsize`, `lgtextsize` | `smTextSize`, `baseTextSize`, `lgTextSize` |
+| `normalcontrast`, `blindcontrast`, `redcontrast`, `greencontrast` | `normalContrast`, `blindContrast`, `redContrast`, `greenContrast` |
+| `searchfunctionality` | `searchfunctionality` (the query, on submit) or `searchSubmit` (on submit; it can cancel the navigation) |
+| `accessibilitymenufunctionality` | `accessibilitymenufunctionality` |
+
+**`dda-select`'s `main_aria_label` now has an effect, but only without a `label`.** 3.x declared
+`main_aria_label` but never used it. From 5.3.1, `dda-select` uses it as the trigger's
+`aria-label`, and only when there is no `label`. With a `label`, the trigger keeps
+`aria-labelledby` and `main_aria_label` is ignored, so the label and the selected value stay
+announced.
+
+**`dda-home-carousel` cards are links.** In 3.x the cards were buttons, and `banner_card_href`
+had no effect. Now a card with `banner_card_href` is a link and it opens the page. If your own
+script opened the page on `cardClick`, remove that code, or the page opens two times.
+
+**Set the new accessible names on a site that is not in English.** 3.x had no attribute for these
+names, so your 3.x markup does not set them. They are English by default, and screen readers
+read them on an Arabic page too. Set them in the language of the page:
+
+| Component | Attribute | Default |
+| --- | --- | --- |
+| `dda-home-carousel` | `aria_label` | `Quick links` |
+| `dda-sticky-footer` | `aria_label` | `Quick actions` |
+| `dda-sticky-footer` | `more_button_label` | `More` |
+| `dda-header` | `screen_reader_link_label` | `Listen to this page using ReadSpeaker` |
+| `dda-header` | `menu_button_label` | `Menu` |
+
+You cannot change five `dda-header` close-button names yet: "Close Sidebar" (three buttons),
+"Close Accessibility" and "Close search". They stay in English.
+
+**The carousel does not scroll when the mouse moves.** The row scrolls with the mouse wheel, the
+scrollbar, touch and the keyboard. It shows a cut card and an edge fade when there are more cards.
+
+**Remove your own 3.x workarounds for the transparent header.** **Silent.**
+Some sites added rules that inverted the header colours, for example
+`body.transparent .dda-mega-menu > li > a { mix-blend-mode: difference; filter: invert(1) brightness(2); }`
+or `body.transparent .dda-search i { color: black; filter: invert(1) brightness(2); }`.
+5.x already shows white text and icons on the transparent header. With these rules, the text and icons turn dark again. Remove every such `filter` and `mix-blend-mode` rule.
+
+### Not brought back
+
+- `dda-header`: `use-login-popup`, `login-popup-links`, `use-navigator` and its `navigatorClick`
+  event, `show-quick-links-icon`, `first-logo-target`, `rel`, `header_default_submenu`,
+  `header_submenu_type`. The last four had no effect in 3.12.10.
+- Components: `dda-centered-image-card`, `dda-custom-card`, `dda-event-card`, `dda-header-menu`
+  (its menus are now part of `dda-header`), `dda-image-card`, `dda-information-card`,
+  `dda-pricing-card`, `dda-slider`, `dda-split-button`,
+  `dda-team-member-card`, `dda-teamsection-card`.
+
+---
+
+## 5. From 5.1.x to 5.2.0
 
 This section also covers 5.1.1. If you start from 5.1.1, the 5.1.1 notes are already done.
 
@@ -119,7 +252,8 @@ alone no longer wins. Add `dda-header:not(.dda-scrolled)` to it. Put the `transp
   always showed "Login" with the `sentiment_satisfied` icon, and only the side menu used the
   props. If you set them, the desktop link now shows your label and icon too.
 - **An empty `login-text` does not hide the Login link.** It shows the default label. Use
-  `hide_login` to remove the link.
+  `hide_login` to remove the link. (Changed in 5.3.0: see
+  [From 5.2.x to 5.3.0](#3-from-52x-to-530).)
 - **`dda-sticky-footer` location and news links with an image look the same.** The new icon
   props take effect only when the image prop is not set.
 
@@ -134,7 +268,7 @@ alone no longer wins. Add `dda-header:not(.dda-scrolled)` to it. Put the `transp
 
 ---
 
-## 4. From 5.0.x to 5.1.0
+## 6. From 5.0.x to 5.1.0
 
 ### Triage: run these first
 
@@ -294,7 +428,7 @@ the top of the page.
 
 ---
 
-## 5. Notes from 5.0.1: fonts and the stylesheet
+## 7. Notes from 5.0.1: fonts and the stylesheet
 
 Read this if you start from 5.0.0 or earlier.
 
@@ -307,7 +441,7 @@ Read this if you start from 5.0.0 or earlier.
 
 ---
 
-## 6. From 4.1.0
+## 8. From 4.1.0
 
 `4.1.0` was published in February 2025 and was never tagged `latest`; most sites never used it.
 It is a separate build and is not documented component by component. Known differences:
@@ -316,13 +450,14 @@ It is a separate build and is not documented component by component. Known diffe
 - It publishes no `dist/dda/dda.css`. Add it (see the checklist).
 - Its `dda-header` is an older implementation. Re-check the header on desktop and on a phone.
 
-Treat a 4.1.0 site like a 3.x site: follow [From 3.x](#7-from-3x-to-50), then
-[5.0.x to 5.1.0](#4-from-50x-to-510) and [5.1.x to 5.2.0](#3-from-51x-to-520), and check every
+Treat a 4.1.0 site like a 3.x site: follow [From 3.x](#9-from-3x-to-50), then
+[Notes from 5.0.1](#7-notes-from-501-fonts-and-the-stylesheet), [5.0.x to 5.1.0](#6-from-50x-to-510),
+[5.1.x to 5.2.0](#5-from-51x-to-520) and [5.2.x to 5.3.0](#3-from-52x-to-530), and check every
 page visually.
 
 ---
 
-## 7. From 3.x to 5.0
+## 9. From 3.x to 5.0
 
 **Why there is no 4.x to upgrade through:** `4.1.0` already existed on npm, so the next major
 skipped to 5 to keep `^4` ranges from resolving to that older build.
@@ -458,7 +593,7 @@ a future major release, with notice.
 
 ---
 
-## 8. CDN users
+## 10. CDN users
 
 jsDelivr syncs from npm automatically. Always use an **exact version**: replace `X.X.X` with
 the version you are upgrading to.