hb-site-paragraph-with-image (site-paragraph-with-image)

Category: content
Tags: content
Package: @htmlbricks/hb-site-paragraph-with-image

Overview

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

Layout and breakpoints

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

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.

Custom element

<hb-site-paragraph-with-image …></hb-site-paragraph-with-image>

Attributes

Attributes use snake_case. From HTML, pass strings; nested structures use JSON strings (see project conventions: booleans as yes / no where applicable).

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

The component parses img and text when they arrive as strings (typical from HTML attributes) via JSON.parse inside an effect.

img object

| 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

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

<hb-site-paragraph-with-image
  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

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

License

Package metadata references Apache-2.0 (see LICENSE.md in the published package when consuming from npm).