hb-sidenav-button (sidenav-button)

Category: layout
Tags: layout, navigation
Package: @htmlbricks/hb-sidenav-button

Overview

hb-sidenav-button is a single sidebar navigation row: a full-width ghost Bulma button inside a list item (<li>). It is meant to be used in stacked menus (for example together with hb-sidebar-cards-navigator). Clicking the row dispatches a pageChange custom event whose detail is the link’s key, so the host can switch views or routes.

The row can show:

• a Bootstrap Icons glyph (when bootstrapIcon is set),
• a Bulma tag badge (when badge is set),
• or control-style visuals for type checkbox, radio, or switch (when there is no badge, using icon state from value).

Optional selected sets aria-current="page" and Bulma “selected” styling for the active row.

Custom element

<hb-sidenav-button …></hb-sidenav-button>

Attributes

Web component attributes are strings. Pass complex data as a JSON string on navlink.

| Attribute | Required | Description | |-----------|----------|-------------| | navlink | yes | JSON string describing one navigation item (see Navlink object below). If the runtime binding delivers a string, the component attempts JSON.parse on it. |

The TypeScript Component type in types/webcomponent.type.d.ts also lists optional id and style. Rendering is driven by navlink; you can still set a normal HTML id on <hb-sidenav-button> in the document when useful.

Navlink object (INavLink)

All consumer-facing keys use the shape below (logical names; in JSON use these exact property names).

| Property | Type | Description | |----------|------|-------------| | key | string | Identifier for this row; sent as pageChange detail page. | | text | string | Primary label (main text in the row). | | bootstrapIcon | string (optional) | Bootstrap Icons name without the bi- prefix (for example "house-door" → bi-house-door). Shown when the row is not using the checkbox/radio-only layout, or as the leading icon for a generic row. | | subtext | string (optional) | Present in typings for shared nav models; this component does not render subtext. | | badge | object (optional) | { "text": string, "class"?: string, "classcolor"?: string }. Renders a Bulma tag on the right. Bulma modifier classes can be passed via class (default-like behavior in markup uses is-rounded) and classcolor (defaults toward is-light). When badge is set, type-based switch UI is not shown (badge takes precedence for the trailing area). | | value | string, number, or boolean (optional) | Drives checkbox / radio / switch visuals (true / filled vs off). | | selected | boolean (optional) | When true, the row is styled as current and exposes aria-current="page". | | type | string (optional) | One of "switch", "range", "radio", "checkbox", "button". Rendered behavior: checkbox and radio show check/circle icons when there is no badge; switch shows a toggle icon when there is no badge; "button" and "range" do not add extra control icons beyond bootstrapIcon / text. |

Events

| Event | Detail | When | |-------|--------|------| | pageChange | { page: string } | Every click on the row button. page is the navlink key. |

Listen in the DOM:

el.addEventListener("pageChange", (e) => {
  console.log(e.detail.page);
});

Styling

Styles use Bulma inside the shadow root. Theme the host page with public --bulma-* variables (see Bulma CSS variables). Variables referenced by this component are documented in extra/docs.ts; the main ones are:

| Variable | Role | |----------|------| | --bulma-link | Left accent stripe and mixes for the selected (aria-current) row. | | --bulma-link-text | Text color on the selected row background mix. | | --bulma-scheme-main-bis | Hover wash for rows. | | --bulma-radius | Corner rounding for each row. | | --bulma-text-weak | Muted tone where weak contrast is used (for example badge-related styling). |

CSS part: li — the outer list item wrapper (::part(li) from the light DOM).

Icons: rows use Bootstrap Icons (bi-*). The component loads the icon font (see component.wc.svelte / styles). For predictable versions in production pages, prefer pinning a known Bootstrap Icons URL instead of relying only on @latest where you control the document.

Slots

None (htmlSlots is empty in extra/docs.ts).

Integration notes

• In Storybook, nav_type is a control helper for picking a type value; at runtime the field lives on navlink.type inside the JSON navlink string.
• Wrap multiple hb-sidenav-button elements in a <ul class="..."> in the light DOM if you need a semantic list; each instance renders one <li part="li">.

HTML examples

Plain icon + label

<hb-sidenav-button
  navlink='{"text":"Home","key":"home","bootstrapIcon":"house-door"}'
></hb-sidenav-button>

Selected row

<hb-sidenav-button
  navlink='{"text":"Home","key":"home","bootstrapIcon":"house-door","selected":true}'
></hb-sidenav-button>

Badge

<hb-sidenav-button
  navlink='{"text":"Messages","key":"messages","bootstrapIcon":"envelope","badge":{"text":"3","classcolor":"is-danger"}}'
></hb-sidenav-button>

Switch (no badge)

<hb-sidenav-button
  navlink='{"text":"Notifications","key":"notifications","bootstrapIcon":"bell","type":"switch","value":true}'
></hb-sidenav-button>

Checkbox / radio (no badge)

<hb-sidenav-button
  navlink='{"text":"Option A","key":"a","type":"checkbox","value":true}'
></hb-sidenav-button>

License

Package metadata references Apache-2.0 (see LICENSE.md in the published package when consuming from npm).