@htmlbricks/hb-card-video 0.71.35 → 0.71.36

package/README.md

@@ -2,50 +2,129 @@
 
 **Category:** media | **Tags:** media, video
 
-### What it does
+### Summary
 
-**Bulma** `card` with a 16:9 `image` frame: YouTube embed when `provider` is `youtube`, otherwise an HTML5 `<video>` with MP4 source. Optional title, truncated description, formatted `time` via Day.js (`dateformat`), “read more” `button is-primary`, and social share placeholders when `pageuri` is set. Bootstrap Icons for the clock in the footer.
+A Bulma **card** with a fixed **16:9** media area at the top, optional title and description, optional timestamp in the footer, and optional “share + action” row when a page URL is supplied. The media area is either an **HTML5 `<video>`** (MP4 `source`) or a **YouTube iframe embed**, depending on `provider`.
 
-### Custom element
+### Behavior: native video vs YouTube
+
+- **`provider` is `"youtube"`** — Renders an `<iframe>` inside Bulma’s `image is-16by9` figure. Set **`videosrc`** to the **full embed URL** (for example `https://www.youtube.com/embed/VIDEO_ID`). The iframe uses `allowfullscreen` and a static `title` of `YouTube video` for accessibility.
+- **Any other `provider` (including omitted or empty)** — Renders a native **`<video controls>`** with a single **`<source src={videosrc} type="video/mp4">`**, plus an empty captions `<track>` placeholder. The figure uses **`has-background-black`** behind the letterboxed frame.
+
+Browsers that do not support `<video>` see the fallback text inside the video element.
+
+### Layout
+
+Structure follows Bulma’s **card** pattern:
+
+1. **`card-image`** — 16:9 figure (`image is-16by9`) containing either the iframe or the video.
+2. **`card-content`** — Optional `title` (`title is-5`), optional description block, then (only if **`pageuri`** is set) Facebook “like” placeholder markup, a Twitter intent link styled as `twitter-share-button`, a line break, and optionally a primary **button** when **`linklabel`** is non-empty.
+3. **`card-footer`** — Rendered **only when `time` is set**. It wraps a **named slot** (see Slots) whose default content is a small grey line with a clock icon and the formatted date/time.
+
+The root inner wrapper uses **`hb-card-video-root`** with flex column layout so the card can stretch vertically (`card-content` grows with `flex: 1`).
+
+### Logic
+
+- **Description** — If `description` is longer than **100 characters**, the UI shows only the **first 100 characters** (no ellipsis added in markup).
+- **`time` + `dateformat`** — When `time` is provided, the footer shows **Day.js**–formatted text. Default **`dateformat`** is `dddd DD MMMM YYYY HH:mm`. The formatter uses **`navigator.language`** as the Day.js locale, then applies a small transform that **uppercases the first letter of each word** in the formatted string.
+- **`pageuri`** — When set, the content area includes **Facebook** (`fb-like` div with `data-href`, etc.) and **Twitter** (`twitter-share-button` / intent URL) **placeholder markup**. Those widgets only become interactive if the **host page** loads the corresponding third-party scripts and initializes them; this component does not bundle those SDKs.
+- **`linklabel`** — Defaults to **`read more`**. The primary **`<a class="button is-primary">`** is rendered only when **`pageuri`** is set **and** `linklabel` is truthy with **non-zero** length (so an empty string hides the button even if `pageuri` is set).
+
+### Custom element tag
 
 `hb-card-video`
 
-### Attributes / props (snake_case)
+### Attributes (names as in typings; string values from HTML)
 
-| Property | Type | Notes |
+From HTML / `setAttribute`, values are **strings** (dates as parseable strings, for example ISO 8601). Use the same attribute names as in the table below (aligned with this package’s typings and custom-element props).
+
+| Attribute | Required | Description |
 | --- | --- | --- |
-| `id` | string (optional) | Element identifier. |
-| `style` | string (optional) | Inline style string. |
-| `title` | string (optional) | Card title. |
-| `description` | string (optional) | Body text (truncated in UI). |
-| `videosrc` | string (required) | Video URL or embed source. |
-| `provider` | union (optional) | `"youtube"` or `""` for native video. |
-| `pageuri` | string (optional) | Page URL for share widgets. |
-| `linklabel` | string (optional) | Label for the “read more” style link. |
-| `time` | Date (optional) | Publication or event time; pass parseable date string in HTML. |
-| `dateformat` | string (optional) | Day.js format string for `time`. |
+| `videosrc` | **Yes** | URL for the MP4 `source` (native video) or the full **YouTube embed** URL (`provider="youtube"`). |
+| `provider` | No | Set to **`youtube`** for iframe mode; omit or use an empty string for native `<video>`. |
+| `title` | No | Card heading (`title is-5`). |
+| `description` | No | Body paragraph; truncated to **100** characters in the UI when longer. |
+| `pageuri` | No | Canonical URL passed into share placeholders and the optional primary button `href`. |
+| `linklabel` | No | Label for the primary button when `pageuri` is set; implementation default **`read more`**. |
+| `time` | No | When set, shows the footer with formatted clock line (or slot content). Use a string the runtime can treat as a `Date` (for example `2026-03-01T12:00:00.000Z`). |
+| `dateformat` | No | Day.js format string; default **`dddd DD MMMM YYYY HH:mm`**. |
+| `id` | No | Passed through for the host / styling hooks. |
+| `style` | No | Inline style string on the component, if your setup forwards it. |
+
+### Events
+
+None. The public **`Events`** type is `{}` — no custom `CustomEvent` payloads are declared for this component.
+
+### Styling
+
+The shadow tree bundles **Bulma 1.x** pieces needed for the card, image ratio, typography, button, and content spacing. **Bootstrap Icons** are loaded for the footer clock icon (see `styles/webcomponent.scss`).
 
