@usesidekick/react 0.1.0

package/src/components/index.ts

@@ -0,0 +1 @@
+export { SidekickPanel } from './SidekickPanel';

package/src/context.tsx

@@ -0,0 +1,157 @@
+'use client';
+
+import { createContext, useContext, ComponentType } from 'react';
+import {
+  SidekickState,
+  Override,
+  AddedColumn,
+  ColumnRename,
+  HiddenColumn,
+  ColumnOrder,
+  MenuItem,
+  TabItem,
+  ActionItem,
+  ValidationRule,
+  SortOption,
+  GroupByOption,
+  KeyboardShortcut,
+} from './types';
+
+export interface SidekickContextValue {
+  state: SidekickState;
+  overrides: Override[];
+  isOverrideEnabled: (id: string) => boolean;
+  toggleOverride: (id: string) => void;
+  // UI getters
+  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>;
+  // Data getters
+  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[];
+  // Behavior getters
+  getKeyboardShortcuts: () => KeyboardShortcut[];
+  emitEvent: (eventName: string, payload: Record<string, unknown>) => void;
+}
+
+export const SidekickContext = createContext<SidekickContextValue | null>(null);
+
+// Safe hook that returns null during SSR instead of throwing
+export function useSidekickSafe(): SidekickContextValue | null {
+  return useContext(SidekickContext);
+}
+
+export function useSidekick(): SidekickContextValue {
+  const context = useContext(SidekickContext);
+  if (!context) {
+    throw new Error('useSidekick must be used within a SidekickProvider');
+  }
+  return context;
+}
+
+// UI Hooks
+
+export function useAddedColumns(tableId: string): AddedColumn[] {
+  const context = useSidekickSafe();
+  if (!context) return [];
+  return context.getColumns(tableId);
+}
+
+export function useColumnRenames(tableId: string): ColumnRename[] {
+  const context = useSidekickSafe();
+  if (!context) return [];
+  return context.getColumnRenames(tableId);
+}
+
+export function useHiddenColumns(tableId: string): HiddenColumn[] {
+  const context = useSidekickSafe();
+  if (!context) return [];
+  return context.getHiddenColumns(tableId);
+}
+
+export function useColumnOrder(tableId: string): ColumnOrder | undefined {
+  const context = useSidekickSafe();
+  if (!context) return undefined;
+  return context.getColumnOrder(tableId);
+}
+
+export function useMenuItems(menuId: string): MenuItem[] {
+  const context = useSidekickSafe();
+  if (!context) return [];
+  return context.getMenuItems(menuId);
+}
+
+export function useTabs(tabGroupId: string): TabItem[] {
+  const context = useSidekickSafe();
+  if (!context) return [];
+  return context.getTabs(tabGroupId);
+}
+
+export function useActions(actionBarId: string): ActionItem[] {
+  const context = useSidekickSafe();
+  if (!context) return [];
+  return context.getActions(actionBarId);
+}
+
+export function useValidations(formId: string): ValidationRule[] {
+  const context = useSidekickSafe();
+  if (!context) return [];
+  return context.getValidations(formId);
+}
+
+export function usePropsModifier(componentId: string, props: Record<string, unknown>): Record<string, unknown> {
+  const context = useSidekickSafe();
+  if (!context) return props;
+  return context.applyPropsModifiers(componentId, props);
+}
+
+// Data Hooks
+
+export function useComputedField<T>(fieldName: string, data: Record<string, unknown>): T | undefined {
+  const context = useSidekickSafe();
+  if (!context) return undefined;
+  return context.getComputedValue<T>(fieldName, data);
+}
+
+export function useFilter<T>(filterName: string, items: T[]): T[] {
+  const context = useSidekickSafe();
+  if (!context) return items;
+  return context.applyFilters(filterName, items);
+}
+
+export function useSortOptions(tableId: string): SortOption[] {
+  const context = useSidekickSafe();
+  if (!context) return [];
+  return context.getSortOptions(tableId);
+}
+
+export function useGroupByOptions(tableId: string): GroupByOption[] {
+  const context = useSidekickSafe();
+  if (!context) return [];
+  return context.getGroupByOptions(tableId);
+}
+
+// Behavior Hooks
+
+export function useKeyboardShortcuts(): KeyboardShortcut[] {
+  const context = useSidekickSafe();
+  if (!context) return [];
+  return context.getKeyboardShortcuts();
+}
+
+export function useEventEmitter(): (eventName: string, payload: Record<string, unknown>) => void {
+  const context = useSidekickSafe();
+  if (!context) return () => {};
+  return context.emitEvent;
+}

