@htmlbricks/hb-calendar-events 0.71.35 → 0.71.36

package/README.md

@@ -1,45 +1,186 @@
-## `hb-calendar-events` — calendar-events
+# `hb-calendar-events` (calendar-events)
 
-**Category:** calendar | **Tags:** calendar
+**Category:** calendar · **Tags:** calendar · **Package:** `@htmlbricks/hb-calendar-events`
 
-### What it does
+## Summary
 
-Classic month grid (7-day week header and variable rows) with selectable cells, “today” styling, and event chips inside each day. Supports adjacent-month padding cells, Italian holidays, JSON `events`, and the same navigation/selection events as the appointments calendar.
+`hb-calendar-events` is a Bulma-styled **month calendar** rendered as a full-width table: a **localized weekday header** (short names, order **Monday → Sunday**), a **variable number of week rows**, and **per-day cells** that can show **muted “padding” days** from the previous/next month. Users can **change the visible month**, **select a day** (current month or padding cells), and **click small event chips** mapped from a JSON `events` list. The component dispatches **`changeCalendarDate`**, **`changeSelectedDate`**, and **`calendarEventClick`** on the host for integration with host apps or sibling calendars.
 
-### Custom element
+---
 
-`hb-calendar-events`
+## Behavior
 
-### Attributes / props (snake_case)
+- **Visible month** is anchored by the `date` prop: internally, `month`/`year` are derived from that value. The default is **the first day of the current month** (`dayjs().startOf("month")`).
+- **Header** (month title + prev/next controls) is shown unless `disable_header` is enabled. Prev/next call `changeMonth(±1)`, update `date`, and dispatch **`changeCalendarDate`** with `{ date }` (a `Date` for the new month anchor).
+- **Weekday labels** use `Intl.DateTimeFormat` with `weekday: "short"` and the browser’s primary language (`navigator.languages[0]`, falling back to `"en"`). **Column order** is fixed in markup as Mon–Sat from `startOf("week") + 1..6` days and **Sunday** in the last column (`startOf("week")`).
+- **Grid size**: `rows = ceil((daysInMonth + dayOfWeekOfMonthStart) / 7)` where `dayOfWeek` follows **dayjs**’s `day()` (0 = Sunday … 6 = Saturday). The first row mixes **previous-month** padding cells and **current-month** days; the last row mixes **current-month** days and **next-month** padding cells; middle rows are **only** current month.
+- **Day selection**: clicking a `<td>` (cell) sets `selected` to the logical calendar date for that cell and dispatches **`changeSelectedDate`** with `{ selectedDate }`. **Padding cells** select dates in the adjacent month (previous or next), not only the visible month.
+- **Events**: optional `events` array is **filtered per month** for the visible month, previous month, and next month so padding cells can still show chips for events that fall on those dates. For each day, chips match events whose **calendar day** (`DD`) equals the cell’s day number in the **month that cell represents** (current, previous, or next). Each chip is a `<button>`; its click handler dispatches **`calendarEventClick`** with `{ eventId }` (the event’s `id` string). Chip **`onclick` does not stop propagation**; hosts that also listen on the cell should account for possible bubbling if they attach listeners outside the shadow root.
+- **`IEvent.link` and `IEvent.icon`** exist in typings but are **not used** in the current template (no link or icon rendering).
+- **`date-holidays`**: the module is imported and `new Holidays("IT")` is constructed, but **no holiday data is read or displayed** in the current markup—do not rely on Italian public holidays in the UI until that logic is wired.
 
-| Property | Type | Notes |
-| --- | --- | --- |
-| `id` | string (optional) | Element identifier. |
-| `style` | string (optional) | Inline style string. |
-| `date` | Date (optional) | Visible month anchor. |
-| `events` | array (optional) | JSON array of `{ date: Date; label: string; id: string; link?; icon?; color? }`. |
-| `selected` | Date (optional) | Highlighted date. |
-| `disable_header` | boolean (optional) | Hide month navigation when true. |
+### `disable_header` coercion
 
-**Theme:** `--hb-calendar-selected`, `--hb-calendar-hover`, `--hb-calendar-today`. **Parts:** `calendar-header`, `calendar-current-time-header`, `cell`. **Slots:** `header_month_icon_prev`, `header_month_icon_next`, `header`, `calendar_month`.
+Inside `$effect`, if `disable_header` is a string, it is treated as **true** when (case-insensitive) `"true"` or `"yes"`, or when the string is **empty** `""`; otherwise **false**. From HTML attributes, expect the usual **string** forms your custom-element layer maps to this prop.
 
-### Events (`CustomEvent` names)
+### `events` and `selected` coercion
 
