@usesidekick/react 0.1.0 → 0.1.2

package/README.md

@@ -1,40 +1,55 @@
-# Sidekick React SDK
+# @usesidekick/react
 
-Zero-change integration for extensible React applications. Override modules can customize any component by name without modifying the host application.
+Zero-change runtime for extensible React applications. Override modules can wrap, replace, or enhance any component by name without modifying the host app's source code.
 
-## Quick Start
-
-### 1. Install
+## Installation
 
 ```bash
 npm install @usesidekick/react
 ```
 
-### 2. Wrap Your App
+For the full automated setup (installs deps, configures build, creates API routes):
+
+```bash
+npx @usesidekick/cli init
+```
+
+## Quick Start
+
+### 1. Wrap Your App
 
 ```tsx
 import { SidekickProvider } from '@usesidekick/react';
 
 export default function App() {
   return (
-    <SidekickProvider>
+    <SidekickProvider overridesEndpoint="/api/sidekick/overrides">
       <YourApp />
     </SidekickProvider>
   );
 }
 ```
 
-### 3. (Production) Add Build Plugin
+### 2. Add the Build Plugin
+
+The `babel-plugin-add-react-displayname` plugin preserves component names through minification so overrides can target them in production.
 
-For production builds, add the `babel-plugin-add-react-displayname` plugin to automatically preserve component names through minification.
+```bash
+npm install -D babel-plugin-add-react-displayname
+```
 
-**Next.js** (`next.config.js`):
-```js
-module.exports = {
-  // Using Babel
-  babel: {
-    plugins: ['add-react-displayname']
-  }
+**Next.js** (`.babelrc`):
+```json
+{
+  "presets": [
+    ["next/babel", {
+      "preset-react": {
+        "runtime": "automatic",
+        "importSource": "@usesidekick/react"
+      }
+    }]
+  ],
+  "plugins": ["add-react-displayname"]
 }
 ```
 
@@ -45,41 +60,25 @@ import react from '@vitejs/plugin-react';
 export default {
   plugins: [
     react({
-      babel: {
-        plugins: ['add-react-displayname']
-      }
+      jsxImportSource: '@usesidekick/react',
+      babel: { plugins: ['add-react-displayname'] }
     })
   ]
 }
 ```
 
-**Webpack** (`.babelrc`):
-```json
-{
-  "plugins": ["add-react-displayname"]
-}
-```
-
-That's it! Override modules can now customize any component in your app.
-
-## How Override Modules Work
-
-Override modules use the SDK to wrap or replace components by name:
-
-### Wrapping Components
-
-Add behavior around any component without modifying it:
+### 3. Write an Override
 
 ```tsx
 import { createOverride } from '@usesidekick/react';
 
 export default createOverride({
-  name: 'Custom Task Card Wrapper',
+  name: 'Beta Banner',
   primitives: ['ui.wrap'],
   activate: (sdk) => {
-    sdk.ui.wrap('TaskCard', (Original) => (props) => (
-      <div className="relative">
-        <span className="badge">New!</span>
+    sdk.ui.wrap('TaskBoard', (Original) => (props) => (
+      <div>
+        <div style={{ background: 'purple', color: 'white', padding: 8 }}>Beta</div>
         <Original {...props} />
       </div>
     ));
@@ -87,159 +86,203 @@ export default createOverride({
 });
 ```
 
-### Replacing Components
-
-Completely swap out a component:
-
-```tsx
-import { createOverride } from '@usesidekick/react';
-import { MyCustomModal } from './MyCustomModal';
-
-export default createOverride({
-  name: 'Custom Modal',
-  primitives: ['ui.replace'],
-  activate: (sdk) => {
-    sdk.ui.replace('TaskModal', MyCustomModal);
-  },
-});
-```
-
-### Injecting Styles
-
-Add CSS without touching any files:
-
-```tsx
-sdk.ui.addStyles(`
-  .task-card {
-    border-radius: 12px;
-    box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
-  }
-`);
-```
-
-## Component Name Resolution
-
-The SDK resolves component names in this order:
-
-1. **displayName** - Explicit name, survives minification
-2. **function name** - Works in development
-3. **Inner component** - For memo/forwardRef wrapped components
-
-| Environment | Name Source | Works? |
-|------------|-------------|--------|
-| Development | function name | Always |
-| Production (with build plugin) | auto-added displayName | Always |
-| Production (without plugin) | minified name | Breaks |
-
-For best results, either:
-- Use the babel plugin (recommended, zero per-component changes)
-- Or manually add `displayName` to components you want to target
-
-## API Reference
-
-### SidekickProvider
-
-```tsx
-<SidekickProvider
-  overridesEndpoint="/api/overrides" // Optional: API endpoint for remote overrides
->
-  {children}
-</SidekickProvider>
-```
-
-### SDK Primitives
+## Override Primitives
 
