Document and export the inputOutline style mixin

.changeset/cold-beds-sort.md

@@ -0,0 +1,5 @@
+---
+'@sumup/circuit-ui': minor
+---
+
+Added the `inputOutline` style mixin. It can be used to communicate to the user that an element is hovered, focused, or active in the disabled, invalid, and warning states.

packages/circuit-ui/index.ts

@@ -173,6 +173,7 @@ export {
   clearfix,
   hideScrollbar,
   shadow,
+  inputOutline,
 } from './styles/style-mixins';
 
 export { sharedPropTypes, styleHelpers };

packages/circuit-ui/styles/style-mixins.docs.mdx

@@ -117,6 +117,25 @@ function focusOutline('inset'): (theme: Theme | { theme: Theme }) => SerializedS
 
 <Story id="features-style-mixins--focus-outline" />
 
+## `inputOutline`
+
+Visually communicates to the user that an element is hovered, focused, or active in the disabled, invalid, and warning states.
+
+```ts
+function inputOutline(
+  theme:
+    | Theme
+    | {
+        theme: Theme;
+        disabled?: boolean;
+        invalid?: boolean;
+        hasWarning?: boolean;
+      },
+): SerializedStyles;
+```
+
+<Story id="features-style-mixins--input-outline" />
+
 ## `disableVisually`
 
 Visually communicates to the user that an element is disabled and prevents user interactions.

packages/circuit-ui/styles/style-mixins.spec.tsx

@@ -469,6 +469,18 @@ describe('Style helpers', () => {
       `);
     });
 
+    it('should match the snapshot when disabled', () => {
+      const { styles } = inputOutline({
+        theme: light,
+        disabled: true,
+      });
+      expect(styles).toMatchInlineSnapshot(`
+        "
+              box-shadow: 0 0 0 1px #999;
+            "
+      `);
+    });
+
     it('should match the snapshot when invalid', () => {
       const { styles } = inputOutline({
         theme: light,

packages/circuit-ui/styles/style-mixins.stories.tsx

@@ -17,6 +17,7 @@
 /** @jsx jsx */
 import { jsx } from '@emotion/core';
 import styled from '@emotion/styled';
+import { Theme } from '@sumup/design-tokens';
 
 import { Stack } from '../../../.storybook/components';
 import Button from '../components/Button';
@@ -26,6 +27,7 @@ import {
   spacing,
   shadow,
   focusOutline,
+  inputOutline,
   disableVisually,
   clearfix,
   hideVisually,
@@ -141,6 +143,15 @@ export const FocusOutline = () => (
   </Stack>
 );
 
+export const InputOutline = () => (
+  <Stack>
+    <Box css={inputOutline} />
+    <Box css={(theme: Theme) => inputOutline({ theme, disabled: true })} />
+    <Box css={(theme: Theme) => inputOutline({ theme, invalid: true })} />
+    <Box css={(theme: Theme) => inputOutline({ theme, hasWarning: true })} />
+  </Stack>
+);
+
 export const DisableVisually = () => (
   <div css={disableVisually}>This element is visually disabled.</div>
 );

packages/circuit-ui/styles/style-mixins.ts

@@ -273,7 +273,6 @@ export const hideVisually = (): SerializedStyles => css`
 /**
  * Visually communicates to the user that an element is focused.
  */
-
 export function focusOutline(
   options: 'inset',
 ): (args: ThemeArgs) => SerializedStyles;
@@ -334,8 +333,8 @@ export const hideScrollbar = (): SerializedStyles => css`
 `;
 
 /**
- * Visually communicates to the user that an input is hovered, focused,
- * or active.
+ * Visually communicates to the user that an element is hovered, focused, or
+ * active in the disabled, invalid, and warning states.
  */
 export const inputOutline = (
   args:
@@ -345,6 +344,9 @@ export const inputOutline = (
         disabled?: boolean;
         invalid?: boolean;
         hasWarning?: boolean;
+        /**
+         * @deprecated
+         */
         showValid?: boolean;
       },
 ): SerializedStyles => {