sygnal 1.0.0

package/.babelrc

@@ -0,0 +1,3 @@
+{
+  "presets": ["@babel/preset-env"]
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 tpresley
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,301 @@
+# Sygnal
+
+Simple library for making clean Cycle.js components
+
+
+## Cycle.js
+
+Cycle.js is a functional reactive coding framework that asks 'what if the user was a function?'
+
+It is worth reading the summary on the [Cycle.js homepage](https://cycle.js.org/ "Cycle.js Homepage"), but essentially Cycle.js allows you to write simple, concise, extensible, and testable code.
+
+## Sygnal
+
+Sygnal makes building Cycle.js apps and components much easier by handling all of the most complex stream plumbing, and provides a minimally opinionated structure to component code while maintaining full forwards and backwards compatibility with all Cycle.js components whether built with or without Sygnal.
+
+
+## Why?
+
+Cycle.js is a powerful and criminally underappreciated framewaork that despite its many advantages (like fully isolated side-effects, functional reactive style, pure by nature components, extremely small number of dependencies and bumdle size, and fast performance) can be challenging to build complex applications with due to the high learning curve to understanding functional reactive style programming with Observables, and the sometimes complex stream plumbing that is required to layer and connect components.
+
+Sygnal provides a structured way to create Cycle.js components that accomplishes several key goals:
+- Minimize boilerplate
+- Provide a simplified way to handle common application tasks
+- Handle all stream plumbing between components
+- Support arbitrarily complex applications with deep component hierarchies
+- Reuse the best patterns from popular frameworks like React and Vue while avoiding the pitfalls
+- Support pure Javascript, Typescript, and JSX
+- Provide application state out of the box, and make it easy to use
+- Use reasonable defaults while providing access to low-level Cycle.js functionality wherever possible
+- Provide automatic debugging information
+- Work with modern bundlers like Vite, and provide easy application bootstrapping
+
+
+## Features
+
+Sygnal provides the following features for quickly building powerful components for building either a full Sygnal based application, or to be used in combination with existing Cycle.js components.
+
+### The component() Function
+
+Sygnal's component() function is the only thing needed ot create single components.  It takes any of a number of optional parameters, and returns a Cycle.js compatible component (See the [Cycle.js documentation](https://cycle.js.org/getting-started.html "Cycle.js Documentation") for a full description, but essentially it returns a function that accepts Cycle.js 'sources' and returns Cycle.js 'sinks').
+
+The 3 most useful parameters to component() are:
+- model: an object that maps 'action' names to the commands or reducers that tell Cycle.js drivers 'what' to do
+- intent: a function that receives Cycle.js sources and returns a map of 'action' names to observable streams telling the application 'when' that action should happen.
+- view: a function receiving the current application state and returning virtual DOM elements (using either Preact style h() functions from snabbdom or by using JSX transpiling using snabbdom-pragma)
+
+Essentially the 'model' parameter determines 'what' should happnen, the 'intent' parameter determines 'when' things happen, the 'view' parameter determines 'where' everything is rendered in the browser, and the provided Cycle.js 'drivers' determine 'how' things happen.
+
+Unlike most other popular frameworks, Sygnal (being built on Cycle.js) does not expect or rely on any events or functions being specified in the HTML view.  Instead, **ALL** events that the application whould respond to (whether a user action, a remote network call, a timer, or any other external event) are detected in the 'intent' function; the 'view' is **ONLY** for presentation.
+
+This strict separation of component logic makes reasoning about how to build the component easier, and makes refactoring and enhancing components a breeze.
+
+
+### The collection() Function
+
+Sygnal's collection() function is a wrapper for Cycle.js's makeCollection() function (See the [documentation here](https://cycle.js.org/api/state.html#cycle-state-source-usage-how-to-handle-a-dynamic-list-of-nested-components "@cycle/state makeComponent documentation")) that provides an extremely simplified API for creating dynamic lists of components from an array, and automatically grows, shrinks and updates with changes to the state. The collection() function is designed to work 'as is' for the vast majority of use cases, and provides configuration options for more advanced use cases.  And in the rare case that collection() is not powerful enough, Sygnal components can seamlessly work with the results of Cycle.js's makeCollection() instead.
+
+
+### The switchable() Function
+
+Sygnal's switchable() function provides an easy way to create a new component that 'switches' between multiple other components (for switching content based on tab or menu navigation for example).
+
+The 'active' component (the component which is made visible) can be set by either providing an observable that emits component names, or by a function that takes the current application state and returns the component name.
+
+
+### The run() Function
+
+Sygnal's run() function is a wrapper for Cycle.js's run() function with the following additions/defaults:
+- Automatically adds application level state (add a 'source' and 'sink' with the name 'STATE')
+- Adds a DOM driver (providing user events and accepting new virtual DOM)
+- Adds an EVENTS driver to allow easy messaging between components or the entire application
+- Adds a LOG driver that simply console.log's any data passed to it
+- Looks for and mounts to an HTML element with an id of root (#root)
+
+*NOTE: Sygnal currently only supports xstream as its observable library despite Cycle.js supporting Most and RxJS as well.  Support for these alternative observable libraries will be added in the near future.*
+
+
+### The processForm() function
+
+A very common task in web pages and borwser applications is to work with inputs.  Unfortunately, the logic and stream plumbing required to do this routine task can be challenging to developers new to observables (and is frustrating even for most veterans).  Sygnal's processForm() helper function takes any HTML form element, and automatically extracts the values from all input fields contained within it.  By default processForm() listens to both 'input' and 'submit' events, but can be configured to listen to any combination of standard or custom events on the form itself or its inputs.
+
+
+
+## Prerequisites
+
+The only prerequisites to use Sygnal are Cycle.js itself and either @cycle/dom or snabbdom-pragma for virtual dom rendering.  However, to handle more advanced observable/stream operations, it's helpful to install [xstream](https://github.com/staltz/xstream "xstream reactive stream libraray), an observable library similar to Most or RxJS that is extremely small and fast, and is tailored for use in browser based functional reactive applications.
+
+To bootstrap a minimal Sygnal application using Vite and JSX:
+
+```bash
+npx degit tpresley/sygnal-template my-awesome-app
+cd my-awesome-app
+npm install
+npm run dev
+```
+
+To build an optimized production ready version:
+
+```bash
+npm run build
+```
+
+The results will be in the 'dist' folder, and you can serve it locally by running:
+
+```bash
+npm preview
+```
+
+Alternatively, you can use any other bundler of your choice (Webpack, babel, rollup, etc.).  In order to generate the required virtual DOM in your 'view' function, you will either need to include [@cycle/dom](https://cycle.js.org/api/dom.html#api-h) to get access to virtual DOM helper functions, **or** you will need to install [snabbdom-pragma](https://www.npmjs.com/package/snabbdom-pragma) and configure your bundler to use it for transforming JSX (see [examples here](https://www.npmjs.com/package/snabbdom-pragma#usage "snabbdom-pragma bundler configuration examples)).
+
+
+## Initialization
+
+If you used the Vite based sygnal-template above, then the initialization code was already added to a script block in index.html for you.  Otherwise, you can initialize a Sygnal app by adding the following to your project entry point (usually index.js):
+
+```javascript
+import { run } from 'sygnal'
+// replace the following line with your app's root component
+import App from './app'
+
+run(App) // <-- automatically binds to a #root HTML element (make sure you have an element with id="root" or the app won't start)
+```
+
+Now you're all set to create components! If you used the Vite based sygnal-template above then you can start a Vite dev server that watches for file changes with:
+
+```bash
+npm run dev
+```
+
+
+## Basic Examples
+
+### Hello World
+
+The most basic (and not very useful) component
+
+```javascript
+import { component } from 'sygnal'
+
+export default component({
+  view: () => <h1>Hello World!</h1>
+})
+```
+
+
+### Using state (basic)
+
+All Sygnal components get state out of the box.  Sub or child components will get state passed from their parent component, but the root component will need an initial state to get things rolling.
+
+This can be provided using the 'initialState' parameter of component().
+
+```javascript
+import { component } from 'sygnal'
+
+export default component({
+  initialState: { who: 'World!' },
+  view: ({ state }) => <h1>Hello { state.who }</h1>
+  // if you prefer not to use JSX, the above is equivalent to:
+  //   view: ({ state }) => h('h2', `Hello ${ state.who }`)
+  // but you will need to add "import { h } from @cycle/dom" to the top of your file
+})
+```
+
+As shown here, the current state of the application (equal to the value of 'initialState' for now) will be passed to the view() function, and can be used in any valid Javascript/JSX syntax that results in virtual DOM.
+
+
+### DOM Events
+
+To make components capable of responding to users interacting with the DOM, you will need to add the 'model' and 'intent' parameters.
+
+The 'model' parameter is an object that maps 'action' names to what should be done when that action happens.
+
+The 'intent' parameter is a function that takes Cycle.js 'sources' and returns an object mapping 'action' names to streams/observables which fire/emit when that action should occur.
+
+This sounds more complicated than it is... basically the 'model' answers **what** can/should happen, and the 'intent' answers **when** those things will happen.
+
+To illustrate, here's a basic counter that increments when the user clicks anywhere in the page:
+
+```javascript
+import { component } from 'sygnal'
+
+export default component({
+  // initialize the count to 0
+  initialState: { count: 0 },
+  model: {
+    // when the 'INCREMENT' action happens, run this 'reducer' function
+    // which takes the current state and returns the updated state,
+    // in this case incrementing the count by 1
+    INCREMENT: (state) => {
+      return { count: state.count + 1 }
+    }
+  },
+  // the 'sources' passed to intent() is an object containing an entry for each Cycle.js 'driver' passed to run() in index.js
+  // the DOM source allows you to select DOM elements by any valid CSS selector, and listen for any DOM events
+  // because we map document click events to the 'INCREMENT' action, it will cause the 'INCREMENT' action in 'model' to fire
+  // whenever the document is clicked
+  intent: (sources) => {
+    return {
+      INCREMENT: sources.DOM.select('document').events('click')
+    }
+  },
+  // every time the state is changed, the view will automatically be efficiently rerendered (only DOM elements that have changed will be impacted)
+  view: ({ state }) => <h1>Current Count: { state.count }</h1>
+})
+```
+
+*NOTE: action names (like INCREMENT in the above example) can be any valid Javascript object key name*
+
+
+### DOM Events (part 2)
+
+Now let's improve our Hello World app with 2-way binding on an input field
+
+```javascript
+import { component } from 'sygnal'
+
+export default component({
+  // initial name
+  initialState: { name: 'World!' },
+  model: {
+    // update the name in the state whenever the 'CHANGE_NAME' action is triggered
+    // this time we use the 2nd parameter of the reducer function which gets the value passed
+    // by the stream that triggered the action
+    CHANGE_NAME: (state, data) => {
+      return { name: data }
+    }
+  },
+  // it's usually more convenient to use destructuring to 'get' the individual sources you need, like DOM in this case
+  intent: ({ DOM }) => {
+    return {
+      // select the input DOM element using it's class name
+      // then map changes to the value ('input' event) to extract the value
+      // that value will then be passed to the 2nd parameter of reducers in 'model'
+      CHANGE_NAME: DOM.select('.name').events('input').map(e => e.target.value)
+    }
+  },
+  view: ({ state }) => {
+    return (
+      <div>
+        <h1>Hello { state.name }</h1>
+        {/* set the 'value' of the input to the current state */}
+        <input className="name" value={ state.name } />
+      </div>
+    )
+  }
+})
+```
+
+*NOTE: The expression DOM.select('.name').events('input') results in an observable that 'fires' or 'emits' whenever the DOM 'input' event occurs*
+
+
+### Multiple Actions
+
+Now let's improve the counter app with increment and decrement buttons as well as an input field to set the count to any value
+
+```javascript
+import { component } from 'sygnal'
+
+// import the xtream observable library so we can do some stream operations
+import xs from 'xstream'
+
+export default component({
+  initialState: { count: 0 },
+  model: {
+    // add the value passed from the stream that triggered the action to the current count
+    // this will either be 1 or -1, so will increment or decrement the count accordingly
+    INCREMENT: (state, data) => ({ count: state.count + data }),
+    SET_COUNT: (state, data) => ({ count: parseInt(data || 0) })
+  },
+  intent: ({ DOM }) => {
+    // rather than pass streams directly to the actions, it is sometimes helpful
+    // to collect them in variables first
+    // it is convention (but not required) to name variables containing streams with a trailing '$'
+    // the 'mapTo' function causes the stream to emit the specified value whenever the stream fires
+    // so the increment$ stream will emit a '1' and the decrement$ stream a '-1' whenever their
+    // respective buttons are pressed, and as usual those values will be passed to the 2nd parameter
+    // of the reducer functions in the 'model'
+    const increment$ = DOM.select('.increment').events('click').mapTo(1)
+    const decrement$ = DOM.select('.decrement').events('click').mapTo(-1)
+    const setCount$  = DOM.select('.number').events('input').map(e => e.target.value)
+
+    return {
+      // the 'merge' function merges the events from all streams passed to it
+      // this causes the 'INCREMENT' action to fire when either the increment$ or decrement$
+      // streams fire, and will pass the value that the stream emeits (1 or -1 in this case)
+      INCREMENT: xs.merge(increment$, decrement$),
+      SET_COUNT: setCount$
+    }
+  },
+  view: ({ state }) => {
+    return (
+      <div>
+        <h1>Current Count: { state.count }</h1>
+        <input type="button" className="increment" value="+" />
+        <input type="button" className="decrement" value="-" />
+        <input className="number" value={ state.count } />
+      </div>
+    )
+  }
+})
+```

package/dist/collection.js

@@ -0,0 +1,83 @@
+'use strict';
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports["default"] = collection;
+
+var _isolate = _interopRequireDefault(require("@cycle/isolate"));
+
+var _state = require("@cycle/state");
+
+function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { "default": obj }; }
+
+function _defineProperty(obj, key, value) { if (key in obj) { Object.defineProperty(obj, key, { value: value, enumerable: true, configurable: true, writable: true }); } else { obj[key] = value; } return obj; }
+
+function _slicedToArray(arr, i) { return _arrayWithHoles(arr) || _iterableToArrayLimit(arr, i) || _unsupportedIterableToArray(arr, i) || _nonIterableRest(); }
+
+function _nonIterableRest() { throw new TypeError("Invalid attempt to destructure non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); }
+
+function _unsupportedIterableToArray(o, minLen) { if (!o) return; if (typeof o === "string") return _arrayLikeToArray(o, minLen); var n = Object.prototype.toString.call(o).slice(8, -1); if (n === "Object" && o.constructor) n = o.constructor.name; if (n === "Map" || n === "Set") return Array.from(o); if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _arrayLikeToArray(o, minLen); }
+
+function _arrayLikeToArray(arr, len) { if (len == null || len > arr.length) len = arr.length; for (var i = 0, arr2 = new Array(len); i < len; i++) { arr2[i] = arr[i]; } return arr2; }
+
+function _iterableToArrayLimit(arr, i) { var _i = arr == null ? null : typeof Symbol !== "undefined" && arr[Symbol.iterator] || arr["@@iterator"]; if (_i == null) return; var _arr = []; var _n = true; var _d = false; var _s, _e; try { for (_i = _i.call(arr); !(_n = (_s = _i.next()).done); _n = true) { _arr.push(_s.value); if (i && _arr.length === i) break; } } catch (err) { _d = true; _e = err; } finally { try { if (!_n && _i["return"] != null) _i["return"](); } finally { if (_d) throw _e; } } return _arr; }
+
+function _arrayWithHoles(arr) { if (Array.isArray(arr)) return arr; }
+
+function collection(component, stateLense) {
+  var combineList = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : ['DOM'];
+  var globalList = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : ['EVENTS'];
+  var stateSourceName = arguments.length > 4 && arguments[4] !== undefined ? arguments[4] : 'STATE';
+  return function (sources) {
+    var collectionOpts = {
+      item: component,
+      itemKey: function itemKey(state) {
+        return state.id;
+      },
+      itemScope: function itemScope(key) {
+        return key;
+      },
+      channel: stateSourceName,
+      collectSinks: function collectSinks(instances) {
+        return Object.entries(sources).reduce(function (acc, _ref) {
+          var _ref2 = _slicedToArray(_ref, 2),
+              name = _ref2[0],
+              stream = _ref2[1];
+
+          if (combineList.includes(name)) {
+            acc[name] = instances.pickCombine(name);
+          } else {
+            acc[name] = instances.pickMerge(name);
+          }
+
+          return acc;
+        }, {});
+      }
+    };
+
+    var isolateOpts = _defineProperty({}, stateSourceName, stateLense);
+
+    globalList.forEach(function (global) {
+      return isolateOpts[global] = null;
+    });
+    combineList.forEach(function (combine) {
+      return isolateOpts[combine] = null;
+    });
+    return makeIsolatedCollection(collectionOpts, isolateOpts, sources);
+  };
+}
+/**
+ * instantiate a cycle collection and isolate
+ * (makes the code for doing isolated collections more readable)
+ *
+ * @param {Object} collectionOpts options for the makeCollection function (see cycle/state documentation)
+ * @param {String|Object} isolateOpts options for the isolate function (see cycle/isolate documentation)
+ * @param {Object} sources object of cycle style sources to use for the created collection
+ * @return {Object} collection of component sinks
+ */
+
+
+function makeIsolatedCollection(collectionOpts, isolateOpts, sources) {
+  return (0, _isolate["default"])((0, _state.makeCollection)(collectionOpts), isolateOpts)(sources);
+}