@gv-tech/design-system 0.8.0

package/src/Icon.stories.tsx

@@ -0,0 +1,101 @@
+import { ComponentProps, Fragment } from 'react';
+import styled, { css } from 'styled-components';
+
+import { Icon } from './Icon';
+import { icons } from './shared/icons';
+
+const Meta = styled.div`
+  color: #666;
+  font-size: 12px;
+`;
+
+const Item = styled.li<{ minimal?: boolean }>`
+  display: inline-flex;
+  flex-direction: row;
+  align-items: center;
+  flex: 0 1 20%;
+  min-width: 120px;
+
+  padding: 0px 7.5px 20px;
+
+  svg {
+    margin-right: 10px;
+    width: 24px;
+    height: 24px;
+  }
+
+  ${(props) =>
+    props.minimal &&
+    css`
+      flex: none;
+      min-width: auto;
+      padding: 0;
+      background: #fff;
+      border: 1px solid #666;
+
+      svg {
+        display: block;
+        margin-right: 0;
+        width: 48px;
+        height: 48px;
+      }
+    `};
+`;
+
+const List = styled.ul`
+  display: flex;
+  flex-flow: row wrap;
+  list-style: none;
+`;
+
+export default {
+  title: 'Design System/Icon',
+  component: Icon,
+};
+
+export const Labels = (_args: Record<string, unknown>) => (
+  <Fragment>
+    There are {Object.keys(icons).length} icons
+    <List>
+      {Object.keys(icons).map((key) => (
+        <Item key={key}>
+          <Icon icon={key} aria-hidden />
+          <Meta>{key}</Meta>
+        </Item>
+      ))}
+    </List>
+  </Fragment>
+);
+
+export const NoLabels = (_args: Record<string, unknown>) => (
+  <List>
+    {Object.keys(icons).map((key) => (
+      <Item minimal key={key}>
+        <Icon icon={key} aria-label={key} />
+      </Item>
+    ))}
+  </List>
+);
+
+NoLabels.storyName = 'no labels';
+
+export const Inline = (args: Partial<ComponentProps<typeof Icon>>) => (
+  <Fragment>
+    this is an inline <Icon {...(args as ComponentProps<typeof Icon>)} /> icon (default)
+  </Fragment>
+);
+Inline.args = {
+  icon: 'facehappy',
+  'aria-label': 'Happy face',
+};
+
+export const Block = (args: Partial<ComponentProps<typeof Icon>>) => (
+  <Fragment>
+    this is a block <Icon {...(args as ComponentProps<typeof Icon>)} /> icon
+  </Fragment>
+);
+Block.args = {
+  icon: 'facehappy',
+  'aria-label': 'Happy face',
+  block: true,
+};

package/src/Icon.tsx

@@ -0,0 +1,64 @@
+import styled from 'styled-components';
+import { icons } from './shared/icons';
+import { IconProps } from './types';
+
+/**
+ * Props for styled Svg component
+ */
+interface SvgProps {
+  block?: boolean;
+}
+
+/**
+ * Styled SVG wrapper
+ */
+const Svg = styled.svg<SvgProps>`
+  display: ${(props) => (props.block ? 'block' : 'inline-block')};
+  vertical-align: middle;
+
+  shape-rendering: inherit;
+  transform: translate3d(0, 0, 0);
+`;
+
+/**
+ * Styled path element
+ */
+const Path = styled.path`
+  fill: currentColor;
+`;
+
+/**
+ * An Icon is a piece of visual element, but we must ensure its accessibility while using it.
+ * It can have 2 purposes:
+ *
+ * - *decorative only*: for example, it illustrates a label next to it. We must ensure that it is ignored by screen readers, by setting `aria-hidden` attribute (ex: `<Icon icon="check" aria-hidden />`)
+ * - *non-decorative*: it means that it delivers information. For example, an icon as only child in a button. The meaning can be obvious visually, but it must have a proper text alternative via `aria-label` for screen readers. (ex: `<Icon icon="print" aria-label="Print this document" />`)
+ *
+ * @example
+ * ```tsx
+ * <Icon icon="check" />
+ * <Icon icon="user" block />
+ * <Icon icon="print" aria-label="Print document" />
+ * ```
+ */
+export const Icon = ({ icon, block = false, ...props }: IconProps) => {
+  const path = icons[icon as keyof typeof icons];
+  if (!path) {
+    if (process.env.NODE_ENV !== 'production') {
+      console.warn(`Icon: icon key "${icon}" not found in icons map.`);
+    }
+
+    // Render an empty, aria-hidden SVG so consumers don't get a broken path element
+    return (
+      <Svg viewBox="0 0 1024 1024" width="20px" height="20px" block={block} aria-hidden {...props}>
+        <Path d="" />
+      </Svg>
+    );
+  }
+
+  return (
+    <Svg viewBox="0 0 1024 1024" width="20px" height="20px" block={block} {...props}>
+      <Path d={path} />
+    </Svg>
+  );
+};

