@usesidekick/react 0.1.0

package/README.md

@@ -0,0 +1,246 @@
+# Sidekick React SDK
+
+Zero-change integration for extensible React applications. Override modules can customize any component by name without modifying the host application.
+
+## Quick Start
+
+### 1. Install
+
+```bash
+npm install @usesidekick/react
+```
+
+### 2. Wrap Your App
+
+```tsx
+import { SidekickProvider } from '@usesidekick/react';
+
+export default function App() {
+  return (
+    <SidekickProvider>
+      <YourApp />
+    </SidekickProvider>
+  );
+}
+```
+
+### 3. (Production) Add Build Plugin
+
+For production builds, add the `babel-plugin-add-react-displayname` plugin to automatically preserve component names through minification.
+
+**Next.js** (`next.config.js`):
+```js
+module.exports = {
+  // Using Babel
+  babel: {
+    plugins: ['add-react-displayname']
+  }
+}
+```
+
+**Vite** (`vite.config.ts`):
+```ts
+import react from '@vitejs/plugin-react';
+
+export default {
+  plugins: [
+    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:
+
+```tsx
+import { createOverride } from '@usesidekick/react';
+
+export default createOverride({
+  name: 'Custom Task Card Wrapper',
+  primitives: ['ui.wrap'],
+  activate: (sdk) => {
+    sdk.ui.wrap('TaskCard', (Original) => (props) => (
+      <div className="relative">
+        <span className="badge">New!</span>
+        <Original {...props} />
+      </div>
+    ));
+  },
+});
+```
+
+### 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
+
+#### UI Primitives
+
+| 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.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 |
+
+#### Data Primitives
+
+| Method | Description |
+|--------|-------------|
+| `sdk.data.computed(fieldName, compute)` | Add a computed field |
+| `sdk.data.addFilter(name, filter)` | Add a data filter |
+| `sdk.data.transform(dataKey, transform)` | Transform data |
+| `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
+
+| Method | Description |
+|--------|-------------|
+| `sdk.behavior.onEvent(name, handler)` | Handle custom events |
+| `sdk.behavior.addKeyboardShortcut(keys, action)` | Add keyboard shortcuts |
+| `sdk.behavior.modifyRoute(pattern, handler)` | Modify routing behavior |
+
+## ExtensionPoints (Optional)
+
+For fine-grained injection slots, you can still use ExtensionPoints:
+
+```tsx
+import { ExtensionPoint } from '@usesidekick/react';
+
+function MyComponent() {
+  return (
+    <div>
+      <ExtensionPoint id="header-actions" props={{ user }} />
+      {/* ... */}
+    </div>
+  );
+}
+```
+
+Override modules can then inject into these points:
+
+```tsx
+sdk.ui.inject('header-actions', ({ user }) => (
+  <button>Hello, {user.name}!</button>
+));
+```
+
+## Technical Details
+
+### How It Works
+
+The SDK overrides `React.createElement` to intercept every component render. When a component is rendered, it checks:
+
+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.
+3. Otherwise, render normally.
+
+This approach requires **zero changes** to existing components - just wrap your app with `SidekickProvider`.
+
+### Performance
+
+- One Map lookup per createElement call
+- Negligible overhead (<1% in benchmarks)
+- No impact 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
+
+### Limitations
+
+- 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)
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,358 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode, ComponentType } from 'react';
+export { configureJsxRuntime, getSeenComponentsFromJsx, isJsxRuntimeConfigured, onConfigChange } from './jsx-runtime.mjs';
+
+interface SidekickProviderProps {
+    children: ReactNode;
+    /** API endpoint to fetch overrides from (for production/DB-backed overrides) */
+    overridesEndpoint?: string;
+}
+declare function SidekickProvider({ children, overridesEndpoint }: SidekickProviderProps): react_jsx_runtime.JSX.Element;
+
+interface Override {
+    id: string;
+    name: string;
+    description: string;
+    version: string;
+    enabled: boolean;
+}
+interface OverrideManifest {
+    id: string;
+    name: string;
+    description: string;
+    version: string;
+    primitives: string[];
+}
+interface OverrideModule {
+    manifest: OverrideManifest;
+    activate: (sdk: SDK) => void | Promise<void>;
+}
+interface WrappedComponent {
+    id: string;
+    overrideId: string;
+    wrapper: (Component: ComponentType) => ComponentType;
+    priority?: number;
+    where?: (props: Record<string, unknown>) => boolean;
+}
+interface AddedColumn {
+    id: string;
+    overrideId: string;
+    tableId: string;
+    header: string;
+    accessor: string | ((row: Record<string, unknown>) => unknown);
+    render?: (value: unknown, row: Record<string, unknown>) => ReactNode;
+    priority?: number;
+}
+interface ColumnRename {
+    id: string;
+    overrideId: string;
+    tableId: string;
+    originalHeader: string;
+    newHeader: string;
+}
+interface HiddenColumn {
+    id: string;
+    overrideId: string;
+    tableId: string;
+    header: string;
+}
+interface ColumnOrder {
+    id: string;
+    overrideId: string;
+    tableId: string;
+    order: string[];
+}
+interface RowFilter {
+    id: string;
+    overrideId: string;
+    tableId: string;
+    filter: (row: Record<string, unknown>) => boolean;
+}
+interface MenuItem {
+    id: string;
+    overrideId: string;
+    menuId: string;
+    label: string;
+    icon?: string;
+    onClick: () => void;
+    priority?: number;
+}
+interface TabItem {
+    id: string;
+    overrideId: string;
+    tabGroupId: string;
+    label: string;
+    content: ComponentType<Record<string, unknown>>;
+    priority?: number;
+}
+interface PropsModifier {
+    id: string;
+    overrideId: string;
+    componentId: string;
+    modifier: (props: Record<string, unknown>) => Record<string, unknown>;
+}
+interface ActionItem {
+    id: string;
+    overrideId: string;
+    actionBarId: string;
+    label: string;
+    icon?: string;
+    onClick: (context: Record<string, unknown>) => void;
+    variant?: 'primary' | 'secondary' | 'danger';
+    priority?: number;
+}
+interface ValidationRule {
+    id: string;
+    overrideId: string;
+    formId: string;
+    fieldName: string;
+    validate: (value: unknown, formData: Record<string, unknown>) => string | null;
+    priority?: number;
+}
+interface ApiInterceptor {
+    id: string;
+    overrideId: string;
+    pathPattern: string | RegExp;
+    handler: (response: unknown, request: {
+        path: string;
+        method: string;
+    }) => unknown;
+}
+interface SortOption {
+    id: string;
+    overrideId: string;
+    tableId: string;
+    label: string;
+    field: string;
+    comparator: (a: Record<string, unknown>, b: Record<string, unknown>) => number;
+}
+interface GroupByOption {
+    id: string;
+    overrideId: string;
+    tableId: string;
+    label: string;
+    grouper: (item: Record<string, unknown>) => string;
+}
+interface DOMModification {
+    id: string;
+    overrideId: string;
+    selector: string;
+    type: 'setText' | 'setAttribute' | 'setStyle' | 'addClass' | 'removeClass';
+    value: unknown;
+}
+interface InjectionPoint {
+    id: string;
+    overrideId: string;
+    selector: string;
+    position: 'before' | 'after' | 'prepend' | 'append';
+    component: ComponentType<Record<string, unknown>>;
+}
+interface DOMEventListener {
+    id: string;
+    overrideId: string;
+    selector: string;
+    eventType: string;
+    handler: (event: Event, element: Element) => void;
+}
+interface EventHandler {
+    id: string;
+    overrideId: string;
+    eventName: string;
+    handler: (payload: Record<string, unknown>) => void;
+    priority?: number;
+}
+interface KeyboardShortcut {
+    id: string;
+    overrideId: string;
+    keys: string;
+    action: () => void;
+    description?: string;
+}
+interface RouteModifier {
+    id: string;
+    overrideId: string;
+    pathPattern: string | RegExp;
+    handler: (context: {
+        path: string;
+        params: Record<string, string>;
+    }) => void | string;
+}
+interface ComputedField {
+    id: string;
+    overrideId: string;
+    fieldName: string;
+    compute: (data: Record<string, unknown>) => unknown;
+}
+interface DataFilter {
+    id: string;
+    overrideId: string;
+    name: string;
+    filter: (items: unknown[]) => unknown[];
+}
+interface DataTransform {
+    id: string;
+    overrideId: string;
+    dataKey: string;
+    transform: (data: unknown) => unknown;
+}
+interface InjectedStyles {
+    id: string;
+    overrideId: string;
+    css: string;
+}
+interface UIPrimitives {
+    wrap: (componentName: string, wrapper: (Component: ComponentType) => ComponentType, options?: {
+        priority?: number;
+        where?: (props: Record<string, unknown>) => boolean;
+    }) => void;
+    replace: (componentName: string, replacement: ComponentType) => void;
+    addStyles: (css: string) => void;
+    addColumn: (tableId: string, config: Omit<AddedColumn, 'id' | 'overrideId' | 'tableId'>) => void;
+    renameColumn: (tableId: string, originalHeader: string, newHeader: string) => void;
+    hideColumn: (tableId: string, header: string) => void;
+    reorderColumns: (tableId: string, order: string[]) => void;
+    filterRows: (tableId: string, filter: (row: Record<string, unknown>) => boolean) => void;
+    addMenuItem: (menuId: string, config: Omit<MenuItem, 'id' | 'overrideId' | 'menuId'>) => void;
+    addTab: (tabGroupId: string, config: Omit<TabItem, 'id' | 'overrideId' | 'tabGroupId'>) => void;
+    modifyProps: (componentId: string, modifier: (props: Record<string, unknown>) => Record<string, unknown>) => void;
+    addAction: (actionBarId: string, config: Omit<ActionItem, 'id' | 'overrideId' | 'actionBarId'>) => void;
+    addValidation: (formId: string, fieldName: string, validate: (value: unknown, formData: Record<string, unknown>) => string | null) => void;
+    setText: (selector: string, text: string) => void;
+    setAttribute: (selector: string, attr: string, value: string) => void;
+    setStyle: (selector: string, styles: Record<string, string>) => void;
+    addClass: (selector: string, className: string) => void;
+    removeClass: (selector: string, className: string) => void;
+    inject: (selector: string, component: ComponentType<Record<string, unknown>>, position?: 'before' | 'after' | 'prepend' | 'append') => void;
+}
+interface DataPrimitives {
+    computed: (fieldName: string, compute: (data: Record<string, unknown>) => unknown) => void;
+    addFilter: (name: string, filter: (items: unknown[]) => unknown[]) => void;
+    transform: (dataKey: string, transformFn: (data: unknown) => unknown) => void;
+    intercept: (pathPattern: string | RegExp, handler: (response: unknown, request: {
+        path: string;
+        method: string;
+    }) => unknown) => void;
+    addSortOption: (tableId: string, config: Omit<SortOption, 'id' | 'overrideId' | 'tableId'>) => void;
+    addGroupBy: (tableId: string, config: Omit<GroupByOption, 'id' | 'overrideId' | 'tableId'>) => void;
+}
+interface BehaviorPrimitives {
+    onEvent: (eventName: string, handler: (payload: Record<string, unknown>) => void, options?: {
+        priority?: number;
+    }) => void;
+    addKeyboardShortcut: (keys: string, action: () => void, description?: string) => void;
+    modifyRoute: (pathPattern: string | RegExp, handler: (context: {
+        path: string;
+        params: Record<string, string>;
+    }) => void | string) => void;
+    onDOMEvent: (selector: string, eventType: string, handler: (event: Event, element: Element) => void) => void;
+}
+interface SDK {
+    ui: UIPrimitives;
+    data: DataPrimitives;
+    behavior: BehaviorPrimitives;
+}
+interface SidekickState {
+    overrides: Override[];
+    wrappers: Map<string, WrappedComponent[]>;
+    replacements: Map<string, ComponentType>;
+    styles: InjectedStyles[];
+    columns: Map<string, AddedColumn[]>;
+    columnRenames: Map<string, ColumnRename[]>;
+    hiddenColumns: Map<string, HiddenColumn[]>;
+    columnOrders: Map<string, ColumnOrder>;
+    rowFilters: Map<string, RowFilter[]>;
+    menuItems: Map<string, MenuItem[]>;
+    tabs: Map<string, TabItem[]>;
+    propsModifiers: Map<string, PropsModifier[]>;
+    actions: Map<string, ActionItem[]>;
+    validations: Map<string, ValidationRule[]>;
+    computedFields: Map<string, ComputedField>;
+    filters: Map<string, DataFilter>;
+    transforms: Map<string, DataTransform>;
+    interceptors: ApiInterceptor[];
+    sortOptions: Map<string, SortOption[]>;
+    groupByOptions: Map<string, GroupByOption[]>;
+    eventHandlers: Map<string, EventHandler[]>;
+    keyboardShortcuts: KeyboardShortcut[];
+    routeModifiers: RouteModifier[];
+    domModifications: DOMModification[];
+    injections: InjectionPoint[];
+    domEventListeners: DOMEventListener[];
+}
+
+interface SidekickContextValue {
+    state: SidekickState;
+    overrides: Override[];
+    isOverrideEnabled: (id: string) => boolean;
+    toggleOverride: (id: string) => void;
+    getColumns: (tableId: string) => AddedColumn[];
+    getColumnRenames: (tableId: string) => ColumnRename[];
+    getHiddenColumns: (tableId: string) => HiddenColumn[];
+    getColumnOrder: (tableId: string) => ColumnOrder | undefined;
+    getMenuItems: (menuId: string) => MenuItem[];
+    getTabs: (tabGroupId: string) => TabItem[];
+    getActions: (actionBarId: string) => ActionItem[];
+    getValidations: (formId: string) => ValidationRule[];
+    getWrapper: (componentName: string) => ((Component: ComponentType) => ComponentType) | undefined;
+    getReplacement: (componentName: string) => ComponentType | undefined;
+    applyPropsModifiers: (componentId: string, props: Record<string, unknown>) => Record<string, unknown>;
+    getComputedValue: <T>(fieldName: string, data: Record<string, unknown>) => T | undefined;
+    applyFilters: <T>(filterName: string, items: T[]) => T[];
+    applyTransform: <T>(dataKey: string, data: T) => T;
+    getSortOptions: (tableId: string) => SortOption[];
+    getGroupByOptions: (tableId: string) => GroupByOption[];
+    getKeyboardShortcuts: () => KeyboardShortcut[];
+    emitEvent: (eventName: string, payload: Record<string, unknown>) => void;
+}
+declare function useSidekickSafe(): SidekickContextValue | null;
+declare function useSidekick(): SidekickContextValue;
+declare function useAddedColumns(tableId: string): AddedColumn[];
+declare function useColumnRenames(tableId: string): ColumnRename[];
+declare function useHiddenColumns(tableId: string): HiddenColumn[];
+declare function useColumnOrder(tableId: string): ColumnOrder | undefined;
+declare function useMenuItems(menuId: string): MenuItem[];
+declare function useTabs(tabGroupId: string): TabItem[];
+declare function useActions(actionBarId: string): ActionItem[];
+declare function useValidations(formId: string): ValidationRule[];
+declare function usePropsModifier(componentId: string, props: Record<string, unknown>): Record<string, unknown>;
+declare function useComputedField<T>(fieldName: string, data: Record<string, unknown>): T | undefined;
+declare function useFilter<T>(filterName: string, items: T[]): T[];
+declare function useSortOptions(tableId: string): SortOption[];
+declare function useGroupByOptions(tableId: string): GroupByOption[];
+declare function useKeyboardShortcuts(): KeyboardShortcut[];
+declare function useEventEmitter(): (eventName: string, payload: Record<string, unknown>) => void;
+
+interface SidekickPanelProps {
+    apiEndpoint?: string;
+    deleteEndpoint?: string;
+    toggleEndpoint?: string;
+    onGenerate?: (request: string) => Promise<{
+        success: boolean;
+        overrideId?: string;
+        error?: string;
+    }>;
+    onDelete?: (overrideId: string) => Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    onToggle?: (overrideId: string, enabled: boolean) => Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+}
+declare function SidekickPanel({ apiEndpoint, deleteEndpoint, toggleEndpoint, onGenerate, onDelete, onToggle }: SidekickPanelProps): react_jsx_runtime.JSX.Element;
+
+declare function registerOverride(module: OverrideModule): void;
+declare function getRegisteredOverrides(): OverrideModule[];
+declare function createOverride(manifest: OverrideManifest, activate: OverrideModule['activate']): OverrideModule;
+
+interface FlagState {
+    [overrideId: string]: boolean;
+}
+declare function loadFlags(): FlagState;
+declare function saveFlags(flags: FlagState): void;
+declare function getFlag(overrideId: string): boolean;
+declare function setFlag(overrideId: string, enabled: boolean): void;
+declare function toggleFlag(overrideId: string): boolean;
+
+export { type ActionItem, type AddedColumn, type ApiInterceptor, type BehaviorPrimitives, type ColumnOrder, type ColumnRename, type ComputedField, type DOMEventListener, type DOMModification, type DataFilter, type DataPrimitives, type DataTransform, type EventHandler, type GroupByOption, type HiddenColumn, type InjectionPoint, type KeyboardShortcut, type MenuItem, type Override, type OverrideManifest, type OverrideModule, type PropsModifier, type RouteModifier, type RowFilter, type SDK, SidekickPanel, SidekickProvider, type SidekickState, type SortOption, type TabItem, type UIPrimitives, type ValidationRule, type WrappedComponent, createOverride, getFlag, getRegisteredOverrides, loadFlags, registerOverride, saveFlags, setFlag, toggleFlag, useActions, useAddedColumns, useColumnOrder, useColumnRenames, useComputedField, useEventEmitter, useFilter, useGroupByOptions, useHiddenColumns, useKeyboardShortcuts, useMenuItems, usePropsModifier, useSidekick, useSidekickSafe, useSortOptions, useTabs, useValidations };