package/src/flags.ts

@@ -0,0 +1,47 @@
+const STORAGE_KEY = 'sidekick_flags';
+
+export interface FlagState {
+  [overrideId: string]: boolean;
+}
+
+export function loadFlags(): FlagState {
+  if (typeof window === 'undefined') {
+    return {};
+  }
+
+  try {
+    const stored = localStorage.getItem(STORAGE_KEY);
+    return stored ? JSON.parse(stored) : {};
+  } catch {
+    return {};
+  }
+}
+
+export function saveFlags(flags: FlagState): void {
+  if (typeof window === 'undefined') {
+    return;
+  }
+
+  try {
+    localStorage.setItem(STORAGE_KEY, JSON.stringify(flags));
+  } catch {
+    console.warn('[Sidekick] Failed to save flags to localStorage');
+  }
+}
+
+export function getFlag(overrideId: string): boolean {
+  const flags = loadFlags();
+  return flags[overrideId] ?? false;
+}
+
+export function setFlag(overrideId: string, enabled: boolean): void {
+  const flags = loadFlags();
+  flags[overrideId] = enabled;
+  saveFlags(flags);
+}
+
+export function toggleFlag(overrideId: string): boolean {
+  const current = getFlag(overrideId);
+  setFlag(overrideId, !current);
+  return !current;
+}

package/src/index.ts

@@ -0,0 +1,71 @@
+// Provider and Context
+export { SidekickProvider } from './provider';
+export {
+  useSidekick,
+  useSidekickSafe,
+  // UI hooks
+  useAddedColumns,
+  useColumnRenames,
+  useHiddenColumns,
+  useColumnOrder,
+  useMenuItems,
+  useTabs,
+  useActions,
+  useValidations,
+  usePropsModifier,
+  // Data hooks
+  useComputedField,
+  useFilter,
+  useSortOptions,
+  useGroupByOptions,
+  // Behavior hooks
+  useKeyboardShortcuts,
+  useEventEmitter,
+} from './context';
+
+// Components
+export { SidekickPanel } from './components';
+
+// Override loader
+export { registerOverride, createOverride, getRegisteredOverrides } from './loader';
+
+// Flags
+export { loadFlags, saveFlags, getFlag, setFlag, toggleFlag } from './flags';
+
+// JSX runtime configuration (for debugging)
+export { configureJsxRuntime, getSeenComponentsFromJsx, onConfigChange, isJsxRuntimeConfigured } from './jsx-runtime';
+
+// Types
+export type {
+  SDK,
+  UIPrimitives,
+  DataPrimitives,
+  BehaviorPrimitives,
+  Override,
+  OverrideManifest,
+  OverrideModule,
+  WrappedComponent,
+  AddedColumn,
+  ColumnRename,
+  HiddenColumn,
+  ColumnOrder,
+  RowFilter,
+  MenuItem,
+  TabItem,
+  PropsModifier,
+  ActionItem,
+  ValidationRule,
+  ComputedField,
+  DataFilter,
+  DataTransform,
+  ApiInterceptor,
+  SortOption,
+  GroupByOption,
+  EventHandler,
+  KeyboardShortcut,
+  RouteModifier,
+  DOMModification,
+  InjectionPoint,
+  DOMEventListener,
+  SidekickState,
+} from './types';

package/src/jsx-dev-runtime.ts

