diff --git a/.changeset/9933-stale-baseschema-premise-docblocks.md b/.changeset/9933-stale-baseschema-premise-docblocks.md new file mode 100644 index 0000000000..1c4d0c7333 --- /dev/null +++ b/.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. diff --git a/packages/types/src/ai.ts b/packages/types/src/ai.ts index 50189d910a..2f814d3076 100644 --- a/packages/types/src/ai.ts +++ b/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. */ diff --git a/packages/types/src/complex.ts b/packages/types/src/complex.ts index 568fb62175..aa400c43c2 100644 --- a/packages/types/src/complex.ts +++ b/packages/types/src/complex.ts @@ -442,12 +442,14 @@ export interface CalendarViewSchema extends BaseSchema { * `titleField` (in * `packages/plugin-calendar/src/calendar-view-renderer.tsx`). * - * `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 `calendar-view` reads — nothing renders it. */ @@ -467,12 +469,14 @@ export interface CalendarViewSchema extends BaseSchema { * `titleField` (in * `packages/plugin-calendar/src/calendar-view-renderer.tsx`). * - * `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 `calendar-view` reads — nothing renders it. */ @@ -632,12 +636,14 @@ export interface FilterBuilderSchema extends BaseSchema { * `fields`, `label`, `name`, `value`, `wrapperClass` (in * `packages/components/src/renderers/complex/filter-builder.tsx`). * - * `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 `filter-builder` reads — nothing renders it. */ @@ -656,12 +662,14 @@ export interface FilterBuilderSchema extends BaseSchema { * `fields`, `label`, `name`, `value`, `wrapperClass` (in * `packages/components/src/renderers/complex/filter-builder.tsx`). * - * `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 `filter-builder` reads — nothing renders it. */ @@ -848,12 +856,14 @@ export interface CarouselSchema extends BaseSchema { * `itemClassName`, `items`, `opts`, `orientation`, `showArrows` (in * `packages/components/src/renderers/complex/carousel.tsx`). * - * `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 `carousel` reads — nothing renders it. */ @@ -872,12 +882,14 @@ export interface CarouselSchema extends BaseSchema { * `itemClassName`, `items`, `opts`, `orientation`, `showArrows` (in * `packages/components/src/renderers/complex/carousel.tsx`). * - * `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 `carousel` reads — nothing renders it. */ @@ -1592,12 +1604,14 @@ export interface ChatbotSchema extends BaseSchema { * `systemPrompt`, `userAvatarFallback`, `userAvatarUrl` (in * `packages/plugin-chatbot/src/renderer.tsx`). * - * `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 `chatbot` reads — nothing renders it. */ @@ -1741,12 +1755,14 @@ export interface ChatbotEnhancedSchema * `streamingEnabled`, `surface`, `systemPrompt`, `userAvatarFallback`, * `userAvatarUrl` (in `packages/plugin-chatbot/src/renderer.tsx`). * - * `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 `chatbot-enhanced` reads — nothing renders it. */ @@ -1855,12 +1871,14 @@ export interface ChatbotFloatingSchema * `systemPrompt`, `userAvatarFallback`, `userAvatarUrl` (in * `packages/plugin-chatbot/src/renderer.tsx`). * - * `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 `chatbot-floating` reads — nothing renders it. */ @@ -2369,12 +2387,14 @@ export interface DashboardComponentSchema extends BaseSchema, Omit