fix(types): drop stale source-line citations from 12 published describe() strings (objectui#8478)

.changeset/8478-describe-line-addresses.md

@@ -0,0 +1,25 @@
+---
+'@object-ui/types': patch
+---
+
+Remove stale source-line citations (`NAME.ext:NNN`) from twelve published `.describe()`
+schema descriptions in `packages/types/src/zod/overlay.zod.ts`,
+`zod/data-display.zod.ts` and `zod/objectql.zod.ts` (objectstack-ai/objectui#8478).
+
+Text only — no accept-set, key, or shape change. Each description was either trimmed to
+its author-useful sentence (the line address removed, with no loss: the same detail is
+already duplicated in an adjacent maintainer-facing JSDoc comment), or rewritten to cite
+the same fact by identifier/behavior instead of by file:line (e.g. "forwarded as `align`
+on `HoverCardContent`" instead of "read at renderers/overlay/hover-card.tsx:24"), which
+survives a line renumbering that a bare address would not.
+
+One of the twelve addresses removed here (`ObjectKanban.tsx:264` on the `limit` field's
+description) was measured to have already drifted — the cited line is now unrelated
+permissions code; the real read site is `ObjectKanban.tsx:365`. Filed back on
+objectstack-ai/objectui#8478 as the drift evidence its own re-grade trigger asked for.
+
+The remaining 15 addresses (`form.zod.ts`, `layout.zod.ts`, `complex.zod.ts`) are out of
+scope for this PR — held by in-flight PR objectstack-ai/objectui#8763 (`form.zod.ts` /
+`layout.zod.ts`); `complex.zod.ts`'s hold (PR objectstack-ai/objectui#8766) cleared when
+that PR merged during this round, so its 6 addresses return to the queue rather than
+riding this PR's scope.

packages/types/src/zod/data-display.zod.ts

@@ -127,7 +127,7 @@ export const ListSchema = BaseSchema.extend({
   dividers: z.boolean().optional().describe('Show dividers between items'),
   dense: z.boolean().optional().describe('Dense spacing'),
   wrapperClass: z.string().optional()
-    .describe('Classes on the wrapper div around the title and the list, read at renderers/data-display/list.tsx:27 — `cn("space-y-2", schema.wrapperClass)` (objectui#7722)'),
+    .describe('Classes on the wrapper div around the title and the list — merged with the base `space-y-2` (objectui#7722)'),
 });
 
 /**
@@ -394,9 +394,9 @@ export const TreeViewSchema = BaseSchema.extend({
     + 'authored `data` would render an empty tree. Rename the key; the array is unchanged.',
   ),
   nodes: z.array(TreeNodeSchema).optional()
-    .describe('Inline tree nodes — the one inline spelling, read at renderers/data-display/tree-view.tsx:105 as the second limb of `boundData || schema.nodes || []` (a `bind`-resolved value wins, so this stays optional and no presence rule exists — objectui#6951 B1). Declared by objectui#6150; a `nodes`-only document became LEGAL at objectui#6939; the `data` fallback spelling was retired by objectui#6951 (the registration\'s own `inputs` and `defaultProps` spell it `nodes`, and the four catalog entries ARE those `defaultProps`)'),
+    .describe('Inline tree nodes — the one inline spelling, read as the second limb of `boundData || schema.nodes || []` (a `bind`-resolved value wins, so this stays optional and no presence rule exists — objectui#6951 B1). Declared by objectui#6150; a `nodes`-only document became LEGAL at objectui#6939; the `data` fallback spelling was retired by objectui#6951 (the registration\'s own `inputs` and `defaultProps` spell it `nodes`, and the four catalog entries ARE those `defaultProps`)'),
   title: z.string().optional()
-    .describe('Heading above the tree, read at renderers/data-display/tree-view.tsx:115 (presence gate) and :117 (the h3 body) (objectui#6150)'),
+    .describe('Heading above the tree — renders only when set (objectui#6150)'),
   defaultExpandedIds: z.array(z.string()).optional().describe('Default expanded node IDs'),
   defaultSelectedIds: z.array(z.string()).optional().describe('Default selected node IDs'),
   expandedIds: z.array(z.string()).optional().describe('Controlled expanded node IDs'),

packages/types/src/zod/objectql.zod.ts

@@ -1194,7 +1194,7 @@ export const ObjectKanbanSchema = BaseSchema.extend({
   objectName: z.string().optional().describe('ObjectQL object name — the LAST rung of the board ladder, after the pre-fetched data prop, bind and the inline row array on data; one of bind, data, objectName must be present (objectui#7780)'),
   groupBy: z.string().describe('Field whose value places a record in a lane — the lane key the object-kanban renderer reads (ObjectKanban.tsx, thirteen sites); required, as the retired groupField was'),
   groupField: retirementTombstone('RETIRED (objectui#7322) — `groupField` is not read by the object-kanban renderer; author `groupBy`. (The view-level `kanban.groupField` alias is unaffected.)'),
-  limit: z.number().int().positive().optional().describe('Row cap — the most records the board fetches, sent as a real $top on the query (ObjectKanban.tsx:264); default 100 (DEFAULT_KANBAN_LIMIT)'),
+  limit: z.number().int().positive().optional().describe('Row cap — the most records the board fetches, sent as a real $top on the query; default 100 (DEFAULT_KANBAN_LIMIT)'),
   titleField: z.string().optional().describe('Title field'),
   cardFields: z.array(z.string()).optional().describe('Card fields'),
   quickAdd: z.boolean().optional().describe('Enable Quick Add button at column bottom'),

packages/types/src/zod/overlay.zod.ts

@@ -141,11 +141,11 @@ export const PopoverSchema = BaseSchema.extend({
 export const TooltipSchema = BaseSchema.extend({
   type: z.literal('tooltip'),
   trigger: z.union([SchemaNodeSchema, z.array(SchemaNodeSchema)]).optional()
-    .describe('Element the tooltip attaches to, read at renderers/overlay/tooltip.tsx:28 — `renderChildren(schema.trigger)` inside `TooltipTrigger` (objectui#6939)'),
+    .describe('Element the tooltip attaches to (objectui#6939)'),
   content: z.union([SchemaNodeSchema, z.array(SchemaNodeSchema)]).optional()
-    .describe('Tooltip content, read FIRST at renderers/overlay/tooltip.tsx:31 — `schema.content || renderChildren(schema.body)`. Optional because `body` is the other half of that read (objectui#6939)'),
+    .describe('Tooltip content, checked before `body` — optional because `body` is the fallback for the same slot (objectui#6939)'),
   body: z.union([SchemaNodeSchema, z.array(SchemaNodeSchema)]).optional()
-    .describe('Rich tooltip content — the fallback half of the same read at renderers/overlay/tooltip.tsx:31, listed by the registration as the "Rich Content" slot (objectui#6939)'),
+    .describe('Rich tooltip content — the fallback for `content`, listed by the registration as the "Rich Content" slot (objectui#6939)'),
   side: z.enum(['top', 'right', 'bottom', 'left']).optional().describe('Tooltip side'),
   align: z.enum(['start', 'center', 'end']).optional().describe('Tooltip alignment'),
   delayDuration: z.number().optional().describe('Delay before showing (ms)'),
@@ -162,7 +162,7 @@ export const HoverCardSchema = BaseSchema.extend({
   open: z.boolean().optional().describe('Controlled open state'),
   side: z.enum(['top', 'right', 'bottom', 'left']).optional().describe('Hover card side'),
   align: z.enum(['start', 'center', 'end']).optional()
-    .describe('Alignment against the trigger, read at renderers/overlay/hover-card.tsx:24 — `align={schema.align}` on HoverCardContent, beside the already-declared `side` (objectui#6150)'),
+    .describe('Alignment against the trigger, forwarded as `align` on `HoverCardContent`, beside the already-declared `side` (objectui#6150)'),
   openDelay: z.number().optional().describe('Delay before opening (ms)'),
   closeDelay: z.number().optional().describe('Delay before closing (ms)'),
   onOpenChange: handlerKeyRefusal('onOpenChange', 'runtime-slot', 'Open change handler'),
@@ -246,13 +246,13 @@ export const ContextMenuSchema = BaseSchema.extend({
   type: z.literal('context-menu'),
   items: z.array(MenuItemSchema).describe('Menu items'),
   trigger: z.union([SchemaNodeSchema, z.array(SchemaNodeSchema)]).optional()
-    .describe("Right-clickable area, read at renderers/overlay/context-menu.tsx:95 — `renderChildren(schema.trigger || {type:'text', value:'Right click here'})`. Optional: the renderer substitutes a placeholder, so trigger-less documents are legal today (objectui#6150)"),
+    .describe("Right-clickable area. Optional: the renderer substitutes a placeholder (`Right click here`) when omitted, so trigger-less documents are legal today (objectui#6150)"),
   triggerClassName: z.string().optional()
-    .describe('Classes for the right-clickable area, read FIRST at renderers/overlay/context-menu.tsx:87 — `schema.triggerClassName || className || schema.className || <a dashed-border default>` (objectui#6939)'),
+    .describe('Classes for the right-clickable area — falls back to `className` / `schema.className`, or a dashed-border default when none are set (objectui#6939)'),
   contentClassName: z.string().optional()
-    .describe('Classes for the menu panel, read at renderers/overlay/context-menu.tsx:88 and applied to `ContextMenuContent` at :98 (objectui#6939)'),
+    .describe('Classes for the menu panel, applied to the underlying `ContextMenuContent` (objectui#6939)'),
   modal: z.boolean().optional()
-    .describe('Forwarded to the Radix `ContextMenu` root at renderers/overlay/context-menu.tsx:91 — `modal={schema.modal}` (objectui#6939)'),
+    .describe('Forwarded to the Radix `ContextMenu` root as `modal` (objectui#6939)'),
 });
 
 /**