@@ -0,0 +1,138 @@
+/**
+ * Custom JSX dev runtime that intercepts component creation.
+ * This is used in development mode.
+ * Uses React.createElement internally to avoid circular dependency with react/jsx-dev-runtime alias.
+ *
+ * IMPORTANT: Uses the same globalThis-based config as jsx-runtime.ts
+ * so all module instances share the same configuration regardless of bundling.
+ */
+
+import React from 'react';
+import { configureJsxRuntime, getSeenComponentsFromJsx } from './jsx-runtime';
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type WrapperGetter = (name: string) => ((Component: any) => any) | undefined;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type ReplacementGetter = (name: string) => any | undefined;
+
+const GLOBAL_KEY = '__SIDEKICK_JSX_CONFIG__';
+
+interface SidekickJsxConfig {
+  getWrapper: WrapperGetter | null;
+  getReplacement: ReplacementGetter | null;
+  listeners: Set<() => void>;
+  seenComponents: Set<string>;
+}
+
+function getGlobalConfig(): SidekickJsxConfig {
+  const g = globalThis as Record<string, unknown>;
+  if (!g[GLOBAL_KEY]) {
+    g[GLOBAL_KEY] = {
+      getWrapper: null,
+      getReplacement: null,
+      listeners: new Set(),
+      seenComponents: new Set<string>(),
+    };
+  }
+  return g[GLOBAL_KEY] as SidekickJsxConfig;
+}
+
+// Debug mode
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const getDebug = () => typeof window !== 'undefined' && (window as any).__SIDEKICK_DEBUG__;
+
+function getComponentName(type: unknown): string | null {
+  if (!type) return null;
+
+  if (typeof type === 'function') {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const fn = type as any;
+    if (fn.displayName) return fn.displayName;
+    if (fn.name) return fn.name;
+    return null;
+  }
+
+  if (typeof type === 'object' && type !== null) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const obj = type as any;
+    if (obj.displayName) return obj.displayName;
+    if (obj.$$typeof) {
+      if (obj.type) return getComponentName(obj.type);
+      if (obj.render) return getComponentName(obj.render);
+    }
+  }
+
+  return null;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function interceptType(type: any): any {
+  if (typeof type === 'function' || (typeof type === 'object' && type !== null)) {
+    const name = getComponentName(type);
+    const debug = getDebug();
+    const config = getGlobalConfig();
+
+    if (name) {
+      if (debug && !config.seenComponents.has(name)) {
+        config.seenComponents.add(name);
+        console.log(`[Sidekick] Seen component: ${name}`);
+      }
+
+      if (config.getReplacement) {
+        const replacement = config.getReplacement(name);
+        if (replacement) {
+          if (debug) console.log(`[Sidekick] Replacing: ${name}`);
+          return replacement;
+        }
+      }
+
+      if (config.getWrapper) {
+        const wrapper = config.getWrapper(name);
+        if (wrapper) {
+          if (debug) console.log(`[Sidekick] Wrapping: ${name}`);
+          return wrapper(type);
+        }
+      }
+    }
+  }
+
+  return type;
+}
+
+// Wrapped jsxDEV function - uses React.createElement to avoid circular alias
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function jsxDEV(
+  type: any,
+  props: any,
+  key: string | undefined,
+  _isStaticChildren: boolean,
+  _source: any,
+  _self: any
+) {
+  const { children, ...restProps } = props || {};
+  const finalProps = key !== undefined ? { ...restProps, key } : restProps;
+
+  // Handle both single child and array of children
+  if (Array.isArray(children)) {
+    return React.createElement(interceptType(type), finalProps, ...children);
+  }
+  return React.createElement(interceptType(type), finalProps, children);
+}
+
+// Re-export Fragment from React
+export const Fragment = React.Fragment;
+
+// Configuration function - configures the shared global state
+export function configureJsxDevRuntime(
+  wrapperGetter: WrapperGetter,
+  replacementGetter: ReplacementGetter
+) {
+  const config = getGlobalConfig();
+  config.getWrapper = wrapperGetter;
+  config.getReplacement = replacementGetter;
+  // Also configure via the production runtime's function (for its listeners)
+  configureJsxRuntime(wrapperGetter, replacementGetter);
+  if (getDebug()) console.log('[Sidekick] JSX dev runtime configured (global)');
+}
+
+export { getSeenComponentsFromJsx };

package/src/jsx-runtime.ts

