hb-vertical-img-txt-archive — integrator guide

Category: content · Tags: content, archive · Package: @htmlbricks/hb-vertical-img-txt-archive

Summary

hb-vertical-img-txt-archive renders a responsive CSS grid of archive cards. Each card stacks an image above a title (h3) and body text (p). Data comes from a single collection value: either an array (when using the element from JavaScript) or a JSON string (typical in HTML).

If collection is missing, empty, not an array, or invalid JSON, the component renders nothing (no placeholder).

Custom element

hb-vertical-img-txt-archive

Data model (collection items)

Each entry in collection matches the Item shape in types/webcomponent.type.d.ts:

| Field | Required | Description | | --- | --- | --- | | title | Yes | Card heading; also used as the image alt text. | | text | Yes | Supporting paragraph under the title. | | image | Yes | Image URL for the card media. | | link | No | Object { type: "tab" \| "page" \| "event"; uri: string }. When present, the whole card is clickable: the component dispatches collectionItemClick, opens tab links in a new window, navigates the document for page, and only notifies the host for event (no built-in navigation). | | subtitle | No | Optional metadata (e.g. date or version); not shown in the current markup. | | index | No | Optional ordering hint for consumers; not used for rendering. |

Example item:

{
  "title": "Release notes",
  "subtitle": "v2.4",
  "text": "Changelog highlights.",
  "image": "https://example.com/card.jpg",
  "link": { "type": "page", "uri": "/releases/2-4" }
}

Attributes (snake_case, string values in HTML)

Web component attributes are strings. Objects and arrays must be JSON-serialized for collection.

| Attribute | Required | Description | | --- | --- | --- | | collection | Yes | JSON array of items (see above). Whitespace-only or invalid JSON logs an error and yields an empty grid. | | id | No | Optional host id (see Component in types/webcomponent.type.d.ts). |

The authoring Component type also lists optional style and size. Layout column count in the current implementation is not driven by size: it is derived from the window width as roughly one column per ~250px of width, capped by the number of items. Optional style may still be useful for host-level styling depending on how your build wires custom-element props; refer to your bundle’s generated typings if you rely on it.

Layout behavior

• The grid uses grid-template-columns: repeat(N, auto) where N is computed from innerWidth (via svelte:window) and the collection length, so the archive reflows on resize.
• Cards use full-width images with object-fit: cover inside the image area.

Events

| Event | detail | When | | --- | --- | --- | | collectionItemClick | { uri: string; link_type?: "tab" \| "page" \| "event" } | User activates a card that defines link. |

Styling (Bulma variables)

The component uses Bulma 1.x design tokens on :host and in layout (see Bulma CSS variables). Prefer --bulma-* custom properties for theme alignment.

CSS custom properties (documented in extra/docs.ts)

| Variable | Role | | --- | --- | | --bulma-block-spacing | Gap between cards in the grid. | | --bulma-radius | Corner radius on the image frame. | | --bulma-column-gap | Space between the image block and text block; also used for spacing under the title. | | --bulma-size-5 | Font size for the card title (h3). | | --bulma-text | Color for the description paragraph. | | --bulma-line-height-main | Line height for body text. |

Defaults fall back to sensible literals in styles/webcomponent.scss if a variable is unset.

CSS ::part selectors

| Part | Targets | | --- | --- | | container | Outer grid wrapper (part="container"). | | item | Single card wrapper (part="item"). | | image | The <img> element (part="image"). | | title | The <h3> (part="title"). | | text | The <p> (part="text"). |

Example:

hb-vertical-img-txt-archive::part(title) {
  font-weight: 700;
}

Slots

None (htmlSlots is empty in extra/docs.ts).

Minimal HTML example

<hb-vertical-img-txt-archive
  collection='[{"title":"One","text":"Short description.","image":"https://placehold.co/300x200","link":{"type":"tab","uri":"https://example.com"}}]'
></hb-vertical-img-txt-archive>

Multi-item example (attribute stays on one line in production, or build the string in JS):

<hb-vertical-img-txt-archive
  collection='[{"title":"Alpha","text":"First item.","image":"https://placehold.co/300x200","link":{"type":"event","uri":"open:alpha"}},{"title":"Beta","text":"Second item.","image":"https://placehold.co/300x200","link":{"type":"page","uri":"/beta"}}]'
></hb-vertical-img-txt-archive>

Related files

• Implementation: component.wc.svelte
• Authoring types: types/webcomponent.type.d.ts
• Metadata, Storybook args, and examples: extra/docs.ts
• Styles: styles/bulma.scss, styles/webcomponent.scss