@htmlbricks/hb-paragraps-around-image 0.71.34 → 0.71.36

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +102 -18
  2. package/main.iife.js +1 -1
  3. package/main.iife.js.map +1 -1
  4. package/manifest.json +28 -13
  5. package/package.json +1 -1
package/README.md CHANGED
@@ -1,37 +1,121 @@
1
- ## `hb-paragraps-around-image` — paragraphs around image
1
+ # hb-paragraps-around-image
2
2
 
3
- **Category:** content
4
- **Tags:** content
3
+ **Category:** content · **Tags:** content
4
+ **Package:** `@htmlbricks/hb-paragraps-around-image`
5
+ **Dependency:** nests `hb-paragraps-around-image-cell` (registered at runtime with the same version as this bundle via `wc-js-utils` `addComponent`).
5
6
 
6
- ### What it does
7
+ ## Overview
7
8
 
8
- Editorial block with a central image and up to six text blocks in two side columns using `hb-paragraps-around-image-cell` (indices 0, 2, 4 left; 1, 3, 5 right). Parses `paragraphs` from JSON and bubbles `paragraphPressed` when a cell fires it.
9
+ `hb-paragraps-around-image` is an editorial layout: a **center column image** flanked by **up to six** rich text blocks rendered as `hb-paragraps-around-image-cell` instances. Paragraph data is supplied as a **JSON string**; each cell is capped at **eight lines** of body text (`max_lines="8"` in the implementation).
9
10
 
10
- ### Custom element
11
+ The host does not render until **both** a non-empty `paragraphs` array (after parsing) and a non-empty `img` URL are present.
12
+
13
+ ## Layout and paragraph order
14
+
15
+ On viewports **900px and wider**, the outer container is a horizontal flex row with three columns: **left**, **center** (image), **right**. Below that breakpoint the block still uses the same DOM order; spacing and flex behavior follow `styles/webcomponent.scss`.
16
+
17
+ Paragraphs map to columns by **array index** (0-based):
18
+
19
+ | Index | Column |
20
+ |-------|--------|
21
+ | 0, 2, 4 | Left |
22
+ | 1, 3, 5 | Right |
23
+
24
+ Omitted indices simply leave a gap in that column (for example, a single object only fills the top-left cell). You can use up to **six** entries for a full two-column stack.
25
+
26
+ ## Paragraph object shape
27
+
28
+ Each item in the `paragraphs` array matches the `Paragraphs` type:
29
+
30
+ | Field | Required | Description |
31
+ |-------|----------|-------------|
32
+ | `text` | Yes | Body copy (line-clamped per cell). |
33
+ | `title` | No | Heading shown by the cell. |
34
+ | `icon` | No | Bootstrap Icons **icon name** (e.g. `globe`, `journal-text`) used inside the cell. |
35
+ | `link` | No | If set, the title behaves as a link to this URL. |
36
+ | `key` | No | Identifier forwarded on `paragraphPressed` when the cell reports a press (see Events). |
37
+
38
+ Icons rely on **Bootstrap Icons**; the component loads the icon font from a CDN (`<svelte:head>` in the implementation, plus a font import in `styles/webcomponent.scss`).
39
+
40
+ ## Custom element
11
41
 
12
42
  `hb-paragraps-around-image`
13
43
 
14
- ### Attributes (snake_case; use string values in HTML)
44
+ ## Attributes (HTML)
45
+
46
+ Web component attributes are **strings**. Use **snake_case** names as in the catalog.
47
+
48
+ | Attribute | Required | Description |
49
+ |-----------|----------|-------------|
50
+ | `img` | Yes | Image URL for the center column (`src` of the central `<img>`; `alt` is empty in the current markup). |
51
+ | `paragraphs` | Yes | **JSON string** encoding an array of paragraph objects (see above). If the runtime value is a string, the component attempts `JSON.parse` inside an effect; invalid JSON is ignored and may leave the layout empty. |
52
+ | `id` | No | Optional host `id`. |
53
+
54
+ The TypeScript `Component` type also includes optional `style`; it is not wired in the current Svelte implementation (commented out), so setting a `style` attribute has no effect until the implementation exposes it.
55
+
56
+ ## Events
57
+
58
+ | Event | `detail` | When |
59
+ |-------|----------|------|
60
+ | `paragraphPressed` | `{ key: string }` | Bubbled from a child `hb-paragraps-around-image-cell` when it emits `paragraphPressed`. Consumers should set a stable `key` on each paragraph object if they need to identify which block was activated. |
61
+
62
+ Listen with `addEventListener("paragraphPressed", ...)` or your framework’s equivalent.
15
63
 