-- **`calendarEventClick`** — `{ eventId: string }`
-- **`changeCalendarDate`** — `{ date: Date }`
-- **`changeSelectedDate`** — `{ selectedDate: Date }`
+- If `events` is a **string**, it is **`JSON.parse`d** into an array (invalid JSON will throw at runtime).
+- If `selected` is a **string**, it is parsed with **`dayjs(selected).toDate()`** (pass a value dayjs understands, e.g. ISO 8601).
 
-### Usage notes
+---
 
-- Styling aligns with Bootstrap-themed CSS variables on the host.
-- Shares behavior with `hb-calendar-appointments` for events and navigation.
-- Shadow DOM + parts allow styling cells and headers.
-- No i18n entries in `docs.ts`; holidays skew Italian.
+## Graphics and layout
 
-### Minimal HTML example
+- **Structure**: Optional header `div` (`part="calendar-header"`) plus a **single `<table class="table is-fullwidth hb-calendar-table">`** with `<thead>` (weekdays) and `<tbody>` (day rows).
+- **Table**: `width: 100%`, `height: 100%`, `table-layout: fixed`, `min-height: 34.375rem`, `border-collapse: collapse`. Each **day cell** has `vertical-align: baseline`, a **1px** border using `--hb-calendar-cell-border`, and **row height** split evenly via inline `style="height: {100/rows}%;"` on `<td>`.
+- **Header** (when enabled): flex row with spacing (`is-flex`, `is-justify-content-space-between`, etc.), default **month + year** text in a title-sized span, and default **small light buttons** `˂` / `˃` for prev/next unless slots override.
+- **Cells**: day number in a `.cell-date` div; **padding** days use **`.cell-date-muted`**. **Today** adds **`.cell-today`** (accent color + bold). **Selected** adds **`.cell-selected`** (background). **Hover** on any `<td>` uses `--hb-calendar-hover`.
+- **Event chips**: `.cell-event` buttons, full width of the cell, stacked; default background `--hb-calendar-event-button-color` and text `--bulma-white-bis`. If `event.color` is set, inline `background-color` (and transparent border) override the default chip background.
+
+---
+
+## Logic (implementation notes)
+
+| Concern | Implementation |
+|--------|------------------|
+| Month navigation | `changeMonth` mutates `date`, then `dispatch("changeCalendarDate", { date })`. |
+| Event lists | `$derived` filters: `monthsEvent`, `previousMonthEvents`, `nextMonthEvents` by `M` + `YYYY` of `f.date`. |
+| Cell click vs chip | Cell `onclick` → `selectDay(...)`; chip `onclick` → `calendarEventClick({ eventId })`. |
+| `id` prop | Normalized in `$effect` to `""` when falsy; used as a conventional element id hook if your layer sets it. |
+
+**Note:** The `$effect` block contains `if (typeof date === "string") dayjs(date).startOf("month").toDate();` **without assigning** the result to `date`. Prefer supplying **`date` as a `Date`** (or rely on your framework’s property deserialization) for a predictable visible month.
+
+---
+
+## Custom element tag
+
+```text
+hb-calendar-events
+```
+
+---
+
+## Properties / attributes (snake_case)
+
+From **`types/webcomponent.type.d.ts`**. In plain HTML, **attributes are strings**; booleans are typically **`yes` / `no`** in this project’s web-component conventions—**and** this component’s `$effect` accepts string forms for `disable_header` as described above. **`events`** should be a **JSON string** representing an array of event objects.
+
+| Name | Type (authoring) | Role |
+|------|------------------|------|
+| `id` | `string` (optional) | Optional identifier; coerced to `""` when missing in `$effect`. |
+| `style` | `string` (optional) | Standard host inline style passthrough (Svelte / element `style`). |
+| `date` | `Date` (optional) | Month anchor; default start of **current** month. Prefer a real `Date` instance. |
+| `events` | `IEvent[]` or JSON **string** | Events to show as chips; optional. Parsed from string when needed. |
+| `selected` | `Date` or parseable **string** (optional) | Highlights the matching day (including padding months). |
+| `disable_header` | `boolean` or string (optional) | When true, the entire header block (nav + slots) is omitted. |
+
+### `IEvent` shape (each item in `events`)
+
+| Field | Required | Notes |
+|-------|----------|--------|
+| `date` | yes | Event occurrence; matched by month/year/day for chip placement. |
+| `label` | yes | Chip button text. |
+| `id` | yes | Passed back as `eventId` in **`calendarEventClick`**. |
+| `link` | no | Typing only; not rendered. |
+| `icon` | no | Typing only; not rendered. |
+| `color` | no | If set, applied as inline `background-color` on the chip. |
+
+---
+
+## Events (host `CustomEvent`)
+
+All dispatched on the **custom element host** via `new CustomEvent(name, { detail })`, so by default they **do not bubble** and are **not composed** through the shadow boundary—listen on the **`hb-calendar-events` element** itself.
+
+| Event name | `detail` (TypeScript) | When |
+|------------|------------------------|------|
+| `calendarEventClick` | `{ eventId: string }` | User activates an event chip (`id` → `eventId`). |
+| `changeCalendarDate` | `{ date: Date }` | Visible month changes (prev/next). |
+| `changeSelectedDate` | `{ selectedDate: Date }` | User selects a day cell (any row, including padding). |
+
+---
+
+## CSS custom properties
+
+Documented in **`extra/docs.ts`** (`styleSetup.vars`); defaults in **`styles/webcomponent.scss`** fall back to Bulma tokens.
+
+| Variable | Role |
+|----------|------|
+| `--hb-calendar-event-button-color` | Default background for event chips (default: `--bulma-link`). |
+| `--hb-calendar-cell-border` | 1px cell border color (default: `--bulma-border`). |
+| `--hb-calendar-hover` | `<td>` hover background (default: `--bulma-background-lighter`). |
+| `--hb-calendar-selected` | Selected cell background (default: `--bulma-info`). |
+| `--hb-calendar-today` | “Today” day number color (default: `--bulma-primary`). |
+| `--bulma-radius` | Chip border radius (docs default `0.375rem`; SCSS fallback `0.25rem`). |
+| `--bulma-white-bis` | Chip text on default chip background. |
+| `--bulma-text-weak` | Muted weekday header tone. |
+
+---
+
+## CSS parts (`::part`)
+
+| Part | Target |
+|------|--------|
+| `calendar-header` | Outer header strip (month navigation area). |
+| `calendar-current-time-header` | Inner span wrapping the default month/year line (and `calendar_month` slot). |
+| `cell` | Each day `<td>` in the grid (current, padding, selected, today). |
+
+---
+
+## Slots
+
+Names and descriptions match **`extra/docs.ts`** (`htmlSlots`).
+
+| Slot | Purpose |
+|------|---------|
+| `header` | Wraps default header content: replace entire header row layout while keeping the outer `calendar-header` part on the parent when `disable_header` is false. |
+| `calendar_month` | Replace the default **month name + year** text inside the title span. |
+| `header_month_icon_prev` | Replace default **previous month** control (default: small `˂` button). |
+| `header_month_icon_next` | Replace default **next month** control (default: small `˃` button). |
+
+---
+
+## Typings
+
+Authoring types for consumers and wrappers live in:
+
+`src/wc/calendar-events/types/webcomponent.type.d.ts`
+
+- **`IEvent`** — one calendar entry (date, label, id, optional link/icon/color).
+- **`Component`** — props: `id`, `style`, `date`, `events`, `selected`, `disable_header`.
+- **`Events`** — maps custom event names to their `detail` shapes: `calendarEventClick`, `changeCalendarDate`, `changeSelectedDate`.
+
+After a full web-component build, generated DOM / Svelte element typings may also list this tag under `types/html-elements.d.ts` and `types/svelte-elements.d.ts` in the package output.
+
+---
+
+## Minimal example
 
 ```html
 <hb-calendar-events
-  events='[{"id":"a","label":"Launch","date":"2026-03-01T09:00:00.000Z","color":"#0d6efd"}]'
+  events='[{"id":"launch","label":"Launch","date":"2026-03-15T10:00:00.000Z"}]'
 ></hb-calendar-events>
 ```
