fix(plugin-calendar): gate ObjectCalendar's standalone query on the object schema (#6484)

* fix(plugin-calendar): gate ObjectCalendar's standalone query on the object schema

The fetch effect built its expand set from `objectSchemaRef.current`, a ref
assigned in the render body, and deliberately omitted `objectSchema` from its
dependency list. That bought one effect run per mount and paid for it with the
expansion, permanently: on that one run the ref was still null,
`buildExpandFields` saw no fields, and the query went out with no `$expand` at
all — and nothing re-ran the effect when the schema landed.

Only the standalone `object-calendar` with `dataConfig.provider === 'object'`
reaches this path; one hosted by ObjectView or ListView takes its rows from the
parent, which objectui#6419 already covers. On the standalone calendar every
lookup / master_detail / user / tree field rendered from its raw foreign-key id.

The ref is replaced by a settled-and-keyed resolution (`{ key, def } | null`)
that GATES the record query — the third member of the family after objectui#6271
(ObjectKanban) and objectui#6419 (ObjectView), written as a third copy rather
than an extraction because neither of those landed a shared helper and this
component's key and gate scope both diverge from theirs.

Measured on this component, not inherited. Instrumented adapter, rows tagged
with the query that produced them, observations read from the DOM and from real
child commits, three latency profiles:

  before             1 find, `$expand` NEVER present. Raw ids paint and stay.
  `objectSchema`     2 finds. Schema slower: raw ids at 30ms, back to the
  in the deps        "Loading calendar..." placeholder at 71ms, expanded at
                     94ms — a three-step paint. Schema faster: the first
                     response is discarded on arrival.
  gated              1 find carrying `$expand` the first time, in all three
                     profiles; one paint, expanded, at 107/88/78ms vs
                     108/94/79ms via the deps.

The gate is on the read having SETTLED, never on a truthy schema: an adapter
with no `getObjectSchema` and a read that throws both settle with nothing and
the calendar still queries, unexpanded. The gate is scoped to the `object`
provider because an inline `value` set issues no metadata read at all — a
whole-effect gate would hold its query open on a resolution nothing produces.

No public surface change: no `index.ts` touched, no export added or removed.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011SfZeFWrhGLHmfq61xbz4q

* test(plugin-calendar): record which expand-gate pins actually discriminate

Reverse verification against the branch's base commit turned SIX of the nine
pins red, not four: the REJECTS pin discriminates too, through its ordering
assertion (`['find', 'schema:issued']` against the base — the query went out
before the schema was even requested). The docstring claimed it could not.
Corrected to the measured result, and the three pins that genuinely stay green
in both directions are now named with the reason each still earns its place.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011SfZeFWrhGLHmfq61xbz4q

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: claude[bot]

.changeset/6453-calendar-expand-gate.md

