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

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

@@ -0,0 +1,84 @@
+- Tooltip container **(1)** is the floating surface that displays the text.
+- Text content **(2)** is the plain text only, providing short contextual information.
+- Trigger element **(3)** is the element that activates the tooltip (icon, button, text, etc.).
+
+This is the default and recommended tooltip variant across the product.
+
+- Tooltip is displayed **above the trigger**, at a distance of 4px.
+- Tooltip container is **center‑aligned** with the trigger
+- Placement automatically adapts to avoid being rendered outside the viewport
+
+The tooltip container must not exceed **320px** in width. When the content is longer than the available space, the text **wraps automatically onto multiple lines**.
+
+- Keep the tooltips compact and easy to scan
+- Keep text to **one short sentence** whenever possible
+- Allow the system to handle placement automatically
+- Allow text to wrap naturally within the container
+
+- Don’t manually force placement unless strictly necessary
+- Don’t create tooltips wider than 320px.
+- Don’t truncate text or rely on horizontal scrolling.
+- Don’t obscure the trigger element
+
+Placement of the tooltip is automatic. It will try to be placed in the default placement, and if it is not possible (tooltip doesn’t fit within the screen), it will try the alternative placement shown below in order.
+
+In special cases, a specific variant can be forced but the use of such enforcement is not recommended (e.g. it could be forced to show tooltips of the SideNav on the side instead of the default above)
+
+- Rely on automatic placement to prevent screen overflow
+- Ensure tooltips remain fully visible within the viewport
+
+- Don’t disable adaptive placement
+- Don’t allow tooltips to be clipped by the viewport
+
+1. top (default): tooltip is placed above the trigger, with the tooltip container center aligned with the trigger.
+2. top-start: tooltip is placed above the trigger, with the tooltip container left aligned, on left-to-right UI (on right-to-left, alignment is on the right).
+3. top-end: tooltip is placed above the trigger, with the tooltip container right aligned, on left-to-right UI (on right-to-left, alignment is on the left).
+
+1. bottom: tooltip is placed below the trigger, with the tooltip container center aligned with the trigger.
+2. bottom-start: tooltip is placed below the trigger, with the tooltip container left aligned, on left-to-right UI (on right-to-left, alignment is on the right).
+3. bottom-end: tooltip is placed below the trigger, with the tooltip container right aligned, on left-to-right UI (on right-to-left, alignment is on the left).
+
+1. end: tooltip is placed next to the trigger, on the right (on left-to-right UI), with the tooltip container center aligned with the trigger.
+2. end-end: tooltip is placed next to the trigger, on the right (on left-to-right UI), with the tooltip container and the trigger bottom aligned.
+3. end-start: tooltip is placed next to the trigger, on the right (on left-to-right UI), with the tooltip container and the trigger top aligned.
+
+1. start: tooltip is placed next to the trigger, on the left (on left-to-right UI), with the tooltip container center aligned with the trigger.
+2. start-end: tooltip is placed next to the trigger, on the left (on left-to-right UI), with the tooltip container and the trigger bottom aligned.
+3. start-start: tooltip is placed next to the trigger, on the left (on left-to-right UI), with the tooltip container and the trigger top aligned.
+
+Tooltips are triggered by user interaction with the trigger element:
+
+- **Mouse:**
+  - Appears on hover
+  - Disappears on mouse leave
+- **Keyboard:**
+  - Appears when the trigger receives focus
+  - Disappears on blur or when pressing Esc
+- **Touch:**
+  - Appears on long press
+  - Disappears when tapping outside
+
+A short delay is applied before displaying the tooltip to avoid accidental activation.
+
+Consideration to have:
+
+- On **desktop**, tooltips are triggered by hover and focus.
+- On **touch devices**, tooltips rely on long‑press interactions.
+- Tooltips must never block or interfere with core interactions on small screens.
+
+If information becomes important on mobile, prefer **inline help text** instead.
+
+Regardless of screen size, the tooltip never exceeds 320px in width. On smaller viewports, content continues to wrap vertically to preserve readability.
+
+Tooltip text must be:
+
+- Plain text only
+- Short and easy to scan
+- Written in sentence case
+- Focused on explaining what or why, not how
+
+- "Refreshes the data"
+- "Only visible to administrators"
+
+- "Click here to refresh the data"
+- "This button allows you to refresh the data displayed on the page"

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

