Add Breadcrumb component documentation

articles/components/breadcrumb/index.adoc

@@ -0,0 +1,292 @@
+---
+tab-title: Usage
+layout: tabbed-page
+title: Breadcrumb
+page-title: Breadcrumb Component | Vaadin components
+description: Breadcrumb is a navigation component that shows a hierarchical path through the application's structure, allowing users to navigate back to previous levels.
+meta-description: Use Vaadin's Breadcrumb component to show a hierarchical path through the application's structure and provide navigation to parent levels.
+page-links:
+  - 'API: https://cdn.vaadin.com/vaadin-web-components/{moduleNpmVersion:@vaadin/breadcrumb}/#/elements/vaadin-breadcrumb[TypeScript] / https://vaadin.com/api/platform/{moduleMavenVersion:com.vaadin:vaadin}/com/vaadin/flow/component/breadcrumb/Breadcrumb.html[Java]'
+  - 'Source: https://github.com/vaadin/web-components/tree/v{moduleNpmVersion:@vaadin/breadcrumb}/packages/breadcrumb[TypeScript] / https://github.com/vaadin/flow-components/tree/{moduleMavenVersion:com.vaadin:vaadin}/vaadin-breadcrumb-flow-parent[Java]'
+---
+
+= Breadcrumb
+:toclevels: 2
+:experimental:
+
+// tag::description[]
+Breadcrumb is a navigation component that shows a hierarchical path through the application's structure, allowing users to navigate back to previous levels.
+// end::description[]
+
+[.example]
+--
+
+ifdef::lit[]
+[source,html]
+----
+include::{root}/frontend/demo/component/breadcrumb/breadcrumb-basic.ts[render,tags=snippet,indent=0,group=Lit]
+----
+endif::[]
+
+ifdef::flow[]
+[source,java]
+----
+include::{root}/src/main/java/com/vaadin/demo/component/breadcrumb/BreadcrumbBasic.java[render,tags=snippet,indent=0,group=Flow]
+----
+endif::[]
+
+ifdef::react[]
+[source,tsx]
+----
+include::{root}/frontend/demo/component/breadcrumb/react/breadcrumb-basic.tsx[render,tags=snippet,indent=0,group=React]
+----
+endif::[]
+
+--
+
+Use Breadcrumb when you want to show the user's current location within a hierarchy and provide navigation to parent levels. The component is particularly useful in applications with deep navigation structures.
+
+
+== Adding Items
+
+Breadcrumb items can be added individually or in bulk. Each item represents a level in the navigation hierarchy.
+
+[.example]
+--
+
+ifdef::lit[]
+[source,html]
+----
+include::{root}/frontend/demo/component/breadcrumb/breadcrumb-items.ts[render,tags=snippet,indent=0,group=Lit]
+----
+endif::[]
+
+ifdef::flow[]
+[source,java]
+----
+include::{root}/src/main/java/com/vaadin/demo/component/breadcrumb/BreadcrumbItems.java[render,tags=snippet,indent=0,group=Flow]
+----
+endif::[]
+
+ifdef::react[]
+[source,tsx]
+----
+include::{root}/frontend/demo/component/breadcrumb/react/breadcrumb-items.tsx[render,tags=snippet,indent=0,group=React]
+----
+endif::[]
+
+--
+
+
+== Navigation
+
+Breadcrumb items can be configured with links to enable navigation. The last item typically represents the current page and should not be clickable.
+
+[.example]
+--
+
+ifdef::lit[]
+[source,html]
+----
+include::{root}/frontend/demo/component/breadcrumb/breadcrumb-navigation.ts[render,tags=snippet,indent=0,group=Lit]
+----
+endif::[]
+
+ifdef::flow[]
+[source,java]
+----
+include::{root}/src/main/java/com/vaadin/demo/component/breadcrumb/BreadcrumbNavigation.java[render,tags=snippet,indent=0,group=Flow]
+----
+endif::[]
+
+ifdef::react[]
+[source,tsx]
+----
+include::{root}/frontend/demo/component/breadcrumb/react/breadcrumb-navigation.tsx[render,tags=snippet,indent=0,group=React]
+----
+endif::[]
+
+--
+
+ifdef::flow[]
+=== Router Integration
+
+In Flow applications, breadcrumb items can be integrated with Vaadin Router for type-safe navigation to specific views.
+
+[.example]
+--
+
+[source,java]
+----
+include::{root}/src/main/java/com/vaadin/demo/component/breadcrumb/BreadcrumbRouter.java[render,tags=snippet,indent=0,group=Flow]
+----
+endif::[]
+
+--
+endif::[]
+
+
+== Disabled Items
+
+Individual breadcrumb items can be disabled to indicate that navigation to that level is not currently available.
+
+[.example]
+--
+
+ifdef::lit[]
+[source,html]
+----
+include::{root}/frontend/demo/component/breadcrumb/breadcrumb-disabled.ts[render,tags=snippet,indent=0,group=Lit]
+----
+endif::[]
+
+ifdef::flow[]
+[source,java]
+----
+include::{root}/src/main/java/com/vaadin/demo/component/breadcrumb/BreadcrumbDisabled.java[render,tags=snippet,indent=0,group=Flow]
+----
+endif::[]
+
+ifdef::react[]
+[source,tsx]
+----
+include::{root}/frontend/demo/component/breadcrumb/react/breadcrumb-disabled.tsx[render,tags=snippet,indent=0,group=React]
+----
+endif::[]
+
+--
+
+
+== Size Variants
+
+Breadcrumb supports different size variants to fit various layout requirements.
+
+[.example]
+--
+
+ifdef::lit[]
+[source,html]
+----
+include::{root}/frontend/demo/component/breadcrumb/breadcrumb-sizes.ts[render,tags=snippet,indent=0,group=Lit]
+----
+endif::[]
+
+ifdef::flow[]
+[source,java]
+----
+include::{root}/src/main/java/com/vaadin/demo/component/breadcrumb/BreadcrumbSizes.java[render,tags=snippet,indent=0,group=Flow]
+----
+endif::[]
+
+ifdef::react[]
+[source,tsx]
+----
+include::{root}/frontend/demo/component/breadcrumb/react/breadcrumb-sizes.tsx[render,tags=snippet,indent=0,group=React]
+----
+endif::[]
+
+--
+
+[cols="1,3",grid=rows]
+|===
+|Variant |Usage Recommendation
+
+|Small
+|Compact option for dense layouts or when space is limited.
+
+|Normal
+|Default size. Suitable for most use cases.
+
+|Large
+|For improved visibility and touch accessibility on larger displays.
+|===
+
+
+== Custom Content
+
+Breadcrumb items can contain custom components in addition to or instead of plain text.
+
+[.example]
+--
+
+ifdef::lit[]
+[source,html]
+----
+include::{root}/frontend/demo/component/breadcrumb/breadcrumb-custom.ts[render,tags=snippet,indent=0,group=Lit]
+----
+endif::[]
+
+ifdef::flow[]
+[source,java]
+----
+include::{root}/src/main/java/com/vaadin/demo/component/breadcrumb/BreadcrumbCustom.java[render,tags=snippet,indent=0,group=Flow]
+----
+endif::[]
+
+ifdef::react[]
+[source,tsx]
+----
+include::{root}/frontend/demo/component/breadcrumb/react/breadcrumb-custom.tsx[render,tags=snippet,indent=0,group=React]
+----
+endif::[]
+
+--
+
+
+== Best Practices
+
+=== Hierarchy Representation
+
+Breadcrumbs should reflect the actual information architecture of your application, not the user's session history. Each level should represent a logical parent-child relationship.
+
+
+=== Current Page Indication
+
+The last breadcrumb item should represent the current page and should not be clickable. This helps users understand their current location.
+
+
+=== Length Consideration
+
+Avoid overly long breadcrumb trails. Consider abbreviating middle levels or using ellipsis for very deep hierarchies to maintain usability.
+
+
+=== Mobile Considerations
+
+On smaller screens, consider showing only the immediate parent and current page, or implement a collapsible breadcrumb pattern.
+
+
+== Keyboard Usage
+
+Users can navigate breadcrumb items using the following keyboard shortcuts:
+
+- kbd:[Tab] / kbd:[Shift+Tab]: Move focus between breadcrumb items
+- kbd:[Enter] / kbd:[Space]: Activate the focused item (if it has a link)
+
+
+== Accessibility
+
+Breadcrumb automatically includes proper ARIA attributes for screen readers:
+
+- The component has `role="navigation"` and `aria-label="Breadcrumb"`
+- The current page item is marked with `aria-current="page"`
+- Disabled items are properly communicated to assistive technologies
+
+
+== Related Components
+
+[cols="1,2"]
+|===
+|Component |Usage Recommendation
+
+|<<../menu-bar#,Menu Bar>>
+|For horizontal navigation menus with dropdown options.
+
+|<<../side-nav#,Side Navigation>>
+|For vertical navigation in application sidebars.
+
+|<<../tabs#,Tabs>>
+|For switching between different views or sections within the same page.
+|===
+
+
+[discussion-id]`BREADCRUMB-COMPONENT-DISCUSSION`