@design-factory/angular 21.1.0 → 22.0.0-next.0

package/.ai/docs/components/dropdown/api.md

@@ -0,0 +1,85 @@
+# Dropdown — API
+
+## `df-dropdown` — Component
+
+_Since 22.0_
+
+Dropdown is a component to provide a button combined to a menu with a list of options.
+
+### Inputs
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| container | `'body' \| null` | `null` | Which element should contain the dropdown menu DOM element. 'body': the menu is appended to document.body (useful when the toggle is inside an element that clips its content via overflow or creates a stacking context). null (default): the menu is rendered inline, where the dropdown is declared. |
+| opened | `boolean` | `false` | If true, the dropdown is open. |
+| placement | `string \| DfDropdownPlacement[]` |  | The dropdown placement relative to its anchor. |
+| size | `DfDropdownSize` |  | Visual size configuration for dropdown items. |
+
+### Outputs
+
+| Name | Type | Description |
+|------|------|-------------|
+| openedChange | `boolean` | Event emitted when the open state changes. |
+
+### Methods
+
+#### `toggle(open: boolean | undefined)` => `void`
+
+Toggles the dropdown menu visibility programmatically.
+
+#### `open()` => `void`
+
+Opens the dropdown menu programmatically.
+
+#### `close()` => `void`
+
+Closes the dropdown menu programmatically.
+
+#### `isOpen()` => `boolean`
+
+Get whether the dropdown menu is currently open.
+
+## `button[dfDropdownToggle]` — Component
+
+_Since 22.0_
+
+Component representing the toggle button of a dropdown, which is used to toggle the visibility of the dropdown menu.
+
+### Inputs
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| appearance | `DfButtonAppearance` | `'solid'` | Visual appearance of the button. In a df-button-group, the group appearance is used unless the button sets an explicit 'solid' or 'outline' appearance. |
+| dfDropdownToggle | `DfDropdown` |  | The dropdown instance controlled by this toggle element. Pass the referenced DfDropdown instance to connect the host button to its menu. |
+| disabled | `boolean` | `false` | Disabled state for buttons and anchor buttons. |
+| iconOnly | `boolean` | `false` | When true, hides the chevron icon for icon-only dropdown buttons. Accessibility: When using iconOnly, you must provide an aria-label attribute on the button element. |
+| mirror | `boolean` | `false` | Enables mirrored styling for inverse surfaces. Ignored if the button is in a df-button-group (the group value is used instead). |
+| size | `DfButtonSize` | `'md'` | Size of the button. Ignored if the button is in a df-button-group (the group size is used instead). |
+| transparent | `boolean` | `false` | Makes outline and text buttons transparent. Solid buttons are unaffected. Ignored if the button is in a df-button-group (transparent buttons are currently not supported in groups). |
+| variant | `DfButtonVariant` | `'primary'` | Semantic variant of the button. Forced to 'primary' if the button is in a df-button-group. |
+
+## `button[dfDropdownItem]` — Directive
+
+_Since 22.0_
+
+Directive representing a button in the dropdown menu.
+
+### Inputs
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| active | `boolean` | `false` | Whether the dropdown item is displayed in its active state. |
+| disabled | `boolean` | `false` | Whether the dropdown item is disabled. |
+
+## `a[dfDropdownItem]` — Directive
+
+_Since 22.0_
+
+Directive representing a link in the dropdown menu.
+
+### Inputs
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| active | `boolean` | `false` | Whether the dropdown item is displayed in its active state. |
+| disabled | `boolean` | `false` | Whether the dropdown item is disabled. |

package/.ai/docs/components/dropdown/developer.md

