{"_id":"@alvandal/ai-ui","name":"@alvandal/ai-ui","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@alvandal/ai-ui","version":"0.1.0","description":"AI UI - Typed UI primitives for AI-to-UI communication","type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"import":"./dist/index.js","types":"./dist/index.d.ts"},"./react":{"import":"./dist/react/index.js","types":"./dist/react/index.d.ts"}},"scripts":{"build":"tsc","prepublishOnly":"npm run build","dev":"tsc --watch","dev:example":"vite","test":"vitest","test:coverage":"vitest --coverage","lint":"eslint src --ext .ts,.tsx","typecheck":"tsc --noEmit","export-schemas":"tsx scripts/export-json-schemas.ts","review:diff":"tsx scripts/review-diff.ts"},"keywords":["ai","ui","primitives","forms","typed","zod"],"repository":{"type":"git","url":"git+https://github.com/aandresalvarez/ai-ui.git"},"homepage":"https://github.com/aandresalvarez/ai-ui#readme","bugs":{"url":"https://github.com/aandresalvarez/ai-ui/issues"},"publishConfig":{"access":"public"},"license":"MIT","dependencies":{"zod":"^3.22.4","zod-to-json-schema":"^3.22.4"},"devDependencies":{"@testing-library/jest-dom":"^6.9.1","@testing-library/react":"^14.3.1","@types/node":"^20.11.0","@types/react":"^18.2.48","@vitejs/plugin-react":"^5.1.3","eslint":"^8.56.0","jsdom":"^28.0.0","react":"^18.2.0","react-dom":"^18.3.1","tsx":"^4.7.0","typescript":"^5.3.3","vite":"^7.3.1","vitest":"^1.6.1"},"peerDependencies":{"react":">=18.0.0"},"peerDependenciesMeta":{"react":{"optional":true}},"engines":{"node":">=18.0.0"},"gitHead":"6077d3725f0cc17b3296c811113c2bd7779b30dd","_id":"@alvandal/ai-ui@0.1.0","_nodeVersion":"24.3.0","_npmVersion":"11.7.0","dist":{"integrity":"sha512-cDFBKj1c1KIjMJbr1OZh81xDA5OI7/9He233co1BVihGklkUEieumh2Z2V12/u0XCwAjXWu/I+VIHEKgVVpWZQ==","shasum":"74d15a9599045f5b027b623f34cba849c7a5c2d9","tarball":"https://registry.npmjs.org/@alvandal/ai-ui/-/ai-ui-0.1.0.tgz","fileCount":258,"unpackedSize":927662,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIFYuTaGVI99mzWWIwVSh6BjhrzsAUnffuIXbht8r2NlIAiEA7LK8P61OppfLrxqDTG2QgJbu/kcoyEEzlLbgmQfv9Fs="}]},"_npmUser":{"name":"alvandal","email":"aandresalvarez@gmail.com"},"directories":{},"maintainers":[{"name":"alvandal","email":"aandresalvarez@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/ai-ui_0.1.0_1771304032938_0.8005994386084321"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-17T04:53:52.828Z","0.1.0":"2026-02-17T04:53:53.139Z","modified":"2026-02-17T04:53:53.365Z"},"maintainers":[{"name":"alvandal","email":"aandresalvarez@gmail.com"}],"description":"AI UI - Typed UI primitives for AI-to-UI communication","homepage":"https://github.com/aandresalvarez/ai-ui#readme","keywords":["ai","ui","primitives","forms","typed","zod"],"repository":{"type":"git","url":"git+https://github.com/aandresalvarez/ai-ui.git"},"bugs":{"url":"https://github.com/aandresalvarez/ai-ui/issues"},"license":"MIT","readme":"# AI UI (AI Interaction Primitives)\n\n> **\"AI Speaks in Components\"**\n\nA type-safe, Zod-validated library for structured UI communication between AI models and React applications. Instead of streaming raw markdown, your AI returns structured JSON contracts that render as interactive, validated UI primitives.\n\n## 🚀 Key Features\n\n- **Type Safety**: 100% TypeScript with strict Zod schemas. No `any`.\n- **Validation Engine**: Pure functions to validate AI responses against the Primitive Registry.\n- **Component Registry**: Central catalog mapping primitive types (`numeric_scale`, `body_map`, etc.) to Zod schemas and metadata.\n- **React Renderer**: Optimally rendered components with a single `<PrimitiveRenderer />` entry point.\n- **State Management**: Immutable conversation state tracking with `useAIUIConversation` hook.\n- **Zero Hallucination**: If the AI sends an invalid primitive, the validation layer rejects it before rendering.\n\n## 📦 Installation\n\nSince the package is not yet published to the npm registry, you can install it directly from GitHub:\n\n```bash\nnpm install github:aandresalvarez/ai-ui\n# Or using SSH\nnpm install git@github:aandresalvarez/ai-ui.git\n\n# Peer dependencies\nnpm install react react-dom zod\n```\n\n## 🛠️ Usage\n\n### 1. The Contract\n\nThe AI should be instructed to return JSON matching the `InteractionContractSchema`.\n\n```json\n{\n  \"type\": \"ui_element\",\n  \"element\": {\n    \"id\": \"pain-level\",\n    \"type\": \"numeric_scale\",\n    \"label\": \"How would you rate your pain?\",\n    \"required\": true,\n    \"version\": \"1.0\",\n    \"constraints\": { \"min\": 0, \"max\": 10, \"step\": 1 }\n  }\n}\n```\n\n### 2. React Implementation\n\nUse the provided hook and renderer to drive the UI.\n\n```tsx\nimport { useAIUIConversation, PrimitiveRenderer } from \"ai-ui\";\n// Import default styles (or provide your own)\nimport \"ai-ui/dist/react/styles/ai-ui.css\";\n\nfunction App() {\n  // Initialize conversation state\n  const { currentPrimitive, submitAnswer, history } =\n    useAIUIConversation(\"session-123\");\n\n  // Handle AI response (mocked or real)\n  // In a real app, you'd fetch this from your AI endpoint\n  // and pass it to recordStep(conversationState, response.element)\n\n  if (!currentPrimitive) return <div>Loading AI response...</div>;\n\n  return (\n    <div className=\"survey-container\">\n      <h1>AI Assessment</h1>\n\n      <PrimitiveRenderer\n        primitive={currentPrimitive}\n        onAnswer={(value) => submitAnswer(value)}\n        disabled={false}\n      />\n\n      <div className=\"history\">Previous steps: {history.length}</div>\n    </div>\n  );\n}\n```\n\n## 🧩 Supported Primitives\n\nThe library currently supports 13 core primitives:\n\n| Category      | Primitives      | Description                                     |\n| ------------- | --------------- | ----------------------------------------------- |\n| **Scale**     | `numeric_scale` | Bounded number selection (e.g., pain 0-10)      |\n|               | `likert_scale`  | Agreement scale (Strongly Disagree -> Agree)    |\n|               | `rating`        | Star/Emoji ratings                              |\n|               | `slider`        | Continuous value selection                      |\n| **Selection** | `single_choice` | Radio button / dropdown selection               |\n|               | `multi_choice`  | Checkbox / multi-select                         |\n|               | `body_map`      | **NEW!** Visual body part selector (Front/Back) |\n| **Input**     | `text_input`    | Free text with validation (email, phone, etc.)  |\n|               | `date_picker`   | Date/Time selection                             |\n|               | `toggle`        | Boolean switch                                  |\n|               | `file_upload`   | File attachment with type constraints           |\n| **Advanced**  | `matrix`        | Grid of questions with shared options           |\n|               | `ranking`       | Drag-and-drop reordering                        |\n\n## 🏗️ Architecture\n\nThe library is architected with strictly separated concerns:\n\n1.  **Primitives Layer** (`src/primitives`): Zod schema definitions. Source of truth.\n2.  **Validation Layer** (`src/validation`): Pure functions for schema validation.\n3.  **Registry Layer** (`src/registry`): Maps types to schemas and metadata.\n4.  **Contract Layer** (`src/contract`): Defines the envelope for AI responses.\n5.  **State Layer** (`src/state`): Immutable state management helpers.\n6.  **React Layer** (`src/react`):\n    - `components/`: Visual implementation of primitives.\n    - `hooks/`: Logic for conversation flow.\n    - `styles/`: CSS variables and base styles.\n\n## 🧪 Development\n\n### Build\n\n```bash\nnpm run build\n```\n\n### Test\n\nIncludes unit tests for validation and integration tests for full flows.\n\n```bash\nnpm test\n```\n\n### Local Verification\n\nRun the adaptive survey example locally:\n\n```bash\nnpx vite\n```\n\n### Review Diff Helper\n\nWhen a review diff is empty or ambiguous, use the helper to pick a target and get fallback hints:\n\n```bash\nnpm run review:diff\n```\n\nUseful flags:\n\n```bash\nnpm run review:diff -- --target main...HEAD\nnpm run review:diff -- --non-interactive --print-only\n```\n\n## 📄 License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-d06499923f1c9d2dca5e1f4976417cd3"}