psammead-section-label -

Description

The @bbc/psammead-section-label package exports one component - a Section Label.

For colours and font family it uses @bbc/psammead-styles and @bbc/gel-foundations for spacing and GEL Typography implemented in Styled Components.

The only provided child should be the title for the section, provided as a string, which will be wrapped in an <h2> element by the component – (see the Accessibility notes).

Installation

npm install @bbc/psammead-section-label

Props

| Argument | Type | Required | Default | Example | | --------- | ---- | -------- | ------- | ------- | | bar | boolean | no | true | false | | mobileDivider | boolean | no | true | false | | visuallyHidden | boolean | no | false | true | | children | string | yes | N/A | 'Most Read' | | dir | string | no | 'ltr' | 'rtl' | | href | string | no | null | 'https://www.bbc/com/igbo/egwuregwu' | | id | string | no | N/A | top-stories-id | | labelId | string | no | N/A | top-stories-label | | linkText | string | no | null | 'See More' | | script | object | yes | N/A | { canon: { groupA: { fontSize: '28', lineHeight: '32',}, groupB: { fontSize: '32', lineHeight: '36' }, groupD: { fontSize: '44', lineHeight: '48' } }, trafalgar: { groupA: { fontSize: '20', lineHeight: '24' }, groupB: { fontSize: '24', lineHeight: '28' }, groupD: { fontSize: '32', lineHeight: '36' } } } | | service | string | yes | N/A | 'news' | | backgroundColor | string | no | C_GHOST | C_LUNAR | | overrideHeadingAs | string | no | null | strong |

Usage

import SectionLabel from '@bbc/psammead-section-label';
import { latin } from '@bbc/gel-foundations/scripts';

const WrappingComponent = () => (
  <div aria-labelledby="example-section-label">
    <SectionLabel
      script={latin}
      dir="ltr"
      labelId="example-section-label"
      service="news"
    >
      Example section
    </SectionLabel>
  </div>
);

Or, without a horizontal bar:

import SectionLabel from '@bbc/psammead-section-label';
import { latin } from '@bbc/gel-foundations/scripts';

const WrappingComponent = () => (
  <div aria-labelledby="example-section-label">
    <SectionLabel
      script={latin}
      dir="ltr"
      bar={false}
      labelId="example-section-label"
      service="news"
    >
      Example section
    </SectionLabel>
  </div>
);

On mobile, this component places a dividing line above the title. This can be disabled by setting the mobileDivider prop to false:

import SectionLabel from '@bbc/psammead-section-label';
import { latin } from '@bbc/gel-foundations/scripts';

const WrappingComponent = () => (
  <div aria-labelledby="example-section-label">
    <SectionLabel
      script={latin}
      dir="ltr"
      mobileDivider={false}
      labelId="example-section-label"
      service="news"
    >
      Example section
    </SectionLabel>
  </div>
);

You can also visually hide the SectionLabel for all breakpoints by adding the visuallyHidden prop:

import SectionLabel from '@bbc/psammead-section-label';
import { latin } from '@bbc/gel-foundations/scripts';

const WrappingComponent = () => (
  <div aria-labelledby="example-section-label">
    <SectionLabel
      script={latin}
      dir="ltr"
      visuallyHidden={true}
      labelId="example-section-label"
      service="news"
    >
      Example section
    </SectionLabel>
  </div>
);

You can even use this component as a link (typically to an index of content related to the section): NB. when doing this both the href and the linkText must be supplied. If either is missing, the link will not be rendered.

import SectionLabel from '@bbc/psammead-section-label';
import { latin } from '@bbc/gel-foundations/scripts';

const WrappingComponent = () => (
  <div aria-labelledby="example-section-label">
    <SectionLabel
      script={latin}
      dir="ltr"
      href="https://www.bbc.com/news/index"
      id="example-section-label"
      linkText="See More"
      service="news"
    >
      Example section
    </SectionLabel>
  </div>
);

You can override the header(h2) to any custom HTML element that fits your accesibility requirement depending on what use case or semantic meaning you want to portray in your pages with the overrideHeadingAs prop.

import SectionLabel from '@bbc/psammead-section-label';
import { latin } from '@bbc/gel-foundations/scripts';

const WrappingComponent = () => (
  <div aria-labelledby="example-section-label">
    <SectionLabel
      script={latin}
      dir="ltr"
      labelId="example-section-label"
      service="news"
      overrideHeadingAs="strong"
    >
      Example section
    </SectionLabel>
  </div>
);

When to use this component

This component should be used to signal the beginning of a grouping of story promos. It should not wrap the story promos or contain any content other than that section's title (aka 'strapline').

Accessibility notes

Although this component has the appearance of a horizontal rule, it does not use an <hr> tag, and therefore does not have the associated semantic meaning.

This component wraps the title string in an <h2> element. The labelId prop will be applied to the <h2> as an id attribute, allowing the content of the element to be referenced by an aria-labelledby attribute. See the examples above.

Setting the visuallyHidden prop to true visually hides this component for all breakpoints, however it will still be available to screen-readers and other assistive technology.

When supplied with an href and the linkText, the section label contains an <a> link, which is aria-labelledby the labelId described above. The linkText is only expected to be useful to visual users, so is marked as aria-hidden="true" to prevent announcement to screen readers. This aria-hidden="true" isn't strictly required - setting the aria-labelledby attribute should prevent screen readers from reading out the linkText. However, it adding it makes clear to screen readers and other developers that the linkText is designed to be ignored by screen readers.

Contributing

Psammead is completely open source. We are grateful for any contributions, whether they be new components, bug fixes or general improvements. Please see our primary contributing guide which can be found at the root of the Psammead respository.

Code of Conduct

We welcome feedback and help on this work. By participating in this project, you agree to abide by the code of conduct. Please take a moment to read it.

License

Psammead is Apache 2.0 licensed.