# `hb-dashboard-card1`

**Package:** `@htmlbricks/hb-dashboard-card1`  
**Category:** data · **Tags:** data, dashboard

## Purpose

`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.

The component applies Bulma’s **light theme** tokens on `:host` and loads **Bootstrap Icons** for the optional header icon (`bi-*` classes).

---

## Registration and usage

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 |
| --- | --- | --- |
| `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. |

Example:

```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.

| 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 CSS variables (`:host`)

Set **`--bulma-*`** variables on the host or an ancestor; they flow into the shadow tree with this component’s Bulma setup.

| 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%"}'
></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 |