@htmlbricks/hb-messages-topics-card 0.71.35 → 0.71.37

package/README.md

@@ -1,49 +1,137 @@
-# hb-messages-topics-card
+# `hb-messages-topics-card`
+
+**Category:** messaging · **Tags:** messaging, chat · **Package:** `@htmlbricks/hb-messages-topics-card`
 
 ## Description
 
-Lists chat or channel previews from `chats`: avatar, title, last message snippet, derived time label, and unread `counter` as a Bulma tag. Clicking a row marks it selected (`_selected`) and dispatches `select` with that chat payload for opening a thread or switching context.
+Renders a vertical list of chat or channel previews from a **`chats`** collection. Each row shows a rounded avatar, a title, a short message preview, a time label, and an unread counter rendered as a Bulma tag. Clicking a row updates internal selection state (`_selected`), highlights the row, and dispatches a **`select`** custom event with the clicked chat object so the host can open a thread or switch context.
 
 ## Styling (Bulma)
 
-The component bundles **Bulma 1.x** in the shadow root: **`elements/tag`** (unread counter), with theme defaults on `:host` (`--bulma-hb-def-*`). Set public **`--bulma-*`** on `body` or `:root` so they inherit onto the host. Row hover and selected backgrounds default from **`--bulma-scheme-main-bis`** and **`--bulma-scheme-main-ter`**; override with **`--hb-topics-card-hover-background-color`** and **`--hb-topics-card-selected-background-color`** if needed. See [Bulma CSS variables](https://bulma.io/documentation/features/css-variables/).
+The component bundles **Bulma 1.x** inside the shadow root: **`layout/media`**, **`layout/level`**, **`elements/image`**, **`elements/tag`**, and typography / spacing helpers, with the light theme applied on `:host`. Public **`--bulma-*`** variables can be set on `body`, `:root`, or the host so they cascade consistently with the rest of the app — see [Bulma CSS variables](https://bulma.io/documentation/features/css-variables/) and the `styleSetup.vars` entries in `extra/docs.ts`.
+
+| Variable | Purpose |
+|----------|---------|
+| `--bulma-text` | Title and preview snippet text. |
+| `--bulma-text-strong` | Strong title weight color (falls back to `--bulma-text`). |
+| `--bulma-text-weak` | Muted time label beside each preview. |
+| `--bulma-border` | Divider between rows. |
+| `--bulma-scheme-main-bis` | Hover background for rows that are not selected. |
+| `--bulma-scheme-main-ter` | Selected row background. |
+| `--bulma-radius-rounded` | Pill shape for the unread counter tag. |
 
 **Shadow markup (simplified):**
 
-- **`div.grid`** — one row per chat (click selects).
-- **`img`**, **`div.header`** (title + time), **`div.details`** (snippet + **`span.tag.is-light.is-rounded`** counter).
+- **`article.media.hb-topics-item`** — clickable row; **`hb-topics-item--selected`** when that chat is selected.
+- **`figure.media-left`** + **`p.image.is-64x64`** + **`img.is-rounded`** — avatar from `img_uri`.
+- **`div.media-content`** — Bulma **`level`** rows for title + time, then preview + counter tag.
+
+## CSS parts
+
+None.
+
+## HTML slots
+
+None.
+
+## Custom element
+
+`hb-messages-topics-card`
+
+## Attributes (snake_case; string values in HTML)
+
+Per the web component contract, attributes are strings. The primary payload is JSON on **`chats`**.
+
+| Attribute | Required | Description |
+|-----------|----------|-------------|
+| `id` | No | Optional host identifier. |
+| `style` | No | Optional inline host styles (typed on the component surface). |
+| `chats` | No* | JSON string: array of chat objects (`IChat[]`). Defaults to an empty list if omitted. |
+
+\* In markup you may omit **`chats`** until you set the attribute; the component defaults to an empty list.
+
+### `chats` JSON shape (`IChat`)
+
+Fields used for layout and labels in the current implementation:
+
+| Field | Role |
+|-------|------|
+| `chat_id` | Stable key for each row (also used in `{#each}` keyed updates). |
+| `title` | Primary line (semibold). |
+| `text` | Preview line under the title. |
+| `img_uri` | Avatar URL (`img` `src`). |
+| `time` | Source for the time label when `localeTimeString` is not set; use an **ISO 8601** string in JSON so it parses as a date. |
+| `localeTimeString` | If set, shown as-is instead of deriving `HH:MM` from `time`. |
+| `counter` | Unread count; rendered in the tag (missing or falsy shows **`0`**). |
+| `_selected` | When `true`, that row starts selected and receives the selected background. |
 
-**Host-level tokens (existing):** `--hb-topics-card-size`, `--hb-topics-card-padding`, derived `--hb-topics-card-double-*`, plus the selected/hover background variables above.
+Additional optional fields (`is_group`, `chat_name`, `chat_img`, `last_message_*`, and so on) are part of the **`IChat`** type so you can carry richer metadata; they are not read by the template today but are still present on objects emitted by **`select`**.
+
+If the **`chats`** prop arrives as a string (for example from an HTML attribute), the component parses it with **`JSON.parse`**; invalid JSON is logged to the console and parsing is skipped.
+
+## Events
+
+| Event | `detail` |
+|-------|----------|
+| `select` | The clicked **`IChat`** object (same reference the list uses after selection is updated). |
+
+Listen in plain JavaScript:
+
+```javascript
+const el = document.querySelector("hb-messages-topics-card");
+el.addEventListener("select", (e) => {
+  const chat = e.detail;
+  console.log(chat.chat_id, chat.title);
+});
+```
+
+## Usage notes
+
+- **Initial selection:** set **`_selected`** on at most one item in the JSON if you want a default active row.
+- **Time display:** without **`localeTimeString`**, the component fills it from **`time`** using the **local** hours and minutes (`HH:MM`). Provide **`localeTimeString`** yourself for relative times or locale-specific formatting.
+- **Unread badge:** the tag always shows a value; **`0`** is shown when there is no positive counter.
+- **Avatars:** the template sets **`alt=""`** on images; if you need accessible names, extend your integration (for example wrapping context or contributing upstream) because the component does not derive labels from `title` today.
 
 ## Types
 
 ```typescript
 export type IChat = {
-	time: Date;
-	title: string;
-	text: string;
-	img_uri: string;
-	is_group?: boolean;
-	chat_name?: string;
-	chat_img?: string;
-	chat_id: string;
-	last_message_author?: string;
-	last_message_author_img?: string;
-	last_message_time?: Date;
-	last_message_text?: string;
-	counter?: number;
-	localeTimeString?: string;
-	_selected?: boolean;
+  time: Date;
+  title: string;
+  text: string;
+  img_uri: string;
+  is_group?: boolean;
+  chat_name?: string;
+  chat_img?: string;
+  chat_id: string;
+  last_message_author?: string;
+  last_message_author_img?: string;
+  last_message_time?: Date;
+  last_message_text?: string;
+  counter?: number;
+  localeTimeString?: string;
+  _selected?: boolean;
 };
 
 export type Component = {
-	id?: string;
-	style?: string;
-
-	chats: IChat[];
+  id?: string;
+  style?: string;
+  chats?: IChat[];
 };
 
 export type Events = {
-	select: IChat;
+  select: IChat;
 };
 ```
+
+## Minimal HTML example
+
+```html
+<hb-messages-topics-card
+  chats='[{"chat_id":"1","title":"Team","text":"Hello","time":"2026-01-01T12:00:00.000Z","img_uri":"https://example.com/a.png","counter":2}]'
+></hb-messages-topics-card>
+```
+
+## Storybook / metadata
+
+Argument controls and additional named examples (selected row, unread badges, single chat) live in `extra/docs.ts`.

package/manifest.json

@@ -86,6 +86,7 @@
           "additionalProperties": false,
           "properties": {
             "chats": {
+              "description": "Parsed from a JSON attribute when omitted in HTML.",
               "items": {
                 "$ref": "#/definitions/IChat"
               },
@@ -98,9 +99,6 @@
               "type": "string"
             }
           },
-          "required": [
-            "chats"
-          ],
           "type": "object"
         },
         "IChat": {
@@ -183,67 +181,43 @@
         "name": "--bulma-text",
         "valueType": "color",
         "defaultValue": "#363636",
-        "description": "Body and description text."
+        "description": "Title and preview snippet text."
       },
       {
         "name": "--bulma-text-strong",
         "valueType": "color",
         "defaultValue": "#363636",
-        "description": "Title emphasis (falls back to `--bulma-text`)."
+        "description": "Strong title weight color (falls back to `--bulma-text`)."
       },
       {
         "name": "--bulma-text-weak",
         "valueType": "color",
         "defaultValue": "#7a7a7a",
-        "description": "Muted time label."
+        "description": "Muted foreground for the timestamp or relative time shown beside each chat preview."
+      },
+      {
+        "name": "--bulma-border",
+        "valueType": "color",
+        "defaultValue": "#dbdbdb",
+        "description": "Row divider between chat previews."
       },
       {
         "name": "--bulma-scheme-main-bis",
         "valueType": "color",
-        "defaultValue": "hsl(0, 0%, 98%)",
-        "description": "Hover row background (default for `--hb-topics-card-hover-background-color`)."
+        "defaultValue": "#fafafa",
+        "description": "Hover background for non-selected rows."
       },
       {
         "name": "--bulma-scheme-main-ter",
         "valueType": "color",
-        "defaultValue": "hsl(0, 0%, 96%)",
-        "description": "Selected row background (default for `--hb-topics-card-selected-background-color`)."
+        "defaultValue": "#f5f5f5",
+        "description": "Selected row background."
       },
       {
         "name": "--bulma-radius-rounded",
         "valueType": "number",
         "defaultValue": "9999px",
         "description": "Pill shape for the unread counter tag."
-      },
-      {
-        "name": "--hb-topics-card-double-padding",
-        "valueType": "string",
-        "defaultValue": ""
-      },
-      {
-        "name": "--hb-topics-card-double-size",
-        "valueType": "number",
-        "defaultValue": ""
-      },
-      {
-        "name": "--hb-topics-card-hover-background-color",
-        "valueType": "color",
-        "defaultValue": ""
-      },
-      {
-        "name": "--hb-topics-card-padding",
-        "valueType": "string",
-        "defaultValue": ""
-      },
-      {
-        "name": "--hb-topics-card-selected-background-color",
-        "valueType": "color",
-        "defaultValue": ""
-      },
-      {
-        "name": "--hb-topics-card-size",
-        "valueType": "number",
-        "defaultValue": ""
       }
     ],
     "parts": []
