From 0ee362ae82e184c647391736df42069ff28c3f8c Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 7 Sep 2026 02:53:46 +0000 Subject: [PATCH] docs(plugin-charts): compile the README's snippets against the shipped surface MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Burn down `packages/plugin-charts/README.md`'s UNGATED_DOCS entry in scripts/check-doc-snippet-types.mjs so the gate compiles the page instead of ledgering it (objectui#5174, batch 31). The row read "6 parse diagnostic(s)". Measured with the gate's own analyzer, all six were TS1109 on one block — the "Schema API" fence, a TYPE shape written as an object literal, one diagnostic per optional member. A parse-only row hides the semantic phase, so the page's other three fences had never been judged at all. - Schema API: the fence is replaced by a members table. It re-declared the published `BarChartSchema` instead of importing it, so the gate would have judged a private copy of the contract; a table teaches the members without teaching the copy. - The bare `const schema = { … }` is annotated `BarChartSchema` and imports the type, so its keys are now checked against the declaration. - The manual-registration loop passes `{ namespace: 'plugin-charts' }`, the shipped call. `register()` with two arguments is the deprecated form and warns at runtime. - `color`'s documented default was `'#8884d8'`, which nothing on the render path reads; the renderer defaults it to the theme token. Corrected, with the drift named. - `chart-bar` is not a registered keyword; both occurrences now read `bar-chart`. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01FhBNJcLRZLe8M87VcUgpKr --- packages/plugin-charts/README.md | 49 +++++++++++++++++++---------- scripts/check-doc-snippet-types.mjs | 2 -- 2 files changed, 32 insertions(+), 19 deletions(-) diff --git a/packages/plugin-charts/README.md b/packages/plugin-charts/README.md index 9d1cb1f1c1..d0e2535ee2 100644 --- a/packages/plugin-charts/README.md +++ b/packages/plugin-charts/README.md @@ -20,11 +20,14 @@ pnpm add @object-ui/plugin-charts ### Automatic Registration (Side-Effect Import) ```typescript -// In your app entry point (e.g., App.tsx or main.tsx) +// In your app entry point (e.g., App.tsx or main.tsx). This side-effect import +// is the one that registers the components; the type import below is erased at +// build time and registers nothing. import '@object-ui/plugin-charts'; +import type { BarChartSchema } from '@object-ui/plugin-charts'; -// Now you can use chart-bar type in your schemas -const schema = { +// Now you can use the bar-chart type in your schemas +const schema: BarChartSchema = { type: 'bar-chart', data: [ { name: 'Jan', value: 400 }, @@ -43,9 +46,11 @@ const schema = { import { chartComponents } from '@object-ui/plugin-charts'; import { ComponentRegistry } from '@object-ui/core'; -// Manually register if needed +// Manually register if needed. The third argument is not optional in practice: +// `register()` without a namespace is the deprecated form and warns at runtime. +// `plugin-charts` is the namespace this package registers under itself. Object.entries(chartComponents).forEach(([type, component]) => { - ComponentRegistry.register(type, component); + ComponentRegistry.register(type, component, { namespace: 'plugin-charts' }); }); ``` @@ -70,17 +75,27 @@ const schema: BarChartSchema = { ## Schema API -```typescript -{ - type: 'bar-chart', - data?: Array>, // Chart data - dataKey?: string, // Y-axis data key (default: 'value') - xAxisKey?: string, // X-axis label key (default: 'name') - height?: number, // Chart height in pixels (default: 400) - color?: string, // Bar color (default: '#8884d8') - className?: string // Tailwind classes -} -``` +`BarChartSchema` is the published contract — import it (see **TypeScript Support** +above) rather than re-declaring this shape in your own code. It is re-exported +from `@object-ui/types`, so the type you annotate with and the schema that +validates your document are the same declaration. + +| Member | Type | Required | Default | Notes | +| --- | --- | --- | --- | --- | +| `type` | `'bar-chart'` | yes | — | The registry keyword this schema renders under. | +| `data` | `Array>` | no | `[]` | Rows to plot — one bar per row. | +| `dataKey` | `string` | no | `'value'` | Row key holding the bar's value (the y axis). | +| `xAxisKey` | `string` | no | `'name'` | Row key holding the bar's category label (the x axis). | +| `height` | `number` | no | `400` | Chart height in pixels — a number, not a CSS length. | +| `color` | `string` | no | `hsl(var(--primary))` | Bar fill colour, forwarded to Recharts verbatim. | +| `className` | `string` | no | `''` | Tailwind classes. Inherited from `BaseSchema`. | + +Every default above is the renderer's own — the parameter defaults of +`ChartBarRenderer`'s implementation in `src/ChartImpl.tsx`, which is what an +omitted member actually resolves to at render time. Note `color`: the type's +JSDoc and the registration's `defaultProps` both still record `'#8884d8'`, but +neither is read on the render path, so an omitted `color` renders as the theme +token above. ## Lazy Loading Architecture @@ -93,7 +108,7 @@ When bundled, Vite automatically creates separate chunks: - `index.js` (~200 bytes) - The entry point - `ChartImpl-xxx.js` (~541 KB minified, ~136 KB gzipped) - The lazy-loaded implementation -The Recharts library is only downloaded when a `chart-bar` component is actually rendered, not on initial page load. +The Recharts library is only downloaded when a `bar-chart` component is actually rendered, not on initial page load. ## Build Output Example diff --git a/scripts/check-doc-snippet-types.mjs b/scripts/check-doc-snippet-types.mjs index 2a761c7dbd..9e23990d8b 100644 --- a/scripts/check-doc-snippet-types.mjs +++ b/scripts/check-doc-snippet-types.mjs @@ -777,8 +777,6 @@ const UNGATED_DOCS = { 'what is left is fragment shape, and no gate reads this page\'s import names.', 'packages/fields/README.md': '2 undefined-name diagnostic(s) — blocks continue an earlier block, or use ambient names the page never defines; 1 unresolved-module diagnostic(s)', - 'packages/plugin-charts/README.md': - '6 parse diagnostic(s) — blocks fenced `ts` that are bare object literals or elided bodies', 'packages/plugin-editor/README.md': '6 parse diagnostic(s) — blocks fenced `ts` that are bare object literals or elided bodies', 'packages/plugin-map/README.md':