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

package/CHANGELOG.md

@@ -4,6 +4,122 @@ 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
+every screen width, `dda-header` gets a `hide_login` prop and uses `login-text` and `login-icon` on
+desktop, and `dda-sticky-footer` can show Material icons for the location and news links. Read
+"From 5.1.x to 5.2.0" in MIGRATION.md before you upgrade.
+
+### Features
+
+- **dda-header: new `hide_login` prop.** It removes the Login link from the desktop toolbar and
+  the side menu. Before, the link always showed. An empty `login-text` still shows the default
+  label; use `hide_login` to remove the link.
+- **dda-sticky-footer: `location-button-icon` and `news-button-icon` show a Material Symbols
+  icon.** The two props existed but did nothing. When a link has an icon and no image
+  (`location-logo-src`, `news-button-src`), it shows the icon, and `location-button-text` /
+  `news-button-text` name the link as visually hidden text. When both are set, the image shows,
+  the same as before.
+
+### Bug Fixes
+
+- **dda-header: the desktop Login link uses `login-text` and `login-icon`.** The desktop toolbar
+  always showed "Login" with the `sentiment_satisfied` icon and ignored both props; only the side
+  menu used them. The tooltip also uses `login-text` now.
+
+### Behaviour Changes
+
+- **Home page service cards (`.quick-links`) scroll sideways when they do not fit.** Before, on
+  wide screens the cards got narrower without limit, and at 992px and below they stacked in one
+  tall column. Now they stay in one row at every width, no card is narrower than 220px, and the
+  row scrolls horizontally with scroll snap. On screens of 992px and below the row spans the
+  screen and each card is 75% of the row (at most 300px), so the next card shows at the edge. A
+  fade on each edge that has more cards (in browsers with scroll-driven animations) and a thin
+  scrollbar also show that the row scrolls. The markup does not change. If your CSS sets
+  `display: grid` on `.quick-links` or a width on `.link-item`, check the home page after you
+  update.
+- **Home page service cards stay on the banner on small screens.** At 992px and below, on
+  screens taller than 600px, the cards sat under the full-height banner, below the first screen
+  and under the sticky footer buttons. They now sit on the banner, 12px above the sticky footer
+  bar, as on desktop, and are compact (112px tall, 24px icon, one line of description).
+  `dda-home-banner`'s slide controls move to 16px above the cards, so the arrows and dots stay
+  clear of them. Both read `--dda-quick-links-gap-sm` (12px) and
+  `--dda-quick-links-card-height-sm` (112px); set these on `:root` to move the cards and the
+  controls together. On short landscape screens (600px tall or less) the cards stay under the
+  banner.
+- **Home page service cards sit 24px higher on the banner.** Above 992px, `.quick-links-wrap`
+  is 24px further from the bottom of the banner, and `dda-home-banner`'s slide controls moved up
+  by the same 24px, so they stay above the cards.
+
 ## 5.1.1 (2026-09-18)
 
 A patch release. It fixes the transparent header on scroll, video slides in the home banner, and

package/MIGRATION.md

@@ -1,7 +1,7 @@
-# Upgrading to 5.1
+# Upgrading to 5.3
 
 This guide takes you from any earlier release of the Dubai Design System packages to
-**5.1.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,9 +22,12 @@ Then read the sections for your version, in this order:
 
 | You are on | Read |
 | --- | --- |
-| **5.0.x** (5.0.0 – 5.0.3) | [Every upgrade](#2-every-upgrade-checklist) → [5.0.x to 5.1.0](#3-from-50x-to-510) |
-| **4.1.0** | [Every upgrade](#2-every-upgrade-checklist) → [From 4.1.0](#5-from-410) → [From 3.x](#6-from-3x-to-50) → [5.0.x to 5.1.0](#3-from-50x-to-510) |
-| **3.x** (3.12.16 or earlier) | [Every upgrade](#2-every-upgrade-checklist) → [From 3.x](#6-from-3x-to-50) → [Notes from 5.0.1](#4-notes-from-501-fonts-and-the-stylesheet) → [5.0.x to 5.1.0](#3-from-50x-to-510) |
+| **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.
@@ -38,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.1.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.1.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](#7-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`.
 
@@ -74,7 +77,183 @@ Do these whatever version you start from.
 
 ---
 
-## 3. From 5.0.x to 5.1.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.
+
+### Triage: run these first
+
+```bash
+# your own layout rules for the home-page service cards and the banner controls
+grep -rn "quick-links\|link-item\|slider-nav" src/
+
+# your own overrides of the transparent header (changed in 5.1.1)
+grep -rn "\.transparent " src/
+
+# a Login label you set for the side menu only
+grep -rn "login-text\|loginText" src/
+```
+
+### Changes that need action
+
+**The home-page service cards (`.quick-links`) have a new layout.** **Silent.**
+The cards stay in one row at every width. A card is never narrower than 220px, and when the
+cards do not fit, the row scrolls sideways. On screens 992px wide or less and taller than 600px,
+the cards sit on the banner, 12px above the sticky footer bar, at a compact 112px height.
+`dda-home-banner` moves its slide controls to 16px above the cards. On desktop the cards and the
+controls are 24px higher than in 5.1.
+
+- Remove your own `display: grid`, widths or heights on `.quick-links` and `.link-item`, and your
+  own `bottom` offsets on `.quick-links-wrap` and `.slider-nav`.
+- To move the small-screen cards and controls together, set `--dda-quick-links-gap-sm` (default
+  `12px`) and `--dda-quick-links-card-height-sm` (default `112px`) on `:root`.
+- Check the home page on a desktop screen, on a phone (390 × 844) and on a phone on its side.
+
+**Transparent header overrides need the new selector (5.1.1).** **Silent.**
+The transparent header rules changed from `.transparent X` to
+`.transparent dda-header:not(.dda-scrolled) X`. An override that starts with `.transparent`
+alone no longer wins. Add `dda-header:not(.dda-scrolled)` to it. Put the `transparent` class on
+`<body>` or on another ancestor of `<dda-header>`, not on `<dda-header>` itself.
+
+### Changes to check, no code change expected
+
+- **The desktop Login link uses `login-text` and `login-icon`.** Before, the desktop toolbar
+  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. (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.
+
+### New, optional
+
+| Component | Addition | Use it to |
+| --- | --- | --- |
+| `dda-header` | `hide_login` | Remove the Login link from the toolbar and the side menu |
+| `dda-sticky-footer` | `location-button-icon`, `news-button-icon` (now used) | Show a Material Symbols icon instead of an image |
+| `dda-input` | `autocomplete` (5.1.1) | Let browsers fill in fields such as `name` and `email` |
+| `dda.css` | `--dda-quick-links-gap-sm`, `--dda-quick-links-card-height-sm` | Move the small-screen cards and banner controls |
+
+---
+
+## 6. From 5.0.x to 5.1.0
 
 ### Triage: run these first
 
@@ -234,7 +413,7 @@ the top of the page.
 
 ---
 
-## 4. 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.
 
@@ -247,7 +426,7 @@ Read this if you start from 5.0.0 or earlier.
 
 ---
 
-## 5. 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:
@@ -256,12 +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](#6-from-3x-to-50), then
-[5.0.x to 5.1.0](#3-from-50x-to-510), and check every page visually.
+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.
 
 ---
 
-## 6. 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.
@@ -397,7 +578,7 @@ a future major release, with notice.
 
 ---
 
-## 7. 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.