@htmlbricks/hb-sidenav-link 0.71.35 → 0.71.36

package/README.md

@@ -1,35 +1,124 @@
-## `hb-sidenav-link` — sidenav link
+# hb-sidenav-link
 
-**Category:** layout  
-**Tags:** layout, navigation
+**Category:** layout · **Tags:** layout, navigation
 
-### What it does
+## Overview
 
-Sidebar nav item: Bootstrap Icons (`bi-*`), label, optional Bulma `tag` badge (`badge.class` / `badge.classcolor` modifiers such as `is-light`, `is-primary`) rendered as **outlined** pills (transparent fill, border/text from the tag color), and either a flat button that dispatches `pageChange` on click or an expandable group of `subLinks` with active state when `navpage` or `selected` matches. Intended for use inside `hb-sidebar-desktop` lists.
+`hb-sidenav-link` is a single sidebar navigation row for hierarchical menus. It renders a Bootstrap Icons label row, an optional Bulma-style tag badge (outlined pill: transparent fill, border and text from the tag color), and either:
 
-### Custom element
+- a **leaf** link that dispatches `pageChange` when the user activates it, or  
+- a **parent** row with `subLinks` that expands to show nested links.
+
+Active styling applies when the current page key (`navpage`) matches a link key, or when the `selected` flag is enabled. The component is intended for use inside `hb-sidebar-desktop` lists (and shares the `INavLink` shape with related layout components).
+
+Bootstrap Icons are loaded from the component (`bootstrap-icons` CSS on jsDelivr). Icon names are the `bi-*` suffix only (for example `house-door` → `bi-house-door`).
+
+## Custom element
 
 `hb-sidenav-link`
 
