feat: add CATEGORIES support

- parse `categories` into a string array on each event object
- add `category-{slug}` CSS classes + `data-categories` attribute on event DOM
- colour-coded left border + background tint for common category names
- document in Event-Object.md and Styling.md; add 3 unit tests

closes #86

Author: KristjanESPERANTO

CALEXT2_Event.js

@@ -123,6 +123,7 @@ class Event {
     eventDom.dataset.title = event.title;
     eventDom.dataset.location = event.location;
     eventDom.dataset.busystatus = event.ms_busystatus;
+    Event.applyCategories(event, eventDom, null);
 
     const mainDom = document.createElement("div");
     mainDom.classList.add("eventMain");
@@ -150,6 +151,7 @@ class Event {
     location.classList.add("eventLocation");
     location.innerHTML = event.location;
     subDom.appendChild(location);
+    Event.applyCategories(event, null, subDom);
 
     // Add attendees if present and enabled
     if (this.showAttendees && event.attendees && event.attendees.length > 0) {
@@ -178,6 +180,34 @@ class Event {
     return eventDom;
   }
 
+  /**
+   * Applies category CSS classes and data-attribute to eventDom,
+   * and appends an eventCategories div to subDom.
+   * Pass null for targetDom or slotDom to skip that part.
+   * @param {object} event - The event data object
+   * @param {HTMLElement|null} targetDom - The event wrapper element
+   * @param {HTMLElement|null} slotDom - The sub-content element
+   */
+  static applyCategories (event, targetDom, slotDom) {
+    const cats = Array.isArray(event.categories) ? event.categories : [];
+    if (targetDom) {
+      for (const cat of cats) {
+        if (cat) {
+          targetDom.classList.add(`category-${cat.toLowerCase().replace(/[^a-z0-9]+/gu, "-").replace(/^-|-$/gu, "")}`);
+        }
+      }
+
+      targetDom.dataset.categories = cats.join(",");
+    }
+
+    if (slotDom && cats.length > 0) {
+      const categoriesDom = document.createElement("div");
+      categoriesDom.classList.add("eventCategories");
+      categoriesDom.innerHTML = cats.join(", ");
+      slotDom.appendChild(categoriesDom);
+    }
+  }
+
   createEventTime () {
     const {locale} = this;
     const event = this.data;

MMM-CalendarExt2.css

@@ -489,3 +489,57 @@
   color: #000;
   text-shadow: 0 0 2px rgb(255 255 255 / 50%);
 }
+
+/** CSS for categories **/
+.CX2 .eventCategories {
+  font-size: 0.85em;
+  margin-top: 4px;
+  opacity: 0.75;
+  font-style: italic;
+}
+
+/* Category color coding via left border + tint – visible in all view modes */
+.CX2 .event[class*="category-"] {
+  border-left: 5px solid transparent;
+}
+
+.CX2 .event.category-work {
+  border-left-color: #2196f3;
+  background-color: rgb(33 150 243 / 12%);
+}
+
+.CX2 .event.category-leisure {
+  border-left-color: #ff9800;
+  background-color: rgb(255 152 0 / 12%);
+}
+
+.CX2 .event.category-deadline {
+  border-left-color: #ff5722;
+  background-color: rgb(255 87 34 / 12%);
+}
+
+.CX2 .event.category-family {
+  border-left-color: #9c27b0;
+  background-color: rgb(156 39 176 / 12%);
+}
+
+.CX2 .event.category-birthday {
+  border-left-color: #e91e63;
+  background-color: rgb(233 30 99 / 12%);
+}
+
+.CX2 .event.category-health {
+  border-left-color: #4caf50;
+  background-color: rgb(76 175 80 / 12%);
+}
+
+.CX2 .event.category-vacation {
+  border-left-color: #00bcd4;
+  background-color: rgb(0 188 212 / 12%);
+  color: white;
+}
+
+.CX2 .event.category-important {
+  border-left-color: #f44336;
+  background-color: rgb(244 67 54 / 12%);
+}

docs/Event-Object.md

@@ -23,6 +23,7 @@ startDateJ: "2019-01-04T19:45:00.000Z";
 title: "Team T.B.A. - Tottenham Hotspur";
 uid: "1:1546631100:1546638300:op54vk5s1r0ivl8i165ampip88@google.com";
 ms_busystatus: "BUSY"; // Only for calendar from MS Outlook. Available : "BUSY", "FREE", "TENTATIVE", "OOF"
+categories: ["Work", "Important"]; // Array of category strings from CATEGORIES property; empty array if absent
 ```
 
 You can use these properties for filtering, sorting, or external usage by notification.

docs/Styling.md

@@ -104,3 +104,34 @@ Each event could have these values as dataset.
 - data-duration
 - data-title
 - data-location
+- data-categories (comma-separated list of categories, e.g. `"Work,Important"`)
+
+## category-based styling
+
+Events with a `CATEGORIES` property in the iCal source automatically receive:
+
+- A CSS class `category-{slug}` on the event wrapper (e.g. `category-work`, `category-family`). The slug is the category name lowercased, with non-alphanumeric runs replaced by `-` — so `"Doctor's Appointment"` becomes `category-doctor-s-appointment` and `"Freizeit & Sport"` becomes `category-freizeit-sport`.
+- A `data-categories` attribute containing all categories as a comma-separated string.
+- A `.eventCategories` div inside the event's `eventSub` area (visible in agenda view).
+
+The module ships built-in colour rules for common English category names (`work`, `health`, `vacation`, `leisure`, `family`, `birthday`, `deadline`, `important`). Add your own in `css/custom.css`:
+
+```css
+/* Example – add to css/custom.css */
+.CX2 .event.category-sports {
+  border-left-color: #8bc34a;
+  background-color: rgb(139 195 74 / 12%);
+}
+.CX2 .event.category-finance {
+  border-left-color: #ffc107;
+  background-color: rgb(255 193 7 / 12%);
+}
+```
+
+Because categories are free-form text defined by your calendar, the class is derived from whatever your iCal files contain. The general selector below targets any event that carries at least one category:
+
+```css
+.CX2 .event[class*="category-"] {
+  border-left: 5px solid transparent;
+}
+```

lib/ical-utils.js

@@ -50,6 +50,14 @@ const eventProp = (event, name) => {
   );
 };
 
+const extractCategories = (primary, fallback = {}) => {
+  if (Array.isArray(primary?.categories)) {
+    return primary.categories;
+  }
+
+  return Array.isArray(fallback.categories) ? fallback.categories : [];
+};
+
 const getAllDayDurationSeconds = (startDate, endDate) => {
   const rawDayCount = (endDate.getTime() - startDate.getTime()) / 86400000;
   const dayCount = Math.max(1, Math.round(rawDayCount));
@@ -156,6 +164,7 @@ const parseAndExpandEvents = (iCalData, startDate, endDate, maxIterations = 1000
           duration: durationSeconds,
           status: eventProp(occurrence, "status") || eventProp(occurrenceEvent, "status"),
           ms_busystatus: eventProp(occurrence, "x-microsoft-cdo-busystatus") || eventProp(occurrenceEvent, "x-microsoft-cdo-busystatus"),
+          categories: extractCategories(occurrence, occurrenceEvent),
           attendees: extractAttendees(occurrenceEvent)
         });
       }
@@ -176,6 +185,7 @@ const parseAndExpandEvents = (iCalData, startDate, endDate, maxIterations = 1000
           duration: getDurationSeconds(event),
           status: eventProp(event, "status"),
           ms_busystatus: eventProp(event, "x-microsoft-cdo-busystatus"),
+          categories: extractCategories(event),
           attendees: extractAttendees(event)
         });
       }

node_helper.js

@@ -136,6 +136,7 @@ module.exports = NodeHelper.create({
       ev.title = item.summary;
       ev.isRecurring = item.isRecurring;
       ev.attendees = item.attendees || [];
+      ev.categories = item.categories || [];
       ev.isCancelled = item.status?.toUpperCase() === "CANCELLED";
       if (
         Array.isArray(calendar.replaceTitle) &&

stylelint.config.mjs

@@ -1,4 +1,4 @@
-const pattern = "^(MMM-CalendarExt2|CX2|fake_module|module-content|[a-z][a-zA-Z0-9]+(_\\d+)?)$";
+const pattern = "^(MMM-CalendarExt2|CX2|fake_module|module-content|[a-z][a-zA-Z0-9-]+(_\\d+)?)$";
 const config = {
   "extends": ["stylelint-config-standard", "stylelint-prettier/recommended"],
   "root": true,

test/ical-utils.test.js

@@ -366,3 +366,77 @@ test("exposes status on a recurring occurrence (from parent event)", () => {
     assert.equal(occurrence.status, "CANCELLED");
   }
 });
+
+test("exposes categories as array on a non-recurring event", () => {
+  const iCalData = joinIcs(
+    "BEGIN:VCALENDAR",
+    "VERSION:2.0",
+    "BEGIN:VEVENT",
+    "UID:cat-single-1",
+    "SUMMARY:Zahnarzt",
+    "CATEGORIES:Health,Important",
+    "DTSTART:20260301T100000Z",
+    "DTEND:20260301T110000Z",
+    "END:VEVENT",
+    "END:VCALENDAR"
+  );
+
+  const result = parseAndExpandEvents(
+    iCalData,
+    new Date("2026-03-01T00:00:00Z"),
+    new Date("2026-03-02T00:00:00Z")
+  );
+
+  assert.equal(result.length, 1);
+  assert.deepEqual(result[0].categories, ["Health", "Important"]);
+});
+
+test("exposes empty categories array when CATEGORIES is absent", () => {
+  const iCalData = joinIcs(
+    "BEGIN:VCALENDAR",
+    "VERSION:2.0",
+    "BEGIN:VEVENT",
+    "UID:cat-absent-1",
+    "SUMMARY:No Categories",
+    "DTSTART:20260301T100000Z",
+    "DTEND:20260301T110000Z",
+    "END:VEVENT",
+    "END:VCALENDAR"
+  );
+
+  const result = parseAndExpandEvents(
+    iCalData,
+    new Date("2026-03-01T00:00:00Z"),
+    new Date("2026-03-02T00:00:00Z")
+  );
+
+  assert.equal(result.length, 1);
+  assert.deepEqual(result[0].categories, []);
+});
+
+test("propagates categories from parent event to recurring occurrences", () => {
+  const iCalData = joinIcs(
+    "BEGIN:VCALENDAR",
+    "VERSION:2.0",
+    "BEGIN:VEVENT",
+    "UID:cat-rec-1",
+    "SUMMARY:Weekly Meeting",
+    "CATEGORIES:Work,Team",
+    "DTSTART:20260302T090000Z",
+    "DTEND:20260302T100000Z",
+    "RRULE:FREQ=WEEKLY;COUNT=3",
+    "END:VEVENT",
+    "END:VCALENDAR"
+  );
+
+  const result = parseAndExpandEvents(
+    iCalData,
+    new Date("2026-03-01T00:00:00Z"),
+    new Date("2026-03-31T00:00:00Z")
+  );
+
+  assert.equal(result.length, 3);
+  for (const occurrence of result) {
+    assert.deepEqual(occurrence.categories, ["Work", "Team"]);
+  }
+});