From 5bf697c60cb74a6d5c470ab2d7b855c2fdfb6348 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 7 Sep 2026 00:18:45 +0000 Subject: [PATCH] docs(providers): compile every README snippet against the shipped surface MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `packages/providers/README.md` leaves the `UNGATED_DOCS` ledger in `scripts/check-doc-snippet-types.mjs` and joins the compiled tier of `check:doc-snippets` (objectui#5174, batch 29). The ledger row read `7 undefined-name diagnostic(s) … plus TS2741x1`. Measured with the gate's own analyzer, the seven undefined names were ambient values the page never defined (`myCustomDataSource`; `App` in the three provider fences; `myMetadata` twice; `myDataSource`) — the Usage Example defines its own `App`, so that name is a stand-in three times, not four. After adding only `declare` stand-ins, one diagnostic remained: `TS2741` — `children` missing on the `MetadataProvider` of the Usage Example, whose only child was a placeholder comment. `MetadataProviderProps` declares `children: ReactNode` required, so the page was teaching a comment as a value; it now nests a real element. Each stand-in is typed from the prop it is passed to (`DataSourceProviderProps['dataSource']`, `MetadataProviderProps['metadata']`, `() => ReactNode`). Both data bounds are declared `any` today, and the fences say so rather than inventing a stronger type — the laundering objectui#8160 and objectui#7912 already track. No type widened, no fragment marker added, no `@ts-expect-error`, and nothing under `packages/providers/src/**` touched. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01FhBNJcLRZLe8M87VcUgpKr --- packages/providers/README.md | 48 ++++++++++++++++++++++++++--- scripts/check-doc-snippet-types.mjs | 2 -- 2 files changed, 44 insertions(+), 6 deletions(-) diff --git a/packages/providers/README.md b/packages/providers/README.md index f5e07bb534..3e986a6de1 100644 --- a/packages/providers/README.md +++ b/packages/providers/README.md @@ -12,12 +12,24 @@ pnpm add @object-ui/providers ## Providers +Every example below compiles against this package's built types. The values your +own app supplies are written as `declare const` stand-ins so each block stands +alone, and each stand-in is typed from the prop it is passed to — so the bound +the example teaches is the bound the package actually declares. + ### DataSourceProvider Generic data source context that decouples ObjectUI from ObjectStack. ```tsx -import { DataSourceProvider } from '@object-ui/providers'; +import type { ReactNode } from 'react'; +import { DataSourceProvider, type DataSourceProviderProps } from '@object-ui/providers'; + +// `DataSourceProviderProps['dataSource']` is declared `any` today, so this +// stand-in inherits `any`: the compiler checks nothing about the adapter's +// shape here (objectui#8160, objectui#7912 track that laundering). +declare const myCustomDataSource: DataSourceProviderProps['dataSource']; +declare const App: () => ReactNode; @@ -29,7 +41,13 @@ import { DataSourceProvider } from '@object-ui/providers'; Schema/metadata management for objects, fields, and views. ```tsx -import { MetadataProvider } from '@object-ui/providers'; +import type { ReactNode } from 'react'; +import { MetadataProvider, type MetadataProviderProps } from '@object-ui/providers'; + +// `MetadataProviderProps['metadata']` is declared `any` today — same bound as +// `dataSource` above, so nothing about this object's shape is checked here. +declare const myMetadata: MetadataProviderProps['metadata']; +declare const App: () => ReactNode; @@ -40,9 +58,15 @@ import { MetadataProvider } from '@object-ui/providers'; Theme management with system theme detection. +`defaultTheme` takes a `ThemePreference` (`auto | light | dark | system`); both +props are optional. + ```tsx +import type { ReactNode } from 'react'; import { ThemeProvider } from '@object-ui/providers'; +declare const App: () => ReactNode; + @@ -50,15 +74,31 @@ import { ThemeProvider } from '@object-ui/providers'; ## Usage Example +`DataSourceProvider` and `MetadataProvider` both declare `children` as required, +so each one needs a real element inside it — a placeholder comment is not a +child. + ```tsx -import { DataSourceProvider, MetadataProvider, ThemeProvider } from '@object-ui/providers'; +import type { ReactNode } from 'react'; +import { + DataSourceProvider, + MetadataProvider, + ThemeProvider, + type DataSourceProviderProps, + type MetadataProviderProps, +} from '@object-ui/providers'; + +declare const myDataSource: DataSourceProviderProps['dataSource']; +declare const myMetadata: MetadataProviderProps['metadata']; +// Your own component tree goes here. +declare const AppContent: () => ReactNode; function App() { return ( - {/* Your app components */} + diff --git a/scripts/check-doc-snippet-types.mjs b/scripts/check-doc-snippet-types.mjs index aafad4af4c..9a427c58d5 100644 --- a/scripts/check-doc-snippet-types.mjs +++ b/scripts/check-doc-snippet-types.mjs @@ -789,8 +789,6 @@ const UNGATED_DOCS = { '2 parse diagnostic(s) — blocks fenced `ts` that are bare object literals or elided bodies', 'packages/plugin-tree/README.md': '3 parse diagnostic(s) — blocks fenced `ts` that are bare object literals or elided bodies', - 'packages/providers/README.md': - '7 undefined-name diagnostic(s) — blocks continue an earlier block, or use ambient names the page never defines; plus TS2741x1 — candidate real defects, un-triaged', }; // ── Fence scanning ───────────────────────────────────────────────────────────