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

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

@@ -0,0 +1,62 @@
+Icon **(1)** indicates status through shape and color. Title **(2)** summarises the message in one short sentence. Dismiss **(3)** is optional, it allows the user to close the Alert when appropriate. It can be set as self closing and disappears after 5 seconds. You don't need to have the dismiss button to have the self closing. Description **(4)** is here to complete the message alert if it needs a bit more details, but keep it short.
+
+Alerts come in five severity levels:
+
+- **Information:** Neutral contextual message.
+- **Success:** Positive result or confirmation.
+- **Warning:** A potential issue requiring attention.
+- **Error:** A serious problem that may block user progress.
+- **Tip:** Used to give a tip to the user.
+
+The Alert has 3 main variants depending on the placement and the informations provided. Dismiss button is optional in any case. Alert should be placed near the related content or action, however it may be place in a different pre-defined place if needed for concrete use cases.
+
+In this case the Alert can be placed in a lot of places but should be placed near the related content or action.
+
+- Keep text aligned to the left.
+- Use this variant close to the related content.
+- Group same-type alerts when possible.
+
+- Do not overuse alerts on a page.
+- Do not use an alert for destructive confirmations. Use a modal instead.
+- Do not display alerts unrelated to the current user goal.
+
+Working like the basic alert but has the option to have a show more/show less button on the top right. It allows to display more informations in the alert.
+
+- Use this variant for short summaries with optional details.
+- Use it to group multiple alerts from the same category.
+
+- Do not include complex content inside the collapse.
+- Do not exceed three lines per grouped alert message.
+- Do not use timed behavior with collapsible alerts.
+
+Should be used when it is in a global context, and impacts the whole screen. It spans the entire width of the screen, and is placed on the top of the page beneath the TopNav. The container Alert sticks to the top of the page even when scrolling. In this case the alert is attached to its header.
+
+- Use this variant when the message impacts the full page context.
+- Place it under the TopNav.
+- Keep it attached to the related page header when applicable.
+
+- Do not use this variant for content-local feedback.
+
+Use a dismiss button when:
+
+- The message is optional or informational.
+- The user may want to hide it after reading.
+
+Try to not make Error Alerts dismissible unless the error is fully resolved.
+
+When clicking on "See more" the Alert expand to show the rest of the content. When clicking on "See less" the Alert shows only the chosen title.
+
+There is no special responsive behaviour for this component beside the "Container" variant. It should still take take the entire width of the screen, and is placed on the top of the page beneath the TopNav.
+
+Be clear, concise, and actionable as Alert messages must convey essential information quickly and tell the user what happened and what they can do next (if anything). Always start with the key point.
+
+Match the message to the severity level as each severity level should express an appropriate tone:
+
+- **Information and Tip:** neutral, factual.
+- **Success:** positive, reassuring.
+- **Warning:** cautious but calm.
+- **Error:** direct and urgent, without creating panic.
+
+Avoid exaggeration. Let the component's color and icon do part of the work. Keep in mind that the component already expresses the severity visually. Don't write "Error:" or "Warning:" in the message.
+
+Use one or two sentences maximum. Alerts are not documentation or long explanations.

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

@@ -0,0 +1,12 @@
+Use an Alert whenever you need to communicate non-blocking but important information to the user. They help users quickly distinguish between levels of severity, understand context, and respond if needed. Alerts must always remain concise, visible and avoid overwhelming the interface. They can include optional action such as "View details" for the user to have more context on the alert meanings.
+
+- Use Alerts for short, actionable, contextual messages.
+- Place Alerts near the related content or action.
+- Use the correct severity level to convey the right urgency.
+- Keep messages clear and direct.
+
+- Do not stack multiple Alerts if they can be grouped.
+- Do not use Alerts for long instructions.
+- Do not rely on color alone for meaning.
+
+The Alert component is often used alongside other informational and feedback components.

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

