autoui-react 0.0.3-alpha

package/README.md

@@ -0,0 +1,244 @@
+# autoui-react
+
+A React + TypeScript runtime that **generates goal-oriented UIs in real-time** using an LLM + your data schema.
+
+> Import one component, declare your schema, give a goal, get a working multi-step UI with implicit shimmer fallbacks.
+
+## Inspiration
+
+This library was inspired by the paper ["Generative and Malleable User Interfaces with Generative and Evolving Task-Driven Data Model"](https://dl.acm.org/doi/10.1145/3706598.3713285) (CHI 2025), which proposes a model-driven approach to UI generation. The paper introduces the concept of using LLMs to interpret users' goals and generate data models that serve as the foundation for UI generation - a concept this library puts into practice.
+
+As the paper states, "We adopt the canonical perspective that user interfaces are graphical representations of underlying data models that describe the intended tasks" and proposes "leveraging Large Language Models (LLMs) to interpret users' prompts and generate a task-driven data model—a structured representation of the essential entities, relationships, and data properties relevant to the intended task."
+
+This library implements this approach, using LLMs to interpret a goal and schema to generate a UI specification that can be rendered with React components.
+
+## Feature Highlights
+
+- **Declarative input only** – supply schema + goal; runtime handles the rest
+- **Incremental AI planning** – UI evolves one interaction at a time
+- **Partial UI updates** – only refresh the parts of the UI that need updating
+- **Zero-config fallbacks** – shimmer placeholders generated automatically
+- **Adapter pattern** – map abstract nodes → any React component library (starting with shadcn)
+- **Type-safety end-to-end** – all AI messages validated by Zod
+- **Streaming UX** – uses @vercel/ai to stream planner output and render progressively
+- **System events** – hook into the AI planning lifecycle to observe or extend behavior
+- **Schema adapters** – connect to multiple database types with Drizzle support out of the box
+
+## Installation
+
+```bash
+npm install autoui-react
+```
+
+## Quick Start
+
+```jsx
+import { AutoUI } from 'autoui-react';
+import { emailsTable, usersTable } from './schema';
+
+function App() {
+  return (
+    <AutoUI 
+      schema={{ emails: emailsTable, users: usersTable }}
+      goal="Create an email inbox with list and detail views"
+    />
+  );
+}
+```
+
+That's it! AutoUI will:
+1. Generate a UI based on your schema and goal
+2. Show shimmer placeholders while loading
+3. Handle data binding and events automatically
+
+## API Reference
+
+### `<AutoUI>` Component
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `schema` | `Record<string, unknown>` \| `AdapterConfig` | Yes | Your data schema or schema adapter config |
+| `goal` | `string` | Yes | What you want the UI to do |
+| `componentAdapter` | `'shadcn'` | No | UI component library to use (default: `'shadcn'`) |
+| `userContext` | `Record<string, unknown>` | No | User information (id, role, etc.) |
+| `onEvent` | `(evt: UIEvent) => void` | No | Callback for UI events |
+| `eventHooks` | `{ [eventType]: EventHook[] }` | No | UI event hooks for interception |
+| `systemEventHooks` | `{ [SystemEventType]: SystemEventHook[] }` | No | Hooks into internal system events |
+| `enablePartialUpdates` | `boolean` | No | Only update parts of the UI that change (default: `true`) |
+| `updatePatterns` | `{ enable* }` | No | Configure which partial update patterns to use |
+| `debugMode` | `boolean` | No | Enable console logging of system events |
+| `mockMode` | `boolean` | No | Use mock data for development (default: `true` in dev) |
+| `planningConfig` | `{ prefetchDepth?, temperature?, streaming? }` | No | Configure the AI planning process |
+
+### Partial UI Updates
+
+AutoUI can selectively update only the portions of the UI that need to change, rather than regenerating the entire interface on each interaction. This results in:
+
+- **Better performance**: Only updating what changes is more efficient
+- **Improved UX**: Maintains UI state between interactions
+- **Reduced LLM usage**: Smaller, more focused prompts
+
+To use partial updates:
+
+```jsx
+<AutoUI 
+  schema={mySchema}
+  goal="Create a project dashboard with list and detail views"
+  enablePartialUpdates={true}
+  updatePatterns={{
+    enableDetailViews: true,  // Show/hide details in a side panel
+    enableDropdowns: true,    // Add dropdown menus to elements
+    enableExpandCollapse: true, // Expand/collapse sections
+    enableFormNavigation: true, // Navigate multi-step forms
+  }}
+/>
+```
+
+The AI will now intelligently determine which parts of the UI to update based on user interactions. For example, clicking on an item in a list will only update the detail view rather than regenerating the entire page.
+
+### Schema Configuration
+
+AutoUI supports different ways to provide your data schema:
+
+#### 1. Direct Schema Object
+
+```jsx
+<AutoUI 
+  schema={{
+    users: {
+      tableName: 'users',
+      columns: {
+        id: { type: 'serial', primaryKey: true },
+        name: { type: 'text', notNull: true },
+        email: { type: 'text', notNull: true },
+      },
+      sampleData: [
+        { id: 1, name: 'John', email: 'john@example.com' }
+      ]
+    }
+  }}
+  goal="Create a user management interface"
+/>
+```
+
+#### 2. Using Drizzle Adapter
+
+```jsx
+import { AutoUI } from 'autoui-react';
+import { db } from './db';  // Your Drizzle instance
+import { users, posts } from './schema';  // Drizzle schema
+
+function MyApp() {
+  return (
+    <AutoUI 
+      schema={{
+        type: 'drizzle',
+        options: {
+          schema: { users, posts },
+          client: { 
+            client: db,
+            // Optional custom query function
+            queryFn: async (tableName, query) => {
+              // Custom query logic here
+              return [];
+            }
+          }
+        }
+      }}
+      goal="Create a user management dashboard"
+    />
+  );
+}
+```
+
+#### 3. Using Mock Data
+
+```jsx
+<AutoUI 
+  schema={{
+    type: 'drizzle',
+    options: {
+      schema: { users, posts },
+      useMockData: true,
+      mockData: {
+        users: [
+          { id: 1, name: 'John', email: 'john@example.com' },
+          { id: 2, name: 'Jane', email: 'jane@example.com' }
+        ]
+      }
+    }
+  }}
+  goal="Create a user management dashboard"
+/>
+```
+
+### System Events
+
+AutoUI provides hooks into its internal planning and rendering process through system events. You can subscribe to these events to monitor or extend the functionality.
+
+```jsx
+import { AutoUI, SystemEventType } from 'autoui-react';
+
+function MyApp() {
+  return (
+    <AutoUI 
+      schema={mySchema}
+      goal="Create a user management dashboard"
+      systemEventHooks={{
+        // Log when planning starts
+        [SystemEventType.PLAN_START]: [(event) => {
+          console.log('Planning started with input:', event.plannerInput);
+        }],
+        
+        // Measure performance of data fetching
+        [SystemEventType.DATA_FETCH_COMPLETE]: [(event) => {
+          console.log(`Fetched ${event.results.length} rows from ${event.tableName} in ${event.executionTimeMs}ms`);
+        }]
+      }}
+    />
+  );
+}
+```
+
+#### Available System Events
+
+| Event Type | Description | Data Properties |
+|------------|-------------|-----------------|
+| `PLAN_START` | Planning process started | `plannerInput` |
+| `PLAN_PROMPT_CREATED` | Prompt for LLM generated | `prompt` |
+| `PLAN_RESPONSE_CHUNK` | Received chunk from LLM | `chunk`, `isComplete` |
+| `PLAN_COMPLETE` | Planning process completed | `layout`, `executionTimeMs` |
+| `PLAN_ERROR` | Error during planning | `error` |
+| `BINDING_RESOLUTION_START` | Started resolving data bindings | `layout` |
+| `BINDING_RESOLUTION_COMPLETE` | Completed binding resolution | `originalLayout`, `resolvedLayout` |
+| `DATA_FETCH_START` | Started fetching data | `tableName`, `query` |
+| `DATA_FETCH_COMPLETE` | Completed data fetch | `tableName`, `results`, `executionTimeMs` |
+| `RENDER_START` | Started rendering | `layout` |
+| `RENDER_COMPLETE` | Completed rendering | `layout`, `renderTimeMs` |
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run development build with watch mode
+npm run dev
+
+# Run tests
+npm test
+
+# Build for production
+npm run build
+
+# Run the example app
+npm run example
+```
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.

package/dist/index.css

@@ -0,0 +1,56 @@
+/* src/styles/autoui.css */
+.autoui-root {
+  display: flex;
+  flex-direction: column;
+  height: 100%;
+  width: 100%;
+}
+.autoui-loading {
+  width: 100%;
+  height: 100%;
+}
+.autoui-shimmer-container {
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+  padding: 1rem;
+}
+.autoui-shimmer-header {
+  height: 2.5rem;
+  background-color: #e5e7eb;
+  border-radius: 0.25rem;
+  animation: pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite;
+}
+.autoui-shimmer-content {
+  height: 16rem;
+  background-color: #e5e7eb;
+  border-radius: 0.25rem;
+  animation: pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite;
+}
+@keyframes pulse {
+  0%, 100% {
+    opacity: 1;
+  }
+  50% {
+    opacity: 0.5;
+  }
+}
+.autoui-content {
+  flex: 1;
+  width: 100%;
+}
+.autoui-error {
+  padding: 1rem;
+  border: 1px solid #fca5a5;
+  background-color: #fee2e2;
+  color: #b91c1c;
+  border-radius: 0.25rem;
+  margin-top: 1rem;
+}
+.autoui-error-title {
+  font-weight: 600;
+}
+.autoui-error-message {
+  font-size: 0.875rem;
+}
+/*# sourceMappingURL=index.css.map */

package/dist/index.css.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/styles/autoui.css"],"sourcesContent":["/* AutoUI Component Styles */\n\n.autoui-root {\n  display: flex;\n  flex-direction: column;\n  height: 100%;\n  width: 100%;\n}\n\n/* Loading states */\n.autoui-loading {\n  width: 100%;\n  height: 100%;\n}\n\n.autoui-shimmer-container {\n  display: flex;\n  flex-direction: column;\n  gap: 1rem;\n  padding: 1rem;\n}\n\n.autoui-shimmer-header {\n  height: 2.5rem;\n  background-color: #e5e7eb;\n  border-radius: 0.25rem;\n  animation: pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite;\n}\n\n.autoui-shimmer-content {\n  height: 16rem;\n  background-color: #e5e7eb;\n  border-radius: 0.25rem;\n  animation: pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite;\n}\n\n@keyframes pulse {\n  0%, 100% {\n    opacity: 1;\n  }\n  50% {\n    opacity: 0.5;\n  }\n}\n\n/* Content */\n.autoui-content {\n  flex: 1;\n  width: 100%;\n}\n\n/* Error states */\n.autoui-error {\n  padding: 1rem;\n  border: 1px solid #fca5a5;\n  background-color: #fee2e2;\n  color: #b91c1c;\n  border-radius: 0.25rem;\n  margin-top: 1rem;\n}\n\n.autoui-error-title {\n  font-weight: 600;\n}\n\n.autoui-error-message {\n  font-size: 0.875rem;\n} "],"mappings":";AAEA,CAAC;AACC,WAAS;AACT,kBAAgB;AAChB,UAAQ;AACR,SAAO;AACT;AAGA,CAAC;AACC,SAAO;AACP,UAAQ;AACV;AAEA,CAAC;AACC,WAAS;AACT,kBAAgB;AAChB,OAAK;AACL,WAAS;AACX;AAEA,CAAC;AACC,UAAQ;AACR,oBAAkB;AAClB,iBAAe;AACf,aAAW,MAAM,GAAG,aAAa,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,GAAG;AACnD;AAEA,CAAC;AACC,UAAQ;AACR,oBAAkB;AAClB,iBAAe;AACf,aAAW,MAAM,GAAG,aAAa,GAAG,EAAE,CAAC,EAAE,GAAG,EAAE,GAAG;AACnD;AAEA,WAVa;AAWX;AACE,aAAS;AACX;AACA;AACE,aAAS;AACX;AACF;AAGA,CAAC;AACC,QAAM;AACN,SAAO;AACT;AAGA,CAAC;AACC,WAAS;AACT,UAAQ,IAAI,MAAM;AAClB,oBAAkB;AAClB,SAAO;AACP,iBAAe;AACf,cAAY;AACd;AAEA,CAAC;AACC,eAAa;AACf;AAEA,CAAC;AACC,aAAW;AACb;","names":[]}