+
+With **explicit month anchor**, **selection**, **no header**, and a listener (vanilla JS):
+
+```html
+<hb-calendar-events
+  id="cal-1"
+  disable_header="yes"
+  date="2026-03-01T00:00:00.000Z"
+  selected="2026-03-15T00:00:00.000Z"
+  events='[{"id":"a","label":"Ship","date":"2026-03-15T12:00:00.000Z","color":"#2574fc"}]'
+></hb-calendar-events>
+
+<script>
+  const el = document.getElementById("cal-1");
+  el.addEventListener("changeSelectedDate", (e) => {
+    console.log("selected", e.detail.selectedDate);
+  });
+  el.addEventListener("calendarEventClick", (e) => {
+    console.log("event", e.detail.eventId);
+  });
+</script>
+```
+
+Adjust attribute serialization (`yes`/`no`, JSON escaping) to match how your **custom element** layer maps host attributes to component props.

package/manifest.json

@@ -158,49 +158,84 @@
       {
         "name": "--hb-calendar-event-button-color",
         "valueType": "color",
-        "defaultValue": ""
+        "defaultValue": "(from `--bulma-link`)",
+        "description": "Background for event chips inside day cells; defaults to `--bulma-link` on `:host`."
+      },
+      {
+        "name": "--hb-calendar-cell-border",
+        "valueType": "color",
+        "defaultValue": "(from `--bulma-border`)",
+        "description": "1px border around each day cell in the month grid."
       },
       {
         "name": "--hb-calendar-hover",
-        "valueType": "string",
-        "defaultValue": ""
+        "valueType": "color",
+        "defaultValue": "(from `--bulma-background-lighter`)",
+        "description": "Background when hovering a selectable day cell."
       },
       {
         "name": "--hb-calendar-selected",
-        "valueType": "string",
-        "defaultValue": ""
+        "valueType": "color",
+        "defaultValue": "(from `--bulma-info`)",
+        "description": "Background for the currently selected day cell."
       },
       {
         "name": "--hb-calendar-today",
-        "valueType": "string",
-        "defaultValue": ""
+        "valueType": "color",
+        "defaultValue": "(from `--bulma-primary`)",
+        "description": "Accent color for the “today” day number in the grid."
+      },
+      {
+        "name": "--bulma-radius",
+        "valueType": "number",
+        "defaultValue": "0.375rem",
+        "description": "Corner radius for event chips inside cells."
+      },
+      {
+        "name": "--bulma-white-bis",
+        "valueType": "color",
+        "defaultValue": "(theme)",
+        "description": "Chip text color on top of `--hb-calendar-event-button-color`."
+      },
+      {
+        "name": "--bulma-text-weak",
+        "valueType": "color",
+        "defaultValue": "(theme)",
+        "description": "Muted weekday labels in the week header row."
       }
     ],
     "parts": [
       {
-        "name": "calendar-header"
+        "name": "calendar-header",
+        "description": "Outer header strip (month navigation and title); same part name as the appointments calendar."
       },
       {
-        "name": "calendar-current-time-header"
+        "name": "calendar-current-time-header",
+        "description": "Month label row and navigation slot targets."
       },
       {
-        "name": "cell"
+        "name": "cell",
+        "description": "Individual day cell in the grid (padding days, current month, today, and selected states)."
       }
     ]
   },
   "contributors": [],
   "htmlSlots": [
     {
-      "name": "header_month_icon_prev"
+      "name": "header_month_icon_prev",
+      "description": "Custom “previous month” control in the header."
     },
     {
-      "name": "header_month_icon_next"
+      "name": "header_month_icon_next",
+      "description": "Custom “next month” control in the header."
     },
     {
-      "name": "header"
+      "name": "header",
+      "description": "Optional content above the month line in the header."
     },
     {
-      "name": "calendar_month"
+      "name": "calendar_month",
+      "description": "Custom month / year label next to navigation controls."
     }
   ],
   "i18n": [],
