Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
delchev wants to merge 2 commits into
base: main
Choose a base branch
from
Open

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0d56d8e
docs: a calendar view adds a page; a document's line-items calendar i…
delchev Aug 9, 2026
fbfe74f
docs: the slot picker adds a page too, so no view replaces a layout
delchev Aug 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
| [`widgets`](/spec/presentation#widgets-custom-dashboard-tiles) | custom KPI / embedded-page dashboard tiles |
Expand Down
32 changes: 31 additions & 1 deletion docs/spec/presentation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -109,7 +109,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
Expand All @@ -125,6 +125,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:
Expand Down