@htmlbricks/hb-site-slideshow-horizontal 0.71.35 → 0.71.37

package/README.md

@@ -1,36 +1,161 @@
-## `hb-site-slideshow-horizontal` — site-slideshow-horizontal
+# `hb-site-slideshow-horizontal` — integrator guide
 
-**Category:** content  
-**Tags:** content, media
+**Category:** content · **Tags:** content, media · **Package:** `@htmlbricks/hb-site-slideshow-horizontal`
 
-### What it does
+## Summary
 
-Horizontal media strip: `data` lists slides with `href`, `caption`, and optional `link`, `externalLink`, `key`, or `duration` for video-style rows. Set `type` to `videos` for that layout; optional `slide` index and `size`. Emits `slideClick` when a slide is activated.
+Horizontal slideshow strip that shows a window of image (or video-style) tiles, with previous/next arrows. Slides are **data-driven** (JSON); there are no light DOM slots.
 
-### Custom element
+## Behavior
 
-`hb-site-slideshow-horizontal`
+- Accepts a **required** `data` payload: an ordered list of slides. Each slide must include a **`href`** (image URL). Entries without `href` are dropped.
+- Slides are sorted by optional **`index`** (ascending), then renumbered internally from `0`.
+- The strip shows **`size`** tiles at once when you set `size` as a positive number. If you omit `size`, the count is derived from the viewport: `round(windowInnerWidth / 250)` (minimum practical width still comes from the host).
+- **`slide`** is the starting index into the flattened list (also used as the window offset for the arrows). It can be synced from the outside; string values are coerced with `Number(...)`.
+- **Previous / next** arrows shift that index and **wrap** across the list so the window is always filled when there are more slides than visible tiles (the implementation may concatenate from the beginning of the list to pad the row).
+- **`type`** switches between a plain image caption layout (`images`, default) and a **video-style** row with a play affordance and optional **`duration`** text.
 
-### Attributes (snake_case; use string values in HTML)
+---
 
-- `id` (optional), `style` (optional): strings.
-- `data` (required): JSON string — array of `{ href; caption?; externalLink?; link?; key?; duration?; index? }`.
-- `type` (optional): `"images"` | `"videos"`.
-- `slide` (optional): number as string (current slide).
-- `size` (optional): number as string.
+## Custom element
 
