@htmlbricks/hb-site-paragraph-with-image 0.71.34 → 0.71.36

package/README.md

@@ -1,39 +1,127 @@
-## `hb-site-paragraph-with-image` — site-paragraph-with-image
+# hb-site-paragraph-with-image
 
-**Category:** content  
-**Tags:** content
+**Package:** `@htmlbricks/hb-site-paragraph-with-image` · **Custom element:** `hb-site-paragraph-with-image`  
+**Category:** content · **Tags:** content
 
-### What it does
+## Description
 
-Marketing block pairing an image (`img`: `src`, optional `alt`) with rich text (`text`: optional `title`, `body`, optional `link` with `label` and optional `src`, `key`, colors). Use `text_side` (`left` / `right`) and `half_space` for layout; CSS parts cover mobile and desktop. CTA uses a **Bulma** `button is-primary` (custom link colors still applied inline). Fires `elClick` when the link is activated.
+A marketing-style content block that pairs a hero **image** with **title**, **body**, and an optional **call-to-action** button. Layout switches between a stacked **mobile** presentation and a side-by-side **wide** row based on the host viewport width. Styling is **Bulma 1.x** inside the shadow root (section spacing, typography, and a primary `button` for the CTA).
 
-### Custom element
+## Layout and breakpoints
 
-`hb-site-paragraph-with-image`
+- **Narrow layout** (when the window inner width is **under 800px**): copy appears first (when `text.title` or `text.body` is present), then the image. Each region exposes dedicated `::part` names prefixed with `mobile_`.
+- **Wide layout** (**800px and wider**): a horizontal flex row places the **image** and **text** columns according to **`text_side`**:
+  - **`text_side="right"`** (default): image column first, text column second.
+  - **`text_side="left"`**: text column first, image column second.
+- Any value other than **`left`** is treated as **`right`** (including empty or unknown strings after normalization).
+- **`half_space`**: on wide layouts, the **image** column uses **`flex-grow: 5`** when `half_space` is enabled, and **`flex-grow: 2`** when it is disabled, so you can bias how much horizontal space the image takes relative to the text column.
 
-### Attributes (snake_case; use string values in HTML)
+If neither `text.title` nor `text.body` is set, the component shows a plain **“no title or body”** placeholder in the text area. If `img.src` is missing, it shows **“no img”** in the image area.
 
-- `id` (optional), `style` (optional): strings.
-- `img` (required): JSON string — `{ src: string; alt?: string }`.
-- `text` (required): JSON string — `{ title?, body?, link?: { label; src?; key?; bgColor?; textColor? } }`.
-- `text_side` (optional): `"left"` | `"right"`.
-- `half_space` (optional): boolean as string when used from HTML.
+## Props and attributes
 
-### Events
+Attributes use **snake_case**. From HTML, pass **strings**; nested structures use **JSON strings** (see project conventions: booleans as **`yes`** / **`no`** where applicable).
 
