@htmlbricks/hb-paragraps-around-image-cell 0.71.35 → 0.71.37

package/README.md

@@ -1,37 +1,115 @@
-## `hb-paragraps-around-image-cell` — paragraph cell around image
+# `hb-paragraps-around-image-cell` — integrator guide
 
-**Category:** content  
-**Tags:** content
+**Category:** content · **Tags:** content · **Package:** `@htmlbricks/hb-paragraps-around-image-cell`
 
-### What it does
+## Summary
 
-One paragraph tile with Bootstrap icon, optional title as external link or key-triggered control (dispatches `paragraphPressed` with `key`), and body text clamped to `max_lines` for consistent height inside `hb-paragraps-around-image` layouts.
+`hb-paragraps-around-image-cell` renders a single content tile: a Bootstrap icon, an optional title row (plain text, external link, or interactive control), and a body paragraph whose height is limited by a line clamp so tiles stay visually consistent in multi-column layouts. It is designed to sit inside `hb-paragraps-around-image` (the parent “paragraphs around image” layout) but can be used on its own wherever you need a compact icon + text block.
 
-### Custom element
+## Custom element
 
-`hb-paragraps-around-image-cell`
+```html
+<hb-paragraps-around-image-cell></hb-paragraps-around-image-cell>
+```
+
+## Attributes (snake_case, string values from HTML)
+
+Web component attributes are always strings. Pass structured data as JSON on `paragraph`, and numeric limits as their string form (for example `"8"`).
+
+| Attribute | Required | Description |
+|-----------|----------|-------------|
+| `paragraph` | No | JSON string (or object from JS) describing the tile. Parsed in the component; missing or invalid values may not render. |
+| `max_lines` | No | Maximum number of lines for the body text clamp. Coerced to a number internally; default **8** if omitted. |
+| `id` | No | Optional host `id` (standard HTML). |
+
+The authoring TypeScript `Component` type also lists an optional `style` field; the current implementation does not wire a `style` prop into the markup, so prefer styling the host from the light DOM (selectors on the custom element) or Bulma variables below.
+
+### `paragraph` object shape
+
+The `paragraph` value matches the shared `Paragraphs` type (same family as the parent `hb-paragraps-around-image` items):
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `text` | string | Body copy (required). |
+| `title` | string (optional) | Heading row above the body. If omitted, only the icon and body are shown. |
+| `icon` | string (optional) | Bootstrap Icons **name without** the `bi-` prefix (the template uses `class="bi bi-{icon}"`). |
+| `link` | string (optional) | If set together with `title`, the title is rendered as an external link (`target="_blank"`) using link styling. |
+| `key` | string (optional) | If `title` is set and `link` is **not**, and `key` **is** set, the title row becomes an underlined, clickable control. A click dispatches `paragraphPressed` with this `key` in the event detail. |
+
+**Title row rules (in order):**
+
+1. `link` present → title is a normal anchor to `link`.
+2. Else `key` present → title is clickable and emits `paragraphPressed`.
+3. Else → title is plain bold text.
+
+If `paragraph` is missing or not an object after parsing, the component logs a warning and renders nothing.
+
+## Events
+
+Listen for the following custom event on the element (or on a parent in the bubbling phase):
+
+| Event | `detail` | When |
+|-------|-----------|------|
+| `paragraphPressed` | `{ key: string }` | User activates the title control when `paragraph.key` is set (and `paragraph.link` is not). |
+
+## Styling
+
+### Bulma CSS variables
+
+The host uses the shared Bulma web-component theme. From the light DOM you can override Bulma variables on `:host` or ancestors; see [Bulma CSS variables](https://bulma.io/documentation/features/css-variables/).
+
+| Variable | Role |
+|----------|------|
+| `--bulma-text` | Body and non-link titles. |
+| `--bulma-link` | Linked title (`paragraph.link`). |
+| `--bulma-text-strong` | Bold title row. |
+| `--bulma-block-spacing` | Vertical rhythm when nested in parent column layouts. |
 
-### Attributes (snake_case; use string values in HTML)
+### Icons
 
-- `id`, `style` (optional): strings.
-- `paragraph` (required): JSON string — `{ text; title?; icon?; link?; key? }`.
-- `max_lines` (optional): number as string — line clamp for body text.
+Bootstrap Icons are loaded for this component (font CSS). Ensure `paragraph.icon` matches an icon name from the Bootstrap Icons set.
 
-### Events
+### Layout notes
 
-- `paragraphPressed`: `{ key: string }`.
+The inner layout uses fixed inline flex/spacing for the icon column and text column. `:host` is `display: block`. There are **no** exposed `::part()` hooks and **no** slots.
 
-### Usage notes
+## Examples
 
-- **Slots:** none.
-- **CSS parts:** `testpart`.
-- Typically embedded by `hb-paragraps-around-image`; usable alone for Storybook-style tiles (no separate image prop on this cell).
+### Clickable title (dispatches `paragraphPressed`)
 
-### Minimal HTML example
+```html
+<hb-paragraps-around-image-cell
+  paragraph='{"text":"Supporting copy for this section.","title":"Open details","icon":"globe","key":"section-1"}'
+  max_lines="6"
+></hb-paragraps-around-image-cell>
+```
+
+### Title as external link
 
 ```html
 <hb-paragraps-around-image-cell
-  paragraph='{"text":"Body copy","title":"Read more","icon":"globe","key":"section-1"}'
+  paragraph='{"text":"Short intro text.","title":"Read documentation","icon":"box-arrow-up-right","link":"https://bulma.io/documentation/"}'
   max_lines="4"
 ></hb-paragraps-around-image-cell>
 ```
+
+### Body only (no title)
+
+```html
+<hb-paragraps-around-image-cell
+  paragraph='{"text":"Sidebar note or caption without a heading row.","icon":"info-circle"}'
+></hb-paragraps-around-image-cell>
+```
+
+### Default clamp (omit `max_lines` → eight lines)
+
+```html
+<hb-paragraps-around-image-cell
+  paragraph='{"text":"Long body …","title":"Title","icon":"text-paragraph","key":"block-a"}'
+></hb-paragraps-around-image-cell>
+```
+
+## Related
+
+- Parent layout: `hb-paragraps-around-image` (grid of cells + central image).
+- Package name in metadata: `@htmlbricks/hb-paragraps-around-image-cell`.

package/manifest.json

@@ -41,15 +41,19 @@
               "type": "number"
             },
             "paragraph": {
-              "$ref": "#/definitions/Paragraphs"
+              "anyOf": [
+                {
+                  "$ref": "#/definitions/Paragraphs"
+                },
+                {
+                  "type": "string"
+                }
+              ]
             },
             "style": {
               "type": "string"
             }
           },