-### Events
+```html
+<hb-site-slideshow-horizontal></hb-site-slideshow-horizontal>
+```
+
+Tag name: **`hb-site-slideshow-horizontal`**
+
+---
+
+## Slide model (`data` items)
+
+Each object in the `data` array can include:
+
+| Field | Required | Description |
+| --- | --- | --- |
+| `href` | **Yes** | Image URL for the tile. |
+| `caption` | No | Shown under the play overlay in `videos` mode, or as an overlay caption in `images` mode when present. |
+| `index` | No | Sort hint before display (lower first). |
+| `externalLink` | No | If set, clicking the tile opens this URL in a **new** tab (`_blank`). Takes precedence over `link` and `key`. |
+| `link` | No | If set (and no `externalLink`), clicking sets **`window.location.href`** to this URL. |
+| `key` | No | If set (and neither `externalLink` nor `link`), clicking dispatches the **`slideClick`** custom event with `{ key }`. |
+| `duration` | No | In `videos` mode, optional duration string next to the title (exposed via CSS part `video_sub_time`). |
+
+If none of `externalLink`, `link`, or `key` is set, the tile is **non-interactive** (still shows image/caption UI).
+
+---
+
+## Attributes and properties (web component)
+
+Use **snake_case** names. In HTML, **attribute values are strings**: pass JSON as a string for `data`, and numeric fields as their decimal string form.
+
+| Name | Required | Description |
+| --- | --- | --- |
+| `data` | **Yes** | JSON string: array of slide objects (see above). Invalid JSON logs an error and yields an empty strip (nothing rendered). |
+| `type` | No | `"images"` (default) or `"videos"`. |
+| `slide` | No | Current / initial slide index (stringified number). |
+| `size` | No | Number of visible tiles per row (stringified integer). When omitted, width-based sizing is used. |
+| `id` | No | Passed through for identification (standard host usage). |
+
+The authoring **`Component`** type also lists an optional `style` field; the current shadow implementation does **not** apply it—prefer styling via **CSS custom properties** and global layout around the host.
+
+---
+
+## Events
+
+Listen with `addEventListener` or the equivalent in your framework.
+
+| Event | `detail` | When |
+| --- | --- | --- |
+| `slideClick` | `{ key: string }` | User activates a slide that defines **`key`** and does not use `externalLink` or `link`. |
+
+---
+
+## Styling (Bulma tokens)
+
+The component uses Bulma **CSS variables** on `:host` for spacing and arrow chrome. See [Bulma CSS variables](https://bulma.io/documentation/features/css-variables/).
+
+### Common CSS custom properties
+
+| Variable | Role |
+| --- | --- |
+| `--bulma-block-spacing` | Vertical margin for the strip and horizontal padding on the arrow hit areas. |
+| `--bulma-white` | Color of the arrow glyphs on the gradient fades. |
+| `--bulma-scheme-invert` | Base for arrow gradient overlays and hover contrast. |
+
+### CSS shadow parts
 
-- `slideClick`: `{ key: string }`.
+Style from outside the shadow root with `::part(...)`.
 
-### Usage notes
+| Part | Role |
+| --- | --- |
+| `video_sub_title` | Title line under the play affordance when `type` is `videos`. |
+| `video_sub_time` | Duration text beside the title when `duration` is set. |
+| `caption_content` | Caption text for image-style slides (`type` `images`). |
 
-- **CSS parts:** `video_sub_title`, `caption_content` (see `extra/docs.ts` for full list).
+### Slots
 
-### Minimal HTML example
+None—content is entirely driven by the `data` JSON.
+
+---
+
+## Minimal HTML example
+
+```html
+<hb-site-slideshow-horizontal
+  data='[
+    {"href":"https://placehold.co/600x400/111/fff","caption":"One"},
+    {"href":"https://placehold.co/600x400/222/fff","caption":"Two"}
+  ]'
+></hb-site-slideshow-horizontal>
+```
+
+### Video-style layout
+
+```html
+<hb-site-slideshow-horizontal
+  type="videos"
+  data='[
+    {"href":"https://placehold.co/640x360/000/fff","caption":"Intro","duration":"0:42"}
+  ]'
+></hb-site-slideshow-horizontal>
+```
+
+### Initial index, fixed strip width, and `slideClick`
 
 ```html
 <hb-site-slideshow-horizontal
-  data='[{"href":"https://placehold.co/600x400","caption":"Slide 1"},{"href":"https://placehold.co/600x401","caption":"Slide 2"}]'
+  id="strip"
+  slide="1"
+  size="5"
+  data='[
+    {"href":"https://placehold.co/400x300/004d40/fff?text=A"},
+    {"href":"https://placehold.co/400x300/1b5e20/fff?text=B","key":"b"},
+    {"href":"https://placehold.co/400x300/33691e/fff?text=C"}
+  ]'
 ></hb-site-slideshow-horizontal>
+
+<script>
+  document.getElementById("strip").addEventListener("slideClick", (e) => {
+    console.log("key:", e.detail.key);
+  });
+</script>
 ```
+
+---
+
+## TypeScript (authoring)
+
+Props and events for wrappers or Storybook align with `types/webcomponent.type.d.ts`:
+
+- **`Component`**: `id`, `data`, optional `slide`, `type`, `size`, and optional `style` (see note above).
+- **`Data`**: slide item shape.
+- **`Events`**: `slideClick` with `{ key: string }`.
+
+---
+
+## Behavior notes
+
+- If **`data`** parses to an empty list, or every item lacks `href`, the component **renders nothing** (no arrows, no section).
+- Negative **`slide`** values are supported by the internal windowing logic; extremely negative values are normalized toward the start of the list.
+- Tiles use pointer interactions on the host page; ensure slide `href` values and link targets meet your accessibility and security policies.