@htmlbricks/hb-table 0.66.12 → 0.66.14

package/README.md

@@ -5,7 +5,9 @@
 
 ### What it does
 
-Bootstrap-striped data table driven by JSON `headers` and `rows` (`_id` required): column sort, header search (text, enum, date range), formatted values (nested keys, datetime via dayjs), copy-to-clipboard, row highlight and `selectrow` clicks. Global `actions` and per-row `_actions` can open confirm or schema dialogs (`hb-dialog` / `hb-dialogform`). Optional multi-select with `selectactions`, `add_item` slot, and `hb-paginate` for page size, sort sync, and server-style `externalfilter` / `total` workflows. i18n via `i18nlang`.
+Bootstrap-striped data table driven by JSON `headers` and `rows` (`_id` required): column sort, header search (text, enum, date range), formatted values (nested keys, datetime via dayjs), copy-to-clipboard, row highlight and `selectrow` clicks. Global `actions` and per-row `_actions` can open confirm or schema dialogs (`hb-dialog` / `hb-dialogform`). Optional multi-select with `selectactions`, `add_item` slot, and `hb-paginate` for page size, sort sync, and server-style `externalfilter` / `total` workflows.
+
+While **`is_loading`** is enabled, the tbody shows Bootstrap **placeholder** skeleton rows (count follows **`size`**, capped at 100), and the same flag is passed to **`hb-paginate`** so the pagination bar shows placeholders too. i18n via `i18nlang`.
 
 ### Custom element
 
