Implement base HTML element component A

The core atom `A` represents the inline text semantic (1) HTML element
`<a>`. It is a special  dynamic and failsafe component since it
internally uses the Gatsby `Link` component to route within the site
(internal links) while also being able to link to external targets. The
URLs are passed through the `to` and `href` props.

References:
  (1) https://developer.mozilla.org/en-US/docs/Web/HTML/Element#Inline_text_semantics
  (2) https://www.gatsbyjs.org/docs/gatsby-link

Associated epic: GH-69
GH-70

src/components/atoms/core/HTMLElements/index.js

@@ -0,0 +1,21 @@
+/*
+ * Copyright (C) 2018-present Arctic Ice Studio <[email protected]>
+ * Copyright (C) 2018-present Sven Greb <[email protected]>
+ *
+ * Project:    Nord Docs
+ * Repository: https://github.com/arcticicestudio/nord-docs
+ * License:    MIT
+ */
+
+/**
+ * @file Provides components that represents basic HTML elements.
+ * @author Arctic Ice Studio <[email protected]>
+ * @author Sven Greb <[email protected]>
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element
+ * @since 0.3.0
+ */
+
+import { A } from "./inlineTextSemantics";
+
+/* eslint-disable-next-line import/prefer-default-export */
+export { A };

src/components/atoms/core/HTMLElements/inlineTextSemantics/A.jsx

@@ -0,0 +1,69 @@
+/*
+ * Copyright (C) 2018-present Arctic Ice Studio <[email protected]>
+ * Copyright (C) 2018-present Sven Greb <[email protected]>
+ *
+ * Project:    Nord Docs
+ * Repository: https://github.com/arcticicestudio/nord-docs
+ * License:    MIT
+ */
+
+/**
+ * @author Arctic Ice Studio <[email protected]>
+ * @author Sven Greb <[email protected]>
+ * @since 0.3.0
+ */
+
+import React from "react";
+import PropTypes from "prop-types";
+import { Link } from "gatsby";
+import styled from "styled-components";
+
+import { isRouteInternal } from "utils";
+
+const BaseComponent = styled.a`
+  color: inherit;
+  cursor: pointer;
+  text-decoration: none;
+
+  &:active,
+  &:focus,
+  &:hover,
+  &:visited {
+    outline: none;
+  }
+`;
+
+/**
+ * A dynamic and failsafe component which either renders to a base HTML link `<a>` (anchor) or a "Gatsby Link" based on
+ * the target/URL type, internal or external, passed to the `to` and `href` props.
+ *
+ * @example <caption>Usage</caption>
+ * <!-- The target is external so both will render to `<a>` with the `href` prop. -->
+ * <A href="https://arcticicestudio.github.io/nord">Nord</A>
+ * <A to="https://arcticicestudio.github.io/nord">Nord</A>
+ * <!-- The target is internal so both will render to `<Link>` with the `to` prop. -->
+ * <A to="/blog">Blog</A>
+ * <A href="/blog">Blog</A>
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a
+ * @see https://www.gatsbyjs.org/docs/gatsby-link
+ * @since 0.3.0
+ */
+const A = ({ children, href, to, ...passProps }) =>
+  isRouteInternal(to) || isRouteInternal(href) ? (
+    <BaseComponent as={Link} to={to || href} {...passProps}>
+      {children}
+    </BaseComponent>
+  ) : (
+    <BaseComponent href={href || to} {...passProps}>
+      {children}
+    </BaseComponent>
+  );
+
+A.propTypes = {
+  children: PropTypes.node.isRequired,
+  to: PropTypes.string
+};
+
+A.defaultProps = { to: "" };
+
+export default A;

src/components/atoms/core/HTMLElements/inlineTextSemantics/index.js

@@ -0,0 +1,21 @@
+/*
+ * Copyright (C) 2018-present Arctic Ice Studio <[email protected]>
+ * Copyright (C) 2018-present Sven Greb <[email protected]>
+ *
+ * Project:    Nord Docs
+ * Repository: https://github.com/arcticicestudio/nord-docs
+ * License:    MIT
+ */
+
+/**
+ * @file Provides components that represent basic HTML elements with inline text semantics functionality.
+ * @author Arctic Ice Studio <[email protected]>
+ * @author Sven Greb <[email protected]>
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element#Inline_text_semantics
+ * @since 0.3.0
+ */
+
+import A from "./A";
+
+/* eslint-disable-next-line import/prefer-default-export */
+export { A };

test/components/atoms/core/HTMLElements/inlineTextSemantics/A.test.jsx

@@ -0,0 +1,37 @@
+/*
+ * Copyright (C) 2018-present Arctic Ice Studio <[email protected]>
+ * Copyright (C) 2018-present Sven Greb <[email protected]>
+ *
+ * Project:    Nord Docs
+ * Repository: https://github.com/arcticicestudio/nord-docs
+ * License:    MIT
+ */
+
+import React from "react";
+import { render } from "react-testing-library";
+
+import { A } from "atoms/core/HTMLElements";
+import { ROUTE_DOCS } from "config/routes/mappings";
+import { metadataNordDocs } from "data/project";
+
+describe("snapshot", () => {
+  test("renders inernal URLs with `to` prop", () => {
+    const { container } = render(<A to={ROUTE_DOCS}>Docs</A>);
+    expect(container).toMatchSnapshot();
+  });
+
+  test("renders inernal URLs with `href` prop", () => {
+    const { container } = render(<A href={ROUTE_DOCS}>Docs</A>);
+    expect(container).toMatchSnapshot();
+  });
+
+  test("renders external URLs with `href` prop", () => {
+    const { container } = render(<A href={metadataNordDocs.homepage}>Docs</A>);
+    expect(container).toMatchSnapshot();
+  });
+
+  test("renders external URLs with `to` prop", () => {
+    const { container } = render(<A to={metadataNordDocs.homepage}>Docs</A>);
+    expect(container).toMatchSnapshot();
+  });
+});

test/components/atoms/core/HTMLElements/inlineTextSemantics/__snapshots__/A.test.jsx.snap

@@ -0,0 +1,45 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`snapshot renders external URLs with \`href\` prop 1`] = `
+<div>
+  <a
+    class="sc-bdVaJa ccNLbx"
+    href="https://nordtheme.com"
+  >
+    Docs
+  </a>
+</div>
+`;
+
+exports[`snapshot renders external URLs with \`to\` prop 1`] = `
+<div>
+  <a
+    class="sc-bdVaJa ccNLbx"
+    href="https://nordtheme.com"
+  >
+    Docs
+  </a>
+</div>
+`;
+
+exports[`snapshot renders inernal URLs with \`href\` prop 1`] = `
+<div>
+  <a
+    class="sc-bdVaJa ccNLbx"
+    href="/docs"
+  >
+    Docs
+  </a>
+</div>
+`;
+
+exports[`snapshot renders inernal URLs with \`to\` prop 1`] = `
+<div>
+  <a
+    class="sc-bdVaJa ccNLbx"
+    href="/docs"
+  >
+    Docs
+  </a>
+</div>
+`;