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

Introduce experimental and legacy component status #2094

Merged
merged 12 commits into from
May 17, 2023
18 changes: 18 additions & 0 deletions .changeset/early-seahorses-whisper.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
---
'@sumup/circuit-ui': major
---

Moved the SingleDayPicker, RangePicker, CalendarTag, and CalendarTagTwoStep components to the ["legacy" status](https://circuit.sumup.com/?path=/docs/introduction-component-lifecycle--docs).

Install the optional peer dependencies...

```bash
npm install react-dates@^21.8 moment@^2.29
```

...and update your imports:

```diff
-import { SingleDayPicker } from '@sumup/circuit-ui';
+import { SingleDayPicker } from '@sumup/circuit-ui/legacy';
```
10 changes: 10 additions & 0 deletions .changeset/metal-bugs-melt.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
---
'@sumup/circuit-ui': major
---

Moved the Tooltip component to the ["legacy" status](https://circuit.sumup.com/?path=/docs/introduction-component-lifecycle--docs). Update your imports:

```diff
-import { Tooltip } from '@sumup/circuit-ui';
+import { Tooltip } from '@sumup/circuit-ui/legacy';
```
10 changes: 10 additions & 0 deletions .changeset/pretty-bananas-juggle.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
---
'@sumup/circuit-ui': major
---

Moved the Sidebar, SidebarContextProvider, and SidebarContextConsumer components to the ["legacy" status](https://circuit.sumup.com/?path=/docs/introduction-component-lifecycle--docs). Update your imports:

```diff
-import { Sidebar } from '@sumup/circuit-ui';
+import { Sidebar } from '@sumup/circuit-ui/legacy';
```
76 changes: 35 additions & 41 deletions .storybook/components/Statuses.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -13,14 +13,22 @@
* limitations under the License.
*/

import type { ReactNode } from 'react';
import { Unstyled } from '@storybook/addon-docs';
import LinkTo from '@storybook/addon-links/react';
import { css, ThemeProvider } from '@emotion/react';
import { light } from '@sumup/design-tokens';
import { Badge, Body, cx, spacing } from '@sumup/circuit-ui';
import { ReactNode } from 'react';
import { Badge, BadgeProps, Body, cx, spacing } from '@sumup/circuit-ui';

type Variant =
| 'stable'
| 'under-review'
| 'experimental'
| 'legacy'
| 'deprecated';

interface StatusProps {
variant: 'stable' | 'deprecated' | 'inReview' | 'experimental';
variant: Variant;
children?: ReactNode;
}

Expand All @@ -30,20 +38,33 @@ const descriptionStyles = css`
}
`;

const variants = {
stable: { variant: 'success', label: 'Stable' },
deprecated: { variant: 'danger', label: 'Deprecated' },
inReview: { variant: 'warning', label: 'In Review' },
experimental: { variant: 'warning', label: 'Experimental' },
} as const;
const variantMap: Record<
Variant,
{ variant: BadgeProps['variant']; label: string }
> = {
'stable': { variant: 'success', label: 'Stable' },
'experimental': { variant: 'promo', label: 'Experimental' },
'under-review': { variant: 'warning', label: 'Under Review' },
'legacy': { variant: 'warning', label: 'Legacy' },
'deprecated': { variant: 'danger', label: 'Deprecated' },
};

export default function Status({
variant: status = 'stable',
children,
...props
}: StatusProps) {
const { variant, label } = variantMap[status];

const Status = ({ variant: status = 'stable', children }: StatusProps) => {
const { variant, label } = variants[status];
const kind = 'Introduction/Component-Lifecycle';
const name = 'Docs';

return (
<ThemeProvider theme={light}>
<Unstyled>
<Badge variant={variant}>{label}</Badge>
<Unstyled {...props}>
<LinkTo {...props} kind={kind} name={name}>
<Badge variant={variant}>{label}</Badge>
</LinkTo>
{children && (
<Body
size="two"
Expand All @@ -57,31 +78,4 @@ const Status = ({ variant: status = 'stable', children }: StatusProps) => {
</Unstyled>
</ThemeProvider>
);
};

/**
* @deprecated Use `<Status variant="stable" />` instead.
*/
Status.Stable = (props: Pick<StatusProps, 'children'>) => (
<Status variant="stable" {...props} />
);
/**
* @deprecated Use `<Status variant="deprecated" />` instead.
*/
Status.Deprecated = (props: Pick<StatusProps, 'children'>) => (
<Status variant="deprecated" {...props} />
);
/**
* @deprecated Use `<Status variant="inReview" />` instead.
*/
Status.InReview = (props: Pick<StatusProps, 'children'>) => (
<Status variant="inReview" {...props} />
);
/**
* @deprecated Use `<Status variant="experimental" />` instead.
*/
Status.Experimental = (props: Pick<StatusProps, 'children'>) => (
<Status variant="experimental" {...props} />
);

export default Status;
}
16 changes: 0 additions & 16 deletions docs/contributing/5-deprecations.mdx

This file was deleted.

61 changes: 61 additions & 0 deletions docs/introduction/3-component-lifecycle.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
import { Meta, Intro, Status } from '../../.storybook/components';

<Meta title="Introduction/Component Lifecycle" />

# Component Lifecycle

<Intro>
Circuit UI components move through different stages throughout their
lifecycle. Within each stage, components meet different requirements and
receive different levels of support.
</Intro>

## Stable

<Status variant="stable" aria-hidden />
connor-baer marked this conversation as resolved.
Show resolved Hide resolved

Stable components solve a proven use case. They meet all of our quality standards including accessibility, [browser support](Introduction/Browser-Support/Docs), localization, test coverage, and documentation. Changes to the component API are unlikely and follow [semantic versioning](https://semver.org/).

## Under Review

<Status variant="under-review" aria-hidden />

Our quality requirements evolve over time. Existing components that haven't been updated yet to meet the latest standards are placed under review. You can continue to use them but be aware of the issues that are listed in the components' documentation.
connor-baer marked this conversation as resolved.
Show resolved Hide resolved

[Contributions](Contributing/Overview/Docs) to resolve the issues are welcome!

## Experimental

<Status variant="experimental" aria-hidden />

Experimental components are under active development. They might not meet our quality standards yet and likely lack sufficient documentation. They don't follow [semantic versioning](https://semver.org/) so breaking changes in minor versions are possible.

This is a good time to provide feedback. [Open an issue](https://github.com/sumup-oss/circuit-ui/issues/new?template=amend-existing-component.md) to suggest improvements.

Experimental components are exported separately from stable components. Import them from `@sumup/circuit-ui/experimental`:

```tsx
import { Component } from '@sumup/circuit-ui/experimental';
```

## Legacy

<Status variant="legacy" aria-hidden />

Legacy components are going to be phased out soon, but don't have a stable replacement yet. You can continue to use them in existing code until a stable alternative becomes available. We don't recommend adopting legacy components in new code. Legacy components won't receive any updates apart from bugfixes.
connor-baer marked this conversation as resolved.
Show resolved Hide resolved

Legacy components are exported separately from stable components. Import them from `@sumup/circuit-ui/legacy`:

```tsx
import { Component } from '@sumup/circuit-ui/legacy';
```

Some legacy components require third-party dependencies which aren't bundled with Circuit UI. Refer to each component's documentation for a list of dependencies that need to be installed manually.
connor-baer marked this conversation as resolved.
Show resolved Hide resolved

## Deprecated

<Status variant="deprecated" aria-hidden />

Deprecated components are going to be removed in the next major release. When used, they log a deprecation warning during local development. Replace them with the alternative that's suggested in the components' documentation. Deprecated components won't receive any updates or bugfixes.

Deprecated components can be exported from `@sumup/circuit-ui` or `@sumup/circuit-ui/legacy`, depending on their previous status.
Loading