@htmlbricks/hb-dashboard-card1 0.71.34 → 0.71.36

package/README.md

@@ -1,45 +1,192 @@
-## `hb-dashboard-card1` — dashboard-card1
+# `hb-dashboard-card1`
 
-**Category:** data | **Tags:** data, dashboard
+**Package:** `@htmlbricks/hb-dashboard-card1`  
+**Category:** data · **Tags:** data, dashboard
 
-### What it does
+## Purpose
 
-Bulma card shell for dashboards: JSON `header` supplies optional Bootstrap Icon name, title label, and right-aligned tag; JSON `body` can remove inner padding with `noborder`. Slots let you inject markup (`header_content`, `content`). Bootstrap Icons are loaded from the CDN in `svelte:head` for `bi` classes on the optional header icon.
+`hb-dashboard-card1` is a compact **Bulma card** layout for dashboards and admin shells. You configure the **header** (optional Bootstrap Icon, title, optional right-aligned tag) and **body** (optional removal of inner padding) via **JSON strings** on attributes. Use the **`header_content`** and **`content`** slots when you need full control over markup inside the card header and body regions.
 
-### Custom element
+The component applies Bulma’s **light theme** tokens on `:host` and loads **Bootstrap Icons** for the optional header icon (`bi-*` classes).
 
-`hb-dashboard-card1`
+---
 
-### Attributes / props (snake_case)
+## Registration and usage
 