@@ -0,0 +1,25 @@
+Buttons must use the correct ARIA role to ensure proper interaction for keyboard and screen reader users.
+
+- Use `<button>` for actions that do not navigate. Buttons trigger in-page behavior such as submitting a form, opening a modal, or deleting an item.
+- Use `<a href="...">` (link) when the action navigates to a new page or URL. A link can be visually styled as a button when it represents a navigational action that benefits from button-level prominence (e.g., a "Back" button pointing to the previous page).
+- For icon-only buttons with no visible label, add `aria-label` with a concise action description: e.g. `aria-label="Close dialog"`.
+
+Disabled buttons require special attention for accessibility. The native `disabled` attribute removes the element from the tab order and prevents any interaction, making it difficult to rely on interactive mechanisms (such as tooltips or ARIA-based descriptions) to communicate why an action is unavailable.
+
+Always provide a clear explanation of why an action is disabled. Since disabled buttons are not focusable:
+
+- Do not attach interaction-based elements (e.g., tooltips or popovers) to the button itself.
+- Instead, surface the explanation through visible, non-interactive content such as helper text or inline messages near the button.
+
+Icon-only buttons have no visible text label. Screen readers rely entirely on an accessible name to announce the button's purpose. Without it, the button will be announced as unlabelled or by its icon character code - which is meaningless to users.
+
+Buttons must be fully operable using a keyboard alone, without requiring a mouse or touch input.
+
+All buttons must be reachable by keyboard using the Tab key in a logical document order. Avoid removing buttons from the tab order unless they are genuinely hidden or inert.
+
+- **Tab** - Moves focus to the next interactive element
+- **Shift + Tab** - Moves focus to the previous interactive element
+
+&nbsp;
+
+- **Space** or **Enter** - Activates the button

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

@@ -0,0 +1,71 @@
+# Button — API
+
+## `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. |
+
+## `button[dfButton], a[dfButton]` — Component
+
+_Since 22.0_
+
+Design Factory button directive for native <button> and <a> elements.
+
+### 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. |
+| disabled | `boolean` | `false` | Disabled state for buttons and anchor buttons. |
+| 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). |
+| tabindex | `string \| number \| null \| undefined` | `undefined` | Host tabindex override. |
+| 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). |
+| type | `HTMLButtonElement['type']` | `'button'` | Native button type attribute. |
+| variant | `DfButtonVariant` | `'primary'` | Semantic variant of the button. Forced to 'primary' if the button is in a df-button-group. |
+
+## `button[dfIconButton], a[dfIconButton]` — Component
+
+_Since 22.0_
+
+Design Factory icon-only button directive for native <button> and <a> elements. Provide an accessible name with aria-label or aria-labelledby. Provide the icon with classes on the host element.
+
+### 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. |
+| disabled | `boolean` | `false` | Disabled state for buttons and anchor buttons. |
+| 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). |
+| tabindex | `string \| number \| null \| undefined` | `undefined` | Host tabindex override. |
+| 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). |
+| type | `HTMLButtonElement['type']` | `'button'` | Native button type attribute. |
+| variant | `DfButtonVariant` | `'primary'` | Semantic variant of the button. Forced to 'primary' if the button is in a df-button-group. |

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

@@ -0,0 +1,52 @@
+Button directives apply DF styling to native elements.
+
+Use `button[dfButton]` for actions. It keeps native button behavior and sets `type="button"` by default.
+
+```angular-html
+<button dfButton>Continue</button>
+
+<button dfButton appearance="outline">Cancel</button>
+```
+
+\
+
+Set `type="submit"` only when the button should submit a form.
+
+Use `a[dfButton]` when the host element must be an anchor. It supports both `href` and Angular `routerLink`, while
+using the same styling inputs as `button[dfButton]`.
+
+```angular-html
+<a dfButton routerLink="/settings">Settings</a>
+```
+
+Use `a[dfIconButton]` for icon-only links. Provide icon classes on the host element, and provide an accessible name with
+`aria-label` or `aria-labelledby`.
+
+Buttons are styled with `variant`, `appearance` and `size`.
+
+- `variant` accepts `primary`, `danger` and `neutral`; use `neutral` only for icon-only buttons.
+- `appearance` accepts `solid`, `outline` and `text`.
+- `size` accepts `sm`, `md` and `lg`; the default is `md`.
+
+> Demo source: [docs/demos/button/variants/](../../demos/button/variants/)
+
+Set `transparent` on `outline` and `text` buttons when the default background should be removed. Solid buttons are not
+affected.
+
+Set `mirror` when the button appears on an inverse surface.
+
+> Demo source: [docs/demos/button/surfaces/](../../demos/button/surfaces/)
+
+Use `dfButton` for text and icon-with-text buttons. Use `dfIconButton` for icon-only buttons, provide icon classes on
+the host element, and provide an accessible name with `aria-label` or `aria-labelledby`.
+
+When a button contains both text and an icon, the icon follows the projected content order. Put the icon before the text
+for a leading icon, or after the text for a trailing icon. In RTL layouts, the visual order follows the normal document
+flow.
+
+> Demo source: [docs/demos/button/icons/](../../demos/button/icons/)
+
+Bind `disabled` to your component state. For native buttons, the directive sets the native `disabled` attribute. For
+anchor buttons, it sets `aria-disabled`, removes the link from the tab order and blocks click or keyboard activation.
+
+> Demo source: [docs/demos/button/disabled/](../../demos/button/disabled/)

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