-          "required": [
-            "paragraph"
-          ],
           "type": "object"
         },
         "Paragraphs": {
@@ -98,22 +102,31 @@
   "styleSetup": {
     "vars": [
       {
-        "name": "--lh",
-        "valueType": "string",
-        "defaultValue": ""
+        "name": "--bulma-text",
+        "valueType": "color",
+        "defaultValue": "#363636",
+        "description": "Body copy and non-link titles."
       },
       {
-        "name": "--max-lines",
-        "valueType": "string",
-        "defaultValue": ""
-      }
-    ],
-    "parts": [
+        "name": "--bulma-link",
+        "valueType": "color",
+        "defaultValue": "#485fc7",
+        "description": "External title links (`paragraph.link`)."
+      },
       {
-        "name": "testpart",
-        "description": "test css part on 2 div tag"
+        "name": "--bulma-text-strong",
+        "valueType": "color",
+        "defaultValue": "#363636",
+        "description": "Bold title row when distinguished from body text."
+      },
+      {
+        "name": "--bulma-block-spacing",
+        "valueType": "number",
+        "defaultValue": "1.5rem",
+        "description": "Vertical rhythm with parent `hb-paragraps-around-image` columns."
       }
-    ]
+    ],
+    "parts": []
   },
   "contributors": [],
   "htmlSlots": [],
@@ -199,5 +212,5 @@
   "size": {},
   "iifePath": "main.iife.js",
   "repoName": "@htmlbricks/hb-paragraps-around-image-cell",
-  "version": "0.71.35"
+  "version": "0.71.37"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@htmlbricks/hb-paragraps-around-image-cell",
-  "version": "0.71.35",
+  "version": "0.71.37",
   "contributors": [],
   "description": "One paragraph tile with Bootstrap icon, optional title as external link or key-triggered control (dispatches paragraphPressed with key), and body text clamped to max_lines for consistent height inside paragraps-around-image layouts.",
   "licenses": [

package/types/webcomponent.type.d.json

@@ -12,15 +12,19 @@
           "type": "number"
         },
         "paragraph": {
-          "$ref": "#/definitions/Paragraphs"
+          "anyOf": [
+            {
+              "$ref": "#/definitions/Paragraphs"
+            },
+            {
+              "type": "string"
+            }
+          ]
         },
         "style": {
           "type": "string"
         }
       },
-      "required": [
-        "paragraph"
-      ],
       "type": "object"
     },
     "Paragraphs": {

package/types/webcomponent.type.d.ts

@@ -1,7 +1,7 @@
 import type { Paragraphs } from "../../paragraps-around-image/types/webcomponent.type";
 
 export type Component = {
-  paragraph: Paragraphs;
+  paragraph?: Paragraphs | string;
   id?: string;
   style?: string;
   max_lines?: number;