@htmlbricks/hb-sidenav-button 0.71.34 → 0.71.36

package/README.md

@@ -1,36 +1,130 @@
-## `hb-sidenav-button` — sidenav button
+# hb-sidenav-button
 
-**Category:** layout  
-**Tags:** layout, navigation
+**Category:** layout · **Tags:** layout, navigation
 
-### What it does
+## Overview
 
-Compact sidebar row as a nav button: optional Bootstrap Icons (`bi-*`) via `bootstrapIcon`, Bulma `tag` badge (optional `badge.class` / `badge.classcolor` modifiers), or visual types (`switch`, `checkbox`, `radio`) from `navlink` JSON; dispatches `pageChange` with the row `key` on click. Used by `hb-sidebar-cards-navigator` and similar stacked menus.
+`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.
 
-### Custom element
+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`
 
-### Attributes (snake_case; use string values in HTML)
+## Props / 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.
 
-- `id`, `style` (optional): strings.
-- `navlink` (required): JSON string — `INavLink` (`key`, `text`, optional `bootstrapIcon`, `badge`, `value`, `type`, `selected`).
+### Navlink object (`INavLink`)
 
-### Events
+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:
+
+```js
+el.addEventListener("pageChange", (e) => {
+  console.log(e.detail.page);
+});
+```
 
-- `pageChange`: `{ page: string }` — typically the link `key`.
+## Styling
 
-### Usage notes
+Styles use **Bulma** inside the shadow root. Theme the host page with public **`--bulma-*`** variables (see [Bulma CSS variables](https://bulma.io/documentation/features/css-variables/)). Variables referenced by this component are documented in `extra/docs.ts`; the main ones are:
 
-- **CSS parts:** `li`.
-- Styling uses Bulma inside the shadow root (buttons and tags); theme CSS variables follow Bulma’s scheme (e.g. `--bulma-link`).
-- Include [Bootstrap Icons](https://icons.getbootstrap.com/) if you use `bootstrapIcon` or the switch/checkbox/radio icons.
-- Storybook `nav_type` is a control helper; the shape lives on `navlink.type`.
+| 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). |
 
-### Minimal HTML example
+**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**
 
 ```html
 <hb-sidenav-button
   navlink='{"text":"Home","key":"home","bootstrapIcon":"house-door"}'
 ></hb-sidenav-button>
 ```
+
+**Selected row**
+
+```html
+<hb-sidenav-button
+  navlink='{"text":"Home","key":"home","bootstrapIcon":"house-door","selected":true}'
+></hb-sidenav-button>
+```
+
+**Badge**
+
+```html
+<hb-sidenav-button
+  navlink='{"text":"Messages","key":"messages","bootstrapIcon":"envelope","badge":{"text":"3","classcolor":"is-danger"}}'
+></hb-sidenav-button>
+```
+
+**Switch (no badge)**
+
+```html
+<hb-sidenav-button
+  navlink='{"text":"Notifications","key":"notifications","bootstrapIcon":"bell","type":"switch","value":true}'
+></hb-sidenav-button>
+```
+
+**Checkbox / radio (no badge)**
+
+```html
+<hb-sidenav-button
+  navlink='{"text":"Option A","key":"a","type":"checkbox","value":true}'
+></hb-sidenav-button>
+```
+
+## Package metadata
+
+- **Name:** `hb-sidenav-button` / `@htmlbricks/hb-sidenav-button`
+- **License:** Apache-2.0 (see package `LICENSE.md` where distributed)

package/manifest.json

@@ -141,11 +141,42 @@
     }
   },
   "styleSetup": {
-    "vars": [],
+    "vars": [
+      {
+        "name": "--bulma-link",
+        "valueType": "color",
+        "defaultValue": "#485fc7",
+        "description": "Ghost button hover and `aria-current` row accent stripe."
+      },
+      {
+        "name": "--bulma-link-text",
+        "valueType": "color",
+        "defaultValue": "#ffffff",
+        "description": "Text on the selected (`aria-current`) row background mix."
+      },
+      {
+        "name": "--bulma-scheme-main-bis",
+        "valueType": "color",
+        "defaultValue": "#f5f5f5",
+        "description": "Hover wash for sidenav rows."
+      },
+      {
+        "name": "--bulma-radius",
+        "valueType": "number",
+        "defaultValue": "0.375rem",
+        "description": "Row pill rounding for each list item."
+      },
+      {
+        "name": "--bulma-text-weak",
+        "valueType": "color",
+        "defaultValue": "#7a7a7a",
+        "description": "Muted badge text when tags use weak contrast."
+      }
+    ],
     "parts": [
       {
         "name": "li",
-        "description": "list element"
+        "description": "Outer list item wrapper for the row."
       }
     ]
   },
@@ -238,5 +269,5 @@
   "size": {},
   "iifePath": "main.iife.js",
   "repoName": "@htmlbricks/hb-sidenav-button",
-  "version": "0.71.34"
+  "version": "0.71.36"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@htmlbricks/hb-sidenav-button",
-  "version": "0.71.34",
+  "version": "0.71.36",
   "contributors": [],
   "description": "Compact sidebar row as a nav button: optional Bootstrap Icons (bi-*) icon, Bulma tag badge, or visual types (switch, checkbox, radio) from navlink JSON; dispatches pageChange with the row key on click. Used by sidebar-cards-navigator and similar stacked menus.",
   "licenses": [