@htmlbricks/hb-calendar-appointments 0.71.34 → 0.71.36

package/README.md

@@ -1,46 +1,147 @@
-## `hb-calendar-appointments` — calendar-appointments
+# `hb-calendar-appointments`
 
-**Category:** calendar | **Tags:** calendar, appointments
+**Category:** calendar · **Tags:** calendar, appointments
 
-### What it does
+## Summary
 
-Month agenda view: events for the current month are grouped by calendar day and listed chronologically with weekday, day number, time, and colored markers. Optional header with month navigation; changing month or selecting a day dispatches `changeCalendarDate`, `changeSelectedDate`, and clicking a row dispatches `calendarEventClick`. Uses Italian public holidays metadata; `events` is supplied as JSON.
+A **month agenda** web component: it shows **only events in the visible month**, grouped **by calendar day**, with **per-day headings** and **clickable rows** for each appointment. An optional **header** switches the month and exposes slots for labels and navigation chrome.
 
-### Custom element
+## What it does
 
-`hb-calendar-appointments`
+- Filters `events` to the month implied by `date` (month + year).
+- Sorts events by `date` when `events` is parsed from a string.
+- Renders one block per day that has at least one event: weekday (long, locale from `navigator.languages[0]` or `en`), day-of-month number, then rows ordered as in the sorted list.
+- Each row shows a Bootstrap Icons dot (`bi-dot`), time (`HH:mm`), and `label`; optional per-event `color` overrides the icon color via inline style.
+- Month navigation (`disable_header` off) updates `date` and emits **`changeCalendarDate`**.
+- Row click emits **`calendarEventClick`** with the event `id`.
 
-### Attributes / props (snake_case)
+The `date-holidays` package is imported and an `IT` instance is constructed in script, but **that object is not used** anywhere in the template or derived data (no holiday-based labels or filtering in the current implementation).
 
-| Property | Type | Notes |
-| --- | --- | --- |
-| `id` | string (optional) | Element identifier. |
-| `style` | string (optional) | Inline style string. |
-| `date` | Date (optional) | Current calendar month context; pass as ISO string / parsed JSON in HTML. |
-| `events` | array (optional) | JSON array of `{ date: Date; label: string; id: string; link?; icon?; color? }`. |
-| `selected` | Date (optional) | Selected day. |
-| `disable_header` | boolean (optional) | Hide the navigation header when true. |
+## UI / layout
 
-**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`.
+| Region | Behavior |
+|--------|------------|
+| **Header** (optional) | Flex row: default title (month name + year via `Intl` + `dayjs`), prev/next controls. Wrapped in `part="calendar-header"`. Inner title span uses `part="calendar-current-time-header"`. Entire header hidden when `disable_header` is enabled (see logic below). |
+| **Slots in header** | `header` wraps title + nav; `calendar_month` replaces default month/year text; `header_month_icon_prev` / `header_month_icon_next` replace default buttons (still wired to `changeMonth(-1)` / `changeMonth(1)` via outer `onclick`). |
+| **Agenda list** | Under `#appointments_container`: for each day bucket, a bold day line (`events_day`) then `event_row` blocks (focusable `role="button"`). If the month has no events, the list area is empty (no placeholder). |
 
-### Events (`CustomEvent` names)
+Icons are loaded for the shadow tree via `styles/webcomponent.scss` (Bootstrap Icons font). A `<svelte:head>` stylesheet link is also present but does not apply inside shadow DOM by itself.
 
-- **`calendarEventClick`** — `{ eventId: string }`
-- **`changeCalendarDate`** — `{ date: Date }`
-- **`changeSelectedDate`** — `{ selectedDate: Date }`
+## Logic
 
-### Usage notes
+- **Visible month:** `month` / `year` derived from `date` (`dayjs`).
+- **Filtering:** `monthsEvent` keeps events whose month and year match `date`.
+- **Grouping:** `eventsOfThisMonthByDay` buckets by day-of-month (`D`); first occurrence of a day creates the bucket, further events append to that bucket’s array.
+- **`disable_header`:** In `$effect`, string values are normalized: `true` / `yes` / `""` (empty) → header hidden; otherwise shown.
+- **`events`:** If a string, `JSON.parse`; then sorted ascending by `new Date(a.date)` vs `new Date(b.date)`.
+- **`selected`:** If a string, parsed with `dayjs(selected).toDate()` for in-component use. There is a **`selectDay`** helper that sets `selected` and would emit **`changeSelectedDate`**, but **nothing in the default markup calls `selectDay`**, so that event is **not** produced by the shipped UI (only the typed API / future wiring).
 
