Merge pull request #8 from IntentFile/docs/calendar-additional-page

docs: a calendar view adds a page; a document's line-items calendar is the items pane

Author: delchev

docs/reference.md

@@ -28,7 +28,7 @@ The quick lookup surface: one line and a minimal snippet per construct. For rule
 | [`function: Attachment` / `Snapshot`](/spec/entities#attachments-and-snapshots) | a Files panel / immutable versioned printed copies |
 | [`forms`](/spec/processes#forms) | task data-entry pages |
 | [`actions`](/spec/processes#actions-custom-buttons) | developer-defined buttons opening custom pages |
-| [`view`](/spec/presentation#view-calendar-range-slots) | calendar / range / slot-booking pages |
+| [`view`](/spec/presentation#view-calendar-range-slots) | an additional calendar / range page, or a slot-booking page |
 | [`documentItemsLayout: chat`](/spec/presentation#documentitemslayout-chat-conversation-threads) | render a document's items as a chat thread |
 | [`reports`](/spec/presentation#reports) | aggregations, charts, dashboard KPI tiles, balance reports |
 | [`scope`](/spec/presentation#lifecycle-scope) | which lifecycle rows an aggregating report counts |

docs/spec/presentation.md

@@ -141,7 +141,7 @@ widgets:
 
 ## view — calendar, range, slots
 
-`view:` (with a `calendar:` / `slots:` descriptor) renders an entity as a time-based page instead of a table:
+`view:` (with a `calendar:` / `slots:` descriptor) places an entity's records on a time surface:
 
 ```yaml
 - name: DayAllocation
@@ -157,6 +157,36 @@ widgets:
 
 `view: calendar` is also expressible as the role alias `function: Calendar`.
 
+### A view adds a page
+
+`view: calendar`, `view: range` and `view: slots` **add** a page; they never take one away. The entity keeps the page family its structure already implies — a list, a master-detail, or a document editor — and the view joins it:
+
+| Route | Page |
+|---|---|
+| `/<Entity>` | the calendar, or the slot picker |
+| `/<Entity>/list` | the entity's own browse page (list / master / document list) |
+| `/<Entity>/create`, `/<Entity>/<id>/edit` | the entity's own editor |
+
+Both browse pages offer a switch to the other, and choosing a day, an event or a free slot opens the entity's own editor. So a document master may be browsed on a calendar — or booked from a slot picker — and still be edited as a document, with its line items, printing and workflow tasks intact: declaring a view never costs an entity its editing surface. A picker is how a record is *created*; the list or document page is how it is worked with afterwards, and an author needs both.
+
+### A document's line items on a calendar
+
+When the entity declaring `view: calendar` is a document's **line-items** child, the document's items pane *is* the calendar instead of the row grid — the shape for a day-grained line, such as a booked day or an allocated hour:
+
+```yaml
+- name: Roster
+  function: Document
+- name: RosterItem
+  function: DocumentItem
+  view: calendar
+  calendar: { start: day, title: Person }
+  fields:
+    - { name: day,   type: date, required: true }
+    - { name: hours, type: decimal, precision: 18, scale: 2 }
+```
+
+The document keeps its header, totals and printing; only the items pane changes. Clicking an event edits that line, clicking an empty day adds one with that date filled in. It cannot be combined with `documentItemsLayout: chat`, which claims the same pane.
+
 ## documentItemsLayout: chat — conversation threads
 
 A document master can render its line-items child as a chat thread (message bubbles + a composer) instead of an editable items table — support cases, tickets, comment threads. The header, status pill, workflow tasks and print stay as in a normal document: