Add Flex Layout documentation

articles/components/html-elements/index.adoc

@@ -18,7 +18,7 @@ Components that can contain other components thereby implement the [interfacenam
 
 The module `flow-html-components` contains the following components:
 
-[cols="4,2,7",options=header]
+[cols="3,2,6",options=header]
 |===
 | Component | HTML Element | Comments
 | `Anchor` | `a` | The https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/a[anchor element] defines a hyperlink to a resource.
@@ -27,8 +27,9 @@ It can link to many kinds of targets, such as web pages, files, email addresses,
 | `Aside`  | `aside` | The https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/aside[aside element] represents content that is indirectly related to the document’s main content, such as a sidebar.
 | `DescriptionList` | `dl` | The https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/dl[description list element] represents a description list, commonly used to implement a glossary or to display metadata (a list of key-value pairs).
 | `Div` | `div` | The https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/div[div element] is a generic container for content.
-| `Emphasis` | `em` | The https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/em[emphasis element] is for words that have a stressed emphasis compared to surrounding text.
+| `Emphasis` | `em` | The https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/em[emphasis element] is for words that have a stressed emphasis compared to the surrounding text.
 | `FieldSet` | `fieldset` | The https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/fieldset[field set element] is used to organize and group related inputs and their labels in a form.
+| `FlexLayout` | `div` + `display:flex` | `Div` with the `display` property set to `flex`. Includes "Flexbox" specific Flow API. See the <<#flex-layout-component,Flex Layout>> section for more information.
 | `Footer` | `footer` | The https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/footer[footer element] represents a footer for a document or a section, often containing content such as copyright notices, contact information, or links to related documents.
 | `H1`, .., `H6` | `h1`, .., `h6` | The https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/Heading_Elements[h1 to h6 elements] represent six levels of section headings, with `h1` being the highest level and `h6` the lowest, commonly used for page or section titles.
 | `Header` | `header` | The https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/header[header element] represents a container for introductory content, usually containing a logo, a search form, and a heading element.
@@ -82,4 +83,19 @@ Also, the HTML fragment must have exactly one root element. If the fragment cont
 
 Last thing to consider is that the `Html` component doesn't support SVG elements as a root node. For SVG content, the `Svg` component should be used instead.
 
+
+== Flex Layout Component
+
+Flex Layout arranges components in a row or a column. Each item can expand to fill the available space or shrink to fit smaller containers.
+
+It leverages the https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/CSS_layout/Flexbox[CSS Flexbox] layout model
+to provide flexible and responsive positioning of child components.
+
+On the client side, Flex Layout is represented by a simple `div` element with `display: flex`.
+
+The Flow API provides convenient constants and methods that make Flex Layout configuration straightforward and intuitive.
+
+[CAUTION]
+It is generally recommended to use the <<{articles}/components/horizontal-layout#,Horizontal Layout>> or the <<{articles}/components/vertical-layout#,Vertical Layout>> component instead. They offer nearly all the same features as Flex Layout, but with better default styling (such as gaps and padding) and a more intuitive API. Flex Layout remains available in the Vaadin API primarily for backward compatibility. However, it is not recommended for use going forward.
+
 [discussion-id]`6774751B-921E-4B79-941E-830D9C3532B4`