# `hb-terms-doc-templates` — integrator guide

**Category:** content · **Tags:** content, compliance · **Package:** `@htmlbricks/hb-terms-doc-templates`

## Summary

`hb-terms-doc-templates` turns structured JSON into long-form legal-style pages: Italian privacy notices (`privacy-doc-italian`) or cookie policies (`cookie-doc-italian`, `cookie-doc-english`, `cookie-doc`). It outputs semantic HTML inside the shadow root (title, numbered chapters, paragraphs, bullet lists, and optional tables via the nested `hb-table` web component). Copy is driven entirely by the `data` payload and optional `i18nlang`; there are no light-DOM slots.

These templates are **starting points for documentation**, not a substitute for legal review.

## Custom element

```html
<hb-terms-doc-templates …></hb-terms-doc-templates>
```

## How it works

1. The host passes a **`data` JSON string** whose root object includes an `id` field that selects the template.
2. On each reactive update, the component parses `data` with `JSON.parse` and **only handles `data` when it is a string**. If `data` is missing, not a string, invalid JSON, or the `id` is not one of the supported values, nothing valid is rendered and the fallback text `invalid doc params` is shown.
3. Supported `id` values:
   - **`privacy-doc-italian`** — Italian privacy policy; input shape `ITPrivacy` (see types).
   - **`cookie-doc-italian`** or **`cookie-doc`** — Italian cookie policy; input shape `CookieContent` (Italian content path; `cookie-doc` is routed the same as `cookie-doc-italian`).
   - **`cookie-doc-english`** — English cookie policy; input shape `CookieContent`.
4. **`i18nlang`** (optional) selects strings from the built-in dictionary (`it`, `en` are registered in metadata). When the language changes, the translator is recreated.
5. **`hb-table`** is registered as a dependency version aligned with this package; chapters may embed a table built from `paragraph.table.headers` and `paragraph.table.rows` with pagination disabled.

Authoritative TypeScript shapes for `data` live in `types/webcomponent.type.d.ts` (`ITPrivacy`, `CookieContent`, nested `CookieRow`, chapters, paragraphs, etc.).

## Attributes (snake_case; HTML values are strings)

| Attribute | Required | Description |
| --- | --- | --- |
| `data` | No (see behavior) | JSON **string** describing the document. Must parse to an object with a supported `id` and the fields expected for that template (site, company, cookies list, privacy admin, and so on). Omitting or leaving invalid shows **`invalid doc params`**. |
| `i18nlang` | No | Language code for UI strings, e.g. `it` or `en`. |
| `id` | No | Optional host identifier string; not used to pick a template (template choice is `data.id`). |
| `style` | No | Present on the `Component` typing for API symmetry; the current implementation does not apply a separate `style` prop beyond normal element styling. |

Nested values inside the JSON (numbers, booleans, arrays) follow normal JSON rules inside the string attribute.

## Events

No custom events are declared for this component (`Events` is `{}` in `types/webcomponent.type.d.ts`).

## Styling

The component uses **Bulma 1.x** content styles in the shadow root. Prefer **`--bulma-*`** variables on `:host` or ancestors (see [Bulma CSS variables](https://bulma.io/documentation/features/css-variables/)).

### CSS custom properties

| Variable | Purpose |
| --- | --- |
| `--bulma-block-spacing` | Vertical spacing between headings, paragraphs, and lists. |
| `--bulma-content-heading-bottom` | Margin below main chapter titles (`h1` / `h2`). |
| `--bulma-line-height-main` | Line height for paragraphs and list items. |

### CSS parts

| Part | Exposed on | Purpose |
| --- | --- | --- |
| `h1` | Document title | Top-level policy title. |
| `h2` | Chapter heading | Includes numeric index from the template. |
| `p` | Paragraph | Body text inside a chapter. |
| `ul` | List | Wrapper for list blocks. |
| `li` | List item | Single bullet entry. |

Sub-headings rendered as `h3` (when `paragraph.title` is set) do **not** expose a `::part` name.

Embedded `hb-table` nodes have their own theming and parts as documented for that component.

### Slots

None.

## Dependencies

The document renderer pulls in **`hb-table`** for tabular sections. Ensure your bundle or loader includes `hb-table` (and its transitive dependencies) if those chapters appear in your template output.

## Examples

### English cookie policy (minimal empty cookie list)

```html
<hb-terms-doc-templates
  i18nlang="en"
  data='{"id":"cookie-doc-english","site":{"name":"Example","url":"https://example.com","privacyPolicyUri":"https://example.com/privacy","cookiePolicyUri":"https://example.com/cookies"},"company":{"name":"Example Ltd","address":"1 Example Street"},"cookies":[]}'
></hb-terms-doc-templates>
```

### Italian privacy notice (trimmed payload)

Fill in `site`, `company`, `privacyAdmin`, `collectedData`, and optional sections per `ITPrivacy` in `types/webcomponent.type.d.ts`. Example skeleton:

```html
<hb-terms-doc-templates
  i18nlang="it"
  data='{"id":"privacy-doc-italian","site":{"name":"Example","url":"https://example.com","privacyPolicyUri":"https://example.com/privacy","cookiePolicyUri":"https://example.com/cookies"},"company":{"name":"Example Srl","address":"Via Example 1"},"privacyAdmin":{"name":"DPO","email":"privacy@example.com"},"collectedData":{"scopes":[],"dataTypes":[]}}'
></hb-terms-doc-templates>
```

For richer samples (including cookie rows with `storage`, `type`, `durate`, optional `third`), see `extra/docs.ts` (`examples`: `italian`, `cookieit`, `cookieen`, `cookieen_no_data`).

## Programmatic usage note

Because the implementation only parses **`data` when `typeof data === "string"`**, assigning a live **object** to a property in JavaScript will not populate the document until you pass a JSON string (for example `element.setAttribute("data", JSON.stringify(payload))` or an equivalent string property, depending on your wrapper).

## Further reading

- Type definitions: `types/webcomponent.type.d.ts`
- Metadata, Bulma variables, parts, and Storybook-style examples: `extra/docs.ts`
- Template builders: `libs/privacyItContent.ts`, `libs/cookieItContent.ts`, `libs/cookieEnContent.ts`