@financial-times/o-teaser/MIGRATION.md

Provides styling for teaser elements, which contain information about an article and link through to it

# Migration guide

### Migrating to v10.0.0

v10.0.0 introduces:

* **Byline** component, which replaces the legacy Headshot component
* **title indicator icon** for only Opinion teaser
* **titlePrefix**

#### Byline

The Byline component is enabled by default (`showByline: true`) in the presets.
When `byline` data is provided, the Byline component will be rendered instead of Headshot.

If you are not ready to use the Byline component, pass:

```js
showByline: false
```

This keeps the existing Headshot behaviour.

If you are migrating to the Byline component, you must provide a `byline` property:

| Property name | Type                           | Note                               |
| ------------- | ------------------------------ | ---------------------------------- |
| `byline`      | `[string, string?, string?][]` | `[text, linkUrl?, headshotUrl?][]` |

Example with single author with headshot:

```js
byline: [
  ['Martin Wolf', '/martin-wolf', '/martin-wolf-headshot']
]
```

Example with multiple authors:

```js
// This will render: Martin Wolf & Paul Krugman
byline: [
  ['Martin Wolf', '/martin-wolf'],
  [' & '],
  ['Paul Krugman', '/paul-krugman']
]
```

#### titlePrefix

`titlePrefix` is enabled by default (`showTitlePrefix: true`) in the presets.
Nothing will be rendered unless a `titlePrefix` string is provided.

| Property name | Type     | Note                            |
| ------------- | -------- | ------------------------------- |
| `titlePrefix` | `string` | Text displayed before the title |


### Migrating to v9.0.0

v9 upgrades [html-react-parser to v5.2.7](https://github.com/remarkablemark/html-react-parser), which has a dependency on React 19.

If you use React 17 or 18, add an override/resolution in your package manager to align React versions.

```json
{
  "overrides": {
    "react": "17.0.2",
    "react-dom": "17.0.2"
  }
}
```

If you are using preact with `preact/compat`, ensure your bundler aliases `react` and `react-dom` to `preact/compat`.


### Migrating to v8.0.0

v8.0.0 includes a minor visual update. You’ll need to check a few things to make sure it looks and works as expected.

### Migrating to v7.2.0

v7.2.0 includes a change to use Image Service V3. Whilst the change should be unobtrusive, there are some checks you will need to perform.

Image service V3 uses a hosts configuration, meaning **a valid system code must be used in order to make image requests** this can be set in your Sass configuration as a global.

```scss
//global scope of your Sass code
$system-code: 'next-article';
```

Your system must appear in the valid hosts for the Image Service, please refer to the [Image Service documentation](https://github.com/Financial-Times/image-service?tab=readme-ov-file#systems--hosts).

## Migrating from v6 to v7

This major release introduces a new design language and visually breaking changes. This includes mobile optimised typography, icons, and buttons. It also removes peer dependencies from deprecated "o2" components.

To upgrade, replace the following "o2" components with their "o3" equivalent:

- [o-normalise](../o-normalise/MIGRATION.md)
- [o-spacing](../o-spacing/MIGRATION.md)
- [o-colors](../o-colors/MIGRATION.md)
- [o-icons](../o-icons/MIGRATION.md)
- [o-buttons](../o-buttons/MIGRATION.md)
- [o-typography](../o-typography/MIGRATION.md)
- [o-editorial-typography](../o-editorial-typography/MIGRATION.md)
- [o-big-number](../o-big-number/MIGRATION.md)
- [o-quote](../o-quote/MIGRATION.md)
- [o-fonts](../o-fonts/MIGRATION.md)

## Migrating from v5 to v6

v6 drops support for Bower and version 2 of the Origami Build Service.

## Migrating from v4 to v5

v5 introduces the font FinancierDisplayWeb at medium weight and normal style. To upgrade make sure your project includes the FinancierDisplayWeb medium font face using [o-fonts](https://o2-core.origami.ft.com/?path=/docs/deprecated-o-icons-sassdoc--docs).

## Migrating from v3 to v4

### Colours and Colour Usecases

All [o-teaser colours and colour usecases](https://github.com/Financial-Times/o-teaser/blob/v3.5.9/src/scss/_color-use-cases.scss) have been renamed to include an o-colors namespace. For example:

- `o-teaser` is now `o-teaser/base`
- `fast-ft` is now `o-teaser/fast-ft`
- `o-teaser-tag` is now `o-teaser/tag`
- `o-teaser-theme-opinion` is now `o-teaser/theme-opinion`
- etc.

```diff
- @include oColorsFor('o-teaser-tag', 'text');
+ color: oColorsByUsecase('o-teaser/tag', 'text');
```

The `commercial-content` colour has been removed. Include [o-labels](https://o2-core.origami.ft.com/?path=/docs/maintained-o-labels-readme--docs&globals=backgrounds:!undefined) and use `o-labels/commercial-content` instead.

The deprecated `o-teaser-promoted-prefix` usecase has been removed. Include [o-labels](https://o2-core.origami.ft.com/?path=/docs/maintained-o-labels-readme--docs&globals=backgrounds:!undefined) and use the `o-labels/commercial-content` colour instead.

### Markup

Deprecated classes have been removed:

- Replace `o-teaser--big-video` with `o-teaser--has-video`
- Replace `o-teaser__duration` with `o-teaser__tag-suffix`

### Sass

The Sass variables `$o-teaser-themes` and `$o-teaser-elements` are now private and must not be used.

All Sass mixins have been removed except `oTeaser` and `oTeaserHeading`. Instead of `oTeaserTag` use [oEditorialTypographyTag](https://github.com/Financial-Times/o-editorial-typography); instead of other mixins include styles using `oTeaser` and update your markup to use `o-teaser` classes.

The `oTeaser` mixin has also been updated. Its two arguments are now accepted within an options `$opts` map like other Origami components:

```diff
-@include oTeaser($elements: ('default', 'images'), $themes: ('small', 'large', 'video'));
+@include oTeaser($opts:(
+	'elements': ('default', 'images'),
+	'themes': ('small', 'large', 'video')
+));
```

### Updated dependencies

The dependencies for this component have all been updated to the latest major versions.
If you have any conflicts while installing this version, you'll need to first update
its dependencies. See [the Bower config for these](./bower.json).

## Migrating from v2 to v3

Version 3 uses a new major version of [o-labels](https://github.com/Financial-Times/o-labels/). Make sure your project is [compatible](https://github.com/Financial-Times/o-labels/blob/master/MIGRATION.md#migrating-from-v3-to-v4) with o-labels@4.0.0

## Migrating from v1 to v2

V1 -> V2 introduces the new major of o-colors, o-labels, and o-typography. Updating to this new version will mean updating any other components that you have which are using any of the updated major versions. There are no other breaking changes in this release.

### From `o-card` to `o-teaser`.

In most cases, migrating to `o-teaser` from `o-card` will be possible by simply replacing the `o-card` class prefix to `o-teaser`, i.e. `o-card__heading` becomes `o-teaser__heading`. However, there are some additional updates you will need to do, particularly around images and themes.

Images now require a containing element, with the `o-teaser__image` class on the `<img>` tag itself, see [Images](#images).

The `landscape` and `standout` themes have been removed, teasers are now responsive using `o-grid` and have a larger set of [themes](#themes).