@@ -0,0 +1,159 @@
+/**
+ * Custom JSX runtime that intercepts component creation.
+ * Uses React.createElement internally to avoid circular dependency with react/jsx-runtime alias.
+ *
+ * IMPORTANT: Uses globalThis to share state between module instances.
+ * When bundled with splitting:false, index.mjs and jsx-runtime.mjs each get their own copy.
+ * The provider configures the copy in index.mjs, but JSX calls use jsx-runtime.mjs.
+ * By storing getters on globalThis, all instances share the same configuration.
+ */
+
+import React from 'react';
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type WrapperGetter = (name: string) => ((Component: any) => any) | undefined;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type ReplacementGetter = (name: string) => any | undefined;
+type ConfigChangeListener = () => void;
+
+const GLOBAL_KEY = '__SIDEKICK_JSX_CONFIG__';
+
+interface SidekickJsxConfig {
+  getWrapper: WrapperGetter | null;
+  getReplacement: ReplacementGetter | null;
+  listeners: Set<ConfigChangeListener>;
+  seenComponents: Set<string>;
+}
+
+function getGlobalConfig(): SidekickJsxConfig {
+  const g = globalThis as Record<string, unknown>;
+  if (!g[GLOBAL_KEY]) {
+    g[GLOBAL_KEY] = {
+      getWrapper: null,
+      getReplacement: null,
+      listeners: new Set<ConfigChangeListener>(),
+      seenComponents: new Set<string>(),
+    };
+  }
+  return g[GLOBAL_KEY] as SidekickJsxConfig;
+}
+
+// Debug mode - check on each call since it might be set after module load
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const getDebug = () => typeof window !== 'undefined' && (window as any).__SIDEKICK_DEBUG__;
+
+function getComponentName(type: unknown): string | null {
+  if (!type) return null;
+
+  if (typeof type === 'function') {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const fn = type as any;
+    if (fn.displayName) return fn.displayName;
+    if (fn.name) return fn.name;
+    return null;
+  }
+
+  if (typeof type === 'object' && type !== null) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const obj = type as any;
+    if (obj.displayName) return obj.displayName;
+    if (obj.$$typeof) {
+      if (obj.type) return getComponentName(obj.type);
+      if (obj.render) return getComponentName(obj.render);
+    }
+  }
+
+  return null;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function interceptType(type: any): any {
+  if (typeof type === 'function' || (typeof type === 'object' && type !== null)) {
+    const name = getComponentName(type);
+    const debug = getDebug();
+    const config = getGlobalConfig();
+
+    if (name) {
+      if (debug && !config.seenComponents.has(name)) {
+        config.seenComponents.add(name);
+        console.log(`[Sidekick] Seen component: ${name}`);
+      }
+
+      if (config.getReplacement) {
+        const replacement = config.getReplacement(name);
+        if (replacement) {
+          if (debug) console.log(`[Sidekick] Replacing: ${name}`);
+          return replacement;
+        }
+      }
+
+      if (config.getWrapper) {
+        const wrapper = config.getWrapper(name);
+        if (wrapper) {
+          if (debug) console.log(`[Sidekick] Wrapping: ${name}`);
+          return wrapper(type);
+        }
+      }
+    }
+  }
+
+  return type;
+}
+
+// Wrapped jsx function - uses React.createElement to avoid circular alias
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function jsx(type: any, props: any, key?: string) {
+  const { children, ...restProps } = props || {};
+  const finalProps = key !== undefined ? { ...restProps, key } : restProps;
+  return React.createElement(interceptType(type), finalProps, children);
+}
+
+// Wrapped jsxs function (for multiple children)
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function jsxs(type: any, props: any, key?: string) {
+  const { children, ...restProps } = props || {};
+  const finalProps = key !== undefined ? { ...restProps, key } : restProps;
+  // For jsxs, children is always an array
+  return React.createElement(interceptType(type), finalProps, ...(children || []));
+}
+
+// Re-export Fragment from React
+export const Fragment = React.Fragment;
+
+// Configuration function - called by SidekickProvider
+export function configureJsxRuntime(
+  wrapperGetter: WrapperGetter,
+  replacementGetter: ReplacementGetter
+) {
+  const config = getGlobalConfig();
+  config.getWrapper = wrapperGetter;
+  config.getReplacement = replacementGetter;
+  if (getDebug()) console.log('[Sidekick] JSX runtime configured (global)');
+
+  // Notify all listeners that config has changed
+  config.listeners.forEach(listener => {
+    try {
+      listener();
+    } catch (e) {
+      console.error('[Sidekick] Config change listener error:', e);
+    }
+  });
+}
+
+// Subscribe to config changes (for triggering re-renders)
+export function onConfigChange(listener: ConfigChangeListener): () => void {
+  const config = getGlobalConfig();
+  config.listeners.add(listener);
+  return () => config.listeners.delete(listener);
+}
+
+// Check if the runtime is configured
+export function isJsxRuntimeConfigured(): boolean {
+  const config = getGlobalConfig();
+  return config.getWrapper !== null || config.getReplacement !== null;
+}
+
+export function getSeenComponentsFromJsx(): string[] {
+  const config = getGlobalConfig();
+  return Array.from(config.seenComponents);
+}

