hb-calendar-events (calendar-events)

Category: calendar · Tags: calendar · Package: @htmlbricks/hb-calendar-events

Summary

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.

Behavior

• 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.

disable_header coercion

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 and selected coercion

• If events is a string, it is JSON.parsed 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).

Graphics and layout

• 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

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. | | 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, 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

<hb-calendar-events
  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):

<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.