@@ -0,0 +1,75 @@
+ 
+
+A button is built from consistent structural elements to keep interaction predictable and scannable:
+
+1. **Container** - The clickable area with padding that ensures a comfortable hit area, even when only an icon is present. It can appear solid, outlined or not be visible at all (text).
+2. **Label** - A short, action-oriented text string that clearly communicates what happens on click. Labels are mandatory for default buttons.
+3. **Left icon** (optional) - Helps reinforce the button's intent with a visual cue placed before the label.
+4. **Right icon** (optional) - Often used to indicate navigation or forward motion (e.g. arrow).
+5. **Icon** - For icon-only buttons.
+
+Solid buttons are the most emphatic and represent the main action on a view. Use them for primary calls-to-action representing the single most important thing a user can do on a given screen.
+
+- Use one solid button per view to guide users to the main outcome (for example: "Save changes", "Submit form", "Create invoice").
+- Place the solid button in a consistent location across similar views (for example, bottom-right in forms) to reduce decision-making effort.
+
+- Don't use multiple solid buttons in the same context as they would all look equally important; use outline or text for alternatives.
+- Don't use solid buttons for low-commitment or exploratory actions (like "View details"); this dilutes their primary meaning.
+
+Use outline for secondary elements as it creates visual hierarchy with the solid button. Their quieter contrast, lighter weight, and reduced scale help the primary action stand out without effort.
+
+- Use outline buttons for actions that are relevant but not the main goal of the page, e.g. "Cancel", "Back", or alternative options.
+- Pair an outline button with a primary solid button when users must weigh a main vs. alternative choice (e.g. "Save" vs. "Discard").
+
+- Don't use outline buttons alone in critical flows where one action clearly drives the outcome; in those cases, a primary solid button should exist.
+- Don't style destructive actions as outline primary (blue) if they are truly high risk; use the danger status (red) to differentiate them clearly.
+
+Tertiary buttons (text appearance) are the least emphatic and are used only for truly low-stakes or supplemental actions, like removing a filter or category.
+
+- Use text buttons for low-priority, contextual actions such as "Learn more", "Show details", or secondary options within a block of text.
+- Use text buttons when the action should be available but should not distract from the primary task on the screen.
+- Use a tertiary button for destructive actions only when the impact is low, localized, and easily reversible.
+
+- Don't use text buttons for high-risk or critical actions; users might overlook them or misinterpret their importance.
+- Don't rely on subtle text buttons in dense interfaces where users expect strong action affordances; consider outline or solid instead.
+
+Icon-only buttons use one icon with no visible label.
+
+- Use icon-only buttons in dense toolbars, table headers, or compact layouts where space is limited and the icon has a widely recognized meaning (e.g. edit, delete, filter, more).
+- Provide an accessible label (e.g. via aria-label) and show a tooltip with the same text on hover and keyboard focus in desktop contexts.
+
+- Do not use icon-only buttons for primary actions or unclear interactions. Only use them in specific contexts where the icon's meaning is obvious; otherwise, prefer labeled buttons.
+- Limit the use of multiple icon-only actions to contexts where users are expected to recognize them (e.g., expert or productivity tools). For less frequent or less obvious actions, use labels to reduce cognitive load.
+
+Mirror is a configuration that adapts the button's colors to maintain adequate contrast on dark or high-contrast backgrounds.
+
+- Use mirror when a button is placed on dark surfaces such as app bars, overlays, or dark sections, and the basic configuration would not meet contrast guidelines.
+- Keep the same appearance and status logic (solid/outline/text, primary/danger/neutral) when switching to mirror so the hierarchy remains consistent.
+
+- Don't use mirror purely for stylistic variation on light backgrounds; its purpose is to ensure readability and accessibility.
+- Don't mix basic and mirror configurations on the same surface without a clear reason; this can confuse users about where they are in the interface.
+
+Used when the button's action is temporarily unavailable. The button appears greyed out and is not interactive. Always provide context to the user explaining why the action is unavailable (e.g. through helper text or inline message).
+
+- Use disabled buttons to indicate actions that are temporarily unavailable due to system state or missing prerequisites (e.g. loading, unavailable data).
+- Provide clear guidance near the control, use helper text, inline validation, or contextual messaging to explain why the action is disabled and what the user must do to enable it.
+
+- Don't rely solely on the disabled state to teach users what to do. If the reason is unclear, users may think the interface is broken; always pair with explanatory text.
+- Don't use disabled buttons for actions that will never become available. If an action is permanently restricted (permissions, plan limits), hide it or replace it with an explanatory pattern instead.
+
+Buttons are available in multiple sizes (small, medium, large), but medium is the default and recommended size for most desktop and web use cases. When choosing a size, users should use the same size consistently across related elements within the same view or section.
+
+On smaller screens, buttons may expand to fill the full available width (full-width button) when they are the primary action. Ensure touch targets are large enough (minimum 44×44px) to meet mobile accessibility requirements. In constrained horizontal layouts like navbars, prefer Icon-only buttons.
+
+Be clear, concise, and action-driven as button labels must communicate the outcome of the action immediately. Always start with a verb that describes what clicking the button will do (e.g., "Save", "Create invoice", "Send report").
+
+Match the label to the button's status as each status communicates a different level of impact:
+
+- Primary → standard, forward-moving actions
+- Danger → destructive or high-risk actions
+- Neutral → low-commitment, icon-only or contextual actions
+
+Avoid vague labels. Let the button's appearance and status do part of the work. Keep in mind that solid, outline, and text appearances already express hierarchy. Don't write "Click to" or "Please" in the label.
+Use one to three words maximum. Buttons are not descriptions or instructions.
+
+> **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/button/overview.md