-- Bootstrap 5–oriented colors via CSS variables above.
-- Italian holiday data is built in; adjust expectations for non-IT locales.
-- Shadow DOM exposes named parts for deeper styling.
-- Pass `events` and dates as JSON strings from HTML attributes; runtime parsing depends on the web component bridge.
+## Custom element
 
-### Minimal HTML example
+```text
+hb-calendar-appointments
+```
+
+## Attributes / properties
+
+HTML attributes are strings. Align with your bridge; the component’s `$effect` coerces some values.
+
+| Name | Typing (`Component`) | Notes |
+|------|----------------------|--------|
+| `id` | `string` (optional) | Passed through like other props; host `id` if set as attribute. |
+| `style` | `string` (optional) | Present in authoring types; not destructured in `component.wc.svelte` (host styling may still apply as a native attribute). |
+| `date` | `Date` (optional) | Default: start of current month (`dayjs().startOf("month")`). Drives which month’s events are shown. From HTML, use an ISO-like string your runtime parses to `Date` / or set the property in JS. |
+| `events` | `IEvent[]` (optional) | JSON array string from attributes; each item: `date`, `label`, `id` required for useful rows; `link`, `icon`, `color` optional (`link` / `icon` are **not read** by the template). |
+| `selected` | `Date` (optional) | Parsed from string in `$effect`. No built-in control updates selection or emits `changeSelectedDate`. |
+| `disable_header` | `boolean` (optional) | Default `false`. For attributes, this codebase often uses **`yes`** / **`no`**; the effect also treats string `"true"`, `"yes"`, and `""` as hide header. |
+
+### `IEvent` (from typings)
+
+| Field | Type | Used in UI |
+|-------|------|------------|
+| `date` | `Date` | Filter, sort, time column, weekday/day grouping |
+| `label` | `string` | Row text (`aria-label`, visible label) |
+| `id` | `string` | `calendarEventClick` payload |
+| `link` | optional `string` | No |
+| `icon` | optional `string` | No |
+| `color` | optional `string` | Icon color (inline `style`) |
+
+## Events (`CustomEvent`)
+
+| Name | `detail` | When emitted (current implementation) |
+|------|-----------|----------------------------------------|
+| `calendarEventClick` | `{ eventId: string }` | User activates an `.event_row` (click path in template). |
+| `changeCalendarDate` | `{ date: Date }` | Prev/next month navigation runs `changeMonth`. |
+| `changeSelectedDate` | `{ selectedDate: Date }` | Only if something called `selectDay` — **not wired** in the default Svelte markup. |
+
+## Styling
+
+### CSS custom properties
+
+Documented in `extra/docs.ts`; defaults from code (`styles/webcomponent.scss` + descriptions in docs):
+
+| Variable | Kind | Default / source | Role |
+|----------|------|-------------------|------|
+| `--hb-calendar-event-button-color` | color | `var(--bulma-link, #485fc7)` on `:host` | Dot icon color when `event.color` is not set. |
+| `--bulma-radius` | size | theme / `0.25rem` fallback in SCSS | `border-radius` on `.event_row`. |
+| `--bulma-border` | color | theme / `hsl(0deg 0% 86%)` fallback | `outline` on `.event_row:hover`. |
+
+### CSS parts (`::part`)
+
+| Part | Description |
+|------|-------------|
+| `calendar-header` | Outer header strip (month navigation + title area). |
+| `calendar-current-time-header` | Inner title span (month slot + default month/year text). |
+
+## Slots
+
+| Slot | Description |
+|------|-------------|
+| `header_month_icon_prev` | Replace default “previous month” control (e.g. icon button). |
+| `header_month_icon_next` | Replace default “next month” control. |
+| `header` | Wraps the whole header row (title + nav); default fills month + controls. |
+| `calendar_month` | Replace/wrap visible month/year label in the header row. |
+
+## Typings
+
+Authoring types live in `types/webcomponent.type.d.ts`:
+
+- **`Component`** — `id`, `style`, `date`, `events`, `selected`, `disable_header`
+- **`IEvent`** — event record shape
+- **`Events`** — `calendarEventClick`, `changeCalendarDate`, `changeSelectedDate`
+
+Built outputs (`types/html-elements.d.ts`, `types/svelte-elements.d.ts`) are regenerated with `npm run build:wc`.
+
+## Example HTML
 
 ```html
 <hb-calendar-appointments
-  disable_header="false"
+  id="agenda-1"
+  disable_header="no"
+  date="2026-04-01T00:00:00.000Z"
+  events='[
+    {"id":"a1","label":"Stand-up","date":"2026-04-17T09:00:00.000Z"},
+    {"id":"a2","label":"Review","date":"2026-04-17T15:30:00.000Z","color":"#b86bff"}
+  ]'
+></hb-calendar-appointments>
+```
+
+With hidden header:
+
+```html
+<hb-calendar-appointments
+  disable_header="yes"
   events='[{"id":"1","label":"Meeting","date":"2026-03-15T10:00:00.000Z"}]'
 ></hb-calendar-appointments>
 ```
