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

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

@@ -0,0 +1,45 @@
+Use the correct ARIA roles to ensure assistive technologies understand the Accordion structure.
+
+Each header must include:
+
+- `aria-expanded="true|false"` to indicate the state
+- `aria-controls="[ID]"` pointing to the associated panel
+
+Each panel must use:
+
+- `role="region"` (optional but recommended for clarity)
+- `aria-labelledby="[HEADER ID]"`
+
+When Accordions reveal or hide content, assistive technologies must be able to understand what changed.
+
+**Expansion / collapse:**
+
+- When a panel expands, the screen reader should announce the header as: "[Title], expanded."
+- When a panel collapses: "[Title], collapsed."
+- Do not automatically move focus into the expanded content. Let the user navigate into it with arrow keys or virtual cursor.
+
+ 
+
+The first focusable element inside the Accordion should always be the first header.
+
+- Tab → moves to the next focusable header or action button.
+- Headers must be reachable regardless of expanded or collapsed state.
+- Content inside a panel is only tabbable if the panel is open and contains focusable elements (links, buttons, inputs).
+
+- On a header: toggles expand/collapse.
+- In Radio mode: sets the selected item (closes the previously selected one).
+- On a button: activates the button without toggling the panel.
+
+ 
+
+Screen Readers should read:
+[type of the element], [text of the element], [state of the element], [selection status] - selected or not selected-
+
+1. Header Title
+2. Subtitle (if present)
+3. Action button (if applicable)
+4. Expanded content
+
+Screen Reader should announce this region as Accordion
+
+For users who zoom up to 300%, apply the responsiveness behaviour of the component.

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

