feat(Header): addressing accessibility concerns and replacing subheader with description

CHANGELOG.md

@@ -20,6 +20,9 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 ### Documentation
 - Improve UX for "knobs" form on component examples @levithomason ([#20](https://github.com/stardust-ui/react/pull/20))
 
+### Fixes
+- Replaced Header `subheader` with `description` and fixed it to render well-formed HTML @mnajdova ([#17](https://github.com/stardust-ui/react/pull/17))
+
 <!--------------------------------[ v0.2.3 ]------------------------------- -->
 ## [v0.2.3](https://github.com/stardust-ui/react/tree/v0.2.3) (2018-07-24)
 [Compare changes](https://github.com/stardust-ui/react/compare/v0.2.2...v0.2.3)

docs/src/examples/components/Header/Types/HeaderExample.shorthand.tsx

@@ -0,0 +1,15 @@
+import React from 'react'
+import { Header } from '@stardust-ui/react'
+
+const HeadersExampleShorthand = () => (
+  <div>
+    <Header as="h1" content="First Header" />
+    <Header as="h2" content="Second Header" />
+    <Header as="h3" content="Third Header" />
+    <Header as="h4" content="Fourth Header" />
+    <Header as="h5" content="Fifth Header" />
+    <Header as="h6" content="Sixth Header" />
+  </div>
+)
+
+export default HeadersExampleShorthand

docs/src/examples/components/Header/Types/PageHeadersExample.tsx → docs/src/examples/components/Header/Types/HeaderExample.tsx

@@ -1,7 +1,7 @@
 import React from 'react'
 import { Header } from '@stardust-ui/react'
 
-const PageHeadersExample = () => (
+const HeaderExample = () => (
   <div>
     <Header as="h1">First Header</Header>
     <Header as="h2">Second Header</Header>
@@ -12,4 +12,4 @@ const PageHeadersExample = () => (
   </div>
 )
 
-export default PageHeadersExample
+export default HeaderExample

docs/src/examples/components/Header/Types/index.tsx

@@ -5,19 +5,9 @@ import ExampleSection from 'docs/src/components/ComponentDoc/ExampleSection'
 const Types = () => (
   <ExampleSection title="Types">
     <ComponentExample
-      title="Page Headers"
-      description="Headers may be oriented to give the hierarchy of a section in the context of the page."
-      examplePath="components/Header/Types/PageHeadersExample"
-    />
-    <ComponentExample
-      title="Subheader"
-      description="Headers may contain subheaders."
-      examplePath="components/Header/Types/SubheaderExample"
-    />
-    <ComponentExample
-      title="Subheader as prop"
-      description="You can pass any Subheader content to the Header subheader prop."
-      examplePath="components/Header/Types/HeaderExampleSubheaderProp"
+      title="Header example"
+      description="Basic usage of the Header component with different h1 tags"
+      examplePath="components/Header/Types/HeaderExample"
     />
   </ExampleSection>
 )

docs/src/examples/components/Header/Variations/HeaderExampleDescription.shorthand.tsx

@@ -0,0 +1,12 @@
+import React from 'react'
+import { Header } from '@stardust-ui/react'
+
+const HeaderExampleDescriptionShorthand = () => (
+  <Header
+    as="h2"
+    content="Account Settings"
+    description="Manage your account settings and set email preferences"
+  />
+)
+
+export default HeaderExampleDescriptionShorthand

docs/src/examples/components/Header/Variations/HeaderExampleDescription.tsx

@@ -0,0 +1,11 @@
+import React from 'react'
+import { Header } from '@stardust-ui/react'
+
+const HeaderExampleDescription = () => (
+  <Header as="h2">
+    Account Settings
+    <Header.Description>Manage your account settings and set email preferences</Header.Description>
+  </Header>
+)
+
+export default HeaderExampleDescription

docs/src/examples/components/Header/Variations/HeaderExampleDescriptionCustomization.shorthand.tsx

@@ -0,0 +1,12 @@
+import React from 'react'
+import { Header } from '@stardust-ui/react'
+
+const HeaderExampleDescriptionCustomizationShorthand = () => (
+  <Header
+    as="h2"
+    content="Account Settings"
+    description={{ content: 'Manage your account settings and set email preferences', as: 'span' }}
+  />
+)
+
+export default HeaderExampleDescriptionCustomizationShorthand

docs/src/examples/components/Header/Types/SubheaderExample.tsx → docs/src/examples/components/Header/Variations/HeaderExampleDescriptionCustomization.tsx

@@ -4,7 +4,9 @@ import { Header } from '@stardust-ui/react'
 const HeaderExampleSubheader = () => (
   <Header as="h2">
     Account Settings
-    <Header.Subheader>Manage your account settings and set email preferences</Header.Subheader>
+    <Header.Description as="span">
+      Manage your account settings and set email preferences
+    </Header.Description>
   </Header>
 )
 

docs/src/examples/components/Header/Variations/HeaderExampleTextAlign.shorthand.tsx

@@ -0,0 +1,10 @@
+import React from 'react'
+import { Header } from '@stardust-ui/react'
+
+const HeaderExampleTextAlign = () => (
+  <div>
+    <Header as="h1" textAlign="right" content="Right aligned Header" />
+  </div>
+)
+
+export default HeaderExampleTextAlign

docs/src/examples/components/Header/Variations/HeaderExampleTextAlign.tsx

@@ -0,0 +1,12 @@
+import React from 'react'
+import { Header } from '@stardust-ui/react'
+
+const HeaderExampleTextAlign = () => (
+  <div>
+    <Header as="h1" textAlign="right">
+      Right aligned Header
+    </Header>
+  </div>
+)
+
+export default HeaderExampleTextAlign

docs/src/examples/components/Header/Variations/index.tsx

@@ -0,0 +1,25 @@
+import React from 'react'
+import ComponentExample from 'docs/src/components/ComponentDoc/ComponentExample'
+import ExampleSection from 'docs/src/components/ComponentDoc/ExampleSection'
+
+const Variations = () => (
+  <ExampleSection title="Variations">
+    <ComponentExample
+      title="Description"
+      description="Headers may contain description."
+      examplePath="components/Header/Variations/HeaderExampleDescription"
+    />
+    <ComponentExample
+      title="Description customizations"
+      description="Descriptions can be customize according to the needs of the user."
+      examplePath="components/Header/Variations/HeaderExampleDescriptionCustomization"
+    />
+    <ComponentExample
+      title="TextAlign"
+      description="Headers may be aligned to the left, right, center or be justified."
+      examplePath="components/Header/Variations/HeaderExampleTextAlign"
+    />
+  </ExampleSection>
+)
+
+export default Variations

docs/src/examples/components/Header/index.tsx

@@ -1,9 +1,11 @@
 import React from 'react'
 import Types from './Types'
+import Variations from './Variations'
 
 const HeaderExamples = () => (
   <div>
     <Types />
+    <Variations />
   </div>
 )
 

src/components/Header/Header.tsx

@@ -2,12 +2,15 @@ import PropTypes from 'prop-types'
 import React from 'react'
 
 import { childrenExist, customPropTypes, UIComponent } from '../../lib'
-import HeaderSubheader from './HeaderSubheader'
+import HeaderDescription from './HeaderDescription'
 import headerRules from './headerRules'
 import headerVariables from './headerVariables'
 
 /**
  * A header provides a short summary of content
+ * @accessibility
+ * Headings communicate the organization of the content on the page. Web browsers, plug-ins, and assistive technologies can use them to provide in-page navigation.
+ * Nest headings by their rank (or level). The most important heading has the rank 1 (<h1>), the least important heading rank 6 (<h6>). Headings with an equal or higher rank start a new section, headings with a lower rank start new subsections that are part of the higher ranked section.
  */
 class Header extends UIComponent<any, any> {
   static className = 'ui-header'
@@ -27,23 +30,27 @@ class Header extends UIComponent<any, any> {
     /** Shorthand for primary content. */
     content: customPropTypes.contentShorthand,
 
-    /** Shorthand for Header.Subheader. */
-    subheader: customPropTypes.itemShorthand,
+    /** Shorthand for Header.Description. */
+    description: customPropTypes.itemShorthand,
 
     /** Align header content. */
     textAlign: PropTypes.oneOf(['left', 'center', 'right', 'justified']),
   }
 
-  static handledProps = ['as', 'children', 'className', 'content', 'subheader', 'textAlign']
+  static defaultProps = {
+    as: 'h1',
+  }
+
+  static handledProps = ['as', 'children', 'className', 'content', 'description', 'textAlign']
 
   static rules = headerRules
 
   static variables = headerVariables
 
-  static Subheader = HeaderSubheader
+  static Description = HeaderDescription
 
   renderComponent({ ElementType, classes, rest }) {
-    const { children, content, subheader } = this.props
+    const { children, content, description } = this.props
 
     if (childrenExist(children)) {
       return (
@@ -53,12 +60,12 @@ class Header extends UIComponent<any, any> {
       )
     }
 
-    const subheaderElement = HeaderSubheader.create(subheader, { generateKey: false })
+    const descriptionElement = HeaderDescription.create(description, { generateKey: false })
 
     return (
       <ElementType {...rest} className={classes.root}>
         {content}
-        {subheaderElement}
+        {descriptionElement}
       </ElementType>
     )
   }

src/components/Header/HeaderSubheader.tsx → src/components/Header/HeaderDescription.tsx

@@ -3,17 +3,17 @@ import React from 'react'
 
 import { childrenExist, createShorthandFactory, customPropTypes, UIComponent } from '../../lib'
 
-import headerSubheaderRules from './headerSubheaderRules'
+import headerDescriptionRules from './headerDescriptionRules'
 
 /**
- * Headers may contain subheaders.
+ * Headers may contain description.
  */
-class HeaderSubheader extends UIComponent<any, any> {
+class HeaderDescription extends UIComponent<any, any> {
   static create: Function
 
-  static className = 'ui-header__subheader'
+  static className = 'ui-header__description'
 
-  static displayName = 'HeaderSubheader'
+  static displayName = 'HeaderDescription'
 
   static propTypes = {
     /** An element type to render as (string or function). */
@@ -29,9 +29,13 @@ class HeaderSubheader extends UIComponent<any, any> {
     content: customPropTypes.contentShorthand,
   }
 
+  static defaultProps = {
+    as: 'p',
+  }
+
   static handledProps = ['as', 'children', 'className', 'content']
 
-  static rules = headerSubheaderRules
+  static rules = headerDescriptionRules
 
   renderComponent({ ElementType, classes, rest }) {
     const { children, content } = this.props
@@ -43,6 +47,6 @@ class HeaderSubheader extends UIComponent<any, any> {
   }
 }
 
-HeaderSubheader.create = createShorthandFactory(HeaderSubheader, content => ({ content }))
+HeaderDescription.create = createShorthandFactory(HeaderDescription, content => ({ content }))
 
-export default HeaderSubheader
+export default HeaderDescription

src/components/Header/headerSubheaderRules.ts → src/components/Header/headerDescriptionRules.ts

@@ -2,8 +2,8 @@ import { pxToRem } from '../../lib'
 
 export default {
   root: () => ({
-    fontSize: pxToRem(21.428),
-    lineHeight: pxToRem(22),
+    display: 'block',
+    fontSize: pxToRem(22),
     color: 'rgba(0,0,0,.6)',
     fontWeight: 400,
   }),

src/components/Header/headerRules.ts

@@ -2,5 +2,6 @@ export default {
   root: ({ props }) => ({
     textAlign: props.textAlign,
     display: 'block',
+    ...(props.description && { marginBottom: 0 }),
   }),
 }

src/components/Header/index.ts

@@ -1,2 +1,2 @@
 export { default } from './Header'
-export { default as HeaderSubheader } from './HeaderSubheader'
+export { default as HeaderDescription } from './HeaderDescription'

src/index.ts

@@ -16,5 +16,5 @@ export { default as ProviderConsumer } from './components/Provider/ProviderConsu
 export { default as Icon } from './components/Icon'
 export { default as Text } from './components/Text'
 export { default as Header } from './components/Header'
-export { HeaderSubheader } from './components/Header'
+export { HeaderDescription } from './components/Header'
 export { default as Avatar } from './components/Avatar'

test/specs/components/Header/HeaderDescription-test.ts

@@ -0,0 +1,7 @@
+import { isConformant } from 'test/specs/commonTests'
+
+import { HeaderDescription } from 'src/components/Header'
+
+describe('HeaderDescription', () => {
+  isConformant(HeaderDescription)
+})