docs(types): expand the flat gantt face's four bare GanttConfig pointers

.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<typeof GanttConfigSchema>`, 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.

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'];