@@ -0,0 +1,15 @@
+ 
+
+Buttons follow a three-level hierarchy (solid, outline, text) based on their importance within a page. Use this hierarchy to distinguish primary, secondary, and tertiary actions, such as submitting forms, opening dialogs, or navigating.
+
+- Use a single "solid" button to represent the main outcome of a view or flow; secondary actions should use outline or text appearances.
+- Choose the button status based on the risk and impact of the action: use danger for destructive or high-risk actions, primary for standard actions, and neutral for icon-only actions that live in navigation or global areas.
+- Write short, action-driven button labels that clearly describe the outcome (e.g., "Save", "Create invoice", "Send").
+- Place buttons close to the content or object they act on, so users immediately understand what will change when they click.
+
+- Don't present multiple solid buttons in the same view as they would compete for attention; this makes it harder for users to choose the right path.
+- Don't use a danger status just to draw attention to an action; reserve it for destructive or high-risk actions so users learn to trust the color semantics.
+- Don't hide important or ambiguous actions behind icon-only buttons; if the meaning isn't obvious from the icon, add a label.
+- Don't rely solely on color or subtle visual differences to express priority or state; use label wording, position, and appearance (solid/outline/text) to support the hierarchy.
+
+The Button component is often used alongside other action and navigation components:

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

@@ -0,0 +1,16 @@
+# Button group — API
+
+## `df-button-group` — Component
+
+_Since 22.0_
+
+Groups a set of related dfButton actions, rendering them as a single visually joined control. Project dfButton elements as content: <df-button-group [size]="'md'" [appearance]="'outline'"> <button dfButton [appearance]="'solid'">Main action</button> <button dfButton>Left</button> <button dfButton>Middle</button> <button dfButton>Right</button> </df-button-group>
+
+### Inputs
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| appearance | `'solid' \| 'outline'` | `'outline'` | The appearance of the buttons in the group. |
+| mirror | `boolean` | `false` | Enables mirrored styling for inverse surfaces. |
+| orientation | `'horizontal' \| 'vertical'` | `'horizontal'` | The orientation of the button group. |
+| size | `DfButtonSize` | `'md'` | The size of the buttons in the group. |

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

