## Feature Examples

### Size
- description: Control the size of a section header with the `size` prop: - `medium` (default) is the standard used in common cases. - `small` is used in dense layouts and panels.
- example:
```jsx
<StorybookComponents.Stack flexDirection="column">
  <SectionHeader title="Medium" size="medium" />
  <SectionHeader title="Small" size="small" />
</StorybookComponents.Stack>;
```

### Horizontal padding
- description: Adjust the `horizontalPadding` of a section header according to the content padding inside the following section: - `large` (default) - `medium` - `small` - `tiny` - `xTiny` - `xxTiny`
- example:
```jsx
<StorybookComponents.Stack flexDirection="column">
  <SectionHeader title="Large" horizontalPadding="large" />
  <SectionHeader title="Medium" horizontalPadding="medium" />
  <SectionHeader title="Small" horizontalPadding="small" />
  <SectionHeader title="Tiny" horizontalPadding="tiny" />
  <SectionHeader title="Extra tiny" horizontalPadding="xTiny" />
  <SectionHeader title="Extra-extra tiny" horizontalPadding="xxTiny" />
</StorybookComponents.Stack>;
```

### Skin
- description: Control the style of a section header using the `skin` prop: - `standard` is the default and is used in most cases. - `neutral` is used to minimize the component's visual weight. - `light` is used as a completely minimal header that blends in with rest of the content. - `bold` gives the title extra presence with the Madefor Display typeface, for a header that opens a page or a major section.
- example:
```jsx
<StorybookComponents.Stack flexDirection="column">
  <SectionHeader title="Standard" skin="standard" />
  <SectionHeader title="Neutral" skin="neutral" />
  <SectionHeader title="Light" skin="light" />
  <SectionHeader title="Bold" skin="bold" />
</StorybookComponents.Stack>;
```

### Bold skin
- description: The `bold` skin renders the title in the Madefor Display typeface at a heavier weight, with more space above it. Use it for the header that opens a page or a major section, where the title has to carry more weight than the section headers nested under it. Keep one bold header per view. Pair it with `standard` or `neutral` headers for the sections beneath.
- example:
```jsx
<StorybookComponents.Stack flexDirection="column">
  <SectionHeader skin="bold" title="Store products" />
  <SectionHeader skin="standard" title="Inventory" />
  <SectionHeader skin="standard" title="Shipping" />
</StorybookComponents.Stack>;
```

### Dividers
- description: Control which dividers are visible with the `divider` prop: - By default, a section header has both top and bottom dividers. - Use `top` when there is already a divider at the bottom of a component. - Use `bottom` when there is already a divider at the top of a component. - Use `none` when there are already dividers at the top and bottom of a component.
- example:
```jsx
<StorybookComponents.Stack flexDirection="column">
  <SectionHeader title="Default" />
  <SectionHeader title="Top" divider="top" />
  <SectionHeader title="Bottom" divider="bottom" />
  <SectionHeader title="No dividers" divider="none" />
</StorybookComponents.Stack>;
```

### Suffix
- description: Use a `suffix` container to add info or actions that relate to the content below a section header. A variety of components can be used in the suffix: - `<InfoIcon/>` - `<TextButton/>` - `<Button/>` - `<IconButton/>` - `<Text/>` or others
- example:
```jsx
<StorybookComponents.Stack flexDirection="column">
  <SectionHeader
    title="Title"
    suffix={
      <InfoIcon
        size="small"
        content="Info icon gives more information about a section."
      />
    }
  />
  <SectionHeader
    title="Title"
    suffix={
      <TextButton
        size="tiny"
        priority="secondary"
        prefixIcon=<Icons.AddSmall />
      >
        Suffix
      </TextButton>
    }
  />
  <SectionHeader
    title="Title"
    suffix={
      <Button size="tiny" priority="secondary">
        Suffix
      </Button>
    }
  />
  <SectionHeader
    title="Title"
    suffix={
      <IconButton size="tiny" priority="secondary">
        <Icons.MoreSmall />
      </IconButton>
    }
  />
  <SectionHeader title="Title" suffix={<Text size="tiny">Suffix</Text>} />
</StorybookComponents.Stack>;
```