package/src/Intro.stories.tsx

@@ -0,0 +1,20 @@
+import { Meta } from '@storybook/react-vite';
+
+const meta: Meta = {
+  title: 'Design System/Introduction',
+  parameters: {
+    docs: {
+      description: {
+        component: `
+# Introduction to the Storybook design system tutorial
+
+The Storybook design system tutorial is a subset of the full [Storybook design system](https://github.com/storybookjs/design-system/), created as a learning resource for those interested in learning how to write and publish a design system using best practice techniques.
+
+Learn more in the [Storybook tutorials](https://storybook.js.org/tutorials/).
+        `,
+      },
+    },
+  },
+};
+
+export default meta;

package/src/Link.stories.tsx

@@ -0,0 +1,69 @@
+import styled from 'styled-components';
+import { action } from 'storybook/actions';
+
+import { Icon } from './Icon';
+import { Link } from './Link';
+import { StoryLinkWrapper } from './StoryLinkWrapper';
+
+const CustomLink = styled(Link)`
+  && {
+    color: red;
+  }
+`;
+
+const onLinkClick = action('onLinkClick');
+
+export default {
+  title: 'Design System/Link',
+  component: Link,
+};
+
+export const All = () => (
+  <div>
+    <Link href="https://storybook.js.org/tutorials/">Default</Link>
+    <br />
+    <Link secondary href="https://storybook.js.org/tutorials/">
+      Secondary
+    </Link>
+    <br />
+    <Link tertiary href="https://storybook.js.org/tutorials/">
+      tertiary
+    </Link>
+    <br />
+    <Link nochrome href="https://storybook.js.org/tutorials/">
+      nochrome
+    </Link>
+    <br />
+    <Link href="https://storybook.js.org/tutorials/">
+      <Icon icon="discord" aria-hidden />
+      With icon in front
+    </Link>
+    <br />
+    <Link containsIcon href="https://storybook.js.org/tutorials/" aria-label="Toggle side bar">
+      <Icon icon="sidebar" aria-hidden />
+    </Link>
+    <br />
+    <Link containsIcon withArrow href="https://storybook.js.org/tutorials/">
+      With arrow behind
+    </Link>
+    <br />
+    <span style={{ background: '#333' }}>
+      <Link inverse href="https://storybook.js.org/tutorials/">
+        Inverted colors
+      </Link>
+    </span>
+    <br />
+    {/* gatsby and styled-components don't work nicely together  */}
+    <Link isButton onClick={onLinkClick}>
+      is actually a button
+    </Link>
+    <br />
+    <Link tertiary LinkWrapper={StoryLinkWrapper} href="http://storybook.js.org">
+      has a LinkWrapper like GatsbyLink or NextLink
+    </Link>
+    <br />
+    <CustomLink tertiary LinkWrapper={StoryLinkWrapper} href="http://storybook.js.org">
+      has a LinkWrapper like GatsbyLink or NextLink with custom styling
+    </CustomLink>
+  </div>
+);

package/src/Link.tsx

