Documents global stylesheet and adds ScalableRect component

Author: birdofpreyru

CHANGELOG.md

@@ -1,4 +1,8 @@
 # Topcoder React Utils Changelog
 
+### v0.1.0
+The first release of the package. In general, everything is set up, we are going
+to move in difference stuff, without changing created package structure.
+
 ### v0.0.x
 Pre-release drafts of the initial package version. A big journey starts here.

README.md

@@ -13,9 +13,13 @@ external ReactJS projects developed by the Topcoder community.
 
 ### <a name="installation">Installation</a>
 Install this package as
-```
+```bash
 $ npm install --save topcoder-react-utils
 ```
+Import the global stylesheet into the root ReactJS component of your app:
+```js
+import 'topcoder-react-utils/dist/style.css';
+```
 
 You are done if you only use components and utilities provided by this
 package. If you are to use configurations to build or test your code, you
@@ -39,18 +43,22 @@ configurations for [ESLint](https://eslint.org/);
 - [**Webpack Configurations**](docs/webpack-config.md) &mdash; Standard configurations for [Webpack](https://webpack.js.org/).
 
 ### <a name="components">Components</a>
-- [**Button**](docs/button.md) &mdash; Handles buttons and button-like links
-(components that look like regular buttons, but behave as links) in the same
-uniform manner;
-- [**Link and NavLink**](docs/link-and-navlink.md) &mdash; Auxiliary wrappers
-around [React Router](https://github.com/ReactTraining/react-router)'s `<Link>`
-and `<NavLink>` components; they help to handle external and internal links in
-the same uniform manner.
+- [**`Button`**](docs/button.md) &mdash; Handles buttons and button-like links
+  (components that look like regular buttons, but behave as links) in the same
+  uniform manner;
+- [**`Link` and `NavLink`**](docs/link-and-navlink.md) &mdash; Auxiliary wrappers
+  around [React Router](https://github.com/ReactTraining/react-router)'s `<Link>`
+  and `<NavLink>` components; they help to handle external and internal links in
+  the same uniform manner;
+- [**`ScalableRect`**](docs/scalable-rect) &mdash; Container that keeps
+  the specified aspect ratio regardless its width you set.
+  
 
 ### <a name="utilities">Utilities</a>
-- [**Global Styles**](docs/global-styles.md) &mdash; TO BE DOCUMENTED;
+- [**Global Styles**](docs/global-styles.md) &mdash; Global styles necessary for
+  a generic application;
 - [**SCSS Mixins**](docs/scss-mixins.md) &mdash; Collection of useful style
-mixins;
+  mixins.
 
 ### <a name="development">Development</a>
 For convenient development you can link this package into your host package:
@@ -80,13 +88,11 @@ organization members and repo admins can commit to `master`) will trigger the
 testing, and, if successful, release of the updated package to the NPM registry.
 
 For successful release to NPM you should bump the package version in the
-`package.json`. To do it conveniently you can use one of the commands:
-- `$ npm version patch`
-- `$ npm version minor`
-- `$ npm version major`
-
-Say, if the current package version is `v0.1.2` these commands will bump `2`,
-`1`, and `0`, correspondingly. Mind that `patch` updates should not introduce
+`package.json`. To do it conveniently you can use `$ npm version UPDATE_TYPE`
+command, where `UPDATE_TYPE` stays for one of `patch`/`minor`/`major` to bump up
+`2`, `1`, or `0` in a sample version number `v0.1.2`. This command will update
+`package.json` and `package-lock.json`, and create a new commit and tag in the
+checked-out Git branch. Mind that `patch` updates should not introduce
 any breaking changes into the codebase! Breaking changes should be done via
 `minor` or `major` update, and they should be documented in
 the [CHANGELOG](CHANGELOG.md).

docs/global-styles.md

@@ -0,0 +1,18 @@
+# Global Styles
+Global styles necessary for a generic application.
+
+**Why?** — There are some standard CSS code we are likely to reuse in any
+web app, so here we provide it.
+
+The global stylesheets are include into your app when you add to your root
+ReactJS component the import
+```js
+import 'topcoder-react-utils/dist/style.css';
+```
+
+This stylesheet, beside bundled-in styles necessary for components provided by
+this package, contains:
+
+- [Eric Meyer's "Reset CSS" 2.0](https://meyerweb.com/eric/tools/css/reset/);
+- Enables `geometryPrecision` for the text rendering quality.
+

docs/scalable-rect.md

@@ -0,0 +1,56 @@
+# ScalableRect
+Container that keeps the specified aspect ratio regardless its width you set.
+
+[Example](#example)
+
+**Why?** — From time to time you need to render an HTML element with
+a specified aspect ratio of its sizes. HTML/CSS allows to achieve that, but
+it demands two nested `<div>` elements, and a non-intuitive CSS code. This
+component hides all technical aspects of that solution under the hood.
+
+**Accepted Props:**
+- **`children`** &mdash; *Node* &mdash; Optional. Any content you want to render
+  inside the container. Defaults to *null*;
+- **`className`** &mdash; *String* &mdash; Optional. The style to be applied to
+  the container itself. When provided, the rendered conainer will be wrapped into
+  an additional `<div>` wrapper, and the style will be applied to that wrapper.
+  Defaults to *null*;
+- **`ratio`** &mdash; *String* &mdash; Optional. Size ratio of the rendered
+  rectangle, in `W:H` form. Defaults to `1:1`.
+- **`styleName`** &mdash; *String* &mdash; Optional. As an alternative to
+  the `className`, you can pass in `styleName` instead. Babel will convert
+  it to the correct classname, following our setup for CSS modules.
+
+### <a name="example">Example</a>
+```scss
+// style.scss
+
+.container {
+  background: red;
+  width: 640px;
+}
+
+.content {
+  background: blue;
+  height: 100%;
+  margin: 10px;
+  width: 100;
+}
+```
+
+```js
+// index.scss
+
+import React from 'react';
+import { ScalableRect } from 'topcoder-react-utils';
+
+import './style.scss';
+
+export default function Example() {
+  return (
+    <ScalableRect styleName="container" ratio="4:3">
+      <div styleName="content" />
+    </ScalableRect>
+  );
+}
+```

src/index.js

@@ -1,11 +1,13 @@
 import Button from 'components/Button';
 import Link from 'components/Link';
 import NavLink from 'components/NavLink';
+import ScalableRect from 'components/ScalableRect';
 
 import 'styles/global.scss';
 
 export {
   Button,
   Link,
   NavLink,
+  ScalableRect,
 };

src/shared/components/ScalableRect/index.jsx

@@ -0,0 +1,49 @@
+
+/**
+ * Creates a dynamically scalable rectangular container with the specified fixed
+ * ratio of its sides.
+ *
+ * Sometimes it is necessary, but not straightforward to implement with HTML and
+ * CSS, thus this component: juts tell it what sides ration you need (in the
+ * form W:H, like 4:3 or 16:9 via the "ratio" prop, and pass in the children
+ * you want to render in this container).
+ */
+
+import PT from 'prop-types';
+import React from 'react';
+
+import './style.scss';
+
+export default function ScalableRect({ children, className, ratio }) {
+  const aux = ratio.split(':');
+  const paddingBottom = `${(100 * aux[1]) / aux[0]}%`;
+
+  /* NOTE: In case the following code looks strange to you, mind that we want to
+   * allow the user to set custom styles on this component. If user passes in a
+   * "className" prop (possibly "styleName", but that one is converted to
+   * "className" by Babel just before being passed into this component), it
+   * should not interfere with the sizing behavior, thus we need an extra <div>
+   * level in this component; however, if user does not need a custom styling,
+   * we can save one level of HTML code, so we do it. */
+  const rect = (
+    <div
+      style={{ paddingBottom }}
+      styleName="container"
+    ><div styleName="wrapper">{children}</div></div>
+  );
+  return className ? (
+    <div className={className}>{rect}</div>
+  ) : rect;
+}
+
+ScalableRect.defaultProps = {
+  children: null,
+  className: null,
+  ratio: '1:1',
+};
+
+ScalableRect.propTypes = {
+  children: PT.node,
+  className: PT.string,
+  ratio: PT.string,
+};

src/shared/components/ScalableRect/style.scss

@@ -0,0 +1,10 @@
+.container {
+  position: relative;
+  width: 100%;
+}
+
+.wrapper {
+  height: 100%;
+  position: absolute;
+  width: 100%;
+}

src/styles/global.scss

@@ -1,3 +1,8 @@
 /* Global styles. */
 
 @import "_global/reset";
+
+html,
+body {
+  text-rendering: geometricPrecision;
+}