@@ -216,12 +251,12 @@
       "data": {
         "events": [
           {
-            "date": "2026-04-16T23:22:18.402Z",
+            "date": "2026-04-17T00:13:27.147Z",
             "id": "test",
             "label": "thetest"
           },
           {
-            "date": "2026-03-30T23:22:18.402Z",
+            "date": "2026-03-31T00:13:27.147Z",
             "id": "test2",
             "label": "thetest start",
             "color": "red"
@@ -242,12 +277,12 @@
       "data": {
         "events": [
           {
-            "date": "2026-04-16T23:22:18.402Z",
+            "date": "2026-04-17T00:13:27.147Z",
             "id": "test",
             "label": "thetest"
           },
           {
-            "date": "2026-03-30T23:22:18.402Z",
+            "date": "2026-03-31T00:13:27.147Z",
             "id": "test2",
             "label": "thetest start",
             "color": "red"
@@ -277,5 +312,5 @@
   "size": {},
   "iifePath": "main.iife.js",
   "repoName": "@htmlbricks/hb-calendar-events",
-  "version": "0.71.35"
+  "version": "0.71.36"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@htmlbricks/hb-calendar-events",
-  "version": "0.71.35",
+  "version": "0.71.36",
   "contributors": [],
   "description": "Classic month grid (7-day week header and variable rows) with selectable cells, “today” styling, and event chips inside each day. Supports adjacent-month padding cells, Italian holidays, JSON `events`, and the same navigation/selection events as the appointments calendar (`changeCalendarDate`, `changeSelectedDate`, `calendarEventClick`).",
   "licenses": [