@khanacademy/wonder-blocks-grid 1.0.24

package/src/components/__tests__/row.test.js

@@ -0,0 +1,175 @@
+// @flow
+
+import * as React from "react";
+import {mount} from "enzyme";
+
+import {
+    MEDIA_DEFAULT_SPEC,
+    MediaLayoutContext,
+} from "@khanacademy/wonder-blocks-layout";
+import Row from "../row.js";
+import Cell from "../cell.js";
+
+describe("Row", () => {
+    describe("large", () => {
+        it("should render Cells with largeCols and cols", () => {
+            // Arrange
+
+            // Act
+            const wrapper = mount(
+                <div>
+                    <MediaLayoutContext.Provider
+                        value={{
+                            overrideSize: undefined,
+                            ssrSize: "large",
+                            mediaSpec: MEDIA_DEFAULT_SPEC,
+                        }}
+                    >
+                        <Row>
+                            <Cell cols={1}>cols</Cell>
+                            <Cell largeCols={1}>largeCols</Cell>
+                            <Cell mediumCols={1}>mediumCols</Cell>
+                            <Cell smallCols={1}>smallCols</Cell>
+                        </Row>
+                    </MediaLayoutContext.Provider>
+                </div>,
+            );
+            const text = wrapper.text();
+
+            // Assert
+            expect(text).toEqual("colslargeCols");
+        });
+
+        it("should throw if there are too many columns", async () => {
+            // Arrange
+            const render = () => {
+                mount(
+                    <div>
+                        <MediaLayoutContext.Provider
+                            value={{
+                                overrideSize: undefined,
+                                ssrSize: "large",
+                                mediaSpec: MEDIA_DEFAULT_SPEC,
+                            }}
+                        >
+                            <Row>
+                                <Cell cols={13}>cols</Cell>
+                            </Row>
+                        </MediaLayoutContext.Provider>
+                    </div>,
+                );
+            };
+
+            // Act, Assert
+            expect(render).toThrow();
+        });
+    });
+
+    describe("medium", () => {
+        it("should render Cells with largeCols and cols", async () => {
+            // Arrange
+
+            // Act
+            const wrapper = mount(
+                <div>
+                    <MediaLayoutContext.Provider
+                        value={{
+                            overrideSize: undefined,
+                            ssrSize: "medium",
+                            mediaSpec: MEDIA_DEFAULT_SPEC,
+                        }}
+                    >
+                        <Row>
+                            <Cell cols={1}>cols</Cell>
+                            <Cell largeCols={1}>largeCols</Cell>
+                            <Cell mediumCols={1}>mediumCols</Cell>
+                            <Cell smallCols={1}>smallCols</Cell>
+                        </Row>
+                    </MediaLayoutContext.Provider>
+                </div>,
+            );
+            const text = wrapper.text();
+
+            // Assert
+            expect(text).toEqual("colsmediumCols");
+        });
+
+        it("should throw if there are too many columns", () => {
+            // Arrange
+            const render = () => {
+                mount(
+                    <div>
+                        <MediaLayoutContext.Provider
+                            value={{
+                                overrideSize: undefined,
+                                ssrSize: "medium",
+                                mediaSpec: MEDIA_DEFAULT_SPEC,
+                            }}
+                        >
+                            <Row>
+                                <Cell cols={9}>cols</Cell>
+                            </Row>
+                        </MediaLayoutContext.Provider>
+                    </div>,
+                );
+            };
+
+            // Act, Assert
+            expect(render).toThrow();
+        });
+    });
+
+    describe("small", () => {
+        it("should render Cells with largeCols and cols", () => {
+            // Arrange
+
+            // Act
+            const wrapper = mount(
+                <div>
+                    <MediaLayoutContext.Provider
+                        value={{
+                            overrideSize: undefined,
+                            ssrSize: "small",
+                            mediaSpec: MEDIA_DEFAULT_SPEC,
+                        }}
+                    >
+                        <Row>
+                            <Cell cols={1}>cols</Cell>
+                            <Cell largeCols={1}>largeCols</Cell>
+                            <Cell mediumCols={1}>mediumCols</Cell>
+                            <Cell smallCols={1}>smallCols</Cell>
+                        </Row>
+                    </MediaLayoutContext.Provider>
+                </div>,
+            );
+            const text = wrapper.text();
+
+            // Assert
+            expect(text).toEqual("colssmallCols");
+        });
+
+        it("should throw if there are too many columns", () => {
+            // Arrange
+            const render = () => {
+                mount(
+                    <div>
+                        <MediaLayoutContext.Provider
+                            value={{
+                                overrideSize: undefined,
+                                ssrSize: "small",
+                                mediaSpec: MEDIA_DEFAULT_SPEC,
+                            }}
+                        >
+                            <Row>
+                                <Cell cols={5}>cols</Cell>
+                            </Row>
+                        </MediaLayoutContext.Provider>
+                    </div>,
+                );
+            };
+
+            // Act, Assert
+            expect(render).toThrow();
+        });
+    });
+});