-**Slot:** `card-footer`. No CSS vars in metadata.
+#### CSS custom properties
 
-### Events (`CustomEvent` names)
+| Variable | Role |
+| --- | --- |
+| `--bulma-black` | Background behind the 16:9 **native** video frame (`has-background-black`). |
+| `--bulma-primary` | Primary **button** (`is-primary`) for the `pageuri` action. |
+| `--bulma-text` | Title and body copy. |
+| `--bulma-link` | Link-toned controls where Bulma applies link styling. |
 
-None declared in types (`Events` is an empty object).
+Other **`--bulma-*`** variables from the bundled Bulma setup may apply on `:host`; see [Bulma CSS variables](https://bulma.io/documentation/features/css-variables/).
 
-### Usage notes
+#### CSS parts (`::part`)
 
-- Card layout follows Bulma `card` / `card-image` / `card-content` / `card-footer` patterns.
-- YouTube vs file video is selected only via `provider`; ensure `videosrc` matches the mode.
-- Shadow DOM contains the player and share UI; slot `card-footer` extends the card.
-- No i18n in `docs.ts`.
+None exposed (`cssParts` is empty in `extra/docs.ts`).
 
-### Minimal HTML example
+#### HTML slots
+
+| Slot | Description |
+| --- | --- |
+| `card-footer` | **Named slot** inside **`card-footer`**, only when **`time`** is set. **Default** slot content is the formatted timestamp row (clock icon + Day.js output). If you supply **slotted** content for `card-footer`, it **replaces** that default (standard slot behavior), while the outer `<footer class="card-footer">` wrapper remains. |
+
+### Typings (`types/webcomponent.type.d.ts`)
+
+```ts
+export type Component = {
+  id?: string;
+  style?: string;
+  title?: string;
+  description?: string;
+  videosrc: string;
+  provider?: "youtube" | "";
+  pageuri?: string;
+  linklabel?: string;
+  time?: Date;
+  dateformat?: string;
+};
+
+export type Events = {};
+```
+
+Use this shape for TypeScript wrappers, Storybook args, or casts when querying the host element. Remember that **DOM attributes are still strings** at the boundary even when typings use `Date` for `time`.
+
+### Example
+
+**Native MP4**
 
 ```html
 <hb-card-video
-  videosrc="https://example.com/media/clip.mp4"
+  videosrc="https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4"
   title="Product tour"
   description="A short walkthrough of the dashboard."
   time="2026-03-01T12:00:00.000Z"
   dateformat="MMM D, YYYY"
+  pageuri="https://example.com/posts/product-tour"
+  linklabel="Open post"
+></hb-card-video>
+```
+
+**YouTube embed**
+
+```html
+<hb-card-video
+  videosrc="https://www.youtube.com/embed/dQw4w9WgXcQ"
+  provider="youtube"
+  title="Sample clip"
+  description="Embedded iframe player."
+  time="2024-01-01T12:00:00.000Z"
 ></hb-card-video>
 ```

package/manifest.json

@@ -105,14 +105,39 @@
     }
   },
   "styleSetup": {
-    "vars": [],
+    "vars": [
+      {
+        "name": "--bulma-black",
+        "valueType": "color",
+        "defaultValue": "#000",
+        "description": "Background behind the 16:9 media frame (`.has-background-black` on the video area)."
+      },
+      {
+        "name": "--bulma-primary",
+        "valueType": "color",
+        "defaultValue": "#00d1b2",
+        "description": "Primary “read more” / action `button is-primary` styling."
+      },
+      {
+        "name": "--bulma-text",
+        "valueType": "color",
+        "defaultValue": "#363636",
+        "description": "Card title and body copy."
+      },
+      {
+        "name": "--bulma-link",
+        "valueType": "color",
+        "defaultValue": "#485fc7",
+        "description": "Link-styled controls in the card content when used."
+      }
+    ],
     "parts": []
   },
   "contributors": [],
   "htmlSlots": [
     {
       "name": "card-footer",
-      "description": ""
+      "description": "Extra actions or metadata below the default footer (timestamp row and share placeholders); appends inside the Bulma `card-footer`."
     }
   ],
   "i18n": [],
@@ -180,5 +205,5 @@
   "size": {},
   "iifePath": "main.iife.js",
   "repoName": "@htmlbricks/hb-card-video",
-  "version": "0.71.35"
+  "version": "0.71.36"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@htmlbricks/hb-card-video",
-  "version": "0.71.35",
+  "version": "0.71.36",
   "contributors": [],
   "description": "Bulma `card` with a 16:9 `image` frame: YouTube embed when `provider` is `youtube`, otherwise an HTML5 `<video>` with MP4 source. Optional title, truncated description (100 chars), formatted `time` via Day.js (`dateformat`), “read more” primary button, and social share placeholders (Facebook/Twitter widgets) when `pageuri` is set.",
   "licenses": [