@@ -261,7 +235,7 @@
             "counter": 0,
             "text": "Hello 0",
             "title": "Hello0",
-            "time": "2026-04-16T23:22:53.482Z",
+            "time": "2026-04-17T00:28:42.015Z",
             "img_uri": "https://www.w3schools.com/howto/img_avatar.png"
           },
           {
@@ -269,7 +243,7 @@
             "counter": 0,
             "text": "Hello 1",
             "title": "Hello1",
-            "time": "2026-04-16T23:22:53.482Z",
+            "time": "2026-04-17T00:28:42.015Z",
             "img_uri": "https://www.w3schools.com/howto/img_avatar.png"
           },
           {
@@ -277,7 +251,7 @@
             "counter": 0,
             "text": "Hello 2",
             "title": "Hello2",
-            "time": "2026-04-16T23:22:53.482Z",
+            "time": "2026-04-17T00:28:42.015Z",
             "img_uri": "https://www.w3schools.com/howto/img_avatar.png"
           }
         ]
@@ -292,7 +266,7 @@
             "counter": 0,
             "text": "Hello 0",
             "title": "Hello0",
-            "time": "2026-04-16T23:22:53.482Z",
+            "time": "2026-04-17T00:28:42.015Z",
             "img_uri": "https://www.w3schools.com/howto/img_avatar.png"
           },
           {
@@ -300,7 +274,7 @@
             "counter": 0,
             "text": "Hello 1",
             "title": "Hello1",
-            "time": "2026-04-16T23:22:53.482Z",
+            "time": "2026-04-17T00:28:42.015Z",
             "img_uri": "https://www.w3schools.com/howto/img_avatar.png",
             "_selected": true
           },
