@htmlbricks/hb-cookie-law-banner 0.71.34 → 0.71.36

package/README.md

@@ -1,40 +1,127 @@
-## `hb-cookie-law-banner` — cookie-law-banner
+# `hb-cookie-law-banner`
 
-**Category:** layout | **Tags:** layout, compliance
+**Category:** layout · **Tags:** layout, compliance
 
-### What it does
+Fixed bottom cookie/consent bar built with Bulma (`notification is-dark`, columns, buttons). It stays visible until the visitor chooses **Accept** or (optionally) **Decline**, then hides and persists the choice in **`localStorage`** so repeat visits do not show the bar again.
 
-Bootstrap alert cookie notice until the user accepts or declines; the choice is stored in `localStorage` under `cookielaw`. Supports i18n via `i18nlang`, optional `cookielawuri4more` link, JSON `capabilities` for extended consent, slots to override title/text, and dispatches `acceptCookieLaw` with `{ accepted: "yes" | "no" }`.
+---
 
-### Custom element
+## Behavior and logic
+
+1. **Persistence** — On **Accept** or **Decline**, the component writes `localStorage.setItem("cookielaw", "yes" | "no")` (`"yes"` for accept, `"no"` for decline). On load, if that key exists, the banner is treated as dismissed and does not show the visible state.
+
+2. **Visibility** — The outer bar uses CSS (see [Styling](#styling)) to sit fixed at the bottom of the viewport. When a stored choice exists, the `is-visible` class is omitted so the bar animates to hidden (opacity / translate). When there is no stored choice, `is-visible` is applied so the bar appears (with a short transition delay).
+
+3. **`allowdecline`** — Only the string `"yes"` enables the decline button. Any other value (including missing) is normalized to **`"no"`** in an effect: accept-only flow with a single primary button.
+
+4. **`cookielawuri4more`** — The “Learn more” anchor is rendered when this attribute is **not** the literal string `"no"`. If the URL is empty, the link still appears and points to `https://wikipedia.org/wiki/HTTP_cookie`. Set `cookielawuri4more="no"` to hide the link entirely.
+
+5. **`capabilities`** — If passed as a JSON string (typical from HTML attributes), the component parses it in an effect. The current markup **does not render** group/item toggles or lists from `capabilities`; the shape exists in typings and metadata for integrators who may read the prop or extend the host app. The visible UI remains title, body, link, and buttons.
+
+6. **Internationalization** — `i18nlang` selects entries from the built-in dictionary (`"en"`, `"it"`). Strings include title, body, “Learn more”, “Accept”, and “Decline”. Override copy with slots when you need full control. (As shipped, the default body string under `en` may still be Italian; use the `text` slot for guaranteed locale-specific copy.)
+
+7. **Host logging** — Choosing an option logs an informational message to the console (`accept cookie law`).
+
+---
+
+## Layout
+
+- **Shell:** Bulma `notification is-dark is-radiusless mb-0` with `role="alert"`.
+- **Grid:** `columns is-mobile is-vcentered is-multiline` — on mobile the text column is full width (`is-12-mobile`); from tablet up, copy uses `is-8-tablet` and actions `is-4-tablet`.
+- **Actions column:** Flex row with wrap, end justification, centered cross-axis, and gap between the optional link and buttons.
+- **Fixed positioning:** Implemented in `styles/webcomponent.scss` (bottom edge, full width, `z-index: 40`), with horizontal column margins reset so the bar does not widen the document scroll width.
+
+---
+
+## Custom element
 
 `hb-cookie-law-banner`
 
-### Attributes / props (snake_case)
+---
+
+## Attributes / properties (snake_case, string-oriented)
+
+Web component attributes are strings. Booleans use **`yes`** / **`no`**. Complex values such as `capabilities` are JSON strings.
+
+| Attribute / prop | Type (logical) | Description |
+| --- | --- | --- |
+| `id` | `string` (optional) | Optional element id (standard host usage). |
+| `style` | `string` (optional) | Inline styles on the host (standard). |
+| `allowdecline` | `"yes"` \| `"no"` (optional, default `"no"`) | `"yes"` shows **Decline**; anything else behaves as `"no"`. |
+| `i18nlang` | `string` (optional) | Language key, e.g. `en`, `it`. |
+| `cookielawuri4more` | `string` (optional) | Policy URL for “Learn more”. Omit or leave empty for the Wikipedia cookie fallback. Use the literal **`no`** to hide the link. |
+| `capabilities` | `ICapabilities` as JSON string (optional) | Structured groups/items for cookie metadata; parsed when provided as a string. Not used by the default UI (see [Behavior](#behavior-and-logic)). |
+
+---
 
-| Property | Type | Notes |
+## Events
+
+| Event | `detail` | When |
 | --- | --- | --- |
-| `id` | string (optional) | Element identifier. |
-| `style` | string (optional) | Inline style string. |
-| `allowdecline` | union (optional) | `"yes"` \| `"no"` — show decline action. |
-| `i18nlang` | string (optional) | Language key (e.g. `en`, `it`). |
-| `capabilities` | object (optional) | JSON `ICapabilities`: cookie groups and items with scopes, mandatory flags, etc. |
-| `cookielawuri4more` | string (optional) | “Learn more” URL. |
+| `acceptCookieLaw` | `{ accepted: boolean }` | After the user clicks **Accept** (`true`) or **Decline** (`false`, only if decline is enabled). The choice is written to `localStorage` before the event is dispatched. |
+
+**Note:** `types/webcomponent.type.d.ts` currently types `accepted` as `"yes" \| "no"`; at runtime the component dispatches a **boolean**. Prefer listening for `true` / `false` in vanilla JS; align the declaration file with runtime if you rely on strict typings.
+
+---
+
+## Slots
+
+| Slot | Purpose |
+| --- | --- |
+| `title` | Replaces the default translated heading inside `title is-5`. |
+| `text` | Replaces the default translated paragraph inside `content is-size-6`. |
+
+Default slot content comes from the i18n dictionary for the active `i18nlang`.
+
+---
+
+## Styling
+
+### Bulma and host tokens
+
+The component forwards Bulma Sass with theme variables on `:host`. Documented CSS custom properties (from metadata / `extra/docs.ts`):
+
+| Variable | Role |
+| --- | --- |
+| `--bulma-scheme-main` | Scheme / surface for the dark notification bar. |
+| `--bulma-text` | Primary text (title and body). |
+| `--bulma-link` | “Learn more” link color on the inverted bar. |
+| `--bulma-border` | Useful if you extend the layout with extra separators. |
+
+See [Bulma CSS variables](https://bulma.io/documentation/features/css-variables/) for the full token set available where Bulma is forwarded.
+
+### Component SCSS
 
-**Slots:** `title`, `text`. **i18n:** Italian and English in metadata.
+`styles/webcomponent.scss` pins the bar to the bottom (`position: fixed`, `inset-inline: 0`, `bottom: 0`), hides it by default (`opacity: 0`, `visibility: hidden`, `translateY(100%)`), and reveals it with `.hb-cookie-law.is-visible` including transition timing.
 
-### Events (`CustomEvent` names)
+### CSS parts
 
-- **`acceptCookieLaw`** — `{ accepted: "yes" | "no" }`
+None (`::part` not exposed).
 
-### Usage notes
+---
 
-- Uses Bootstrap alert styling patterns.
-- Fullscreen layout size hint in metadata for Storybook-style hosts.
-- Shadow DOM; override copy via `title` and `text` slots.
-- Set `i18nlang` to match declared languages.
+## TypeScript typings
 
-### Minimal HTML example
+Authoring types live in `types/webcomponent.type.d.ts`.
+
+**`ICapabilities`** — Cookie catalog shape:
+
+- **`groups`:** `{ _id, label, type }[]`
+- **`items`:** entries with `groupId`, `title`, `scope`, `_id`, `cookieName`, and optional fields such as `description`, `descriptionUrl`, `thirdCompanyName`, `isMandatory`, `isTechnical`, `isMarketing`, `isThirdPartyOwned`, `isSessionCookie`, `cookieExpirationInSeconds`
+
+**`Component`** (props):
+
+- `id?`, `style?`, `allowdecline?`, `i18nlang?`, `cookielawuri4more?`, `capabilities?` (typed as `ICapabilities` in TS; from HTML pass JSON string)
+
+**`Events`:**
+
+- `acceptCookieLaw`: `{ accepted: "yes" | "no" }` in the type file — see [Events](#events) for runtime `boolean` behavior.
+
+---
+
+## Example
+
+Minimal host page with English copy, optional policy URL, and decline enabled:
 
 ```html
 <hb-cookie-law-banner
@@ -42,4 +129,40 @@ Bootstrap alert cookie notice until the user accepts or declines; the choice is
   i18nlang="en"
   cookielawuri4more="https://example.com/cookies"
 ></hb-cookie-law-banner>
+
+<script>
+  document.querySelector("hb-cookie-law-banner").addEventListener("acceptCookieLaw", (e) => {
+    console.log(e.detail.accepted); // true = accept, false = decline
+  });
+</script>
+```
+
+Accept-only (no decline button):
+
+```html
+<hb-cookie-law-banner allowdecline="no"></hb-cookie-law-banner>
+```
+
+Hide “Learn more”:
+
+```html
+<hb-cookie-law-banner cookielawuri4more="no"></hb-cookie-law-banner>
+```
+
+Custom title and body via slots (shadow DOM slot API depends on how you mount the bundle; with declarative shadow DOM or frameworks, use the same slot names):
+
+```html
+<hb-cookie-law-banner allowdecline="yes">
+  <span slot="title">Cookies on this site</span>
+  <span slot="text">We use cookies to run the site and measure usage. See our policy for details.</span>
+</hb-cookie-law-banner>
+```
+
+Optional `capabilities` JSON string (for hosts that store or forward metadata; default UI unchanged):
+
+```html
+<hb-cookie-law-banner
+  allowdecline="yes"
+  capabilities='{"groups":[{"_id":"essential","label":"Essential","type":"technical"}],"items":[{"groupId":"essential","title":"Session","scope":"strictly_necessary","_id":"1","cookieName":"sid","isTechnical":true,"isMandatory":true}]}'
+></hb-cookie-law-banner>
 ```

package/manifest.json

@@ -184,18 +184,43 @@
     }
   },
   "styleSetup": {
-    "vars": [],
+    "vars": [
+      {
+        "name": "--bulma-scheme-main",
+        "valueType": "color",
+        "defaultValue": "(theme)",
+        "description": "Dark notification (`notification is-dark`) maps surface colors through the active scheme; set on `:host` or document for bar contrast."
+      },
+      {
+        "name": "--bulma-text",
+        "valueType": "color",
+        "defaultValue": "(theme)",
+        "description": "Primary text on the bar (title and body copy)."
+      },
+      {
+        "name": "--bulma-link",
+        "valueType": "color",
+        "defaultValue": "(theme)",
+        "description": "“Learn more” link color on the inverted bar."
+      },
+      {
+        "name": "--bulma-border",
+        "valueType": "color",
+        "defaultValue": "(theme)",
+        "description": "Subtle separators if you extend the layout with extra rules."
+      }
+    ],
     "parts": []
   },
   "contributors": [],
   "htmlSlots": [
     {
       "name": "title",
-      "description": ""
+      "description": "Replace the default translated cookie title inside the `title is-5` heading."
     },
     {
       "name": "text",
-      "description": ""
+      "description": "Replace the default translated explanatory paragraph inside the `content` block."
     }
   ],
   "i18n": [
@@ -297,5 +322,5 @@
   },
   "iifePath": "main.iife.js",
   "repoName": "@htmlbricks/hb-cookie-law-banner",
-  "version": "0.71.34"
+  "version": "0.71.36"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@htmlbricks/hb-cookie-law-banner",
-  "version": "0.71.34",
+  "version": "0.71.36",
   "contributors": [],
   "description": "Bootstrap alert cookie notice shown until the user chooses accept or decline; the choice is stored in `localStorage` under `cookielaw` so the banner stays hidden on return visits. Supports i18n via `i18nlang`, optional `cookielawuri4more` link, JSON `capabilities` for extended consent, slots to override title/text, and dispatches `acceptCookieLaw` with `{ accepted: boolean }`.",
   "licenses": [