react 0.7.1 → 0.8.0

package/lib/ReactMultiChildUpdateTypes.js

@@ -0,0 +1,36 @@
+/**
+ * Copyright 2013 Facebook, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * @providesModule ReactMultiChildUpdateTypes
+ */
+
+var keyMirror = require("./keyMirror");
+
+/**
+ * When a component's children are updated, a series of update configuration
+ * objects are created in order to batch and serialize the required changes.
+ *
+ * Enumerates all the possible types of update configurations.
+ *
+ * @internal
+ */
+var ReactMultiChildUpdateTypes = keyMirror({
+  INSERT_MARKUP: null,
+  MOVE_EXISTING: null,
+  REMOVE_NODE: null,
+  TEXT_CONTENT: null
+});
+
+module.exports = ReactMultiChildUpdateTypes;

package/lib/ReactOwner.js

@@ -0,0 +1,146 @@
+/**
+ * Copyright 2013 Facebook, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * @providesModule ReactOwner
+ */
+
+"use strict";
+
+var invariant = require("./invariant");
+
+/**
+ * ReactOwners are capable of storing references to owned components.
+ *
+ * All components are capable of //being// referenced by owner components, but
+ * only ReactOwner components are capable of //referencing// owned components.
+ * The named reference is known as a "ref".
+ *
+ * Refs are available when mounted and updated during reconciliation.
+ *
+ *   var MyComponent = React.createClass({
+ *     render: function() {
+ *       return (
+ *         <div onClick={this.handleClick}>
+ *           <CustomComponent ref="custom" />
+ *         </div>
+ *       );
+ *     },
+ *     handleClick: function() {
+ *       this.refs.custom.handleClick();
+ *     },
+ *     componentDidMount: function() {
+ *       this.refs.custom.initialize();
+ *     }
+ *   });
+ *
+ * Refs should rarely be used. When refs are used, they should only be done to
+ * control data that is not handled by React's data flow.
+ *
+ * @class ReactOwner
+ */
+var ReactOwner = {
+
+  /**
+   * @param {?object} object
+   * @return {boolean} True if `object` is a valid owner.
+   * @final
+   */
+  isValidOwner: function(object) {
+    return !!(
+      object &&
+      typeof object.attachRef === 'function' &&
+      typeof object.detachRef === 'function'
+    );
+  },
+
+  /**
+   * Adds a component by ref to an owner component.
+   *
+   * @param {ReactComponent} component Component to reference.
+   * @param {string} ref Name by which to refer to the component.
+   * @param {ReactOwner} owner Component on which to record the ref.
+   * @final
+   * @internal
+   */
+  addComponentAsRefTo: function(component, ref, owner) {
+    ("production" !== process.env.NODE_ENV ? invariant(
+      ReactOwner.isValidOwner(owner),
+      'addComponentAsRefTo(...): Only a ReactOwner can have refs.'
+    ) : invariant(ReactOwner.isValidOwner(owner)));
+    owner.attachRef(ref, component);
+  },
+
+  /**
+   * Removes a component by ref from an owner component.
+   *
+   * @param {ReactComponent} component Component to dereference.
+   * @param {string} ref Name of the ref to remove.
+   * @param {ReactOwner} owner Component on which the ref is recorded.
+   * @final
+   * @internal
+   */
+  removeComponentAsRefFrom: function(component, ref, owner) {
+    ("production" !== process.env.NODE_ENV ? invariant(
+      ReactOwner.isValidOwner(owner),
+      'removeComponentAsRefFrom(...): Only a ReactOwner can have refs.'
+    ) : invariant(ReactOwner.isValidOwner(owner)));
+    // Check that `component` is still the current ref because we do not want to
+    // detach the ref if another component stole it.
+    if (owner.refs[ref] === component) {
+      owner.detachRef(ref);
+    }
+  },
+
+  /**
+   * A ReactComponent must mix this in to have refs.
+   *
+   * @lends {ReactOwner.prototype}
+   */
+  Mixin: {
+
+    /**
+     * Lazily allocates the refs object and stores `component` as `ref`.
+     *
+     * @param {string} ref Reference name.
+     * @param {component} component Component to store as `ref`.
+     * @final
+     * @private
+     */
+    attachRef: function(ref, component) {
+      ("production" !== process.env.NODE_ENV ? invariant(
+        component.isOwnedBy(this),
+        'attachRef(%s, ...): Only a component\'s owner can store a ref to it.',
+        ref
+      ) : invariant(component.isOwnedBy(this)));
+      var refs = this.refs || (this.refs = {});
+      refs[ref] = component;
+    },
+
+    /**
+     * Detaches a reference name.
+     *
+     * @param {string} ref Name to dereference.
+     * @final
+     * @private
+     */
+    detachRef: function(ref) {
+      delete this.refs[ref];
+    }
+
+  }
+
+};
+
+module.exports = ReactOwner;

package/lib/ReactPerf.js

