Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat!: Remove HeadingLevel type, group Heading sizes in story #1387

Merged
merged 16 commits into from
Jul 19, 2024
Merged
Show file tree
Hide file tree
Changes from 10 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 5 additions & 6 deletions packages/css/src/components/heading/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,15 +2,14 @@

# Heading

A heading conveys information about the content below it.
Use headings to allow the user to grasp the structure of the page quickly.
Communicates the organization of the content on a page.
VincentSmedinga marked this conversation as resolved.
Show resolved Hide resolved

## Guidelines

- A heading describes the content beneath it.
alimpens marked this conversation as resolved.
Show resolved Hide resolved
- Do not use a heading for formatting and styling. Use it to represent the page’s structure.
- Use headings hierarchically, and do not skip heading levels.
So, an `h1` heading should be followed by an `h2`, not an `h3`.
- Every page should contain one Heading with level 1.
- Do not skip heading levels, e.g. a level 2 Heading should be followed by one with level 3, not level 4.
- Do not use a Heading for formatting and styling, but represent the page’s structure.
VincentSmedinga marked this conversation as resolved.
Show resolved Hide resolved
User agents may use heading information to generate a table of contents for a document.
alimpens marked this conversation as resolved.
Show resolved Hide resolved

## Relevant WCAG Requirements

Expand Down
6 changes: 3 additions & 3 deletions packages/react/documentation/coding-conventions.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,13 +22,13 @@ However, barrel files have 2 potential pitfalls:

We can avoid this last pitfall by adhering to the following code convention: barrel file imports should only be used to import from a package, not within one.

To illustrate: If the `Accordion` React component needs the `HeadingLevel` type from the `Heading` React component, it should import it like this:
To illustrate: If the `Accordion` React component needs the `HeadingProps` type from the `Heading` React component, it should import it like this:

`import { HeadingLevel } from '../Heading/Heading'`
`import type { HeadingProps } from '../Heading/Heading'`

Instead of this:

`import { HeadingLevel } from '../Heading'` or `import { HeadingLevel } from '../'`
`import type { HeadingProps } from '../Heading'` or `import type { HeadingProps } from '../'`

## Subcomponents

Expand Down
4 changes: 2 additions & 2 deletions packages/react/src/Accordion/Accordion.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -8,12 +8,12 @@ import { forwardRef, useImperativeHandle, useRef } from 'react'
import type { ForwardedRef, HTMLAttributes, PropsWithChildren } from 'react'
import AccordionContext from './AccordionContext'
import { AccordionSection } from './AccordionSection'
import { HeadingLevel } from '../Heading/Heading'
import type { HeadingProps } from '../Heading/Heading'
import { useKeyboardFocus } from '../common/useKeyboardFocus'

export type AccordionProps = {
/** The hierarchical level of the Accordion Section heading(s) within the document. */
headingLevel: HeadingLevel
headingLevel: HeadingProps['level']
/** The HTML element to use for each Accordion Section. */
sectionAs?: 'div' | 'section'
} & PropsWithChildren<HTMLAttributes<HTMLDivElement>>
Expand Down
4 changes: 2 additions & 2 deletions packages/react/src/Accordion/AccordionContext.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,10 @@
*/

import { createContext } from 'react'
import { HeadingLevel } from '../Heading/Heading'
import type { HeadingProps } from '../Heading/Heading'

export type AccordionContextValue = {
headingLevel: HeadingLevel
headingLevel: HeadingProps['level']
sectionAs?: 'div' | 'section'
}

Expand Down
4 changes: 2 additions & 2 deletions packages/react/src/Alert/Alert.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ import clsx from 'clsx'
import { forwardRef } from 'react'
import type { ForwardedRef, HTMLAttributes, PropsWithChildren } from 'react'
import { Heading } from '../Heading'
import type { HeadingLevel } from '../Heading'
import type { HeadingProps } from '../Heading'
import { Icon } from '../Icon'
import { IconButton } from '../IconButton'