package/src/components/cell.js

@@ -0,0 +1,186 @@
+// @flow
+import * as React from "react";
+
+import {MediaLayout} from "@khanacademy/wonder-blocks-layout";
+import {View} from "@khanacademy/wonder-blocks-core";
+import type {MediaSize} from "@khanacademy/wonder-blocks-layout";
+import type {StyleType} from "@khanacademy/wonder-blocks-core";
+
+import styles from "../util/styles.js";
+import {flexBasis} from "../util/utils.js";
+
+type Props = {|
+    /** The number of columns this cell should span on a Small Grid. */
+    smallCols: number,
+
+    /** The number of columns this cell should span on a Medium Grid. */
+    mediumCols: number,
+
+    /** The number of columns this cell should span on a Large Grid. */
+    largeCols: number,
+
+    /** The number of columns this should should span by default. */
+    cols: number | ((mediaSize: MediaSize) => number),
+
+    /**
+     * The child components to populate inside the cell. Can also accept a
+     * function which receives the `mediaSize`, `totalColumns`, and cell
+     * `width` and should return some React Nodes to render.
+     */
+    children:
+        | React.Node
+        | (({|
+              mediaSize: MediaSize,
+              totalColumns: number,
+              cols: number,
+          |}) => React.Node),
+
+    /** The styling to apply to the cell. */
+    style?: StyleType,
+|};
+
+type DefaultProps = {|
+    smallCols: $PropertyType<Props, "smallCols">,
+    mediumCols: $PropertyType<Props, "mediumCols">,
+    largeCols: $PropertyType<Props, "largeCols">,
+    cols: $PropertyType<Props, "cols">,
+|};
+
+/**
+ * A Cell is a container whose width is set based on the width of the
+ * specified columns at the current grid size. You will specify the number
+ * of columns that you want this component to span at each grid size.
+ * This component should only be used as a child of a [Row](#row).
+ *
+ * This component renders a [View](#view) that
+ * uses Flex Box and has a [flex-basis](https://developer.mozilla.org/en-US/docs/Web/CSS/flex-basis)
+ * of the specified "width" and [flex-shrink](https://developer.mozilla.org/en-US/docs/Web/CSS/flex-shrink)
+ * of 0.
+ *
+ * By default (with no properties specified) it will display at all
+ * grid sizes. If you specify the `smallCols`, `mediumCols`, `largeCols`, or
+ * `cols` props then the component will only be shown at those grid sizes and
+ * using the specified column width.
+ */
+export default class Cell extends React.Component<Props> {
+    static isClassOf(instance: React.Element<any>): boolean {
+        return instance && instance.type && instance.type.__IS_CELL__;
+    }
+
+    static getCols(props: Props, mediaSize: MediaSize): ?number {
+        // If no option was specified then we just return undefined,
+        // components may handle this case differently.
+        // We go through all the ways in which a fixed width can be
+        // specified and find the one that matches our current grid size.
+        if (
+            !props.smallCols &&
+            !props.mediumCols &&
+            !props.largeCols &&
+            !props.cols
+        ) {
+            return undefined;
+        } else if (props.smallCols && mediaSize === "small") {
+            return props.smallCols;
+        } else if (props.mediumCols && mediaSize === "medium") {
+            return props.mediumCols;
+        } else if (props.largeCols && mediaSize === "large") {
+            return props.largeCols;
+        } else if (typeof props.cols === "function") {
+            return props.cols(mediaSize);
+        } else if (props.cols) {
+            return props.cols;
+        }
+
+        // If nothing applies then we return null (usually resulting
+        // in the component not being rendered)
+        return null;
+    }
+
+    // HACK(kevinb): we use a stack method here because we can't get a ref to
+    // each cell in a row without cloning them all.
+    static shouldDisplay(props: Props, mediaSize: MediaSize): boolean {
+        const cols = Cell.getCols(props, mediaSize);
+        return cols !== null && cols !== 0;
+    }
+
+    static defaultProps: DefaultProps = {
+        smallCols: 0,
+        mediumCols: 0,
+        largeCols: 0,
+        cols: 0,
+    };
+
+    static __IS_CELL__: boolean = true;
+
+    render(): React.Node {
+        const {children, style} = this.props;
+
+        return (
+            <MediaLayout>
+                {({mediaSize, mediaSpec}) => {
+                    const spec = mediaSpec[mediaSize];
+                    if (!spec) {
+                        throw new Error(`mediaSpec.${mediaSize} is undefined`);
+                    }
+
+                    // Get the settings for this particular size of grid
+                    const {totalColumns, gutterWidth, marginWidth} = spec;
+
+                    const cols = Cell.getCols(this.props, mediaSize);
+
+                    // If no columns are specified then we just don't render this cell
+                    if (cols === undefined || cols === null || cols === 0) {
+                        return null;
+                    }
+
+                    if (cols > totalColumns) {
+                        throw new Error(
+                            `Specified columns ${cols} is greater than the maximum ` +
+                                `${totalColumns} at the ${mediaSize} grid size.`,
+                        );
+                    }
+
+                    // We need to start by calculating the total width of all the "content"
+                    // We do this by starting with the full width (100%) and then
+                    // subtracting all of the gutter spaces inbetween the cells
+                    // (gutterWidth * (totalColumns - 1)) and the width of the two margins
+                    // (marginWidth * 2).
+                    const contentWidth = `(100% - ${
+                        gutterWidth * (totalColumns - 1)
+                    }px - ${marginWidth * 2}px)`;
+
+                    // Now that we have the full width we can calculate the width of this
+                    // particular cell by multiplying the full width (allCellWidth) by
+                    // the ratio of this cell (cols / totalColumns). But we then need to
+                    // add back in the missing gutter widths:
+                    // (gutterWidth * (cols - 1)). This gives us to full width of
+                    // this particular cell.
+                    const calcWidth = `calc(${contentWidth} * ${
+                        cols / totalColumns
+                    } + ${gutterWidth * (cols - 1)}px)`;
+
+                    // If the contents are a function then we call it with the mediaSize,
+                    // totalColumns, and cols properties and render the return value.
+                    const contents =
+                        typeof children === "function"
+                            ? children({mediaSize, totalColumns, cols})
+                            : children;
+
+                    // Render a fixed-width cell (flex-basis: size, flex-shrink: 0)
+                    // that matches the intended width of the cell
+                    return (
+                        <View
+                            style={[
+                                styles.cellFixed,
+                                flexBasis(calcWidth),
+                                style,
+                            ]}
+                        >
+                            {contents}
+                        </View>
+                    );
+                }}
+            </MediaLayout>
+        );
+    }
+}