### Title
- description: Use the `title` prop to describe the content that appears below the section header. The default is a text value, but the container can accept any component.
- example:
```jsx
<StorybookComponents.Stack flexDirection="column">
  <SectionHeader title="Default" />
  <SectionHeader
    title={
      <Text weight="bold" size="small">
        Custom title
      </Text>
    }
  />
  <SectionHeader title=<StorybookComponents.Placeholder height="24px" /> />
</StorybookComponents.Stack>;
```

### Title alignment
- description: Control the title's position with the `align` prop: - Use `start` (default) for left-aligned lists. - Use `center` in settings panels.
- example:
```jsx
<StorybookComponents.Stack flexDirection="column">
  <SectionHeader title="Start" align="start" />
  <SectionHeader title="Center" align="center" />
</StorybookComponents.Stack>;
```

### Title overflow
- description: Title text that does not fit in one line gets truncated with an ellipsis. The full text appears in a tooltip when hovering over the truncated text.
- example:
```jsx
<SectionHeader title="A very long section title goes into a title container in this case. It even has multiple sentences inside. It will be truncated by ellipses once it reaches the second line" />;
```

## Common Use Case Examples

### Group content in cards
- description: Use section headers to organize card info into separate categories. This makes the whole card easier to scan.
- example:
```jsx
() => {
  const items = [
    {
      sectionTitle: 'Monday, Feb 7',
    },
    {
      time: '7:00 PM - 9:00 PM',
      event: 'Registration & reception',
    },
    {
      sectionTitle: 'Tuesday, Feb 8',
    },
    {
      time: '8:00 AM - 10:00 AM',
      event: 'Keynote address by Steven H. Kastner',
      divider: true,
    },
    {
      time: '10:00 AM - 1:00 PM',
      event: 'Break & networking',
      divider: true,
    },
    {
      time: '1:00 PM - 3:00 PM',
      event: 'Keynote address by Linda Contreras',
      divider: true,
    },
    {
      time: '7:00 PM - 9:00 PM',
      event: 'Evening reception',
    },
    {
      sectionTitle: 'Wednesday, Feb 9',
    },
    {
      time: '8:00 AM - 10:00 AM',
      event: 'Keynote address by Susan W. Eaton',
      divider: true,
    },
    {
      time: '10:00 AM - 1:00 PM',
      event: 'Keynote address by Bjorn Rettig',
    },
  ];

  const pirmaryAction = {
    text: 'Edit',
    onClick: () => ({}),
  };

  const secondaryActions = [
    {
      text: 'Hide',
      icon: <Icons.HiddenSmall />,
      onClick: () => ({}),
    },
    {
      text: 'Cancel',
      icon: <Icons.BlockSmall />,
      onClick: () => ({}),
    },
    {
      text: 'Delete',
      icon: <Icons.DeleteSmall />,
      onClick: () => ({}),
    },
  ];

  const actionsList = (
    <TableActionCell
      primaryAction={pirmaryAction}
      secondaryActions={secondaryActions}
      numOfVisibleSecondaryActions={0}
      size="small"
    />
  );

  const primaryAction = (
    <Button size="small" priority="secondary" prefixIcon={<Icons.AddSmall />}>
      Add Item
    </Button>
  );

  return (
    <Card hideOverflow>
      <Card.Header
        title="Event schedule"
        subtitle="Build a schedule to keep guests informed throughout your event."
        suffix={primaryAction}
      />
      {items.map((params) => {
        if (params.sectionTitle) {
          return <SectionHeader title={params.sectionTitle} size="small" />;
        }
        return (
          <TableListItem
            showDivider={params.divider}
            onClick={() => {}}
            options={[
              { value: <Text size="small">{params.time}</Text>, width: '25%' },
              { value: <Text size="small">{params.event}</Text>, width: '50%' },
              { value: actionsList },
            ]}
          />
        );
      })}
    </Card>
  );
};
```

## Accessibility Examples

### Title as a heading
- description: By default, a section header title is a text element (`<span>`). For better accessibility, use the `as` prop to render the section header title as a heading element.
- example:
```jsx
<StorybookComponents.Stack flexDirection="column">
  <SectionHeader title="Default" />
  <SectionHeader title="Title as <h3> heading" as="h3" />
</StorybookComponents.Stack>;
```