makeComponent supports sending events up through props handlers

Author: staltz

readme.md

@@ -210,9 +210,9 @@ const CycleApp = makeComponent(main);
 
 Besides `makeComponent`, this library also provides the `makeCycleReactComponent(run)` API which is more powerful and can support more use cases.
 
-It takes one argument, a `run` function which should set up and execute your application, and return three things: source, sink, (optionally:) dispose function.
+It takes one argument, a `run` function which should set up and execute your application, and return three things: source, sink, (optionally:) events object, and dispose function.
 
-- `run: () => {source, sink, dispose}`
+- `run: () => {source, sink, events, dispose}`
 
 As an example usage:
 
@@ -222,11 +222,22 @@ const CycleApp = makeCycleReactComponent(() => {
   const program = setup(main, {...drivers, react: reactDriver});
   const source = program.sources.react;
   const sink = program.sinks.react;
+  const events = {...program.sinks};
+  delete events.react;
+  for (let name in events) if (name in drivers) delete events[name];
   const dispose = program.run();
-  return {source, sink, dispose};
+  return {source, sink, events, dispose};
 });
 ```
 
+**source** is an instance of ReactSource from this library, provided to the `main` so that events can be selected in the intent.
+
+**sink** is the stream of ReactElements your `main` creates, which should be rendered in the component we're creating.
+
+**events** is a *subset* of the sinks, and contains streams that describe events that can be listened by the parent component of the `CycleApp` component. For instance, the stream `events.save` will emit events that the parent component can listen by passing the prop `onSave` to `CycleApp` component. This `events` object is optional, you do not need to create it if this component does not bubble events up to the parent.
+
+**dispose** is a function `() => void` that runs any other disposal logic you want to happen on componentWillUnmount. This is optional.
+
 Use this API to customize how instances of the returned component will use shared resources like non-rendering drivers. See recipes below.
 
   </p>
@@ -246,6 +257,9 @@ function makeComponent(main, drivers, channel = 'react') {
     const program = setup(main, {...drivers, [channel]: () => new ReactSource()});
     const source = program.sources[channel];
     const sink = program.sinks[channel];
+    const events = {...program.sinks};
+    delete events[channel];
+    for (let name in events) if (name in drivers) delete events[name];
     const dispose = program.run();
     return {source, sink, dispose};
   });
@@ -268,6 +282,8 @@ function makeComponentReusing(main, engine, channel = 'react') {
     const sources = {...engine.sources, [channel]: source};
     const sinks = main(sources);
     const sink = sinks[channel];
+    const events = {...sinks};
+    delete events[channel];
     const dispose = engine.run(sinks);
     return {source, sink, dispose};
   });

src/convert.ts

@@ -8,18 +8,21 @@ import {
   createElement,
   ComponentType,
 } from 'react';
-import {Stream} from 'xstream';
+import {Stream, Subscription} from 'xstream';
 import {ScopeContext} from './context';
 import {Sources, FantasySinks, Drivers, setup} from '@cycle/run';
 import {ReactSource} from './ReactSource';
 import {StreamRenderer} from './StreamRenderer';
 
-type RunOnDidMount = () => {
+type CycleReactEngine = {
   source: ReactSource;
   sink: Stream<ReactElement<any>>;
+  events?: {[name: string]: Stream<any>};
   dispose?: () => void;
 };
 
+type RunOnDidMount = () => CycleReactEngine;
+
 type State = {
   source: ReactSource | null;
   sink: Stream<ReactElement<any>> | null;
@@ -32,17 +35,37 @@ export function makeCycleReactComponent<P = any>(
     constructor(props: P) {
       super(props);
       this.state = {source: null, sink: null};
+      this._subs = [];
     }
 
     public _dispose?: () => void;
+    public _subs: Array<Subscription>;
 
     public componentDidMount() {
-      const {source, sink, dispose} = run();
+      const {source, sink, events, dispose} = run();
       source._props$._n(this.props);
       this._dispose = dispose;
+      if (events) {
+        this._subscribeToEvents(events);
+      }
       this.setState({source, sink});
     }
 
+    public _subscribeToEvents(events: Pick<CycleReactEngine, 'events'>) {
+      if (!events) return;
+      for (let name in events) {
+        if (!events[name]) continue;
+        const handlerName = `on${name[0].toUpperCase()}${name.slice(1)}`;
+        this._subs.push(
+          events[name].subscribe({
+            next: x => {
+              if (this.props[handlerName]) this.props[handlerName](x);
+            },
+          }),
+        );
+      }
+    }
+
     public render() {
       const {source, sink} = this.state;
       if (!source || !sink) return null;
@@ -61,6 +84,9 @@ export function makeCycleReactComponent<P = any>(
 
     public componentWillUnmount() {
       if (this._dispose) this._dispose();
+      for (const sub of this._subs) {
+        sub.unsubscribe();
+      }
     }
   };
 }
@@ -82,14 +108,22 @@ export function makeComponent<
       } as any);
       const source: ReactSource = program.sources[channel];
       const sink = program.sinks[channel];
+      const events = {...(program.sinks as object)};
+      delete events[channel];
+      for (let name in events) {
+        if (name in drivers) delete events[name];
+      }
       const dispose = program.run();
-      return {source, sink, dispose};
+      return {source, sink, events, dispose};
     });
   } else {
     return makeCycleReactComponent<P>(() => {
       const source = new ReactSource();
-      const sink = main({[channel]: source} as any)[channel];
-      return {source, sink};
+      const sinks = main({[channel]: source} as any);
+      const events = {...(sinks as object)};
+      delete events[channel];
+      const sink = sinks[channel];
+      return {source, sink, events};
     });
   }
 }

test/conversion.ts

@@ -112,6 +112,35 @@ describe('Conversion', function() {
     renderer.create(createElement(RootComponent, {name: 'Alice', age: 30}));
   });
 
+  it('output React component routes other sinks to handlers in props', done => {
+    function main(sources: {react: ReactSource}) {
+      return {
+        react: xs.of(
+          h('section', [h('div', {}, [h('h1', {}, 'Hello world')])]),
+        ),
+        something: xs
+          .periodic(200)
+          .mapTo('yellow')
+          .take(1),
+      };
+    }
+
+    const RootComponent = makeCycleReactComponent(() => {
+      const source = new ReactSource();
+      const sinks = main({react: source});
+      const sink = sinks.react;
+      return {source, sink, events: {something: sinks.something}};
+    });
+    renderer.create(
+      createElement(RootComponent, {
+        onSomething: x => {
+          assert.strictEqual(x, 'yellow');
+          done();
+        },
+      }),
+    );
+  });
+
   it('sources.react.props() evolves over time as new props come in', done => {
     function main(sources: {react: ReactSource}) {
       let first = false;