@@ -0,0 +1,279 @@
+# Accordion — API
+
+## `df-accordion` — Component
+
+_Since 22.0.0_
+
+An accordion is a vertically stacked list of headers that reveal or hide associated sections of content Each header and content section is called an accordion-item. This component is a container for these items and provides an API to handle them.
+
+### Inputs
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| addon | `'none' \| 'icon' \| 'number'` | `'none'` | Addon type to show on the left side of the accordion header. Only valid for 'default' and 'interactive' variant. |
+| animated | `boolean \| undefined` | `true` | If true, accordion-item will be animated. |
+| arrowPosition | `'start' \| 'end'` | `'end'` | Position of the expandable icon on the accordion header. |
+| closeOthers | `boolean \| undefined` | `false` | If true, only one accordion-item at the time can stay open. |
+| itemDestroyOnHide | `boolean \| undefined` | `true` | If true, the accordion-item body container will be removed from the DOM when the accordion-item is collapsed. It will be just hidden otherwise. |
+| itemHeadingLevel | `HeadingLevel` | `2` | The HTML heading level to use for the accordion-item-header. Should be an integer between 1 and 6, if an invalid value is provided, it will default to 2. |
+| separator | `boolean \| undefined` | `false` | When an item is visible (a.k.a. expanded), a separator line is shown below the item header. |
+| size | `'sm' \| 'md' \| 'lg'` | `'md'` | The size of the accordion. |
+| subtitleType | `'none' \| 'inline' \| 'block'` | `'none'` | In case of subtitle, defines how the subtitle is displayed. Only valid for 'default' and 'interactive'. On an interactive variant, subtitle is always displayed as inline. |
+
+### Outputs
+
+| Name | Type | Description |
+|------|------|-------------|
+| itemHidden | `string` | An event fired when an item is hidden. Event payload is the id of the item. |
+| itemShown | `string` | An event fired when an item is shown. Event payload is the id of the item. |
+
+### Methods
+
+#### `collapse(itemId: string)` => `Promise<void>`
+
+Collapses an item with the given id. Has no effect if the itemId does not correspond to any item.
+
+#### `collapseAll()` => `Promise<void>`
+
+Collapses all items.
+
+#### `toggle(itemId: string)` => `Promise<void>`
+
+Toggles an item with the given id. It will toggle an item, even if it is disabled.
+
+#### `expand(itemId: string)` => `Promise<void>`
+
+Expands an item with the given id. If closeOthers is true, it will collapse other panels.
+
+#### `expandAll()` => `Promise<void>`
+
+Expands all items. If closeOthers is true and all items are closed, it will open the first one. Otherwise, it will keep the opened one.
+
+#### `isExpanded(itemId: string)` => `boolean`
+
+Checks if an item with the given id is expanded. If the itemId does not correspond to any item, it returns false.
+
+## `df-accordion-selectable` — Component
+
+_Since 22.0.0_
+
+A selectable accordion is a vertically stacked list of headers with built-in radio inputs, following the radio-group pattern. Expanding an item selects it. Each header and content section is a selectable accordion-item. This component is a container for these items and provides an API to handle them. It always enforces closeOthers behavior (only one item open at a time) and uses role="radiogroup" for accessibility.
+
+### Inputs
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| addon | `'none' \| 'icon' \| 'number'` | `'none'` | Addon type to show on the left side of the accordion header. Only valid for 'default' and 'interactive' variant. |
+| animated | `boolean \| undefined` | `true` | If true, accordion-item will be animated. |
+| ariaLabel | `string` |  | Accessible label for the radiogroup. Use when there is no visible heading that can be referenced by ariaLabelledBy. |
+| ariaLabelledBy | `string` |  | ID of an element that labels this radiogroup. Preferred over ariaLabel when a visible heading exists. |
+| arrowPosition | `'start' \| 'end'` | `'end'` | Position of the expandable icon on the accordion header. |
+| id | `string` |  | The id of the accordion. Used to derive the radio group name for selectable items. |
+| itemDestroyOnHide | `boolean \| undefined` | `true` | If true, the accordion-item body container will be removed from the DOM when the accordion-item is collapsed. It will be just hidden otherwise. |
+| itemHeadingLevel | `HeadingLevel` | `2` | The HTML heading level to use for the accordion-item-header. Should be an integer between 1 and 6, if an invalid value is provided, it will default to 2. |
+| separator | `boolean \| undefined` | `false` | When an item is visible (a.k.a. expanded), a separator line is shown below the item header. |
+| size | `'sm' \| 'md' \| 'lg'` | `'md'` | The size of the accordion. |
+| subtitleType | `'none' \| 'inline' \| 'block'` | `'none'` | In case of subtitle, defines how the subtitle is displayed. Only valid for 'default' and 'interactive'. On an interactive variant, subtitle is always displayed as inline. |
+
+### Outputs
+
+| Name | Type | Description |
+|------|------|-------------|
+| itemHidden | `string` | An event fired when an item is hidden. Event payload is the id of the item. |
+| itemShown | `string` | An event fired when an item is shown. Event payload is the id of the item. |
+
+### Methods
+
+#### `toggle(itemId: string)` => `Promise<void>`
+
+Toggles an item with the given id. It will toggle an item, even if it is disabled.
+
+#### `expand(itemId: string)` => `Promise<void>`
+
+Expands an item with the given id. If closeOthers is true, it will collapse other panels.
+
+#### `expandAll()` => `Promise<void>`
+
+Expands all items. If closeOthers is true and all items are closed, it will open the first one. Otherwise, it will keep the opened one.
+
+#### `isExpanded(itemId: string)` => `boolean`
+
+Checks if an item with the given id is expanded. If the itemId does not correspond to any item, it returns false.
+
+## DfAccordionConfig — Configuration
+
+Configuration options supported by provideDfAccordionConfig
+
+### Properties
+
+| Name | Type | Description |
+|------|------|-------------|
+| animated | `boolean` | If true, accordion items will be animated. |
+| ariaToggleButtonLabel | `string` | Accessibility label for the accordion-item toggle button in the interactive variant. |
+
+### Methods
+
+#### `provideDfAccordionConfig(config: Partial<DfAccordionConfig> | ((prevConfig: Partial<DfAccordionConfig>) => Partial<DfAccordionConfig>) | undefined)` => `FactoryProvider`
+
+Provides the configuration for the accordion component.
+
+#### `injectDfAccordionConfig()` => `WritableSignal<Partial<DfAccordionConfig>>`
+
+Injects the configuration for the accordion component.
+
+## `ng-template[dfAccordionItemBody]` — Directive
+
+_Since 22.0.0_
+
+A directive to define a template containing the body content of the accordion item.
+
+## `ng-template[dfAccordionItemTitle]` — Directive
+
+_Since 22.0.0_
+
+A directive to define a template containing the title of the accordion item.
+
+## `df-accordion-item` — Component
+
+_Since 22.0.0_
+
+An accordion item is a group of a header and a collapsible content section. It is used within an accordion component to display and hide content. This is the basic template for an accordion item. See DfAccordionItemInteractive for a template with interactive elements in the header. As its content, it accepts two directives: dfAccordionItemTitle: to define the title of the accordion item. dfAccordionItemBody: to define the body content of the accordion item.
+
+### Inputs
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| destroyOnHide | `boolean \| undefined` | `true` | If true, the accordion-item body container will be removed from the DOM when the accordion-item is collapsed. It will be just hidden otherwise. |
+| disabled | `boolean \| undefined` | `false` | If true, the accordion-item will be disabled. It will not react to user's clicks, but still will be possible to toggle programmatically. |
+| iconClass | `string` | `undefined` | Optional input only valid for Icon variant to set custom icon class |
+| id | `string` | `'dfId-[number]'` | The id of the accordion-item. It can be used for controlling the accordion-item via the accordion api. |
+| number | `string` | `undefined` | Optional input only valid for addon number variant to set the custom number |
+| subtitle | `string` | `undefined` | Optional input only valid if the accordion's subtitleType is 'inline' or 'block' to set custom subtitle |
+| visible | `boolean \| undefined` | `false` | If true, the accordion-item will be visible (expanded). Otherwise, it will be hidden (collapsed). |
+
+### Outputs
+
+| Name | Type | Description |
+|------|------|-------------|
+| hidden | `void` | An event fired when an item is hidden. |
+| shown | `void` | An event fired when an item is shown. |
+| visibleChange | `boolean` | An event fired when the visible value changes. Event payload is the new value of visible. |
+
+### Methods
+
+#### `toggle()` => `Promise<void>`
+
+Toggles the item. It will toggle the item, even if it is disabled.
+
+#### `expand()` => `Promise<void>`
+
+Expands the item. If closeOthers is true, it will collapse other panels.
+
+#### `collapse()` => `Promise<void>`
+
+Collapses the item.
+
+#### `isExpanded()` => `boolean`
+
+Checks if the item is expanded.
+
+## `ng-template[dfAccordionItemSelectableSubsection]` — Directive
+
+_Since 22.0.0_
+
+A directive to define a template containing a subsection element inside the selectable accordion item header.
+
+## `df-accordion-item-selectable` — Component
+
+_Since 22.0.0_
+
+An accordion item with a built-in radio input in the header. Implements ControlValueAccessor so it can be used with formControlName or ngModel. All selectable items sharing the same form control act as a radio group: expanding an item selects its value. As its content, it accepts two directives: dfAccordionItemTitle: to define the title of the accordion item. dfAccordionItemBody: to define the body content of the accordion item. Optionally: dfAccordionItemSelectableSubsection: to define a subsection element inside the header.
+
+### Inputs
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| destroyOnHide | `boolean \| undefined` | `true` | If true, the accordion-item body container will be removed from the DOM when the accordion-item is collapsed. It will be just hidden otherwise. |
+| iconClass | `string` |  | Optional input only valid for Icon variant to set custom icon class. |
+| id | `string` | `'dfId-[number]'` | The id of the accordion-item. It can be used for controlling the accordion-item via the accordion api. |
+| number | `string` | `''` | Optional input only valid for addon number variant to set the number. |
+| subtitle | `string` |  | Optional input only valid if the accordion's subtitleType is 'inline' or 'block' to set custom subtitle. |
+| subtitleType | `'none' \| 'inline' \| 'block'` |  | In case of subtitle, defines how the subtitle is displayed. Only valid for 'default' and 'card'. On a card variant, subtitle is always displayed as inline. |
+| value | `string` |  | The value this item represents in the radio group. When the item is expanded, this value is emitted to the form control. |
+| visible | `boolean \| undefined` | `false` | If true, the accordion-item will be visible (expanded). Otherwise, it will be hidden (collapsed). |
+
+### Outputs
+
+| Name | Type | Description |
+|------|------|-------------|
+| hidden | `void` | An event fired when an item is hidden. |
+| shown | `void` | An event fired when an item is shown. |
+| visibleChange | `boolean` | An event fired when the visible value changes. Event payload is the new value of visible. |
+
+### Methods
+
+#### `toggle()` => `Promise<void>`
+
+Toggles the item. It will toggle the item, even if it is disabled.
+
+#### `expand()` => `Promise<void>`
+
+Expands the item. Since the parent accordion has closeOthers, it will collapse other panels.
+
+#### `collapse()` => `Promise<void>`
+
+Collapses the item.
+
+#### `isExpanded()` => `boolean`
+
+Checks if the item is expanded.
+
+## `ng-template[dfAccordionItemInteractiveSection]` — Directive
+
+_Since 22.0.0_
+
+A directive to define a template containing an interactive element inside the accordion item header.
+
+## `df-accordion-item-interactive` — Component
+
+_Since 22.0.0_
+
+An accordion item is a group of a header and a collapsible content section. It is used within an accordion component to display and hide content. This template is for the case when it is needed an interactive section inside the header. As its content, it accepts three directives: dfAccordionItemTitle: to define the title of the accordion item. DfAccordionItemInteractiveSection: to define a template containing an interactive element. dfAccordionItemBody: to define the body content of the accordion item.
+
+### Inputs
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| destroyOnHide | `boolean \| undefined` | `true` | If true, the accordion-item body container will be removed from the DOM when the accordion-item is collapsed. It will be just hidden otherwise. |
+| disabled | `boolean \| undefined` | `false` | If true, the accordion-item will be disabled. It will not react to user's clicks, but still will be possible to toggle programmatically. |
+| iconClass | `string` |  | Optional input only valid for Icon variant to set custom icon class |
+| id | `string` | `'dfId-[number]'` | The id of the accordion-item. It can be used for controlling the accordion-item via the accordion api. |
+| number | `string` | `''` | Optional input only valid for addon number variant to set custom the number |
+| subtitle | `string` |  | Optional input only valid if the accordion's subtitleType is 'inline' or 'block' to set custom subtitle |
+| visible | `boolean \| undefined` | `false` | If true, the accordion-item will be visible (expanded). Otherwise, it will be hidden (collapsed). |
+
+### Outputs
+
+| Name | Type | Description |
+|------|------|-------------|
+| hidden | `void` | An event fired when an item is hidden. |
+| shown | `void` | An event fired when an item is shown. |
+| visibleChange | `boolean` | An event fired when the visible value changes. Event payload is the new value of visible. |
+
+### Methods
+
+#### `toggle()` => `Promise<void>`
+
+Toggles the item It will toggle the item, even if it is disabled.
+
+#### `expand()` => `Promise<void>`
+
+Expands an item. If closeOthers is true, it will collapse other panels.
+
+#### `collapse()` => `Promise<void>`
+
+Collapses the item.
+
+#### `isExpanded()` => `boolean`
+
+Checks if the item is expanded.

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