package/src/components/cell.md

@@ -0,0 +1,58 @@
+**Example:**
+
+A row inside of a grid containing many Cells. Each cell has a column width of 1 and will display at different sizes of the viewport (always matching the number of available columns).
+
+```jsx
+import {Row} from "@khanacademy/wonder-blocks-grid";
+import Color from "@khanacademy/wonder-blocks-color";
+import {View, Text} from "@khanacademy/wonder-blocks-core";
+import {MediaLayout} from "@khanacademy/wonder-blocks-layout";
+import {StyleSheet} from "aphrodite";
+
+const styleSheets = {
+    all: StyleSheet.create({
+        background: {
+            background: Color.offBlack,
+        },
+
+        cell: {
+            height: 100,
+            padding: "5px 0",
+        },
+    }),
+    small: StyleSheet.create({
+        cell: {
+            background: Color.blue,
+        },
+    }),
+    medium: StyleSheet.create({
+        cell: {
+            background: Color.green,
+        },
+    }),
+    large: StyleSheet.create({
+        cell: {
+            background: Color.gold,
+        },
+    }),
+};
+
+<MediaLayout styleSheets={styleSheets}>
+    {({styles}) => <View style={styles.background}>
+        <Row>
+            <Cell cols={1} style={styles.cell}>1</Cell>
+            <Cell cols={1} style={styles.cell}>1</Cell>
+            <Cell cols={1} style={styles.cell}>1</Cell>
+            <Cell cols={1} style={styles.cell}>1</Cell>
+            <Cell mediumCols={1} largeCols={1} style={styles.cell}>1</Cell>
+            <Cell mediumCols={1} largeCols={1} style={styles.cell}>1</Cell>
+            <Cell mediumCols={1} largeCols={1} style={styles.cell}>1</Cell>
+            <Cell mediumCols={1} largeCols={1} style={styles.cell}>1</Cell>
+            <Cell largeCols={1} style={styles.cell}>1</Cell>
+            <Cell largeCols={1} style={styles.cell}>1</Cell>
+            <Cell largeCols={1} style={styles.cell}>1</Cell>
+            <Cell largeCols={1} style={styles.cell}>1</Cell>
+        </Row>
+    </View>}
+</MediaLayout>;
+```