@@ -0,0 +1,32 @@
+Use `df-button-group` to group a set of related `dfButton` actions and render them as a single visually joined control.
+Project the `dfButton` elements as content.
+
+Set `appearance` on the group to apply the same appearance to every button. The main action of the group can stand out
+by setting `appearance="solid"` on its own button.
+
+```angular-html
+<df-button-group aria-label="Basic example">
+  <button dfButton appearance="solid">Main Action</button>
+  <button dfButton>Left</button>
+  <button dfButton>Middle</button>
+  <button dfButton>Right</button>
+</df-button-group>
+```
+
+\
+
+Set `orientation="vertical"` on the group to stack the buttons vertically. The default is `horizontal`.
+
+> Demo source: [docs/demos/buttongroup/orientation/](../../demos/buttongroup/orientation/)
+
+Set `size` on the group to size every button consistently. It accepts `sm`, `md` and `lg`; the default is `md`.
+
+> Demo source: [docs/demos/buttongroup/sizing/](../../demos/buttongroup/sizing/)
+
+Set `disabled` on the individual `dfButton` elements that should be disabled.
+
+> Demo source: [docs/demos/buttongroup/disabled/](../../demos/buttongroup/disabled/)
+
+Set `mirror` on the group when it appears on an inverse surface.
+
+> Demo source: [docs/demos/buttongroup/mirror/](../../demos/buttongroup/mirror/)

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

@@ -0,0 +1,15 @@
+A Drawer must support full keyboard navigation. All interactive elements within it should appear in the natural tab order, and users must be able to move through them using **Tab and Shift+Tab**, activate them with **Enter or Space**, and use **Arrow keys** when the component type expects it.
+
+The drawer must not block standard keyboard behavior unless the specific variant intentionally requires it. Keyboard users should always be able to reach, operate, and exit the drawer using familiar key patterns.
+
+The Drawer should open with a clear and easy-to-use trigger, such as a [button](/components/button). This trigger must be keyboard accessible, so users can reach it with **Tab** and activate it with **Enter or Space**. It should have a label that explains what will happen when it is used, like "Open filters" or "Show details." When the drawer opens, the trigger should update its state using something like aria-expanded, so screen readers know the drawer is now open.
+
+When a Drawer opens, the focus should move to the first interactive element inside it. Focus should not land on empty space or hidden element.
+
+The Drawer's content must be read in a clear, logical order that matches how it appears on the screen. If the Drawer opens, the screen reader should not suddenly jump to the middle of it or skip important parts. Elements that are shown on the screen should always be announced, while items that are hidden or collapsed should not be read.
+
+A Drawer should start with a clear heading that tells the user what the drawer is about. **This heading must follow the normal order of headings on the page**, but by default it is an h2. For example, if the surrounding page uses an h2, then the Drawer's title might be an h3, so the structure stays logical.
+
+The heading should be short, direct, and visible on the screen, because **screen readers use headings to help users jump to different parts of a page**. Only one main heading is needed at the top of the Drawer, and it should not replace or repeat higher-level headings on the page. Using the correct heading level helps users understand how the Drawer fits into the rest of the content and makes navigation easier for people who rely on assistive technology.
+
+All interactive elements inside a Drawer must expose a clear accessible name so their purpose can be correctly announced by assistive technologies. Each button, link, input, or control must be identifiable through a visible label such as aria-label or aria-labelledby.

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