@@ -0,0 +1,23 @@
+A **Tooltip** is a small, non‑interactive overlay that displays short, **plain‑text information** when users hover over, focus on, or long‑press an element.
+
+Tooltips are used to **clarify the purpose of a control**, explain an icon, or provide brief contextual hints **without interrupting the user's flow**.
+
+Tooltip content is **always optional** and must not contain information that is required to understand or use the interface.
+
+- Use tooltips to clarify **icon‑only controls** or ambiguous UI elements
+- Keep content **short, concise, and plain text only**
+- Trigger tooltips on **hover and keyboard focus**
+- Use tooltips as **supporting information**, not primary guidance
+
+- Don’t include rich text, links, or interactive elements
+- Don’t use tooltips for long explanations or instructions
+- Don’t place critical or mandatory information in a tooltip
+- Don’t rely on tooltips as the only way to understand an interface
+
+Tooltips are often confused with other informational components:
+
+- **Tooltip**: Use for short, plain‑text hints tied to a specific UI element.
+- **Popover**: Use when richer information, structured content, or interactions are required.
+- **Toast**: Use for system feedback unrelated to a specific control.
+
+If information must be visible to all users or is essential to task completion, **do not use a tooltip**, instead write it in plain text.

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

@@ -0,0 +1,51 @@
+TopNav must be fully usable with keyboard-only interaction. Navigation order and behavior should stay consistent across desktop and mobile modes.
+
+> **Info:** WCAG guidance for disclosure navigation menus is a good baseline for TopNav behavior: [View WCAG Disclosure Navigation Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/examples/disclosure-navigation/).
+
+When users tab into TopNav from content above, focus should land on the first focusable element from left to right.
+
+- If **Search** is present and focusable, **Search** receives first focus.
+- If **Search** is not present, focus should land on the first focusable navigation control.
+- If a skip link is available before TopNav, users should still be able to move directly to main content.
+
+Screen readers should announce the region as a navigation landmark with the number of available items.
+
+`Tab` moves focus to the next focusable control. `Shift+Tab` moves focus to the previous control.
+
+Arrow keys are mainly relevant in screen-reader and menubar navigation contexts.
+
+- `ArrowRight` reads or moves to the next item.
+- `ArrowLeft` reads or moves to the previous item.
+- If a grouped control is expanded, arrow keys should continue movement within that group before leaving it.
+
+Arrow keys should not trigger unexpected page scrolling while the user is navigating TopNav controls.
+
+- If the focused item is expandable, `Enter` and `Space` expand it.
+- If the focused item is collapsible, `Enter` and `Space` collapse it.
+- If the focused item is a navigation destination, `Enter` and `Space` activate it.
+
+- `Home` moves focus to the first TopNav item in the current row.
+- `End` moves focus to the last TopNav item in the current row.
+
+ 
+
+Screen Readers should read:
+
+1. read: **Amadeus text icon**
+2. read: **input search**
+3. read: **TopNav button**
+4. read: **"item name", visit the page**
+
+TopNav should not introduce heading-level jumps in page content.
+
+- Keep page heading structure in the content area.
+- Keep TopNav labels short and descriptive.
+
+Expose TopNav as a navigation landmark so assistive technologies can locate it quickly.
+
+- Announce it as top navigation with the number of items when possible.
+- Keep landmark naming consistent across pages.
+
+For users who zoom up to 300%, apply responsive TopNav behavior and preserve keyboard operability.
+
+> **Warning:** Do not rely on horizontal scrolling to keep TopNav usable at high zoom. Move lower-priority actions into overflow behavior before reducing hit targets.

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