-#### UI Primitives
+### UI
 
 | Method | Description |
 |--------|-------------|
-| `sdk.ui.wrap(name, wrapper)` | Wrap a component by name |
-| `sdk.ui.replace(name, component)` | Replace a component by name |
-| `sdk.ui.inject(extensionPointId, component)` | Inject into an ExtensionPoint |
+| `sdk.ui.wrap(name, wrapper)` | Wrap a component with additional markup/logic |
+| `sdk.ui.replace(name, component)` | Replace a component entirely |
+| `sdk.ui.inject(extensionPointId, component)` | Inject into an `<ExtensionPoint>` slot |
 | `sdk.ui.addStyles(css)` | Inject global CSS |
 | `sdk.ui.addColumn(tableId, config)` | Add a column to a table |
 | `sdk.ui.addMenuItem(menuId, config)` | Add a menu item |
 | `sdk.ui.addTab(tabGroupId, config)` | Add a tab |
 | `sdk.ui.addAction(actionBarId, config)` | Add an action button |
-| `sdk.ui.modifyProps(componentId, modifier)` | Modify component props |
+| `sdk.ui.modifyProps(componentId, modifier)` | Modify a component's props at render time |
 
-#### Data Primitives
+### Data
 
 | Method | Description |
 |--------|-------------|
-| `sdk.data.computed(fieldName, compute)` | Add a computed field |
+| `sdk.data.computed(fieldName, compute)` | Add a computed/derived field |
 | `sdk.data.addFilter(name, filter)` | Add a data filter |
-| `sdk.data.transform(dataKey, transform)` | Transform data |
+| `sdk.data.transform(dataKey, transform)` | Transform data before render |
 | `sdk.data.intercept(pathPattern, handler)` | Intercept API responses |
 | `sdk.data.addSortOption(tableId, config)` | Add a sort option |
 | `sdk.data.addGroupBy(tableId, config)` | Add a group-by option |
 
-#### Behavior Primitives
+### Behavior
 
 | Method | Description |
 |--------|-------------|
-| `sdk.behavior.onEvent(name, handler)` | Handle custom events |
-| `sdk.behavior.addKeyboardShortcut(keys, action)` | Add keyboard shortcuts |
+| `sdk.behavior.onEvent(name, handler)` | Listen for custom events |
+| `sdk.behavior.addKeyboardShortcut(keys, action)` | Register keyboard shortcuts |
 | `sdk.behavior.modifyRoute(pattern, handler)` | Modify routing behavior |
 
-## ExtensionPoints (Optional)
+## React Hooks
 
-For fine-grained injection slots, you can still use ExtensionPoints:
+The SDK provides hooks for host apps that want to read override state:
 
 ```tsx
-import { ExtensionPoint } from '@usesidekick/react';
-
-function MyComponent() {
-  return (
-    <div>
-      <ExtensionPoint id="header-actions" props={{ user }} />
-      {/* ... */}
-    </div>
-  );
-}
+import {
+  useAddedColumns,
+  useColumnRenames,
+  useHiddenColumns,
+  useColumnOrder,
+  useMenuItems,
+  useTabs,
+  useActions,
+  useValidations,
+  usePropsModifier,
+  useComputedField,
+  useFilter,
+  useSortOptions,
+  useGroupByOptions,
+  useKeyboardShortcuts,
+  useEventEmitter,
+} from '@usesidekick/react';
 ```
 
