hb-layout

Category: layout · Tags: layout, shell · Package: @htmlbricks/hb-layout

Overview

hb-layout is a responsive application shell that picks one of two nested implementations based on the viewport width:

• Viewport width < 800px — mounts hb-layout-mobile (mobile chrome, off-canvas patterns, compact navbar).
• Viewport width ≥ 800px — mounts hb-layout-desktop (sidebar + desktop navbar).

The host forwards configuration props, named slots, and many custom events from whichever child is active. Bulma-driven child packages (navbar, footer, sidebar, cookie banner, and so on) inherit theme tokens you set on hb-layout or its ancestors.

Consumer rules (web components)

• Attribute names use snake_case (for example page_title, cookielawuri4more).
• From HTML, pass objects and arrays as JSON strings (for example company='{"siteName":"Acme"}').
• Pass booleans as the strings yes or no where the platform expects stringly attributes (see individual props below; some nested booleans remain JSON booleans inside JSON payloads).
• For authoritative TypeScript shapes of nested objects (company, contacts, navlinks, …), see types/webcomponent.type.d.ts in this folder and the shared types re-exported from hb-footer, hb-navbar, and hb-sidenav-link (paths referenced in that file).

Props (attributes / properties)

| Name | Purpose | |------|---------| | i18nlang | Locale hint passed into nested chrome (for example en, it). | | i18nlanguages | Languages for the sidebar language UI: either a JSON array of { code, label } or an equivalent in-memory array when using a framework binding. | | id | Declared on the component type; use the id attribute on the <hb-layout> element in HTML when you need a stable host id. | | style | Present in typings for host-level styling; the inner implementation focuses on nested layout tags—set styles on the custom element as needed. | | page_title | Title string shown in layout chrome (navbar / header context). | | pagename | Optional current page key label consumed by sidebar navigation state. | | company | Company / brand payload (ICompany) — JSON from HTML. | | contacts | Contact blocks for footer (IContacts). | | socials | Social links payload (ISocials). | | usermenu | Navbar user menu definition (IUserMenu). | | navlinks | Sidebar / navigation entries (INavLink[]). Icons use Bootstrap Icons names without the bi- prefix (for example "gear"). | | sidebar | Sidebar options: title, logo, type, enablefooter, enablethemeswitch (footer/theme toggles use yes / no / false-style string flags where applicable). | | footer | Footer behaviour: type — auto | small | regular | large; disable_expanding_small — boolean in the JSON object. | | policies | Footer policy links (IPolicies[]). | | columns | Extra footer column configuration (IColumn[]) when supported by hb-footer. | | cookielaw | Enables or configures cookie-law UI together with the fields below (yes / no, with child layouts also accepting true / false in nested checks). | | cookielawuri4more | “Learn more” URL for the cookie banner. | | cookielawlanguage | Language passed into hb-cookie-law-banner. | | cookielawallowdecline | Whether decline is offered (yes / no). | | single_screen | When enabled, uses a single-viewport column layout with footer behaviour tuned for compact shells (see Storybook-style examples in extra/docs.ts). | | heders | (Spelling as in the API.) Optional array of { name?, content, property? } objects rendered as <meta> tags via <svelte:head>: either name+content or Open Graph–style property+content. |

Events

The table lists events hb-layout forwards or emits. Listen with addEventListener or your framework’s on* bindings on hb-layout.

| Event | detail | Notes | |-------|----------|--------| | offcanvasswitch | { isOpen: boolean } | Mobile / drawer state from the active child. | | pageChange | { page: string } | Sidebar or shell navigated to a new logical page key. | | navbarDropDownClick | { key: string } | Desktop path only at the hb-layout wrapper: the mobile branch in component.wc.svelte does not re-dispatch this handler, so you will not receive it while the mobile layout is mounted. | | footerClick | { elClick: string } | Footer interaction payload from hb-footer. | | navbarSlotClick | { side: "left" \| "right" \| "center" } | Navbar slot clicks bubbled from the nested navbar. | | themeChange | { mode: "light" \| "dark" \| "auto" } | Theme mode changes from sidebar chrome. | | languageChange | { code: string } | Language selection changes from sidebar chrome. |

Slots

Slots are declared on hb-layout and forwarded into the active hb-layout-* child where the child exposes an equivalent surface.

| Slot | Role | Availability at the hb-layout bridge | |------|------|------------------------------------------| | page | Primary application view / routed content. | Mobile and desktop — always forwarded. | | nav-center-slot | Center navbar region (tabs, titles, tools). | Mobile and desktop. | | nav-right-slot | Right navbar actions / menus. | Mobile and desktop. | | nav-left-slot | Left navbar region. | Mobile only — the desktop branch does not wrap this slot; desktop left chrome is driven by company / sidebar inside hb-layout-desktop. | | nav-header-slot | Optional row above the main navbar. | Mobile only — not passed through in the desktop branch of hb-layout. |

Theme and layout styling (Bulma)

Set --bulma-* CSS variables on hb-layout (or on an ancestor) so nested navbar, sidebar, footer, and page regions share one palette. Optional chrome overrides (inherit into nested shadow hosts):

| Variable | Role | |----------|------| | --hb-layout-navbar-background | Top hb-navbar strip only (overrides Bulma navbar token for that host). | | --hb-layout-sidebar-background | hb-sidebar-desktop shell only (navbar unchanged). | | --bulma-text | Primary text forwarded into navbar, sidebar, and page regions. | | --bulma-background | Application background behind the shell. | | --bulma-link | Interactive accents in forwarded navigation components. | | --bulma-border | Dividers and low-contrast outlines. |

Per-component fallbacks: hb-navbar still resolves --hb-navbar-background-color then --bulma-navbar-background-color; hb-sidebar-desktop uses --hb-sidebar-background-color then --bulma-scheme-main-bis / --bulma-scheme-main-ter (see those packages’ READMEs).

See also Bulma CSS variables.

CSS ::part API

Expose these parts from the mounted child layout (same names as in styleSetup / extra/docs.ts):

| Part | Description | |------|-------------| | container | Outer shell wrapping navbar, main column, and footer stack. | | navbar | Top navigation bar (part="navbar" on nested hb-navbar). | | page | Main scrollable content column. | | footer | Footer region from hb-footer. |

Nested packages

Published bundles pull in hb-layout-desktop and hb-layout-mobile, each with its own dependency tree (hb-navbar, hb-footer, hb-offcanvas, hb-sidebar-desktop, hb-sidenav-link, hb-dropdown-simple, hb-cookie-law-banner, hb-contact-item, …). See dependencies in extra/docs.ts for the full graph used by documentation and catalog tooling.

Examples and metadata

Storybook-oriented examples (default shell, cookie law, single-screen mode, minimal nav) live in extra/docs.ts alongside styleSetup, htmlSlots, and storybookArgs.

Type reference (summary)

The authoring Component / Events types live in types/webcomponent.type.d.ts. They compose:

• IContacts, ISocials, ICompany, IColumn, IPolicies from the footer typings,
• IUserMenu from the navbar typings,
• INavLink from the sidenav link typings,

plus this host’s fields (i18nlanguages, sidebar, footer, heders, cookie-law props, single_screen, etc.). Open that file for exact optional fields and unions.