-- `elClick`: `{ key: string }`.
+| Attribute | Required | Description |
+|-----------|----------|-------------|
+| `img` | Yes | JSON object: **`{ "src": string, "alt"?: string }`**. `src` is the image URL. `alt` is passed to the `<img>` when present. |
+| `text` | Yes | JSON object: optional **`title`**, **`body`**, and optional **`link`** (see [Link object](#link-object)). At least one of `title` or `body` should be set for meaningful copy. |
+| `text_side` | No | **`"left"`** or **`"right"`**. Controls column order on wide layouts. Defaults to **`right`**. |
+| `half_space` | No | Wider image column when truthy. From attributes, the implementation treats the string **`"yes"`**, the string **`"true"`**, or boolean **`true`** (after coercion) as enabled. Prefer **`yes`** / **`no`** for HTML consistency with other web components in this library. |
+| `id` | No | Optional identifier (typed on the component; reserved for host integration). |
+| `style` | No | Optional inline host style (present on the TypeScript `Component` type; not applied by the current Svelte implementation). |
 
-### Usage notes
+The component parses **`img`** and **`text`** when they arrive as strings (typical from HTML attributes) via `JSON.parse` inside an effect.
 
-- **CSS parts:** `mobile_text_content`, `mobile_title`, `mobile_text_body`, `mobile_link_button`, `mobile_image_content`, `image_content`, `text_content`, `link_button`, `title`, `text_body`.
-- No `htmlSlots` in docs; structure is prop-driven.
+### `img` object
 
-### Minimal HTML example
+| Field | Required | Description |
+|-------|----------|-------------|
+| `src` | Yes | Image URL used for the `<img>` element. |
+| `alt` | No | Alternate text for the image. |
+
+### `text` object
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `title` | string | Optional main heading (rendered as **`h1`** in both layouts). |
+| `body` | string | Optional body copy (single **`<p>`**). |
+| `link` | object | Optional CTA; see [Link object](#link-object). |
+
+### Link object
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `label` | Yes (for a visible button) | Button label. A Bulma **`button is-primary`** is rendered only when `label` is set. |
+| `key` | No | Logical key forwarded in **`elClick`** when the button is activated (see [Events](#events)). |
+| `src` | No | Reserved in the type definition for host apps; **this component does not navigate** or open URLs from `src` automatically. |
+| `bgColor` | No | When set, applied inline as **background** and **border** color on the CTA. |
+| `textColor` | No | When set, applied inline as **text** color on the CTA. |
+
+## Events
+
+Listen with `addEventListener` or your framework’s event binding.
+
+| Event | `detail` | When it fires |
+|-------|----------|----------------|
+| `elClick` | `{ key: string }` | When the user activates the CTA **and** `text.link.key` is defined. The `detail.key` matches `text.link.key`. |
+
+If the user clicks the CTA but **`text.link.key`** is missing, the handler logs a console warning (**`"no key"`**) and **does not** dispatch `elClick`. To receive clicks, always set a **`key`** on `text.link` when you rely on this event.
+
+## Styling (Bulma CSS variables)
+
+The shadow tree uses **Bulma 1.x** and shared host baseline styles. Theme the block from the light DOM by setting **`--bulma-*`** variables so they inherit onto the custom element. Documented overrides (from component metadata):
+
+| Variable | Role |
+|----------|------|
+| `--bulma-section-padding` | Feeds internal **`--hb-spiw-pad`** for host padding and text column insets (see `styles/webcomponent.scss`). |
+| `--bulma-primary` | Primary CTA styling for **`button is-primary`** when a link is present. |
+| `--bulma-text` | Title and body copy color. |
+| `--bulma-text-strong` | Strong heading / emphasis tone where Bulma maps it. |
+
+The host also uses **`min-height: 21.875rem`** and **`display: block`** so the section keeps a stable footprint in page layouts.
+
+## CSS `::part`
+
+Use these part names to style inner surfaces without piercing the shadow root arbitrarily.
+
+| Part | Description |
+|------|-------------|
+| `mobile_text_content` | Mobile column wrapping title, body, and CTA. |
+| `mobile_title` | Mobile headline (`h1`). |
+| `mobile_text_body` | Mobile body paragraph. |
+| `mobile_link_button` | Mobile primary CTA button. |
+| `mobile_image_content` | Mobile figure wrapper around the image. |
+| `image_content` | Wide-layout image column surface. |
+| `text_content` | Wide-layout text column wrapper (title, body, CTA). |
+| `link_button` | Wide-layout primary CTA button. |
+| `title` | Wide-layout section headline (`h1`). |
+| `text_body` | Wide-layout body paragraph. |
+
+## Slots
+
+None. All structure and copy come from the **`img`** and **`text`** attributes (JSON).
+
+## Minimal HTML example
 
 ```html
 <hb-site-paragraph-with-image
-  img='{"src":"https://example.com/image.png","alt":"Logo"}'
-  text='{"title":"Heading","body":"Short copy.","link":{"label":"Read more"}}'
+  img='{"src":"https://example.com/hero.png","alt":"Product"}'
+  text='{"title":"Built for clarity","body":"Short supporting copy goes here.","link":{"label":"Learn more","key":"learn-more"}}'
   text_side="right"
+  half_space="yes"
 ></hb-site-paragraph-with-image>
 ```
+
+### Listening for `elClick`
+
+```html
+<script>
+  const el = document.querySelector("hb-site-paragraph-with-image");
+  el.addEventListener("elClick", (e) => {
+    console.log("CTA key:", e.detail.key);
+  });
+</script>
+```
+
+Ensure **`text.link.key`** is set whenever you need this event; the label alone is not enough for dispatch.

package/manifest.json

@@ -143,47 +143,72 @@
     }
   },
   "styleSetup": {
-    "vars": [],
+    "vars": [
+      {
+        "name": "--bulma-section-padding",
+        "valueType": "number",
+        "defaultValue": "",
+        "description": "Feeds `--hb-spiw-pad` for host padding and text column insets."
+      },
+      {
+        "name": "--bulma-primary",
+        "valueType": "color",
+        "defaultValue": "",
+        "description": "Primary CTA (`button is-primary`) when a `link` is present."
+      },
+      {
+        "name": "--bulma-text",
+        "valueType": "color",
+        "defaultValue": "",
+        "description": "Title and body copy."
+      },
+      {
+        "name": "--bulma-text-strong",
+        "valueType": "color",
+        "defaultValue": "",
+        "description": "Heading weight / strong emphasis where Bulma maps it."
+      }
+    ],
     "parts": [
       {
         "name": "mobile_text_content",
-        "description": "mobile_text_content"
+        "description": "Stacked mobile column wrapping title, body, and CTA."
       },
       {
         "name": "mobile_title",
-        "description": "mobile_title"
+        "description": "Mobile headline (`h1`) above the body."
       },
       {
         "name": "mobile_text_body",
-        "description": "mobile_text_body"
+        "description": "Mobile paragraph body."
       },
       {
         "name": "mobile_link_button",
-        "description": "mobile_link_button"
+        "description": "Mobile primary button wrapping the optional link."
       },
       {
         "name": "mobile_image_content",
-        "description": "mobile_image_content"
+        "description": "Mobile figure wrapper for the hero image."
       },
       {
         "name": "image_content",
-        "description": "image content"
+        "description": "Desktop (or wide) image column surface."
       },
       {
         "name": "text_content",
-        "description": "text content"
+        "description": "Desktop text column wrapper (title, body, CTA)."
       },
       {
         "name": "link_button",
-        "description": "link button"
+        "description": "Desktop CTA button (`button is-primary`)."
       },
       {
         "name": "title",
-        "description": "title"
+        "description": "Desktop section headline rendered as an `h1` above the body copy."
       },
       {
         "name": "text_body",
-        "description": "text body"
+        "description": "Desktop body paragraph."
       }
     ]
   },
@@ -198,7 +223,7 @@
           "src": "https://upload.wikimedia.org/wikipedia/en/thumb/4/4a/Commons-logo.svg/446px-Commons-logo.svg.png"
         },
         "text": {
-          "title": "PragraphWithImage Regular",
+          "title": "ParagraphWithImage regular",
           "body": "lore ipsum dolor sit ame1t, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.",
           "link": {
             "label": "linkato"
@@ -279,5 +304,5 @@
   "size": {},
   "iifePath": "main.iife.js",
   "repoName": "@htmlbricks/hb-site-paragraph-with-image",
-  "version": "0.71.34"
+  "version": "0.71.36"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@htmlbricks/hb-site-paragraph-with-image",
-  "version": "0.71.34",
+  "version": "0.71.36",
   "contributors": [],
   "description": "Marketing block pairing an image (`img`) with rich text (`text`: title, body, optional link). Use `text_side` (`left` / `right`) and `half_space` for layout; responsive parts cover mobile and desktop. CTA is a Bulma `button is-primary` (optional inline colors on the link). Fires `elClick` when the link area is used.",
   "licenses": [