@@ -0,0 +1,252 @@
+import type { ComponentType, ReactNode } from 'react';
+import { Fragment } from 'react';
+import styled, { css } from 'styled-components';
+import { darken } from 'polished';
+
+import { Icon } from './Icon';
+import { color } from './shared/styles';
+import { LinkProps } from './types';
+
+/**
+ * Props for styled link components
+ */
+interface StyledLinkProps {
+  secondary?: boolean;
+  tertiary?: boolean;
+  nochrome?: boolean;
+  inverse?: boolean;
+  isButton?: boolean;
+  containsIcon?: boolean;
+  withArrow?: boolean;
+}
+
+/**
+ * Props for LinkInner component
+ */
+interface LinkInnerProps {
+  withArrow?: boolean;
+}
+
+const linkStyles = css<StyledLinkProps>`
+  display: inline-block;
+  transition:
+    transform 150ms ease-out,
+    color 150ms ease-out;
+  text-decoration: none;
+
+  color: ${color.secondary};
+
+  &:hover,
+  &:focus {
+    cursor: pointer;
+    transform: translateY(-1px);
+    color: ${darken(0.07, color.secondary)};
+  }
+  &:active {
+    transform: translateY(0);
+    color: ${darken(0.1, color.secondary)};
+  }
+
+  svg {
+    display: inline-block;
+    height: 1em;
+    width: 1em;
+    vertical-align: text-top;
+    position: relative;
+    bottom: -0.125em;
+    margin-right: 0.4em;
+  }
+
+  ${(props) =>
+    props.containsIcon &&
+    css`
+      svg {
+        height: 1em;
+        width: 1em;
+        vertical-align: middle;
+        position: relative;
+        bottom: 0;
+        margin-right: 0;
+      }
+    `};
+
+  ${(props) =>
+    props.secondary &&
+    css`
+      color: ${color.mediumdark};
+
+      &:hover {
+        color: ${color.dark};
+      }
+
+      &:active {
+        color: ${color.darker};
+      }
+    `};
+
+  ${(props) =>
+    props.tertiary &&
+    css`
+      color: ${color.dark};
+
+      &:hover {
+        color: ${color.darkest};
+      }
+
+      &:active {
+        color: ${color.mediumdark};
+      }
+    `};
+
+  ${(props) =>
+    props.nochrome &&
+    css`
+      color: inherit;
+
+      &:hover,
+      &:active {
+        color: inherit;
+        text-decoration: underline;
+      }
+    `};
+
+  ${(props) =>
+    props.inverse &&
+    css`
+      color: ${color.lightest};
+
+      &:hover {
+        color: ${color.lighter};
+      }
+
+      &:active {
+        color: ${color.light};
+      }
+    `};
+
+  ${(props) =>
+    props.isButton &&
+    css`
+      border: 0;
+      border-radius: 0;
+      background: none;
+      padding: 0;
+      font-size: inherit;
+    `};
+`;
+
+const LinkInner = styled.span<LinkInnerProps>`
+  ${(props) =>
+    props.withArrow &&
+    css`
+      > svg:last-of-type {
+        height: 0.7em;
+        width: 0.7em;
+        margin-right: 0;
+        margin-left: 0.25em;
+        bottom: auto;
+        vertical-align: inherit;
+      }
+    `};
+`;
+
+const LinkA = styled.a<StyledLinkProps>`
+  ${linkStyles};
+`;
+
+const LinkButton = styled.button<StyledLinkProps>`
+  /* reset button styles */
+  background: none;
+  color: inherit;
+  border: none;
+  padding: 0;
+  font: inherit;
+  cursor: pointer;
+  outline: inherit;
+
+  ${linkStyles};
+`;
+
+const applyStyle = (LinkWrapper?: LinkProps['LinkWrapper']) => {
+  return (
+    LinkWrapper &&
+    styled(
+      ({
+        containsIcon: _containsIcon,
+        inverse: _inverse,
+        nochrome: _nochrome,
+        secondary: _secondary,
+        tertiary: _tertiary,
+        children: _children,
+        ...linkWrapperRest
+      }: Record<string, unknown>) => (
+        <LinkWrapper {...(linkWrapperRest as Record<string, unknown>)}>{_children as ReactNode}</LinkWrapper>
+      ),
+    )`
+      ${linkStyles};
+    `
+  );
+};
+
+/**
+ * Links can contains text and/or icons. Be careful using only icons, you must provide a text alternative via aria-label for accessibility.
+ *
+ * @example
+ * ```tsx
+ * <Link href="/home">Home</Link>
+ * <Link secondary href="/about">About</Link>
+ * <Link withArrow>Learn more</Link>
+ * ```
+ */
+export const Link = ({
+  isButton = false,
+  withArrow = false,
+  secondary = false,
+  tertiary = false,
+  nochrome = false,
+  inverse = false,
+  containsIcon = false,
+  LinkWrapper,
+  children,
+  ...props
+}: LinkProps) => {
+  // Dev-time accessibility check for icon-only links
+  if (process.env.NODE_ENV !== 'production') {
+    const hasAriaLabel = Object.prototype.hasOwnProperty.call(props, 'aria-label');
+    const noVisibleChildren = !children || (typeof children === 'string' && children.trim() === '');
+    if (containsIcon && noVisibleChildren && !hasAriaLabel) {
+      console.warn('Link: icon-only links should include an `aria-label` or visible text for accessibility.');
+    }
+  }
+  const content = (
+    <Fragment>
+      <LinkInner withArrow={withArrow}>
+        {children}
+        {withArrow && <Icon icon="arrowright" />}
+      </LinkInner>
+    </Fragment>
+  );
+
+  const StyledLinkWrapper = applyStyle(LinkWrapper);
+
+  let SelectedLink: ComponentType<Record<string, unknown>> = LinkA;
+  if (LinkWrapper) {
+    SelectedLink = StyledLinkWrapper as ComponentType<Record<string, unknown>>;
+  } else if (isButton) {
+    SelectedLink = LinkButton as ComponentType<Record<string, unknown>>;
+  }
+
+  return (
+    <SelectedLink
+      secondary={secondary}
+      tertiary={tertiary}
+      nochrome={nochrome}
+      inverse={inverse}
+      isButton={isButton}
+      containsIcon={containsIcon}
+      {...props}
+    >
+      {content}
+    </SelectedLink>
+  );
+};

