@object-ui/plugin-ai 17.6.0 → 17.7.0

package/README.md

@@ -5,7 +5,7 @@ AI-powered components for Object UI — form assistance, recommendations, and na
 ## Features
 
 - 🤖 **AI Form Assist** - Intelligent field suggestions and auto-fill for forms
-- 💡 **AI Recommendations** - Display AI-generated recommendations in list, grid, or carousel layouts
+- 💡 **AI Recommendations** - Display AI-generated recommendations in list or grid layouts
 - 🗣️ **Natural Language Query** - Let users query data using natural language
 - 📦 **Auto-registered** - Components register with `ComponentRegistry` on import
 - 🎯 **Type-Safe** - Full TypeScript support
@@ -22,41 +22,55 @@ 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',
+  suggestions: [
+    { fieldName: 'company', value: 'ObjectStack Inc.', confidence: 0.92 },
+  ],
+  showConfidence: true,
+};
 
 function SmartForm() {
   return (
     <div>
-      <AIFormAssist
-        formId="new-contact"
-        objectName="Contact"
-        fields={['name', 'email', 'company']}
-        showConfidence
-      />
+      <AIFormAssist schema={contactAssist} />
     </div>
   );
 }
 
+const productPicks: AIRecommendationsSchema = {
+  type: 'ai-recommendations',
+  layout: 'grid',
+  recommendations: recommendationsData,
+};
+
 function RecommendationsPanel() {
-  return (
-    <AIRecommendations
-      objectName="Product"
-      maxResults={5}
-      layout="grid"
-      recommendations={recommendationsData}
-    />
-  );
+  return <AIRecommendations schema={productPicks} />;
 }
 
+const orderSearch: NLQuerySchema = {
+  type: 'nl-query',
+  placeholder: 'Ask a question about your orders...',
+  suggestions: ['Show orders from last week', 'Top customers by revenue'],
+};
+
 function SearchBar() {
-  return (
-    <NLQueryInput
-      objectName="Order"
-      placeholder="Ask a question about your orders..."
-      suggestions={['Show orders from last week', 'Top customers by revenue']}
-    />
-  );
+  return <NLQueryInput schema={orderSearch} />;
 }
 ```
 
@@ -64,61 +78,146 @@ 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
-<AIFormAssist
-  formId="new-lead"
-  objectName="Lead"
-  fields={['name', 'email', 'phone']}
-  autoFill={false}
-  showConfidence
-  showReasoning={false}
-/>
+import { AIFormAssist } from '@object-ui/plugin-ai';
+import type { AIFormAssistSchema } from '@object-ui/types';
+
+const leadAssist: AIFormAssistSchema = {
+  type: 'ai-form-assist',
+  suggestions: [
+    { fieldName: 'phone', value: '+86 21 0000 0000', confidence: 0.71, reasoning: 'Matched the company record' },
+  ],
+  showConfidence: true,
+  showReasoning: false,
+};
+
+const assistPanel = (
+  <AIFormAssist
+    schema={leadAssist}
+    onApply={(suggestion) => 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
-<AIRecommendations
-  objectName="Product"
-  recommendations={data}
-  maxResults={10}
-  layout="list"       // 'list' | 'grid' | 'carousel'
-  showScores={false}
-  emptyMessage="No recommendations available"
-/>
+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',
+  recommendations: data.slice(0, 10), // every item handed over is rendered
+  layout: 'list', // 'list' | 'grid'
+  showScores: false,
+  emptyMessage: 'No recommendations available',
+};
+
+const panel = (
+  <AIRecommendations schema={productPicks} onSelect={(item) => 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
-<NLQueryInput
-  objectName="Order"
-  placeholder="Ask anything..."
-  suggestions={['Recent orders', 'Revenue by month']}
-  showHistory={false}
-/>
+import { NLQueryInput } from '@object-ui/plugin-ai';
+import type { NLQuerySchema } from '@object-ui/types';
+
+const orderSearch: NLQuerySchema = {
+  type: 'nl-query',
+  placeholder: 'Ask anything...',
+  suggestions: ['Recent orders', 'Revenue by month'],
+  showHistory: false,
+};
+
+const searchBar = <NLQueryInput schema={orderSearch} onSubmit={(query) => console.log(query)} />;
 ```
 
-### Schema-Driven Usage
+## Schema-Driven Usage
 
