diff --git a/BitBlazor.sln b/BitBlazor.sln index 2bd0d03..fcfe668 100644 --- a/BitBlazor.sln +++ b/BitBlazor.sln @@ -36,6 +36,7 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "components", "components", docs\components\alert.md = docs\components\alert.md docs\components\avatar.md = docs\components\avatar.md docs\components\badge.md = docs\components\badge.md + docs\components\bottomnav.md = docs\components\bottomnav.md docs\components\breadcrumb.md = docs\components\breadcrumb.md docs\components\button-badge.md = docs\components\button-badge.md docs\components\button.md = docs\components\button.md diff --git a/docs/README.md b/docs/README.md index 56c1cf1..42fe4c4 100644 --- a/docs/README.md +++ b/docs/README.md @@ -37,6 +37,11 @@ Small and adaptable labels for adding information. - Support for rounded shapes - Various colors available +#### [BottomNav](components/bottomnav.md) +Mobile-optimized bottom navigation bar to show the current location or quick actions. +- Support for the customization of items, icons, alerts and badges +- Accessibility support + #### [Breadcrumb](components/breadcrumb.md) Breadcrumb navigation component to display the current location within a hierarchy. - Support for the customization of items and the separator diff --git a/docs/components/bottomnav.md b/docs/components/bottomnav.md new file mode 100644 index 0000000..5ca28a8 --- /dev/null +++ b/docs/components/bottomnav.md @@ -0,0 +1,107 @@ +# BitBottomNav + +The `BitBottomNav` component renders a [mobile-optimized bottom navigation bar](https://italia.github.io/bootstrap-italia/docs/menu-di-navigazione/bottomnav/) to show the current location or quick actions. It supports icons, badges, alert indicators and accessibility-friendly labels for each item. + +## Namespace + +```csharp +BitBlazor.Components +``` + +## Description + +BitBottomNav displays a horizontal list of navigation entries optimized for bottom placement (common on mobile apps). Each entry is a BitBottomNavItem that can render: +- a text, +- an icon (via BitIcon), +- an optional badge (text/number), +- an optional alert indicator (dot) when no badge is present, +- an active state applied via the IsActive flag. + +Items are rendered as anchor elements (``) so they are keyboard-focusable and navigable. Visual styling is provided by the consuming app's stylesheet; the component emits semantic classes the CSS targets. + +## Parameters + +| Name | Type | Required | Default | Description | +|-----------|--------------------------------------|----------|---------|-----------------------------------------------------------------------------| +| Items | IReadOnlyList | ✗ | `Enumerable.Empty().ToList()` | The collection of items to render in the bottom navigation. | + +## BitBottomNavItem + +Each item in Items is a `BitBottomNavItem`. Main properties: + +| Property | Type | Default | Description | +|------------|----------|---------------------|---------------------------------------------------------| +| `Text` | `string` | `string.Empty` | Visible label for the item. | +| `Icon` | `string?` | `null` | Optional icon name (rendered via `BitIcon`). | +| `Link` | `string?` | `null` | Optional URL for the item (). | +| `BadgeText` | `string?` | `null` | Optional badge text; when present renders a badge element. | +| `BadgeAriaLabel` | `string?` | `null` | Optional ARIA label for the badge/alert; rendered in a visually-hidden span. | +| `IsActive` | `bool` | `false` | If `true`, the item gets an active class (indicates current/selected item). | +| `IsAlertActive` | `bool` | `false` | When `true` and no `BadgeText` is set, a small alert indicator (dot) is rendered. | + +Helper methods on `BitBottomNavItem`: +- `HasBadge()` — `true` when `BadgeText` is non-empty. +- `HasAriaLabel()` — `true` when (badge or alert) and `BadgeAriaLabel` is non-empty. +- `HasIcon()` — `true` when `Icon` is non-empty. + +## Usage Examples + +### Default + +C# (prepare items): + +```csharp +var items = new List + { + new BitBottomNavItem { Text = "Messages", Link = "#", Icon = BitBlazor.Utilities.Icons.ItComment, BadgeText = "1", BadgeAriaLabel = "to read" }, + new BitBottomNavItem { Text = "Images", Link = "#", Icon = BitBlazor.Utilities.Icons.ItCamera, BadgeText = "2", BadgeAriaLabel = "to view" }, + new BitBottomNavItem { Text = "Documents", Link = "#", Icon = BitBlazor.Utilities.Icons.ItFile, BadgeText = "42", BadgeAriaLabel = "to examine" }, + new BitBottomNavItem { Text = "Favorites", Link = "#", Icon = BitBlazor.Utilities.Icons.ItStarOutline, IsActive = true }, + new BitBottomNavItem { Text = "Settings", Link = "#", Icon = BitBlazor.Utilities.Icons.ItSettings, IsAlertActive = true } + }; +``` + +Razor (render component): + +```razor + +``` + +## Common scenarios: +- Numeric/text badge: set `BadgeText` = "7" and optionally `BadgeAriaLabel` = "7 unread messages". +- Alert indicator (dot): set `IsAlertActive` = true and leave `BadgeText` empty. +- Icon-only visual with accessible status: supply Icon, Text, and a `BadgeAriaLabel` if there is a badge or alert. + +## Accessibility +- When a badge or alert is present and BadgeAriaLabel is provided, the label is rendered inside a visually-hidden span next to the visible label so assistive technologies receive the context (for example, "3 unread notifications"). +- Items render as anchors (), providing keyboard focus and native navigation behavior. Supply meaningful Link values. +- Provide concise and descriptive `Text` and `BadgeAriaLabel` strings to maximize clarity for screen reader users. + +## Generated CSS Classes + +- `bottom-nav` — root container on the