docs(types): the content-channel tombstones state the BaseSchema premise in the tense it is true (objectui#9933)

.changeset/9933-stale-baseschema-premise-docblocks.md

@@ -0,0 +1,11 @@
+---
+'@object-ui/types': patch
+---
+
+Correct a stale premise in the published declaration docs of the content-channel tombstones (objectui#9933).
+
+The `body?: never` / `children?: never` docblocks of the components that read neither content channel (objectui#9256), and the `body?: never` docblocks of the components that read `children` (objectui#8284: `box`, `span`, `container`, `flex`, `stack`, `grid`, `scroll-area`, `form`, `toggle`), justified each tombstone with a present-tense premise: that `body` (and `children`) are inherited-and-optional from `BaseSchema`, and that `BaseSchema`'s own docblock concedes the two spellings without saying which component reads which. Since objectui#6771 retired the `body` spelling, that premise is false: `BaseSchema.body` is `never`, and `BaseSchema`'s own docblock no longer admits the two-spelling ambiguity. These docblocks ship in the emitted `.d.ts`, so a declarations reader was taught the premise the retirement removed.
+
+Each paragraph now dates the inherited-and-optional state to before its own tombstone and states the present: `BaseSchema` refuses `body` itself and still declares `children`, which the neither-channel tombstone refuses. The rest of each docblock — what the renderer reads, how that was measured, and the `@deprecated` remedy — is unchanged.
+
+Comment text only: no declaration, member, type or export moves, and every authored document type-checks and parses exactly as it did before.

packages/types/src/ai.ts

@@ -201,12 +201,14 @@ export interface AIFormAssistSchema extends BaseSchema {
    * the props bag `SchemaRenderer` spreads rather than from `schema.*`, and
    * carries zero `body` / `children` reads either way.
    *
-   * `body` and `children` are inherited-and-optional from {@link BaseSchema},
-   * whose own docblock admits "some components use `children` instead of
-   * `body`" without saying which — so authoring either here type-checked,
-   * parsed green through `.passthrough()`, and rendered NOTHING: no error, no
-   * warning, no element. `SchemaRenderer` strips both keys out of the props bag
-   * it spreads, so neither reaches the component by another route either.
+   * Before objectui#9256 tombstoned them here, `body` and `children` were both
+   * inherited-and-optional from {@link BaseSchema} — so authoring either here
+   * type-checked, parsed green through `.passthrough()`, and rendered NOTHING:
+   * no error, no warning, no element. objectui#6771 has since retired `body` on
+   * `BaseSchema` itself; `BaseSchema` still declares `children`, so this node's
+   * own tombstone is what refuses it here. `SchemaRenderer` strips both keys
+   * out of the props bag it spreads, so neither reaches the component by
+   * another route either.
    *
    * @deprecated Not a channel `ai-form-assist` reads — nothing renders it.
    */
@@ -225,12 +227,14 @@ export interface AIFormAssistSchema extends BaseSchema {
    * the props bag `SchemaRenderer` spreads rather than from `schema.*`, and
    * carries zero `body` / `children` reads either way.
    *
-   * `body` and `children` are inherited-and-optional from {@link BaseSchema},
-   * whose own docblock admits "some components use `children` instead of
-   * `body`" without saying which — so authoring either here type-checked,
-   * parsed green through `.passthrough()`, and rendered NOTHING: no error, no
-   * warning, no element. `SchemaRenderer` strips both keys out of the props bag
-   * it spreads, so neither reaches the component by another route either.
+   * Before objectui#9256 tombstoned them here, `body` and `children` were both
+   * inherited-and-optional from {@link BaseSchema} — so authoring either here
+   * type-checked, parsed green through `.passthrough()`, and rendered NOTHING:
+   * no error, no warning, no element. objectui#6771 has since retired `body` on
+   * `BaseSchema` itself; `BaseSchema` still declares `children`, so this node's
+   * own tombstone is what refuses it here. `SchemaRenderer` strips both keys
+   * out of the props bag it spreads, so neither reaches the component by
+   * another route either.
    *
    * @deprecated Not a channel `ai-form-assist` reads — nothing renders it.
    */
@@ -384,12 +388,14 @@ export interface AIRecommendationsSchema extends BaseSchema {
    * the props bag `SchemaRenderer` spreads rather than from `schema.*`, and
    * carries zero `body` / `children` reads either way.
    *
-   * `body` and `children` are inherited-and-optional from {@link BaseSchema},
-   * whose own docblock admits "some components use `children` instead of
-   * `body`" without saying which — so authoring either here type-checked,
-   * parsed green through `.passthrough()`, and rendered NOTHING: no error, no
-   * warning, no element. `SchemaRenderer` strips both keys out of the props bag
-   * it spreads, so neither reaches the component by another route either.
+   * Before objectui#9256 tombstoned them here, `body` and `children` were both
+   * inherited-and-optional from {@link BaseSchema} — so authoring either here
+   * type-checked, parsed green through `.passthrough()`, and rendered NOTHING:
+   * no error, no warning, no element. objectui#6771 has since retired `body` on
+   * `BaseSchema` itself; `BaseSchema` still declares `children`, so this node's
+   * own tombstone is what refuses it here. `SchemaRenderer` strips both keys
+   * out of the props bag it spreads, so neither reaches the component by
+   * another route either.
    *
    * @deprecated Not a channel `ai-recommendations` reads — nothing renders it.
    */
@@ -408,12 +414,14 @@ export interface AIRecommendationsSchema extends BaseSchema {
    * the props bag `SchemaRenderer` spreads rather than from `schema.*`, and
    * carries zero `body` / `children` reads either way.
    *
-   * `body` and `children` are inherited-and-optional from {@link BaseSchema},
-   * whose own docblock admits "some components use `children` instead of
-   * `body`" without saying which — so authoring either here type-checked,
-   * parsed green through `.passthrough()`, and rendered NOTHING: no error, no
-   * warning, no element. `SchemaRenderer` strips both keys out of the props bag
-   * it spreads, so neither reaches the component by another route either.
+   * Before objectui#9256 tombstoned them here, `body` and `children` were both
+   * inherited-and-optional from {@link BaseSchema} — so authoring either here
+   * type-checked, parsed green through `.passthrough()`, and rendered NOTHING:
+   * no error, no warning, no element. objectui#6771 has since retired `body` on
+   * `BaseSchema` itself; `BaseSchema` still declares `children`, so this node's
+   * own tombstone is what refuses it here. `SchemaRenderer` strips both keys
+   * out of the props bag it spreads, so neither reaches the component by
+   * another route either.
    *
    * @deprecated Not a channel `ai-recommendations` reads — nothing renders it.
    */
@@ -549,12 +557,14 @@ export interface NLQuerySchema extends BaseSchema {
    * the props bag `SchemaRenderer` spreads rather than from `schema.*`, and
    * carries zero `body` / `children` reads either way.
    *
-   * `body` and `children` are inherited-and-optional from {@link BaseSchema},
-   * whose own docblock admits "some components use `children` instead of
-   * `body`" without saying which — so authoring either here type-checked,
-   * parsed green through `.passthrough()`, and rendered NOTHING: no error, no
-   * warning, no element. `SchemaRenderer` strips both keys out of the props bag
-   * it spreads, so neither reaches the component by another route either.
+   * Before objectui#9256 tombstoned them here, `body` and `children` were both
+   * inherited-and-optional from {@link BaseSchema} — so authoring either here
+   * type-checked, parsed green through `.passthrough()`, and rendered NOTHING:
+   * no error, no warning, no element. objectui#6771 has since retired `body` on
+   * `BaseSchema` itself; `BaseSchema` still declares `children`, so this node's
+   * own tombstone is what refuses it here. `SchemaRenderer` strips both keys
+   * out of the props bag it spreads, so neither reaches the component by
+   * another route either.
    *
    * @deprecated Not a channel `nl-query` reads — nothing renders it.
    */
@@ -573,12 +583,14 @@ export interface NLQuerySchema extends BaseSchema {
    * the props bag `SchemaRenderer` spreads rather than from `schema.*`, and
    * carries zero `body` / `children` reads either way.
    *
-   * `body` and `children` are inherited-and-optional from {@link BaseSchema},
-   * whose own docblock admits "some components use `children` instead of
-   * `body`" without saying which — so authoring either here type-checked,
-   * parsed green through `.passthrough()`, and rendered NOTHING: no error, no
-   * warning, no element. `SchemaRenderer` strips both keys out of the props bag
-   * it spreads, so neither reaches the component by another route either.
+   * Before objectui#9256 tombstoned them here, `body` and `children` were both
+   * inherited-and-optional from {@link BaseSchema} — so authoring either here
+   * type-checked, parsed green through `.passthrough()`, and rendered NOTHING:
+   * no error, no warning, no element. objectui#6771 has since retired `body` on
+   * `BaseSchema` itself; `BaseSchema` still declares `children`, so this node's
+   * own tombstone is what refuses it here. `SchemaRenderer` strips both keys
+   * out of the props bag it spreads, so neither reaches the component by
+   * another route either.
    *
    * @deprecated Not a channel `nl-query` reads — nothing renders it.
    */