@@ -0,0 +1,59 @@
+Use `<df-dropdown>` for the menu content and connect it to a native button with `[dfDropdownToggle]`. Use
+`button[dfDropdownItem]` for commands and `a[dfDropdownItem]` for navigation items.
+
+```angular-html
+<button [dfDropdownToggle]="menu">Actions</button>
+<df-dropdown #menu>
+  <button dfDropdownItem>Refresh</button>
+  <a dfDropdownItem href="/settings">Settings</a>
+</df-dropdown>
+```
+
+> Demo source: [docs/demos/dropdown/basic/](../../demos/dropdown/basic/)
+
+The dropdown toggle uses the DF button styling inputs. Set `appearance`, `variant`, `size`, `transparent` and `mirror`
+on the toggle button the same way you would for a regular button.
+
+> Demo source: [docs/demos/dropdown/toggle/](../../demos/dropdown/toggle/)
+
+Set `size` on both the toggle and the dropdown menu when the entire control needs to render in a different size.
+
+> Demo source: [docs/demos/dropdown/sizes/](../../demos/dropdown/sizes/)
+
+Pair a primary action with a dropdown of related actions by composing the toggle with
+[`df-button-group`](/components/buttongroup). The toggle inherits the group `appearance`, `size` and `mirror`, so
+they only need to be set once on the group.
+
+```angular-html
+<df-button-group aria-label="Split button">
+  <button dfButton>Save</button>
+  <button [dfDropdownToggle]="menu" aria-label="More save options"></button>
+</df-button-group>
+<df-dropdown #menu>
+  <button dfDropdownItem>Save and close</button>
+  <button dfDropdownItem>Save as draft</button>
+</df-dropdown>
+```
+
+> Demo source: [docs/demos/dropdown/split/](../../demos/dropdown/split/)
+
+Use `[opened]` and `(openedChange)` when the open state is owned by the parent component. Use `open()`, `close()` or
+`toggle(open?: boolean)` when you need to open or close the menu programmatically.
+
+```angular-html
+<button [dfDropdownToggle]="menu">Actions</button>
+<df-dropdown #menu [opened]="opened" (openedChange)="opened = $event">...</df-dropdown>
+```
+
+The dropdown does not apply any ARIA `role` attribute automatically. You must set the appropriate roles on the container and on each item to match your use case.
+
+For example, use `role="listbox"` on the dropdown and `role="option"` on each item:
+
+```angular-html
+<button [dfDropdownToggle]="menu">Choose color</button>
+<df-dropdown #menu role="listbox">
+  <button dfDropdownItem role="option" aria-selected="true">Red</button>
+  <button dfDropdownItem role="option" aria-selected="false">Green</button>
+  <button dfDropdownItem role="option" aria-selected="false">Blue</button>
+</df-dropdown>
+```

package/.ai/docs/components/dropdown/guidelines.md