Expand All @@ -23,7 +23,7 @@ export type AlertProps = {
* The hierarchical level of the Heading within the document.
* Note: this intentionally does not change the font size.
*/
headingLevel?: HeadingLevel
headingLevel?: HeadingProps['level']
/** A function to run when dismissing. */
onClose?: () => void
/** The significance of the message conveyed. */
Expand Down
4 changes: 2 additions & 2 deletions packages/react/src/FormErrorList/FormErrorList.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ import { forwardRef } from 'react'
import type { ForwardedRef, HTMLAttributes } from 'react'
import { useAddErrorCountToDocumentTitle } from './useAddErrorCountToDocumentTitle'
import { Alert } from '../Alert'
import type { HeadingLevel } from '../Heading'
import type { HeadingProps } from '../Heading'
import { LinkList } from '../LinkList'

export type FormError = {
Expand All @@ -30,7 +30,7 @@ export type FormErrorListProps = {
* The hierarchical level of the Heading within the document.
* Note: this intentionally does not change the font size.
*/
headingLevel?: HeadingLevel
headingLevel?: HeadingProps['level']
} & HTMLAttributes<HTMLDivElement>

export const FormErrorList = forwardRef(
Expand Down
7 changes: 2 additions & 5 deletions packages/react/src/Heading/Heading.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -9,16 +9,13 @@ import { forwardRef } from 'react'
import type { ForwardedRef, HTMLAttributes, PropsWithChildren } from 'react'
import { getHeadingElement } from './getHeadingElement'

export type HeadingLevel = 1 | 2 | 3 | 4
type HeadingSize = 'level-1' | 'level-2' | 'level-3' | 'level-4' | 'level-5' | 'level-6'

export type HeadingProps = {
/** Changes the text colour for readability on a dark background. */
inverseColor?: boolean
/** The hierarchical level within the document. */
level?: HeadingLevel
level?: 1 | 2 | 3 | 4
/** Uses larger or smaller text without changing its position in the heading hierarchy. */
size?: HeadingSize
size?: 'level-1' | 'level-2' | 'level-3' | 'level-4' | 'level-5' | 'level-6'
} & PropsWithChildren<HTMLAttributes<HTMLHeadingElement>>

export const Heading = forwardRef(
Expand Down
4 changes: 2 additions & 2 deletions packages/react/src/Heading/getHeadingElement.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
import { HeadingLevel } from './Heading'
import type { HeadingProps } from './Heading'

export function getHeadingElement(level: HeadingLevel) {
export function getHeadingElement(level: HeadingProps['level']) {
switch (level) {
case 2:
return 'h2'
Expand Down
2 changes: 1 addition & 1 deletion packages/react/src/Heading/index.ts
Original file line number Diff line number Diff line change
@@ -1,2 +1,2 @@
export { Heading } from './Heading'
export type { HeadingLevel, HeadingProps } from './Heading'
export type { HeadingProps } from './Heading'
4 changes: 2 additions & 2 deletions packages/react/src/TableOfContents/TableOfContents.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ import type { ForwardedRef, HTMLAttributes, PropsWithChildren } from 'react'
import { TableOfContentsLink } from './TableOfContentsLink'
import { TableOfContentsList } from './TableOfContentsList'
import { Heading } from '../Heading'
import type { HeadingLevel } from '../Heading'
import type { HeadingProps } from '../Heading'

export type TableOfContentsProps = {
/** The text for the Heading. */
Expand All @@ -18,7 +18,7 @@ export type TableOfContentsProps = {
* The hierarchical level of the Heading within the document.
* Note: this intentionally does not change the font size.
*/
headingLevel?: HeadingLevel
headingLevel?: HeadingProps['level']
} & PropsWithChildren<HTMLAttributes<HTMLElement>>

const TableOfContentsRoot = forwardRef(
Expand Down
29 changes: 21 additions & 8 deletions storybook/src/components/Heading/Heading.docs.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -14,21 +14,34 @@ import README from "../../../../packages/css/src/components/heading/README.md?ra

## Examples

### Heading 1
### Levels

<Canvas of={HeadingStories.Heading1} />
We’ve limited the number of heading levels to four.
More detailed content should probably be split into multiple pages or have some sections merged.

### Heading 2
#### Level 1

<Canvas of={HeadingStories.Heading2} />
<Canvas of={HeadingStories.Level1} />

### Heading 3
#### Level 2

<Canvas of={HeadingStories.Heading3} />
<Canvas of={HeadingStories.Level2} />

### Heading 4
#### Level 3

<Canvas of={HeadingStories.Heading4} />
<Canvas of={HeadingStories.Level3} />

#### Level 4

<Canvas of={HeadingStories.Level4} />

### Sizes

It may be visually more suitable to display a heading in a smaller font size.
Six sizes from the set of [Text Levels](?path=/docs/docs-design-guidelines-typography--docs) can be used for this purpose.
alimpens marked this conversation as resolved.
Show resolved Hide resolved
Ensure that you still select a level that accurately represents the section’s hierarchy.

<Canvas of={HeadingStories.Sizes} />

### Inverse colour

Expand Down
23 changes: 18 additions & 5 deletions storybook/src/components/Heading/Heading.stories.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
* Copyright Gemeente Amsterdam
*/

import { Heading } from '@amsterdam/design-system-react/src'
import { Column, Heading } from '@amsterdam/design-system-react/src'
import { Meta, StoryObj } from '@storybook/react'
import { inverseColorDecorator } from '../shared/decorators'
import { exampleHeading } from '../shared/exampleContent'
Expand Down Expand Up @@ -32,26 +32,39 @@ type Story = StoryObj<typeof meta>

export const Default: Story = {}

export const Heading1: Story = {}
export const Level1: Story = {}

export const Heading2: Story = {
export const Level2: Story = {
args: {
level: 2,
},
}

export const Heading3: Story = {
export const Level3: Story = {
args: {
level: 3,
},
}

export const Heading4: Story = {
export const Level4: Story = {
args: {
level: 4,
},
}

export const Sizes: Story = {
render: (args) => (
<Column gap="small">
<Heading {...args} key="level-1" size="level-1" />
<Heading {...args} key="level-2" size="level-2" />
<Heading {...args} key="level-3" size="level-3" />
<Heading {...args} key="level-4" size="level-4" />
<Heading {...args} key="level-5" size="level-5" />
<Heading {...args} key="level-6" size="level-6" />
</Column>
),
}

export const InvertedColor: Story = {
args: {
inverseColor: true,
Expand Down