feat(subheading): add subheading component (#828)

Mark Jones · web-flow · commit b988adedb36c · 2018-08-31T14:55:14.000-07:00
* feat(subheading) create subheading
* based on Typography component
* defaults to type level 3
* subheading level 1-6 maps to type level 3-8
* applied italics to component names in readme
diff --git a/packages/fast-components-class-name-contracts-msft/src/index.ts b/packages/fast-components-class-name-contracts-msft/src/index.ts
@@ -3,3 +3,4 @@ export * from "./flipper";
 export * from "./heading";
 export * from "./managed-classes";
 export * from "./paragraph";
+export * from "./subheading";
diff --git a/packages/fast-components-class-name-contracts-msft/src/subheading/index.ts b/packages/fast-components-class-name-contracts-msft/src/subheading/index.ts
@@ -0,0 +1,12 @@
+/**
+ * The class name contract for the subheading component
+ */
+export interface ISubheadingClassNameContract {
+    subheading: string;
+    subheading_1: string;
+    subheading_2: string;
+    subheading_3: string;
+    subheading_4: string;
+    subheading_5: string;
+    subheading_6: string;
+}
diff --git a/packages/fast-components-react-msft/app/examples.ts b/packages/fast-components-react-msft/app/examples.ts
@@ -28,6 +28,9 @@ export { LabelExamples };
 import ParagraphExamples from "../src/paragraph/examples.data";
 export { ParagraphExamples };
 
+import SubheadingExamples from "../src/subheading/examples.data";
+export { SubheadingExamples };
+
 import ToggleExamples from "../src/toggle/examples.data";
 export { ToggleExamples };
 
diff --git a/packages/fast-components-react-msft/src/index.ts b/packages/fast-components-react-msft/src/index.ts
@@ -23,6 +23,9 @@ export { Image } ;
 import Label from "./label";
 export { Label } ;
 
+import Subheading from "./subheading";
+export { Subheading };
+
 import TextField from "./text-field";
 export { TextField };
 
diff --git a/packages/fast-components-react-msft/src/subheading/README.md b/packages/fast-components-react-msft/src/subheading/README.md
@@ -0,0 +1,8 @@
+# Subheading
+Use various *subheading* sizes to create a clear hierarchy within your page. Subheadings are paired with the Heading component.
+
+## Usage
+Use the appropriate numbered tag for the relative importance of each *subheading* compared to other *subheadings* on the page. Subheadings should be descriptive summaries of the content below them. Choose a *subheading* level that best organizes your page content. Then choose the *subheading* tag and level to meet your design needs. For example, an `<h2>` element does not absolutely require level 2, it could be any of the other levels as well.
+
+## Style guide
+Subheadings are a great way to break up your writing. They improve the layout of a page and draw attention to important points.
diff --git a/packages/fast-components-react-msft/src/subheading/__snapshots__/subheading.spec.tsx.snap b/packages/fast-components-react-msft/src/subheading/__snapshots__/subheading.spec.tsx.snap
@@ -0,0 +1,72 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`generate snapshots Subheading: 0 1`] = `
+<h3
+  className="typography_3-0-1-31 subheading-0-1-22 subheading_1-0-1-23"
+>
+  Subheading test string
+</h3>
+`;
+
+exports[`generate snapshots Subheading: 1 1`] = `
+<h1
+  className="typography_3-0-1-47 subheading-0-1-38 subheading_1-0-1-39"
+  data-sketch-symbol="Subheading 1"
+>
+  Subheading test string
+</h1>
+`;
+
+exports[`generate snapshots Subheading: 2 1`] = `
+<h1
+  className="typography_3-0-1-63 subheading-0-1-54 subheading_1-0-1-55"
+  data-sketch-symbol="Subheading 1"
+>
+  Subheading test string
+</h1>
+`;
+
+exports[`generate snapshots Subheading: 3 1`] = `
+<h2
+  className="typography_4-0-1-80 subheading-0-1-70 subheading_2-0-1-72"
+  data-sketch-symbol="Subheading 2"
+>
+  Subheading test string
+</h2>
+`;
+
+exports[`generate snapshots Subheading: 4 1`] = `
+<h3
+  className="typography_5-0-1-97 subheading-0-1-86 subheading_3-0-1-89"
+  data-sketch-symbol="Subheading 3"
+>
+  Subheading test string
+</h3>
+`;
+
+exports[`generate snapshots Subheading: 5 1`] = `
+<h4
+  className="typography_6-0-1-114 subheading-0-1-102 subheading_4-0-1-106"
+  data-sketch-symbol="Subheading 4"
+>
+  Subheading test string
+</h4>
+`;
+
+exports[`generate snapshots Subheading: 6 1`] = `
+<h5
+  className="typography_7-0-1-131 subheading-0-1-118 subheading_5-0-1-123"
+  data-sketch-symbol="Subheading 5"
+>
+  Subheading test string
+</h5>
+`;
+
+exports[`generate snapshots Subheading: 7 1`] = `
+<h6
+  className="typography_8-0-1-148 subheading-0-1-134 subheading_6-0-1-140"
+  data-sketch-symbol="Subheading 6"
+>
+  Subheading test string
+</h6>
+`;
diff --git a/packages/fast-components-react-msft/src/subheading/examples.data.tsx b/packages/fast-components-react-msft/src/subheading/examples.data.tsx
@@ -0,0 +1,69 @@
+import * as React from "react";
+import { IComponentFactoryExample  } from "@microsoft/fast-development-site-react";
+import Subheading from "./index";
+import {
+    ISubheadingHandledProps,
+    ISubheadingUnhandledProps,
+    SubheadingLevel,
+    SubheadingTag
+} from "./subheading.props";
+import Schema from "./subheading.schema.json";
+import Documentation from "./.tmp/documentation";
+
+const testString: string = "Subheading test string";
+
+export default {
+    name: "Subheading",
+    component: Subheading,
+    schema: Schema as any,
+    documentation: <Documentation />,
+    detailData: {
+        children: "Subheading"
+    },
+    data: [
+        {
+            children: testString
+        },
+        {
+            tag: SubheadingTag.h1,
+            children: testString,
+            "data-sketch-symbol": "Subheading 1"
+        },
+        {
+            tag: SubheadingTag.h1,
+            level: SubheadingLevel._1,
+            children: testString,
+            "data-sketch-symbol": "Subheading 1"
+        },
+        {
+            tag: SubheadingTag.h2,
+            level: SubheadingLevel._2,
+            children: testString,
+            "data-sketch-symbol" : "Subheading 2"
+        },
+        {
+            tag: SubheadingTag.h3,
+            level: SubheadingLevel._3,
+            children: testString,
+            "data-sketch-symbol": "Subheading 3"
+        },
+        {
+            tag: SubheadingTag.h4,
+            level: SubheadingLevel._4,
+            children: testString,
+            "data-sketch-symbol": "Subheading 4"
+        },
+        {
+            tag: SubheadingTag.h5,
+            level: SubheadingLevel._5,
+            children: testString,
+            "data-sketch-symbol": "Subheading 5"
+        },
+        {
+            tag: SubheadingTag.h6,
+            level: SubheadingLevel._6,
+            children: testString,
+            "data-sketch-symbol": "Subheading 6"
+        }
+    ]
+} as IComponentFactoryExample<ISubheadingHandledProps>;
diff --git a/packages/fast-components-react-msft/src/subheading/index.ts b/packages/fast-components-react-msft/src/subheading/index.ts
@@ -0,0 +1,13 @@
+import * as React from "react";
+import { IFoundationProps } from "@microsoft/fast-components-react-base";
+import Subheading, {
+    ISubheadingHandledProps,
+    ISubheadingUnhandledProps,
+    SubheadingLevel,
+    SubheadingTag
+} from "./subheading";
+import manageJss, { IJSSManagerProps } from "@microsoft/fast-jss-manager-react";
+import { IDesignSystem, SubheadingStyles } from "@microsoft/fast-components-styles-msft";
+
+export default manageJss(SubheadingStyles)(Subheading);
+export * from "./subheading";
diff --git a/packages/fast-components-react-msft/src/subheading/subheading.props.ts b/packages/fast-components-react-msft/src/subheading/subheading.props.ts
@@ -0,0 +1,43 @@
+import * as React from "react";
+import { IManagedClasses, ISubheadingClassNameContract  } from "@microsoft/fast-components-class-name-contracts-msft";
+
+export enum SubheadingLevel {
+    _1 = 1,
+    _2 = 2,
+    _3 = 3,
+    _4 = 4,
+    _5 = 5,
+    _6 = 6
+}
+
+export enum SubheadingTag {
+    h1 = "h1",
+    h2 = "h2",
+    h3 = "h3",
+    h4 = "h4",
+    h5 = "h5",
+    h6 = "h6",
+    p = "p"
+}
+
+export interface ISubheadingHandledProps {
+
+    /**
+     * The subheading content
+     */
+    children?: React.ReactNode | React.ReactNode[];
+
+    /**
+     * The subheading level used to map to typographic level
+     */
+    level?: SubheadingLevel;
+
+    /**
+     * The subheading tag used to create the underlying html element
+     */
+    tag?: SubheadingTag;
+}
+
+export interface ISubheadingUnhandledProps extends React.HTMLAttributes<HTMLHeadingElement | HTMLParagraphElement> {}
+export interface ISubheadingManagedClasses extends IManagedClasses<ISubheadingClassNameContract> {}
+export type SubheadingProps = ISubheadingHandledProps & ISubheadingUnhandledProps & ISubheadingManagedClasses;
diff --git a/packages/fast-components-react-msft/src/subheading/subheading.schema.json b/packages/fast-components-react-msft/src/subheading/subheading.schema.json
@@ -0,0 +1,37 @@
+{
+    "$schema": "http://json.schema.org/schema#",
+    "title": "Subheading",
+    "description": "A Subheading component's schema definition",
+    "type": "object",
+    "id": "Subheading",
+    "children": true,
+    "properties": {
+        "tag": {
+            "title": "HTML Tag",
+            "type": "string",
+            "enum": [
+                "h1",
+                "h2",
+                "h3",
+                "h4",
+                "h5",
+                "h6",
+                "p"                
+            ],
+            "default": "h3" 
+        },
+        "level": {
+            "title": "Level",
+            "type": "number",
+            "enum": [
+                1,
+                2,
+                3,
+                4,
+                5,
+                6
+            ],
+            "default": 1
+        }
+    }
+}
diff --git a/packages/fast-components-react-msft/src/subheading/subheading.spec.tsx b/packages/fast-components-react-msft/src/subheading/subheading.spec.tsx
@@ -0,0 +1,67 @@
+import * as React from "react";
+import * as Adapter from "enzyme-adapter-react-16";
+import { configure, shallow } from "enzyme";
+import examples from "./examples.data";
+import { generateSnapshots } from "@microsoft/fast-jest-snapshots-react";
+import {
+    ISubheadingHandledProps,
+    ISubheadingManagedClasses,
+    ISubheadingUnhandledProps,
+    SubheadingLevel,
+    SubheadingTag,
+ } from "./subheading";
+
+ /**
+  * Configure enzyme
+  */
+configure({adapter: new Adapter()});
+
+describe("generate snapshots", (): void => {
+    generateSnapshots(examples);
+}
+
+describe("subheading", (): void => {
+
+    const Component: React.ComponentClass<ISubheadingHandledProps> = examples.component;
+
+    test("should return a valid object which includes all props that are not enumerated as handledProps", (): void => {
+        const handledProps: ISubheadingHandledProps = {
+            tag: SubheadingTag.h1,
+            level: SubheadingLevel._1
+        };
+
+        const unhandledProps: ISubheadingUnhandledProps = {
+            "aria-hidden": true
+        };
+
+        const props: ISubheadingHandledProps & ISubheadingUnhandledProps = {...handledProps, ...unhandledProps};
+
+        const rendered: any = shallow(
+            <Component {...props} />
+        );
+
+        const subheading: any = rendered.first().shallow();
+
+        expect(subheading.prop("aria-hidden")).toEqual(true);
+    });
+
+    test("should render the correct `tag` when `tag` prop is passed in", (): void => {
+        const rendered: any = shallow(
+            <Component tag={SubheadingTag.h4} />
+        );
+
+        const subheading: any = rendered.first().shallow();
+
+        expect(subheading.instance().props.tag).toEqual(SubheadingTag.h4);
+    });
+
+    test("should render default level if none is specified", (): void => {
+        const rendered: any = shallow(
+            <Component />
+        );
+
+        const subheading: any = rendered.first().shallow();
+
+        expect(subheading.instance().props.level).toEqual(SubheadingLevel._1);
+    });
+});
diff --git a/packages/fast-components-react-msft/src/subheading/subheading.tsx b/packages/fast-components-react-msft/src/subheading/subheading.tsx
diff --git a/packages/fast-components-styles-msft/src/index.ts b/packages/fast-components-styles-msft/src/index.ts
diff --git a/packages/fast-components-styles-msft/src/subheading/index.ts b/packages/fast-components-styles-msft/src/subheading/index.ts
