sygnal 1.0.1 → 1.1.2

package/README.md

@@ -1,13 +1,13 @@
 # Sygnal
 
-Simple library for making clean Cycle.js components
+An intuitive framework for building fast and small components or applications based on Cycle.js
 
 
 ## 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.
+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 using a functional reactive style, and helps ensure that all side-effects are isolated away from your component code.
 
 ## Sygnal
 
@@ -42,7 +42,7 @@ Sygnal's component() function is the only thing needed to create a stand-alone c
 The 3 most common/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)
+- **view**: a function receiving the current application state and returning virtual DOM elements (using either Preact style h() functions 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.
 
@@ -83,9 +83,9 @@ A very common task in web pages and browser applications is to work with form in
 
 ## 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 library"), 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.
+For plain Javascript usage, Sygnal has no prerequisites as all dependencies are pre-bundled.
 
-To bootstrap a minimal Sygnal application using Vite and JSX:
+To bootstrap a minimal Sygnal application using Vite and that supports JSX:
 
 ```bash
 npx degit tpresley/sygnal-template my-awesome-app
@@ -106,7 +106,7 @@ The results will be in the 'dist' folder, and you can serve it locally by runnin
 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")).
+Alternatively, you can use any other bundler of your choice (Webpack, Babel, Rollup, etc.).  To use JSX in your components while using alternative bundlers, 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
@@ -161,7 +161,7 @@ export default component({
   //
   //   view: ({ state }) => h('h2', `Hello ${ state.who }`)
   //
-  // but you will need to add "import { h } from @cycle/dom" to the top of your file
+  // but you will need to add "import { h } from 'sygnal'" to the top of your file
 })
 ```
 
@@ -314,4 +314,7 @@ export default component({
 
 Sygnal is the result of several years of building Cycle.js apps, and our attempts to make that process more enjoyable.  It has been used for moderate scale production applications, and we are making it available to the world in the hopes it is useful, and brings more attention to the wonderful work of the Cycle.js team.
 
-We will continue to add documentation, example code, and live demonstrations over the coming days and weeks!
+Until better documentation is available, here are some well-commented projects using most of Sygnal's features:
+- Sygnal ToDoMVC ( [GitHub](https://github.com/tpresley/sygnal-todomvc) | [Live Demo](https://tpresley.github.io/sygnal-todomvc/) ) - The [ToDoMVC](https://todomvc.com/) framework comparison app implemented in Sygnal
+- Sygnal 2048 ( [GitHub](https://github.com/tpresley/sygnal-2048) | [Live Demo](https://tpresley.github.io/sygnal-2048/) ) - The [2048 Game](https://github.com/gabrielecirulli/2048 "Original 2048 GitHub repo") implemeted in Sygnal
+- Sygnal Calculator ( [GitHub](https://github.com/tpresley/sygnal-calculator) | [Live Demo](https://tpresley.github.io/sygnal-calculator/) ) - A simple calculator implemeted in Sygnal

package/dist/extra/classes.js

@@ -0,0 +1,124 @@
+'use strict';
+/**
+ * return a validated and properly separated string of CSS class names from any number of strings, arrays, and objects
+ *
+ * @param  {...String|Array|Object} args any number of strings or arrays with valid CSS class names, or objects where the keys are valid class names and the values evaluate to true or false
+ * @return {String} list of `active` classes separated by spaces
+ *
+ * any `string` or `array` arguments are simply validated and appended to the result
+ * `objects` will evaluate the values (which can be booleans or functions), and the keys with `thruthy` values will be validated and appended to the result
+ * this function makes it easier to set dynamic classes on HTML elements
+ */
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports["default"] = classes;
+
+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 _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 _typeof(obj) { "@babel/helpers - typeof"; return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function (obj) { return typeof obj; } : function (obj) { return obj && "function" == typeof Symbol && obj.constructor === Symbol && obj !== Symbol.prototype ? "symbol" : typeof obj; }, _typeof(obj); }
+
+function _toConsumableArray(arr) { return _arrayWithoutHoles(arr) || _iterableToArray(arr) || _unsupportedIterableToArray(arr) || _nonIterableSpread(); }
+
+function _nonIterableSpread() { throw new TypeError("Invalid attempt to spread 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 _iterableToArray(iter) { if (typeof Symbol !== "undefined" && iter[Symbol.iterator] != null || iter["@@iterator"] != null) return Array.from(iter); }
+
+function _arrayWithoutHoles(arr) { if (Array.isArray(arr)) return _arrayLikeToArray(arr); }
+
+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 classes() {
+  for (var _len = arguments.length, args = new Array(_len), _key = 0; _key < _len; _key++) {
+    args[_key] = arguments[_key];
+  }
+
+  return args.reduce(function (acc, arg) {
+    if (typeof arg === 'string' && !acc.includes(arg)) {
+      acc.push.apply(acc, _toConsumableArray(classes_processString(arg)));
+    } else if (Array.isArray(arg)) {
+      acc.push.apply(acc, _toConsumableArray(classes_processArray(arg)));
+    } else if (_typeof(arg) === 'object') {
+      acc.push.apply(acc, _toConsumableArray(classes_processObject(arg)));
+    }
+
+    return acc;
+  }, []).join(' ');
+}
+/**
+ * validate a string as a CSS class name
+ *
+ * @param {String} className CSS class name to validate
+ * @return {Boolean} true if the name is a valid CSS class, false otherwise
+ */
+
+
+function isValidClassName(className) {
+  return /^[a-zA-Z0-9-_]+$/.test(className);
+}
+/**
+ * find and validate CSS class names in a string
+ *
+ * @param {String} str string containing one or more CSS class names
+ * @return {Array} valid CSS classnames from the provided string
+ */
+
+
+function classes_processString(str) {
+  if (typeof str !== 'string') throw new Error('Class name must be a string');
+  return str.trim().split(' ').reduce(function (acc, item) {
+    if (item.trim().length === 0) return acc;
+    if (!isValidClassName(item)) throw new Error("".concat(item, " is not a valid CSS class name"));
+    acc.push(item);
+    return acc;
+  }, []);
+}
+/**
+ * find and validate CSS class names in an array of strings
+ *
+ * @param {Array} arr array containing one or more strings with valid CSS class names
+ * @return {Array} valid CSS class names from the provided array
+ */
+
+
+function classes_processArray(arr) {
+  return arr.map(classes_processString).flat();
+}
+/**
+ * find and validate CSS class names in an object, and exclude keys whose value evaluates to `false`
+ *
+ * @param {Object} obj object with keys as CSS class names and values which if `truthy` cause the associated key to be returned
+ * @return {Array} valid CSS class names from the keys of the provided object where the associated value evaluated to `true`
+ *
+ * the value for each key can be either a value that evaluates to a boolean or a function that returns a boolean
+ * if the value is a function, it will be run and the returned value will be used
+ */
+
+
+function classes_processObject(obj) {
+  var ret = Object.entries(obj).filter(function (_ref) {
+    var _ref2 = _slicedToArray(_ref, 2),
+        key = _ref2[0],
+        predicate = _ref2[1];
+
+    return typeof predicate === 'function' ? predicate() : !!predicate;
+  }).map(function (_ref3) {
+    var _ref4 = _slicedToArray(_ref3, 2),
+        key = _ref4[0],
+        _ = _ref4[1];
+
+    var trimmed = key.trim();
+    if (!isValidClassName(trimmed)) throw new Error("".concat(trimmed, " is not a valid CSS class name"));
+    return trimmed;
+  });
+  return ret;
+}

package/dist/index.js

@@ -5,12 +5,28 @@ function _typeof(obj) { "@babel/helpers - typeof"; return _typeof = "function" =
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
+var _exportNames = {
+  component: true,
+  ABORT: true,
+  collection: true,
+  switchable: true,
+  processForm: true,
+  run: true,
+  classes: true,
+  xs: true
+};
 Object.defineProperty(exports, "ABORT", {
   enumerable: true,
   get: function get() {
     return _component.ABORT;
   }
 });
+Object.defineProperty(exports, "classes", {
+  enumerable: true,
+  get: function get() {
+    return _classes["default"];
+  }
+});
 Object.defineProperty(exports, "collection", {
   enumerable: true,
   get: function get() {
@@ -41,6 +57,12 @@ Object.defineProperty(exports, "switchable", {
     return _switchable["default"];
   }
 });
+Object.defineProperty(exports, "xs", {
+  enumerable: true,
+  get: function get() {
+    return _xstream["default"];
+  }
+});
 
 var _component = _interopRequireWildcard(require("./component"));
 
@@ -52,6 +74,24 @@ var _processForm = _interopRequireDefault(require("./extra/processForm"));
 
 var _run = _interopRequireDefault(require("./extra/run"));
 
+var _classes = _interopRequireDefault(require("./extra/classes"));
+
+var _dom = require("@cycle/dom");
+
+Object.keys(_dom).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (Object.prototype.hasOwnProperty.call(_exportNames, key)) return;
+  if (key in exports && exports[key] === _dom[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function get() {
+      return _dom[key];
+    }
+  });
+});
+
+var _xstream = _interopRequireDefault(require("xstream"));
+
 function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { "default": obj }; }
 
 function _getRequireWildcardCache(nodeInterop) { if (typeof WeakMap !== "function") return null; var cacheBabelInterop = new WeakMap(); var cacheNodeInterop = new WeakMap(); return (_getRequireWildcardCache = function _getRequireWildcardCache(nodeInterop) { return nodeInterop ? cacheNodeInterop : cacheBabelInterop; })(nodeInterop); }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sygnal",
-  "version": "1.0.1",
+  "version": "1.1.2",
   "description": "An intuitive framework for building fast and small components or applications based on Cycle.js",
   "main": "./dist/index.js",
   "exports": "./dist/index.js",