From ff05e60ff0426f67fb701ee0df24f2eafd289235 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 26 Aug 2026 12:01:25 +0000 Subject: [PATCH] docs(types): expand the flat gantt face's four bare GanttConfig pointers MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `colorField`, `parentField`, `tooltipFields` and `quickFilters` on `ObjectGanttSchema`'s flattened gantt face carried a bare `See {@link GanttConfig}.` pointer. All four arrive from the spec half of `SpecGanttConfig & { … }` — the local half declares exactly ten top-level members and none of these is among them — and the spec's emitted `.d.ts` carries no per-member JSDoc, so the pointer led to a type documenting nothing about the key. Each one-liner now stands alone, written from the renderer's live read sites in `plugin-gantt`. The seven member-qualified pointers (`{@link GanttConfig.borderColorField}` and friends) name members of the local half, resolve to real prose, and are untouched. Prose only. Measured on the built artifact, not asserted: `ObjectGanttSchema` keeps all 45 members with checker-resolved types byte-identical, and the built face's 51 declaration lines diff clean with comments stripped. The four bare pointers went 4 to 0 in `dist/objectql.d.ts`; the seven qualified ones stayed at 7. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_011SfZeFWrhGLHmfq61xbz4q --- .changeset/6547-flat-gantt-face-pointers.md | 43 +++++++++++++++++++++ packages/types/src/objectql.ts | 38 ++++++++++++++++-- 2 files changed, 77 insertions(+), 4 deletions(-) create mode 100644 .changeset/6547-flat-gantt-face-pointers.md diff --git a/.changeset/6547-flat-gantt-face-pointers.md b/.changeset/6547-flat-gantt-face-pointers.md new file mode 100644 index 000000000..aa716d266 --- /dev/null +++ b/.changeset/6547-flat-gantt-face-pointers.md @@ -0,0 +1,43 @@ +--- +'@object-ui/types': patch +--- + +`ObjectGanttSchema`'s flattened gantt face documents `colorField`, `parentField`, +`tooltipFields` and `quickFilters` in its own words, instead of pointing at a type that +says nothing about them (objectui#6547). + +Those four members carried a bare `See {@link GanttConfig}.` pointer. `GanttConfig` is +`SpecGanttConfig & { … }`, and all four arrive from the **spec** half: the local half of +that intersection declares exactly ten top-level members (`timeSegments`, `lockField`, +`objectField`, `summaryExtent`, `defaultCollapsedDepth`, `borderColorField`, +`dependencyTypes`, `timeZone`, `exportFileName`, `interactions`) and none of these four is +among them. `SpecGanttConfig` is `z.input`, and the spec's +emitted `.d.ts` carries no per-member JSDoc — its 19 members are bare `z.ZodOptional` +entries under one type-level "Gantt Settings" docblock. So the pointer was not merely +unhelpful, it was misdirecting: a reader who followed it landed on a type documenting +nothing about the key and concluded the key was undocumented. + +Verified on the built artifact rather than the source: all four bare pointers were present +in `dist/objectql.d.ts` before this change and none is after, so the defect was on the +published surface and the repair reaches it. + +**Prose only — the published shape is unchanged, and that is the point.** The natural +repair, writing the prose onto `GanttConfig`, means re-declaring these members inside the +intersection; PR objectui#6546 measured that as a widened published surface on the built +`dist/index.d.ts` and it was rejected there. So the shape was measured, not asserted: +`ObjectGanttSchema`'s 45 members and their checker-resolved types are byte-identical +before and after, and the built face's 51 declaration lines diff clean with comments +stripped. Only comment bytes moved. + +The seven **member-qualified** pointers (`See {@link GanttConfig.borderColorField}`, +`.lockField`, `.summaryExtent`, `.defaultCollapsedDepth`, `.timeSegments`, +`.interactions`, `.exportFileName`) name members of that ten-member local half, resolve to +real prose, and are deliberately left alone — the defect is the bare form, and a substring +search for `{@link GanttConfig` hits both. + +The prose is taken from the renderer's live read sites in `plugin-gantt`, not invented: +`colorField`'s status/state/priority/severity fallback chain and the platform default +blue, `parentField`'s unknown-id-renders-as-root rule, `tooltipFields`' drop-empty-rows +behaviour (which is what lets a mixed-object tree list the union of every level's fields) +and its replacement of the default date · duration · progress tooltip line, and +`quickFilters`' schema-resolved option domains. No behaviour change, no runtime code. diff --git a/packages/types/src/objectql.ts b/packages/types/src/objectql.ts index 573e194df..6c82feaf4 100644 --- a/packages/types/src/objectql.ts +++ b/packages/types/src/objectql.ts @@ -2417,7 +2417,14 @@ export interface ObjectGanttSchema extends BaseSchema { // instead of being dropped silently. So a node carrying both spellings renders // the `gantt` block's values — the reverse of the pre-#6469 order. - /** Record field carrying the bar fill colour. See {@link GanttConfig}. */ + /** + * Record field carrying the bar's FILL colour: any CSS colour or a semantic + * palette name (red/orange/…), typically a server-computed status colour. + * When it is unset — or when the record's value is empty — the bar falls back + * to the record's own `status`/`state`/`priority`/`severity` value, so the + * timeline tells the same colour story as list/kanban. With neither, bars + * take the platform default blue. + */ colorField?: GanttConfig['colorField']; /** Per-task alert stroke colour field. See {@link GanttConfig.borderColorField}. */ borderColorField?: GanttConfig['borderColorField']; @@ -2428,7 +2435,14 @@ export interface ObjectGanttSchema extends BaseSchema { * alias and this one wins. */ dependenciesField?: GanttConfig['dependenciesField']; - /** Single-parent pointer field building the task tree. See {@link GanttConfig}. */ + /** + * Record field holding this row's PARENT id — the single-parent pointer the + * task tree is built from: indentation, expand/collapse and summary rollup + * all follow it. An empty value, or one naming no loaded row, renders that + * row as a root. Leave unset for a flat chart; `groupByField` is the + * alternative, bucketing leaves under synthesized rows instead of a + * record-declared hierarchy. + */ parentField?: GanttConfig['parentField']; /** Record field mapping onto a node kind (task/summary/milestone/group). */ typeField?: GanttConfig['typeField']; @@ -2440,7 +2454,16 @@ export interface ObjectGanttSchema extends BaseSchema { summaryExtent?: GanttConfig['summaryExtent']; /** Auto-collapse depth on first render. See {@link GanttConfig.defaultCollapsedDepth}. */ defaultCollapsedDepth?: GanttConfig['defaultCollapsedDepth']; - /** Extra record fields listed in the bar tooltip. See {@link GanttConfig}. */ + /** + * Extra record fields listed as label/value rows in a bar's hover tooltip, in + * the order given. Each entry is a field name (dot-paths allowed) or + * `{ field, label }` to set the label explicitly; otherwise the label comes + * from the object schema, falling back to a humanized field name, and the + * value is formatted by field type the way a list cell would render it. A row + * whose value is empty is DROPPED rather than dashed, so a mixed-object tree + * can list the union of every level's fields here. Any surviving rows replace + * the tooltip's default date · duration · progress line. + */ tooltipFields?: GanttConfig['tooltipFields']; /** Baseline (planned) start field → planned-vs-actual reference bars. */ baselineStartField?: GanttConfig['baselineStartField']; @@ -2456,7 +2479,14 @@ export interface ObjectGanttSchema extends BaseSchema { effortField?: GanttConfig['effortField']; /** Per-resource capacity ceiling (default 1); loads above it flag overload. */ capacity?: GanttConfig['capacity']; - /** Quick-filter dropdowns rendered above the chart. See {@link GanttConfig}. */ + /** + * Quick-filter dropdowns rendered above the chart — a row of multi-selects, + * each narrowing the visible bars by one record field. A dimension's options + * resolve from the object schema (a select's options, or the referenced + * records for a lookup), so the dropdown offers that field's full domain + * rather than only the values present in the loaded page; declare `options` + * on the dimension to override that with a fixed list. + */ quickFilters?: GanttConfig['quickFilters']; /** Recompute the timeline range when filtering (default true). */ autoZoomToFilter?: GanttConfig['autoZoomToFilter'];