@@ -309,7 +283,7 @@
             "counter": 0,
             "text": "Hello 2",
             "title": "Hello2",
-            "time": "2026-04-16T23:22:53.482Z",
+            "time": "2026-04-17T00:28:42.015Z",
             "img_uri": "https://www.w3schools.com/howto/img_avatar.png"
           }
         ]
@@ -325,7 +299,7 @@
             "counter": 3,
             "text": "Can you review the PR?",
             "title": "Engineering",
-            "time": "2026-04-16T23:22:53.482Z",
+            "time": "2026-04-17T00:28:42.015Z",
             "img_uri": "https://www.w3schools.com/howto/img_avatar.png"
           },
           {
@@ -333,7 +307,7 @@
             "counter": 12,
             "text": "Contract signed",
             "title": "Sales",
-            "time": "2026-04-16T23:22:53.482Z",
+            "time": "2026-04-17T00:28:42.015Z",
             "img_uri": "https://www.w3schools.com/howto/img_avatar.png"
           },
           {
@@ -341,7 +315,7 @@
             "counter": 1,
             "text": "Ticket #4421 updated",
             "title": "Support",
-            "time": "2026-04-16T23:22:53.482Z",
+            "time": "2026-04-17T00:28:42.015Z",
             "img_uri": "https://www.w3schools.com/howto/img_avatar.png"
           }
         ]
