Introduce experimental and legacy component status (#2094)

sumup-oss · May 17, 2023 · da1a11b · da1a11b
1 parent 9677a30
commit da1a11b
Show file tree

Hide file tree

Showing 73 changed files with 501 additions and 256 deletions.
diff --git a/.changeset/early-seahorses-whisper.md b/.changeset/early-seahorses-whisper.md
@@ -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';
+```
diff --git a/.changeset/metal-bugs-melt.md b/.changeset/metal-bugs-melt.md
@@ -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';
+```
diff --git a/.changeset/pretty-bananas-juggle.md b/.changeset/pretty-bananas-juggle.md
@@ -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';
+```
diff --git a/.storybook/components/Statuses.tsx b/.storybook/components/Statuses.tsx
@@ -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;
 }
 
@@ -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"
@@ -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;
+}
diff --git a/...ng/6-browser-support-for-contributors.mdx → ...ng/5-browser-support-for-contributors.mdx b/...ng/6-browser-support-for-contributors.mdx → ...ng/5-browser-support-for-contributors.mdx
diff --git a/docs/contributing/5-deprecations.mdx b/docs/contributing/5-deprecations.mdx
diff --git a/docs/introduction/3-component-lifecycle.mdx b/docs/introduction/3-component-lifecycle.mdx
@@ -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 />
+
+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.
+
+[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.
+
+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.
+
+## 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.
diff --git a/docs/introduction/3-browser-support.mdx → docs/introduction/4-browser-support.mdx b/docs/introduction/3-browser-support.mdx → docs/introduction/4-browser-support.mdx