-Components auto-register with `ComponentRegistry`:
+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`:
+
+| Component | Registry `type` | Schema type |
+|---|---|---|
+| `AIFormAssist` | `ai-form-assist` | `AIFormAssistSchema` |
+| `AIRecommendations` | `ai-recommendations` | `AIRecommendationsSchema` |
+| `NLQueryInput` | `nl-query` | `NLQuerySchema` |
 
 ```json
 {
   "type": "ai-form-assist",
-  "formId": "new-contact",
-  "objectName": "Contact",
-  "fields": ["name", "email"],
-  "showConfidence": true
+  "showConfidence": true,
+  "showReasoning": true
 }
 ```
 
+## Localization
+
+The components read their built-in copy (button labels, headings, the empty
+and loading states, the default `placeholder` and `emptyMessage`) from the
+`ai.*` namespace of `@object-ui/i18n`, so they follow the language of the
+`I18nProvider` they are mounted under. With no provider they render English.
+
+Dates (the `nl-query` history) and percentages (confidence and score badges)
+are formatted in the display locale — `useDisplayLocale()` from
+`@object-ui/i18n`: the tenant's regional locale when one is configured, the UI
+language otherwise — never in the machine's locale (objectui#10232).
+
+## What these components do not do
+
+They are **presentation only**: each one renders the data on its schema and
+reports the user's decisions through its callbacks. None of them fetches, none
+of them queries, and none of them caps a list.
+
+`formId`, `objectName`, `fields`, `autoFill` and `maxResults` were declared,
+offered in the designer and taught here — and read by nothing, at any depth.
+They are retired (objectui#8178, ADR-0049, director decision batch #78,
+2026-09-07) and are refused by the schema types now, so a node that carries one
+is a compile error rather than a silent no-op:
+
+| Key | Was on | Instead |
+|---|---|---|
+| `formId` | `AIFormAssistSchema` | the host owns the form; pass `suggestions` in and act on `onApply` |
+| `objectName` | all three schemas | scope the query in the host that answers it |
+| `fields` | `AIFormAssistSchema` | each suggestion names its own `fieldName` |
+| `autoFill` | `AIFormAssistSchema` | apply the suggestions you want from `onApply` |
+| `maxResults` | `AIRecommendationsSchema` | slice `recommendations` before handing it over — **every item is rendered** |
+
+Four more keys went the same way (objectui#10874), on seven member slots. `config` and `context`
+were read by nothing: none of these components calls a model, so neither
+configured anything. `onApplySuggestion` and `onRejectSuggestion` were typed
+`string` and read by nothing either. All four are now refused by the schema
+types and by the validator alike:
+
+| Key | Was on | Instead |
+|---|---|---|
+| `config` | all three schemas | configure the model in your host's own AI service (ObjectUI has no AI-provider API; these components call no model), and hand its output to the node as `suggestions`, `recommendations` or `result` |
+| `context` | `AIFormAssistSchema`, `AIRecommendationsSchema` | pass it to your host's own AI service when you ask it for suggestions or recommendations |
+| `onApplySuggestion` | `AIFormAssistSchema` | the `onApply` component prop |
+| `onRejectSuggestion` | `AIFormAssistSchema` | delete it — the component has no reject callback |
+
+`onSelect` and `onDismiss` (`AIRecommendationsSchema`) and `onSubmit`
+(`NLQuerySchema`) were typed `string` too, but the components DO call them:
+a string there was called as a function and threw at click. They are now typed
+as the callbacks the components invoke — `(item) => void` and
+`(query) => void` — so pass a function, either as the component prop of the same
+name or on a node you build in TypeScript. The validator still refuses them in
+a JSON document, because JSON has no function value.
+
 ## Links
 
 - 📚 [Documentation](https://www.objectui.org/docs/plugins/plugin-ai)

package/dist/AIFormAssist.d.ts

@@ -9,6 +9,16 @@ export interface AIFormAssistProps {
 }
 /**
  * AIFormAssist - AI-powered form filling assistant
- * Provides intelligent field suggestions based on context and historical data.
+ *
+ * Renders the `suggestions` it is handed and reports the author's decisions
+ * through `onApply`; it generates nothing and fetches nothing. The whole read
+ * surface is the destructure below — `suggestions`, `showConfidence`,
+ * `showReasoning`.
+ *
+ * `autoFill` used to be destructured here with a default and never referenced
+ * again, so nothing was ever filled automatically. It is retired along with
+ * `formId`, `objectName` and `fields` (objectui#8178, ADR-0049, director
+ * decision batch #78) and is a `?: never` tombstone on `AIFormAssistSchema`.
+ * Applying a suggestion is the author's act, through `onApply`.
  */
 export declare const AIFormAssist: React.FC<AIFormAssistProps>;

package/dist/AIRecommendations.d.ts

@@ -9,6 +9,19 @@ export interface AIRecommendationsProps {
 }
 /**
  * AIRecommendations - AI-powered recommendation component
- * Displays intelligent recommendations based on context and user behavior.
+ *
+ * Renders EVERY item in `schema.recommendations`, in both the `list` and the
+ * `grid` layout, and the count badge in the header reports that same length.
+ * There is no cap: the caller decides how many items to hand over, and slicing
+ * — if it is wanted — happens before the array reaches this component.
+ *
+ * That sentence replaces a promise this component never honoured.
+ * `AIRecommendationsSchema.maxResults` was declared as *"Maximum number of
+ * results to display"*, offered in the designer, and read by nothing: a node
+ * carrying `maxResults: 5` against a 50-item list rendered 50 rows with no
+ * diagnostic. The key is retired (objectui#8178, ADR-0049, director decision
+ * batch #78) rather than implemented, because nothing pulled on it; it is a
+ * `?: never` tombstone on the schema now, and the behaviour stated here is
+ * pinned by `AIRecommendations.rendersEveryItem-8178.test.tsx`.
  */
 export declare const AIRecommendations: React.FC<AIRecommendationsProps>;

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { AIFormAssist } from './AIFormAssist';
-import { AIRecommendations } from './AIRecommendations';
-import { NLQueryInput } from './NLQueryInput';
+import { AIFormAssist } from './AIFormAssist.js';
+import { AIRecommendations } from './AIRecommendations.js';
+import { NLQueryInput } from './NLQueryInput.js';
 export { AIFormAssist, AIRecommendations, NLQueryInput };