@@ -0,0 +1,29 @@
+---
+'@object-ui/plugin-calendar': patch
+---
+
+A standalone `object-calendar` bound to an object now queries WITH its `$expand`, so
+lookup / master_detail / user / tree fields render the related record instead of a raw
+foreign-key id (objectui#6453).
+
+`ObjectCalendar`'s fetch effect built its expand set from a ref assigned in the render body
+(`objectSchemaRef.current = objectSchema`) and left `objectSchema` out of its dependency
+list. That bought the effect exactly one run per mount and paid for it with the expansion,
+permanently: on that one run the ref was still `null`, `buildExpandFields` saw no fields,
+the query went out with no `$expand` at all, and nothing re-ran the effect when the schema
+landed. Only the standalone calendar reached this path — one hosted by `ObjectView` or
+`ListView` receives its rows as `data`, which objectui#6419 already covers.
+
+The ref is replaced by a settled-and-keyed resolution (`{ key, def } | null`) that GATES the
+record query, the third member of the family after objectui#6271 (`ObjectKanban`) and
+objectui#6419 (`ObjectView`). Measured on this component rather than inherited: gated, the
+calendar issues one query carrying `$expand` in every latency profile; the alternative of
+adding `objectSchema` to the dependency list issued two, and when the schema read was the
+slower of the two it painted raw ids, reverted to the "Loading calendar..." placeholder,
+then swapped — a three-step paint the correct rows do not arrive any later than.
+
+The gate is on the schema read having SETTLED, never on a truthy schema: an adapter that
+exposes no `getObjectSchema`, and a read that throws, both settle with nothing and the
+calendar still queries (unexpanded) rather than waiting forever. An inline `value` data set
+is deliberately not gated — it issues no metadata read, so there would be no resolution to
+wait for.

packages/plugin-calendar/src/ObjectCalendar.tsx

@@ -22,7 +22,7 @@
  * - Works with object/value data providers
  */
 
-import React, { useEffect, useState, useCallback, useMemo, useRef } from 'react';
+import React, { useEffect, useState, useCallback, useMemo } from 'react';
 import type { ObjectGridSchema, DataSource, ViewData, CalendarConfig } from '@object-ui/types';
 import { CalendarView } from './CalendarView';
 import { usePullToRefresh } from '@object-ui/mobile';
@@ -177,7 +177,12 @@ export const ObjectCalendar: React.FC<ObjectCalendarComponentProps> = ({
   const [data, setData] = useState<any[]>(hasExternalData ? externalData! : []);
   const [loading, setLoading] = useState(hasExternalData ? (externalLoading ?? false) : true);
   const [error, setError] = useState<Error | null>(null);
-  const [objectSchema, setObjectSchema] = useState<any>(null);
+  // The object-schema read and the fact that it has SETTLED are ONE piece of
+  // state, keyed by the object it belongs to (objectui#6453). The derived
+  // `objectSchema` / `objectSchemaReady` pair lives further down, next to
+  // `dataConfig`, because the key is the object the RECORD QUERY will use.
+  const [schemaResolution, setSchemaResolution] =
+    useState<{ key: string; def: any } | null>(null);
   const [currentDate, setCurrentDate] = useState(new Date());
   const isMobile = useIsMobile();
   const schemaDefaultView = (schema as any).defaultView as 'month' | 'week' | 'day' | undefined;
@@ -237,9 +242,33 @@ export const ObjectCalendar: React.FC<ObjectCalendarComponentProps> = ({
   ]);
   const hasInlineData = dataConfig?.provider === 'value';
 
-  // Use ref for objectSchema to avoid double-fetch on mount
-  const objectSchemaRef = useRef<any>(null);
-  objectSchemaRef.current = objectSchema;
+  // ⭐ objectui#6453 — this replaces a `useRef` written in the render body
+  // (`objectSchemaRef.current = objectSchema`), which existed so the fetch
+  // effect below could read the schema without listing it as a dependency.
+  // That bought the effect one run per mount and paid for it with the
+  // expansion, permanently: on that one run the ref was still `null`,
+  // `buildExpandFields` saw no fields, and the standalone calendar's query went
+  // out with no `$expand` at all — so every lookup / master_detail / user /
+  // tree field rendered from its raw foreign-key id, forever.
+  //
+  // The KEY is the object the record query will use, which on this component is
+  // NOT simply `schema.objectName`: an authored `data` block can name a
+  // different object. Comparing it during render means switching objects closes
+  // the gate in the same commit that changes it, not one commit later, so no
+  // query can carry the previous object's expand set.
+  const schemaObjectName =
+    dataConfig?.provider === 'object' ? dataConfig.object : schema.objectName;
+  const schemaKey = schemaObjectName ?? '';
+  /**
+   * Has the object schema for THIS object finished resolving? Note what this is
+   * NOT: "`objectSchema` is truthy". A calendar whose adapter exposes no
+   * `getObjectSchema`, or whose schema read failed, must still fetch its
+   * records — gating on a truthy schema would leave those calendars empty
+   * forever. "Settled with nothing" and "not yet settled" are different states
+   * and only the second may hold the query.
+   */
+  const objectSchemaReady = schemaResolution !== null && schemaResolution.key === schemaKey;
+  const objectSchema = objectSchemaReady ? schemaResolution.def : null;
 
   // Sync external data/loading changes from parent (e.g. ObjectView re-fetches after filter change)
   useEffect(() => {
@@ -259,6 +288,23 @@ export const ObjectCalendar: React.FC<ObjectCalendarComponentProps> = ({
     // Skip internal fetch when data is managed by a parent component
     if (hasExternalData) return;
 
+    // ⭐ objectui#6453 — the object schema GATES this query; it does not refine
+    // it afterwards. Measured on THIS component (instrumented adapter, three
+    // latency profiles), the alternative — putting `objectSchema` in the
+    // dependency list below — costs two queries and, when the schema read is
+    // the slower of the two, a THREE-step paint: raw ids, back to the
+    // "Loading calendar..." placeholder (this effect calls `setLoading(true)`
+    // on re-run, and `loading` is an early return above), then the expanded
+    // rows. When the schema read is the faster one the first response is
+    // instead discarded on arrival — a round trip bought and thrown away.
+    // Gating is the only shape that is right in every profile.
+    //
+    // Scoped to the `object` provider deliberately: an inline (`value`) data
+    // set has no expand set to derive and issues no metadata read at all, so
+    // gating it would hold a query open on a resolution nothing was going to
+    // produce.
+    if (dataConfig?.provider === 'object' && !objectSchemaReady) return;
+
     let isMounted = true;
     const fetchData = async () => {
       try {
@@ -280,7 +326,11 @@ export const ObjectCalendar: React.FC<ObjectCalendarComponentProps> = ({
         if (dataConfig?.provider === 'object') {
           const objectName = dataConfig.object;
           // Auto-inject $expand for lookup/master_detail fields
-          const expand = buildExpandFields(objectSchemaRef.current?.fields);
+          // Reached only with the schema resolved (the gate above), so a
+          // calendar whose object declares relations queries WITH its
+          // expansion the first time. `objectSchema` is `null` here only
+          // when there was nothing to resolve it from.
+          const expand = buildExpandFields(objectSchema?.fields);
           const result = await dataSource.find(objectName, {
             $filter: schema.filter,
             $orderby: convertSortToQueryParams(schema.sort),
@@ -309,31 +359,40 @@ export const ObjectCalendar: React.FC<ObjectCalendarComponentProps> = ({
 
     fetchData();
     return () => { isMounted = false; };
-  }, [hasExternalData, dataConfig, dataSource, hasInlineData, schema.filter, schema.sort, refreshKey]);
-
-  // Fetch object schema for field metadata
+  }, [hasExternalData, dataConfig, dataSource, hasInlineData, schema.filter, schema.sort,
+      refreshKey, objectSchemaReady, objectSchema]);
+
+  // Fetch object schema for field metadata.
+  //
+  // Every exit settles the resolution — success, failure, and "there is nothing
+  // to read from" alike — because the record query above WAITS on this
+  // (objectui#6453). A path that returned without settling would not merely
+  // skip the expansion, it would hold that query open forever.
   useEffect(() => {
+    let isMounted = true;
+    const key = schemaKey;
     const fetchObjectSchema = async () => {
+      // No source for a schema — including an inline (`value`) data set, which
+      // issues no metadata read here and did not before. Settle with none, so
+      // anything gated on this still runs (unexpanded: with no schema there is
+      // no expand set to derive, which is the same query these cases produced
+      // before).
+      if (hasInlineData || !dataSource || !key || typeof dataSource.getObjectSchema !== 'function') {
+        if (isMounted) setSchemaResolution({ key, def: null });
+        return;
+      }
       try {
-        if (!dataSource) return;
-        
-        const objectName = dataConfig?.provider === 'object' 
-          ? dataConfig.object 
-          : schema.objectName;
-          
-        if (!objectName) return;
-        
-        const schemaData = await dataSource.getObjectSchema(objectName);
-        setObjectSchema(schemaData);
+        const schemaData = await dataSource.getObjectSchema(key);
+        if (isMounted) setSchemaResolution({ key, def: schemaData });
       } catch (err) {
         console.error('Failed to fetch object schema:', err);
+        if (isMounted) setSchemaResolution({ key, def: null });
       }
     };
 
-    if (!hasInlineData && dataSource) {
-      fetchObjectSchema();
-    }
-  }, [schema.objectName, dataSource, hasInlineData, dataConfig]);
+    fetchObjectSchema();
+    return () => { isMounted = false; };
+  }, [schemaKey, dataSource, hasInlineData]);
 
   // Transform data to calendar events
   const events = useMemo(() => {