package/src/loader.ts

@@ -0,0 +1,35 @@
+import { OverrideModule, OverrideManifest } from './types';
+
+export interface LoadedOverride {
+  manifest: OverrideManifest;
+  module: OverrideModule;
+}
+
+// In a real implementation, this would dynamically import from the /sidekick/overrides directory
+// For now, we'll use a registry pattern where overrides register themselves
+
+const overrideRegistry = new Map<string, OverrideModule>();
+
+export function registerOverride(module: OverrideModule): void {
+  overrideRegistry.set(module.manifest.id, module);
+}
+
+export function getRegisteredOverrides(): OverrideModule[] {
+  return Array.from(overrideRegistry.values());
+}
+
+export function getOverrideById(id: string): OverrideModule | undefined {
+  return overrideRegistry.get(id);
+}
+
+export function clearOverrides(): void {
+  overrideRegistry.clear();
+}
+
+// Helper to create an override module
+export function createOverride(
+  manifest: OverrideManifest,
+  activate: OverrideModule['activate']
+): OverrideModule {
+  return { manifest, activate };
+}

package/src/primitives/behavior.ts

@@ -0,0 +1,70 @@
+import {
+  BehaviorPrimitives,
+  SidekickState,
+  EventHandler,
+  KeyboardShortcut,
+  RouteModifier,
+  DOMEventListener,
+} from '../types';
+
+function generateId(): string {
+  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+    const r = (Math.random() * 16) | 0;
+    const v = c === 'x' ? r : (r & 0x3) | 0x8;
+    return v.toString(16);
+  });
+}
+
+export function createBehaviorPrimitives(
+  state: SidekickState,
+  currentOverrideId: string
+): BehaviorPrimitives {
+  return {
+    onEvent(eventName, handler, options = {}) {
+      const eventHandler: EventHandler = {
+        id: generateId(),
+        overrideId: currentOverrideId,
+        eventName,
+        handler,
+        priority: options.priority ?? 0,
+      };
+
+      const existing = state.eventHandlers.get(eventName) ?? [];
+      existing.push(eventHandler);
+      existing.sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
+      state.eventHandlers.set(eventName, existing);
+    },
+
+    addKeyboardShortcut(keys, action, description) {
+      const shortcut: KeyboardShortcut = {
+        id: generateId(),
+        overrideId: currentOverrideId,
+        keys,
+        action,
+        description,
+      };
+      state.keyboardShortcuts.push(shortcut);
+    },
+
+    modifyRoute(pathPattern, handler) {
+      const modifier: RouteModifier = {
+        id: generateId(),
+        overrideId: currentOverrideId,
+        pathPattern,
+        handler,
+      };
+      state.routeModifiers.push(modifier);
+    },
+
+    onDOMEvent(selector, eventType, handler) {
+      const listener: DOMEventListener = {
+        id: generateId(),
+        overrideId: currentOverrideId,
+        selector,
+        eventType,
+        handler,
+      };
+      state.domEventListeners.push(listener);
+    },
+  };
+}