# Calendar Editor

A booking calendar on capacity: week / day / month views, mobile agenda, occupancy with buffers, blocked intervals, opening hours, in-panel create / reschedule / cancel, and round-trip import / export in **JSON** (`.calendar`) and **iCalendar** (`.ics`).

Built on top of the [`gadgets/calendar`](https://cdn.sgapps.io/components/application-prototype-thirdparty/docs/#/gadgets/calendar.md) module (SGApps.IO product: written in-house, no third-party code, no network of its own). The editor adds a save/export toolbar, settings dialogs for resource / opening hours / blocked intervals, and acts as its own host adapter -- creates / reschedules / cancellations are written straight back into the in-memory event list so the editor is self-sufficient out of the box.

## Live Demo

<iframe id="ce2-demo" src="/online/webapp/calendar-editor/url/aHR0cHM6Ly9zZ2FwcHMubG9jYWwvc2NyaXB0cy9tb2R1bGVzL3NnYXBwcy9hcHBsaWNhdGlvbnMvY2FsZW5kYXItZWRpdG9yL3NhbXBsZS5pY3M=" width="100%" height="560" frameborder="0" style="border:1px solid #ccc; border-radius:4px;"></iframe>

<script>window._wsConnect('ce2-demo', 'calSocket');</script>

The demo opens with a sample `.ics` file (three service-bay bookings around 26-28 October 2026). Navigate with ◀ / ▶ or **Today** -- if you don't see them, press **Today** then ◀ to find the week.

## Embed

```html
<iframe src="https://sgapps.io/online/webapp/calendar-editor"
    width="100%" height="640" frameborder="0"></iframe>
```

### Open with a file

The first argument becomes the file (local file-manager path OR an `http(s)://` URL). The extension picks the parser:

| Extension | Format | Round-trip |
|---|---|---|
| `.calendar`, `.json` (JSON content) | SGApps.IO in-house schema | ✅ full -- resource, opening hours, statuses, blocks, events, locale, zones |
| `.ics`, `.vcs` | RFC 5545 iCalendar | ✅ events only; resource / opening hours / custom statuses lost (not in the standard) |

```html
<iframe src="https://sgapps.io/online/webapp/calendar-editor/url/aHR0cHM6Ly9leGFtcGxlLmNvbS9ib29raW5ncy5pY3M=" width="100%" height="640" frameborder="0"></iframe>
```

### In-page (no iframe)

```html
<script src="https://cdn.sgapps.io/scripts/modules-webapp/exporter.js"></script>
<sgapps-calendar-editor--tool id="cal"></sgapps-calendar-editor--tool>
<script>
Application.require("b2b.editor.calendar-editor").then(function (factory) {
    var app = factory();
    document.getElementById("cal").replaceWith(app.node());
    app.editor().then(function (ed) {
        ed.visible(true);
        // ed.client is a WindowSocket client ready for fire(…)
    });
});
</script>
```

---

## Events Reference

```js
var socket = new WindowSocket(iframe.contentWindow);
socket.start();
socket.fire("webapp::instance::request", eventName, ...args, callback);
```

The calendar also emits events upward through `api-event::instance:*`; see the full list under **Calendar events (upstream)** below.

---

### `getEvents`, `setEvents`, `upsertEvent`, `removeEvent`

```js
socket.fire("webapp::instance::request", "upsertEvent",
    { id: "k-99", start: "2026-10-26T07:30:00Z", end: "2026-10-26T09:00:00Z",
      title: "New booking", status: "open", quantity: 1 },
    function (err, id) {});
```

<button onclick="window._ws('calSocket')&&window.calSocket.fire('webapp::instance::request','upsertEvent',{id:'docs-'+Date.now(),start:new Date(Date.now()+3600000).toISOString(),end:new Date(Date.now()+2*3600000).toISOString(),title:'Added from docs',description:'Hello from the Try button',status:'open',quantity:1},function(e,id){if(e)return alert('Error: '+e.message);alert('Added booking '+id)})">Try: Add a 1-hour booking (now+1h)</button>
<button onclick="window._ws('calSocket')&&window.calSocket.fire('webapp::instance::request','getEvents',function(e,l){if(e)return alert('Error: '+e.message);alert(l.length+' events:\n\n'+l.map(function(x){return x.id+' -- '+(x.title||'(untitled)')+' @ '+x.start}).slice(0,15).join('\n'))})">Try: List events</button>
<button onclick="window._ws('calSocket')&&window.calSocket.fire('webapp::instance::request','setEvents',[],function(e){if(e)return alert('Error: '+e.message);alert('Cleared all events')})">Try: Clear all events</button>

---

### `setView`, `getView`, `today`, `prev`, `next`, `setDate`

```js
socket.fire("webapp::instance::request", "setView", "month", function (err) {});
socket.fire("webapp::instance::request", "setDate", "2026-10-26", function (err) {});
```

<button onclick="window._ws('calSocket')&&window.calSocket.fire('webapp::instance::request','setView','month',function(e){if(e)return alert('Error: '+e.message);})">Try: Month view</button>
<button onclick="window._ws('calSocket')&&window.calSocket.fire('webapp::instance::request','setView','week',function(e){if(e)return alert('Error: '+e.message);})">Try: Week view</button>
<button onclick="window._ws('calSocket')&&window.calSocket.fire('webapp::instance::request','setView','day',function(e){if(e)return alert('Error: '+e.message);})">Try: Day view</button>
<button onclick="window._ws('calSocket')&&window.calSocket.fire('webapp::instance::request','today',function(e){if(e)return alert('Error: '+e.message);})">Try: Today</button>
<button onclick="window._ws('calSocket')&&window.calSocket.fire('webapp::instance::request','prev',function(e){if(e)return alert('Error: '+e.message);})">Try: Prev period</button>
<button onclick="window._ws('calSocket')&&window.calSocket.fire('webapp::instance::request','next',function(e){if(e)return alert('Error: '+e.message);})">Try: Next period</button>
<button onclick="window._ws('calSocket')&&window.calSocket.fire('webapp::instance::request','setDate','2026-10-26',function(e){if(e)return alert('Error: '+e.message);})">Try: Jump to 2026-10-26</button>

---

### `setResource`, `setCapacity`, `setOpeningHours`

```js
socket.fire("webapp::instance::request", "setCapacity", 3, function (err) {});

socket.fire("webapp::instance::request", "setOpeningHours", {
    0: null, 1: [["09:00", "18:00"]], 2: [["09:00", "18:00"]],
    3: [["09:00", "18:00"]], 4: [["09:00", "18:00"]], 5: [["09:00", "18:00"]], 6: null
}, function (err) {});
```

<button onclick="window._ws('calSocket')&&window.calSocket.fire('webapp::instance::request','setCapacity',3,function(e){if(e)return alert('Error: '+e.message);})">Try: Capacity = 3</button>
<button onclick="window._ws('calSocket')&&window.calSocket.fire('webapp::instance::request','setCapacity',1,function(e){if(e)return alert('Error: '+e.message);})">Try: Capacity = 1</button>
<button onclick="window._ws('calSocket')&&window.calSocket.fire('webapp::instance::request','setOpeningHours',{0:null,1:[['08:00','20:00']],2:[['08:00','20:00']],3:[['08:00','20:00']],4:[['08:00','20:00']],5:[['08:00','20:00']],6:[['10:00','16:00']]},function(e){if(e)return alert('Error: '+e.message);})">Try: Mon-Fri 08-20, Sat 10-16</button>
<button onclick="window._ws('calSocket')&&window.calSocket.fire('webapp::instance::request','setOpeningHours',{0:null,1:null,2:null,3:null,4:null,5:null,6:null},function(e){if(e)return alert('Error: '+e.message);})">Try: Closed all week</button>

---

### `setBlocks`, `getBlocks`, `addBlock`, `removeBlock`

```js
// Absolute block
socket.fire("webapp::instance::request", "addBlock",
    { id: "maint-1", start: "2026-10-26T09:00:00Z", end: "2026-10-26T10:00:00Z",
      label: "Maintenance", kind: "deny" },
    function (err) {});

// Recurring daily lunch
socket.fire("webapp::instance::request", "addBlock",
    { id: "lunch", weekday: -1, startTime: "12:00", endTime: "13:00",
      label: "Lunch break", kind: "deny", active: true },
    function (err) {});
```

<button onclick="window._ws('calSocket')&&window.calSocket.fire('webapp::instance::request','addBlock',{id:'docs-lunch',weekday:-1,startTime:'12:00',endTime:'13:00',label:'Lunch (demo)',kind:'deny',active:true},function(e){if(e)return alert('Error: '+e.message);})">Try: Add daily lunch 12-13</button>
<button onclick="window._ws('calSocket')&&window.calSocket.fire('webapp::instance::request','removeBlock','docs-lunch',function(e){if(e)return alert('Error: '+e.message);})">Try: Remove daily lunch</button>
<button onclick="window._ws('calSocket')&&window.calSocket.fire('webapp::instance::request','setBlocks',[],function(e){if(e)return alert('Error: '+e.message);})">Try: Clear all blocks</button>

---

### `setLocale`, `setTimeZone`, `setReadOnly`

Languages shipped: `en`, `ro`, `ru`, `es`, `fr`, `it`, `de`, `zh`. See [`gadgets/calendar` §Languages](https://cdn.sgapps.io/components/application-prototype-thirdparty/docs/#/gadgets/calendar.md) for plural rules + conventions per locale.

```js
socket.fire("webapp::instance::request", "setLocale", "ro", function (err) {});
socket.fire("webapp::instance::request", "setTimeZone", "Europe/Chisinau", "Europe/Chisinau", function (err) {});
```

<button onclick="window._ws('calSocket')&&window.calSocket.fire('webapp::instance::request','setLocale','ro',function(e){if(e)return alert('Error: '+e.message);})">Try: Switch to Romanian</button>
<button onclick="window._ws('calSocket')&&window.calSocket.fire('webapp::instance::request','setLocale','ru',function(e){if(e)return alert('Error: '+e.message);})">Try: Switch to Russian</button>
<button onclick="window._ws('calSocket')&&window.calSocket.fire('webapp::instance::request','setLocale','en',function(e){if(e)return alert('Error: '+e.message);})">Try: Switch to English</button>
<button onclick="window._ws('calSocket')&&window.calSocket.fire('webapp::instance::request','setTimeZone','Europe/Chisinau','Europe/Chisinau',function(e){if(e)return alert('Error: '+e.message);})">Try: TZ = Europe/Chișinău</button>
<button onclick="window._ws('calSocket')&&window.calSocket.fire('webapp::instance::request','setReadOnly',true,function(e){if(e)return alert('Error: '+e.message);alert('Read-only. Toolbar still works; the create / cancel actions in the panels do not.')})">Try: Read-only on</button>
<button onclick="window._ws('calSocket')&&window.calSocket.fire('webapp::instance::request','setReadOnly',false,function(e){if(e)return alert('Error: '+e.message);})">Try: Read-only off</button>

---

### `openCreate`, `selectEvent`, `closePanel`

```js
socket.fire("webapp::instance::request", "openCreate",
    "2026-10-26T10:00:00Z", "2026-10-26T11:00:00Z", function (err) {});
```

<button onclick="window._ws('calSocket')&&window.calSocket.fire('webapp::instance::request','today',function(){window.calSocket.fire('webapp::instance::request','getRange',function(e,r){var start=new Date(r.start);start.setUTCHours(10,0,0,0);var end=new Date(start.getTime()+3600000);window.calSocket.fire('webapp::instance::request','openCreate',start.toISOString(),end.toISOString(),function(){})})})">Try: Open create at 10:00 today</button>
<button onclick="window._ws('calSocket')&&window.calSocket.fire('webapp::instance::request','closePanel',function(e){if(e)return alert('Error: '+e.message);})">Try: Close any open panel</button>

---

### `dayStats`, `rangeStats`, `findSlots`

```js
socket.fire("webapp::instance::request", "rangeStats", function (err, s) { console.log(s); });

socket.fire("webapp::instance::request", "findSlots",
    { durationMinutes: 90, quantity: 1, count: 3, stepMinutes: 90 },
    function (err, slots) { console.log(slots); });
```

<button onclick="window._ws('calSocket')&&window.calSocket.fire('webapp::instance::request','rangeStats',function(e,s){if(e)return alert('Error: '+e.message);alert(JSON.stringify(s,null,2))})">Try: Range stats</button>
<button onclick="window._ws('calSocket')&&window.calSocket.fire('webapp::instance::request','findSlots',{durationMinutes:90,quantity:1,count:5,stepMinutes:90},function(e,s){if(e)return alert('Error: '+(e.message||e));alert(s.length+' free slots:\n\n'+s.map(function(x){return x.start+' → '+x.end+' ('+x.free+' free)'}).join('\n'))})">Try: Find 5 free 90-min slots</button>

---

### `exportAs`, `toICS`

```js
socket.fire("webapp::instance::request", "exportAs", "ics",
    function (err, text) {
        var blob = new Blob([text], { type: "text/calendar" });
        var a = document.createElement("a");
        a.href = URL.createObjectURL(blob); a.download = "bookings.ics"; a.click();
    });
```

<button onclick="window._ws('calSocket')&&window.calSocket.fire('webapp::instance::request','exportAs','ics',function(e,t){if(e)return alert('Error: '+e.message);var b=new Blob([t],{type:'text/calendar'});var a=document.createElement('a');a.href=URL.createObjectURL(b);a.download='bookings.ics';a.click();})">Try: Download as .ics</button>
<button onclick="window._ws('calSocket')&&window.calSocket.fire('webapp::instance::request','exportAs','calendar',function(e,t){if(e)return alert('Error: '+e.message);var b=new Blob([t],{type:'application/json'});var a=document.createElement('a');a.href=URL.createObjectURL(b);a.download='bookings.calendar';a.click();})">Try: Download as .calendar (JSON)</button>
<button onclick="window._ws('calSocket')&&window.calSocket.fire('webapp::instance::request','toICS',null,function(e,t){if(e)return alert('Error: '+e.message);alert('ICS (first 500 chars):\n\n'+t.substring(0,500))})">Try: Peek at ICS</button>

---

### `save`, `saveAs`

Writes the current calendar back to the file it was opened with:

```js
socket.fire("webapp::instance::request", "save", function (err) {});
socket.fire("webapp::instance::request", "saveAs", "ics", "/home/me/bookings.ics", function (err) {});
```

Call `saveAs` with `null` filename to open the file-selector dialog. The toolbar's **Save** falls back to Save-As on the first save of a URL-opened calendar.

---

## Calendar events (upstream)

Forwarded through `api-event::instance:*`:

```js
socket.on("api-event::instance:event:create-requested", function (draft) {
    // the user confirmed a new booking in the panel; the editor's
    // built-in host adapter already wrote it in-memory. Replace this
    // adapter in your own code to send it to your server first.
});
```

| Event | Payload |
|---|---|
| `ready` | the instance |
| `event:range-changed` | `{view, start, end, days}` |
| `event:view-changed` | `{view}` |
| `event:day-focused` | `{date}` |
| `event:scope-filter` | `{scope}` |
| `event:status-filter` | `{hidden: []}` |
| `event:event-selected` | the booking, with its `data` |
| `event:event-deselected` | `{id}` |
| `event:draft-changed` | the draft, on every panel change |
| `event:create-requested` | `{start, end, date, durationMinutes, quantity, scope, title, token, override}` |
| `event:reschedule-requested` | `{id, start, end, base: {start, end}, quantity, data}` |
| `event:cancel-requested` | `{id, reason, note, data}` |
| `event:error` | `{code, message, error}` |

---

## Data shapes

**A booking** (what `upsertEvent` takes and `getEvents` returns):

```js
{
    id: "k-5",
    start: "2026-10-26T07:30:00Z",       // ISO 8601 UTC
    end:   "2026-10-26T09:00:00Z",
    quantity: 1,                          // capacity units; decimals allowed
    title: "Aroma Coffee Shop Ltd",
    subtitle: null,
    description: "Full espresso machine service + descaling",
    code: "K-5",
    status: "open",                       // key of statuses
    scope: null,
    bufferBefore: 15,                     // minutes held before start
    bufferAfter: 15,
    editable: true,
    data: { anything: "the host wants back" }
}
```

**A blocked interval** -- absolute:

```js
{ id: "maint-1", start: "2026-10-26T09:00:00Z", end: "2026-10-26T10:00:00Z",
  label: "Maintenance", kind: "deny" }
```

Or recurring (wall-clock time in the business zone):

```js
{ id: "lunch", weekday: -1, startTime: "12:00", endTime: "13:00",
  label: "Lunch", kind: "deny", active: true }
```

`weekday: -1` = every day; `0` = Sunday, …, `6` = Saturday. `kind: "allow"` inverts it into an availability window.

---

## Use Cases

### A booking widget on a landing page

Embed with `readOnly: true` on load, use `addBlock` for recurring breaks and let the user see when the resource is free -- no risk of them creating a stray booking.

### Resource planner for an operations dashboard

Open with `setView("month")`, call `rangeStats` on `event:range-changed` to surface peak and percentage per week.

### Import an exported calendar from another system

Save it as `.ics`, point the editor at it via `/online/webapp/calendar-editor/url/<base64 of URL>`. VEVENT blocks are parsed; resource / opening hours stay at the editor's defaults.

### Build your own write backend

The editor ships with a built-in host adapter that writes to its own memory. For a server-backed workflow:

1. Set `readOnly: false` (default).
2. Listen for `api-event::instance:event:create-requested` / `event:reschedule-requested` / `event:cancel-requested`.
3. POST to your API; on success call `upsertEvent(booking)` or `removeEvent(id)`; on failure call `failRequest(idOrToken, message)`.
4. Suppress the in-memory adapter by hiding or overriding your own listeners.

---

## Privacy

The calendar module **does not touch the network itself**. Data arrives through `set*` / `upsertEvent` and leaves through `getEvents` / `exportAs`. No tiles, no autocomplete, no analytics. See the module docs for the full policy.