@dubai-design-system/components-js 5.0.3 → 5.1.0

package/CHANGELOG.md

@@ -4,6 +4,203 @@ 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.1.0 (2026-09-14)
+
+A minor release. It adds a working header search, and fixes issues a consumer reported after
+upgrading to 5.0.3 plus layout and API faults found while building a vanilla JS sample site
+against the published package. The two `dda-header` navigation faults were also present in
+3.12.x; they are fixed here, not newly introduced.
+
+**Upgrading?** `MIGRATION.md`, which ships next to this file, has a step-by-step guide from
+5.0.x, 4.1.0 and 3.x, with the searches to run and the attributes to change.
+
+### Features
+
+- **dda-header: the search works.** The desktop field is now a `<form role="search">`, so
+  Enter submits. Every non-empty search emits a cancelable `searchSubmit` event with
+  `detail.query`. The new `search_action` prop sends the search to a results page with a
+  plain GET, using `search_input_name` (default `q`) as the parameter, so static sites need no
+  JavaScript; cancel the event to route inside an app. On phone-width screens the search button
+  now opens a search field under the header, with `aria-expanded`, focus moved into the field,
+  and Escape or a close button to dismiss it.
+- **Components report user choices.** New events: dda-pagination `pageChange`
+  (`{ page }`), dda-select `selectionChange` (`{ value }`, only when the value changes),
+  dda-dropdown and dda-avatar `optionSelect` (`{ value }`, on every pick), and
+  dda-creditcard-field `valueChange` (`{ value }`). dda-ui-card now fires its `linkClick` event,
+  which was declared but never emitted (detail: the click `MouseEvent`), and dda-tabs `tabClick`
+  is typed as the tab index it always sent. The props these components update themselves
+  (`current_page`, `total_pages`, `selected`, `value`) are declared mutable.
+- **New props for data that was hardcoded or unreachable:** `dda-toggle` `title_text` and
+  `supporting`, `dda-footer` `logo-description`, `dda-breadcrumb` `breadcrumbs`, and
+  `dda-vertical-stepper` `current_step` (details below).
+
+### Accessibility
+
+Fixes from an axe-core and accessibility-tree audit of a sample site built on the package.
+
+- **Icon names are no longer read aloud (1.1.1, 4.1.2).** Decorative Material icons in
+  dda-button, dda-link-button, dda-accordion, dda-checkbox, dda-chip, dda-pagination, dda-tabs,
+  dda-segmented-tabs, dda-select, dda-dropdown, dda-number-field, dda-phonefield,
+  dda-search-input, dda-textarea, dda-alert, dda-ui-card and dda-header are `aria-hidden`, so a
+  button reads "Continue", not "Continue arrow_forward".
+- **Icon-only controls have names.** New label props with English defaults:
+  dda-alert `close_button_label` ("Close"), dda-chip `close_button_label` ("Remove"),
+  dda-search-input `clear_button_label` ("Clear search"), dda-pagination
+  `previous_button_label` / `next_button_label` ("Previous page" / "Next page"),
+  dda-dropdown / dda-number-field / dda-phonefield `toggle_button_label`, dda-header
+  `menu_button_label` ("Menu", replacing the text "hamburger menu text"), and dda-segmented-tabs
+  `icon_labels` for icon-only segments. Toggles that open a list set `aria-expanded`, and
+  dda-pagination marks the current page with `aria-current="page"`.
+- **Form labels are connected without an id prop (1.3.1, 4.1.2).** Found with WAVE. The
+  fields rendered `<label for={input_id}>` and `<input id={input_id}>`, so without the prop the
+  label pointed nowhere. dda-input, dda-textarea, dda-search-input, dda-attach-file,
+  dda-number-field, dda-phonefield, dda-creditcard-field, dda-select, dda-dropdown and
+  dda-range-slider now generate a unique id when `input_id` / `button_id` / the slider ids are
+  not set; the props still win when set.
+- **dda-select and dda-dropdown announce the chosen value.** The label no longer names the
+  trigger through `for`; the trigger uses `aria-labelledby` (label, then its own text), so a
+  screen reader hears "Topic, General question", not only "Topic".
+- **dda-attach-file works with a keyboard and screen reader (2.1.1).** The file input was
+  `display: none`. It is now visually hidden but focusable, the "Choose File" control shows a
+  focus ring, the input is named "Choose file" without a visible label, and the remove button
+  is named "Remove <file name>". The input stays in the page after a file is chosen, so a native
+  form submit includes the file.
+- **dda-phonefield is a telephone input.** It was `type="number"`, announced as a spin button,
+  changed by arrow keys, and dropped leading zeros. It is now `type="tel"` with
+  `autocomplete="tel-national"` by default, and country options have unique ids.
+- **dda-range-slider inputs are named** "Minimum" and "Maximum" by default, and are no longer
+  wrapped in empty `<label>` elements.
+- **dda-textarea in rich text mode** no longer points its label's `for` at the editor `<div>`.
+- **Keyboard focus is visible on dda-checkbox and dda-toggle (2.4.7).**
+- **dda-banner is reachable by keyboard (2.1.1).** The slide row is one focusable, named
+  region (`aria_label`, default "Slides") with a focus ring.
+- **Placeholder text meets 4.5:1 (1.4.3).** Grouped and single fields use
+  `--dda-on-surface-variant-40`: 6.49:1 in light theme and 7.46:1 in dark theme, up from 3.18:1.
+- **dda-home-banner text stays readable over any photo (1.4.3).** A built-in scrim sits behind
+  the slide text, mirrored for right-to-left pages.
+- **Links in running text are underlined (1.4.1).** `dda.css` removed every link underline;
+  unclassed links inside `p`, `td`, `dd`, `blockquote` and `figcaption` now keep one.
+- **Heading levels can follow the page outline.** New `heading_level` prop on dda-alert
+  (default 4), dda-footer (default 4) and dda-ui-card (default 3, was a fixed `h1`).
+- **dda-sticky-footer is an `<aside>` named "Quick actions"** (`aria_label`), so it no longer
+  adds a second footer landmark. Its services image is decorative when the text is shown.
+- **dda-header:** the language buttons carry `lang` (`language_lang`, default `ar`); the
+  side-menu language button uses `language_text`; the ReadSpeaker item is rendered only when
+  `read-speaker-link` is set; and logo links use `first-logo-href` / `second-logo-href`
+  (default `/`, previously `#`).
+
+### Bug Fixes
+
+- **Headings rendered at body size.** `legacy-compat.css` sized `h1`–`h6`, `.h1`–`.h6` and
+  `.dda-h1`–`.dda-h6` with `--font-h1`…`--font-h6 !important`, and the same file used
+  `--font-body`, `--font-caption`, `--font-display`, `--font-small`, `--line-height-*`,
+  `--font-weight-*` and `--gap-*`. None of these were defined, so every heading, the legacy
+  caption and body classes, the Light/Regular/Medium/Bold weights and `.dda-gap-xs/-lg` fell
+  back to inherited values. They are now defined as aliases of the current tokens (with zero
+  specificity, so a site's own values still win), and the heading, body and caption rules no
+  longer use `!important`, so component classes keep their own sizes. Present since 5.0.0.
+- **dda-home-banner: the slide title was tiny on laptop screens.** A rule in `dda.css` for
+  landscape screens up to 1600px wide set the slide title to 1.2rem and the subtitle to 1rem,
+  so most laptops showed a 19px hero title instead of the display size (36px at a 16px base).
+  The rule now applies only to short landscape screens (600px tall or less), such as a phone on
+  its side, where the full-height banner cannot fit the large title.
+- **dda-home-banner: the slide controls were hidden behind the quick-link cards.** The cards
+  rise by the sticky footer height (new in this release), but the previous/next/pause controls
+  and dots stayed at a fixed offset, so on large screens they sat under the white cards: invisible,
+  yet still clickable. The controls now rise by the same `--dda-sticky-footer-height`.
+- **dda-header: the transparent header gradient blocked taps.** Its 250px decorative gradient
+  reaches below the header and caught pointer events, so on short landscape screens the slide
+  call-to-action under it could not be clicked. The gradient now ignores pointer events.
+- **Crashes on missing data.** dda-credit-card no longer throws without `card_number` (it
+  shows `****`) and renders the card-type image only when `card_type` is set.
+  dda-horizontal-stepper, dda-vertical-stepper and dda-segmented-tabs no longer throw on a
+  missing or invalid JSON attribute, re-render when `steps`, `items` or `selected_index`
+  change, and segmented tabs accept non-string items.
+- **dda-header: the page scrolled behind the open side menu.** While the hamburger menu is
+  open, the page underneath no longer scrolls on touch or wheel input; the menu itself still
+  does. The lock is released when the menu closes by any route and when the header is removed.
+
+- **dda-header: the top menu was invisible at the site root.** When
+  `location.pathname` was `/`, the header added the `transparent` class to its own
+  `<header>`. The link and icon rules matched and turned the menu white, but the background
+  rule needs a `.transparent` *ancestor* and never matched, so the header stayed white. The
+  quick links were white on white on every site's home page.
+- **dda-header: side-menu submenu links did not navigate.** Every link below the first level
+  of `side-menu-items` cancelled its click to toggle a submenu, including links with no
+  submenu. Those links now navigate. Links that open a submenu still toggle it.
+- **dda-banner: slides rendered unstyled.** The component shipped only
+  `:host { display: block }`, so slides stacked as bare images. They now sit in a horizontal
+  row that scrolls and snaps one slide at a time. Smooth scrolling is off under
+  `prefers-reduced-motion`.
+- **dda-banner: a missing or invalid `slides` attribute threw.** It now renders an empty
+  banner and logs no error.
+- **dda-horizontal-stepper: the active line ran past the stepper on the last step.** The
+  connector drawn after the active step has no next step to reach on the last one, so it
+  widened the page. The last step no longer draws it.
+- **dda-vertical-stepper: `current_step` was ignored.** The prop was `current_Step`, whose
+  HTML attribute is `current_-step`, so the `current_step` attribute used in the docs never
+  moved the active step. `current_step` is now a real prop. `current_Step` (and
+  `current_-step`) keep working as a deprecated alias; `current_step` wins when both are set.
+- **dda-number-field, dda-phonefield: the fields overflowed narrow containers.** The grouped
+  `<input>` kept its intrinsic width, so the number field's currency button sat outside the
+  field and the phone field grew past its grid cell. The input now shrinks to the space left.
+  The rule is in the shared `input.css`, so every grouped field benefits.
+- **dda-radiobutton: the circle was invisible without `size`.** It took its dimensions only
+  from `size="sm|md|lg"`. It now defaults to the `md` size (21px).
+- **dda-footer: the text under the logo was hardcoded.** It always read "Design outstanding
+  interfaces with advanced Figma features in a matter of minutes." It now comes from the new
+  `logo-description` attribute (`logoDescription` property).
+- **dda-toggle: the label text was hardcoded.** Every toggle showed "Radio Button Title" and
+  "Supporting Text". The text now comes from the new `title_text` and `supporting` props, the
+  names `dda-checkbox` and `dda-radiobutton` already use.
+- **dda-breadcrumb: the items could only be set with the `data-breadcrumbs` attribute.** It
+  was read once and was not a prop, so frameworks and scripts could not set the items as a
+  property, and later changes did not re-render. The new `breadcrumbs` prop takes an array or
+  a JSON string and re-renders when it changes. `data-breadcrumbs` still works when the prop is
+  not set, and invalid JSON renders no items instead of throwing.
+- **dda-sticky-footer: the fixed bar covered the home-page quick-link cards.**
+  `.quick-links-wrap` sat 45px above the bottom of the banner, less than the bar's height, so
+  at 1366×900 the bar hid the bottom 52px of the cards. The sticky footer now sets
+  `--dda-sticky-footer-height` on `:root`, and `.quick-links-wrap` adds it to its offset. Pages
+  without a sticky footer, and the stacked layout below 992px, keep the 45px offset.
+- **dda.css: Material icons in quick-link cards had no size.** `.quick-links .link-item` sized
+  only `svg` icons. Material Icons `<i>` glyphs now get the same size, spacing and color.
+
+### Behaviour Changes
+
+- **dda-header no longer chooses the transparent style from the URL.** To show the
+  transparent header over a dark hero, set the class on an ancestor, as the static templates
+  do: `<body class="transparent">`. The header now renders both the colored and the white
+  logo, and CSS shows the correct one. The old automatic style never showed a transparent
+  background, so no page that rendered correctly before changes.
+- **dda-home-banner logs a console warning when it finds no `<slide>` children.** Only
+  `<slide>` elements are shown; a banner built from `<div>` or card elements used to render
+  blank without a hint.
+- **dda-footer shows no text under the logo unless `logo-description` is set.** Sites that
+  kept the placeholder sentence lose it; set `logo-description` to show your own text.
+- **dda-toggle shows no label text unless `title_text` or `supporting` is set.** Set
+  `title_text` for a visible label, or keep `aria_label` for an accessible name only.
+- **dda-sticky-footer writes `--dda-sticky-footer-height` on `:root`** while it is on the
+  page, and removes it when it is removed.
+- **dda-header search no longer renders `id="ddaSearch"`.** Each header gets its own input
+  ids, so two headers on a page no longer clash. Code that used
+  `getElementById('ddaSearch')` should listen for `searchSubmit` instead.
+- **dda-header adds `dda-scroll-lock` to `<html>` while the side menu is open,** which sets
+  `overflow: hidden` on `html` and `body`.
+- **dda-ui-card renders its title as `h3`, not `h1`.** Set `heading_level` to keep another level.
+- **dda-sticky-footer renders `<aside>`, not `<footer>`.** Selectors such as
+  `dda-sticky-footer footer` must use the `.dda-footer` class.
+- **dda-header logo links point to `/` by default,** not `#`. Set `first-logo-href` and
+  `second-logo-href` for another URL.
+- **dda-header hides the ReadSpeaker item when `read-speaker-link` is not set.** It did nothing
+  without the link.
+- **Placeholder text is darker, links in running text are underlined, and home-banner slides
+  have a scrim.** These are deliberate contrast fixes; check pages that restyled them.
+- **Headings are larger.** With the heading fix, `h1`–`h6` follow the type scale (for example
+  `h1` 57px and `h3` 40px at a 16px base) instead of 16px, and component titles use their own
+  sizes (alert title 24px, card title 18px, footer title 36px). Check pages that relied on
+  headings rendering at body size.
+
 ## 5.0.3 (2026-09-08)
 
 An accessibility release for `dda-header`. The search and accessibility controls in the
@@ -127,7 +324,7 @@ stylesheet produced a 404 for all twelve font URLs and fell back to `sans-serif`
 
 A full accessibility and correctness review of all 34 components. This is a **major**
 release: several fixes change the rendered DOM, remove hardcoded ids, or alter which CSS
-selectors match. **See [MIGRATION.md](../../MIGRATION.md) for what to change in your own code.**
+selectors match. **See `MIGRATION.md`, which ships next to this file, for what to change in your own code.**
 `docs/a11y/consumer-impact.md` has the verified, itemised list with file and line
 citations, and `docs/a11y/findings.md` records the 51 findings behind them.
 

package/MIGRATION.md

@@ -0,0 +1,423 @@
+# Upgrading to 5.1
+
+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
+`CHANGELOG.md`.
+
+All four packages share one version and must be upgraded together:
+`@dubai-design-system/components-js`, `components-react`, `components-vue` and
+`components-angular`.
+
+---
+
+## 1. Find your starting point
+
+Check the version you have now:
+
+```bash
+npm ls @dubai-design-system/components-js
+```
+
+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) |
+
+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.
+
+---
+
+## 2. Every upgrade: checklist
+
+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
+  # and, if you use a wrapper:
+  npm install @dubai-design-system/components-react@5.1.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).
+- [ ] **Load the icon fonts.** `dda.css` ships no icon font. Without these links, icons render
+  as words such as `chevron_right`.
+
+  ```html
+  <link href="https://fonts.googleapis.com/icon?family=Material+Icons" rel="stylesheet">
+  <link href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@20..48,100..700,0..1,-50..200" rel="stylesheet">
+  ```
+
+- [ ] **If you bundle with Vite or Rollup, do not use the lazy loader.**
+  `defineCustomElements()` from `components-js/loader` (and the Vue plugin, which calls it)
+  loads component chunks with dynamic imports these bundlers cannot follow, so the
+  components never render. Import each component you use instead:
+
+  ```js
+  import '@dubai-design-system/components-js/dist/components/dda-header.js';
+  import '@dubai-design-system/components-js/dist/components/dda-button.js';
+  ```
+
+  The CDN loader and the React wrapper are not affected.
+
+- [ ] **If you self-host `dda.css`,** copy `dist/assets/fonts/` next to it and keep the
+  relative path `../assets/fonts/dubai/`, or the Dubai typeface does not load.
+- [ ] **Clear any cached copy of the old package** (CDN edge cache, service worker, build
+  cache) and load every page type once: home page, a content page, a form, and a page on a
+  phone-width screen.
+
+---
+
+## 3. From 5.0.x to 5.1.0
+
+### Triage: run these first
+
+```bash
+# header: the old fixed search id is gone
+grep -rn "ddaSearch" src/
+
+# header: pages that relied on the automatic transparent style at "/"
+grep -rln "<dda-header" src/
+
+# vertical stepper: the prop that used to work
+grep -rn "current_-step\|current_Step" src/
+
+# components that showed placeholder text you may have relied on
+grep -rn "<dda-toggle\|<dda-footer" src/
+
+# manual offsets you may have added around the home-page quick links
+grep -rn "quick-links-wrap" src/
+```
+
+### Changes that need action
+
+**`dda-header` no longer turns transparent by itself at `/`.** **Silent.**
+Before 5.1.0 the header added a `transparent` class to itself on the site root. That made the
+menu links white while the header stayed white, so the top menu was invisible on every home
+page. The header now never guesses from the URL.
+
+- To keep a transparent header over a dark hero image, add the class to an ancestor:
+
+  ```html
+  <body class="transparent">
+  ```
+
+- The header now renders both logos and CSS shows the right one. If you set only
+  `first-logo-src`, it is also used on the transparent header; set `first-logo-white-src`
+  (and `second-logo-white-src`) for a white version.
+
+**`dda-header` search is now a real search.** **Silent** if you scripted the old field.
+The old field was not in a form and did nothing. It is now a `<form role="search">`:
+
+- `id="ddaSearch"` is gone. Every header gets its own ids, so two headers on a page no
+  longer clash. Replace `document.getElementById('ddaSearch')` with the new event.
+- Pressing Enter emits a cancelable `searchSubmit` event with `detail.query`.
+- Set `search_action` to a results page and the browser goes there with the query, no
+  JavaScript needed. The parameter name is `search_input_name`, default `q`.
+- On phone-width screens the search button now opens a search field under the header.
+
+```html
+<!-- static site: results page reads ?q= -->
+<dda-header search_action="/search.html"></dda-header>
+```
+
+```js
+// app with its own router
+header.addEventListener('searchSubmit', (event) => {
+  event.preventDefault();
+  router.push(`/search?q=${encodeURIComponent(event.detail.query)}`);
+});
+```
+
+In React the event is `onSearchSubmit`.
+
+**`dda-toggle` shows no label unless you set one.**
+It used to show the fixed text "Radio Button Title" and "Supporting Text". Set the new props:
+
+```html
+<dda-toggle input_id="news" title_text="Newsletter" supporting="One email a month"></dda-toggle>
+```
+
+Keep `aria_label` when there is no visible label.
+
+**`dda-footer` shows no text under the logo unless you set it.**
+It used to show the fixed sentence "Design outstanding interfaces with advanced Figma
+features in a matter of minutes." Set `logo-description` (`logoDescription` in JavaScript and
+the wrappers) to show your own text.
+
+**`dda-vertical-stepper` reads `current_step`.**
+The old prop was `current_Step`, and its HTML attribute was `current_-step`, so the documented
+`current_step` attribute did nothing. `current_step` now works. It counts from 0: `1` is the
+second step. `current_Step` and `current_-step` still work but are deprecated; move to
+`current_step`.
+
+**Side-menu links below the first level now navigate.**
+Before 5.1.0 every nested `side-menu-items` link cancelled its click. Links without a
+`subMenu` now go to their `href`. Check that nested items have real URLs; `"#"` now jumps to
+the top of the page.
+
+**Accessibility fixes that change markup.** **Silent** if your CSS or scripts target the old markup.
+
+- `dda-sticky-footer` renders `<aside aria-label="Quick actions">`, not `<footer>`. Replace
+  selectors such as `dda-sticky-footer footer` with `dda-sticky-footer .dda-footer`.
+- `dda-ui-card` renders its title as `h3`, not `h1`. Set `heading_level` (1–6) to match your
+  page outline, and target `.dda-card-title`, not `h1`.
+- `dda-header` logo links go to `/` instead of `#`. Set `first-logo-href` and
+  `second-logo-href`, especially if your site is served under a subpath, where `/` leaves it. The ReadSpeaker item shows only when `read-speaker-link` is set.
+- `dda-phonefield` renders `type="tel"`, not `type="number"`, and `autocomplete` defaults to
+  `tel-national`. Code that read `valueAsNumber` or relied on the number spinner must read the
+  string value instead; set `autocomplete="tel"` to keep the old hint.
+- `dda-select` and `dda-dropdown` labels have no `for` attribute any more; the trigger is named
+  with `aria-labelledby`. Clicking the label still opens the list. `dda-range-slider` inputs are
+  wrapped in `<span>`, not `<label>`.
+- `dda-attach-file` always renders its file input (visually hidden). Selectors that assumed
+  the input disappears after a file is chosen must change.
+- Icon-only buttons now have English default names ("Close", "Remove", "Clear search",
+  "Previous page", "Next page", "Menu"). On an Arabic page, set the matching `*_label` props.
+
+### Changes to check, no code change expected
+
+- **Headings are larger.** Before 5.1.0 an undefined token made every heading, `.dda-h1`–`.dda-h6`
+  and component title render at body size (16px). Headings now follow the type scale (`h1`
+  57px, `h2` 48px, `h3` 40px at a 16px base) and component titles use their own sizes. If a page
+  looks too large, set a smaller heading level or class rather than restyling the tokens; to
+  change the scale itself, override `--dda-h1`…`--dda-h6`.
+
+- **The page no longer scrolls behind the open hamburger menu.** While the menu is open, the
+  header adds `dda-scroll-lock` to `<html>`, which sets `overflow: hidden` on `html` and
+  `body`. If your own CSS sets `overflow` on `html` or `body`, check the open menu on a phone.
+- **`dda-sticky-footer` sets `--dda-sticky-footer-height` on `:root`,** and the home-page
+  `.quick-links-wrap` adds it to its bottom offset, so the cards sit above the fixed bar.
+  Remove any offset you added yourself.
+- **`dda-radiobutton` shows its circle without `size`.** It defaults to the `md` size (21px).
+  Radios without `size` were invisible before.
+- **`dda-number-field` and `dda-phonefield` fit narrow containers.** The input now shrinks, so
+  the currency button stays inside the field.
+- **`dda-horizontal-stepper`** no longer draws a line past its right edge on the last step,
+  which widened the page.
+- **`dda-banner`** lays out its slides as a horizontal row that scrolls and snaps, instead of
+  stacked images. A missing `slides` attribute no longer throws.
+- **`dda-home-banner`** logs a console warning when it has no `<slide>` children. Only
+  `<slide>` elements are shown.
+- **Material icons in `.quick-links .link-item`** get the same size as SVG icons.
+- **Placeholder text is darker** (4.5:1 contrast or better), **links inside paragraphs and table
+  cells are underlined**, and **home-banner slides have a dark scrim behind the text.** If you
+  restyled any of these, check that your override still meets contrast.
+- **`dda-checkbox` and `dda-toggle` show a focus ring** under keyboard focus, and the
+  `dda-banner` slide row is a keyboard tab stop.
+
+### New, optional
+
+| Component | Addition | Use it to |
+| --- | --- | --- |
+| `dda-header` | `search_action` prop, `searchSubmit` event | Send searches to a results page or your router |
+| `dda-breadcrumb` | `breadcrumbs` prop (array or JSON string) | Set items from JavaScript or a framework; `data-breadcrumbs` still works |
+| `dda-toggle` | `title_text`, `supporting` | Show a visible label |
+| `dda-footer` | `logo-description` | Show text under the footer logo |
+| `dda-vertical-stepper` | `current_step` | Set the active step |
+| `dda-alert`, `dda-footer`, `dda-ui-card` | `heading_level` | Match the heading level to your page |
+| `dda-alert`, `dda-chip`, `dda-search-input`, `dda-pagination`, `dda-dropdown`, `dda-number-field`, `dda-phonefield`, `dda-header` | `*_label` props | Name icon-only buttons, e.g. in Arabic |
+| `dda-segmented-tabs` | `icon_labels` | Name icon-only segments |
+| `dda-header` | `first-logo-href`, `second-logo-href`, `language_lang` | Logo link targets, language of the language button |
+| `dda-banner`, `dda-sticky-footer` | `aria_label` | Name the slide region / quick actions |
+| `dda-pagination` | `pageChange` event | React when the user changes page |
+| `dda-select` | `selectionChange` event | React when the selected value changes |
+| `dda-dropdown`, `dda-avatar` | `optionSelect` event | React to a menu pick |
+| `dda-creditcard-field` | `valueChange` event | Read the value as the user types |
+| `dda-ui-card` | `linkClick` event (now fired) | Track or intercept card link clicks |
+
+---
+
+## 4. Notes from 5.0.1: fonts and the stylesheet
+
+Read this if you start from 5.0.0 or earlier.
+
+- The Dubai typeface is declared only in `dist/dda/dda.css`. A page that loads the components
+  but not `dda.css` falls back to a sans-serif font. Load `dda.css`.
+- The font files ship in `dist/assets/fonts/dubai/` as `woff2`, `woff` and `ttf`. The old `eot`
+  and `svg` formats are gone; they served only Internet Explorer and very old Safari.
+- The React and Vue wrappers published with 5.0.0 missed some props and events
+  (`autocomplete`, `input_id`, `selected_index`, `segmentChange`). 5.0.1 and later have them.
+
+---
+
+## 5. 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:
+
+- It has no `dda-banner`, `dda-home-banner` or `dda-ui-card`.
+- 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.
+
+---
+
+## 6. 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.
+
+Most consumers need to change nothing here. These changes affect you only if you wrote CSS or
+JavaScript that reaches inside a component's rendered markup, or used one of the fixed ids the
+components used to emit.
+
+### Triage
+
+```bash
+# hardcoded ids these components used to emit
+grep -rn "getElementById('search')\|getElementById(\"search\")\|#search\b" src/
+grep -rn "getElementById('editor')\|getElementById(\"editor\")\|#editor\b" src/
+
+# reaching into a shadow root that no longer exists
+grep -rn "shadowRoot" src/ | grep -i "footer"
+grep -rn "::part(" src/
+
+# selectors keyed on an element type that changed
+grep -rn "div\.accordion-header\|span\.chip-close\|div\.dots" src/
+grep -rn "\.dda-avatar\s*>\|\.dda-avatar >" src/
+```
+
+Then load a page in dark theme and look at the footers. If they looked unstyled before, they
+are now fully styled; that is the intended fix.
+
+### Breaking changes
+
+#### `dda-footer` and `dda-sticky-footer` no longer use shadow DOM
+
+They rendered as **unstyled raw HTML** in 3.x: their shadow stylesheet was empty and global
+CSS could not reach inside. They now render fully styled.
+
+| | 3.x | 5.0 and later |
+|---|---|---|
+| `element.shadowRoot` | a `ShadowRoot` | `null` |
+| `::part(...)` | targetable | nothing to target |
+| Appearance | unstyled | fully styled |
+
+**Migrate:** delete any `shadowRoot` traversal or `::part()` rules for these two and style them
+with ordinary selectors. **Re-check your footer layout visually**; this is a total visual
+change.
+
+#### Hardcoded ids removed: `#search` and `#editor` — **Silent**
+
+`dda-search-input` emitted `id="search"` and `dda-textarea` emitted `id="editor"` on every
+instance, which gave duplicate ids as soon as a page used two.
+
+```html
+<!-- 3.x: the id was implicit -->
+<dda-search-input label="Find"></dda-search-input>
+<script>document.getElementById('search').focus()</script>
+
+<!-- 5.0 and later: you supply the id -->
+<dda-search-input label="Find" input_id="site-search"></dda-search-input>
+<script>document.getElementById('site-search').focus()</script>
+```
+
+**Migrate:** set `input_id` (both components) to the id your code expects.
+`getElementById` just returns `null`, so search for these rather than waiting for an error.
+
+#### `dda-search-input`'s label now points at the input
+
+In 3.x the visible `<label for>` targeted the clear button. It now targets the text field.
+**Migrate:** set `input_id`; without it the label has nothing to point at.
+
+#### `dda-avatar` wraps its content in `.avatar-trigger`
+
+```html
+<!-- 3.x -->
+<dda-avatar><div class="dda-avatar"><img …></div></dda-avatar>
+
+<!-- 5.0 and later: a wrapper always sits between -->
+<dda-avatar><div class="dda-avatar">
+  <button class="avatar-trigger"><img …></button>   <!-- when `options` is set -->
+  <div class="avatar-trigger"><img …></div>          <!-- when it is not -->
+</div></dda-avatar>
+```
+
+**Migrate:** replace direct-child selectors (`.dda-avatar > img`) with descendant selectors
+(`.dda-avatar img`).
+
+#### Element types changed on three controls
+
+These were `div`/`span` elements with a click handler and no keyboard access.
+
+| Component | 3.x | 5.0 and later | Class |
+|---|---|---|---|
+| `dda-accordion` | `div.accordion-header` | `button.accordion-header` | unchanged |
+| `dda-chip` | `span.chip-close` | `button.chip-close` | unchanged |
+| `dda-home-banner` | `div.dots` (direct `ul` child) | `li > button.dots` | unchanged |
+
+**Migrate:** drop the element type from your selectors (`.accordion-header`, not
+`div.accordion-header`). For the banner dots, also drop any direct-child combinator: there is
+now an `<li>` in between.
+
+### Behaviour changes to check
+
+- **`dda-header` sets `scroll-padding-top` on `:root`** (170px; 100px below 767px), so keyboard
+  focus cannot land behind the fixed header. Every anchor jump and `scrollIntoView()` on the
+  page is offset. Remove any manual compensation or you will double-offset.
+- **`dda-home-banner` writes `inert` and `aria-hidden` onto your `<slide>` elements.** Slides
+  that are not showing cannot be focused or clicked. It also became a working carousel, with
+  autoplay, previous/next/pause controls and a live region.
+- **`dda-segmented-tabs` selects its first segment on load.** In 3.x it had no interactivity.
+- **`dda-sticky-footer` marks itself `inert` while scroll-hidden.**
+- **`dda-tabs`:** `aria_label` names the tab group; each tab is named by its own text.
+- **`dda-pagination`:** dot spacing 8px → 15px, so the control is wider.
+- **`dda-tooltip`:** `Escape` dismisses an open tooltip.
+- **Dark theme:** `--dda-primary-variant-95` and `--dda-color-warning-40` changed value. Info
+  alerts get a deeper fill; warning alerts a brighter amber.
+- **Muted and disabled text is darker in light theme,** for readable contrast. Disabled
+  controls look more present than before; that is deliberate.
+- **`dda-header`'s accessibility icon** changed from `accessible_forward` to `accessibility`.
+
+### New props from 5.0
+
+| Component | Prop | Why |
+|---|---|---|
+| `dda-search-input`, `dda-textarea` | `input_id` | Restores a removed hardcoded id |
+| `dda-creditcard-field`, `dda-phonefield` | `autocomplete` | Browser autofill |
+| `dda-progressbar` | `aria_label` | Names the progress bar for screen readers |
+| `dda-home-banner` | `autoplay`, `interval`, label props | The carousel is real now |
+| `dda-segmented-tabs` | `selected_index` | Choose the initially selected segment |
+
+### `dda.css` if you used `@latest` on the CDN
+
+`dist/dda/dda.css` was **missing from 3.12.16**, and the CDN served a stale cached copy from an
+older release. 5.0.0 and later ship the file again, as a superset of that copy: every class in
+it is still present. Those legacy rules are kept for compatibility and will be removed only in
+a future major release, with notice.
+
+---
+
+## 7. CDN users
+
+jsDelivr syncs from npm automatically. Always use an **exact version**: replace `X.X.X` with
+the version you are upgrading to.
+
+```html
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@dubai-design-system/components-js@X.X.X/dist/dda/dda.css" />
+<link rel="stylesheet" href="https://fonts.googleapis.com/icon?family=Material+Icons" />
+<script type="module">
+  import { defineCustomElements } from 'https://cdn.jsdelivr.net/npm/@dubai-design-system/components-js@X.X.X/loader/index.es2017.js';
+  defineCustomElements();
+</script>
+```
+
+Do **not** use `@latest` or leave the version out. jsDelivr caches version aliases, and an
+unversioned loader URL loads chunks from mixed versions, which stops components rendering.
+
+---
+
+## If something breaks that is not listed here
+
+Note the component, the version you came from, the browser, and what you expected to see, and
+report it to the Dubai Design System team. An undocumented change is a gap in this guide, not
+your mistake.