@@ -0,0 +1,88 @@
+/**
+ * Copyright 2013 Facebook, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * @providesModule ReactPerf
+ * @typechecks static-only
+ */
+
+"use strict";
+
+var ReactPerf = {
+  /**
+   * Boolean to enable/disable measurement. Set to false by default to prevent
+   * accidental logging and perf loss.
+   */
+  enableMeasure: false,
+
+  /**
+   * Holds onto the measure function in use. By default, don't measure
+   * anything, but we'll override this if we inject a measure function.
+   */
+  storedMeasure: _noMeasure,
+
+  /**
+   * Use this to wrap methods you want to measure.
+   *
+   * @param {string} objName
+   * @param {string} fnName
+   * @param {function} func
+   * @return {function}
+   */
+  measure: function(objName, fnName, func) {
+    if ("production" !== process.env.NODE_ENV) {
+      var measuredFunc = null;
+      return function() {
+        if (ReactPerf.enableMeasure) {
+          if (!measuredFunc) {
+            measuredFunc = ReactPerf.storedMeasure(objName, fnName, func);
+          }
+          return measuredFunc.apply(this, arguments);
+        }
+        return func.apply(this, arguments);
+      };
+    }
+    return func;
+  },
+
+  injection: {
+    /**
+     * @param {function} measure
+     */
+    injectMeasure: function(measure) {
+      ReactPerf.storedMeasure = measure;
+    }
+  }
+};
+
+if ("production" !== process.env.NODE_ENV) {
+  var ExecutionEnvironment = require("./ExecutionEnvironment");
+  var url = (ExecutionEnvironment.canUseDOM && window.location.href) || '';
+  ReactPerf.enableMeasure = ReactPerf.enableMeasure ||
+    (/[?&]react_perf\b/).test(url);
+}
+
+/**
+ * Simply passes through the measured function, without measuring it.
+ *
+ * @param {string} objName
+ * @param {string} fnName
+ * @param {function} func
+ * @return {function}
+ */
+function _noMeasure(objName, fnName, func) {
+  return func;
+}
+
+module.exports = ReactPerf;

package/lib/ReactPropTransferer.js

@@ -0,0 +1,128 @@
+/**
+ * Copyright 2013 Facebook, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * @providesModule ReactPropTransferer
+ */
+
+"use strict";
+
+var emptyFunction = require("./emptyFunction");
+var invariant = require("./invariant");
+var joinClasses = require("./joinClasses");
+var merge = require("./merge");
+
+/**
+ * Creates a transfer strategy that will merge prop values using the supplied
+ * `mergeStrategy`. If a prop was previously unset, this just sets it.
+ *
+ * @param {function} mergeStrategy
+ * @return {function}
+ */
+function createTransferStrategy(mergeStrategy) {
+  return function(props, key, value) {
+    if (!props.hasOwnProperty(key)) {
+      props[key] = value;
+    } else {
+      props[key] = mergeStrategy(props[key], value);
+    }
+  };
+}
+
+/**
+ * Transfer strategies dictate how props are transferred by `transferPropsTo`.
+ */
+var TransferStrategies = {
+  /**
+   * Never transfer `children`.
+   */
+  children: emptyFunction,
+  /**
+   * Transfer the `className` prop by merging them.
+   */
+  className: createTransferStrategy(joinClasses),
+  /**
+   * Never transfer the `ref` prop.
+   */
+  ref: emptyFunction,
+  /**
+   * Transfer the `style` prop (which is an object) by merging them.
+   */
+  style: createTransferStrategy(merge)
+};
+
+/**
+ * ReactPropTransferer are capable of transferring props to another component
+ * using a `transferPropsTo` method.
+ *
+ * @class ReactPropTransferer
+ */
+var ReactPropTransferer = {
+
+  TransferStrategies: TransferStrategies,
+
+  /**
+   * @lends {ReactPropTransferer.prototype}
+   */
+  Mixin: {
+
+    /**
+     * Transfer props from this component to a target component.
+     *
+     * Props that do not have an explicit transfer strategy will be transferred
+     * only if the target component does not already have the prop set.
+     *
+     * This is usually used to pass down props to a returned root component.
+     *
+     * @param {ReactComponent} component Component receiving the properties.
+     * @return {ReactComponent} The supplied `component`.
+     * @final
+     * @protected
+     */
+    transferPropsTo: function(component) {
+      ("production" !== process.env.NODE_ENV ? invariant(
+        component.props.__owner__ === this,
+        '%s: You can\'t call transferPropsTo() on a component that you ' +
+        'don\'t own, %s. This usually means you are calling ' +
+        'transferPropsTo() on a component passed in as props or children.',
+        this.constructor.displayName,
+        component.constructor.displayName
+      ) : invariant(component.props.__owner__ === this));
+
+      var props = {};
+      for (var thatKey in component.props) {
+        if (component.props.hasOwnProperty(thatKey)) {
+          props[thatKey] = component.props[thatKey];
+        }
+      }
+      for (var thisKey in this.props) {
+        if (!this.props.hasOwnProperty(thisKey)) {
+          continue;
+        }
+        var transferStrategy = TransferStrategies[thisKey];
+        if (transferStrategy) {
+          transferStrategy(props, thisKey, this.props[thisKey]);
+        } else if (!props.hasOwnProperty(thisKey)) {
+          props[thisKey] = this.props[thisKey];
+        }
+      }
+      component.props = props;
+      return component;
+    }
+
+  }
+
+};
+
+module.exports = ReactPropTransferer;