@@ -0,0 +1,190 @@
+# TopNav — API
+
+## `df-topnav` — Component
+
+_Since 21.1_
+
+TopNav (Top Navigation Bar) provides consistent access to product-level navigation and global actions across Amadeus applications. It is recommended to be used with a DfAppContainer to ensure the correct layout and responsiveness, but it can also be used without it if needed. See Design Factory documentation for details and examples.
+
+### Inputs
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| mainNavStyle | `'basic' \| 'mirror'` |  | The style of the TopNav main nav, which determines the applied styles. Can be either "basic" or "mirror". If navigation links are present this input is ignored and the applied style will be determined based on the number of navigation links and the superheader input. |
+| mode | `'sidenav' \| 'dropdown'` | `'sidenav'` | The mode of the TopNav, which determines the behavior of the navigation. Can be either "sidenav" or "dropdown". |
+| showToggle | `boolean` | `false` | When set to true, the toggle button will be always shown. Useful when the TopNav is used without any navigation links but the toggle button is still needed to access other content. When not provided, the toggle button will be shown automatically when there are navigation links and the screen size is smaller than large. |
+| superheader | `boolean` |  | When set to true, the superheader layout will be applied, which moves the navigation to a second line and applies the "mirror" style to it. When not provided, the superheader layout will be applied automatically when there are more than 5 navigation links and the screen size is large or bigger. |
+
+## `df-env-banner` — Component
+
+_Since 21.1_
+
+The environment banner component, used to display a banner at the top of the page indicating the current environment (e.g., development, staging, production). See Design Factory example
+
+## `df-app-container` — Component
+
+_Since 21.1_
+
+AppContainer is a simple wrapper component that provides a consistent layout for applications using the DfTopNav component. It ensures that the content of the application is displayed correctly below the DfTopNav and can be used to apply common styles or layout properties to the entire application. See Design Factory documentation for details and examples.
+
+## `df-topnav-quick-actions` — Component
+
+_Since 21.1_
+
+The TopNav quick actions component, used to display a list of quick action buttons in the TopNav. On large screens, the buttons are displayed inline, while on smaller screens, they are displayed in a drawer. See Design Factory example
+
+### Inputs
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| reversedVertical | `boolean` | `true` | When true, the quick action buttons will be displayed in reversed order in the drawer on smaller screens. This is useful when the quick actions are defined in the template in the same order as the navigation items, so that the first quick action is closest to the navigation on smaller screens. Defaults to true. |
+| tabletDrawerContainer | `HTMLElement` |  | The container element in which the drawer will be rendered on smaller screens. By default, it will try to render in the drawer container provided by the app container, and if not available, it will render in the body element. This input can be used to specify a different container element for the drawer. |
+
+## `ng-template[dfTopNavQuickActionInTopNav]` — Directive
+
+_Since 21.1_
+
+The TopNav action "in topnav" content directive. It drives the display of the DfTopNavQuickAction on larger screens, where the quick action is displayed in a topnav.
+
+## `ng-template[dfTopNavQuickActionInDrawer]` — Directive
+
+_Since 21.1_
+
+The TopNav action "in drawer" content directive. It drives the display of the DfTopNavQuickAction on smaller screens, where the quick action is displayed in a drawer.
+
+## `df-topnav-quick-action` — Component
+
+_Since 21.1_
+
+The TopNav quick action component, used to display a quick action in the TopNav. Consider using the DfTopNavQuickActionButton component instead, which provides a button with the appropriate styling and behavior for quick actions in the TopNav. It should be used inside a DfTopNavQuickActions component. It requires a DfTopNavQuickActionInTopNav template to be provided as content, which will be displayed in desktop. An optional DfTopNavQuickActionInDrawer template can also be provided, which will be displayed in mobile and tablet instead of the topnav template. See Design Factory example
+
+## `df-topnav-quick-action-theme-picker` — Component
+
+_Since 21.1_
+
+DfTopNavQuickActionThemePicker is a topnav quick action dropdown component that allows users to select a theme mode for the application. It uses the DfThemeService to manage theme state and apply the selected theme. The component displays an icon and label corresponding to the current theme selection and provides options for users to change the theme.
+
+### Inputs
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| appearance | `'primary' \| 'neutral'` | `'neutral'` | The appearance of the TopNav button, which will determine its color. It can be either 'primary' or 'neutral'. |
+| themeOptions | `{ themeMode: string; icon: string }[]` |  | An array of theme options to display in the dropdown Each option includes a themeMode which corresponds to a theme mode in the DfThemeService, and an icon which is a FontAwesome class name for the icon to display next to the option. |
+
+## `input[dfTopNavQuickActionSearchInput]` — Component
+
+_Since 21.1_
+
+The TopNav quick action search input directive. It should be used inside a DfTopNavQuickActionSearch component.
+
+## `df-topnav-quick-action-search` — Component
+
+_Since 21.1_
+
+The TopNav quick action search component, used to display a search input in the TopNav quick actions. It should be used inside a DfTopNavQuickActions component and contain a ng-template with an input DfTopNavQuickActionSearchInput. See Design Factory example
+
+### Inputs
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| ariaLabel | `string` |  | The aria-label of the search. It is required to set it if you have more than one global search in your page, to allow assistive technologies to differentiate between them. See ARIA guidelines for more information. |
+
+## `ng-template[dfTopNavQuickActionButtonContent]` — Directive
+
+_Since 21.1_
+
+The TopNav action content directive, used to provide the content of the popover or drawer associated to a DfTopNavQuickActionButton. It is showed in a popover in desktop and in a drawer on tablet and mobile when the associated quick action button is clicked.
+
+## `ng-template[dfTopNavQuickActionButtonIcon]` — Directive
+
+_Since 21.1_
+
+The TopNav action icon directive, used to provide a custom icon for the DfTopNavQuickActionButton. If not provided, the quick action button will use the default icon specified by the DfTopNavQuickActionButton.icon input.
+
+## `df-topnav-quick-action-button` — Component
+
+_Since 21.1_
+
+The TopNav quick action button component, used to display a quick action button in the TopNav. It should be used inside a DfTopNavQuickActions component. It can be associated with a popover content using the DfTopNavQuickActionButtonContent directive or be used alone with the DfTopNavQuickActionButton.act output. The icon can be set through the DfTopNavQuickActionButton.icon input or by using the DfTopNavQuickActionButtonIcon directive. See Design Factory example
+
+### Inputs
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| appearance | `'primary' \| 'neutral'` | `'neutral'` | The appearance of the quick action button, which will determine its color. It can be either 'primary' or 'neutral'. |
+| disabled | `boolean` | `false` | Whether the quick action button is disabled or not. |
+| icon | `string` |  | The icon of the quick action button. |
+| label | `string` |  | The label of the quick action button, which will be used as the aria-label attribute for accessibility on desktop and label in the drawer. |
+
+### Outputs
+
+| Name | Type | Description |
+|------|------|-------------|
+| act | `void` | The event emitted when the quick action button is clicked. It can be used to perform an action instead of showing the associated popover or drawer content. |
+
+## `df-topnav-navigation` — Component
+
+_Since 21.1_
+
+The TopNav navigation component, used to display a list of navigation items in the TopNav.
+
+## `df-topnav-navigation-link` — Component
+
+_Since 21.1_
+
+The TopNav navigation item component, used to display a navigation link in the TopNav. It should be used inside a DfTopNavNavigation component.
+
+### Inputs
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| href | `string` |  | The external href of the navigation link, which will be used as the link target. Use routerLink for internal links. |
+| label | `string` |  | The label of the navigation link, which will be displayed as the link text. |
+| routerLink | `string` |  | The internal router link of the navigation link, which will be used as the link target. Use href for external links. |
+| routerLinkActiveOptions | `IsActiveMatchOptions \| { exact: boolean }` | `{ exact: false }` | The options to determine when the link is active based on the Router state. It can be either an object of type IsActiveMatchOptions or an object with an "exact" boolean property. When not provided, it defaults to { exact: false }. |
+
+### Properties
+
+| Name | Type | Description |
+|------|------|-------------|
+| active | `Signal<boolean>` | Indicates if the link is currently active based on the Router state. |
+
+## `df-topnav-navigation-item` — Component
+
+_Since 21.1_
+
+The TopNav navigation item component, used to display a navigation link in the TopNav which can have child navigation links. It should be used inside a DfTopNavNavigation component.
+
+### Inputs
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| label | `string` |  | The label of the navigation item, which will be displayed as the link text. |
+| routerLink | `string` |  | The routerLink of the navigation item, which will be used as the link target. It should be an internal route. |
+
+### Properties
+
+| Name | Type | Description |
+|------|------|-------------|
+| active | `Signal<boolean>` | Indicates if the navigation item is currently active based on the Router state of its child links. |
+
+## `ng-template[dfTopNavBrandLinkContent]` — Directive
+
+_Since 21.1_
+
+A directive to mark the company template in the DfTopNavBrand brand component. This is used to customize the display of the company logo and name in the DfTopNavBrand brand component.
+
+## `df-topnav-brand` — Component
+
+_Since 21.1_
+
+The TopNav brand component, used to display the company and product information. See Design Factory example
+
+### Inputs
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| amaudeusLogoVector | `boolean` | `false` | Whether to display the Amadeus logo as a vector graphic instead of text. |
+| href | `string` | `'/'` | The URL to navigate to when the brand is clicked. Defaults to "/". |
+| module | `string` |  | The module. |
+| product | `string` |  | The product. |

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