@@ -0,0 +1,56 @@
+# Drawer — API
+
+## `ng-template[dfDrawerHeader]` — Directive
+
+A directive to define a template containing the header content of the drawer.
+
+## `ng-template[dfDrawerBody]` — Directive
+
+A directive to define a template containing the body content of the drawer.
+
+## `ng-template[dfDrawerFooter]` — Directive
+
+A directive to define a template containing the footer content of the drawer.
+
+## `df-drawer` — Component
+
+_Since 21.1_
+
+Enables users to show contextual content via a sliding panel from any screen edge. See Design Factory documentation for details and examples.
+
+### Inputs
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| backdrop | `boolean` | `true` | If true displays the backdrop element and disables the body scrolling, otherwise the body of the document is navigable |
+| bodyScroll | `boolean` | `false` | If true allows body scrolling when the drawer is open. |
+| className | `string` | `''` | CSS classes to be applied on the widget main container |
+| closeOnBackdropClick | `boolean` | `true` | If true the drawer will be closed when clicking on the backdrop, otherwise the backdrop is static and non iteractive. |
+| configuration | `DrawerConfiguration` | `'overlay'` | The display configuration of the drawer. 'overlay' (default): the drawer overlays the page content with a backdrop. 'inline': the drawer stays in the document flow and moves content as it expands/resizes. |
+| container | `HTMLElement \| null` | `document.body` | Which element should contain the drawer and backdrop DOM elements. If it is not null, the drawer and backdrop DOM elements are moved to the specified container. Otherwise, they stay where the widget is located. Defaults to document.body in the browser and null on the server. |
+| focusOnInit | `boolean` | `true` | If true focuses the drawer when it is opened. |
+| keepInDom | `boolean` | `false` | If true, the drawer element is kept in the DOM when it is not visible. This can be useful to preserve the state of the drawer content when it is hidden. |
+| position | `DfDrawerPosition` | `'inline-start'` | The position of the drawer on the screen. |
+| resizable | `boolean` | `false` | If true, the drawer can be resized by the user. |
+| visible | `boolean` | `false` | If true, the drawer is shown; otherwise, it is hidden. |
+
+### Outputs
+
+| Name | Type | Description |
+|------|------|-------------|
+| maximizedChange | `boolean` | Event to be triggered when the maximized state changes. |
+| maxSize | `void` | Event to be triggered when the maximum size is reached. |
+| minimizedChange | `boolean` | Event to be triggered when the minimized state changes. |
+| minSize | `void` | Event to be triggered when the minimum size is reached. |
+| resizingChange | `boolean` | Event to be triggered when the user start or stop moving the drawer. |
+| visibleChange | `boolean` | Event to be triggered when the visible property changes. |
+
+### Methods
+
+#### `open(animated: boolean | undefined)` => `Promise<void>`
+
+Trigger the opening of the drawer.
+
+#### `close(animated: boolean | undefined)` => `Promise<void>`
+
+Trigger the closing of the drawer.

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

@@ -0,0 +1,36 @@
+In this default configuration, the drawer container is placed over the page content. To anchor the drawer to a different side of the screen, set `position` to one of acceptable values:
+
+- inline-start
+- inline-end
+- block-start
+- block-end
+
+You can enable the resizing of the drawer by adding `resizable` to the drawer element.
+
+```angular-html
+<df-drawer resizable> </df-drawer>
+```
+
+Be sure to handle the drawer content responsiveness when changing the size, you might want to set the `--df-drawer-min-size` in order to limit the minimum size of the container.
+
+```angular-ts
+encapsulation: ViewEncapsulation.None,
+  styles: `
+    .df-drawer.df-inline-start {
+      --df-drawer-min-size: 250px;
+    }`
+```
+
+> Demo source: [docs/demos/drawer/overlay/](../../demos/drawer/overlay/)
+
+Inline drawers are part of the document flow, so you need to handle the position by setting the `order` in your layout. See the example below for how to set this up.
+
+```angular-html
+<df-drawer configuration="inline" [style.order]="2"> </df-drawer>
+
+<div [style.order]="1">
+  <h6>Main Page Content</h6>
+</div>
+```
+
+> Demo source: [docs/demos/drawer/inline/](../../demos/drawer/inline/)

package/.ai/docs/components/drawer/examples.md

@@ -0,0 +1,9 @@
+> Demo source: [docs/demos/drawer/overlay/](../../demos/drawer/overlay/)
+
+- Add a **semi-transparent background to visually separate** the Overlay Drawer and prevent interaction with the underlying page (optional).
+
+- **Don’t place complex or long workflows** inside an Overlay Drawer.
+- **Don’t open a Drawer on top of another** because stacking Drawers creates confusion.
+- **Don’t allow interaction with the page behind** the Drawer when a background is present.
+
+> Demo source: [docs/demos/drawer/inline/](../../demos/drawer/inline/)

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

