React Kapsule Wrapper

Common errors

• TypeError: (0, react_kapsule__WEBPACK_IMPORTED_MODULE_0__.fromKapsule) is not a function

  cause Attempting to import `fromKapsule` as a named export instead of a default export in an ES module environment.
  fix Change the import statement to `import fromKapsule from 'react-kapsule';` (removing the curly braces).

• Module not found: Can't resolve 'react-kapsule'

  cause The 'react-kapsule' package is not installed or incorrectly referenced in your project's dependencies.
  fix Install the package using your package manager: `npm install react-kapsule` or `yarn add react-kapsule`. Ensure it's listed in `package.json`.

• Cannot read properties of undefined (reading 'increment')

  cause Attempting to call a Kapsule method (e.g., `increment`) on the wrapped React component without a valid ref, or before the ref has been assigned (e.g., during initial render before mount).
  fix Ensure the ref is correctly attached to the `MyReactKapsuleComponent` and checked for `null` or `undefined` before attempting to call methods. Methods are only available after the component has mounted.

Warnings

• gotcha Props specified in `options.initPropNames` are only used during the initial instantiation of the Kapsule component. Modifying these props after the component has mounted will have no effect on the underlying Kapsule component's configuration.
  Fix: Ensure that props intended for dynamic updates are NOT listed in `initPropNames`. Only use `initPropNames` for static, initial configuration values.
• gotcha Methods of the underlying Kapsule component, when exposed via `options.methodNames`, are accessible only through a React ref to the wrapped component instance. They are not directly available as props.
  Fix: Use `useRef` or `createRef` to get a reference to the `MyReactKapsuleComponent`. Call methods like `myRef.current.myMethod()` instead of trying to pass them as props.
• breaking This package lists 'react' as a peer dependency, requiring `react@>=16.13.1`. Using an incompatible version of React (e.g., older than 16.13.1) can lead to unexpected behavior or runtime errors.
  Fix: Ensure your project's `react` and `react-dom` versions satisfy the peer dependency requirement by upgrading to `react@^16.13.1` or newer (e.g., `npm install react@^16.13.1 react-dom@^16.13.1`).

Install

• npm install react-kapsule npm
• yarn add react-kapsule yarn
• pnpm add react-kapsule pnpm

Imports

• fromKapsule
  wrong:

  import { fromKapsule } from 'react-kapsule';

  correct:

  import fromKapsule from 'react-kapsule';

  `fromKapsule` is the default export of the 'react-kapsule' package.
• fromKapsule (CJS)
  wrong:

  const { fromKapsule } = require('react-kapsule');

  correct:

  const fromKapsule = require('react-kapsule');

  For CommonJS environments, `fromKapsule` is the default export when requiring the package.
• Kapsule (from parent library)
  wrong:

  import { Kapsule } from 'kapsule';

  correct:

  import Kapsule from 'kapsule';

  While react-kapsule wraps Kapsule components, Kapsule itself is typically imported from the 'kapsule' package, where it is also a default export.

Quickstart

This quickstart demonstrates wrapping a Kapsule component with `fromKapsule`, passing initial props, exposing Kapsule methods, and interacting with them via a React ref to update the component imperatively.

import React, { useRef, useEffect } from 'react';
import ReactDOM from 'react-dom/client';
import Kapsule from 'kapsule';
import fromKapsule from 'react-kapsule';

// Define a simple Kapsule component
const myKapsuleComponent = Kapsule({
  props: {
    message: { default: 'Hello' },
    count: { default: 0 }
  },
  methods: {
    increment: function(state) { state.count++; },
    setMessage: function(state, msg) { state.message = msg; }
  },
  init(domNode, state) {
    state.container = document.createElement('div');
    domNode.appendChild(state.container);
  },
  update(state) {
    state.container.innerHTML = `<span>${state.message} from Kapsule! Count: ${state.count}</span>`;
  }
});

// Wrap the Kapsule component for React
const MyReactKapsuleComponent = fromKapsule(myKapsuleComponent, {
  methodNames: ['increment', 'setMessage'] // Expose Kapsule methods as React component methods
});

function App() {
  const kapsuleRef = useRef(null);

  useEffect(() => {
    const interval = setInterval(() => {
      if (kapsuleRef.current) {
        (kapsuleRef.current as any).increment(); // Call exposed Kapsule method
      }
    }, 1000);
    return () => clearInterval(interval);
  }, []);

  return (
    <div>
      <h1>React Kapsule Example</h1>
      <MyReactKapsuleComponent
        ref={kapsuleRef}
        message="Greetings"
        count={10}
      />
      <button onClick={() => (kapsuleRef.current as any)?.setMessage('New message!')}>
        Change Message
      </button>
    </div>
  );
}

const rootElement = document.getElementById('root');
if (rootElement) {
  const root = ReactDOM.createRoot(rootElement);
  root.render(<App />);
} else {
  console.error("Root element not found");
}