# `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](https://bulma.io/documentation/features/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.