sandlot 0.1.1 → 0.1.3

package/src/react.tsx

@@ -1,331 +0,0 @@
-/**
- * React-specific helpers for Sandlot
- *
- * These helpers simplify working with dynamically loaded React components,
- * particularly when using the render function pattern for isolation.
- *
- * @example
- * ```tsx
- * import { DynamicMount } from 'sandlot/react';
- *
- * function App() {
- *   const [module, setModule] = useState(null);
- *
- *   return (
- *     <DynamicMount
- *       module={module}
- *       props={{ name: "World" }}
- *       fallback={<div>Loading...</div>}
- *     />
- *   );
- * }
- * ```
- */
-
-import {
-  useRef,
-  useEffect,
-  useCallback,
-  useState,
-  type ReactElement,
-  type RefObject,
-  type CSSProperties,
-} from "react";
-
-/**
- * Interface for dynamic modules that use the render function pattern.
- * Dynamic components should export a `render` function that mounts
- * the component into a container and returns a cleanup function.
- */
-export interface DynamicRenderModule<P = Record<string, unknown>> {
-  /**
-   * Mount the component into a container element
-   *
-   * @param container - The DOM element to render into
-   * @param props - Props to pass to the component
-   * @returns A cleanup function to unmount the component
-   */
-  render: (container: HTMLElement, props?: P) => (() => void) | void;
-}
-
-/**
- * Props for the DynamicMount component
- */
-export interface DynamicMountProps<P = Record<string, unknown>> {
-  /** The loaded dynamic module with a render function */
-  module: DynamicRenderModule<P> | null | undefined;
-  /** Props to pass to the dynamic component */
-  props?: P;
-  /** Optional className for the container div */
-  className?: string;
-  /** Optional style for the container div */
-  style?: CSSProperties;
-  /** Optional id for the container div */
-  id?: string;
-  /** Content to render while module is loading (null/undefined) */
-  fallback?: ReactElement | null;
-  /** Called when the dynamic component mounts */
-  onMount?: () => void;
-  /** Called when the dynamic component unmounts */
-  onUnmount?: () => void;
-  /** Called if rendering fails */
-  onError?: (error: Error) => void;
-}
-
-/**
- * Component that mounts a dynamic module's render function into a container.
- * Handles cleanup automatically when the module changes or unmounts.
- *
- * This is the recommended way to render dynamically loaded components
- * that use the render function pattern for React instance isolation.
- *
- * @example
- * ```tsx
- * import { DynamicMount } from 'sandlot/react';
- * import { loadModule } from 'sandlot';
- *
- * function App() {
- *   const [module, setModule] = useState(null);
- *
- *   const loadComponent = async (buildResult: BundleResult) => {
- *     const mod = await loadModule(buildResult);
- *     setModule(mod);
- *   };
- *
- *   return (
- *     <div>
- *       <button onClick={loadComponent}>Load</button>
- *       <DynamicMount
- *         module={module}
- *         props={{ count: 5 }}
- *         fallback={<div>Click to load...</div>}
- *         className="dynamic-container"
- *       />
- *     </div>
- *   );
- * }
- * ```
- */
-export function DynamicMount<P = Record<string, unknown>>({
-  module,
-  props,
-  className,
-  style,
-  id,
-  fallback = null,
-  onMount,
-  onUnmount,
-  onError,
-}: DynamicMountProps<P>): ReactElement | null {
-  const containerRef = useRef<HTMLDivElement>(null);
-  const cleanupRef = useRef<(() => void) | null>(null);
-  const [error, setError] = useState<Error | null>(null);
-
-  useEffect(() => {
-    if (!module || !containerRef.current) return;
-
-    try {
-      // Clean up previous render
-      if (cleanupRef.current) {
-        cleanupRef.current();
-        cleanupRef.current = null;
-        onUnmount?.();
-      }
-
-      // Clear any previous error
-      setError(null);
-
-      // Mount the new component
-      const cleanup = module.render(containerRef.current, props);
-      cleanupRef.current = cleanup ?? null;
-      onMount?.();
-    } catch (err) {
-      const error = err instanceof Error ? err : new Error(String(err));
-      setError(error);
-      onError?.(error);
-    }
-
-    return () => {
-      if (cleanupRef.current) {
-        cleanupRef.current();
-        cleanupRef.current = null;
-        onUnmount?.();
-      }
-    };
-  }, [module, props, onMount, onUnmount, onError]);
-
-  // Show fallback if no module
-  if (!module) {
-    return fallback;
-  }
-
-  // Show error if render failed
-  if (error) {
-    return (
-      <div
-        style={{
-          color: "red",
-          padding: "8px",
-          border: "1px solid red",
-          borderRadius: "4px",
-        }}
-      >
-        Failed to render dynamic component: {error.message}
-      </div>
-    );
-  }
-
-  return <div ref={containerRef} className={className} style={style} id={id} />;
-}
-
-/**
- * Result returned by useDynamicComponent hook
- */
-export interface UseDynamicComponentResult {
-  /** Ref to attach to the container element */
-  containerRef: RefObject<HTMLDivElement | null>;
-  /** Whether the component is currently mounted */
-  isMounted: boolean;
-  /** Any error that occurred during mounting */
-  error: Error | null;
-  /** Manually trigger a re-render with new props */
-  update: (props?: Record<string, unknown>) => void;
-  /** Manually unmount the component */
-  unmount: () => void;
-}
-
-/**
- * Hook for mounting dynamic modules with more control than DynamicMount.
- * Provides access to mount state and manual control over mounting/unmounting.
- *
- * @param module - The dynamic module to mount
- * @param props - Props to pass to the component
- * @returns Object with containerRef, state, and control functions
- *
- * @example
- * ```tsx
- * import { useDynamicComponent } from 'sandlot/react';
- *
- * function App() {
- *   const { containerRef, isMounted, error, unmount } = useDynamicComponent(
- *     module,
- *     { initialCount: 0 }
- *   );
- *
- *   return (
- *     <div>
- *       <div ref={containerRef} />
- *       {isMounted && <button onClick={unmount}>Remove</button>}
- *       {error && <div>Error: {error.message}</div>}
- *     </div>
- *   );
- * }
- * ```
- */
-export function useDynamicComponent<P = Record<string, unknown>>(
-  module: DynamicRenderModule<P> | null | undefined,
-  props?: P,
-): UseDynamicComponentResult {
-  const containerRef = useRef<HTMLDivElement | null>(null);
-  const cleanupRef = useRef<(() => void) | null>(null);
-  const propsRef = useRef(props);
-  const [isMounted, setIsMounted] = useState(false);
-  const [error, setError] = useState<Error | null>(null);
-
-  // Keep props ref updated
-  propsRef.current = props;
-
-  const unmount = useCallback(() => {
-    if (cleanupRef.current) {
-      cleanupRef.current();
-      cleanupRef.current = null;
-    }
-    setIsMounted(false);
-  }, []);
-
-  const update = useCallback(
-    (newProps?: Record<string, unknown>) => {
-      if (!module || !containerRef.current) return;
-
-      try {
-        unmount();
-        setError(null);
-        const cleanup = module.render(
-          containerRef.current,
-          (newProps ?? propsRef.current) as P,
-        );
-        cleanupRef.current = cleanup ?? null;
-        setIsMounted(true);
-      } catch (err) {
-        setError(err instanceof Error ? err : new Error(String(err)));
-      }
-    },
-    [module, unmount],
-  );
-
-  useEffect(() => {
-    if (module && containerRef.current) {
-      update(props as Record<string, unknown>);
-    }
-    return unmount;
-  }, [module, props, update, unmount]);
-
-  return { containerRef, isMounted, error, update, unmount };
-}
-
-/**
- * Code template for a React component's render function.
- * This is the pattern dynamic components should follow when using
- * the render function pattern for React instance isolation.
- *
- * Dynamic components import React from esm.sh and use their own
- * ReactDOM.createRoot to mount, avoiding conflicts with the host's React.
- */
-export const REACT_RENDER_TEMPLATE = `
-import React from "react";
-import { createRoot } from "react-dom/client";
-
-// Your component here
-function MyComponent(props) {
-  return <div>Hello {props.name}</div>;
-}
-
-// Export a render function that mounts using esm.sh's ReactDOM
-export function render(container, props) {
-  const root = createRoot(container);
-  root.render(<MyComponent {...props} />);
-  return () => root.unmount();
-}
-`.trim();
-
-/**
- * Generate render function code for a given component name.
- * Useful for code generation tools or agents.
- *
- * @param componentName - The name of the component to wrap
- * @param hasProps - Whether the component accepts props
- */
-export function generateRenderFunction(
-  componentName: string,
-  hasProps = true,
-): string {
-  if (hasProps) {
-    return `
-// Export a render function that mounts using esm.sh's ReactDOM
-export function render(container: HTMLElement, props?: Parameters<typeof ${componentName}>[0]) {
-  const root = createRoot(container);
-  root.render(<${componentName} {...props} />);
-  return () => root.unmount();
-}
-`.trim();
-  }
-
-  return `
-// Export a render function that mounts using esm.sh's ReactDOM
-export function render(container: HTMLElement) {
-  const root = createRoot(container);
-  root.render(<${componentName} />);
-  return () => root.unmount();
-}
-`.trim();
-}