@@ -0,0 +1,43 @@
+Use `df-accordion` with `df-accordion-item` elements. Each item takes a title and body via `ng-template` directives.
+Set `[visible]="true"` to expand an item by default. Use `[disabled]="true"` to prevent interaction.
+
+> Demo source: [docs/demos/accordion/basic/](../../demos/accordion/basic/)
+
+Use the `closeOthers` input to allow only one panel to be open at any given time.
+
+> Demo source: [docs/demos/accordion/close-others/](../../demos/accordion/close-others/)
+
+Use the `separator` input to add a visual divider between the header and body of expanded items.
+
+> Demo source: [docs/demos/accordion/separator/](../../demos/accordion/separator/)
+
+Accordion items support subtitles, numbering panels, and icons. Control the display with `subtitleType` (`none`, `inline`, `block`),
+`addon` (`none`, `number`, `icon`), and `arrowPosition` (`start`, `end`). When an addon is present, the arrow is forced to the opposite side.
+
+> Demo source: [docs/demos/accordion/addons-subtitle/](../../demos/accordion/addons-subtitle/)
+
+Use the accordion's API to control items programmatically. Call `toggle(id)`, `expand(id)`, `collapse(id)`,
+`expandAll()`, or `collapseAll()` on the `DfAccordion` instance obtained via a template reference variable.
+
+> Demo source: [docs/demos/accordion/programmatic-control/](../../demos/accordion/programmatic-control/)
+
+Use `df-accordion-item-interactive` to place an interactive element (a button or a toggle) inside the accordion header,
+next to the expand/collapse arrow. Define the element via the `dfAccordionItemInteractiveSection` template.
+
+> Demo source: [docs/demos/accordion/interactive/](../../demos/accordion/interactive/)
+
+Combine the interactive variant with subtitles, icons, and numbers. The same addon and arrow constraints apply:
+when an addon is present, the arrow is forced to the opposite side.
+
+> Demo source: [docs/demos/accordion/interactive-addons-subtitle/](../../demos/accordion/interactive-addons-subtitle/)
+
+Use `df-accordion-selectable` with `df-accordion-item-selectable` for a radio-group pattern where expanding an item
+selects it. Each item carries a `value` emitted to the form control. Only one item can be open at a time.
+
+> Demo source: [docs/demos/accordion/selectable/](../../demos/accordion/selectable/)
+
+Selectable items can be customized with badges in the title and a subsection below the header for extra details.
+Use the `dfAccordionItemSelectableSubsection` template to render additional content alongside the radio input.
+Each item body is rendered via `NgComponentOutlet` to allow fully dynamic content.
+
+> Demo source: [docs/demos/accordion/selectable-extended/](../../demos/accordion/selectable-extended/)

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