package/lib/ReactPropTypes.js

@@ -0,0 +1,158 @@
+/**
+ * Copyright 2013 Facebook, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * @providesModule ReactPropTypes
+ */
+
+"use strict";
+
+var createObjectFrom = require("./createObjectFrom");
+var invariant = require("./invariant");
+
+/**
+ * Collection of methods that allow declaration and validation of props that are
+ * supplied to React components. Example usage:
+ *
+ *   var Props = require('ReactPropTypes');
+ *   var MyArticle = React.createClass({
+ *     propTypes: {
+ *       // An optional string prop named "description".
+ *       description: Props.string,
+ *
+ *       // A required enum prop named "category".
+ *       category: Props.oneOf(['News','Photos']).isRequired,
+ *
+ *       // A prop named "dialog" that requires an instance of Dialog.
+ *       dialog: Props.instanceOf(Dialog).isRequired
+ *     },
+ *     render: function() { ... }
+ *   });
+ *
+ * A more formal specification of how these methods are used:
+ *
+ *   type := array|bool|func|object|number|string|oneOf([...])|instanceOf(...)
+ *   decl := ReactPropTypes.{type}(.isRequired)?
+ *
+ * Each and every declaration produces a function with the same signature. This
+ * allows the creation of custom validation functions. For example:
+ *
+ *   var Props = require('ReactPropTypes');
+ *   var MyLink = React.createClass({
+ *     propTypes: {
+ *       // An optional string or URI prop named "href".
+ *       href: function(props, propName, componentName) {
+ *         var propValue = props[propName];
+ *         invariant(
+ *           propValue == null ||
+ *           typeof propValue === 'string' ||
+ *           propValue instanceof URI,
+ *           'Invalid `%s` supplied to `%s`, expected string or URI.',
+ *           propName,
+ *           componentName
+ *         );
+ *       }
+ *     },
+ *     render: function() { ... }
+ *   });
+ *
+ * @internal
+ */
+var Props = {
+
+  array: createPrimitiveTypeChecker('array'),
+  bool: createPrimitiveTypeChecker('boolean'),
+  func: createPrimitiveTypeChecker('function'),
+  number: createPrimitiveTypeChecker('number'),
+  object: createPrimitiveTypeChecker('object'),
+  string: createPrimitiveTypeChecker('string'),
+
+  oneOf: createEnumTypeChecker,
+
+  instanceOf: createInstanceTypeChecker
+
+};
+
+var ANONYMOUS = '<<anonymous>>';
+
+function createPrimitiveTypeChecker(expectedType) {
+  function validatePrimitiveType(propValue, propName, componentName) {
+    var propType = typeof propValue;
+    if (propType === 'object' && Array.isArray(propValue)) {
+      propType = 'array';
+    }
+    ("production" !== process.env.NODE_ENV ? invariant(
+      propType === expectedType,
+      'Invalid prop `%s` of type `%s` supplied to `%s`, expected `%s`.',
+      propName,
+      propType,
+      componentName,
+      expectedType
+    ) : invariant(propType === expectedType));
+  }
+  return createChainableTypeChecker(validatePrimitiveType);
+}
+
+function createEnumTypeChecker(expectedValues) {
+  var expectedEnum = createObjectFrom(expectedValues);
+  function validateEnumType(propValue, propName, componentName) {
+    ("production" !== process.env.NODE_ENV ? invariant(
+      expectedEnum[propValue],
+      'Invalid prop `%s` supplied to `%s`, expected one of %s.',
+      propName,
+      componentName,
+      JSON.stringify(Object.keys(expectedEnum))
+    ) : invariant(expectedEnum[propValue]));
+  }
+  return createChainableTypeChecker(validateEnumType);
+}
+
+function createInstanceTypeChecker(expectedClass) {
+  function validateInstanceType(propValue, propName, componentName) {
+    ("production" !== process.env.NODE_ENV ? invariant(
+      propValue instanceof expectedClass,
+      'Invalid prop `%s` supplied to `%s`, expected instance of `%s`.',
+      propName,
+      componentName,
+      expectedClass.name || ANONYMOUS
+    ) : invariant(propValue instanceof expectedClass));
+  }
+  return createChainableTypeChecker(validateInstanceType);
+}
+
+function createChainableTypeChecker(validate) {
+  function createTypeChecker(isRequired) {
+    function checkType(props, propName, componentName) {
+      var propValue = props[propName];
+      if (propValue != null) {
+        // Only validate if there is a value to check.
+        validate(propValue, propName, componentName || ANONYMOUS);
+      } else {
+        ("production" !== process.env.NODE_ENV ? invariant(
+          !isRequired,
+          'Required prop `%s` was not specified in `%s`.',
+          propName,
+          componentName || ANONYMOUS
+        ) : invariant(!isRequired));
+      }
+    }
+    if (!isRequired) {
+      checkType.isRequired = createTypeChecker(true);
+    }
+    return checkType;
+  }
+  return createTypeChecker(false);
+}
+
+module.exports = Props;