+
+Listen in JavaScript, for example:
+
+```js
+document.querySelector("hb-calendar-appointments")?.addEventListener("calendarEventClick", (e) => {
+  console.log(e.detail.eventId);
+});
+document.querySelector("hb-calendar-appointments")?.addEventListener("changeCalendarDate", (e) => {
+  console.log(e.detail.date);
+});
+```

package/manifest.json

@@ -158,35 +158,50 @@
       {
         "name": "--hb-calendar-event-button-color",
         "valueType": "color",
-        "defaultValue": "",
-        "description": "Default dot color for events; falls back to `--bulma-link` when unset."
+        "defaultValue": "(from `--bulma-link`)",
+        "description": "Color for the event marker icon (Bootstrap Icon) in each row; host default on `:host` maps to `--bulma-link`."
+      },
+      {
+        "name": "--bulma-radius",
+        "valueType": "number",
+        "defaultValue": "0.375rem",
+        "description": "Corner radius for interactive event rows on hover."
+      },
+      {
+        "name": "--bulma-border",
+        "valueType": "color",
+        "defaultValue": "(theme)",
+        "description": "Outline color for hovered event rows."
       }
     ],
     "parts": [
       {
-        "name": "calendar-header"
-      },
-      {
-        "name": "calendar-current-time-header"
+        "name": "calendar-header",
+        "description": "Outer header strip (month navigation and title); style layout and chrome of the top bar."
       },
       {
-        "name": "cell"
+        "name": "calendar-current-time-header",
+        "description": "Inner header row showing the current month label and controls next to the navigation slots."
       }
     ]
   },
   "contributors": [],
   "htmlSlots": [
     {
-      "name": "header_month_icon_prev"
+      "name": "header_month_icon_prev",
+      "description": "Previous-month control inside the header (e.g. custom chevron or icon button)."
     },
     {
-      "name": "header_month_icon_next"
+      "name": "header_month_icon_next",
+      "description": "Next-month control inside the header (e.g. custom chevron or icon button)."
     },
     {
-      "name": "header"
+      "name": "header",
+      "description": "Optional content above the month line; wraps the default title when empty."
     },
     {
-      "name": "calendar_month"
+      "name": "calendar_month",
+      "description": "Replace or wrap the visible month / year label in the header row."
     }
   ],
   "i18n": [],
@@ -197,12 +212,12 @@
       "data": {
         "events": [
           {
-            "date": "2026-04-16T23:11:50.599Z",
+            "date": "2026-04-17T00:13:29.971Z",
             "id": "test",
             "label": "thetest"
           },
           {
-            "date": "2026-03-30T23:11:50.599Z",
+            "date": "2026-03-31T00:13:29.971Z",
             "id": "test2",
             "label": "thetest start",
             "color": "red"
@@ -223,12 +238,12 @@
       "data": {
         "events": [
           {
-            "date": "2026-04-16T23:11:50.599Z",
+            "date": "2026-04-17T00:13:29.971Z",
             "id": "test",
             "label": "thetest"
           },
           {
-            "date": "2026-03-30T23:11:50.599Z",
+            "date": "2026-03-31T00:13:29.971Z",
             "id": "test2",
             "label": "thetest start",
             "color": "red"
@@ -243,18 +258,18 @@
       "data": {
         "events": [
           {
-            "date": "2026-04-16T23:11:50.599Z",
+            "date": "2026-04-17T00:13:29.971Z",
             "id": "test",
             "label": "thetest"
           },
           {
-            "date": "2026-03-30T23:11:50.599Z",
+            "date": "2026-03-31T00:13:29.971Z",
             "id": "test2",
             "label": "thetest start",
             "color": "red"
           }
         ],
-        "selected": "2026-04-16T23:11:50.599Z"
+        "selected": "2026-04-17T00:13:29.971Z"
       }
     }
   ],
@@ -279,5 +294,5 @@
   "size": {},
   "iifePath": "main.iife.js",
   "repoName": "@htmlbricks/hb-calendar-appointments",
-  "version": "0.71.34"
+  "version": "0.71.36"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@htmlbricks/hb-calendar-appointments",
-  "version": "0.71.34",
+  "version": "0.71.36",
   "contributors": [],
   "description": "Month agenda view: events for the current month are grouped by calendar day and listed chronologically with weekday, day number, time, and colored markers. Optional header with month navigation; changing month or selecting a day dispatches `changeCalendarDate`, `changeSelectedDate`, and clicking a row dispatches `calendarEventClick`. Uses Italian public holidays metadata and accepts `events` as JSON.",
   "licenses": [