-### Attributes (snake_case; use string values in HTML)
+## Props (TypeScript `Component`)
+
+| Property    | Type        | Required | Notes |
+|------------|-------------|----------|--------|
+| `navlink`  | `INavLink`  | yes      | From HTML, pass a **JSON string** (see below). |
+| `navpage`  | `string`    | no       | Current page key; drives active row and expanded groups. |
+| `selected` | `boolean`   | no       | When true, forces the “current page” appearance. From HTML use string encodings (see [Attributes](#attributes-snake_case-string-values-in-html)). |
+| `id`       | `string`    | no       | Optional identifier (typed on the component API). |
+| `style`    | `string`    | no       | Optional inline style (typed on the component API). |
+
+## `INavLink` shape
+
+Used for the root `navlink` and, recursively, for each entry in `subLinks`.
+
+| Field       | Type           | Required | Description |
+|------------|----------------|----------|-------------|
+| `key`      | `string`       | yes      | Stable id for the link; sent as `page` in `pageChange` for leaf clicks. |
+| `label`    | `string`       | yes      | Visible label. |
+| `icon`     | `string`       | no       | Bootstrap Icons name without the `bi-` prefix. |
+| `group`    | `string`       | no       | Present in the shared nav typings for interoperability. |
+| `badge`    | object         | no       | `text` (string), optional Bulma modifier classes `class` and `classcolor` (for example `is-rounded`, `is-light`). |
+| `subLinks` | `INavLink[]`   | no       | If non-empty, the row becomes an expandable group instead of a single leaf. |
+| `active`   | `boolean`      | no       | Present on the shared type; not read by this component’s markup. |
+| `open`     | `boolean`      | no       | When `navlink` is provided as a JSON string, `open: true` initializes the group as expanded. |
+
+### Badges
+
+`badge` supports:
+
+- `text` — badge label.  
+- `class` — optional Bulma tag class (defaults to `is-rounded` in the template).  
+- `classcolor` — optional color modifier (defaults to `is-light`).
+
+## Attributes (snake_case; string values in HTML)
+
+Reflects the web component contract: attributes are strings.
+
+| Attribute   | Required | Description |
+|------------|----------|-------------|
+| `navlink`  | yes      | JSON string representing `INavLink`. |
+| `navpage`  | no       | Current page key string. |
+| `selected` | no       | Boolean-as-string: `yes` / `no` per project conventions. The implementation also treats the literal strings `true` / `yes` as true, **and treats an empty string as true**; any other value becomes false unless already boolean true inside the app. Prefer explicit `yes` or `no` from HTML. |
+| `id`       | no       | String. |
+| `style`    | no       | String. |
+
+If `navlink` arrives as a string, the component parses it as JSON and applies `open` from the parsed object when `open === true`.
+
+## Events
+
+| Event        | `detail`              | When it fires |
+|-------------|------------------------|----------------|
+| `pageChange` | `{ page: string }`    | User activates a **non-active** leaf: either the root row (no `subLinks`) or a sub-link whose `key` does not match `navpage` and is not forced selected. **Active** rows (matching `navpage` or `selected`) are static for accessibility (`aria-current="page"`) and do **not** dispatch `pageChange` on click. |
+
+Listen in plain DOM:
+
+```js
+document.querySelector('hb-sidenav-link').addEventListener('pageChange', (e) => {
+  console.log(e.detail.page);
+});
+```
+
+## Behavior
+
+### Leaf row (no `subLinks`)
+
+- If `navlink.key === navpage` **or** `selected` is true: one full-width “current” button (link styling), no click navigation event.  
+- Otherwise: ghost button; click dispatches `pageChange` with `detail.page === navlink.key`.
+
+### Parent row (non-empty `subLinks`)
+
+- The parent row is a control that toggles expand/collapse and shows **▼** when open or when any child `key` equals `navpage`, otherwise **►**.  
+- The nested list is shown when the group is open **or** when some child has `key === navpage`.  
+- Each child follows the same active vs ghost rules as a leaf; inactive children dispatch `pageChange` with `detail.page ===` that child’s `key`.
+
+### Layout
+
+Labels use a flexible middle column; a fixed-width trail column (`--hb-sidenav-trail-width`) keeps titles aligned when some rows omit a badge or use the expand chevron. Long badge text is truncated with an ellipsis in the component styles.
 
-- `id`, `style` (optional): strings.
-- `navlink` (required): JSON string — `INavLink` (`label`, `key`, optional `icon`, `group`, `badge`, `subLinks`, `active`, `open`).
-- `navpage` (optional): string — current app page key for active styling.
-- `selected` (optional): boolean string — force selected appearance.
+## Styling (Bulma and component variables)
 
-### Events
+Buttons and tags live in the **shadow root**. Theme with public **`--bulma-*`** variables on `body`, `:root`, or an ancestor; see [Bulma CSS variables](https://bulma.io/documentation/features/css-variables/). Additional tokens are listed in `extra/docs.ts`.
 
-- `pageChange`: `{ page: string }`.
+| CSS custom property | Default (from docs) | Purpose |
+|--------------------|---------------------|---------|
+| `--bulma-link` | `#485fc7` | Active row stripe, chevrons, and interactive accents. |
+| `--bulma-link-text` | `#ffffff` | Text color on the active row background mix. |
+| `--bulma-text` | `#363636` | Default label color for inactive rows. |
+| `--bulma-scheme-main` | `#ffffff` | Row surface behind ghost buttons. |
+| `--bulma-radius` | `0.375rem` | Row rounding for list items. |
+| `--hb-sidenav-trail-width` | `3.5rem` | Width of the right column (badges / expand chevron); keeps labels aligned when some rows omit a badge. |
 
-### Usage notes
+### CSS parts
 
-- **CSS parts:** `li`.
-- **Layout:** labels share a flexible middle column; the right column is fixed width (`--hb-sidenav-trail-width`, default `3.5rem`) so titles stay aligned whether a badge or chevron is present. Long badge text truncates with an ellipsis. Badges use an outline treatment so they stay visible on ghost (unselected) rows.
-- Bulma buttons and tags are scoped inside the component; include Bootstrap Icons CSS for `icon` / `subLinks[].icon`.
-- Export type `INavLink` is shared with `hb-offcanvas` / `hb-sidebar-desktop` `navlinks` arrays.
+| Part | Description |
+|------|-------------|
+| `li` | Bulma menu list row (`li`) wrapping the ghost or link button, label column, badge or chevron trail, and nested sub-links. |
 
-### Minimal HTML example
+**Slots:** none (`htmlSlots` is empty).
+
+## Examples
+
+### Simple leaf
 
 ```html
 <hb-sidenav-link
@@ -37,3 +126,38 @@ Sidebar nav item: Bootstrap Icons (`bi-*`), label, optional Bulma `tag` badge (`
   navlink='{"label":"Home","key":"home","icon":"house-door"}'
 ></hb-sidenav-link>
 ```
+
+### Leaf with badge
+
+```html
+<hb-sidenav-link
+  navlink='{"label":"Home","key":"home","icon":"house-door","badge":{"text":"3","classcolor":"is-danger"}}'
+></hb-sidenav-link>
+```
+
+### Expandable group with sub-links
+
+```html
+<hb-sidenav-link
+  navpage="dash"
+  navlink='{"label":"Workspace","key":"workspace","icon":"folder2-open","subLinks":[{"label":"Dashboard","key":"dash","icon":"speedometer2"},{"label":"Projects","key":"projects","icon":"kanban"}]}'
+></hb-sidenav-link>
+```
+
+### Force selected appearance
+
+```html
+<hb-sidenav-link
+  selected="yes"
+  navlink='{"label":"Home","key":"home","icon":"house-door"}'
+></hb-sidenav-link>
+```
+
+## Related types
+
+`INavLink` matches the structure used by **`hb-offcanvas`** and **`hb-sidebar-desktop`** for `navlinks` arrays, so the same serialized objects can be reused across layout components.
+
+## Package metadata
+
+- **npm:** `@htmlbricks/hb-sidenav-link`  
+- **License:** Apache-2.0 (see package `LICENSE.md` in distribution)

package/manifest.json

@@ -133,6 +133,36 @@
   },
   "styleSetup": {
     "vars": [
+      {
+        "name": "--bulma-link",
+        "valueType": "color",
+        "defaultValue": "#485fc7",
+        "description": "Active row stripe, chevrons, and interactive accents."
+      },
+      {
+        "name": "--bulma-link-text",
+        "valueType": "color",
+        "defaultValue": "#ffffff",
+        "description": "Text color on the active row background mix."
+      },
+      {
+        "name": "--bulma-text",
+        "valueType": "color",
+        "defaultValue": "#363636",
+        "description": "Default label color for inactive rows."
+      },
+      {
+        "name": "--bulma-scheme-main",
+        "valueType": "color",
+        "defaultValue": "#ffffff",
+        "description": "Row surface behind ghost buttons."
+      },
+      {
+        "name": "--bulma-radius",
+        "valueType": "number",
+        "defaultValue": "0.375rem",
+        "description": "Row rounding for list items."
+      },
       {
         "name": "--hb-sidenav-trail-width",
         "valueType": "number",
@@ -143,7 +173,7 @@
     "parts": [
       {
         "name": "li",
-        "description": "list element"
+        "description": "Bulma menu list row (`li`) wrapping the ghost button, label column, badge or chevron trail, and nested sub-links."
       }
     ]
   },
@@ -243,5 +273,5 @@
   "size": {},
   "iifePath": "main.iife.js",
   "repoName": "@htmlbricks/hb-sidenav-link",
-  "version": "0.71.35"
+  "version": "0.71.36"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@htmlbricks/hb-sidenav-link",
-  "version": "0.71.35",
+  "version": "0.71.36",
   "contributors": [],
   "description": "Sidebar nav item: Bootstrap Icons (bi-*), label, optional Bulma-style tag badge (outlined pill: transparent fill, border uses tag foreground color), and either a flat button that dispatches pageChange on click or an expandable group of subLinks with active state when navpage or selected matches. Intended for use inside sidebar-desktop lists.",
   "licenses": [