From 5504e7c39c8598d8614295faeb865b7ec6b61903 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 8 Sep 2026 01:09:34 +0000
Subject: [PATCH] docs(plugin-calendar): rewrite the two object-calendar
 examples onto declared keys

Both `object-calendar` blocks in this README taught keys that
`ObjectCalendarSchema` does not declare and the renderer does not read:
`object`, `startField`, `endField`, `dataSource` and a `fields` container.
Measured on the renderer, with `schema.objectName` (19 occurrences) as the
non-vacuity control in the same run: `schema.object`, `schema.startField`,
`schema.fields` and `schema.dataSource` each have 0 read sites.

The wrong start-date key was not a partial failure. `getCalendarConfig` gates
the entire flat-property branch on the start-date spelling, so the first
block's correctly spelled `titleField` was never read either and the node
rendered the "Calendar configuration required" refusal screen.

Both blocks are now annotated `ObjectCalendarSchema`, which puts them inside
`check:doc-snippets` instead of leaving them as bare literals compiled against
nothing. The annotation's real reach is stated in the file rather than implied:
it type-checks the VALUES of declared keys, and it does NOT check key names,
because this interface extends `BaseSchema` and its `[key: string]: any`
admits any spelling.

Claude-Session: https://claude.ai/code/session_01FhBNJcLRZLe8M87VcUgpKr
---
 packages/plugin-calendar/README.md | 51 +++++++++++++++++++++---------
 1 file changed, 36 insertions(+), 15 deletions(-)

diff --git a/packages/plugin-calendar/README.md b/packages/plugin-calendar/README.md
index 56ca775fc..fcc26a3d9 100644
--- a/packages/plugin-calendar/README.md
+++ b/packages/plugin-calendar/README.md
@@ -256,14 +256,29 @@ fields when they differ.
 
 ### With ObjectQL Integration
 
+Every key below is one `ObjectCalendarSchema` declares. Spelling the start-date
+key anything else is not a partial failure: `getCalendarConfig` gates the whole
+configuration on it, so a calendar whose title and end keys are spelled correctly
+still renders the "Calendar configuration required" refusal screen and never
+reads them.
+
 ```typescript
-const schema = {
+import type { ObjectCalendarSchema } from '@object-ui/types';
+
+// What this annotation buys, and what it does not - measured, objectui#7925.
+// It type-checks the VALUES of the declared keys: `defaultView: 'agenda'` and
+// `titleField: 42` are both compile errors, and `check:doc-snippets` re-runs
+// that check on every commit. It does NOT check key NAMES - this interface
+// extends `BaseSchema`, whose `[key: string]: any` admits any spelling, so a
+// misspelt key still compiles clean. Read the block as type-checked values,
+// never as a guarded key set.
+const schema: ObjectCalendarSchema = {
   type: 'object-calendar',
-  object: 'events',
+  objectName: 'events',
   titleField: 'name',
-  startField: 'startDate',
-  endField: 'endDate',
-  colorField: 'category.color'
+  startDateField: 'startDate',
+  endDateField: 'endDate',
+  defaultView: 'month'
 };
 ```
 
@@ -298,29 +313,35 @@ Authored JSON reacts to clicks through the node's action channel instead
 
 ## ObjectQL Integration
 
-When using with ObjectStack, the calendar can automatically fetch and display events:
+When using with ObjectStack, the calendar can automatically fetch and display
+events. The adapter is **not** a schema key: `ObjectCalendarRenderer` reads it
+from the renderer context that `SchemaRendererProvider` supplies. The schema
+names the object and its fields with the same flat keys as above - there is no
+`fields` container.
 
 ```typescript
 import { createObjectStackAdapter } from '@object-ui/data-objectstack';
+import type { ObjectCalendarSchema } from '@object-ui/types';
 
 const dataSource = createObjectStackAdapter({
   baseUrl: 'https://api.example.com',
   token: 'your-auth-token'
 });
 
-const schema = {
+// The annotation checks the values of the declared keys, not the key names -
+// see the note on the first `object-calendar` block above.
+const schema: ObjectCalendarSchema = {
   type: 'object-calendar',
-  dataSource,
-  object: 'calendar_events',
-  fields: {
-    title: 'title',
-    start: 'start_time',
-    end: 'end_time',
-    color: 'category_color'
-  }
+  objectName: 'calendar_events',
+  titleField: 'title',
+  startDateField: 'start_time',
+  endDateField: 'end_time',
+  defaultView: 'month'
 };
 ```
 
+Pass the adapter to `SchemaRendererProvider` to wire the fetch up.
+
 ## Customization
 
 Style the calendar with Tailwind classes: