hb-sidebar-desktop (sidebar-desktop)

Category: layout
Tags: layout, navigation
Package: @htmlbricks/hb-sidebar-desktop

Overview

hb-sidebar-desktop is a fixed-width desktop sidebar shell: optional company branding (logo URI and title), a scrollable navigation list rendered with nested hb-sidenav-link elements, optional section groups, an optional language dropdown, and a Bulma-aligned theme control (light, dark, or system). It is styled with Bulma tokens and Bootstrap Icons (loaded for menu icons).

The host drives the active route with navpage (page key) and supplies navlinks (and optionally groups). When the user selects a page, a child link, or a theme/language option, the component dispatches bubbling, composed custom events so the host can update routing, persist theme, and sync language.

Dependency

This package expects hb-sidenav-link to be available (same version family as your bundle). Each row is a hb-sidenav-link with navlink passed as a JSON string and navpage mirrored from the sidebar.

Slots

| Slot | Description | |------|-------------| | test | Optional light-DOM content at the very top of the sidebar shell, before the padded inner column (outside brand, nav, and controls). | | header | Optional content inside the brand title row, before the logo and company title (same row as the header CSS part). | | footer | Optional footer region below the nav list and the theme/language toolbar. Rendered only when enablefooter is yes (default slot content in the implementation is placeholder text until you override it). |

CSS parts

| Part | Description | |------|-------------| | header | Top chrome in the brand title row (the surface that wraps the header slot and brand). |

Styling (Bulma CSS variables)

Public theming uses --bulma-* on the host document or on ancestors; see Bulma CSS variables. Documented variables match extra/docs.ts / styleSetup:

| Variable | Role | |----------|------| | --bulma-navbar-background-color | Sidebar shell background (same token chain as hb-navbar). | | --bulma-scheme-main-bis | Fallback surface when the navbar background token is unset. | | --bulma-text | Default labels and menu copy. | | --bulma-link | Active row accent and theme/language controls. | | --bulma-block-spacing | Brand block spacing and vertical rhythm inside the shell. | | --bulma-border | Section separators / hairlines. |

Icons: pass Bootstrap Icons suffix only on each INavLink (for example house-door, not bi or bi-). The component loads the Bootstrap Icons font stylesheet in the shadow tree.

Navigation model

navlinks

navlinks is an array of INavLink objects (or a JSON string that parses to that array). Each item includes:

• key — stable page identifier (emitted on pageChange and matched against navpage for selection).
• label — visible text.
• icon — optional Bootstrap Icons suffix.
• group — optional string key; used to place the item under a grouped section (see below).
• badge — optional { text, class?, classcolor? }.
• subLinks — optional nested links (handled by hb-sidenav-link).

groups

Optional groups is { key: string; label: string }[] (or a JSON string). When groups is non-empty, the sidebar renders each group’s label as a Bulma menu-label, then every navlinks item whose group equals that key.

If some navlinks entries have a group that is not listed in groups, the component auto-generates sections: it derives distinct group values from those links and uses the raw group string as the section heading label.

Links without a group are listed first, above any grouped sections.

Theme behavior

• enablethemeswitch: when yes, three buttons appear: light, dark, and auto (system).
• Choosing a mode updates internal state, applies Bulma document hooks on document.documentElement and document.body (data-theme, theme-light / theme-dark classes, cleared for auto), and dispatches themeChange with { mode: "light" | "dark" | "auto" }.
• themepreference: when set to light, dark, or auto, the sidebar treats it as a controlled value and syncs hooks to match. If it is unset or invalid on mount, the component reads the current preference from the document (data-theme / theme classes).
• The host may ignore themeChange and only drive themepreference, or combine both (for example persist themeChange then set themepreference).

Language behavior

• i18nlanguages: array of { code, label } or a JSON string (array of objects or of string codes; string codes use the code as the label).
• i18nlang: active BCP-47 / app language code; should match a code in i18nlanguages when you rely on the “active” state in the dropdown.
• The language dropdown appears when there is at least one parsed option. Picking an option dispatches languageChange with { code: string }. The host should update i18nlang (for example on hb-layout) and reload copy.

The bottom toolbar (language + theme) is shown when enablethemeswitch is yes or there is at least one language option.

Custom element

<hb-sidebar-desktop …></hb-sidebar-desktop>

Attributes and properties (snake_case)

Web component attributes are strings. Booleans use yes / no where noted. Objects and arrays are typically passed as JSON strings from HTML, or as JS properties.

| Name | Description | |------|-------------| | id | Optional element id. | | companylogouri | Optional image URL for the brand logo (shown when companytitle is set and a URI is provided). | | companytitle | Optional company or product title next to the logo. | | navpage | Active page key; forwarded to each hb-sidenav-link. | | navlinks | JSON string or array: list of INavLink entries. | | groups | Optional JSON string or array: { key, label }[] for explicit section headings and membership. | | enablefooter | yes (default) shows the footer chrome and the footer slot; no or false hides it. | | enablethemeswitch | yes (default) shows the theme control; no hides it (language-only toolbar still possible if languages are set). | | themepreference | Optional controlled theme: light, dark, or auto. | | i18nlang | Optional current language code for the selector. | | i18nlanguages | Optional JSON string or array of { code, label } (or string codes). |

The authoring Component type also includes style, cookielawallowdecline, cookielawlanguage, cookielawuri4more, and single_screen for catalog alignment. They are not read by the current component.wc.svelte implementation; treat them as reserved unless a future version wires them in.

Events

All events bubble and are composed (usable from the light DOM).

| Event | detail | |-------|----------| | pageChange | { page: string } — selected nav key. | | themeChange | { mode: "light" \| "dark" \| "auto" } — user-chosen theme; host may persist and/or set themepreference. | | languageChange | { code: string } — chosen language; host should set i18nlang. |

Examples

Minimal HTML

<hb-sidebar-desktop
  companytitle="Acme"
  navpage="home"
  navlinks='[{"label":"Home","key":"home","icon":"house-door"}]'
></hb-sidebar-desktop>

Grouped navigation (explicit groups)

<hb-sidebar-desktop
  navpage="settings"
  groups='[{"key":"admin","label":"Administration"},{"key":"stats","label":"Statistics"}]'
  navlinks='[
    {"label":"Home","key":"home","icon":"house-door"},
    {"label":"Settings","key":"settings","icon":"gear","group":"admin"},
    {"label":"Users","key":"users","icon":"people-fill","group":"admin"},
    {"label":"Stats","key":"stats","icon":"graph-up","group":"stats"}
  ]'
></hb-sidebar-desktop>

Theme + language

<hb-sidebar-desktop
  navpage="home"
  enablethemeswitch="yes"
  themepreference="auto"
  i18nlang="en"
  i18nlanguages='[
    {"code":"en","label":"English"},
    {"code":"it","label":"Italiano"}
  ]'
  navlinks='[{"label":"Home","key":"home","icon":"house-door"}]'
></hb-sidebar-desktop>

JavaScript property API

const el = document.querySelector("hb-sidebar-desktop");
el.navlinks = [
  { label: "Home", key: "home", icon: "house-door" },
  { label: "Settings", key: "settings", icon: "gear", group: "admin" },
];
el.navpage = "home";
el.addEventListener("pageChange", (e) => {
  console.log(e.detail.page);
});

Related components

Navigation shape and icon rules align with other layout shells that reuse the same navlinks / hb-sidenav-link pattern (for example mobile off-canvas navigation in hb-offcanvas).

License

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