Knockout to React Migration

Conventions

Turning Knockout components into React components

• Params need to be unwrapped in the registerReactComponent template using ko.unwrap

• Components should be default exported

• Component prop interfaces should be named ${ComponentName}Props

• Component prop interfaces should be exported

• Every migrated component must have tests

• CSS should be moved into the React components where possible

• Styles should be created via the css prop (not the style property)

• CSS mixins should be moved to Util/CSSMixin

• CSSMixins must return CSSObject

Writing tests for migrated React components

• Every component should have a test with the name Component.test.tsx next to the component (i.e. LegalHoldDot.tsx & LegalHoldDot.test.tsx)
• Every test extends a TestPage to create utility methods to access your component (i.e. finding it, clicking it, reading its values, etc.)
• Adding a data-uie-name attribute (should be unique to your component's name!) to your component and accessing it via a CSS selector (i.e. this.get('[data-uie-name="legal-hold-dot-pending-icon"]')) is the easiest way to "find" your component in a test
• A test page is typed with the properties of your component (that's why you always should export Props of your React component), so that it can instantiate your component with different props for a test run
• Basic tests include rendering your component with different props and accessing (through the extended TestPage's util methods) the component afterwards to check that the props are properly rendered
• Advanced tests simulate events (i.e. videoElement.dispatchEvent(new Event('pause'));) to assert state updates of a component
• The test should aim to test behavior not implementation of the component
• The test should not share state with other testcases. Favor functions that create a state over reusing existing state.

Example PRs / Best Practices

• Migrate LegalHoldDot to React (simple "leaf" component)
• Migrate SeekBar to React (component with event listeners)
• Creating a test that uses a feature flag (mimic Config.getConfig().FEATURE.ENABLE_FEDERATION)

Skeleton React Component (TSX)

Registering a React component in Knockout world

import React from 'react';
import {registerReactComponent} from 'Util/ComponentUtil';

const Component = (props) => {}

registerReactComponent('component-name', Component);

You can then use the newly registered component in knockout templates like this

<component-name params='user: user'></component-name>

Examples

Refactor element as HTMLElement

Knockout

viewModel: {
  createViewModel(params: MediaButtonProps, {element}: ko.components.ComponentInfo): MediaButtonComponent {
    return new MediaButtonComponent(params, element as HTMLElement);
  }
}

React

const MediaButton: React.FC<MediaButtonProps> = (props: MediaButtonProps) => {
  const element = useRef<HTMLElement>();
  // ...
}

Refactor $(...)

Knockout

const inputElement = $(element).find('.search-input');

React

const inputElement = useRef<HTMLInputElement>();

return (
  <input className="search-input" ref={inputElement} />
);

Refactor ko.observable

Knockout

const isPlaying = ko.observable(false);

React

const [isPlaying, setIsPlaying] = useState<boolean>(false);

Refactor <!-- ko if -->

Knockout

<!-- ko if: isUploaded -->
  <div>Uploaded</div>
<!-- /ko -->

React

{ isUploaded && <div>Uploaded</div> }

Refactor <!-- ko foreach -->

Knockout

<!-- ko foreach: selectedUsers -->
  <span data-bind="text: name()"></span>
<!-- /ko -->

React

{selectedUsers.map(({name, id}) => (
  <span key={id}>{name}</span>
))}

Refactor addEventListener & removeEventListener

Knockout

constructor() {
  // ...
  this.mediaElement.addEventListener('playing', this.onPlay);
  this.mediaElement.addEventListener('pause', this.onPause);
}

readonly dispose = () => {
  this.mediaElement.removeEventListener('playing', this.onPlay);
  this.mediaElement.removeEventListener('pause', this.onPause);
};

React

useEffect(() => {
  mediaElement?.addEventListener('playing', onPlay);
  mediaElement?.addEventListener('pause', onPause);

  return () => {
    mediaElement?.removeEventListener('playing', onPlay);
    mediaElement?.removeEventListener('pause', onPause);
  };
}, [mediaElement]);

Refactor css class

Knockout

<div class="media-button media-button-play"></div>

React

<div className="media-button media-button-play"></div>

Refactor data-bind="css"

Knockout

<div class="legal-hold-dot" data-bind="css: {'legal-hold-dot--active': !isPending(), 'legal-hold-dot--interactive': isInteractive, 'legal-hold-dot--large': large}"></div>

React

import cx from 'classnames';

// ...

<div
  className={cx('legal-hold-dot', {
    'legal-hold-dot--active': !isPending,
    'legal-hold-dot--interactive': isInteractive,
    'legal-hold-dot--large': large,
  })}
/>

Refactor data-bind="click"

Knockout

<div data-bind="click: onClickPlay"></div>

React

<div onClick={onClickPlay}></div>

Refactor ko.components.register

Knockout

ko.components.register('legal-hold-dot', {
  template: `
    <div>
      <!-- ko if: isPending() -->
        <pending-icon></pending-icon>
      <!-- /ko -->
      <!-- ... -->
    </div>
    `,
  viewModel: function (params): void {
    // ...
  },
});

React

registerReactComponent('legal-hold-dot', {
  component: LegalHoldDot,
  template: '<div data-bind="react: {conversation, isPending: ko.unwrap(isPending), large, legalHoldModal}"></div>',
});

Refactor Params

• Params will be renamed to Props
• All parameters that are of type ko.Subscribable have to become plain properties
• to make them plain properties, they must be unwrapped in the template definition when using registerReactComponent
• Props have to be exported to be used with the TestPage class

Knockout

interface Params {
  asset: FileAsset;
  cancel?: () => void;
  large: boolean;
  pause?: () => void;
  play?: () => void;
  src: HTMLMediaElement;
  transferState: ko.PureComputed<AssetTransferState>;
  uploadProgress: ko.PureComputed<number>;
}

React

interface MediaButtonProps {
  asset: FileAsset;
  cancel?: () => void;
  large: boolean;
  pause?: () => void;
  play: () => void;
  src: HTMLMediaElement;
  transferState: AssetTransferState;
  uploadProgress: number;
}

...
registerReactComponent('componentname', {
  component: ...,

  template: `<div 
  data-bind="react: {
    asset, 
    cancel, 
    large, 
    pause, 
    play, 
    src, 
    transferState: ko.unwrap(transferState), 
    uploadProgress: ko.unwrap(uploadProgress)
  }"></div>`,

})

Handling subscribable child props

• useKoSubscribableChildren takes root and names of child props to watch, updates if root changes
• It subscribes to child value changes and always returns the latest value

Knockout

<div>
  <div data-bind="text: user.name()"></div>
  <div data-bind="text: user.phone()"></div>
</div>

React

import {useKoSubscribableChildren} from 'Util/ComponentUtil';

const Comp = ({user}) => {
  const {name, phone} = useKoSubscribableChildren(user, ['name', 'phone']);

  return (
    <div>
      <div>{name}</div>
      <div>{phone}</div>
    </div>
  )
}

Refactor icons

Knockout

<read-icon class="panel__action-item__icon"></read-icon>

React

import Icon from 'Components/Icon';

// ...

<Icon name="read-icon" className="panel__action-item__icon" />

// or

<Icon.Read className="panel__action-item__icon" />

Migrating SVGs

<svg
  viewBox="0 0 16 16"
  dangerouslySetInnerHTML={{__html: SVGProvider['mic-off-icon']?.documentElement?.innerHTML}}
></svg>

Common Errors

Invalid value for prop `data-uie-value` on <div> tag. Either remove it from the element, or pass a string or number value to keep it in the DOM.

Problem:

<div data-uie-value={user.name}></div>

In the above case, the name property was undefined and not always guaranteed which was a problem because it is expected to be a string.