@@ -0,0 +1,58 @@
+The Drawer is composed of the following elements:
+
+- **Header (1)**: The top section. It usually contains a title that clearly communicates the purpose of the Drawer and an optional close button that is always visible.
+- **Body (2)**: The main content area. It hosts the contextual information or interactive elements such as forms, filters, or details.
+- **Resizer (3)**: Allows users to adjust the drawer's dimensions.
+- **Backdrop (4)**: An optional layer that appears behind the Drawer when using an overlay configuration.
+- **Footer (5)**: Placed at the bottom of the drawer and is used for primary and secondary actions, such as "Apply," "Cancel," or "Save."
+- **Close button (6)**: The most explicit way for users to dismiss the drawer whenever they want.
+
+The Overlay Drawer **appears on top of the page content** and is **anchored to one edge of the viewport**. It temporarily covers part of the main interface and **can include a semi-transparent backdrop** to keep the user's attention on the Drawer content. This variant is best for **tasks that require focus**. The Overlay Drawer has a light shadow applied to it.
+
+- Add a **semi-transparent backdrop to visually separate** the Overlay Drawer and prevent interaction with the underlying page (optional).
+
+- **Don't place complex or long workflows** inside an Overlay Drawer.
+- **Don't open a Drawer on top of another** because stacking Drawers creates confusion.
+- **Don't allow interaction with the page behind** the Drawer when a backdrop is present.
+
+**The Inline Drawer is integrated into the page layout** rather than floating above it. When opened, **it pushes or shifts the surrounding content** to make space, so the main page remains visible and interactive. This variant is **ideal for tasks that complement the primary content**, such as showing additional details or configuration options, without isolating the user from the rest of the interface. It feels like part of the page rather than a separate layer, and **it does not use a backdrop overlay**.
+
+- Use an Inline Drawer **when you want to keep the main content visible and allow users to interact with both** areas at the same time.
+- Make sure **the Drawer feels integrated into the page layout** and does not look like a floating element.
+- **Keep the Drawer width reasonable** so the main content remains usable and readable.
+
+- **Don't add a backdrop layer** because Inline Drawers are meant to coexist with visible content.
+- **Avoid stacking multiple Inline Drawers** because this creates complexity and confusion.
+
+**Resizing gives users flexibility to adjust the Drawer's dimensions** based on their needs. This interaction is especially useful when the Drawer contains detailed content that benefits from more space.
+
+The Drawer includes a resizer handle placed on the edge where resizing makes sense:
+
+- **Vertical resizing for Drawers anchored at the top or bottom.**
+- **Horizontal resizing for Drawers anchored on the left or right.**
+
+Users can click and drag the handle to increase or decrease the Drawer's size. The resizing should feel smooth and responsive, with clear visual feedback during the drag action.
+
+- **Start with an initial size that fits the content perfectly** so users do not need to resize immediately.
+- **Allow resizing only within reasonable limits** to keep the layout usable.
+- **Set a maximum width around 2/3 of the viewport** so the Drawer never takes over the entire screen.
+- **Keep resizing smooth and responsive** with clear visual feedback during the drag action.
+
+- **Don't make the initial size too small or too large** because users expect it to feel right for the content.
+
+Closing the Drawer is essential for user control and a smooth experience. **Users should always have clear, predictable ways to dismiss the Drawer** without confusion or frustration.
+
+When the content inside the Drawer exceeds the available space, **scrolling becomes necessary to maintain usability and clarity**. The scroll should be handled in a way that keeps essential elements accessible at all times.
+
+- The body of the Drawer should support vertical scrolling when content is long.
+- The header and footer remain fixed so users can always see the title and key actions while scrolling through the content.
+
+Drawers should adapt to different screen sizes without breaking the user's sense of context. The goal is to maintain usability and clarity whether on desktop or mobile.
+
+On desktop, the Drawer acts as **a secondary panel that slides in from one edge of the screen** without taking over the entire viewport. To maintain clarity and avoid disrupting the workflow, the Drawer should never occupy the full width (for left and right anchored Drawers) or the full height (for top and bottom anchored Drawers). It is recommended to leave at least one-third of the main content visible.
+
+On smaller screens, the Drawer transforms into a full-screen view, **occupying the entire width and height of the viewport**. This approach ensures clarity and usability on devices where partial overlays can feel confusing. While open, the main content is hidden, and the user's focus shifts entirely to the Drawer. A clear close option is essential for easy navigation. This mobile behaviour supports the same tasks as desktop but optimizes for touch interaction and limited space.
+
+When writing for Drawers, start by **making the header clear and descriptive** so users immediately understand the purpose, like "Filter Options" or "Edit Settings." **Keep the tone simple and direct**, avoiding jargon or vague terms. **In the body, use concise helper text only when necessary** and ensure all fields have visible labels for clarity and accessibility. **For actions, prioritize clarity**: the buttons should state exactly what they do, such as "Apply Filters" or "Save Changes," instead of generic words like "OK." Finally, **maintain consistency in tone across all elements**: friendly, professional, and focused on guiding the user through a short, contextual task without overwhelming them.
+
+> **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/drawer/overview.md