package/src/StoryLinkWrapper.d.ts

@@ -0,0 +1 @@
+export {};

package/src/StoryLinkWrapper.tsx

@@ -0,0 +1,33 @@
+import React from 'react';
+import { action } from 'storybook/actions';
+
+const fireClickAction = action('onLinkClick');
+
+interface Props {
+  children: React.ReactNode;
+  className?: string;
+  href?: string | null;
+  onClick?: () => void;
+  to?: string | null;
+}
+
+export const StoryLinkWrapper: React.FC<Props> = ({
+  children,
+  className = '',
+  href = null,
+  onClick = () => {},
+  to = null,
+  ...rest
+}) => {
+  const modifiedOnClick = (event: React.MouseEvent) => {
+    event.preventDefault();
+    onClick?.();
+    fireClickAction(href || to);
+  };
+
+  return (
+    <a className={className} href={(href || to) ?? undefined} onClick={modifiedOnClick} {...rest}>
+      {children}
+    </a>
+  );
+};

package/src/__tests__/Avatar.test.tsx

@@ -0,0 +1,28 @@
+import { describe, it, expect } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import { Avatar } from '../Avatar';
+import '@testing-library/jest-dom';
+
+describe('Avatar', () => {
+  it('renders initials when no image is provided', () => {
+    render(<Avatar username="John Doe" />);
+    expect(screen.getByText('J')).toBeInTheDocument();
+  });
+
+  it('renders an image when src is provided', () => {
+    render(<Avatar src="https://example.com/avatar.jpg" username="Jane Doe" />);
+    const img = screen.getByAltText('Jane Doe');
+    expect(img).toBeInTheDocument();
+    expect(img).toHaveAttribute('src', 'https://example.com/avatar.jpg');
+  });
+
+  it('shows loading state accurately', () => {
+    render(<Avatar loading username="Loading..." />);
+    expect(screen.getByLabelText('Loading avatar ...')).toBeInTheDocument();
+  });
+
+  it('renders correct initial based on username', () => {
+    render(<Avatar username="Eric Garcia" />);
+    expect(screen.getByText('E')).toBeInTheDocument();
+  });
+});

package/src/__tests__/Badge.test.tsx

@@ -0,0 +1,25 @@
+import { describe, it, expect } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import { Badge } from '../Badge';
+import '@testing-library/jest-dom';
+
+describe('Badge', () => {
+  it('renders with children text', () => {
+    render(<Badge>New</Badge>);
+    expect(screen.getByText('New')).toBeInTheDocument();
+  });
+
+  it('renders with different statuses', () => {
+    const { rerender } = render(<Badge status="positive">Positive</Badge>);
+    expect(screen.getByText('Positive')).toBeInTheDocument();
+
+    rerender(<Badge status="negative">Negative</Badge>);
+    expect(screen.getByText('Negative')).toBeInTheDocument();
+
+    rerender(<Badge status="warning">Warning</Badge>);
+    expect(screen.getByText('Warning')).toBeInTheDocument();
+
+    rerender(<Badge status="error">Error</Badge>);
+    expect(screen.getByText('Error')).toBeInTheDocument();
+  });
+});

