@craftguild/jscalendar 0.5.0 → 0.5.2

package/README.md

@@ -1,15 +1,25 @@
+<p style="text-align: center;">
+<img src="assets/d97d4d10-44f9-4b49-9fc2-5aaf33c667ef.png" alt="JSCalendar logo" style="max-height: 320px; height: auto; width: auto;" />
+</p>
+
 # RFC 8984 (JSCalendar) TypeScript Library
 
 This library provides a thin, practical TypeScript API for working with
-RFC 8984 (JSCalendar) objects. It focuses on creation, mutation, search,
-and export. It does **not** implement a calendar application or server.
-The goal is to keep the data model easy to use in web apps and CLIs while
-preserving access to the full RFC object structure when you need it.
+RFC 8984 (JSCalendar) objects while staying close to the spec. It focuses
+on creation, patching, recurrence expansion, search, and iCalendar export.
+It does **not** implement a calendar application or server; it is a data
+model toolkit you can use in web apps, CLIs, or services.
 
 Primary object types are **Event**, **Task**, and **Group**. A **Group**
 acts as a container when you want to bundle multiple objects. The API is
-intentionally small: you create objects, mutate them with safe helpers,
-query them with search utilities, and export them to iCalendar as needed.
+intentionally small but opinionated: constructors normalize required
+fields, validation is strict by default, and `patch` applies RFC 8984
+PatchObject semantics.
+
+For developer experience, the library offers builder helpers that fill
+`@type` fields and validate nested structures (participants, locations,
+alerts, recurrence rules, and more). You can still pass raw, typed
+JSCalendar objects directly when your data already matches the spec.
 
 ## Installation
 
@@ -84,20 +94,6 @@ const task = new JsCal.Task({
 });
 ```
 
-Id maps use `{ id, value }` entries. If you need to merge into an
-existing map, pass it as the second argument. Entries with `id` overwrite
-matching ids; entries without `id` get new generated ids.
-
-```ts
-const mergedLocations = JsCal.locations(
-  [
-    { id: "l1", value: { name: "Room A Updated" } },
-    { value: { name: "Room B" } },
-  ],
-  existingLocations,
-);
-```
-
 ### Group
 
 `entries` accepts either plain JSCalendar objects (including `eject()` results)
@@ -204,17 +200,59 @@ plain.title = "Exported";
 const updated = event.patch({ title: "Live" });
 ```
 
-## Updates and Mutations
+## Patch Usage
 
 Patch helpers return new instances and keep metadata such as
 `updated` and `sequence` consistent. Use `patch` for RFC 8984 PatchObject
-semantics.
+semantics. You can set raw values directly, or use helper methods if you
+prefer validated, type-safe inputs.
 
 ```ts
 const patchedEvent = event.patch({ title: "Updated title" });
 const patchedAgain = patchedEvent.patch({ title: "Patched title" });
 ```
 
+You can also patch nested maps by replacing the full map in one call:
+
+```ts
+const withParticipants = event.patch({
+  participants: {
+    p1: { "@type": "Participant", roles: { attendee: true }, email: "a@example.com" },
+  },
+});
+```
+
+Two common patterns for nested patches:
+
+1) Set raw values directly
+```ts
+const withLocations = event.patch({
+  locations: {
+    l1: { "@type": "Location", name: "Room A" },
+  },
+});
+```
+
+2) Use helpers to build or merge map values
+```ts
+const withLocations = event.patch({
+  locations: JsCal.locations([
+    { id: "l1", value: JsCal.Location({ name: "Room A" }) },
+    { value: JsCal.Location({ name: "Room B" }) },
+  ]),
+});
+```
+
+To merge into an existing map, pass the current map as the second argument:
+```ts
+const withLocations = event.patch({
+  locations: JsCal.locations(
+    [{ value: JsCal.Location({ name: "Room C" }) }],
+    event.data.locations,
+  ),
+});
+```
+
 ## Date Inputs and Time Zones
 
 Date fields accept either RFC 8984 strings or JavaScript `Date`. When a
@@ -351,26 +389,6 @@ const icalMany = JsCal.toICal([event, task], { includeXJSCalendar: true });
 console.log(icalMany);
 ```
 
-## Practical Example
-
-**Weekly engineering sync (every Wednesday 10:30, 1 hour)**
-
-```ts
-const weekly = new JsCal.Event({
-  title: "Engineering Sync",
-  start: "2026-02-04T10:30:00",
-  timeZone: "Asia/Tokyo",
-  duration: JsCal.duration.hours(1),
-  recurrenceRules: [
-    {
-      "@type": "RecurrenceRule",
-      frequency: "weekly",
-      byDay: [{ "@type": "NDay", day: "we" }],
-    },
-  ],
-});
-```
-
 ## Compliance and Deviations
 
 ### RFC 8984 Conformance (Implemented)

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@craftguild/jscalendar",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "RFC 8984 (JSCalendar) data model helpers for TypeScript",
+  "license": "MIT",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",