@@ -357,7 +331,7 @@
             "counter": 0,
             "text": "Only conversation in the list",
             "title": "Direct message",
-            "time": "2026-04-16T23:22:53.482Z",
+            "time": "2026-04-17T00:28:42.015Z",
             "img_uri": "https://www.w3schools.com/howto/img_avatar.png",
             "_selected": true
           }
@@ -386,5 +360,5 @@
   "size": {},
   "iifePath": "main.iife.js",
   "repoName": "@htmlbricks/hb-messages-topics-card",
-  "version": "0.71.35"
+  "version": "0.71.37"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@htmlbricks/hb-messages-topics-card",
-  "version": "0.71.35",
+  "version": "0.71.37",
   "contributors": [],
   "description": "Lists chat or channel previews from `chats`: avatar, title, last message snippet, derived time label, and unread `counter` badge. Clicking a row marks it selected (`_selected`) and dispatches `select` with that chat payload for opening a thread or switching context.",
   "licenses": [

package/types/webcomponent.type.d.json

@@ -6,6 +6,7 @@
       "additionalProperties": false,
       "properties": {
         "chats": {
+          "description": "Parsed from a JSON attribute when omitted in HTML.",
           "items": {
             "$ref": "#/definitions/IChat"
           },
@@ -18,9 +19,6 @@
           "type": "string"
         }
       },
-      "required": [
-        "chats"
-      ],
       "type": "object"
     },
     "IChat": {

package/types/webcomponent.type.d.ts

@@ -19,8 +19,8 @@ export type IChat = {
 export type Component = {
 	id?: string;
 	style?: string;
-
-	chats: IChat[];
+	/** Parsed from a JSON attribute when omitted in HTML. */
+	chats?: IChat[];
 };
 
 export type Events = {