-Override modules can then inject into these points:
+## SidekickPanel
+
+A built-in admin panel for managing overrides at runtime. Supports AI-powered generation, toggling, and deletion.
 
 ```tsx
-sdk.ui.inject('header-actions', ({ user }) => (
-  <button>Hello, {user.name}!</button>
-));
+import { SidekickPanel } from '@usesidekick/react';
+
+<SidekickPanel
+  apiEndpoint="/api/sidekick/generate"
+  toggleEndpoint="/api/sidekick/toggle"
+  deleteEndpoint="/api/sidekick/delete"
+/>
 ```
 
-## Technical Details
+| Prop | Type | Description |
+|------|------|-------------|
+| `apiEndpoint` | `string?` | Endpoint for AI override generation |
+| `toggleEndpoint` | `string?` | Endpoint for enable/disable |
+| `deleteEndpoint` | `string?` | Endpoint for deletion |
+| `onGenerate` | `function?` | Custom generate handler (overrides `apiEndpoint`) |
+| `onToggle` | `function?` | Custom toggle handler (overrides `toggleEndpoint`) |
+| `onDelete` | `function?` | Custom delete handler (overrides `deleteEndpoint`) |
+
+## Server (`@usesidekick/react/server`)
+
+Server-side utilities for building the Sidekick API backend. Handles override CRUD, AI generation, and validation.
 
-### How It Works
+### Setup with Drizzle + Neon
 
-The SDK overrides `React.createElement` to intercept every component render. When a component is rendered, it checks:
+```ts
+// app/api/sidekick/[...action]/route.ts
+import { createSidekickHandler, createDrizzleStorage } from '@usesidekick/react/server';
+import { db } from '@/lib/db';
+import { overrides } from '@/lib/db/schema';
+
+const handler = createSidekickHandler({
+  storage: createDrizzleStorage(db, overrides),
+});
+
+export const GET = handler.GET;
+export const POST = handler.POST;
+```
 
-1. Is there a replacement registered for this component name? If so, use it.
-2. Is there a wrapper registered? If so, wrap the original component.
+This single catch-all route handles four actions (dispatched by the last URL path segment):
+
+| Method | Path | Action |
+|--------|------|--------|
+| GET | `/api/sidekick/overrides` | List all overrides |
+| POST | `/api/sidekick/generate` | AI-generate an override |
+| POST | `/api/sidekick/toggle` | Enable/disable an override |
+| POST | `/api/sidekick/delete` | Delete an override |
+
+### Server Exports
+
+```ts
+import {
+  // Handler factory
+  createSidekickHandler,
+
+  // Storage
+  createDrizzleStorage,   // Drizzle ORM adapter
+  sidekickOverrides,      // pgTable definition (for your schema)
+
+  // AI generation (for custom integrations)
+  buildSystemPrompt,
+  buildUserPrompt,
+  callAI,
+  parseAIResponse,
+  validateCode,
+  formatDesignSystem,
+} from '@usesidekick/react/server';
+```
+
+### Custom Storage Adapter
+
+Implement `SidekickStorage` to use any database:
+
+```ts
+import type { SidekickStorage } from '@usesidekick/react/server';
+
+const myStorage: SidekickStorage = {
+  listOverrides: async () => { /* ... */ },
+  getOverride: async (id) => { /* ... */ },
+  createOverride: async (data) => { /* ... */ },
+  updateOverride: async (id, data) => { /* ... */ },
+  deleteOverride: async (id) => { /* ... */ },
+};
+
+const handler = createSidekickHandler({ storage: myStorage });
+```
+
+## How It Works
+
+The SDK overrides `React.createElement` via a custom JSX runtime to intercept every component render. When a component renders, it checks:
+
+1. Is there a **replacement** registered for this component? Use it.
+2. Is there a **wrapper** registered? Wrap the original.
 3. Otherwise, render normally.
 
-This approach requires **zero changes** to existing components - just wrap your app with `SidekickProvider`.
+This requires **zero changes** to existing components.
+
+### Component Name Resolution
+
+Names are resolved in order: `displayName` > `function.name` > inner component name (for memo/forwardRef).
+
+| Environment | Name Source | Reliable? |
+|-------------|-------------|-----------|
+| Development | function name | Yes |
+| Production + build plugin | auto-added displayName | Yes |
+| Production without plugin | minified name | No |
 
 ### Performance
 