@@ -0,0 +1,19 @@
+The Drawer component is a sliding panel designed to present contextual or secondary content without disrupting the user's primary workflow. It appears from one edge of the screen and provides a space for tasks such as viewing details, filling in a form, adjusting settings, or applying filters.
+
+- **Use Drawers for short and focused tasks** that can be completed quickly without requiring a full-page transition.
+- Always **provide a clear and predictable way for users to open the Drawer** so they understand what will happen when they interact with the trigger.
+- **Include a clear and descriptive title in the header** so users immediately understand the purpose of the Drawer.
+- **Keep the main content visible** whenever possible so users do not lose their sense of context while working inside the Drawer.
+- **Offer more than one way to dismiss the drawer**, such as a close button, clicking outside the drawer for overlays, using keyboard tab or completing an action that logically ends the task.
+- **Preserve the state of the Drawer** when it is used for settings or filters so users do not lose their progress when closing and reopening it.
+
+- **Don't open a Drawer on top of another** because stacking Drawers creates confusion.
+- **Don't open a Drawer without an explicit user action** because unexpected behaviour break trust and disrupt the experience.
+- **Don't close the Drawer automatically without user intent** because users should always feel in control of the interaction.
+- **Don't overload the header or footer with too many actions.**
+
+The **Drawer** is related to components that manage content visibility and context. **Cards** often display summarized information, and a **Drawer** can extend that experience by showing more details without leaving the page. **Accordion** and **Collapse** also reveal hidden content, but they do so inline, while a Drawer provides a larger, dedicated space for interaction. Compared to a **Modal**, the **Drawer** without backdrop is less disruptive because it keeps part of the main content visible, making it better for tasks that require maintaining context.
+
+</div>
+
+The Drawer is an effective container for filtering and sorting because it provides a dedicated space for controls without interrupting the main content.

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

@@ -0,0 +1,27 @@
+Use semantic roles and states to ensure assistive technologies correctly interpret the Dropdown and its menu:
+
+- The dropdown trigger must be a `button` element.
+- Use `aria-controls="(id of the menu container)"` to associate the trigger with the menu.
+- Use `aria-expanded="true | false"` to reflect the open or closed state of the menu.
+- The menu container must use `role="listbox"`.
+- Each actionable item inside the menu must use `role="option"`.
+- Use `aria-live="polite"` on the menu container to announce state changes to screen reader users.
+
+Without `aria-live`, a screen reader user focused on the trigger button may not know the menu has appeared. With `aria-live="polite"`, the screen reader announces the change immediately, keeping the user informed without requiring manual navigation. This aligns with **WCAG 4.1.3 Status Messages (AA)**.
+
+Avoid using generic containers (`div`, `span`) without roles, as this prevents correct screen reader interpretation.
+
+The Dropdown trigger must be fully operable using the keyboard. When users navigate through the page using **Tab**, the trigger must receive focus in the natural tab order. Activating the trigger using **Enter** or **Space** opens the dropdown menu.
+
+Once the dropdown menu is open, keyboard navigation moves inside the menu and follows a predictable, linear pattern.
+
+- **Arrow Up** / **Arrow Down** move focus between menu items without wrapping past the first or last item.
+- **Enter** or **Space** activates the focused item and closes the menu.
+- **Escape** closes the menu and returns focus to the trigger.
+- **Tab** moves focus out of the menu to the next focusable element on the page, closing the menu automatically. The menu also closes whenever focus leaves the Dropdown entirely.
+
+- The Dropdown trigger must have a clear accessible name that describes its purpose (e.g. "More actions", "Options").
+- Icon‑only triggers must provide an accessible label via `aria-label` or equivalent.
+- Menu items must have concise, descriptive labels that clearly communicate the action.
+
+Do not rely on icons alone to convey meaning.