@@ -0,0 +1,43 @@
+> **Tip:** Open them in a new tab with the button **Open in new tab** to observe the layout on different screen breakpoints.
+
+The first part of a TopNav is the brand, which is used to display the product logo and name. It is a link re-directing to the homepage of the product.
+
+The default behavior is showing Amadeus as the brand company, but it can be customized by providing a custom template with the `dfTopNavBrandLinkContent` directive.
+
+> Demo source: [docs/demos/topnav/brand/](../../demos/topnav/brand/)
+
+The second part of a TopNav is the navigation. It is used to configure the links of the app.
+
+The default behavior creates one nav when the number of root nodes is **five or less** and two navs when the number of root nodes is **more than five**.  
+This behavior can be overriden by setting the `superheader` input of the topnav.
+
+This first example showcases a flat navigation i.e. only root links.
+
+> Demo source: [docs/demos/topnav/navigation/](../../demos/topnav/navigation/)
+
+This second example showcases a tree navigation i.e. links with sub-links.
+
+You can set the input `mode` to `dropdown` in order to show dropdowns instead of a sidenav on desktop. Note that this is only supported for a navigation nesting level of two or less.
+
+> Demo source: [docs/demos/topnav/navigation/](../../demos/topnav/navigation/)
+
+The third part of the TopNav contains the quick actions.  
+Quick actions can be user login, settings, notiications and more.
+
+The component `DfTopNavQuickActionButton` allows to configure the look and the content of a quick action.
+
+- For things like settings and notifications, you may set a template using the `dfTopNavQuickActionContent` directive that will be shown in a popover in desktop and in the drawer in mobile.
+- For other actions, you can listen to the `act` output and perform the desired action.
+
+You can also use:
+
+- `DfTopNavQuickActionSearch` to setup a global search.
+- `DfTopNavQuickActionThemePicker` to allow users to select a theme mode for the application.
+- `DfTopNavQuickAction` for full control over the quick action content.
+- `DfTopNavQuickActionThemePicker` to setup a light / dark mode picker
+
+> Demo source: [docs/demos/topnav/quick-actions/](../../demos/topnav/quick-actions/)
+
+The environment banner is used to display the current environment of the application, such as "Test Environment" or "Production Environment".
+
+> Demo source: [docs/demos/topnav/environment-banner/](../../demos/topnav/environment-banner/)

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

