feat(typography): add new Kbd component (#2041)

Author: jzempel

packages/typography/demo/kbd.stories.mdx

@@ -0,0 +1,20 @@
+import { Meta, ArgsTable, Canvas, Story, Markdown } from '@storybook/addon-docs';
+import { Kbd } from '@zendeskgarden/react-typography';
+import { KbdStory } from './stories/KbdStory';
+import README from '../README.md';
+
+<Meta title="Packages/Typography/Kbd" component={Kbd} />
+
+# API
+
+<ArgsTable />
+
+# Demo
+
+<Canvas>
+  <Story name="Kbd" args={{ children: '⌃ ⌥ /', size: 'inherit' }}>
+    {args => <KbdStory {...args} />}
+  </Story>
+</Canvas>
+
+<Markdown>{README}</Markdown>

packages/typography/demo/stories/KbdStory.tsx

@@ -0,0 +1,27 @@
+/**
+ * Copyright Zendesk, Inc.
+ *
+ * Use of this source code is governed under the Apache License, Version 2.0
+ * found at http://www.apache.org/licenses/LICENSE-2.0.
+ */
+
+import React from 'react';
+import { StoryFn } from '@storybook/react';
+import { IKbdProps, Kbd } from '@zendeskgarden/react-typography';
+
+interface IArgs extends IKbdProps {
+  children: string;
+}
+
+export const KbdStory: StoryFn<IArgs> = ({ children, ...args }) => (
+  <>
+    {children.split(' ').map((child, index) => (
+      <>
+        {index > 0 ? ' ' : ''}
+        <Kbd key={index} {...args}>
+          {child}
+        </Kbd>
+      </>
+    ))}
+  </>
+);

packages/typography/src/elements/Kbd.spec.tsx

@@ -0,0 +1,50 @@
+/**
+ * Copyright Zendesk, Inc.
+ *
+ * Use of this source code is governed under the Apache License, Version 2.0
+ * found at http://www.apache.org/licenses/LICENSE-2.0.
+ */
+
+import React from 'react';
+import { render, renderRtl } from 'garden-test-utils';
+import { Kbd } from './Kbd';
+
+describe('Kbd', () => {
+  it('renders the expected element', () => {
+    const { container } = render(<Kbd />);
+
+    expect(container.firstChild!.nodeName).toBe('KBD');
+  });
+
+  it('forces left-to-right text direction', () => {
+    const { container } = renderRtl(<Kbd />);
+
+    expect(container.firstChild).toHaveStyleRule('direction', 'ltr');
+  });
+
+  describe('size', () => {
+    it('renders inherited size', () => {
+      const { container } = render(<Kbd />);
+
+      expect(container.firstChild).not.toHaveStyleRule('font-size', 'inherit');
+    });
+
+    it('renders small styling if provided', () => {
+      const { container } = render(<Kbd size="small" />);
+
+      expect(container.firstChild).toHaveStyleRule('font-size', '11px');
+    });
+
+    it('renders medium styling if provided', () => {
+      const { container } = render(<Kbd size="medium" />);
+
+      expect(container.firstChild).toHaveStyleRule('font-size', '13px');
+    });
+
+    it('renders large styling if provided', () => {
+      const { container } = render(<Kbd size="large" />);
+
+      expect(container.firstChild).toHaveStyleRule('font-size', '17px');
+    });
+  });
+});

packages/typography/src/elements/Kbd.tsx

@@ -0,0 +1,24 @@
+/**
+ * Copyright Zendesk, Inc.
+ *
+ * Use of this source code is governed under the Apache License, Version 2.0
+ * found at http://www.apache.org/licenses/LICENSE-2.0.
+ */
+
+import React, { forwardRef } from 'react';
+import PropTypes from 'prop-types';
+import { StyledKbd } from '../styled';
+import { IKbdProps, INHERIT_SIZE } from '../types';
+
+/**
+ * @extends HTMLAttributes<HTMLElement>
+ */
+export const Kbd = forwardRef<HTMLElement, IKbdProps>(({ size = 'inherit', ...other }, ref) => (
+  <StyledKbd $size={size} {...other} ref={ref} />
+));
+
+Kbd.displayName = 'Kbd';
+
+Kbd.propTypes = {
+  size: PropTypes.oneOf(INHERIT_SIZE)
+};

packages/typography/src/index.ts

@@ -15,6 +15,7 @@ export { Blockquote } from './elements/Blockquote';
 export { Code } from './elements/Code';
 export { CodeBlock } from './elements/CodeBlock';
 export { Ellipsis } from './elements/Ellipsis';
+export { Kbd } from './elements/Kbd';
 export { Paragraph } from './elements/Paragraph';
 export { OrderedList } from './elements/lists/OrderedList';
 export { UnorderedList } from './elements/lists/UnorderedList';
@@ -31,6 +32,7 @@ export type {
   ICodeProps,
   ICodeBlockProps,
   IEllipsisProps,
+  IKbdProps,
   IParagraphProps,
   IOrderedListProps,
   IUnorderedListProps,

packages/typography/src/styled/StyledKbd.ts

@@ -0,0 +1,66 @@
+/**
+ * Copyright Zendesk, Inc.
+ *
+ * Use of this source code is governed under the Apache License, Version 2.0
+ * found at http://www.apache.org/licenses/LICENSE-2.0.
+ */
+
+import styled, { css, DefaultTheme, ThemeProps } from 'styled-components';
+import { math, stripUnit } from 'polished';
+import { componentStyles } from '@zendeskgarden/react-theming';
+import { StyledCode } from './StyledCode';
+import { IKbdProps } from '../types';
+
+const COMPONENT_ID = 'typography.code';
+
+interface IStyledKbdProps extends ThemeProps<DefaultTheme> {
+  $size?: IKbdProps['size'];
+}
+
+const sizeStyles = ({ theme, $size }: IStyledKbdProps) => {
+  let paddingHorizontal;
+  let paddingVertical = '0';
+
+  switch ($size) {
+    case 'small':
+      paddingHorizontal = `${theme.space.base}px`;
+      break;
+
+    case 'medium':
+      paddingHorizontal = `${theme.space.base * 1.5}px`;
+      break;
+
+    case 'large':
+      paddingHorizontal = `${theme.space.base * 1.75}px`;
+      break;
+
+    default:
+      paddingHorizontal = `${stripUnit(math(`${theme.space.base * 1.5} / (${theme.fontSizes.md} - 1px)`))}em`;
+      paddingVertical = '1.5px';
+      break;
+  }
+
+  const padding = `${paddingVertical} ${paddingHorizontal}`;
+
+  return css`
+    && {
+      padding: ${padding};
+    }
+  `;
+};
+
+/*
+ * 1. Force left-to-right text direction
+ */
+export const StyledKbd = styled(StyledCode as 'kbd').attrs({
+  'data-garden-id': COMPONENT_ID,
+  'data-garden-version': PACKAGE_VERSION,
+  as: 'kbd'
+})<IStyledKbdProps>`
+  display: inline-block; /* [1] */
+  direction: ltr; /* [1] */
+
+  ${sizeStyles};
+
+  ${componentStyles};
+`;

packages/typography/src/styled/index.ts

@@ -14,6 +14,7 @@ export * from './StyledCodeBlockToken';
 export * from './StyledEllipsis';
 export * from './StyledFont';
 export * from './StyledIcon';
+export * from './StyledKbd';
 export * from './StyledList';
 export * from './StyledListItem';
 export * from './StyledParagraph';

packages/typography/src/types/index.ts

@@ -91,6 +91,11 @@ export interface IEllipsisProps extends HTMLAttributes<HTMLDivElement> {
   tag?: any;
 }
 
+export interface IKbdProps extends HTMLAttributes<HTMLElement> {
+  /** Adjusts the font size. By default font size is inherited from the surrounding text. */
+  size?: (typeof INHERIT_SIZE)[number];
+}
+
 export interface IParagraphProps extends HTMLAttributes<HTMLParagraphElement> {
   /** Controls the spacing between sibling paragraphs */
   size?: Size;