@@ -0,0 +1,80 @@
+ 
+
+**Basic variant:**
+
+- **Icon left (1):** Is optional and adds semantic value to increase context comprehension. Different from the right icon, which helps to understand what sort of behavior will be actioned.
+- **Label (2):** Describes the action category or entry point (e.g., "More actions").
+- **Dropdown menu (3):** A contextual list of related actions. Items should be short, actionable, and ordered logically.
+
+**Split variant:**
+
+- **Main button (4):** Executes the main action directly, without requiring menu interaction.
+- **Dropdown trigger (5):** A smaller, adjacent trigger that opens a menu of secondary or alternative actions related to the main action.
+
+The Basic Dropdown is used when all actions have similar importance and none needs to be shown as a primary action.
+
+- Use the Basic Dropdown when you need **a compact entry point to several related actions** of equal importance.
+- Ensure the trigger label reflects the nature of the action(s).
+
+- Don't place unrelated or infrequent actions together. Dropdowns are not catch-all containers.
+
+The Split Dropdown is used when one action is clearly primary and should remain directly accessible, while secondary actions are placed in the dropdown.
+
+- Use the Split Dropdown when **a primary action must stay visible**, with alternatives grouped under the dropdown.
+
+- Don't place unrelated or infrequent actions together. Dropdowns are not catch-all containers.
+
+The Dropdown with left icon enhances the trigger's recognisability by pairing the label with a meaningful icon. This visual cue helps users identify the nature of the contained actions more quickly.
+
+- **Keep icon style consistent** with the rest of the system.
+- **Prefer simple, universally recognisable icons** for faster scanning.
+
+- **Don't add icons purely for decoration**, they must add semantic value and highlight content.
+- Don't add any icons other than the one on the left.
+
+The Icon‑only Dropdown is a compact standalone Dropdown, used in interfaces where space is limited or where adding a label would be redundant. It exposes secondary actions while keeping layouts clean and lightweight.
+
+- Choose icons that are widely recognised and consistent across the product.
+- Ensure that the icon meaning is well established and unambiguous.
+
+- Don't cluster multiple similar icons together.
+- Don't rely solely on the icon for meaning when the context is ambiguous. Use the Basic Dropdown instead.
+
+The dropdown menu should behave in a way that feels immediate. The interactions should remain simple: opening the menu reveals a short list of contextual actions, selecting an item performs the action and closes the menu, and clicking outside dismisses it. The dropdown menu can be anchored to the trigger, either on the left or on the right.
+
+- Keep the **menu visually anchored to its trigger** to preserve spatial consistency.
+- **Use dividers or titles to separate** logical subgroups of actions.
+
+- **Don't overload the Dropdown menu** with too many actions because long lists slow users down and increase cognitive load.
+- **Don't apply complex or inconsistent sorting rules** that force users to "learn" the menu.
+
+Use an external link to navigate users outside the current product or application, typically to documentation, support platforms, or external tools.
+
+- Clearly indicate that the link leads to an external destination (label + icon).
+- Use concise, descriptive link text that explains what the user will access.
+
+- Don't use external links for core workflows or critical in-app actions.
+
+In case of doubt we recommend using the medium size which is the standard size for Design Factory. When using a size, try to keep the same all across your pages.
+
+The menu should appear exactly when the user expects it, remain visually connected to its trigger, and disappear as soon as its purpose is fulfilled.
+
+**Opening:** The menu opens instantly when the user activates the trigger (click or tap). There should be no delay, hover dependencies, or unexpected animations.
+
+**Positioning:** The menu stays anchored to the trigger so users immediately understand its origin and context.
+
+**Selection:** Choosing an action immediately triggers the corresponding behavior and closes the menu.
+
+**Closing:** Clicking or tapping outside the menu dismisses it. The menu can also be closed by clicking the element that opened it. The component should never remain open unintentionally or obstruct surrounding content.
+
+There is no special responsive behaviour for this component.
+
+Write labels and menu items that are clear, concise, and action‑oriented so users immediately understand what the Dropdown contains and what each action will do. Always favor wording that helps users scan quickly and decide without hesitation.
+
+Use consistent, predictable phrasing for all actions:
+
+- **Action labels** → start with a clear verb ("Edit", "Duplicate", "Download")
+- **Categories or sections** → use short, factual nouns ("Share", "Settings")
+- **Icon‑only Dropdown** → ensure tooltip text reflects the exact action category
+
+> **Tip:** For a full view on UX Writing guidelines, check the following document: [Amadeus UX Writing Style Guide](<https://amadeusworkplace.sharepoint.com/:w:/r/sites/UXCommunity_official/_layouts/15/Doc.aspx?sourcedoc=%7BB0C79089-403F-41AE-AFA3-C5BEDFCB8254%7D&file=Amadeus%20UX%20Writing%20Style%20Guide%20(Brecht%20ALGOET_Marcos%20LLORENS).docx&action=default&mobileredirect=true>)

package/.ai/docs/components/dropdown/overview.md

@@ -0,0 +1,16 @@
+ 
+
+The Dropdown is **an action component that reveals a concise set of related actions** without exposing them permanently in the interface. It relies on a trigger button that opens a contextual menu containing secondary or complementary actions, helping keep the layout clean while still providing access to relevant options.
+
+- Use Dropdowns only **for actions that belong to the same functional group**.
+- Use Dropdowns **to reduce visual noise** when secondary actions don't need constant visibility.
+- **Keep Dropdown menus short and ordered logically** (frequency, alphabetical order…).
+
+- **Don't use Dropdowns for choosing values**. You can use the [Select](/components/select) component instead.
+- **Don't hide essential or high-priority actions** inside a Dropdown.
+- **Don't use Dropdowns for filtering or sorting** content.
+- **Don't overload Dropdowns menus** with long or complex lists.
+
+The Dropdown is used to expose a small set of related actions that are secondary to the current context and do not need to be visible at all times. Unlike a **Button**, which represents a single, immediate call to action, or a **Button group**, which displays several related actions side by side and keeps them always visible, a Dropdown helps reduce visual clutter by revealing actions only when needed. A **Select** component, on the other hand, is used for choosing a value within a form or a selection workflow and directly affects data or state, not actions.
+
+</div>

package/.ai/docs/components/sidenav/accessibility.md

@@ -0,0 +1,48 @@
+- WCAG guidelines for disclosure navigation menus served as a base for the ones in this page - [View WCAG Disclosure Navigation Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/examples/disclosure-navigation/)
+
+Case : The users are focused on an element in the top bar. Then, the users focus the next element and this one is the side navigation. It will focus the first element of the side navigation.
+
+Screen Reader should announce this region as : Side navigation with a list of “x” elements.
+
+**Tabs** reach focusable elements.
+
+- Tab → focus to the next focusable element
+- Shift + tab → focus to the previous focusable element
+
+**Arrow key** reach focusable elements.
+
+Screen Readers would read each item after pusching the arrow key.
+
+This not scrolling down the side navigation.
+
+- down → read the next item
+- up → read the previous item
+
+- If the item is expandable, it expands it.
+- If the item is collapsable, it collapses it.
+- If the item is not expandable, it opens the page in the content area.
+- On expand/colapse icon button it activates the action of the button.
+
+Use case: Expand an expandable item. The users focus [L1] Item 2. Then push "enter" or "space bar" keys, it expand the list. The focus stays on [L1] Item 2.
+
+Use case: Enter or Space bar will visit the content of the item selected : Level 1 or lower level, here an example with level 2.
+The focus will go on next focusable element of the content.
+
+Use case: Enter or Space bar will visit the content of the item selected : Level 1 or lower level, here an example with level 2.
+The focus will go on next focusable element of the content.
+
+Screen Readers should read:<br>
+[type of the element], [text of the element], [state of the element]
+
+1. read: input search
+2. read: Button aria-label, [L1] Item, current page
+3. read: Button aria-label, [L1] Item, expanded
+4. read: Button aria-label, [L2] Item, visit the page
+5. read: Button aria-label, [L2] Item, visit the page
+6. read: Button aria-label, [L1] Item, collapsed
+7. read: Button aria-label, collapse the side navigation
+8. read: Button aria-label, resize the side navigation
+
+Screen Reader should announce this region as : Side navigation with a list of “x” elements
+
+For users who zoom up to 300%, apply the responsivness behaviour of the component.

package/.ai/docs/components/sidenav/api.md

@@ -0,0 +1,110 @@
+# SideNav — API
+
+## `df-sidenav` — Component
+
+_Since 21.0.0_
+
+SideNav is a component to provide navigation feature with a panel on the side of your page
+
+### Inputs
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| collapsible | `boolean` | `true` | Flag whether the sidenav should have the collapse button |
+| disableInitialDesktopAutoScroll | `boolean` | `false` | Flag to disable the automatic scroll to active link on desktop when the sidenav is initialized. |
+| enableMobile | `boolean` | `true` | Flag to enable the mobile sidenav display of the items. |
+| resizable | `boolean` | `true` | Flag whether the sidenav should be resizable |
+| searchable | `boolean` | `true` | Flag whether the sidenav includes a search input |
+
+### Properties
+
+| Name | Type | Description |
+|------|------|-------------|
+| isMinimized | `Signal<boolean>` | Flag to indicate if the sidenav is minimized |
+
+### Methods
+
+#### `toggleMinimize(minimized: boolean)` => `void`
+
+Toggles the minimized state of the sidenav
+
+#### `visibleChangeHandler(isVisible: boolean)` => `void`
+
+Handles visibility changes of the sidenav component to handle the component state accordingly.
+
+#### `resizingChangeHandler(isResizing: boolean)` => `void`
+
+Handles changes when the sidenav is resized, to handle the state accordingly.
+
+#### `navigateToChildren(itemRef: DfSidenavItemComponent | null | undefined)` => `void`
+
+Method to add the given item to the mobile navigation stack
+
+#### `navigateBack()` => `void`
+
+Method to navigate back in the mobile navigation stack
+
+## `df-sidenav-input` — Component
+
+_Since 22.0_
+
+A wrapper of the DfSidenavComponent driven by a data array provided as an input. All inputs are forwarded to the underlying DfSidenavComponent.
+
+### Inputs
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| className | `string` | `''` | Class name applied to the underlying DfSidenavComponent host element. |
+| collapsible | `boolean` | `true` | Flag whether the sidenav should have the collapse button. |
+| disableInitialDesktopAutoScroll | `boolean` | `false` | Flag to disable the automatic scroll to active link on desktop when the sidenav is initialized. |
+| enableMobile | `boolean` | `true` | Flag to enable the mobile sidenav display of the items. |
+| items | `DfSideNavInputNode[]` | `[]` | Navigation items to render in the sidenav. |
+| resizable | `boolean` | `false` | Flag whether the sidenav should be resizable. |
+| searchable | `boolean` | `false` | Flag whether the sidenav includes a search input. |
+
+### Properties
+
+| Name | Type | Description |
+|------|------|-------------|
+| isMinimized | `Signal<boolean>` | Whether the sidenav is currently minimized. |
+
+### Methods
+
+#### `toggleMinimize(minimized: boolean | undefined)` => `void`
+
+Toggle or set the minimized state of the sidenav.
+
+## `[dfSidenavIcon]` — Directive
+
+_Since 21.0.0_
+
+Utility directive for marking icon content in sidenav items and links. Needed for identification of the projected icon content. Use in case if there is no icon provided with font-awesome.
+
+## `df-sidenav-link` — Component
+
+_Since 21.0.0_
+
+Sidenav link that can be used inside or directly inside the
+
+### Inputs
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| active | `boolean` |  | Explicitly sets the active state of the link. When provided, the link renders as a plain <a href> (no Angular Router). When undefined (default), the Angular Router determines the active state. |
+| icon | `string` | `''` | The icon class name or inline content (e.g., font awesome class) |
+| label | `string` |  | The label of the link |
+| linkPath | `string` |  | The router link path for to the link |
+| routerLinkActiveOptions | `IsActiveMatchOptions \| { exact: boolean }` | `{ exact: false }` | Options to determine when the router link is considered active |
+
+## `df-sidenav-item` — Component
+
+_Since 21.0.0_
+
+Sidenav element that should be nested inside or
+
+### Inputs
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| icon | `string` | `''` | Optional icon class for the sidenav item |
+| label | `unknown` |  | Label of the sidenav item |

package/.ai/docs/components/sidenav/developer.md

@@ -0,0 +1,14 @@
+> **Tip:** Open them in a new tab with the button **Open in new tab** to observe the layout on different screen breakpoints. If you toggle `Device toolbar` in the **Developer Tools** and refresh the page the Sidenav will use the mobile layout.
+
+SideNav should be used together with [TopNav](/components/topnav/overview) as a part of the [Navigation Pattern](/patterns/navigation-pattern/overview).
+
+SideNav has two main elements:
+
+- [SidenavItemComponent](https://github.com/Amadeus-xDLC/design-factory.design-system/blob/main/projects/angular/components/sidenav/sidenav-item/sidenav-item.component.ts) - should be nested inside the SideNav and is a container for the Links
+- [SidenavLinkComponent](https://github.com/Amadeus-xDLC/design-factory.design-system/blob/main/projects/angular/components/sidenav/sidenav-link/sidenav-link.component.ts) - should be nested inside the SideNav and is a leaf component that handles navigation
+
+Both of these elements can contain icon, although it is allowed only on the root level (not nested). When collapsed the presense of the icon impacts the display by showing only respecive icon and having a bigger width. Below you can observe examples with and without icons respectively.
+
+> Demo source: [docs/demos/sidenav/sidenav-basic-with-icon/](../../demos/sidenav/sidenav-basic-with-icon/)
+
+> Demo source: [docs/demos/sidenav/sidenav-basic-no-icon/](../../demos/sidenav/sidenav-basic-no-icon/)

package/.ai/docs/components/sidenav/guidelines.md

@@ -0,0 +1,83 @@
+The SideNav comes in two variants: **expanded** (default) and **collapsed** (optional).  
+Each variant is structured around three main areas:
+
+- **Header (1)** _(optional)_: Can include a CTA button or a search field to filter the menu.
+- **Content (2)**: Main area containing the navigation tree. It includes two types of items:
+  - **Pages** → Open a page
+  - **Folders** → Group pages or sub-folders without loading a page
+- **Expand/Collapse trigger (3)** _(optional)_: Switches between two predefined widths of the SideNav.
+
+The SideNav supports different configurations depending on the level of complexity or guidance needed.
+The expanded variant remains the default, offering clearer structure and easier scanning, while the collapsed variant is optional and best suited for experienced users.
+The following Do/Don't guidelines help ensure a consistent and efficient navigation experience.
+
+- Mix the use of pages and folders in the navigation, allowing for a parent item to contain both sub-pages and sub-folders, enabling more adaptability to the user needs.
+- Do restrict the use of icons to the first level for a distinct and meaningful navigation.
+
+- Don't use the SideNav in it's collapsed variant only. The default variant is the expanded one, which allows for a richer experience and faster understanding of the navigation. Collapse variant only works once the user is used to the Navigation of the UI and doesn't require as much information.
+- An item containing sub-pages, should be a folder, and therefore not have content of its own. This way the menu is simplified, and when clicking on an item only one action is possible avoiding confusion (folder will expand it's content on the sideNav; pages will load its content on the right).
+- Don't have more than three levels of navigation in the SideNav, allowing for a flatter structure, which supports faster scanning and better information visibility.
+
+> **Info:** Previous version had a white background, however we have decided to go for a light blue background for the revamp of the SideNav. White version is still available but keep in mind that it should be used when there is no other solution. **Brand compliance & enforcement**: using only blue reinforces the Amadeus brand and theme, whereas the a white version could end up looking more like a white label type of component, or dilute the identity by having too many options. **Differentiation**: using a blue tint, allows for the Navigation to pop from the rest of the content, but at the same time, having the option to collapse the Navigation, we can keep the Navigation hidden and non obstructive. For more information on the subject, please check the Navigation pattern.
+
+SideNav is part of the Navigation pattern proposed by Amadeus, and is always combined with the TopNav. However, TopNav may be used standalone, without the need of a SideNav.
+
+Navigations levels can be split between the TopNav and the SideNav: having the 1st level at the TopNav, and levels 2 to 4 on the SideNav. Or relying solely on the SideNav for the Navigation, allowing to have up to three levels. If additional levels are required, other components are to be used in combination, such as Scrollspy.
+
+Within the SideNav, items display different states depending on the current page and the user’s actions.  
+The example below highlights the main states you will encounter.
+
+Visible states in the image:
+
+- Active (No active level) **(1)** **(2)**
+- Active (Active level) **(3)**
+- Default (page) **(4)**
+- Default (folder) **(5)**
+
+The SideNav includes several interactions to support smooth navigation: expanding or collapsing the component, opening or closing rows, showing tooltips for long names, and loading the selected page. These behaviours follow the same motion and feedback principles used across DF components.
+
+Clicking the expand/collapse button triggers the animation: the button flips horizontally and the SideNav grows or shrinks.  
+On large screens, the overlay on the right disappears when expanded, and the content adjusts to the new available width.
+
+During expansion:
+
+- The SideNav widens to the right.
+- CTA buttons and search inputs keep their position and grow horizontally.
+- Items appear progressively (icons first, then text). Parent folders open automatically to reveal the active page.
+- An overlay briefly covers the page content while resizing.
+
+During collapse:
+
+- All open sections close before shrinking.
+- The SideNav contracts to the left until only icons remain (or nothing when no icons are used).
+- CTA and search inputs reduce to icon buttons.
+- The overlay fades out as the SideNav shrinks.
+
+Selecting a row with children rotates the chevron upward while revealing the nested items.  
+Closing the row rotates the chevron downward and collapses the sub-items back under their parent.
+
+If a label is too long, it shows an ellipsis. Hovering displays a tooltip with the full name, aligned to the row and positioned on its right.
+
+Clicking a page item loads its content on the right. No additional animation is required for this action.
+
+There are two flavours to the SideNav, one adapted to most screens, present in Figma under the name SideNav v2, and another one more adapted to smaller screens, present in Figma under the name SideNav_mobile v2.
+
+SideNav_mobile has some variation compared to the regular size that we have seen throughout this guide: the collapse/expand button is fused into the top bar, and replaced by a hamburger menu. Additionally some items from the TopNav may appear in the SideNav.
+
+**To test the mobile experience, open your browser’s developer tools and activate mobile view instead of only adjusting the window size.**
+
+> **Info:** For more details, on this flavour, please wait for the review of the new TopNav component, and navigation patterns.
+
+When there is a lot of elements on the side nav, a scroll option becomes available to be able to see the whole content. This is specially relevant when the height of the viewport isn't very large.
+
+The bottom of the SideNav containing the collapse/expand trigger is on a layer above the rest of the items of the SideNav, meaning items scroll underneath it. Additionally a small shadow appears in those cases, to show there is additional content, and scroll is needed to view the whole thing.
+
+> **Warning:** We advise against having too many items on the SideNav (for example more than 10 items at the same level), if this is your case, you might need to review the Information Architecture of your whole ecosystem.
+
+The possible CTA button, Search bar and Expand/Collapse trigger work as regular Button or Icon button with their corresponding states.
+
+Items on the SideNav should contain meaningful names, allowing user to easily and uniquely identify the different parts of your UI.
+
+We recommend using names with a maximum of 24 characters, to ensure the whole text is visible at a glance on the default size of the SideNav, even on items on Level 3 with smaller width space.
+
+> **Tip:** For a full view on UX Writing guidelines, check the following document: [Amadeus UX Writing Style Guide (Brecht ALGOET_Marcos LLORENS).docx](<https://amadeusworkplace.sharepoint.com/:w:/r/sites/UXCommunity_official/_layouts/15/Doc.aspx?sourcedoc=%7BB0C79089-403F-41AE-AFA3-C5BEDFCB8254%7D&file=Amadeus%20UX%20Writing%20Style%20Guide%20(Brecht%20ALGOET_Marcos%20LLORENS).docx&action=default&mobileredirect=true>)

package/.ai/docs/components/sidenav/overview.md

@@ -0,0 +1,16 @@
+Use a SideNav when your application or website requires persistent, structured access to multiple sections or features. It is especially effective in layouts with complex hierarchies, dashboards, or tools where users need to switch contexts frequently without losing their place. Sidenavs help maintain orientation and reduce cognitive load by keeping navigation visible and consistent.
+
+- Use the SideNav when three or more levels navigation are required.
+- Use the SideNav when the user has to switch between pages of the UI with frequency.
+- Use the SideNav on the left, for left to right UIs, and use it on the right on right to left UIs.
+
+- Don't use the SideNav for simple UI with a limited information architecture. In such cases it is better to rely solely on the TopNav.
+- Don't use the SideNav standalone, always combine it with a TopNav (at least a basic one with only the logo).
+
+SideNav is part of the Navigation pattern proposed by Amadeus, and is always combined with the TopNav. However, TopNav may be used standalone, without the need of a SideNav.
+
+Navigations levels can be split between the TopNav and the SideNav: having the 1st level at the TopNav, and levels 2 to 4 on the SideNav. Or relying solely on the SideNav for the Navigation, allowing to have up to three levels. If additional levels are required, other components are to be used in combination, such as Scrollspy.
+
+> **Info:** Not sure which component to use? Check the [Navigation pattern](/patterns/navigation-pattern) for more in depth details.
+
+</div>

package/.ai/docs/components/tooltip/accessibility.md

@@ -0,0 +1,11 @@
+- Tooltips appear when the trigger element receives keyboard focus
+- Tooltips themselves are not focusable
+- Pressing Esc dismisses the tooltip
+- Keyboard navigation is never trapped by the tooltip
+
+- Tooltip content is announced by screen readers when the trigger receives focus
+- Screen readers read the trigger first, followed by the tooltip content
+
+Tooltips must not contain information required to understand or operate the interface.
+
+The tooltip text is associated with the trigger using aria-describedby.

package/.ai/docs/components/tooltip/api.md

@@ -0,0 +1,39 @@
+# Tooltip — API
+
+## `[dfTooltip]` — Directive
+
+_Since 22.0_
+
+A directive that attaches a tooltip to its host element. The tooltip is shown when the host element is hovered, receives keyboard focus or long press, and hidden when the mouse leaves, the element loses keyboard focus, or the user presses Escape. The tooltip window is rendered in document.body and positioned next to the host using the configured placement preference.
+
+### Inputs
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| dfTooltip | `string \| null \| undefined` |  | Text content to be displayed inside the tooltip. |
+| dfTooltipAnimated | `boolean \| undefined` |  | Whether showing or hiding the tooltip should be animated. |
+| dfTooltipDisabled | `boolean \| undefined` |  | Whether the tooltip is disabled. When true, the tooltip will not be displayed, even if the reference element is focused, hovered or long-pressed. |
+| dfTooltipPlacement | `DfTooltipPlacementArray \| undefined` |  | List of placements, in order of preference. The first valid placement will be used. |
+| dfTooltipSize | `DfTooltipSize \| undefined` |  | Size of the tooltip. |
+
+## DfTooltipConfig — Configuration
+
+_Since 22.0_
+
+Configuration options supported by provideDfTooltipConfig. These defaults apply to every DfTooltip instance within the providing injector, unless explicitly overridden on the directive itself.
+
+### Properties
+
+| Name | Type | Description |
+|------|------|-------------|
+| animated | `boolean` | Whether showing or hiding the tooltip should be animated. |
+
+### Methods
+
+#### `provideDfTooltipConfig(config: Partial<DfTooltipConfig> | ((prevConfig: Partial<DfTooltipConfig>) => Partial<DfTooltipConfig>) | undefined)` => `FactoryProvider`
+
+Provides the configuration for the tooltip component.
+
+#### `injectDfTooltipConfig()` => `WritableSignal<Partial<DfTooltipConfig>>`
+
+Injects the configuration for the tooltip component.

package/.ai/docs/components/tooltip/developer.md

@@ -0,0 +1,16 @@
+Add the `dfTooltip` directive to a focusable element and pass the tooltip content as its value.
+
+> Demo source: [docs/demos/tooltip/basic/](../../demos/tooltip/basic/)
+
+Use the `dfTooltipSize` input to adjust the tooltip size. Supported values are `'sm'`, `'md'` (default) and `'lg'`.
+
+> Demo source: [docs/demos/tooltip/sizes/](../../demos/tooltip/sizes/)
+
+It is recommended to use the default auto-placement behavior. This ensures that the tooltip is always visible and doesn't get cut off.
+If you need to specify preferred placements, use the `dfTooltipPlacement` input to control where the tooltip appears relative to its reference element.
+Pass either a space-separated list or an array of placements, ordered by preference. The first placement that fits the viewport will be used.
+
+Prefer the `'auto'`, `'vertical'` and `'horizontal'` shortcuts so the positioning system can automatically adapt to the available
+space. The `'start'` and `'end'` placements are direction-aware and automatically flip for right-to-left layouts.
+
+> Demo source: [docs/demos/tooltip/placements/](../../demos/tooltip/placements/)