@@ -0,0 +1,121 @@
+The TopNav is structured around four areas.
+
+- **Branding (1):** contains logo and product name. It should link to the product default page.
+- **Search (2):** optional search entry point. It can be input based or icon only based on available width.
+- **Quick actions (3):** optional global actions such as tenant, app switcher, AI, help, notifications, and profile.
+- **Menu (4):** first level navigation with items and optional dropdowns for grouped destinations.
+
+Practical guidance:
+
+- Keep product and module names concise so they remain readable on tablet widths.
+- Keep first level menu labels to one or two words when possible.
+- Use the quick action area only for actions that remain useful regardless of the page the user is on.
+
+ 
+
+> **Warning:** In general, please use **"Amadeus (in Amadeus font) + Product name"**. The combination of **"Amadeus (woodmark) + website name"** is **reserved for corporate website** such as [Amadeus.com](https://amadeus.com), Amadeus Careers... For a full detail on when to use which, please refer to the following brand guidelines: [https://www.figma.com/design/MRzMbwwtkOz1Ct9MBHYXPY/Product-naming-in-UI-guide?node-id=3-56&t=IHx83kSSIV5I38im-1](https://www.figma.com/design/MRzMbwwtkOz1Ct9MBHYXPY/Product-naming-in-UI-guide?node-id=3-56&t=IHx83kSSIV5I38im-1)
+
+- Do keep the order of branding, navigation, and actions stable across pages.
+- Do provide accessible names for icon only actions and show tooltips on hover and focus.
+- Do ensure the active first level destination remains clearly visible.
+
+- Don't place page local actions in the quick actions area.
+- Don't use the branding area for temporary campaign content.
+- Don't mix first level and deep hierarchy items in the same row.
+
+TopNav has three main variants based on first level navigation density.
+
+Use this variant when navigation happens through landing flows or when global actions are the primary goal.
+
+Use this as the default variant. It balances strong navigation visibility with enough room for global actions.
+
+Use the two row superheader when first level navigation has more than five critical destinations that must remain visible.
+
+- Do choose the smallest variant that keeps essential destinations visible.
+- Do move low frequency destinations to secondary menus before moving to a superheader.
+- Do validate localized labels because translated terms often require more horizontal space.
+
+- Don't reserve empty slots for future items.
+- Don't switch variants across pages without a clear information architecture reason.
+- Don't keep crowded one row navigation when users struggle to scan labels quickly.
+
+Other variants combine environment banners and dropdown capabilities to support ecosystem and navigation complexity.
+
+ 
+
+Use an environment banner when users must stay aware of environment or context, for example production versus test, or when they switch between tenant contexts.
+
+ 
+
+Use dropdowns only when grouped destinations are genuinely related and users can predict the group content from the trigger label. If a SideNav is already present, keep the hierarchy there to avoid two competing navigation models.
+
+- Do use environment banners only when users can take actions with high impact in the wrong context.
+- Do keep dropdown groups short and semantically consistent.
+- Do expose the current context clearly when a tenant or environment is active.
+
+- Don't use environment banners for purely decorative messaging.
+- Don't hide first level destinations in deep dropdown structures.
+- Don't create overlapping groups where the same destination appears in multiple dropdowns.
+
+ 
+
+> **Info:** TopNav is the primary component of the Amadeus navigation pattern. Keep first level destinations in TopNav, use SideNav for deeper levels, and use Scrollspy for long in page sections.
+
+Global actions support high frequency cross product tasks:
+
+1. **User profile**: opens account actions, profile settings, and sign out.
+2. **Notifications**: surfaces system updates and user specific events.
+3. **Help center**: links to support and contextual assistance.
+4. **AI**: gives access to assistant capabilities.
+5. **App switcher**: lets users move between applications in the same ecosystem.
+6. **Tenant**: shows and changes active tenant or context.
+
+Guidance:
+
+- Keep visual order stable because users develop muscle memory for these actions.
+- Show unread counts only for truly actionable events.
+- Ensure tenant switches are explicit and reversible.
+- Keep icon semantics consistent with other navigation surfaces in the product.
+
+On mobile, selecting the hamburger control morphs the icon into a close icon while the navigation panel slides from left to right. This panel should open with synchronized timing between icon and panel transitions.
+
+Interaction guidance:
+
+- Keep animation short and smooth so state change is clear without delaying navigation.
+- Preserve current page highlight in the opened panel so users keep orientation.
+- Block background content interaction while the mobile panel is open.
+
+Keyboard and focus guidance:
+
+- Enter and Space open and close the mobile panel trigger.
+- Escape closes the panel and returns focus to the trigger.
+- Tab cycles through interactive items in visual order.
+- When dropdowns are present in desktop navigation, arrow navigation should move between sibling items and Escape should close the open dropdown.
+
+Edge cases:
+
+- If labels overflow, keep labels readable through truncation plus tooltip rather than shrinking text.
+- If action count increases, move low priority actions into an overflow menu before reducing hit target size.
+
+TopNav is available in desktop and mobile configurations. Below 1200px first level navigation items are moved to SideNav and are accessed through the hamburger pattern.
+
+| Screen size     | Configuration           | Behaviour                                                                    |
+| --------------- | ----------------------- | ---------------------------------------------------------------------------- |
+| >= 1200px       | Desktop TopNav          | First level navigation stays visible in TopNav.                              |
+| 992px to 1199px | Transitional desktop    | Keep essential actions visible. Prioritize core destinations.                |
+| < 992px         | TopNav mobile + SideNav | Use full width top bar with hamburger trigger and slide in navigation panel. |
+
+For narrow mobile displays, the opened navigation panel should take the full device width so labels remain readable and touch targets remain comfortable.
+
+> **Tip:** Validate responsive behaviour with browser device emulation plus touch interaction testing. Window resizing alone does not reproduce full mobile interaction states.
+
+Use clear and predictable language in TopNav labels so users can decide quickly where each destination leads.
+
+Writing guidance:
+
+- Prefer short nouns or noun phrases with one or two words.
+- Keep naming style consistent across all first level items.
+- Use user facing vocabulary instead of internal team terminology.
+- Prioritize labels that reflect user goals rather than internal system structure.
+
+> **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/topnav/overview.md

@@ -0,0 +1,17 @@
+TopNav provides persistent access to **product identity**, **first level navigation**, and **global actions** such as **search**, **profile**, **notifications**, and **tenant selection**.
+
+Use **TopNav** when users move frequently between major product areas and need this structure to stay visible across pages. Keep the structure stable so users can build navigation memory and switch contexts faster.
+
+- Use TopNav as the primary first level navigation surface for medium and large information architectures.
+- Keep item labels short and concrete so users can scan the menu quickly.
+- Reserve the right action area for global actions that remain relevant regardless of the page the user is on.
+
+- Don't use TopNav as a full command toolbar. Place page specific actions in local page headers.
+- Don't duplicate the same navigation level in TopNav and page body navigation.
+- Don't overload the bar with decorative icons that do not trigger clear actions.
+
+**TopNav** can work on its own for shallow navigation. For richer information architectures, pair **TopNav** with **SideNav** so the first level stays in **TopNav** while deeper levels move into **SideNav**. If a section still needs deep in page navigation, add **Scrollspy** in the content area.
+
+> **Info:** Not sure how to split navigation levels across components? Check the [Navigation pattern](/patterns/navigation-pattern).
+
+</div>

package/.ai/docs/demos/accordion/addons-subtitle/accordion-addons-subtitle.html

@@ -0,0 +1,75 @@
+<df-accordion itemHeadingLevel="3" [subtitleType]="subtitleType()" [addon]="addon()" [arrowPosition]="arrowPosition()">
+  <df-accordion-item
+    [visible]="true"
+    subtitle="Additional info about first item"
+    number="01"
+    iconClass="fa-light fa-home"
+  >
+    <ng-template dfAccordionItemTitle>First item</ng-template>
+    <ng-template dfAccordionItemBody>Content of the first accordion item.</ng-template>
+  </df-accordion-item>
+
+  <df-accordion-item subtitle="Additional info about second item" number="02" iconClass="fa-light fa-user">
+    <ng-template dfAccordionItemTitle>Second item</ng-template>
+    <ng-template dfAccordionItemBody>Content of the second accordion item.</ng-template>
+  </df-accordion-item>
+
+  <df-accordion-item subtitle="Additional info about third item" number="03" iconClass="fa-light fa-cog">
+    <ng-template dfAccordionItemTitle>Third item</ng-template>
+    <ng-template dfAccordionItemBody>Content of the third accordion item.</ng-template>
+  </df-accordion-item>
+</df-accordion>
+
+<hr class="my-6" />
+
+<div class="d-inline-grid gap-4" style="grid-template-columns: auto auto">
+  <label class="form-label fw-semibold mb-0 align-self-center" for="subtitle-none">Subtitle</label>
+  <div class="btn-group btn-group-sm" ngDefaultControl role="radiogroup">
+    <input [(ngModel)]="subtitleType" class="btn-check" id="subtitle-none" name="subtitle" type="radio" value="none" />
+    <label class="btn btn-outline-primary" for="subtitle-none">None</label>
+    <input
+      [(ngModel)]="subtitleType"
+      class="btn-check"
+      id="subtitle-inline"
+      name="subtitle"
+      type="radio"
+      value="inline"
+    />
+    <label class="btn btn-outline-primary" for="subtitle-inline">Inline</label>
+    <input
+      [(ngModel)]="subtitleType"
+      class="btn-check"
+      id="subtitle-block"
+      name="subtitle"
+      type="radio"
+      value="block"
+    />
+    <label class="btn btn-outline-primary" for="subtitle-block">Block</label>
+  </div>
+
+  <label class="form-label fw-semibold mb-0 align-self-center" for="addon-none">Addon</label>
+  <div class="btn-group btn-group-sm" ngDefaultControl role="radiogroup">
+    <input [(ngModel)]="addon" class="btn-check" id="addon-none" name="addon" type="radio" value="none" />
+    <label class="btn btn-outline-primary" for="addon-none">None</label>
+    <input [(ngModel)]="addon" class="btn-check" id="addon-number" name="addon" type="radio" value="number" />
+    <label class="btn btn-outline-primary" for="addon-number">Numbers</label>
+    <input [(ngModel)]="addon" class="btn-check" id="addon-icon" name="addon" type="radio" value="icon" />
+    <label class="btn btn-outline-primary" for="addon-icon">Icon</label>
+  </div>
+
+  <label class="form-label fw-semibold mb-0 align-self-center" for="arrow-start">Arrow</label>
+  <div class="btn-group btn-group-sm" ngDefaultControl role="radiogroup">
+    <input
+      [(ngModel)]="arrowPosition"
+      [disabled]="addon() !== 'none'"
+      class="btn-check"
+      id="arrow-start"
+      name="arrow"
+      type="radio"
+      value="start"
+    />
+    <label class="btn btn-outline-primary" for="arrow-start">Left</label>
+    <input [(ngModel)]="arrowPosition" class="btn-check" id="arrow-end" name="arrow" type="radio" value="end" />
+    <label class="btn btn-outline-primary" for="arrow-end">Right</label>
+  </div>
+</div>

package/.ai/docs/demos/accordion/addons-subtitle/accordion-addons-subtitle.ts

@@ -0,0 +1,27 @@
+import { Component, effect, signal } from '@angular/core';
+import { FormsModule } from '@angular/forms';
+import {
+  DfAccordion,
+  DfAccordionItem,
+  DfAccordionItemBody,
+  DfAccordionItemTitle
+} from '@design-factory/angular/accordion';
+
+@Component({
+  selector: 'df-demo-accordion-addons-subtitle',
+  templateUrl: './accordion-addons-subtitle.html',
+  imports: [DfAccordion, DfAccordionItem, DfAccordionItemBody, DfAccordionItemTitle, FormsModule]
+})
+export class DfDemoAccordionAddonsSubtitle {
+  protected readonly subtitleType = signal<'block' | 'inline' | 'none'>('none');
+  protected readonly addon = signal<'none' | 'icon' | 'number'>('none');
+  protected readonly arrowPosition = signal<'start' | 'end'>('end');
+
+  constructor() {
+    effect(() => {
+      if (this.addon() !== 'none' && this.arrowPosition() === 'start') {
+        this.arrowPosition.set('end');
+      }
+    });
+  }
+}