-- One Map lookup per createElement call
-- Negligible overhead (<1% in benchmarks)
-- No impact when no overrides are registered
+- One `Map.get()` per `createElement` call
+- No overhead when no overrides are registered
 
 ### Compatibility
 
-- Functional components
-- Class components
-- React.memo wrapped components
-- React.forwardRef wrapped components
-- Suspense boundaries
-- Portals
-- **Not supported**: Server Components (Next.js RSC) - client components only
+Works with: functional components, class components, `React.memo`, `React.forwardRef`, Suspense, Portals.
+
+**Not supported:** React Server Components (client-side only).
+
+## Package Exports
+
+| Import Path | Description |
+|-------------|-------------|
+| `@usesidekick/react` | Provider, hooks, panel, override API, types |
+| `@usesidekick/react/jsx-runtime` | Custom JSX runtime (configured via `jsxImportSource`) |
+| `@usesidekick/react/jsx-dev-runtime` | Development JSX runtime |
+| `@usesidekick/react/server` | Server handler, storage adapters, AI generation |
 
-### Limitations
+## Peer Dependencies
 
-- Anonymous components (`export default () => ...`) cannot be targeted by name
-- Server Components cannot be intercepted (they don't run on client)
-- React-specific (other frameworks need separate adapters)
+| Package | Version | Required? |
+|---------|---------|-----------|
+| `react` | ^18.2.0 | Yes |
+| `drizzle-orm` | >=0.29.0 | Only if using `createDrizzleStorage` |
+| `next` | >=14.0.0 | Only if using `createSidekickHandler` |
 
 ## License
 

package/dist/server/index.d.mts

@@ -222,6 +222,8 @@ type DrizzleDb = {
 };
 declare function createDrizzleStorage(db: DrizzleDb, overridesTable: typeof sidekickOverrides): SidekickStorage;
 
+declare function createJsonFileStorage(filePath?: string): SidekickStorage;
+
 declare function formatDesignSystem(schema: Record<string, unknown>): string;
 declare function buildSystemPrompt(schema: Record<string, unknown>): string;
 declare function buildUserPrompt(request: string, previousErrors?: string[], existingCode?: string): string;
@@ -232,4 +234,4 @@ declare function validateCode(code: string): {
     errors: string[];
 };
 
-export { type GeneratedOverride, type NewOverrideRecord, type NewSidekickOverride, type OverrideManifest, type OverrideRecord, type SidekickHandlerOptions, type SidekickOverride, type SidekickStorage, buildSystemPrompt, buildUserPrompt, callAI, createDrizzleStorage, createSidekickHandler, formatDesignSystem, parseAIResponse, sidekickOverrides, validateCode };
+export { type GeneratedOverride, type NewOverrideRecord, type NewSidekickOverride, type OverrideManifest, type OverrideRecord, type SidekickHandlerOptions, type SidekickOverride, type SidekickStorage, buildSystemPrompt, buildUserPrompt, callAI, createDrizzleStorage, createJsonFileStorage, createSidekickHandler, formatDesignSystem, parseAIResponse, sidekickOverrides, validateCode };

package/dist/server/index.d.ts

@@ -222,6 +222,8 @@ type DrizzleDb = {
 };
 declare function createDrizzleStorage(db: DrizzleDb, overridesTable: typeof sidekickOverrides): SidekickStorage;
 
+declare function createJsonFileStorage(filePath?: string): SidekickStorage;
+
 declare function formatDesignSystem(schema: Record<string, unknown>): string;
 declare function buildSystemPrompt(schema: Record<string, unknown>): string;
 declare function buildUserPrompt(request: string, previousErrors?: string[], existingCode?: string): string;
@@ -232,4 +234,4 @@ declare function validateCode(code: string): {
     errors: string[];
 };
 
-export { type GeneratedOverride, type NewOverrideRecord, type NewSidekickOverride, type OverrideManifest, type OverrideRecord, type SidekickHandlerOptions, type SidekickOverride, type SidekickStorage, buildSystemPrompt, buildUserPrompt, callAI, createDrizzleStorage, createSidekickHandler, formatDesignSystem, parseAIResponse, sidekickOverrides, validateCode };
+export { type GeneratedOverride, type NewOverrideRecord, type NewSidekickOverride, type OverrideManifest, type OverrideRecord, type SidekickHandlerOptions, type SidekickOverride, type SidekickStorage, buildSystemPrompt, buildUserPrompt, callAI, createDrizzleStorage, createJsonFileStorage, createSidekickHandler, formatDesignSystem, parseAIResponse, sidekickOverrides, validateCode };

package/dist/server/index.js

@@ -34,6 +34,7 @@ __export(server_exports, {
   buildUserPrompt: () => buildUserPrompt,
   callAI: () => callAI,
   createDrizzleStorage: () => createDrizzleStorage,
+  createJsonFileStorage: () => createJsonFileStorage,
   createSidekickHandler: () => createSidekickHandler,
   formatDesignSystem: () => formatDesignSystem,
   parseAIResponse: () => parseAIResponse,
@@ -613,6 +614,81 @@ function createDrizzleStorage(db, overridesTable) {
   };
 }
 
+// src/server/json-storage.ts
+var fs2 = __toESM(require("fs/promises"));
+var path2 = __toESM(require("path"));
+function deserializeDates(record) {
+  return {
+    ...record,
+    createdAt: new Date(record.createdAt),
+    updatedAt: new Date(record.updatedAt)
+  };
+}
+async function readData(filePath) {
+  try {
+    const raw = await fs2.readFile(filePath, "utf-8");
+    const parsed = JSON.parse(raw);
+    return {
+      overrides: (parsed.overrides || []).map(deserializeDates)
+    };
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      const empty = { overrides: [] };
+      await fs2.mkdir(path2.dirname(filePath), { recursive: true });
+      await fs2.writeFile(filePath, JSON.stringify(empty, null, 2) + "\n");
+      return empty;
+    }
+    throw err;
+  }
+}
+async function writeData(filePath, data) {
+  const tmpPath = filePath + ".tmp";
+  await fs2.mkdir(path2.dirname(filePath), { recursive: true });
+  await fs2.writeFile(tmpPath, JSON.stringify(data, null, 2) + "\n");
+  await fs2.rename(tmpPath, filePath);
+}
+function createJsonFileStorage(filePath) {
+  const resolvedPath = filePath || path2.join(process.cwd(), ".sidekick", "overrides.json");
+  return {
+    async listOverrides() {
+      const data = await readData(resolvedPath);
+      return data.overrides;
+    },
+    async getOverride(id) {
+      const data = await readData(resolvedPath);
+      return data.overrides.find((o) => o.id === id) ?? null;
+    },
+    async createOverride(record) {
+      const data = await readData(resolvedPath);
+      data.overrides.push({
+        id: record.id,
+        name: record.name,
+        description: record.description,
+        version: record.version,
+        primitives: record.primitives,
+        code: record.code,
+        enabled: record.enabled ?? true,
+        createdAt: record.createdAt ?? /* @__PURE__ */ new Date(),
+        updatedAt: record.updatedAt ?? /* @__PURE__ */ new Date()
+      });
+      await writeData(resolvedPath, data);
+    },
+    async updateOverride(id, updates) {
+      const data = await readData(resolvedPath);
+      const idx = data.overrides.findIndex((o) => o.id === id);
+      if (idx === -1) return;
+      const { id: _id, createdAt: _ca, ...rest } = updates;
+      data.overrides[idx] = { ...data.overrides[idx], ...rest, updatedAt: /* @__PURE__ */ new Date() };
+      await writeData(resolvedPath, data);
+    },
+    async deleteOverride(id) {
+      const data = await readData(resolvedPath);
+      data.overrides = data.overrides.filter((o) => o.id !== id);
+      await writeData(resolvedPath, data);
+    }
+  };
+}
+
 // src/server/drizzle-schema.ts
 var import_pg_core = require("drizzle-orm/pg-core");
 var sidekickOverrides = (0, import_pg_core.pgTable)("overrides", {
@@ -633,6 +709,7 @@ var sidekickOverrides = (0, import_pg_core.pgTable)("overrides", {
   buildUserPrompt,
   callAI,
   createDrizzleStorage,
+  createJsonFileStorage,
   createSidekickHandler,
   formatDesignSystem,
   parseAIResponse,