@@ -0,0 +1,99 @@
+ 
+
+**Basic:**
+
+- **Number (1):** Indicates the order or step when the accordion is used in numbered or sequential formats.
+- **Title (2):** Primary label of the section; it summarizes the content.
+- **Subtitle (3):** Optional secondary label used to provide additional context or clarify the scope of the section.
+- **Button (4):** Optional action placed in the header for secondary or complementary tasks directly related to the panel content.
+- **Accordion arrow (5):** Visual indicator of the expand/collapse state; rotates to show whether the panel is open or closed.
+- **Content (6):** The information revealed when the panel is expanded; can include text, lists, media, or form elements.
+- **Divider (7):** Visual separator used to distinguish between header and content for better readability.
+
+**Radio button:**
+
+- **Radio button (8):** Indicates exclusive selection.
+
+The accordion has 2 main variants depending on the types of actions.
+
+This is the default accordion variant. Each section can be opened or closed independently. It is useful for structuring dense information within a single page without overwhelming the user.
+
+- Use it when users only need to **focus on a few key pieces of content** on a page.
+- Write short, **clear, and meaningful titles** for each section.
+- Keep the **default state collapsed** to give users an overview of all topics.
+- Add only relevant content inside each expanded panel to **prevent unnecessary scrolling**.
+- Structure content with short paragraphs, bullet points, or subheaders when useful.
+- Ensure the accordion header is a large, **easy-to-click target**.
+- Keep the **same structure and layout** across your accordions.
+
+- Don't nest an **accordion inside another accordion** - this significantly increases cognitive load.
+- Don't overload the component with too many sections; reorganize or **group content if needed**.
+- Don't use accordion if people need to open the majority of sections to have their questions answered, or to get the full story.
+- Don't use overly **long or ambiguous titles**.
+- Don't use **more than one subtitle position** in the same accordion (e.g. subtitle left and subtitle right).
+
+A mode where only one section can be opened at a time; selecting a section expands it while automatically closing the previous one, with one section always kept open. It behaves similarly to a radio button group.
+
+- Use when the user must **make an exclusive choice** (e.g. payment method, configuration option).
+- Use when the user needs to **quickly compare multiple options** without interaction conflicts.
+- Ensure that the selected state is **visually distinct**.
+- Use icons, badges, or indicators only when they add meaningful information.
+
+- Don't use radio mode for **long text content** (collapsing/expanding repeatedly creates a poor reading experience).
+- Don't include large logos or **visual elements in the header**.
+- Don't use radio mode for **informational sections that are not mutually exclusive**.
+
+ 
+
+> **Info:** This variant is most commonly used in the checkout pattern as shown in the example below
+
+- Use when a title alone does not provide enough context.
+- Useful for documentation topics, FAQs, and multi-level explanations.
+
+- Use when the section requires a secondary action directly related to the content, such as toggling a setting or opening an external link.
+- Useful when the user needs to perform an action without opening the panel, or when the action complements the information inside the accordion.
+
+> **Info:** When this variant is used, only the button becomes clickable. Clicking on the header will not expand the accordion
+
+> **Info:** This variant should be used as a replacement for the deprecated expandable card component.
+
+ 
+
+- Great for steps, instructions, or sequential processes.
+- Use 1/2/3 for short lists (1 to 9 items)
+- Use 01/02/03 for longer sequences (10+ items).
+
+- Use only if the icon clearly enhances understanding.
+- Never use an icon without a label.
+- Keep icon placement consistent.
+
+In case of doubt we recommend using to the medium size which is the standard size for Design Factory. When using a size, try to keep the same all across your pages.
+
+- Clicking the header toggles the section.
+- The animation should follow DF motion principles.
+
+For narrower mobile displays the accordion is to take the full width of the device when displayed.
+
+ 
+
+| Screen size                                       | Component size                                                       |
+| ------------------------------------------------- | -------------------------------------------------------------------- |
+| L: [992px; n[<br>Desktop                          | 100% of space available for display minus 16px padding on each side. |
+| M: [768px; 992px[<br>Tablets & larger smartphones | 100% of space available for display minus 16px padding on each side. |
+| S: [576px; 768px[<br>Landscape phones             | 100% of space available for display minus 16px padding on each side. |
+| XS: [-inf; 576px[<br>Portrait phones              | 100% of space available for display minus 8px padding on each side.  |
+
+Write short, clear titles that express the main idea.
+Use subtitles only when additional context is necessary.
+Avoid repeating the same information in both title and content.
+
+Prioritize clarity:
+
+- short paragraphs
+- bullet points
+- clear callouts when needed
+
+Each section should convey one primary idea.
+Avoid overly narrative text; keep content functional and to the point.
+
+> **Tip:** For a full view on UX Writing guidelines, check the following document: Amadeus UX Writing Style Guide

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

@@ -0,0 +1,17 @@
+ 
+
+Use an accordion when you need to:
+
+- Present several key pieces of information on a single page without overwhelming users.
+- Let users quickly scan section titles and expand only what is relevant to them.
+- Reduce scrolling by hiding non-essential or secondary content.
+- Structure content into at least two or more sections.
+
+- Keep section titles clear and meaningful.
+- Use the component to streamline pages with multiple informational blocks.
+- Limit the number of sections or group them into categories if the list becomes long.
+
+- Don’t hide important content inside an accordion - ensure critical information remains visible to avoid being missed.
+- Don't overload the accordion with too many sections - reorganize or restructure instead.
+
+Accordions are designed to manage content density, not navigation. They help structure information within a single page by reducing visible clutter and allowing users to reveal details progressively. When choosing whether to use an Accordion or another pattern, consider the nature of the content, how often users need to access it, and whether visibility or discoverability is the priority.

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

@@ -0,0 +1,24 @@
+Use the appropriate role depending on the severity:
+
+- **Information, Tip & Success:** `role="status"`. Announces changes politely, without interrupting screen reader focus.
+- **Warning & Error:** `role="alert"`. Announces immediately and with higher priority.
+
+Avoid adding `aria-live` unless you need a specific announcement behavior.
+
+When Alerts appear after a user action or via system feedback:
+
+- Ensure the Alert is inserted into the DOM at the moment it becomes relevant, this triggers screen reader announcement.
+- Avoid showing Alerts that are visually hidden and later revealed; screen readers may miss them.
+- Do not use timers or automatic removal for critical content. The timer should start once the user is done reading it.
+
+> **Info:** DOM (Document Object Model) is the internal structure of the web page that the browser builds from HTML. When an element (like an Alert) is inserted into the DOM dynamically, assistive technologies such as screen readers detect it and announce it automatically. This is why Alerts triggered by user actions must be created and added programmatically at the moment they become relevant, not just shown/hidden.
+
+The first focusable element should be "See more" when available, or the "Close" button if present. It should have an accessible name (`aria-label="Dismiss"` or "Close alert") and be operable with Enter and Space.
+
+Do not force focus onto an Alert unless:
+
+- It is critical.
+- It directly blocks user progress.
+- The user cannot continue without reading it.
+
+For all other Alerts, do not steal focus from user controls.

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

@@ -0,0 +1,65 @@
+# Alert — API
+
+## `df-alert-title` — Component
+
+_Since 22.0_
+
+Defines the title content inside a <df-alert>.
+
+## `df-alert-details` — Component
+
+_Since 22.0_
+
+Defines the details content inside a <df-alert>.
+
+## `df-alert` — Component
+
+_Since 22.0_
+
+Provides contextual feedback messages for the user. Supports several visual types, dismissal, and collapsible content.
+
+### Inputs
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| animated | `boolean \| undefined` | `true` | If true, closing and collapsible transitions are animated. |
+| appearance | `DfAlertAppearance` | `'default'` | Alert appearance variant. 'default': regular alert with rounded corners and leading border. 'banner': full-width alert with square corners and bottom border. |
+| dismissible | `boolean \| undefined` | `true` | If true, alert can be dismissed by the user. The close button (×) will be displayed and you can be notified of the event with the (closed) output. |
+| expandable | `boolean \| undefined` | `false` | If true, alert details can be toggled with a "see more" control. When false, details are shown inline when present. |
+| size | `DfAlertSize` | `'md'` | Size of the alert. Accepts 'sm', 'md' or 'lg'. |
+| type | `DfAlertType` | `'warning'` | Type of the alert. Supported types: 'success', 'info', 'warning', 'danger', 'tip'. |
+
+### Outputs
+
+| Name | Type | Description |
+|------|------|-------------|
+| closed | `void` | Emitted after the alert closing transition finishes, whether triggered by the close button or the close() method. |
+
+### Methods
+
+#### `close(animated: boolean | undefined)` => `Promise<void>`
+
+Triggers alert closing programmatically.
+
+## DfAlertConfig — Configuration
+
+Configuration options supported by provideDfAlertConfig. These defaults apply to every DfAlert instance within the providing injector, unless explicitly overridden on the component itself.
+
+### Properties
+
+| Name | Type | Description |
+|------|------|-------------|
+| animated | `boolean` | If true, the alert closing will be animated. Animation is triggered when clicked on the close button (×), via the .close() function or the visible prop is changed |
+| ariaCloseButtonLabel | `string` | Accessibility close button label |
+| collapseLabel | `string` | Label shown when alert details can be collapsed. |
+| expandLabel | `string` | Label shown when alert details can be expanded. |
+
+### Methods
+
+#### `provideDfAlertConfig(config: Partial<DfAlertConfig> | ((prevConfig: Partial<DfAlertConfig>) => Partial<DfAlertConfig>) | undefined)` => `FactoryProvider`
+
+Provides the configuration for the alert component.
+
+#### `injectDfAlertConfig()` => `WritableSignal<Partial<DfAlertConfig>>`
+
+Injects the configuration for the alert component.

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

@@ -0,0 +1,63 @@
+Use the default alert when the standard appearance is enough. Adjust `type` and `size` when the message needs a
+different semantic meaning or more visual emphasis.
+
+> Demo source: [docs/demos/alert/basic/](../../demos/alert/basic/)
+
+Use the title for the short summary that should stay easy to scan. Use details for supporting information, longer
+descriptions or follow-up instructions. `<df-alert-title>` is optional. When there is no explicit title slot, direct
+content projected into `<df-alert>` is used as the title.
+
+```angular-html
+<!-- short version -->
+<df-alert>Short description</df-alert>
+
+<!-- preferred -->
+<df-alert>
+  <df-alert-title>Short description</df-alert-title>
+  <df-alert-details>
+    More detailed content can include longer text, formatting and additional guidance.
+  </df-alert-details>
+</df-alert>
+
+<!-- possible -->
+<df-alert>
+  Short description
+  <df-alert-details>More details go here.</df-alert-details>
+</df-alert>
+```
+
+By default, details are visible immediately. Add the `expandable` attribute only when the details should be collapsible.
+
+Alerts are dismissible by default. Set `[dismissible]="false"` when the message must stay visible. Treat dismissal as
+parent-owned state: listen to `(closed)` and remove the alert from your own state, either with conditional rendering or
+by updating a collection.
+
+```angular-html
+@if (!closed) {
+  <df-alert (closed)="closed = true">Closable alert</df-alert>
+}
+```
+
+> Demo source: [docs/demos/alert/dismissal/](../../demos/alert/dismissal/)
+
+Use `<df-alert-details>` for the secondary content. Add `expandable` when the "See more" control should be
+rendered, and use `[(expanded)]` when that state must be controlled.
+
+```angular-html
+<df-alert expandable [(expanded)]="expanded">
+  <df-alert-title>Short description</df-alert-title>
+  <df-alert-details>More details go here</df-alert-details>
+</df-alert>
+```
+
+If no explicit `<df-alert-title>` is provided, any projected content outside of `<df-alert-details>` is treated as the
+title.
+
+> Demo source: [docs/demos/alert/expandable/](../../demos/alert/expandable/)
+
+Use `appearance="banner"` when the alert should use banner styling. It can be used inside nested layouts, or positioned
+at page level when it should span the full content width.
+
+> Demo source: [docs/demos/alert/card/](../../demos/alert/card/)
+
+> Demo source: [docs/demos/alert/banner/](../../demos/alert/banner/)