16
- - `id`, `style` (optional): strings.
17
- - `img` (required): string — image URL.
18
- - `paragraphs` (required): JSON string — array of `{ text; title?; icon?; link?; key? }`.
64
+ ## Styling (Bulma theme variables)
19
65
 
20
- ### Events
66
+ The component forwards shared Bulma setup (`styles/bulma.scss`) and local layout (`styles/webcomponent.scss`). Set public **`--bulma-*`** variables on `body`, `:root`, or an ancestor so they cascade into `:host` and nested cells. See [Bulma CSS variables](https://bulma.io/documentation/features/css-variables/).
21
67
 
22
- - `paragraphPressed`: `{ key: string }`.
68
+ | Variable | Role |
69
+ |----------|------|
70
+ | `--bulma-block-spacing` | Horizontal padding on the left and right columns (`.col`). Default in metadata: `1.5rem`. |
71
+ | `--bulma-text` | Default body text color (inherited by nested `hb-paragraps-around-image-cell`). |
72
+ | `--bulma-link` | Title links and interactive affordances in child cells. |
73
+ | `--bulma-text-strong` | Strong / title-weight copy where the theme distinguishes it. |
23
74
 
24
- ### Usage notes
75
+ **Slots:** none — layout is entirely data-driven.
76
+ **CSS parts:** none on this host.
25
77
 
26
- - **Slots:** `skelcontent`.
27
- - **CSS parts:** `testpart`.
28
- - Up to six paragraph objects; layout alternates columns per index.
78
+ ## Minimal example
29
79
 
30
- ### Minimal HTML example
80
+ ```html
81
+ <hb-paragraps-around-image
82
+ img="https://placehold.co/300x200"
83
+ paragraphs='[{"text":"Body copy here.","title":"Title","icon":"globe","link":"https://example.com","key":"intro"}]'
84
+ ></hb-paragraps-around-image>
85
+ ```
86
+
87
+ ## Multi-block example (two columns)
88
+
89
+ ```html
90
+ <hb-paragraps-around-image
91
+ img="https://placehold.co/300x200"
92
+ paragraphs='[
93
+ {"text":"Left column first block.","title":"Left 1","icon":"journal-text","link":"https://example.com","key":"L1"},
94
+ {"text":"Right column first block.","title":"Right 1","icon":"journal-text","link":"https://example.org","key":"R1"},
95
+ {"text":"Left column second block.","title":"Left 2","icon":"journal-text","key":"L2"},
96
+ {"text":"Right column second block.","title":"Right 2","icon":"journal-text","key":"R2"}
97
+ ]'
98
+ ></hb-paragraps-around-image>
99
+ ```
100
+
101
+ ## Script listener example
31
102
 
32
103
  ```html
33
104
  <hb-paragraps-around-image
105
+ id="editorial"
34
106
  img="https://placehold.co/300x200"
35
- paragraphs='[{"text":"Hello body","title":"Title","icon":"globe","link":"https://example.com"}]'
107
+ paragraphs='[{"text":"Click the title if it is a link; keys identify blocks.","title":"Press me","key":"block-a"}]'
36
108
  ></hb-paragraps-around-image>
109
+
110
+ <script>
111
+ document.getElementById("editorial")?.addEventListener("paragraphPressed", (e) => {
112
+ console.log("key:", e.detail.key);
113
+ });
114
+ </script>
37
115
  ```
116
+
117
+ ## Implementation notes for integrators
118
+
119
+ - **Empty state:** If `paragraphs` is missing, empty, not parseable as JSON, or `img` is missing, nothing inside `#container` is shown.
120
+ - **Child package:** Ensure `hb-paragraps-around-image-cell` is available (same bundle or registered before use) so nested custom elements upgrade correctly.
121
+ - **Accessibility:** Central image uses `alt=""`; prefer meaningful `img` URLs or extend the cell package if you need richer semantics.