@htmlbricks/hb-vertical-img-txt-archive 0.71.34 → 0.71.36

package/README.md

@@ -1,36 +1,130 @@
-## `hb-vertical-img-txt-archive` — vertical-img-txt-archive
+# `hb-vertical-img-txt-archive`
 
+**Package folder:** `vertical-img-txt-archive`  
 **Category:** content  
 **Tags:** content, archive
 
-### What it does
+## Overview
 
-Vertical archive grid: `collection` items with `title`, `text`, `image`, and `link` (`type`: `tab` | `page` | `event`, `uri`). Optional `subtitle` on items; optional `size` sets column count. CSS parts style `container`, `item`, `image`, `title`, and `text`. Emits `collectionItemClick` with the item `uri` when an entry is activated.
+`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).
 
-### Custom element
+If `collection` is missing, empty, not an array, or invalid JSON, the component renders **nothing** (no placeholder).
 
-`hb-vertical-img-txt-archive`
+## Custom element
 
-### Attributes (snake_case; use string values in HTML)
+```text
+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` | Yes (in typings) | Object `{ type: "tab" \| "page" \| "event"; uri: string }`. Reserved for navigation or host-side handling; the current template does not render links or buttons from this field. |
+| `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:
+
+```json
+{
+  "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
+
+The `Events` map in `types/webcomponent.type.d.ts` defines:
+
+| Event | `detail` |
+| --- | --- |
+| `collectionItemClick` | `{ uri: string }` |
 
-- `id` (optional), `style` (optional): strings.
-- `collection` (required): JSON string — `Item[]` (`title`, `text`, `image`, `link`, optional `subtitle`, `index`).
-- `size` (optional): number as string — column count.
+The present Svelte implementation **does not** attach per-item click handlers or dispatch `collectionItemClick`. Use this type when you extend the component or when your toolchain expects the event name; for plain HTML usage, treat navigation as **host-managed** (e.g. wrap cards or listen on a parent) unless a future version wires clicks to `link.uri`.
 
-### Events
+## Styling (Bulma variables)
 
-- `collectionItemClick`: `{ uri: string }`.
+The component uses **Bulma 1.x** design tokens on `:host` and in layout (see [Bulma CSS variables](https://bulma.io/documentation/features/css-variables/)). Prefer **`--bulma-*`** custom properties for theme alignment.
 
-### Usage notes
+### CSS custom properties (documented in `extra/docs.ts`)
 
-- **CSS parts:** `container`, `item`, `image`, `title`, `text`.
-- No named content slots 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. |
 
-### Minimal HTML example
+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:
+
+```css
+hb-vertical-img-txt-archive::part(title) {
+  font-weight: 700;
+}
+```
+
+### Slots
+
+None (`htmlSlots` is empty in `extra/docs.ts`).
+
+## Minimal HTML example
 
 ```html
 <hb-vertical-img-txt-archive
-  collection='[{"title":"One","text":"Body","image":"https://placehold.co/300x200","link":{"type":"tab","uri":"https://example.com"}}]'
-  size="3"
+  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):
+
+```html
+<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`

package/manifest.json

@@ -119,26 +119,68 @@
       }
     },
     "collectionItemClick": {
-      "collectionItemClick": "eventEvent"
+      "action": "collectionItemClick"
     }
   },
   "styleSetup": {
-    "vars": [],
+    "vars": [
+      {
+        "name": "--bulma-block-spacing",
+        "valueType": "number",
+        "defaultValue": "",
+        "description": "Grid gap between archive cards."
+      },
+      {
+        "name": "--bulma-radius",
+        "valueType": "number",
+        "defaultValue": "",
+        "description": "Rounded corners on card images."
+      },
+      {
+        "name": "--bulma-column-gap",
+        "valueType": "number",
+        "defaultValue": "",
+        "description": "Space between image stack and text block."
+      },
+      {
+        "name": "--bulma-size-5",
+        "valueType": "number",
+        "defaultValue": "",
+        "description": "Card title (`h3`) font size."
+      },
+      {
+        "name": "--bulma-text",
+        "valueType": "color",
+        "defaultValue": "",
+        "description": "Body copy color under each title."
+      },
+      {
+        "name": "--bulma-line-height-main",
+        "valueType": "number",
+        "defaultValue": "",
+        "description": "Line height for description paragraphs."
+      }
+    ],
     "parts": [
       {
-        "name": "container"
+        "name": "container",
+        "description": "CSS grid host; column count follows viewport and optional `size`."
       },
       {
-        "name": "item"
+        "name": "item",
+        "description": "Single archive card wrapper (image + text column)."
       },
       {
-        "name": "image"
+        "name": "image",
+        "description": "Cover image element for the card."
       },
       {
-        "name": "title"
+        "name": "title",
+        "description": "Card heading (`h3`)."
       },
       {
-        "name": "text"
+        "name": "text",
+        "description": "Supporting paragraph under the title."
       }
     ]
   },
@@ -399,5 +441,5 @@
   "size": {},
   "iifePath": "main.iife.js",
   "repoName": "@htmlbricks/hb-vertical-img-txt-archive",
-  "version": "0.71.34"
+  "version": "0.71.36"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@htmlbricks/hb-vertical-img-txt-archive",
-  "version": "0.71.34",
+  "version": "0.71.36",
   "contributors": [],
   "description": "Vertical archive grid: `collection` items with `title`, `text`, `image`, and `link` (e.g. `type` + `uri`). Optional `size` sets column count; CSS parts style container, item, image, title, and text. Emits `collectionItemClick` when an item is chosen.",
   "licenses": [