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

package/CHANGELOG.md

@@ -4,6 +4,74 @@ 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.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,123 @@ 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`.
+
+### 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-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.
+
+### 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-scroll-icon`, `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 +237,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 +253,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 +413,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 +426,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 +435,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 +578,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.