package/src/components/gutter.js

@@ -0,0 +1,59 @@
+// @flow
+import * as React from "react";
+import {
+    MediaLayout,
+    Strut,
+    queryMatchesSize,
+} from "@khanacademy/wonder-blocks-layout";
+import type {MediaQuery} from "@khanacademy/wonder-blocks-layout";
+
+type Props = {|
+    /**
+     * Which media should this cell be renderer on.  Defaults to all.
+     */
+    mediaQuery: MediaQuery,
+|};
+
+type DefaultProps = {|
+    mediaQuery: $PropertyType<Props, "mediaQuery">,
+|};
+
+/**
+ * Gutter is a component whose width is set based on the size of grid currently
+ * being displayed. Used for spacing out cells from each other. The gutter
+ * itself doesn't hold any content, it just spaces it out.
+ *
+ * Gutters are inserted automatically inside of a [Row](#row) in-between Cells.
+ * You may only need to use Gutters if you're manually building your own
+ * sub-grid, or some-such (this should be relatively rare).
+ *
+ * By default (with no properties specified) it will display at all
+ * grid sizes. If you specify the `small`, `medium`, or `large`
+ * props then the component will only be shown at those grid sizes.
+ */
+export default class Gutter extends React.Component<Props> {
+    static defaultProps: DefaultProps = {
+        mediaQuery: "all",
+    };
+
+    render(): React.Node {
+        return (
+            <MediaLayout>
+                {({mediaSize, mediaSpec}) => {
+                    const spec = mediaSpec[mediaSize];
+                    if (!spec) {
+                        throw new Error(`mediaSpec.${mediaSize} is undefined`);
+                    }
+
+                    const {gutterWidth} = spec;
+
+                    if (!queryMatchesSize(this.props.mediaQuery, mediaSize)) {
+                        return null;
+                    }
+
+                    return <Strut size={gutterWidth} />;
+                }}
+            </MediaLayout>
+        );
+    }
+}

package/src/components/row.js