package/src/__tests__/Button.test.tsx

@@ -0,0 +1,38 @@
+import { render, screen } from '@testing-library/react';
+import { describe, it, expect } from 'vitest';
+
+import { Button } from '../Button';
+import assertNoA11yViolations from '../test-utils/axe';
+
+describe('Button', () => {
+  it('renders children text', async () => {
+    const { container } = render(<Button>Click me</Button>);
+    expect(screen.getByText('Click me')).toBeTruthy();
+    await assertNoA11yViolations(container);
+  });
+
+  it('applies disabled when isDisabled prop is true', async () => {
+    const { container } = render(<Button isDisabled>Disabled</Button>);
+    const btn = screen.getByText('Disabled').closest('button');
+    expect(btn).toHaveAttribute('disabled');
+    await assertNoA11yViolations(container);
+  });
+
+  it('mounts icon-only button with accessible name', async () => {
+    // Render an icon-only button with aria-label to satisfy accessibility
+    const { container } = render(
+      <Button containsIcon aria-label="Icon action" isDisabled>
+        {/* icon-only scenario simulated with no children */}
+      </Button>,
+    );
+    const btn = screen.getByRole('button', { name: 'Icon action' });
+    expect(btn).toBeTruthy();
+    await assertNoA11yViolations(container);
+  });
+
+  it('fails axe for icon-only button without accessible name', async () => {
+    const { container } = render(<Button containsIcon isDisabled />);
+    // Expect the helper to throw with accessibility violations
+    await expect(assertNoA11yViolations(container)).rejects.toThrow(/Accessibility violations detected/);
+  });
+});

package/src/__tests__/Icon.test.tsx

@@ -0,0 +1,26 @@
+import { render, screen } from '@testing-library/react';
+import { describe, it, expect } from 'vitest';
+
+import { Icon } from '../Icon';
+import assertNoA11yViolations from '../test-utils/axe';
+
+describe('Icon', () => {
+  it('renders an svg for a valid icon key', async () => {
+    const { container } = render(<Icon icon="check" data-testid="icon" />);
+    const el = screen.getByTestId('icon');
+    expect(el.tagName.toLowerCase()).toBe('svg');
+    // path should exist (may be empty if icon not present)
+    expect(el.querySelector('path')).not.toBeNull();
+    await assertNoA11yViolations(container);
+  });
+
+  it('renders aria-hidden fallback for unknown icon key', async () => {
+    const { container } = render(<Icon icon={'__does_not_exist__' as unknown as string} data-testid="missing" />);
+    const el = screen.getByTestId('missing');
+    expect(el.getAttribute('aria-hidden')).not.toBeNull();
+    const path = el.querySelector('path');
+    expect(path).not.toBeNull();
+    expect(path?.getAttribute('d')).toBe('');
+    await assertNoA11yViolations(container);
+  });
+});

package/src/__tests__/Link.test.tsx

@@ -0,0 +1,31 @@
+import { describe, it, expect } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import { Link } from '../Link';
+import '@testing-library/jest-dom';
+
+describe('Link', () => {
+  it('renders a link with correct text', () => {
+    render(<Link href="https://example.com">Example</Link>);
+    const linkElement = screen.getByRole('link', { name: /example/i });
+    expect(linkElement).toBeInTheDocument();
+    expect(linkElement).toHaveAttribute('href', 'https://example.com');
+  });
+
+  it('renders as a button when isButton is true', () => {
+    render(<Link isButton>Button Link</Link>);
+    const buttonElement = screen.getByRole('button', { name: /button link/i });
+    expect(buttonElement).toBeInTheDocument();
+  });
+
+  it('renders an arrow icon when withArrow is true', () => {
+    const { container } = render(<Link withArrow>Arrow Link</Link>);
+    const svg = container.querySelector('svg');
+    expect(svg).toBeInTheDocument();
+  });
+
+  it('renders with secondary styling', () => {
+    render(<Link secondary>Secondary Link</Link>);
+    const linkElement = screen.getByText('Secondary Link').closest('a');
+    expect(linkElement).toHaveStyle('color: rgb(153, 153, 153)'); // color.mediumdark
+  });
+});