@@ -16,13 +18,13 @@ Bootstrap-striped data table driven by JSON `headers` and `rows` (`_id` required
 - `id` (optional), `style` (optional): strings.
 - `rows` (required): JSON string — row objects with `_id` and column keys; optional `_actions`, `_evidenced`.
 - `headers` (required): JSON string — `ITableHeader[]` (`label`, `key`, optional `type`, `format`, `search`, `click`, `select`, `nosort`, `sortBy`, `truncateAt`, `copyTxt`, `tooltip`).
-- `actions` (optional): JSON string — global `IActionButton[]`.
-- `selectactions` (optional): JSON string.
+- `actions` (optional): JSON string — global row `IActionButton[]` (see **Actions** below).
+- `selectactions` (optional): JSON string — toolbar buttons when multi-select is enabled (different shape from `actions`; see **Multi-select**).
 - `selectrow`, `enableselect`, `selected` (optional): strings (selection mode / ids).
 - `size`, `page`, `pages`, `total` (optional): numbers as strings for pagination / server totals.
 - `externalfilter` (optional): boolean string — host-driven filters.
 - `disablepagination` (optional): boolean string.
-- `add_item` (optional): boolean string — show add row UI.
+- `add_item` (optional): boolean string — show the **Add** button (see **Add button** below).
 - `i18nlang` (optional): string (`it`, `en`, … per registered i18n).
 - `page_size_type` (optional): `"number"` | `"select"`.
 - `page_size_options` (optional): comma-separated sizes, e.g. `"10,25,50,100"`.
@@ -31,6 +33,53 @@ Bootstrap-striped data table driven by JSON `headers` and `rows` (`_id` required
 - `disable_paginate_sort` (optional): boolean string.
 - `sort_strict_direction` (optional): boolean string.
 - `sort_direction` (optional): string — current sort direction.
+- **`is_loading` (optional):** boolean string (`"yes"` / `"true"`) or boolean in frameworks — enables loading placeholders in the table body (row count = `size`) and forwards the same state to **`hb-paginate`**.
+
+### Actions (`actions` and `_actions`)
+
+Use **`actions`** for a column of buttons that is the same for every row (one set per row, same definitions). Use **`_actions`** on a single row object for buttons only on that row (e.g. variable actions per record). Both use the same **`IActionButton`** shape.
+
+| Field | Purpose |
+| --- | --- |
+| `name` | Stable id for the action; emitted in events as `action`. |
+| `type` | `"text"` — show `iconOrText` as label; `"icon"` — show a **Bootstrap Icon** (see below). |
+| `iconOrText` | For `type: "text"`, the visible label. For `type: "icon"`, the **icon name** as on [Bootstrap Icons](https://icons.getbootstrap.com/) **without** the `bi-` prefix (e.g. `pencil`, `trash3`, `github`). The component renders a `<i>` with class `bi-{iconOrText}` (e.g. `bi-pencil`). |
+| `btnClass` | Optional Bootstrap **button colour / style suffix** after `btn-`. Examples: `primary`, `secondary`, `success`, `danger`, `warning`, `info`, `light`, `dark`, `link`. If omitted, **text** buttons default to `link`, **icon** buttons default to `light`. The full class is `btn btn-{btnClass}`. |
+| `disabled` | If true, the control is disabled. |
+| `confirm` | If set, clicking opens **`hb-dialog`** confirm; on confirm the table emits `tableaction` / related confirm events. |
+| `edit` | If set (and no `confirm`), clicking opens **`hb-dialogform`** with the given `schema`. |
+| `tooltip` | Optional; passed to **`hb-tooltip`** for icon buttons. |
+
+**Behaviour without `confirm` / `edit`:** the table dispatches **`tableaction`** with `{ itemId, action }` where `action` is the button `name`. For **`_actions`** on a row, the same flow applies but the event **`tableCustomActionClick`** is also fired with `{ itemId, action }` so you can distinguish custom per-row actions if needed.
+
+**Icons:** load Bootstrap Icons CSS in the host page (the component already injects the icons stylesheet in the light DOM head for tooltips; for consistent icon font inside the shadow tree, ensure Bootstrap Icons are available). Icon names must match the Bootstrap Icons set.
+
+### Multi-select (`enableselect`, `selectactions`)
+
+- Set **`enableselect`** to `"yes"` / `"true"` and pass **`selectactions`**: an array of `{ name, type, iconOrText }` used for bulk actions on checked rows. **`actiononselected`** fires with `{ key: name, selectedItems }`.
+- Row checkboxes appear only when **`selectactions`** has entries.
+
+### Add button (`add_item`)
+
+Set **`add_item`** to `"yes"` / `"true"` (or boolean `true` in frameworks) to show a primary **Add** control in the toolbar below the table (same **`nav`** as pagination — `part="table-actions"`). It is meant to let the user start creating a **new row**; the table does not insert data by itself.
+
+- **Visibility:** the button is rendered only when **`enableselect`** is *not* active (multi-select gear mode hides it).
+- **Click:** dispatches the **`addItem`** custom event with payload **`{ id }`**, where **`id`** is the table’s own **`id`** attribute (empty string if unset). The host should listen for `addItem` and open a form, navigate to a create page, call an API, etc.
+- **Label / icon:** default content is a Bootstrap **plus** icon (`bi-plus`). Override with the **`add-button-content`** slot if you need text or a different icon.
+
+```html
+<hb-table
+  id="my-list"
+  add_item="yes"
+  headers='[{"label":"Title","key":"title"}]'
+  rows='[{"_id":"1","title":"A"}]'
+></hb-table>
+<script>
+  document.querySelector("hb-table").addEventListener("addItem", (e) => {
+    console.log("Create new item for table:", e.detail.id); // "my-list"
+  });
+</script>
+```
 
 ### Events
 
@@ -46,14 +95,15 @@ Bootstrap-striped data table driven by JSON `headers` and `rows` (`_id` required
 - `showConfirmModal` / `showConfirmModalForm`: modal visibility payloads with `action` and `detail: { id; show }`.
 - `confirmActionModal` / `confirmActionModalForm`: `{ action; id; confirm }`.
 - `clipboardCopyText`: `{ text: string }`.
-- `addItem`: `{ id: string }`.
+- **`addItem`:** `{ id: string }` — fired when the **Add** button is clicked; `id` is the table `id` attribute (see **Add button**).
 
 ### Usage notes
 
-- **Slots:** `add-button-content`, `buttons-container`.
+- **Slots:** `add-button-content` (Add button body), `buttons-container` (extra toolbar content).
 - **CSS parts:** `table`, `table-actions`, `selected-row`, `common-row`.
-- **i18n:** italian and english in docs metadata; set `i18nlang` accordingly.
-- Pair with `hb-paginate` / dialogs as in Storybook examples in `extra/docs.ts`.
+- **i18n:** Italian and English in docs metadata; set `i18nlang` accordingly.
+- **`hb-paginate`:** embedded when pagination is enabled; receives **`is_loading`** automatically when the table is loading.
+- See `extra/docs.ts` for Storybook-style examples.
 
 ### Minimal HTML example
 
@@ -65,3 +115,32 @@ Bootstrap-striped data table driven by JSON `headers` and `rows` (`_id` required
   pages="1"
 ></hb-table>
 ```
+
+### Loading example
+
+```html
+<hb-table
+  is_loading="yes"
+  size="10"
+  headers='[{"label":"Title","key":"title"}]'
+  rows='[]'
+  total="0"
+  page="0"
+  pages="0"
+></hb-table>
+```
+
+### Actions example (global column + Bootstrap icon)
+
+```html
+<hb-table
+  headers='[{"label":"Name","key":"name"},{"label":"Tools","key":"tools","type":"actions","nosort":true}]'
+  rows='[{"_id":"1","name":"Alice"}]'
+  actions='[
+    {"name":"edit","type":"icon","iconOrText":"pencil","btnClass":"primary"},
+    {"name":"delete","type":"icon","iconOrText":"trash","btnClass":"danger"}
+  ]'
+></hb-table>
+```
+
+Listen for `tableaction` to handle `edit` / `delete` by `event.detail.itemId` and `event.detail.action`.