From 80210b0d41ef23d6105d72bd4e126e52307f8c4a Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 6 Sep 2026 22:15:05 +0000 Subject: [PATCH] docs(plugin-ai): compile the README's snippets against the shipped surface Burns down the `packages/plugin-ai/README.md` entry in this gate's `UNGATED_DOCS` ledger (objectui#5174, batch 27). The entry is deleted rather than rewritten because the page now reads zero. The page taught an API the components do not have. All three exported components take a single `schema` prop plus callbacks (`AIFormAssistProps`, `AIRecommendationsProps`, `NLQueryInputProps`), while every example passed flat props -- `formId=`, `objectName=`, `fields=`, `maxResults=`, `layout=`. The README was wrong against components that are right, so the README is what moves: one typed binding per example, annotated with the schema type `@object-ui/types` exports, passed as `schema={...}`, with `declare const` stand-ins for the two ambient names the page never defined. Three of the four `tsx` fences were bare JSX with no import line, so the undefined component name short-circuited the prop check on the same element: the ledger's `TS2322x3` was the visible half of six. The three latent ones surface only once the names resolve, and this diff pays down all six. No `packages/plugin-ai/src/**` or `packages/types/src/**` edit, no widened type, no fragment marker, no loosened gate. The gate file's strictness region is byte-identical. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01FhBNJcLRZLe8M87VcUgpKr --- packages/plugin-ai/README.md | 151 +++++++++++++++++++--------- scripts/check-doc-snippet-types.mjs | 2 - 2 files changed, 103 insertions(+), 50 deletions(-) diff --git a/packages/plugin-ai/README.md b/packages/plugin-ai/README.md index 41f80744a5..680ca1be68 100644 --- a/packages/plugin-ai/README.md +++ b/packages/plugin-ai/README.md @@ -22,41 +22,58 @@ npm install @object-ui/plugin-ai ## Quick Start +Every component in this package takes exactly one schema object plus optional +callbacks — `schema` carries the configuration, the callbacks carry the +behaviour. The schema types ship from `@object-ui/types`. + ```tsx import { AIFormAssist, AIRecommendations, NLQueryInput } from '@object-ui/plugin-ai'; +import type { + AIFormAssistSchema, + AIRecommendationItem, + AIRecommendationsSchema, + NLQuerySchema, +} from '@object-ui/types'; + +declare const recommendationsData: AIRecommendationItem[]; + +const contactAssist: AIFormAssistSchema = { + type: 'ai-form-assist', + formId: 'new-contact', + objectName: 'Contact', + fields: ['name', 'email', 'company'], + showConfidence: true, +}; function SmartForm() { return (
- +
); } +const productPicks: AIRecommendationsSchema = { + type: 'ai-recommendations', + objectName: 'Product', + maxResults: 5, + layout: 'grid', + recommendations: recommendationsData, +}; + function RecommendationsPanel() { - return ( - - ); + return ; } +const orderSearch: NLQuerySchema = { + type: 'nl-query', + objectName: 'Order', + placeholder: 'Ask a question about your orders...', + suggestions: ['Show orders from last week', 'Top customers by revenue'], +}; + function SearchBar() { - return ( - - ); + return ; } ``` @@ -64,50 +81,88 @@ function SearchBar() { ### AIFormAssist -AI-powered form field suggestions and auto-fill: +AI-powered form field suggestions and auto-fill. Props: `schema`, plus the +optional `onApply` and `onRefresh` callbacks. ```tsx - +import { AIFormAssist } from '@object-ui/plugin-ai'; +import type { AIFormAssistSchema } from '@object-ui/types'; + +const leadAssist: AIFormAssistSchema = { + type: 'ai-form-assist', + formId: 'new-lead', + objectName: 'Lead', + fields: ['name', 'email', 'phone'], + autoFill: false, + showConfidence: true, + showReasoning: false, +}; + +const assistPanel = ( + console.log(suggestion.fieldName, suggestion.value)} + /> +); ``` ### AIRecommendations -Display AI-generated recommendations: +Display AI-generated recommendations. Props: `schema`, plus the optional +`onSelect` and `onDismiss` callbacks. ```tsx - +import { AIRecommendations } from '@object-ui/plugin-ai'; +import type { AIRecommendationItem, AIRecommendationsSchema } from '@object-ui/types'; + +declare const data: AIRecommendationItem[]; + +const productPicks: AIRecommendationsSchema = { + type: 'ai-recommendations', + objectName: 'Product', + recommendations: data, + maxResults: 10, + layout: 'list', // 'list' | 'grid' | 'carousel' + showScores: false, + emptyMessage: 'No recommendations available', +}; + +const panel = ( + console.log(item.id)} /> +); ``` ### NLQueryInput -Natural language query input for data exploration: +Natural language query input for data exploration. Props: `schema`, plus the +optional `onSubmit` callback. ```tsx - +import { NLQueryInput } from '@object-ui/plugin-ai'; +import type { NLQuerySchema } from '@object-ui/types'; + +const orderSearch: NLQuerySchema = { + type: 'nl-query', + objectName: 'Order', + placeholder: 'Ask anything...', + suggestions: ['Recent orders', 'Revenue by month'], + showHistory: false, +}; + +const searchBar = console.log(query)} />; ``` -### Schema-Driven Usage +## Schema-Driven Usage + +Components auto-register with `ComponentRegistry` on import. The registry key is +the schema's `type`, and it is **not** always the component name — `NLQueryInput` +registers as `nl-query`: -Components auto-register with `ComponentRegistry`: +| Component | Registry `type` | Schema type | +|---|---|---| +| `AIFormAssist` | `ai-form-assist` | `AIFormAssistSchema` | +| `AIRecommendations` | `ai-recommendations` | `AIRecommendationsSchema` | +| `NLQueryInput` | `nl-query` | `NLQuerySchema` | ```json { diff --git a/scripts/check-doc-snippet-types.mjs b/scripts/check-doc-snippet-types.mjs index 56aca37a18..7216a2eea8 100644 --- a/scripts/check-doc-snippet-types.mjs +++ b/scripts/check-doc-snippet-types.mjs @@ -779,8 +779,6 @@ const UNGATED_DOCS = { '1 parse diagnostic(s) — blocks fenced `ts` that are bare object literals or elided bodies; 15 undefined-name diagnostic(s) — blocks continue an earlier block, or use ambient names the page never defines; plus TS2741x1 — candidate real defects, un-triaged', '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-ai/README.md': - '5 undefined-name diagnostic(s) — blocks continue an earlier block, or use ambient names the page never defines; plus TS2322x3 — candidate real defects, un-triaged', 'packages/plugin-charts/README.md': '6 parse diagnostic(s) — blocks fenced `ts` that are bare object literals or elided bodies', 'packages/plugin-chatbot/README.md':