-| Property | Type | Notes |
+Load your built script (or bundle) so the custom element is defined, then use the tag in HTML or in any framework that renders real DOM. Attribute names are **`snake_case`**. From HTML, **structured props are JSON strings** (see [Attributes](#attributes)).
+
+---
+
+## Custom element
+
+| Tag |
+| --- |
+| `hb-dashboard-card1` |
+
+---
+
+## Attributes
+
+All reflected / declarative inputs are **strings** at the DOM boundary (HTML `attributes` or `setAttribute`). Pass **objects as JSON**.
+
+| Attribute | Required | Description |
+| --- | --- | --- |
+| `id` | No | Passed through for identification / testing (host element `id`). |
+| `header` | No | JSON object describing the header row. If omitted, invalid, or empty after parse, the default header chrome still renders but **title and icon stay empty** unless you use the `header_content` slot. |
+| `body` | No | JSON object for body options. If omitted or invalid, defaults to `{ "noborder": false }`. |
+
+### `header` JSON shape
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `label` | string | Main title text (truncates with ellipsis when space is tight). |
+| `icon` | string | Optional Bootstrap Icons **glyph name only** (no `bi-` prefix), e.g. `"graph-up"`, `"bell"`. |
+| `badge` | string | Optional text for a Bulma **`tag`** on the right (status, delta, count). |
+
+Example:
+
+```json
+{ "label": "Revenue", "icon": "graph-up", "badge": "+12%" }
+```
+
+### `body` JSON shape
+
+| Field | Type | Description |
 | --- | --- | --- |
-| `id` | string (optional) | Element identifier. |
-| `style` | string (optional) | Inline style string. |
-| `header` | object (optional) | JSON `{ icon?: string; label: string; badge?: string }`. |
-| `body` | object (optional) | JSON `{ noborder?: boolean }`. |
+| `noborder` | boolean | When `true`, the main **`card-content`** area uses **no padding** (`p-0`), useful for charts or tables that should bleed to the card edges. |
 
-**Bulma `--bulma-*` theme vars** (see `extra/docs.ts`). **Parts:** `text_placeholder`, `badge`, `card`. **Slots:** `header_content`, `content`.
+Example:
 
-### Events (`CustomEvent` names)
+```json
+{ "noborder": true }
+```
+
+### Parsing behavior
+
+- **`header` and `body`** accept either a **string** (parsed with `JSON.parse`) or an object when set from JavaScript on the custom element’s property layer.
+- **Invalid JSON** or non-object values for `body` fall back to **`{ noborder: false }`**.
+- **Invalid or empty `header` JSON** yields **no parsed header**; the component does not throw.
+
+### `style` (TypeScript only)
+
+The authoring type `Component` includes an optional **`style`** field for wrappers and tooling. The current Svelte implementation does **not** destructure or apply that prop inside the component; use normal **host** `style` / CSS if you need outer layout tweaks.
+
+---
+
+## Slots
+
+Shadow slots let you replace the default fragments Bulma would otherwise own.
 
-None declared in types (`Events` is an empty object).
+| Slot | Default | When you use it |
+| --- | --- | --- |
+| `header_content` | Built-in **`card-header-title`** row: optional icon, `label`, optional `badge`. | Supplying **children with `slot="header_content"` replaces the entire default title row**. Use this for fully custom header markup. |
+| `content` | Empty (reserved for your body markup). | Main **`card-content`** area: charts, tables, metrics, etc. |
+
+---
+
+## Custom events
+
+None. The `Events` contract for this component is **empty**—there are no documented `CustomEvent` outputs from the host.
 
-### Styling (Bulma)
+---
 
-The component uses Bulma `card`, `card-header`, `card-header-title`, `card-content`, and `tag`. Theme defaults are applied on `:host` via Bulma’s light theme and `setup-theme`. Override card look with public `--bulma-*` properties (for example `--bulma-card-background-color`, `--bulma-card-shadow`, `--bulma-card-header-color`). Bootstrap Icons remain a separate stylesheet for `header.icon`.
+## Styling
 
-### Usage notes
+### Bulma CSS variables (`:host`)
 
-- `header.icon` should be a bootstrap-icons icon name string (without the `bi-` prefix).
-- Use `::part(card)` and related parts for host-level theming inside shadow root.
-- No i18n in `docs.ts`.
+Set **`--bulma-*`** variables on the host or an ancestor; they flow into the shadow tree with this component’s Bulma setup.
 
-### Minimal HTML example
+| Variable | Role |
+| --- | --- |
+| `--bulma-card-background-color` | Card panel background. |
+| `--bulma-card-shadow` | Elevation / shadow around the card. |
+| `--bulma-card-header-color` | Header title text color. |
+| `--bulma-text-strong` | Strong text context used with header styling. |
+
+Defaults and longer descriptions are listed in `extra/docs.ts` (`styleSetup.vars`) for catalog and design tools.
+
+### CSS parts
+
+| Part | Element | Use |
+| --- | --- | --- |
+| `card` | Root `.card` container | Host-level tweaks to the whole widget (radius, border, background overrides complementary to variables). |
+
+### Icons
+
+- **In-component icon:** `header.icon` uses classes `bi bi-{icon}`; names match [Bootstrap Icons](https://icons.getbootstrap.com/).
+- **Stylesheets:** Icons are loaded from a CDN in the component (`svelte:head`) and the shared stylesheet also references Bootstrap Icons for consistent font loading—integrators typically do not need to add another icon link unless they strip shadow assets.
+
+---
+
+## Markup structure (Bulma)
+
+The implementation uses Bulma **`card`**, **`card-header`**, **`card-header-title`**, **`card-content`**, and **`tag`**. Header layout uses flex helpers so long **labels truncate** and the **badge stays right-aligned**.
+
+---
+
+## Internationalization
+
+No built-in i18n strings; all visible text comes from your **`header`** JSON, slot content, or slotted children.
+
+---
+
+## Examples
+
+### Minimal header with icon and badge
 
 ```html
 <hb-dashboard-card1
   header='{"label":"Revenue","icon":"graph-up","badge":"+12%"}'
-  body='{"noborder":false}'
 ></hb-dashboard-card1>
 ```
+
+### Title only, padded body
+
+```html
+<hb-dashboard-card1 header='{"label":"Active users"}'></hb-dashboard-card1>
+```
+
+### Tight body for a chart or table
+
+```html
+<hb-dashboard-card1
+  header='{"label":"Metrics","icon":"graph-up","badge":"live"}'
+  body='{"noborder":true}'
+>
+  <div slot="content" style="height: 200px; background: linear-gradient(...)"></div>
+</hb-dashboard-card1>
+```
+
+### Custom header via slot
+
+Replacing the default row removes the built-in icon/label/badge layout; style slotted nodes from **your** stylesheet (shadow Bulma rules do not target slotted light DOM unless the component exposes `::slotted(...)` rules).
+
+```html
+<hb-dashboard-card1 body='{"noborder":true}'>
+  <div slot="header_content" style="display:flex;align-items:center;gap:0.5rem;width:100%;">
+    <strong>Custom</strong>
+    <span style="margin-left:auto;">meta</span>
+  </div>
+  <p slot="content">Body from slot.</p>
+</hb-dashboard-card1>
+```
+
+### JavaScript: set properties
+
+```js
+const el = document.querySelector("hb-dashboard-card1");
+el.header = { label: "Alerts", icon: "bell", badge: "3" };
+el.body = { noborder: false };
+```
+
+---
+
+## Files in this package (for contributors)
+
+| File | Role |
+| --- | --- |
+| `component.wc.svelte` | Custom element implementation |
+| `types/webcomponent.type.d.ts` | `Component` / `Events` authoring types |
+| `extra/docs.ts` | Catalog metadata, CSS vars, parts, slots, Storybook args |
+| `styles/bulma.scss` | Bulma modules + theme on `:host` |
+| `styles/webcomponent.scss` | Layout tweaks, icon import |

package/manifest.json

@@ -75,19 +75,19 @@
         "name": "--bulma-card-background-color",
         "valueType": "color",
         "defaultValue": "#ffffff",
-        "description": "Card surface."
+        "description": "Controls the visible card panel background so dashboard widgets match your shell while keeping inner content contrast clear for readers."
       },
       {
         "name": "--bulma-card-shadow",
         "valueType": "other",
         "defaultValue": "0 0.5em 1em -0.125em rgba(10, 10, 10, 0.1)",
-        "description": "Card elevation."
+        "description": "Defines the drop shadow around the whole card, letting you tune depth against flat dashboards or dense grids without editing shadow markup."
       },
       {
         "name": "--bulma-card-header-color",
         "valueType": "color",
         "defaultValue": "#363636",
-        "description": "Header title color."
+        "description": "Sets the header title ink color so the metric label stays legible when you customize the card background or embed it on dark sections."
       },
       {
         "name": "--bulma-text-strong",
@@ -99,23 +99,27 @@
     "parts": [
       {
         "name": "text_placeholder",
-        "description": "Text placeholder css div element part"
+        "description": "Header title text node wrapper; use for typography, truncation, or color without replacing the whole header slot."
       },
       {
         "name": "badge",
-        "description": "badge"
+        "description": "Right-aligned Bulma `tag` in the card header (e.g. status or delta); style pill colors from the host."
       },
       {
         "name": "card",
-        "description": "main container"
+        "description": "Root Bulma `card` element; use for elevation, border, or background on the whole widget."
       }
     ]
   },
   "contributors": [],
   "htmlSlots": [
+    {
+      "name": "header_content",
+      "description": "Optional markup between the icon/title row and the end of `card-header` (extra controls or meta)."
+    },
     {
       "name": "content",
-      "description": ""
+      "description": "Main `card-content` body; replaces or augments the default padded content area."
     }
   ],
   "i18n": [],
@@ -188,5 +192,5 @@
   "size": {},
   "iifePath": "main.iife.js",
   "repoName": "@htmlbricks/hb-dashboard-card1",
-  "version": "0.71.34"
+  "version": "0.71.36"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@htmlbricks/hb-dashboard-card1",
-  "version": "0.71.34",
+  "version": "0.71.36",
   "contributors": [],
   "description": "Bulma card shell for dashboards: JSON `header` supplies optional Bootstrap Icon name, title label, and right-aligned tag; JSON `body` can remove inner padding with `noborder`. Default slots `header_content` and `content` let you inject arbitrary markup between the standard header row and body.",
   "licenses": [