From 78d67aa0590065373b287bd3534aa468fc6fb66b Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 6 Sep 2026 03:09:10 +0000 Subject: [PATCH 1/2] =?UTF-8?q?docs(plugin-calendar):=20shrink=20UNGATED?= =?UTF-8?q?=5FDOCS=20by=20one=20=E2=80=94=20the=20calendar=20README's=2010?= =?UTF-8?q?=20blocks=20compile?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `packages/plugin-calendar/README.md` leaves the `check-doc-snippet-types` ledger. All 10 of its ts/tsx blocks now compile --strict against the built `dist/*.d.ts`; no FRAGMENT_MARKER was written and no entry was added. Three blocks were repaired at the document, never by weakening the gate: - The authored-surface listing was a bare brace-wrapped block using `?:` optional-property notation inside a ```typescript fence — not expression syntax, so it could not parse at all (TS1109 x14). It is now a `type` alias, which keeps the `?:` markers a reader needs, plus two assignments that hold the listing to `CalendarViewSchema` in both directions. An earlier draft rewrote it as an annotated VALUE literal; that form compiles but destroys the optionality notation that `readme-calendar-view-schema.test.ts` reads, turning that pin red with 12 false "README says required" claims. The pin is a working guard and is left untouched. - `data: [...]` — a literal ellipsis standing in for "your records" — is not an expression either (TS1109 x1). It is now an empty array with a comment. - The two host-only handlers took their parameters implicitly `any` (TS7006 x2) because their object literal had no annotation. The annotation now supplies `CalendarEvent` and `CalendarViewMode` from the shipped schema. The ledger reason for this entry was stale in both halves and is reported in the PR rather than reproduced: 15 parse diagnostics reproduce, not 9, and the two remaining diagnostics are implicit-any, not undefined-name. A limit is published rather than left to be discovered: `CalendarViewSchema` extends `BaseSchema`, whose `[key: string]: any` means the compiler checks every key's TYPE and no key's SPELLING. A note in the README says so. Part of #5174 Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_013uAaxiwgYDybsTNV9xwa1M --- packages/plugin-calendar/README.md | 62 ++++++++++++++++++++--------- scripts/check-doc-snippet-types.mjs | 2 - 2 files changed, 43 insertions(+), 21 deletions(-) diff --git a/packages/plugin-calendar/README.md b/packages/plugin-calendar/README.md index 69692e2d86..08da9d7f11 100644 --- a/packages/plugin-calendar/README.md +++ b/packages/plugin-calendar/README.md @@ -156,23 +156,40 @@ reads (objectui#5667). Two of them — `data` and `className` — refine common any node. ```typescript -{ - type: 'calendar-view', - data?: any, // records rendered as events (array, or a binding expression) - titleField?: string, // default 'title' - startDateField?: string, // default 'start' - endDateField?: string, // default 'end' - allDayField?: string, // default 'allDay' - colorField?: string, // default 'color' - view?: CalendarViewMode, // 'month' | 'week' | 'day' (default 'month') - currentDate?: string | Date, // ISO string authored; Date from a React host - allowCreate?: boolean, // default false — shows the "New event" button - className?: string, // Tailwind classes for the container - onEventClick?: (event: CalendarEvent) => void, // HOST-ONLY (see below) - onViewChange?: (view: CalendarViewMode) => void // HOST-ONLY (see below) -} +import type { CalendarViewSchema, CalendarViewMode, CalendarEvent } from '@object-ui/types'; + +type CalendarViewNode = { + type: 'calendar-view'; + data?: any; // records rendered as events (array, or a binding expression) + titleField?: string; // default 'title' + startDateField?: string; // default 'start' + endDateField?: string; // default 'end' + allDayField?: string; // default 'allDay' + colorField?: string; // default 'color' + view?: CalendarViewMode; // 'month' | 'week' | 'day' (default 'month') + currentDate?: string | Date; // ISO string authored; Date from a React host + allowCreate?: boolean; // default false — shows the "New event" button + className?: string; // Tailwind classes for the container + onEventClick?: (event: CalendarEvent) => void; // HOST-ONLY (see below) + onViewChange?: (view: CalendarViewMode) => void; // HOST-ONLY (see below) +}; + +// The listing above is held to the shipped type BY THE COMPILER, both +// directions, rather than by this paragraph: a key whose type here disagrees +// with what `CalendarViewSchema` declares is a compile error. +declare const authored: CalendarViewNode; +declare const shipped: CalendarViewSchema; +const forwards: CalendarViewSchema = authored; +const backwards: CalendarViewNode = shipped; ``` +> **What those two assignments do and do not buy.** They check every key's +> **type**, in both directions. They do **not** check a key's **spelling**: +> `CalendarViewSchema` extends `BaseSchema`, whose `[key: string]: any` accepts +> any name, so a key invented or misspelled here is `any` rather than an error. +> Key-level validity is the strict `@objectstack/spec` twin's question, not +> TypeScript's. + There is deliberately **no authorable `events` key**: the renderer computes its events from `data` plus the field-name keys, and drops an authored `events` (objectui#4433). Nine formerly declared keys — `events`, `defaultView`, @@ -256,11 +273,16 @@ The handlers are host-only — a function can only come from a React host building the node in code, never from authored JSON: ```typescript -const schema = { +import type { CalendarViewSchema } from '@object-ui/types'; + +// The annotation is what types the two handler parameters: `event` is +// `CalendarEvent` and `view` is `CalendarViewMode`, read off the shipped +// schema. Without it both are implicitly `any`. +const schema: CalendarViewSchema = { type: 'calendar-view', data: [], onEventClick: (event) => { - console.log('Event clicked:', event); + console.log('Event clicked:', event.title); // Open event details modal }, onViewChange: (view) => { @@ -304,10 +326,12 @@ const schema = { Style the calendar with Tailwind classes: ```typescript -const schema = { +import type { CalendarViewSchema } from '@object-ui/types'; + +const schema: CalendarViewSchema = { type: 'calendar-view', className: 'border rounded-lg shadow-lg', - data: [...] + data: [] // your records }; ``` diff --git a/scripts/check-doc-snippet-types.mjs b/scripts/check-doc-snippet-types.mjs index d62916c55e..d978bcf21e 100644 --- a/scripts/check-doc-snippet-types.mjs +++ b/scripts/check-doc-snippet-types.mjs @@ -729,8 +729,6 @@ const UNGATED_DOCS = { '12 undefined-name diagnostic(s) — blocks continue an earlier block, or use ambient names the page never defines; plus TS2322x4 TS2345x1 TS2353x1 — candidate real defects, un-triaged', 'packages/plugin-ai/README.md': '5 undefined-name diagnostic(s) — blocks continue an earlier block, or use ambient names the page never defines; plus TS2322x3 — candidate real defects, un-triaged', - 'packages/plugin-calendar/README.md': - '9 parse diagnostic(s) — blocks fenced `ts` that are bare object literals or elided bodies; 2 undefined-name diagnostic(s) — blocks continue an earlier block, or use ambient names the page never defines', 'packages/plugin-charts/README.md': '6 parse diagnostic(s) — blocks fenced `ts` that are bare object literals or elided bodies', 'packages/plugin-chatbot/README.md': From 8fbe7b72495d8cbf982d01a944490d00ce9db7c6 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 6 Sep 2026 03:28:06 +0000 Subject: [PATCH 2/2] docs(plugin-calendar): cite objectui#7927 on the key-spelling limit The note added above states the limit; this points at the card that owns it. Part of #5174 Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_013uAaxiwgYDybsTNV9xwa1M --- packages/plugin-calendar/README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/packages/plugin-calendar/README.md b/packages/plugin-calendar/README.md index 08da9d7f11..56ca775fc6 100644 --- a/packages/plugin-calendar/README.md +++ b/packages/plugin-calendar/README.md @@ -186,9 +186,9 @@ const backwards: CalendarViewNode = shipped; > **What those two assignments do and do not buy.** They check every key's > **type**, in both directions. They do **not** check a key's **spelling**: > `CalendarViewSchema` extends `BaseSchema`, whose `[key: string]: any` accepts -> any name, so a key invented or misspelled here is `any` rather than an error. -> Key-level validity is the strict `@objectstack/spec` twin's question, not -> TypeScript's. +> any name, so a key invented or misspelled here is `any` rather than an error +> (objectui#7927). Key-level validity is the strict `@objectstack/spec` twin's +> question, not TypeScript's. There is deliberately **no authorable `events` key**: the renderer computes its events from `data` plus the field-name keys, and drops an authored `events`