@@ -0,0 +1,141 @@
+// @flow
+import * as React from "react";
+import {View} from "@khanacademy/wonder-blocks-core";
+import {
+    MediaLayout,
+    Strut,
+    queryMatchesSize,
+} from "@khanacademy/wonder-blocks-layout";
+import type {StyleType} from "@khanacademy/wonder-blocks-core";
+import type {MediaQuery, MediaSize} from "@khanacademy/wonder-blocks-layout";
+
+import styles from "../util/styles.js";
+import Gutter from "./gutter.js";
+import Cell from "./cell.js";
+
+type Props = {|
+    /**
+     * Which media should this cell be renderer on.  Defaults to all.
+     */
+    mediaQuery: MediaQuery,
+
+    /**
+     * The child components to populate inside the row. Typically this will be
+     * a [Cell](#cell), but it can also include any elements
+     * that could fit in a [flexbox](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Flexible_Box_Layout/Basic_Concepts_of_Flexbox).
+     * Can also accept a function which receives the `mediaSize` and
+     * `totalColumns` and should return some React Nodes to render.
+     */
+    children:
+        | React.Node
+        | (({|
+              mediaSize: MediaSize,
+              totalColumns: number,
+          |}) => React.Node),
+
+    /** The styling to apply to the row. */
+    style?: StyleType,
+|};
+
+type DefaultProps = {|
+    mediaQuery: $PropertyType<Props, "mediaQuery">,
+|};
+
+/**
+ * A Row holds all of the Cells that make up the contents of the grid. A row
+ * also provides the margins on the sides and inserts the gutter spacing
+ * in-between the cells. Typically this component will hold a [Cell](#cell),
+ * but it can also include any elements that could fit in a
+ * [flexbox](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Flexible_Box_Layout/Basic_Concepts_of_Flexbox).
+ *
+ * This component will automatically attempt to insert [Gutters](#gutter)
+ * in-between all child elements. Additionally, it'll perform some basic checks
+ * to ensure that no impossible layouts are accidentally generated.
+ *
+ * Typically this component will be used as a child of a [Grid](#grid-1),
+ * but it's not a requirement, you can use it as a descendant, as well.
+ *
+ * By default (with no properties specified) it will display at all
+ * grid sizes. If you specify the `small`, `medium`, or `large`
+ * props then the component will only be shown at those grid sizes.
+ */
+export default class Row extends React.Component<Props> {
+    static defaultProps: DefaultProps = {
+        mediaQuery: "all",
+    };
+
+    render(): React.Node {
+        const {style, children} = this.props;
+
+        return (
+            <MediaLayout>
+                {({mediaSize, mediaSpec}) => {
+                    const spec = mediaSpec[mediaSize];
+                    if (!spec) {
+                        throw new Error(`mediaSpec.${mediaSize} is undefined`);
+                    }
+
+                    const {marginWidth, maxWidth, totalColumns} = spec;
+                    const shouldDisplay = queryMatchesSize(
+                        this.props.mediaQuery,
+                        mediaSize,
+                    );
+
+                    // Don't render the row if it's been disabled at this size
+                    if (!shouldDisplay) {
+                        return null;
+                    }
+
+                    // If the contents are a function then we call it with the mediaSize and
+                    // totalColumns properties and render the return value.
+                    const contents =
+                        typeof children === "function"
+                            ? children({mediaSize, totalColumns})
+                            : children;
+
+                    const filteredContents: Array<React.Node> = (React.Children.toArray(
+                        contents,
+                    ): Array<React.Node>)
+                        // Go through all of the contents and pre-emptively remove anything
+                        // that shouldn't be rendered.
+                        .filter(
+                            // Flow doesn't let us check .type on a non-null React.Node so
+                            // we have to cast it to any.
+                            (item: any) =>
+                                Cell.isClassOf(item)
+                                    ? Cell.shouldDisplay(item.props, mediaSize)
+                                    : true,
+                        )
+                        // Intersperse Gutter elements between the cells.
+                        .reduce(
+                            (acc, elem, index) => [
+                                ...acc,
+                                elem,
+                                <Gutter key={`gutter-${index}`} />,
+                            ],
+                            [],
+                        )
+                        // We only want gutters between each cell in the row.  The reduce
+                        // adds a gutter after every cell so we need to remove the last
+                        // element which is an unnecessary gutteer.
+                        .slice(0, -1);
+
+                    return (
+                        <View
+                            style={[
+                                styles.row,
+                                !!maxWidth && styles.rowMaxWidth,
+                                !!maxWidth && {maxWidth},
+                                style,
+                            ]}
+                        >
+                            <Strut size={marginWidth} />
+                            {filteredContents}
+                            <Strut size={marginWidth} />
+                        </View>
+                    );
+                }}
+            </MediaLayout>
+        );
+    }
+}